@spicyapi/sdk 0.4.0 → 0.5.0

package/README.md

@@ -1,54 +1,188 @@
 # @spicyapi/sdk
 
-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 Agent Skill.
+The official TypeScript SDK for [SpicyAPI](https://spicyapi.ai) — one API for video, image and chat
+models. It contains the typed client, webhook verification helpers, a documentation index and
+generated OpenAPI types.
+
+It does **not** install the CLI, MCP server or Agent Skill.
 
 ```bash
 npm install @spicyapi/sdk
 ```
 
+Requires Node.js 22.13 or later.
+
+## Get a key first
+
+1. Create an account at [spicyapi.ai/register](https://spicyapi.ai/register) — accounts are opened
+   in batches, so you may join the waitlist first.
+2. Create a key on the [API keys page](https://spicyapi.ai/console/keys). It starts with `sk-spicy-`
+   and is shown once.
+3. Put it in the environment your server reads, never in source:
+
+```bash
+export SPICY_API_KEY="sk-spicy-..."   # paste your own key
+```
+
+## Your first task
+
 ```ts
+import { randomUUID } from "node:crypto";
 import { SpicyClient } from "@spicyapi/sdk";
 
+// Reads SPICY_API_KEY from the environment; never pass a key as an argument.
 const client = new SpicyClient();
-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. When a caller needs an exact price
-confirmation, call `quoteTask` with the request, display its `estimatedCost`, `maxCharge` and
-`expiresAt`, then pass unchanged input, `quoteId` and `expectedCost` to `createTask` or `run`.
-Pre-authorized server workflows can submit directly at current pricing; separate health, balance and
-quote requests are not mandatory API steps.
+// 1. Take a model id from the live catalog instead of hard-coding one. Ids read
+//    `<maker>/<model>/<task>`, e.g. `bytedance/seedream-5.0-pro/text-to-image`.
+const catalog = await client.listModels({ modality: "image" });
+const model = catalog.items[0].model;
 
-## Submit and wait
+// 2. Read that model's input schema, and build `input` from it — two models in
+//    one family can take different fields.
+const { inputSchema } = await client.getModel(model);
 
-```ts
-const model = process.env.SPICY_MODEL;
-const operationId = process.env.SPICY_IDEMPOTENCY_KEY;
-if (!model || !operationId) throw new Error("Set a model and a persisted operation key");
+// 3. One billable task, waited to a terminal state.
 const task = await client.run(
-  { model, input: { prompt: "A quiet mountain lake" } },
-  { idempotencyKey: operationId, onAccepted: ({ taskId }) => console.log({ taskId }) },
+  { model, input: { prompt: "A cinematic night portrait" } },
+  {
+    idempotencyKey: randomUUID(),
+    onAccepted: ({ taskId }) => console.log({ taskId }),
+  },
 );
+
 if (task.state === "succeeded") {
   console.log(task.output?.assets?.[0]?.url);
 }
 ```
 
-Use a model and input supported by its current schema. `run` submits once and handles adaptive
-polling, including pending media transfer. Its local timeout includes submission and waiting; timing
-out or aborting does not cancel the accepted task. Resume with the saved task ID. Use a webhook for
-background jobs to avoid polling entirely.
+`run` submits once and handles adaptive polling, including pending media transfer. Its local timeout
+covers submission and waiting; timing out or aborting **does not cancel the accepted task** — resume
+later with the saved task ID. For background jobs, use a webhook and skip polling entirely.
+
+## Three rules
+
+1. **The key stays on a server.** Set `SPICY_API_KEY` through the process environment or a secret
+   manager. Never place a live key in browser code, a mobile bundle, source, prompts, logs or
+   committed configuration.
+2. **Read the schema before building `input`.** Two models in one family can take different fields.
+   `getModel` returns the current schema; do not copy fields from a different model.
+3. **`createTask`, `run` and `retryTask` spend money.** Persist one idempotency key per logical
+   attempt and reuse it for every retry of that attempt. A new key means a new generation.
+
+## Client reference
+
+| Method                                        | Purpose                                                   |
+| --------------------------------------------- | --------------------------------------------------------- |
+| `listModels` / `getModel`                     | Live models, schemas, examples and your prices            |
+| `quoteTask`                                   | Exact price for a request, without creating anything      |
+| `createTask` / `run` / `retryTask`            | Create or retry a billable task (`run` also waits)        |
+| `purgeTask`                                   | Destroy one terminal task's stored content; idempotent    |
+| `getTask` / `waitForTask`                     | Read once, or wait for a terminal state with a time bound |
+| `listTasks`                                   | One page of task metadata for the current key             |
+| `getBalance` / `getUsage`                     | Available, held and total balance; settled spending       |
+| `getStatus`                                   | Public health and readiness                               |
+| `createUploadUrl` / `commitUploadedFile`      | Direct-upload ticket, then the `spicy://` commit          |
+| `uploadBytes` / `uploadFile` / `uploadBase64` | Shortcuts around that upload flow                         |
+| `createDownloadUrl`                           | Short-lived URL for a task output                         |
+
+`createTask` and `run` accept `retentionSeconds`, sent as `X-Spicy-Retention`, to shorten how long
+that one task's outputs and prompt are kept. It only ever shortens; the account settings and the
+platform maximum still apply, and the deadlines that took effect come back in the task record's
+`retention` object alongside `contentState`.
+
+`purgeTask` destroys one terminal task's generated media, result payload, prompt and input text. It
+is idempotent — repeating it on an already destroyed task succeeds — and it **destroys content, not
+the record of what it cost**: the ledger entry, charged amount, model, state, timestamps and request
+ID all remain queryable. It is not a refund and does not reverse a charge.
+
+TypeScript is the current official SDK. For Python, Go and other languages, generate a client from
+the [OpenAPI 3.1 contract](https://spicyapi.ai/docs/api-reference). Do not describe an unpublished
+third-party wrapper as an official SDK.
+
+## Confirming a price before you spend
+
+When a caller needs an exact price confirmation, quote the request, show the numbers, then pass the
+quote into creation:
+
+```ts
+const payload = { model, input };
+const quote = await client.quoteTask(payload);
+// Show quote.estimatedCost, quote.maxCharge and quote.expiresAt to the user.
+
+const accepted = await client.createTask(
+  { ...payload, quoteId: quote.quoteId, expectedCost: quote.estimatedCost },
+  { idempotencyKey: operationId },
+);
+```
 
-Documentation: <https://spicyapi.ai/en/docs>
+Pre-authorized server workflows can submit directly at current pricing. Separate health, balance and
+quote requests are not mandatory steps — the exact `estimatedCost` comes back with the acceptance.
+
+## Media inputs and results
+
+Pass a publicly accessible HTTPS image, video or audio URL directly in the field the model schema
+specifies. Uploading is optional:
+
+- `createUploadUrl` → PUT → `commitUploadedFile` returns an account-bound `spicy://` URI valid for
+  one day. `uploadFile` wraps all three steps.
+- `uploadBase64` accepts a Data URI or raw standard Base64 with an explicit `contentType`.
+- Small schema-declared image fields accept Data URIs directly in `input` (1 MiB decoded per image,
+  2 MiB total JSON body, with documented pixel limits). The upload helper handles larger files
+  within upload and model limits.
+
+`getTask` and `waitForTask` return ready media in `output.assets` — `url`, `expiresAt`, MIME, and
+available dimensions, duration and byte count. Download `asset.url` directly **without forwarding
+`SPICY_API_KEY`**; no separate `createDownloadUrl` call is needed. `pending` assets need another
+poll. URLs normally last 20 minutes, inside the 14-day result retention window; poll again to
+refresh one. See the [media guide](https://spicyapi.ai/docs/media).
+
+## Webhooks
+
+```ts
+import { verifyWebhook } from "@spicyapi/sdk";
+
+const { payload, taskId } = verifyWebhook({
+  rawBody, // the exact received bytes, before any parsing
+  secret: process.env.SPICY_WEBHOOK_SECRET!,
+  timestamp: headers["x-webhook-timestamp"],
+  signature: headers["x-webhook-signature"],
+  payloadVersion: 2,
+});
+```
+
+Verify against the **exact received bytes**, before any JSON parsing or re-serialization, and
+deduplicate on `request_id` rather than a full-body hash. V2 webhooks carry the same result fields
+as a task read; a retry keeps the business event and `request_id` but refreshes `url` and
+`expiresAt`. V1 payloads are unchanged.
+
+## Task history
+
+`listTasks` reads one page of metadata for the current API key. It does not fetch each task's
+inputs, results or media URLs. Keep the UTC dates fixed while paging and pass the cursor unchanged:
+
+```ts
+const filters = { from: "2026-09-01", to: "2026-09-07", limit: 20 };
+const page = await client.listTasks(filters);
+if (page.hasMore && page.nextCursor) {
+  const nextPage = await client.listTasks({ ...filters, cursor: page.nextCursor });
+  console.log(nextPage.items);
+}
+```
+
+The UTC interval is `[from,to)`, defaults to seven days ending tomorrow UTC, and cannot exceed 92
+days. Page size defaults to 20 and is capped at 100. Optional `state` and `model` filters narrow the
+results. Each `cost` is an exact decimal USD string, final only when `settled` is true. Hidden tasks
+are excluded, so use `getUsage` for settled spending reports.
+
+History is for discovery and recovery. Use `run`, `waitForTask` or webhooks to track normal
+completion, and `getTask` only for a result you actually selected.
 
 ## 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.
+This SDK deliberately keeps tasks, quotes and uploads in one small client and does not reimplement
+the OpenAI streaming protocol. For token-by-token chat, use the official `openai` client against
+SpicyAPI's compatible endpoints (`npm install openai`):
 
 ```js
 import OpenAI from "openai";
@@ -56,8 +190,9 @@ import OpenAI from "openai";
 const client = new OpenAI({
   apiKey: process.env.SPICY_API_KEY,
   baseURL: "https://api.spicyapi.ai/v1",
-  maxRetries: 0,
+  maxRetries: 0, // never silently repeat a billable operation
 });
+
 const signal = AbortSignal.timeout(120_000);
 const stream = await client.chat.completions.create(
   {
@@ -66,82 +201,38 @@ const stream = await client.chat.completions.create(
     stream: true,
     stream_options: { include_usage: true },
   },
-  {
-    signal,
-    headers: { "Idempotency-Key": process.env.SPICY_IDEMPOTENCY_KEY },
-  },
+  { 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");
+    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.
+Notes that matter in production:
 
-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.
+- 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.
+- Enable tool or reasoning fields only when the model schema supports them. Reasoning-capable models
+  may return `delta.reasoning_content`, which can need an explicit type extension in the official
+  client; its tokens are already counted in `completion_tokens`.
+- Compatibility requests use the price at acceptance. Use native `quoteTask` and `createTask` when
+  confirming `expectedCost` is required.
+- 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)
+See the [complete compatibility guide](https://spicyapi.ai/docs/quotes-and-compatibility) and the
+[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). `uploadFile` wraps these steps;
-`uploadBase64` also accepts a Data URI or raw standard Base64 with an explicit `contentType`. Small
-schema-declared image fields can accept Data URIs directly in `input` (1 MiB decoded per image, 2
-MiB total JSON body, with documented pixel limits). The upload helper is separate and supports
-larger files within upload and model limits. See the
-[media guide](https://docs.spicyapi.ai/en/docs/media).
-
-`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.
+## More
 
-## Task history
-
-`listTasks` reads one page of metadata for the current API key. It does not fetch each task's
-inputs, results, or media URLs. Keep the UTC dates fixed while paging and pass the returned cursor
-unchanged:
-
-```ts
-const filters = { from: "2026-09-01", to: "2026-09-07", limit: 20 };
-const page = await client.listTasks(filters);
-if (page.hasMore && page.nextCursor) {
-  const nextPage = await client.listTasks({ ...filters, cursor: page.nextCursor });
-  console.log(nextPage.items);
-}
-```
-
-The UTC interval is `[from,to)`, defaults to seven days ending tomorrow UTC, and cannot exceed 92
-days. Page size defaults to 20 and is capped at 100. Optional `state` and `model` filters narrow the
-results. Each item's `cost` remains an exact decimal USD string; it is final only when `settled` is
-true. Hidden tasks are excluded, so use `getUsage` for settled spending reports. Use `getTask` for a
-selected result, not automatically for every item. History is for discovery and recovery; use `run`,
-`waitForTask`, or webhooks for normal completion tracking.
+- [Developer hub](https://spicyapi.ai/developers) · [Full documentation](https://spicyapi.ai/docs)
+- Prefer a terminal? [`@spicyapi/cli`](https://www.npmjs.com/package/@spicyapi/cli). Prefer a coding
+  agent? [`@spicyapi/mcp`](https://www.npmjs.com/package/@spicyapi/mcp).