@softr/sdk 0.0.18 → 0.0.20

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { q } from "./core/query.js";
 import { SoftrUserGroupId, SoftrUserGroups, User } from "./auth/user.js";
-import { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, GetOptions, ListOptions, ListResult, MetricOptions, MetricResult, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions } from "./types.js";
+import { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions } from "./types.js";
 import { Permissions } from "./auth/permissions.js";
 import { SoftrContext } from "./auth/context.js";
 import { AccessBehaviour, AccessCheck, AccessError, AccessReason, RouteVisibility, VisibilityHandle, defineVisibility, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
-export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourcePermissions, type GetOptions, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type Permissions, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };
+export { type AccessBehaviour, type AccessCheck, type AccessError, type AccessReason, type AggregationFunction, type ChartDataOptions, type ChartDataResult, type CreateOptions, type DatasourcePermissions, type GetOptions, type JsonValue, type ListOptions, type ListResult, type MetricOptions, type MetricResult, type Permissions, type RouteVisibility, type SoftrContext, type SoftrMe, type SoftrPermissions, type SoftrRecord, type SoftrUser, type SoftrUserGroupId, type SoftrUserGroups, type UpdateOptions, type User, type VisibilityHandle, defineVisibility, getSoftrContext, initialSoftrContext, isAccessError, isAlreadySignedInError, isForbiddenError, isUnauthenticatedError, q, softrAuthMiddleware, useCurrentUser, usePermissions, useUserTimezone };

package/dist/types.d.ts

@@ -53,16 +53,19 @@ interface ListOptions {
   /** Override the timezone for this request. */
   timeZone?: string;
 }
-interface ListResult<T = SoftrRecord> {
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+interface SoftrRecord<T extends Record<string, JsonValue> = Record<string, JsonValue>> {
+  id: string;
+  fields: T;
+}
+interface ListResult<T extends SoftrRecord = SoftrRecord> {
   records: T[];
   total: number;
   /** Offset to pass as `offset` in the next call, or `null` when there are no more pages. */
   nextOffset: number | null;
 }
-interface SoftrRecord {
-  id: string;
-  fields: Record<string, unknown>;
-}
 type AggregationFunction = 'SUM' | 'AVG' | 'MAX' | 'MIN' | 'COUNT' | 'DISTINCT';
 interface MetricOptions {
   select?: Record<string, string>;
@@ -91,7 +94,7 @@ interface ChartDataOptions {
   timeZone?: string;
 }
 interface ChartDataResult {
-  data: Record<string, unknown>[];
+  data: Record<string, JsonValue>[];
   executionTimestamp: Date;
 }
 interface CreateOptions {
@@ -100,7 +103,7 @@ interface CreateOptions {
    * When provided, `data` keys are interpreted as aliases.
    */
   select?: Record<string, string>;
-  data: Record<string, unknown>;
+  data: Record<string, JsonValue>;
 }
 interface UpdateOptions {
   id: string;
@@ -109,7 +112,7 @@ interface UpdateOptions {
    * When provided, `data` keys are interpreted as aliases.
    */
   select?: Record<string, string>;
-  data: Record<string, unknown>;
+  data: Record<string, JsonValue>;
 }
 //#endregion
-export { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, GetOptions, ListOptions, ListResult, MetricOptions, MetricResult, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions };
+export { AggregationFunction, ChartDataOptions, ChartDataResult, CreateOptions, DatasourcePermissions, GetOptions, JsonValue, ListOptions, ListResult, MetricOptions, MetricResult, SoftrMe, SoftrPermissions, SoftrRecord, SoftrUser, UpdateOptions };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -5,12 +5,12 @@ 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, or auth. Load this before any
-  other Softr SDK skill.
+  visibility, the current user, reading records, writing records, or auth. Load
+  this before any other Softr SDK skill.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.17
+  library_version: 0.0.20
 ---
 
 # Softr SDK core
@@ -20,6 +20,7 @@ metadata:
 > **CRITICAL**: The SDK is split across four entrypoints and the split is enforced. `ds` and `auth` exist only on `@softr/sdk/server` and only run inside a `createServerFn` handler. Importing them anywhere else fails the build.
 > **CRITICAL**: Every route file must declare its audience with `defineVisibility`. There is no default and nothing is inherited from a sibling. A route file without a declaration is a lint error.
 > **CRITICAL**: The app is already wired. `src/start.ts`, `src/router.tsx` and `src/routes/__root.tsx` register the middleware and resolve the session. Do not add a second registration.
+> **CRITICAL**: `ds.metric`, `ds.chartData`, `workflow.trigger` and `integration.fetch` are exploratory. They exist on the entrypoints below and they typecheck, but their endpoints are not final. Do not build a feature on any of them. Tell the user the capability is not ready and ask how they want to proceed.
 
 Load this skill, then load **one** sub-skill for the task at hand. Add a second only when the work genuinely crosses that boundary. A page that lists records behind a group restriction needs `reading-records` plus `routes-and-visibility`.
 
@@ -39,6 +40,7 @@ Load this skill, then load **one** sub-skill for the task at hand. Add a second
 | 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) |
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 
 ## Quick Decision Tree
@@ -53,6 +55,9 @@ Showing the visitor's name, or hiding UI they cannot use?
 Putting records on a page, in a table, a list or a detail view?
   load softr-sdk/reading-records
 
+Submitting a form, editing a record, or deleting one?
+  load softr-sdk/data-mutations
+
 Wiring a login, signup, or sign-out?
   load softr-sdk/auth
 
@@ -118,4 +123,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.17.
+Targets `@softr/sdk` v0.0.20.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.17
+  library_version: 0.0.20
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.17
+  library_version: 0.0.20
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.

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

@@ -0,0 +1,115 @@
+---
+name: data-mutations
+description: >-
+  Create, update and delete records in a Softr datasource from inside a server
+  function: ds.create, ds.update and ds.delete from @softr/sdk/server, the data
+  payload key, select field aliasing on the way in and out, and what each call
+  returns or throws. Writes only. Reads, metrics and chart data are not covered.
+metadata:
+  type: sub-skill
+  library: softr-sdk
+  library_version: 0.0.20
+---
+
+This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
+
+# Writing records
+
+`ds` writes records to a Softr datasource. Like every read, a write lives on `@softr/sdk/server` and runs on the server only, so it happens inside a `createServerFn` handler and never in a component.
+
+## Setup
+
+```ts
+import { createServerFn } from '@tanstack/react-start'
+import { z } from 'zod'
+import { ds } from '@softr/sdk/server'
+import { q } from '@softr/sdk'
+```
+
+Pass a zod schema straight to `.validator`. Start accepts it and types `data` from it.
+
+## Core Patterns
+
+### Create a record
+
+```ts
+const NewProject = z.object({ name: z.string(), status: z.string() })
+
+const createProject = createServerFn({ method: 'POST' })
+  .validator(NewProject)
+  .handler(async ({ data }) =>
+    ds.create('ds_projects', {
+      data,
+      select: q.select({ name: 'fld_name', status: 'fld_status' }),
+    }),
+  )
+```
+
+Returns the created record as `{ id, fields }`.
+
+**The payload key is `data`, not `fields`.** A record answers with `fields`, which is where the confusion comes from, but the option you pass is `data`. `CreateOptions` requires it, so a call keyed by `fields` does not type-check.
+
+**`data` speaks whatever `select` maps.** The keys above are the schema's own names because `select` maps them to field ids, which is why the validated input can go straight through. With no `select`, `data` has to be keyed by raw field ids instead.
+
+### Update a record
+
+```ts
+const Rename = z.object({ id: z.string(), name: z.string() })
+
+const renameProject = createServerFn({ method: 'POST' })
+  .validator(Rename)
+  .handler(async ({ data }) =>
+    ds.update('ds_projects', {
+      id: data.id,
+      data: { name: data.name },
+      select: q.select({ name: 'fld_name' }),
+    }),
+  )
+```
+
+The record id is its own option, so keep it out of `data`.
+
+Returns the updated record. `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. An empty `id` throws.
+
+### Delete a record
+
+```ts
+const RecordId = z.object({ id: z.string() })
+
+const deleteProject = createServerFn({ method: 'POST' })
+  .validator(RecordId)
+  .handler(async ({ data }) => ds.delete('ds_projects', data.id))
+```
+
+**`delete` takes the record id as a positional argument**, unlike `create` and `update`, which take an options object. It resolves to nothing.
+
+### Naming fields with `select`
+
+`select` works in both directions on a write. Going in, it turns your names into Softr field ids. Coming back, it turns the returned field ids into your names. Without it, `data` has to be keyed by raw field ids and the returned record answers with them too.
+
+The map has to cover every key in `data`. A key it does not map is not translated, so the write does not land on the field you meant.
+
+### Writing on behalf of the visitor
+
+Stamping a record with who created it, or scoping an update to the person making it, reads the visitor off the handler's `context`. That is [current-user](../current-user/SKILL.md)'s subject, including the null guest and how Start types it. Load that skill rather than looking for it here.
+
+## Failure Modes
+
+**A write that sends `fields`.** The option is `data`. Only typecheck catches this, so it survives any run that does not typecheck.
+
+**A key missing from `select`.** The key is not translated, so the field it was meant for is not the field written. Check the map covers every key rather than trusting the call to complain.
+
+**A write with no `select` and your own key names.** Without a map, `data` must be keyed by raw field ids.
+
+**Passing an options object to `delete`.** The second argument is the id itself. `delete` throws when the record cannot be deleted.
+
+**Expecting `select` on a read-then-write round trip.** `ds.get` takes no `select`, so a record fetched by id answers with raw field ids. Load `reading-records` before pairing a read with a write.
+
+**A write outside a server function.** `ds` is server-only. Importing it into a component fails the build.
+
+**Reading the visitor from somewhere other than `context`.** There is nothing to import. See [current-user](../current-user/SKILL.md).
+
+## References
+
+- [reading-records/SKILL.md](../reading-records/SKILL.md): fetching the record a write is about to change
+- [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to stamp or scope a write

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.17
+  library_version: 0.0.20
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the client/server boundary.
@@ -29,7 +29,36 @@ import { q } from '@softr/sdk'
 
 `ds` is server-only and lives on `@softr/sdk/server`. `q` builds queries and nothing more, so it ships on the root entrypoint and can be imported anywhere.
 
-A record comes back as `{ id: string; fields: Record<string, unknown> }`.
+A record comes back as `{ id: string; fields: Record<string, unknown> }`. When you write a TypeScript type for the fields, the shape of each value depends on the Softr field type — see [references/field-types.md](./references/field-types.md) for the full mapping.
+
+## Typing record fields
+
+Declare a local type for the records you fetch using `SoftrRecord<Fields>`. Use the shapes from the field-types reference, not guesses from the field name. The most common mistake is treating SELECT and LINKED_RECORD fields as strings — they are objects:
+
+```ts
+import type { SoftrRecord } from '@softr/sdk'
+
+type Product = SoftrRecord<{
+  name: string                            // SINGLE_LINE_TEXT
+  price: number | null                    // CURRENCY
+  category: { id: string; label: string } // SELECT — not a string
+  supplier: { id: string; label: string } // LINKED_RECORD — not a string
+}>
+```
+
+`SoftrRecord<Fields>` is shorthand for `{ id: string; fields: Fields }` — the `Fields` type parameter constrains every value to `JsonValue`, so TypeScript rejects non-serializable types like `Date` objects.
+
+Cast at the `ds.list` call using the `ListResult` generic so the type flows through the loader automatically:
+
+```ts
+import type { ListResult, SoftrRecord } from '@softr/sdk'
+
+const fetchProducts = createServerFn().handler(() =>
+  ds.list('products', { select, limit: 100 }) as Promise<ListResult<Product>>
+)
+```
+
+`loaderData` is then already typed as `ListResult<Product>` — no second cast needed in the component. All the shapes in [references/field-types.md](./references/field-types.md) satisfy the `JsonValue` constraint.
 
 ## Core Patterns
 
@@ -130,6 +159,7 @@ A read the visitor is not allowed to make throws rather than coming back empty,
 
 ## References
 
+- [references/field-types.md](./references/field-types.md): TypeScript shape for every Softr field type
 - [references/query-builder.md](./references/query-builder.md): every `q` field type and operator
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor off `context` to scope a query
 - [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): deciding who sees the page the records land on

package/skills/softr-sdk/reading-records/references/field-types.md

@@ -0,0 +1,70 @@
+# Softr field types — TypeScript shapes
+
+When you write a TypeScript type for a record's fields, use these shapes. The field's **type** (shown in the datasource metadata or described by the user) determines the shape, not the field's name.
+
+```ts
+// Simple scalar types
+SINGLE_LINE_TEXT: string
+LONG_TEXT: string
+EMAIL: string
+PHONE: string
+URL: string
+ADDRESS: string
+LOCATION: string
+BUTTON: string
+RECORD_ID: string
+DATETIME: string       // ISO timestamp string
+DATE: string           // ISO date string
+TIME: string
+CREATED_AT: string
+UPDATED_AT: string
+CHECKBOX: string | boolean
+AUTONUMBER: number | null
+NUMBER: number | null
+PERCENT: number | null
+CURRENCY: number | null
+PROGRESS: number | null
+DURATION: number | null
+COUNT: number | null
+RATING: string | number | null
+FORMULA: string | number
+
+// Object types — these are NOT plain strings
+SELECT: { id: string; label: string }
+LINKED_RECORD: { id: string; label: string }
+
+DATE_RANGE: { from: string; to: string }
+
+ATTACHMENT: {
+  filename: string | null | undefined
+  id: string | null | undefined
+  type: string | null | undefined
+  url: string
+  thumbnails?: Array<{ size: 'small' | 'medium' | 'large'; url: string }>
+}
+
+USER: { avatarUrl: string | null; id: string; name: string; email: string }
+
+CREATED_BY: string | string[] | { avatarUrl: string | null; id: string; name: string; email: string }
+UPDATED_BY: string | string[] | { avatarUrl: string | null; id: string; name: string; email: string }
+
+// These depend on what the linked field/aggregation resolves to
+LOOKUP: unknown
+ROLLUP: unknown
+```
+
+## The non-obvious ones
+
+**SELECT and LINKED_RECORD** are the most commonly mistyped. They are never a plain string — always `{ id: string; label: string }`. To display the value, use `.label`. To filter or compare, use `.id`.
+
+```tsx
+// Correct
+<td>{record.fields.status?.label}</td>
+
+// Wrong — status is not a string
+<td>{record.fields.status}</td>
+```
+
+**CHECKBOX** can be either a string (`'true'` / `'false'`) or a boolean depending on the datasource. Type it as `string | boolean` and coerce when needed: `!!record.fields.active`.
+
+**CREATED_BY / UPDATED_BY** can be a plain id string, an array of ids, or a full user object. Narrow before using.

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.17
+  library_version: 0.0.20
 ---
 
 This skill builds on softr-sdk. Read it first for the entrypoints and the wiring that puts a visitor on route context.