@spicyapi/sdk 0.1.0 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 Official TypeScript SDK for the SpicyAPI public API. It contains the typed client, webhook
 verification helpers, documentation index, and generated OpenAPI types. It does not install the CLI,
-MCP server, or Codex Skill.
+MCP server, or Agent Skill.
 
 ```bash
 npm install @spicyapi/sdk
@@ -16,6 +16,83 @@ const models = await client.listModels({ includeSchema: true });
 ```
 
 Set `SPICY_API_KEY` with your process secret manager. Task creation and retry may reserve funds; use
-stable idempotency keys and explicit user confirmation.
+stable idempotency keys and explicit user confirmation. Call `quoteTask` with the exact request
+first, display its `estimatedCost`, `maxCharge` and `expiresAt`, then call `createTask` with the
+unchanged input, `quoteId` and `expectedCost`.
 
 Documentation: <https://spicyapi.ai/en/docs>
+
+## Chat and LLM streaming
+
+Use the official `openai` client for `/v1/chat/completions`; install it separately with
+`npm install openai`. The native SDK intentionally keeps tasks, quotes and uploads in one small
+client. It does not reimplement the OpenAI streaming protocol.
+
+```js
+import OpenAI from "openai";
+
+const client = new OpenAI({
+  apiKey: process.env.SPICY_API_KEY,
+  baseURL: "https://api.spicyapi.ai/v1",
+  maxRetries: 0,
+});
+const signal = AbortSignal.timeout(120_000);
+const stream = await client.chat.completions.create(
+  {
+    model: process.env.SPICY_MODEL,
+    messages: [{ role: "user", content: "Explain a rainbow in one sentence." }],
+    stream: true,
+    stream_options: { include_usage: true },
+  },
+  {
+    signal,
+    headers: { "Idempotency-Key": process.env.SPICY_IDEMPOTENCY_KEY },
+  },
+);
+try {
+  for await (const chunk of stream) {
+    process.stdout.write(chunk.choices[0]?.delta.content ?? "");
+    if (chunk.usage) process.stderr.write(JSON.stringify(chunk.usage) + "\n");
+  }
+} finally {
+  stream.controller.abort();
+}
+```
+
+The abort signal covers stream consumption as well as connection setup. Aborting stops the local
+stream; it does not cancel an accepted task or promise a refund. With `stream: false`, read
+`choices[0].message.content`. In a tool conversation, accumulate tool-call fragments by index and
+preserve the complete assistant message before adding matching `tool_call_id` results. Only enable
+tools or reasoning fields when the model schema supports them.
+
+CLI and MCP currently submit and track native tasks; they do not expose live chat token streaming.
+Use this client path for a token-by-token interface, or native `jobs/stream` when you need quote
+confirmation and the platform event envelope.
+
+Select `SPICY_MODEL` from the live model schema. Keep API keys on your server and persist
+`SPICY_IDEMPOTENCY_KEY` for the same logical action; disable automatic retries to avoid silently
+repeating a billable operation. Compatibility requests use the price at acceptance. Use native
+`quoteTask` and `createTask` when confirming `expectedCost` is required.
+
+Reasoning-capable models may return `delta.reasoning_content`; it is optional and may need an
+explicit type extension in the official client. Reasoning tokens are already included in
+`completion_tokens`. Stream completion is not proof of financial settlement.
+
+[Complete compatibility guide](https://spicyapi.ai/en/docs/quotes-and-compatibility) ·
+[Official JavaScript client](https://github.com/openai/openai-node)
+
+## Media inputs and results
+
+Pass a publicly accessible HTTPS image, video, or audio URL directly in the field specified by the
+model schema. Uploading is optional: local files use `createUploadUrl` → PUT → `commitUploadedFile`,
+then the returned account-bound `spicy://` URI (valid for one day).
+
+`getTask` and `waitForTask` return ready media in `output.assets`, including `url`, `expiresAt`,
+MIME, and available dimensions, duration, and byte count. Download `asset.url` directly without
+forwarding `SPICY_API_KEY`; no separate `createDownloadUrl` call is required. `pending` assets need
+another poll. URLs normally last 20 minutes, within the 14-day result retention window. Poll again
+to refresh a URL; `createDownloadUrl` remains available for older integrations.
+
+V2 webhooks use the same result fields. A retry keeps the business event and `request_id`, but
+refreshes `url` and `expiresAt`. Verify the signature against the exact received body and
+deduplicate using `request_id`, not a full-body hash. V1 payloads remain unchanged.