@blazingagents/sdk 0.43.0 → 0.43.1

package/README.md

@@ -10,19 +10,24 @@
   </p>
 </div>
 
-The official resource-style client SDK for the Blazing Agents `/v1` API. It
-requires Node.js 24 or newer.
+The official TypeScript SDK is a client for the Blazing Agents `/v1` API that
+your backend uses to manage Agents and run them for your users. It requires
+Node.js 24 or newer.
 
 ## Features
 
-- Typed clients for Agents, Workspaces, Skills, Providers, Prompts, Tasks,
-  Sessions, Artifacts, Slack and Telegram Chat Connections, usage, Tenant settings, and merchant monetization.
-- Stateful chat with explicit message batches, steer receipts, and one-call Tool approvals.
-- Stateless text or structured-object generation.
-- Public Zod contracts for validating API requests and responses.
-- Cursor pagination and binary transfers.
-- Request correlation and a typed, forward-compatible error model.
-- End-user scoped clients for user-owned resources and generation.
+- A typed method for every `/v1` operation an API key can call: Agents,
+  Skills, Sessions, Memories, Prompts, Tasks, Workspaces, Artifacts,
+  Providers, MCP Connections, Chat Connections, usage, spending limits, Tenant
+  settings, and merchant monetization.
+- Chat streams in the AI SDK UI message stream format, with steering, Tool
+  approvals, and backend functions that run in your process.
+- Text and structured-object generation.
+- End-user scoped clients through `forUser`.
+- Cursor pagination, uploads, and downloads.
+- Request IDs and typed errors.
+- `BlazingAgentsChatTransport` and `createChatRelay` connect AI SDK `useChat`
+  to your backend.
 
 ## Installation
 
@@ -30,19 +35,21 @@ requires Node.js 24 or newer.
 npm install @blazingagents/sdk ai@^7.0.84 zod@^4.5.4
 ```
 
-`ai` (`^7.0.84`) and `zod` (`^4.5.4`) are peer dependencies. The SDK
-re-exports AI SDK message types and Zod schemas, so consumers share these
-dependencies with the SDK.
+`ai` and `zod` are required peer dependencies. The SDK re-exports AI SDK
+message types and Zod schemas, so your app and the SDK share one copy of each.
 
 ## Quick start
 
-Create a Tenant API key in the Blazing Agents dashboard, then pass it to the
-client or read it from your server environment.
+Create a Full API key in the Blazing Agents dashboard and set
+`BLAZING_AGENTS_API_KEY` in your server environment. The key acts for your
+whole Tenant, so keep it on your backend and never send it to a browser.
 
 ```ts
 import { BlazingAgents } from "@blazingagents/sdk";
 
-const client = new BlazingAgents({ apiKey: "ba_..." });
+const client = new BlazingAgents({
+  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
+});
 
 const result = await client.completion({
   agentId: "ag_...",
@@ -52,32 +59,59 @@ const result = await client.completion({
 console.log(await result.text);
 ```
 
-For stateful chat, pass one user message or an ordered batch.
+Replace `ag_...` with an Agent ID from the dashboard.
 
-```ts
-const chat = await client.chat({
-  agentId: "ag_...",
-  messages: [
-    { id: "first", role: "user", parts: [{ type: "text", text: "Compare the plans." }] },
-    { id: "second", role: "user", parts: [{ type: "text", text: "Include annual pricing." }] },
-  ],
-});
+For requests from your users, scope the client to the user ID that your
+backend verified at sign-in, never to an ID from the request body. A scoped
+client reaches only that End-user's Agents, Sessions, and Workspace. An
+unscoped Agent shares one Workspace across all your users, so give each user
+an Agent of their own:
 
-const sessionId = await chat.sessionId;
-return chat.toResponse();
+```ts
+export async function createAgentForUser(userId: string): Promise<string> {
+  const agent = await client.forUser(userId).agents.create({
+    name: "Assistant",
+    providerId: "prv_...",
+    model: "openai/gpt-6-luna",
+  });
+  return agent.id;
+}
+
+export async function chatAsUser(
+  userId: string,
+  agentId: string,
+  text: string
+): Promise<Response> {
+  const chat = await client.forUser(userId).chat({
+    agentId,
+    message: {
+      id: crypto.randomUUID(),
+      role: "user",
+      parts: [{ type: "text", text }],
+    },
+  });
+  return chat.toResponse();
+}
 ```
 
-Keep API keys on the server. For browser chat applications, serve
-`createChatRelay` from your backend and use `BlazingAgentsChatTransport` with
-AI SDK `useChat`. The relay runs each request as the signed-in End-user with
-`client.forUser(userId)`.
+Call `createAgentForUser` once per user and store the Agent ID with the user.
+A scoped chat with an Agent created without the scope fails with `404`.
+`chatAsUser` returns the chat as a streaming `Response`. To chat from the
+browser with `useChat`, serve `createChatRelay` from your backend and use
+`BlazingAgentsChatTransport`. The relay scopes each request to the user that
+your `resolveContext` returns.
+
+## Examples
+
+The [examples repository](https://github.com/blazingagents/examples) has
+complete TypeScript and Python apps built on the Blazing Agents SDKs.
 
 ## Documentation
 
 Read the
 [TypeScript SDK documentation](https://docs.blazingagents.com/sdk/typescript)
-for authentication, resource guides, generation and streaming, React
-integration, error handling, and the complete API reference.
+for client setup, End-user scoping, chat and generation, a guide to each
+resource, and error handling.
 
 ## Development
 

package/dist/contracts/entities/memories.js

@@ -41,7 +41,7 @@ export const createMemoryBodySchema = z
     text: memoryTextSchema.describe("The note to remember, up to 10 KiB."),
     userId: userIdSchema
         .default("")
-        .describe("The end user this memory belongs to. Only turns that pass the same `userId` see it. Leave it out or send an empty string for a general memory that every turn of the agent sees. It cannot change after creation."),
+        .describe("The end user this memory belongs to. Turns for that end user see it. Leave it out or send an empty string for a general memory, which unscoped turns see; a turn made through `forUser` sees only its end user's memories. It cannot change after creation."),
 })
     .strict();
 export const updateMemoryBodySchema = z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blazingagents/sdk",
-  "version": "0.43.0",
+  "version": "0.43.1",
   "description": "TypeScript SDK for the Blazing Agents API",
   "homepage": "https://docs.blazingagents.com",
   "bugs": {