@posthaste/sdk 0.1.0 → 0.3.0

package/README.md

@@ -89,6 +89,91 @@ await posthaste.emails.send({
 });
 ```
 
+### Attachments
+
+Up to 10 files per message, 10 MiB combined once decoded. `content` accepts a `Uint8Array` — the
+SDK base64-encodes it — or a string that is already base64, sent as-is and never re-encoded (so it
+is never corrupted by double-encoding).
+
+```ts
+await posthaste.emails.send({
+  from: 'Acme <billing@acme.com>',
+  to: 'customer@example.com',
+  subject: 'Your receipt',
+  html: '<p>Thanks for your order.</p>',
+  attachments: [
+    { filename: 'receipt.pdf', contentType: 'application/pdf', content: pdfBytes }, // Uint8Array
+  ],
+});
+```
+
+An inline image is the same shape with two extra fields — `disposition: 'inline'` and a `cid`,
+referenced from the html as `cid:logo`:
+
+```ts
+await posthaste.emails.send({
+  from: 'Acme <billing@acme.com>',
+  to: 'customer@example.com',
+  subject: 'Welcome',
+  html: '<p>Hello <img src="cid:logo"></p>',
+  attachments: [
+    {
+      filename: 'logo.png',
+      contentType: 'image/png',
+      content: logoBytes,
+      disposition: 'inline',
+      cid: 'logo',
+    },
+  ],
+});
+```
+
+Executable file types (`.exe`, `.js`, `.bat`, `.vbs`, `.msi`, and the rest of Gmail's blocked set)
+are refused with `attachment_type_blocked`, checked against the **final** extension — so
+`invoice.pdf.exe` is blocked. Read a stored attachment's bytes back with `downloadAttachment`:
+
+```ts
+const stored = message.content!.attachments[0]!; // metadata: id, filename, contentType, …
+const file = await posthaste.messages.downloadAttachment(message.id, stored.id);
+file.bytes; // Uint8Array — the exact bytes that were sent
+file.contentType; // an inert type on a small allowlist, or application/octet-stream
+```
+
+### Scheduling
+
+Add `scheduledAt` to send later instead of immediately. It must be **ISO-8601 with a timezone
+offset** — `2026-08-25T09:00:00-05:00`, not `"tomorrow 9am"` — because that is unambiguous and it
+is what `Date.toISOString()` already produces.
+
+```ts
+const result = await posthaste.emails.send({
+  from: 'Acme <billing@acme.com>',
+  to: 'customer@example.com',
+  subject: 'Renewal reminder',
+  text: 'Your plan renews in three days.',
+  scheduledAt: '2026-08-25T09:00:00-05:00',
+});
+
+result.status; // 'scheduled'
+result.scheduledAt; // '2026-08-25T14:00:00.000Z' — normalized to UTC
+```
+
+A timestamp within 60 seconds of now collapses to an ordinary immediate send. Beyond that, how far
+ahead you can go depends on your plan, bounded platform-wide so nothing can schedule past the
+30-day retention window; going past it throws `schedule_too_far` carrying `maxDays`, the limit that
+actually applied.
+
+Quota — suppression, domain verification, your daily and monthly allowance — is decided in full on
+the day the mail actually leaves, not the day you scheduled it. Cancel any time before then:
+
+```ts
+await posthaste.emails.cancelSchedule(result.id);
+// { id, status: 'canceled' } — a retry after a lost response returns the same success again
+```
+
+A cancel attempted after the message has already released throws `not_scheduled`, carrying the
+message's current `status`.
+
 ### Two success statuses, and why you are told which
 
 The API answers a **new** send with `202 { status: 'queued' }` and an **idempotency replay** with
@@ -143,32 +228,52 @@ Details worth knowing:
 
 ## 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.
+**Every list is paginated.** `limit` and `before` in, `{ data, nextCursor }` out — plus `hasMore` on
+the three endpoints that send it. `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`
+| Resource           | `limit`            | Cursor      | `hasMore`? |
+| ------------------ | ------------------ | ----------- | ---------- |
+| `messages`         | 1–100, default 25  | `before`    | yes        |
+| `suppressions`     | 1–200, default 50  | `before`    | yes        |
+| `domains`          | 1–100, default 100 | `before`    | **no**     |
+| `webhooks`         | 1–100, default 50  | `before`    | **no**     |
+| `apiKeys`          | 1–100, default 50  | `before`    | **no**     |
+| `billing.invoices` | 1–100, default 50  | `before`    | **no**     |
+| `billing.history`  | 1–200, default 100 | **`after`** | **no**     |
+
+### Check both signals, and neither on its own
 
-`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 —
+The two obvious loops each break on a different endpoint, in opposite directions.
 
 ```ts
-// WRONG. This can never terminate.
+// WRONG, way one. This can never terminate.
+// `nextCursor` is derived from the last row of a page, and /v1/inbound/messages
+// returns a non-null cursor on its FINAL page — so this asks for the page after
+// the last one, gets an empty page carrying the same cursor, and spins for ever.
 let cursor: string | null | undefined = undefined;
 do {
   const page = await posthaste.messages.list({ before: cursor });
   cursor = page.nextCursor;
 } while (cursor);
+
+// WRONG, way two. This stops after ONE page.
+// domains, webhooks, apiKeys, billing.invoices and billing.history send no
+// `hasMore` at all, so this reads `undefined`, treats it as "that was
+// everything", and silently truncates. Compare with `=== false`.
+if (!page.hasMore) return;
 ```
 
-— 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.
+Neither failure produces an error. The first hangs; the second quietly gives you a partial list —
+sixty invoices behind a default of fifty is fifty invoices and no way to tell.
 
-`autoPaginate` encodes the correct condition, so you cannot get it wrong:
+`autoPaginate` consults both signals and treats each as authoritative only where the server actually
+sends it, so you cannot get either wrong:
 
 ```ts
 for await (const message of posthaste.messages.autoPaginate({ status: 'bounced' })) {
@@ -176,8 +281,8 @@ for await (const message of posthaste.messages.autoPaginate({ status: 'bounced'
 }
 ```
 
-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.
+It stops on `hasMore === false`, on a null cursor, on an empty page, and on 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:
 
@@ -185,8 +290,31 @@ For the common "give me an array" case, with a ceiling you choose:
 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.
+`messages`, `suppressions`, `domains`, `webhooks` and `apiKeys` all have the same three methods
+(`list`, `autoPaginate`, `listAll`). `billing` names its two lists explicitly:
+`invoices` / `autoPaginateInvoices` / `listAllInvoices`, and `history` / `autoPaginateHistory` /
+`listAllHistory`.
+
+### `billing.history` is the exception
+
+It is the one list that reads **forward**, and it does not take `before` at all. The billing record
+is a hash chain, a chain is verified from its start, and a record that renders in a different order
+than it verifies in is one people stop trusting — so events come back **oldest first** and you
+resume with `after`.
+
+`after` is a **sequence number** (a `BillingEvent.seq`), not a prefixed id; passing an id is a
+`400 invalid_request`. `nextCursor` is that number as a string, so passing it straight back is
+correct.
+
+```ts
+for await (const event of posthaste.billing.autoPaginateHistory()) {
+  console.log(event.seq, event.type);
+}
+```
+
+`chain` travels with every page and verifies the **whole account history**, not the page you are
+holding — so it means the same thing on page four as on page one. `autoPaginateHistory` yields only
+the events; call `history()` if you need the verification too.
 
 ---
 
@@ -198,7 +326,7 @@ Register an endpoint and Posthaste posts events to it as they happen. The signin
 ```ts
 const hook = await posthaste.webhooks.create({
   url: 'https://acme.com/hooks/posthaste',
-  eventTypes: ['delivered', 'bounced', 'complained'], // omit for all ten
+  eventTypes: ['delivered', 'bounced', 'complained'], // omit for all thirteen
 });
 
 await store(hook.signingSecret); // whsec_… — you cannot read it again
@@ -271,8 +399,9 @@ verifyWebhook(rawBody, header, secret, { toleranceSeconds: 300 });
 `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`.
+The thirteen event types are `accepted`, `queued`, `attempted`, `delivered`, `deferred`, `bounced`,
+`complained`, `failed`, `rejected`, `suppressed`, `scheduled`, `schedule_canceled` and
+`schedule_failed` — exported as `EVENT_TYPES`.
 
 ---
 
@@ -307,7 +436,8 @@ switch (err.type) {
     return permanent(err); // do not retry — fix the request
 
   case 'rate_limited':
-    return retryAfter(err.retryAfterSeconds ?? 60); // seconds; transient
+  case 'platform_paused':
+    return retryAfter(err.retryAfterSeconds ?? 60); // transient; come back
 
   case 'daily_limit_reached':
   case 'monthly_limit_reached':
@@ -343,21 +473,30 @@ 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`:
+**It branches on `error.type`, not on the status.** Four 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**   |
+| type                    | what it means                       | `Retry-After`  | classified as      | retried?  |
+| ----------------------- | ----------------------------------- | -------------- | ------------------ | --------- |
+| `rate_limited`          | too many requests for this key      | seconds        | `isRateLimited`    | yes       |
+| `platform_paused`       | the PLATFORM's daily send ceiling   | a few minutes  | `isRateLimited`    | see below |
+| `daily_limit_reached`   | today's warmup cap is spent         | until midnight | `isQuotaExhausted` | **no**    |
+| `monthly_limit_reached` | the plan's monthly allowance is out | up to a month  | `isQuotaExhausted` | **no**    |
 
-The last two are exhausted quota, not throttling. Retrying them in-process would hammer a wall the
+The bottom 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.
+`platform_paused` looks like them and is not one of them. It says the platform's own daily total is
+full, not that you have spent anything: nothing about your account changes it, upgrading does not
+clear it, and it frees as the day's total drains rather than on a calendar boundary. So it is
+`isRateLimited`, never `isQuotaExhausted` — tell a customer to come back, not to upgrade.
+
+A `Retry-After` longer than `maxRetryDelayMs` (60 seconds by default) is not slept through, whatever
+its type: blocking a request handler for fifteen minutes is indistinguishable from a hang. The real
+`platform_paused` ceiling sends about five minutes, so in practice it comes back to you to schedule —
+that is `maxRetryDelayMs` judging the length of the wait, not the quota rule, and raising
+`maxRetryDelayMs` makes the SDK sit through it.
 
 **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
@@ -377,7 +516,9 @@ account.verify()                              GET    /v1/account/verify
 account.usage()                               GET    /v1/usage
 
 domains.create({ name })                      POST   /v1/domains
-domains.list()                                GET    /v1/domains
+domains.list(params)                          GET    /v1/domains
+domains.autoPaginate(params)                  GET    /v1/domains    (all pages)
+domains.listAll(params, maxItems)             GET    /v1/domains    (all pages)
 domains.verify(id)                            POST   /v1/domains/:id/verify
 domains.delete(id)                            DELETE /v1/domains/:id
 domains.setup(id)                             GET    /v1/domains/:id/setup
@@ -385,11 +526,13 @@ domains.connectCloudflare(id, { token })      POST   /v1/domains/:id/cloudflare
 domains.disconnectCloudflare()                DELETE /v1/account/cloudflare
 
 emails.send(params)                           POST   /v1/emails
+emails.cancelSchedule(id)                     DELETE /v1/emails/:id/schedule
 
 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.downloadAttachment(msgId, attId)     GET    /v1/messages/:id/attachments/:attachmentId
 messages.stats(params)                        GET    /v1/stats/messages
 
 suppressions.list(params)                     GET    /v1/suppressions
@@ -399,14 +542,22 @@ 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.list(params)                         GET    /v1/webhooks
+webhooks.autoPaginate(params)                 GET    /v1/webhooks   (all pages)
+webhooks.listAll(params, maxItems)            GET    /v1/webhooks   (all pages)
 webhooks.delete(id)                           DELETE /v1/webhooks/:id
 
-apiKeys.list()                                GET    /v1/api-keys
+apiKeys.list(params)                          GET    /v1/api-keys
+apiKeys.autoPaginate(params)                  GET    /v1/api-keys   (all pages)
+apiKeys.listAll(params, maxItems)             GET    /v1/api-keys   (all pages)
 
 billing.get()                                 GET    /v1/billing
-billing.history()                             GET    /v1/billing/history
-billing.invoices()                            GET    /v1/billing/invoices
+billing.history(params)                       GET    /v1/billing/history  (`after`, oldest first)
+billing.autoPaginateHistory(params)           GET    /v1/billing/history  (all pages)
+billing.listAllHistory(params, maxItems)      GET    /v1/billing/history  (all pages)
+billing.invoices(params)                      GET    /v1/billing/invoices
+billing.autoPaginateInvoices(params)          GET    /v1/billing/invoices (all pages)
+billing.listAllInvoices(params, maxItems)     GET    /v1/billing/invoices (all pages)
 billing.invoice(id)                           GET    /v1/billing/invoices/:id
 ```
 

package/dist/base64.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pure base64 encoder for attachment bytes.
+ *
+ * Hand-rolled on purpose: this package ships with zero dependencies (enforced
+ * by packaging.test.ts), `Buffer` is Node-only and this SDK also runs bundled
+ * in edge runtimes, and `btoa` chokes on code points over 0xff unless the
+ * input is first mangled through a binary string. Fifteen lines beats any of
+ * those failure modes.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;

package/dist/base64.js

@@ -0,0 +1,22 @@
+/**
+ * Pure base64 encoder for attachment bytes.
+ *
+ * Hand-rolled on purpose: this package ships with zero dependencies (enforced
+ * by packaging.test.ts), `Buffer` is Node-only and this SDK also runs bundled
+ * in edge runtimes, and `btoa` chokes on code points over 0xff unless the
+ * input is first mangled through a binary string. Fifteen lines beats any of
+ * those failure modes.
+ */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function bytesToBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const a = bytes[i];
+        const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        out += ALPHABET[a >> 2] + ALPHABET[((a & 0x03) << 4) | (b >> 4)];
+        out += i + 1 < bytes.length ? ALPHABET[((b & 0x0f) << 2) | (c >> 6)] : '=';
+        out += i + 2 < bytes.length ? ALPHABET[c & 0x3f] : '=';
+    }
+    return out;
+}

package/dist/client.d.ts

@@ -12,7 +12,7 @@
  * 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';
+import type { Account, Billing, BillingEvent, BillingHistory, ChainVerification, CloudflarePublishResult, ConnectCloudflareParams, CreateDomainParams, CreateSuppressionParams, CreateWebhookParams, CreatedDomain, CreatedSuppression, CreatedWebhook, CursorPage, Domain, DomainSetup, DomainVerification, Invoice, InvoiceDetail, ApiKey, ListApiKeysParams, ListBillingHistoryParams, ListDomainsParams, ListInvoicesParams, ListMessagesParams, ListSuppressionsParams, ListWebhooksParams, Message, MessageStats, MessageStatsParams, MessageSummary, Page, SendEmailParams, SendEmailResult, Suppression, Usage, Webhook } from './types.js';
 export declare class Posthaste {
     private readonly http;
     readonly account: AccountResource;
@@ -52,8 +52,19 @@ export declare class DomainsResource {
      * 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>>;
+    /**
+     * `GET /v1/domains` — one keyset page, newest first.
+     *
+     * `limit` defaults to 100, which is also its maximum, so on most accounts the
+     * first page is every domain. It is still a page: past a hundred domains the
+     * rest are behind `nextCursor`, and there is no `hasMore` here to tell you so.
+     * Use `autoPaginate` if the count is not bounded by something you control.
+     */
+    list(params?: ListDomainsParams, options?: RequestOptions): Promise<CursorPage<Domain>>;
+    /** Every domain, across every page. */
+    autoPaginate(params?: ListDomainsParams, options?: RequestOptions): AsyncGenerator<Domain, void, undefined>;
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params?: ListDomainsParams, maxItems?: number, options?: RequestOptions): Promise<Domain[]>;
     /**
      * `POST /v1/domains/:id/verify` — look for the records and record the result.
      *
@@ -120,6 +131,18 @@ export declare class EmailsResource {
      * the header.
      */
     send(params: SendEmailParams, options?: RequestOptions): Promise<SendEmailResult>;
+    /**
+     * `DELETE /v1/emails/:id/schedule` — cancel a scheduled send.
+     *
+     * Succeeds until the message is released to delivery (which happens within
+     * about a minute of its scheduled time). A message that already released
+     * throws `not_scheduled` carrying its current status; a cancel retried
+     * after a lost response returns success again rather than erroring.
+     */
+    cancelSchedule(id: string, options?: RequestOptions): Promise<{
+        id: string;
+        status: 'canceled';
+    }>;
 }
 export declare class MessagesResource {
     private readonly http;
@@ -140,6 +163,19 @@ export declare class MessagesResource {
      * linkage, with the chain re-verified on read (`recordIntact`).
      */
     get(id: string, options?: RequestOptions): Promise<Message>;
+    /**
+     * `GET /v1/messages/:id/attachments/:attachmentId` — the stored bytes.
+     *
+     * The attachment id comes from `get(id).content.attachments[].id`. Returns
+     * the exact bytes that were sent; the server serves them with
+     * `Content-Disposition: attachment` and only ever an inert content type,
+     * echoed here for callers who re-serve the file.
+     */
+    downloadAttachment(messageId: string, attachmentId: string, options?: RequestOptions): Promise<{
+        bytes: Uint8Array;
+        contentType: string;
+        filename: string | null;
+    }>;
     /**
      * `GET /v1/stats/messages` — daily volume with the previous window for
      * comparison.
@@ -195,8 +231,17 @@ export declare class WebhooksResource {
      * 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>>;
+    /**
+     * `GET /v1/webhooks` — one keyset page, newest first. Never includes secrets.
+     *
+     * `limit` defaults to 50 and caps at 100. There is no `hasMore` on this
+     * endpoint; `nextCursor` is the end-of-list signal.
+     */
+    list(params?: ListWebhooksParams, options?: RequestOptions): Promise<CursorPage<Webhook>>;
+    /** Every webhook, across every page. */
+    autoPaginate(params?: ListWebhooksParams, options?: RequestOptions): AsyncGenerator<Webhook, void, undefined>;
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params?: ListWebhooksParams, maxItems?: number, options?: RequestOptions): Promise<Webhook[]>;
     /** `DELETE /v1/webhooks/:id` — 204, or 404 for an unknown id. */
     delete(id: string, options?: RequestOptions): Promise<void>;
 }
@@ -204,14 +249,22 @@ export declare class ApiKeysResource {
     private readonly http;
     constructor(http: HttpClient);
     /**
-     * `GET /v1/api-keys` — the 100 most recent keys, revoked ones included.
+     * `GET /v1/api-keys` — one keyset page of keys, revoked ones included.
+     *
+     * `limit` defaults to 50 and caps at 100, and revoked keys count towards it —
+     * so an account that has rotated its credentials a few times will have more
+     * than one page. No `hasMore`; `nextCursor` is the end-of-list signal.
      *
      * 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>>;
+    list(params?: ListApiKeysParams, options?: RequestOptions): Promise<CursorPage<ApiKey>>;
+    /** Every key, across every page. */
+    autoPaginate(params?: ListApiKeysParams, options?: RequestOptions): AsyncGenerator<ApiKey, void, undefined>;
+    /** Drain `autoPaginate` into an array, up to `maxItems`. */
+    listAll(params?: ListApiKeysParams, maxItems?: number, options?: RequestOptions): Promise<ApiKey[]>;
 }
 export declare class BillingResource {
     private readonly http;
@@ -225,10 +278,48 @@ export declare class BillingResource {
      * 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/history` — one page of the hash-chained commercial record,
+     * plus its verification.
+     *
+     * THE ODD ONE OUT, in two ways that a caller who assumes the house style will
+     * get wrong:
+     *
+     *   - It reads FORWARD. Events come back oldest first, and the page resumes
+     *     from `after`, not `before`. That is not a stylistic choice: a hash chain
+     *     is verified from its start, and a record that renders in a different
+     *     order than it verifies in is one people stop trusting.
+     *   - `after` is a SEQUENCE NUMBER — a `BillingEvent.seq` — not a prefixed id.
+     *     Passing an id gets `400 invalid_request`. `nextCursor` is that number
+     *     rendered as a string, so passing it straight back is correct.
+     *
+     * `limit` defaults to 100 and caps at 200. `chain` is verified over the whole
+     * account history rather than over the page, so it means the same thing on
+     * every page.
+     */
+    history(params?: ListBillingHistoryParams, options?: RequestOptions): Promise<BillingHistory>;
+    /**
+     * Every billing event, oldest first, across every page.
+     *
+     * Note that this yields the EVENTS only. `chain` is per-response, so if you
+     * need the verification as well, call `history` and read it from there.
+     */
+    autoPaginateHistory(params?: ListBillingHistoryParams, options?: RequestOptions): AsyncGenerator<BillingEvent, void, undefined>;
+    /** Drain `autoPaginateHistory` into an array, up to `maxItems`. */
+    listAllHistory(params?: ListBillingHistoryParams, maxItems?: number, options?: RequestOptions): Promise<BillingEvent[]>;
+    /**
+     * `GET /v1/billing/invoices` — one keyset page, newest first.
+     *
+     * `limit` defaults to 50 and caps at 100, and there is no `hasMore` here. An
+     * account past its fiftieth invoice that reads only `data` is silently short
+     * of its own financial record — follow `nextCursor`, or use
+     * `autoPaginateInvoices`.
+     */
+    invoices(params?: ListInvoicesParams, options?: RequestOptions): Promise<CursorPage<Invoice>>;
+    /** Every invoice, across every page. */
+    autoPaginateInvoices(params?: ListInvoicesParams, options?: RequestOptions): AsyncGenerator<Invoice, void, undefined>;
+    /** Drain `autoPaginateInvoices` into an array, up to `maxItems`. */
+    listAllInvoices(params?: ListInvoicesParams, maxItems?: number, options?: RequestOptions): Promise<Invoice[]>;
     /** `GET /v1/billing/invoices/:id` — the same document plus the supplier block. */
     invoice(id: string, options?: RequestOptions): Promise<InvoiceDetail>;
 }