@softr/sdk 0.0.99-se22717.0 → 0.0.99

package/dist/auth/isomorphic.d.ts

@@ -1,7 +1,7 @@
 import { User } from "./user.js";
 import { Formatting } from "../formatting.js";
 import { SoftrContext } from "./context.js";
-import * as react3 from "react";
+import * as react0 from "react";
 import { ReactNode } from "react";
 import * as _tanstack_react_start0 from "@tanstack/react-start";
 
@@ -105,7 +105,7 @@ declare function AuthSettingsProvider({
 }: {
   value: AuthOptions;
   children?: ReactNode;
-}): react3.JSX.Element;
+}): react0.JSX.Element;
 /**
  * Which ways in this app offers. Requires an {@link AuthSettingsProvider}
  * above it.

package/dist/datasource/fields.js

@@ -27,10 +27,8 @@ function makeSortSet(aliases) {
 /**
 * Ands the filters of every `where` call into one, which is what an accumulated `where` needs.
 *
-* The backend takes a group inside a group and no deeper, and the docs promise the caller both levels.
-* A wrapper added here would spend one of them: a single `where` handing over an AND with an OR inside
-* would arrive three deep and be refused. So one filter goes through as it is, and a group that is itself
-* an AND contributes its members to the group built here rather than sitting inside it.
+* One filter goes through as it is. A group that is itself an AND contributes its members to the group
+* built here rather than sitting inside it. So the request is no deeper than the filters the caller wrote.
 */
 function andAll(filters) {
 	if (filters.length === 1) return filters[0];

package/dist/datasource/filter.js

@@ -5,62 +5,48 @@ const INTERNAL_KIND = Symbol("KIND");
 /**
 * Converts filter utility conditions to a format our backend supports.
 *
-* A leaf becomes a group of one, because the wire format has no way to hold a bare
-* condition and a group side by side at the same level.
+* Each group holds its conditions in `filters` and its nested groups in `filterGroups`, at any depth.
+* Both lists are always present. A single condition becomes the only member of an AND group.
 *
 * @example
 * ```tsx
-* const json = buildFilterCriteria(fields.title.contains("hello"));
+* const json = buildFilterCriteria(fields.$and(fields.title.contains("hello"), fields.$or(fields.rating.gt(3), fields.rating.isEmpty())));
 * // result
 * {
-*   "filterCriteria": {
-*     "filterConditionGroup": {
-*       "logicalOperator": "AND"
-*       "filterGroups": [{
-*         "logicalOperator": "AND",
-*         "filters": [{
-*           "subject": "title",
-*           "type": "TEXT",
-*           "operator": "CONTAINS",
-*           "value": "hello"
-*         }],
-*       }]
-*     }
+*   "filterConditionGroup": {
+*     "logicalOperator": "AND",
+*     "filters": [{ "subject": "title", "type": "TEXT", "operator": "CONTAINS", "value": "hello" }],
+*     "filterGroups": [{
+*       "logicalOperator": "OR",
+*       "filters": [
+*         { "subject": "rating", "type": "NUMERIC", "operator": "GT", "value": "3" },
+*         { "subject": "rating", "type": "TEXT", "operator": "IS_EMPTY" }
+*       ],
+*       "filterGroups": []
+*     }]
 *   }
-*  }
-*
+* }
 * ```
 */
 function buildFilterCriteria(input) {
-	assert(INTERNAL_KIND in input, "a filter must come from the callback a read hands you");
-	if (isFilter(input)) return { filterConditionGroup: {
-		logicalOperator: "AND",
-		filterGroups: [{
-			logicalOperator: "AND",
-			filters: [stripInternalKind(input)]
-		}]
-	} };
-	if (isFilterGroup(input)) {
-		if (input.filters.length === 0) return { filterConditionGroup: {
-			logicalOperator: input.logicalOperator,
-			filterGroups: []
-		} };
-		return { filterConditionGroup: {
-			logicalOperator: input.logicalOperator,
-			filterGroups: input.filters.map((inner) => {
-				if (isFilter(inner)) return {
-					logicalOperator: "AND",
-					filters: [stripInternalKind(inner)]
-				};
-				if (!inner.filters.every(isFilter)) throw new Error("Cannot nest filter groups more than three levels deep.");
-				return {
-					logicalOperator: inner.logicalOperator,
-					filters: inner.filters.map(stripInternalKind)
-				};
-			})
-		} };
+	return { filterConditionGroup: isFilterGroup(input) ? buildFilterGroup(input.logicalOperator, input.filters) : buildFilterGroup("AND", [input]) };
+}
+function buildFilterGroup(logicalOperator, members) {
+	const filters = [];
+	const filterGroups = [];
+	for (const member of members) {
+		assert(INTERNAL_KIND in member, "a filter must come from the callback a read hands you");
+		if (isFilterGroup(member)) filterGroups.push(buildFilterGroup(member.logicalOperator, member.filters));
+		else {
+			assert(isFilter(member), () => "Unknown filter kind: " + String(member[INTERNAL_KIND]));
+			filters.push(stripInternalKind(member));
+		}
 	}
-	throw new Error("Unknown filter kind: " + input[INTERNAL_KIND]);
+	return {
+		logicalOperator,
+		filters,
+		filterGroups
+	};
 }
 /**
 * Converts order-by utility conditions to a format our backend supports
@@ -115,13 +101,14 @@ function dealiasOrderBy(orderbys, aliases) {
 */
 function dealiasFilterCriteria(criteria, aliases) {
 	if (!criteria.filterConditionGroup) return criteria;
-	return { filterConditionGroup: {
-		...criteria.filterConditionGroup,
-		filterGroups: criteria.filterConditionGroup.filterGroups.map((group) => ({
+	return { filterConditionGroup: dealiasGroup(criteria.filterConditionGroup) };
+	function dealiasGroup(group) {
+		return {
 			...group,
-			filters: group.filters.map(dealiasFilter)
-		}))
-	} };
+			filters: group.filters.map(dealiasFilter),
+			filterGroups: group.filterGroups.map(dealiasGroup)
+		};
+	}
 	function dealiasFilter(filter) {
 		const subject = aliases[filter.subject];
 		assert(subject, () => `Could not find an alias for subject "${filter.subject}"`);

package/dist/package.js

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

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 # Softr SDK core
@@ -20,11 +20,11 @@ metadata:
 >
 > **CRITICAL**: Every route file must declare its settings with `definePage`, guard itself with them in `beforeLoad` and render them in `head`. 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 `mcp` sub-skill before doing so.
+> **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**: `ai.generate` and `ai.stream` live on `@softr/sdk/server` and only run inside a `createServerFn` handler. Use `defineAiAction` from `@softr/sdk` to declare the action with the model it runs on, an id copied from the `ai_list_models` tool. Softr runs the model on its own keys; never ask the user for an API key for the app's own AI feature. Load the `ai` sub-skill for the full pattern.
+> **CRITICAL**: `ai.generate` and `ai.stream` live on `@softr/sdk/server` and only run inside a `createServerFn` handler. Use `defineAiAction` from `@softr/sdk` to declare the action with the model it runs on, an id copied from the `ai_list_models` tool. Softr runs the model on its own keys; never ask the user for an API key for the app's own AI feature. Load the `softr-sdk/ai` sub-skill for the full pattern.
 >
-> **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 `workflows` sub-skill for the full pattern.
+> **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`.
 
@@ -59,46 +59,46 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 ```text
 Adding a page, or changing who may see one?
-  load the `routes-and-visibility` sub-skill
+  load softr-sdk/routes-and-visibility
 
 Hiding a region of a page from some visitors?
-  load the `region-visibility` sub-skill
+  load softr-sdk/region-visibility
 
 Showing the visitor's name, email or groups?
-  load the `current-user` sub-skill
+  load softr-sdk/current-user
 
 Putting records on a page, in a table, a list or a detail view?
-  load the `record-queries` sub-skill
+  load softr-sdk/record-queries
 
 Drawing a chart, a stat tile, or any aggregated number?
-  load the `charts-and-metrics` sub-skill
+  load softr-sdk/charts-and-metrics
 
 Submitting a form, editing a record, or deleting one?
-  load the `record-mutations` sub-skill
+  load softr-sdk/record-mutations
 
 Triggering a Softr workflow from a button or form?
-  load the `workflows` sub-skill
+  load softr-sdk/workflows
 
 Wiring a login, signup, or sign-out?
-  load the `auth` sub-skill
+  load softr-sdk/auth
 
 Asking an AI model for anything: a summary, fields out of a document, a classification, a draft, a chat?
-  load the `ai` sub-skill — Softr runs the model on its own keys, nothing to connect; pick the model from ai_list_models
+  load softr-sdk/ai — Softr runs the model on its own keys, nothing to connect; pick the model from ai_list_models
 
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
-  load the `integrations` sub-skill
+  load softr-sdk/integrations
 
 Running a model on the user's OWN provider account, because they chose that for the feature?
-  load the `integrations` sub-skill: its "Calling an AI model" section
+  load softr-sdk/integrations: its "Calling an AI model" section
 
 Opening the app to an AI assistant over MCP?
-  load the `mcp` sub-skill
+  load softr-sdk/mcp
 
 Adding an install button, or making the app installable?
-  load the `pwa` sub-skill
+  load softr-sdk/pwa
 
 Showing a date, a time or a number on a page?
-  load the `formatting` sub-skill
+  load softr-sdk/formatting
 
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

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.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.99-se22717.0
+  library_version: 0.0.99
 ---
 
 # The current user
@@ -73,7 +73,7 @@ Never pass the visitor's id from a loader into a server function. The loader als
 ```ts
 import { createServerFn } from '@tanstack/react-start'
 import { defineQuery } from '@softr/sdk'
-import { ds } from '@softr/sdk/server'
+import { auth, ds } from '@softr/sdk/server'
 
 const myInvoices = defineQuery({
   id: 'myInvoices',
@@ -84,12 +84,14 @@ const myInvoices = defineQuery({
 })
 
 const getMyInvoices = createServerFn().handler(async ({ context }) => {
-  if (!context.user) throw new Error('Not signed in')
-  const userId = context.user.id
-  return await ds.list(myInvoices).where((q) => q.owner.is(userId))
+  const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+  if (me === null) return { records: [], total: 0, nextOffset: null }
+  return await ds.list(myInvoices).where((q) => q.owner.isOneOf([me.id]))
 })
 ```
 
+Here `owner` links to Users, and `usersQuery` is the app's query on the Users table. `auth.currentUserRow` answers `null` when the visitor is signed out or has no row. See [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records) for the scope every read of the table takes.
+
 `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.
 
 ### The visitor's role, in a server function

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.99-se22717.0
+  library_version: 0.0.99
 ---
 
 # Dates, times and numbers

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

@@ -7,7 +7,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 # Installing the app

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.
@@ -114,7 +114,7 @@ Resolves to nothing. A record that cannot be deleted throws.
 
 ### Change only the records the visitor may read
 
-When a role reads only some records of a table, it updates and deletes only those records. `permissions` decides who may run the mutation, not which record. The id comes from the browser, so it can name any record. Before the write, read the record through the same query and scope as every read of the table (see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records)). Refuse the write when that read answers `null`, with the same error as a missing record, so the visitor cannot find out which ids exist. Keep the field that the scope filters on, such as the owner, out of the update's `fields`. If it is in `fields`, a visitor can move a record to another person.
+When a role reads only some records of a table, it updates and deletes only those records. `permissions` decides who may run the mutation, not which record. The id comes from the browser, so it can name any record. Before the write, read the record through the same query and scope as every read of the table (see [record-queries](../record-queries/SKILL.md#keep-each-visitor-to-their-own-records)). When the role changes fewer records than it reads, that read filters on the records it may change instead (see [Only the roles that change a table](#only-the-roles-that-change-a-table)). Refuse the write when that read answers `null`, with the same error as a missing record, so the visitor cannot find out which ids exist. Keep the field that the scope filters on, such as the owner, out of the update's `fields`. If it is in `fields`, a visitor can move a record to another person.
 
 Below, `bookings` is the query every read of bookings uses, and `usersQuery` is the app's query on the Users table. `updateBooking` declares `status` only, not `client`.
 
@@ -136,7 +136,7 @@ A delete takes the same read before `ds.delete`. A create into a table that take
 
 ### Only the roles that change a table
 
-Often fewer roles change a table than read it. A mutation's `customGroups` names only the roles that may change the table, also when more roles read it. In a barber app, every client reads the free hours, but only barbers open or close them. So the slot update names the barbers' group only, and a barber still changes only their own slots, through the read above:
+Often fewer roles change a table than read it. A mutation's `customGroups` names only the roles that may change the table, also when more roles read it. In a barber app, every client reads the free hours, but only barbers open or close them. So the slot update names the barbers' group only:
 
 ```ts
 const updateSlot = defineMutation({
@@ -148,6 +148,20 @@ const updateSlot = defineMutation({
 })
 ```
 
+A barber also changes only their own slots. Every client reads every slot, so the read scope does not stop one barber from changing another barber's hours. When a role changes fewer records than it reads, the read before the write filters on the records it may change. Here `slots` is the query every read of slots uses, and its `barber` field links to Users:
+
+```ts
+const setSlotOpen = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string(), open: z.boolean() }))
+  .handler(async ({ context, data }) => {
+    const me = await auth.currentUserRow(context.user, usersQuery, 'email')
+    if (me === null) throw new Error('Slot not found')
+    const slot = await ds.get(slots, { id: data.id }).where((q) => q.barber.isOneOf([me.id]))
+    if (slot === null) throw new Error('Slot not found')
+    await ds.update(updateSlot, { id: slot.id, data: { open: data.open } })
+  })
+```
+
 ### Edit an existing record
 
 An edit form needs both halves: a `defineQuery` to load the record and a `defineMutation` to save it. They are separate declarations over the same table, so give both the fields the form touches, and read the loaded values off the query's names.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.
@@ -197,7 +197,7 @@ const getMyBooking = createServerFn()
   })
 ```
 
-The filter matches the field that holds the owner. A link to the Users table holds the visitor's row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds that row by email, or answers `null` when they are signed out or have no row. A `USER` field holds the account itself, so it filters on `context.user.id` after a check for a signed-out visitor. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
+The filter matches the field that holds the owner. A link to the Users table holds the visitor's row there, not `context.user.id`. `auth.currentUserRow(context.user, usersQuery, 'email')` finds that row by email, or answers `null` when they are signed out or have no row. See [current-user](../current-user/SKILL.md) for how the visitor gets onto `context`.
 
 ### A picker over a scoped table
 
@@ -264,11 +264,13 @@ const listMessages = createServerFn()
     return await ds
       .list(messages)
       .where((q) => q.chat.isOneOf([chat.id]))
-      .orderBy((q) => q.sentAt.asc)
+      .orderBy((q) => q.sentAt.desc)
       .limit(100)
   })
 ```
 
+The read sorts newest first, so the limit keeps the newest 100 messages. Reverse them in the page to show the oldest on top.
+
 A server function that posts a message reads the chat the same way before `ds.create`.
 
 ### Other people's records show only what the role needs

package/skills/softr-sdk/record-queries/references/filters-and-sorting.md

@@ -125,7 +125,7 @@ Both take filters or nested groups:
 )
 ```
 
-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.
+Groups nest to any depth.
 
 **An `$or` with no members matches every row.** When its members come from a list that can be empty, return no rows for an empty list instead of reading the table.
 
@@ -144,5 +144,4 @@ Each field carries `.asc` and `.desc` handles and nothing else. An array applies
 | --- | --- |
 | `a filter must come from the callback a read hands you` | A `where` value built as a plain object |
 | `a sort must come from the callback a read hands you` | An `orderBy` value not from the callback's `.asc` / `.desc` handles |
-| `Cannot nest filter groups more than three levels deep.` | A group nested one level too far |
 | A `TypeError` reading an operator off `undefined` | Filtering or sorting on a field the query does not declare |

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

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

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **Boundary.** `definePage`, `pageHead`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.99-se22717.0
+  library_version: 0.0.99
 ---
 
 **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.