silon-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silon
+
+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,560 @@
+# Silon Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/silon-sdk)](https://www.npmjs.com/package/silon-sdk)
+
+Node.js client for the [Silon](https://silon.tech) messaging platform API —
+send messages on any channel (WhatsApp, SMS, email, push, web push, voice),
+manage CRM contacts and groups, run bulk campaigns, consume events, and verify
+webhooks. ESM-only, TypeScript-first, **zero runtime dependencies** (built on
+native `fetch`, `FormData` and `node:crypto`).
+
+## Installation
+
+```bash
+npm install silon-sdk
+```
+
+Requires Node.js >= 18. The package ships compiled ESM plus `.d.ts` type
+declarations; there is no CommonJS build (`require("silon-sdk")` will not work —
+use `import`, or dynamic `import()` from CJS).
+
+## Quickstart
+
+```ts
+import Silon from "silon-sdk";
+
+const client = new Silon({
+  apiKey: "sk_live_...",   // Settings → API keys; or set SILON_API_KEY
+  workspace: "acme",       // => https://acme.silon.tech; or set SILON_WORKSPACE / SILON_BASE_URL
+});
+
+const sent = await client.messages.send({
+  channel: "whatsapp",
+  to: { client_id: "cust_001" },
+  content: { body: "Your order has shipped 📦" },
+});
+console.log(sent.id, sent.status);   // e.g. "9f3e..." "queued"
+```
+
+The API is Promise-based throughout — every operation returns a `Promise` you
+`await` (this is the platform idiom; the Python SDK additionally ships a sync
+client).
+
+## Sending
+
+Three entry points, every channel: `messages.send` targets a single recipient
+via `to`; `messages.sendBatch` sends many independent, personalised messages
+in one call — inline rows via `messages` (max 500) or an uploaded CSV via
+`file`; `broadcasts.create` fans one piece of content out to an `audience`
+(a client group, explicit client ids, or an inline `recipients` list). On
+`messages.send`, exactly one of `to` / `audience` is required, and on
+`messages.sendBatch` exactly one of `messages` / `file` (the SDK validates
+both client-side and throws `SilonError` before any network call).
+
+```ts
+// Approved WhatsApp template to a raw number
+await client.messages.send({
+  channel: "whatsapp",
+  to: { phone_number: "+12025550123" },
+  whatsapp_template: {
+    name: "order_confirmed",
+    language: "en",
+    variables: { body_1: "Sara", body_2: "ORD-42" },
+  },
+  provider: "meta_cloud",
+});
+
+// Personalised batch — every row is its own message (same shape as a
+// messages.send body minus `audience`); the top-level channel is the
+// default, a row's own channel wins. Max 500 rows, all-or-nothing: any
+// invalid row 422s the whole batch (`messages[3].to.phone_number`) and
+// nothing is queued.
+const batch = await client.messages.sendBatch({
+  channel: "sms",
+  messages: [
+    { to: { phone_number: "+96550001234" }, content: { body: "Sara, table for 2 at 7pm." } },
+    { to: { phone_number: "+96550001235" }, content: { body: "Omar, table for 4 at 9pm." } },
+    {
+      channel: "email",
+      to: { email: "lulu@example.com" },
+      content: { subject: "Booking confirmed", body: "Lulu, table for 6 at 8pm." },
+    },
+  ],
+});
+// Per-row envelopes come back in request order; poll each id individually.
+// Inline batches have no GET endpoint — the per-row ids are the tracking
+// primitive.
+for (const row of batch.messages ?? []) {
+  const status = await client.messages.retrieve(row.id);
+  console.log(row.id, status.is_sent);
+}
+
+// Batch from an uploaded CSV — request-level fields are row defaults, CSV
+// columns override per row ({{name}} renders from the row). The rows expand
+// asynchronously: the 202 is an aggregate (no per-row `messages`) and the
+// returned id IS the bulk batch id.
+const uploaded = await client.bulk.files.upload("phone_number,name\n+96550001234,Sara\n");
+const fileBatch = await client.messages.sendBatch({
+  file: uploaded.name,
+  channel: "sms",
+  content: { body: "Hello {{name}}" },
+});
+console.log(fileBatch.status, fileBatch.row_count); // "queued" 1
+const detail = await client.bulk.retrieve(Number(fileBatch.id)); // per-row status
+
+// Email broadcast to a client group
+const result = await client.broadcasts.create({
+  channel: "email",
+  audience: { type: "client_group", slug: "vip" },
+  content: { subject: "We saved you a seat", body: "<h1>Hello</h1>" },
+});
+console.log(result.target_count, result.skipped_count);
+// Why rows were skipped, itemised (skipped_count stays the sum):
+console.log(result.skipped);  // { suppressed: 2, wrong_channel: 0, duplicate: 1 }
+
+// SMS broadcast to an inline ad-hoc list (max 1,000 rows; rows may also be
+// { email } or { client_id } — duplicates are deduped into skipped.duplicate)
+await client.broadcasts.create({
+  channel: "sms",
+  audience: {
+    type: "recipients",
+    recipients: [{ phone_number: "+96550001234" }, { phone_number: "+96550001235" }],
+  },
+  content: { body: "Flash sale ends tonight" },
+});
+
+// Track it
+const broadcast = await client.broadcasts.retrieve(result.id);
+const page = await client.broadcasts.deliveries(result.id, { limit: 100 });
+for await (const delivery of page.autoPaging()) {
+  console.log(delivery.client_id, delivery.status);
+}
+```
+
+`messages.send` with `audience` keeps working as a legacy alias, but
+`broadcasts.create` is the preferred broadcast entry point.
+
+Every `messages.send` / `messages.sendBatch` / `broadcasts.create` /
+`otp.send` call carries an
+`Idempotency-Key` header (auto-generated UUIDv4 unless you pass
+`idempotency_key`), so automatic retries can never double-send. The key is a
+request header, never part of the JSON body.
+
+## Scheduling and cancellation
+
+Pass `send_at` — an ISO-8601 date-time string **with a UTC offset** (e.g.
+`"2026-07-15T09:00:00+03:00"`; date-times stay strings in this SDK, so call
+`.toISOString()` on a `Date` yourself) — on `messages.send`,
+`broadcasts.create`, or the **file** form of `messages.sendBatch` to schedule
+the send instead of dispatching immediately. It must be strictly in the
+future and at most 90 days ahead; naive date-times are rejected — otherwise
+the server answers `422 send-at-invalid`. The response is the normal `202`
+envelope with `status: "scheduled"`, and its `id` is stable across the
+lifecycle: `messages.retrieve` / `broadcasts.retrieve` resolve it before
+dispatch (`"scheduled"`) and after (the normal queued/sent lifecycle).
+
+```ts
+const scheduled = await client.messages.send({
+  channel: "sms",
+  to: { phone_number: "+96550001234" },
+  content: { body: "Doors open in an hour" },
+  send_at: new Date(Date.now() + 3600_000).toISOString(),
+});
+console.log(scheduled.status);                    // "scheduled"
+
+// Changed your mind? Allowed while still "scheduled":
+const canceled = await client.messages.cancel(scheduled.id);
+console.log(canceled.status);                     // "canceled" — never dispatches
+```
+
+`messages.cancel(id)` and `broadcasts.cancel(id)` return the same envelope
+types as their create calls, now showing `status: "canceled"`, and emit a
+`message.canceled` / `broadcast.canceled` event. Cancel is idempotent by
+nature — repeating a cancel answers `200` with the canceled envelope again
+(no `Idempotency-Key` is sent, and none is needed). Once the send has
+dispatched (or for an immediate send's id) the server answers
+`409 not-cancellable` (`ConflictError`); an unknown id is a `404`.
+
+Notes:
+
+- A scheduled broadcast may answer `target_count: null` /
+  `skipped_count: null` when its audience resolves at dispatch time.
+- `send_at` on `sendBatch` works with the `file` form only (rows expand and
+  send at dispatch time). With inline `messages` it is rejected
+  `422 batch-invalid` — schedule those rows individually via
+  `messages.send`, which supports per-message cancel; there is no batch
+  cancel resource.
+- Scheduled creates are idempotency-keyed exactly like immediate ones — a
+  replay returns the scheduled envelope.
+- With an `sk_test_` key, scheduled sends simulate delivery on dispatch,
+  like any other test-mode send.
+
+## Suppressions
+
+`client.suppressions` manages the workspace do-not-contact list. A row is an
+address (E.164 phone or email, stored normalized so any formatting matches)
+optionally scoped to one channel — omit `channel` to suppress the address
+everywhere. It is enforced automatically on **every** send path:
+
+- **Single-recipient sends** (`messages.send` with `to`, `otp.send`) to a
+  suppressed address reject `422 recipient-suppressed`
+  (`UnprocessableEntityError`).
+- **Fan-outs** (`broadcasts.create`, `messages.sendBatch`, legacy bulk)
+  silently **skip** suppressed recipients — never an error. The `202`
+  envelope itemises why rows were skipped in an additive `skipped` object,
+  with `skipped_count` staying the sum:
+
+  ```jsonc
+  { "skipped_count": 6, "skipped": { "suppressed": 3, "wrong_channel": 2, "duplicate": 1 } }
+  ```
+
+  On broadcasts `skipped` is `null` exactly when `target_count` is `null`
+  (scheduled audience resolves at dispatch). Inline batches omit suppressed
+  rows from `messages`; file-form batches report their skips on the bulk
+  read side (`client.bulk.retrieve(id)`) once async expansion runs.
+
+```ts
+// Honour a STOP reply on every channel:
+const row = await client.suppressions.create({
+  address: "+96550001234",
+  reason: "stop",             // "manual" (default) | "unsubscribe" | "hard_bounce" | "stop"
+});                            // omit `channel` => suppressed everywhere
+
+// Audit the list — cursor-paginated, filterable:
+const page = await client.suppressions.list({ reason: "stop", channel: "sms" });
+for await (const s of page.autoPaging()) console.log(s.address, s.reason);
+
+// The customer opted back in:
+await client.suppressions.delete(row.id);   // 204 — sends resume immediately
+```
+
+`create` is idempotent by nature: a new row answers `201`, and re-creating
+the same (address, channel) pair answers `200` with the **existing** object —
+never an error, and no `Idempotency-Key` is needed or sent. Rows are
+mode-scoped: `sk_test_` keys list, manage and enforce test suppressions only,
+live keys live ones. Scopes: `suppressions:read` to list,
+`suppressions:write` to create/delete.
+
+**Transactional/legal override.** For sends that must go out regardless
+(receipts, statements, legally required notices), pass
+`override_suppression: true` on `messages.send` — single-recipient sends
+only. The API key must carry the `suppressions:override` scope (part of no
+default preset; grant it explicitly), otherwise the server rejects
+`403 missing-scope`; combined with `audience`, or used on
+`broadcasts.create` / `messages.sendBatch`, it is rejected
+`422 override-not-allowed`. An overridden send proceeds and its delivery row
+is flagged `suppression_overridden: true`.
+
+```ts
+await client.messages.send({
+  channel: "email",
+  to: { email: "sara@example.com" },      // suppressed (unsubscribed)
+  content: { subject: "Your invoice", body: "…" },
+  override_suppression: true,             // requires the suppressions:override scope
+});
+```
+
+## Test mode
+
+Use an `sk_test_` API key (Settings → API keys) to integrate and CI-test
+without a provider account or a real message. Test requests traverse the full
+pipeline — validation, scopes, rate limits, idempotency, delivery rows,
+events — but never reach a provider and never bill. Every affected response
+envelope (message send/status, batch, broadcast, OTP, events, webhook
+endpoints, suppressions) carries `livemode: false` (`true` for live traffic).
+
+Magic recipients force deterministic outcomes; statuses settle asynchronously
+a few seconds after the `202`, so polling and webhooks behave realistically.
+The always-suppressed fixtures act as if on the suppression list without a
+`suppressions.create` row existing — use them to test your
+`recipient-suppressed` handling:
+
+| Recipient | Outcome |
+| --- | --- |
+| `+15005550001` | delivered |
+| `+15005550002` | failed (simulated provider error) |
+| `+15005550009` | always suppressed — single send `422 recipient-suppressed`; fan-outs skip it into `skipped.suppressed` |
+| `delivered@silon.test` | delivered |
+| `bounce@silon.test` | failed (simulated bounce) |
+| `suppressed@silon.test` | always suppressed — single send `422 recipient-suppressed`; fan-outs skip it into `skipped.suppressed` |
+| anything else | delivered |
+
+In **live** mode a magic recipient is rejected with
+`422 test-recipient-in-live`, so test fixtures can never leak into real sends.
+
+Test-mode OTPs are never dispatched: the magic code `"000000"` always
+verifies (and only it).
+
+Webhook endpoints are fixed to one mode at create time via the `livemode`
+create param (default `true`): test events deliver only to
+`livemode: false` endpoints, live events only to `livemode: true` ones —
+register one endpoint per mode to consume both streams.
+
+```ts
+const test = new Silon({ apiKey: "sk_test_...", workspace: "acme" });
+
+const sent = await test.messages.send({
+  channel: "sms",
+  to: { phone_number: "+15005550002" },   // will settle as "failed"
+  content: { body: "CI check" },
+});
+console.log(sent.livemode);               // false
+
+await test.webhookEndpoints.create({
+  url: "https://ci.example.com/hooks/silon",
+  livemode: false,                        // receives test events only
+});
+```
+
+## Resources
+
+| Resource | Methods |
+| --- | --- |
+| `client.messages` | `send`, `sendBatch`, `retrieve`, `cancel` |
+| `client.broadcasts` | `create`, `retrieve`, `deliveries` (paginated), `cancel` |
+| `client.otp` | `send`, `verify` |
+| `client.clients` | `list` (deprecated bare array), `listPaginated` (paginated), `create`, `retrieve`, `update`, `replace`, `delete` |
+| `client.clientGroups` | `list` (deprecated bare array), `listPaginated` (paginated), `create`, `retrieve`, `update`, `replace`, `delete` |
+| `client.bulk` | `list`, `retrieve`, `send` (deprecated — use `messages.sendBatch`), `files.list`, `files.upload`, `recipients.retrieve` |
+| `client.reports` | `messages`, `channels`, `clients`, `users`, `bulks`, `specificBulks`, `subscriptions`, `awsUsage`, `balance` |
+| `client.whatsappTemplates` | `list`, `retrieve` |
+| `client.templates` | `list` (paginated), `create`, `retrieve`, `update`, `delete` |
+| `client.webhookEndpoints` | `list` (paginated), `create`, `retrieve`, `update`, `delete`, `test`, `listAttempts` (paginated) |
+| `client.suppressions` | `list` (paginated), `create`, `delete` |
+| `client.events` | `list` (paginated), `retrieve` |
+| `client.push` | `subscribeAndroid`, `subscribeIos`, `upsertDevices`, `markRead`, `listNotifications` (deprecated), `subscribeWeb` (deprecated) |
+| `client.profile` | `retrieve`, `update`, `replace` |
+| `client.auth` | `signup`, `login` (deprecated) |
+
+## Pagination
+
+Cursor-paginated lists (`events`, `webhookEndpoints`,
+`webhookEndpoints.listAttempts`, `templates`, `broadcasts.deliveries`,
+`suppressions`, `clients.listPaginated`, `clientGroups.listPaginated`)
+return a `Page<T>` you can walk manually or drain with `autoPaging()`, an
+async generator that fetches each following page only when the current one is
+exhausted:
+
+```ts
+const page = await client.events.list({ type: "message.failed", limit: 100 });
+
+for (const event of page.results) { /* this page only */ }
+
+for await (const event of page.autoPaging()) { /* every page, lazily */ }
+
+// manual walking
+if (page.hasNextPage) {
+  const next = await page.nextPage();   // throws SilonError on the last page
+}
+```
+
+### CRM lists (`clients`, `clientGroups`)
+
+The canonical CRM list routes are now plural and cursor-paginated
+(`GET /api/v1/crm/clients/`, `GET /api/v1/crm/groups/`). Reach them with the
+new `listPaginated()` methods, which return a `Page<T>` like every other
+cursor list:
+
+```ts
+const page = await client.clients.listPaginated({ limit: 100 });
+for await (const contact of page.autoPaging()) { /* every contact, lazily */ }
+```
+
+For **back-compat**, the original `clients.list()` / `clientGroups.list()`
+still work unchanged: they return a bare `ClientProfile[]` / `ClientGroup[]`
+from the (now deprecated) singular route, so existing call sites that use
+`.length`, indexing, `.map`, or a plain `for…of` keep working exactly as
+before. Both are marked `@deprecated` — migrate to `listPaginated()`, which
+scales past the singular route's unbounded response. `create`, `retrieve`,
+`update`, `replace` and `delete` now target the plural canonical routes; their
+request/response shapes are unchanged.
+
+## Errors
+
+Non-2xx responses reject with a typed error carrying the parsed payload:
+
+```ts
+import Silon, { UnprocessableEntityError, RateLimitError } from "silon-sdk";
+
+try {
+  await client.messages.send({ channel: "banana", to: { client_id: "x" } });
+} catch (err) {
+  if (err instanceof UnprocessableEntityError) {        // 422
+    console.log(err.statusCode, err.requestId);
+    for (const detail of err.errors) {
+      console.log(detail.code, detail.attr, detail.detail);
+    }
+  } else if (err instanceof RateLimitError) {           // 429
+    console.log("retry after", err.retryAfter, "seconds");
+  } else {
+    throw err;
+  }
+}
+```
+
+`BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError`
+(403), `NotFoundError` (404), `ConflictError` (409, idempotency-key reuse or
+cancelling a send that is no longer scheduled), `GoneError` (410, expired
+OTP), `UnprocessableEntityError` (422),
+`RateLimitError` (429, with `retryAfter` seconds parsed from `Retry-After` or
+`RateLimit-Reset`) and `InternalServerError` (>= 500) all subclass
+`APIStatusError`, which carries `statusCode`, `requestId` (`X-Request-Id`),
+`errorType`, `errors`, `retryable` and the raw parsed `body`. Network failures
+reject with `APIConnectionError`; timeouts with its subclass `APITimeoutError`.
+Everything extends the base `SilonError`.
+
+`err.retryable` is the error body's `retryable` bool read verbatim — `true`
+iff retrying the SAME request could ever succeed (429, 5xx, an in-flight
+idempotency twin), `false` for every other 4xx — and `null` when a
+legacy/non-v1 body omits it (it is never recomputed from the status code).
+
+### Retries
+
+Requests are retried automatically (default `maxRetries: 2`, exponential
+backoff with jitter, honouring `Retry-After` / `RateLimit-Reset`) — but only
+when it is safe: idempotent methods (GET/HEAD/OPTIONS/PUT/DELETE), plus POSTs
+that carry an `Idempotency-Key`. The same key value is replayed on every
+attempt; plain POST/PATCH are never retried.
+
+## Webhooks
+
+Verify the `Silon-Signature` header on deliveries with the endpoint's
+one-time `whsec_` secret — no HTTP client needed:
+
+```ts
+import { webhooks } from "silon-sdk";
+
+const event = webhooks.constructEvent(
+  rawBody,                              // the raw (unparsed) request body
+  req.headers["silon-signature"],
+  process.env.SILON_WEBHOOK_SECRET,
+);
+if (event.type === "broadcast.completed") {
+  console.log(event.data.sent, "delivered,", event.data.failed, "failed");
+}
+```
+
+`constructEvent` throws `WebhookSignatureVerificationError` on a missing,
+stale or mismatching signature. Lower-level pieces are also exported:
+`webhooks.verifySignature(payload, header, secret, tolerance?)` returns a
+boolean (constant-time compare; default tolerance 300 s, `<= 0` skips the
+freshness check), `webhooks.sign(secret, payload, timestamp?)` produces a
+valid header for tests, and `webhooks.SIGNATURE_HEADER` is the header name.
+
+## Configuration
+
+| Option           | Env fallback      | Default | Notes                                                     |
+| ---------------- | ----------------- | ------- | --------------------------------------------------------- |
+| `apiKey`         | `SILON_API_KEY`   | —       | Required                                                   |
+| `baseUrl`        | `SILON_BASE_URL`  | —       | Wins over `workspace`; trailing `/` stripped               |
+| `workspace`      | `SILON_WORKSPACE` | —       | Expands to `https://<workspace>.silon.tech`                |
+| `timeoutMs`      | —                 | `30000` | Per-attempt timeout (`AbortSignal.timeout`)                |
+| `maxRetries`     | —                 | `2`     | Automatic retries after the initial attempt                |
+| `defaultHeaders` | —                 | —       | Merged over the computed defaults                          |
+| `fetch`          | —                 | global  | Injectable `fetch` — testing, or on-prem custom TLS        |
+
+A base URL must be resolvable at construction time, from one of four sources
+checked in this order — otherwise the constructor throws `SilonError`
+immediately (as it does for a missing API key):
+
+1. `baseUrl` option (wins over everything)
+2. `SILON_BASE_URL` env var
+3. `workspace` option → `https://<workspace>.silon.tech`
+4. `SILON_WORKSPACE` env var → same expansion
+
+## On-prem / self-hosted instances
+
+The `workspace` shortcut is SaaS-only sugar; everything else in the SDK is
+host-agnostic. For a self-hosted Silon, point `baseUrl` at your instance:
+
+```ts
+const client = new Silon({ apiKey: "sk_live_...", baseUrl: "https://silon.customer.internal" });
+```
+
+API keys, the error contract, retries, idempotency, and webhook signature
+verification all behave identically — they ride on the base URL.
+
+**Private CA / self-signed TLS.** The `fetch` option is the transport seam.
+Node's built-in fetch is powered by [undici](https://undici.nodejs.org), so
+bind a `fetch` to an undici `Agent` that trusts your CA:
+
+```ts
+import { Agent, fetch as undiciFetch } from "undici";
+import { readFileSync } from "node:fs";
+
+const agent = new Agent({
+  connect: { ca: readFileSync("/etc/pki/customer-ca.pem") },
+});
+
+const client = new Silon({
+  apiKey: "sk_live_...",
+  baseUrl: "https://10.20.0.5",
+  fetch: (input, init) => undiciFetch(input, { ...init, dispatcher: agent }),
+});
+```
+
+(Alternatively, `NODE_EXTRA_CA_CERTS=/etc/pki/customer-ca.pem` extends the
+default trust store process-wide with no code changes.)
+
+The SDK's `timeoutMs` still applies with a custom `fetch` — each attempt is
+passed an `AbortSignal.timeout(timeoutMs)` signal, so forward `init.signal`
+if you wrap the call.
+
+**Reverse proxies.** Cursor pagination never follows the server's opaque
+`next` URL directly — the SDK extracts only its query parameters and
+re-issues the request against your configured `baseUrl`, so a proxy that
+rewrites hostnames can't send pagination to an unreachable internal host.
+
+## Deprecated operations
+
+`auth.login`, `bulk.send`, `push.listNotifications` and `push.subscribeWeb`
+wrap legacy endpoints. They still work, but are tagged `@deprecated` (surfaced
+by editors and TypeScript) and emit a one-time-per-process
+`DeprecationWarning` via `process.emitWarning` when first called. Prefer
+scoped `sk_live_` API keys over `auth.login`, `messages.sendBatch` (inline
+`messages` rows or an uploaded CSV via `file`) over `bulk.send`, and the
+widget over `push.subscribeWeb`. `bulk.files.upload` / `bulk.files.list` stay
+non-deprecated — uploading is the ingestion path feeding `sendBatch`'s file
+form.
+
+## Deviations from the cross-language SPEC (approved for Node)
+
+- **Promise-based, async-only API** — the platform idiom (Python also ships a
+  sync client).
+- **JSON field names stay `snake_case`** in params and response types
+  (stripe/openai-node convention); TypeScript interfaces mirror the wire
+  format, no camelCase transform.
+- **Date-times stay ISO-8601 strings** (typed `string`), not `Date` objects.
+- `idempotency_key` and `extra_body` are passed inside the params object
+  (mirroring Python's kwargs); both are SDK-level and never sent as JSON body
+  fields.
+- Client-side validation failures (e.g. the `to`/`audience` XOR on
+  `messages.send`) throw `SilonError` — Node has no `ValueError`; likewise
+  `nextPage()` on the last page throws `SilonError` instead of an
+  illegal-state error type.
+- Timeout is configured as `timeoutMs` (milliseconds), matching JS platform
+  convention; SPEC's 30 s default = `30000`.
+- `bulk.files.upload` accepts raw content (`string`, `Uint8Array`/`Buffer`) or
+  a `{filename, content}` pair — not filesystem paths or streams (Python also
+  reads paths/file objects); read the file yourself first.
+- `bulk.send` attachments are passed as `files` (the wire field name); Python
+  calls the same parameter `attachments`.
+- Operation names are camelCase (`reports.awsUsage`, `reports.specificBulks`,
+  `push.subscribeAndroid`, `push.markRead`, …) per JS convention, while wire
+  field names in params/responses stay snake_case.
+- **Response headers are not surfaced on results.** SPEC's optional
+  `Idempotent-Replayed` / `RateLimit-Limit`/`Remaining`/`Reset` surfacing is
+  a per-SDK "optional / at minimum" seam, and this SDK has no precedent for
+  exposing response metadata on results (resource methods return the decoded
+  body only, and `request()` returns the parsed JSON, not the `Response`). No
+  such seam was added. `RateLimit-Reset` is still consumed internally for
+  retry backoff, and `Retry-After` / `RateLimit-Reset` are parsed onto
+  `RateLimitError.retryAfter`.
+
+## Development
+
+```sh
+npm install
+npm test        # vitest, fully offline (scripted fake fetch)
+npm run build   # tsc strict -> dist/ (ESM + .d.ts)
+```