meterflow 0.5.1 → 0.7.0

package/README.md

@@ -23,6 +23,7 @@ Track what your customers use, enforce credit balances, and manage subscriptions
   - [Usage events](#usage-events)
   - [Subscriptions](#subscriptions)
   - [Plans](#plans)
+  - [Webhook receipts](#webhook-receipts)
   - [Entitlements — ask before you act](#entitlements--ask-before-you-act)
 - [Idempotency — safe retries for writes](#idempotency--safe-retries-for-writes)
 - [Automatic retries](#automatic-retries)
@@ -177,15 +178,26 @@ bal.total_granted;  // "5250.000000"
 bal.total_consumed; // "1705.000000"
 ```
 
-**Transactions** — the full history, newest first, paginated:
+**Transactions** — the customer's history, newest first, **a page at a time**:
 
 ```typescript
-const txns = await client.credits.transactions("customer_123", { page: 1, limit: 50 });
-for (const t of txns) {
+const page = await client.credits.transactions("customer_123");          // 50 rows by default
+for (const t of page.data) {
   console.log(t.transaction_type, t.amount, t.balance_after, t.description, t.created_at);
 }
+
+// The whole history, page by page. `next_cursor` is null once there is nothing after it.
+let cursor: string | undefined;
+do {
+  const page = await client.credits.transactions("customer_123", { limit: 200, cursor });
+  handle(page.data);
+  cursor = page.next_cursor ?? undefined;
+} while (cursor);
 ```
 
+> **The cursor is opaque.** Pass back exactly what `next_cursor` gave you; do not build one, and do
+> not read anything out of it. `limit` is 1–200 and defaults to 50.
+
 > **Amounts are decimal strings.** Balances and amounts come back as strings (`"3545.000000"`) to avoid floating-point drift on money-like values. Parse deliberately (`Number(...)` or a decimal library) when you need arithmetic.
 
 ### Usage events
@@ -198,7 +210,7 @@ Record an event every time a customer does the thing you charge for. Events are
 await client.usage.record({
   event_name: "images.generated",
   customer_external_id: "customer_123",
-  value: 1,                                  // what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
+  value: 1,                                  // optional — what the meter aggregates: 1 for counts, seconds/MB/etc. for sums
   properties: {},                            // free-form context; {} when unused
   timestamp: new Date().toISOString(),       // optional — defaults to arrival time on the server
 });
@@ -224,6 +236,40 @@ for (let i = 0; i < events.length; i += MAX_BATCH_EVENTS) {
 }
 ```
 
+### Record quantities, not calls
+
+**A batch of 100 events is still 100 events.** Batching saves HTTP requests, not quota: each item in a `recordBatch` is its own record, and your plan's monthly allowance counts records. The thing that actually moves the number is sending **one event that carries the quantity**.
+
+If your meter's aggregation is `sum`, MeterFlow adds up the `value` of its events — so one event with `value: 100` is **one** event against your monthly allowance and **100 units** against the meter. Record per unit of work instead of per API call:
+
+```typescript
+// ❌ One event per call — 100 calls is 100 events against your plan.
+for (const chunk of completion.chunks) {
+  await client.usage.record({
+    event_name: "tokens.used",
+    customer_external_id: "customer_123",
+    value: 1,
+    properties: {},
+  });
+}
+
+// ✅ One event carrying the quantity — 1 event against your plan, 1,300 units on the meter.
+await client.usage.record({
+  event_name: "tokens.used",
+  customer_external_id: "customer_123",
+  value: 1300,                 // a `sum` meter adds these up
+  properties: { model: "gpt-4o-mini" },
+});
+```
+
+This is usually the difference between fitting a plan and outgrowing it: 1,000 users × 100 calls a day is ~3M events a month recorded per call, and ~30k recorded per session. Aggregate in your app over whatever window you can afford to lose on a crash — a request, a job, a minute — then send one event.
+
+Two things to keep in mind:
+
+- **It only helps a `sum` meter.** A `count` meter ignores `value` and counts occurrences, so there each occurrence has to be its own event. `max` and `min` read `value` as a measurement, not a quantity to add, and `unique_count` does not read it at all — it counts distinct values of the property its meter names.
+- **`value` is optional.** Leave it out and MeterFlow fills it in: for a `sum`, `max` or `min` meter that names an `aggregation_field`, the numeric value of that property on the event; otherwise `1`. So the event above can be written `properties: { tokens: 1300 }` with no `value`, as long as the meter's `aggregation_field` is `tokens`. An explicit `value` always wins, a property that is absent or is not a number falls through to `1`, and a negative one is refused with a `422`.
+- **Billing is unchanged.** A metered plan limit charges per unit — the event's `value` — so 100 units cost the same whether they arrived as 100 events or one. You are not rounding anyone's bill by batching.
+
 **Summary** — a customer's usage, broken down by meter:
 
 ```typescript
@@ -262,11 +308,16 @@ console.log(sub.status); // "trialing" if the plan has trial days, else "active"
 **List / get:**
 
 ```typescript
-const all = await client.subscriptions.list();                                // whole project (in your key's environment)
+const page = await client.subscriptions.list();                                 // whole project (in your key's environment)
 const theirs = await client.subscriptions.list({ customer_id: "customer_123" }); // one customer
+const more = await client.subscriptions.list({ limit: 200, cursor: page.next_cursor ?? undefined });
 const one = await client.subscriptions.get(sub.id);
+
+page.data.forEach((subscription) => console.log(subscription.customer_external_id, subscription.status));
 ```
 
+> **`list()` answers a page**, `{ data, next_cursor }` — `get()` still answers one subscription.
+
 > Like all reads, these are scoped to the key's environment: a live key lists live subscriptions only, a test key test ones only.
 
 **Update** — change status or metadata. Statuses: `active`, `trialing`, `past_due`, `paused`, `canceled`, `expired`:
@@ -299,6 +350,27 @@ plan.meter_limits;   // included units + overage rate per meter
 
 Typical use: render your pricing page or signup flow from `plans.list()` so it can never drift from what billing actually enforces.
 
+### Webhook receipts
+
+Webhooks are **read-only** through the SDK too: endpoints are registered in the dashboard, where the signing secret is shown once and never again. What the SDK gives you is the other half — which endpoints exist, and what MeterFlow actually sent them.
+
+```typescript
+const endpoints = await client.webhooks.list();                   // this project's endpoints
+const receipts = await client.webhooks.deliveries(endpoint_id);   // newest first
+receipts[0].event_type;    // "usage.recorded"
+receipts[0].status;        // "pending" | "retrying" | "success" | "failed"
+receipts[0].response_code; // what your server answered — 200, 500, or null if it never answered
+receipts[0].attempts;      // how many times we have tried
+receipts[0].next_retry_at; // when we will try again, or null
+receipts[0].payload;       // exactly what we sent
+```
+
+Typical use: answering "did that event reach my endpoint?" from your own tooling instead of opening the dashboard — and reading `response_body` when the answer is no.
+
+Two things to know. The list is capped at the **most recent 100** attempts per endpoint; it is a debugging surface, not an export. And it follows your key: a `mf_test_*` key reads test receipts, a `mf_live_*` key live ones, while the endpoint list itself is shared by both worlds, because an endpoint is configuration and receives events from each.
+
+> This is not the same as [verifying webhooks](#verifying-webhooks) below. That proves a request your server just received really came from us; this reads what we sent.
+
 ### Entitlements — ask before you act
 
 The one call to make **before** doing work for a customer: "may they use this feature — and how much is left?" A **hard** limit says no here; recording usage afterwards never blocks, so an app that skips this call gets an honest ledger but no enforcement.
@@ -307,7 +379,7 @@ The one call to make **before** doing work for a customer: "may they use this fe
 const gate = await client.entitlements.check("customer_123", "images.generated");
 
 if (!gate.allowed) {
-  // gate.reason: "hard_limit_reached" | "no_subscription" | "not_in_plan" | "insufficient_credits"
+  // gate.reason: "hard_limit_reached" | "no_subscription" | "not_in_plan" | "insufficient_credits" | "spend_cap_reached"
   return showUpgradePrompt(gate); // gate.used / gate.included / gate.period_end are there for the copy
 }
 
@@ -331,6 +403,30 @@ const { entitlements, period_end } = await client.entitlements.get("customer_123
 
 Prefer to be told rather than to ask? Subscribe a webhook to `limit.reached` (see below).
 
+### The balance portal — a page you don't have to build
+
+Mint a short-lived link to a MeterFlow-hosted page showing **one** customer's balance and ledger.
+Call it from your server; send the `url` to that customer.
+
+```typescript
+const link = await client.portal.createSession({
+  customer_external_id: "customer_123",
+  topup_url: "https://acme.test/billing",   // your checkout — "buy more" goes here
+  return_url: "https://acme.test/app",      // where "done" goes
+  expires_in_minutes: 60,                   // default 60, maximum 1440
+});
+
+sendEmail(customer.email, `Your balance: ${link.url}`);
+```
+
+The token in that link reads **that one customer's** balance and ledger, in the environment of the
+key you minted it with, and nothing else: it cannot write, cannot name another customer, and is
+refused everywhere else in the API. It is never your API key — never send that to anyone.
+
+> **MeterFlow never takes the payment.** `topup_url` is a link we carry and hand back to the page;
+> what happens there is between you and your own payment provider. Grant the credits with
+> `credits.grant()` when your checkout tells you it was paid.
+
 ## Idempotency — safe retries for writes
 
 Connections drop. When your app can't tell whether a write arrived, the correct move is to send it again **with the same idempotency key** — MeterFlow recognises the key and acts only once:
@@ -345,6 +441,17 @@ await client.credits.deduct(
 
 Every write method accepts the option: `credits.grant/deduct`, `usage.record/recordBatch`, `subscriptions.create/update`. Use a key that identifies the *business operation* (order ID, job ID) — not a random value per attempt, which would defeat the purpose.
 
+**A key is bound to the body you first used it with.** MeterFlow stores a fingerprint of the request alongside the key, so a retry only replays when it is genuinely the same request. Reuse the key with a *different* body and the call is refused with `ConflictError` (409) instead of quietly handing back the original record:
+
+```typescript
+await client.credits.grant({ customer_external_id: "customer_123", amount: 100, metadata: {} }, { idempotencyKey: "welcome-123" });
+
+// Same key, different amount → ConflictError. Nothing is written, and the first grant stands.
+await client.credits.grant({ customer_external_id: "customer_123", amount: 250, metadata: {} }, { idempotencyKey: "welcome-123" });
+```
+
+That is deliberate: silently returning the first record would turn two different operations into one and report success. One key per operation, reused only to retry that same operation. Keys stay namespaced per environment, so a `mf_test_` and a `mf_live_` key never collide.
+
 ## Automatic retries
 
 The SDK retries transient failures for you — exponential backoff with jitter, 3 attempts by default:
@@ -377,7 +484,7 @@ Every error carries:
 
 - **`requestId`** — the API's `X-Request-ID` for that call. Include it when contacting support; it pinpoints the exact request in our logs.
 - **`statusCode`**, **`errorType`**, and **`retryable`** — for programmatic handling and structured logging.
-- **`message`** — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 5,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`{ field, message }[]`).
+- **`message`** — the API's own sentence (e.g. `Plan limit reached: the Drip plan includes 50,000 usage events per month…`). A `ValidationError` appends its field detail (`Validation failed: amount: must be greater than 0`) and also exposes it structured as **`.fields`** (`{ field, message }[]`).
 
 ```typescript
 import { MeterFlowError, InsufficientCreditsError, RateLimitError } from "meterflow";
@@ -440,6 +547,12 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `subscription.created` | a subscription is created | `customer_id`, `plan_id`, `subscription_id`, `status` |
 | `subscription.updated` | a subscription is updated | `customer_id`, `subscription_id`, `status` |
 | `limit.reached` | a customer first reaches a **hard** or **soft** limit's included units this billing period (once per meter per period; metered limits report through `credit.deducted` instead) | `customer_id`, `subscription_id`, `feature` (the meter's `event_name`), `meter_id`, `limit_type`, `included`, `used`, `period_start`, `period_end` |
+| `balance.low` | a spend takes a customer's balance **down through** this endpoint's `low_balance_threshold` — a crossing, so it fires once and not again while they stay below. Raised by both doors that spend: `credits.deduct` and a metered usage charge. **Both crossing events follow from the endpoint's `low_balance_threshold`: set one and the API adds them, clear it and the API removes them — so a line is the only thing to configure.** | `customer_id`, `balance`, `threshold`, `suggested_topup` (the subscription's `topup_amount`, `null` when unset), `transaction_id` |
+| `balance.exhausted` | a balance reaches zero, **or** a request is refused for want of credits (a deduction returning 402, or `entitlements.check` answering `insufficient_credits`). Unlike `balance.low` this repeats: every refused request is its own blocked request | `customer_id`, `balance`, `reason` (`balance_zero` / `insufficient_credits`), `requested_amount` and `feature` where they apply, `transaction_id` on the zero case |
+| `subscription.renewed` | a billing period opens — either a paid period rolling forward or a **trial converting** to its first paid period, told apart by `reason` (the renewer emits no `subscription.updated` for either) | `customer_id`, `subscription_id`, `plan_id`, `status`, `reason` (`period_renewed` / `trial_converted`), `current_period_start`, `current_period_end`, `credits_granted` |
+| `subscription.canceled` | a subscription's status becomes canceled — fired **alongside** `subscription.updated`, once, on the call that actually cancels | `customer_id`, `subscription_id`, `plan_id`, `canceled_at` |
+| `balance.topped_up` | a grant takes a customer's balance **up through** this endpoint's `low_balance_threshold` — the upward mirror of `balance.low`, on the same per-endpoint line, so the endpoint told "low" is the one told "recovered". Subscribed together with `balance.low` by setting the threshold, never on its own | `customer_id`, `balance`, `threshold`, `amount`, `transaction_id` |
+| `cap.reached` | a customer's credit spending reaches their subscription's `spend_cap` for the period — once per subscription per period, whether they landed on the cap or were refused by it. A refusal that still leaves headroom is not a reach and does not fire | `customer_id`, `subscription_id`, `cap`, `spent`, `period_start`, `period_end` |
 
 For example, a `credit.granted` delivery:
 
@@ -509,6 +622,6 @@ await client.usage.record({
 
 // Support asks: "what's Ana's situation?"
 const balance = await client.credits.balance("ana");
-const history = await client.credits.transactions("ana", { limit: 20 });
+const { data: history } = await client.credits.transactions("ana");
 const usage = await client.usage.summary("ana");
 ```

package/dist/client.d.ts

@@ -2,7 +2,9 @@ import { CreditsResource } from "./resources/credits";
 import { UsageResource } from "./resources/usage";
 import { SubscriptionsResource } from "./resources/subscriptions";
 import { PlansResource } from "./resources/plans";
+import { PortalResource } from "./resources/portal";
 import { EntitlementsResource } from "./resources/entitlements";
+import { WebhooksResource } from "./resources/webhooks";
 export interface MeterFlowOptions {
     apiKey: string;
     baseUrl?: string;
@@ -22,13 +24,18 @@ export declare class MeterFlow {
     private _usage?;
     private _subscriptions?;
     private _plans?;
+    private _portal?;
     private _entitlements?;
+    private _webhooks?;
     constructor(options: MeterFlowOptions);
+    get portal(): PortalResource;
     get credits(): CreditsResource;
     get usage(): UsageResource;
     get subscriptions(): SubscriptionsResource;
     get plans(): PlansResource;
     get entitlements(): EntitlementsResource;
+    /** Read-only: the endpoints registered for this project, and what we sent them. */
+    get webhooks(): WebhooksResource;
     /** @internal — used by resource classes only; not part of the public API */
     request<T>(method: string, path: string, opts?: RequestOptions): Promise<T>;
 }

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAS;IACpB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,OAAO,CAAC,QAAQ,CAAC,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAC,CAAgB;IAC/B,OAAO,CAAC,cAAc,CAAC,CAAwB;IAC/C,OAAO,CAAC,MAAM,CAAC,CAAgB;IAC/B,OAAO,CAAC,aAAa,CAAC,CAAuB;gBAEjC,OAAO,EAAE,gBAAgB;IAerC,IAAI,OAAO,IAAI,eAAe,CAE7B;IAED,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,aAAa,IAAI,qBAAqB,CAEzC;IAED,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,YAAY,IAAI,oBAAoB,CAEvC;IAED,4EAA4E;IAC5E,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAG5E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,SAAS;IACpB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IAE7C,OAAO,CAAC,QAAQ,CAAC,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAC,CAAgB;IAC/B,OAAO,CAAC,cAAc,CAAC,CAAwB;IAC/C,OAAO,CAAC,MAAM,CAAC,CAAgB;IAC/B,OAAO,CAAC,OAAO,CAAC,CAAiB;IACjC,OAAO,CAAC,aAAa,CAAC,CAAuB;IAC7C,OAAO,CAAC,SAAS,CAAC,CAAmB;gBAEzB,OAAO,EAAE,gBAAgB;IAerC,IAAI,MAAM,IAAI,cAAc,CAE3B;IAED,IAAI,OAAO,IAAI,eAAe,CAE7B;IAED,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,aAAa,IAAI,qBAAqB,CAEzC;IAED,IAAI,KAAK,IAAI,aAAa,CAEzB;IAED,IAAI,YAAY,IAAI,oBAAoB,CAEvC;IAED,mFAAmF;IACnF,IAAI,QAAQ,IAAI,gBAAgB,CAE/B;IAED,4EAA4E;IAC5E,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAG5E"}

package/dist/index.cjs

@@ -35,7 +35,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.5.1";
+var version = "0.7.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -245,6 +245,13 @@ var CreditsResource = class {
   balance(customerId) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/balance`);
   }
+  /**
+   * One page of the customer's ledger, newest first.
+   *
+   * The ledger grows with every charge, so it is read a page at a time: `data` holds the rows and
+   * `next_cursor` the mark for the page after this one (`null` on the last). Pass it back as
+   * `cursor` unchanged — it is opaque, and nothing but this API reads it.
+   */
   transactions(customerId, query) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`, {
       ...query !== void 0 && { query }
@@ -303,6 +310,12 @@ var SubscriptionsResource = class {
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
     });
   }
+  /**
+   * One page of the project's subscriptions in this key's environment, newest first.
+   *
+   * `data` holds the rows and `next_cursor` the mark for the page after this one (`null` on the
+   * last). Pass it back as `cursor` unchanged — it is opaque, and nothing but this API reads it.
+   */
   list(query) {
     return this.client.request("GET", "subscriptions", {
       ...query !== void 0 && { query }
@@ -339,6 +352,29 @@ var PlansResource = class {
   }
 };
 
+// src/resources/portal.ts
+var PortalResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Mint a link to the hosted balance page for one of your customers.
+   *
+   * Call this from **your** server and send the `url` to that customer — it carries a short-lived
+   * token that can read their balance and their ledger and nothing else, in the environment of the
+   * key you called with. It is never your API key, and it can write nothing.
+   *
+   * The page shows the balance and sends "buy more" to your own checkout (`topup_url`): MeterFlow
+   * never takes the payment. `expires_in_minutes` defaults to 60 and may not exceed 1440.
+   *
+   * The two reads behind the page are **not** on this client by design: they belong to the person
+   * holding the link, and this client holds a secret key.
+   */
+  createSession(body) {
+    return this.client.request("POST", "portal/sessions", { body });
+  }
+};
+
 // src/resources/entitlements.ts
 var EntitlementsResource = class {
   constructor(client) {
@@ -356,6 +392,28 @@ var EntitlementsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every endpoint registered for the key's project. Never includes a secret. */
+  list() {
+    return this.client.request("GET", "webhooks");
+  }
+  /**
+   * One endpoint's delivery attempts, newest first: the payload sent, the HTTP status that came
+   * back, how many attempts and when the next retry is due.
+   *
+   * Capped at the most recent 100, and scoped to the key's own environment — a `mf_test_*` key
+   * reads test receipts, a `mf_live_*` key live ones. A webhook belonging to another project
+   * answers 404.
+   */
+  deliveries(webhookId) {
+    return this.client.request("GET", `webhooks/${encodeURIComponent(webhookId)}/deliveries`);
+  }
+};
+
 // src/client.ts
 var MeterFlow = class {
   options;
@@ -363,7 +421,9 @@ var MeterFlow = class {
   _usage;
   _subscriptions;
   _plans;
+  _portal;
   _entitlements;
+  _webhooks;
   constructor(options) {
     if (!options.apiKey.startsWith("mf_live_") && !options.apiKey.startsWith("mf_test_")) {
       throw new Error("apiKey must start with mf_live_ or mf_test_");
@@ -378,6 +438,9 @@ var MeterFlow = class {
       fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
     };
   }
+  get portal() {
+    return this._portal ??= new PortalResource(this);
+  }
   get credits() {
     return this._credits ??= new CreditsResource(this);
   }
@@ -393,6 +456,10 @@ var MeterFlow = class {
   get entitlements() {
     return this._entitlements ??= new EntitlementsResource(this);
   }
+  /** Read-only: the endpoints registered for this project, and what we sent them. */
+  get webhooks() {
+    return this._webhooks ??= new WebhooksResource(this);
+  }
   /** @internal — used by resource classes only; not part of the public API */
   request(method, path, opts) {
     return httpRequest(this.options, method, path, opts);

package/dist/index.js

@@ -35,7 +35,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.5.1";
+var version = "0.7.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -245,6 +245,13 @@ var CreditsResource = class {
   balance(customerId) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/balance`);
   }
+  /**
+   * One page of the customer's ledger, newest first.
+   *
+   * The ledger grows with every charge, so it is read a page at a time: `data` holds the rows and
+   * `next_cursor` the mark for the page after this one (`null` on the last). Pass it back as
+   * `cursor` unchanged — it is opaque, and nothing but this API reads it.
+   */
   transactions(customerId, query) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`, {
       ...query !== void 0 && { query }
@@ -303,6 +310,12 @@ var SubscriptionsResource = class {
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
     });
   }
+  /**
+   * One page of the project's subscriptions in this key's environment, newest first.
+   *
+   * `data` holds the rows and `next_cursor` the mark for the page after this one (`null` on the
+   * last). Pass it back as `cursor` unchanged — it is opaque, and nothing but this API reads it.
+   */
   list(query) {
     return this.client.request("GET", "subscriptions", {
       ...query !== void 0 && { query }
@@ -339,6 +352,29 @@ var PlansResource = class {
   }
 };
 
+// src/resources/portal.ts
+var PortalResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Mint a link to the hosted balance page for one of your customers.
+   *
+   * Call this from **your** server and send the `url` to that customer — it carries a short-lived
+   * token that can read their balance and their ledger and nothing else, in the environment of the
+   * key you called with. It is never your API key, and it can write nothing.
+   *
+   * The page shows the balance and sends "buy more" to your own checkout (`topup_url`): MeterFlow
+   * never takes the payment. `expires_in_minutes` defaults to 60 and may not exceed 1440.
+   *
+   * The two reads behind the page are **not** on this client by design: they belong to the person
+   * holding the link, and this client holds a secret key.
+   */
+  createSession(body) {
+    return this.client.request("POST", "portal/sessions", { body });
+  }
+};
+
 // src/resources/entitlements.ts
 var EntitlementsResource = class {
   constructor(client) {
@@ -356,6 +392,28 @@ var EntitlementsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every endpoint registered for the key's project. Never includes a secret. */
+  list() {
+    return this.client.request("GET", "webhooks");
+  }
+  /**
+   * One endpoint's delivery attempts, newest first: the payload sent, the HTTP status that came
+   * back, how many attempts and when the next retry is due.
+   *
+   * Capped at the most recent 100, and scoped to the key's own environment — a `mf_test_*` key
+   * reads test receipts, a `mf_live_*` key live ones. A webhook belonging to another project
+   * answers 404.
+   */
+  deliveries(webhookId) {
+    return this.client.request("GET", `webhooks/${encodeURIComponent(webhookId)}/deliveries`);
+  }
+};
+
 // src/client.ts
 var MeterFlow = class {
   options;
@@ -363,7 +421,9 @@ var MeterFlow = class {
   _usage;
   _subscriptions;
   _plans;
+  _portal;
   _entitlements;
+  _webhooks;
   constructor(options) {
     if (!options.apiKey.startsWith("mf_live_") && !options.apiKey.startsWith("mf_test_")) {
       throw new Error("apiKey must start with mf_live_ or mf_test_");
@@ -378,6 +438,9 @@ var MeterFlow = class {
       fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
     };
   }
+  get portal() {
+    return this._portal ??= new PortalResource(this);
+  }
   get credits() {
     return this._credits ??= new CreditsResource(this);
   }
@@ -393,6 +456,10 @@ var MeterFlow = class {
   get entitlements() {
     return this._entitlements ??= new EntitlementsResource(this);
   }
+  /** Read-only: the endpoints registered for this project, and what we sent them. */
+  get webhooks() {
+    return this._webhooks ??= new WebhooksResource(this);
+  }
   /** @internal — used by resource classes only; not part of the public API */
   request(method, path, opts) {
     return httpRequest(this.options, method, path, opts);

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.5.1";
+var version = "0.7.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -209,6 +209,13 @@ var CreditsResource = class {
   balance(customerId) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/balance`);
   }
+  /**
+   * One page of the customer's ledger, newest first.
+   *
+   * The ledger grows with every charge, so it is read a page at a time: `data` holds the rows and
+   * `next_cursor` the mark for the page after this one (`null` on the last). Pass it back as
+   * `cursor` unchanged — it is opaque, and nothing but this API reads it.
+   */
   transactions(customerId, query) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`, {
       ...query !== void 0 && { query }
@@ -267,6 +274,12 @@ var SubscriptionsResource = class {
       ...opts?.idempotencyKey !== void 0 && { idempotencyKey: opts.idempotencyKey }
     });
   }
+  /**
+   * One page of the project's subscriptions in this key's environment, newest first.
+   *
+   * `data` holds the rows and `next_cursor` the mark for the page after this one (`null` on the
+   * last). Pass it back as `cursor` unchanged — it is opaque, and nothing but this API reads it.
+   */
   list(query) {
     return this.client.request("GET", "subscriptions", {
       ...query !== void 0 && { query }
@@ -303,6 +316,29 @@ var PlansResource = class {
   }
 };
 
+// src/resources/portal.ts
+var PortalResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Mint a link to the hosted balance page for one of your customers.
+   *
+   * Call this from **your** server and send the `url` to that customer — it carries a short-lived
+   * token that can read their balance and their ledger and nothing else, in the environment of the
+   * key you called with. It is never your API key, and it can write nothing.
+   *
+   * The page shows the balance and sends "buy more" to your own checkout (`topup_url`): MeterFlow
+   * never takes the payment. `expires_in_minutes` defaults to 60 and may not exceed 1440.
+   *
+   * The two reads behind the page are **not** on this client by design: they belong to the person
+   * holding the link, and this client holds a secret key.
+   */
+  createSession(body) {
+    return this.client.request("POST", "portal/sessions", { body });
+  }
+};
+
 // src/resources/entitlements.ts
 var EntitlementsResource = class {
   constructor(client) {
@@ -320,6 +356,28 @@ var EntitlementsResource = class {
   }
 };
 
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every endpoint registered for the key's project. Never includes a secret. */
+  list() {
+    return this.client.request("GET", "webhooks");
+  }
+  /**
+   * One endpoint's delivery attempts, newest first: the payload sent, the HTTP status that came
+   * back, how many attempts and when the next retry is due.
+   *
+   * Capped at the most recent 100, and scoped to the key's own environment — a `mf_test_*` key
+   * reads test receipts, a `mf_live_*` key live ones. A webhook belonging to another project
+   * answers 404.
+   */
+  deliveries(webhookId) {
+    return this.client.request("GET", `webhooks/${encodeURIComponent(webhookId)}/deliveries`);
+  }
+};
+
 // src/client.ts
 var MeterFlow = class {
   options;
@@ -327,7 +385,9 @@ var MeterFlow = class {
   _usage;
   _subscriptions;
   _plans;
+  _portal;
   _entitlements;
+  _webhooks;
   constructor(options) {
     if (!options.apiKey.startsWith("mf_live_") && !options.apiKey.startsWith("mf_test_")) {
       throw new Error("apiKey must start with mf_live_ or mf_test_");
@@ -342,6 +402,9 @@ var MeterFlow = class {
       fetch: options.fetch ?? globalThis.fetch.bind(globalThis)
     };
   }
+  get portal() {
+    return this._portal ??= new PortalResource(this);
+  }
   get credits() {
     return this._credits ??= new CreditsResource(this);
   }
@@ -357,6 +420,10 @@ var MeterFlow = class {
   get entitlements() {
     return this._entitlements ??= new EntitlementsResource(this);
   }
+  /** Read-only: the endpoints registered for this project, and what we sent them. */
+  get webhooks() {
+    return this._webhooks ??= new WebhooksResource(this);
+  }
   /** @internal — used by resource classes only; not part of the public API */
   request(method, path, opts) {
     return httpRequest(this.options, method, path, opts);

package/dist/resources/credits.d.ts

@@ -3,6 +3,7 @@ import type { components } from "../types/openapi";
 type CreditGrantRequest = components["schemas"]["CreditGrantRequest"];
 type CreditDeductRequest = components["schemas"]["CreditDeductRequest"];
 type CreditTransactionResponse = components["schemas"]["CreditTransactionResponse"];
+type CreditTransactionPage = components["schemas"]["CreditTransactionPage"];
 type CreditBalanceResponse = components["schemas"]["CreditBalanceResponse"];
 export interface GrantOptions {
     idempotencyKey?: string;
@@ -10,9 +11,10 @@ export interface GrantOptions {
 export interface DeductOptions {
     idempotencyKey?: string;
 }
-export interface TransactionsQuery {
-    page?: number;
+/** One page of a list: how many rows, and where to carry on from. */
+export interface PageQuery {
     limit?: number;
+    cursor?: string;
 }
 export declare class CreditsResource {
     private readonly client;
@@ -20,7 +22,14 @@ export declare class CreditsResource {
     grant(body: CreditGrantRequest, opts?: GrantOptions): Promise<CreditTransactionResponse>;
     deduct(body: CreditDeductRequest, opts?: DeductOptions): Promise<CreditTransactionResponse>;
     balance(customerId: string): Promise<CreditBalanceResponse>;
-    transactions(customerId: string, query?: TransactionsQuery): Promise<CreditTransactionResponse[]>;
+    /**
+     * One page of the customer's ledger, newest first.
+     *
+     * The ledger grows with every charge, so it is read a page at a time: `data` holds the rows and
+     * `next_cursor` the mark for the page after this one (`null` on the last). Pass it back as
+     * `cursor` unchanged — it is opaque, and nothing but this API reads it.
+     */
+    transactions(customerId: string, query?: PageQuery): Promise<CreditTransactionPage>;
 }
 export {};
 //# sourceMappingURL=credits.d.ts.map

package/dist/resources/credits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../../src/resources/credits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,CAAC;AACtE,KAAK,mBAAmB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,qBAAqB,CAAC,CAAC;AACxE,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AACpF,KAAK,qBAAqB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,uBAAuB,CAAC,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,KAAK,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAOxF,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAO3F,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI3D,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC;CAKlG"}
+{"version":3,"file":"credits.d.ts","sourceRoot":"","sources":["../../../src/resources/credits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,CAAC;AACtE,KAAK,mBAAmB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,qBAAqB,CAAC,CAAC;AACxE,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AACpF,KAAK,qBAAqB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,uBAAuB,CAAC,CAAC;AAC5E,KAAK,qBAAqB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,uBAAuB,CAAC,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,KAAK,CAAC,IAAI,EAAE,kBAAkB,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAOxF,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAO3F,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAI3D;;;;;;OAMG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAKpF"}

package/dist/resources/portal.d.ts

@@ -0,0 +1,24 @@
+import type { MeterFlow } from "../client";
+import type { components } from "../types/openapi";
+type PortalLinkRequest = components["schemas"]["PortalLinkRequest"];
+type PortalLinkResponse = components["schemas"]["PortalLinkResponse"];
+export declare class PortalResource {
+    private readonly client;
+    constructor(client: MeterFlow);
+    /**
+     * Mint a link to the hosted balance page for one of your customers.
+     *
+     * Call this from **your** server and send the `url` to that customer — it carries a short-lived
+     * token that can read their balance and their ledger and nothing else, in the environment of the
+     * key you called with. It is never your API key, and it can write nothing.
+     *
+     * The page shows the balance and sends "buy more" to your own checkout (`topup_url`): MeterFlow
+     * never takes the payment. `expires_in_minutes` defaults to 60 and may not exceed 1440.
+     *
+     * The two reads behind the page are **not** on this client by design: they belong to the person
+     * holding the link, and this client holds a secret key.
+     */
+    createSession(body: PortalLinkRequest): Promise<PortalLinkResponse>;
+}
+export {};
+//# sourceMappingURL=portal.d.ts.map

package/dist/resources/portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portal.d.ts","sourceRoot":"","sources":["../../../src/resources/portal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,iBAAiB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,mBAAmB,CAAC,CAAC;AACpE,KAAK,kBAAkB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,oBAAoB,CAAC,CAAC;AAEtE,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAGpE"}

package/dist/resources/subscriptions.d.ts

@@ -3,17 +3,28 @@ import type { components } from "../types/openapi";
 type SubscriptionCreateRequest = components["schemas"]["SubscriptionCreateRequest"];
 type SubscriptionUpdateRequest = components["schemas"]["SubscriptionUpdateRequest"];
 type SubscriptionResponse = components["schemas"]["SubscriptionResponse"];
+type SubscriptionPage = components["schemas"]["SubscriptionPage"];
 export interface CreateOptions {
     idempotencyKey?: string;
 }
 export interface ListQuery {
     customer_id?: string;
+    /** Rows per page, 1–200 (50 by default). */
+    limit?: number;
+    /** `next_cursor` from the previous page; omit for the first. */
+    cursor?: string;
 }
 export declare class SubscriptionsResource {
     private readonly client;
     constructor(client: MeterFlow);
     create(body: SubscriptionCreateRequest, opts?: CreateOptions): Promise<SubscriptionResponse>;
-    list(query?: ListQuery): Promise<SubscriptionResponse[]>;
+    /**
+     * One page of the project's subscriptions in this key's environment, newest first.
+     *
+     * `data` holds the rows and `next_cursor` the mark for the page after this one (`null` on the
+     * last). Pass it back as `cursor` unchanged — it is opaque, and nothing but this API reads it.
+     */
+    list(query?: ListQuery): Promise<SubscriptionPage>;
     get(subscriptionId: string): Promise<SubscriptionResponse>;
     update(subscriptionId: string, body: SubscriptionUpdateRequest, opts?: {
         idempotencyKey?: string;

package/dist/resources/subscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../../src/resources/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AACpF,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AACpF,KAAK,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,MAAM,CAAC,IAAI,EAAE,yBAAyB,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAO5F,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAMxD,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI1D,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAOlI,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../../src/resources/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AACpF,KAAK,yBAAyB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,2BAA2B,CAAC,CAAC;AACpF,KAAK,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,CAAC;AAC1E,KAAK,gBAAgB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAElE,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,MAAM,CAAC,IAAI,EAAE,yBAAyB,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAO5F;;;;;OAKG;IACH,IAAI,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAMlD,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI1D,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,EAAE,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAOlI,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAG9C"}

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,31 @@
+import type { MeterFlow } from "../client";
+import type { components } from "../types/openapi";
+type WebhookResponse = components["schemas"]["WebhookResponse"];
+type WebhookDeliveryResponse = components["schemas"]["WebhookDeliveryResponse"];
+/**
+ * Webhook **receipts** — read-only on purpose.
+ *
+ * An endpoint is registered, edited and deleted in the dashboard, where the signing secret is
+ * shown once and never again. What an SDK consumer needs at 3am is the other half: which
+ * endpoints exist, and what MeterFlow actually sent them. That is this.
+ *
+ * Not to be confused with `meterflow/webhook`, which verifies the signature on a webhook your
+ * server has just received. This reads what we sent; that proves we sent it.
+ */
+export declare class WebhooksResource {
+    private readonly client;
+    constructor(client: MeterFlow);
+    /** Every endpoint registered for the key's project. Never includes a secret. */
+    list(): Promise<WebhookResponse[]>;
+    /**
+     * One endpoint's delivery attempts, newest first: the payload sent, the HTTP status that came
+     * back, how many attempts and when the next retry is due.
+     *
+     * Capped at the most recent 100, and scoped to the key's own environment — a `mf_test_*` key
+     * reads test receipts, a `mf_live_*` key live ones. A webhook belonging to another project
+     * answers 404.
+     */
+    deliveries(webhookId: string): Promise<WebhookDeliveryResponse[]>;
+}
+export {};
+//# sourceMappingURL=webhooks.d.ts.map

package/dist/resources/webhooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../../src/resources/webhooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,eAAe,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,iBAAiB,CAAC,CAAC;AAChE,KAAK,uBAAuB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,yBAAyB,CAAC,CAAC;AAEhF;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,gFAAgF;IAChF,IAAI,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAIlC;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC;CAGlE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meterflow",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Official Node.js SDK for MeterFlow — usage-based billing, credit management, and metering.",
   "license": "MIT",
   "author": "MeterFlow",