Workflow SDK reference
Complete TypeScript SDK for Grid82 workflows: triggers, db operations, ai decisions and generation, step sleeps, approvals, and http egress.
Every workflow imports workflow and trigger helpers from "grid82:workflow". Every SDK operation inside the handler takes a unique literal string label as its first argument; Grid82 uses these labels to draw the live diagram and correlate paused runs across replays.
Defining a workflow and triggers
import { workflow, schedule, record, manual, webhook } from "grid82:workflow";
export default workflow(
{
name: "Weekly pipeline digest",
trigger: schedule("weekdays 09:00", { timezone: "Europe/Paris" }),
apps: ["Sales CRM"],
egress: ["hooks.slack.com"],
maxWrites: 500,
},
async ({ trigger, db, ai, step, approval, http }) => {
// ...
},
);Supported triggers
| Trigger | trigger payload fields | Notes |
|---|---|---|
schedule(pattern, { timezone? }) | firedAt, runId | Accepts cron strings or phrases ("weekdays 09:00", "every day 07:30", "every monday, thursday 18:00", "monthly 1 09:00", "every hour", "every 15 minutes") |
record.created("App.Table", { when? }) | record, runId | Fires when a new record satisfies optional when |
record.updated("App.Table", { fields?, when? }) | record, previous, runId | Fires when listed fields change and record satisfies when |
record.deleted("App.Table") | previous, runId | Fires after deletion |
manual({ input }) | input, runId | Field types: "text", "number", "boolean", "date", "record" (append "?" for optional inputs) |
webhook({ input }) | input, runId | Studio app workflows only; endpoint https://{suite}/hooks/{app}/{workflow} (max 64 KB JSON, deduplicated by webhook-id) |
Database operations (db)
Access tables by exact display name (db["Sales CRM"].Deals or db.Sales.Deals). Field values use display names (record["Net value"]), select options use labels ("Won"), and links return [{ id, label }] objects:
| Method | Behaviour |
|---|---|
db.App.Table.find(label, { where?, sort?, limit? }) | Returns matching records (limit default 100, max 1,000) |
db.App.Table.get(label, idOrLink) | Fetches one record by ID or link field value (or null) |
db.App.Table.create(label, fields) | Creates a record and returns it |
db.App.Table.update(label, idOrLink, fields) | Updates a record ("now" and "today" supported for date fields) |
db.App.Table.delete(label, idOrLink) | Deletes a record |
where supports plain equality ({ Stage: "Proposal" }), typed operators (gt, gte, lt, lte, before, after, is_any_of, contains, is_empty, is_checked), and or: [{ ... }, { ... }].
Durable steps and waits (step)
step.do(label, () => ..., { retries?: 3, timeout?: "5 minutes" }). Wraps synchronous computation, data formatting,Date.now(), orMath.random()in a memoized durable step (retries0..10,timeoutup to"30 minutes").step.sleep(label, "2 days")/step.sleepUntil(label, isoDate). Pauses execution at zero cost for up to 1 year.
Approvals (approval.ask)
const decision = await approval.ask("Approve large discount", {
role: "Sales Manager",
question: "Approve 25% discount on Northwind renewal?",
show: { Deal: deal.Name, Amount: deal["Net value"] },
timeout: "7 days", // default 7 days, max 30 days
});
// decision: { approved: boolean, by?: string, at?: string, note?: string, timedOut?: boolean }AI steps (ai)
Use decision steps (ai.yes, ai.choose, ai.score) for classification and routing, and generative steps (ai.write, ai.extract) for drafting text or structured extraction:
| Method | Return value | Model options |
|---|---|---|
ai.yes(label, { question, context }) | Probability 0..1 | Decision model (fast, sub-second) |
ai.choose(label, { question, options, context }) | { choice, probabilities, confidence } | Decision model |
ai.score(label, { question, context, scale? }) | { score, level, probabilities, confidence } | Decision model |
ai.write(label, { instructions, context?, output?, model? }) | Plain text or structured output object | "fast" (default), "smart", or any OpenRouter model ID |
ai.extract(label, { from, output, model? }) | Extracted object matching output types ("string", "number", "boolean", "string[]", "number[]") | "fast" (default), "smart", or OpenRouter ID |
Outbound HTTP (http)
Studio app workflows may call domains listed in egress via http.get(label, url, headers?) and http.post(label, url, body, headers?). To protect webhook tokens, store the full destination URL in a suite secret and pass "secret:SECRET_NAME" as the url argument. Secrets cannot be interpolated inside request headers or JSON bodies.