samva 0.27.0 → 0.28.1

package/AGENTS.md

@@ -29,3 +29,10 @@ not recipient delivery. A timeout preserves the original idempotency key and bod
 send another email. `uncertain` requires reconciliation. Only a permitted person can cancel before
 acceptance or retry an eligible original action without extending its deadline. Approval is also
 asynchronous. See https://samva.dev/docs/mailboxes/approvals for the receipt contract.
+
+Use `client.topics` (Promise) or `Topics` from `samva/effect/topics` (Effect) for topic management
+and per-channel subscription preferences. `setSubscriptions` writes explicit `subscribed` or
+`unsubscribed` status; `checkSubscription` resolves effective status including topic defaults.
+`subscriptions.subscribe` requires `topicId` and requests recipient confirmation; acceptance
+does not create a confirmed contact or subscription. Campaigns require `audience.topicId`, and
+email content accepts `topicId`.

package/README.md

@@ -1,5 +1,7 @@
 # samva
 
+Samva is the email API for your app: transactional and campaign sending, inbound mail, and webhooks behind one API.
+
 TypeScript SDK for Samva's public customer API.
 
 ## Documentation
@@ -54,7 +56,7 @@ const message = await client.messages.send({
   },
 });
 
-const messages = await client.messages.list({ 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.
 ```
 
@@ -210,7 +212,8 @@ The Promise client exposes:
 - `organizations`
 - `scheduledMessages`
 - `templates`
-- `unsubscribeGroups`
+- `topics`
+- `topicForms`
 - `webhooks`
 - `whoami`
 
@@ -238,7 +241,7 @@ The Effect SDK exposes Pascal-cased domain modules with lower-camel operations:
 - `Organizations`
 - `ScheduledMessages`
 - `Templates`
-- `UnsubscribeGroups`
+- `Topics`
 - `Webhooks`
 - `Whoami`
 
@@ -316,10 +319,10 @@ const allContacts = Stream.runCollect(Contacts.list.items());
 const firstFifty = Stream.runCollect(Contacts.list.items().pipe(Stream.take(50)));
 
 // Caller params (start cursor, limit, filters) are respected:
-const recent = Contacts.list.items({ limit: "100", after: "2026-01-01T00:00:00Z" });
+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. 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.
+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. Pass `limit` as a number; both clients serialize it as a query string. A list bounded by design, such as `CustomFields.list`, answers `{ items }` in one response and carries no companions. Stream pagination is Effect-only.
 
 ### Redacted secrets
 
@@ -397,7 +400,7 @@ const message =
 
 ```typescript
 const response = await client.conversations.list({
-  limit: "20",
+  limit: 20,
   status: "active",
 });
 ```
@@ -428,7 +431,11 @@ const campaign = await client.campaigns.create({
     channel: "email",
     email: { subject: "What's new", html: "<h1>Updates</h1>" },
   },
-  audience: { includeTags: ["subscribers"], excludeTags: ["bounced"] },
+  audience: {
+    topicId: "unsub_1234567890abcdef",
+    includeTags: ["subscribers"],
+    excludeTags: ["bounced"],
+  },
 });
 
 const run = await client.campaigns.scheduleRun({