@softr/sdk 0.0.68-alpha.1 → 0.0.68

package/dist/auth/current-user-row.d.ts

@@ -0,0 +1,20 @@
+import { User } from "./user.js";
+import { DatasourceAction, ReadShape } from "../action.js";
+import { GetRecord } from "../datasource/record.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/auth/current-user-row.d.ts
+
+/**
+ * The signed-in visitor's own row of the Users table, found by email, or null when they are signed out
+ * or the table holds no row for them. For a "mine" filter, an owner set on create, or a page scoped to
+ * what the visitor owns: the row's id is what a link to Users holds.
+ *
+ * @example
+ * const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+ * if (me === null) return []
+ * return ds.list(tasks).where((q) => q.assignee.isOneOf([me.id]))
+ */
+declare function currentUserRow<TShape extends ReadShape>(user: User | null, usersQuery: DatasourceAction<TShape>, email: keyof TShape["fields"] & string): Promise<GetRecord<TShape>>;
+//#endregion
+export { currentUserRow };

package/dist/auth/current-user-row.js

@@ -0,0 +1,22 @@
+import { makeChain } from "../datasource/fields.js";
+import { listRecords } from "../datasource/record.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/auth/current-user-row.ts
+/**
+* The signed-in visitor's own row of the Users table, found by email, or null when they are signed out
+* or the table holds no row for them. For a "mine" filter, an owner set on create, or a page scoped to
+* what the visitor owns: the row's id is what a link to Users holds.
+*
+* @example
+* const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+* if (me === null) return []
+* return ds.list(tasks).where((q) => q.assignee.isOneOf([me.id]))
+*/
+async function currentUserRow(user, usersQuery, email) {
+	if (user === null) return null;
+	return (await listRecords(usersQuery).where(() => makeChain(email).is(user.email)).limit(1)).records[0] ?? null;
+}
+
+//#endregion
+export { currentUserRow };

package/dist/auth/server.d.ts

@@ -6,6 +6,7 @@ import { checkPasswordLink, requestPasswordReset, setPasswordWithLink } from "./
 import { settings } from "./methods/settings.js";
 import { confirmSignUp, signUp } from "./methods/signup.js";
 import { signInWithGoogle } from "./methods/social.js";
+import { currentUserRow } from "./current-user-row.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/auth/server.d.ts
@@ -33,6 +34,7 @@ declare const auth: {
   resetAuthenticator: typeof resetAuthenticator;
   removeAuthenticator: typeof removeAuthenticator;
   settings: typeof settings;
+  currentUserRow: typeof currentUserRow;
 };
 //#endregion
 export { auth };

package/dist/auth/server.js

@@ -6,6 +6,7 @@ import { signIn, signOut } from "./methods/password.js";
 import { checkPasswordLink, requestPasswordReset, setPasswordWithLink } from "./methods/passwordLink.js";
 import { confirmSignUp, signUp } from "./methods/signup.js";
 import { signInWithGoogle } from "./methods/social.js";
+import { currentUserRow } from "./current-user-row.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/auth/server.ts
@@ -31,7 +32,8 @@ const auth = {
 	sendAuthenticatorResetCode,
 	resetAuthenticator,
 	removeAuthenticator,
-	settings
+	settings,
+	currentUserRow
 };
 
 //#endregion

package/dist/cli.js

@@ -4,6 +4,7 @@ import { requireDefined } from "./assertions.js";
 import { fetchSoftrEnvInput, metadataSourceFromEnv } from "./codegen/fetch-metadata.js";
 import { renderUserGroupsDoc } from "./codegen/user-groups.js";
 import { renderSoftrEnv } from "./codegen/softr-env.js";
+import { renderSoftrFields } from "./codegen/softr-fields.js";
 import { writeIfChanged } from "./codegen/write-if-changed.js";
 import { writeDatasourceDocs } from "./codegen/write-datasource-docs.js";
 import { writeFileSync } from "node:fs";
@@ -12,6 +13,7 @@ import { parseArgs } from "node:util";
 
 //#region src/cli.ts
 const OUTPUT = "softr-env.d.ts";
+const FIELDS_OUTPUT = "src/softr-fields.ts";
 const DOCS_DIR = "docs/datasources";
 const USER_GROUPS_DOC = "docs/user-groups.md";
 async function generate({ json }) {
@@ -19,6 +21,11 @@ async function generate({ json }) {
 	const input = await fetchSoftrEnvInput(metadataSourceFromEnv());
 	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(input, version), "utf8");
 	const report = writeDocs(input);
+	report.docs.push({
+		subject: "field shapes",
+		path: FIELDS_OUTPUT,
+		changed: writeIfChanged(path.resolve(process.cwd(), FIELDS_OUTPUT), renderSoftrFields(input.datasources, version))
+	});
 	if (json) {
 		process.stdout.write(`${JSON.stringify(report)}\n`);
 		return;

package/dist/codegen/softr-fields.js

@@ -0,0 +1,41 @@
+//#region src/codegen/softr-fields.ts
+/**
+* Renders the app's `src/softr-fields.ts`: every registered datasource's fields by id, with the type
+* and options a value's text depends on, registered with the SDK as a side effect of being imported.
+* The root route imports it once, and `formatValue(query, alias, value, formatting)` then formats any
+* value a query read by its field's own type.
+*/
+function renderSoftrFields(datasources, sdkVersion) {
+	const entries = [...datasources].sort((a, b) => a.id.localeCompare(b.id)).map((datasource) => {
+		const fields = [...datasource.fields].sort((a, b) => a.id.localeCompare(b.id)).map((field) => {
+			const shape = { type: field.type };
+			if (field.options !== null && field.options !== void 0 && Object.keys(field.options).length > 0) shape.options = field.options;
+			if (field.allowMultipleEntries) shape.allowMultipleEntries = true;
+			return `    ${JSON.stringify(field.id)}: ${JSON.stringify(shape)},`;
+		});
+		return [
+			`  // ${datasource.name}`,
+			`  ${JSON.stringify(datasource.id)}: {`,
+			...fields,
+			"  },"
+		].join("\n");
+	});
+	return [
+		`// Generated by @softr/sdk ${sdkVersion}. Do not edit: the SDK's codegen rewrites it after a schema change.`,
+		"//",
+		"// The type and options of every field, by datasource and field id, for `formatValue` and",
+		"// `fieldShape` from @softr/sdk. Imported once, in the root route, it registers them with the SDK.",
+		"import { registerSoftrFields } from \"@softr/sdk\";",
+		"import type { SoftrFieldRegistry } from \"@softr/sdk\";",
+		"",
+		"export const softrFields = {",
+		...entries,
+		"} as const satisfies SoftrFieldRegistry;",
+		"",
+		"registerSoftrFields(softrFields);",
+		""
+	].join("\n");
+}
+
+//#endregion
+export { renderSoftrFields };

package/dist/core/integration.d.ts

@@ -7,13 +7,6 @@ interface IntegrationFetchInit {
   headers?: Record<string, string>;
   body?: string;
   signal?: AbortSignal;
-  /**
-   * Relay the vendor's answer as it is produced instead of waiting for all of it — for any endpoint
-   * that streams, such as an LLM completion requested with `"stream": true`. The returned `Response`
-   * body is then the vendor's own stream, readable chunk by chunk. A vendor that answers in one piece
-   * still works.
-   */
-  stream?: boolean;
 }
 declare function integrationCreateFetcher(action: IntegrationAction): (init?: IntegrationFetchInit) => Promise<Response>;
 declare const integration: {

package/dist/core/integration.js

@@ -3,16 +3,15 @@ import { readSessionToken } from "../auth/session.js";
 import { dsUrl, refererHeader } from "../datasource/record.js";
 
 //#region src/core/integration.ts
-const EVENT_STREAM = "text/event-stream";
-async function integrationFetch(action, { params, query, headers = {}, body, signal, stream = false } = {}) {
+async function integrationFetch(action, { params, query, headers = {}, body, signal } = {}) {
 	if (signal?.aborted) throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
 	const payload = {
 		method: action.resource.method,
 		url: buildUrl(action.resource.url, params, query),
-		headers: stream ? withAcceptEventStream(headers) : headers
+		headers
 	};
 	if (body !== void 0) payload.body = body;
-	return fetch(`${dsUrl(action.id)}/${stream ? "proxy/stream" : "proxy"}`, {
+	return fetch(`${dsUrl(action.id)}/proxy`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -31,12 +30,6 @@ function buildUrl(template, params, query) {
 	if (query !== void 0 && Object.keys(query).length > 0) url += `?${new URLSearchParams(query).toString()}`;
 	return url;
 }
-function withAcceptEventStream(headers) {
-	return Object.keys(headers).some((name) => name.toLowerCase() === "accept") ? headers : {
-		...headers,
-		Accept: EVENT_STREAM
-	};
-}
 function integrationCreateFetcher(action) {
 	return (init) => integrationFetch(action, init);
 }

package/dist/core/options.d.ts

@@ -0,0 +1,36 @@
+import { DatasourceAction, ReadShape } from "../action.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/core/options.d.ts
+/** One row a linked-record picker offers. */
+type RecordOption = {
+  id: string;
+  label: string;
+};
+/** A page of a picker's rows, in the shape `LinkedRecordPicker`'s `load` answers with. */
+type RecordOptions = {
+  options: RecordOption[];
+  nextOffset: number | null;
+};
+/**
+ * The rows a linked field can point at, for a picker: each record of the query as its id and the text
+ * of one field, searched on that field when a term is given, a page at a time.
+ *
+ * @example
+ * const loadCompanies = createServerFn()
+ *   .validator(z.object({ term: z.string(), offset: z.number().nullable() }))
+ *   .handler(({ data }) => ds.options(companiesQuery, { label: 'name', ...data }))
+ */
+declare function listOptions<TShape extends ReadShape>(query: DatasourceAction<TShape>, {
+  label,
+  term,
+  offset,
+  limit
+}: {
+  label: keyof TShape["fields"] & string;
+  term?: string;
+  offset?: number | null;
+  limit?: number;
+}): Promise<RecordOptions>;
+//#endregion
+export { RecordOption, RecordOptions, listOptions };

package/dist/core/options.js

@@ -0,0 +1,39 @@
+import { makeChain } from "../datasource/fields.js";
+import { listRecords } from "../datasource/record.js";
+import "@tanstack/react-start/server-only";
+
+//#region src/core/options.ts
+/**
+* The rows a linked field can point at, for a picker: each record of the query as its id and the text
+* of one field, searched on that field when a term is given, a page at a time.
+*
+* @example
+* const loadCompanies = createServerFn()
+*   .validator(z.object({ term: z.string(), offset: z.number().nullable() }))
+*   .handler(({ data }) => ds.options(companiesQuery, { label: 'name', ...data }))
+*/
+async function listOptions(query, { label, term = "", offset = null, limit = 20 }) {
+	let list = listRecords(query).limit(limit).offset(offset);
+	const needle = term.trim();
+	if (needle !== "") list = list.where(() => makeChain(label).contains(needle));
+	const page = await list;
+	return {
+		options: page.records.map((record) => ({
+			id: record.id,
+			label: labelOf(record.fields[label])
+		})),
+		nextOffset: page.nextOffset
+	};
+}
+/** The text a label field holds: its own text, or the label of the choice or record it names. */
+function labelOf(value) {
+	if (value === null || value === void 0) return "";
+	if (typeof value === "object") {
+		const label = value.label;
+		return typeof label === "string" ? label : "";
+	}
+	return String(value);
+}
+
+//#endregion
+export { listOptions };

package/dist/core/use-overrides.d.ts

@@ -0,0 +1,17 @@
+//#region src/core/use-overrides.d.ts
+/**
+ * The edits a page has saved that its loader has not re-run for, keyed by record id: what a drawer or
+ * an inline control wrote, merged over the loader's rows until a fresh read replaces them.
+ *
+ * `onSaved` is the shape a drawer's `onSaved` callback takes: it fires before the write, and again
+ * with the old value if the write fails, so the row moves at once and moves back on failure.
+ */
+declare function useOverrides<TPatch extends object>(): {
+  /** What is pending for one record, or undefined when nobody has touched it. */
+  of: (recordId: string) => TPatch | undefined;
+  onSaved: (recordId: string, patch: TPatch) => void;
+  /** Drops what is pending for one record, once a fresh read of it has replaced the row. */
+  clear: (recordId: string) => void;
+};
+//#endregion
+export { useOverrides };

package/dist/core/use-overrides.js

@@ -0,0 +1,30 @@
+import { useState } from "react";
+
+//#region src/core/use-overrides.ts
+/**
+* The edits a page has saved that its loader has not re-run for, keyed by record id: what a drawer or
+* an inline control wrote, merged over the loader's rows until a fresh read replaces them.
+*
+* `onSaved` is the shape a drawer's `onSaved` callback takes: it fires before the write, and again
+* with the old value if the write fails, so the row moves at once and moves back on failure.
+*/
+function useOverrides() {
+	const [pending, setPending] = useState({});
+	return {
+		of: (recordId) => pending[recordId],
+		onSaved: (recordId, patch) => setPending((current) => ({
+			...current,
+			[recordId]: {
+				...current[recordId],
+				...patch
+			}
+		})),
+		clear: (recordId) => setPending((current) => ({
+			...current,
+			[recordId]: void 0
+		}))
+	};
+}
+
+//#endregion
+export { useOverrides };

package/dist/datasource/datasource.d.ts

@@ -1,4 +1,5 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
+import { listOptions } from "../core/options.js";
 import { chart, metric } from "./chart.js";
 import "@tanstack/react-start/server-only";
 
@@ -11,6 +12,7 @@ declare const ds: {
   delete: typeof deleteRecord;
   metric: typeof metric;
   chart: typeof chart;
+  options: typeof listOptions;
 };
 //#endregion
 export { ds };

package/dist/datasource/datasource.js

@@ -1,5 +1,6 @@
 import { createRecord, deleteRecord, getRecord, listRecords, updateRecord } from "./record.js";
 import { chart, metric } from "./chart.js";
+import { listOptions } from "../core/options.js";
 import "@tanstack/react-start/server-only";
 
 //#region src/datasource/datasource.ts
@@ -10,7 +11,8 @@ const ds = {
 	update: updateRecord,
 	delete: deleteRecord,
 	metric,
-	chart
+	chart,
+	options: listOptions
 };
 
 //#endregion

package/dist/datasource/fields.js

@@ -46,7 +46,8 @@ function group(logicalOperator, filters) {
 /**
 * One chain per alias, carrying every operator whatever the alias reads as. Only the types
 * narrow: a call the types reject cannot reach here, so there is nothing for a per-type
-* runtime chain to catch.
+* runtime chain to catch. Exported for a filter built on an alias the caller named, where no
+* type stands behind the chain.
 */
 function makeChain(subject) {
 	return {
@@ -87,4 +88,4 @@ function leaf(subject, operator, value) {
 }
 
 //#endregion
-export { andAll, makeFieldSet, makeSortSet };
+export { andAll, makeChain, makeFieldSet, makeSortSet };

package/dist/datasource/record.d.ts

@@ -68,6 +68,7 @@ interface ListResult<TRecord extends SoftrRecord = SoftrRecord> {
   total: number;
   nextOffset: number | null;
 }
+type GetRecord<TShape extends ReadShape> = SoftrRecord<ActionRecord<TShape>> | null;
 /**
  * Queries a list of records from the datasource.
  *
@@ -135,4 +136,4 @@ declare function deleteRecord<TShape extends ActionShape & {
   id: string;
 }): Promise<void>;
 //#endregion
-export { WhereCallback, createRecord, deleteRecord, getRecord, listRecords, updateRecord };
+export { GetRecord, WhereCallback, createRecord, deleteRecord, getRecord, listRecords, updateRecord };

package/dist/fields/format.d.ts

@@ -0,0 +1,45 @@
+import { Formatting } from "../formatting.js";
+
+//#region src/fields/format.d.ts
+
+/**
+ * A field's type and options, which is all its text depends on. The generated `src/softr-fields.ts`
+ * holds one per field of every registered datasource.
+ */
+type FieldShape = {
+  type: string;
+  options?: Record<string, unknown> | null;
+  /** True when the field holds several values, which read back as an array. */
+  allowMultipleEntries?: boolean;
+};
+/** The fields of every registered datasource, by datasource id then field id. */
+type SoftrFieldRegistry = Record<string, Record<string, FieldShape>>;
+/**
+ * Makes the app's fields known to `fieldShape` and `formatValue`. The generated `src/softr-fields.ts`
+ * calls it once as a side effect of being imported; the root route imports that file.
+ */
+declare function registerSoftrFields(fields: SoftrFieldRegistry): void;
+/**
+ * The shape of a field a query reads, by the alias the query holds it under. Throws when the app has
+ * not registered its fields: the generated `src/softr-fields.ts` is not imported.
+ */
+declare function fieldShape(query: {
+  datasourceId: string;
+  fields: Record<string, string>;
+}, alias: string): FieldShape;
+/**
+ * A value a query read, as the text a page shows it as, by the field's own type and options: money with
+ * its symbol, a date in the app's format, a choice or a linked record by its label, a rating out of its
+ * scale, a duration in hours and minutes, a checkbox as Yes or No. '' for a value the record does not
+ * hold. Several values read joined by a comma.
+ */
+declare function formatValue(query: {
+  datasourceId: string;
+  fields: Record<string, string>;
+}, alias: string, value: unknown, formatting: Formatting): string;
+/** `formatValue` for a shape in hand, such as one from `src/softr-fields.ts` or a `returnedField`. */
+declare function formatField(shape: FieldShape, value: unknown, formatting: Formatting): string;
+/** A duration, which the datasource holds in milliseconds, as hours and minutes; seconds only under an hour. */
+declare function formatDuration(milliseconds: number): string;
+//#endregion
+export { FieldShape, SoftrFieldRegistry, fieldShape, formatDuration, formatField, formatValue, registerSoftrFields };

package/dist/fields/format.js

@@ -0,0 +1,140 @@
+import { formatDate, formatDateTime, formatNumber } from "../formatting.js";
+
+//#region src/fields/format.ts
+let registry = {};
+/**
+* Makes the app's fields known to `fieldShape` and `formatValue`. The generated `src/softr-fields.ts`
+* calls it once as a side effect of being imported; the root route imports that file.
+*/
+function registerSoftrFields(fields) {
+	registry = {
+		...registry,
+		...fields
+	};
+}
+/**
+* The shape of a field a query reads, by the alias the query holds it under. Throws when the app has
+* not registered its fields: the generated `src/softr-fields.ts` is not imported.
+*/
+function fieldShape(query, alias) {
+	const fieldId = query.fields[alias];
+	if (fieldId === void 0) throw new Error(`The query has no field "${alias}"; it reads ${Object.keys(query.fields).join(", ")}.`);
+	const shape = registry[query.datasourceId]?.[fieldId];
+	if (shape === void 0) throw new Error(`No shape is registered for field ${fieldId} of datasource ${query.datasourceId}. Import the generated src/softr-fields.ts once, in the root route, and run the SDK's codegen after a schema change.`);
+	return shape;
+}
+/**
+* A value a query read, as the text a page shows it as, by the field's own type and options: money with
+* its symbol, a date in the app's format, a choice or a linked record by its label, a rating out of its
+* scale, a duration in hours and minutes, a checkbox as Yes or No. '' for a value the record does not
+* hold. Several values read joined by a comma.
+*/
+function formatValue(query, alias, value, formatting) {
+	return formatField(fieldShape(query, alias), value, formatting);
+}
+/** `formatValue` for a shape in hand, such as one from `src/softr-fields.ts` or a `returnedField`. */
+function formatField(shape, value, formatting) {
+	if (value === null || value === void 0) return "";
+	if (Array.isArray(value)) return value.map((entry) => formatField({
+		...shape,
+		allowMultipleEntries: false
+	}, entry, formatting)).filter((text$1) => text$1 !== "").join(", ");
+	const returned = computedReturns(shape);
+	if (returned !== null) return formatField(returned, value, formatting);
+	const options = shape.options ?? {};
+	switch (shape.type) {
+		case "CHECKBOX": return value === true ? "Yes" : "No";
+		case "NUMBER":
+		case "COUNT":
+		case "PROGRESS": return typeof value === "number" ? formatNumber(value, formatting, digits(precisionOf(options))) : text(value);
+		case "AUTONUMBER": return text(value);
+		case "CURRENCY": {
+			if (typeof value !== "number") return text(value);
+			const code = options.isoCode;
+			const precision = precisionOf(options) ?? 2;
+			const cents = {
+				minimumFractionDigits: Number.isInteger(value) ? 0 : precision,
+				maximumFractionDigits: precision
+			};
+			if (typeof code === "string" && /^[A-Z]{3}$/.test(code)) return formatNumber(value, formatting, {
+				style: "currency",
+				currency: code,
+				...cents
+			});
+			const amount = formatNumber(value, formatting, cents);
+			const symbol = typeof options.customSymbol === "string" ? options.customSymbol : "";
+			if (symbol === "") return amount;
+			return options.symbolOrCodePosition === "AFTER" ? `${amount} ${symbol}` : `${symbol}${amount}`;
+		}
+		case "PERCENT": return typeof value === "number" ? `${formatNumber(value, formatting, digits(precisionOf(options)))}%` : text(value);
+		case "RATING": return typeof value === "number" ? `${value}/${numberOption(options, "max") ?? 5}` : text(value);
+		case "DURATION": return typeof value === "number" ? formatDuration(value) : text(value);
+		case "DATE":
+		case "DATETIME": return isDateValue(value) ? formatDateTime(value, formatting, { dateStyle: "medium" }) : text(value);
+		case "CREATED_AT":
+		case "UPDATED_AT":
+			if (!isDateValue(value)) return text(value);
+			return options.precision === "DATE" ? formatDate(value, formatting, { dateStyle: "medium" }) : formatDateTime(value, formatting, { dateStyle: "medium" });
+		case "DATE_RANGE": {
+			const range = value;
+			return [isDateValue(range.from) ? formatDateTime(range.from, formatting, { dateStyle: "medium" }) : "", isDateValue(range.to) ? formatDateTime(range.to, formatting, { dateStyle: "medium" }) : ""].filter((part) => part !== "").join(" – ");
+		}
+		case "USER": {
+			const person = value;
+			return text(person.name ?? person.email);
+		}
+		case "ATTACHMENT": {
+			const file = value;
+			return typeof file.filename === "string" && file.filename !== "" ? file.filename : "File";
+		}
+		default:
+			if (typeof value === "object" && "label" in value) return text(value.label);
+			return text(value);
+	}
+}
+/** The shape a FORMULA, LOOKUP or ROLLUP reads as, when its options say; null for any other field. */
+function computedReturns(shape) {
+	if (shape.type !== "FORMULA" && shape.type !== "LOOKUP" && shape.type !== "ROLLUP") return null;
+	const returned = shape.options?.returnedField;
+	if (typeof returned !== "object" || returned === null || !("type" in returned) || typeof returned.type !== "string") return null;
+	const options = "options" in returned && typeof returned.options === "object" ? returned.options : null;
+	return {
+		type: returned.type,
+		options
+	};
+}
+function text(value) {
+	return value === null || value === void 0 ? "" : String(value);
+}
+function isDateValue(value) {
+	return typeof value === "string" && value !== "" || typeof value === "number" || value instanceof Date;
+}
+function numberOption(options, key) {
+	const value = options[key];
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
+}
+function precisionOf(options) {
+	return numberOption(options, "precision");
+}
+function digits(precision) {
+	return precision === void 0 ? void 0 : {
+		minimumFractionDigits: precision,
+		maximumFractionDigits: precision
+	};
+}
+/** A duration, which the datasource holds in milliseconds, as hours and minutes; seconds only under an hour. */
+function formatDuration(milliseconds) {
+	const total = Math.round(milliseconds / 1e3);
+	const hours = Math.floor(total / 3600);
+	const minutes = Math.floor(total % 3600 / 60);
+	const rest = total % 60;
+	const parts = [
+		hours > 0 ? `${hours}h` : "",
+		minutes > 0 ? `${minutes}m` : "",
+		hours === 0 && rest > 0 ? `${rest}s` : ""
+	].filter((part) => part !== "");
+	return parts.length === 0 ? "0m" : parts.join(" ");
+}
+
+//#endregion
+export { fieldShape, formatDuration, formatField, formatValue, registerSoftrFields };

package/dist/index.d.ts

@@ -10,8 +10,10 @@ import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedErr
 import { toReturnPath } from "./auth/returnPath.js";
 import { AuthOptions, AuthSettingsProvider, getAuthSettings, getSoftrContext, initialSoftrContext, softrAuthMiddleware, useAuthSettings, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
+import { FieldShape, SoftrFieldRegistry, fieldShape, formatDuration, formatField, formatValue, registerSoftrFields } from "./fields/format.js";
+import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, type AuthOptions, type AuthSettings, AuthSettingsProvider, type DateOptions, type DateParts, type DateSeparator, type DateValue, DefaultErrorOverlay, type FieldShape, type FileAttachment, type FileItem, type FixedDateFormat, FormattedDate, type Formatting, FormattingScope, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, type SoftrFieldRegistry, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, type WeekDay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/index.js

@@ -7,8 +7,10 @@ import { FormattedDate, FormattingScope, formatDate, formatDateTime, formatNumbe
 import { SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { AuthSettingsProvider, getAuthSettings, getSoftrContext, initialSoftrContext, softrAuthMiddleware, useAuthSettings, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
+import { fieldShape, formatDuration, formatField, formatValue, registerSoftrFields } from "./fields/format.js";
+import { useOverrides } from "./core/use-overrides.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, formatDate, formatDateTime, formatNumber, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, usePwaInstall, useUserTimezone };
+export { Audience, AuthSettingsProvider, DefaultErrorOverlay, FormattedDate, FormattingScope, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, fieldShape, formatDate, formatDateTime, formatDuration, formatField, formatNumber, formatValue, getAuthSettings, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, registerSoftrFields, softrAuthMiddleware, softrMcpMiddleware, toReturnPath, useAuthSettings, useCurrentUser, useFileUpload, useFormatting, useOverrides, usePwaInstall, useUserTimezone };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start0 from "@tanstack/react-start";
+import * as _tanstack_react_start4 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start4.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

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

package/dist/server.d.ts

@@ -1,7 +1,8 @@
 import { upload } from "./core/file-upload.js";
 import { auth } from "./auth/server.js";
+import { RecordOption, RecordOptions } from "./core/options.js";
 import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
-export { auth, ds, integration, upload, workflow };
+export { type RecordOption, type RecordOptions, auth, ds, integration, upload, workflow };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 # Softr SDK core
@@ -30,7 +30,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `FormattedDate`, `FormattingScope`, `useFormatting`, `formatDate`, `formatDateTime`, `formatNumber`, `formatValue`, `formatField`, `fieldShape`, `registerSoftrFields`, `useOverrides`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -48,7 +48,6 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | 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) |
-| Show an AI answer as it is written (a chat, an assistant, a live summary) | [integrations/SKILL.md](./integrations/SKILL.md), section "Streaming a vendor answer" |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
@@ -83,9 +82,6 @@ Wiring a login, signup, or sign-out?
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
   load softr-sdk/integrations
 
-Showing an AI answer as it is written: a chat, an assistant, a summary that types itself out?
-  load softr-sdk/integrations and stream the call: its "Streaming a vendor answer" section
-
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 

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

@@ -19,7 +19,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

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.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 # Dates, times and numbers
@@ -116,6 +116,24 @@ The currency comes from the field or from the user, never from the locale. A Ger
 
 `formatDate` and `formatDateTime` show a timestamp in UTC while `formatting.timeZone` is `null`. In JSX, prefer `<FormattedDate />`, which waits instead.
 
+### A field's own text: `formatValue`
+
+A value a query read already knows how it should look: money with its symbol and cents, a percent, a rating out of its scale, a duration in hours and minutes, a date in the app's format, a choice or a linked record by its label, a checkbox as Yes or No, several values joined by a comma, `''` for nothing. `formatValue` reads the field's type and options from the generated `src/softr-fields.ts` and does all of it, so a page never branches on a type itself.
+
+```tsx
+import { formatValue, useFormatting } from '@softr/sdk'
+import { dealsQuery } from '#/server/deals.ts'
+
+function Amount({ deal }: { deal: Deal }) {
+  const formatting = useFormatting()
+  return <span>{formatValue(dealsQuery, 'amount', deal.fields.amount, formatting)}</span>
+}
+```
+
+The second argument is the alias the query holds the field under. `formatField(shape, value, formatting)` does the same for a shape in hand, and `fieldShape(query, alias)` reads one.
+
+The SDK's codegen writes `src/softr-fields.ts` beside `softr-env.d.ts` after every schema change; it registers the shapes as a side effect of being imported, and the root route imports it once. `formatValue` throws when that import is missing.
+
 ### Outside render: a server function or `beforeLoad`
 
 Not every date ends up in a component. A CSV or spreadsheet export, a text the server sends, or a value a loader prepares are formatted before React runs. There, `context.formatting` holds the same `Formatting` that `useFormatting()` returns. See [current-user](../current-user/SKILL.md) for how `context` reaches a handler.

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

@@ -5,12 +5,12 @@ description: >-
   defineIntegration from @softr/sdk declares the action with its integrationId,
   the one HTTP method and endpoint url it allows, and permissions;
   integration.createFetcher from @softr/sdk/server binds it and returns a
-  fetcher function you call with optional params, query, headers, body, and
-  stream for a vendor answer that arrives in pieces. Check res.ok before res.json().
+  fetcher function you call with optional params, query, headers, and body.
+  Check res.ok before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **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.
@@ -129,15 +129,9 @@ Do not add an `Authorization` key to `headers` — Softr injects the integration
 
 ## Calling an AI model
 
-**Two shapes, decided by who reads the answer.** An answer the user reads as it is written — a chat, an
-assistant, a long summary shown on the page — streams: pass `stream: true` and relay the body, see
-[Streaming a vendor answer](#streaming-a-vendor-answer) below. An answer the server reads — JSON the page
-lays out, text saved to a field — is buffered: the call below, then `res.json()`. A chat is never buffered:
-the user would watch a blank panel until the last token.
-
 A button on one record that hands its fields to the model and shows the answer is the `ai-action` pattern:
-it carries the buffered call and the model id, so write the call by hand only for another shape — a batch,
-a field the model fills on create, or a chat, which streams. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on
+it carries this call and the model id, so write the call by hand only for another shape — a batch, a chat,
+a field the model fills on create. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on
 `https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of
 `model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
 
@@ -170,49 +164,6 @@ const text = body.content.flatMap((block) => (block.type === 'text' && block.tex
 the button is pressed. `claude-opus-5-5` is the current default; `claude-sonnet-5-5` is the cheaper one for a
 short summary.
 
-## Streaming a vendor answer
-
-Some vendor endpoints can send their answer in pieces while they produce it — LLM completions token by token, long exports, live event feeds. The fetcher relays such an answer as it arrives when you pass `stream: true`; the response body is then the vendor's own stream, unchanged.
-
-Every connected LLM streams its completion. Ask the vendor for it in the request **and** pass `stream: true` to the fetcher; one without the other gains nothing:
-
-| integrationType | Endpoint | How to ask for the stream |
-|---|---|---|
-| ANTHROPIC_AI | `POST /v1/messages` | `"stream": true` in the body |
-| OPEN_AI | `POST /v1/chat/completions` or `POST /v1/responses` | `"stream": true` in the body |
-| GEMINI_AI | `POST /v1beta/models/{model}:streamGenerateContent` with `query: { alt: 'sse' }` | the endpoint itself; `generateContent` never streams, so the action's `url` must name the streaming one |
-| MISTRAL_AI | `POST /v1/chat/completions` | `"stream": true` in the body |
-| DEEP_SEEK_AI | `POST /chat/completions` | `"stream": true` in the body |
-| COHERE | `POST /v2/chat` | `"stream": true` in the body |
-
-For any other vendor, read that endpoint's docs: it streams when they offer a `stream` flag, an `Accept: text/event-stream` variant, or a chunked response to read incrementally. Most REST calls answer in one piece; call those without `stream` and `res.json()` works.
-
-Hand a streamed body to the browser as a `Response` from the server function and read it there. The example below streams a completion through the `askClaude` action declared above; the same shape applies to any vendor endpoint that streams.
-
-```ts
-const streamAnswer = createServerFn({ method: 'POST' })
-  .validator((data: { prompt: string }) => data)
-  .handler(async ({ data }) => {
-    const claude = integration.createFetcher(askClaude)
-    const res = await claude({
-      stream: true,
-      headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
-      body: JSON.stringify({
-        model: 'claude-opus-5-5',
-        max_tokens: 1024,
-        stream: true,
-        messages: [{ role: 'user', content: data.prompt }],
-      }),
-    })
-    if (!res.ok) throw new Error(`AI error: ${res.status} ${await res.text()}`)
-    return new Response(res.body, { headers: { 'Content-Type': 'text/event-stream' } })
-  })
-```
-
-On the client, call the server function's URL with `fetch` and read `response.body` with a `ReadableStream` reader; each chunk arrives in the vendor's own format, for an event stream one or more `event:`/`data:` frames. Use `stream: true` only together with a request that asks the vendor to stream: without it the vendor answers in one piece, which still works but gains nothing.
-
-`stream: true` is not available for REST_API integrations; those always answer in one piece.
-
 ## Base URLs by integration type
 
 Match the `integrationType` from the attached integrations section to find the base URL:
@@ -284,7 +235,3 @@ If the API the user needs is not in the table above, call it directly from a ser
 **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()`.
 
 **Reusing one action for a different endpoint.** An action authorizes one `method` and one endpoint `url`. A different endpoint belongs to a different action — declare one for it, with its own audience.
-
-**Buffering an answer the user watches being written.** A chat or assistant called without `stream: true` shows nothing until the last token arrives, and a long answer then hits the proxy's read timeout. Pass `stream: true`, ask the vendor to stream in the request, and return `res.body` in a `Response`.
-
-**Reading a streamed body with `res.json()`.** With `stream: true` the body is an event stream, not one JSON document. Return `res.body` in a `Response` or read it with a stream reader; `res.json()` waits for the end and then fails to parse.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 # Installing the app

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

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **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.
@@ -135,6 +135,18 @@ await ds.update(updateProject, {
 
 A read answers a SELECT as `{ id, label }` and a write takes `{ id }`, so pass the id through rather than the whole value.
 
+### Show the edit before the loader re-runs
+
+A list whose rows a drawer or an inline control edits keeps the saved values over the loader's rows until a fresh read replaces them. `useOverrides` holds them by record id:
+
+```tsx
+const overrides = useOverrides<Partial<Deal['fields']>>()
+const rows = deals.map((deal) => ({ ...deal, fields: { ...deal.fields, ...overrides.of(deal.id) } }))
+<DealsDrawer onSaved={overrides.onSaved} />
+```
+
+`onSaved(recordId, patch)` is what a drawer calls before the write and again with the old value if the write fails; `clear(recordId)` drops a record's patch once the page has reloaded it.
+
 ### Form dropdowns for linked record fields
 
 A form select for a `LINKED_RECORD` field needs its options from the linked table, not from the record being edited. Query the linked table with its own `defineQuery` and `ds.list`; each result's `id` is what you pass to the write payload. See [record-queries](../record-queries/SKILL.md).

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **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. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -146,6 +146,18 @@ const listMyInvoices = createServerFn().handler(async ({ context }) => {
 })
 ```
 
+When the owner is a link to the Users table, the row to match is the visitor's own row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds it by email, or answers `null` when they are signed out or have no row:
+
+```ts
+import { auth, ds } from '@softr/sdk/server'
+
+const listMyDeals = createServerFn().handler(async ({ context }) => {
+  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+  if (me === null) return { records: [], nextOffset: null }
+  return await ds.list(deals).where((q) => q.owner.isOneOf([me.id]))
+})
+```
+
 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`.
 
 ### Populate a control from a linked table
@@ -178,6 +190,14 @@ Each returned record is one option: `record.id` is the value a `where` filter an
 ds.list(products).where((q) => q.status.is(selectedStatusId))
 ```
 
+For a picker that searches and pages, `ds.options` answers the shape a linked-record picker's `load` takes, `{ options: [{ id, label }], nextOffset }`, searched on the label field when a term is given:
+
+```ts
+const loadProductStatuses = createServerFn()
+  .validator(z.object({ term: z.string(), offset: z.number().nullable() }))
+  .handler(({ data }) => ds.options(productStatuses, { label: 'name', ...data }))
+```
+
 Skip this request when the options are predefined and fixed — hardcode them instead.
 
 A read the datasource turns down throws rather than coming back empty, and it throws a plain `Error` carrying the status, followed by the reason the datasource gives when it sends one. 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/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.1
+  library_version: 0.0.68
 ---
 
 **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.