@posthaste/sdk 0.1.0

package/dist/pagination.js

@@ -0,0 +1,69 @@
+/**
+ * Keyset pagination.
+ *
+ * The API pages by cursor rather than by offset: `limit` + `before`, answering
+ * with `{ data, hasMore, nextCursor }`. `before` is the id of the last row you
+ * received, which is what `nextCursor` hands you.
+ *
+ * THE TRAP THIS MODULE EXISTS TO CLOSE
+ *
+ * The obvious loop is `while (nextCursor) { … }`. It is wrong. `nextCursor` is
+ * derived from the last row of a page, and at least one endpoint on this API
+ * returns a non-null cursor on its final page — the documentation calls it out
+ * for `/v1/inbound/messages`. A cursor loop over such an endpoint asks for the
+ * page after the last one, gets an empty page with the same cursor back, and
+ * spins forever. Nothing about it looks wrong in a log; it just never finishes.
+ *
+ * `hasMore` is the server's actual answer to "is there another page", computed
+ * by fetching one row more than you asked for. It is the only correct
+ * condition, so `autoPaginate` is the API this SDK puts in front of people —
+ * `list` is still there for anyone who wants a single page.
+ */
+/**
+ * Walk every page and yield every item.
+ *
+ * Belt and braces, because an infinite loop in someone's job runner is a bad
+ * way to learn about a contract change:
+ *
+ *   - stops on `hasMore === false`, always;
+ *   - stops if a page comes back empty, because there is nothing to advance to;
+ *   - stops if the cursor does not MOVE, which is what a non-null terminal
+ *     cursor looks like from here.
+ */
+export async function* autoPaginate(fetchPage, params) {
+    let before = params.before;
+    let seen;
+    for (;;) {
+        const page = await fetchPage({ ...params, before });
+        for (const item of page.data)
+            yield item;
+        if (!page.hasMore)
+            return;
+        if (page.data.length === 0)
+            return;
+        // Prefer the server's cursor; fall back to the last row's id, which is what
+        // the cursor is anyway. Either way the NEXT request must ask for something
+        // different from the last one.
+        const next = page.nextCursor ?? page.data[page.data.length - 1]?.id;
+        if (!next || next === seen)
+            return;
+        seen = next;
+        before = next;
+    }
+}
+/**
+ * Collect an auto-paginated stream into an array.
+ *
+ * `maxItems` is not optional garnish. Draining an unbounded list into memory is
+ * how a helper like this turns into an incident on the one account that has
+ * four million messages, so there is a ceiling and the caller chooses it.
+ */
+export async function collect(source, maxItems) {
+    const out = [];
+    for await (const item of source) {
+        out.push(item);
+        if (out.length >= maxItems)
+            break;
+    }
+    return out;
+}

package/dist/types.d.ts

@@ -0,0 +1,593 @@
+/**
+ * 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.
+ */
+import type { AccountId, ApiKeyId, DomainId, InvoiceId, MessageId, PaymentId, SubscriptionId, SuppressionId, WebhookId } from './ids.js';
+/** `message_status` in the database. The lifecycle a message can be in. */
+export declare const MESSAGE_STATUSES: readonly ['queued', 'sending', 'delivered', 'bounced', 'complained', 'failed', 'rejected'];
+export type MessageStatus = (typeof MESSAGE_STATUSES)[number];
+/**
+ * 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 declare const EVENT_TYPES: readonly ['accepted', 'queued', 'attempted', 'delivered', 'deferred', 'bounced', 'complained', 'failed', 'rejected', 'suppressed'];
+export type EventType = (typeof EVENT_TYPES)[number];
+/**
+ * `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 declare const SUPPRESSION_REASONS: readonly ['hard_bounce', 'complaint', 'manual', 'unsubscribe', 'spam_trap'];
+export type SuppressionReason = (typeof SUPPRESSION_REASONS)[number];
+/** `domain_status`. */
+export type DomainStatus = 'pending' | 'verified' | 'failed' | 'disabled';
+/** `account_status`. */
+export type AccountStatus = 'active' | 'suspended' | 'closed';
+/** `webhook_status`. */
+export type WebhookStatus = 'active' | 'disabled';
+/** `subscription_status`. */
+export type SubscriptionStatus = 'incomplete' | 'active' | 'past_due' | 'paused' | 'cancelled' | 'expired';
+/** `payment_status`. */
+export type PaymentStatus = 'created' | 'authorized' | 'captured' | 'failed' | 'refunded' | 'partially_refunded';
+export type PlanId = 'free' | 'starter' | 'growth' | 'scale' | 'enterprise';
+export type KeyEnvironment = 'live' | 'test';
+/**
+ * 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 declare const SCOPES: readonly ['account:read', 'domains:read', 'domains:write', 'emails:send', 'messages:read', 'suppressions:read', 'suppressions:write', 'webhooks:read', 'webhooks:write'];
+export type Scope = (typeof SCOPES)[number];
+/**
+ * A keyset page.
+ *
+ * `hasMore` is the ONLY correct loop condition. `nextCursor` is populated from
+ * the last row of a full page, and there are endpoints and edge cases where it
+ * is non-null on the final page — a `while (nextCursor)` loop over those never
+ * terminates. `autoPaginate` on each resource encodes the right condition so
+ * this cannot be got wrong by hand.
+ */
+export interface Page<T> {
+    data: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+/** A list that is not paginated. Returned whole. */
+export interface List<T> {
+    data: T[];
+}
+export interface PaginationParams {
+    /** Page size. Messages cap at 100, suppressions at 200. */
+    limit?: number;
+    /** The `nextCursor` from the previous page. */
+    before?: string;
+}
+export interface AccountPlan {
+    id: PlanId;
+    name: string;
+    monthlyEmails: number;
+    /** `null` means unlimited. */
+    maxDomains: number | null;
+    retentionDays: number;
+    dedicatedIp: boolean;
+}
+export interface AccountSubscriptionSummary {
+    status: SubscriptionStatus;
+    graceEndsAt: string | null;
+    cancelAtPeriodEnd: boolean;
+}
+export interface AccountSending {
+    dailyLimit: number;
+    sentToday: number;
+    remainingToday: number;
+    warmupTier: number;
+    sentThisMonth: number;
+    remainingThisMonth: number;
+}
+export interface Account {
+    id: AccountId;
+    name: string;
+    slug: string;
+    status: AccountStatus;
+    environment: KeyEnvironment;
+    scopes: string[];
+    /** Null only on an account with no warmup row — in practice, never. */
+    plan: AccountPlan | null;
+    /** Present only while there is something to say about the subscription. */
+    subscription: AccountSubscriptionSummary | null;
+    sending: AccountSending | null;
+}
+/** `GET /v1/account/verify` — a replay of the whole event chain. */
+export interface ChainVerification {
+    intact: boolean;
+    /** The sequence number at which the record stops being trustworthy. */
+    brokenAt: number | null;
+    problem: string | null;
+    checked: string;
+}
+export interface UsageDay {
+    /** `YYYY-MM-DD`. */
+    day: string;
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+}
+export interface Usage {
+    /** `YYYY-MM-DD`, first day of the current UTC month. */
+    periodStart: string;
+    periodEnd: string;
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    /** Null while nothing has been sent — not zero, which would be a claim. */
+    deliveryRate: number | null;
+    complaintRate: number | null;
+    bounceRate: number | null;
+    days: UsageDay[];
+}
+export interface DnsRecord {
+    name: string;
+    type: 'TXT' | 'MX' | 'CNAME';
+    value: string;
+    /** TXT values over 255 characters have to be published as split strings. */
+    chunks?: string[];
+    /** Only required records gate verification. Only DKIM is required. */
+    required: boolean;
+    purpose: string;
+    /** Present when publishing the record carries a risk (SPF, DMARC). */
+    warning?: string;
+}
+export interface CreateDomainParams {
+    name: string;
+}
+export interface CreatedDomain {
+    id: DomainId;
+    name: string;
+    status: 'pending';
+    records: DnsRecord[];
+}
+export interface Domain {
+    id: DomainId;
+    name: string;
+    status: DomainStatus;
+    verifiedAt: string | null;
+    createdAt: string;
+    /** Which DKIM key signs this domain's mail, so a rotation is visible. */
+    selector: string;
+    /** Messages ever sent from it. Non-zero is what makes deletion refused. */
+    messagesSent: number;
+    lastCheckedAt: string | null;
+    /** Returned on the LIST too, so the setup values are never lost with a tab. */
+    records: DnsRecord[];
+}
+export type CheckStatus = 'pass' | 'fail' | 'not_found';
+export interface RecordCheck {
+    record: 'dkim' | 'spf' | 'dmarc';
+    name: string;
+    required: boolean;
+    status: CheckStatus;
+    detail: string;
+}
+export interface DomainVerification {
+    id: DomainId;
+    name: string;
+    status: 'verified' | 'failed';
+    verified: boolean;
+    /** Every check is reported, passing or not. */
+    checks: RecordCheck[];
+}
+export interface DnsHost {
+    id: string;
+    name: string;
+    url: string;
+    note: string | null;
+    nameservers: string[];
+}
+export interface DomainSetup {
+    /** Who runs this domain's DNS, when we could work it out. */
+    host: DnsHost | null;
+    /** Present only when the provider supports one-click publishing. */
+    oneClick: {
+        provider: string;
+        url: string;
+    } | null;
+}
+export interface ConnectCloudflareParams {
+    /**
+     * A Cloudflare API token with Zone:DNS:Edit on the zone. Optional only when
+     * a token was previously stored with `remember`.
+     */
+    token?: string;
+    /** Store the token, so adding a second domain needs no paste. */
+    remember?: boolean;
+}
+export interface CloudflarePublishResult {
+    published: Array<{
+        type: 'TXT';
+        name: string;
+        created: boolean;
+    }>;
+    zone: string;
+    verified: boolean;
+    message: string;
+    /** SPF and DMARC — deliberately left alone, and said so. */
+    notPublished: Array<{
+        type: string;
+        name: string;
+        value: string;
+        why: string;
+    }>;
+}
+export interface SendEmailParams {
+    from: string;
+    to: string;
+    subject?: string;
+    text?: string;
+    html?: string;
+    replyTo?: string;
+    headers?: Record<string, string>;
+    listUnsubscribe?: string;
+    /**
+     * Idempotency key — a BODY field, not a header.
+     *
+     * The `Idempotency-Key` HTTP header is CORS-allowlisted by the API but no
+     * handler reads it, so sending it buys nothing. This field is the one the
+     * server checks. Supplying it also makes the send safe for this SDK to
+     * retry; without it a send is never retried automatically.
+     */
+    idempotencyKey?: string;
+}
+export interface SendEmailResult {
+    id: MessageId;
+    /**
+     * `queued` for a new send (HTTP 202), `duplicate` for an idempotency replay
+     * (HTTP 200). Both are success, and both carry the id of the one real
+     * message.
+     */
+    status: 'queued' | 'duplicate';
+    /**
+     * True when this request matched an earlier one by `idempotencyKey` and no
+     * new message was created. Surfaced rather than hidden, because "we did
+     * nothing, here is the thing you already sent" is a materially different
+     * answer from "accepted".
+     */
+    duplicate: boolean;
+}
+export interface ListMessagesParams extends PaginationParams {
+    /** Max 100, default 25. */
+    limit?: number;
+    status?: MessageStatus;
+    /** Exact recipient. Resolves through an equality index. */
+    to?: string;
+    /** Free text over recipient and subject. */
+    search?: string;
+    /** A `dom_` id, not a domain name. */
+    domain?: string;
+    /** ISO-8601. Inclusive. */
+    from?: string;
+    /** ISO-8601. Exclusive. */
+    until?: string;
+}
+export interface MessageSummary {
+    id: MessageId;
+    from: string;
+    to: string;
+    subject: string | null;
+    status: MessageStatus;
+    attempts: number;
+    smtpCode: number | null;
+    createdAt: string;
+}
+export interface WaybillEntry {
+    seq: number;
+    type: EventType;
+    at: string;
+    detail: Record<string, unknown> | null;
+    hash: string;
+    prevHash: string;
+}
+export interface MessageContent {
+    text: string | null;
+    html: string | null;
+    /** The composed, signed message as it went on the wire. */
+    raw: string | null;
+    replyTo: string | null;
+    headers: Record<string, string>;
+}
+export interface Message {
+    id: MessageId;
+    /** The hash chain over this message's own events was re-verified on read. */
+    recordIntact: boolean;
+    /** Present only when `recordIntact` is false. */
+    recordProblem?: string;
+    from: string;
+    to: string;
+    subject: string | null;
+    status: MessageStatus;
+    attempts: number;
+    smtp: {
+        code: number;
+        message: string | null;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+    /** Null once the body has aged out of the plan's retention window. */
+    content: MessageContent | null;
+    /** Every hand the message passed through, with its hash linkage. */
+    waybill: WaybillEntry[];
+}
+export interface MessageStatsParams {
+    /** 1–365, default 30. */
+    days?: number;
+    /** A `dom_` id. */
+    domain?: string;
+    /** An IANA zone, so buckets land on your midnight rather than UTC's. */
+    tz?: string;
+}
+export interface StatsDay {
+    /** `YYYY-MM-DD`. */
+    day: string;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    failed: number;
+    rejected: number;
+    pending: number;
+    total: number;
+}
+export interface StatsTotals {
+    delivered: number;
+    bounced: number;
+    complained: number;
+    failed: number;
+    rejected: number;
+    pending: number;
+    total: number;
+    /** Everything that has finished. Rates are over this, not over `total`. */
+    settled: number;
+    deliveryRate: number | null;
+    bounceRate: number | null;
+    complaintRate: number | null;
+}
+export interface MessageStats {
+    data: StatsDay[];
+    totals: StatsTotals;
+    /** The same window immediately before this one, for comparison. */
+    previous: StatsTotals;
+    change: {
+        total: number | null;
+        delivered: number | null;
+        bounced: number | null;
+        complained: number | null;
+    };
+    busiest: {
+        day: string;
+        total: number;
+    } | null;
+    /** The industry thresholds a sender is judged against, as percentages. */
+    thresholds: {
+        complaintRate: number;
+        bounceRate: number;
+    };
+    range: {
+        days: number;
+        tz: string;
+    };
+}
+export interface ListSuppressionsParams extends PaginationParams {
+    /** Max 200, default 50. */
+    limit?: number;
+    /** Partial address match. */
+    search?: string;
+    reason?: SuppressionReason;
+}
+export interface Suppression {
+    id: SuppressionId;
+    address: string;
+    reason: SuppressionReason;
+    detail: string | null;
+    createdAt: string;
+    /** A `platform` entry is not the account's to remove. */
+    scope: 'platform' | 'account';
+}
+export interface CreateSuppressionParams {
+    address: string;
+    /** Free text stored as the entry's detail. The reason is always `manual`. */
+    reason?: string;
+}
+export interface CreatedSuppression {
+    /** Normalised — lower-cased and trimmed by the server. */
+    address: string;
+    reason: 'manual';
+}
+export interface CreateWebhookParams {
+    /** http or https only. */
+    url: string;
+    /** Empty or absent means every event type. Max 20. */
+    eventTypes?: EventType[];
+}
+export interface CreatedWebhook {
+    id: WebhookId;
+    url: string;
+    eventTypes: EventType[];
+    status: 'active';
+    /**
+     * Shown exactly once, on creation, and never retrievable afterwards. Store
+     * it now — nobody, including us, can recover it.
+     */
+    signingSecret: string;
+}
+export interface Webhook {
+    id: WebhookId;
+    url: string;
+    eventTypes: EventType[];
+    status: WebhookStatus;
+    createdAt: string;
+}
+/** The JSON body delivered to a webhook endpoint. */
+export interface WebhookEvent {
+    /** Identical to the `posthaste-delivery-id` header. Deduplicate on it. */
+    id: string;
+    type: EventType;
+    createdAt: string;
+    data: {
+        /** Null for an event that is not about one specific message. */
+        messageId: MessageId | null;
+        detail?: Record<string, unknown>;
+    };
+}
+export interface ApiKey {
+    id: ApiKeyId;
+    name: string;
+    environment: KeyEnvironment;
+    scopes: string[];
+    /** Enough to recognise which key this is, not enough to use it. */
+    hint: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+    revokedAt: string | null;
+}
+export interface BillingCharge {
+    currency: string;
+    totalMinor: number;
+    baseMinor: number;
+    taxMinor: number;
+    taxLabel: string | null;
+    exportOfServices: boolean;
+    display: string;
+}
+export interface BillingPlan {
+    id: PlanId;
+    name: string;
+    /** The one published price, identical for everyone. */
+    priceUsd: number;
+    /** Never inferred from `priceUsd === 0` — Free is zero, Enterprise is not. */
+    custom: boolean;
+    /** Only sent for custom plans. */
+    items?: string[];
+    monthlyEmails: number;
+    /** `null` means unlimited. */
+    maxDomains: number | null;
+    retentionDays: number;
+    /** What this customer would actually be charged, in their currency. */
+    charge: BillingCharge | null;
+    /** The same figures in every currency we bill in, keyed by currency code. */
+    charges: Record<string, BillingCharge> | null;
+}
+export interface BillingSubscription {
+    id: SubscriptionId;
+    plan: PlanId;
+    status: SubscriptionStatus;
+    currency: string;
+    amountMinor: number;
+    interval: 'month' | 'year';
+    currentPeriodEnd: string | null;
+    graceEndsAt: string | null;
+    cancelAtPeriodEnd: boolean;
+    /** Only ever present while the subscription is `incomplete`. */
+    checkoutUrl: string | null;
+}
+export interface BillingProfile {
+    legalName: string | null;
+    billingEmail: string | null;
+    country: string | null;
+    taxIdKind: 'gst' | 'vat' | 'abn' | 'other' | null;
+    taxId: string | null;
+    currency: string | null;
+}
+export interface BillingPayment {
+    id: PaymentId;
+    kind: string;
+    status: PaymentStatus;
+    currency: string;
+    amountMinor: number;
+    taxAmountMinor: number;
+    method: string | null;
+    paidAt: string | null;
+    createdAt: string;
+    failureReason: string | null;
+    /** Null for a payment that failed — money that did not move has no document. */
+    invoiceId: InvoiceId | null;
+    invoiceNumber: string | null;
+}
+export interface Billing {
+    plan: {
+        id: PlanId;
+        name: string;
+        priceUsd: number;
+    };
+    subscription: BillingSubscription | null;
+    profile: BillingProfile | null;
+    payments: BillingPayment[];
+    plans: BillingPlan[];
+    /** False when the deployment has no payment provider configured. */
+    configured: boolean;
+}
+export interface BillingEvent {
+    seq: number;
+    type: string;
+    actor: string;
+    reason: string | null;
+    detail: Record<string, unknown>;
+    occurredAt: string;
+    hash: string;
+}
+export interface BillingHistory {
+    /** The chain replayed in the database, so the record can be checked. */
+    chain: {
+        valid: boolean;
+        brokenAt: number | null;
+        reason: string | null;
+    };
+    data: BillingEvent[];
+}
+export interface Invoice {
+    id: InvoiceId;
+    /** The number quoted to an accountant, e.g. `PH-2026-27-0001`. */
+    number: string;
+    issuedAt: string;
+    currency: string;
+    subtotalMinor: number;
+    taxMinor: number;
+    taxRateBp: number | null;
+    totalMinor: number;
+    paidMinor: number;
+    plan: string;
+    periodStart: string | null;
+    periodEnd: string | null;
+    buyer: {
+        name: string;
+        email: string | null;
+        country: string | null;
+        taxId: string | null;
+    };
+    payment: {
+        method: string | null;
+        reference: string | null;
+        paidAt: string | null;
+    };
+}
+/** The single-invoice fetch carries the supplier block the list omits. */
+export interface InvoiceDetail extends Invoice {
+    supplier: {
+        name: string;
+        lines: string[];
+    };
+}