samva 0.10.0 → 0.12.0

package/README.md

@@ -54,10 +54,8 @@ const message = await client.messages.send({
   },
 });
 
-const messages = await client.messages.list({
-  page: "1",
-  limit: "20",
-});
+const messages = await client.messages.list({ limit: "20" });
+// Pass `messages.nextCursor` back as `cursor` for the next page; it is null on the last page.
 ```
 
 ## Effect Quick Start
@@ -118,6 +116,26 @@ The Promise and Effect clients identify their public SDK surface and package ver
 advisory `x-samva-client` request header. Supply your own value in `headers`, or set the header to
 `null` in Promise request options or `undefined` in Effect client configuration to omit it.
 
+## Send a Published Template
+
+Author a template as TSX with `samva templates init`, then publish an exact commit with
+`samva templates publish --commit HEAD` (see [`@samva/cli`](https://www.npmjs.com/package/@samva/cli)).
+A published template is addressed by its slug, which is the `id` in its `defineTemplate`:
+
+```typescript
+await client.messages.send({
+  to: [{ email: "ada@example.com" }],
+  channel: "email",
+  email: {
+    templateSlug: "order-shipped",
+    templateData: { name: "Ada", orderId: "A-1042" },
+  },
+});
+```
+
+A template send omits `subject`, `html`, and `text`; the request fails if `templateData` does not
+match the template's input schema. `samva templates types` generates TypeScript types for that input.
+
 ## Service Surface
 
 The Promise client exposes:
@@ -132,8 +150,13 @@ The Promise client exposes:
 - `conversations`
 - `customFields`
 - `email`
+- `extensionInstallations`
+- `extensions`
+- `feedback`
+- `mailboxes`
 - `media`
 - `messages`
+- `namespaces`
 - `operations`
 - `organizations`
 - `scheduledMessages`
@@ -153,8 +176,13 @@ The Effect SDK exposes Pascal-cased domain modules with lower-camel operations:
 - `Conversations`
 - `CustomFields`
 - `Email`
+- `ExtensionInstallations`
+- `Extensions`
+- `Feedback`
+- `Mailboxes`
 - `Media`
 - `Messages`
+- `Namespaces`
 - `Operations`
 - `Organizations`
 - `ScheduledMessages`
@@ -205,7 +233,7 @@ Reusing a key with identical content replays the original response; reusing it w
 
 ### Stream pagination
 
-Every list operation that returns the uniform `{ items, pagination: { page, limit, total, totalPages } }` envelope carries two `Stream` companions, so you traverse pages without hand-rolling a `page` loop:
+Every list answers `{ items, nextCursor }`: pass `nextCursor` back as `cursor` for the next page, and stop when it is null. Every list operation that pages carries two `Stream` companions, so you traverse pages without hand-rolling a cursor loop:
 
 - **`list.items(input?)`** — a `Stream` of individual items across all pages.
 - **`list.pages(input?)`** — a `Stream` of raw page envelopes.
@@ -220,11 +248,11 @@ const allContacts = Stream.runCollect(Contacts.list.items());
 // Bounded consumption is lazy — this fetches only as many pages as it needs:
 const firstFifty = Stream.runCollect(Contacts.list.items().pipe(Stream.take(50)));
 
-// Caller params (start page, limit, filters) are respected:
-const activeFrom2 = Contacts.list.items({ page: "2", limit: "100", status: "active" });
+// Caller params (start cursor, limit, filters) are respected:
+const recent = Contacts.list.items({ limit: "100", after: "2026-01-01T00:00:00Z" });
 ```
 
-The companions are attached uniformly to every paginated list, including `Messages.list`, `Contacts.list`, `Campaigns.list`, `Email.listDomains`, and `Webhooks.list`. Each page fetch reuses the ambient `Retry` policy. Reads retry per page; pagination does not nest retries. Page and limit inputs retain their OpenAPI wire-string representation. The Promise client is unchanged; stream pagination is Effect-only.
+The companions are attached uniformly to every paginated list, including `Messages.list`, `Contacts.list`, `Campaigns.list`, `Email.listDomains`, and `Webhooks.list`. Each page fetch reuses the ambient `Retry` policy. Reads retry per page; pagination does not nest retries. The `limit` input retains its OpenAPI wire-string representation. A list bounded by design, such as `CustomFields.list`, answers `{ items }` in one response and carries no companions. The Promise client is unchanged; stream pagination is Effect-only.
 
 ### Redacted secrets
 
@@ -298,7 +326,6 @@ const message =
 
 ```typescript
 const response = await client.conversations.list({
-  page: "1",
   limit: "20",
   status: "active",
 });
@@ -344,6 +371,29 @@ const recipients = await client.campaigns.listRecipients({
 });
 ```
 
+### Read Mailbox Events
+
+`mailboxes.events` reads the `mailbox.*` events over a WebSocket, for a program without a public
+URL for webhooks. Asking for the next event marks the previous one handled; the stream reconnects
+after transient closes from the last event it holds and throws `MailboxEventStreamError` when the
+caller has to act. Its `_tag` is the API error tag the host refused with (`UnauthorizedError`,
+`ForbiddenError`, `ResourceNotFoundError`, `CursorExpiredError`, `ValidationError`, and the
+rest), with the host's `message`, `status`, `fields`, and `retryAfterSeconds`. A `429`, `5xx`, or
+`408` refusal is retried after the delay the host asked for; every other refusal ends the stream.
+It needs a runtime whose `WebSocket` accepts request headers, such as Node or Bun, or one passed
+as the `WebSocket` option.
+
+```typescript
+const events = client.mailboxes.events({ cursor: savedCursor, mailboxIds: ["mbx_..."] });
+for await (const event of events) {
+  await handle(event.type, event.data);
+  await saveCursor(event.cursor);
+}
+```
+
+With Effect, `Mailboxes.events(options)` is a `Stream` of the same events that fails with a
+`MailboxEventStreamFailure`, so `Effect.catchTag("CursorExpiredError", ...)` handles one cause.
+
 ### Custom Headers
 
 ```typescript