meterflow 0.5.1 → 0.6.0

package/README.md

@@ -177,10 +177,10 @@ bal.total_granted;  // "5250.000000"
 bal.total_consumed; // "1705.000000"
 ```
 
-**Transactions** — the full history, newest first, paginated:
+**Transactions** — the customer's full history, newest first, in one response:
 
 ```typescript
-const txns = await client.credits.transactions("customer_123", { page: 1, limit: 50 });
+const txns = await client.credits.transactions("customer_123");
 for (const t of txns) {
   console.log(t.transaction_type, t.amount, t.balance_after, t.description, t.created_at);
 }
@@ -224,6 +224,39 @@ 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`, `min` and `unique_count` read `value` as a measurement, not a quantity to add.
+- **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
@@ -345,6 +378,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 +421,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 +484,10 @@ 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 deduction 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. Needs the threshold set on the webhook; without one it never fires | `customer_id`, `balance`, `threshold`, `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 rolls forward (the renewer; no `subscription.updated` is emitted for a renewal) | `customer_id`, `subscription_id`, `plan_id`, `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` |
 
 For example, a `credit.granted` delivery:
 
@@ -509,6 +557,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 history = await client.credits.transactions("ana");
 const usage = await client.usage.summary("ana");
 ```

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.6.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -245,10 +245,8 @@ var CreditsResource = class {
   balance(customerId) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/balance`);
   }
-  transactions(customerId, query) {
-    return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`, {
-      ...query !== void 0 && { query }
-    });
+  transactions(customerId) {
+    return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`);
   }
 };
 

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.6.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -245,10 +245,8 @@ var CreditsResource = class {
   balance(customerId) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/balance`);
   }
-  transactions(customerId, query) {
-    return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`, {
-      ...query !== void 0 && { query }
-    });
+  transactions(customerId) {
+    return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`);
   }
 };
 

package/dist/index.mjs

@@ -1,5 +1,5 @@
 // package.json
-var version = "0.5.1";
+var version = "0.6.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -209,10 +209,8 @@ var CreditsResource = class {
   balance(customerId) {
     return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/balance`);
   }
-  transactions(customerId, query) {
-    return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`, {
-      ...query !== void 0 && { query }
-    });
+  transactions(customerId) {
+    return this.client.request("GET", `credits/${encodeURIComponent(customerId)}/transactions`);
   }
 };
 

package/dist/resources/credits.d.ts

@@ -10,17 +10,13 @@ export interface GrantOptions {
 export interface DeductOptions {
     idempotencyKey?: string;
 }
-export interface TransactionsQuery {
-    page?: number;
-    limit?: number;
-}
 export declare class CreditsResource {
     private readonly client;
     constructor(client: MeterFlow);
     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[]>;
+    transactions(customerId: string): Promise<CreditTransactionResponse[]>;
 }
 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;AAE5E,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;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,GAAG,OAAO,CAAC,yBAAyB,EAAE,CAAC;CAGvE"}

package/package.json

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