@sendora/sdk 1.1.0

package/src/messages.ts

@@ -0,0 +1,88 @@
+import { paginate } from './pagination.ts';
+import type { Transport } from './transport.ts';
+import type {
+  Message,
+  MessageDetail,
+  MessagePage,
+  MessageSearch,
+  MessageSearchBody,
+  RequestOptions,
+} from './types.ts';
+
+/** The message log of the token's server and each message's timeline. */
+export class MessagesResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * One message as the log holds it: its recipients with their state, its
+   * attachments described, and every event on its timeline. Bodies are
+   * never returned.
+   *
+   * @example
+   * const message = await sendora.messages.get(messageId);
+   * const delivered = message.recipients.every((recipient) => recipient.status === 'delivered');
+   */
+  get(messageId: string, options: RequestOptions = {}): Promise<MessageDetail> {
+    return this.#transport.request<MessageDetail>({
+      method: 'GET',
+      path: `/v1/messages/${encodeURIComponent(messageId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * One page of the log, newest first. Every filter is optional; pass the
+   * page's `next` as `after` for the following page, or use `searchAll`.
+   *
+   * @example
+   * const page = await sendora.messages.search({ tag: 'invoice', status: 'bounced', limit: 20 });
+   */
+  search(search: MessageSearch = {}, options: RequestOptions = {}): Promise<MessagePage> {
+    return this.#transport.request<MessagePage>({
+      method: 'POST',
+      path: '/v1/messages/search',
+      body: encodeSearch(search),
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Every message the filters match, page by page, for `for await`.
+   *
+   * @example
+   * for await (const message of sendora.messages.searchAll({ recipient: 'anna@example.com' })) {
+   *   console.log(message.messageId, message.subject);
+   * }
+   */
+  searchAll(search: MessageSearch = {}, options: RequestOptions = {}): AsyncIterable<Message> {
+    return paginate(
+      (after) => this.search({ ...search, after }, options),
+      (page) => page.messages,
+      (page) => page.next,
+      search.after,
+    );
+  }
+}
+
+/** The body as the API takes it: times as ISO 8601 strings. */
+export function encodeSearch(search: MessageSearch): MessageSearchBody {
+  const { from, to, ...fields } = search;
+  const body: MessageSearchBody = { ...fields };
+  if (from !== undefined) {
+    body.from = isoOf(from);
+  }
+  if (to !== undefined) {
+    body.to = isoOf(to);
+  }
+  return body;
+}
+
+function isoOf(value: Date | string): string {
+  return typeof value === 'string' ? value : value.toISOString();
+}

package/src/pagination.ts

@@ -0,0 +1,18 @@
+/** Walks a cursor-paged list: fetches a page, yields its items, follows `next` until it is null. */
+export async function* paginate<Page, Item>(
+  fetchPage: (after: string | undefined) => Promise<Page>,
+  itemsOf: (page: Page) => Item[],
+  nextOf: (page: Page) => string | null,
+  start: string | undefined,
+): AsyncGenerator<Item, void, undefined> {
+  let after = start;
+  for (;;) {
+    const page = await fetchPage(after);
+    yield* itemsOf(page);
+    const next = nextOf(page);
+    if (next === null) {
+      return;
+    }
+    after = next;
+  }
+}

package/src/retry.ts

@@ -0,0 +1,20 @@
+export const DEFAULT_MAX_RETRIES = 2;
+
+/** The most a call waits across all its retries; a longer Retry-After is handed to the caller instead. */
+export const MAX_TOTAL_WAIT_MS = 5000;
+
+const BASE_DELAY_MS = 500;
+const MAX_BACKOFF_MS = 2000;
+
+/** Retry-After in full when the API gave one; otherwise 500 ms doubling to 2 s, jittered between half and one and a half. */
+export function retryDelayMs(
+  attempt: number,
+  retryAfterSeconds: number | null,
+  random: () => number,
+): number {
+  if (retryAfterSeconds !== null) {
+    return retryAfterSeconds * 1000;
+  }
+  const backoff = Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_BACKOFF_MS);
+  return Math.round(backoff * (0.5 + random()));
+}

package/src/streams.ts

@@ -0,0 +1,100 @@
+import type { Transport } from './transport.ts';
+import type {
+  CreateStreamRequest,
+  RequestOptions,
+  Stream,
+  StreamList,
+  UpdateStreamRequest,
+} from './types.ts';
+
+/** The streams of the token's own server: the default transactional one, and any the account added. */
+export class StreamsResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Adds a stream to the server. A transactional stream is available to
+   * every account; a broadcast stream needs broadcast enabled for the
+   * account (`broadcast_not_enabled`); an inbound stream receives mail at
+   * its own address, one live per server (`inbound_stream_exists`), on an
+   * active account (`tenant_not_active`). A taken name answers
+   * `stream_exists` with `existingId`.
+   *
+   * @example
+   * const stream = await sendora.streams.create({ kind: 'transactional', name: 'Aviseringar' });
+   * await sendora.email.send({ ...message, streamId: stream.streamId });
+   */
+  create(request: CreateStreamRequest, options: RequestOptions = {}): Promise<Stream> {
+    return this.#transport.request<Stream>({
+      method: 'POST',
+      path: '/v1/streams',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every stream of the server, archived ones included, oldest first. */
+  list(options: RequestOptions = {}): Promise<StreamList> {
+    return this.#transport.request<StreamList>({
+      method: 'GET',
+      path: '/v1/streams',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One stream by id. */
+  get(streamId: string, options: RequestOptions = {}): Promise<Stream> {
+    return this.#transport.request<Stream>({
+      method: 'GET',
+      path: `/v1/streams/${encodeURIComponent(streamId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Renames a stream, or sets how long an inbound stream keeps received
+   * content; the id stays. A name another stream of the server carries
+   * answers `stream_exists`.
+   *
+   * @example
+   * await sendora.streams.update(streamId, { name: 'Driftinformation' });
+   * await sendora.streams.update(inboundStreamId, { contentRetentionDays: 7 });
+   */
+  update(
+    streamId: string,
+    request: UpdateStreamRequest,
+    options: RequestOptions = {},
+  ): Promise<Stream> {
+    return this.#transport.request<Stream>({
+      method: 'PATCH',
+      path: `/v1/streams/${encodeURIComponent(streamId)}`,
+      body: request,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * The stream takes no new messages from now on; what it already holds
+   * is still delivered. Archiving again changes nothing. The default
+   * stream cannot be archived (`default_stream`).
+   *
+   * @example
+   * const archived = await sendora.streams.archive(streamId);
+   * console.log(archived.archivedAt);
+   */
+  archive(streamId: string, options: RequestOptions = {}): Promise<Stream> {
+    return this.#transport.request<Stream>({
+      method: 'POST',
+      path: `/v1/streams/${encodeURIComponent(streamId)}/archive`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}

package/src/suppressions.ts

@@ -0,0 +1,73 @@
+import { paginate } from './pagination.ts';
+import type { Transport } from './transport.ts';
+import type {
+  DeleteSuppressionRequest,
+  RequestOptions,
+  Suppression,
+  SuppressionPage,
+  SuppressionQuery,
+} from './types.ts';
+
+/** The addresses the token's server no longer sends to, one list per stream. */
+export class SuppressionsResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * One page of a stream's list, newest first: hard bounces, spam
+   * complaints and addresses added by hand. The default stream's list
+   * unless `streamId` names another. A send to any of them is refused
+   * with `recipient_suppressed`.
+   *
+   * @example
+   * const { suppressions, next } = await sendora.suppressions.list({ streamId, limit: 200 });
+   */
+  list(query: SuppressionQuery = {}, options: RequestOptions = {}): Promise<SuppressionPage> {
+    return this.#transport.request<SuppressionPage>({
+      method: 'GET',
+      path: '/v1/suppressions',
+      query: { streamId: query.streamId, limit: query.limit, after: query.after },
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Every suppressed address, page by page, for `for await`.
+   *
+   * @example
+   * for await (const entry of sendora.suppressions.listAll()) {
+   *   console.log(entry.address, entry.reason);
+   * }
+   */
+  listAll(query: SuppressionQuery = {}, options: RequestOptions = {}): AsyncIterable<Suppression> {
+    return paginate(
+      (after) => this.list({ ...query, after }, options),
+      (page) => page.suppressions,
+      (page) => page.next,
+      query.after,
+    );
+  }
+
+  /**
+   * Lifts a hard bounce or a manual entry from a stream's list so the
+   * server may send to the address again on that stream; the default
+   * stream's list unless `streamId` names another. A spam complaint cannot
+   * be lifted this way: `spam_complaint_locked`.
+   *
+   * @example
+   * await sendora.suppressions.delete({ address: 'anna@example.com' });
+   */
+  delete(request: DeleteSuppressionRequest, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'POST',
+      path: '/v1/suppressions/delete',
+      body: request,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,70 @@
+import type { Transport } from './transport.ts';
+import type {
+  CreatedToken,
+  CreateTokenRequest,
+  RequestOptions,
+  Token,
+  TokenList,
+} from './types.ts';
+
+/** The API tokens of the token's own server. Every token of a server has the same rights. */
+export class TokensResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Creates another live token and answers its value once; it is never
+   * shown again, so store it at once.
+   *
+   * @example
+   * const { token, tokenId } = await sendora.tokens.create({ name: 'Fakturasystemet' });
+   */
+  create(request: CreateTokenRequest, options: RequestOptions = {}): Promise<CreatedToken> {
+    return this.#transport.request<CreatedToken>({
+      method: 'POST',
+      path: '/v1/tokens',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every token of the server, revoked ones included. */
+  list(options: RequestOptions = {}): Promise<TokenList> {
+    return this.#transport.request<TokenList>({
+      method: 'GET',
+      path: '/v1/tokens',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One token by id; its value is never part of the answer. */
+  get(tokenId: string, options: RequestOptions = {}): Promise<Token> {
+    return this.#transport.request<Token>({
+      method: 'GET',
+      path: `/v1/tokens/${encodeURIComponent(tokenId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * The token stops working at once. The last live token of a server
+   * cannot be revoked (`last_token`), so a server is never locked out.
+   *
+   * @example
+   * await sendora.tokens.revoke(tokenId);
+   */
+  revoke(tokenId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/tokens/${encodeURIComponent(tokenId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}

package/src/transport.ts

@@ -0,0 +1,179 @@
+import { errorFromAnswer, SendoraError } from './error.ts';
+import { MAX_TOTAL_WAIT_MS, retryDelayMs } from './retry.ts';
+
+export type Method = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+
+export interface RequestSpec {
+  method: Method;
+  path: string;
+  query?: Record<string, string | number | undefined> | undefined;
+  body?: unknown;
+  headers?: Record<string, string> | undefined;
+  /** Safe to send again after a lost connection: reads, deletes and sends under an idempotency key. */
+  idempotent: boolean;
+  signal?: AbortSignal | undefined;
+}
+
+export interface TransportOptions {
+  baseUrl: string;
+  token: string;
+  fetch: typeof fetch;
+  timeoutMs: number;
+  maxRetries: number;
+  userAgent: string;
+  /** Waits between attempts; tests replace it. */
+  sleep?: ((ms: number) => Promise<void>) | undefined;
+  /** The jitter source in [0, 1); tests pin it. */
+  random?: (() => number) | undefined;
+}
+
+type Attempt<T> = { ok: true; value: T } | { ok: false; error: SendoraError };
+
+/**
+ * One request path for every resource: builds the request, sends it,
+ * turns the answer into a value or a SendoraError, and repeats it within
+ * the retry budget when repeating could help and cannot cause harm.
+ */
+export class Transport {
+  readonly #options: TransportOptions;
+  readonly #sleep: (ms: number) => Promise<void>;
+  readonly #random: () => number;
+
+  constructor(options: TransportOptions) {
+    this.#options = options;
+    this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    this.#random = options.random ?? Math.random;
+  }
+
+  async request<T>(spec: RequestSpec): Promise<T> {
+    const url = this.#url(spec);
+    const body = spec.body === undefined ? undefined : JSON.stringify(spec.body);
+    let waitedMs = 0;
+    for (let attempt = 0; ; attempt += 1) {
+      const outcome = await this.#attempt<T>(spec, url, body);
+      if (outcome.ok) {
+        return outcome.value;
+      }
+      const { error } = outcome;
+      const mayRepeat =
+        spec.idempotent || error.code === 'rate_limited' || error.code === 'sending_disabled';
+      if (attempt >= this.#options.maxRetries || !error.retryable || !mayRepeat) {
+        throw error;
+      }
+      const delay = retryDelayMs(attempt, error.retryAfter, this.#random);
+      if (waitedMs + delay > MAX_TOTAL_WAIT_MS) {
+        throw error;
+      }
+      waitedMs += delay;
+      await this.#sleep(delay);
+    }
+  }
+
+  async #attempt<T>(spec: RequestSpec, url: string, body: string | undefined): Promise<Attempt<T>> {
+    const timeout = AbortSignal.timeout(this.#options.timeoutMs);
+    const signal = spec.signal === undefined ? timeout : AbortSignal.any([spec.signal, timeout]);
+    const init: RequestInit = {
+      method: spec.method,
+      headers: this.#headers(spec, body),
+      signal,
+      redirect: 'manual',
+    };
+    if (body !== undefined) {
+      init.body = body;
+    }
+    let response: Response;
+    try {
+      response = await this.#options.fetch(url, init);
+    } catch (cause) {
+      if (spec.signal?.aborted) {
+        throw cause;
+      }
+      if (timeout.aborted) {
+        return {
+          ok: false,
+          error: new SendoraError({
+            code: 'timeout',
+            status: null,
+            message: `The API did not answer within ${String(this.#options.timeoutMs)} ms.`,
+            cause,
+          }),
+        };
+      }
+      return {
+        ok: false,
+        error: new SendoraError({
+          code: 'connection_failed',
+          status: null,
+          message: 'The connection to the API failed.',
+          cause,
+        }),
+      };
+    }
+    if (response.status === 204) {
+      await response.body?.cancel();
+      return { ok: true, value: undefined as T };
+    }
+    const json = parseJson(await response.text());
+    if (response.status === 0 || (response.status >= 300 && response.status < 400)) {
+      return {
+        ok: false,
+        error: new SendoraError({
+          code: 'unexpected_response',
+          status: response.status,
+          message: `The API answered a redirect; check baseUrl (${this.#options.baseUrl}).`,
+        }),
+      };
+    }
+    if (response.ok) {
+      if (json === undefined) {
+        return {
+          ok: false,
+          error: new SendoraError({
+            code: 'unexpected_response',
+            status: response.status,
+            message: `The API answered ${String(response.status)} without a JSON body.`,
+          }),
+        };
+      }
+      return { ok: true, value: json as T };
+    }
+    return {
+      ok: false,
+      error: errorFromAnswer(response.status, json, response.headers.get('retry-after')),
+    };
+  }
+
+  #headers(spec: RequestSpec, body: string | undefined): Record<string, string> {
+    const headers: Record<string, string> = {
+      authorization: `Bearer ${this.#options.token}`,
+      accept: 'application/json',
+      'user-agent': this.#options.userAgent,
+      ...spec.headers,
+    };
+    if (body !== undefined) {
+      headers['content-type'] = 'application/json';
+    }
+    return headers;
+  }
+
+  #url(spec: RequestSpec): string {
+    const url = new URL(`${this.#options.baseUrl.replace(/\/+$/, '')}${spec.path}`);
+    for (const [name, value] of Object.entries(spec.query ?? {})) {
+      if (value !== undefined) {
+        url.searchParams.set(name, String(value));
+      }
+    }
+    return url.toString();
+  }
+}
+
+function parseJson(text: string): unknown {
+  if (text === '') {
+    return undefined;
+  }
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return undefined;
+  }
+}