@posthaste/sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,459 @@
+/**
+ * The client.
+ *
+ * One class, one resource object per area of the API, and every method a thin
+ * declaration of a URL, a method, a body and — the only interesting bit —
+ * whether repeating the request is safe.
+ *
+ * Scope: the API-KEY surface only. Endpoints that require a browser session
+ * (sign-in, checkout, profile, minting keys) are deliberately absent, because
+ * they refuse a Bearer token and an SDK method that can only ever 403 is worse
+ * than no method. `/admin/v1/*` is absent for the same reason. `/v1/inbound/*`
+ * is absent because a customer cannot use it — see the README.
+ */
+import { HttpClient } from './http.js';
+import { autoPaginate as paginate, collect } from './pagination.js';
+export class Posthaste {
+    http;
+    account;
+    domains;
+    emails;
+    messages;
+    suppressions;
+    webhooks;
+    apiKeys;
+    billing;
+    constructor(options) {
+        this.http = new HttpClient(options);
+        this.account = new AccountResource(this.http);
+        this.domains = new DomainsResource(this.http);
+        this.emails = new EmailsResource(this.http);
+        this.messages = new MessagesResource(this.http);
+        this.suppressions = new SuppressionsResource(this.http);
+        this.webhooks = new WebhooksResource(this.http);
+        this.apiKeys = new ApiKeysResource(this.http);
+        this.billing = new BillingResource(this.http);
+    }
+}
+// ---------------------------------------------------------------------------
+// Account
+// ---------------------------------------------------------------------------
+export class AccountResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** `GET /v1/me` — who this key belongs to, its scopes, plan and sending caps. */
+    me(options) {
+        return this.http.request({ method: 'GET', path: '/v1/me', idempotent: true, options });
+    }
+    /**
+     * `GET /v1/account/verify` — replay the account's ENTIRE event chain.
+     *
+     * The strong claim, not the per-message one: nothing in the whole delivery
+     * history has been altered or removed. Expensive by design; not a health
+     * check to run on every request.
+     */
+    verify(options) {
+        return this.http.request({
+            method: 'GET',
+            path: '/v1/account/verify',
+            idempotent: true,
+            options,
+        });
+    }
+    /** `GET /v1/usage` — the current UTC month, with the daily series behind it. */
+    usage(options) {
+        return this.http.request({ method: 'GET', path: '/v1/usage', idempotent: true, options });
+    }
+}
+// ---------------------------------------------------------------------------
+// Domains
+// ---------------------------------------------------------------------------
+export class DomainsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * `POST /v1/domains` — 201 with the DNS records to publish.
+     *
+     * Safe to repeat: a second create for the same name is refused with `409
+     * conflict` rather than producing a second domain, so a retry after a lost
+     * response cannot leave duplicates behind.
+     */
+    create(params, options) {
+        return this.http.request({
+            method: 'POST',
+            path: '/v1/domains',
+            body: params,
+            idempotent: true,
+            options,
+        });
+    }
+    /** `GET /v1/domains` — every domain, newest first. Not paginated. */
+    list(options) {
+        return this.http.request({ method: 'GET', path: '/v1/domains', idempotent: true, options });
+    }
+    /**
+     * `POST /v1/domains/:id/verify` — look for the records and record the result.
+     *
+     * Branch on `verified`, not on `status`: `checks` reports SPF and DMARC too,
+     * and neither of them failing stops the domain being usable.
+     */
+    verify(id, options) {
+        return this.http.request({
+            method: 'POST',
+            path: `/v1/domains/${encodeURIComponent(id)}/verify`,
+            idempotent: true,
+            options,
+        });
+    }
+    /**
+     * `DELETE /v1/domains/:id` — 204.
+     *
+     * Refused with `409 domain_in_use` while any message references it. That is
+     * deliberate: the delivery record is the product, and deleting the domain
+     * would take its history with it.
+     */
+    delete(id, options) {
+        return this.http.requestVoid({
+            method: 'DELETE',
+            path: `/v1/domains/${encodeURIComponent(id)}`,
+            idempotent: true,
+            options,
+        });
+    }
+    /** `GET /v1/domains/:id/setup` — who runs this domain's DNS, and whether one-click is available. */
+    setup(id, options) {
+        return this.http.request({
+            method: 'GET',
+            path: `/v1/domains/${encodeURIComponent(id)}/setup`,
+            idempotent: true,
+            options,
+        });
+    }
+    /**
+     * `POST /v1/domains/:id/cloudflare` — publish the DKIM record on the
+     * customer's behalf.
+     *
+     * Only DKIM is written. SPF and DMARC come back under `notPublished`,
+     * untouched, because overwriting either is worse than asking somebody to
+     * copy a string by hand.
+     *
+     * Safe to repeat: the record write is an upsert and the token store is an
+     * `on conflict do update`.
+     */
+    connectCloudflare(id, params = {}, options) {
+        return this.http.request({
+            method: 'POST',
+            path: `/v1/domains/${encodeURIComponent(id)}/cloudflare`,
+            body: params,
+            idempotent: true,
+            options,
+        });
+    }
+    /**
+     * `DELETE /v1/account/cloudflare` — forget the stored Cloudflare token.
+     *
+     * Account-scoped rather than domain-scoped (one token serves every domain),
+     * but it lives here because it is part of the DNS story and needs
+     * `domains:write`. Always 204, whether a token was stored or not.
+     */
+    disconnectCloudflare(options) {
+        return this.http.requestVoid({
+            method: 'DELETE',
+            path: '/v1/account/cloudflare',
+            idempotent: true,
+            options,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Sending
+// ---------------------------------------------------------------------------
+export class EmailsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * `POST /v1/emails`.
+     *
+     * TWO success statuses, and they mean different things:
+     *
+     *   202 `{ status: 'queued' }`    — accepted, a new message exists.
+     *   200 `{ status: 'duplicate' }` — an idempotency replay. No new message was
+     *                                   created; the id is the original one.
+     *
+     * Both are returned as a `SendEmailResult` with a `duplicate` boolean, rather
+     * than collapsed into "it worked". A caller that bills, logs or counts per
+     * send needs to know which of the two happened, and finding out from an HTTP
+     * status they never see is not a reasonable ask.
+     *
+     * RETRIES. A send is only repeated automatically when `idempotencyKey` is
+     * set, because without one a retry after a lost response sends the email
+     * twice. Setting it is the single most useful thing you can do here.
+     *
+     * IDEMPOTENCY IS A BODY FIELD. It goes in the JSON as `idempotencyKey`. The
+     * `Idempotency-Key` HTTP header is in the API's CORS allowlist but no handler
+     * reads it, so a client that sends the header and not the field gets no
+     * idempotency at all and no warning that it has none. This SDK never sends
+     * the header.
+     */
+    async send(params, options) {
+        const { status, text } = await this.http.send({
+            method: 'POST',
+            path: '/v1/emails',
+            body: params,
+            // The whole rule, in one expression.
+            idempotent: Boolean(params.idempotencyKey),
+            options,
+        });
+        const parsed = JSON.parse(text);
+        return {
+            id: parsed.id,
+            status: parsed.status,
+            /*
+             * Read from the BODY, not from `status === 200`.
+             *
+             * The body is the authoritative answer and survives a proxy that
+             * normalises a 202 to a 200; the status is a corroborating signal, not
+             * the source of truth.
+             */
+            duplicate: parsed.status === 'duplicate',
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+export class MessagesResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** `GET /v1/messages` — one keyset page, newest first. */
+    list(params = {}, options) {
+        return this.http.request({
+            method: 'GET',
+            path: '/v1/messages',
+            query: params,
+            idempotent: true,
+            options,
+        });
+    }
+    /**
+     * Every message matching the filter, across every page.
+     *
+     * Loops on `hasMore`. Never write the `while (nextCursor)` version by hand —
+     * see `pagination.ts` for why it does not terminate.
+     */
+    autoPaginate(params = {}, options) {
+        return paginate((p) => this.list(p, options), params);
+    }
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params = {}, maxItems = 1000, options) {
+        return collect(this.autoPaginate(params, options), maxItems);
+    }
+    /**
+     * `GET /v1/messages/:id` — the waybill: content, every event, and the hash
+     * linkage, with the chain re-verified on read (`recordIntact`).
+     */
+    get(id, options) {
+        return this.http.request({
+            method: 'GET',
+            path: `/v1/messages/${encodeURIComponent(id)}`,
+            idempotent: true,
+            options,
+        });
+    }
+    /**
+     * `GET /v1/stats/messages` — daily volume with the previous window for
+     * comparison.
+     *
+     * Rates here are PERCENTAGES over settled mail (`total` minus `pending`).
+     * `GET /v1/usage` reports its rates as fractions over everything sent — the
+     * two endpoints genuinely differ, and dividing one by 100 to compare them is
+     * not enough.
+     */
+    stats(params = {}, options) {
+        return this.http.request({
+            method: 'GET',
+            path: '/v1/stats/messages',
+            query: params,
+            idempotent: true,
+            options,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Suppressions
+// ---------------------------------------------------------------------------
+export class SuppressionsResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** `GET /v1/suppressions` — one keyset page. `limit` caps at 200. */
+    list(params = {}, options) {
+        return this.http.request({
+            method: 'GET',
+            path: '/v1/suppressions',
+            query: params,
+            idempotent: true,
+            options,
+        });
+    }
+    /** Every suppression matching the filter. Loops on `hasMore`. */
+    autoPaginate(params = {}, options) {
+        return paginate((p) => this.list(p, options), params);
+    }
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params = {}, maxItems = 1000, options) {
+        return collect(this.autoPaginate(params, options), maxItems);
+    }
+    /**
+     * `POST /v1/suppressions` — 201.
+     *
+     * `reason` here is free text and is stored as the entry's DETAIL. The entry's
+     * own reason is always `manual`; only the platform creates `hard_bounce`,
+     * `complaint`, `unsubscribe` and `spam_trap` entries.
+     *
+     * Safe to repeat: the insert is `on conflict do nothing`, and re-adding an
+     * address answers 201 again.
+     */
+    create(params, options) {
+        return this.http.request({
+            method: 'POST',
+            path: '/v1/suppressions',
+            body: params,
+            idempotent: true,
+            options,
+        });
+    }
+    /**
+     * `DELETE /v1/suppressions/:address` — 204.
+     *
+     * Addressed by ADDRESS, not by `sup_` id, and this SDK URL-encodes it for
+     * you. Two entries are refused: a `complaint` (422 `suppression_protected` —
+     * sending again is what gets an IP blocklisted) and a platform-wide entry
+     * (422 `suppression_platform`).
+     */
+    delete(address, options) {
+        return this.http.requestVoid({
+            method: 'DELETE',
+            path: `/v1/suppressions/${encodeURIComponent(address)}`,
+            idempotent: true,
+            options,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Webhooks
+// ---------------------------------------------------------------------------
+export class WebhooksResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * `POST /v1/webhooks` — 201, carrying `signingSecret`.
+     *
+     * The secret is shown exactly ONCE and is not retrievable afterwards, because
+     * a signing secret that can be re-read is one that anybody with a stolen API
+     * key can read too. Store it before you do anything else with the response.
+     *
+     * NOT auto-retried: repeating this creates a second webhook, and the
+     * duplicate would then receive every event twice.
+     */
+    create(params, options) {
+        return this.http.request({
+            method: 'POST',
+            path: '/v1/webhooks',
+            body: params,
+            idempotent: false,
+            options,
+        });
+    }
+    /** `GET /v1/webhooks` — newest first. Not paginated. Never includes secrets. */
+    list(options) {
+        return this.http.request({ method: 'GET', path: '/v1/webhooks', idempotent: true, options });
+    }
+    /** `DELETE /v1/webhooks/:id` — 204, or 404 for an unknown id. */
+    delete(id, options) {
+        return this.http.requestVoid({
+            method: 'DELETE',
+            path: `/v1/webhooks/${encodeURIComponent(id)}`,
+            idempotent: true,
+            options,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// API keys
+// ---------------------------------------------------------------------------
+export class ApiKeysResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * `GET /v1/api-keys` — the 100 most recent keys, revoked ones included.
+     *
+     * Read only, and that is the whole resource. Creating and revoking keys
+     * requires a signed-in owner or admin and refuses a Bearer key outright: a
+     * server-side credential that could mint more credentials would make every
+     * narrow key one request away from a full one.
+     */
+    list(options) {
+        return this.http.request({ method: 'GET', path: '/v1/api-keys', idempotent: true, options });
+    }
+}
+// ---------------------------------------------------------------------------
+// Billing
+// ---------------------------------------------------------------------------
+export class BillingResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * `GET /v1/billing` — current plan, subscription, profile, recent payments
+     * and the full price list.
+     *
+     * All four billing reads accept `billing:read` OR `account:read`; an API key
+     * cannot hold `billing:read`, so in practice `account:read` is the one that
+     * gets you in. Money is always in minor units.
+     */
+    get(options) {
+        return this.http.request({ method: 'GET', path: '/v1/billing', idempotent: true, options });
+    }
+    /** `GET /v1/billing/history` — the hash-chained commercial record, oldest first, plus its verification. */
+    history(options) {
+        return this.http.request({
+            method: 'GET',
+            path: '/v1/billing/history',
+            idempotent: true,
+            options,
+        });
+    }
+    /** `GET /v1/billing/invoices` — the 100 most recent, newest first. Not paginated. */
+    invoices(options) {
+        return this.http.request({
+            method: 'GET',
+            path: '/v1/billing/invoices',
+            idempotent: true,
+            options,
+        });
+    }
+    /** `GET /v1/billing/invoices/:id` — the same document plus the supplier block. */
+    invoice(id, options) {
+        return this.http.request({
+            method: 'GET',
+            path: `/v1/billing/invoices/${encodeURIComponent(id)}`,
+            idempotent: true,
+            options,
+        });
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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.
+ */
+/**
+ * The `error.type` values the API emits.
+ *
+ * Listed as a union so a `switch` is exhaustive where it can be, and widened
+ * with `(string & {})` so a type this SDK version has not heard of still
+ * type-checks — a new refusal reason must not be a compile error for anybody
+ * who has not upgraded.
+ */
+export type KnownErrorType = 'unauthorized' | 'unauthenticated' | 'forbidden' | 'csrf_failed' | 'email_unverified' | 'invalid_request' | 'not_found' | 'conflict'
+/** Inbound addresses. Not reachable through this SDK — see the README. */
+ | 'address_taken' | 'invalid_address' | 'domain_not_found' | 'domain_not_verified' | 'suppressed' | 'rate_limited' | 'daily_limit_reached' | 'monthly_limit_reached' | 'domain_limit_reached' | 'domain_in_use' | 'token_required' | 'cloudflare_token_invalid' | 'cloudflare_zone_not_found' | 'cloudflare_write_failed' | 'suppression_protected' | 'suppression_platform' | 'not_configured' | 'provider_error' | 'already_subscribed' | 'internal' | 'unknown_error' | 'connection_error' | 'timeout';
+export type PosthasteErrorType = KnownErrorType | (string & {});
+/** One entry of `error.fields`, present on some — not all — 400s. */
+export interface FieldError {
+    /** Dotted path into the request body, e.g. `headers.x-thing`. */
+    path: string;
+    message: string;
+}
+export interface PosthasteErrorInit {
+    status: number;
+    type: PosthasteErrorType;
+    message: string;
+    fields?: FieldError[];
+    retryAfterSeconds?: number;
+    /** The parsed response body, exactly as it arrived. */
+    body?: unknown;
+    cause?: unknown;
+}
+export declare class PosthasteError extends Error {
+    readonly 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`.
+     */
+    readonly status: number;
+    readonly type: PosthasteErrorType;
+    /**
+     * 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.
+     */
+    readonly fields?: FieldError[];
+    /**
+     * 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.
+     */
+    readonly retryAfterSeconds?: number;
+    /** The parsed body. `undefined` when there was nothing parseable. */
+    readonly body?: unknown;
+    constructor(init: PosthasteErrorInit);
+    /**
+     * 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(): boolean;
+    /** True for the per-key request-rate limiter, which is short and transient. */
+    get isRateLimited(): boolean;
+}
+export declare function isPosthasteError(value: unknown): value is 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 declare function errorFromResponse(status: number, rawBody: string, retryAfterHeader: string | null): PosthasteError;
+/**
+ * `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 declare function parseRetryAfter(header: string | null): number | undefined;