@softr/sdk 0.0.68-alpha.0 → 0.0.68-alpha.1

package/dist/package.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.68-alpha.0",
+  "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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  library_version: 0.0.68-alpha.1
 ---
 
 # Dates, times and numbers

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

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.68-alpha.0
+  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`:
 
@@ -168,10 +174,18 @@ short summary.
 
 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:
+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 |
 
-- 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.
+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.
 
@@ -271,4 +285,6 @@ If the API the user needs is not in the table above, call it directly from a ser
 
 **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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.68-alpha.0
+  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.