@softr/sdk 0.0.30-alpha.0 → 0.0.31

package/dist/action.d.ts

@@ -2,7 +2,7 @@ import { SoftrUserGroupId } from "./auth/user.js";
 
 //#region src/action.d.ts
 type ActionOperation = "read" | "create" | "update" | "delete";
-type ActionPermission = {
+type ActionPermissions = {
   userGroup: "ALL_USERS";
 } | {
   userGroup: "NON_LOGGED_IN_USERS";
@@ -10,6 +10,11 @@ type ActionPermission = {
   userGroup: "LOGGED_IN_USERS";
   userGroupIds?: Array<SoftrUserGroupId>;
 };
+type Action<TResource> = {
+  id: string;
+  resource: TResource;
+  permissions: ActionPermissions;
+};
 /**
  * Describes the datasources available in the app and their read, create and update types.
  *
@@ -42,7 +47,7 @@ type FieldIdOf<TDatasource$1, TOperation$1> = keyof SoftrDatasources extends nev
 type ReadFieldIdOf<TDatasource$1> = keyof SoftrDatasources extends never ? string : keyof ReadOf<TDatasource$1> & string;
 type ActionShape = {
   id: string;
-  datasource: SoftrDatasourceId;
+  datasourceId: SoftrDatasourceId;
   operation: ActionOperation;
   fields?: Record<string, string>;
 };
@@ -51,40 +56,48 @@ type ReadShape = ActionShape & {
   fields: Record<string, string>;
 };
 type ActionData<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
-  datasource: infer TDatasource;
+  datasourceId: infer TDatasource;
   operation: infer TOperation;
   fields: infer TFields;
 } ? { [Alias in keyof TFields]?: WriteOf<TDatasource, TOperation>[TFields[Alias] & keyof WriteOf<TDatasource, TOperation>] } : Record<string, unknown>;
 type ActionRecord<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
-  datasource: infer TDatasource;
+  datasourceId: infer TDatasource;
   fields: infer TFields;
 } ? { [Alias in keyof TFields]: ReadOf<TDatasource>[TFields[Alias] & keyof ReadOf<TDatasource>] } : Record<string, unknown>;
 declare const brand: unique symbol;
-type Action<TShape extends ActionShape = ActionShape> = {
-  type: "action";
+type DatasourceResource = {
+  type: "DATASOURCE";
+  datasourceId: SoftrDatasourceId;
+  operation: ActionOperation;
+  fields?: Record<string, string>;
+};
+/**
+ * A datasource-backed action (query or mutation). The `TShape` brand carries field and
+ * operation type info for compile-time checking of `ds.*` calls.
+ */
+type DatasourceAction<TShape extends ActionShape = ActionShape> = Action<DatasourceResource> & {
   id: TShape["id"];
-} & {
   readonly [brand]: TShape;
 };
 type WriteDeclaration<TId extends string, TDatasource$1, TOperation$1, TFields$1> = {
   id: TId;
-  datasource: TDatasource$1;
+  datasourceId: TDatasource$1;
   operation: TOperation$1;
   fields: TFields$1;
-  permission: ActionPermission;
+  permissions: ActionPermissions;
 };
 type ReadDeclaration<TId extends string, TDatasource$1, TFields$1> = {
   id: TId;
-  datasource: TDatasource$1;
+  datasourceId: TDatasource$1;
   fields: TFields$1;
-  permission: ActionPermission;
+  permissions: ActionPermissions;
 };
 type DeleteDeclaration<TId extends string, TDatasource$1> = {
   id: TId;
-  datasource: TDatasource$1;
+  datasourceId: TDatasource$1;
   operation: "delete";
   fields?: never;
-  permission: ActionPermission;
+  permissions: ActionPermissions;
 };
 /**
  * Declares a read: which datasource, which fields participate, and who may run it.
@@ -94,9 +107,9 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  * @example
  * const publishedPosts = defineQuery({
  *   id: "publishedPosts",
- *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   fields: { title: "V1StGXR8", author: "Z7pQm4Kd", publishedAt: "Xp2dLh6v" },
- *   permission: { userGroup: "ALL_USERS" },
+ *   permissions: { userGroup: "ALL_USERS" },
  * })
  *
  * const { records } = await ds
@@ -104,9 +117,9 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  *   .where((q) => q.publishedAt.lte(today))
  *   .orderBy((q) => q.publishedAt.desc)
  */
-declare function defineQuery<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): Action<{
+declare function defineQuery<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): DatasourceAction<{
   id: TId;
-  datasource: TDatasource$1;
+  datasourceId: TDatasource$1;
   operation: "read";
   fields: TFields$1;
 }>;
@@ -119,10 +132,10 @@ declare function defineQuery<const TId extends string, const TDatasource$1 exten
  * @example
  * const closeOrder = defineMutation({
  *   id: "closeOrder",
- *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   operation: "update",
  *   fields: { status: "V1StGXR8", closedAt: "Z7pQm4Kd" },
- *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ *   permissions: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
  * })
  *
  * await ds.update(closeOrder, { id, data: { status: "closed" } })
@@ -130,23 +143,88 @@ declare function defineQuery<const TId extends string, const TDatasource$1 exten
  * @example
  * const removeOrder = defineMutation({
  *   id: "removeOrder",
- *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   datasourceId: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   operation: "delete",
- *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ *   permissions: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
  * })
  *
  * await ds.delete(removeOrder, { id })
  */
-declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): Action<{
+declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): DatasourceAction<{
   id: TId;
-  datasource: TDatasource$1;
+  datasourceId: TDatasource$1;
   operation: TOperation$1;
   fields: TFields$1;
 }>;
-declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): Action<{
+declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): DatasourceAction<{
   id: TId;
-  datasource: TDatasource$1;
+  datasourceId: TDatasource$1;
   operation: "delete";
 }>;
+type WorkflowTemplateValue = "{LOGGED_IN_USER:EMAIL}" | "{LOGGED_IN_USER:NAME}" | "{LOGGED_IN_USER:RECORD_ID}" | `{LOGGED_IN_USER:${string}}` | "{CURRENT_DATE_TIME}" | "{CURRENT_DATE}";
+type WorkflowBodyValue = WorkflowTemplateValue | (string & {}) | number | boolean | null;
+type WorkflowResource = {
+  type: "WORKFLOW";
+  workflowId: string;
+  triggerId: string;
+  body?: Record<string, WorkflowBodyValue>;
+};
+type WorkflowAction<TId extends string = string> = Action<WorkflowResource> & {
+  id: TId;
+};
+type WorkflowDefinition<TId extends string> = {
+  id: TId;
+  workflowId: string;
+  triggerId: string;
+  permissions: ActionPermissions;
+  body?: Record<string, WorkflowBodyValue>;
+};
+/**
+ * Declares a workflow trigger: which workflow, which trigger, who may run it, and any
+ * hardcoded data resolved server-side (e.g. logged-in user fields, current date).
+ *
+ * Pass the returned object to `workflow.trigger()` at runtime — optionally with additional
+ * payload. Values in `body` are resolved by the server and cannot be overridden at runtime.
+ *
+ * @example
+ * const notifyTeam = defineWorkflow({
+ *   id: "notifyTeam",
+ *   workflowId: "wf_abc123",
+ *   triggerId: "tr_xyz789",
+ *   permissions: { userGroup: "LOGGED_IN_USERS" },
+ *   body: { requestedBy: "{LOGGED_IN_USER:EMAIL}", at: "{CURRENT_DATE_TIME}" },
+ * });
+ *
+ * await workflow.trigger(notifyTeam, { subject: "Hello" });
+ */
+declare function defineWorkflow<const TId extends string>(definition: WorkflowDefinition<TId>): WorkflowAction<TId>;
+type IntegrationResource = {
+  type: "INTEGRATION";
+  datasourceId: string;
+};
+type IntegrationAction<TId extends string = string> = Action<IntegrationResource> & {
+  id: TId;
+};
+type IntegrationDefinition<TId extends string> = {
+  id: TId;
+  datasourceId: string;
+  permissions: ActionPermissions;
+};
+/**
+ * Declares an integration: which connected data source to call through, and who may call it.
+ *
+ * Pass the returned object to `integration.createFetcher()` to get a bound fetcher.
+ *
+ * @example
+ * const googleCalendar = defineIntegration({
+ *   id: "googleCalendar",
+ *   datasourceId: "25d60213-ef4f-4fa0-b094-a46931b2d120",
+ *   permissions: { userGroup: "LOGGED_IN_USERS" },
+ * })
+ *
+ * const calendar = integration.createFetcher(googleCalendar)
+ * const res = await calendar('https://www.googleapis.com/calendar/v3/calendars/primary/events')
+ */
+declare function defineIntegration<const TId extends string>(definition: IntegrationDefinition<TId>): IntegrationAction<TId>;
 //#endregion
-export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineMutation, defineQuery };
+export { ActionData, ActionPermissions, ActionRecord, ActionShape, DatasourceAction, FieldTypeOf, IntegrationAction, ReadOf, ReadShape, SoftrDatasources, WorkflowAction, defineIntegration, defineMutation, defineQuery, defineWorkflow };

package/dist/action.js

@@ -1,22 +1,59 @@
 //#region src/action.ts
 function defineQuery(definition) {
 	return {
-		type: "action",
-		...definition,
-		operation: "read"
+		id: definition.id,
+		resource: {
+			type: "DATASOURCE",
+			datasourceId: definition.datasourceId,
+			operation: "read",
+			fields: definition.fields
+		},
+		permissions: definition.permissions
 	};
 }
 function defineMutation(definition) {
+	const { id, datasourceId, operation, fields, permissions } = definition;
 	return {
-		type: "action",
-		...definition
+		id,
+		resource: {
+			type: "DATASOURCE",
+			datasourceId,
+			operation,
+			fields
+		},
+		permissions
 	};
 }
-function isAction(value) {
+function defineWorkflow(definition) {
+	const { id, workflowId, triggerId, body, permissions } = definition;
+	return {
+		id,
+		resource: {
+			type: "WORKFLOW",
+			workflowId,
+			triggerId,
+			body
+		},
+		permissions
+	};
+}
+function defineIntegration(definition) {
+	const { id, datasourceId, permissions } = definition;
+	return {
+		id,
+		resource: {
+			type: "INTEGRATION",
+			datasourceId
+		},
+		permissions
+	};
+}
+function isDatasourceAction(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
-	return candidate.type === "action" && typeof candidate.id === "string" && typeof candidate.datasource === "string";
+	const resource = candidate.resource;
+	return typeof candidate.id === "string" && typeof resource === "object" && resource !== null && resource.type === "DATASOURCE";
 }
 
 //#endregion
-export { defineMutation, defineQuery, isAction };
+export { defineIntegration, defineMutation, defineQuery, defineWorkflow, isDatasourceAction };

package/dist/auth/platform.js

@@ -278,4 +278,4 @@ function withoutTrailingSlash(url) {
 }
 
 //#endregion
-export { makePlatform };
+export { makePlatform, platformApiUrl };

package/dist/core/integration.d.ts

@@ -1,24 +1,15 @@
+import { IntegrationAction } from "../action.js";
+
 //#region src/core/integration.d.ts
-interface IntegrationFetchOptions {
-  dataSourceId: string;
-  url: string;
+interface IntegrationFetchInit {
   method?: string;
   headers?: Record<string, string>;
   body?: string;
-  queryParams?: Record<string, string>;
   signal?: AbortSignal;
 }
-declare function integrationFetch({
-  dataSourceId,
-  url: rawUrl,
-  method,
-  headers,
-  body,
-  queryParams,
-  signal
-}: IntegrationFetchOptions): Promise<Response>;
+declare function integrationCreateFetcher(action: IntegrationAction): (url: string, init?: IntegrationFetchInit) => Promise<Response>;
 declare const integration: {
-  fetch: typeof integrationFetch;
+  createFetcher: typeof integrationCreateFetcher;
 };
 //#endregion
 export { integration };

package/dist/core/integration.js

@@ -2,13 +2,8 @@ import { readSessionToken } from "../auth/session.js";
 import { dsUrl } from "../datasource/record.js";
 
 //#region src/core/integration.ts
-async function integrationFetch({ dataSourceId, url: rawUrl, method = "GET", headers = {}, body, queryParams, signal }) {
+async function integrationFetch(action, url, { method = "GET", headers = {}, body, signal } = {}) {
 	if (signal?.aborted) throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
-	let url = rawUrl;
-	if (queryParams && Object.keys(queryParams).length > 0) {
-		const params = new URLSearchParams(queryParams);
-		url += (rawUrl.includes("?") ? "&" : "?") + params.toString();
-	}
 	const upperMethod = method.toUpperCase();
 	const payload = {
 		method: upperMethod,
@@ -16,7 +11,7 @@ async function integrationFetch({ dataSourceId, url: rawUrl, method = "GET", hea
 		headers
 	};
 	if (upperMethod !== "GET" && upperMethod !== "HEAD" && body !== void 0) payload.body = body;
-	return fetch(`${dsUrl(dataSourceId)}/proxy`, {
+	return fetch(`${dsUrl(action.resource.datasourceId)}/proxy`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -26,7 +21,10 @@ async function integrationFetch({ dataSourceId, url: rawUrl, method = "GET", hea
 		signal
 	});
 }
-const integration = { fetch: integrationFetch };
+function integrationCreateFetcher(action) {
+	return (url, init) => integrationFetch(action, url, init);
+}
+const integration = { createFetcher: integrationCreateFetcher };
 
 //#endregion
 export { integration };

package/dist/core/workflow.d.ts

@@ -1,5 +1,8 @@
+import { WorkflowAction } from "../action.js";
+
 //#region src/core/workflow.d.ts
-declare function triggerWorkflow(workflowId: string, payload?: Record<string, unknown>): Promise<void>;
+type FlatValue = string | number | boolean | null;
+declare function triggerWorkflow(action: WorkflowAction, payload?: Record<string, FlatValue>): Promise<void>;
 declare const workflow: {
   trigger: typeof triggerWorkflow;
 };

package/dist/core/workflow.js

@@ -1,17 +1,31 @@
+import { sessionConfig } from "../auth/config.js";
+import { platformApiUrl } from "../auth/platform.js";
 import { readSessionToken } from "../auth/session.js";
 
 //#region src/core/workflow.ts
-const BASE_URL = () => (import.meta.env.VITE_SOFTR_BASE_URL ?? "").replace(/\/$/, "");
-async function triggerWorkflow(workflowId, payload) {
-	const res = await fetch(`${BASE_URL()}/api/workflows/${workflowId}/trigger`, {
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function triggerWorkflow(action, payload) {
+	const baseUrl = `${await platformApiUrl()}/v1/vibe/applications/${sessionConfig().applicationId}/actions/${action.id}/workflow`;
+	const triggerRes = await fetch(baseUrl, {
 		method: "POST",
 		headers: {
-			"Authorization": `Bearer ${readSessionToken()}`,
-			...payload ? { "Content-Type": "application/json" } : {}
+			Authorization: `Bearer ${readSessionToken()}`,
+			"Content-Type": "application/json"
 		},
-		...payload ? { body: JSON.stringify(payload) } : {}
+		body: JSON.stringify(payload ?? {})
 	});
-	if (!res.ok) throw new Error(`Softr workflow trigger failed: ${res.status}`);
+	if (!triggerRes.ok) throw new Error(`Workflow trigger failed: ${triggerRes.status}`);
+	const execution = await triggerRes.json();
+	if (execution.status === "FINISHED") return;
+	if (execution.status === "PENDING_INTERACTION") throw new Error("Workflow requires interaction");
+	while (true) {
+		await sleep(2e3);
+		const detailsRes = await fetch(`${baseUrl}/${execution.id}`, { headers: { Authorization: `Bearer ${readSessionToken()}` } });
+		if (!detailsRes.ok) throw new Error(`Workflow status check failed: ${detailsRes.status}`);
+		const details = await detailsRes.json();
+		if (details.status === "FINISHED") return;
+		if (details.status === "PENDING_INTERACTION") throw new Error("Workflow requires interaction");
+	}
 }
 const workflow = { trigger: triggerWorkflow };
 

package/dist/datasource/chart.d.ts

@@ -1,4 +1,4 @@
-import { Action, FieldTypeOf, ReadShape, SoftrDatasources } from "../action.js";
+import { DatasourceAction, FieldTypeOf, ReadShape, SoftrDatasources } from "../action.js";
 import { ConstructableOrderBy } from "./filter.js";
 import { DateFieldType, NumberFieldType, SortSet } from "./fields.js";
 import { WhereCallback } from "./record.js";
@@ -84,14 +84,14 @@ type Unusable = {
  * field's value; a date field also carries bucket leaves. A multi-value field has no handle
  * body, because exploding it would count each record once per value and inflate every metric.
  */
-type DimensionSet<TShape extends ReadShape> = keyof SoftrDatasources extends never ? Record<string, AnyDimension> : { [Alias in keyof TShape["fields"]]: DimensionFor<FieldTypeOf<TShape["datasource"], TShape["fields"][Alias]>> };
+type DimensionSet<TShape extends ReadShape> = keyof SoftrDatasources extends never ? Record<string, AnyDimension> : { [Alias in keyof TShape["fields"]]: DimensionFor<FieldTypeOf<TShape["datasourceId"], TShape["fields"][Alias]>> };
 type DimensionFor<TFieldType> = [TFieldType] extends [never] ? AnyDimension : TFieldType extends `${string}[]` | "ATTACHMENT" | "DATE_RANGE" ? Unusable : TFieldType extends "DATE" ? DateDimension : TFieldType extends DateFieldType ? DatetimeDimension : TFieldType extends NumberFieldType ? Dimension<number | null> : TFieldType extends "CHECKBOX" ? Dimension<boolean | null> : Dimension<string | null>;
 /**
  * The handles a `metrics` callback is handed: aggregation leaves per alias, gated by the
  * field's declared type, plus `$count`. A field whose aggregate would come back as a
  * coerced non-number has no leaves at all.
  */
-type MeasureSet<TShape extends ReadShape> = (keyof SoftrDatasources extends never ? Record<string, AnyMeasures> : { [Alias in keyof TShape["fields"]]: MeasureFor<FieldTypeOf<TShape["datasource"], TShape["fields"][Alias]>> }) & {
+type MeasureSet<TShape extends ReadShape> = (keyof SoftrDatasources extends never ? Record<string, AnyMeasures> : { [Alias in keyof TShape["fields"]]: MeasureFor<FieldTypeOf<TShape["datasourceId"], TShape["fields"][Alias]>> }) & {
   /** Counts the rows in each group. Takes no field: every row counts once. */
   readonly $count: Measure<number>;
 };
@@ -181,7 +181,7 @@ type MetricBuilder<TShape extends ReadShape, TValue$1> = {
  *   .orderBy((q) => q.month.asc)
  * // data: Array<{ month: string | null; revenue: number | null; orders: number }>
  */
-declare function chart<TShape extends ReadShape>(query: Action<TShape>): ChartSeed<TShape>;
+declare function chart<TShape extends ReadShape>(query: DatasourceAction<TShape>): ChartSeed<TShape>;
 /**
  * Aggregates records into one value, with no grouping.
  *
@@ -191,6 +191,6 @@ declare function chart<TShape extends ReadShape>(query: Action<TShape>): ChartSe
  *   .where((q) => q.status.is("paid"))
  * // value: number | null
  */
-declare function metric<TShape extends ReadShape, TMeasure extends Measure<unknown>>(query: Action<TShape>, pick: (q: MeasureSet<TShape>) => TMeasure): MetricBuilder<TShape, ColumnValue<TMeasure>>;
+declare function metric<TShape extends ReadShape, TMeasure extends Measure<unknown>>(query: DatasourceAction<TShape>, pick: (q: MeasureSet<TShape>) => TMeasure): MetricBuilder<TShape, ColumnValue<TMeasure>>;
 //#endregion
 export { chart, metric };

package/dist/datasource/fields.d.ts

@@ -112,7 +112,7 @@ type Combinators = {
  * the action never declared has to resolve too, so that case is open by name and permissive
  * by operator.
  */
-type FieldSet<TShape extends ReadShape> = keyof SoftrDatasources extends never ? Record<string, AnyChain> & Combinators : { [Alias in keyof TShape['fields']]: ChainFor<FieldTypeOf<TShape['datasource'], TShape['fields'][Alias]>, NonNullable<ReadOf<TShape['datasource']>[TShape['fields'][Alias] & keyof ReadOf<TShape['datasource']>]>> } & Combinators;
+type FieldSet<TShape extends ReadShape> = keyof SoftrDatasources extends never ? Record<string, AnyChain> & Combinators : { [Alias in keyof TShape['fields']]: ChainFor<FieldTypeOf<TShape['datasourceId'], TShape['fields'][Alias]>, NonNullable<ReadOf<TShape['datasourceId']>[TShape['fields'][Alias] & keyof ReadOf<TShape['datasourceId']>]>> } & Combinators;
 /** What an `orderBy` callback is handed: two handles per alias and nothing else. */
 type SortSet<TRecord> = { [K in keyof TRecord]: {
   readonly asc: ConstructableOrderBy;

package/dist/datasource/record.d.ts

@@ -1,4 +1,4 @@
-import { Action, ActionData, ActionRecord, ActionShape, ReadShape } from "../action.js";
+import { ActionData, ActionRecord, ActionShape, DatasourceAction, ReadShape } from "../action.js";
 import { AnyConstructable, ConstructableOrderBy } from "./filter.js";
 import { FieldSet, SortSet } from "./fields.js";
 
@@ -78,7 +78,7 @@ interface ListResult<TRecord extends SoftrRecord = SoftrRecord> {
  *   .orderBy((q) => q.publishedAt.desc)
  *   .limit(50)
  */
-declare function listRecords<TShape extends ReadShape>(query: Action<TShape>): ListBuilder<TShape>;
+declare function listRecords<TShape extends ReadShape>(query: DatasourceAction<TShape>): ListBuilder<TShape>;
 /**
  * Gets a single record by ID.
  *
@@ -94,7 +94,7 @@ declare function listRecords<TShape extends ReadShape>(query: Action<TShape>): L
  *   .get(posts, { id: "record-id" })
  *   .where((q) => q.publishedAt.lte(today))
  */
-declare function getRecord<TShape extends ReadShape>(query: Action<TShape>, options: GetOptions): GetBuilder<TShape>;
+declare function getRecord<TShape extends ReadShape>(query: DatasourceAction<TShape>, options: GetOptions): GetBuilder<TShape>;
 /**
  * Creates a record and returns it.
  *
@@ -105,7 +105,7 @@ declare function getRecord<TShape extends ReadShape>(query: Action<TShape>, opti
  */
 declare function createRecord<TShape extends ActionShape & {
   operation: "create";
-}>(action: Action<TShape>, options: {
+}>(action: DatasourceAction<TShape>, options: {
   data: ActionData<TShape>;
 }): Promise<SoftrRecord<ActionRecord<TShape>>>;
 /**
@@ -119,7 +119,7 @@ declare function createRecord<TShape extends ActionShape & {
  */
 declare function updateRecord<TShape extends ActionShape & {
   operation: "update";
-}>(action: Action<TShape>, options: {
+}>(action: DatasourceAction<TShape>, options: {
   id: string;
   data: ActionData<TShape>;
 }): Promise<SoftrRecord<ActionRecord<TShape>>>;
@@ -131,7 +131,7 @@ declare function updateRecord<TShape extends ActionShape & {
  */
 declare function deleteRecord<TShape extends ActionShape & {
   operation: "delete";
-}>(action: Action<TShape>, options: {
+}>(action: DatasourceAction<TShape>, options: {
   id: string;
 }): Promise<void>;
 //#endregion

package/dist/datasource/record.js

@@ -1,5 +1,5 @@
 import { assert, panic } from "../assertions.js";
-import { isAction } from "../action.js";
+import { isDatasourceAction } from "../action.js";
 import { readUserTimezone } from "../cookies.js";
 import { readSessionToken } from "../auth/session.js";
 import { buildFilterCriteria, buildOrderBy, dealiasFilterCriteria, dealiasOrderBy } from "./filter.js";
@@ -233,12 +233,12 @@ async function deleteRecord(action, options) {
 }
 function resolveTarget(subject, operation) {
 	const declaredBy = operation === "read" ? "defineQuery" : "defineMutation";
-	assert(isAction(subject), () => `Expected an action from ${declaredBy} but got ${JSON.stringify(subject)}`);
+	assert(isDatasourceAction(subject), () => `Expected an action from ${declaredBy} but got ${JSON.stringify(subject)}`);
 	const action = subject;
-	assert(action.operation === operation, () => `action "${action.id}" is declared as ${action.operation}, not ${operation}`);
+	assert(action.resource.operation === operation, () => `action "${action.id}" is declared as ${action.resource.operation}, not ${operation}`);
 	return {
-		datasourceId: action.datasource,
-		select: action.fields ?? {}
+		datasourceId: action.resource.datasourceId,
+		select: action.resource.fields ?? {}
 	};
 }
 function aliasFields(fields, aliases) {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { SoftrDatasources, defineMutation, defineQuery } from "./action.js";
+import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { SoftrContext } from "./auth/context.js";
 import { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { DefaultErrorOverlay, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineMutation, defineQuery, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { type ActionPermissions, DefaultErrorOverlay, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { defineMutation, defineQuery } from "./action.js";
+import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 
-export { DefaultErrorOverlay, defineMutation, defineQuery, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.30-alpha.0";
+var version = "0.0.31";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.30-alpha.0",
+  "version": "0.0.31",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 # Softr SDK core
@@ -21,7 +21,7 @@ metadata:
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register the middleware and resolve the session. Do not add a second registration.
-> **CRITICAL**: `workflow.trigger` is exploratory. It exists on the entrypoints below and typechecks, but its endpoint is not final. Do not build a feature on it. Tell the user the capability is not ready and ask how they want to proceed.
+> **CRITICAL**: `workflow.trigger` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineWorkflow` from `@softr/sdk` to declare the action, then pass it to `workflow.trigger`. Load the `softr-sdk/workflows` sub-skill for the full pattern.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `record-queries` plus `routes-and-visibility`.
 
@@ -43,6 +43,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Fetch records from a datasource | [record-queries/SKILL.md](./record-queries/SKILL.md) |
 | Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
 | Create, update or delete a record | [record-mutations/SKILL.md](./record-mutations/SKILL.md) |
+| Trigger a Softr workflow | [workflows/SKILL.md](./workflows/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 
@@ -64,6 +65,9 @@ Drawing a chart, a stat tile, or any aggregated number?
 Submitting a form, editing a record, or deleting one?
   load softr-sdk/record-mutations
 
+Triggering a Softr workflow from a button or form?
+  load softr-sdk/workflows
+
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
 

package/skills/softr-sdk/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -30,7 +30,7 @@ import { ds } from '@softr/sdk/server'
 
 const sales = defineQuery({
   id: 'sales',
-  datasource: '00000000-0000-0000-0000-000000000000',
+  datasourceId: '00000000-0000-0000-0000-000000000000',
   fields: {
     amount: 'Vk9cXm2pSz6Ld4',   // CURRENCY
     region: 'fZk3Qm9pLw2Xa1',   // SELECT
@@ -38,7 +38,7 @@ const sales = defineQuery({
     closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
     rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
   },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 ```
 

package/skills/softr-sdk/current-user/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/integrations/SKILL.md

@@ -2,27 +2,27 @@
 name: integrations
 description: >-
   Call a third-party service connected to the app as an integration:
-  integration.fetch({ dataSourceId, url, method, queryParams, body }) from
-  @softr/sdk/server, reading the datasource id and integration type from the
-  "Attached data sources" prompt section, looking up the base URL from the
-  reference table by integrationType, constructing the URL path, and passing
-  query params as an object. Check res.ok before res.json().
+  defineIntegration from @softr/sdk declares the action with its datasourceId
+  and permissions; integration.createFetcher from @softr/sdk/server binds it
+  and returns a fetcher function you call with url, optional method, headers,
+  and body. Check res.ok before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
-**Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
 
 # Integrations
 
-`integration.fetch` calls a third-party API through Softr's authenticated proxy. It handles authorization automatically — you never set API keys or auth headers yourself.
+`integration.createFetcher` calls a third-party API through Softr's authenticated proxy. It handles authorization automatically — you never set API keys or auth headers yourself.
 
 ## Setup
 
 ```ts
 import { createServerFn } from '@tanstack/react-start'
+import { defineIntegration } from '@softr/sdk'
 import { integration } from '@softr/sdk/server'
 ```
 
@@ -34,38 +34,52 @@ When the user attaches integrations to the chat, they appear in the `## Attached
 - "Gmail" — database `<databaseId>`, integration `<integrationId>`, type `GMAIL`
 ```
 
-Use `databaseId` as `dataSourceId` in the options object passed to `integration.fetch` — that is the `database` coordinate, not the `integration` one. The `integration` value is the OAuth connection identifier; do not pass it to `integration.fetch`. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path and pass query parameters as the `queryParams` object.
+Use `databaseId` as `datasourceId` in `defineIntegration` — that is the `database` coordinate, not the `integration` one. The `integration` value is the OAuth connection identifier; do not pass it anywhere. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL path, including any query parameters, directly in the `url` string.
+
+## Declare the integration action
+
+```ts
+const googleCalendar = defineIntegration({
+  id: 'googleCalendar',
+  datasourceId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+Write the object inline in `defineIntegration`. Passing it through a variable widens the types.
 
 ## Core pattern
 
+`integration.createFetcher(action)` binds the action and returns a fetcher function. Call that function with a `url` and optional `method`, `headers`, `body`, and `signal`.
+
 ```ts
 const getCalendarEvents = createServerFn().handler(async () => {
-  const res = await integration.fetch({
-    dataSourceId: '25d60213-ef4f-4fa0-b094-a46931b2d120',
-    url: 'https://www.googleapis.com/calendar/v3/calendars/primary/events',
-    queryParams: {
-      timeMin: new Date().toISOString(),
-      singleEvents: 'true',
-      orderBy: 'startTime',
-      maxResults: '10',
-    },
-  })
+  const calendar = integration.createFetcher(googleCalendar)
+  const now = new Date().toISOString()
+  const res = await calendar(
+    `https://www.googleapis.com/calendar/v3/calendars/primary/events?timeMin=${now}&singleEvents=true&orderBy=startTime&maxResults=10`,
+  )
   if (!res.ok) throw new Error(`Integration request failed: ${res.status} ${await res.text()}`)
   return res.json()
 })
 ```
 
-`dataSourceId` is the `databaseId` from the attached data sources section — the `database` coordinate, not the `integration` one. The base URL (`https://www.googleapis.com`) is looked up from the reference table below by matching `integrationType` (`GOOGLE_CALENDAR`). The path and query params come from your knowledge of the Google Calendar REST API.
+Include query parameters directly in the `url` string — there is no separate `queryParams` option.
 
 ## POST request
 
 ```ts
+const slackDs = defineIntegration({
+  id: 'slack',
+  datasourceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
+})
+
 const sendSlackMessage = createServerFn({ method: 'POST' })
   .validator((data: { channel: string; text: string }) => data)
   .handler(async ({ data }) => {
-    const res = await integration.fetch({
-      dataSourceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
-      url: 'https://slack.com/api/chat.postMessage',
+    const slack = integration.createFetcher(slackDs)
+    const res = await slack('https://slack.com/api/chat.postMessage', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ channel: data.channel, text: data.text }),
@@ -141,4 +155,4 @@ If the API the user needs is not in the table above, call it directly from a ser
 
 **Setting Authorization headers.** Softr injects credentials automatically. A manually set `Authorization` header overrides the injected one and the request is rejected by the third-party API.
 
-**Not checking `res.ok`.** `integration.fetch` returns the proxied response as-is. A 4xx or 5xx from the third-party API is not thrown — call `res.ok` or `res.status` before calling `res.json()`.
+**Not checking `res.ok`.** The fetcher returns the proxied response as-is. A 4xx or 5xx from the third-party API is not thrown — call `res.ok` or `res.status` before calling `res.json()`.

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -38,18 +38,18 @@ A mutation declares exactly one operation, and each of the three needs its own d
 ```ts
 const createProject = defineMutation({
   id: 'createProject',
-  datasource: '00000000-0000-0000-0000-000000000000',
+  datasourceId: '00000000-0000-0000-0000-000000000000',
   operation: 'create',
   fields: {
     name: 'fZk3Qm9pLw2Xa1',    // SINGLE_LINE_TEXT
     status: 'Ru7bVx2cNq0Ed9',  // SELECT, choice ids 'draft' | 'active' | 'archived'
     dueDate: 'Xp2dLh6vKz9Fa3', // DATETIME
   },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 ```
 
-The declaration follows the same rules as a read, spelled out in [record-queries](../record-queries/SKILL.md): `id` reads like a name and is unique across the app, queries counted alongside mutations; `datasource` is the opaque UUID from the table's registration, never derived from its name; the keys of `fields` are names you choose and the values are opaque field ids; `permission` declares who may run the mutation, from the same three choices, and the SDK enforces it; and the object is written inline, because passing it through a variable or a spread widens the field ids and the types stop checking.
+The declaration follows the same rules as a read, spelled out in [record-queries](../record-queries/SKILL.md): `id` reads like a name and is unique across the app, queries counted alongside mutations; `datasourceId` is the opaque UUID from the table's registration, never derived from its name; the keys of `fields` are names you choose and the values are opaque field ids; `permissions` declares who may run the mutation, from the same three choices, and the SDK enforces it; and the object is written inline, because passing it through a variable or a spread widens the field ids and the types stop checking.
 
 The mutation's `fields` bound the write: `data` can only name them, and the returned record only carries them. A delete mutation declares no `fields`, and giving it some is a type error.
 
@@ -76,10 +76,10 @@ Returns the created record as `{ id, fields }`, with `fields` keyed by the mutat
 ```ts
 const updateProject = defineMutation({
   id: 'updateProject',
-  datasource: '00000000-0000-0000-0000-000000000000',
+  datasourceId: '00000000-0000-0000-0000-000000000000',
   operation: 'update',
   fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 
 const archiveProject = createServerFn({ method: 'POST' })
@@ -98,9 +98,9 @@ The record id is its own option; keep it out of `data`. An empty `id` throws.
 ```ts
 const deleteProject = defineMutation({
   id: 'deleteProject',
-  datasource: '00000000-0000-0000-0000-000000000000',
+  datasourceId: '00000000-0000-0000-0000-000000000000',
   operation: 'delete',
-  permission: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 
 const removeProject = createServerFn({ method: 'POST' })
@@ -119,9 +119,9 @@ An edit form needs both halves: a `defineQuery` to load the record and a `define
 ```ts
 const projectDetail = defineQuery({
   id: 'projectDetail',
-  datasource: '00000000-0000-0000-0000-000000000000',
+  datasourceId: '00000000-0000-0000-0000-000000000000',
   fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 
 const project = await ds.get(projectDetail, { id })

package/skills/softr-sdk/record-queries/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -38,21 +38,21 @@ Every read takes a query: which datasource, which fields, who it is for.
 ```ts
 const publishedPosts = defineQuery({
   id: 'publishedPosts',
-  datasource: '00000000-0000-0000-0000-000000000000',
+  datasourceId: '00000000-0000-0000-0000-000000000000',
   fields: {
     title: 'fZk3Qm9pLw2Xa1',      // SINGLE_LINE_TEXT
     published: 'Ru7bVx2cNq0Ed9',  // CHECKBOX
     publishedAt: 'Xp2dLh6vKz9Fa3',// DATETIME
     views: 'mB4kQ8yTn1sWc7',      // NUMBER
   },
-  permission: { userGroup: 'ALL_USERS' },
+  permissions: { userGroup: 'ALL_USERS' },
 })
 ```
 
 - `id` is the name the person building the app sees, so `publishedPosts`, not `q1`. It must be unique across the app: no two declarations may share one, queries and mutations counted together.
-- `datasource` is the opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is not the table id and is never derived from the table's name.
+- `datasourceId` is the opaque UUID from the table's registration on the application (Softr Studio's Data tab, or the `register_application_data_source` tool when an agent does it). It is not the table id and is never derived from the table's name.
 - The keys of `fields` are names you choose. The values are field ids, opaque strings the table's schema gives you: `get_table` returns them for a Softr table, `list_data_source_table_fields` for a table on a connected database. Everything downstream speaks your names: the returned records, `where`, `orderBy`.
-- `permission` declares who may run the query, and the SDK enforces it:
+- `permissions` declares who may run the query, and the SDK enforces it:
   - `{ userGroup: 'ALL_USERS' }`: everyone, signed out included.
   - `{ userGroup: 'NON_LOGGED_IN_USERS' }`: signed-out visitors only.
   - `{ userGroup: 'LOGGED_IN_USERS' }`: any signed-in visitor, narrowed to particular groups with `userGroupIds: ['00000000-0000-0000-0000-00000000000a']`.
@@ -132,9 +132,9 @@ if (first.nextOffset !== null) {
 ```ts
 const myInvoices = defineQuery({
   id: 'myInvoices',
-  datasource: '00000000-0000-0000-0000-000000000001',
+  datasourceId: '00000000-0000-0000-0000-000000000001',
   fields: { owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' },
-  permission: { userGroup: 'LOGGED_IN_USERS' },
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
 })
 
 const listMyInvoices = createServerFn().handler(async ({ context }) => {
@@ -144,7 +144,7 @@ const listMyInvoices = createServerFn().handler(async ({ context }) => {
 })
 ```
 
-The SDK enforces `permission`, so a visitor outside the declared audience never reaches the records. Which of those records belong to one visitor is a separate question, and the `where` above answers it: a group says nothing about who owns a row, so a per-visitor read filters on `context.user`. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
+The SDK enforces `permissions`, so a visitor outside the declared audience never reaches the records. Which of those records belong to one visitor is a separate question, and the `where` above answers it: a group says nothing about who owns a row, so a per-visitor read filters on `context.user`. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
 
 A read the datasource turns down throws rather than coming back empty, and it throws a plain `Error` carrying the status. There is no typed predicate to narrow it with. Handle it where you would handle any other failed fetch: an `errorComponent` on the route, or a check in the handler.
 

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.29
+  library_version: 0.0.31
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/workflows/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: workflows
+description: >-
+  Trigger a Softr workflow from a server function: defineWorkflow from @softr/sdk
+  declares the action with its workflowId, triggerId, permissions, and optional
+  hardcoded body; workflow.trigger from @softr/sdk/server fires it with an optional
+  flat runtime payload and resolves to void when the workflow finishes.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.31
+---
+
+**Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+
+# Triggering workflows
+
+`workflow.trigger` fires a Softr workflow and waits for it to finish. It resolves to `void`.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineWorkflow } from '@softr/sdk'
+import { workflow } from '@softr/sdk/server'
+```
+
+## Declare the workflow action
+
+Every trigger needs a workflow action: which workflow, which trigger step, who may run it, and any data that is always sent.
+
+```ts
+const sendWelcomeEmail = defineWorkflow({
+  id: 'sendWelcomeEmail',
+  workflowId: 'c9d8e7f6-a5b4-4c3d-8e2f-1a0b9c8d7e6f',
+  triggerId: '926da496-749f-4006-999c-197d8a556122',
+  permissions: { userGroup: 'LOGGED_IN_USERS' },
+  body: {
+    email: '{LOGGED_IN_USER:EMAIL}',  // resolved server-side from the signed-in user
+    name: '{LOGGED_IN_USER:NAME}',
+    plan: 'enterprise',               // any hardcoded value — always sent, never overridden at runtime
+  },
+})
+```
+
+- `id` is a name you choose, unique across the app.
+- `workflowId` and `triggerId` are opaque UUIDs from the workflow definition in the Softr UI. Pass them as inline string literals — never derive them at runtime.
+- `permissions` declares who may run the trigger. Uses the same format as queries and mutations.
+- `body` is hardcoded data the server resolves before calling the workflow. It is **not** passed by the caller at runtime — the workflow always receives it. Template values draw from the signed-in user and the current time (see table below).
+
+Write the object inline in `defineWorkflow`. Passing it through a variable widens the types.
+
+## Template values in `body`
+
+These placeholders are resolved server-side when the workflow runs:
+
+| Value | Resolves to |
+|---|---|
+| `{LOGGED_IN_USER:EMAIL}` | Signed-in user's email |
+| `{LOGGED_IN_USER:NAME}` | Signed-in user's name |
+| `{LOGGED_IN_USER:RECORD_ID}` | Signed-in user's record id |
+| `{LOGGED_IN_USER:<field>}` | Any other field from the user record |
+| `{CURRENT_DATE_TIME}` | Current date and time |
+| `{CURRENT_DATE}` | Current date |
+
+## Core pattern
+
+```ts
+const runWorkflow = createServerFn({ method: 'POST' })
+  .validator(z.object({ message: z.string() }))
+  .handler(async ({ data }) => {
+    await workflow.trigger(sendWelcomeEmail, { message: data.message })
+  })
+```
+
+`workflow.trigger` takes the action object and an optional flat runtime payload. The payload only accepts primitive values — `string`, `number`, `boolean`, `null`. Use the action's `body` for anything that is always the same or comes from the user session.
+
+`workflow.trigger` resolves only when the workflow has finished.
+
+## Triggering without a runtime payload
+
+```ts
+const run = createServerFn({ method: 'POST' }).handler(async () => {
+  await workflow.trigger(sendWelcomeEmail)
+})
+```
+
+Omit the second argument when the action's `body` already carries everything the workflow needs.
+
+## Failure modes
+
+**Calling `workflow.trigger` from a component.** `workflow` lives on `@softr/sdk/server`. Wrap it in a `createServerFn`.
+
+```ts
+// Wrong: calling from a click handler
+<button onClick={() => workflow.trigger(sendWelcomeEmail)}>Run</button>
+
+// Correct: server function, called from the button
+const run = createServerFn({ method: 'POST' }).handler(() =>
+  workflow.trigger(sendWelcomeEmail),
+)
+// …
+const submit = useServerFn(run)
+<button onClick={() => submit()}>Run</button>
+```
+
+**Computing `workflowId` or `triggerId` at runtime.** Both are static UUIDs from the workflow definition. Derive them from user input and the call fails at request time.
+
+**Passing nested objects in the runtime payload.** The second argument to `workflow.trigger` only accepts flat values — `string`, `number`, `boolean`, or `null`. Put anything that needs server-side resolution in the action's `body` instead.
+
+**Not awaiting the result.** `workflow.trigger` is async. Fire-and-forget loses the result and swallows any error.
+
+## References
+
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to include them in the payload