@statebacked/client

StateBacked.dev client for web, Node, and Deno

Deploy invincible workflows and real-time, multiplayer backends with StateBacked.dev.

Check out the full State Backed docs for more detailed information and deploy your own state machine backend in just a few minutes.

This is the client library for interacting with the State Backed API. You can find the API docs for the State Backed client here.

The StateBacked.dev client provides an easy interface to interact with the State Backed API to create machines and machine versions, create machine instances, read the state of instances, and send events to instances.

Generally, you will want to use the web dashboard or smply, the State Backed CLI for administrative operations like creating machines and machine versions (smply machines create and smply machine-versions create) and use the API client for production operations like creating machine instances, subscribing to real-time state updates, and sending events.

Use the @statebacked/react package to connect to your machine instances from React.

Example

import { StateBackedClient } from "@statebacked/client";

const sessionId = crypto.randomUUID();

// you can create anonymous State Backed sessions or fully authenticated
// sessions to securely pass end-user claims to your machine authorizers
const client = new StateBackedClient({
  anonymous: {
    orgId: "org-YOUR_STATE_BACKED_ORG_ID",
    getSessionId() {
      return sessionId;
    }
  }
});

// create a new machine instance or get its current state if it already exists
// your machine's allowWrite authorizer will determine whether the request with
// the given authorization claims (in this case of anonymous access, just a session ID)
// will be allowed to create an instance with this name and initial context.

const { state, publicContext, tags, done } = await client.machineInstances.getOrCreate(
  "user-onboarding", // machine name
  sessionId, // machine instance name
  () => ({
    context: {
      your: "optional initial context",
    }
  })
);

// we can send an event to the `user-onboarding` machine instance
// for our current sesion and use the updated machine state and any
// public context. The event will only be accepted if your
// allowWrite machine authorizer allows the request with the given authorization
// claims (in this case of anonymous access, just a session ID) to
// send this event to this machine instance.

const { state, publicContext, tags, done } = await client.machineInstances.sendEvent(
  "user-onboarding", // machine name
  sessionId, // machine instance name
  {
    event: {
      type: "completed-tutorial",
      role: "engineer",
      preferredChannel: "email",
    }
  }
);

// we can also subscribe to state updates for any machine instance
// as long as your allowRead machine authorizer allows the request with
// our authorization claims to read its state

const unsubscribe = client.machineInstances.subscribe(
  "user-onboarding", // machine name
  sessionId, // machine instance name
  ({ state, publicContext, tags, done }) => {
    // react to new state
  }
);

// when you're done:
unsubscribe();