@softr/sdk 0.0.20 → 0.0.21

package/dist/auth/isomorphic.d.ts

@@ -18,7 +18,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
  *   requestMiddleware: [softrAuthMiddleware()],
  * }))
  */
-declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, {
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: Permissions;
 }>;
@@ -48,7 +48,7 @@ declare function initialSoftrContext(): SoftrContext;
  * @example
  * function Greeting() {
  *   const user = useCurrentUser()
- *   return <p>{user ? `Hello, ${user.name}` : "Please sign in"}</p>
+ *   return <p>{user ? `Hello, ${user.fullName}` : "Please sign in"}</p>
  * }
  */
 declare function useCurrentUser(): User | null;

package/dist/auth/isomorphic.js

@@ -2,6 +2,7 @@ import { assert, panic, requireDefined } from "../assertions.js";
 import { writeCookies } from "../cookies.js";
 import { sessionConfig } from "./config.js";
 import { makePlatform } from "./platform.js";
+import { bootErrorMiddleware } from "../boot-error.js";
 import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
 import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
@@ -20,7 +21,7 @@ import { createMiddleware, createServerFn, getGlobalStartContext } from "@tansta
 * }))
 */
 function softrAuthMiddleware() {
-	return createMiddleware({ type: "request" }).server(async ({ next }) => {
+	return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware()]).server(async ({ next }) => {
 		async function getSession() {
 			const token = readSessionToken();
 			const cached = readSessionData(token);
@@ -77,7 +78,7 @@ function initialSoftrContext() {
 * @example
 * function Greeting() {
 *   const user = useCurrentUser()
-*   return <p>{user ? `Hello, ${user.name}` : "Please sign in"}</p>
+*   return <p>{user ? `Hello, ${user.fullName}` : "Please sign in"}</p>
 * }
 */
 function useCurrentUser() {

package/dist/auth/methods/password.js

@@ -1,4 +1,4 @@
-import { panic, softAssert, todo } from "../../assertions.js";
+import { panic, softAssert } from "../../assertions.js";
 import { writeCookies } from "../../cookies.js";
 import { sessionConfig } from "../config.js";
 import { makePlatform } from "../platform.js";
@@ -10,26 +10,20 @@ import { authError } from "./utils.js";
 * Signs a visitor in with an email and password.
 */
 async function signIn(credentials) {
-	const platform = makePlatform(sessionConfig().applicationId);
-	const result = await platform.signIn(credentials);
+	const result = await makePlatform(sessionConfig().applicationId).tokens(credentials);
 	if (!result.ok) {
 		if (result.status === 401 || result.status === 429) return authError(result.status === 401 ? "invalidCredentials" : "tooManyAttempts", result.message);
 		if (result.status >= 500) panic(result.message);
-		if (result.status === 400) todo(result.message);
 		throw new Error(`${result.message}. Check SOFTR_APPLICATION_ID and that the app allows sign-in.`);
 	}
-	const body = result.data;
-	if (body?.authenticatorAppAction) todo(`Sign-in needs an authenticator step (${body.authenticatorAppAction}), which the SDK cannot finish yet.`);
-	const token = body?.jwt;
-	if (!token) todo("This app is configured for passwordless sign-in, which the SDK cannot finish yet.");
-	const sessionResult = await platform.session(token);
-	if (!sessionResult.ok) panic(sessionResult.message);
-	const session = sessionResult.data;
-	if (session.user === null) panic("Session token issued, but no user came back with it.");
-	writeCookies([makeSessionTokenCookie(token), makeSessionDataCookie(session, token)]);
+	const { jwt, user, permissions } = result.data;
+	writeCookies([makeSessionTokenCookie(jwt), makeSessionDataCookie({
+		user,
+		permissions
+	}, jwt)]);
 	return {
 		success: true,
-		data: session.user
+		data: user
 	};
 }
 /**

package/dist/auth/platform.js

@@ -1,5 +1,6 @@
 import { panic } from "../assertions.js";
 import { sessionConfig } from "./config.js";
+import { userSchema } from "./user.js";
 import { permissionsSchema } from "./permissions.js";
 import { z } from "zod";
 
@@ -11,22 +12,9 @@ function makePlatform(applicationId) {
 				method: "GET",
 				token
 			}, z.object({
-				user: z.object({
-					id: z.string(),
-					email: z.string().nullish(),
-					fullName: z.string().nullish(),
-					userGroupIds: z.array(z.string()).nullish()
-				}).nullish(),
+				user: userSchema.nullable(),
 				permissions: permissionsSchema
-			}).transform(({ user, permissions }) => ({
-				user: user ? {
-					id: user.id,
-					email: user.email ?? "",
-					name: user.fullName ?? "",
-					userGroupIds: user.userGroupIds ?? []
-				} : null,
-				permissions
-			})));
+			}));
 			if (result.status === 404) panic(`Application ${applicationId} not found. Check SOFTR_APPLICATION_ID.`);
 			return result;
 		},
@@ -35,32 +23,9 @@ function makePlatform(applicationId) {
 			json: credentials
 		}, z.object({
 			jwt: z.string(),
-			user: z.object({
-				id: z.string(),
-				email: z.string().nullish(),
-				fullName: z.string().nullish(),
-				userGroupIds: z.array(z.string()).nullish()
-			}).nullish(),
+			user: userSchema,
 			permissions: permissionsSchema
-		}).transform(({ jwt, user, permissions }) => ({
-			token: jwt,
-			session: {
-				user: user ? {
-					id: user.id,
-					email: user.email ?? "",
-					name: user.fullName ?? "",
-					userGroupIds: user.userGroupIds ?? []
-				} : null,
-				permissions
-			}
-		}))),
-		signIn: (credentials) => request(`/v1/applications/${applicationId}/users/sign-in`, {
-			method: "POST",
-			json: credentials
-		}, z.object({
-			jwt: z.string().nullish(),
-			authenticatorAppAction: z.string().nullish()
-		}).nullable()),
+		})),
 		signUp: (body) => request(`/v1/applications/${applicationId}/users/sign-up`, {
 			method: "POST",
 			json: body

package/dist/auth/session.js

@@ -1,5 +1,6 @@
 import { readRequestCookies, serializeCookie, writeCookies } from "../cookies.js";
 import { sessionConfig } from "./config.js";
+import { userSchema } from "./user.js";
 import { permissionsSchema } from "./permissions.js";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 import { z } from "zod";
@@ -69,12 +70,7 @@ function clearSession() {
 	clearCookies([SESSION_TOKEN, SESSION_DATA]);
 }
 const sessionDataSchema = z.object({
-	user: z.object({
-		id: z.string(),
-		email: z.string(),
-		name: z.string(),
-		userGroupIds: z.array(z.string())
-	}).nullable(),
+	user: userSchema.nullable(),
 	permissions: permissionsSchema,
 	exp: z.number(),
 	tb: z.string()

package/dist/auth/user.d.ts

@@ -1,4 +1,7 @@
+import { z } from "zod";
+
 //#region src/auth/user.d.ts
+
 /**
  * Declare this interface in your app to narrow every group id the SDK takes and
  * returns. Without a declaration, a group id is a plain `string`.
@@ -21,7 +24,7 @@ type SoftrUserGroupId = SoftrUserGroups extends {
 type User = {
   id: string;
   email: string;
-  name: string;
+  fullName: string;
   userGroupIds: Array<SoftrUserGroupId>;
 };
 //#endregion

package/dist/auth/user.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+//#region src/auth/user.ts
+const userSchema = z.object({
+	id: z.string(),
+	email: z.string(),
+	fullName: z.string(),
+	userGroupIds: z.array(z.string())
+});
+
+//#endregion
+export { userSchema };

package/dist/boot-error.js

@@ -0,0 +1,252 @@
+import { isNotFound, isRedirect } from "@tanstack/react-router";
+import { createMiddleware } from "@tanstack/react-start";
+
+//#region src/boot-error.ts
+/**
+* Catches errors thrown before the router renders, in request middleware or SSR
+* setup, where a route's `errorComponent` cannot reach. Without it the browser
+* gets a bare JSON 500 and the real message only reaches the terminal.
+*
+* Compose it as a dependency of the outermost request middleware, so that it
+* wraps everything registered after it.
+*/
+function bootErrorMiddleware() {
+	return createMiddleware({ type: "request" }).server(async ({ next, handlerType }) => {
+		try {
+			return await next();
+		} catch (error) {
+			if (handlerType === "serverFn" || error instanceof Response || isRedirect(error) || isNotFound(error)) throw error;
+			return new Response(errorPage(error), {
+				status: 500,
+				headers: { "content-type": "text/html; charset=utf-8" }
+			});
+		}
+	});
+}
+function errorPage(error) {
+	if (process.env.NODE_ENV === "production") return page("Something went wrong", "This page couldn’t be shown. Try again in a moment, and if it keeps happening, reach out to the owner of this app.", { note: "If you are the owner, you can check what happened in Studio." });
+	const cause = error instanceof Error ? error.cause : void 0;
+	const root = cause instanceof Error ? cause : error;
+	const message = root instanceof Error ? root.message : String(root);
+	const stack = root instanceof Error ? root.stack : void 0;
+	return page("This app crashed", "The app stopped before it could start. The technical details below show where it failed and can be copied to the agent to help fix the issue.", {
+		note: "These details are only shown because the app is running in development mode.",
+		detail: `<pre class="message">${escapeHtml(message)}</pre>`,
+		actions: stack ? `<button type="button" id="toggle" aria-expanded="true" aria-controls="panel">
+             <svg class="chevron" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9 18 6-6-6-6"/></svg>
+             Technical details
+           </button>` : "",
+		panel: stack ? `<div class="stack" id="panel">
+             <pre id="stack">${escapeHtml(stack)}</pre>
+             <button type="button" id="copy" aria-label="Copy stack trace">
+               <svg class="copy" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
+               <svg class="check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
+             </button>
+           </div>
+           <script>
+             const toggle = document.getElementById('toggle')
+             const panel = document.getElementById('panel')
+             const stack = document.getElementById('stack')
+
+             const setOpen = (open) => {
+               toggle.setAttribute('aria-expanded', String(open))
+               panel.hidden = !open
+             }
+             setOpen(false)
+             toggle.addEventListener('click', () => {
+               setOpen(toggle.getAttribute('aria-expanded') === 'false')
+             })
+
+             document.getElementById('copy').addEventListener('click', async (event) => {
+               const button = event.currentTarget
+               try {
+                 await navigator.clipboard.writeText(stack.textContent)
+                 button.dataset.copied = ''
+                 setTimeout(() => delete button.dataset.copied, 1500)
+               } catch {
+                 // Denied clipboard permission. Select it so Ctrl/Cmd+C works.
+                 getSelection().selectAllChildren(stack)
+               }
+             })
+           <\/script>` : ""
+	});
+}
+function page(title, description, { note = "", detail = "", actions = "", panel = "" } = {}) {
+	return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(title)}</title>
+    <style>
+      /* Mirrors the shadcn tokens the templates ship. Theme follows the OS
+         here, because a stored choice needs the app to be running. */
+      :root {
+        color-scheme: light dark;
+        --background: oklch(1 0 0);
+        --foreground: oklch(0.145 0 0);
+        --card: oklch(1 0 0);
+        --muted: oklch(0.97 0 0);
+        --muted-foreground: oklch(0.556 0 0);
+        --border: oklch(0.922 0 0);
+        --input: oklch(0.922 0 0);
+        --input-fill: oklch(1 0 0);
+        --input-fill-hover: oklch(0.97 0 0);
+        --primary: oklch(0.205 0 0);
+        --primary-foreground: oklch(0.985 0 0);
+        --destructive: oklch(0.577 0.245 27.325);
+        --radius: 0.625rem;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --background: oklch(0.145 0 0);
+          --foreground: oklch(0.985 0 0);
+          --card: oklch(0.205 0 0);
+          --muted: oklch(0.269 0 0);
+          --muted-foreground: oklch(0.708 0 0);
+          --border: oklch(1 0 0 / 10%);
+          --input: oklch(1 0 0 / 15%);
+          --input-fill: oklch(1 0 0 / 4.5%);
+          --input-fill-hover: oklch(1 0 0 / 7.5%);
+          --primary: oklch(0.922 0 0);
+          --primary-foreground: oklch(0.205 0 0);
+          --destructive: oklch(0.704 0.191 22.216);
+        }
+      }
+      * { box-sizing: border-box }
+      body {
+        margin: 0;
+        min-height: 100dvh;
+        display: grid;
+        place-items: center;
+        /* Without an explicit minmax the column sizes to main's max-width and
+           overflows narrow viewports. */
+        grid-template-columns: minmax(0, 1fr);
+        padding: 1.5rem;
+        background: var(--background);
+        color: var(--foreground);
+        font: 0.875rem/1.5 Inter, ui-sans-serif, system-ui, sans-serif;
+        overflow-wrap: anywhere;
+      }
+      main {
+        width: 100%;
+        max-width: 36rem;
+        display: flex;
+        flex-direction: column;
+        gap: 1.25rem;
+        padding: 1.5rem;
+        border-radius: calc(var(--radius) + 4px);
+        background: var(--card);
+        box-shadow: 0 0 0 1px color-mix(in oklch, var(--foreground) 10%, transparent);
+      }
+      .alert {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: 2.5rem;
+        height: 2.5rem;
+        border-radius: var(--radius);
+        background: color-mix(in oklch, var(--destructive) 12%, transparent);
+        color: var(--destructive);
+      }
+      .alert svg { width: 1.25rem; height: 1.25rem }
+      h1 { margin: 0; font-size: 1rem; font-weight: 500; line-height: 1.375 }
+      p { margin: 0.375rem 0 0; color: var(--muted-foreground) }
+      p.note { margin-top: 0.75rem; opacity: 0.65 }
+      pre {
+        margin: 0;
+        padding: 0.75rem;
+        border-radius: var(--radius);
+        background: var(--muted);
+        font: 0.75rem/1.6 ui-monospace, SFMono-Regular, Menlo, monospace;
+        max-height: 16rem;
+        overflow: auto;
+      }
+      pre.message { font-size: 0.8125rem; white-space: pre-wrap }
+      .actions { display: flex; flex-wrap: wrap; gap: 0.5rem }
+      .actions button {
+        display: inline-flex;
+        align-items: center;
+        gap: 0.375rem;
+        height: 2rem;
+        padding: 0 0.75rem;
+        border-radius: var(--radius);
+        font: inherit;
+        font-weight: 500;
+        cursor: pointer;
+        user-select: none;
+      }
+      .actions button svg { width: 0.875rem; height: 0.875rem }
+      #toggle {
+        padding-left: 0.5rem;
+        border: 1px solid var(--input);
+        background: var(--input-fill);
+        color: inherit;
+      }
+      #toggle:hover { background: var(--input-fill-hover) }
+      .chevron { transition: transform 150ms }
+      #toggle[aria-expanded='true'] .chevron { transform: rotate(90deg) }
+      .stack { position: relative }
+      .stack pre { padding-right: 2.75rem }
+      #copy {
+        position: absolute;
+        top: 0.375rem;
+        right: 0.375rem;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 1.75rem;
+        height: 1.75rem;
+        padding: 0;
+        /* Opaque, so the stack trace underneath never shows through the icon. */
+        border: 1px solid var(--input);
+        border-radius: calc(var(--radius) - 2px);
+        background: var(--card);
+        color: var(--muted-foreground);
+        cursor: pointer;
+      }
+      #copy:hover {
+        background: color-mix(in oklch, var(--card), var(--foreground) 6%);
+        color: var(--foreground);
+      }
+      #copy svg { width: 0.875rem; height: 0.875rem }
+      #copy .check, #copy[data-copied] .copy { display: none }
+      #copy[data-copied] .check { display: block }
+      .retry {
+        border: 1px solid transparent;
+        background: var(--primary);
+        color: var(--primary-foreground);
+      }
+      /* Mixed with the card rather than faded, so it stays opaque. */
+      .retry:hover { background: color-mix(in oklch, var(--primary) 80%, var(--card)) }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="alert">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><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"/><path d="M12 9v4"/><path d="M12 17h.01"/></svg>
+      </div>
+      <div>
+        <h1>${escapeHtml(title)}</h1>
+        <p>${escapeHtml(description)}</p>
+        ${note ? `<p class="note">${escapeHtml(note)}</p>` : ""}
+      </div>
+      ${detail}
+      <div class="actions">
+        <button type="button" class="retry" onclick="location.reload()">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M8 16H3v5"/></svg>
+          Try again
+        </button>
+        ${actions}
+      </div>
+      ${panel}
+    </main>
+  </body>
+</html>`;
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+//#endregion
+export { bootErrorMiddleware };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "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.20
+  library_version: 0.0.21
 ---
 
 # Softr SDK core
@@ -116,11 +116,11 @@ type SoftrContext = {
 type User = {
   id: string
   email: string
-  name: string
+  fullName: string
   userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
 }
 ```
 
 ## Version
 
-Targets `@softr/sdk` v0.0.20.
+Targets `@softr/sdk` v0.0.21.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.20
+  library_version: 0.0.21
 ---
 
 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.20
+  library_version: 0.0.21
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.
@@ -46,7 +46,7 @@ import { useCurrentUser } from '@softr/sdk'
 
 function Header() {
   const user = useCurrentUser()
-  return <p>{user ? `Hello, ${user.name}` : 'Please sign in'}</p>
+  return <p>{user ? `Hello, ${user.fullName}` : 'Please sign in'}</p>
 }
 ```
 
@@ -68,11 +68,14 @@ A `guard()` in `beforeLoad` guarantees a visitor at runtime, but it does not cha
 ```ts
 import { createServerFn } from '@tanstack/react-start'
 
+// The datasource id from the table's registration on the application — not the table id.
+const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93'
+
 const getMyInvoices = createServerFn().handler(async ({ context }) => {
   if (!context.user) throw new Error('Not signed in')
 
-  return await ds.list('ds_invoices', {
-    select: q.select({ owner: 'fld_owner', amount: 'fld_amount' }),
+  return await ds.list(INVOICES, {
+    select: q.select({ owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' }),
     where: q.text('owner').is(context.user.id),
   })
 })
@@ -85,13 +88,15 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 ```tsx
 import { usePermissions } from '@softr/sdk'
 
+const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93' // the registered datasource's id
+
 function NewInvoiceButton() {
-  const { create } = usePermissions('ds_invoices')
+  const { create } = usePermissions(INVOICES)
   return create ? <button>New invoice</button> : null
 }
 ```
 
-`usePermissions(datasourceId)` returns `{ read, create, update, delete }` for one datasource. It hides a control. It does not protect what the control does.
+`usePermissions(datasourceId)` returns `{ read, create, update, delete }` for one datasource. The id is the opaque UUID from the table's registration on the application, the same one `ds.*` takes — not the table id, and never built from the table's name. It hides a control. It does not protect what the control does.
 
 Pass an id the visitor's session has no entry for and it throws while rendering, so a typo takes the page down rather than returning four falses.
 

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.20
+  library_version: 0.0.21
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
@@ -24,10 +24,16 @@ 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.
+
 ## Core Patterns
 
 ### Create a record
@@ -38,9 +44,9 @@ const NewProject = z.object({ name: z.string(), status: z.string() })
 const createProject = createServerFn({ method: 'POST' })
   .validator(NewProject)
   .handler(async ({ data }) =>
-    ds.create('ds_projects', {
+    ds.create(PROJECTS, {
       data,
-      select: q.select({ name: 'fld_name', status: 'fld_status' }),
+      select: q.select({ name: 'fZk3Qm9pLw2Xa1', status: 'Ru7bVx2cNq0Ed9' }),
     }),
   )
 ```
@@ -59,10 +65,10 @@ const Rename = z.object({ id: z.string(), name: z.string() })
 const renameProject = createServerFn({ method: 'POST' })
   .validator(Rename)
   .handler(async ({ data }) =>
-    ds.update('ds_projects', {
+    ds.update(PROJECTS, {
       id: data.id,
       data: { name: data.name },
-      select: q.select({ name: 'fld_name' }),
+      select: q.select({ name: 'fZk3Qm9pLw2Xa1' }),
     }),
   )
 ```
@@ -78,7 +84,7 @@ const RecordId = z.object({ id: z.string() })
 
 const deleteProject = createServerFn({ method: 'POST' })
   .validator(RecordId)
-  .handler(async ({ data }) => ds.delete('ds_projects', data.id))
+  .handler(async ({ data }) => ds.delete(PROJECTS, data.id))
 ```
 
 **`delete` takes the record id as a positional argument**, unlike `create` and `update`, which take an options object. It resolves to nothing.
@@ -95,6 +101,8 @@ Stamping a record with who created it, or scoping an update to the person making
 
 ## Failure Modes
 
+**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 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.20
+  library_version: 0.0.21
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
@@ -25,10 +25,16 @@ 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.
+
 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.
 
 ## Typing record fields
@@ -53,8 +59,10 @@ 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(PRODUCTS, { select, limit: 100 }) as Promise<ListResult<Product>>
 )
 ```
 
@@ -66,12 +74,12 @@ const fetchProducts = createServerFn().handler(() =>
 
 ```ts
 const listPublishedPosts = createServerFn().handler(async () => {
-  return await ds.list('ds_posts', {
+  return await ds.list(POSTS, {
     select: q.select({
-      title: 'fld_title',
-      author: 'fld_author',
-      published: 'fld_published',
-      publishedAt: 'fld_published_at',
+      title: 'fZk3Qm9pLw2Xa1',
+      author: 'mB4kQ8yTn1sWc7',
+      published: 'Ru7bVx2cNq0Ed9',
+      publishedAt: 'Xp2dLh6vKz9Fa3',
     }),
     where: q.boolean('published').is(true),
     orderBy: q.desc('publishedAt'),
@@ -80,20 +88,20 @@ const listPublishedPosts = createServerFn().handler(async () => {
 })
 ```
 
-Returns `{ records, total, nextOffset }`. `ds.list('ds_posts')` on its own returns the first 20 records with their raw field ids. `limit` defaults to 20 and is clamped to 100. A larger number is silently reduced, so more than a hundred records means paginating.
+Returns `{ records, total, nextOffset }`. `ds.list(POSTS)` on its own returns the first 20 records with their raw field ids. `limit` defaults to 20 and is clamped to 100. A larger number is silently reduced, so more than a hundred records means paginating.
 
 **Filtering or sorting requires a `select`, and it has to cover every field you name.** `where` and `orderBy` speak aliases, so without a map to translate through they throw at request time. That is why `published` is in the map above even though the table never displays it.
 
 ### Name the fields with `select`
 
-Softr field ids are opaque (`fld_a1b2c3`). `q.select` maps your own names onto them, and those names are what the rest of the call speaks:
+Softr field ids are opaque strings (`fZk3Qm9pLw2Xa1`), copied from the table's schema. `q.select` maps your own names onto them, and those names are what the rest of the call speaks:
 
 ```ts
-const select = q.select({ title: 'fld_a1b2c3', views: 'fld_d4e5f6' })
+const select = q.select({ title: 'fZk3Qm9pLw2Xa1', views: 'Ru7bVx2cNq0Ed9' })
 
-await ds.list('ds_posts', {
+await ds.list(POSTS, {
   select,
-  where: q.number('views').gt(100),   // alias, not fld_d4e5f6
+  where: q.number('views').gt(100),   // alias, not Ru7bVx2cNq0Ed9
   orderBy: q.asc('title'),            // alias here too
 })
 // records[0].fields is { title: ..., views: ... }
@@ -104,7 +112,7 @@ Once `select` is present it is the whole vocabulary. The returned record carries
 ### Get one record
 
 ```ts
-const post = await ds.get('ds_posts', { id: postId })
+const post = await ds.get(POSTS, { id: postId })
 if (post === null) throw notFound()
 ```
 
@@ -130,9 +138,9 @@ Five field types, `q.text`, `q.number`, `q.boolean`, `q.date` and `q.array`, com
 ### Paginate
 
 ```ts
-const first = await ds.list('ds_posts', { limit: 50 })
+const first = await ds.list(POSTS, { limit: 50 })
 if (first.nextOffset !== null) {
-  const second = await ds.list('ds_posts', { limit: 50, offset: first.nextOffset })
+  const second = await ds.list(POSTS, { limit: 50, offset: first.nextOffset })
 }
 ```
 
@@ -141,11 +149,13 @@ 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('ds_invoices', {
-    select: q.select({ owner: 'fld_owner', amount: 'fld_amount' }),
+  return await ds.list(INVOICES, {
+    select: q.select({ owner: 'Gq5wNt8rJy3Hb1', amount: 'Vk9cXm2pSz6Ld4' }),
     where: q.text('owner').is(context.user.id),
   })
 })

package/skills/softr-sdk/reading-records/references/query-builder.md

@@ -10,7 +10,7 @@ import { q } from '@softr/sdk'
 
 ```ts
 await ds.list(datasourceId, {
-  select: q.select({ alias: 'fld_id', ... }),   // optional field map
+  select: q.select({ alias: '<field id>', ... }),   // optional field map
   where: <one filter, or q.and/q.or of filters>,
   orderBy: q.asc('alias') | [q.desc('a'), q.asc('b')],
   limit: number,                                // default 20, clamped down to 100
@@ -123,10 +123,10 @@ Sorts are applied in array order.
 ## Field maps
 
 ```ts
-const select = q.select({ title: 'fld_a1b2c3', views: 'fld_d4e5f6' })
+const select = q.select({ title: 'fZk3Qm9pLw2Xa1', views: 'Ru7bVx2cNq0Ed9' })
 ```
 
-`q.select` maps names you choose onto Softr field ids. Two rules follow from that:
+`q.select` maps names you choose onto Softr field ids — opaque strings copied from the table's schema. Two rules follow from that:
 
 1. The returned record carries exactly the keys in the map. A field left out is not returned, and no error is raised.
 2. `where` and `orderBy` name aliases, and every one of them must be in the map. A name that is not throws `Could not find an alias for subject "..."` at request time, and so does a `where` or `orderBy` passed with no `select` at all.

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