@xmodeai/sdk 0.1.0 → 0.1.1

package/llms.txt

@@ -0,0 +1,193 @@
+# @xmodeai/sdk — LLM usage guide
+
+Official SDK for the xMode API (AI image and video generation). This file is a
+dense, authoritative reference for AI coding agents. For prose docs see
+README.md; for exact types read the bundled `.d.ts`.
+
+## Mental model
+
+- Generation is **async**: you submit a job (HTTP 202, status `queued`), then
+  either poll for the result or receive a signed webhook. The SDK's `*AndWait`
+  helpers poll for you.
+- The SDK is a **tolerant reader**: responses are NOT validated. Unknown fields,
+  unknown `status` values, and unknown error `code`s pass through without
+  throwing. Always handle the `default`/unknown case; never assume the union is
+  exhaustive at runtime.
+- Result URLs (`images[].url`, `videos[].url`) are signed and expire in ~23h —
+  download or re-host; do not store them long-term.
+- Currency is **xTokens**. `cost.xTokens` on a succeeded record is what was
+  debited.
+
+## Install & construct
+
+```ts
+import XMode from '@xmodeai/sdk';
+
+const client = new XMode({
+  apiKey: process.env.XMODE_API_KEY, // default: env XMODE_API_KEY. Required.
+  baseUrl: 'https://api.xmode.ai',   // default
+  timeout: 30_000,                   // per-attempt ms, default
+  maxRetries: 2,                     // default
+  fetch: globalThis.fetch,           // override for tests / custom runtimes
+  defaultHeaders: {},                // merged into every request
+});
+```
+
+Runtimes: Node ≥18.17, Bun, Deno, Cloudflare Workers, browsers (key exposure!).
+Zero runtime dependencies; uses the platform `fetch`.
+
+## Method surface
+
+```
+client.generations.create(input: CreateGenerationInput, opts?) => Promise<QueuedGenerationRecord>
+client.generations.get(requestId: string, opts?)             => Promise<GenerationRecord>
+client.generations.list(params?: GenerationListParams, opts?) => PagePromise<GenerationRecord>
+client.generations.createAndWait(input, wait?: WaitOptions)  => Promise<GenerationRecord>   // poll default 10 min
+client.generations.wait(requestId, wait?: WaitOptions)       => Promise<GenerationRecord>
+
+client.videos.create(input: CreateVideoInput, opts?)         => Promise<QueuedVideoRecord>
+client.videos.get(requestId, opts?)                          => Promise<VideoRecord>
+client.videos.createAndWait(input, wait?: WaitOptions)       => Promise<VideoRecord>          // poll default 20 min
+client.videos.wait(requestId, wait?: WaitOptions)            => Promise<VideoRecord>
+
+client.balance.get(opts?)                                    => Promise<BalanceResponse>
+client.balance.history(params?, opts?)                       => PagePromise<BalanceLedgerEntry>
+
+client.endUsers.list(params?: EndUserListParams, opts?)      => PagePromise<EndUserRecord>
+client.endUsers.block(email: string, opts?)                  => Promise<BlockEndUserResponse>
+client.endUsers.unblock(email: string, opts?)                => Promise<UnblockEndUserResponse>
+client.endUsers.delete(email: string, opts?)                 => Promise<DeleteEndUserResponse> // 409 if pending jobs
+
+client.request<T = unknown>({ method, path, body?, query?, policy?, signal?, timeout?, maxRetries? }) => Promise<T>
+```
+
+`opts` (RequestOptions): `{ signal?, timeout?, maxRetries?, headers? }`.
+`WaitOptions`: `{ pollInterval? = 5000, timeout?, signal? }`.
+
+## Inputs
+
+CreateGenerationInput:
+- `endUserEmail` (required) — your end-user's email; groups jobs per user.
+- `prompt` (required) — 1–8000 chars, English.
+- `model` (required) — alias string, e.g. `'xSD4.5'`. Any string is accepted
+  (forward-compat); known aliases autocomplete.
+- `references?` — single HTTPS URL or array of 1–10 URLs.
+- `size?` — `'2K'` | `'4K'` | explicit `'WxH'` (e.g. `'2048x2048'`). Default `2K`.
+- `aspectRatio?` — `'auto' | 'square' | 'landscape' | 'portrait'`.
+- `n?` — 1–15 images (each billed). Constraint: `references.length + n ≤ 15`.
+- `seed?`, `watermark?`, `guidanceScale?` (1–20), `responseFormat?` (`'url'|'b64_json'`).
+- `sequential?` (`'auto'|'disabled'`) + `sequentialOptions?: { maxImages }` for connected series.
+- `webhookUrl?` — HTTPS URL to receive the terminal record.
+
+CreateVideoInput (model `'xW2.7S'`):
+- `endUserEmail`, `model`, `prompt`, `image` (HTTPS URL) — required.
+- `negative_prompt?`, `audio_url?` (HTTPS), `resolution?` (`'720p'|'1080p'`, default `'1080p'`),
+  `duration?` (2–15s, default 5), `prompt_extend?` (default true), `seed?` (number|null), `webhookUrl?`.
+
+## Records (responses)
+
+Discriminated by `status`: `'queued' | 'processing' | 'succeeded' | 'failed' | 'expired'`
+(plus possible future values — handle the default case).
+
+- queued: `{ requestId, status:'queued', model, prompt, referencesCount, endUserEmail, createdAt, pollUrl }`
+- processing: like queued without `pollUrl`.
+- succeeded (image): `+ images: { id, url?, error?, size?, expiresAt }[], cost: { xTokens }, finishedAt`
+- succeeded (video): `+ videos: { id, url?, error?, duration?, resolution?, expiresAt }[], cost, finishedAt`
+- failed: `+ error: { code, message }, finishedAt`
+- expired: `+ finishedAt` (URLs already dead).
+
+An image record always has `referencesCount`; a video record never does — use
+that to discriminate (see `isVideoEvent`).
+
+## Recipes
+
+Submit and wait:
+```ts
+const r = await client.generations.createAndWait({
+  endUserEmail: 'alice@your-product.com', model: 'xSD4.5', prompt: 'a red panda astronaut',
+});
+if (r.status === 'succeeded') console.log(r.images[0]?.url);
+else if (r.status === 'failed') console.error(r.error.code, r.error.message);
+// createAndWait/wait RETURN failed/expired records — they only throw on poll timeout.
+```
+
+Manual polling:
+```ts
+const queued = await client.generations.create({ endUserEmail, model: 'xSD4.5', prompt });
+let rec = await client.generations.get(queued.requestId);
+// recommended poll interval: 5s. Terminal = succeeded|failed|expired.
+```
+
+Paginate (await one page, or for-await all items):
+```ts
+const page = await client.generations.list({ pageSize: 50, status: 'failed' });
+for await (const g of client.generations.list({ endUserEmail: 'alice@your-product.com' })) {
+  console.log(g.requestId);
+}
+```
+
+Verify a webhook (subpath `@xmodeai/sdk/webhooks`, pass the RAW body):
+```ts
+import { verifyWebhook, isVideoEvent } from '@xmodeai/sdk/webhooks';
+const { event } = await verifyWebhook({ payload: rawBody, headers: req.headers, secret });
+if (event.status === 'succeeded') {/* same shape as generations.get / videos.get */}
+// throws WebhookVerificationError (reason: missing_header|invalid_signature|timestamp_out_of_tolerance|malformed)
+```
+
+Use a not-yet-typed API parameter/endpoint without waiting for an SDK release:
+```ts
+await client.request({
+  method: 'POST', path: '/v1/videos',
+  body: { endUserEmail, model: 'xSV2.0', prompt, image, cameraMotion: 'orbit' },
+});
+```
+
+## Errors
+
+All API errors extend `XModeAPIError` (`{ status, code, message, fields?, requestId? }`),
+subclassed by `code`:
+
+| class | code(s) | http |
+|---|---|---|
+| ValidationError | validation_error | 400 |
+| AuthenticationError | unauthorized, account_blocked | 401 |
+| PaymentRequiredError | payment_required | 402 |
+| PermissionDeniedError | forbidden | 403 |
+| NotFoundError | not_found | 404 |
+| ConflictError | conflict | 409 |
+| ContentPolicyError | content_policy | 422 |
+| RateLimitError | rate_limited (+retryAfter) | 429 |
+| ProviderError | provider_error, provider_timeout | 5xx |
+| InternalServerError | internal_error | 5xx |
+
+Unknown `code` → base `XModeAPIError` (never a mapping crash). Network failures →
+`APIConnectionError` / `APIConnectionTimeoutError`. Poll budget exceeded →
+`XModePollTimeoutError` (carries `lastRecord`).
+
+```ts
+import { ContentPolicyError, RateLimitError } from '@xmodeai/sdk';
+try { await client.generations.create({ endUserEmail, model: 'xSD4.5', prompt }); }
+catch (e) {
+  if (e instanceof ContentPolicyError) {/* prompt rejected */}
+  else if (e instanceof RateLimitError) {/* back off; e.retryAfter seconds */}
+  else throw e;
+}
+```
+
+## Retries (important)
+
+- GET / `block` / `unblock` / `delete` → retried on network errors, 408, 429, 5xx.
+- `generations.create` / `videos.create` → retried **only on 429**. They debit
+  xTokens and have no idempotency key, so a timed-out/5xx create is NOT retried
+  automatically (it may have succeeded). Re-submitting risks a double charge.
+
+Backoff is exponential with jitter and honors `Retry-After`. Tune with
+`maxRetries` (client or per-call).
+
+## Don'ts
+
+- Don't assume `status`/`error.code` is one of the known literals at runtime —
+  new values can appear; handle the default branch.
+- Don't re-serialize the webhook body before `verifyWebhook` — pass the raw string.
+- Don't retry a failed `create` blindly — check via `list`/`get` first.
+- Don't store result URLs long-term — they expire (~23h).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmodeai/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official TypeScript/JavaScript SDK for the xMode API — AI image and video generation.",
   "type": "module",
   "license": "MIT",
@@ -37,7 +37,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "llms.txt"
   ],
   "publishConfig": {
     "access": "public"