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

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

@@ -1,20 +1,17 @@
 ---
 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.
+  Read the signed-in Softr visitor: useCurrentUser and the User type,
+  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 and the SoftrUserGroups module augmentation
+  that narrows group ids to your own.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
-
 # 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.
@@ -24,7 +21,7 @@ One visitor is resolved once per request and published three ways: as a hook in
 Nothing to install or register, since the app is already wired. Import from the root entrypoint:
 
 ```ts
-import { useCurrentUser, usePermissions } from '@softr/sdk'
+import { useCurrentUser } from '@softr/sdk'
 import type { User } from '@softr/sdk'
 ```
 
@@ -56,12 +53,12 @@ It returns `User | null` and never suspends or fetches. It selects off root rout
 
 ```tsx
 export const Route = createFileRoute('/_app/invoices')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   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).
+A `guardRoute` 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. `isAuthorized(visibility, 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`
 
@@ -85,24 +82,7 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 })
 ```
 
-`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'
-
-const INVOICES = '00000000-0000-0000-0000-000000000001' // the registered datasource's id
-
-function NewInvoiceButton() {
-  const { create } = usePermissions(INVOICES)
-  return create ? <button>New invoice</button> : null
-}
-```
-
-`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.
+`context.user` is 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.
 
 ### Narrowing group ids to your own
 
@@ -122,6 +102,7 @@ With this declaration, `user.userGroupIds` and every `userGroupIds` the SDK acce
 
 ## References
 
-- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized()` narrows `context.user` while applying the route's rule
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `isAuthorized` narrows `context.user` while applying the route's rule
+- [region-visibility/SKILL.md](../region-visibility/SKILL.md): rendering a region only to the visitors a rule admits
 - [record-queries/SKILL.md](../record-queries/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/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
 **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/integrations/SKILL.md

@@ -9,10 +9,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Integrations
 

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

@@ -11,10 +11,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Writing records
 

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

@@ -13,10 +13,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Reading records
 

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

@@ -0,0 +1,63 @@
+---
+name: region-visibility
+description: >-
+  Show part of a page only to the visitors a rule admits: the Audience
+  component, its children and fallback, where a region's rule may be declared,
+  and why hiding a control is not authorization. Use when a button, a column, a
+  nav item or a panel should appear for some visitors and not others, on a page
+  everyone may open. Gating the whole route is routes-and-visibility.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.45
+---
+
+**Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.
+
+# Region visibility
+
+A route's rule decides who may open the page. A region's rule decides what they see once they are on it. The two are independent: an admin panel on a page every signed-in visitor may open is a region, and so is a refund button only staff should reach for.
+
+## Setup
+
+Wrap the region in `Audience` and give it a rule:
+
+```tsx
+import { Audience, defineVisibility } from '@softr/sdk'
+
+const staffOnly = defineVisibility({
+  userGroup: 'LOGGED_IN_USERS',
+  userGroupIds: ['00000000-0000-0000-0000-00000000000a'],
+})
+
+function InvoiceActions({ invoice }: { invoice: Invoice }) {
+  return (
+    <Audience visibility={staffOnly} fallback={<p>Contact your account manager to refund.</p>}>
+      <RefundButton invoice={invoice} />
+    </Audience>
+  )
+}
+```
+
+`Audience` renders its children for the visitors the rule admits and `fallback` for everyone else. Without a `fallback` it renders nothing.
+
+The rules are the same four a route uses, and [routes-and-visibility](../routes-and-visibility/SKILL.md) covers them.
+
+## Core Patterns
+
+### Where the rule is declared
+
+A region's rule is an ordinary value. It can sit beside the component, or come from a module the whole app shares so several regions read the same one. A route's rule cannot. Softr reads that one out of the route file, so it has to be declared there.
+
+Two files cannot hold a region's rule. Any declaration in `__root.tsx` is a build error. In the lazy half of a split route, Softr takes the first declaration as the route's own. Put the rule in the component's file or a shared module and import it.
+
+A route file may declare a region's rule alongside its own. The route's rule is the one `beforeLoad` names.
+
+### Hiding a control is not authorization
+
+`Audience` decides what to render and nothing else. The server function behind a hidden button is still reachable on its own, and Softr authorizes that request whatever the page rendered. If a region hides something sensitive, declare the action behind it with the permissions it should have.
+
+## References
+
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): the rule shapes, and gating a whole page
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a rule has admitted

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

@@ -3,19 +3,20 @@ 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
-  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
-  requires a declaration alongside the rules that reject a duplicate, computed
-  or root-level one.
+  ways to apply a rule: guardRoute and assertRouteAccess in a route,
+  isAuthorized and checkAccess anywhere. Covers per-reason overrides, the
+  redirect and throw strategies, rendering an access error with
+  isAccessError, isUnauthenticatedError, isForbiddenError and
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that requires a
+  declaration alongside the rules that reject a duplicate, computed or
+  root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.
 
 # Route visibility
 
@@ -27,12 +28,12 @@ Every route file, without exception, looks like this:
 
 ```tsx
 import { createFileRoute } from '@tanstack/react-router'
-import { defineVisibility } from '@softr/sdk'
+import { defineVisibility, guardRoute } from '@softr/sdk'
 
 const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   component: Billing,
 })
 
@@ -41,12 +42,13 @@ function Billing() {
 }
 ```
 
-One `defineVisibility` call per file, at module scope, with an inline object literal as its argument.
+The route's rule is one `defineVisibility` call at module scope, with an inline object literal as its argument.
 
-Three rules about that shape, because Softr reads the file rather than running it:
+Four constraints on that shape, because Softr 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`.
+- The route guards itself in `beforeLoad`, naming a rule declared in the same file. A rule imported from elsewhere is rejected.
 - Never declare on `__root.tsx`. The root cannot carry an audience, so a declaration there would gate nothing while looking like it does. Softr rejects it. Put the rule on a layout below the root instead.
 
 The four rules:
@@ -70,28 +72,28 @@ Absent or empty `userGroupIds` means **any** signed-in visitor, not "nobody".
 ```tsx
 // src/routes/_app.tsx: guards every route under /_app
 import { Outlet, createFileRoute } from '@tanstack/react-router'
-import { defineVisibility } from '@softr/sdk'
+import { defineVisibility, guardRoute } from '@softr/sdk'
 
 const visibility = defineVisibility({ userGroup: 'LOGGED_IN_USERS' })
 
 export const Route = createFileRoute('/_app')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   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.
+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 `userGroupIds` 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
 
-`guard()` takes per-reason overrides. A bare string is shorthand for a redirect.
+`guardRoute` takes per-reason overrides as a second argument. 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({
+beforeLoad: guardRoute(visibility, { unauthenticated: '/marketing/sign-up' }),
+beforeLoad: guardRoute(visibility, { forbidden: { strategy: 'throw' } }),
+beforeLoad: guardRoute(visibility, {
   unauthenticated: { strategy: 'redirect', to: '/marketing/sign-up' },
   forbidden: { strategy: 'throw' },
 }),
@@ -122,13 +124,13 @@ All three reasons are required, because nothing fills in a reason the file leave
 | `forbidden` | Signed in, in none of the named groups |
 | `alreadyAuthenticated` | Signed-in visitor on a signed-out-only route |
 
-That file covers every route at once; a route's own `guard()` overrides win over it. `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.
+That file covers every route at once; a route's own overrides win over it. `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'
+import { defineVisibility, guardRoute, isAccessError, isForbiddenError } from '@softr/sdk'
 
 const visibility = defineVisibility({
   userGroup: 'LOGGED_IN_USERS',
@@ -136,7 +138,7 @@ const visibility = defineVisibility({
 })
 
 export const Route = createFileRoute('/_app/billing')({
-  beforeLoad: visibility.guard(),
+  beforeLoad: guardRoute(visibility),
   component: Billing,
   errorComponent: ({ error }: { error: unknown }) => {
     if (isForbiddenError(error)) return <UpgradePrompt />
@@ -152,24 +154,27 @@ Use the predicates: `isAccessError` for any of the three, and `isUnauthenticated
 
 ### 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 `softr.json` for each reason. It takes no overrides.
+`guardRoute` covers almost everything. When a route needs its own logic afterwards, `assertRouteAccess(visibility, context)` 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`.
+It also narrows `context.user` for the rest of the handler: `User` under `LOGGED_IN_USERS`, `null` under `NON_LOGGED_IN_USERS`. `guardRoute` cannot, because it hands `beforeLoad` a function rather than running inside one.
 
 ```ts
 import { redirect } from '@tanstack/react-router'
+import { assertRouteAccess } from '@softr/sdk'
 
 beforeLoad: ({ context }) => {
-  if (visibility.isAuthorized(context)) {
-    if (context.user.email.endsWith('@example.com')) throw redirect({ to: '/internal' })
-  }
+  assertRouteAccess(visibility, 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.
+Reach for `assertRouteAccess` when the route wants the error thrown for it, `isAuthorized(visibility, context)` when it wants the same narrowing without a throw, and `checkAccess(visibility, context)` when it needs to branch on why. `checkAccess` returns `{ ok: true } | { ok: false, reason }` and throws nothing. All of them are synchronous and make no request.
+
+`guardRoute` and `assertRouteAccess` throw router redirects, so they belong in a route and nowhere else. That is what `Route` in their names marks. `isAuthorized` and `checkAccess` throw nothing and answer anywhere, in a loader, a component or a server function.
 
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor a guard has just admitted
 - [record-queries/SKILL.md](../record-queries/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
+- [region-visibility/SKILL.md](../region-visibility/SKILL.md): showing part of a page to some of the visitors the route admits

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

@@ -9,10 +9,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.43
+  library_version: 0.0.45
 ---
 
-**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. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
+**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.
 
 # Triggering workflows
 

package/dist/mcp.d.ts

@@ -1,36 +0,0 @@
-import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start2 from "@tanstack/react-start";
-
-//#region src/mcp.d.ts
-
-type SoftrMcpOptions = {
-  /**
-   * The actions to expose as tools, from `defineQuery` and `defineMutation`.
-   *
-   * Listing them is deliberate: an action left out is invisible over MCP, even
-   * though the app's own pages may use it. The action's own `permissions` still
-   * decide who may run the ones that are listed.
-   */
-  actions?: Array<DatasourceAction>;
-};
-/**
- * Serves the MCP endpoint and its OAuth flow from the app's own origin.
- *
- * Register it in the app's `src/start.ts`, ahead of `softrAuthMiddleware`: it
- * answers its own paths and resolves the caller from the bearer token, so it
- * must not sit behind the session lookup that middleware does on every
- * request. Everything else passes straight through.
- *
- * @example
- * import { publishedPosts, addCafe } from './actions'
- *
- * export const startInstance = createStart(() => ({
- *   requestMiddleware: [
- *     softrMcpMiddleware({ actions: [publishedPosts, addCafe] }),
- *     softrAuthMiddleware(),
- *   ],
- * }))
- */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start2.RequestMiddlewareAfterServer<{}, undefined, undefined>;
-//#endregion
-export { softrMcpMiddleware };