@softr/sdk 0.0.66 → 0.0.68-alpha.0

package/dist/core/integration.d.ts

@@ -7,6 +7,13 @@ interface IntegrationFetchInit {
   headers?: Record<string, string>;
   body?: string;
   signal?: AbortSignal;
+  /**
+   * Relay the vendor's answer as it is produced instead of waiting for all of it — for any endpoint
+   * that streams, such as an LLM completion requested with `"stream": true`. The returned `Response`
+   * body is then the vendor's own stream, readable chunk by chunk. A vendor that answers in one piece
+   * still works.
+   */
+  stream?: boolean;
 }
 declare function integrationCreateFetcher(action: IntegrationAction): (init?: IntegrationFetchInit) => Promise<Response>;
 declare const integration: {

package/dist/core/integration.js

@@ -3,15 +3,16 @@ import { readSessionToken } from "../auth/session.js";
 import { dsUrl, refererHeader } from "../datasource/record.js";
 
 //#region src/core/integration.ts
-async function integrationFetch(action, { params, query, headers = {}, body, signal } = {}) {
+const EVENT_STREAM = "text/event-stream";
+async function integrationFetch(action, { params, query, headers = {}, body, signal, stream = false } = {}) {
 	if (signal?.aborted) throw signal.reason ?? new DOMException("The operation was aborted.", "AbortError");
 	const payload = {
 		method: action.resource.method,
 		url: buildUrl(action.resource.url, params, query),
-		headers
+		headers: stream ? withAcceptEventStream(headers) : headers
 	};
 	if (body !== void 0) payload.body = body;
-	return fetch(`${dsUrl(action.id)}/proxy`, {
+	return fetch(`${dsUrl(action.id)}/${stream ? "proxy/stream" : "proxy"}`, {
 		method: "POST",
 		headers: {
 			"Content-Type": "application/json",
@@ -30,6 +31,12 @@ function buildUrl(template, params, query) {
 	if (query !== void 0 && Object.keys(query).length > 0) url += `?${new URLSearchParams(query).toString()}`;
 	return url;
 }
+function withAcceptEventStream(headers) {
+	return Object.keys(headers).some((name) => name.toLowerCase() === "accept") ? headers : {
+		...headers,
+		Accept: EVENT_STREAM
+	};
+}
 function integrationCreateFetcher(action) {
 	return (init) => integrationFetch(action, init);
 }

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start4 from "@tanstack/react-start";
+import * as _tanstack_react_start0 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -31,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start4.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

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

package/package.json

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

package/skills/softr-sdk/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.66
+  library_version: 0.0.68-alpha.0
 ---
 
 # Softr SDK core

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

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

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.66
+  library_version: 0.0.68-alpha.0
 ---
 
 **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.66
+  library_version: 0.0.68-alpha.0
 ---
 
 # The current user

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

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.66
+  library_version: 0.0.68-alpha.0
 ---
 
 # Dates, times and numbers

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

@@ -5,12 +5,12 @@ description: >-
   defineIntegration from @softr/sdk declares the action with its integrationId,
   the one HTTP method and endpoint url it allows, and permissions;
   integration.createFetcher from @softr/sdk/server binds it and returns a
-  fetcher function you call with optional params, query, headers, and body.
-  Check res.ok before res.json().
+  fetcher function you call with optional params, query, headers, body, and
+  stream for a vendor answer that arrives in pieces. Check res.ok before res.json().
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.66
+  library_version: 0.0.68-alpha.0
 ---
 
 **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.
@@ -127,6 +127,78 @@ const sendSlackMessage = createServerFn({ method: 'POST' })
 
 Do not add an `Authorization` key to `headers` — Softr injects the integration's credentials automatically.
 
+## Calling an AI model
+
+A button on one record that hands its fields to the model and shows the answer is the `ai-action` pattern:
+it carries this call and the model id, so write the call by hand only for another shape — a batch, a chat,
+a field the model fills on create. An AI integration is called like any other. For `ANTHROPIC_AI`, the action is `POST` on
+`https://api.anthropic.com/v1/messages`, the request carries the `anthropic-version` header and a body of
+`model`, `max_tokens`, `system` and `messages`, and the answer's text is in `content[].text`:
+
+```ts
+const askClaude = defineIntegration({
+  id: 'askClaude',
+  integrationId: '<the ANTHROPIC_AI integration id from the attached integrations>',
+  method: 'POST',
+  url: 'https://api.anthropic.com/v1/messages',
+  permissions: { userGroupTypes: ['LOGGED_IN_USERS'] },
+})
+
+const claude = integration.createFetcher(askClaude)
+const res = await claude({
+  headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
+  body: JSON.stringify({
+    model: 'claude-opus-5-5',
+    max_tokens: 1024,
+    system: 'You write a short briefing for a sales team. Use only the facts given.',
+    messages: [{ role: 'user', content: facts }],
+  }),
+})
+if (!res.ok) throw new Error(`AI error: ${res.status} ${await res.text()}`)
+const body = (await res.json()) as { content: Array<{ type: string; text?: string }> }
+const text = body.content.flatMap((block) => (block.type === 'text' && block.text ? [block.text] : [])).join('')
+```
+
+**Use the model id above as it is written here.** Model ids are not derivable: one spelled from memory
+(`claude-3-5-…`, `claude-sonnet-4-…`) names a model that no longer answers, and the error only shows up when
+the button is pressed. `claude-opus-5-5` is the current default; `claude-sonnet-5-5` is the cheaper one for a
+short summary.
+
+## Streaming a vendor answer
+
+Some vendor endpoints can send their answer in pieces while they produce it — LLM completions token by token, long exports, live event feeds. The fetcher relays such an answer as it arrives when you pass `stream: true`; the response body is then the vendor's own stream, unchanged.
+
+Decide per call, from the vendor's API docs for that endpoint, not from the integration type or the action:
+
+- The endpoint offers a streaming mode (a `stream: true` body flag, an `Accept: text/event-stream` variant, a chunked response the docs say to read incrementally). Ask the vendor for it in the request and pass `stream: true` to the fetcher.
+- The endpoint answers in one piece, which is the case for most REST calls. Call the fetcher without `stream`; the answer is buffered and `res.json()` works.
+
+Hand a streamed body to the browser as a `Response` from the server function and read it there. The example below streams a completion through the `askClaude` action declared above; the same shape applies to any vendor endpoint that streams.
+
+```ts
+const streamAnswer = createServerFn({ method: 'POST' })
+  .validator((data: { prompt: string }) => data)
+  .handler(async ({ data }) => {
+    const claude = integration.createFetcher(askClaude)
+    const res = await claude({
+      stream: true,
+      headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
+      body: JSON.stringify({
+        model: 'claude-opus-5-5',
+        max_tokens: 1024,
+        stream: true,
+        messages: [{ role: 'user', content: data.prompt }],
+      }),
+    })
+    if (!res.ok) throw new Error(`AI error: ${res.status} ${await res.text()}`)
+    return new Response(res.body, { headers: { 'Content-Type': 'text/event-stream' } })
+  })
+```
+
+On the client, call the server function's URL with `fetch` and read `response.body` with a `ReadableStream` reader; each chunk arrives in the vendor's own format, for an event stream one or more `event:`/`data:` frames. Use `stream: true` only together with a request that asks the vendor to stream: without it the vendor answers in one piece, which still works but gains nothing.
+
+`stream: true` is not available for REST_API integrations; those always answer in one piece.
+
 ## Base URLs by integration type
 
 Match the `integrationType` from the attached integrations section to find the base URL:
@@ -198,3 +270,5 @@ If the API the user needs is not in the table above, call it directly from a ser
 **Not checking `res.ok`.** The fetcher returns the proxied response as-is. A 4xx or 5xx from the third-party API is not thrown — call `res.ok` or `res.status` before calling `res.json()`.
 
 **Reusing one action for a different endpoint.** An action authorizes one `method` and one endpoint `url`. A different endpoint belongs to a different action — declare one for it, with its own audience.
+
+**Reading a streamed body with `res.json()`.** With `stream: true` the body is an event stream, not one JSON document. Return `res.body` in a `Response` or read it with a stream reader; `res.json()` waits for the end and then fails to parse.

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.66
+  library_version: 0.0.68-alpha.0
 ---
 
 **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.66
+  library_version: 0.0.68-alpha.0
 ---
 
 # Installing the app

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

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

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

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

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

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

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

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.66
+  library_version: 0.0.68-alpha.0
 ---
 
 **Boundary.** `defineVisibility`, 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.66
+  library_version: 0.0.68-alpha.0
 ---
 
 **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.