@arbiterflow/client

Backend SDK for ArbiterFlow. Fire triggers, execute your own node types through a dispatch handler, and manage workflows, runs, secrets, and connectors from your server.

Install

npm install @arbiterflow/client

Ships ESM and CJS builds with bundled type declarations. Node 18.17 or newer.

For embedding the editor alongside this SDK, see the integration guide.

Usage

import { createArbiterFlowClient } from "@arbiterflow/client";

const af = createArbiterFlowClient({
  apiKey: process.env.AF_API_KEY!,
  projectId: "proj_main",
  dispatchSecret: process.env.AF_DISPATCH_SECRET,
});

serverUrl defaults to https://arbiterflow-api.solopress.ai; self-hosters pass their own.

await af.triggers.fire("livechat.conversation_escalated", {
  conversationId: "conv_123",
});

createArbiterFlowClient returns namespaced groups: workflows, runs, triggers, hooks, nodes, secrets, connectors, analytics, and dispatch.

Dispatch handlers

Dispatch is how ArbiterFlow calls back into your application to execute a node. Requests are signed, so the handler takes the raw request body plus the x-af-signature header and verifies it before invoking your callback.

Framework adapters handle that plumbing:

import { createExpressDispatchHandler } from "@arbiterflow/client/express";

app.post(
  "/arbiterflow/dispatch",
  express.text({ type: "*/*" }),
  createExpressDispatchHandler(options, async ({ nodeType, input, config }) => {
    switch (nodeType) {
      case "billing.charge":
        return { output: await charge(input) };
      default:
        return { error: `unknown node type: ${nodeType}`, status: 400 };
    }
  })
);

Available adapters:

| Import | Export | |---|---| | @arbiterflow/client/express | createExpressDispatchHandler(options, fn) | | @arbiterflow/client/fastify | createFastifyDispatchHandler(options, fn) | | @arbiterflow/client/hono | mountHonoDispatch(app, path, options, fn) |

On any other framework, use the core primitive directly:

const handler = af.dispatch.handler(async (envelope) => ({ output: {} }));
const { status, body } = await handler(rawBody, signatureHeader);

Signature verification requires the raw, unparsed body — make sure your framework is not JSON-parsing it first.

Webhook signatures

signWebhookBody is exported for verifying or generating signatures yourself.

License

MIT