meterflow 0.4.4 → 0.5.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)
+  - [Entitlements — ask before you act](#entitlements--ask-before-you-act)
 - [Idempotency — safe retries for writes](#idempotency--safe-retries-for-writes)
 - [Automatic retries](#automatic-retries)
 - [Error handling](#error-handling)
@@ -298,6 +299,38 @@ 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.
 
+### 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.
+
+```typescript
+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"
+  return showUpgradePrompt(gate); // gate.used / gate.included / gate.period_end are there for the copy
+}
+
+await generateImage();
+await client.usage.record({ event_name: "images.generated", customer_external_id: "customer_123", value: 1, properties: {} });
+```
+
+- `feature` is a meter's `event_name` (metered — `included`, `used`, `remaining` filled in) or a plan feature key like `"sso"` (boolean).
+- `{ quantity: 5 }` asks "may they do **5** more?" — one call instead of one per item for batch work.
+- A **soft** limit answers `allowed: true` with `reason: "soft_limit_exceeded"` — let it through, nudge the upgrade.
+- A **metered** limit stays allowed while the customer's credits cover the overage; otherwise `insufficient_credits`.
+- `allowed: false` is a normal resolved answer, never an exception. A feature key the project does not know at all is a `NotFoundError` — that is a typo, not a plan.
+- The answer carries `Cache-Control: private, max-age=15`; on hot paths cache it per customer for a few seconds rather than calling on every request.
+
+**All of them at once** — for a settings or pricing screen:
+
+```typescript
+const { entitlements, period_end } = await client.entitlements.get("customer_123");
+// [{ feature: "sso", feature_type: "boolean", allowed: true }, { feature: "images.generated", feature_type: "metered", used: "120", included: 500, remaining: "380", ... }]
+```
+
+Prefer to be told rather than to ask? Subscribe a webhook to `limit.reached` (see below).
+
 ## 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:
@@ -367,7 +400,7 @@ try {
 
 ## Verifying webhooks
 
-MeterFlow notifies your app of activity you'd otherwise poll for — credits granted or deducted, usage recorded, subscriptions created or updated. Every delivery is signed with **HMAC-SHA256** in the `X-MeterFlow-Signature` header, using the webhook's secret — verify before trusting:
+MeterFlow notifies your app of activity you'd otherwise poll for — credits granted or deducted, usage recorded, subscriptions created or updated, a customer reaching a plan limit. Every delivery is signed with **HMAC-SHA256** in the `X-MeterFlow-Signature` header, using the webhook's secret — verify before trusting:
 
 ```typescript
 import express from "express";
@@ -406,6 +439,7 @@ Every delivery is a flat JSON object (`Content-Type: application/json`) with two
 | `credit.deducted` | credits are deducted | `customer_id`, `amount`, `balance_after`, `transaction_id` |
 | `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` |
 
 For example, a `credit.granted` delivery:
 

package/dist/client.d.ts

@@ -2,6 +2,7 @@ import { CreditsResource } from "./resources/credits";
 import { UsageResource } from "./resources/usage";
 import { SubscriptionsResource } from "./resources/subscriptions";
 import { PlansResource } from "./resources/plans";
+import { EntitlementsResource } from "./resources/entitlements";
 export interface MeterFlowOptions {
     apiKey: string;
     baseUrl?: string;
@@ -21,11 +22,13 @@ export declare class MeterFlow {
     private _usage?;
     private _subscriptions?;
     private _plans?;
+    private _entitlements?;
     constructor(options: MeterFlowOptions);
     get credits(): CreditsResource;
     get usage(): UsageResource;
     get subscriptions(): SubscriptionsResource;
     get plans(): PlansResource;
+    get entitlements(): EntitlementsResource;
     /** @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;AAElD,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;gBAEnB,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,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,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"}

package/dist/index.cjs

@@ -35,7 +35,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.4.4";
+var version = "0.5.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -330,6 +330,23 @@ var PlansResource = class {
   }
 };
 
+// src/resources/entitlements.ts
+var EntitlementsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every feature on the customer's plan, with this period's usage. Empty `entitlements` without a subscription. */
+  get(customerId) {
+    return this.client.request("GET", `entitlements/${encodeURIComponent(customerId)}`);
+  }
+  /** May this customer use `feature` (`quantity` more units of it) right now? */
+  check(customerId, feature, opts) {
+    const query = { feature };
+    if (opts?.quantity !== void 0) query["quantity"] = opts.quantity;
+    return this.client.request("GET", `entitlements/${encodeURIComponent(customerId)}/check`, { query });
+  }
+};
+
 // src/client.ts
 var MeterFlow = class {
   options;
@@ -337,6 +354,7 @@ var MeterFlow = class {
   _usage;
   _subscriptions;
   _plans;
+  _entitlements;
   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_");
@@ -363,6 +381,9 @@ var MeterFlow = class {
   get plans() {
     return this._plans ??= new PlansResource(this);
   }
+  get entitlements() {
+    return this._entitlements ??= new EntitlementsResource(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.4.4";
+var version = "0.5.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -330,6 +330,23 @@ var PlansResource = class {
   }
 };
 
+// src/resources/entitlements.ts
+var EntitlementsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every feature on the customer's plan, with this period's usage. Empty `entitlements` without a subscription. */
+  get(customerId) {
+    return this.client.request("GET", `entitlements/${encodeURIComponent(customerId)}`);
+  }
+  /** May this customer use `feature` (`quantity` more units of it) right now? */
+  check(customerId, feature, opts) {
+    const query = { feature };
+    if (opts?.quantity !== void 0) query["quantity"] = opts.quantity;
+    return this.client.request("GET", `entitlements/${encodeURIComponent(customerId)}/check`, { query });
+  }
+};
+
 // src/client.ts
 var MeterFlow = class {
   options;
@@ -337,6 +354,7 @@ var MeterFlow = class {
   _usage;
   _subscriptions;
   _plans;
+  _entitlements;
   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_");
@@ -363,6 +381,9 @@ var MeterFlow = class {
   get plans() {
     return this._plans ??= new PlansResource(this);
   }
+  get entitlements() {
+    return this._entitlements ??= new EntitlementsResource(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.4.4";
+var version = "0.5.0";
 
 // src/errors.ts
 var MeterFlowError = class extends Error {
@@ -294,6 +294,23 @@ var PlansResource = class {
   }
 };
 
+// src/resources/entitlements.ts
+var EntitlementsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Every feature on the customer's plan, with this period's usage. Empty `entitlements` without a subscription. */
+  get(customerId) {
+    return this.client.request("GET", `entitlements/${encodeURIComponent(customerId)}`);
+  }
+  /** May this customer use `feature` (`quantity` more units of it) right now? */
+  check(customerId, feature, opts) {
+    const query = { feature };
+    if (opts?.quantity !== void 0) query["quantity"] = opts.quantity;
+    return this.client.request("GET", `entitlements/${encodeURIComponent(customerId)}/check`, { query });
+  }
+};
+
 // src/client.ts
 var MeterFlow = class {
   options;
@@ -301,6 +318,7 @@ var MeterFlow = class {
   _usage;
   _subscriptions;
   _plans;
+  _entitlements;
   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_");
@@ -327,6 +345,9 @@ var MeterFlow = class {
   get plans() {
     return this._plans ??= new PlansResource(this);
   }
+  get entitlements() {
+    return this._entitlements ??= new EntitlementsResource(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/entitlements.d.ts

@@ -0,0 +1,29 @@
+import type { MeterFlow } from "../client";
+import type { components } from "../types/openapi";
+type EntitlementResponse = components["schemas"]["EntitlementResponse"];
+type EntitlementsResponse = components["schemas"]["EntitlementsResponse"];
+export interface CheckOptions {
+    /** How many more units the app is about to use — "may they do 5 more?". Defaults to 1 on the server. */
+    quantity?: number;
+}
+/**
+ * Ask BEFORE doing the work. `check()` is where a hard limit says no; recording usage afterwards
+ * never blocks, so an app that skips this call gets no enforcement at all — only an honest ledger.
+ *
+ * `allowed: false` is a normal answer, not an error: the promise resolves and `reason` says why
+ * (`no_subscription`, `not_in_plan`, `hard_limit_reached`, `insufficient_credits`). A feature key
+ * the project does not know at all is a 404 → `NotFoundError`, because that is a typo, not a plan.
+ *
+ * Both calls return `Cache-Control: private, max-age=15` — cache per customer for a few seconds
+ * on hot paths rather than calling on every request.
+ */
+export declare class EntitlementsResource {
+    private readonly client;
+    constructor(client: MeterFlow);
+    /** Every feature on the customer's plan, with this period's usage. Empty `entitlements` without a subscription. */
+    get(customerId: string): Promise<EntitlementsResponse>;
+    /** May this customer use `feature` (`quantity` more units of it) right now? */
+    check(customerId: string, feature: string, opts?: CheckOptions): Promise<EntitlementResponse>;
+}
+export {};
+//# sourceMappingURL=entitlements.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../../../src/resources/entitlements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,KAAK,mBAAmB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,qBAAqB,CAAC,CAAC;AACxE,KAAK,oBAAoB,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,sBAAsB,CAAC,CAAC;AAE1E,MAAM,WAAW,YAAY;IAC3B,wGAAwG;IACxG,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAE9C,mHAAmH;IACnH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAItD,+EAA+E;IAC/E,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAK9F"}

package/package.json

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