@xmodeai/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xMode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @xmodeai/sdk
+
+Official TypeScript / JavaScript SDK for the [xMode API](https://dashboard.xmode.ai/docs) — AI image and video generation.
+
+- **Zero runtime dependencies.** Uses the platform `fetch` — works on Node 18+, Bun, Deno, Cloudflare Workers and other edge runtimes.
+- **Async-first.** Submit a job, then poll or receive a webhook. Helpers do the polling for you.
+- **Forward-compatible.** New models and fields the API adds later never break an installed version.
+- **Typed.** First-class TypeScript types with autocomplete for known models, tolerant of everything else.
+
+## Install
+
+```bash
+npm install @xmodeai/sdk
+```
+
+## Quickstart
+
+```ts
+import XMode from '@xmodeai/sdk';
+
+const client = new XMode({ apiKey: process.env.XMODE_API_KEY });
+
+// Submit and wait for the result in one call.
+const result = await client.generations.createAndWait({
+  endUserEmail: 'alice@your-product.com',
+  model: 'xSD4.5',
+  prompt: 'Editorial photo of a red panda astronaut, studio lighting, 85mm',
+});
+
+if (result.status === 'succeeded') {
+  console.log(result.images[0]?.url); // signed URL, valid ~23h — download or re-host
+} else if (result.status === 'failed') {
+  console.error(result.error.code, result.error.message);
+}
+```
+
+The API key is read from the `XMODE_API_KEY` environment variable when you don't
+pass `apiKey` explicitly.
+
+## Polling vs. webhooks
+
+`createAndWait` polls for you (every 5s by default) and resolves once the job
+reaches a terminal status. If you'd rather drive it yourself:
+
+```ts
+const queued = await client.generations.create({ endUserEmail, model: 'xSD4.5', prompt });
+// ... later
+const record = await client.generations.get(queued.requestId);
+// or poll an existing job until terminal:
+const done = await client.generations.wait(queued.requestId, { pollInterval: 5000 });
+```
+
+For production, prefer **webhooks**: pass `webhookUrl` to `create` and verify the
+delivery (see below) instead of polling.
+
+> `createAndWait` / `wait` **return** the terminal record — including `failed`
+> and `expired`. They only throw `XModePollTimeoutError` if the wait budget
+> (default 10 min for images, 20 min for videos) elapses first.
+
+## Videos
+
+```ts
+const video = await client.videos.createAndWait({
+  endUserEmail: 'alice@your-product.com',
+  model: 'xW2.7S',
+  prompt: 'camera slowly pushing in, gentle motion',
+  image: 'https://your-cdn.example.com/input.png',
+  resolution: '1080p',
+  duration: 5,
+});
+
+if (video.status === 'succeeded') console.log(video.videos[0]?.url);
+```
+
+## Verifying webhooks
+
+The webhook helper is published at the `@xmodeai/sdk/webhooks` subpath and uses Web
+Crypto, so it runs on Node and every edge runtime. **Pass the raw request body**
+— do not re-serialize the parsed JSON.
+
+```ts
+import { verifyWebhook } from '@xmodeai/sdk/webhooks';
+
+// Example: a framework that gives you the raw body string.
+const { event } = await verifyWebhook({
+  payload: rawBody,
+  headers: request.headers,
+  secret: process.env.XMODE_WEBHOOK_SECRET,
+});
+
+if (event.status === 'succeeded') {
+  // event is the same shape as generations.get / videos.get
+}
+```
+
+Verification fails (throws `WebhookVerificationError` with a `reason`) on a bad
+signature, a timestamp outside the 5-minute tolerance, or missing headers.
+
+## Pagination
+
+List methods return a value you can `await` for one page or `for await` to
+stream every item across all pages.
+
+```ts
+const firstPage = await client.generations.list({ pageSize: 50 });
+
+for await (const generation of client.generations.list({ status: 'failed' })) {
+  console.log(generation.requestId);
+}
+```
+
+## Balance and end-users
+
+```ts
+const { xTokens } = await client.balance.get();
+
+await client.endUsers.block('alice@your-product.com');
+await client.endUsers.unblock('alice@your-product.com');
+await client.endUsers.delete('alice@your-product.com'); // 409 ConflictError if jobs are pending
+```
+
+## Error handling
+
+Every API error is an instance of `XModeAPIError`, subclassed by the stable
+error `code`:
+
+| Class | Code | 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` | 429 |
+| `ProviderError` | `provider_error`, `provider_timeout` | 5xx |
+| `InternalServerError` | `internal_error` | 5xx |
+
+```ts
+import { RateLimitError, ContentPolicyError } from '@xmodeai/sdk';
+
+try {
+  await client.generations.create({ endUserEmail, model: 'xSD4.5', prompt });
+} catch (err) {
+  if (err instanceof ContentPolicyError) {/* prompt was rejected */}
+  else if (err instanceof RateLimitError) {/* back off; err.retryAfter is in seconds */}
+  else throw err;
+}
+```
+
+Network failures throw `APIConnectionError` / `APIConnectionTimeoutError`. An
+unrecognized error code yields a plain `XModeAPIError` rather than crashing, so a
+new server-side code never breaks your handling.
+
+## Retries
+
+Retryable requests use exponential backoff with jitter and honor `Retry-After`.
+By default:
+
+- **GET** and idempotent operations (`block`, `unblock`, `delete`) retry on
+  network errors, `408`, `429` and `5xx` (default `maxRetries: 2`).
+- **`generations.create` / `videos.create` retry only on `429`.** They debit
+  xTokens and have no idempotency key, so a timed-out create is never retried
+  automatically — it might have succeeded server-side.
+
+## Using new API features before they're in the SDK
+
+A new model that uses an existing endpoint just works — `model` accepts any
+string. For a brand-new parameter or endpoint that isn't typed yet, use the
+low-level escape hatch (same auth, retry and error handling):
+
+```ts
+await client.request({
+  method: 'POST',
+  path: '/v1/videos',
+  body: { endUserEmail, model: 'xSV2.0', prompt, image, cameraMotion: 'orbit' },
+});
+```
+
+## Configuration
+
+```ts
+new XMode({
+  apiKey: '...',            // default: process.env.XMODE_API_KEY
+  baseUrl: '...',           // default: https://api.xmode.ai
+  timeout: 30_000,          // per-attempt timeout in ms
+  maxRetries: 2,            // automatic retries for retryable requests
+  fetch: customFetch,       // custom fetch (tests / older runtimes)
+  defaultHeaders: { ... },  // sent with every request
+});
+```
+
+> A custom `baseUrl` receives your `Authorization: Bearer` key on every request —
+> only point it at an xMode-operated host.
+
+## Runtime support
+
+Node 18.17+, Bun, Deno, Cloudflare Workers and other `fetch`-capable runtimes.
+The SDK can run in a browser, but doing so exposes your API key — keep keys
+server-side.
+
+## Versioning
+
+Pre-1.0, breaking changes bump the **minor** version and additive changes bump
+the **patch** version. From 1.0.0 onward the SDK follows standard semver.
+
+## License
+
+MIT