@softr/sdk 0.0.27 → 0.0.28

package/dist/action.d.ts

@@ -31,84 +31,41 @@ type ActionPermission = {
  */
 interface SoftrDatasources {}
 type SoftrDatasourceId = keyof SoftrDatasources extends never ? string : keyof SoftrDatasources & string;
-/** The read type one datasource returns. */
 type ReadOf<TDatasource$1> = TDatasource$1 extends keyof SoftrDatasources ? SoftrDatasources[TDatasource$1] extends {
   read: infer TRecord;
 } ? TRecord : never : never;
-/**
- * The DSv2 type name one field declares, as codegen emitted it: `"NUMBER"`, `"SELECT[]"`.
- * `never` for a field no augmentation describes.
- */
 type FieldTypeOf<TDatasource$1, TFieldId> = TDatasource$1 extends keyof SoftrDatasources ? SoftrDatasources[TDatasource$1] extends {
   fieldTypes: infer TTypes;
 } ? TFieldId extends keyof TTypes ? TTypes[TFieldId] : never : never : never;
-/** The write type one datasource accepts for one operation. */
 type WriteOf<TDatasource$1, TOperation$1> = TDatasource$1 extends keyof SoftrDatasources ? TOperation$1 extends keyof SoftrDatasources[TDatasource$1] ? SoftrDatasources[TDatasource$1][TOperation$1] : never : never;
-/** The field ids a write may name. Any string, until {@link SoftrDatasources} is declared. */
 type FieldIdOf<TDatasource$1, TOperation$1> = keyof SoftrDatasources extends never ? string : keyof WriteOf<TDatasource$1, TOperation$1> & string;
-/**
- * The field ids a read may name. Any string, until {@link SoftrDatasources} is declared.
- *
- * A read constrains against the record type rather than a write type, because a read may
- * name a field no write can: a formula or a lookup is on the record and on neither.
- */
 type ReadFieldIdOf<TDatasource$1> = keyof SoftrDatasources extends never ? string : keyof ReadOf<TDatasource$1> & string;
-/**
- * What an action declares, as the type layer reads it. `permission` is absent because no
- * call site depends on it, and the build reads it off the value.
- */
 type ActionShape = {
   id: string;
   datasource: SoftrDatasourceId;
   operation: ActionOperation;
   fields?: Record<string, string>;
 };
-/** What a read declares. A read is the whole field list, so `fields` is not optional. */
 type ReadShape = ActionShape & {
   operation: "read";
   fields: Record<string, string>;
 };
-/**
- * What one action writes: its own aliases, each resolved to the value that field accepts.
- *
- * An alias renames the field, and a mapped type keeps a property's docstring only while it
- * keeps the key, so the prose that sits on the field in `softr-env.d.ts` does not reach the
- * call site. The type does.
- */
 type ActionData<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
   datasource: infer TDatasource;
   operation: infer TOperation;
   fields: infer TFields;
 } ? { [Alias in keyof TFields]?: WriteOf<TDatasource, TOperation>[TFields[Alias] & keyof WriteOf<TDatasource, TOperation>] } : Record<string, unknown>;
-/**
- * What a mutation reads back: the same aliases, resolved against the table's read type.
- *
- * A write returns the record it wrote, and the SDK aliases its fields on the way out, so a
- * field the action never declared is absent from the result as well as from the payload.
- *
- * Every alias the action does declare is present. An empty field reads as `null`, so nothing
- * here is optional.
- */
 type ActionRecord<TShape extends ActionShape> = keyof SoftrDatasources extends never ? Record<string, unknown> : TShape extends {
   datasource: infer TDatasource;
   fields: infer TFields;
 } ? { [Alias in keyof TFields]: ReadOf<TDatasource>[TFields[Alias] & keyof ReadOf<TDatasource>] } : Record<string, unknown>;
 declare const brand: unique symbol;
-/**
- * A handle to a declared action, and the only thing a mutation accepts. The brand keeps it
- * nominal, so an object literal of the same shape will not do and no mutation can be reached
- * without passing through a declaration the build reads.
- *
- * The brand carries the declaration itself, which is what lets a call site resolve what the
- * action writes without codegen having said anything about this action.
- */
 type Action<TShape extends ActionShape = ActionShape> = {
   type: "action";
   id: TShape["id"];
 } & {
   readonly [brand]: TShape;
 };
-/** What a write action declares. */
 type WriteDeclaration<TId extends string, TDatasource$1, TOperation$1, TFields$1> = {
   id: TId;
   datasource: TDatasource$1;
@@ -116,15 +73,12 @@ type WriteDeclaration<TId extends string, TDatasource$1, TOperation$1, TFields$1
   fields: TFields$1;
   permission: ActionPermission;
 };
-/** What a read action declares. */
 type ReadDeclaration<TId extends string, TDatasource$1, TFields$1> = {
   id: TId;
   datasource: TDatasource$1;
-  operation: "read";
   fields: TFields$1;
   permission: ActionPermission;
 };
-/** What a delete action declares. `fields?: never` so a stray one is rejected rather than ignored. */
 type DeleteDeclaration<TId extends string, TDatasource$1> = {
   id: TId;
   datasource: TDatasource$1;
@@ -132,28 +86,15 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
   fields?: never;
   permission: ActionPermission;
 };
-/** The whole declaration, which is what an action is at runtime and in the manifest. */
-
 /**
- * Declares a data operation: which datasource, which of the four operations, which fields
- * participate, and who may run it.
- *
- * One call per action, at module scope, with a literal: the build reads these declarations
- * to publish what the app may read and write.
+ * Declares a read: which datasource, which fields participate, and who may run it.
  *
- * The keys of `fields` are aliases the app chooses and the values are field ids of the
- * datasource the action names. The result, `data`, `where` and `orderBy` at the call site
- * are all keyed by those aliases, so nothing there restates what the action already says.
- *
- * A read fixes the table and the columns. It does not fix which rows: `where`, `orderBy` and
- * the paging arguments stay at the call site, because a list screen changes them as the user
- * types and a declaration cannot follow that.
+ * The argument must be a static object.
  *
  * @example
- * const publishedPosts = defineAction({
+ * const publishedPosts = defineQuery({
  *   id: "publishedPosts",
  *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
- *   operation: "read",
  *   fields: { title: "V1StGXR8", author: "Z7pQm4Kd", publishedAt: "Xp2dLh6v" },
  *   permission: { userGroup: "ALL_USERS" },
  * })
@@ -162,9 +103,21 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  *   .list(publishedPosts)
  *   .where((q) => q.publishedAt.lte(today))
  *   .orderBy((q) => q.publishedAt.desc)
+ */
+declare function defineQuery<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): Action<{
+  id: TId;
+  datasource: TDatasource$1;
+  operation: "read";
+  fields: TFields$1;
+}>;
+/**
+ * Declares a write: which datasource, whether it creates, updates or deletes, which fields
+ * participate, and who may run it.
+ *
+ * The argument must be a static object.
  *
  * @example
- * const closeOrderAction = defineAction({
+ * const closeOrder = defineMutation({
  *   id: "closeOrder",
  *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
  *   operation: "update",
@@ -172,24 +125,28 @@ type DeleteDeclaration<TId extends string, TDatasource$1> = {
  *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
  * })
  *
- * await ds.update(closeOrderAction, { id, data: { status: "closed" } })
+ * await ds.update(closeOrder, { id, data: { status: "closed" } })
+ *
+ * @example
+ * const removeOrder = defineMutation({
+ *   id: "removeOrder",
+ *   datasource: "8f14e45f-ceea-467a-9d0b-2c1a0e3b5d77",
+ *   operation: "delete",
+ *   permission: { userGroup: "LOGGED_IN_USERS", userGroupIds: ["grp_staff"] },
+ * })
+ *
+ * await ds.delete(removeOrder, { id })
  */
-declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TFields$1 extends Record<string, ReadFieldIdOf<TDatasource$1>>>(definition: ReadDeclaration<TId, TDatasource$1, TFields$1>): Action<{
-  id: TId;
-  datasource: TDatasource$1;
-  operation: "read";
-  fields: TFields$1;
-}>;
-declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): Action<{
+declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId, const TOperation$1 extends "create" | "update", const TFields$1 extends Record<string, FieldIdOf<TDatasource$1, TOperation$1>>>(definition: WriteDeclaration<TId, TDatasource$1, TOperation$1, TFields$1>): Action<{
   id: TId;
   datasource: TDatasource$1;
   operation: TOperation$1;
   fields: TFields$1;
 }>;
-declare function defineAction<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): Action<{
+declare function defineMutation<const TId extends string, const TDatasource$1 extends SoftrDatasourceId>(definition: DeleteDeclaration<TId, TDatasource$1>): Action<{
   id: TId;
   datasource: TDatasource$1;
   operation: "delete";
 }>;
 //#endregion
-export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineAction };
+export { Action, ActionData, ActionRecord, ActionShape, FieldTypeOf, ReadOf, ReadShape, SoftrDatasources, defineMutation, defineQuery };

package/dist/action.js

@@ -1,16 +1,17 @@
 //#region src/action.ts
-function defineAction(definition) {
+function defineQuery(definition) {
+	return {
+		type: "action",
+		...definition,
+		operation: "read"
+	};
+}
+function defineMutation(definition) {
 	return {
 		type: "action",
 		...definition
 	};
 }
-/**
-* True for anything {@link defineAction} produced, whatever its operation.
-*
-* Matched on `type` rather than with `instanceof`, so two copies of the SDK in one
-* dependency tree still recognise each other's actions.
-*/
 function isAction(value) {
 	if (typeof value !== "object" || value === null) return false;
 	const candidate = value;
@@ -18,4 +19,4 @@ function isAction(value) {
 }
 
 //#endregion
-export { defineAction, isAction };
+export { defineMutation, defineQuery, isAction };

package/dist/codegen/datasource-types.js

@@ -443,7 +443,7 @@ function nameOf(datasourceId, context) {
 }
 /**
 * Always quoted, even where an identifier would do. Find All References on a field id at a
-* `defineAction` call site matches string literals and quoted property names, so a bare key is
+* `defineQuery` call site matches string literals and quoted property names, so a bare key is
 * invisible to it and the id no longer navigates here.
 */
 function key(name) {

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.28";
 
 //#endregion
 export { version };

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.28
 ---
 
 # Softr SDK core

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.28
 ---
 
 **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/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.28
 ---
 
 **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.

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

@@ -8,7 +8,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.28
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `q` 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.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.28
 ---
 
 **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 +33,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 +49,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/reading-records/SKILL.md

@@ -5,12 +5,12 @@ description: >-
   ds.get from @softr/sdk/server, the q query builder (q.text, q.number,
   q.boolean, q.date, q.array, q.and, q.or, q.asc, q.desc), q.select field
   aliasing, filtering, sorting, the 20-record default and 100-record cap, and
-  nextOffset pagination. Reads only. Mutations, workflows, integrations, metrics
-  and chart data are not covered.
+  nextOffset pagination. Reads only. Mutations, workflows, integrations, and
+  chart/metric aggregations (ds.chart, ds.metric) are not covered.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.27
+  library_version: 0.0.28
 ---
 
 **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. `q` 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.

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.27
+  library_version: 0.0.28
 ---
 
 **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.