@posthaste/sdk 0.1.0

package/README.md

@@ -0,0 +1,454 @@
+# @posthaste/sdk
+
+The official TypeScript SDK for the [Posthaste](https://posthastemail.dev) transactional email API.
+
+**Zero runtime dependencies.** Global `fetch` and `node:crypto`, nothing else — so it installs in
+about a second, adds nothing to your lockfile, and has no transitive supply chain to audit.
+
+```bash
+npm i @posthaste/sdk
+```
+
+Requires Node 22 or newer (or any runtime with a global `fetch`). ESM only.
+
+---
+
+## Quickstart
+
+```ts
+import { Posthaste } from '@posthaste/sdk';
+
+const posthaste = new Posthaste({ apiKey: process.env.POSTHASTE_API_KEY! });
+
+const sent = await posthaste.emails.send({
+  from: 'Acme <billing@acme.com>',
+  to: 'customer@example.com',
+  subject: 'Your receipt',
+  html: '<p>Thanks for your order.</p>',
+  text: 'Thanks for your order.',
+  idempotencyKey: `receipt-${orderId}`,
+});
+
+console.log(sent.id, sent.duplicate); // msg_AZLm3kQ8T2Sf9pXbNc7HrQ  false
+```
+
+## Authentication
+
+Posthaste authenticates with an API key sent as a bearer token. Create one in the dashboard under
+**Settings → API keys**; it is shown exactly once.
+
+```ts
+const posthaste = new Posthaste({
+  apiKey: process.env.POSTHASTE_API_KEY!, // ph_live_… or ph_test_…
+  baseUrl: 'https://api.posthastemail.dev', // the default
+  timeoutMs: 30_000, // per attempt
+  maxRetries: 2, // retries after the first attempt
+});
+```
+
+A key carries **scopes**, and a call that needs one the key does not hold fails with a `403` naming
+the missing scope. The nine scopes are `account:read`, `domains:read`, `domains:write`,
+`emails:send`, `messages:read`, `suppressions:read`, `suppressions:write`, `webhooks:read`,
+`webhooks:write`.
+
+### Bringing your own `fetch`
+
+```ts
+import { ProxyAgent } from 'undici';
+
+const dispatcher = new ProxyAgent('http://proxy.internal:8080');
+
+const posthaste = new Posthaste({
+  apiKey: process.env.POSTHASTE_API_KEY!,
+  fetch: (url, init) => fetch(url, { ...init, dispatcher } as RequestInit),
+});
+```
+
+Useful behind a corporate proxy, for tracing, and for tests — the SDK's own end-to-end suite passes
+a `fetch` that forwards straight into an in-process server.
+
+---
+
+## Sending
+
+`emails.send` maps to `POST /v1/emails`. One recipient per call: there is no `cc`, no `bcc` and no
+array — send `to` a list of people by making a call per person, so one bad address cannot spoil the
+rest.
+
+```ts
+await posthaste.emails.send({
+  from: 'Acme <billing@acme.com>', // must be on a VERIFIED domain
+  to: 'customer@example.com',
+  subject: 'Your receipt',
+  text: 'Thanks for your order.', // text or html — at least one
+  html: '<p>Thanks for your order.</p>',
+  replyTo: 'support@acme.com',
+  headers: { 'X-Order-Id': orderId },
+  listUnsubscribe: '<https://acme.com/unsub?u=123>, <mailto:unsub@acme.com>',
+  idempotencyKey: `receipt-${orderId}`,
+});
+```
+
+### Two success statuses, and why you are told which
+
+The API answers a **new** send with `202 { status: 'queued' }` and an **idempotency replay** with
+`200 { status: 'duplicate' }`. Both are success. The SDK returns both, with the difference made
+explicit rather than hidden:
+
+```ts
+const result = await posthaste.emails.send({
+  from,
+  to,
+  text,
+  idempotencyKey: `receipt-${orderId}`,
+});
+
+if (result.duplicate) {
+  // Nothing was sent. `result.id` is the message we accepted the first time.
+} else {
+  // A new message exists and is queued for delivery.
+}
+```
+
+If you bill, count, or log per send, that distinction is the difference between an accurate number
+and a slowly-drifting one.
+
+---
+
+## Idempotency
+
+**`idempotencyKey` is a BODY field, not a header.**
+
+The `Idempotency-Key` HTTP header is in the API's CORS allowlist — so nothing complains if you send
+it — but **no handler reads it**. A client that sets the header and not the field gets no idempotency
+at all, and no warning that it has none: the retry simply sends a second email. This SDK never sends
+the header, and `idempotencyKey` in the params maps to the body field.
+
+```ts
+// Correct. The key travels in the JSON body.
+await posthaste.emails.send({ from, to, text, idempotencyKey: `receipt-${orderId}` });
+```
+
+Details worth knowing:
+
+- The key is scoped to your account and lives as long as the message record — there is no expiry
+  window.
+- **The body is not part of the comparison.** Reusing a key with different content returns the
+  ORIGINAL message, silently. Derive the key from the thing you are sending (`receipt-${orderId}`),
+  never from a timestamp or a random value per attempt.
+- A replay is not billed and does not consume quota.
+- The duplicate check runs before the domain lookup, suppression and quota, so a replay is cheap.
+
+---
+
+## Pagination
+
+Lists are keyset-paginated: `limit` and `before` in, `{ data, hasMore, nextCursor }` out. `before`
+is the id of the last row you received, which is exactly what `nextCursor` gives you.
+
+```ts
+const page = await posthaste.messages.list({ limit: 50, status: 'bounced' });
+// page.data, page.hasMore, page.nextCursor
+```
+
+### Loop on `hasMore`, never on `nextCursor`
+
+`nextCursor` is derived from the last row of a page, and some endpoints return a **non-null cursor
+on the final page**. The obvious loop —
+
+```ts
+// WRONG. This can never terminate.
+let cursor: string | null | undefined = undefined;
+do {
+  const page = await posthaste.messages.list({ before: cursor });
+  cursor = page.nextCursor;
+} while (cursor);
+```
+
+— asks for the page after the last one, gets an empty page carrying the same cursor back, and spins
+for ever. Nothing errors; it just never finishes.
+
+`autoPaginate` encodes the correct condition, so you cannot get it wrong:
+
+```ts
+for await (const message of posthaste.messages.autoPaginate({ status: 'bounced' })) {
+  console.log(message.id, message.to);
+}
+```
+
+It stops on `hasMore === false`, and also stops on an empty page or a cursor that fails to advance —
+so a contract change upstream produces a short result, never an infinite loop.
+
+For the common "give me an array" case, with a ceiling you choose:
+
+```ts
+const recent = await posthaste.messages.listAll({ status: 'bounced' }, 500);
+```
+
+`suppressions` has the same three methods. `domains`, `webhooks`, `apiKeys` and
+`billing.invoices` are not paginated — they return `{ data }` whole, capped server-side at 100.
+
+---
+
+## Webhooks
+
+Register an endpoint and Posthaste posts events to it as they happen. The signing secret is returned
+**exactly once**, on creation, and is not retrievable afterwards.
+
+```ts
+const hook = await posthaste.webhooks.create({
+  url: 'https://acme.com/hooks/posthaste',
+  eventTypes: ['delivered', 'bounced', 'complained'], // omit for all ten
+});
+
+await store(hook.signingSecret); // whsec_… — you cannot read it again
+```
+
+### Verifying a delivery
+
+```ts
+import express from 'express';
+import { verifyWebhook, DELIVERY_ID_HEADER } from '@posthaste/sdk';
+
+const app = express();
+
+app.post(
+  '/hooks/posthaste',
+  // THE RAW BYTES. Not express.json().
+  express.raw({ type: 'application/json' }),
+  (req, res) => {
+    const result = verifyWebhook(
+      req.body, // a Buffer
+      req.get('posthaste-signature'),
+      process.env.POSTHASTE_WEBHOOK_SECRET!,
+    );
+
+    if (!result.valid) {
+      console.warn('rejected webhook', result.reason);
+      return res.sendStatus(400);
+    }
+
+    const event = JSON.parse(req.body.toString('utf8'));
+
+    // Deduplicate on the delivery id — a retry is not a second event.
+    enqueue(req.get(DELIVERY_ID_HEADER), event);
+
+    // Acknowledge FAST and do the work elsewhere: we time out after 10 seconds.
+    return res.sendStatus(204);
+  },
+);
+```
+
+In Next.js the raw body is `await req.text()`; in Fastify, register the route with a raw body parser.
+
+**Verify over the RAW BYTES.** A body that has been parsed and re-serialised will _never_ verify.
+`JSON.parse` followed by `JSON.stringify` is not a byte-level round trip — key order and whitespace
+are both free to change — and the signature covers the bytes we sent, 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.
+
+The scheme, for reference:
+
+```
+posthaste-signature: t=<unix seconds>,v1=<hex>
+signed payload     = `${t}.${rawBody}`
+signature          = HMAC-SHA256(secret, signed payload), lower-case hex
+```
+
+`verifyWebhook` parses the header **by key**, not positionally (`v1=` exists so a `v2=` can be added
+beside it), compares in constant time, and rejects a timestamp more than 300 seconds old **or more
+than 300 seconds in the future** — a future timestamp is not clock skew to be generous about, it is
+an attacker buying an unlimited replay window.
+
+```ts
+verifyWebhook(rawBody, header, secret, { toleranceSeconds: 300 });
+// -> { valid: true }
+// -> { valid: false, reason: 'malformed_header' | 'unsupported_version'
+//                          | 'timestamp_too_old' | 'timestamp_in_future'
+//                          | 'signature_mismatch' }
+```
+
+`parseWebhookEvent` verifies and JSON-parses in one step, returning `null` on any failure, for the
+common case where a bad delivery just gets a 400.
+
+The ten event types are `accepted`, `queued`, `attempted`, `delivered`, `deferred`, `bounced`,
+`complained`, `failed`, `rejected` and `suppressed` — exported as `EVENT_TYPES`.
+
+---
+
+## Errors
+
+Every failure — including the ones that never reached a server — throws a `PosthasteError`.
+
+```ts
+import { PosthasteError, isPosthasteError } from '@posthaste/sdk';
+
+try {
+  await posthaste.emails.send({ from, to, text });
+} catch (err) {
+  if (!isPosthasteError(err)) throw err;
+
+  err.status; // 422 — or 0 when the request never got a response
+  err.type; // 'domain_not_verified'
+  err.message; // human-readable, safe to log
+  err.fields; // [{ path, message }] on SOME 400s — always check
+  err.retryAfterSeconds; // when the server said
+  err.body; // the parsed body, for the extra keys a refusal carries
+}
+```
+
+Branch on `type`, not on `status`:
+
+```ts
+switch (err.type) {
+  case 'domain_not_verified':
+  case 'invalid_address':
+  case 'suppressed':
+    return permanent(err); // do not retry — fix the request
+
+  case 'rate_limited':
+    return retryAfter(err.retryAfterSeconds ?? 60); // seconds; transient
+
+  case 'daily_limit_reached':
+  case 'monthly_limit_reached':
+    return alertOps(err); // quota, not throttling. Hours or days away.
+
+  default:
+    return transient(err);
+}
+```
+
+Two traps this SDK handles for you, both worth knowing about:
+
+- **`err.fields` is not always there.** It 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. Never index into it
+  unchecked.
+- **An unhandled 500 does not use the error envelope.** The API installs no custom error handler, so
+  a thrown exception is serialised by the framework as `{ statusCode, error: "Internal Server
+Error", message }` — where `error` is a _string_. Reading `body.error.type` off that is
+  `undefined`, and reading `body.error.message` throws. The SDK parses it defensively, gives you the
+  framework's `message`, and sets `type` to `'unknown_error'` rather than inventing a documented one.
+  A proxy's HTML error page and an empty body are handled the same way.
+
+Two synthetic types never sent by the server: `'connection_error'` (the request never opened) and
+`'timeout'` (it opened and never answered). Both carry `status: 0`.
+
+---
+
+## Retries
+
+The SDK retries `408`, `429` and `5xx`, and connection failures, with **exponential backoff and full
+jitter** — capped at 8 seconds per wait, two retries by default. It honours `Retry-After` when the
+server sends one.
+
+Two rules make this safe rather than merely automatic.
+
+**It branches on `error.type`, not on the status.** Three different refusals arrive as `429`:
+
+| type                    | what it means                       | `Retry-After`  | retried? |
+| ----------------------- | ----------------------------------- | -------------- | -------- |
+| `rate_limited`          | too many requests for this key      | seconds        | yes      |
+| `daily_limit_reached`   | today's warmup cap is spent         | until midnight | **no**   |
+| `monthly_limit_reached` | the plan's monthly allowance is out | up to a month  | **no**   |
+
+The last two are exhausted quota, not throttling. Retrying them in-process would hammer a wall the
+calendar has to move before it opens, while burning your request-rate limit on the way. They are
+raised immediately, with `err.isQuotaExhausted === true` and the wait on
+`err.retryAfterSeconds`, so _you_ can decide — a queue, a delay, an alert.
+
+A `Retry-After` longer than `maxRetryDelayMs` (60 seconds by default) is also not slept through:
+blocking a request handler for fifteen minutes is indistinguishable from a hang.
+
+**It never retries a request that repeating could duplicate.** Concretely, a send is retried **only
+when you supplied an `idempotencyKey`**, and `webhooks.create` is never retried (a duplicate
+endpoint would receive every event twice, for ever). Everything else — every `GET`, every `DELETE`,
+`domains.create` (a duplicate is a `409`), `suppressions.create` (an upsert) — is safe to repeat and
+is repeated.
+
+Turn it all off with `maxRetries: 0`.
+
+---
+
+## API surface
+
+```
+account.me()                                  GET    /v1/me
+account.verify()                              GET    /v1/account/verify
+account.usage()                               GET    /v1/usage
+
+domains.create({ name })                      POST   /v1/domains
+domains.list()                                GET    /v1/domains
+domains.verify(id)                            POST   /v1/domains/:id/verify
+domains.delete(id)                            DELETE /v1/domains/:id
+domains.setup(id)                             GET    /v1/domains/:id/setup
+domains.connectCloudflare(id, { token })      POST   /v1/domains/:id/cloudflare
+domains.disconnectCloudflare()                DELETE /v1/account/cloudflare
+
+emails.send(params)                           POST   /v1/emails
+
+messages.list(params)                         GET    /v1/messages
+messages.autoPaginate(params)                 GET    /v1/messages   (all pages)
+messages.listAll(params, maxItems)            GET    /v1/messages   (all pages)
+messages.get(id)                              GET    /v1/messages/:id
+messages.stats(params)                        GET    /v1/stats/messages
+
+suppressions.list(params)                     GET    /v1/suppressions
+suppressions.autoPaginate(params)             GET    /v1/suppressions (all pages)
+suppressions.listAll(params, maxItems)        GET    /v1/suppressions (all pages)
+suppressions.create({ address, reason })      POST   /v1/suppressions
+suppressions.delete(address)                  DELETE /v1/suppressions/:address
+
+webhooks.create({ url, eventTypes })          POST   /v1/webhooks
+webhooks.list()                               GET    /v1/webhooks
+webhooks.delete(id)                           DELETE /v1/webhooks/:id
+
+apiKeys.list()                                GET    /v1/api-keys
+
+billing.get()                                 GET    /v1/billing
+billing.history()                             GET    /v1/billing/history
+billing.invoices()                            GET    /v1/billing/invoices
+billing.invoice(id)                           GET    /v1/billing/invoices/:id
+```
+
+### What is deliberately not here
+
+- **Creating and revoking API keys.** Those require a signed-in owner or admin and refuse a bearer
+  key outright — a server-side credential that could mint more credentials would put every narrow
+  key one request away from a full one. An SDK method that can only ever `403` is worse than none.
+- **Anything session-only**: sign-in, checkout, plan changes, profile edits. Same reason.
+- **Inbound mail** (`/v1/inbound/*`). The routes exist, but a customer cannot use them: domain setup
+  returns no MX record, there is no dashboard for it, and the receiving host is unset in production.
+  Shipping them would be a promise the platform does not currently keep.
+- **`/admin/v1/*`**, the platform operator API.
+
+---
+
+## Types
+
+Everything is exported: request params, response shapes, `MessageStatus`, `EventType`,
+`SuppressionReason`, `Scope`, `PlanId`, and the error `type` union.
+
+```ts
+import type {
+  Message,
+  MessageStatus,
+  SendEmailParams,
+  SendEmailResult,
+  EventType,
+  WebhookEvent,
+  PosthasteErrorType,
+} from '@posthaste/sdk';
+```
+
+Ids are prefixed strings — `msg_`, `dom_`, `whk_`, `sup_`, `key_`, `inv_`, `acct_` — and the types
+returned from the API encode that (`MessageId` is `` `msg_${string}` ``). Methods **accept** plain
+`string`, so an id loaded from your own database needs no cast.
+
+`PosthasteErrorType` is a union widened with `(string & {})`: a `switch` stays useful, and a refusal
+reason added after your SDK version still type-checks.
+
+---
+
+## Licence
+
+MIT.

package/dist/client.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 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, type PosthasteOptions, type RequestOptions } from './http.js';
+import type { Account, Billing, BillingHistory, ChainVerification, CloudflarePublishResult, ConnectCloudflareParams, CreateDomainParams, CreateSuppressionParams, CreateWebhookParams, CreatedDomain, CreatedSuppression, CreatedWebhook, Domain, DomainSetup, DomainVerification, Invoice, InvoiceDetail, List, ApiKey, ListMessagesParams, ListSuppressionsParams, Message, MessageStats, MessageStatsParams, MessageSummary, Page, SendEmailParams, SendEmailResult, Suppression, Usage, Webhook } from './types.js';
+export declare class Posthaste {
+    private readonly http;
+    readonly account: AccountResource;
+    readonly domains: DomainsResource;
+    readonly emails: EmailsResource;
+    readonly messages: MessagesResource;
+    readonly suppressions: SuppressionsResource;
+    readonly webhooks: WebhooksResource;
+    readonly apiKeys: ApiKeysResource;
+    readonly billing: BillingResource;
+    constructor(options: PosthasteOptions);
+}
+export declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /v1/me` — who this key belongs to, its scopes, plan and sending caps. */
+    me(options?: RequestOptions): Promise<Account>;
+    /**
+     * `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?: RequestOptions): Promise<ChainVerification>;
+    /** `GET /v1/usage` — the current UTC month, with the daily series behind it. */
+    usage(options?: RequestOptions): Promise<Usage>;
+}
+export declare class DomainsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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: CreateDomainParams, options?: RequestOptions): Promise<CreatedDomain>;
+    /** `GET /v1/domains` — every domain, newest first. Not paginated. */
+    list(options?: RequestOptions): Promise<List<Domain>>;
+    /**
+     * `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: string, options?: RequestOptions): Promise<DomainVerification>;
+    /**
+     * `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: string, options?: RequestOptions): Promise<void>;
+    /** `GET /v1/domains/:id/setup` — who runs this domain's DNS, and whether one-click is available. */
+    setup(id: string, options?: RequestOptions): Promise<DomainSetup>;
+    /**
+     * `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: string, params?: ConnectCloudflareParams, options?: RequestOptions): Promise<CloudflarePublishResult>;
+    /**
+     * `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?: RequestOptions): Promise<void>;
+}
+export declare class EmailsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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.
+     */
+    send(params: SendEmailParams, options?: RequestOptions): Promise<SendEmailResult>;
+}
+export declare class MessagesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /v1/messages` — one keyset page, newest first. */
+    list(params?: ListMessagesParams, options?: RequestOptions): Promise<Page<MessageSummary>>;
+    /**
+     * 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?: ListMessagesParams, options?: RequestOptions): AsyncGenerator<MessageSummary, void, undefined>;
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params?: ListMessagesParams, maxItems?: number, options?: RequestOptions): Promise<MessageSummary[]>;
+    /**
+     * `GET /v1/messages/:id` — the waybill: content, every event, and the hash
+     * linkage, with the chain re-verified on read (`recordIntact`).
+     */
+    get(id: string, options?: RequestOptions): Promise<Message>;
+    /**
+     * `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?: MessageStatsParams, options?: RequestOptions): Promise<MessageStats>;
+}
+export declare class SuppressionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** `GET /v1/suppressions` — one keyset page. `limit` caps at 200. */
+    list(params?: ListSuppressionsParams, options?: RequestOptions): Promise<Page<Suppression>>;
+    /** Every suppression matching the filter. Loops on `hasMore`. */
+    autoPaginate(params?: ListSuppressionsParams, options?: RequestOptions): AsyncGenerator<Suppression, void, undefined>;
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params?: ListSuppressionsParams, maxItems?: number, options?: RequestOptions): Promise<Suppression[]>;
+    /**
+     * `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: CreateSuppressionParams, options?: RequestOptions): Promise<CreatedSuppression>;
+    /**
+     * `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: string, options?: RequestOptions): Promise<void>;
+}
+export declare class WebhooksResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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: CreateWebhookParams, options?: RequestOptions): Promise<CreatedWebhook>;
+    /** `GET /v1/webhooks` — newest first. Not paginated. Never includes secrets. */
+    list(options?: RequestOptions): Promise<List<Webhook>>;
+    /** `DELETE /v1/webhooks/:id` — 204, or 404 for an unknown id. */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+}
+export declare class ApiKeysResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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?: RequestOptions): Promise<List<ApiKey>>;
+}
+export declare class BillingResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * `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?: RequestOptions): Promise<Billing>;
+    /** `GET /v1/billing/history` — the hash-chained commercial record, oldest first, plus its verification. */
+    history(options?: RequestOptions): Promise<BillingHistory>;
+    /** `GET /v1/billing/invoices` — the 100 most recent, newest first. Not paginated. */
+    invoices(options?: RequestOptions): Promise<List<Invoice>>;
+    /** `GET /v1/billing/invoices/:id` — the same document plus the supplier block. */
+    invoice(id: string, options?: RequestOptions): Promise<InvoiceDetail>;
+}