@sendora/sdk 1.1.0

package/README.md

@@ -0,0 +1,364 @@
+# @sendora/sdk
+
+The official TypeScript SDK for [Sendora](https://sendora.se), transactional
+email delivery hosted in Sweden. Zero dependencies. Runs on Node 20.19 or
+newer and on any runtime with `fetch` and WebCrypto: Bun, Deno, Cloudflare
+Workers. ESM only; CommonJS projects on Node 20.19 or 22.12 and newer load it
+with `require`.
+
+```sh
+npm install @sendora/sdk
+```
+
+The token is a secret. Create it in the dashboard, keep it on the server,
+and never ship it to a browser. The client throws at construction when the
+token is missing, so build it at startup.
+
+```ts
+import { Sendora } from '@sendora/sdk';
+
+const sendora = new Sendora({ token: process.env.SENDORA_API_TOKEN });
+
+const { messageId } = await sendora.email.send({
+  from: { email: 'no-reply@example.se', name: 'Example AB' },
+  to: ['anna@example.com'],
+  subject: 'Din faktura för september',
+  text: 'Hej Anna, fakturan finns bifogad.',
+  attachments: [{ name: 'faktura.pdf', content: pdfBytes, contentType: 'application/pdf' }],
+  tag: 'invoice',
+  metadata: { invoiceId: '2026-0912' },
+});
+```
+
+`from` must be on a verified sending domain. `to`, `cc` and `bcc` take
+plain addresses or objects with a display name, at most 50 in all; at least
+one of `text` and `html` is required. `streamId` names the stream of the
+server the message goes on; without it the default transactional stream. Attachments take bytes (`Uint8Array`,
+so a Node `Buffer` too) or a base64 string. Every method takes what the
+route takes and answers what the route answers; every call accepts an
+`options.signal` to cancel it.
+
+## Sending
+
+| Call                                          | Answers                                                                    |
+| --------------------------------------------- | -------------------------------------------------------------------------- |
+| `sendora.email.send(message, options?)`       | `{ messageId, status: 'accepted', submittedAt }`                           |
+| `sendora.email.sendBatch(messages, options?)` | `{ results }`, one per message in order, `accepted` with its id or `error` |
+
+`accepted` means the message is stored and on its way to the mail server;
+delivery, deferral, bounce and complaint arrive later as events on the
+message and as webhooks.
+
+`options.idempotencyKey` names the request so a retry cannot send twice.
+The SDK makes a random UUID when you give none; give your own when a retry
+may come from another process. The API remembers a key for 24 hours and
+refuses it with a different body (`idempotency_key_mismatch`).
+
+A batch never fails halfway. Each result is `status: 'accepted'` with the
+id, or `status: 'error'` with the same `error` code a single send would
+throw; a retried batch answers the items sent before with `replayed: true`.
+
+```ts
+const { results } = await sendora.email.sendBatch(messages, { idempotencyKey: 'invoices-2026-09' });
+for (const result of results) {
+  if (result.status === 'error') {
+    console.log(result.index, result.error, result.message);
+  }
+}
+```
+
+## Messages
+
+| Call                                   | Answers                                                                     |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| `sendora.messages.get(messageId)`      | The message with its recipients, its attachments described and its timeline |
+| `sendora.messages.search(filters?)`    | `{ messages, next }`, one page newest first                                 |
+| `sendora.messages.searchAll(filters?)` | Every match, page by page, for `for await`                                  |
+
+Filters: `recipient`, `streamId`, `tag`, `status` (`queued`, `delivered`,
+`deferred`, `bounced`, `expired`), `from` and `to` as `Date` or ISO 8601,
+`limit` (1 to 100), `after`. Bodies are never returned; the log keeps messages for 13
+months.
+
+```ts
+const message = await sendora.messages.get(messageId);
+const delivered = message.recipients.every((recipient) => recipient.status === 'delivered');
+
+for await (const bounced of sendora.messages.searchAll({
+  status: 'bounced',
+  from: new Date('2026-09-01'),
+})) {
+  console.log(bounced.messageId, bounced.subject);
+}
+```
+
+## Streams
+
+Every message goes on a stream of its server. A server starts with a
+default transactional stream, and the account adds more: transactional
+ones for every account, broadcast ones once Sendora has enabled broadcast
+for the account, which an administrator applies for under Broadcast in
+the dashboard, and one inbound stream, which receives mail at its
+`inboundAddress` instead of sending. Each sending stream has a
+suppression list of its own.
+
+| Call                                                               | Answers                                                                                                              |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `sendora.streams.create({ kind, name })`                           | The stream; a taken name is `stream_exists`, a second inbound stream `inbound_stream_exists`, both with `existingId` |
+| `sendora.streams.list()`                                           | `{ streams }`, archived ones included                                                                                |
+| `sendora.streams.get(streamId)`                                    | One stream                                                                                                           |
+| `sendora.streams.update(streamId, { name, contentRetentionDays })` | The updated stream; the days apply to an inbound stream                                                              |
+| `sendora.streams.archive(streamId)`                                | The stream with `archivedAt`; it takes no new messages from then on                                                  |
+
+```ts
+const stream = await sendora.streams.create({ kind: 'transactional', name: 'Aviseringar' });
+await sendora.email.send({ ...message, streamId: stream.streamId });
+```
+
+## Broadcasts
+
+One message to many on a broadcast stream, sent as a whole: the content
+once and one entry per message, up to 50,000 and 50 MB per broadcast.
+Every message is a message in the log with its own events and webhooks,
+carrying the `broadcastId`, and every recipient gets their own
+unsubscribe link where `{{ unsubscribe_url }}` stands. Addresses on the
+stream's suppression list are dropped and counted in `suppressed`. The
+SDK sets an idempotency key, so a retry answers the same broadcast. A
+message's `substitutions`, up to 20 strings, replace `{{ key }}` in the
+subject, the text and the HTML, escaped in the HTML; a key the content
+names that a message lacks throws `substitution_missing`.
+
+| Call                                           | Answers                                                       |
+| ---------------------------------------------- | ------------------------------------------------------------- |
+| `sendora.broadcasts.send(broadcast, options?)` | `{ broadcastId, total, suppressed }`; refused whole otherwise |
+| `sendora.broadcasts.get(broadcastId)`          | The broadcast with `status`, `released` and `failed`          |
+| `sendora.broadcasts.list({ limit?, after? })`  | `{ broadcasts, next }`, newest first                          |
+| `sendora.broadcasts.cancel(broadcastId)`       | The cancelled broadcast; what had not left counts as failed   |
+
+```ts
+const { broadcastId } = await sendora.broadcasts.send({
+  streamId: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
+  from: { email: 'nyheter@example.se', name: 'Example AB' },
+  subject: 'Nyheter i oktober',
+  text: 'Hej! Här är månadens nyheter. Vill du inte ha fler? {{ unsubscribe_url }}',
+  messages: ['anna@example.com', 'bo@example.com'].map((email) => ({ to: [email] })),
+});
+const progress = await sendora.broadcasts.get(broadcastId);
+```
+
+## Suppressions
+
+Addresses the server no longer sends to: hard bounces, spam complaints and
+entries added by hand. A send to one of them throws `recipient_suppressed`.
+
+| Call                                                       | Answers                                   |
+| ---------------------------------------------------------- | ----------------------------------------- |
+| `sendora.suppressions.list({ streamId?, limit?, after? })` | `{ suppressions, next }`, newest first    |
+| `sendora.suppressions.listAll({ streamId? })`              | Every entry, for `for await`              |
+| `sendora.suppressions.delete({ address, streamId? })`      | Nothing; the address may be sent to again |
+
+Every stream has a list of its own; without `streamId` the calls mean the
+default transactional stream. A spam complaint or a recipient's own
+unsubscribe cannot be lifted this way (`spam_complaint_locked`,
+`unsubscribe_locked`); only Sendora support can, at the recipient's own
+request. A refused send carries `streamId` beside `suppressed`.
+
+```ts
+await sendora.suppressions.delete({ address: 'anna@example.com' });
+```
+
+## Tokens
+
+Every token of a server has the same rights; the value is shown once, when
+it is created.
+
+| Call                              | Answers                                                |
+| --------------------------------- | ------------------------------------------------------ |
+| `sendora.tokens.create({ name })` | The token with its `token` value, once                 |
+| `sendora.tokens.list()`           | `{ tokens }`, revoked ones included                    |
+| `sendora.tokens.get(tokenId)`     | One token, without its value                           |
+| `sendora.tokens.revoke(tokenId)`  | Nothing; the last live token is refused (`last_token`) |
+
+## Webhooks
+
+An https URL of yours that Sendora posts events to as they happen, signed
+with a secret shown once at creation.
+
+| Call                                                     | Answers                                          |
+| -------------------------------------------------------- | ------------------------------------------------ |
+| `sendora.webhooks.create({ url, events?, streamId? })`   | The webhook with its `secret`, once              |
+| `sendora.webhooks.list()`                                | `{ webhooks }`                                   |
+| `sendora.webhooks.get(webhookId)`                        | One webhook                                      |
+| `sendora.webhooks.delete(webhookId)`                     | Nothing; pending deliveries are dropped          |
+| `sendora.webhooks.deliveries(webhookId, { status? })`    | `{ deliveries, next }`, newest first             |
+| `sendora.webhooks.deliveriesAll(webhookId, { status? })` | Every delivery, for `for await`                  |
+| `sendora.webhooks.replay(webhookId, deliveryId)`         | The delivery, queued again                       |
+| `sendora.webhooks.receive(request, secret)`              | The verified, typed event from a Fetch `Request` |
+
+Events: `delivered`, `bounced`, `deferred`, `spam_complaint` and
+`unsubscribed` about a message, with `messageId`, `streamId`, `recipient`,
+`occurredAt`, `serverId`, your `tag` and `metadata`, and `details` from the
+receiver, or for `unsubscribed` the `source` (`link` or `one_click`);
+`cap_warning` and `cap_reached` about usage, with `scope`, `cap`, `used`
+and the period; `inbound` about a message received on an inbound stream,
+with `inboundMessageId`, `envelopeRecipient`, the sizes, the
+`authentication` verdicts and, for a webhook with `inboundContent:
+'full'`, the message itself: `from`, `to`, `subject`, `text`, `html`,
+`attachments` and the rest. Every event carries `id`, the delivery id,
+and `attempt`.
+
+A failed delivery is retried with growing delays for about a day, then it
+is `dead` until you replay it. Deliveries arrive at least once and not
+always in order, so key your handling on `event.id`.
+
+### Receiving
+
+Verify the signature before you parse anything, answer 2xx quickly, and do
+the work afterwards. With a framework that hands you a Fetch `Request`
+(Next.js route handlers, Hono, SvelteKit, Cloudflare Workers):
+
+```ts
+import { Sendora } from '@sendora/sdk';
+
+const sendora = new Sendora({ token: process.env.SENDORA_API_TOKEN });
+
+export async function POST(request: Request): Promise<Response> {
+  const event = await sendora.webhooks.receive(request, process.env.SENDORA_WEBHOOK_SECRET);
+  if (event.event === 'bounced' && event.details.hard) {
+    console.log(
+      `${event.recipient} is undeliverable: ${event.details.classification ?? 'unknown'}`,
+    );
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+With Express or Fastify, keep the raw body (`express.raw({ type: '*/*' })`
+or the raw-body plugin) and call the verifier directly:
+
+```ts
+import { verifyWebhook } from '@sendora/sdk';
+
+const event = await verifyWebhook({
+  secret: process.env.SENDORA_WEBHOOK_SECRET,
+  signature: req.headers['sendora-signature'],
+  body: req.body,
+});
+```
+
+The signature is `Sendora-Signature: t=<unix seconds>,v1=<hex>`, an
+HMAC-SHA256 with your secret over `<t>.<raw body>`, compared in constant
+time through WebCrypto. A signature older than five minutes is refused
+(`stale_signature`; `toleranceSeconds` changes the limit), a wrong one
+throws `invalid_signature`.
+
+## Domains
+
+Sending domains belong to the account, and every server sends from them.
+A domain sends once both DNS records are seen.
+
+| Call                                 | Answers                                                                      |
+| ------------------------------------ | ---------------------------------------------------------------------------- |
+| `sendora.domains.create({ domain })` | The domain with `returnPath` (CNAME) and `dkim` (TXT) to add                 |
+| `sendora.domains.list()`             | `{ domains }`                                                                |
+| `sendora.domains.get(domainId)`      | One domain with the state of its records                                     |
+| `sendora.domains.verify(domainId)`   | The domain plus `check` per record: `ok`, `missing`, `mismatch`, `dns_error` |
+| `sendora.domains.delete(domainId)`   | Nothing; mail from it is refused from then on                                |
+
+```ts
+const domain = await sendora.domains.create({ domain: 'example.se' });
+console.log(`${domain.returnPath.type} ${domain.returnPath.host} -> ${domain.returnPath.value}`);
+console.log(`${domain.dkim.type} ${domain.dkim.host} -> ${domain.dkim.value}`);
+```
+
+## Errors
+
+Every failed call throws `SendoraError`. Narrow on `code`:
+
+```ts
+import { SendoraError } from '@sendora/sdk';
+
+try {
+  await sendora.email.send(message);
+} catch (error) {
+  if (error instanceof SendoraError) {
+    switch (error.code) {
+      case 'recipient_suppressed':
+        // error.suppressed lists the addresses and why
+        break;
+      case 'rate_limited':
+        // error.retryAfter seconds; error.scope and error.limit say whose limit
+        break;
+      case 'invalid_request':
+        // error.issues, one { path, message } per field
+        break;
+    }
+  }
+  throw error;
+}
+```
+
+| Code                              | Status | Meaning                                                                   |
+| --------------------------------- | ------ | ------------------------------------------------------------------------- |
+| `invalid_request`                 | 400    | A field is wrong; `issues` says which.                                    |
+| `idempotency_key_required`        | 400    | A batch was sent without a key.                                           |
+| `unauthorized`                    | 401    | The token is missing, malformed or revoked.                               |
+| `payment_required`                | 402    | The account has no active subscription.                                   |
+| `tenant_paused`                   | 403    | Sendora has paused the account.                                           |
+| `tenant_not_active`               | 403    | The account is not approved to send, or not active for an inbound stream. |
+| `spam_complaint_locked`           | 403    | Only support can lift a spam-complaint suppression.                       |
+| `unsubscribe_locked`              | 403    | Only support can lift a recipient's own unsubscribe.                      |
+| `not_found`                       | 404    | No such id on this server, or no such suppressed address.                 |
+| `domain_exists`                   | 409    | The account already has the domain; `existingId` names it.                |
+| `webhook_exists`                  | 409    | The server already has a webhook for that URL; `existingId` names it.     |
+| `stream_exists`                   | 409    | The server already has a stream with that name; `existingId` names it.    |
+| `inbound_stream_exists`           | 409    | The server already has a live inbound stream; `existingId` names it.      |
+| `default_stream`                  | 409    | The default stream cannot be archived.                                    |
+| `last_token`                      | 409    | The only live token cannot be revoked.                                    |
+| `request_too_large`               | 413    | The body exceeds 10 MB.                                                   |
+| `from_domain_not_verified`        | 422    | The From domain is not a verified sending domain.                         |
+| `stream_not_found`                | 422    | `streamId` names no stream of this server.                                |
+| `stream_archived`                 | 422    | The stream is archived and takes no new messages.                         |
+| `stream_paused`                   | 422    | Sendora paused the stream after complaints; support resumes it.           |
+| `stream_not_sendable`             | 422    | An inbound stream receives mail; it takes no messages and has no list.    |
+| `stream_not_broadcast`            | 422    | A broadcast goes on a broadcast stream; this one is transactional.        |
+| `substitution_missing`            | 422    | The content names a `{{ key }}` a message does not give.                  |
+| `broadcast_not_open`              | 409    | The broadcast is completed or cancelled; nothing is left to cancel.       |
+| `broadcast_not_enabled`           | 422    | Broadcast is not enabled for the account: no broadcast stream, no send.   |
+| `unsubscribe_placeholder_missing` | 422    | A broadcast message lacks `{{ unsubscribe_url }}` in a part.              |
+| `list_unsubscribe_reserved`       | 422    | Sendora writes List-Unsubscribe on broadcast streams; leave it out.       |
+| `recipient_suppressed`            | 422    | Recipients on the suppression list; `suppressed` lists them.              |
+| `idempotency_key_mismatch`        | 422    | The key was used before with a different body.                            |
+| `rate_limited`                    | 429    | Per-minute limit; `retryAfter`, `scope`, `limit`.                         |
+| `monthly_cap_reached`             | 429    | The monthly cap is used up; `scope`, `cap`, `used`, `resetsAt`.           |
+| `sending_disabled`                | 503    | Sending is paused for everyone; `retryAfter`.                             |
+| `connection_failed`               | none   | The request never reached the API; `cause` holds the failure.             |
+| `timeout`                         | none   | No answer within `timeoutMs`.                                             |
+| `unexpected_response`             | any    | An answer without a JSON error body, such as from a proxy.                |
+| `invalid_signature`               | none   | A webhook's signature is missing, malformed or wrong.                     |
+| `stale_signature`                 | none   | A webhook's signature is older than the tolerance.                        |
+
+`error.retryable` is true when waiting and calling again could succeed.
+Neither the token nor a request body is ever part of an error.
+
+## Retries
+
+Lost connections, timeouts, `rate_limited`, `sending_disabled` and server
+errors are retried with jittered backoff, twice by default, honouring
+`retryAfter` when it fits within five seconds of waiting in all. A longer
+`retryAfter` is thrown at once for you to schedule. A request that creates
+something (`tokens.create`, `webhooks.create`, `domains.create`, `replay`)
+is repeated only after a `rate_limited` or `sending_disabled` answer, never
+after a lost connection, so nothing is created twice. Nothing else is
+retried. `new Sendora({ maxRetries: 0 })` turns retries off; `timeoutMs`
+sets the limit per attempt.
+
+## For coding agents
+
+The package ships `skills/sendora/SKILL.md`, a short guide in the agent
+skill format with the rules above; point your agent at it or at this
+README. Every exported symbol carries JSDoc with an example.
+
+## Docs
+
+Guides and the HTTP reference: [sendora.se/docs](https://sendora.se/docs).

package/dist/base64.d.ts

@@ -0,0 +1,3 @@
+/** Standard base64 without line breaks, as the API takes attachment content; needs nothing from the runtime. */
+export declare function toBase64(bytes: Uint8Array): string;
+//# sourceMappingURL=base64.d.ts.map

package/dist/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAEA,gHAAgH;AAChH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAalD"}

package/dist/base64.js

@@ -0,0 +1,17 @@
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Standard base64 without line breaks, as the API takes attachment content; needs nothing from the runtime. */
+export function toBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i] ?? 0;
+        const b = bytes[i + 1];
+        const c = bytes[i + 2];
+        const n = (a << 16) | ((b ?? 0) << 8) | (c ?? 0);
+        out += ALPHABET.charAt((n >>> 18) & 63);
+        out += ALPHABET.charAt((n >>> 12) & 63);
+        out += b === undefined ? '=' : ALPHABET.charAt((n >>> 6) & 63);
+        out += c === undefined ? '=' : ALPHABET.charAt(n & 63);
+    }
+    return out;
+}
+//# sourceMappingURL=base64.js.map

package/dist/base64.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.js","sourceRoot":"","sources":["../src/base64.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,kEAAkE,CAAC;AAEpF,gHAAgH;AAChH,MAAM,UAAU,QAAQ,CAAC,KAAiB;IACxC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACjD,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QACxC,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QACxC,GAAG,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC/D,GAAG,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/broadcasts.d.ts

@@ -0,0 +1,60 @@
+import type { Transport } from './transport.ts';
+import type { AcceptedBroadcast, Broadcast, BroadcastList, BroadcastPage, RequestOptions, SendBroadcastBody, SendBroadcastRequest, SendOptions } from './types.ts';
+/** One message to many, on a broadcast stream of the token's server: sent as a whole, followed as a whole. */
+export declare class BroadcastsResource {
+    #private;
+    constructor(transport: Transport);
+    /**
+     * Stores the content once and one message per entry of `messages`, up to
+     * 50,000, on a broadcast stream. Every message is a message in the log
+     * with its own events and webhooks, sent with the recipient's own
+     * unsubscribe link where `{{ unsubscribe_url }}` stands. Addresses on the
+     * stream's suppression list are dropped and counted in `suppressed`; a
+     * list with nothing left throws `recipient_suppressed`. A larger list is
+     * several broadcasts under one tag. The SDK sets an idempotency key, so a
+     * retry answers the same broadcast; pass your own to make a retry from
+     * your side safe too.
+     *
+     * @example
+     * const { broadcastId, total } = await sendora.broadcasts.send({
+     *   streamId,
+     *   from: { email: 'nyheter@example.se', name: 'Example AB' },
+     *   subject: 'Nyheter i oktober',
+     *   text: 'Hej!\n\nHär är månadens nyheter.\n\nVill du inte ha fler? {{ unsubscribe_url }}',
+     *   messages: recipients.map((email) => ({ to: [email] })),
+     * });
+     */
+    send(request: SendBroadcastRequest, options?: SendOptions): Promise<AcceptedBroadcast>;
+    /**
+     * The broadcast and how far it has come: `released` and `failed` move
+     * as the worker hands its messages over, and `status` is `completed`
+     * once nothing is left.
+     *
+     * @example
+     * const broadcast = await sendora.broadcasts.get(broadcastId);
+     * console.log(`${broadcast.released} of ${broadcast.total} released`);
+     */
+    get(broadcastId: string, options?: RequestOptions): Promise<Broadcast>;
+    /**
+     * One page of the server's broadcasts, newest first; pass the page's
+     * `next` as `after` for the following one.
+     *
+     * @example
+     * const { broadcasts } = await sendora.broadcasts.list({ limit: 20 });
+     */
+    list(query?: BroadcastList, options?: RequestOptions): Promise<BroadcastPage>;
+    /**
+     * Holds every message of the broadcast that has not been handed to the
+     * mail server yet; those count as `failed`. A message already on its way
+     * is delivered. A completed or cancelled broadcast throws
+     * `broadcast_not_open`.
+     *
+     * @example
+     * const cancelled = await sendora.broadcasts.cancel(broadcastId);
+     * console.log(`${cancelled.failed} messages held back`);
+     */
+    cancel(broadcastId: string, options?: RequestOptions): Promise<Broadcast>;
+}
+/** The body as the API takes it: attachment bytes become base64, everything else is passed through. */
+export declare function encodeBroadcastRequest(request: SendBroadcastRequest): SendBroadcastBody;
+//# sourceMappingURL=broadcasts.d.ts.map

package/dist/broadcasts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcasts.d.ts","sourceRoot":"","sources":["../src/broadcasts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,aAAa,EACb,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,8GAA8G;AAC9G,qBAAa,kBAAkB;;gBAGjB,SAAS,EAAE,SAAS;IAIhC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAW1F;;;;;;;;OAQG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;IAS1E;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,GAAE,aAAkB,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAUrF;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,SAAS,CAAC;CAQ9E;AAED,uGAAuG;AACvG,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,iBAAiB,CAMvF"}

package/dist/broadcasts.js

@@ -0,0 +1,98 @@
+import { encodeAttachment } from "./email.js";
+/** One message to many, on a broadcast stream of the token's server: sent as a whole, followed as a whole. */
+export class BroadcastsResource {
+    #transport;
+    constructor(transport) {
+        this.#transport = transport;
+    }
+    /**
+     * Stores the content once and one message per entry of `messages`, up to
+     * 50,000, on a broadcast stream. Every message is a message in the log
+     * with its own events and webhooks, sent with the recipient's own
+     * unsubscribe link where `{{ unsubscribe_url }}` stands. Addresses on the
+     * stream's suppression list are dropped and counted in `suppressed`; a
+     * list with nothing left throws `recipient_suppressed`. A larger list is
+     * several broadcasts under one tag. The SDK sets an idempotency key, so a
+     * retry answers the same broadcast; pass your own to make a retry from
+     * your side safe too.
+     *
+     * @example
+     * const { broadcastId, total } = await sendora.broadcasts.send({
+     *   streamId,
+     *   from: { email: 'nyheter@example.se', name: 'Example AB' },
+     *   subject: 'Nyheter i oktober',
+     *   text: 'Hej!\n\nHär är månadens nyheter.\n\nVill du inte ha fler? {{ unsubscribe_url }}',
+     *   messages: recipients.map((email) => ({ to: [email] })),
+     * });
+     */
+    send(request, options = {}) {
+        return this.#transport.request({
+            method: 'POST',
+            path: '/v1/broadcasts',
+            body: encodeBroadcastRequest(request),
+            headers: { 'idempotency-key': options.idempotencyKey ?? crypto.randomUUID() },
+            idempotent: true,
+            signal: options.signal,
+        });
+    }
+    /**
+     * The broadcast and how far it has come: `released` and `failed` move
+     * as the worker hands its messages over, and `status` is `completed`
+     * once nothing is left.
+     *
+     * @example
+     * const broadcast = await sendora.broadcasts.get(broadcastId);
+     * console.log(`${broadcast.released} of ${broadcast.total} released`);
+     */
+    get(broadcastId, options = {}) {
+        return this.#transport.request({
+            method: 'GET',
+            path: `/v1/broadcasts/${encodeURIComponent(broadcastId)}`,
+            idempotent: true,
+            signal: options.signal,
+        });
+    }
+    /**
+     * One page of the server's broadcasts, newest first; pass the page's
+     * `next` as `after` for the following one.
+     *
+     * @example
+     * const { broadcasts } = await sendora.broadcasts.list({ limit: 20 });
+     */
+    list(query = {}, options = {}) {
+        return this.#transport.request({
+            method: 'GET',
+            path: '/v1/broadcasts',
+            query: { limit: query.limit, after: query.after },
+            idempotent: true,
+            signal: options.signal,
+        });
+    }
+    /**
+     * Holds every message of the broadcast that has not been handed to the
+     * mail server yet; those count as `failed`. A message already on its way
+     * is delivered. A completed or cancelled broadcast throws
+     * `broadcast_not_open`.
+     *
+     * @example
+     * const cancelled = await sendora.broadcasts.cancel(broadcastId);
+     * console.log(`${cancelled.failed} messages held back`);
+     */
+    cancel(broadcastId, options = {}) {
+        return this.#transport.request({
+            method: 'POST',
+            path: `/v1/broadcasts/${encodeURIComponent(broadcastId)}/cancel`,
+            idempotent: true,
+            signal: options.signal,
+        });
+    }
+}
+/** The body as the API takes it: attachment bytes become base64, everything else is passed through. */
+export function encodeBroadcastRequest(request) {
+    const { attachments, ...fields } = request;
+    if (attachments === undefined) {
+        return fields;
+    }
+    return { ...fields, attachments: attachments.map(encodeAttachment) };
+}
+//# sourceMappingURL=broadcasts.js.map

package/dist/broadcasts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcasts.js","sourceRoot":"","sources":["../src/broadcasts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAa9C,8GAA8G;AAC9G,MAAM,OAAO,kBAAkB;IACpB,UAAU,CAAY;IAE/B,YAAY,SAAoB;QAC9B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,CAAC,OAA6B,EAAE,UAAuB,EAAE;QAC3D,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAoB;YAChD,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,gBAAgB;YACtB,IAAI,EAAE,sBAAsB,CAAC,OAAO,CAAC;YACrC,OAAO,EAAE,EAAE,iBAAiB,EAAE,OAAO,CAAC,cAAc,IAAI,MAAM,CAAC,UAAU,EAAE,EAAE;YAC7E,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,WAAmB,EAAE,UAA0B,EAAE;QACnD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAY;YACxC,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,WAAW,CAAC,EAAE;YACzD,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,QAAuB,EAAE,EAAE,UAA0B,EAAE;QAC1D,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAgB;YAC5C,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB;YACtB,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE;YACjD,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAmB,EAAE,UAA0B,EAAE;QACtD,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAY;YACxC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,kBAAkB,kBAAkB,CAAC,WAAW,CAAC,SAAS;YAChE,UAAU,EAAE,IAAI;YAChB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;IACL,CAAC;CACF;AAED,uGAAuG;AACvG,MAAM,UAAU,sBAAsB,CAAC,OAA6B;IAClE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3C,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,GAAG,MAAM,EAAE,WAAW,EAAE,WAAW,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,CAAC;AACvE,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,51 @@
+import { DomainsResource } from './domains.ts';
+import { BroadcastsResource } from './broadcasts.ts';
+import { EmailResource } from './email.ts';
+import { MessagesResource } from './messages.ts';
+import { StreamsResource } from './streams.ts';
+import { SuppressionsResource } from './suppressions.ts';
+import { TokensResource } from './tokens.ts';
+import { WebhooksResource } from './webhooks.ts';
+export declare const DEFAULT_BASE_URL = "https://api.sendora.se";
+export interface SendoraOptions {
+    /**
+     * 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.
+     */
+    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.
+ *
+ * @example
+ * import { Sendora } from '@sendora/sdk';
+ *
+ * const sendora = new Sendora({ token: process.env.SENDORA_API_TOKEN });
+ * const { messageId } = await sendora.email.send({
+ *   from: 'no-reply@example.se',
+ *   to: ['anna@example.com'],
+ *   subject: 'Välkommen',
+ *   text: 'Hej Anna!',
+ * });
+ */
+export declare class Sendora {
+    readonly email: EmailResource;
+    readonly broadcasts: BroadcastsResource;
+    readonly messages: MessagesResource;
+    readonly streams: StreamsResource;
+    readonly suppressions: SuppressionsResource;
+    readonly tokens: TokensResource;
+    readonly webhooks: WebhooksResource;
+    readonly domains: DomainsResource;
+    constructor(options: SendoraOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,eAAO,MAAM,gBAAgB,2BAA2B,CAAC;AAGzD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,OAAO,KAAK,GAAG,SAAS,CAAC;IACjC,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,0GAA0G;IAC1G,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,OAAO;IAClB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;gBAEtB,OAAO,EAAE,cAAc;CA+BpC"}