@cana-ai/sdk 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,165 @@
+# @cana-ai/sdk
+
+OpenAI-compatible client for Cana **Apps** — programmatic access to your agent
+with **HMAC auth**, **server-hosted MCP** federation, **streaming**, and
+**typed structured output**.
+
+Point any OpenAI SDK at a Cana App and it just works. Or use this client to get
+auto MCP dispatch, Web-Crypto signing, and Zod typing for free.
+
+```bash
+npm install @cana-ai/sdk
+# or just drop a script tag — see below
+```
+
+---
+
+## Quick start (Node / Bun / Deno / Workers)
+
+```ts
+import { CanaClient } from "@cana-ai/sdk/openai";
+
+const client = new CanaClient({
+  appId:      "app_…",
+  signingKey: process.env.CANA_APP_KEY!,   // csk_live_…
+  apiBase:    "https://cana.build",        // optional
+});
+
+const c = await client.chat.completions.create({
+  model:    "openai/gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+});
+console.log(c.choices[0].message.content);
+```
+
+Model strings are `<provider>/<model-id>` — `openai/gpt-4o`,
+`anthropic/claude-haiku-4-5-20251001`, `moonshot/moonshot-v1-32k`,
+`google/gemini-2.5-pro`, etc. The proxy resolves the right credentials from the
+App owner's provider configs.
+
+## Streaming
+
+```ts
+const stream = await client.chat.completions.create({
+  model:    "openai/gpt-4o",
+  messages: [{ role: "user", content: "Write a haiku about TCP." }],
+  stream:   true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta.content ?? "");
+}
+```
+
+Chunks are verbatim OpenAI Server-Sent-Events shapes, with `[DONE]`
+auto-terminated.
+
+## Typed structured output (Zod)
+
+```ts
+import { z } from "zod";
+
+const Person = z.object({ name: z.string(), age: z.number() });
+
+const { result } = await client.chat.completions.generate({
+  model:    "openai/gpt-4o",
+  messages: [{ role: "user", content: "Pick a friendly person" }],
+  schema:   Person,
+});
+
+result.name; // string
+result.age;  // number
+```
+
+Uses OpenAI's strict `response_format: { type: "json_schema" }` under the hood.
+Optional peer dep: `zod-to-json-schema` (auto-converts your schema).
+
+## MCP federation — discover + auto-dispatch
+
+Server-hosted MCP connectors are exposed via two helper endpoints; the SDK
+drives the loop for you:
+
+```ts
+const r = await client.runWithMcp({
+  model:    "anthropic/claude-haiku-4-5-20251001",
+  messages: [{ role: "user", content: "Find last week's PRs in cana-web" }],
+  mcp:      ["github", "search"],   // connector names attached to your App
+  maxRounds: 5,
+});
+
+console.log(r.message.content);
+```
+
+Or do it by hand:
+
+```ts
+const { tools } = await client.mcp.tools(["github"]);
+// `tools` is in OpenAI tool format → pass to chat.completions.create
+// When you get a tool_call back named `mcp__github__<tool>`, dispatch:
+const out = await client.mcp.execute({ name: "mcp__github__list_prs", arguments: { repo: "…" } });
+```
+
+Tool names follow the `mcp__<connector>__<tool>` convention; everything else
+is treated as a client-side tool you handle yourself.
+
+## Browser — `<script>` tag
+
+A pre-built IIFE bundle is hosted at the App owner's Cana URL:
+
+```html
+<script src="https://cana.build/sdk/openai.js"></script>
+<script>
+  const client = new CanaOpenAI.CanaClient({
+    appId:      "app_…",
+    signingKey: "csk_live_…",  // server-issued, scoped to one App
+  });
+  client.chat.completions.create({
+    model:    "openai/gpt-4o",
+    messages: [{ role: "user", content: "Hello" }],
+  }).then(c => console.log(c.choices[0].message.content));
+</script>
+```
+
+> Browser-direct mode leaks the signing key to anyone who views source. Use it
+> for prototypes; in prod, proxy through your own server.
+
+## Plain OpenAI SDK
+
+Any OpenAI client can hit the proxy directly if it can sign requests. The
+URL shape is `https://<base>/api/v1/apps/<appId>/openai`. You'll need a fetch
+hook that adds:
+
+```
+X-Cana-App-Signature: t=<unix-ms>,v1=<hmac-sha256-hex>
+```
+
+over the canonical string `${unixMs}.${rawBody}`. The Node/browser examples
+above do this for you.
+
+## Errors
+
+All non-2xx responses throw `CanaApiError` with a typed `.code` and `.status`.
+Common codes: `signature_invalid`, `signature_expired`, `app_paused`,
+`rate_limited`, `billing_exceeded`, `unknown_provider`, `model_not_found`,
+`mcp_connector_unknown`, `upstream_error`.
+
+```ts
+import { CanaApiError } from "@cana-ai/sdk/openai";
+
+try {
+  await client.chat.completions.create({ … });
+} catch (e) {
+  if (e instanceof CanaApiError && e.code === "rate_limited") {
+    // back off, check `Retry-After`
+  } else throw e;
+}
+```
+
+## Web Crypto only
+
+Zero `node:crypto` import — works on Node 18+, Bun, Deno, Cloudflare Workers,
+and modern browsers out of the box.
+
+## License
+
+MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cana-ai/sdk",
-  "version": "0.2.0",
-  "description": "Cana Apps SDK — programmatic access for embedders who drive their own UI.",
+  "version": "0.2.1",
+  "description": "OpenAI-compatible client for Cana Apps — HMAC auth, server-hosted MCP federation, streaming, typed structured output. Web Crypto only (Node 18+, Bun, Deno, Workers, browsers).",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,7 +16,23 @@
       "import": "./dist/openai/index.js"
     }
   },
-  "files": ["dist"],
+  "files": ["dist", "README.md"],
+  "keywords": [
+    "cana",
+    "openai",
+    "openai-compatible",
+    "llm",
+    "agent",
+    "mcp",
+    "model-context-protocol",
+    "structured-output",
+    "hmac",
+    "ai-sdk",
+    "anthropic",
+    "moonshot"
+  ],
+  "license": "MIT",
+  "homepage": "https://cana.build",
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "dev": "tsc -p tsconfig.json --watch",