@softr/sdk 0.0.67 → 0.0.68-alpha.1

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.67";
+var version = "0.0.68-alpha.1";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.67",
+  "version": "0.0.68-alpha.1",
   "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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 # Softr SDK core
@@ -48,6 +48,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Trigger a Softr workflow | [workflows/SKILL.md](./workflows/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) |
+| Show an AI answer as it is written (a chat, an assistant, a live summary) | [integrations/SKILL.md](./integrations/SKILL.md), section "Streaming a vendor answer" |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
 | Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 | Show a date, a time or a number | [formatting/SKILL.md](./formatting/SKILL.md) |
@@ -82,6 +83,9 @@ Wiring a login, signup, or sign-out?
 Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)?
   load softr-sdk/integrations
 
+Showing an AI answer as it is written: a chat, an assistant, a summary that types itself out?
+  load softr-sdk/integrations and stream the call: its "Streaming a vendor answer" section
+
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 

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

@@ -19,7 +19,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 # 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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 # 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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.
@@ -129,9 +129,15 @@ Do not add an `Authorization` key to `headers` — Softr injects the integration
 
 ## Calling an AI model
 
+**Two shapes, decided by who reads the answer.** An answer the user reads as it is written — a chat, an
+assistant, a long summary shown on the page — streams: pass `stream: true` and relay the body, see
+[Streaming a vendor answer](#streaming-a-vendor-answer) below. An answer the server reads — JSON the page
+lays out, text saved to a field — is buffered: the call below, then `res.json()`. A chat is never buffered:
+the user would watch a blank panel until the last token.
+
 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
+it carries the buffered call and the model id, so write the call by hand only for another shape — a batch,
+a field the model fills on create, or a chat, which streams. 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`:
 
@@ -164,6 +170,49 @@ const text = body.content.flatMap((block) => (block.type === 'text' && block.tex
 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.
+
+Every connected LLM streams its completion. Ask the vendor for it in the request **and** pass `stream: true` to the fetcher; one without the other gains nothing:
+
+| integrationType | Endpoint | How to ask for the stream |
+|---|---|---|
+| ANTHROPIC_AI | `POST /v1/messages` | `"stream": true` in the body |
+| OPEN_AI | `POST /v1/chat/completions` or `POST /v1/responses` | `"stream": true` in the body |
+| GEMINI_AI | `POST /v1beta/models/{model}:streamGenerateContent` with `query: { alt: 'sse' }` | the endpoint itself; `generateContent` never streams, so the action's `url` must name the streaming one |
+| MISTRAL_AI | `POST /v1/chat/completions` | `"stream": true` in the body |
+| DEEP_SEEK_AI | `POST /chat/completions` | `"stream": true` in the body |
+| COHERE | `POST /v2/chat` | `"stream": true` in the body |
+
+For any other vendor, read that endpoint's docs: it streams when they offer a `stream` flag, an `Accept: text/event-stream` variant, or a chunked response to read incrementally. Most REST calls answer in one piece; call those without `stream` 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:
@@ -235,3 +284,7 @@ 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.
+
+**Buffering an answer the user watches being written.** A chat or assistant called without `stream: true` shows nothing until the last token arrives, and a long answer then hits the proxy's read timeout. Pass `stream: true`, ask the vendor to stream in the request, and return `res.body` in a `Response`.
+
+**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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 # 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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.67
+  library_version: 0.0.68-alpha.1
 ---
 
 **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.