@softr/sdk 0.0.27 → 0.0.29

package/dist/core/integration.d.ts

@@ -1,5 +1,5 @@
 //#region src/core/integration.d.ts
-declare function integrationFetch(integrationId: string, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+declare function integrationFetch(datasourceId: string, input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
 declare const integration: {
   fetch: typeof integrationFetch;
 };

package/dist/core/integration.js

@@ -2,7 +2,7 @@ import { readSessionToken } from "../auth/session.js";
 import { dsUrl } from "../datasource/record.js";
 
 //#region src/core/integration.ts
-async function integrationFetch(integrationId, input, init) {
+async function integrationFetch(datasourceId, input, init) {
 	const req = new Request(input, init);
 	if (req.signal.aborted) throw req.signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
 	const reqHeaders = {};
@@ -16,7 +16,7 @@ async function integrationFetch(integrationId, input, init) {
 	};
 	const method = req.method.toUpperCase();
 	if (method !== "GET" && method !== "HEAD" && req.body !== null) payload.body = await req.clone().text();
-	return fetch(`${dsUrl(integrationId)}/proxy`, {
+	return fetch(`${dsUrl(datasourceId)}/proxy`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",

package/dist/datasource/record.js

@@ -232,7 +232,8 @@ async function deleteRecord(action, options) {
 	if (!res.ok) throw new Error(`Softr datasource delete failed for "${datasourceId}": ${res.status}`);
 }
 function resolveTarget(subject, operation) {
-	assert(isAction(subject), "a read or a mutation takes an action from defineAction");
+	const declaredBy = operation === "read" ? "defineQuery" : "defineMutation";
+	assert(isAction(subject), () => `Expected an action from ${declaredBy} but got ${JSON.stringify(subject)}`);
 	const action = subject;
 	assert(action.operation === operation, () => `action "${action.id}" is declared as ${action.operation}, not ${operation}`);
 	return {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { SoftrDatasources, defineAction } from "./action.js";
+import { SoftrDatasources, defineMutation, defineQuery } from "./action.js";
 import { SoftrContext } from "./auth/context.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";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { DefaultErrorOverlay, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineAction, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { DefaultErrorOverlay, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineMutation, defineQuery, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { defineAction } from "./action.js";
+import { defineMutation, defineQuery } from "./action.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";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 
-export { DefaultErrorOverlay, defineAction, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { DefaultErrorOverlay, defineMutation, defineQuery, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/package.js

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

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -5,13 +5,13 @@ description: >-
   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, writing records, or auth. Load
-  this when unsure which sub-skill applies, or when touching the wiring; each
-  sub-skill stands alone for its own task.
+  visibility, the current user, reading records, charts and metrics, writing
+  records, or auth. Load this when unsure which sub-skill applies, or when
+  touching the wiring; each sub-skill stands alone for its own task.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.29
 ---
 
 # Softr SDK core
@@ -23,13 +23,13 @@ metadata:
 > **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.
 > **CRITICAL**: `workflow.trigger` is exploratory. It exists on the entrypoints below and typechecks, but its endpoint is not final. Do not build a feature on it. Tell the user the capability is not ready and ask how they want to proceed.
 
-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 `reading-records` plus `routes-and-visibility`.
+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`.
 
 ## Entrypoints
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineVisibility`, `q`, `useCurrentUser`, `usePermissions`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `useCurrentUser`, `usePermissions`, `useUserTimezone`, `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` |
@@ -40,8 +40,9 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | --- | --- |
 | 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) |
-| Create, update or delete a record | [data-mutations/SKILL.md](./data-mutations/SKILL.md) |
+| Fetch records from a datasource | [record-queries/SKILL.md](./record-queries/SKILL.md) |
+| Chart, aggregate or count records | [charts-and-metrics/SKILL.md](./charts-and-metrics/SKILL.md) |
+| Create, update or delete a record | [record-mutations/SKILL.md](./record-mutations/SKILL.md) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 
@@ -55,10 +56,13 @@ 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
+  load softr-sdk/record-queries
+
+Drawing a chart, a stat tile, or any aggregated number?
+  load softr-sdk/charts-and-metrics
 
 Submitting a form, editing a record, or deleting one?
-  load softr-sdk/data-mutations
+  load softr-sdk/record-mutations
 
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
@@ -125,7 +129,3 @@ type User = {
   userGroupIds: Array<SoftrUserGroupId>   // plain string unless you declare your ids
 }
 ```
-
-## Version
-
-Targets `@softr/sdk` v0.0.26.

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

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.29
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. 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.

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

@@ -0,0 +1,180 @@
+---
+name: charts-and-metrics
+description: >-
+  Aggregate Softr datasource records inside a server function: ds.chart with
+  groupBy, metrics, where and orderBy for chart rows, ds.metric for a single
+  headline number, date bucket intervals, which aggregations each kind of field
+  offers, the two-group-column ceiling, and distinct values for filter controls.
+  Use when drawing a chart, a stat tile or any counted, summed or averaged
+  number, when filling a dropdown from a real column, or when a chart comes back
+  scrambled or with the wrong rows. Aggregation only: fetching individual
+  records is record-queries, and changing them is record-mutations.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.29
+---
+
+**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.
+
+# Charts and metrics
+
+`ds.chart` groups records and aggregates each group into one row: the data behind a bar chart, a line, a pie. `ds.metric` aggregates everything into one value: the number on a stat tile. Both live on `@softr/sdk/server` and run inside a `createServerFn` handler, and both take the same query `ds.list` takes, with the same `where` filters.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { defineQuery } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+
+const sales = defineQuery({
+  id: 'sales',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  fields: {
+    amount: 'Vk9cXm2pSz6Ld4',   // CURRENCY
+    region: 'fZk3Qm9pLw2Xa1',   // SELECT
+    status: 'Ru7bVx2cNq0Ed9',   // SELECT, choice ids 'paid' | 'open' | 'void'
+    closedAt: 'Xp2dLh6vKz9Fa3', // DATETIME
+    rep: 'Gq5wNt8rJy3Hb1',      // LINKED_RECORD
+  },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+A chart only sees the query's declared fields, so a field to group, aggregate or filter by must be in `fields`. Declaring a query belongs to [record-queries](../record-queries/SKILL.md); one query serves `ds.list`, `ds.chart` and `ds.metric`.
+
+## Core Patterns
+
+### A bar chart
+
+```ts
+const ordersByRegion = createServerFn().handler(async () => {
+  const { data } = await ds
+    .chart(sales)
+    .groupBy((q) => ({ region: q.region }))
+    .metrics((q) => ({ orders: q.$count }))
+    .orderBy((q) => q.orders.desc)
+  return data
+})
+// data: Array<{ region: string | null; orders: number }>
+```
+
+One row per group, keyed by the names you chose in `groupBy` and `metrics`. `orders` is `number`, not `number | null`: a group that exists holds at least one record. The `null` region is the bucket of records with no value. The result also carries `executionTimestamp: Date`, when the numbers were computed.
+
+A SELECT or LINKED_RECORD group column comes back as the choice's display label, not its id. Labels are user-editable and a `where` on the same field compares ids, so a clicked bar's value cannot be fed straight back into a filter.
+
+### A time series
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .where((q) => q.status.is('paid'))
+  .orderBy((q) => q.month.asc)
+// data: Array<{ month: string | null; revenue: number | null }>
+```
+
+`q.closedAt` bare groups by the field's value. The bucket leaves hanging off it group a date field by the bucket: `byDay`, `byWeek`, `byMonth`, `byQuarter`, `byYear`, and the cyclic `byHourOfDay`, `byDayOfWeek`, `byMonthOfYear`, `byQuarterOfYear`. What each one holds is in [references/aggregations.md](./references/aggregations.md); `byMonth` reads as `"2025-06"`.
+
+**Sort the time axis ascending yourself.** Left unsorted, rows come back by the first bucket ascending when there is one, else by the first metric descending. A time axis that misses the fallback arrives in value order, which draws a scrambled line rather than failing.
+
+### Spread, not just totals
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ region: q.region }))
+  .metrics((q) => ({
+    smallest: q.amount.min,
+    typical: q.amount.avg,
+    biggest: q.amount.max,
+  }))
+  .orderBy((q) => q.typical.desc)
+```
+
+Any number of metrics in one request, several over the same field included. Each row carries all of them, so one request can feed two panels. A metric key may not reuse a group key, and two metrics may not ask for the same value. `avg` comes back rounded to two decimals.
+
+### Two group columns, which is the ceiling
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ month: q.closedAt.byMonth, region: q.region }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => [q.month.asc, q.revenue.desc])
+// data: Array<{ month: string | null; region: string | null; revenue: number | null }>
+```
+
+The result is long format, one row per month and region pair, so the app pivots into one array per series before charting. **A chart groups by at most two columns**, each a different field, and a field cannot be grouped and aggregated in the same chart. A third group column is a compile error.
+
+### Distinct values, for a filter control
+
+```ts
+const { data } = await ds.chart(sales).groupBy((q) => ({ region: q.region }))
+// data: Array<{ region: string | null }>
+```
+
+Skip `metrics` entirely and the rows hold the distinct group values, one each. This is the cheapest way to fill a dropdown from a real column.
+
+### A headline number
+
+```ts
+const { value } = await ds
+  .metric(sales, (q) => q.amount.sum)
+  .where((q) => q.status.is('paid'))
+// value: number | null
+```
+
+One aggregation, no grouping, one value. Whenever the answer is a single number, a stat tile or a count, reach for `ds.metric` rather than a one-row chart: there is nothing to group by and nothing to unpack out of `data`. The same measure handles apply, `q.$count` included:
+
+```ts
+const { value: open } = await ds.metric(sales, (q) => q.$count).where((q) => q.status.is('open'))
+// open: number
+```
+
+### Top N
+
+```ts
+const { data } = await ds
+  .chart(sales)
+  .groupBy((q) => ({ rep: q.rep }))
+  .metrics((q) => ({ revenue: q.amount.sum }))
+  .orderBy((q) => q.revenue.desc)
+
+const top5 = data.slice(0, 5)
+```
+
+A chart has no row limit to set, so a top-N is a client-side slice of the fully sorted rows.
+
+### A dashboard load
+
+```ts
+const loadDashboard = createServerFn().handler(async () => {
+  const [mtd, series] = await Promise.all([
+    ds
+      .metric(sales, (q) => q.amount.sum)
+      .where((q) => q.$and(q.status.is('paid'), q.closedAt.gte('2026-09-01'))),
+    ds
+      .chart(sales)
+      .groupBy((q) => ({ month: q.closedAt.byMonth }))
+      .metrics((q) => ({ revenue: q.amount.sum }))
+      .where((q) => q.status.is('paid'))
+      .orderBy((q) => q.month.asc),
+  ])
+  return { mtd: mtd.value, series: series.data }
+})
+```
+
+Each tile and panel is its own request, fired in parallel from one handler.
+
+## Order of calls
+
+`groupBy` comes first and exactly once; a chart cannot be awaited before it. `metrics` follows, at most once, or not at all for distinct values. `where` can be chained anywhere, repeatedly, and calling it more than once ands the filters together. `orderBy` sorts by the chart's own keys, group and metric alike, and only sees the keys declared so far, so call it last.
+
+## References
+
+- [references/aggregations.md](./references/aggregations.md): every bucket interval and its value type, and which aggregations each kind of field offers. Load it when choosing a bucket or when a field does not offer the aggregation you expected.
+- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the query a chart aggregates over. Load it when the declaration itself is what you are writing.
+- [record-queries/references/filters-and-sorting.md](../record-queries/references/filters-and-sorting.md): every filter operator by field type. Load it when the `where` you need is not shown here, or when a filter is rejected.

package/skills/softr-sdk/charts-and-metrics/references/aggregations.md

@@ -0,0 +1,76 @@
+# Buckets, aggregations and chart rules
+
+## Group columns
+
+A bare handle in `groupBy` groups by the field's value. What the column reads back as depends on the field's declared type:
+
+| Field type | Column value |
+| --- | --- |
+| SELECT, LINKED_RECORD, CREATED_BY, UPDATED_BY | `string \| null`, the display label, not the id |
+| Text fields | `string \| null` |
+| Number fields | `number \| null` |
+| CHECKBOX | `boolean \| null` |
+| DATE, DATETIME, CREATED_AT, UPDATED_AT | `string \| null`, or a bucket leaf below |
+| Multi-value (`SELECT[]` and friends), ATTACHMENT, DATE_RANGE | Cannot group |
+
+`null` is always the bucket of records with no value. A multi-value field can neither group nor aggregate: exploding it would count each record once per value and inflate every metric.
+
+## Date buckets
+
+Leaves on every date and datetime handle, `q.closedAt.byMonth` style:
+
+| Leaf | Groups by | Column value |
+| --- | --- | --- |
+| `.byDay` | Calendar day | `"2025-06-14"` |
+| `.byWeek` | Calendar week | The ISO date of the week's Monday |
+| `.byMonth` | Calendar month | `"2025-06"` |
+| `.byQuarter` | Calendar quarter | `"Q2 2025"`, a display string, not a parseable date |
+| `.byYear` | Calendar year | The year as a `number` |
+| `.byHourOfDay` | Hour of day | `0`–`23`. DATETIME fields only, not DATE |
+| `.byDayOfWeek` | Day of week | `1`–`7`, 1 is Sunday |
+| `.byMonthOfYear` | Month of year | `1`–`12` |
+| `.byQuarterOfYear` | Quarter of year | `1`–`4` |
+
+Every bucket value is `| null` for the empty bucket. The cyclic buckets come back as bare numbers; the app supplies the labels.
+
+`byWeek` is Monday-based while `byDayOfWeek` counts from Sunday, so the two cannot be lined up by arithmetic alone.
+
+## Aggregations
+
+Handles in `metrics`, and the second argument of `ds.metric`:
+
+| Handle | Available on | Comes back as |
+| --- | --- | --- |
+| `.sum` | Number fields | `number \| null` |
+| `.avg` | Number fields | `number \| null`, rounded to two decimals |
+| `.min` / `.max` | Number fields | `number \| null` |
+| `.min` / `.max` | Date fields | `string \| null`, as `"2025-06-14"` |
+| `.distinct` | Number and date fields | `number`, the count of distinct values |
+| `q.$count` | No field: counts rows | `number` |
+
+Number fields: NUMBER, PERCENT, CURRENCY, PROGRESS, RATING, DURATION, COUNT, AUTONUMBER. Date fields: DATE, DATETIME, CREATED_AT, UPDATED_AT.
+
+Every other field offers no aggregations at all. `q.$count` is the only measure that touches no field, so a text or choice column is measured by grouping on it and counting rows.
+
+`sum`, `avg`, `min` and `max` are `null` for a group with no values. `$count` and `distinct` are plain `number`.
+
+## Rules
+
+- `groupBy` takes one or two columns, is required, and is called once. A third column, and a chart with no group columns, are compile errors.
+- Each group column is a different field, and a field cannot be grouped and aggregated in the same chart.
+- `metrics` is optional and called at most once. A metric key may not reuse a group key, and two metrics may not ask for the same aggregation of the same field.
+- `orderBy` names the chart's own keys, group and metric alike. Call it last: it only sees keys already declared.
+- Left unsorted, rows come back by the first bucket column ascending; with no bucket, by the first metric descending; with neither, by the first group ascending.
+- There is no row limit. A top-N is a client-side `slice` of the sorted rows.
+
+## Errors
+
+| Message | Cause |
+| --- | --- |
+| `a chart needs at least one column to group by` | Awaiting a chart whose `groupBy` produced no columns |
+| `a chart may group by at most two columns` | Three or more group columns |
+| `a chart may group by a field only once` | The same field twice in `groupBy` |
+| `a field cannot be grouped and aggregated in one chart` | One field in both `groupBy` and `metrics` |
+| `two metrics ask for the same value` | The same aggregation of the same field under two keys |
+| `"..." is not a column of this chart` | An `orderBy` key that is neither a group nor a metric key |
+| `a chart column must come from the callback a chart hands you` | A hand-built object where a handle belongs |

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.29
 ---
 
 **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.
@@ -69,7 +69,7 @@ A `guard()` in `beforeLoad` guarantees a visitor at runtime, but it does not cha
 import { createServerFn } from '@tanstack/react-start'
 
 // The datasource id from the table's registration on the application — not the table id.
-const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93'
+const INVOICES = '00000000-0000-0000-0000-000000000001'
 
 const getMyInvoices = createServerFn().handler(async ({ context }) => {
   if (!context.user) throw new Error('Not signed in')
@@ -88,7 +88,7 @@ const getMyInvoices = createServerFn().handler(async ({ context }) => {
 ```tsx
 import { usePermissions } from '@softr/sdk'
 
-const INVOICES = 'e4b7c2a1-9d3f-4e68-b05a-7f1c6d2e8a93' // the registered datasource's id
+const INVOICES = '00000000-0000-0000-0000-000000000001' // the registered datasource's id
 
 function NewInvoiceButton() {
   const { create } = usePermissions(INVOICES)
@@ -107,8 +107,8 @@ Pass an id the visitor's session has no entry for and it throws while rendering,
 declare module '@softr/sdk' {
   interface SoftrUserGroups {
     ids:
-      | 'b1f2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d'
-      | 'f9e8d7c6-5b4a-4938-8271-605f4e3d2c1b'
+      | '00000000-0000-0000-0000-00000000000a'
+      | '00000000-0000-0000-0000-00000000000b'
   }
 }
 export {}
@@ -119,5 +119,5 @@ 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
-- [reading-records/SKILL.md](../reading-records/SKILL.md): filtering a query by the visitor, and who really authorizes the read
+- [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/integrations/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: integrations
 description: >-
-  Call a third-party service connected to the app as an integration: integration.fetch
-  from @softr/sdk/server, reading the datasource id and integration type from the
-  "Attached data sources" prompt section, looking up the base URL from the reference
-  table by integrationType, and constructing the full API URL from base URL plus the
-  path and query params the model knows from training. Check res.ok before res.json().
+  Call a third-party service connected to the app as an integration:
+  integration.fetch from @softr/sdk/server, reading the datasource id and
+  integration type from the "Attached data sources" prompt section, looking up
+  the base URL from the reference table by integrationType, and constructing the
+  full API URL from base URL plus the path and query params the model knows from
+  training. Check res.ok before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.29
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -33,7 +34,7 @@ When the user attaches integrations to the chat, they appear in the `## Attached
 - "Gmail" — database `<databaseId>`, integration `<integrationId>`, type `GMAIL`
 ```
 
-Use `databaseId` as the first argument to `integration.fetch`. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL by appending the path and query parameters your training knows for that API.
+Use `databaseId` as the first argument to `integration.fetch` — that is the `database` coordinate, not the `integration` one. The `integration` value is the OAuth connection identifier; do not pass it to `integration.fetch`. Use `integrationType` (e.g. `GMAIL`) to look up the base URL from the reference table below — then construct the full URL by appending the path and query parameters your training knows for that API.
 
 ## Core pattern
 
@@ -49,7 +50,7 @@ const getCalendarEvents = createServerFn().handler(async () => {
 })
 ```
 
-The id (`25d60213-…`) is the `databaseId` from the attached data sources section. The base URL (`https://www.googleapis.com`) is looked up from the reference table below by matching `integrationType` (`GOOGLE_CALENDAR`). The path and query params come from your knowledge of the Google Calendar REST API.
+The id (`25d60213-…`) is the `databaseId` from the attached data sources section — the `database` coordinate, not the `integration` one. The base URL (`https://www.googleapis.com`) is looked up from the reference table below by matching `integrationType` (`GOOGLE_CALENDAR`). The path and query params come from your knowledge of the Google Calendar REST API.
 
 ## POST request
 

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

@@ -0,0 +1,149 @@
+---
+name: record-mutations
+description: >-
+  Create, update and delete records in a Softr datasource with defineMutation,
+  ds.create, ds.update and ds.delete: one declaration per operation, the data
+  payload keyed by your own field names, what each field type accepts on a
+  write, and the record each call returns. Use when submitting a form, saving an
+  edit or deleting a record, or when a write throws, writes the wrong field or
+  silently changes nothing. Writes only: fetching records is record-queries, and
+  aggregating them is charts-and-metrics.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.29
+---
+
+**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.
+
+# Writing records
+
+`ds` writes records to a Softr datasource, from the server only.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+import { defineMutation } from '@softr/sdk'
+import { ds } from '@softr/sdk/server'
+```
+
+A write's input arrives from the client, so validate it. Pass a zod schema straight to `.validator`; Start accepts it and types `data` from it.
+
+## Declare the write
+
+A mutation declares exactly one operation, and each of the three needs its own declaration. One datasource carries as many mutations as the app needs, alongside its queries. A create mutation only works with `ds.create`; hand it to `ds.update` and the call throws `action "createProject" is declared as create, not update`.
+
+```ts
+const createProject = defineMutation({
+  id: 'createProject',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  operation: 'create',
+  fields: {
+    name: 'fZk3Qm9pLw2Xa1',    // SINGLE_LINE_TEXT
+    status: 'Ru7bVx2cNq0Ed9',  // SELECT, choice ids 'draft' | 'active' | 'archived'
+    dueDate: 'Xp2dLh6vKz9Fa3', // DATETIME
+  },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+```
+
+The declaration follows the same rules as a read, spelled out in [record-queries](../record-queries/SKILL.md): `id` reads like a name and is unique across the app, queries counted alongside mutations; `datasource` is the opaque UUID from the table's registration, never derived from its name; the keys of `fields` are names you choose and the values are opaque field ids; `permission` declares who may run the mutation, from the same three choices, and the SDK enforces it; and the object is written inline, because passing it through a variable or a spread widens the field ids and the types stop checking.
+
+The mutation's `fields` bound the write: `data` can only name them, and the returned record only carries them. A delete mutation declares no `fields`, and giving it some is a type error.
+
+## Core Patterns
+
+### Create a record
+
+```ts
+const NewProject = z.object({ name: z.string(), dueDate: z.string() })
+
+const addProject = createServerFn({ method: 'POST' })
+  .validator(NewProject)
+  .handler(async ({ data }) =>
+    ds.create(createProject, {
+      data: { name: data.name, dueDate: data.dueDate, status: { id: 'draft' } },
+    }),
+  )
+```
+
+Returns the created record as `{ id, fields }`, with `fields` keyed by the mutation's names and holding the same value shapes a read returns. Every key in `data` is optional. A field left out, or written as `null`, gets the datasource's default.
+
+### Update a record
+
+```ts
+const updateProject = defineMutation({
+  id: 'updateProject',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  operation: 'update',
+  fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const archiveProject = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ data }) =>
+    ds.update(updateProject, { id: data.id, data: { status: { id: 'archived' } } }),
+  )
+```
+
+The record id is its own option; keep it out of `data`. An empty `id` throws.
+
+`update` writes the keys in `data` and leaves every other field alone, so a field you leave out is a field you are not writing. On an update, `null` clears the field, where on a create it reached the default. Returns the updated record.
+
+### Delete a record
+
+```ts
+const deleteProject = defineMutation({
+  id: 'deleteProject',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  operation: 'delete',
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const removeProject = createServerFn({ method: 'POST' })
+  .validator(z.object({ id: z.string() }))
+  .handler(async ({ data }) => {
+    await ds.delete(deleteProject, { id: data.id })
+  })
+```
+
+Resolves to nothing. A record that cannot be deleted throws.
+
+### 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.
+
+```ts
+const projectDetail = defineQuery({
+  id: 'projectDetail',
+  datasource: '00000000-0000-0000-0000-000000000000',
+  fields: { status: 'Ru7bVx2cNq0Ed9', dueDate: 'Xp2dLh6vKz9Fa3' },
+  permission: { userGroup: 'LOGGED_IN_USERS' },
+})
+
+const project = await ds.get(projectDetail, { id })
+await ds.update(updateProject, {
+  id,
+  data: { status: { id: project.fields.status.id } },
+})
+```
+
+A read answers a SELECT as `{ id, label }` and a write takes `{ id }`, so pass the id through rather than the whole value.
+
+### What a write accepts
+
+Each key of `data` accepts exactly what its field takes (see [record-queries](../record-queries/SKILL.md#typing)):
+
+- SELECT and LINKED_RECORD take `{ id }`. Not a bare string, and not the `{ id, label }` a read returns; the label is display data and a write does not accept it. A generated SELECT narrows the id to the field's own choices.
+- CHECKBOX takes a boolean. Dates take ISO strings, never `Date` instances.
+- ATTACHMENT takes `{ url }`, optionally with `filename`, `id` and `type`.
+- A multi-entry field takes an array of the value.
+
+## References
+
+- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the read half of an edit form, and the codegen the write types come from. Load it alongside this skill for any screen that shows a record before changing it.
+- [record-queries/references/field-types.md](../record-queries/references/field-types.md): the value shape every field reads back as. Load it when you are unsure what a field accepts.
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context`