@vxil/sdk 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @vxil/sdk
 
-Typed JavaScript/TypeScript client for the [Vxil](https://vxil.com) REST API — backend building blocks (auth, cms, files, payments, notifications, jobs, realtime, vector search, AI, and more) you enable in one line.
+Typed JavaScript/TypeScript client for the [Vxil](https://vxil.com) REST API — backend building blocks (auth, cms, files, payments integration, notifications, jobs, realtime, vector search, AI, and more) you enable in one line.
 
 ```bash
 npm install @vxil/sdk
@@ -13,14 +13,91 @@ const vx = new Vxil({ apiKey: process.env.VXIL_API_KEY! });
 
 await vx.users.upsert({ id: 'u_1', email: 'ada@example.com' });
 await vx.notifications.send({ user_id: 'u_1', template: 'welcome', data: { app_name: 'MyApp' } });
-const items = await vx.from('tasks').list({ status: 'open' });
+const { items } = await vx.from('tasks').query({ filter: { status: 'open' } });
 ```
 
-- Zero dependencies; works in Node ≥18, browsers, and edge runtimes.
+- Zero dependencies. Runs anywhere `fetch` exists: Node ≥ 18, browsers, edge runtimes, and **React Native / Expo** (Hermes) — the SDK uses none of the WHATWG `URL` / `URLSearchParams` surface React Native only partially provides.
 - Defaults to `https://api.vxil.com`; pass `baseUrl` to target another environment.
-- Every feature the tenant has enabled is available as a typed namespace; generate a
-  project-exact client with `npx @vxil/cli gen`.
+- Every feature the tenant has enabled is available as a typed namespace; generate a project-exact client with `npx @vxil/cli gen`.
+- Every non-2xx response throws a `VxilError` carrying the structured error envelope (`status`, `code`, `message`, `hint`, `fixUrl`, `requestId`, and `retryAfter` in seconds when the server sent `Retry-After`).
 
-Docs: [vxil.com](https://vxil.com) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard) · Terms: [vxil.com/terms](https://vxil.com/terms)
+## Server mode and end-user mode
+
+A **server key** is a secret: keep it in a server route handler and never ship it in a browser or app bundle. To call Vxil from a browser or a phone directly, use a **thin-client key** (the `end_user_required` class — it refuses any request without a valid end-user session) together with the signed-in user's session token:
+
+```ts
+const vx = new Vxil({
+  apiKey: PUBLIC_VXIL_KEY,        // thin-client key: reads + owner-scoped writes only
+  endUserToken: session.token,    // from vx.auth.signIn / your sign-in flow
+});
+// reads and writes on owner-scoped resources are confined to this user
+const { items } = await vx.from('meals').query({ limit: 20 });
+```
+
+`vx.asEndUser(token)` returns a client for another session with everything else inherited; nothing in the SDK caches a token.
+
+## Retries, timeouts and request hooks
+
+All three are **off by default** — with none of them set the client is a single `fetch` per call, exactly as before.
+
+```ts
+const vx = new Vxil({
+  apiKey,
+  timeoutMs: 10_000,                 // per attempt; aborts the request AND its body read
+  retry: { attempts: 2 },            // up to 3 requests in total
+  hooks: {
+    beforeRequest: (req) => ({ 'x-request-id': crypto.randomUUID() }),
+    afterResponse: ({ request, response, durationMs }) => log(request.method, request.url, response.status, durationMs),
+    onRetry: ({ request, delayMs, status, error }) => log('retry', request.url, delayMs, status ?? error),
+  },
+});
+```
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `retry.attempts` | `0` (off) | Retries after the first attempt. |
+| `retry.retryOn` | `[429, 502, 503, 504]` | Response statuses that trigger a retry. |
+| `retry.backoffMs` | `250` | First delay; doubles per retry, with jitter in `[½, 1]` of the computed delay. |
+| `retry.maxBackoffMs` | `10_000` | Longest wait between attempts. A `Retry-After` beyond it ends the loop instead of waiting. |
+| `retry.respectRetryAfter` | `true` | Use the response's `Retry-After` (seconds or HTTP-date) as the delay when present. |
+| `retry.retryOnNetworkError` | `true` | Also retry when `fetch` itself fails (DNS, reset, a `timeoutMs` timeout). |
+| `timeoutMs` | none | Per-attempt timeout via `AbortController`; throws `VxilError` `{ status: 0, code: 'request_timeout' }`. |
+| `hooks.beforeRequest` | — | Runs before every attempt; may return headers to add for that attempt. |
+| `hooks.afterResponse` | — | Runs after every response (retried or final) with the response and its duration. |
+| `hooks.onRetry` | — | Runs right before the client sleeps for a retry. |
+
+Rules that keep retries safe:
+
+- **Only idempotent requests are ever retried**: `GET`, `HEAD`, `PUT`, `DELETE`, and a `POST` only when the call carries an `Idempotency-Key` (the `{ idempotencyKey }` option on the money routes — `payments.credits.consume`, `notifications.send`, …). A bare `POST` or a `PATCH` is never retried, whatever `retry` says.
+- Hooks receive a **frozen** request descriptor (`method`, `url`, `headers`, `attempt`) that never includes the credential headers, and they cannot set them either; rotate a session with `vx.asEndUser(token)`.
+- A thrown hook aborts the call. The body of a response a hook sees has already been read; inspect `status` and `headers`.
+
+## Errors
+
+```ts
+import { VxilError } from '@vxil/sdk';
+
+try {
+  await vx.payments.credits.consume({ user_id, credit_type: 'tokens', amount: 5 }, { idempotencyKey });
+} catch (e) {
+  if (e instanceof VxilError && e.status === 429) {
+    showToast(`Try again in ${Math.ceil(e.retryAfter ?? 30)}s`);
+  }
+}
+```
+
+## Changelog
+
+### 0.4.0 — 2026-09-11
+
+- React-Native-clean: every query string is built without `URLSearchParams` (React Native's polyfill throws on `.set` before 0.81); wire bytes unchanged.
+- `VxilError.retryAfter` (seconds) parsed from `Retry-After`.
+- Opt-in `retry`, `timeoutMs` and `hooks` options on the client (see above). No behaviour changes unless set.
+
+### 0.3.0
+
+- Agent inner-loop wave: structured output, usage, `@vxil/react` companions.
+
+Docs: [vxil.com/docs/guide](https://vxil.com/docs/guide) · Dashboard: [vxil.com/dashboard](https://vxil.com/dashboard) · Terms: [vxil.com/terms](https://vxil.com/terms)
 
 MIT © techmaker.io