@sendora/sdk 1.1.0

package/src/version.ts

@@ -0,0 +1,2 @@
+/** The package version, sent as the User-Agent; a test holds it equal to package.json. */
+export const SDK_VERSION = '1.1.0';

package/src/webhook-verify.ts

@@ -0,0 +1,147 @@
+import { SendoraError } from './error.ts';
+import type { WebhookEvent, WebhookEventName } from './types.ts';
+
+export interface VerifyWebhookInput {
+  /** The signing secret the webhook was created with; `undefined`, as an unset environment variable gives, throws. */
+  secret: string | undefined;
+  /** The Sendora-Signature header as received. */
+  signature: string | null | undefined;
+  /** The raw request body exactly as received; parse nothing before verifying. */
+  body: string | Uint8Array;
+  /** How old a signature may be, in seconds; five minutes by default. */
+  toleranceSeconds?: number | undefined;
+  /** The current time in seconds since the epoch; tests pin it. */
+  now?: number | undefined;
+}
+
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const MAC_HEX = /^[0-9a-f]{64}$/i;
+
+const eventNames: ReadonlySet<string> = new Set<WebhookEventName>([
+  'delivered',
+  'bounced',
+  'deferred',
+  'spam_complaint',
+  'unsubscribed',
+  'cap_warning',
+  'cap_reached',
+  'inbound',
+]);
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/**
+ * Checks a webhook request came from Sendora and answers its event, typed
+ * by `event`. The header is `Sendora-Signature: t=<unix seconds>,v1=<hex>`,
+ * the hex an HMAC-SHA256 with your secret over `<t>.<raw body>`; the
+ * timestamp is inside the signed text, so a captured request cannot be
+ * replayed after the tolerance. Throws `SendoraError` with
+ * `invalid_signature` or `stale_signature`.
+ *
+ * @example
+ * const event = await verifyWebhook({
+ *   secret: process.env.SENDORA_WEBHOOK_SECRET,
+ *   signature: req.headers['sendora-signature'],
+ *   body: rawBody,
+ * });
+ * if (event.event === 'bounced' && event.details.hard) {
+ *   await markUndeliverable(event.recipient);
+ * }
+ */
+export async function verifyWebhook(input: VerifyWebhookInput): Promise<WebhookEvent> {
+  if (input.secret === undefined || input.secret === '') {
+    throw new TypeError('verifyWebhook needs the signing secret the webhook was created with.');
+  }
+  const signature = parseSignature(input.signature);
+  const now = input.now ?? Math.floor(Date.now() / 1000);
+  const age = Math.abs(now - signature.timestamp);
+  if (age > (input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) {
+    throw new SendoraError({
+      code: 'stale_signature',
+      status: null,
+      message: `The signature is ${String(age)} seconds old, more than the tolerance allows.`,
+    });
+  }
+  const body = typeof input.body === 'string' ? encoder.encode(input.body) : input.body;
+  const signed = concat(encoder.encode(`${String(signature.timestamp)}.`), body);
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(input.secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['verify'],
+  );
+  if (!(await crypto.subtle.verify('HMAC', key, signature.mac, signed))) {
+    throw invalidSignature('The signature does not match the body.');
+  }
+  return parseEvent(decoder.decode(body));
+}
+
+function parseSignature(header: string | null | undefined): {
+  timestamp: number;
+  mac: Uint8Array<ArrayBuffer>;
+} {
+  if (typeof header !== 'string' || header === '') {
+    throw invalidSignature('The request carries no Sendora-Signature header.');
+  }
+  const parts = new Map<string, string>();
+  for (const part of header.split(',')) {
+    const separator = part.indexOf('=');
+    if (separator > 0) {
+      parts.set(part.slice(0, separator).trim(), part.slice(separator + 1).trim());
+    }
+  }
+  const timestamp = Number(parts.get('t'));
+  const hex = parts.get('v1');
+  if (!Number.isInteger(timestamp) || hex === undefined || !MAC_HEX.test(hex)) {
+    throw invalidSignature('The Sendora-Signature header is malformed.');
+  }
+  const mac = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < mac.length; i += 1) {
+    mac[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return { timestamp, mac };
+}
+
+function parseEvent(text: string): WebhookEvent {
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    throw unknownEvent();
+  }
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    !('event' in value) ||
+    typeof value.event !== 'string' ||
+    !eventNames.has(value.event) ||
+    !('id' in value) ||
+    typeof value.id !== 'string' ||
+    !('attempt' in value) ||
+    typeof value.attempt !== 'number'
+  ) {
+    throw unknownEvent();
+  }
+  return value as WebhookEvent;
+}
+
+function invalidSignature(message: string): SendoraError {
+  return new SendoraError({ code: 'invalid_signature', status: null, message });
+}
+
+function unknownEvent(): SendoraError {
+  return new SendoraError({
+    code: 'unexpected_response',
+    status: null,
+    message: 'The body is signed but is not an event this SDK knows.',
+  });
+}
+
+function concat(head: Uint8Array, tail: Uint8Array): Uint8Array<ArrayBuffer> {
+  const joined = new Uint8Array(head.length + tail.length);
+  joined.set(head, 0);
+  joined.set(tail, head.length);
+  return joined;
+}

package/src/webhooks.ts

@@ -0,0 +1,157 @@
+import { paginate } from './pagination.ts';
+import type { Transport } from './transport.ts';
+import type {
+  CreatedWebhook,
+  CreateWebhookRequest,
+  Delivery,
+  DeliveryPage,
+  DeliveryQuery,
+  ReceiveOptions,
+  RequestOptions,
+  Webhook,
+  WebhookEvent,
+  WebhookList,
+} from './types.ts';
+import { verifyWebhook } from './webhook-verify.ts';
+
+/** Where the server's events are posted, every delivery of them, and the receiving side. */
+export class WebhooksResource {
+  readonly #transport: Transport;
+
+  constructor(transport: Transport) {
+    this.#transport = transport;
+  }
+
+  /**
+   * Registers an https URL on a public host to receive events, all of them
+   * unless `events` narrows it, from every stream unless `streamId` limits
+   * it to one. The answer carries the signing `secret` once; keep it
+   * beside the token and hand it to `receive` or `verifyWebhook`.
+   *
+   * @example
+   * const { secret } = await sendora.webhooks.create({
+   *   url: 'https://example.se/hooks/sendora',
+   *   events: ['delivered', 'bounced', 'spam_complaint'],
+   * });
+   */
+  create(request: CreateWebhookRequest, options: RequestOptions = {}): Promise<CreatedWebhook> {
+    return this.#transport.request<CreatedWebhook>({
+      method: 'POST',
+      path: '/v1/webhooks',
+      body: request,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /** Every webhook of the server. */
+  list(options: RequestOptions = {}): Promise<WebhookList> {
+    return this.#transport.request<WebhookList>({
+      method: 'GET',
+      path: '/v1/webhooks',
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** One webhook by id. */
+  get(webhookId: string, options: RequestOptions = {}): Promise<Webhook> {
+    return this.#transport.request<Webhook>({
+      method: 'GET',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** Removes the webhook; deliveries still pending are dropped with it. */
+  delete(webhookId: string, options: RequestOptions = {}): Promise<void> {
+    return this.#transport.request<undefined>({
+      method: 'DELETE',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}`,
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * One page of the events handed to the webhook, newest first, with the
+   * outcome of the last attempt; `status` narrows to `pending`,
+   * `delivered` or `dead`.
+   *
+   * @example
+   * const { deliveries } = await sendora.webhooks.deliveries(webhookId, { status: 'dead' });
+   */
+  deliveries(
+    webhookId: string,
+    query: DeliveryQuery = {},
+    options: RequestOptions = {},
+  ): Promise<DeliveryPage> {
+    return this.#transport.request<DeliveryPage>({
+      method: 'GET',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}/deliveries`,
+      query: { limit: query.limit, after: query.after, status: query.status },
+      idempotent: true,
+      signal: options.signal,
+    });
+  }
+
+  /** Every delivery the query matches, page by page, for `for await`. */
+  deliveriesAll(
+    webhookId: string,
+    query: DeliveryQuery = {},
+    options: RequestOptions = {},
+  ): AsyncIterable<Delivery> {
+    return paginate(
+      (after) => this.deliveries(webhookId, { ...query, after }, options),
+      (page) => page.deliveries,
+      (page) => page.next,
+      query.after,
+    );
+  }
+
+  /**
+   * Queues a delivery again, whatever its state, with the same payload.
+   *
+   * @example
+   * for await (const dead of sendora.webhooks.deliveriesAll(webhookId, { status: 'dead' })) {
+   *   await sendora.webhooks.replay(webhookId, dead.deliveryId);
+   * }
+   */
+  replay(webhookId: string, deliveryId: string, options: RequestOptions = {}): Promise<Delivery> {
+    return this.#transport.request<Delivery>({
+      method: 'POST',
+      path: `/v1/webhooks/${encodeURIComponent(webhookId)}/deliveries/${encodeURIComponent(deliveryId)}/replay`,
+      idempotent: false,
+      signal: options.signal,
+    });
+  }
+
+  /**
+   * The receiving side for any framework that hands you a Fetch `Request`
+   * (Next.js route handlers, Hono, SvelteKit, Cloudflare Workers): reads the
+   * raw body, verifies the signature with the webhook's secret and answers
+   * the typed event. For Express or Fastify, pass the raw body to
+   * `verifyWebhook` instead. Answer 2xx quickly and do the work afterwards;
+   * deliveries arrive at least once, so key your handling on `event.id`.
+   *
+   * @example
+   * export async function POST(request: Request) {
+   *   const event = await sendora.webhooks.receive(request, process.env.SENDORA_WEBHOOK_SECRET);
+   *   await queue.push(event);
+   *   return new Response(null, { status: 204 });
+   * }
+   */
+  async receive(
+    request: Request,
+    secret: string | undefined,
+    options: ReceiveOptions = {},
+  ): Promise<WebhookEvent> {
+    return verifyWebhook({
+      secret,
+      signature: request.headers.get('sendora-signature'),
+      body: new Uint8Array(await request.arrayBuffer()),
+      toleranceSeconds: options.toleranceSeconds,
+    });
+  }
+}