@sendora/sdk 1.1.0 → 2.1.0

package/dist/webhook-verify.js

@@ -15,11 +15,13 @@ const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 /**
  * Checks a webhook request came from Sendora and answers its event, typed
- * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>`,
- * the hex an HMAC-SHA256 with your secret over `<t>.<raw body>`; the
- * timestamp is inside the signed text, so a captured request cannot be
- * replayed after the tolerance. Throws `SendoraError` with
- * `invalid_signature` or `stale_signature`.
+ * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]`,
+ * one hex per live secret of the webhook, each an HMAC-SHA256 with that
+ * secret over `<t>.<raw body>`; the one your secret produces is enough, so
+ * a secret being rolled in verifies as well as the old one. The timestamp
+ * is inside the signed text, so a captured request cannot be replayed
+ * after the tolerance. Throws `SendoraError` with `invalid_signature` or
+ * `stale_signature`.
  *
  * @example
  * const event = await verifyWebhook({
@@ -48,32 +50,51 @@ export async function verifyWebhook(input) {
     const body = typeof input.body === 'string' ? encoder.encode(input.body) : input.body;
     const signed = concat(encoder.encode(`${String(signature.timestamp)}.`), body);
     const key = await crypto.subtle.importKey('raw', encoder.encode(input.secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
-    if (!(await crypto.subtle.verify('HMAC', key, signature.mac, signed))) {
-        throw invalidSignature('The signature does not match the body.');
+    // Every signature is checked, so the time taken says nothing about which one matched.
+    let matched = false;
+    for (const mac of signature.macs) {
+        matched = (await crypto.subtle.verify('HMAC', key, mac, signed)) || matched;
+    }
+    if (!matched) {
+        throw invalidSignature('No signature in the header matches the body under this secret.');
     }
     return parseEvent(decoder.decode(body));
 }
+/** The timestamp and every `v1` value, one per live secret of the webhook. */
 function parseSignature(header) {
     if (typeof header !== 'string' || header === '') {
         throw invalidSignature('The request carries no Sendora-Signature header.');
     }
-    const parts = new Map();
+    let timestamp;
+    const macs = [];
     for (const part of header.split(',')) {
         const separator = part.indexOf('=');
-        if (separator > 0) {
-            parts.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+        if (separator <= 0) {
+            continue;
+        }
+        const name = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (name === 't') {
+            timestamp = Number(value);
+        }
+        else if (name === 'v1') {
+            if (!MAC_HEX.test(value)) {
+                throw invalidSignature('The Sendora-Signature header is malformed.');
+            }
+            macs.push(bytesOf(value));
         }
     }
-    const timestamp = Number(parts.get('t'));
-    const hex = parts.get('v1');
-    if (!Number.isInteger(timestamp) || hex === undefined || !MAC_HEX.test(hex)) {
+    if (timestamp === undefined || !Number.isInteger(timestamp) || macs.length === 0) {
         throw invalidSignature('The Sendora-Signature header is malformed.');
     }
-    const mac = new Uint8Array(hex.length / 2);
-    for (let i = 0; i < mac.length; i += 1) {
-        mac[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    return { timestamp, macs };
+}
+function bytesOf(hex) {
+    const bytes = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < bytes.length; i += 1) {
+        bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
     }
-    return { timestamp, mac };
+    return bytes;
 }
 function parseEvent(text) {
     let value;

package/dist/webhook-verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook-verify.js","sourceRoot":"","sources":["../src/webhook-verify.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhook-verify.js","sourceRoot":"","sources":["../src/webhook-verify.ts"],"names":[],"mappings":"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"}

package/dist/webhooks.d.ts

@@ -1,5 +1,5 @@
 import type { Transport } from './transport.ts';
-import type { CreatedWebhook, CreateWebhookRequest, Delivery, DeliveryPage, DeliveryQuery, ReceiveOptions, RequestOptions, Webhook, WebhookEvent, WebhookList } from './types.ts';
+import type { CreatedWebhook, CreatedWebhookSecret, CreateWebhookRequest, Delivery, DeliveryPage, DeliveryQuery, ReceiveOptions, RequestOptions, Webhook, WebhookEvent, WebhookList } from './types.ts';
 /** Where the server's events are posted, every delivery of them, and the receiving side. */
 export declare class WebhooksResource {
     #private;
@@ -23,6 +23,18 @@ export declare class WebhooksResource {
     get(webhookId: string, options?: RequestOptions): Promise<Webhook>;
     /** Removes the webhook; deliveries still pending are dropped with it. */
     delete(webhookId: string, options?: RequestOptions): Promise<void>;
+    /**
+     * Adds a second live secret and answers its value once. Every delivery
+     * then carries one signature per live secret, the newest first, so
+     * switch your receiver to the new secret and delete the old one; a third
+     * is refused with `secret_limit`.
+     *
+     *
+     * const { secret, secretId } = await sendora.webhooks.createSecret(webhookId);
+     */
+    createSecret(webhookId: string, options?: RequestOptions): Promise<CreatedWebhookSecret>;
+    /** Deletes a secret; deliveries are no longer signed with it. The last live secret is refused (`last_secret`). */
+    deleteSecret(webhookId: string, secretId: string, options?: RequestOptions): Promise<void>;
     /**
      * One page of the events handed to the webhook, newest first, with the
      * outcome of the last attempt; `status` narrows to `pending`,

package/dist/webhooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,OAAO,EACP,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,4FAA4F;AAC5F,qBAAa,gBAAgB;;gBAGf,SAAS,EAAE,SAAS;IAIhC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAU5F,mCAAmC;IACnC,IAAI,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IASxD,yBAAyB;IACzB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAStE,yEAAyE;IACzE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAStE;;;;;;;OAOG;IACH,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,aAAkB,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAUxB,uEAAuE;IACvE,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,aAAkB,EACzB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAAC,QAAQ,CAAC;IAS1B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAS9F;;;;;;;;;;;;;;OAcG;IACG,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC;CAQzB"}
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACpB,oBAAoB,EACpB,QAAQ,EACR,YAAY,EACZ,aAAa,EACb,cAAc,EACd,cAAc,EACd,OAAO,EACP,YAAY,EACZ,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,4FAA4F;AAC5F,qBAAa,gBAAgB;;gBAGf,SAAS,EAAE,SAAS;IAIhC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IAU5F,mCAAmC;IACnC,IAAI,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IASxD,yBAAyB;IACzB,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,OAAO,CAAC;IAStE,yEAAyE;IACzE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAStE;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAS5F,kHAAkH;IAClH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9F;;;;;;;OAOG;IACH,UAAU,CACR,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,aAAkB,EACzB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC;IAUxB,uEAAuE;IACvE,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,aAAkB,EACzB,OAAO,GAAE,cAAmB,GAC3B,aAAa,CAAC,QAAQ,CAAC;IAS1B;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAS9F;;;;;;;;;;;;;;OAcG;IACG,OAAO,CACX,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC;CAQzB"}

package/dist/webhooks.js

@@ -54,6 +54,32 @@ export class WebhooksResource {
             signal: options.signal,
         });
     }
+    /**
+     * Adds a second live secret and answers its value once. Every delivery
+     * then carries one signature per live secret, the newest first, so
+     * switch your receiver to the new secret and delete the old one; a third
+     * is refused with `secret_limit`.
+     *
+     *
+     * const { secret, secretId } = await sendora.webhooks.createSecret(webhookId);
+     */
+    createSecret(webhookId, options = {}) {
+        return this.#transport.request({
+            method: 'POST',
+            path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets`,
+            idempotent: false,
+            signal: options.signal,
+        });
+    }
+    /** Deletes a secret; deliveries are no longer signed with it. The last live secret is refused (`last_secret`). */
+    deleteSecret(webhookId, secretId, options = {}) {
+        return this.#transport.request({
+            method: 'DELETE',
+            path: `/v1/webhooks/${encodeURIComponent(webhookId)}/secrets/${encodeURIComponent(secretId)}`,
+            idempotent: true,
+            signal: options.signal,
+        });
+    }
     /**
      * One page of the events handed to the webhook, newest first, with the
      * outcome of the last attempt; `status` narrows to `pending`,

package/dist/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../src/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAe3C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,4FAA4F;AAC5F,MAAM,OAAO,gBAAgB;IAClB,UAAU,CAAY;IAE/B,YAAY,SAAoB;QAC9B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAA6B,EAAE,UAA0B,EAAE;QAChE,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAiB;YAC7C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,cAAc;YACpB,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED,mCAAmC;IACnC,IAAI,CAAC,UAA0B,EAAE;QAC/B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAc;YAC1C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,cAAc;YACpB,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED,yBAAyB;IACzB,GAAG,CAAC,SAAiB,EAAE,UAA0B,EAAE;QACjD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAU;YACtC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE;YACrD,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED,yEAAyE;IACzE,MAAM,CAAC,SAAiB,EAAE,UAA0B,EAAE;QACpD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAY;YACxC,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE;YACrD,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAiB,EAAE,UAA0B,EAAE;QAC1D,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAuB;YACnD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,UAAU;YAC7D,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED,kHAAkH;IAClH,YAAY,CAAC,SAAiB,EAAE,QAAgB,EAAE,UAA0B,EAAE;QAC5E,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAY;YACxC,MAAM,EAAE,QAAQ;YAChB,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,YAAY,kBAAkB,CAAC,QAAQ,CAAC,EAAE;YAC7F,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,UAAU,CACR,SAAiB,EACjB,QAAuB,EAAE,EACzB,UAA0B,EAAE;QAE5B,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAe;YAC3C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,aAAa;YAChE,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE;YACvE,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED,uEAAuE;IACvE,aAAa,CACX,SAAiB,EACjB,QAAuB,EAAE,EACzB,UAA0B,EAAE;QAE5B,OAAO,QAAQ,CACb,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,EAAE,GAAG,KAAK,EAAE,KAAK,EAAE,EAAE,OAAO,CAAC,EACnE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,EACzB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EACnB,KAAK,CAAC,KAAK,CACZ,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,SAAiB,EAAE,UAAkB,EAAE,UAA0B,EAAE;QACxE,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAW;YACvC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,eAAe,kBAAkB,CAAC,UAAU,CAAC,SAAS;YACzG,UAAU,EAAE,KAAK;YACjB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,OAAO,CACX,OAAgB,EAChB,MAA0B,EAC1B,UAA0B,EAAE;QAE5B,OAAO,aAAa,CAAC;YACnB,MAAM;YACN,SAAS,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;YACnD,IAAI,EAAE,IAAI,UAAU,CAAC,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC;YACjD,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;SAC3C,CAAC,CAAC;IACL,CAAC;CACF"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sendora/sdk",
-  "version": "1.1.0",
-  "description": "The official TypeScript SDK for Sendora, transactional email delivery hosted in Sweden.",
+  "version": "2.1.0",
+  "description": "The official TypeScript SDK for Sendora, transactional email delivery.",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -21,11 +21,6 @@
   "engines": {
     "node": ">=20.19"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hornta/sendora.git",
-    "directory": "sdks/typescript"
-  },
   "homepage": "https://sendora.se/docs",
   "keywords": [
     "sendora",
@@ -38,10 +33,10 @@
     "typescript": "~6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.6.2",
+    "@sendora/observability": "0.0.0",
     "@sendora/api": "0.0.0",
-    "@sendora/db": "0.0.0",
     "@sendora/domain": "0.0.0",
-    "@sendora/observability": "0.0.0"
+    "@sendora/db": "0.0.0"
   },
   "scripts": {
     "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json"

package/skills/sendora/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sendora
-description: Send transactional email through Sendora with @sendora/sdk, read the message log, manage streams, suppressions, tokens, webhooks and sending domains, and receive signed webhooks. Use when a task mentions Sendora, @sendora/sdk, or sending email from a system hosted in Sweden.
+description: Send transactional email through Sendora with @sendora/sdk, read the message log, manage streams, suppressions, keys, webhooks, servers and sending domains, and receive signed webhooks. Use when a task mentions Sendora, @sendora/sdk, or sending email from a system hosted in Sweden.
 ---
 
 # Sendora
@@ -12,12 +12,20 @@ complete reference; every call, every error code and every event is in it.
 
 ## Rules
 
-- The API token is a secret. Read it from the environment on the server
-  and never send it to a browser. `new Sendora({ token })` throws when the
-  token is missing, so construct the client at startup.
-- One client per server token: `const sendora = new Sendora({ token })`.
-  Every resource hangs off it: `email`, `messages`, `streams`,
-  `suppressions`, `tokens`, `webhooks`, `domains`.
+- Two kinds of key, two clients. A server key (`sk_…`) drives
+  `new Sendora({ token })`: `email`, `messages`, `inbound`, `streams`,
+  `suppressions`, `tokens`, `webhooks`, `inboundDomains`, everything inside
+  one server. An account key (`ak_…`) drives `new SendoraAccount({ token })`:
+  `servers`, `servers.tokens` and `domains`, and it never sends. A key of
+  the wrong kind throws `wrong_token_kind`.
+- Every key is a secret. Read it from the environment on the server and
+  never send it to a browser. Either client throws when its key is
+  missing, so construct it at startup.
+- A server is created with its first key: `account.servers.create({ name })`
+  answers `token.token` once, and `new Sendora({ token })` sends with it. A
+  server or the account holds at most two live keys, so rotate by creating
+  the new key, switching to it, then revoking the old one; the last live
+  key can never be revoked.
 - Every method takes what the route takes and answers what the route
   answers. Do not build request bodies by hand or call `fetch` yourself.
 - Do not add idempotency keys or retry loops of your own. The SDK gives
@@ -40,8 +48,10 @@ complete reference; every call, every error code and every event is in it.
   `suppressions.delete({ address })`; a spam complaint cannot be lifted by
   the customer. Lists are per stream: pass `streamId` when the send went on
   a stream other than the default.
-- `from` must be on a verified sending domain; `domains.create` answers
-  the two DNS records to add, and `domains.verify` checks them now.
+- `from` must be on a verified sending domain of the account;
+  `account.domains.create` answers the two DNS records to add, and
+  `account.domains.verify` checks them now. A server key cannot manage
+  domains.
 - A message goes on the server's default transactional stream unless it
   names another with `streamId`; `streams.create` adds one. Never make a
   stream per message or per customer; a stream is a kind of mail.

package/src/account.ts

@@ -0,0 +1,40 @@
+import { DomainsResource } from './domains.ts';
+import { transportFor, type ClientOptions } from './options.ts';
+import { ServersResource } from './servers.ts';
+
+export interface SendoraAccountOptions extends ClientOptions {
+  /**
+   * An account key (`ak_…`), created by an administrator in the dashboard.
+   * It manages the account and never sends. Keep it on the server; never
+   * ship it to a browser. `undefined`, as an unset environment variable
+   * gives, throws at construction rather than at the first call.
+   */
+  token: string | undefined;
+}
+
+/**
+ * The account client: the servers, each server's keys and the sending
+ * domains, under an account key. Sending, the log, streams, suppressions
+ * and webhooks belong to a server and to `Sendora` with a server key.
+ *
+ * @example
+ * import { Sendora, SendoraAccount } from '@sendora/sdk';
+ *
+ * const account = new SendoraAccount({ token: process.env.SENDORA_ACCOUNT_TOKEN });
+ * const server = await account.servers.create({ name: 'Fakturering' });
+ * const sendora = new Sendora({ token: server.token.token });
+ */
+export class SendoraAccount {
+  readonly servers: ServersResource;
+  readonly domains: DomainsResource;
+
+  constructor(options: SendoraAccountOptions) {
+    const transport = transportFor(
+      options.token,
+      options,
+      'SendoraAccount needs an account key (ak_…); an administrator creates one in the dashboard.',
+    );
+    this.servers = new ServersResource(transport);
+    this.domains = new DomainsResource(transport);
+  }
+}

package/src/client.ts

@@ -1,37 +1,28 @@
-import { DomainsResource } from './domains.ts';
 import { BroadcastsResource } from './broadcasts.ts';
 import { EmailResource } from './email.ts';
+import { InboundResource } from './inbound.ts';
+import { InboundDomainsResource } from './inbound-domains.ts';
 import { MessagesResource } from './messages.ts';
-import { DEFAULT_MAX_RETRIES } from './retry.ts';
+import { transportFor, type ClientOptions } from './options.ts';
 import { StreamsResource } from './streams.ts';
 import { SuppressionsResource } from './suppressions.ts';
 import { TokensResource } from './tokens.ts';
-import { Transport } from './transport.ts';
-import { SDK_VERSION } from './version.ts';
 import { WebhooksResource } from './webhooks.ts';
 
-export const DEFAULT_BASE_URL = 'https://api.sendora.se';
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-export interface SendoraOptions {
+export interface SendoraOptions extends ClientOptions {
   /**
-   * A server's API token, created in the dashboard. Keep it on the server;
-   * never ship it to a browser. `undefined`, as an unset environment
-   * variable gives, throws at construction rather than at the first call.
+   * A server key (`sk_…`), answered once when the server is created or a
+   * key is added to it. Keep it on the server; never ship it to a browser.
+   * `undefined`, as an unset environment variable gives, throws at
+   * construction rather than at the first call.
    */
   token: string | undefined;
-  /** The API's origin; https://api.sendora.se unless you test against another. */
-  baseUrl?: string | undefined;
-  /** The fetch to use; the global one unless you need a proxy or a fake. */
-  fetch?: typeof fetch | undefined;
-  /** How long one attempt may take; 30 seconds by default. */
-  timeoutMs?: number | undefined;
-  /** How many times a failed call is repeated when repeating is safe; 2 by default, 0 turns retries off. */
-  maxRetries?: number | undefined;
 }
 
 /**
- * The client. One instance per server token; every resource hangs off it.
+ * The server client. One instance per server key; every resource of the
+ * server hangs off it. The account's servers and sending domains are
+ * `SendoraAccount` with an account key.
  *
  * @example
  * import { Sendora } from '@sendora/sdk';
@@ -48,41 +39,27 @@ export class Sendora {
   readonly email: EmailResource;
   readonly broadcasts: BroadcastsResource;
   readonly messages: MessagesResource;
+  readonly inbound: InboundResource;
+  readonly inboundDomains: InboundDomainsResource;
   readonly streams: StreamsResource;
   readonly suppressions: SuppressionsResource;
   readonly tokens: TokensResource;
   readonly webhooks: WebhooksResource;
-  readonly domains: DomainsResource;
 
   constructor(options: SendoraOptions) {
-    if (options.token === undefined || options.token.trim() === '') {
-      throw new TypeError('Sendora needs a server API token; create one in the dashboard.');
-    }
-    const baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
-    new URL(baseUrl);
-    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    if (!(timeoutMs > 0)) {
-      throw new TypeError('timeoutMs must be a positive number of milliseconds.');
-    }
-    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
-    if (!Number.isInteger(maxRetries) || maxRetries < 0) {
-      throw new TypeError('maxRetries must be a whole number of zero or more.');
-    }
-    const transport = new Transport({
-      baseUrl,
-      token: options.token,
-      fetch: options.fetch ?? fetch,
-      timeoutMs,
-      maxRetries,
-      userAgent: `sendora-sdk/${SDK_VERSION}`,
-    });
+    const transport = transportFor(
+      options.token,
+      options,
+      'Sendora needs a server key (sk_…); it is shown once when the server or the key is created.',
+    );
     this.email = new EmailResource(transport);
     this.broadcasts = new BroadcastsResource(transport);
     this.messages = new MessagesResource(transport);
+    this.inbound = new InboundResource(transport);
+    this.inboundDomains = new InboundDomainsResource(transport);
     this.streams = new StreamsResource(transport);
     this.suppressions = new SuppressionsResource(transport);
     this.tokens = new TokensResource(transport);
     this.webhooks = new WebhooksResource(transport);
-    this.domains = new DomainsResource(transport);
   }
 }

package/src/domains.ts

@@ -7,7 +7,7 @@ import type {
   VerifiedDomain,
 } from './types.ts';
 
-/** The account's sending domains and the two DNS records each one needs. Any server's token manages them. */
+/** The account's sending domains and the two DNS records each one needs, managed with the account key; every server sends from them. */
 export class DomainsResource {
   readonly #transport: Transport;
 

package/src/error.ts

@@ -1,9 +1,10 @@
 import type { LimitScope, SuppressedRecipient, ValidationIssue } from './types.ts';
 
-/** Every code the API answers, the three the SDK raises when it never got a proper answer, and the two of the webhook verifier. */
+/** Every code the API answers, under either kind of key, the three the SDK raises when it never got a proper answer, and the two of the webhook verifier. */
 export type SendoraErrorCode =
   | 'invalid_request'
   | 'unauthorized'
+  | 'wrong_token_kind'
   | 'payment_required'
   | 'tenant_paused'
   | 'tenant_not_active'
@@ -11,11 +12,20 @@ export type SendoraErrorCode =
   | 'unsubscribe_locked'
   | 'not_found'
   | 'domain_exists'
+  | 'domain_reserved'
+  | 'inbound_domain_exists'
   | 'webhook_exists'
   | 'stream_exists'
   | 'inbound_stream_exists'
   | 'default_stream'
   | 'last_token'
+  | 'token_limit'
+  | 'last_secret'
+  | 'secret_limit'
+  | 'server_exists'
+  | 'server_limit'
+  | 'server_reserved'
+  | 'server_in_flight'
   | 'request_too_large'
   | 'from_domain_not_verified'
   | 'stream_not_found'
@@ -28,6 +38,8 @@ export type SendoraErrorCode =
   | 'substitution_missing'
   | 'unsubscribe_placeholder_missing'
   | 'list_unsubscribe_reserved'
+  | 'content_expired'
+  | 'content_unreadable'
   | 'recipient_suppressed'
   | 'idempotency_key_mismatch'
   | 'idempotency_key_required'
@@ -43,6 +55,7 @@ export type SendoraErrorCode =
 const apiCodes: ReadonlySet<string> = new Set<SendoraErrorCode>([
   'invalid_request',
   'unauthorized',
+  'wrong_token_kind',
   'payment_required',
   'tenant_paused',
   'tenant_not_active',
@@ -50,11 +63,20 @@ const apiCodes: ReadonlySet<string> = new Set<SendoraErrorCode>([
   'unsubscribe_locked',
   'not_found',
   'domain_exists',
+  'domain_reserved',
+  'inbound_domain_exists',
   'webhook_exists',
   'stream_exists',
   'inbound_stream_exists',
   'default_stream',
   'last_token',
+  'token_limit',
+  'last_secret',
+  'secret_limit',
+  'server_exists',
+  'server_limit',
+  'server_reserved',
+  'server_in_flight',
   'request_too_large',
   'from_domain_not_verified',
   'stream_not_found',
@@ -67,6 +89,8 @@ const apiCodes: ReadonlySet<string> = new Set<SendoraErrorCode>([
   'substitution_missing',
   'unsubscribe_placeholder_missing',
   'list_unsubscribe_reserved',
+  'content_expired',
+  'content_unreadable',
   'recipient_suppressed',
   'idempotency_key_mismatch',
   'idempotency_key_required',
@@ -85,6 +109,7 @@ export interface SendoraErrorFields {
   cap?: number | null;
   used?: number | null;
   resetsAt?: string | null;
+  max?: number | null;
   issues?: ValidationIssue[];
   suppressed?: SuppressedRecipient[];
   streamId?: string | null;
@@ -124,13 +149,15 @@ export class SendoraError extends Error {
   readonly used: number | null;
   /** When the month counter resets, on monthly_cap_reached. */
   readonly resetsAt: string | null;
+  /** Live keys the server or the account may hold, on token_limit; servers the account may have, on server_limit; live secrets a webhook may hold, on secret_limit. */
+  readonly max: number | null;
   /** One entry per invalid field, on invalid_request. */
   readonly issues: ValidationIssue[];
   /** The recipients the server refused, on recipient_suppressed. */
   readonly suppressed: SuppressedRecipient[];
   /** The stream whose suppression list refused the send, on recipient_suppressed. */
   readonly streamId: string | null;
-  /** The id of the domain, webhook or stream that already exists, on domain_exists, webhook_exists and stream_exists. */
+  /** The id of the domain, webhook or stream that already exists, on domain_exists, webhook_exists, stream_exists, inbound_stream_exists and, when the stream already has a domain, inbound_domain_exists. */
   readonly existingId: string | null;
 
   constructor(fields: SendoraErrorFields) {
@@ -143,6 +170,7 @@ export class SendoraError extends Error {
     this.cap = fields.cap ?? null;
     this.used = fields.used ?? null;
     this.resetsAt = fields.resetsAt ?? null;
+    this.max = fields.max ?? null;
     this.issues = fields.issues ?? [];
     this.suppressed = fields.suppressed ?? [];
     this.streamId = fields.streamId ?? null;
@@ -172,6 +200,7 @@ export class SendoraError extends Error {
       cap: this.cap,
       used: this.used,
       resetsAt: this.resetsAt,
+      max: this.max,
       issues: this.issues,
       suppressed: this.suppressed,
       streamId: this.streamId,
@@ -205,11 +234,15 @@ export function errorFromAnswer(
     cap: integerOf(answer.cap),
     used: integerOf(answer.used),
     resetsAt: typeof answer.resetsAt === 'string' ? answer.resetsAt : null,
+    max: integerOf(answer.max) ?? integerOf(answer.maxServers),
     issues,
     suppressed: Array.isArray(answer.suppressed) ? answer.suppressed.filter(isSuppressed) : [],
     streamId: code === 'recipient_suppressed' ? stringOf(answer.streamId) : null,
     existingId:
-      stringOf(answer.domainId) ?? stringOf(answer.webhookId) ?? stringOf(answer.streamId),
+      stringOf(answer.domainId) ??
+      stringOf(answer.webhookId) ??
+      stringOf(answer.streamId) ??
+      stringOf(answer.inboundDomainId),
   });
 }
 

package/src/inbound-domains.ts

@@ -0,0 +1,89 @@
+import type { Transport } from './transport.ts';
+import type {
+  CreateInboundDomainRequest,
+  InboundDomain,
+  InboundDomainList,
+  RequestOptions,
+  VerifiedInboundDomain,
+} from './types.ts';
+
+/** The server's own domains for receiving: one per inbound stream, catch-all, with the two DNS records each one needs. */
+export class InboundDomainsResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Claims a domain for an inbound stream and answers the two records to
+   * create: an MX that brings the domain's mail to Sendora and a TXT
+   * record that proves the claim. Mail is accepted once both are seen.
+   * `domain_reserved` is a name of Sendora's own; `inbound_domain_exists`
+   * is a stream that already has a domain (`existingId` names it) or a
+   * name another account holds verified.
+   *
+   * @example
+   * const domain = await sendora.inboundDomains.create({ streamId, domain: 'post.example.se' });
+   * console.log(domain.mx.host, domain.mx.value);
+   * console.log(domain.txt.host, domain.txt.value);
+   */
+  create(
+    request: CreateInboundDomainRequest,
+    options: RequestOptions = {},
+  ): Promise<InboundDomain> {
+    return this.#transport.request<InboundDomain>({
+      method: 'POST',
+      path: '/v1/inbound/domains',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every inbound domain of the token's server. */
+  list(options: RequestOptions = {}): Promise<InboundDomainList> {
+    return this.#transport.request<InboundDomainList>({
+      method: 'GET',
+      path: '/v1/inbound/domains',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One domain by id, with the state of its records. */
+  get(inboundDomainId: string, options: RequestOptions = {}): Promise<InboundDomain> {
+    return this.#transport.request<InboundDomain>({
+      method: 'GET',
+      path: `/v1/inbound/domains/${encodeURIComponent(inboundDomainId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Looks both records up now and answers the domain as it stands plus
+   * what each lookup found: `ok`, `missing`, `mismatch` or `dns_error`.
+   *
+   * @example
+   * const { verified, check } = await sendora.inboundDomains.verify(inboundDomainId);
+   */
+  verify(inboundDomainId: string, options: RequestOptions = {}): Promise<VerifiedInboundDomain> {
+    return this.#transport.request<VerifiedInboundDomain>({
+      method: 'POST',
+      path: `/v1/inbound/domains/${encodeURIComponent(inboundDomainId)}/verify`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** Removes the domain; mail to it is refused from then on, and the name is free for another claim. */
+  delete(inboundDomainId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/inbound/domains/${encodeURIComponent(inboundDomainId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}