`.
```tsx title="components/workflow-canvas.tsx"
"use client";
import {
useWorkflowBuilder,
useWorkflowCanvasRun,
} from "better-supabase/blocks/workflow-builder/react";
export function CanvasStatus({ runId }: { runId: string }) {
const { run, nodes } = useWorkflowCanvasRun(runId);
return (
{run?.status}:{" "}
{Object.values(nodes).filter((n) => n.status === "completed").length}{" "}
nodes done
);
}
```
`useWorkflowBuilder({ tenant })` returns the definitions, the step library
and a `builder` bound to the user's session. `useWorkflowCanvasRun(id)`
returns the run and each node's status by node id, and loads them again on
every message on `workflow-run:`. Both are Client Component hooks; in
Server Components, call `builder.definitions.list()` and
`builder.nodeRuns.list(run)` instead.
## Alerts [#alerts]
```ts
await builder.alerts.save({
definition: id,
onEvent: "failed",
channel: { type: "email", to },
});
await builder.alerts.save({
definition: id,
onEvent: "slow",
threshold: 3600,
channel,
});
await serviceBuilder.alerts.check(); // from a cron route
```
A `failed` alert fires when a run of the definition fails. A `slow` alert
fires from `alerts.check()` when a run is still unfinished `threshold`
seconds after it started. Each alert fires once per run and emits a
`workflow_alert.triggered` outbox event with the alert, its `channel` and the run.
Your outbox consumer sends it; the module only stores the channel. Runs
match a definition on their `bs.definition` attribute, which
`graphStarter` sets.
## Functions [#functions]
| Function | Granted to | Does |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
| `save_workflow_definition`, `workflow_definitions_list`, `workflow_definition_get`, `remove_workflow_definition` | `authenticated`, `service_role` | Definitions |
| `save_workflow_draft(definition, graph)`, `publish_workflow_version(version, compiled)` | `authenticated`, `service_role` | Drafts and publishing |
| `workflow_versions_list`, `workflow_version_get`, `validate_workflow_graph` | `authenticated`, `service_role` | Versions and graph checks |
| `workflow_start_target(definition)` | `authenticated`, `service_role` | The published version a `workflow.run` may start |
| `save_workflow_trigger`, `workflow_triggers_list`, `remove_workflow_trigger`, `rotate_workflow_webhook_token` | `authenticated`, `service_role` | Triggers |
| `workflow_webhook_target(token)`, `workflow_event_targets(type, tenant)` | `service_role` | What a webhook or an event starts |
| `save_workflow_credential`, `workflow_credentials_list`, `remove_workflow_credential` | `authenticated`, `service_role` | Credentials |
| `workflow_credential_get(id)` | `service_role` | A credential's ref, for `resolve` |
| `sync_workflow_steps(steps)`, `workflow_steps_list()` | `service_role`, `authenticated` | The step library |
| `record_workflow_node_run(...)`, `workflow_node_runs_list(run)` | `service_role`, `authenticated` | Node status |
| `save_workflow_alert`, `workflow_alerts_list`, `remove_workflow_alert` | `authenticated`, `service_role` | Alerts |
| `check_workflow_alerts(batch)` | `service_role` | Fires the slow alerts that are due |
# Workflow SDK
> Run the Workflow SDK on Supabase with a World over Postgres and Supabase Queues, and start runs, resume hooks and protect routes as the signed-in user.
Source: https://bettersupabase.com/docs/blocks/workflow-sdk
The Workflow SDK (`workflow`) needs a World: the storage and queue its runs,
steps, hooks and events live in. `better-supabase/workflow-sdk/world` is a
World on your Supabase database. Its tables sit in a `workflow` schema that
only the service role reads, its messages wait in a
[jobs](/docs/blocks/jobs) queue, and every run is copied into the
[workflows](/docs/blocks/workflows) block's `workflow_runs`, so members
list and follow runs through RLS. `better-supabase/workflow-sdk` has the
helpers that start runs and resume hooks as the signed-in user.
```bash
better-supabase sql add workflow-sdk-world # adds workflows and jobs as well
pnpm add workflow @workflow/world @workflow/world-postgres pg
```
The world entry imports `pg` and Node built-ins, so it runs on Node, not on
edge runtimes. The helpers in `better-supabase/workflow-sdk` import only
`workflow`.
## Selecting the World [#selecting-the-world]
```ts title="next.config.ts"
import { withWorkflow } from "workflow/next";
export default withWorkflow(nextConfig);
```
```bash title=".env"
WORKFLOW_TARGET_WORLD=better-supabase/workflow-sdk/world
SUPABASE_DB_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
```
The entry's default export is `createWorld()`, which reads its options from
the environment, so the SDK and tools that select a World by package name
load it without code. To build one yourself, call `createSupabaseWorld`:
```ts title="lib/world.ts"
import { createSupabaseWorld } from "better-supabase/workflow-sdk/world";
export const world = createSupabaseWorld({
connectionString: process.env.SUPABASE_DB_URL,
delivery: "pg_net",
});
```
| Variable | Option | Default |
| ---------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
| `WORKFLOW_POSTGRES_URL`, `SUPABASE_DB_URL`, `DATABASE_URL` | `connectionString` | the first one set |
| `WORKFLOW_DELIVERY` | `delivery` | `poll` |
| `WORKFLOW_FLOW_URL` | `flowUrl` | `WORKFLOW_LOCAL_BASE_URL` or `http://localhost:$PORT`, plus `/.well-known/workflow/v1/flow` |
| `WORKFLOW_DELIVERY_SECRET` | `deliverySecret` | the Vault secret `workflow_delivery_secret` |
| `WORKFLOW_ENCRYPTION_KEY` | `encryptionKey` | the Vault secret `workflow_encryption_key` |
| `WORKFLOW_DELIVERY_QUEUE` | `queue` | `workflow_deliveries` |
| `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | `concurrency` | 50 |
| `WORKFLOW_POSTGRES_POLL_INTERVAL_MS` | `pollInterval` | 250 |
The World speaks the `@workflow/world` protocol in
`WORKFLOW_WORLD_PROTOCOL` and stores its tables in the shape of the
`@workflow/world-postgres` version in `WORLD_POSTGRES_VERSION`. It passes
the `@workflow/world-testing` suite.
## Delivery [#delivery]
The SDK hands each step and each workflow turn to the queue, and the queue
posts it to the flow route that `withWorkflow` adds.
| Mode | Who posts | Use it on |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| `poll` (default) | the World, in the process that queues: it claims jobs and posts them | a server, a container, `next dev` |
| `pg_net` | `dispatch_workflow_deliveries()` on a pg\_cron schedule, through pg\_net | serverless hosts with no long-running process |
For `pg_net`, set `sql.modules.workflow-sdk-world.options.delivery` to
`pg_net` (the data file then schedules the dispatcher every
`options.schedule`, `1 seconds` by default) and store the route and a
secret in Vault:
```sql
select vault.create_secret('https://app.example.com/.well-known/workflow/v1/flow', 'workflow_flow_url');
select vault.create_secret(encode(extensions.gen_random_bytes(32), 'hex'), 'workflow_delivery_secret');
```
In poll mode, the first message a process queues starts its poller, and
`world.start()` also queues the runs that were active when the last
process stopped. Call it once at startup, for example from
`instrumentation.ts`.
Each delivery is signed with the secret (`x-bs-signature`, an HMAC-SHA256
over the time, the job and the body). The World's queue handler refuses an
unsigned or stale request with a 401 Problem Details response, and
completes or fails the job itself, so a delivery whose response is lost runs
again after its lease. Leave the flow route out of your proxy's matcher: the
World checks the signature, not a session.
Poll mode needs the secret too, unless `NODE_ENV` is `development` or
`test`: without one, the flow route answers every delivery with 401. Store
it in Vault as above or set `WORKFLOW_DELIVERY_SECRET`. A secret or key that
isn't in Vault counts as not set; a Vault read that fails is not cached, so
the next delivery reads again, and until then the route answers 503 and run
data can't be read or written.
A poll delivery that the flow route doesn't answer within `deliveryTimeout`
seconds (300 by default, at least `lease`) is aborted and retried. The
poller extends the job's lease only while the request is open.
## Encryption [#encryption]
With a 32-byte master key (base64 or hex) in `encryptionKey` or the Vault
secret `workflow_encryption_key`, the World derives an AES-256 key per run
with HKDF-SHA256, and the SDK stores the run's inputs, outputs and step
data encrypted. Without one, they are stored as JSON in the `workflow`
schema. When Vault can't be read, the World doesn't fall back to
unencrypted data: the read fails, and the next one tries Vault again.
## Starting runs as the user [#starting-runs-as-the-user]
```ts title="app/invoices/actions.ts"
"use server";
import { startFor } from "better-supabase/workflow-sdk";
import { approveInvoice } from "@/workflows/approve-invoice";
export async function requestApproval(invoiceId: string) {
const ctx = await server.context();
const run = await startFor(ctx, approveInvoice, [invoiceId], {
idempotencyKey: `approve:${invoiceId}`,
});
return run.runId;
}
```
`startFor` starts the run with the `bs.tenant` and `bs.actor` attributes
of the caller, which the World copies into `workflow_runs.tenant_id` and
`actor_id`. With `idempotencyKey`, it returns the run that already has the
key instead of starting another. To act as the user inside a step, pass
`workflowContext(ctx)` as an argument: it keeps the actor and tenant and
drops the claims, so no token ends up in the run's stored state.
| Helper | Does |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `workflowStarter({ name: workflow })` | The `start` callback for `schedules.tick` and `admission.tick`, as the schedule's or request's creator |
| `startOnEvent(workflow, { types })` | An outbox handler that starts the workflow per matching event (`invoice.paid`, `invoice.*`, `*`), once |
| `hookMetadata(ctx, permission?)` | Metadata for `createHook`, naming the actor and the permission a tenant member needs to resume it |
| `authorizeHook(token, ctx, { can })` | The hook, when the caller created it or holds its permission; `HookForbiddenError` (403) otherwise |
| `protectWebHandler(handler, key, { can })` | Answers 401 or 403 as `application/problem+json` before a workflow UI route or a run's stream |
## Approvals with hooks [#approvals-with-hooks]
```ts title="workflows/approve-invoice.ts"
import type { RequestContext } from "better-supabase";
import { hookMetadata } from "better-supabase/workflow-sdk";
import { createHook } from "workflow";
export async function approveInvoice(invoiceId: string, ctx: RequestContext) {
"use workflow";
const hook = createHook<{ approved: boolean }>({
metadata: hookMetadata(ctx, "invoice.approve"),
});
const { approved } = await hook;
// ...
}
```
```ts title="app/api/approvals/[token]/route.ts"
import { authorizeHook } from "better-supabase/workflow-sdk";
import { resumeHook } from "workflow/api";
export async function POST(request: Request, { params }) {
const { token } = await params;
const ctx = await server.context(request);
await authorizeHook(token, ctx, {
can: (tenant, permission) => canInTenant(ctx, tenant, permission),
});
await resumeHook(token, await request.json());
return new Response(null, { status: 204 });
}
```
A hook token in a link or an email is not enough to resume the run:
`authorizeHook` also checks who is asking. `can` is your permission check,
for example a call to `member_can(auth.uid(), tenant, permission)`.
## Graph workflows [#graph-workflows]
`better-supabase/workflow-sdk/builder` runs the graphs of the
[workflow builder](/docs/blocks/workflow-builder) on the Workflow SDK.
`compileGraph` turns a graph into dynamic workflow source: each step node
calls its own step, sleep nodes call `sleep` and approval nodes wait on
`createHook({ token: ":" })`. Pass it as `compile`, and
`graphStarter` as `start`, to `createBuilder`.
```ts title="workflows/graph.ts"
import {
executeGraph,
type GraphStepCall,
type WorkflowGraph,
} from "better-supabase/blocks/workflow-builder";
import { createHook, sleep } from "workflow";
import { steps } from "./steps";
export async function graphExecutor(
graph: WorkflowGraph,
input: unknown,
meta: { runKey: string },
) {
"use workflow";
return executeGraph(graph, input, {
runKey: meta.runKey,
step: (call: GraphStepCall) => steps[call.step](call),
sleep: (ms) => sleep(ms),
approval: (token) => createHook({ token }),
});
}
```
The executor imports `executeGraph` from the block rather than from
`workflow-sdk/builder`, so the workflow bundle doesn't load `workflow/api`,
which the workflow sandbox can't run.
```ts title="workflows/steps.ts"
import {
nodeRunReporter,
type GraphStepCall,
} from "better-supabase/workflow-sdk/builder";
const report = nodeRunReporter(serviceBuilder.nodeRuns);
export async function sendEmail(call: GraphStepCall) {
"use step";
return report(call, () => email.send(call.config));
}
export const steps = { "email.send": sendEmail };
```
Dynamic workflows are experimental in the Workflow SDK. With
`WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS=1`, `graphStarter` compiles the
published version's graph again on every start and runs that source; it
never runs the `compiled` form stored with the version. Source over 128 KiB
fails to publish. Node ids are 1 to 100 letters, digits, underscores or
hyphens, in `validateGraph` and in `validate_workflow_graph`. Without it, `graphStarter` starts `executor`, a static
`"use workflow"` function that walks the stored graph with `executeGraph`
and takes the same branches. Either way a run carries `bs.definition`,
`bs.version`, `bs.tenant`, `bs.actor` and `bs.key`, and a start with a key
that already ran returns the first run.
`nodeRunReporter` records each step node's status, output and error in
`workflow_node_runs` for the canvas. A record that fails never fails the
step.
## Analytics [#analytics]
`world.analytics` lists runs (by workflow name, status, attributes and a
time window), their steps, events, hooks and waits, and the attribute keys
in use. Pages hold at most 100 runs or 1000 steps and events. `startFor`
uses it to find a run by its idempotency key.
# Workflows
> A run registry for any workflow engine that members read through RLS, cron schedules, counting semaphores, admission control for starts, and useWorkflowRuns over Realtime.
Source: https://bettersupabase.com/docs/blocks/workflows
The `workflows` block records the runs of your durable workflows in one
table, whatever engine runs them, so a run list, a run page and a cancel
button work the same way for every engine. It also adds schedules,
semaphores and admission control. Each of these hands a start to the engine
you choose rather than running the workflow itself. The
[Workflow SDK adapter](/docs/blocks/workflow-sdk) is the engine that ships
with it.
```bash
better-supabase sql add workflows # adds tenant and access as well
```
| Table | Holds |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `workflow_runs` | One row per run: `engine`, `external_id`, `definition`, `tenant_id`, `actor_id`, `status`, `attributes`, `error` and the times |
| `workflow_schedules` | Recurring starts: `name`, `workflow`, `input`, `cron`, `timezone`, `next_run_at`, `paused` |
| `workflow_semaphores` | The holders of each semaphore key, until they release it or their lease ends |
| `workflow_start_requests` | Starts waiting for room under their key's concurrency, debounce or singleton rule |
| Permission | Lets | Default roles |
| ---------------- | ----------------------------------------------------------- | --------------- |
| `workflow.read` | members read the tenant's runs and schedules | none by default |
| `workflow.run` | members start runs, for helpers such as `protectWebHandler` | none by default |
| `workflow.admin` | members cancel any run of the tenant and manage schedules | none by default |
Grant the keys to your roles in `sql.modules.access.roles`. A user always
reads the runs they started, without a permission.
A run's status is `queued`, `running`, `waiting`, `completed`, `failed` or
`cancelled`. Every status change sends a payload-free Realtime message on
`workflow-run:` and, for a run with a tenant, on
`workflow-runs:`. With the [outbox](/docs/blocks/outbox) installed,
a run that ends emits `workflow_run.completed`, `workflow_run.failed` or
`workflow_run.cancelled`.
## Reading runs [#reading-runs]
```ts title="app/workflows/page.tsx"
import {
createWorkflows,
rpcTransport,
} from "better-supabase/blocks/workflows";
const workflows = createWorkflows({ transport: rpcTransport(supabase) });
const runs = await workflows.runs
.list({ tenant: organizationId, status: "running", limit: 50 })
.orThrow();
const run = await workflows.runs.get(runId).orThrow();
await workflows.runs.requestCancel(runId);
```
`runs.get` and `requestCancel` take the row's id or the engine's run id.
`list` returns the newest runs first; pass the last run's
`createdAt` as `cursor` for the next page. `requestCancel` sets `cancel_requested_at`
for the run's actor, a `workflow.admin` of its tenant or the service role.
The engine does the cancelling. The Workflow SDK adapter calls
`run.cancel()` for you.
Engines write runs with `runs.record` (service role), and
`runs.purge({ olderThan })` deletes finished runs older than 30 days by
default.
## In Client Components [#in-client-components]
```tsx title="components/run-list.tsx"
"use client";
import { useWorkflowRuns } from "better-supabase/blocks/workflows/react";
export function RunList({ organizationId }: { organizationId: string }) {
const { runs, error } = useWorkflowRuns({ tenant: organizationId });
if (error) return {error.message}
;
return (
{runs?.map((run) => (
-
{run.definition}: {run.status}
))}
);
}
```
`useWorkflowRuns` loads the list and loads it again on every message on
`workflow-runs:`. Without a `tenant`, it loads the user's own runs
once. `useWorkflowRun(id)` reads one run, follows `workflow-run:` and
returns `cancel()`. In Server Components, call `workflows.runs.list()`
instead.
## Schedules [#schedules]
Workflow schedules sit between job schedules and per-user AI tasks; see
[three scheduling layers](/docs/blocks/jobs#three-scheduling-layers).
```ts title="app/api/cron/workflows/route.ts"
import {
createWorkflows,
sqlTransport,
} from "better-supabase/blocks/workflows";
import { workflowStarter } from "better-supabase/workflow-sdk";
import { weeklyDigest } from "@/workflows/digest";
const workflows = createWorkflows({ transport: sqlTransport(postgres.admin) });
await workflows.schedules.create({
name: "weekly-digest",
workflow: "weeklyDigest",
cron: "0 9 * * 1",
timezone: "Europe/Amsterdam",
input: [organizationId],
tenant: organizationId,
});
export async function GET() {
const result = await workflows.schedules
.tick({ start: workflowStarter({ weeklyDigest }) })
.orThrow();
return Response.json(result);
}
```
`cron` takes five cron fields, a macro such as `@daily` or an interval such
as `30 seconds`. `tick` claims the due schedules, starts each one with the
idempotency key `schedule::` and moves it to its next time,
so a tick that runs twice for the same fire time starts one run. A start
that throws stays due and runs again once its lease ends. Call `tick` from
a cron route or a job every minute.
Members with `workflow.admin` create, pause and remove the schedules of
their tenant; the service role manages every schedule.
## Semaphores and admission [#semaphores-and-admission]
```ts
const free = await workflows.semaphores
.acquire("stripe-sync", runId, { max: 3, ttl: 300 })
.orThrow();
await workflows.semaphores.release("stripe-sync", runId);
await workflows.admission.request({
key: `import:${organizationId}`,
workflow: "importContacts",
input: [fileId],
tenant: organizationId,
concurrency: 1,
debounce: 30,
});
await workflows.admission.tick({ start: workflowStarter({ importContacts }) });
```
A semaphore lets at most `max` holders take a key at once, each until it
releases the key or its `ttl` runs out. Admission queues starts by key:
`concurrency` caps the runs of the key that are active, `debounce` waits
that many seconds and replaces a request that is still waiting, and
`singleton` drops the request while a run with the key is waiting or
active. `admission.tick` starts the requests whose key has room, with the
idempotency key `admission:`. Both are service-role functions.
## Functions [#functions]
| Function | Granted to | Does |
| ------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
| `workflow_runs_list(tenant, definition, status, max, before)` | `authenticated`, `service_role` | The runs the caller may read, newest first |
| `workflow_run_get(run)` | `authenticated`, `service_role` | One run by its id or its engine's id |
| `request_workflow_cancel(run)` | `authenticated`, `service_role` | Marks a run for cancellation |
| `record_workflow_run(...)` | `service_role` | Creates or updates a run by engine and external id |
| `purge_workflow_runs(older_than, batch)` | `service_role` | Deletes finished runs |
| `create_workflow_schedule(...)` | `authenticated`, `service_role` | Creates or replaces a schedule by tenant and name |
| `workflow_schedules_list(tenant)` | `authenticated`, `service_role` | The schedules the caller may read |
| `pause_workflow_schedule(id, paused)`, `remove_workflow_schedule` | `authenticated`, `service_role` | Pauses, resumes or removes a schedule |
| `claim_due_workflow_schedules`, `advance_workflow_schedule` | `service_role` | The schedule tick |
| `acquire_workflow_semaphore`, `release_workflow_semaphore` | `service_role` | Semaphores |
| `request_workflow_start`, `claim_workflow_start_requests`, `mark_*` | `service_role` | Admission control |
# Build a ChatGPT clone
> The modules, routes and components behind the example's /assistant and /knowledge pages, from a stored chat to tenant keys and metering.
Source: https://bettersupabase.com/docs/build/chatgpt-clone
The Next.js example's `/assistant` page is a chat app on the
[AI chat block](/docs/blocks/ai-chat) and the [AI SDK](/docs/ai-sdk): a chat
list, branching messages, resumable streams with stop, file uploads, a
knowledge search tool and memory. This guide walks through it in the order
you would build it. Run it with `pnpm dev:portless` and sign in as
`member@acme.test` (password `password123`); without `AI_GATEWAY_API_KEY`
a scripted model answers, so it runs offline.
## The modules [#the-modules]
```ts title="better-supabase.config.ts"
sql: {
modules: {
streams: { api: "api" },
"ai-chat": { api: "api" },
"ai-files": { api: "api" },
knowledge: { api: "api" },
memory: { api: "api" },
agents: { api: "api" },
connectors: { api: "api" },
"ai-tasks": { api: "api" },
"ai-providers": { api: "api" },
"ai-cache": { api: "api" },
},
},
```
| Module | Gives the clone | Page |
| -------------- | --------------------------------------------------------------------- | ----------------------------------------- |
| `ai-chat` | chats, folders, pins, the message tree, runs, sharing and the catalog | [AI chat](/docs/blocks/ai-chat) |
| `streams` | resumable answers that survive a reload | [Streams](/docs/blocks/streams) |
| `ai-files` | uploads read as the caller, and generated files | [AI files](/docs/blocks/ai-files) |
| `knowledge` | documents chunked and embedded for the search tool | [Knowledge](/docs/blocks/knowledge) |
| `memory` | facts and core memory per user | [Memory](/docs/blocks/memory) |
| `agents` | custom assistants with their own instructions and tools | [Agents](/docs/blocks/agents) |
| `connectors` | MCP servers with per-user OAuth | [Connectors](/docs/blocks/connectors) |
| `ai-tasks` | prompts on a schedule | [AI tasks](/docs/blocks/ai-tasks) |
| `ai-providers` | tenant keys, batches and sandboxes | [AI providers](/docs/blocks/ai-providers) |
| `ai-cache` | repeated model calls answered from Postgres | [AI cache](/docs/blocks/ai-cache) |
Run `better-supabase sql sync`, generate a migration with
`supabase db schema declarative sync`, then `better-supabase sql data`.
### The chat route [#the-chat-route]
`createAssistant` from `better-supabase/ai-sdk/chat` is the whole server
side: it stores the user's message, runs the model, streams the answer
through the stream store and saves it when it ends. The example builds one
per process in `src/features/assistant/assistant-server.ts` and mounts it
on three routes:
| Route | Does |
| --------------------------- | ----------------------------------------- |
| `POST /api/chat` | stores the message and streams the answer |
| `GET /api/chat/[id]/stream` | resumes the answer after a reload |
| `POST /api/chat/[id]/stop` | stops the answer |
`assistantContext` builds the per-request context: the caller's chat block,
their files, the knowledge search tool and their memory, all read through
RLS as the signed-in member.
### The client [#the-client]
`useAssistant` from `better-supabase/ai-sdk/react` is `useChat` wired to
those routes. The chat list, the new-chat form and the
stored chat live in `src/features/assistant/components`. Edit and
regenerate create sibling messages; `messages.siblings` and
`messages.switchBranch` move between them.
### Files and knowledge [#files-and-knowledge]
Uploads go to Storage as the caller, and `aiFileDownload` reads them back for
the model, so a member never reads another member's file. `/knowledge`
ingests documents into the knowledge block; `searchTool` gives the model a
tool that searches them with the tenant's embeddings.
### Memory [#memory]
`withMemory` adds the user's core memory to the instructions, and
`memoryTool` lets the model save and recall facts. Memory is per user and
per organization.
### Tenant keys, metering and caching [#tenant-keys-metering-and-caching]
The example's `run` adds the organization's own provider keys with
`byokOptions`, so a tenant that saved an Anthropic key pays for its own
calls ([tenant keys](/docs/ai-sdk/providers)). Register
[`meterTelemetry`](/docs/ai-sdk/telemetry) in `instrumentation.ts` to meter
every call on the usage block, and wrap deterministic calls such as titles
or summaries with [`cacheMiddleware`](/docs/ai-sdk/cache).
## Beyond the example [#beyond-the-example]
The blocks hold more than the example shows:
* Plans gate models through `ai_model_catalog` and `usageQuota`; an empty
quota answers with a 429 and `Retry-After`.
* [Agents](/docs/ai-sdk/agents) run as a `ToolLoopAgent` with tool approvals,
and [MCP connectors](/docs/ai-sdk/mcp) keep each user's tokens in Vault.
* [AI tasks](/docs/blocks/ai-tasks) run a prompt on a cron, and
[batches](/docs/ai-sdk/batches) run thousands at the batch price.
* Sharing by link (`shares.create`), temporary chats that `chats.purge`
removes, feedback and moderation events are chat block calls.
# Build a unibox inbox
> The modules, routes and components behind the example's /inbox page and Help sheet, where the assistant answers first and staff take over, plus the channel adapters that bring Slack and WhatsApp into the same list.
Source: https://bettersupabase.com/docs/build/unibox-inbox
The Next.js example has a staff inbox at `/inbox` and a Help sheet in the
header. A signed-in user asks a question in the sheet, the assistant from
[Build a ChatGPT clone](/docs/build/chatgpt-clone) answers, and staff see
the conversation in `/inbox`, where a reply takes it over. Conversations
from Slack, WhatsApp or SMS land in the same list through the
[Chat SDK channel helpers](/docs/chat-sdk/channels). Sign in as
`member@acme.test` to ask, and as `admin@acme.test` in another browser to
answer (password `password123`).
## The modules [#the-modules]
```ts title="better-supabase.config.ts"
sql: {
modules: {
jobs: {},
streams: { api: "api" },
inbox: { api: "api" },
"chat-sdk-state": {},
"ai-chat": { api: "api" },
},
},
```
| Module | Gives the inbox | Page |
| ---------------- | ----------------------------------------------------------------------------- | ------------------------------------- |
| `inbox` | inboxes, contacts, conversations, messages, notes, receipts and the bot mode | [Inbox](/docs/blocks/inbox) |
| `jobs` | the `inbox_bot` and `inbox_outbound` queues | [Jobs](/docs/blocks/jobs) |
| `streams` | resumable bot output | [Streams](/docs/blocks/streams) |
| `chat-sdk-state` | Chat SDK's subscriptions, locks and cache on Postgres | [State adapter](/docs/chat-sdk/state) |
| `ai-chat` | the assistant's chats; the Help conversation's chat has the conversation's id | [AI chat](/docs/blocks/ai-chat) |
The example's access contract gives `member` `inbox.read` and
`inbox.reply`, and `admin` also `inbox.assign` and `inbox.manage`.
### The staff inbox [#the-staff-inbox]
`/inbox` loads conversations with `conversations.list` and keeps them live
with `useInbox`. The conversation panel shows messages, internal notes,
read receipts and typing; the composer sends replies and notes. Assigning,
snoozing and resolving go through `src/features/inbox/inbox-actions.ts`.
### The Help sheet [#the-help-sheet]
`useInboxWidget` in `help-sheet.tsx` opens a conversation for the signed-in
user on the first question. `askForHelp` opens it with `botMode: "bot"`, so
the assistant answers until a staff member replies.
### The assistant answers [#the-assistant-answers]
`answerHelp` in `src/features/inbox/help-bot.ts` runs inside `after()`,
with the user's session, once the message is saved:
1. It loads the conversation and returns when `botMode` is no longer `bot`.
2. It shows the bot as typing and sends the question to the assistant's
`respond` with the conversation id as the chat id, so the assistant keeps
the thread's history.
3. It collects the text deltas, checks `botMode` again, and posts the answer
as a Markdown message with the author type `bot`.
A staff reply switches the conversation to `human`, so the next question
goes to staff only.
### Channels [#channels]
To add Slack or WhatsApp, record the installation with
`createChatInstallations`, receive the platform's webhooks with
`webhook()`, replay them into your Chat SDK instance with `inboundHandler`,
and deliver staff replies with `deliver()`. The token stays in the
credential provider; the installation row keeps its `credential_ref`.
### Bots on a queue [#bots-on-a-queue]
The module also queues an `inbox_bot` job for each contact message in bot
mode. A bot that runs without the user's session, for example a Chat SDK
bot behind [`inboxAdapter`](/docs/chat-sdk/inbox-adapter), drains that
queue:
```ts title="app/api/jobs/drain/route.ts"
export const GET = jobs.drainRoute({
secret: process.env.CRON_SECRET,
handlers: {
inbox_bot: (payload) => inboxBot.dispatch(payload),
inbox_outbound: (payload) => send(payload),
},
});
```
The example answers inline instead, so it has no drain route and the
queued `inbox_bot` jobs stay unclaimed. In production, either drain the
queue with a handler that does nothing, or move the answer into a handler
that loads the conversation's contact through the service role.
# Build a workflow builder
> The modules, routes and components behind the example's /workflows pages, where members draw a graph, publish it and watch each run on the canvas.
Source: https://bettersupabase.com/docs/build/workflow-builder
The Next.js example's `/workflows/builder` page lets members of a tenant
draw a workflow as a graph, publish it, and start it by hand, from a
webhook, on a schedule or on an event. Each run shows on the canvas node by
node. The graph lives in the [workflow builder block](/docs/blocks/workflow-builder);
the [Workflow SDK](/docs/blocks/workflow-sdk) runs it. Sign in as
`admin@acme.test` (password `password123`) to edit and publish.
## The modules [#the-modules]
```ts title="better-supabase.config.ts"
sql: {
modules: {
jobs: {},
credentials: { api: "api" },
workflows: { api: "api" },
"workflow-sdk-world": {},
"workflow-builder": { api: "api" },
},
},
```
| Module | Gives the builder | Page |
| -------------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
| `workflows` | the engine-neutral run registry, schedules, semaphores and admission | [Workflows](/docs/blocks/workflows) |
| `workflow-sdk-world` | the Workflow SDK's storage and queue on Postgres | [Workflow SDK](/docs/blocks/workflow-sdk) |
| `workflow-builder` | definitions, versions, triggers, credentials, node runs and alerts | [Workflow builder](/docs/blocks/workflow-builder) |
| `credentials` | the Vault functions credential rows resolve through | [Credentials](/docs/extending/credentials) |
Grant the `workflow.*` keys to your roles. The example's access contract
(`supabase/schemas/045_access_contract.sql`) gives `owner` and `admin` all
of them, and `member` `workflow.read` and `workflow.run`.
### The server [#the-server]
`builderFor(supabase)` in `src/features/workflows/builder/builder-server.ts`
creates the block as the caller, with a service transport for webhooks,
events and secrets. Three options connect it to the Workflow SDK:
| Option | Example value | Does |
| --------- | ----------------------------------- | ------------------------------------------------------- |
| `steps` | `stepLibrary` | the steps the canvas offers, synced to the step library |
| `compile` | `compileGraph` | turns a published graph into the engine's form |
| `start` | `graphStarter({ steps, executor })` | starts a run of a published version |
`graph-steps.ts` holds the step functions, keyed by the names in the step
library, and `graph-workflow.ts` the `"use workflow"` executor that walks a
compiled graph.
### The canvas [#the-canvas]
The editor in `src/features/workflows/builder/components` draws nodes and
edges with React Flow. Saving writes a draft version; `validateGraph` checks
it for cycles, missing steps and unreachable nodes before the publish dialog
lets a member publish. `diffGraphs` shows what changed since the published
version.
### Triggers [#triggers]
The trigger sheet adds a manual, webhook, schedule or event trigger.
Webhook calls arrive on `/api/workflows/hooks/[token]`; the token's SHA-256
is all the table keeps. `/api/workflows/tick` runs every minute from a cron
and starts due schedules and queued admission requests through
`triggers.starter`.
### Credentials [#credentials]
The credential sheet stores a secret in Vault and saves only the
`credential_ref` on the tenant's row. Steps read it at run time through
`credentials.resolve`, so a rotated secret takes effect on the next run.
### Run status [#run-status]
Each step records its node run, so `/workflows/[run]` and the canvas show
which node is running, waiting for an approval, done or failed, with its
output and error. Alerts on a definition fire once per failed or slow run.
## Another engine [#another-engine]
The graph and the run registry don't depend on the Workflow SDK. An engine
provides a `GraphCompiler` and a `BuilderStarter`, and reports its runs with
`workflows.runs.record`. [Add another SDK](/docs/extending/add-an-sdk)
describes the contract for a Temporal adapter.
# Channels
> Record Slack, WhatsApp, Messenger and SMS conversations in the inbox with Chat SDK adapters, deliver staff replies on their channel and keep the event store clean.
Source: https://bettersupabase.com/docs/chat-sdk/channels
These helpers in `better-supabase/chat-sdk` put conversations from a
Chat SDK platform adapter into the [inbox](/docs/blocks/inbox), and post
staff replies back on the same platform. All of them take `createInbox` on
a service transport.
## Installations [#installations]
`createChatInstallations` records which workspace or number an adapter is
installed on, per organization. The token stays in the
[credential provider](/docs/extending/credentials); the row only keeps its
`credential_ref`.
```ts title="lib/installations.ts"
import {
createChatInstallations,
sqlTransport,
} from "better-supabase/chat-sdk";
export const installations = createChatInstallations({
transport: sqlTransport(postgres.asService()),
credentials,
});
await installations
.install({
adapter: "slack",
externalId: teamId,
tenant: organizationId,
credentialRef,
})
.orThrow();
```
A reinstall revokes the credential it replaces, `uninstall(adapter, externalId)`
revokes the current one, and `uninstallTenant(tenant)` removes every live
install of an organization before it is deleted. `get` and `list` read
them back. Organization exports leave out `credential_ref`, and the
[organization purge](/docs/blocks/data-lifecycle#credentials) keeps the
installation rows and doesn't revoke them, so call `uninstallTenant` first.
## Building an adapter with its token [#building-an-adapter-with-its-token]
`channelAdapter` asks the credential provider for the install's token and
hands it to the adapter factory:
```ts
import { createSlackAdapter } from "@chat-adapter/slack";
import { channelAdapter } from "better-supabase/chat-sdk";
const install = await installations.get("slack", teamId).orThrow();
const slack = await channelAdapter({
credentials,
ref: install.credentialRef,
create: (token) => createSlackAdapter({ botToken: token.token }),
});
```
## Receiving webhooks [#receiving-webhooks]
`webhook()` returns a route handler that verifies the request, stores the
raw event in the inbox's event table and answers `200` at once. Platforms
retry slow endpoints, so the processing happens afterwards:
```ts title="app/api/chat/whatsapp/route.ts"
import { after } from "next/server";
import { webhook } from "better-supabase/chat-sdk";
import { handler, inbox } from "@/lib/chat";
export const POST = webhook({
inbox,
adapter: "whatsapp",
verify: (request, body) => verifyMetaSignature(request, body),
externalId: (body) => JSON.parse(body).entry?.[0]?.id,
after: () => after(() => handler.drain()),
});
export const GET = POST;
```
| Option | Meaning |
| ----------------------------------- | -------------------------------------------------------------------------------- |
| `adapter` | The adapter name the event is replayed into |
| `credentials` and `ref` | Verify the request with `credentials.verifyInbound` before storing it |
| `verify` | Verifies the request when no credential ref does |
| `externalId` | The platform's event id, so a retried delivery is stored once |
| `passthrough`, `passthroughHandler` | Requests answered synchronously, by default `GET` and Slack's `url_verification` |
| `after` | Runs after the event is stored |
Without `credentials` or `verify`, every request is stored, so set one in
production.
## Replaying events into Chat SDK [#replaying-events-into-chat-sdk]
`inboundHandler` replays stored events into your `Chat` instance and
records channel messages in the inbox:
```ts title="lib/chat.ts"
import { inboundHandler } from "better-supabase/chat-sdk";
export const handler = inboundHandler({
chat: bot,
inbox,
inboxes: { whatsapp: whatsappInboxId, slack: slackInboxId },
});
bot.onNewMessage(/.*/, async (thread, message) => {
await handler.mirror(thread, message);
});
```
`drain({ limit, maxAttempts })` processes pending events oldest first and
returns `{ processed, failed }`. Delivery status callbacks from WhatsApp,
Messenger, Instagram and Twilio update the matching delivery instead of
reaching Chat SDK; pass `parsers` to add more. `mirror` finds or opens the
conversation for the thread, upserts the contact from the message's author
and skips bot messages and the echoes of replies `deliver` posted.
Platform file URLs usually need the bot's token. Pass `copyFile` to copy
each file into the `inbox-files` bucket; without it only files with a
public URL are kept.
## Delivering staff replies [#delivering-staff-replies]
A staff reply on a channel inbox queues an `inbox_outbound` job.
`deliver()` posts it with the conversation's adapter, records the delivery
with the platform's message id and throws on failure, so the job retries:
```ts title="app/api/jobs/drain/route.ts"
import { deliver, whatsappWindowOpen } from "better-supabase/chat-sdk";
const send = deliver({
chat: bot,
inbox,
template: async ({ conversation }) =>
conversation.inbox?.channel === "whatsapp" &&
!(await whatsappWindowOpen(inbox, conversation.id))
? { markdown: "We replied to your question. Answer here to continue." }
: null,
});
export const GET = jobs.drainRoute({
secret: process.env.CRON_SECRET,
handlers: { inbox_outbound: (payload) => send(payload) },
});
```
`template` replaces the message when the channel's reply window is closed,
such as WhatsApp's 24 hours after the contact's last message. The adapter
defaults to the inbox's channel (`sms` posts with `twilio`); `adapterFor`
picks another.
## Maintenance [#maintenance]
`maintain` runs the periodic work: it reopens snoozed conversations whose
time came, replays events a crashed request left pending, deletes
processed events after `keepEvents` (7 days by default) and purges expired
[state](/docs/chat-sdk/state).
```ts title="app/api/cron/inbox/route.ts"
import { maintain } from "better-supabase/chat-sdk";
export async function GET() {
return Response.json(await maintain({ inbox, handler, state }));
}
```
Protect the route with your cron secret like the jobs drain route.
# Inbox adapter
> inboxAdapter, a Chat SDK adapter whose threads are inbox conversations, so a bot answers visitors in the in-app widget and staff can take over.
Source: https://bettersupabase.com/docs/chat-sdk/inbox-adapter
`inboxAdapter` makes the [inbox](/docs/blocks/inbox) a Chat SDK platform.
A thread is a conversation (`inbox:`), the bot's replies
are messages with the author type `bot`, and reactions, edits, typing and
read state go through the same `createInbox` client.
```ts title="lib/bot.ts"
import { createInbox, sqlTransport } from "better-supabase/blocks/inbox";
import { inboxAdapter } from "better-supabase/chat-sdk";
const inbox = createInbox({ transport: sqlTransport(postgres.asService()) });
export const inboxBot = inboxAdapter({
inbox,
userName: "Acme bot",
streams,
});
```
| Option | Default | Meaning |
| ---------- | -------- | ------------------------------------------------------------------------------- |
| `inbox` | required | `createInbox` on a service transport; the bot writes as the service |
| `userName` | `bot` | The bot's name on its messages and reactions |
| `verify` | none | Checks requests to `handleWebhook`; without it `handleWebhook` answers 401 |
| `streams` | none | A [stream store](/docs/blocks/streams) for streamed replies a reader can resume |
## Running the bot [#running-the-bot]
The module queues an `inbox_bot` job when a contact writes in a
conversation whose `botMode` is `bot`. Hand the job to `dispatch`, which
loads the message and runs the bot's Chat SDK handlers. Messages from
staff, notes and other bots are skipped, so the bot never answers itself:
```ts
await inboxBot.dispatch({ conversation_id, message_id });
```
When the bot can't help, hand the conversation to staff. `handoff` sets
`botMode` to `human`, so later messages queue no bot job:
```ts
bot.onSubscribedMessage(async (thread, message) => {
if (/human|agent/i.test(message.text)) {
await inbox.conversations
.handoff(conversationIdOf(thread.id), "asked for a person")
.orThrow();
await thread.post("Someone from the team will reply here.");
}
});
```
`conversationIdOf(threadId)` turns a thread id back into a conversation
id. A staff reply in a bot conversation also switches it to `human`.
## Streamed replies [#streamed-replies]
A streamed `thread.post` shows the bot as typing while it writes, then
posts one message with the full text. With `streams`, the chunks also go
to the stream store as they arrive, and the message's `metadata.stream_id`
names the stream, so a client can replay the reply chunk by chunk.
## Limits [#limits]
Cards and modals render as their fallback text, and `scheduleMessage`,
`openModal` and `postEphemeral` aren't implemented: the in-app widget has
no surface for them.
# Chat SDK
> Run Chat SDK bots on Supabase with a Postgres state adapter, an inbox adapter for the in-app widget, and helpers that record Slack, WhatsApp and SMS messages in the inbox.
Source: https://bettersupabase.com/docs/chat-sdk
`better-supabase/chat-sdk` connects [Chat SDK](https://chat-sdk.dev) to
Supabase. It adds no tables of its own: the state lives in the
`chat-sdk-state` [SQL module](/docs/blocks/sql), and conversations live in
the [inbox](/docs/blocks/inbox).
```bash
pnpm add chat
pnpm better-supabase sql add chat-sdk-state inbox
```
`chat` is an optional peer (`>=4.41 <5`), so apps that don't run a bot
never install it. Every platform adapter, such as `@chat-adapter/slack`, is
the app's own dependency.
| Page | Covers |
| --------------------------------------------- | --------------------------------------------------------------------- |
| [State](/docs/chat-sdk/state) | `createSupabaseState`, the `StateAdapter` on Postgres |
| [Inbox adapter](/docs/chat-sdk/inbox-adapter) | `inboxAdapter`, a bot that answers in the in-app widget |
| [Channels](/docs/chat-sdk/channels) | `webhook`, `inboundHandler`, `deliver`, `maintain` and installations |
| [React](/docs/chat-sdk/react) | `better-supabase/chat-sdk/react`, the inbox hooks for chat interfaces |
## How a message flows [#how-a-message-flows]
1. A platform webhook reaches the route from `webhook()`, which verifies
it, stores it in the inbox's event table and answers at once.
2. `inboundHandler().drain()` replays the stored event into Chat SDK.
Your handlers call `handler.mirror(thread, message)`, which records the
message in the inbox, so staff see it next to widget conversations.
3. A staff reply queues an `inbox_outbound` job; `deliver()` posts it with
the platform adapter and records the delivery.
4. In `bot` mode, a contact's message queues an `inbox_bot` job instead,
and `inboxAdapter().dispatch()` runs your bot's handlers on it.
5. `maintain()` on a cron reopens snoozed conversations, replays events a
crashed request left, purges old events and deletes expired state.
A minimal bot on the widget:
```ts title="lib/bot.ts"
import "server-only";
import { Chat } from "chat";
import { createInbox, sqlTransport } from "better-supabase/blocks/inbox";
import { createSupabaseState, inboxAdapter } from "better-supabase/chat-sdk";
const transport = sqlTransport(postgres.asService());
export const inbox = createInbox({ transport });
export const inboxBot = inboxAdapter({ inbox, userName: "Acme bot" });
export const bot = new Chat({
userName: "Acme bot",
adapters: { inbox: inboxBot },
state: createSupabaseState({ transport }),
});
bot.onNewMention(async (thread, message) => {
await thread.post(`You wrote: ${message.text}`);
});
```
Run the bot jobs from a [jobs](/docs/blocks/jobs) drain route. Declare
`inbox_bot` in your queues with the `InboxBotJob` shape
(`conversation_id`, `message_id`), then:
```ts title="app/api/jobs/drain/route.ts"
import "server-only";
import { inboxBot } from "@/lib/bot";
import { jobs } from "@/lib/jobs";
export const GET = jobs.drainRoute({
secret: process.env.CRON_SECRET,
handlers: {
inbox_bot: (payload) => inboxBot.dispatch(payload),
},
});
```
## Credentials [#credentials]
Platform tokens never sit in the inbox tables. An installation stores a
`credential_ref`, and `channelAdapter` asks the
[credential provider](/docs/extending/credentials) for the token each time
it builds an adapter, so a rotated or revoked token takes effect on the
next message.
# React
> better-supabase/chat-sdk/react re-exports the inbox hooks for chat interfaces, a staff list, a thread with typing, and an in-app widget.
Source: https://bettersupabase.com/docs/chat-sdk/react
`better-supabase/chat-sdk/react` re-exports `useInbox`, `useConversation`
and `useInboxWidget` from `better-supabase/blocks/inbox/react`, so a chat
interface imports its hooks from the same place as its bot. They are the
same functions; see [Inbox](/docs/blocks/inbox#realtime) for their options.
```tsx title="components/help-chat.tsx"
"use client";
import { useInboxWidget } from "better-supabase/chat-sdk/react";
import { askForHelp, loadMessages, sendHelp } from "./help-actions";
export function HelpChat({ userId }: { userId: string }) {
const widget = useInboxWidget({
storageKey: `help:${userId}`,
open: (message) => askForHelp({ message }),
send: (conversationId, message) => sendHelp({ conversationId, message }),
load: (conversationId) => loadMessages({ conversationId }),
});
return (