@sendora/sdk 1.1.0 → 2.1.0

package/src/inbound.ts

@@ -0,0 +1,135 @@
+import { paginate } from './pagination.ts';
+import type { Transport } from './transport.ts';
+import type {
+  InboundMessage,
+  InboundMessageDetail,
+  InboundPage,
+  InboundSearch,
+  InboundSearchBody,
+  RequestOptions,
+} from './types.ts';
+
+/** The mail the token's server has received on its inbound stream. */
+export class InboundResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * One received message: its envelope, parties, headers, text and HTML,
+   * and its attachments described. The attachment bytes and the raw
+   * message are downloads of their own. Once the stream's content window
+   * has passed, `contentAvailable` is false and the content fields are
+   * null.
+   *
+   * @example
+   * const message = await sendora.inbound.get(inboundMessageId);
+   * console.log(message.from?.address, message.subject, message.text);
+   */
+  get(inboundMessageId: string, options: RequestOptions = {}): Promise<InboundMessageDetail> {
+    return this.#transport.request<InboundMessageDetail>({
+      method: 'GET',
+      path: `/v1/inbound/${encodeURIComponent(inboundMessageId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * One page of received messages, 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.inbound.search({ from: 'anna@example.com', limit: 20 });
+   */
+  search(search: InboundSearch = {}, options: RequestOptions = {}): Promise<InboundPage> {
+    return this.#transport.request<InboundPage>({
+      method: 'POST',
+      path: '/v1/inbound/search',
+      body: encodeInboundSearch(search),
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Every received message the filters match, page by page, for `for await`.
+   *
+   * @example
+   * for await (const message of sendora.inbound.searchAll({ recipient: address })) {
+   *   console.log(message.receivedAt, message.subject);
+   * }
+   */
+  searchAll(
+    search: InboundSearch = {},
+    options: RequestOptions = {},
+  ): AsyncIterable<InboundMessage> {
+    return paginate(
+      (after) => this.search({ ...search, after }, options),
+      (page) => page.messages,
+      (page) => page.next,
+      search.after,
+    );
+  }
+
+  /**
+   * The message byte for byte as it was received, as `message/rfc822`.
+   * Throws `content_expired` once the stream's content window has passed.
+   *
+   * @example
+   * const raw = await sendora.inbound.raw(inboundMessageId);
+   * await writeFile(`${inboundMessageId}.eml`, raw);
+   */
+  raw(inboundMessageId: string, options: RequestOptions = {}): Promise<Uint8Array> {
+    return this.#transport.requestBytes({
+      method: 'GET',
+      path: `/v1/inbound/${encodeURIComponent(inboundMessageId)}/raw`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * An attachment's bytes, whatever the sender declared them to be; the
+   * name and the declared type are on the message. Throws
+   * `content_expired` once the stream's content window has passed.
+   *
+   * @example
+   * const message = await sendora.inbound.get(inboundMessageId);
+   * for (const attachment of message.attachments) {
+   *   const bytes = await sendora.inbound.attachment(inboundMessageId, attachment.attachmentId);
+   * }
+   */
+  attachment(
+    inboundMessageId: string,
+    attachmentId: string,
+    options: RequestOptions = {},
+  ): Promise<Uint8Array> {
+    return this.#transport.requestBytes({
+      method: 'GET',
+      path: `/v1/inbound/${encodeURIComponent(inboundMessageId)}/attachments/${encodeURIComponent(attachmentId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}
+
+/** The body as the API takes it: times as ISO 8601 strings. */
+export function encodeInboundSearch(search: InboundSearch): InboundSearchBody {
+  const { receivedFrom, receivedTo, ...fields } = search;
+  const body: InboundSearchBody = { ...fields };
+  if (receivedFrom !== undefined) {
+    body.receivedFrom = isoOf(receivedFrom);
+  }
+  if (receivedTo !== undefined) {
+    body.receivedTo = isoOf(receivedTo);
+  }
+  return body;
+}
+
+function isoOf(value: Date | string): string {
+  return typeof value === 'string' ? value : value.toISOString();
+}

package/src/index.ts

@@ -1,11 +1,18 @@
-export { DEFAULT_BASE_URL, Sendora } from './client.ts';
+export { SendoraAccount } from './account.ts';
+export type { SendoraAccountOptions } from './account.ts';
+export { 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 { InboundResource } from './inbound.ts';
+export type { InboundDomainsResource } from './inbound-domains.ts';
 export type { MessagesResource } from './messages.ts';
+export { DEFAULT_BASE_URL } from './options.ts';
+export type { ClientOptions } from './options.ts';
+export type { ServersResource, ServerTokensResource } from './servers.ts';
 export type { StreamsResource } from './streams.ts';
 export type { SuppressionsResource } from './suppressions.ts';
 export type { TokensResource } from './tokens.ts';

package/src/options.ts

@@ -0,0 +1,51 @@
+import { DEFAULT_MAX_RETRIES } from './retry.ts';
+import { Transport } from './transport.ts';
+import { SDK_VERSION } from './version.ts';
+
+export const DEFAULT_BASE_URL = 'https://api.sendora.se';
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** What both clients take besides the key. */
+export interface ClientOptions {
+  /** 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 transport a client's resources share, built once at construction so
+ * a missing key or a nonsense option fails at startup rather than at the
+ * first call.
+ */
+export function transportFor(
+  token: string | undefined,
+  options: ClientOptions,
+  missingKey: string,
+): Transport {
+  if (token === undefined || token.trim() === '') {
+    throw new TypeError(missingKey);
+  }
+  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.');
+  }
+  return new Transport({
+    baseUrl,
+    token,
+    fetch: options.fetch ?? fetch,
+    timeoutMs,
+    maxRetries,
+    userAgent: `sendora-sdk/${SDK_VERSION}`,
+  });
+}

package/src/servers.ts

@@ -0,0 +1,166 @@
+import type { Transport } from './transport.ts';
+import type {
+  CreatedServer,
+  CreatedToken,
+  CreateServerRequest,
+  CreateTokenRequest,
+  RequestOptions,
+  Server,
+  ServerList,
+  Token,
+  TokenList,
+  UpdateServerRequest,
+} from './types.ts';
+
+/**
+ * The keys of one server, managed with the account key. A server holds at
+ * most two live keys, so rotation is create, switch, revoke.
+ */
+export class ServerTokensResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Creates another live key for the server and answers its value once; it
+   * is never shown again, so store it at once. A third live key is refused
+   * with `token_limit`.
+   *
+   * @example
+   * const { token } = await account.servers.tokens.create(serverId, { name: 'Fakturasystemet' });
+   */
+  create(
+    serverId: string,
+    request: CreateTokenRequest,
+    options: RequestOptions = {},
+  ): Promise<CreatedToken> {
+    return this.#transport.request<CreatedToken>({
+      method: 'POST',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens`,
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every key of the server, revoked ones included. */
+  list(serverId: string, options: RequestOptions = {}): Promise<TokenList> {
+    return this.#transport.request<TokenList>({
+      method: 'GET',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One key by id; its value is never part of the answer. */
+  get(serverId: string, tokenId: string, options: RequestOptions = {}): Promise<Token> {
+    return this.#transport.request<Token>({
+      method: 'GET',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens/${encodeURIComponent(tokenId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * The key stops working at once. The last live key of a server cannot be
+   * revoked (`last_token`), so a server is never locked out.
+   *
+   * @example
+   * await account.servers.tokens.revoke(serverId, tokenId);
+   */
+  revoke(serverId: string, tokenId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/servers/${encodeURIComponent(serverId)}/tokens/${encodeURIComponent(tokenId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}
+
+/** The account's servers: each an isolation boundary with its own keys, streams, log, suppressions and webhooks. */
+export class ServersResource {
+  readonly #transport: Transport;
+  /** The keys of each server. */
+  readonly tokens: ServerTokensResource;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+    this.tokens = new ServerTokensResource(transport);
+  }
+
+  /**
+   * Creates a server with its default transactional stream and its first
+   * key, whose value is answered this once. A taken name is
+   * `server_exists`; the account's cap is `server_limit` with `max`.
+   *
+   * @example
+   * const server = await account.servers.create({ name: 'Fakturering' });
+   * const sendora = new Sendora({ token: server.token.token });
+   */
+  create(request: CreateServerRequest, options: RequestOptions = {}): Promise<CreatedServer> {
+    return this.#transport.request<CreatedServer>({
+      method: 'POST',
+      path: '/v1/servers',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every server of the account, oldest first. */
+  list(options: RequestOptions = {}): Promise<ServerList> {
+    return this.#transport.request<ServerList>({
+      method: 'GET',
+      path: '/v1/servers',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One server by id. */
+  get(serverId: string, options: RequestOptions = {}): Promise<Server> {
+    return this.#transport.request<Server>({
+      method: 'GET',
+      path: `/v1/servers/${encodeURIComponent(serverId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** Renames the server; the id, the keys and everything it holds stay. A taken name is `server_exists`. */
+  update(
+    serverId: string,
+    request: UpdateServerRequest,
+    options: RequestOptions = {},
+  ): Promise<Server> {
+    return this.#transport.request<Server>({
+      method: 'PATCH',
+      path: `/v1/servers/${encodeURIComponent(serverId)}`,
+      body: request,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * Removes the server with its keys, streams, messages, suppressions and
+   * webhooks. Refused with `server_in_flight` while its messages are still
+   * being delivered; try again once they have left.
+   *
+   * @example
+   * await account.servers.delete(serverId);
+   */
+  delete(serverId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/servers/${encodeURIComponent(serverId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+}

package/src/transport.ts

@@ -46,11 +46,20 @@ export class Transport {
   }
 
   async request<T>(spec: RequestSpec): Promise<T> {
+    return this.#send<T>(spec, 'json');
+  }
+
+  /** A download: the answer's bytes as they came, with the same errors and retries as any other request. */
+  async requestBytes(spec: RequestSpec): Promise<Uint8Array> {
+    return this.#send<Uint8Array>(spec, 'bytes');
+  }
+
+  async #send<T>(spec: RequestSpec, shape: 'json' | 'bytes'): 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);
+      const outcome = await this.#attempt<T>(spec, url, body, shape);
       if (outcome.ok) {
         return outcome.value;
       }
@@ -69,12 +78,17 @@ export class Transport {
     }
   }
 
-  async #attempt<T>(spec: RequestSpec, url: string, body: string | undefined): Promise<Attempt<T>> {
+  async #attempt<T>(
+    spec: RequestSpec,
+    url: string,
+    body: string | undefined,
+    shape: 'json' | 'bytes',
+  ): 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),
+      headers: this.#headers(spec, body, shape),
       signal,
       redirect: 'manual',
     };
@@ -113,6 +127,9 @@ export class Transport {
       await response.body?.cancel();
       return { ok: true, value: undefined as T };
     }
+    if (shape === 'bytes' && response.ok) {
+      return { ok: true, value: new Uint8Array(await response.arrayBuffer()) as T };
+    }
     const json = parseJson(await response.text());
     if (response.status === 0 || (response.status >= 300 && response.status < 400)) {
       return {
@@ -143,10 +160,14 @@ export class Transport {
     };
   }
 
-  #headers(spec: RequestSpec, body: string | undefined): Record<string, string> {
+  #headers(
+    spec: RequestSpec,
+    body: string | undefined,
+    shape: 'json' | 'bytes',
+  ): Record<string, string> {
     const headers: Record<string, string> = {
       authorization: `Bearer ${this.#options.token}`,
-      accept: 'application/json',
+      accept: shape === 'bytes' ? '*/*' : 'application/json',
       'user-agent': this.#options.userAgent,
       ...spec.headers,
     };