@softr/sdk 0.0.84 → 0.0.85

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.84";
+var version = "0.0.85";
 
 //#endregion
 export { version };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 # Softr SDK core
@@ -16,8 +16,11 @@ metadata:
 `@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` and guard itself with that rule in `beforeLoad`. There is no default and nothing is inherited from a sibling.
+>
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register `softrAuthMiddleware` and resolve the session. Do not add a second registration of it. `softrMcpMiddleware` is the one thing an app adds to `src/start.ts` itself — load the `softr-sdk/mcp` sub-skill before doing so.
+>
 > **CRITICAL**: `workflow.trigger` lives on `@softr/sdk/server` and only runs inside a `createServerFn` handler. Use `defineWorkflow` from `@softr/sdk` to declare the action, then pass it to `workflow.trigger`. Load the `softr-sdk/workflows` sub-skill for the full pattern.
 
 Each sub-skill stands alone for its task and repeats the boundary above, so most work needs **one** sub-skill and not this file. Load this one when you are unsure which sub-skill applies, or when the wiring below is what you are touching. Add a second sub-skill only when the work genuinely crosses that boundary: a page that lists records behind a group restriction needs `record-queries` plus `routes-and-visibility`.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -465,4 +465,4 @@ The page keeps showing the old name and photo until its route context loads agai
 ## 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 `alreadyAuthenticated` redirect that keeps a signed-in visitor off a login page
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `NON_LOGGED_IN_USERS` and the `alreadyAuthenticated` redirect that keeps a signed-in visitor off a login page

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 # Dates, times and numbers
@@ -16,6 +16,7 @@ metadata:
 Softr stores every date and time as UTC. The builder chooses in Studio how the app shows dates, times and numbers: in each visitor's own format and zone (the default), or in one fixed format or zone for everyone. The SDK resolves that choice once per request. The server and the browser then format with the same values, so the page the server renders and the page the browser hydrates show the same text.
 
 > **CRITICAL**: Never call `toLocaleDateString`, `toLocaleTimeString`, `toLocaleString` or `new Intl.DateTimeFormat` / `new Intl.NumberFormat` in code that renders. The server and the browser have different locales and time zones, so the text differs and React throws a hydration mismatch. A hard-coded `'en-US'` or `timeZone: 'UTC'` hides the error but ignores the builder's settings and shows the wrong format and day to most visitors.
+>
 > **CRITICAL**: Format with the helpers below and nothing else. They follow the app's settings, and they are the only formatters that give the same text on the server and in the browser.
 
 ## Setup

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -59,8 +59,7 @@ Declare the **full endpoint path**, not just the host — one action names one e
 
 `integration.createFetcher(action)` binds the action and returns a fetcher function. The `method` and `url` come from the action — you do not repeat them on the call. Pass an optional init object with:
 
-- `params` — fills `{placeholder}` tokens in the declared url, one key per token. Pass each value raw: the
-  SDK encodes it.
+- `params` — fills `{placeholder}` tokens in the declared url, one key per token. Pass each value raw: the SDK encodes it.
 - `query` — appended as a query string (`?key=value`).
 - `headers` — extra request headers.
 - `body` — request body string.
@@ -127,11 +126,7 @@ Do not add an `Authorization` key to `headers` — Softr injects the integration
 
 ## Calling an AI model
 
-A button on one record that hands its fields to the model and shows the answer is the `ai-action` pattern:
-it carries this call and the model id, so write the call by hand only for another shape — a batch, a chat,
-a field the model fills on create. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on
-`https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of
-`model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
+A button on one record that hands its fields to the model and shows the answer is the `ai-action` pattern: it carries this call and the model id, so write the call by hand only for another shape — a batch, a chat, a field the model fills on create. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on `https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of `model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
 
 ```ts
 const askClaude = defineIntegration({
@@ -157,17 +152,14 @@ const body = (await res.json()) as { content: Array<{ type: string; text?: strin
 const text = body.content.flatMap((block) => (block.type === 'text' && block.text ? [block.text] : [])).join('')
 ```
 
-**Use the model id above as it is written here.** Model ids are not derivable: one spelled from memory
-(`claude-3-5-…`, `claude-sonnet-4-…`) names a model that no longer answers, and the error only shows up when
-the button is pressed. `claude-opus-5-5` is the current default; `claude-sonnet-5-5` is the cheaper one for a
-short summary.
+**Use the model id above as it is written here.** Model ids are not derivable: one spelled from memory (`claude-3-5-…`, `claude-sonnet-4-…`) names a model that no longer answers, and the error only shows up when the button is pressed. `claude-opus-5-5` is the current default; `claude-sonnet-5-5` is the cheaper one for a short summary.
 
 ## Base URLs by integration type
 
 Match the `integrationType` from the attached integrations section to find the base URL:
 
 | integrationType | Base URL |
-|---|---|
+| --- | --- |
 | ANTHROPIC_AI | `https://api.anthropic.com` |
 | APOLLO | `https://api.apollo.io` |
 | APIFY | `https://api.apify.com` |
@@ -216,8 +208,7 @@ Match the `integrationType` from the attached integrations section to find the b
 | XERO | `https://api.xero.com` |
 | ZOOM | `https://api.zoom.us` |
 
-`REST_API` is a custom API, so it has no row here. Each connection has its own base URL, and
-`connect-a-service` says where to read it.
+`REST_API` is a custom API, so it has no row here. Each connection has its own base URL, and `connect-a-service` says where to read it.
 
 ## When the type is in the table but nothing is attached
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.
@@ -64,6 +64,7 @@ Connecting starts with an approval page the app serves. Most people hit it signe
 **The app's login has to send them back.** Every exit that ends a sign-in, the second-factor step included, goes to `toReturnPath(location)` instead of the home page. See [auth/SKILL.md](../auth/SKILL.md). Lose the search param anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
 
 `toReturnPath` only ever goes to a path on this app. Never follow the param without it. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
+
 ## Failure modes
 
 **Registering with no actions.** `softrMcpMiddleware()` is valid and serves an endpoint with nothing on it. The assistant connects, lists tools, finds only `whoami`. Pass the actions.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 # Installing the app
@@ -17,6 +17,7 @@ metadata:
 The builder turns installing on in Studio, under Settings → Mobile app, and sets the name, colour and icon there. The app already answers with its manifest and icon once they do. What the app adds is two things: the links that point the browser at them, and a button that tells visitors how to install.
 
 > **CRITICAL**: Never write a web app manifest, icon files, a service worker, or `manifest` / `apple-touch-icon` links of your own, in `public/` or in `head()`. The app already serves them from Studio's settings, and a file of your own shadows those settings.
+>
 > **CRITICAL**: Render an install button only while `usePwaInstall()` returns `available: true`. Never show it unconditionally, never cache the answer, never replace the check with your own. Softr can switch installing off for an app, and this check is the only way that reaches the button.
 
 ## Setup

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
@@ -63,9 +63,7 @@ defineVisibility({
 })
 ```
 
-Everyone is both audiences, as in the first line above. A set names each audience at most once and
-is never empty — the type and the build both reject one that does not. `customGroups` never stands alone: it narrows the `LOGGED_IN_USERS` half of the set, so the rule still names that half, and one without `userGroupTypes` is a type error. Absent or empty it
-means **any** signed-in visitor, not "nobody".
+Everyone is both audiences, as in the first line above. A set names each audience at most once and is never empty — the type and the build both reject one that does not. `customGroups` never stands alone: it narrows the `LOGGED_IN_USERS` half of the set, so the rule still names that half, and one without `userGroupTypes` is a type error. Absent or empty it means **any** signed-in visitor, not "nobody".
 
 Take every id in `customGroups` from `docs/user-groups.md`, which lists each group the app has with its name and id. An id the app does not have is a type error.
 
@@ -88,7 +86,7 @@ export const Route = createFileRoute('/_app')({
 
 The whole match chain runs, so a layout guards everything beneath it. Sibling routes do not guard each other. `/admin/index.tsx` does nothing for `/admin/users.tsx` unless an `admin.tsx` layout exists. A route below a guarded layout declares and guards its own rule too.
 
-A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can *throw* — a `customGroups` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
+A thrown error renders in place of the guarded route's component. A shell layout guarded with `LOGGED_IN_USERS`, where `unauthenticated` redirects, sends a signed-out visitor away before anything renders there. A rule that can _throw_ — a `customGroups` rule with `forbidden` set to throw — should not sit on the shell itself, or the error replaces the nav and chrome. Put it on a layout inside the shell, or on the restricted routes, so the error renders inside the chrome.
 
 ### Change what a denied visitor gets
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.84
+  library_version: 0.0.85
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -56,7 +56,7 @@ Write the object inline in `defineWorkflow`. Passing it through a variable widen
 These placeholders are resolved server-side when the workflow runs:
 
 | Value | Resolves to |
-|---|---|
+| --- | --- |
 | `{LOGGED_IN_USER:EMAIL}` | Signed-in user's email |
 | `{LOGGED_IN_USER:NAME}` | Signed-in user's name |
 | `{LOGGED_IN_USER:RECORD_ID}` | Signed-in user's record id |