@posthaste/sdk 0.1.0

package/dist/errors.js

@@ -0,0 +1,154 @@
+/**
+ * Errors.
+ *
+ * Every failure this SDK can produce arrives as a `PosthasteError`, including
+ * the ones that never touched the server (a socket that would not open, a
+ * request that timed out). One `catch` clause, one shape.
+ */
+export class PosthasteError extends Error {
+    name = 'PosthasteError';
+    /**
+     * The HTTP status. `0` when the request never got a response at all — a DNS
+     * failure, a refused connection, an abort. Checking `status >= 500` is
+     * therefore not a substitute for checking `type`.
+     */
+    status;
+    type;
+    /**
+     * Field-level detail, when the server sent any.
+     *
+     * `error.fields` appears on the 400s produced by the shared body validator
+     * and is ABSENT on the several 400s that are hand-written with a message
+     * only. Always treat it as optional; never index into it unchecked.
+     */
+    fields;
+    /**
+     * How long to wait, in seconds, when the server said. Taken from
+     * `error.retryAfterSeconds` (rate limiting) or the `Retry-After` header
+     * (quota exhaustion), in that order.
+     */
+    retryAfterSeconds;
+    /** The parsed body. `undefined` when there was nothing parseable. */
+    body;
+    constructor(init) {
+        super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+        this.status = init.status;
+        this.type = init.type;
+        if (init.fields)
+            this.fields = init.fields;
+        if (init.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = init.retryAfterSeconds;
+        if (init.body !== undefined)
+            this.body = init.body;
+    }
+    /**
+     * True for the two refusals that mean "your allowance is spent", as opposed
+     * to "you are going too fast".
+     *
+     * Both arrive as 429 with a `Retry-After`, and the status alone cannot tell
+     * them apart — which is exactly the trap that makes a naive retry loop hammer
+     * a wall for the rest of the month. This SDK never retries these in-process.
+     */
+    get isQuotaExhausted() {
+        return this.type === 'daily_limit_reached' || this.type === 'monthly_limit_reached';
+    }
+    /** True for the per-key request-rate limiter, which is short and transient. */
+    get isRateLimited() {
+        return this.type === 'rate_limited';
+    }
+}
+export function isPosthasteError(value) {
+    return value instanceof PosthasteError;
+}
+/**
+ * Turn a response body into an error.
+ *
+ * The API's own refusals use `{ error: { type, message, ... } }`. Two kinds of
+ * response do NOT, and both are parsed defensively here rather than assumed
+ * away:
+ *
+ *   An UNHANDLED 500. There is no `setErrorHandler` on the API, so a thrown
+ *   exception is serialised by Fastify's default handler as
+ *   `{ statusCode, error: "Internal Server Error", message }` — `error` is a
+ *   STRING. Reading `body.error.type` off that yields `undefined` and reading
+ *   `body.error.message` throws, which would turn the one response where a
+ *   caller most needs a clear message into a crash inside the SDK.
+ *
+ *   Anything that never reached the application at all — a proxy's HTML error
+ *   page, an empty body, a truncated response.
+ *
+ * Neither invents a `type`: both become `unknown_error`, so nothing downstream
+ * can mistake an unclassified failure for a documented one.
+ */
+export function errorFromResponse(status, rawBody, retryAfterHeader) {
+    let body;
+    try {
+        body = rawBody.length > 0 ? JSON.parse(rawBody) : undefined;
+    }
+    catch {
+        body = undefined;
+    }
+    const envelope = typeof body === 'object' && body !== null ? body.error : undefined;
+    const headerRetry = parseRetryAfter(retryAfterHeader);
+    // The documented shape: `error` is an object carrying a machine-readable type.
+    if (typeof envelope === 'object' && envelope !== null) {
+        const e = envelope;
+        const type = typeof e.type === 'string' ? e.type : 'unknown_error';
+        const message = typeof e.message === 'string' && e.message.length > 0
+            ? e.message
+            : `Posthaste request failed with status ${status}`;
+        const fields = Array.isArray(e.fields)
+            ? e.fields
+                .filter((f) => typeof f === 'object' && f !== null)
+                .map((f) => ({
+                path: typeof f.path === 'string' ? f.path : '',
+                message: typeof f.message === 'string' ? f.message : '',
+            }))
+            : undefined;
+        // The rate limiter puts its wait INSIDE the error object; the quota
+        // refusals put theirs in a Retry-After header. Prefer the body, because
+        // only it is specific to this refusal.
+        const bodyRetry = typeof e.retryAfterSeconds === 'number' ? e.retryAfterSeconds : undefined;
+        return new PosthasteError({
+            status,
+            type,
+            message,
+            ...(fields && fields.length > 0 ? { fields } : {}),
+            ...(bodyRetry !== undefined
+                ? { retryAfterSeconds: bodyRetry }
+                : headerRetry !== undefined
+                    ? { retryAfterSeconds: headerRetry }
+                    : {}),
+            body,
+        });
+    }
+    // Not the envelope. `error` may be a string ("Internal Server Error"), or
+    // there may be no body at all. Use whatever human-readable text exists.
+    const record = typeof body === 'object' && body !== null ? body : {};
+    const message = (typeof record.message === 'string' && record.message) ||
+        (typeof envelope === 'string' && envelope) ||
+        (rawBody.trim().length > 0 && rawBody.trim().length <= 300 ? rawBody.trim() : '') ||
+        `Posthaste request failed with status ${status}`;
+    return new PosthasteError({
+        status,
+        type: 'unknown_error',
+        message,
+        ...(headerRetry !== undefined ? { retryAfterSeconds: headerRetry } : {}),
+        ...(body !== undefined ? { body } : {}),
+    });
+}
+/**
+ * `Retry-After` is either a number of seconds or an HTTP date. The API sends
+ * seconds; a proxy in front of it may not.
+ */
+export function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const trimmed = header.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const at = Date.parse(trimmed);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}

package/dist/http.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The transport.
+ *
+ * Zero dependencies: global `fetch` and nothing else. Everything interesting
+ * lives here — authentication, query building, timeouts, the retry policy and
+ * the error mapping — so every resource method below is a one-liner and none
+ * of them can quietly disagree about how a failure is handled.
+ */
+import { parseRetryAfter } from './errors.js';
+/**
+ * A structural `fetch`.
+ *
+ * Deliberately minimal rather than `typeof globalThis.fetch`: the global type
+ * differs between DOM lib, `@types/node` and whatever a bundler injects, and an
+ * SDK that only needs a status, a header and a body should not force a consumer
+ * into one of them. The real `fetch` satisfies this; so does a five-line test
+ * shim, and so does a proxy-aware wrapper.
+ */
+export interface PosthasteResponse {
+    readonly status: number;
+    readonly headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+export interface PosthasteRequestInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}
+export type FetchLike = (url: string, init: PosthasteRequestInit) => Promise<PosthasteResponse>;
+export interface PosthasteOptions {
+    /** A `ph_live_…` or `ph_test_…` key. Sent as `Authorization: Bearer …`. */
+    apiKey: string;
+    /** Defaults to `https://api.posthastemail.dev`. No trailing slash needed. */
+    baseUrl?: string;
+    /**
+     * The `fetch` to use. Defaults to the global one.
+     *
+     * Injectable because it is genuinely useful — a proxy agent, a tracing
+     * wrapper, a mock — and because it is how this package's own integration test
+     * drives a real in-process Fastify app without opening a socket.
+     */
+    fetch?: FetchLike;
+    /** Per-attempt, not per-call. Default 30s. `0` disables the timeout. */
+    timeoutMs?: number;
+    /** Retries AFTER the first attempt. Default 2. `0` disables retrying. */
+    maxRetries?: number;
+    /**
+     * Longest server-requested wait this SDK will actually sit through, in
+     * milliseconds. Default 60s.
+     *
+     * A `Retry-After` beyond this is honoured by NOT retrying: a quota that frees
+     * at midnight is not something to block a request handler on, and sleeping
+     * through it would look like a hang.
+     */
+    maxRetryDelayMs?: number;
+    /** Extra headers on every request. Cannot override `authorization`. */
+    headers?: Record<string, string>;
+    /** Appended to the SDK's own `user-agent`. */
+    userAgent?: string;
+    /**
+     * How the SDK waits between retries. Advanced — exists so tests can assert
+     * backoff without spending real seconds on it.
+     */
+    sleep?: (ms: number) => Promise<void>;
+    /** Injectable randomness for retry jitter. Advanced; testing only. */
+    random?: () => number;
+}
+export interface RequestOptions {
+    /** Abort this call from outside. Composed with the client's own timeout. */
+    signal?: AbortSignal;
+    /** Extra headers for one call. */
+    headers?: Record<string, string>;
+}
+export interface InternalRequest {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /**
+     * Whether repeating this request is harmless.
+     *
+     * GET and DELETE always are. A POST is only idempotent when the server makes
+     * it so, and each call site says which it is — see `emails.send`, where the
+     * answer depends on whether the caller supplied an `idempotencyKey`.
+     */
+    idempotent: boolean;
+    options?: RequestOptions;
+}
+/** Kept in step with package.json — it is the only place it is stated twice. */
+export declare const SDK_VERSION = "0.1.0";
+export declare class HttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly doFetch;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly maxRetryDelayMs;
+    private readonly extraHeaders;
+    private readonly userAgent;
+    private readonly sleep;
+    private readonly random;
+    constructor(options: PosthasteOptions);
+    /** A request whose 204 or empty body is expected. */
+    requestVoid(req: InternalRequest): Promise<void>;
+    request<T>(req: InternalRequest): Promise<T>;
+    /**
+     * Send, retry, and map a failure onto a `PosthasteError`.
+     *
+     * Returns the status alongside the body text because the send path needs the
+     * status itself — 202 and 200 are both success there and mean different
+     * things — and a caller cannot recover it from the JSON.
+     */
+    send(req: InternalRequest): Promise<{
+        status: number;
+        text: string;
+    }>;
+    /**
+     * How long to wait before repeating this request, or `null` for "do not".
+     *
+     * The decision branches on `error.type` and NOT on the status, which is the
+     * whole point. All three of these are 429:
+     *
+     *   `rate_limited` — the per-key request limiter. Transient, measured in
+     *     seconds, and exactly what a retry is for.
+     *   `daily_limit_reached` — the warmup cap. `Retry-After` is the seconds
+     *     until midnight UTC.
+     *   `monthly_limit_reached` — the plan allowance. `Retry-After` can be
+     *     weeks.
+     *
+     * A retry loop written against the status treats the last two as a hiccup and
+     * hammers a wall it cannot get through until the calendar moves — burning the
+     * caller's own rate limit on requests that are all going to be refused.
+     */
+    private retryDelayFor;
+    private backoff;
+    /**
+     * Exponential with FULL jitter.
+     *
+     * Without jitter every client that failed on the same upstream blip retries
+     * in the same millisecond, and the recovery attempt is itself a thundering
+     * herd against a service that has only just come back.
+     */
+    private jitteredBackoff;
+    private attempt;
+    private buildUrl;
+}
+export { parseRetryAfter };

package/dist/http.js

@@ -0,0 +1,258 @@
+/**
+ * The transport.
+ *
+ * Zero dependencies: global `fetch` and nothing else. Everything interesting
+ * lives here — authentication, query building, timeouts, the retry policy and
+ * the error mapping — so every resource method below is a one-liner and none
+ * of them can quietly disagree about how a failure is handled.
+ */
+import { PosthasteError, errorFromResponse, parseRetryAfter } from './errors.js';
+const DEFAULT_BASE_URL = 'https://api.posthastemail.dev';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RETRY_DELAY_MS = 60_000;
+/** First backoff step. Doubles per attempt, with full jitter, capped at 8s. */
+const BASE_BACKOFF_MS = 500;
+const MAX_BACKOFF_MS = 8_000;
+/** Kept in step with package.json — it is the only place it is stated twice. */
+export const SDK_VERSION = '0.1.0';
+const defaultSleep = (ms) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    // Never hold a process open just to wait out a retry.
+    timer.unref?.();
+});
+export class HttpClient {
+    apiKey;
+    baseUrl;
+    doFetch;
+    timeoutMs;
+    maxRetries;
+    maxRetryDelayMs;
+    extraHeaders;
+    userAgent;
+    sleep;
+    random;
+    constructor(options) {
+        if (!options.apiKey || typeof options.apiKey !== 'string') {
+            throw new PosthasteError({
+                status: 0,
+                type: 'invalid_request',
+                message: 'A Posthaste API key is required: new Posthaste({ apiKey }).',
+            });
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (!fetchImpl) {
+            throw new PosthasteError({
+                status: 0,
+                type: 'invalid_request',
+                message: 'No global fetch is available in this runtime. Pass one: new Posthaste({ apiKey, fetch }).',
+            });
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.doFetch = fetchImpl;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.maxRetryDelayMs = options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS;
+        this.extraHeaders = options.headers ?? {};
+        this.userAgent = options.userAgent
+            ? `posthaste-sdk-node/${SDK_VERSION} ${options.userAgent}`
+            : `posthaste-sdk-node/${SDK_VERSION}`;
+        this.sleep = options.sleep ?? defaultSleep;
+        this.random = options.random ?? Math.random;
+    }
+    /** A request whose 204 or empty body is expected. */
+    async requestVoid(req) {
+        await this.send(req);
+    }
+    async request(req) {
+        const { status, text } = await this.send(req);
+        if (status === 204 || text.length === 0)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new PosthasteError({
+                status,
+                type: 'unknown_error',
+                message: `Posthaste returned a ${status} whose body is not JSON.`,
+                cause,
+            });
+        }
+    }
+    /**
+     * Send, retry, and map a failure onto a `PosthasteError`.
+     *
+     * Returns the status alongside the body text because the send path needs the
+     * status itself — 202 and 200 are both success there and mean different
+     * things — and a caller cannot recover it from the JSON.
+     */
+    async send(req) {
+        const url = this.buildUrl(req.path, req.query);
+        const headers = {
+            ...this.extraHeaders,
+            ...(req.options?.headers ?? {}),
+            accept: 'application/json',
+            'user-agent': this.userAgent,
+            // Last, so neither the per-client nor the per-call headers can replace it.
+            authorization: `Bearer ${this.apiKey}`,
+        };
+        let body;
+        if (req.body !== undefined) {
+            body = JSON.stringify(req.body);
+            headers['content-type'] = 'application/json';
+        }
+        let attempt = 0;
+        for (;;) {
+            let response;
+            try {
+                response = await this.attempt(url, { method: req.method, headers, body }, req.options);
+            }
+            catch (cause) {
+                const error = transportError(cause);
+                // A connection that never produced a response is safe to repeat only
+                // under the same rule as everything else: the request has to be one
+                // that repeating cannot duplicate.
+                if (req.idempotent && attempt < this.maxRetries) {
+                    await this.backoff(attempt, undefined);
+                    attempt += 1;
+                    continue;
+                }
+                throw error;
+            }
+            if (response.status < 400) {
+                return { status: response.status, text: await response.text() };
+            }
+            const text = await response.text();
+            const error = errorFromResponse(response.status, text, response.headers.get('retry-after') ?? null);
+            const wait = this.retryDelayFor(error, req, attempt);
+            if (wait === null)
+                throw error;
+            await this.sleep(wait);
+            attempt += 1;
+        }
+    }
+    /**
+     * How long to wait before repeating this request, or `null` for "do not".
+     *
+     * The decision branches on `error.type` and NOT on the status, which is the
+     * whole point. All three of these are 429:
+     *
+     *   `rate_limited` — the per-key request limiter. Transient, measured in
+     *     seconds, and exactly what a retry is for.
+     *   `daily_limit_reached` — the warmup cap. `Retry-After` is the seconds
+     *     until midnight UTC.
+     *   `monthly_limit_reached` — the plan allowance. `Retry-After` can be
+     *     weeks.
+     *
+     * A retry loop written against the status treats the last two as a hiccup and
+     * hammers a wall it cannot get through until the calendar moves — burning the
+     * caller's own rate limit on requests that are all going to be refused.
+     */
+    retryDelayFor(error, req, attempt) {
+        if (attempt >= this.maxRetries)
+            return null;
+        if (!req.idempotent)
+            return null;
+        // Quota exhaustion. Never in-process, whatever Retry-After says.
+        if (error.isQuotaExhausted)
+            return null;
+        const retryable = error.isRateLimited || error.status === 408 || error.status === 429 || error.status >= 500;
+        if (!retryable)
+            return null;
+        if (error.retryAfterSeconds !== undefined) {
+            const requested = error.retryAfterSeconds * 1000;
+            // Honour it — unless honouring it would mean blocking for longer than a
+            // caller could reasonably want, in which case give them the error back
+            // and let them decide.
+            if (requested > this.maxRetryDelayMs)
+                return null;
+            return Math.max(0, requested);
+        }
+        return this.jitteredBackoff(attempt);
+    }
+    async backoff(attempt, retryAfterMs) {
+        await this.sleep(retryAfterMs ?? this.jitteredBackoff(attempt));
+    }
+    /**
+     * Exponential with FULL jitter.
+     *
+     * Without jitter every client that failed on the same upstream blip retries
+     * in the same millisecond, and the recovery attempt is itself a thundering
+     * herd against a service that has only just come back.
+     */
+    jitteredBackoff(attempt) {
+        const ceiling = Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** attempt);
+        return Math.round(this.random() * ceiling);
+    }
+    async attempt(url, init, options) {
+        if (this.timeoutMs <= 0 && !options?.signal) {
+            return this.doFetch(url, init);
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort(options?.signal?.reason);
+        let timer;
+        if (options?.signal) {
+            if (options.signal.aborted)
+                abort();
+            else
+                options.signal.addEventListener('abort', abort, { once: true });
+        }
+        if (this.timeoutMs > 0) {
+            timer = setTimeout(() => controller.abort(new TimeoutAbort()), this.timeoutMs);
+            timer.unref?.();
+        }
+        try {
+            return await this.doFetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            options?.signal?.removeEventListener('abort', abort);
+        }
+    }
+    buildUrl(path, query) {
+        const search = [];
+        for (const [key, value] of Object.entries(query ?? {})) {
+            // `undefined` means "not asked for". `null` is never produced by the
+            // param builders, and an empty string is a real, if odd, filter.
+            if (value === undefined)
+                continue;
+            search.push(`${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`);
+        }
+        return `${this.baseUrl}${path}${search.length > 0 ? `?${search.join('&')}` : ''}`;
+    }
+}
+/** Marker so an abort we caused is distinguishable from one the caller caused. */
+class TimeoutAbort extends Error {
+    constructor() {
+        super('Posthaste request timed out');
+        this.name = 'PosthasteTimeout';
+    }
+}
+function transportError(cause) {
+    const timedOut = cause instanceof TimeoutAbort ||
+        (typeof cause === 'object' &&
+            cause !== null &&
+            cause.name === 'PosthasteTimeout') ||
+        (typeof cause === 'object' &&
+            cause !== null &&
+            cause.cause instanceof TimeoutAbort);
+    if (timedOut) {
+        return new PosthasteError({
+            status: 0,
+            type: 'timeout',
+            message: 'The Posthaste request timed out before the server responded.',
+            cause,
+        });
+    }
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new PosthasteError({
+        status: 0,
+        type: 'connection_error',
+        message: `Could not reach Posthaste: ${message}`,
+        cause,
+    });
+}
+export { parseRetryAfter };

package/dist/ids.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public identifiers.
+ *
+ * The API never returns a bare UUID. Every id is `<prefix>_<22 chars of
+ * base64url>`, which means a value that turns up in a log or a support ticket
+ * announces what it is, and passing a domain id where a message id belongs is
+ * visible rather than silent.
+ *
+ * The template-literal types below encode that on the way OUT — a `MessageId`
+ * read off a response is known to start `msg_`. They are deliberately NOT used
+ * on the way IN: an id loaded from your own database is a `string`, and
+ * demanding a cast to pass it back would be a type that punishes correct code.
+ * Every method therefore accepts a plain `string` and returns a prefixed one.
+ */
+export type PrefixedId<Prefix extends string> = `${Prefix}_${string}`;
+export type AccountId = PrefixedId<'acct'>;
+export type ApiKeyId = PrefixedId<'key'>;
+export type DomainId = PrefixedId<'dom'>;
+export type MessageId = PrefixedId<'msg'>;
+export type EventId = PrefixedId<'evt'>;
+export type SuppressionId = PrefixedId<'sup'>;
+export type WebhookId = PrefixedId<'whk'>;
+export type SubscriptionId = PrefixedId<'sub'>;
+export type PaymentId = PrefixedId<'pay'>;
+export type InvoiceId = PrefixedId<'inv'>;

package/dist/ids.js

@@ -0,0 +1,15 @@
+/**
+ * Public identifiers.
+ *
+ * The API never returns a bare UUID. Every id is `<prefix>_<22 chars of
+ * base64url>`, which means a value that turns up in a log or a support ticket
+ * announces what it is, and passing a domain id where a message id belongs is
+ * visible rather than silent.
+ *
+ * The template-literal types below encode that on the way OUT — a `MessageId`
+ * read off a response is known to start `msg_`. They are deliberately NOT used
+ * on the way IN: an id loaded from your own database is a `string`, and
+ * demanding a cast to pass it back would be a type that punishes correct code.
+ * Every method therefore accepts a plain `string` and returns a prefixed one.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @posthaste/sdk — the official TypeScript SDK for the Posthaste
+ * transactional email API.
+ *
+ * Zero runtime dependencies: global `fetch` and `node:crypto`, nothing else.
+ */
+export { Posthaste } from './client.js';
+export { AccountResource, ApiKeysResource, BillingResource, DomainsResource, EmailsResource, MessagesResource, SuppressionsResource, WebhooksResource, } from './client.js';
+export { PosthasteError, isPosthasteError, type PosthasteErrorType, type KnownErrorType, type FieldError, } from './errors.js';
+export { SDK_VERSION, type PosthasteOptions, type RequestOptions, type FetchLike, type PosthasteRequestInit, type PosthasteResponse, } from './http.js';
+export { autoPaginate, collect, type PageFetcher } from './pagination.js';
+export { verifyWebhook, parseWebhookEvent, SIGNATURE_HEADER, DELIVERY_ID_HEADER, ATTEMPT_HEADER, type VerifyWebhookOptions, type WebhookVerifyResult, type WebhookVerifyFailure, } from './webhooks.js';
+export type { AccountId, ApiKeyId, DomainId, EventId, InvoiceId, MessageId, PaymentId, PrefixedId, SubscriptionId, SuppressionId, WebhookId, } from './ids.js';
+export { EVENT_TYPES, MESSAGE_STATUSES, SCOPES, SUPPRESSION_REASONS, type Account, type AccountPlan, type AccountSending, type AccountStatus, type AccountSubscriptionSummary, type ApiKey, type Billing, type BillingCharge, type BillingEvent, type BillingHistory, type BillingPayment, type BillingPlan, type BillingProfile, type BillingSubscription, type ChainVerification, type CheckStatus, type CloudflarePublishResult, type ConnectCloudflareParams, type CreateDomainParams, type CreateSuppressionParams, type CreateWebhookParams, type CreatedDomain, type CreatedSuppression, type CreatedWebhook, type DnsHost, type DnsRecord, type Domain, type DomainSetup, type DomainStatus, type DomainVerification, type EventType, type Invoice, type InvoiceDetail, type KeyEnvironment, type List, type ListMessagesParams, type ListSuppressionsParams, type Message, type MessageContent, type MessageStats, type MessageStatsParams, type MessageStatus, type MessageSummary, type Page, type PaginationParams, type PaymentStatus, type PlanId, type RecordCheck, type Scope, type SendEmailParams, type SendEmailResult, type StatsDay, type StatsTotals, type SubscriptionStatus, type Suppression, type SuppressionReason, type Usage, type UsageDay, type WaybillEntry, type Webhook, type WebhookEvent, type WebhookStatus, } from './types.js';
+export { Posthaste as default } from './client.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @posthaste/sdk — the official TypeScript SDK for the Posthaste
+ * transactional email API.
+ *
+ * Zero runtime dependencies: global `fetch` and `node:crypto`, nothing else.
+ */
+export { Posthaste } from './client.js';
+export { AccountResource, ApiKeysResource, BillingResource, DomainsResource, EmailsResource, MessagesResource, SuppressionsResource, WebhooksResource, } from './client.js';
+export { PosthasteError, isPosthasteError, } from './errors.js';
+export { SDK_VERSION, } from './http.js';
+export { autoPaginate, collect } from './pagination.js';
+export { verifyWebhook, parseWebhookEvent, SIGNATURE_HEADER, DELIVERY_ID_HEADER, ATTEMPT_HEADER, } from './webhooks.js';
+export { EVENT_TYPES, MESSAGE_STATUSES, SCOPES, SUPPRESSION_REASONS, } from './types.js';
+export { Posthaste as default } from './client.js';

package/dist/pagination.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+import type { Page, PaginationParams } from './types.js';
+export type PageFetcher<TItem, TParams> = (params: TParams) => Promise<Page<TItem>>;
+/**
+ * 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 declare function autoPaginate<TItem extends {
+    id: string;
+}, TParams extends PaginationParams>(fetchPage: PageFetcher<TItem, TParams>, params: TParams): AsyncGenerator<TItem, void, undefined>;
+/**
+ * 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 declare function collect<T>(source: AsyncIterable<T>, maxItems: number): Promise<T[]>;