@softr/sdk 0.0.19 → 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.19",
+  "version": "0.0.20",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.19
+  library_version: 0.0.20
 ---
 
 # Softr SDK core
@@ -123,4 +123,4 @@ type User = {
 
 ## Version
 
-Targets `@softr/sdk` v0.0.19.
+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.19
+  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.19
+  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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.19
+  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/reading-records/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.19
+  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.19
+  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.