@softr/sdk 0.0.22-alpha.0 → 0.0.22-alpha.2

package/dist/core/datasource.js

@@ -8,7 +8,7 @@ import { readSessionToken } from "../auth/session.js";
 const MAX_RECORD_COUNT = 100;
 const COUNT_CNT = "COUNT_CNT";
 const dsUrl = (datasourceId) => {
-	const datasourceApiUrl = process.env.SOFTR_DATASOURCE_API_URL || "https://datasource-api-staging12.softr.io";
+	const datasourceApiUrl = process.env.SOFTR_DATASOURCE_API_URL;
 	if (!datasourceApiUrl) panic("SOFTR_DATASOURCE_API_URL is not set.");
 	const { applicationId } = sessionConfig();
 	return `${withoutTrailingSlash(datasourceApiUrl)}/v1/datasource/vibe/applications/${applicationId}/datasources/${datasourceId}`;

package/dist/preview-identity/preview-identity.js

@@ -0,0 +1,141 @@
+import { makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName } from "../auth/session.js";
+
+//#region src/preview-identity/preview-identity.ts
+const PREVIEW_REDEMPTION_PATH = "/__preview/identity";
+const PREVIEW_SIGNED_IN_PATH = "/__preview/signed-in";
+/**
+* Signs the preview in as one of the app's own users by spending the one-time grant studio-api put
+* in this URL. No cookie of its own is forwarded: the grant is the only credential, and studio-api
+* authorized the builder before it issued one.
+*/
+const redeemGrant = async (req, res) => {
+	res.setHeader("Cache-Control", "no-store");
+	res.setHeader("Referrer-Policy", "no-referrer");
+	if (req.method !== "GET") {
+		sendJson(res, 405, { error: `${PREVIEW_REDEMPTION_PATH} only supports GET` });
+		return;
+	}
+	const grant = searchParamsOf(req).get("grant");
+	if (!grant) {
+		sendJson(res, 400, { error: "no grant" });
+		return;
+	}
+	const landing = landingPath(searchParamsOf(req).get("next"));
+	let session;
+	try {
+		session = await redeemPreviewGrant(req, grant);
+	} catch (error) {
+		sendJson(res, statusOf(error), { error: messageOf(error) });
+		return;
+	}
+	const secure = requestIsHttps(req);
+	res.statusCode = 302;
+	res.setHeader("Location", landing);
+	res.setHeader("Set-Cookie", session.anonymous ? makeSessionClearingCookies(secure) : makeSessionTokenCookie(session.jwt, secure));
+	res.end();
+};
+/**
+* Whether the preview currently holds a session, and nothing else.
+*
+* Presence only, never decoded: whether anyone is signed in is all Studio's picker needs, and
+* decoding would put an app user's identity on a route the studio bundle can read. Asked under the
+* one name this scheme's app would read, so a cookie the app ignores reads as signed out here too
+* rather than as a session it cannot see.
+*/
+const reportSignedIn = (req, res) => {
+	res.setHeader("Cache-Control", "no-store");
+	if (req.method !== "GET") {
+		sendJson(res, 405, { error: `${PREVIEW_SIGNED_IN_PATH} only supports GET` });
+		return;
+	}
+	sendJson(res, 200, { signedIn: hasSessionCookie(req.headers.cookie, sessionTokenCookieName(requestIsHttps(req))) });
+};
+var RedemptionError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+function statusOf(error) {
+	return error instanceof RedemptionError ? error.status : 503;
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+async function redeemPreviewGrant(req, grant) {
+	const applicationId = process.env.SOFTR_APPLICATION_ID;
+	const studioApiUrl = process.env.SOFTR_STUDIO_API_URL?.trim() || studioApiUrlFor(req);
+	if (!applicationId || !studioApiUrl) throw new RedemptionError(503, "studio-api is unavailable");
+	let response;
+	try {
+		response = await fetch(`${studioApiUrl}/v1/applications/${encodeURIComponent(applicationId)}/vibe-coding/preview-identity/redeem`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			body: JSON.stringify({ grant })
+		});
+	} catch {
+		throw new RedemptionError(503, "studio-api is unreachable");
+	}
+	if (!response.ok) throw new RedemptionError(response.status, "studio-api refused the preview identity grant");
+	const body = await response.json().catch(() => null);
+	if (typeof body !== "object" || body === null) throw new RedemptionError(503, "studio-api returned no session");
+	const { anonymous, jwt } = body;
+	if (anonymous === true) return { anonymous: true };
+	if (typeof jwt !== "string" || jwt.length === 0) throw new RedemptionError(503, "studio-api returned no token");
+	return {
+		anonymous: false,
+		jwt
+	};
+}
+const STAGING_HOST_PATTERN = /(?:^|\.)staging(\d+)\.softr\.io$/;
+/**
+* The studio-api base URL of the environment this dev server runs in, read off the request's host.
+*
+* The host is the only per-environment signal the app has: it is served at
+* `<slug>-app.vibe-coding-preview.staging12.softr.io`, and staging 12's API is
+* `studio-api-staging12.softr.io`. Every other host gives `null` — localhost included.
+*/
+function studioApiUrlFor(req) {
+	const forwarded = req.headers["x-forwarded-host"];
+	const name = ((Array.isArray(forwarded) ? forwarded[0] : forwarded) ?? req.headers.host ?? "").split(",")[0].trim().split(":")[0];
+	const digits = STAGING_HOST_PATTERN.exec(name)?.[1];
+	if (!digits) return null;
+	return `https://studio-api-staging${digits.padStart(2, "0")}.softr.io`;
+}
+function hasSessionCookie(header, name) {
+	if (!header) return false;
+	return header.split(";").some((pair) => {
+		const separator = pair.indexOf("=");
+		return separator !== -1 && pair.slice(0, separator).trim() === name;
+	});
+}
+/**
+* Whether this request is https, by the same rule the session code reads the cookie back with.
+*
+* h3's `getRequestProtocol` compares `x-forwarded-proto` for exact equality, so it reads anything
+* else — `https, http` from a two-hop chain, or `HTTPS` — as not-https. Being more generous here
+* than it is writes `__Host-session_token` where the app then looks up `session_token`, and the
+* visitor is silently anonymous with no error on either side.
+*/
+function requestIsHttps(req) {
+	const forwarded = req.headers["x-forwarded-proto"];
+	if (forwarded === "https") return true;
+	if (forwarded === "http") return false;
+	return Boolean(req.socket?.encrypted);
+}
+function landingPath(next) {
+	if (!next || !next.startsWith("/") || next.startsWith("//") || next.includes("\\") || next.includes("://") || /[\u0000-\u001f\u007f]/.test(next)) return "/";
+	return next;
+}
+function searchParamsOf(req) {
+	return new URL(req.url ?? "", "http://request.invalid").searchParams;
+}
+function sendJson(res, status, body) {
+	res.statusCode = status;
+	res.setHeader("Content-Type", "application/json");
+	res.end(JSON.stringify(body));
+}
+
+//#endregion
+export { PREVIEW_REDEMPTION_PATH, PREVIEW_SIGNED_IN_PATH, redeemGrant, reportSignedIn };

package/dist/routes/discover.d.ts

@@ -2,8 +2,13 @@ import "@tanstack/router-generator";
 
 //#region src/routes/discover.d.ts
 
+type DatasourceMethod = "list" | "get" | "create" | "update" | "delete" | "metric" | "chartData";
+type DatasourceAccess = {
+  id: string;
+  methods: Array<DatasourceMethod>;
+};
 type VisibilityValue = string | Array<VisibilityValue> | {
   [key: string]: VisibilityValue;
 };
 //#endregion
-export { VisibilityValue };
+export { DatasourceAccess, VisibilityValue };

package/dist/routes/discover.js

@@ -65,6 +65,42 @@ function extractVisibility(source, filePath) {
 		}
 	};
 }
+/** Reads all ds.method() calls from the source text. The route file is never executed. */
+function extractDatasources(source, filePath) {
+	let program;
+	try {
+		program = parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"]
+		});
+	} catch (error) {
+		const position = error.loc;
+		return {
+			ok: false,
+			error: {
+				code: "unparsable",
+				message: `could not parse ${filePath}: ${error.message}`,
+				filePath,
+				line: position?.line ?? 1,
+				column: position?.column ?? 0
+			}
+		};
+	}
+	const raw = findDatasourceCalls(program, filePath);
+	if (!raw.ok) return raw;
+	const byId = /* @__PURE__ */ new Map();
+	for (const { id, method } of raw.calls) {
+		if (!byId.has(id)) byId.set(id, /* @__PURE__ */ new Set());
+		byId.get(id).add(method);
+	}
+	return {
+		ok: true,
+		datasources: Array.from(byId.entries()).map(([id, methods]) => ({
+			id,
+			methods: [...methods]
+		}))
+	};
+}
 /**
 * The generator `mkdirSync`s `tmpDir` and the directory of `generatedRouteTree` outside the `fs`
 * shim, so defaulted they create directories in the crawled project. Aimed at `os.tmpdir()` both
@@ -74,7 +110,18 @@ function extractVisibility(source, filePath) {
 const TMP_DIR = os.tmpdir();
 const generatedRouteTreePath = () => path.join(TMP_DIR, `softr-sdk-route-tree-${randomUUID()}.gen.ts`);
 const SDK_PACKAGE_NAME = "@softr/sdk";
+const SDK_SERVER_PACKAGE_NAME = "@softr/sdk/server";
 const VISIBILITY_FUNCTION = "defineVisibility";
+const DS_BINDING = "ds";
+const DS_METHODS = new Set([
+	"list",
+	"get",
+	"create",
+	"update",
+	"delete",
+	"metric",
+	"chartData"
+]);
 function fail(code, message, filePath, line, column) {
 	return {
 		ok: false,
@@ -87,6 +134,66 @@ function fail(code, message, filePath, line, column) {
 		}
 	};
 }
+function findDatasourceCalls(ast, filePath) {
+	const calls = [];
+	let error = null;
+	traverse(ast, { CallExpression(path$1) {
+		const { node } = path$1;
+		const { callee } = node;
+		if (callee.type !== "MemberExpression") return;
+		if (callee.computed) return;
+		if (callee.object.type !== "Identifier") return;
+		if (callee.property.type !== "Identifier") return;
+		const method = callee.property.name;
+		if (!DS_METHODS.has(method)) return;
+		if (!isDsImport(path$1, callee.object.name)) return;
+		const firstArg = node.arguments[0];
+		if (firstArg === void 0 || firstArg.type === "SpreadElement") {
+			error = {
+				code: "not-literal",
+				message: `${filePath}: ds.${method}() must be called with a string literal datasource id`,
+				filePath,
+				line: node.loc?.start.line ?? 1,
+				column: node.loc?.start.column ?? 0
+			};
+			path$1.stop();
+			return;
+		}
+		if (firstArg.type !== "StringLiteral") {
+			error = {
+				code: "not-literal",
+				message: `${filePath}: the datasource id passed to ds.${method}() must be a string literal`,
+				filePath,
+				line: firstArg.loc?.start.line ?? 1,
+				column: firstArg.loc?.start.column ?? 0
+			};
+			path$1.stop();
+			return;
+		}
+		calls.push({
+			id: firstArg.value,
+			method
+		});
+	} });
+	if (error !== null) return {
+		ok: false,
+		error
+	};
+	return {
+		ok: true,
+		calls
+	};
+}
+function isDsImport(path$1, name) {
+	const binding = path$1.scope.getBinding(name);
+	if (binding === void 0 || binding.kind !== "module") return false;
+	const specifier = binding.path.node;
+	const declaration = binding.path.parent;
+	if (specifier.type !== "ImportSpecifier" || declaration.type !== "ImportDeclaration") return false;
+	if (specifier.importKind === "type" || declaration.importKind === "type") return false;
+	if (declaration.source.value !== SDK_SERVER_PACKAGE_NAME) return false;
+	return (specifier.imported.type === "Identifier" ? specifier.imported.name : specifier.imported.value) === DS_BINDING;
+}
 const traverse = babelTraverse.default ?? babelTraverse;
 /** Only a call initialising a top-level variable counts; one inside a function or block does not. */
 function findVisibilityCalls(ast) {
@@ -195,4 +302,4 @@ function readLiteral(input) {
 }
 
 //#endregion
-export { crawlRoutes, extractVisibility };
+export { crawlRoutes, extractDatasources, extractVisibility };

package/dist/routes/manifest.d.ts

@@ -1,6 +1,12 @@
-import { VisibilityValue } from "./discover.js";
+import { DatasourceAccess, VisibilityValue } from "./discover.js";
 
 //#region src/routes/manifest.d.ts
+type DatasourceEntry = DatasourceAccess & {
+  /** Project-relative path to the file where the datasource is accessed. */
+  filename: string;
+  /** Route path, if the file is a route file. */
+  route?: string;
+};
 type ManifestNode = {
   routePath: string;
   filePath: string;
@@ -12,6 +18,7 @@ type ManifestNode = {
 };
 type Manifest = {
   root: ManifestNode;
+  datasources: Array<DatasourceEntry>;
 };
 //#endregion
 export { Manifest, ManifestNode };

package/dist/routes/manifest.js

@@ -1,4 +1,4 @@
-import { crawlRoutes, extractVisibility } from "./discover.js";
+import { crawlRoutes, extractDatasources, extractVisibility } from "./discover.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { inferFullPath } from "@tanstack/router-generator";
@@ -33,11 +33,13 @@ async function generateRoutesManifest(root) {
 }
 function buildManifest(opts) {
 	const routesDirectory = opts.crawl.routesDirectory;
+	const datasources = [];
 	const toNode = (node) => {
 		const projectRelative = toProjectRelative(opts.root, routesDirectory, node.filePath);
 		const routePath = node.routePath;
 		if (routePath === void 0) throw new Error(`the route crawl produced a node with no route path: ${projectRelative}`);
 		let declared = visibilityOf(opts, node.filePath);
+		datasources.push(...datasourceEntriesOf(opts, node.filePath, routePath));
 		const lazyPiece = opts.crawl.routePiecesByPath[routePath]?.lazy;
 		if (lazyPiece && lazyPiece.filePath !== node.filePath) {
 			const lazyDeclared = visibilityOf(opts, lazyPiece.filePath);
@@ -49,6 +51,7 @@ function buildManifest(opts) {
 				column: lazyDeclared.column
 			});
 			if (lazyDeclared !== null) declared = lazyDeclared;
+			datasources.push(...datasourceEntriesOf(opts, lazyPiece.filePath, routePath));
 		}
 		return {
 			routePath,
@@ -70,14 +73,18 @@ function buildManifest(opts) {
 		line: rootDeclared.line,
 		column: rootDeclared.column
 	});
-	return { root: {
-		routePath: ROOT_ROUTE_ID,
-		filePath: rootRelative,
-		inferFullPath: inferFullPath(rootNode) ?? null,
-		createFileRouteProps: [...rootNode.createFileRouteProps ?? []].sort(),
-		visibility: null,
-		children: opts.crawl.routeTree.map(toNode)
-	} };
+	datasources.push(...datasourceEntriesOf(opts, rootNode.filePath, ROOT_ROUTE_ID));
+	return {
+		root: {
+			routePath: ROOT_ROUTE_ID,
+			filePath: rootRelative,
+			inferFullPath: inferFullPath(rootNode) ?? null,
+			createFileRouteProps: [...rootNode.createFileRouteProps ?? []].sort(),
+			visibility: null,
+			children: opts.crawl.routeTree.map(toNode)
+		},
+		datasources
+	};
 }
 /**
 * `rootRouteId` from `@tanstack/router-core`, which is what a consumer matches against — not the
@@ -131,6 +138,19 @@ function visibilityOf(opts, filePath) {
 	checkVisibilityShape(declared);
 	return declared;
 }
+function datasourceEntriesOf(opts, filePath, routePath) {
+	const projectRelative = toProjectRelative(opts.root, opts.crawl.routesDirectory, filePath);
+	const source = opts.sources.get(path.resolve(opts.root, opts.crawl.routesDirectory, filePath));
+	if (source === void 0) return [];
+	const result = extractDatasources(source, projectRelative);
+	if (!result.ok) throw new ManifestError(result.error);
+	return result.datasources.map(({ id, methods }) => ({
+		id,
+		methods,
+		filename: projectRelative,
+		route: routePath
+	}));
+}
 /**
 * Only ENOENT becomes `null`. The caller reads `null` as "nothing declared here", so swallowing any
 * other read error would turn an unreadable declaration into an ungated route.

package/dist/server.d.ts

@@ -2,6 +2,5 @@ import { auth } from "./auth/server.js";
 import { ds } from "./core/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
-import { makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName } from "./auth/session.js";
 import "@tanstack/react-start/server-only";
-export { auth, ds, integration, makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName, workflow };
+export { auth, ds, integration, workflow };

package/dist/server.js

@@ -1,8 +1,7 @@
-import { makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName } from "./auth/session.js";
 import { auth } from "./auth/server.js";
 import { ds } from "./core/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";
 
-export { auth, ds, integration, makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName, workflow };
+export { auth, ds, integration, workflow };

package/dist/vite.js

@@ -31,7 +31,34 @@ async function generateManifest(root) {
 * edit engine when the pod supplies one.
 */
 function softr() {
-	return [routesManifest(), editEngine()];
+	return [
+		routesManifest(),
+		previewIdentity(),
+		editEngine()
+	];
+}
+/**
+* The routes that sign the preview in as one of the app's own users, and report whether it is.
+*
+* They live in this package, not in the edit engine, because signing the preview in means writing
+* the very cookie this app's own session code reads back — one implementation of the cookie format,
+* with no version to keep in step across a package seam.
+*
+* `SOFTR_APPLICATION_ID` is the gate: the pod sets it, and it is what binds a redemption to the
+* application the grant was issued for. An app running on a developer's machine has none, and
+* serves neither route.
+*/
+async function previewIdentity() {
+	if (!process.env.SOFTR_APPLICATION_ID) return false;
+	const { PREVIEW_REDEMPTION_PATH, PREVIEW_SIGNED_IN_PATH, redeemGrant, reportSignedIn } = await import("./preview-identity/preview-identity.js");
+	return {
+		name: "softr-preview-identity",
+		apply: "serve",
+		configureServer(server) {
+			server.middlewares.use(PREVIEW_REDEMPTION_PATH, redeemGrant);
+			server.middlewares.use(PREVIEW_SIGNED_IN_PATH, reportSignedIn);
+		}
+	};
 }
 /** Plugin order does not matter: this puts nothing into the module graph. */
 function routesManifest() {

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.21
+  library_version: 0.0.22-alpha.2
 ---
 
 # Softr SDK core

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.21
+  library_version: 0.0.22-alpha.2
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.21
+  library_version: 0.0.22-alpha.2
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.21
+  library_version: 0.0.22-alpha.2
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
@@ -24,15 +24,13 @@ import { createServerFn } from '@tanstack/react-start'
 import { z } from 'zod'
 import { ds } from '@softr/sdk/server'
 import { q } from '@softr/sdk'
-
-// The datasource id Softr assigned when the table was registered on the application.
-// Copy it from the registration (datasource.datasourceId); it is not the table id.
-const PROJECTS = '8ffb4814-b028-4496-b679-7face2167ebc'
 ```
 
 Pass a zod schema straight to `.validator`. Start accepts it and types `data` from it.
 
-Every `ds` call names its datasource by that id: 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 never derived from the table's name. Field ids are opaque too (`fZk3Qm9pLw2Xa1`, not `fld_<name>`) and come from the table's schema.
+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 never derived from the table's name. Field ids are opaque too (`fZk3Qm9pLw2Xa1`, not `fld_<name>`) and come from the table's schema.
+
+**The datasource id must be a string literal at the call site.**
 
 ## Core Patterns
 
@@ -44,7 +42,7 @@ const NewProject = z.object({ name: z.string(), status: z.string() })
 const createProject = createServerFn({ method: 'POST' })
   .validator(NewProject)
   .handler(async ({ data }) =>
-    ds.create(PROJECTS, {
+    ds.create('8ffb4814-b028-4496-b679-7face2167ebc', {
       data,
       select: q.select({ name: 'fZk3Qm9pLw2Xa1', status: 'Ru7bVx2cNq0Ed9' }),
     }),
@@ -65,7 +63,7 @@ const Rename = z.object({ id: z.string(), name: z.string() })
 const renameProject = createServerFn({ method: 'POST' })
   .validator(Rename)
   .handler(async ({ data }) =>
-    ds.update(PROJECTS, {
+    ds.update('8ffb4814-b028-4496-b679-7face2167ebc', {
       id: data.id,
       data: { name: data.name },
       select: q.select({ name: 'fZk3Qm9pLw2Xa1' }),
@@ -84,7 +82,7 @@ const RecordId = z.object({ id: z.string() })
 
 const deleteProject = createServerFn({ method: 'POST' })
   .validator(RecordId)
-  .handler(async ({ data }) => ds.delete(PROJECTS, data.id))
+  .handler(async ({ data }) => ds.delete('8ffb4814-b028-4496-b679-7face2167ebc', data.id))
 ```
 
 **`delete` takes the record id as a positional argument**, unlike `create` and `update`, which take an options object. It resolves to nothing.
@@ -103,6 +101,8 @@ Stamping a record with who created it, or scoping an update to the person making
 
 **A datasource id built from a name.** `'ds_projects'`, the table id, or the table's name glued to a uuid are not datasource ids. The id is the opaque UUID assigned when the table was registered on the application; copy it from there. Anything else fails at request time as not found or forbidden.
 
+**A datasource id stored in a variable.** The build reads ids statically to build the route manifest; it cannot resolve a name. Pass the UUID as a string literal directly at the call site. The lint rule `@softr/ds-no-computed-id` catches this at development time.
+
 **A write that sends `fields`.** The option is `data`. Only typecheck catches this, so it survives any run that does not typecheck.
 
 **A key missing from `select`.** The key is not translated, so the field it was meant for is not the field written. Check the map covers every key rather than trusting the call to complain.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.21
+  library_version: 0.0.22-alpha.2
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
@@ -25,15 +25,22 @@ This skill builds on softr-sdk. Read it first for the entrypoints and the client
 import { createServerFn } from '@tanstack/react-start'
 import { ds } from '@softr/sdk/server'
 import { q } from '@softr/sdk'
-
-// The datasource id Softr assigned when the table was registered on the application.
-// Copy it from the registration (datasource.datasourceId); it is not the table id.
-const POSTS = '8ffb4814-b028-4496-b679-7face2167ebc'
 ```
 
 `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 that id: 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.
+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:
+
+```ts
+// correct
+ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { ... })
+
+// wrong — the build cannot read this
+const POSTS = '8ffb4814-b028-4496-b679-7face2167ebc'
+ds.list(POSTS, { ... })
+```
 
 A record comes back as `{ id: string; fields: Record<string, unknown> }`. When you write a TypeScript type for the fields, the shape of each value depends on the Softr field type — see [references/field-types.md](./references/field-types.md) for the full mapping.
 
@@ -59,10 +66,8 @@ Cast at the `ds.list` call using the `ListResult` generic so the type flows thro
 ```ts
 import type { ListResult, SoftrRecord } from '@softr/sdk'
 
-const PRODUCTS = '3c1e8a52-6f0d-4b7e-9a21-5d84c0f7b2e6' // from the table's registration
-
 const fetchProducts = createServerFn().handler(() =>
-  ds.list(PRODUCTS, { select, limit: 100 }) as Promise<ListResult<Product>>
+  ds.list('3c1e8a52-6f0d-4b7e-9a21-5d84c0f7b2e6', { select, limit: 100 }) as Promise<ListResult<Product>>
 )
 ```
 
@@ -74,7 +79,7 @@ const fetchProducts = createServerFn().handler(() =>
 
 ```ts
 const listPublishedPosts = createServerFn().handler(async () => {
-  return await ds.list(POSTS, {
+  return await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', {
     select: q.select({
       title: 'fZk3Qm9pLw2Xa1',
       author: 'mB4kQ8yTn1sWc7',
@@ -99,7 +104,7 @@ Softr field ids are opaque strings (`fZk3Qm9pLw2Xa1`), copied from the table's s
 ```ts
 const select = q.select({ title: 'fZk3Qm9pLw2Xa1', views: 'Ru7bVx2cNq0Ed9' })
 
-await ds.list(POSTS, {
+await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', {
   select,
   where: q.number('views').gt(100),   // alias, not Ru7bVx2cNq0Ed9
   orderBy: q.asc('title'),            // alias here too
@@ -112,7 +117,7 @@ Once `select` is present it is the whole vocabulary. The returned record carries
 ### Get one record
 
 ```ts
-const post = await ds.get(POSTS, { id: postId })
+const post = await ds.get('8ffb4814-b028-4496-b679-7face2167ebc', { id: postId })
 if (post === null) throw notFound()
 ```
 
@@ -138,9 +143,9 @@ Five field types, `q.text`, `q.number`, `q.boolean`, `q.date` and `q.array`, com
 ### Paginate
 
 ```ts
-const first = await ds.list(POSTS, { limit: 50 })
+const first = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50 })
 if (first.nextOffset !== null) {
-  const second = await ds.list(POSTS, { limit: 50, offset: first.nextOffset })
+  const second = await ds.list('8ffb4814-b028-4496-b679-7face2167ebc', { limit: 50, offset: first.nextOffset })
 }
 ```
 
@@ -149,12 +154,10 @@ if (first.nextOffset !== null) {
 ### Scope the read to the visitor
 
 ```ts
-const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93' // from the table's registration
-
 const listMyInvoices = createServerFn().handler(async ({ context }) => {
   if (!context.user) throw new Error('Not signed in')
 
-  return await ds.list(INVOICES, {
+  return await ds.list('e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93', {
     select: q.select({ owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' }),
     where: q.text('owner').is(context.user.id),
   })

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.21
+  library_version: 0.0.22-alpha.2
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.

package/dist/auth/session.d.ts

@@ -1,16 +0,0 @@
-import "./context.js";
-
-//#region src/auth/session.d.ts
-
-declare function makeSessionTokenCookie(token: string, secure?: boolean): string;
-/** The clearing pair, for the same out-of-context caller as `makeSessionTokenCookie`. */
-declare function makeSessionClearingCookies(secure: boolean): Array<string>;
-/**
- * The name `readSessionToken` would look the token up under on a request of this
- * scheme, for a caller that only needs to know whether one is present and cannot
- * decode it. Same `secure` argument as `makeSessionTokenCookie`, so a caller that
- * writes and a caller that probes cannot disagree about the name.
- */
-declare function sessionTokenCookieName(secure: boolean): string;
-//#endregion
-export { makeSessionClearingCookies, makeSessionTokenCookie, sessionTokenCookieName };