@softr/sdk 0.0.14 → 0.0.16

package/README.md

@@ -1,3 +1,5 @@
 # @softr/sdk
 
 Internal Softr package. Not intended for direct use.
+
+Working on the package itself: see `DOCS.md` in this directory.

package/dist/client.d.ts

@@ -1,3 +1 @@
-import { useUserTimezone } from "./client/timezone.js";
-import "@tanstack/react-start/client-only";
-export { useUserTimezone };
+import "@tanstack/react-start/client-only";

package/dist/client.js

@@ -1,4 +1,3 @@
-import { useUserTimezone } from "./client/timezone.js";
 import "@tanstack/react-start/client-only";
 
-export { useUserTimezone };
+export {  };

package/dist/index.d.ts

@@ -5,4 +5,5 @@ 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";
-export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourcePermissions, type GetOptions, 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 };
+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 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 };

package/dist/index.js

@@ -1,5 +1,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";
 
-export { defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions };
+export { defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/timezone.d.ts

@@ -0,0 +1,4 @@
+//#region src/timezone.d.ts
+declare function useUserTimezone(): void;
+//#endregion
+export { useUserTimezone };

package/dist/{client/timezone.js → timezone.js}

@@ -1,6 +1,6 @@
 import { useEffect } from "react";
 
-//#region src/client/timezone.ts
+//#region src/timezone.ts
 function useUserTimezone() {
 	useEffect(() => {
 		document.cookie = `user-timezone=${Intl.DateTimeFormat().resolvedOptions().timeZone}; path=/`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
@@ -8,7 +8,7 @@
     "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
     "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
   },
-  "files": ["dist"],
+  "files": ["dist", "skills", "!skills/_artifacts"],
   "publishConfig": { "access": "public" },
   "scripts": {
     "build": "tsdown",
@@ -23,6 +23,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@tanstack/intent": "^0.3.6",
     "@tanstack/react-router": "^1.168.0",
     "@tanstack/react-start": "^1.168.0",
     "@types/babel__traverse": "^7.28.0",
@@ -32,10 +33,10 @@
     "vite": "^8.0.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "vite": "^8.0.0",
     "@tanstack/react-router": "^1.168.0",
-    "@tanstack/react-start": "^1.168.0"
+    "@tanstack/react-start": "^1.168.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "vite": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -44,5 +45,11 @@
     "vite": {
       "optional": true
     }
+  },
+  "keywords": ["tanstack-intent"],
+  "intent": {
+    "version": 1,
+    "repo": "@softr/sdk",
+    "docs": "https://www.npmjs.com/package/@softr/sdk"
   }
 }

package/skills/softr-sdk/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: softr-sdk
+description: >-
+  Entry point for @softr/sdk, the layer a Softr app uses to reach Softr: the
+  four entrypoints (@softr/sdk, /server, /client, /vite) and the client-server
+  boundary between them, softrAuthMiddleware, getSoftrContext,
+  initialSoftrContext, SoftrContext, and which sub-skill to load for route
+  visibility, the current user, reading records, or auth. Load this before any
+  other Softr SDK skill.
+metadata:
+  type: core
+  library: softr-sdk
+  library_version: 0.0.16
+---
+
+# Softr SDK core
+
+`@softr/sdk` is how a Softr application talks to Softr. The visitor's identity, who may see a route, records in a datasource, signing in: all of it goes through this package. Everything else is an ordinary TanStack Start app. Routes, server functions, loaders and middleware are Start's, not Softr's.
+
+> **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
+> **CRITICAL**: Every route file must declare its audience with `defineVisibility`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
+> **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.
+
+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`.
+
+## Entrypoints
+
+| Import | Runs | Holds |
+| --- | --- | --- |
+| `@softr/sdk` | Both | `defineVisibility`, `q`, `useCurrentUser`, `usePermissions`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
+| `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
+| `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
+
+## Sub-Skills
+
+| Task | Sub-Skill |
+| --- | --- |
+| Add a route, or change who can see one | [routes-and-visibility/SKILL.md](./routes-and-visibility/SKILL.md) |
+| Read the signed-in visitor or what they may do | [current-user/SKILL.md](./current-user/SKILL.md) |
+| Fetch records from a datasource | [reading-records/SKILL.md](./reading-records/SKILL.md) |
+| Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
+
+## Quick Decision Tree
+
+```text
+Adding a page, or changing who may see one?
+  load softr-sdk/routes-and-visibility
+
+Showing the visitor's name, or hiding UI they cannot use?
+  load softr-sdk/current-user
+
+Putting records on a page, in a table, a list or a detail view?
+  load softr-sdk/reading-records
+
+Wiring a login, signup, or sign-out?
+  load softr-sdk/auth
+
+Writing a server function, loader, or middleware in general?
+  not a Softr concern. Use the TanStack Start skills.
+```
+
+## The wiring
+
+Already present in the app. Read it to understand where the visitor comes from. Do not recreate it.
+
+```ts
+// src/start.ts: resolves the visitor once per request
+import { createCsrfMiddleware, createStart } from '@tanstack/react-start'
+import { softrAuthMiddleware } from '@softr/sdk'
+
+export const startInstance = createStart(() => ({
+  requestMiddleware: [
+    createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' }),
+    softrAuthMiddleware(),
+  ],
+}))
+```
+
+```tsx
+// src/routes/__root.tsx: publishes the visitor as route context
+import { createRootRouteWithContext } from '@tanstack/react-router'
+import { getSoftrContext } from '@softr/sdk'
+import type { SoftrContext } from '@softr/sdk'
+
+export const Route = createRootRouteWithContext<SoftrContext>()({
+  beforeLoad: async () => await getSoftrContext(),
+  shellComponent: RootDocument,
+})
+```
+
+```ts
+// src/router.tsx: the context before any request has resolved one
+import { createRouter } from '@tanstack/react-router'
+import { initialSoftrContext } from '@softr/sdk'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  return createRouter({ routeTree, context: initialSoftrContext() })
+}
+```
+
+`SoftrContext` is what all three produce, and what every guard and every server function reads:
+
+```ts
+type SoftrContext = {
+  user: User | null                                   // null means signed out
+  permissions: { datasource: Record<string, DatasourcePermissions> }
+}
+
+type User = {
+  id: string
+  email: string
+  name: string
+  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
+}
+```
+
+## Version
+
+Targets `@softr/sdk` v0.0.15.

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

@@ -0,0 +1,171 @@
+---
+name: auth
+description: >-
+  Sign a Softr visitor in, out, or up from a server function: auth.signIn,
+  auth.signOut, auth.signUp and auth.confirmSignUp from @softr/sdk/server, the
+  Result shape they answer with ({ success, data } | { success, error }) and its
+  codes invalidCredentials, tooManyAttempts, emailTaken, invalidDetails and
+  invalidCode, the two-step sign-up, and redirecting after a successful sign-in.
+  The blank template already ships working login and signup pages.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.16
+---
+
+This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
+
+# Auth
+
+`auth` is what changes who the visitor is. It exposes four calls and nothing else:
+
+| Call | Does |
+| --- | --- |
+| `auth.signIn({ email, password })` | Signs a visitor in |
+| `auth.signOut()` | Signs the visitor out |
+| `auth.signUp({ email, name? })` | Emails a verification code, creates no account |
+| `auth.confirmSignUp({ email, password, code, name? })` | Creates the account and signs in |
+
+**The blank template already ships a working login page and signup page.** Read `src/routes/_auth/login.tsx` before writing anything new. Most tasks are an edit to those, not a new flow.
+
+## Setup
+
+`auth` is server-only, so every call sits inside a `createServerFn` handler:
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { redirect } from '@tanstack/react-router'
+import { auth } from '@softr/sdk/server'
+import { z } from 'zod'
+```
+
+Pass a zod schema straight to `.validator`. Start accepts it directly and types `data` from it:
+
+```ts
+const Credentials = z.object({ email: z.string(), password: z.string() })
+
+const signIn = createServerFn({ method: 'POST' })
+  .validator(Credentials)
+  .handler(async ({ data }) => { /* data is { email, password } */ })
+```
+
+Keep the schema to the shape the call needs. Softr is what decides whether an email exists, whether a password is right, and whether a code is still valid, and it answers with the codes below. A second set of rules in the app is just a second place to be wrong.
+
+A form that posts `FormData` instead validates with a function, since a zod object schema does not accept `FormData`:
+
+```ts
+.validator((fields: FormData) => Credentials.parse(Object.fromEntries(fields)))
+```
+
+`signIn`, `signUp` and `confirmSignUp` answer with a `Result` rather than throwing on something the visitor can fix. `signOut` returns nothing.
+
+```ts
+type Result<T> =
+  | { success: true; data: T }
+  | { success: false; error: { code: AuthErrorCode; message: string } }
+
+type AuthErrorCode =
+  | 'invalidCredentials'   // signIn: wrong email or password
+  | 'tooManyAttempts'      // signIn: rate limited
+  | 'emailTaken'           // signUp or confirmSignUp: that email already has an account
+  | 'invalidDetails'       // signUp: details Softr rejected
+  | 'invalidCode'          // confirmSignUp: wrong or expired verification code
+```
+
+Each code comes from the call named beside it. Email and password is the sign-in method these calls cover.
+
+## Core Patterns
+
+### Sign in
+
+```ts
+const signIn = createServerFn({ method: 'POST' })
+  .validator(Credentials)
+  .handler(async ({ data }) => {
+    const result = await auth.signIn(data)
+
+    if (!result.success) {
+      return {
+        message:
+          result.error.code === 'tooManyAttempts'
+            ? 'Too many attempts. Please try again in a few minutes.'
+            : 'Please ensure your email and password are correct.',
+      }
+    }
+
+    throw redirect({ to: '/' })
+  })
+```
+
+Two exits: return a message for the form to render, or `throw redirect` on success. Do not put `error.message` in front of the visitor. Write your own wording, as above.
+
+Call it from the component with `useServerFn`:
+
+```tsx
+import { useServerFn } from '@tanstack/react-start'
+
+const submit = useServerFn(signIn)
+```
+
+A server function that throws `redirect` needs the hook. Call the imported function directly and the throw never reaches the router, so a successful sign-in leaves the visitor on the form.
+
+A login page is a `NON_LOGGED_IN_USERS` route, which is what keeps an already-signed-in visitor off it. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
+
+### Sign out
+
+```ts
+const signOut = createServerFn({ method: 'POST' }).handler(async () => {
+  await auth.signOut()
+  throw redirect({ to: '/login' })
+})
+```
+
+It returns nothing and has no failure the visitor can act on, so send them somewhere and let the redirect re-resolve the context.
+
+### Sign up, in two steps
+
+```ts
+const Details = z.object({ email: z.string(), name: z.string() })
+const Confirmation = Details.extend({ password: z.string(), code: z.string() })
+
+// Step 1: emails a code. No account exists yet.
+const startSignUp = createServerFn({ method: 'POST' })
+  .validator(Details)
+  .handler(async ({ data }) => {
+    const result = await auth.signUp(data)
+    if (!result.success) {
+      return {
+        message:
+          result.error.code === 'emailTaken'
+            ? 'That email already has an account.'
+            : 'Please check the details and try again.',
+      }
+    }
+    return { message: null }   // now show the code field
+  })
+
+// Step 2: creates the account and signs the visitor in.
+const finishSignUp = createServerFn({ method: 'POST' })
+  .validator(Confirmation)
+  .handler(async ({ data }) => {
+    const result = await auth.confirmSignUp(data)
+    if (!result.success) {
+      return {
+        message:
+          result.error.code === 'emailTaken'
+            ? 'That email already has an account. Please sign in instead.'
+            : 'That code is not valid. Please try again.',
+      }
+    }
+
+    throw redirect({ to: '/' })
+  })
+```
+
+The UI has to carry email and password into step two, plus the name if step one collected one. `name` is optional to `confirmSignUp`, the rest is not. It is the only call that creates the account.
+
+## References
+
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor these calls establish
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `NON_LOGGED_IN_USERS` and the `alreadySignedIn` redirect that keeps a signed-in visitor off a login page
+- `src/routes/_auth/login.tsx` and `signup.tsx` in your own app: the implementations it was scaffolded with

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

@@ -0,0 +1,118 @@
+---
+name: current-user
+description: >-
+  Read the signed-in Softr visitor and what they may do: useCurrentUser and the
+  User type, usePermissions and DatasourcePermissions, context.user in a route's
+  beforeLoad, and context.user inside a server function handler, where Start
+  types it from the app's registered request middleware. Covers the null guest,
+  SoftrUserGroups module augmentation for narrowing group ids, and why
+  permissions are a rendering hint rather than an authorization check.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.16
+---
+
+This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.
+
+# The current user
+
+One visitor is resolved once per request and published three ways: as a hook in components, as route context in `beforeLoad`, and on the `context` argument inside a server function. All three read the same `SoftrContext`. Which one you reach for depends only on where the code runs.
+
+## Setup
+
+Nothing to install or register, since the app is already wired. Import from the root entrypoint:
+
+```ts
+import { useCurrentUser, usePermissions } from '@softr/sdk'
+import type { User } from '@softr/sdk'
+```
+
+```ts
+type User = {
+  id: string
+  email: string
+  name: string
+  userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
+}
+```
+
+## Core Patterns
+
+### In a component: `useCurrentUser()`
+
+```tsx
+import { useCurrentUser } from '@softr/sdk'
+
+function Header() {
+  const user = useCurrentUser()
+  return <p>{user ? `Hello, ${user.name}` : 'Please sign in'}</p>
+}
+```
+
+It returns `User | null` and never suspends or fetches. It selects off root route context, so it is available anywhere below the root, on the server render and in the browser alike.
+
+### In a route: `context.user`
+
+```tsx
+export const Route = createFileRoute('/_app/invoices')({
+  beforeLoad: visibility.guard(),
+  loader: ({ context }) => fetchInvoicesFor({ data: { userId: context.user!.id } }),
+})
+```
+
+A `guard()` in `beforeLoad` guarantees a visitor at runtime, but it does not change what the compiler sees. `context.user` is still `User | null` further down the route. `visibility.isAuthorized(context)` is the check that narrows it, so prefer that over `!`. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
+
+### In a server function: `context`
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+
+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' }),
+    where: q.text('owner').is(context.user.id),
+  })
+})
+```
+
+`context.user` and `context.permissions` are typed. Start derives a handler's context from the app's registered request middleware as well as the server function's own, so there is nothing to import and nothing to cast.
+
+### Hiding UI the visitor cannot use
+
+```tsx
+import { usePermissions } from '@softr/sdk'
+
+function NewInvoiceButton() {
+  const { create } = usePermissions('ds_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.
+
+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.
+
+### Narrowing group ids to your own
+
+```ts
+// src/softr.d.ts
+declare module '@softr/sdk' {
+  interface SoftrUserGroups {
+    ids:
+      | 'b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'
+      | 'f9e8d7c6-5b4a-4938-8271-605f4e3d2c1b'
+  }
+}
+export {}
+```
+
+With this declaration, `user.userGroupIds` and every `userGroupIds` the SDK accepts narrow to those ids, and a typo stops compiling. Without it they are plain `string`.
+
+## References
+
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized()` narrows `context.user` while applying the route's rule
+- [reading-records/SKILL.md](../reading-records/SKILL.md): filtering a query by the visitor, and who really authorizes the read
+- [auth/SKILL.md](../auth/SKILL.md): what changes the value `useCurrentUser` returns

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

@@ -0,0 +1,135 @@
+---
+name: reading-records
+description: >-
+  Fetch records from a Softr datasource inside a server function: ds.list and
+  ds.get from @softr/sdk/server, the q query builder (q.text, q.number,
+  q.boolean, q.date, q.array, q.and, q.or, q.asc, q.desc), q.select field
+  aliasing, filtering, sorting, the 20-record default and 100-record cap, and
+  nextOffset pagination. Reads only. Mutations, workflows, integrations, metrics
+  and chart data are not covered.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.16
+---
+
+This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
+
+# 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.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+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.
+
+A record comes back as `{ id: string; fields: Record<string, unknown> }`.
+
+## Core Patterns
+
+### List records
+
+```ts
+const listPublishedPosts = createServerFn().handler(async () => {
+  return await ds.list('ds_posts', {
+    select: q.select({
+      title: 'fld_title',
+      author: 'fld_author',
+      published: 'fld_published',
+      publishedAt: 'fld_published_at',
+    }),
+    where: q.boolean('published').is(true),
+    orderBy: q.desc('publishedAt'),
+    limit: 50,
+  })
+})
+```
+
+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.
+
+**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:
+
+```ts
+const select = q.select({ title: 'fld_a1b2c3', views: 'fld_d4e5f6' })
+
+await ds.list('ds_posts', {
+  select,
+  where: q.number('views').gt(100),   // alias, not fld_d4e5f6
+  orderBy: q.asc('title'),            // alias here too
+})
+// records[0].fields is { title: ..., views: ... }
+```
+
+Once `select` is present it is the whole vocabulary. The returned record carries exactly those keys, and any field you filter or sort on must appear in the map.
+
+### Get one record
+
+```ts
+const post = await ds.get('ds_posts', { id: postId })
+if (post === null) throw notFound()
+```
+
+A record that does not exist comes back as `null`, not an error.
+
+The type also accepts `{ where }` instead of `{ id }`, but there is no way to pass a `select` alongside it, so the filter cannot be translated and the call throws. Fetch one record by id, or use `ds.list` with a `limit` of 1 when you need to find it by a field.
+
+### Filter with `q`
+
+```ts
+where: q.and(
+  q.text('status').is('active'),
+  q.number('amount').gte(100),
+  q.or(
+    q.text('owner').is(user.id),
+    q.array('collaborators').hasAllOf([user.id]),
+  ),
+)
+```
+
+Five field types, `q.text`, `q.number`, `q.boolean`, `q.date` and `q.array`, combined with `q.and` and `q.or`. The full operator matrix is in [references/query-builder.md](./references/query-builder.md).
+
+### Paginate
+
+```ts
+const first = await ds.list('ds_posts', { limit: 50 })
+if (first.nextOffset !== null) {
+  const second = await ds.list('ds_posts', { limit: 50, offset: first.nextOffset })
+}
+```
+
+`nextOffset` is `null` when there are no more pages. `total` is the count of all matching records, not the count returned.
+
+### Scope the read to the visitor
+
+```ts
+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' }),
+    where: q.text('owner').is(context.user.id),
+  })
+})
+```
+
+See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
+
+A server function is its own endpoint, reachable whether or not the visitor ever matched the route that displays the data. A route's visibility rule decides who sees a page. The server function decides for itself who gets the records.
+
+A read the visitor is not allowed to make throws rather than coming back empty, and it throws a plain `Error` carrying the status. There is no typed predicate to narrow it with. Handle it where you would handle any other failed fetch: an `errorComponent` on the route, or a check in the handler.
+
+## References
+
+- [references/query-builder.md](./references/query-builder.md): every `q` field type and operator
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to scope a query
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): deciding who sees the page the records land on

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

@@ -0,0 +1,144 @@
+# `q`, the query builder
+
+Every filter, sort and field map passed to `ds` is built with `q`, imported from `@softr/sdk`. Filters and sorts built any other way are rejected at runtime.
+
+```ts
+import { q } from '@softr/sdk'
+```
+
+## Shape
+
+```ts
+await ds.list(datasourceId, {
+  select: q.select({ alias: 'fld_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
+  offset: number | null,
+})
+```
+
+`where` takes exactly one value. For more than one condition, wrap them in `q.and(...)` or `q.or(...)`.
+
+## Field types and operators
+
+Pick the builder that matches the field's type. The type travels with the operator and decides how the value is compared.
+
+### `q.text(field)`
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: string)` | Exactly equal |
+| `.isNot(value: string)` | Not equal |
+| `.contains(value: string)` | Substring match |
+| `.startsWith(value: string)` | Prefix match |
+| `.endsWith(value: string)` | Suffix match |
+| `.isOneOf(values: string[])` | Equal to any of |
+| `.isNoneOf(values: string[])` | Equal to none of |
+| `.hasAllOf(values: string[])` | Contains all of |
+| `.isEmpty()` | No value |
+| `.isNotEmpty()` | Has a value |
+
+### `q.number(field)`
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: number)` | Equal |
+| `.isNot(value: number)` | Not equal |
+| `.gt(value: number)` | Greater than |
+| `.gte(value: number)` | Greater than or equal |
+| `.lt(value: number)` | Less than |
+| `.lte(value: number)` | Less than or equal |
+| `.between(start: number, end: number)` | Inclusive range |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+Takes JavaScript numbers.
+
+### `q.boolean(field)`
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: boolean)` | Equal |
+| `.isNot(value: boolean)` | Not equal |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+### `q.date(field)`
+
+| Call | Meaning |
+| --- | --- |
+| `.is(value: string)` | On that date |
+| `.isNot(value: string)` | Not on that date |
+| `.gt(value: string)` | After |
+| `.gte(value: string)` | On or after |
+| `.lt(value: string)` | Before |
+| `.lte(value: string)` | On or before |
+| `.between(start: string, end: string)` | Inclusive range |
+| `.isNotBetween(start: string, end: string)` | Outside the range |
+| `.isEmpty()` / `.isNotEmpty()` | No value / has a value |
+
+Every value is an ISO date string, either `'2026-01-31'` or a full timestamp. A `Date` instance is not accepted. Call `.toISOString()` first.
+
+### `q.array(field)`
+
+For multi-value fields: linked records, multi-selects, collaborators.
+
+| Call | Meaning |
+| --- | --- |
+| `.is(values: string[])` | Exactly this set |
+| `.isOneOf(values: string[])` | Contains at least one of |
+| `.isNoneOf(values: string[])` | Contains none of |
+| `.hasAllOf(values: string[])` | Contains all of |
+| `.isEmpty()` / `.isNotEmpty()` | Empty / non-empty |
+
+## Combining
+
+```ts
+q.and(...filters)   // all must match
+q.or(...filters)    // any may match
+```
+
+Both take filters or nested groups:
+
+```ts
+where: q.and(
+  q.text('status').is('active'),
+  q.or(
+    q.number('amount').gte(1000),
+    q.array('tags').hasAllOf(['priority']),
+  ),
+)
+```
+
+Nesting goes two levels, a group inside a group. A third level throws `Cannot nest filter groups more than three levels deep.` Flatten by distributing the outer condition rather than nesting further.
+
+## Sorting
+
+```ts
+orderBy: q.asc('title')
+orderBy: [q.desc('publishedAt'), q.asc('title')]
+```
+
+Sorts are applied in array order.
+
+## Field maps
+
+```ts
+const select = q.select({ title: 'fld_a1b2c3', views: 'fld_d4e5f6' })
+```
+
+`q.select` maps names you choose onto Softr field ids. 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.
+
+So `select` must list every field the query touches, not just the ones being displayed.
+
+## Errors
+
+| Message | Cause |
+| --- | --- |
+| `Filters cannot be constructed manually. Use the 'q' helper.` | A `where` value built as a plain object |
+| `orderBy conditions cannot be constructed manually. Use the 'q' helper.` | An `orderBy` value not from `q.asc` / `q.desc` |
+| `Cannot nest filter groups more than three levels deep.` | A group nested one level too far |
+| `Could not find an alias for subject "..."` | A sort field missing from `select`, or an `orderBy` with no `select` at all |
+| `Could not find an alias for subject "undefined"` | The same thing on a filter, which does not report the field name |

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

@@ -0,0 +1,160 @@
+---
+name: routes-and-visibility
+description: >-
+  Add a route file to a Softr app and declare who may see it: defineVisibility
+  with ALL_USERS, LOGGED_IN_USERS or NON_LOGGED_IN_USERS, userGroupIds, and the
+  four ways to enforce a rule (guard, assert, isAuthorized, check). Covers
+  per-reason overrides, the redirect and throw strategies, rendering an access
+  error with isAccessError, isUnauthenticatedError, isForbiddenError and
+  isAlreadySignedInError, guarding a layout, and the lint rule that requires a
+  declaration alongside the build rules that reject a duplicate, computed or
+  root-level one.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.16
+---
+
+This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.
+
+# Route visibility
+
+Every route file in a Softr app declares who may see it. The build reads that declaration out of the source text without executing it and publishes it to Softr Studio, which shows the app owner every route and its audience. That is why the rules below are strict: a rule the build cannot read is a rule Studio cannot show.
+
+## Setup
+
+Every route file, without exception, looks like this:
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { defineVisibility } from '@softr/sdk'
+
+const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
+
+export const Route = createFileRoute('/_app/billing')({
+  beforeLoad: visibility.guard(),
+  component: Billing,
+})
+
+function Billing() {
+  return <h1>Billing</h1>
+}
+```
+
+One `defineVisibility` call per file, at module scope, with an inline object literal as its argument.
+
+Three rules about that shape, because the build reads the file rather than running it:
+
+- The call must initialise a top-level `const`.
+- The import must be a direct named import from `@softr/sdk`.
+- Never declare on `__root.tsx`. The root cannot carry an audience, so the build rejects a declaration there rather than shipping an app that only looks gated. Put the rule on a layout below the root instead.
+
+The four rules:
+
+```ts
+defineVisibility({ userGroup: 'ALL_USERS' })            // everyone, signed in or not
+defineVisibility({ userGroup: 'NON_LOGGED_IN_USERS' })  // signed-out only: login, signup
+defineVisibility({ userGroup: 'LOGGED_IN_USERS' })      // any signed-in visitor
+defineVisibility({                                      // those groups only
+  userGroup: 'LOGGED_IN_USERS',
+  userGroupIds: ['b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],
+})
+```
+
+Absent or empty `userGroupIds` means **any** signed-in visitor, not "nobody".
+
+## Core Patterns
+
+### Guard a whole section with one layout route
+
+```tsx
+// src/routes/_app.tsx: guards every route under /_app
+import { Outlet, createFileRoute } from '@tanstack/react-router'
+import { defineVisibility } from '@softr/sdk'
+
+const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
+
+export const Route = createFileRoute('/_app')({
+  beforeLoad: visibility.guard(),
+  component: () => <Outlet />,
+})
+```
+
+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.
+
+### Change what a denied visitor gets
+
+`guard()` takes per-reason overrides. A bare string is shorthand for a redirect.
+
+```ts
+beforeLoad: visibility.guard({ unauthenticated: '/marketing/sign-up' }),
+beforeLoad: visibility.guard({ forbidden: { strategy: 'throw' } }),
+beforeLoad: visibility.guard({
+  unauthenticated: { strategy: 'redirect', to: '/marketing/sign-up' },
+  forbidden: { strategy: 'throw' },
+}),
+```
+
+The long redirect form and the bare string do the same thing.
+
+The defaults, when no override is given:
+
+| Reason | Condition | Default |
+| --- | --- | --- |
+| `unauthenticated` | Route needs a visitor, none present | Redirect to `/login` |
+| `forbidden` | Signed in, in none of the named groups | Throw, renders in place |
+| `alreadySignedIn` | Signed-in visitor on a signed-out-only route | Redirect to `/` |
+
+`ALL_USERS` admits everyone, so it never redirects and never throws. Only `strategy: 'throw'` reaches an `errorComponent`. A redirect navigates away and the route never renders.
+
+### Render the error in place
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { defineVisibility, isAccessError, isForbiddenError } from '@softr/sdk'
+
+const visibility = defineVisibility({
+  userGroup: 'LOGGED_IN_USERS',
+  userGroupIds: ['b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],
+})
+
+export const Route = createFileRoute('/_app/billing')({
+  beforeLoad: visibility.guard(),
+  component: Billing,
+  errorComponent: ({ error }: { error: unknown }) => {
+    if (isForbiddenError(error)) return <UpgradePrompt />
+    if (isAccessError(error)) return <NoAccess />
+    return <SomethingWentWrong />
+  },
+})
+```
+
+The error carries a `type` discriminant and its `reason`, nothing else. It never names the groups the route wanted, which would hand that list to the one visitor who was just turned away.
+
+Use the predicates: `isAccessError` for any of the three, and `isUnauthenticatedError`, `isForbiddenError`, `isAlreadySignedInError` for one each. The error is plain data rather than an `Error` subclass, so `instanceof` never matches and there is no `message` to read. That is also why the parameter is annotated `error: unknown`. The router types it as `Error`, and the wider annotation is what lets the predicates narrow it. Leave it as it is.
+
+### Run the check and then keep going
+
+`guard()` covers almost everything. When a route needs its own logic afterwards, `assert()` applies the same rule and throws the same access error, using the default behaviour for each reason. It takes no overrides.
+
+`assert()` guarantees the visitor at runtime but does not narrow `context.user` for the compiler. `isAuthorized()` is the one that narrows. It is a type predicate, so inside its `true` branch `context.user` is `User` under `LOGGED_IN_USERS` and `null` under `NON_LOGGED_IN_USERS`.
+
+```ts
+import { redirect } from '@tanstack/react-router'
+
+beforeLoad: ({ context }) => {
+  if (visibility.isAuthorized(context)) {
+    if (context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
+  }
+},
+```
+
+Reach for `assert()` when the route wants the error thrown for it, and `check(context)` when it needs to branch on why. `check` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
+
+## References
+
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a guard has just admitted
+- [reading-records/SKILL.md](../reading-records/SKILL.md): a guard covers the page, not the server function behind it
+- [auth/SKILL.md](../auth/SKILL.md): `NON_LOGGED_IN_USERS` and the sign-in flow it fronts

package/dist/client/timezone.d.ts

@@ -1,4 +0,0 @@
-//#region src/client/timezone.d.ts
-declare function useUserTimezone(): void;
-//#endregion
-export { useUserTimezone };