Workflows

on.createdfunction

Runs after a row of the table is inserted (and committed). row is the new row; user who wrote it.

on.created<R>(table: string, handler: Handler<R>): Workflow

Parameters

Returns

Workflow

Errors

Does not throw.

Permissions

The run acts as the platform (row-level security doesn't apply to step.ctx.db and step.sql).

export const enquiryReceived = on.created<Enquiry>("enquiry", async ({ row }, step) => {
  await step.send.notify("enquiry-received", { role: "ops", vars: { name: row.name } });
});

Source: internal/kernel/appsdk/workflows/index.ts:144

on.updatedfunction

Runs after any update of a row; old is the row before.

on.updated<R>(table: string, handler: Handler<R>): Workflow

Parameters

Returns

Workflow

Errors

Does not throw.

Permissions

As on.created.

export const priceChanged = on.updated<Experience>("experience", async ({ row, old }, step) => {
  if (old && old.price !== row.price) await step.run("log", () => step.ctx.log("price", old.price, "→", row.price));
});

Source: internal/kernel/appsdk/workflows/index.ts:145

on.transitionfunction

Runs when a row's column moves into one value (status becomes confirmed), not on every later update while it stays there.

on.transition<R>(table: string, column: string, to: string, handler: Handler<R>): Workflow

Parameters

Returns

Workflow

Errors

Does not throw.

Permissions

As on.created.

export const bookingConfirmed = on.transition<Booking>("booking", "status", "confirmed", async ({ row }, step) => {
  await step.send.email("booking-confirmed", { to: row.email, vars: { ref: row.ref, team_size: row.team_size, link: step.url("/bookings") } });
});

Source: internal/kernel/appsdk/workflows/index.ts:149

on.deletedfunction

Runs when a row is deleted; row is the row as it was. On a soft-delete table, when the row moves into the trash.

on.deleted<R>(table: string, handler: Handler<R>): Workflow

Parameters

Returns

Workflow

Errors

Does not throw.

Permissions

As on.created.

export const noteDeleted = on.deleted("ops_note", async ({ row }, step) => {
  await step.run("audit", () => step.ctx.log("deleted note", row.id));
});

Source: internal/kernel/appsdk/workflows/index.ts:147

cronfunction

Runs on a schedule: "06:00" (daily), "daily 06:00", "every 15m", "weekly mon 09:00" or a 5-field cron expression, in tz (IANA, default UTC). The run's tick is the scheduled time.

cron(schedule: string, opts: { tz?: string }, handler: Handler): Workflow

Parameters

Returns

Workflow

Errors

Does not throw.

Permissions

As on.created.

export const morningDigest = cron("06:00", { tz: "Asia/Kolkata" }, async (_e, step) => {
  const rows = await step.sql("waiting", "select count(*)::int as n from booking where status = 'requested'");
  const count = Number(rows[0]?.n ?? 0);
  if (count > 0) await step.send.notify("bookings-waiting", { role: "ops", vars: { count } });
});

Source: internal/kernel/appsdk/workflows/index.ts:154

webhookfunction

An inbound webhook at /__appbricx/hooks/<name> on the app host (and /hooks/<project>/<name> on the platform). verify checks the sender: "stripe", "github", "razorpay" or a generic HMAC; without it the body must carry Appbricx's own signature. body and headers are the request's.

webhook(name: string, opts: { verify?: string | Record<string, unknown> }, handler: Handler): Workflow

Parameters

Returns

Workflow

Errors

Does not throw.

Permissions

Callers prove who they are with the signature; each event id runs once.

export const stripeEvents = webhook("stripe", { verify: "stripe" }, async ({ body }, step) => {
  const e = body as { type: string; data: { object: { id: string } } };
  if (e.type === "checkout.session.completed") await step.sql("paid", "update orders set status = 'paid' where checkout_id = $1", [e.data.object.id]);
});

RelatedPOST /__appbricx/hooks/:nameMCP call_app

Source: internal/kernel/appsdk/workflows/index.ts:161

step.runmethod

Runs fn once for the run and records its result: on every later run of the code (after a sleep or a retry) it answers from the journal instead of running again. Put reads, writes, HTTP calls, integration calls and anything random inside it.

step.run<T>(name: string, fn: () => Promise<T> | T): Promise<T>

Parameters

Returns

Promise<T>

Errors

• Rejects with what fn threw; the step is retried with backoff, then the run goes to the dead letters (run {action: "replay"}).

Permissions

None beyond the ctx it uses.

const s = await step.run("session", () => step.ctx.db.get("class_session", row.session_id));

Source: internal/kernel/appsdk/workflows/index.ts:169

step.nowmethod

The time, recorded: the same on every run of the code. Use it instead of new Date() (the checks refuse Date.now() and new Date() outside step.run).

step.now(): Promise<Date>

Returns

Promise<Date>

Errors

Does not throw.

Permissions

None.

const now = await step.now();

Source: internal/kernel/appsdk/workflows/index.ts:171

step.sleepmethod

Waits "30s", "15m", "2h", "1d" (or milliseconds) without holding anything: the run sleeps and wakes at the time.

step.sleep(duration: string | number): Promise<void>

Parameters

Returns

Promise<void>

Errors

Does not throw.

Permissions

None.

await step.sleep("1d");

Source: internal/kernel/appsdk/workflows/index.ts:173

step.sleepUntilmethod

Waits until a time, optionally minus a duration (a reminder a day before). A time already past doesn't wait.

step.sleepUntil(when: Date | string, opts?: { minus?: string | number }): Promise<void>

Parameters

Returns

Promise<void>

Errors

Does not throw.

Permissions

None.

await step.sleepUntil(row.starts_at, { minus: "1d" });
await step.send.email("reminder", { to: row.email, vars: { title: row.title } });

Source: internal/kernel/appsdk/workflows/index.ts:175

step.waitFormethod

Waits for ctx.signal(name, key, payload) from an action or another workflow and answers its payload, or null at the timeout. Each waitFor takes its own signal; one sent before the run got here counts.

step.waitFor<T = unknown>(name: string, opts?: { key?: string; timeout?: string | number }): Promise<T | null>

Parameters

Returns

Promise<T | null>

Errors

• A signal name can't contain : (put the rest in its key).

Permissions

None.

const feedback = await step.waitFor<{ stars: number }>("feedback", { key: row.id, timeout: "7d" });
if (feedback) await step.run("keep", () => step.ctx.db.update("booking", row.id, { notes: feedback.stars + " stars" }));

Relatedctx.signal

Source: internal/kernel/appsdk/workflows/index.ts:177

step.sqlmethod

One SQL statement with $1… params, recorded under name.

step.sql(name: string, sql: string, params?: unknown[]): Promise<Loose[]>

Parameters

Returns

The rows it returned.

Errors

• Rejects with Postgres's message.

Permissions

Runs as the platform: row-level security doesn't apply.

await step.sql("complete", "update class_session set status = 'completed' where status = 'scheduled' and ends_at < now()");

Source: internal/kernel/appsdk/workflows/index.ts:190

step.ctxproperty

The raw server ctx: db, http.fetch, config, secrets, signal, email, sms, pdf, log, app.url, and integrations.invoke(id, action, input) for a connected integration. Its calls aren't recorded: wrap anything that must happen once in step.run.

step.ctx: ServerCtx

Returns

ServerCtx

Errors

Does not throw.

Permissions

As the platform.

await step.run("slack", () =>
  step.ctx.integrations.invoke("slack", "send_channel_message", { channel: "C0123456", text: "New booking " + row.ref }),
);

RelatedIntegrations

Source: internal/kernel/appsdk/workflows/index.ts:194

step.send.emailmethod

Renders messages/email/<template>.md (or .html, .mjml) with vars and sends it once to to. vars are type-checked against the template's front matter; locale picks <name>.<locale>.md, then <name>.<language>.md, then the default.

step.send.email<N extends Names<"email">>(template: N, m: { to: string | string[]; vars: VarsOf<"email", N>; locale?: string }): Promise<{ queued: number }>

Parameters

Returns

Promise<{ queued: number }>

Errors

Does not throw.

Permissions

In dev and verify, mail to anyone but the project's owners and admins stays in the outbox (tail kind emails) unless the env secret APPBRICX_EMAIL_DELIVERY=live.

await step.send.email("booking-confirmed", {
  to: row.email,
  vars: { ref: row.ref, team_size: row.team_size, link: step.url("/bookings") },
});

RelatedMCP message_previews

Source: internal/kernel/appsdk/workflows/index.ts:181

step.send.smsmethod

Renders messages/sms/<template>.txt with vars and sends it once.

step.send.sms<N extends Names<"sms">>(template: N, m: { to: string | string[]; vars: VarsOf<"sms", N>; locale?: string }): Promise<{ queued: number }>

Parameters

Returns

Promise<{ queued: number }>

Errors

Does not throw.

Permissions

As step.send.email.

await step.send.sms("table-ready", { to: row.phone, vars: { name: row.name } });

Source: internal/kernel/appsdk/workflows/index.ts:182

step.send.notifymethod

An in-app notification from messages/notify/<template>.md (title, link in the front matter) to one user or everyone with a role.

step.send.notify<N extends Names<"notify">>(template: N, m: { user?: string; role?: string; vars: VarsOf<"notify", N>; locale?: string }): Promise<unknown>

Parameters

Returns

Promise<unknown>

Errors

Does not throw.

Permissions

None.

await step.send.notify("bookings-waiting", { role: "ops", vars: { count } });

Source: internal/kernel/appsdk/workflows/index.ts:183

step.promptmethod

Asks the app's AI with prompts/<name>.md (model, max_tokens, system in the front matter) filled with vars; the answer is recorded. The AI runs on the project's own key (the AI_API_KEY secret).

step.prompt<N extends Names<"prompt">>(name: N, vars: VarsOf<"prompt", N>): Promise<string>

Parameters

Returns

Promise<string>

Errors

• Rejects when the project has no AI key or AI is off for it.

Permissions

Server only; the key never reaches the browser.

const summary = await step.prompt("summarise-feedback", { comments: rows.map((r) => r.body).join("\n") });

RelatedAi keys

Source: internal/kernel/appsdk/workflows/index.ts:186

step.pdfmethod

Prints HTML as a PDF kept as an app file, once (recorded).

step.pdf(name: string, html: string, opts?: { landscape?: boolean }): Promise<{ fileId: string; url: string; bytes: number }>

Parameters

Returns

{ fileId, url, bytes }.

Errors

Does not throw.

Permissions

None.

const pdf = await step.pdf("invoice", invoiceHtml);
await step.run("save", () => step.ctx.db.update("invoice", row.id, { pdf: pdf.url }));

Source: internal/kernel/appsdk/workflows/index.ts:188

step.urlmethod

An absolute URL of the app (its dev host, production host or custom domain), for links in messages.

step.url(path: string): string

Parameters

Returns

string

Errors

Does not throw.

Permissions

None.

step.url("/bookings/" + row.id)

Source: internal/kernel/appsdk/workflows/index.ts:192