@posthaste/sdk 0.1.0

package/dist/types.js

@@ -0,0 +1,76 @@
+/**
+ * The wire types.
+ *
+ * Every shape here was written from the handler that produces it — see
+ * `apps/api/src/app.ts`, `billing-routes.ts`, `dashboard-routes.ts` and
+ * `cloudflare-routes.ts` — rather than from the documentation, so a field
+ * present here is a field the server actually sends.
+ *
+ * Timestamps are ISO-8601 strings. They are `timestamptz` in Postgres and are
+ * JSON-serialised on the way out, so they arrive as strings however they were
+ * stored; typing them as `Date` would be a lie that only shows up at runtime.
+ */
+// ---------------------------------------------------------------------------
+// Enumerations
+// ---------------------------------------------------------------------------
+/** `message_status` in the database. The lifecycle a message can be in. */
+export const MESSAGE_STATUSES = [
+    'queued',
+    'sending',
+    'delivered',
+    'bounced',
+    'complained',
+    'failed',
+    'rejected',
+];
+/**
+ * The ten webhook event types (`event_type` in the database).
+ *
+ * Note that these are NOT the same set as `MessageStatus`: `accepted`,
+ * `attempted`, `deferred` and `suppressed` are things that happen to a message
+ * without changing the status it rests in.
+ */
+export const EVENT_TYPES = [
+    'accepted',
+    'queued',
+    'attempted',
+    'delivered',
+    'deferred',
+    'bounced',
+    'complained',
+    'failed',
+    'rejected',
+    'suppressed',
+];
+/**
+ * `suppression_reason` in the database.
+ *
+ * Spelled exactly as the server spells it. `hard_bounce` is by far the most
+ * common one, and guessing at `bounce` produces a filter that silently matches
+ * nothing rather than an error.
+ */
+export const SUPPRESSION_REASONS = [
+    'hard_bounce',
+    'complaint',
+    'manual',
+    'unsubscribe',
+    'spam_trap',
+];
+/**
+ * Every scope an API key can be granted.
+ *
+ * `billing:read` is absent on purpose: it is not in the API's grantable set —
+ * a session carries it, and the billing reads also accept `account:read`,
+ * which is what an API key uses to reach them.
+ */
+export const SCOPES = [
+    'account:read',
+    'domains:read',
+    'domains:write',
+    'emails:send',
+    'messages:read',
+    'suppressions:read',
+    'suppressions:write',
+    'webhooks:read',
+    'webhooks:write',
+];

package/dist/webhooks.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Webhook signature verification.
+ *
+ * A webhook endpoint is a URL on the public internet. Anyone who learns it can
+ * POST to it, so without a signature you cannot tell our delivery from a
+ * forgery — and a forged `bounced` event would make you suppress an address
+ * that is perfectly fine, while a forged `delivered` would hide a failure.
+ *
+ * The scheme:
+ *
+ *     posthaste-signature: t=<unix seconds>,v1=<hex>
+ *     signed payload      = `${t}.${rawBody}`
+ *     signature           = HMAC-SHA256(secret, signed payload), lower-case hex
+ *
+ * Signing the body alone would be replayable for ever. Binding the timestamp is
+ * what lets a receiver reject something stale, and `v1=` is a version tag so
+ * the scheme can change without breaking every receiver on the same day.
+ *
+ * This is a REIMPLEMENTATION of `packages/core/src/webhook-signature.ts`, not
+ * an import of it: `@email/core` is a private workspace package that could
+ * never resolve for somebody who installed this SDK from npm. The two are held
+ * together by a test that signs with core and verifies with this file, so they
+ * cannot drift apart silently.
+ */
+/** The header the signature arrives in. Lower-cased; HTTP headers are not case-sensitive. */
+export declare const SIGNATURE_HEADER = "posthaste-signature";
+/** Stable across every retry of the same event. Deduplicate on it. */
+export declare const DELIVERY_ID_HEADER = "posthaste-delivery-id";
+/** Which attempt this is, starting at 1. */
+export declare const ATTEMPT_HEADER = "posthaste-attempt";
+export type WebhookVerifyFailure = 'malformed_header' | 'unsupported_version' | 'timestamp_too_old' | 'timestamp_in_future' | 'signature_mismatch';
+/**
+ * Discriminated on `valid`, so a `if (!result.valid)` branch has the reason and
+ * a valid one carries no reason to accidentally log.
+ */
+export type WebhookVerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: WebhookVerifyFailure;
+};
+export interface VerifyWebhookOptions {
+    /** How far in either direction a timestamp may be. Default 300 seconds. */
+    toleranceSeconds?: number;
+    /** Injectable clock, so the replay window can actually be tested. */
+    nowSeconds?: number;
+}
+/**
+ * Verify a webhook delivery.
+ *
+ * `rawBody` MUST be the exact bytes we sent — `express.raw()`, `await
+ * req.text()`, `request.get_data()`. A parsed-then-re-serialised object will
+ * NEVER verify: `JSON.stringify` is free to reorder keys, drop insignificant
+ * whitespace and re-escape strings, and the signature covers the bytes, not the
+ * object they decode to. This is the single most common reason verification
+ * "mysteriously" fails, and no amount of correct key handling rescues it.
+ *
+ * @param rawBody  the request body, as bytes or as the exact string they decode to
+ * @param signatureHeader  the `posthaste-signature` header value
+ * @param secret  the `signingSecret` returned once when the webhook was created
+ */
+export declare function verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, options?: VerifyWebhookOptions): WebhookVerifyResult;
+/**
+ * Verify and parse in one step.
+ *
+ * Returns the decoded event on success and `null` on any failure, for the
+ * common case where the only thing a handler does with a bad delivery is
+ * answer 400. Use `verifyWebhook` directly when the reason matters.
+ */
+export declare function parseWebhookEvent<T = unknown>(rawBody: string | Uint8Array, signatureHeader: string | null | undefined, secret: string, options?: VerifyWebhookOptions): T | null;

package/dist/webhooks.js

@@ -0,0 +1,130 @@
+/**
+ * Webhook signature verification.
+ *
+ * A webhook endpoint is a URL on the public internet. Anyone who learns it can
+ * POST to it, so without a signature you cannot tell our delivery from a
+ * forgery — and a forged `bounced` event would make you suppress an address
+ * that is perfectly fine, while a forged `delivered` would hide a failure.
+ *
+ * The scheme:
+ *
+ *     posthaste-signature: t=<unix seconds>,v1=<hex>
+ *     signed payload      = `${t}.${rawBody}`
+ *     signature           = HMAC-SHA256(secret, signed payload), lower-case hex
+ *
+ * Signing the body alone would be replayable for ever. Binding the timestamp is
+ * what lets a receiver reject something stale, and `v1=` is a version tag so
+ * the scheme can change without breaking every receiver on the same day.
+ *
+ * This is a REIMPLEMENTATION of `packages/core/src/webhook-signature.ts`, not
+ * an import of it: `@email/core` is a private workspace package that could
+ * never resolve for somebody who installed this SDK from npm. The two are held
+ * together by a test that signs with core and verifies with this file, so they
+ * cannot drift apart silently.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/** The header the signature arrives in. Lower-cased; HTTP headers are not case-sensitive. */
+export const SIGNATURE_HEADER = 'posthaste-signature';
+/** Stable across every retry of the same event. Deduplicate on it. */
+export const DELIVERY_ID_HEADER = 'posthaste-delivery-id';
+/** Which attempt this is, starting at 1. */
+export const ATTEMPT_HEADER = 'posthaste-attempt';
+const SCHEME_VERSION = 'v1';
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Verify a webhook delivery.
+ *
+ * `rawBody` MUST be the exact bytes we sent — `express.raw()`, `await
+ * req.text()`, `request.get_data()`. A parsed-then-re-serialised object will
+ * NEVER verify: `JSON.stringify` is free to reorder keys, drop insignificant
+ * whitespace and re-escape strings, and the signature covers the bytes, not the
+ * object they decode to. This is the single most common reason verification
+ * "mysteriously" fails, and no amount of correct key handling rescues it.
+ *
+ * @param rawBody  the request body, as bytes or as the exact string they decode to
+ * @param signatureHeader  the `posthaste-signature` header value
+ * @param secret  the `signingSecret` returned once when the webhook was created
+ */
+export function verifyWebhook(rawBody, signatureHeader, secret, options = {}) {
+    if (typeof signatureHeader !== 'string' || signatureHeader.length === 0) {
+        return fail('malformed_header');
+    }
+    if (typeof secret !== 'string' || secret.length === 0) {
+        return fail('signature_mismatch');
+    }
+    const tolerance = options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+    const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+    /*
+     * Parsed BY KEY, never positionally.
+     *
+     * `v1=` is a version tag precisely so a `v2=` can be added beside it. A
+     * parser that reads "the second comma-separated field" breaks the day the
+     * order changes or a field is inserted — and breaks by reading the wrong
+     * value into the signature comparison, which fails closed but for the wrong
+     * reason and is maddening to debug.
+     */
+    const parts = new Map();
+    for (const piece of signatureHeader.split(',')) {
+        const idx = piece.indexOf('=');
+        if (idx > 0)
+            parts.set(piece.slice(0, idx).trim(), piece.slice(idx + 1).trim());
+    }
+    const t = parts.get('t');
+    const provided = parts.get(SCHEME_VERSION);
+    if (!t || !/^\d+$/.test(t))
+        return fail('malformed_header');
+    if (!provided) {
+        // A timestamp with no v1 is either a newer scheme we do not implement or a
+        // truncated header. Neither is acceptable, and they are worth telling apart.
+        return fail(parts.size > 1 ? 'unsupported_version' : 'malformed_header');
+    }
+    const timestamp = Number(t);
+    if (now - timestamp > tolerance)
+        return fail('timestamp_too_old');
+    /*
+     * A future timestamp is rejected too, and by the same tolerance.
+     *
+     * It is tempting to be generous about this on the grounds of clock skew. Do
+     * not: a signature dated an hour ahead is not skew, it is an attacker buying
+     * themselves an hour-long replay window with a request you would otherwise
+     * accept the whole time.
+     */
+    if (timestamp - now > tolerance)
+        return fail('timestamp_in_future');
+    const mac = createHmac('sha256', secret);
+    mac.update(`${timestamp}.`);
+    mac.update(rawBody);
+    const expected = mac.digest('hex');
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    /*
+     * Constant time, and length-checked first because timingSafeEqual throws on
+     * a length mismatch. A `===` here would leak how many leading hex characters
+     * matched, which is enough to forge a signature one character at a time.
+     */
+    if (a.length !== b.length || !timingSafeEqual(a, b))
+        return fail('signature_mismatch');
+    return { valid: true };
+}
+/**
+ * Verify and parse in one step.
+ *
+ * Returns the decoded event on success and `null` on any failure, for the
+ * common case where the only thing a handler does with a bad delivery is
+ * answer 400. Use `verifyWebhook` directly when the reason matters.
+ */
+export function parseWebhookEvent(rawBody, signatureHeader, secret, options = {}) {
+    const result = verifyWebhook(rawBody, signatureHeader, secret, options);
+    if (!result.valid)
+        return null;
+    const text = typeof rawBody === 'string' ? rawBody : Buffer.from(rawBody).toString('utf8');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function fail(reason) {
+    return { valid: false, reason };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@posthaste/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the Posthaste transactional email API.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "posthaste",
+    "email",
+    "transactional-email",
+    "smtp",
+    "webhooks"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}