@sendora/sdk 1.1.0

package/src/broadcasts.ts

@@ -0,0 +1,115 @@
+import { encodeAttachment } from './email.ts';
+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 class BroadcastsResource {
+  readonly #transport: Transport;
+
+  constructor(transport: 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: SendBroadcastRequest, options: SendOptions = {}): Promise<AcceptedBroadcast> {
+    return this.#transport.request<AcceptedBroadcast>({
+      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: string, options: RequestOptions = {}): Promise<Broadcast> {
+    return this.#transport.request<Broadcast>({
+      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: BroadcastList = {}, options: RequestOptions = {}): Promise<BroadcastPage> {
+    return this.#transport.request<BroadcastPage>({
+      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: string, options: RequestOptions = {}): Promise<Broadcast> {
+    return this.#transport.request<Broadcast>({
+      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: SendBroadcastRequest): SendBroadcastBody {
+  const { attachments, ...fields } = request;
+  if (attachments === undefined) {
+    return fields;
+  }
+  return { ...fields, attachments: attachments.map(encodeAttachment) };
+}

package/src/client.ts

@@ -0,0 +1,88 @@
+import { DomainsResource } from './domains.ts';
+import { BroadcastsResource } from './broadcasts.ts';
+import { EmailResource } from './email.ts';
+import { MessagesResource } from './messages.ts';
+import { DEFAULT_MAX_RETRIES } from './retry.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 {
+  /**
+   * 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 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) {
+    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}`,
+    });
+    this.email = new EmailResource(transport);
+    this.broadcasts = new BroadcastsResource(transport);
+    this.messages = new MessagesResource(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

@@ -0,0 +1,84 @@
+import type { Transport } from './transport.ts';
+import type {
+  CreateDomainRequest,
+  DomainList,
+  RequestOptions,
+  SendingDomain,
+  VerifiedDomain,
+} from './types.ts';
+
+/** The account's sending domains and the two DNS records each one needs. Any server's token manages them. */
+export class DomainsResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Adds a domain with its own DKIM key and answers the two records to
+   * create: a CNAME for the return path and a TXT record for the DKIM key.
+   * Mail may go out once both are seen. `domain_exists` carries the id of
+   * the domain the account already has as `existingId`.
+   *
+   * @example
+   * const domain = await sendora.domains.create({ domain: 'example.se' });
+   * console.log(domain.returnPath.host, domain.returnPath.value);
+   * console.log(domain.dkim.host, domain.dkim.value);
+   */
+  create(request: CreateDomainRequest, options: RequestOptions = {}): Promise<SendingDomain> {
+    return this.#transport.request<SendingDomain>({
+      method: 'POST',
+      path: '/v1/domains',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every sending domain of the account. */
+  list(options: RequestOptions = {}): Promise<DomainList> {
+    return this.#transport.request<DomainList>({
+      method: 'GET',
+      path: '/v1/domains',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One domain by id, with the state of its records. */
+  get(domainId: string, options: RequestOptions = {}): Promise<SendingDomain> {
+    return this.#transport.request<SendingDomain>({
+      method: 'GET',
+      path: `/v1/domains/${encodeURIComponent(domainId)}`,
+      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.domains.verify(domainId);
+   */
+  verify(domainId: string, options: RequestOptions = {}): Promise<VerifiedDomain> {
+    return this.#transport.request<VerifiedDomain>({
+      method: 'POST',
+      path: `/v1/domains/${encodeURIComponent(domainId)}/verify`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** Removes the domain; mail from it is refused from then on and its DKIM key is gone. */
+  delete(domainId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/domains/${encodeURIComponent(domainId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}

package/src/email.ts

@@ -0,0 +1,83 @@
+import { toBase64 } from './base64.ts';
+import type { Transport } from './transport.ts';
+import type {
+  AcceptedEmail,
+  Attachment,
+  BatchResult,
+  EncodedAttachment,
+  SendEmailBody,
+  SendEmailRequest,
+  SendOptions,
+} from './types.ts';
+
+/** Hands messages over for delivery, one at a time or up to 100 in a batch. */
+export class EmailResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Sends one message and answers at once with its id. Delivery, deferral,
+   * bounce and complaint arrive later as events on the message and as
+   * webhooks. Every send carries an idempotency key, yours or a random one,
+   * so the SDK's retries can never send twice.
+   *
+   * @example
+   * 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',
+   * });
+   */
+  send(request: SendEmailRequest, options: SendOptions = {}): Promise<AcceptedEmail> {
+    return this.#transport.request<AcceptedEmail>({
+      method: 'POST',
+      path: '/v1/email',
+      body: encodeSendRequest(request),
+      headers: { 'idempotency-key': options.idempotencyKey ?? crypto.randomUUID() },
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Sends up to 100 messages and answers one result per message, in order:
+   * accepted with its id, or refused with the same error a single send
+   * would give. The batch as a whole never fails halfway, so read
+   * `results[i].status`. A retry under the same key sends nothing twice:
+   * items accepted before come back with `replayed` set.
+   *
+   * @example
+   * const { results } = await sendora.email.sendBatch(messages, { idempotencyKey: 'invoices-2026-09' });
+   * const refused = results.filter((result) => result.status === 'error');
+   */
+  sendBatch(messages: SendEmailRequest[], options: SendOptions = {}): Promise<BatchResult> {
+    return this.#transport.request<BatchResult>({
+      method: 'POST',
+      path: '/v1/email/batch',
+      body: messages.map(encodeSendRequest),
+      headers: { 'idempotency-key': options.idempotencyKey ?? crypto.randomUUID() },
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}
+
+/** The body as the API takes it: attachment bytes become base64, everything else is passed through. */
+export function encodeSendRequest(request: SendEmailRequest): SendEmailBody {
+  const { attachments, ...fields } = request;
+  if (attachments === undefined) {
+    return fields;
+  }
+  return { ...fields, attachments: attachments.map(encodeAttachment) };
+}
+
+export function encodeAttachment(attachment: Attachment): EncodedAttachment {
+  const { content, ...fields } = attachment;
+  return { ...fields, content: typeof content === 'string' ? content : toBase64(content) };
+}

package/src/error.ts

@@ -0,0 +1,252 @@
+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. */
+export type SendoraErrorCode =
+  | 'invalid_request'
+  | 'unauthorized'
+  | 'payment_required'
+  | 'tenant_paused'
+  | 'tenant_not_active'
+  | 'spam_complaint_locked'
+  | 'unsubscribe_locked'
+  | 'not_found'
+  | 'domain_exists'
+  | 'webhook_exists'
+  | 'stream_exists'
+  | 'inbound_stream_exists'
+  | 'default_stream'
+  | 'last_token'
+  | 'request_too_large'
+  | 'from_domain_not_verified'
+  | 'stream_not_found'
+  | 'stream_archived'
+  | 'stream_paused'
+  | 'stream_not_sendable'
+  | 'stream_not_broadcast'
+  | 'broadcast_not_enabled'
+  | 'broadcast_not_open'
+  | 'substitution_missing'
+  | 'unsubscribe_placeholder_missing'
+  | 'list_unsubscribe_reserved'
+  | 'recipient_suppressed'
+  | 'idempotency_key_mismatch'
+  | 'idempotency_key_required'
+  | 'rate_limited'
+  | 'monthly_cap_reached'
+  | 'sending_disabled'
+  | 'connection_failed'
+  | 'timeout'
+  | 'unexpected_response'
+  | 'invalid_signature'
+  | 'stale_signature';
+
+const apiCodes: ReadonlySet<string> = new Set<SendoraErrorCode>([
+  'invalid_request',
+  'unauthorized',
+  'payment_required',
+  'tenant_paused',
+  'tenant_not_active',
+  'spam_complaint_locked',
+  'unsubscribe_locked',
+  'not_found',
+  'domain_exists',
+  'webhook_exists',
+  'stream_exists',
+  'inbound_stream_exists',
+  'default_stream',
+  'last_token',
+  'request_too_large',
+  'from_domain_not_verified',
+  'stream_not_found',
+  'stream_archived',
+  'stream_paused',
+  'stream_not_sendable',
+  'stream_not_broadcast',
+  'broadcast_not_enabled',
+  'broadcast_not_open',
+  'substitution_missing',
+  'unsubscribe_placeholder_missing',
+  'list_unsubscribe_reserved',
+  'recipient_suppressed',
+  'idempotency_key_mismatch',
+  'idempotency_key_required',
+  'rate_limited',
+  'monthly_cap_reached',
+  'sending_disabled',
+]);
+
+export interface SendoraErrorFields {
+  code: SendoraErrorCode;
+  message: string;
+  status: number | null;
+  retryAfter?: number | null;
+  scope?: LimitScope | null;
+  limit?: number | null;
+  cap?: number | null;
+  used?: number | null;
+  resetsAt?: string | null;
+  issues?: ValidationIssue[];
+  suppressed?: SuppressedRecipient[];
+  streamId?: string | null;
+  existingId?: string | null;
+  cause?: unknown;
+}
+
+/**
+ * What every failed call throws. Narrow on `code`; the other fields are
+ * filled where the API gives them and null or empty otherwise. Neither the
+ * token nor the request body is ever part of it.
+ *
+ * @example
+ * try {
+ *   await sendora.email.send(message);
+ * } catch (error) {
+ *   if (error instanceof SendoraError && error.code === 'recipient_suppressed') {
+ *     console.log(error.suppressed.map((entry) => entry.address));
+ *   } else {
+ *     throw error;
+ *   }
+ * }
+ */
+export class SendoraError extends Error {
+  override readonly name = 'SendoraError';
+  readonly code: SendoraErrorCode;
+  /** The HTTP status, or null when no answer arrived. */
+  readonly status: number | null;
+  /** Seconds to wait before trying again, when the API said so. */
+  readonly retryAfter: number | null;
+  /** Whose limit or cap it is, on rate_limited and monthly_cap_reached. */
+  readonly scope: LimitScope | null;
+  /** Emails per minute allowed for that scope, on rate_limited. */
+  readonly limit: number | null;
+  /** The monthly cap and what was used of it, on monthly_cap_reached. */
+  readonly cap: number | null;
+  readonly used: number | null;
+  /** When the month counter resets, on monthly_cap_reached. */
+  readonly resetsAt: string | 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. */
+  readonly existingId: string | null;
+
+  constructor(fields: SendoraErrorFields) {
+    super(fields.message, { cause: fields.cause });
+    this.code = fields.code;
+    this.status = fields.status;
+    this.retryAfter = fields.retryAfter ?? null;
+    this.scope = fields.scope ?? null;
+    this.limit = fields.limit ?? null;
+    this.cap = fields.cap ?? null;
+    this.used = fields.used ?? null;
+    this.resetsAt = fields.resetsAt ?? null;
+    this.issues = fields.issues ?? [];
+    this.suppressed = fields.suppressed ?? [];
+    this.streamId = fields.streamId ?? null;
+    this.existingId = fields.existingId ?? null;
+  }
+
+  /** True when waiting and calling again could succeed: a rate limit, sending paused for everyone, a lost connection, a timeout, or a server-side failure. */
+  get retryable(): boolean {
+    return (
+      this.code === 'rate_limited' ||
+      this.code === 'sending_disabled' ||
+      this.code === 'connection_failed' ||
+      this.code === 'timeout' ||
+      (this.status !== null && this.status >= 500)
+    );
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      status: this.status,
+      message: this.message,
+      retryAfter: this.retryAfter,
+      scope: this.scope,
+      limit: this.limit,
+      cap: this.cap,
+      used: this.used,
+      resetsAt: this.resetsAt,
+      issues: this.issues,
+      suppressed: this.suppressed,
+      streamId: this.streamId,
+      existingId: this.existingId,
+    };
+  }
+}
+
+/** The error a non-2xx answer amounts to; an answer without a known code is `unexpected_response`. */
+export function errorFromAnswer(
+  status: number,
+  body: unknown,
+  retryAfterHeader: string | null,
+): SendoraError {
+  const answer = isRecord(body) ? body : {};
+  const code = knownCode(answer.error);
+  const issues = Array.isArray(answer.issues) ? answer.issues.filter(isIssue) : [];
+  const message =
+    typeof answer.message === 'string'
+      ? answer.message
+      : code === 'invalid_request'
+        ? `The request is invalid: ${issues.map((issue) => `${issue.path}: ${issue.message}`).join('; ')}`
+        : `The API answered ${String(status)} without an error body.`;
+  return new SendoraError({
+    code,
+    message,
+    status,
+    retryAfter: integerOf(answer.retryAfter) ?? integerOf(retryAfterHeader),
+    scope: answer.scope === 'tenant' || answer.scope === 'server' ? answer.scope : null,
+    limit: integerOf(answer.limit),
+    cap: integerOf(answer.cap),
+    used: integerOf(answer.used),
+    resetsAt: typeof answer.resetsAt === 'string' ? answer.resetsAt : null,
+    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),
+  });
+}
+
+function stringOf(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}
+
+function knownCode(value: unknown): SendoraErrorCode {
+  return typeof value === 'string' && apiCodes.has(value)
+    ? (value as SendoraErrorCode)
+    : 'unexpected_response';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isIssue(value: unknown): value is ValidationIssue {
+  return isRecord(value) && typeof value.path === 'string' && typeof value.message === 'string';
+}
+
+function isSuppressed(value: unknown): value is SuppressedRecipient {
+  return (
+    isRecord(value) &&
+    typeof value.address === 'string' &&
+    (value.reason === 'hard_bounce' ||
+      value.reason === 'spam_complaint' ||
+      value.reason === 'manual')
+  );
+}
+
+function integerOf(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isInteger(value)) {
+    return value;
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value)) {
+    return Number(value);
+  }
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { DEFAULT_BASE_URL, Sendora } from './client.ts';
+export type { SendoraOptions } from './client.ts';
+export type { BroadcastsResource } from './broadcasts.ts';
+export type { DomainsResource } from './domains.ts';
+export type { EmailResource } from './email.ts';
+export { SendoraError } from './error.ts';
+export type { SendoraErrorCode } from './error.ts';
+export type { MessagesResource } from './messages.ts';
+export type { StreamsResource } from './streams.ts';
+export type { SuppressionsResource } from './suppressions.ts';
+export type { TokensResource } from './tokens.ts';
+export type * from './types.ts';
+export { SDK_VERSION } from './version.ts';
+export { verifyWebhook } from './webhook-verify.ts';
+export type { VerifyWebhookInput } from './webhook-verify.ts';
+export type { WebhooksResource } from './webhooks.ts';