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

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/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

@@ -61,12 +61,21 @@ async function editEngine() {
 	if (!dir) return false;
 	const entry = pathToFileURL(path.join(dir, "dist", "vite.js")).href;
 	try {
-		return (await import(entry)).editEngineStudio();
+		return (await import(entry)).editEngineStudio({ sessionCookies: await sessionCookies() });
 	} catch (error) {
 		console.error(`[softr] could not load the edit engine from ${entry}:`, error);
 		return false;
 	}
 }
+/** Imported only for a preview, so an ordinary build never loads the session machinery at all. */
+async function sessionCookies() {
+	const { makeSessionTokenCookie, makeSessionClearingCookies, sessionTokenCookieName } = await import("./auth/session.js");
+	return {
+		makeSessionTokenCookie,
+		makeSessionClearingCookies,
+		sessionTokenCookieName
+	};
+}
 
 //#endregion
 export { MANIFEST_RELATIVE_PATH, generateManifest, softr };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.22-alpha.0",
+  "version": "0.0.22-alpha.1",
   "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.1
 ---
 
 # 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.1
 ---
 
 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.1
 ---
 
 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.1
 ---
 
 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.1
 ---
 
 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.1
 ---
 
 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 };