@softr/sdk 0.0.22 → 0.0.23

package/dist/core/datasource.d.ts

@@ -1,10 +1,20 @@
-import { ChartDataOptions, ChartDataResult, CreateOptions, GetOptions, ListOptions, ListResult, MetricOptions, MetricResult, SoftrRecord, UpdateOptions } from "../types.js";
+import { ChartDataOptions, ChartDataResult, CreateOptions, GetOptions, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrRecord, UpdateOptions } from "../types.js";
 
 //#region src/core/datasource.d.ts
-declare function listRecords(datasourceId: string, options?: ListOptions): Promise<ListResult>;
-declare function getRecord(datasourceId: string, options: GetOptions): Promise<SoftrRecord | null>;
-declare function createRecord(datasourceId: string, options: CreateOptions): Promise<SoftrRecord>;
-declare function updateRecord(datasourceId: string, options: UpdateOptions): Promise<SoftrRecord>;
+declare function listRecords<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options?: Omit<ListOptions, 'select'> & {
+  select?: Sel;
+}): Promise<ListResult<SoftrRecord<RecordFieldsFor<Id, Sel>>>>;
+declare function getRecord<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options: Omit<GetOptions, 'select'> & {
+  select?: Sel;
+}): Promise<SoftrRecord<RecordFieldsFor<Id, Sel>> | null>;
+declare function createRecord<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options: Omit<CreateOptions, 'select' | 'data'> & {
+  select?: Sel;
+  data: Partial<RecordFieldsFor<Id, Sel>>;
+}): Promise<SoftrRecord<RecordFieldsFor<Id, Sel>>>;
+declare function updateRecord<Id extends string, Sel extends Record<string, string> = Record<never, never>>(datasourceId: Id, options: Omit<UpdateOptions, 'select' | 'data'> & {
+  select?: Sel;
+  data: Partial<RecordFieldsFor<Id, Sel>>;
+}): Promise<SoftrRecord<RecordFieldsFor<Id, Sel>>>;
 declare function deleteRecord(datasourceId: string, id: string): Promise<void>;
 declare function getMetric(datasourceId: string, options: MetricOptions): Promise<MetricResult>;
 declare function getChartData(datasourceId: string, options: ChartDataOptions): Promise<ChartDataResult>;

package/dist/core/datasource.js

@@ -3,6 +3,7 @@ import { panic } from "../assertions.js";
 import { readUserTimezone } from "../cookies.js";
 import { sessionConfig } from "../auth/config.js";
 import { readSessionToken } from "../auth/session.js";
+import { assertResponseOk } from "./utils.js";
 
 //#region src/core/datasource.ts
 const MAX_RECORD_COUNT = 100;
@@ -36,7 +37,7 @@ async function listRecords(datasourceId, options = {}) {
 			}
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource list failed for "${datasourceId}": ${res.status}`);
+	await assertResponseOk(res, `Softr datasource list failed for "${datasourceId}"`);
 	const payload = await res.json();
 	const nextOffset = payload.offset < payload.total ? payload.offset : null;
 	return {
@@ -60,13 +61,18 @@ async function getRecord(datasourceId, options) {
 			},
 			body: JSON.stringify({ options: { userLocale: "en-US" } })
 		});
-		if (!res.ok) throw new Error(`Softr datasource get failed for "${datasourceId}": ${res.status}`);
+		await assertResponseOk(res, `Softr datasource get failed for "${datasourceId}"`);
 		const contentLength = res.headers.get("Content-Length");
 		if (contentLength && parseInt(contentLength, 10) === 0) return null;
-		return res.json();
+		const record = await res.json();
+		return {
+			id: record.id,
+			fields: options.select ? aliasFields(record.fields, options.select) : record.fields
+		};
 	}
 	return (await listRecords(datasourceId, {
 		where: options.where,
+		select: options.select,
 		limit: 1,
 		timeZone: options.timeZone
 	})).records[0] ?? null;
@@ -81,12 +87,12 @@ async function createRecord(datasourceId, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`Softr datasource create failed for "${datasourceId}": ${res.status}`);
+	await assertResponseOk(res, `Softr datasource create failed for "${datasourceId}"`);
 	const record = await res.json();
-	return options.select ? {
+	return {
 		id: record.id,
-		fields: aliasFields(record.fields, options.select)
-	} : record;
+		fields: options.select ? aliasFields(record.fields, options.select) : record.fields
+	};
 }
 async function updateRecord(datasourceId, options) {
 	if (!options.id) throw new Error(`Softr datasource update: id must not be empty`);
@@ -99,19 +105,18 @@ async function updateRecord(datasourceId, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`Softr datasource update failed for "${datasourceId}": ${res.status}`);
+	await assertResponseOk(res, `Softr datasource update failed for "${datasourceId}"`);
 	const record = await res.json();
-	return options.select ? {
+	return {
 		id: record.id,
-		fields: aliasFields(record.fields, options.select)
-	} : record;
+		fields: options.select ? aliasFields(record.fields, options.select) : record.fields
+	};
 }
 async function deleteRecord(datasourceId, id) {
-	const res = await fetch(`${dsUrl(datasourceId)}/records/${id}`, {
+	await assertResponseOk(await fetch(`${dsUrl(datasourceId)}/records/${id}`, {
 		method: "DELETE",
 		headers: { "Authorization": `Bearer ${readSessionToken()}` }
-	});
-	if (!res.ok) throw new Error(`Softr datasource delete failed for "${datasourceId}": ${res.status}`);
+	}), `Softr datasource delete failed for "${datasourceId}"`);
 }
 async function getMetric(datasourceId, options) {
 	const { select, where, aggregation, field } = options;
@@ -133,7 +138,7 @@ async function getMetric(datasourceId, options) {
 			filterCriteria
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource metric failed for "${datasourceId}": ${res.status}`);
+	await assertResponseOk(res, `Softr datasource metric failed for "${datasourceId}"`);
 	const payload = await res.json();
 	const executionTimestamp = /* @__PURE__ */ new Date(payload.executionTimestamp * 1e3);
 	let value;
@@ -171,7 +176,7 @@ async function getChartData(datasourceId, options) {
 			yAxisFields
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource chartData failed for "${datasourceId}": ${res.status}`);
+	await assertResponseOk(res, `Softr datasource chartData failed for "${datasourceId}"`);
 	const payload = await res.json();
 	const executionTimestamp = /* @__PURE__ */ new Date(payload.executionTimestamp * 1e3);
 	const aliases = {};

package/dist/core/utils.js

@@ -0,0 +1,14 @@
+//#region src/core/utils.ts
+async function assertResponseOk(res, message) {
+	if (!res.ok) {
+		let fullMessage = `${message}: ${res.status}`;
+		if (process.env.NODE_ENV !== "production") {
+			const body = await res.text().catch(() => "");
+			if (body) fullMessage += `\n\n${body}`;
+		}
+		throw new Error(fullMessage);
+	}
+}
+
+//#endregion
+export { assertResponseOk };

package/dist/default-error-overlay.d.ts

@@ -0,0 +1,13 @@
+import * as react0 from "react";
+
+//#region src/default-error-overlay.d.ts
+type Props = {
+  error: Error;
+  reset?: () => void;
+};
+declare function DefaultErrorOverlay({
+  error,
+  reset
+}: Props): react0.JSX.Element;
+//#endregion
+export { DefaultErrorOverlay };

package/dist/default-error-overlay.js

@@ -0,0 +1,319 @@
+import { useRef, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/default-error-overlay.tsx
+function DefaultErrorOverlay({ error, reset }) {
+	if (process.env.NODE_ENV === "production") return /* @__PURE__ */ jsx("div", {
+		style: s.overlay,
+		children: /* @__PURE__ */ jsxs("div", {
+			style: s.card,
+			children: [
+				/* @__PURE__ */ jsx(AlertIcon, {}),
+				/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("h1", {
+					style: s.heading,
+					children: "Something went wrong"
+				}), /* @__PURE__ */ jsx("p", {
+					style: s.body,
+					children: "This page couldn't be shown. Try again in a moment."
+				})] }),
+				/* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(RetryButton, { onClick: reset }) })
+			]
+		})
+	});
+	return /* @__PURE__ */ jsx(DevView, {
+		error,
+		reset
+	});
+}
+function DevView({ error, reset }) {
+	return /* @__PURE__ */ jsx("div", {
+		style: s.overlay,
+		children: /* @__PURE__ */ jsxs("div", {
+			style: s.card,
+			children: [
+				/* @__PURE__ */ jsx(AlertIcon, {}),
+				/* @__PURE__ */ jsxs("div", { children: [
+					/* @__PURE__ */ jsx("h1", {
+						style: s.heading,
+						children: "Something went wrong"
+					}),
+					/* @__PURE__ */ jsx("p", {
+						style: s.body,
+						children: "A render error was caught. Copy the details to the agent to help fix the issue."
+					}),
+					/* @__PURE__ */ jsx("p", {
+						style: s.note,
+						children: "Only shown in development mode."
+					})
+				] }),
+				/* @__PURE__ */ jsx("pre", {
+					style: s.message,
+					children: error.message
+				}),
+				error.stack && /* @__PURE__ */ jsx(StackTrace, { stack: error.stack }),
+				/* @__PURE__ */ jsx("div", { children: /* @__PURE__ */ jsx(RetryButton, { onClick: reset }) })
+			]
+		})
+	});
+}
+function cleanStack(stack) {
+	return stack.split("\n").slice(1).filter((line) => line.trim().startsWith("at ") && !line.includes("/node_modules/")).map((line) => line.replace(/https?:\/\/[^/]+\//, "").replace(/\?[^):]+/g, "")).join("\n");
+}
+function StackTrace({ stack }) {
+	const cleaned = cleanStack(stack);
+	const [open, setOpen] = useState(false);
+	const [copied, setCopied] = useState(false);
+	const ref = useRef(null);
+	if (!cleaned) return null;
+	async function copy() {
+		try {
+			await navigator.clipboard.writeText(cleaned);
+			setCopied(true);
+			setTimeout(() => setCopied(false), 1500);
+		} catch {
+			if (ref.current) getSelection()?.selectAllChildren(ref.current);
+		}
+	}
+	return /* @__PURE__ */ jsxs("div", {
+		style: {
+			display: "flex",
+			flexDirection: "column",
+			gap: "0.5rem"
+		},
+		children: [/* @__PURE__ */ jsxs("button", {
+			type: "button",
+			style: s.toggle,
+			"aria-expanded": open,
+			onClick: () => setOpen((v) => !v),
+			children: [/* @__PURE__ */ jsx("svg", {
+				style: {
+					width: "0.875rem",
+					height: "0.875rem",
+					flexShrink: 0,
+					transition: "transform 150ms",
+					transform: open ? "rotate(90deg)" : "none"
+				},
+				viewBox: "0 0 24 24",
+				fill: "none",
+				stroke: "currentColor",
+				strokeWidth: "2",
+				strokeLinecap: "round",
+				strokeLinejoin: "round",
+				children: /* @__PURE__ */ jsx("path", { d: "m9 18 6-6-6-6" })
+			}), "Stack trace"]
+		}), open && /* @__PURE__ */ jsxs("div", {
+			style: { position: "relative" },
+			children: [/* @__PURE__ */ jsx("pre", {
+				ref,
+				style: s.stack,
+				children: cleaned
+			}), /* @__PURE__ */ jsx("button", {
+				type: "button",
+				style: s.copy,
+				"aria-label": "Copy stack trace",
+				onClick: copy,
+				children: copied ? /* @__PURE__ */ jsx("svg", {
+					style: icon.sm,
+					viewBox: "0 0 24 24",
+					fill: "none",
+					stroke: "currentColor",
+					strokeWidth: "2",
+					strokeLinecap: "round",
+					strokeLinejoin: "round",
+					children: /* @__PURE__ */ jsx("path", { d: "M20 6 9 17l-5-5" })
+				}) : /* @__PURE__ */ jsxs("svg", {
+					style: icon.sm,
+					viewBox: "0 0 24 24",
+					fill: "none",
+					stroke: "currentColor",
+					strokeWidth: "2",
+					strokeLinecap: "round",
+					strokeLinejoin: "round",
+					children: [/* @__PURE__ */ jsx("rect", {
+						width: "14",
+						height: "14",
+						x: "8",
+						y: "8",
+						rx: "2",
+						ry: "2"
+					}), /* @__PURE__ */ jsx("path", { d: "M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2" })]
+				})
+			})]
+		})]
+	});
+}
+function AlertIcon() {
+	return /* @__PURE__ */ jsx("div", {
+		style: s.alert,
+		children: /* @__PURE__ */ jsxs("svg", {
+			style: icon.md,
+			viewBox: "0 0 24 24",
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: "2",
+			strokeLinecap: "round",
+			strokeLinejoin: "round",
+			children: [
+				/* @__PURE__ */ jsx("path", { d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" }),
+				/* @__PURE__ */ jsx("path", { d: "M12 9v4" }),
+				/* @__PURE__ */ jsx("path", { d: "M12 17h.01" })
+			]
+		})
+	});
+}
+function RetryButton({ onClick }) {
+	return /* @__PURE__ */ jsxs("button", {
+		type: "button",
+		style: s.retry,
+		onClick,
+		children: [/* @__PURE__ */ jsxs("svg", {
+			style: icon.sm,
+			viewBox: "0 0 24 24",
+			fill: "none",
+			stroke: "currentColor",
+			strokeWidth: "2",
+			strokeLinecap: "round",
+			strokeLinejoin: "round",
+			children: [
+				/* @__PURE__ */ jsx("path", { d: "M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" }),
+				/* @__PURE__ */ jsx("path", { d: "M21 3v5h-5" }),
+				/* @__PURE__ */ jsx("path", { d: "M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" }),
+				/* @__PURE__ */ jsx("path", { d: "M8 16H3v5" })
+			]
+		}), "Try again"]
+	});
+}
+const icon = {
+	sm: {
+		width: "0.875rem",
+		height: "0.875rem"
+	},
+	md: {
+		width: "1.25rem",
+		height: "1.25rem"
+	}
+};
+const s = {
+	overlay: {
+		minHeight: "100vh",
+		display: "grid",
+		placeItems: "center",
+		gridTemplateColumns: "minmax(0, 1fr)",
+		padding: "1.5rem"
+	},
+	card: {
+		width: "100%",
+		maxWidth: "36rem",
+		display: "flex",
+		flexDirection: "column",
+		gap: "1.25rem",
+		padding: "1.5rem",
+		borderRadius: "calc(var(--radius, 0.625rem) + 4px)",
+		background: "var(--card, oklch(1 0 0))",
+		boxShadow: "0 0 0 1px color-mix(in oklch, var(--foreground, oklch(0.145 0 0)) 10%, transparent)"
+	},
+	alert: {
+		display: "flex",
+		alignItems: "center",
+		justifyContent: "center",
+		width: "2.5rem",
+		height: "2.5rem",
+		borderRadius: "var(--radius, 0.625rem)",
+		background: "color-mix(in oklch, var(--destructive, oklch(0.577 0.245 27.325)) 12%, transparent)",
+		color: "var(--destructive, oklch(0.577 0.245 27.325))",
+		flexShrink: 0
+	},
+	heading: {
+		margin: 0,
+		fontSize: "1rem",
+		fontWeight: 500,
+		lineHeight: 1.375
+	},
+	body: {
+		margin: "0.375rem 0 0",
+		fontSize: "0.875rem",
+		color: "var(--muted-foreground, oklch(0.556 0 0))"
+	},
+	note: {
+		margin: "0.75rem 0 0",
+		fontSize: "0.875rem",
+		color: "var(--muted-foreground, oklch(0.556 0 0))",
+		opacity: .65
+	},
+	message: {
+		margin: 0,
+		padding: "0.75rem",
+		borderRadius: "var(--radius, 0.625rem)",
+		background: "var(--muted, oklch(0.97 0 0))",
+		fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+		fontSize: "0.8125rem",
+		lineHeight: 1.6,
+		whiteSpace: "pre-wrap",
+		overflowWrap: "anywhere",
+		maxHeight: "12rem",
+		overflow: "auto"
+	},
+	toggle: {
+		display: "inline-flex",
+		alignItems: "center",
+		gap: "0.375rem",
+		height: "2rem",
+		padding: "0 0.75rem 0 0.5rem",
+		border: "1px solid var(--input, oklch(0.922 0 0))",
+		borderRadius: "var(--radius, 0.625rem)",
+		background: "var(--input-fill, oklch(1 0 0))",
+		color: "var(--primary-foreground, oklch(0.985 0 0))",
+		fontFamily: "inherit",
+		fontSize: "0.875rem",
+		fontWeight: 500,
+		cursor: "pointer",
+		userSelect: "none"
+	},
+	stack: {
+		margin: 0,
+		padding: "0.75rem",
+		paddingRight: "2.75rem",
+		borderRadius: "var(--radius, 0.625rem)",
+		background: "var(--muted, oklch(0.97 0 0))",
+		fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+		fontSize: "0.75rem",
+		lineHeight: 1.6,
+		maxHeight: "16rem",
+		overflow: "auto"
+	},
+	copy: {
+		position: "absolute",
+		top: "0.375rem",
+		right: "0.375rem",
+		display: "inline-flex",
+		alignItems: "center",
+		justifyContent: "center",
+		width: "1.75rem",
+		height: "1.75rem",
+		padding: 0,
+		border: "1px solid var(--input, oklch(0.922 0 0))",
+		borderRadius: "calc(var(--radius, 0.625rem) - 2px)",
+		background: "var(--card, oklch(1 0 0))",
+		color: "var(--muted-foreground, oklch(0.556 0 0))",
+		cursor: "pointer"
+	},
+	retry: {
+		display: "inline-flex",
+		alignItems: "center",
+		gap: "0.375rem",
+		height: "2rem",
+		padding: "0 0.75rem",
+		border: "1px solid transparent",
+		borderRadius: "var(--radius, 0.625rem)",
+		background: "var(--primary, oklch(0.205 0 0))",
+		color: "var(--primary-foreground, oklch(0.985 0 0))",
+		fontFamily: "inherit",
+		fontSize: "0.875rem",
+		fontWeight: 500,
+		cursor: "pointer",
+		userSelect: "none"
+	}
+};
+
+//#endregion
+export { DefaultErrorOverlay };

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { q } from "./core/query.js";
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions } from "./types.js";
+import { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, DatasourceTypeMap, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions } from "./types.js";
 import { Permissions } from "./auth/permissions.js";
 import { SoftrContext } from "./auth/context.js";
 import { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
-export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourcePermissions, type GetOptions, type JsonValue, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type Permissions, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+import { DefaultErrorOverlay } from "./default-error-overlay.js";
+export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourcePermissions, type DatasourceTypeMap, DefaultErrorOverlay, type GetOptions, type JsonValue, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type Permissions, type RecordFieldsFor, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/index.js

@@ -2,5 +2,6 @@ import { q } from "./core/query.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 { defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { DefaultErrorOverlay, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/types.d.ts

@@ -26,11 +26,13 @@ type GetByIdOptions = {
   id: string;
   where?: never;
   timeZone?: string;
+  select?: Record<string, string>;
 };
 type GetByWhereOptions = {
   id?: never;
   where: AnyConstructable;
   timeZone?: string;
+  select?: Record<string, string>;
 };
 type GetOptions = GetByIdOptions | GetByWhereOptions;
 interface ListOptions {
@@ -66,6 +68,14 @@ interface ListResult<T extends SoftrRecord = SoftrRecord> {
   /** Offset to pass as `offset` in the next call, or `null` when there are no more pages. */
   nextOffset: number | null;
 }
+/**
+ * Augment this interface in a generated datasource-types file to enable
+ * typed `ds.list()` / `ds.get()` return values per datasource ID.
+ * Maps datasource ID → raw field shape (keyed by field ID).
+ */
+interface DatasourceTypeMap {}
+type AliasedFields<Sel extends Record<string, string>, Raw extends Record<string, JsonValue>> = { [K in keyof Sel]: Sel[K] extends keyof Raw ? Raw[Sel[K]] : JsonValue };
+type RecordFieldsFor<Id extends string, Sel extends Record<string, string>> = Id extends keyof DatasourceTypeMap ? [keyof Sel] extends [never] ? DatasourceTypeMap[Id] : AliasedFields<Sel, DatasourceTypeMap[Id]> : Record<string, JsonValue>;
 type AggregationFunction = 'SUM' | 'AVG' | 'MAX' | 'MIN' | 'COUNT' | 'DISTINCT';
 interface MetricOptions {
   select?: Record<string, string>;
@@ -115,4 +125,4 @@ interface UpdateOptions {
   data: Record<string, JsonValue>;
 }
 //#endregion
-export { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions };
+export { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, DatasourceTypeMap, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, RecordFieldsFor, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -6,11 +6,12 @@ description: >-
   boundary between them, softrAuthMiddleware, getSoftrContext,
   initialSoftrContext, SoftrContext, and which sub-skill to load for route
   visibility, the current user, reading records, writing records, or auth. Load
-  this before any other Softr SDK skill.
+  this when unsure which sub-skill applies, or when touching the wiring; each
+  sub-skill stands alone for its own task.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.22
+  library_version: 0.0.23
 ---
 
 # Softr SDK core
@@ -22,7 +23,7 @@ metadata:
 > **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**: `ds.metric`, `ds.chartData`, `workflow.trigger` and `integration.fetch` are exploratory. They exist on the entrypoints below and they typecheck, but their endpoints are not final. Do not build a feature on any of them. Tell the user the capability is not ready and ask how they want to proceed.
 
-Load this skill, then load **one** sub-skill for the task at hand. Add a second only when the work genuinely crosses that boundary. A page that lists records behind a group restriction needs `reading-records` plus `routes-and-visibility`.
+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 `reading-records` plus `routes-and-visibility`.
 
 ## Entrypoints
 
@@ -123,4 +124,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.21.
+Targets `@softr/sdk` v0.0.23.

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

@@ -10,10 +10,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.22
+  library_version: 0.0.23
 ---
 
-This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
+**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.
 
 # Auth
 

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

@@ -10,10 +10,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.22
+  library_version: 0.0.23
 ---
 
-This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.
+**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.
 
 # The current user
 

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

@@ -8,14 +8,14 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.22
+  library_version: 0.0.23
 ---
 
-This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
+**Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `q` 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.
 
 # Writing records
 
-`ds` writes records to a Softr datasource. Like every read, a write lives on `@softr/sdk/server` and runs on the server only, so it happens inside a `createServerFn` handler and never in a component.
+`ds` writes records to a Softr datasource, from the server only.
 
 ## Setup
 
@@ -49,7 +49,7 @@ const createProject = createServerFn({ method: 'POST' })
   )
 ```
 
-Returns the created record as `{ id, fields }`.
+Resolves to `{ id, fields }`, and on a Softr table `fields` holds **only the keys you wrote** — not the rest of the record. See "What a write answers with" below.
 
 **The payload key is `data`, not `fields`.** A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`. `CreateOptions` requires it, so a call keyed by `fields` does not type-check.
 
@@ -73,7 +73,24 @@ const renameProject = createServerFn({ method: 'POST' })
 
 The record id is its own option, so keep it out of `data`.
 
-Returns the updated record. `update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. An empty `id` throws.
+`update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. An empty `id` throws.
+
+### What a write answers with
+
+`create` and `update` resolve to `{ id, fields }`, but `fields` is **not the record**. On a Softr table it carries only the keys you sent, aliased through `select`; a status change answers with `{ id, fields: { status } }` and nothing else. (Other datasource types may answer with more. Rely on neither.)
+
+So the answer is a receipt, not a replacement for what the page holds. Putting it where a loader-fetched record was blanks every column you did not write. Two honest ways to show the result:
+
+- **A quick change to one field** — a status select, a card dragged to another column, an archive toggle — is optimistic: change that one field in your own state immediately, keep the rest of the record as the loader gave it, save in the background, and on a rejected write restore the old value with a clear message. Do not `router.invalidate()` or re-fetch after a successful write; the local change is already what the user sees.
+- **A saved form, or anything that changes several fields**, refreshes the route's data — `router.invalidate()`, see `@tanstack/router-core#router-core/data-loading` — so the list or detail re-reads through its own `select`.
+
+Do not re-read the one record with `ds.get` for either: it takes no `select`, so it answers with raw field ids.
+
+### Writing a choice field
+
+A `SELECT` or `LINKED_RECORD` field reads back as `{ id, label }` (see [field-types](../reading-records/references/field-types.md)). Writing one accepts the option's `id`, its `label`, or `{ id, label }`, matched case-insensitively.
+
+**A value that matches no option is not an error — it silently adds a new option to the field.** A typo'd label leaves a junk choice in the schema. So write `{ label }` (or the `{ id, label }` you read), copy labels from the table's schema verbatim, and never invent one.
 
 ### Delete a record
 
@@ -113,8 +130,6 @@ Stamping a record with who created it, or scoping an update to the person making
 
 **Expecting `select` on a read-then-write round trip.** `ds.get` takes no `select`, so a record fetched by id answers with raw field ids. Load `reading-records` before pairing a read with a write.
 
-**A write outside a server function.** `ds` is server-only. Importing it into a component fails the build.
-
 **Reading the visitor from somewhere other than `context`.** There is nothing to import. See [current-user](../current-user/SKILL.md).
 
 ## References

package/skills/softr-sdk/reading-records/SKILL.md

@@ -10,14 +10,14 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.22
+  library_version: 0.0.23
 ---
 
-This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
+**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. `q` 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.
 
 # Reading records
 
-`ds` reads records out of a Softr datasource. It lives on `@softr/sdk/server` and runs on the server only, so every read happens inside a `createServerFn` handler or a server-side route hook, never in a component.
+`ds` reads records out of a Softr datasource, from the server only.
 
 ## Setup
 
@@ -27,8 +27,6 @@ import { ds } from '@softr/sdk/server'
 import { q } from '@softr/sdk'
 ```
 
-`ds` is server-only and lives on `@softr/sdk/server`. `q` builds queries and nothing more, so it ships on the root entrypoint and can be imported anywhere.
-
 Every `ds` call names its datasource by an 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 it is never derived from the table's name — `'ds_posts'` or a name glued to a uuid fails at request time as not found or forbidden.
 
 **The datasource id must be a string literal at the call site.** Do not assign it to a variable and pass the variable — the build reads ids statically and cannot resolve a name. Write the UUID directly as the first argument:

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

@@ -12,10 +12,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.22
+  library_version: 0.0.23
 ---
 
-This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.
+**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.
 
 # Route visibility
 
@@ -82,7 +82,7 @@ export const Route = createFileRoute('/_app')({
 
 The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. Routes below a guarded layout still declare their own rule, because the declaration is what Studio reads.
 
-A thrown error renders in place of the guarded route's component. Guard the layout that draws your nav and chrome, and the error screen replaces the chrome along with it. Put the guard on a layout inside the shell rather than on the shell itself.
+A thrown error renders in place of the guarded route's component. The template's `_app.tsx` shell is guarded with `LOGGED_IN_USERS`, whose default for a signed-out visitor is a redirect, so nothing ever renders there. A rule that can *throw* — a `userGroupIds` rule, whose `forbidden` default is throw — should not sit on the shell itself, or the refusal replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the refusal renders inside the chrome.
 
 ### Change what a denied visitor gets