@revstackhq/node 0.0.0-dev-20260226054346

package/dist/src/modules/customers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customers.d.ts","sourceRoot":"","sources":["../../../src/modules/customers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EACL,QAAQ,EACR,sBAAsB,EACtB,oBAAoB,EACpB,UAAU,EACV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,UAAU;gBACjC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;;OAMG;IACG,QAAQ,CAAC,MAAM,EAAE,sBAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAOjE;;;;;OAKG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMhD;;;;;OAKG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAOrE;;;;;;OAMG;IACG,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,QAAQ,CAAC;IAOpB;;;;;OAKG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAKhE"}

package/dist/src/modules/customers.js

@@ -0,0 +1,75 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Client for managing end-user (customer) records.
+ * Provides full CRUD operations on the `app_users` table.
+ *
+ * @example
+ * ```typescript
+ * const customer = await revstack.customers.identify({
+ *   customerId: "user-123",
+ *   email: "john@acme.com",
+ * });
+ * ```
+ */
+export class CustomersClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Identify (upsert) a customer. Creates the customer if not found,
+     * or updates it if a record with the same `customerId` already exists.
+     *
+     * @param params - Customer identification parameters.
+     * @returns The created or updated customer record.
+     */
+    async identify(params) {
+        return this.request("/customers", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    /**
+     * Retrieve a customer by ID.
+     *
+     * @param customerId - The customer's unique identifier.
+     * @returns The customer record.
+     */
+    async get(customerId) {
+        return this.request(`/customers/${customerId}`, {
+            method: "GET",
+        });
+    }
+    /**
+     * List customers with optional pagination.
+     *
+     * @param params - Pagination parameters (limit, offset).
+     * @returns A paginated list of customer records.
+     */
+    async list(params) {
+        return this.request(`/customers${this.buildQuery(params)}`, { method: "GET" });
+    }
+    /**
+     * Update an existing customer's profile.
+     *
+     * @param customerId - The customer's unique identifier.
+     * @param params - Fields to update (email, metadata).
+     * @returns The updated customer record.
+     */
+    async update(customerId, params) {
+        return this.request(`/customers/${customerId}`, {
+            method: "PATCH",
+            body: JSON.stringify(params),
+        });
+    }
+    /**
+     * Delete a customer and all associated data.
+     *
+     * @param customerId - The customer's unique identifier.
+     * @returns Confirmation of deletion.
+     */
+    async delete(customerId) {
+        return this.request(`/customers/${customerId}`, {
+            method: "DELETE",
+        });
+    }
+}

package/dist/src/modules/entitlements.d.ts

@@ -0,0 +1,54 @@
+import { BaseClient } from "@/modules/base";
+import { Entitlement, EntitlementCheckOptions, EntitlementCheckResult } from "@/types";
+/**
+ * Client for checking and querying feature entitlements.
+ * The `check()` method is the core primitive of the SDK — it determines whether
+ * a customer is allowed to use a specific feature based on their plan.
+ *
+ * @example
+ * ```typescript
+ * const { allowed, reason } = await revstack.entitlements.check(
+ *   "usr_abc",
+ *   "api-calls",
+ *   { amount: 10 }
+ * );
+ *
+ * if (!allowed) {
+ *   throw new Error(`Access denied: ${reason}`);
+ * }
+ * ```
+ */
+export declare class EntitlementsClient extends BaseClient {
+    constructor(config: {
+        secretKey: string;
+        baseUrl: string;
+        timeout: number;
+    });
+    /**
+     * Check whether a customer has access to a specific feature.
+     * This is the most critical method in the SDK — it evaluates the customer's
+     * plan, metered usage, and custom entitlement overrides.
+     *
+     * @param customerId - The customer to check.
+     * @param featureId - The entitlement slug or ID.
+     * @param options - Optional check parameters (e.g. requested amount).
+     * @returns The check result with `allowed`, `reason`, and `remainingBalance`.
+     */
+    check(customerId: string, featureId: string, options?: EntitlementCheckOptions): Promise<EntitlementCheckResult>;
+    /**
+     * List all active entitlements for a customer, including limits from
+     * their plan and any custom overrides.
+     *
+     * @param customerId - The customer whose entitlements to list.
+     * @returns Array of entitlement definitions the customer has access to.
+     */
+    list(customerId: string): Promise<Entitlement[]>;
+    /**
+     * Retrieve a single entitlement definition by ID.
+     *
+     * @param entitlementId - The entitlement's unique identifier.
+     * @returns The entitlement definition.
+     */
+    get(entitlementId: string): Promise<Entitlement>;
+}
+//# sourceMappingURL=entitlements.d.ts.map

package/dist/src/modules/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../../../src/modules/entitlements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;;;;;OASG;IACG,KAAK,CACT,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,sBAAsB,CAAC;IAWlC;;;;;;OAMG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAMtD;;;;;OAKG;IACG,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAKvD"}

package/dist/src/modules/entitlements.js

@@ -0,0 +1,67 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Client for checking and querying feature entitlements.
+ * The `check()` method is the core primitive of the SDK — it determines whether
+ * a customer is allowed to use a specific feature based on their plan.
+ *
+ * @example
+ * ```typescript
+ * const { allowed, reason } = await revstack.entitlements.check(
+ *   "usr_abc",
+ *   "api-calls",
+ *   { amount: 10 }
+ * );
+ *
+ * if (!allowed) {
+ *   throw new Error(`Access denied: ${reason}`);
+ * }
+ * ```
+ */
+export class EntitlementsClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Check whether a customer has access to a specific feature.
+     * This is the most critical method in the SDK — it evaluates the customer's
+     * plan, metered usage, and custom entitlement overrides.
+     *
+     * @param customerId - The customer to check.
+     * @param featureId - The entitlement slug or ID.
+     * @param options - Optional check parameters (e.g. requested amount).
+     * @returns The check result with `allowed`, `reason`, and `remainingBalance`.
+     */
+    async check(customerId, featureId, options) {
+        return this.request("/entitlements/check", {
+            method: "POST",
+            body: JSON.stringify({
+                customerId,
+                featureId,
+                requestedAmount: options?.amount || 1,
+            }),
+        });
+    }
+    /**
+     * List all active entitlements for a customer, including limits from
+     * their plan and any custom overrides.
+     *
+     * @param customerId - The customer whose entitlements to list.
+     * @returns Array of entitlement definitions the customer has access to.
+     */
+    async list(customerId) {
+        return this.request(`/entitlements/customer/${customerId}`, {
+            method: "GET",
+        });
+    }
+    /**
+     * Retrieve a single entitlement definition by ID.
+     *
+     * @param entitlementId - The entitlement's unique identifier.
+     * @returns The entitlement definition.
+     */
+    async get(entitlementId) {
+        return this.request(`/entitlements/${entitlementId}`, {
+            method: "GET",
+        });
+    }
+}

package/dist/src/modules/invoices.d.ts

@@ -0,0 +1,38 @@
+import { BaseClient } from "@/modules/base";
+import { Invoice, ListInvoicesParams, PaginatedResponse } from "@/types";
+/**
+ * Read-only client for querying billing invoices.
+ * Used to display billing history to end users. Invoice creation is handled
+ * automatically by the payment pipeline and is not accessible from the SDK.
+ *
+ * @example
+ * ```typescript
+ * // List invoices for a customer's billing history page
+ * const { data: invoices } = await revstack.invoices.list({
+ *   customerId: "usr_abc",
+ *   status: "paid",
+ * });
+ * ```
+ */
+export declare class InvoicesClient extends BaseClient {
+    constructor(config: {
+        secretKey: string;
+        baseUrl: string;
+        timeout: number;
+    });
+    /**
+     * List invoices with optional filters.
+     *
+     * @param params - Filter and pagination parameters.
+     * @returns A paginated list of invoices.
+     */
+    list(params?: ListInvoicesParams): Promise<PaginatedResponse<Invoice>>;
+    /**
+     * Retrieve a single invoice by ID.
+     *
+     * @param invoiceId - The invoice's unique identifier.
+     * @returns The invoice record.
+     */
+    get(invoiceId: string): Promise<Invoice>;
+}
+//# sourceMappingURL=invoices.d.ts.map

package/dist/src/modules/invoices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoices.d.ts","sourceRoot":"","sources":["../../../src/modules/invoices.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEzE;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,UAAU;gBAChC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;OAKG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAO5E;;;;;OAKG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAK/C"}

package/dist/src/modules/invoices.js

@@ -0,0 +1,40 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Read-only client for querying billing invoices.
+ * Used to display billing history to end users. Invoice creation is handled
+ * automatically by the payment pipeline and is not accessible from the SDK.
+ *
+ * @example
+ * ```typescript
+ * // List invoices for a customer's billing history page
+ * const { data: invoices } = await revstack.invoices.list({
+ *   customerId: "usr_abc",
+ *   status: "paid",
+ * });
+ * ```
+ */
+export class InvoicesClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * List invoices with optional filters.
+     *
+     * @param params - Filter and pagination parameters.
+     * @returns A paginated list of invoices.
+     */
+    async list(params) {
+        return this.request(`/invoices${this.buildQuery(params)}`, { method: "GET" });
+    }
+    /**
+     * Retrieve a single invoice by ID.
+     *
+     * @param invoiceId - The invoice's unique identifier.
+     * @returns The invoice record.
+     */
+    async get(invoiceId) {
+        return this.request(`/invoices/${invoiceId}`, {
+            method: "GET",
+        });
+    }
+}

package/dist/src/modules/plans.d.ts

@@ -0,0 +1,40 @@
+import { BaseClient } from "@/modules/base";
+import { Plan, ListPlansParams, PaginatedResponse } from "@/types";
+/**
+ * Read-only client for querying billing plans.
+ * Used by the merchant's frontend to render pricing pages and plan selectors.
+ * Plan mutations are handled via `revstack.admin.plans`.
+ *
+ * @example
+ * ```typescript
+ * // Fetch all public plans for the pricing page
+ * const { data: plans } = await revstack.plans.list({ status: "active" });
+ *
+ * // Get a specific plan with prices and entitlements
+ * const proPlan = await revstack.plans.get("plan_pro");
+ * console.log(proPlan.prices);       // billing intervals
+ * console.log(proPlan.entitlements);  // feature allocations
+ * ```
+ */
+export declare class PlansClient extends BaseClient {
+    constructor(config: {
+        secretKey: string;
+        baseUrl: string;
+        timeout: number;
+    });
+    /**
+     * List plans with optional filters.
+     *
+     * @param params - Filter and pagination parameters.
+     * @returns A paginated list of plans.
+     */
+    list(params?: ListPlansParams): Promise<PaginatedResponse<Plan>>;
+    /**
+     * Retrieve a single plan by ID, including its nested prices and entitlements.
+     *
+     * @param planId - The plan's unique identifier.
+     * @returns The plan with populated `prices[]` and `entitlements[]`.
+     */
+    get(planId: string): Promise<Plan>;
+}
+//# sourceMappingURL=plans.d.ts.map

package/dist/src/modules/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../../../src/modules/plans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEnE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAY,SAAQ,UAAU;gBAC7B,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;OAKG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAOtE;;;;;OAKG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAKzC"}

package/dist/src/modules/plans.js

@@ -0,0 +1,42 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Read-only client for querying billing plans.
+ * Used by the merchant's frontend to render pricing pages and plan selectors.
+ * Plan mutations are handled via `revstack.admin.plans`.
+ *
+ * @example
+ * ```typescript
+ * // Fetch all public plans for the pricing page
+ * const { data: plans } = await revstack.plans.list({ status: "active" });
+ *
+ * // Get a specific plan with prices and entitlements
+ * const proPlan = await revstack.plans.get("plan_pro");
+ * console.log(proPlan.prices);       // billing intervals
+ * console.log(proPlan.entitlements);  // feature allocations
+ * ```
+ */
+export class PlansClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * List plans with optional filters.
+     *
+     * @param params - Filter and pagination parameters.
+     * @returns A paginated list of plans.
+     */
+    async list(params) {
+        return this.request(`/plans${this.buildQuery(params)}`, { method: "GET" });
+    }
+    /**
+     * Retrieve a single plan by ID, including its nested prices and entitlements.
+     *
+     * @param planId - The plan's unique identifier.
+     * @returns The plan with populated `prices[]` and `entitlements[]`.
+     */
+    async get(planId) {
+        return this.request(`/plans/${planId}`, {
+            method: "GET",
+        });
+    }
+}

package/dist/src/modules/subscriptions.d.ts

@@ -0,0 +1,60 @@
+import { BaseClient } from "@/modules/base";
+import { Subscription, CreateSubscriptionParams, ChangePlanParams, ListSubscriptionsParams, PaginatedResponse } from "@/types";
+/**
+ * Client for managing customer subscriptions.
+ * Handles creating, retrieving, canceling, and upgrading/downgrading subscriptions.
+ *
+ * @example
+ * ```typescript
+ * const sub = await revstack.subscriptions.create({
+ *   customerId: "usr_abc",
+ *   planId: "plan_pro",
+ * });
+ * ```
+ */
+export declare class SubscriptionsClient extends BaseClient {
+    constructor(config: {
+        secretKey: string;
+        baseUrl: string;
+        timeout: number;
+    });
+    /**
+     * List subscriptions with optional filters.
+     *
+     * @param params - Filter and pagination parameters.
+     * @returns A paginated list of subscriptions.
+     */
+    list(params?: ListSubscriptionsParams): Promise<PaginatedResponse<Subscription>>;
+    /**
+     * Retrieve a subscription by ID.
+     *
+     * @param subscriptionId - The subscription's unique identifier.
+     * @returns The subscription record.
+     */
+    get(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Create a new subscription for a customer.
+     *
+     * @param params - Subscription creation parameters (customerId, planId).
+     * @returns The newly created subscription.
+     */
+    create(params: CreateSubscriptionParams): Promise<Subscription>;
+    /**
+     * Cancel an active subscription. The subscription will remain active until
+     * the end of the current billing period.
+     *
+     * @param subscriptionId - The subscription to cancel.
+     * @returns The updated subscription with `canceled` status.
+     */
+    cancel(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Change the plan of an existing subscription (upgrade or downgrade).
+     * Proration is handled automatically by the billing engine.
+     *
+     * @param subscriptionId - The subscription to modify.
+     * @param params - The new plan and optional price to switch to.
+     * @returns The updated subscription.
+     */
+    changePlan(subscriptionId: string, params: ChangePlanParams): Promise<Subscription>;
+}
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/src/modules/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../../../src/modules/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EAChB,uBAAuB,EACvB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;GAWG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;OAKG;IACG,IAAI,CACR,MAAM,CAAC,EAAE,uBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,YAAY,CAAC,CAAC;IAO3C;;;;;OAKG;IACG,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAMxD;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC;IAOrE;;;;;;OAMG;IACG,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAO3D;;;;;;;OAOG;IACG,UAAU,CACd,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,YAAY,CAAC;CASzB"}

package/dist/src/modules/subscriptions.js

@@ -0,0 +1,74 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Client for managing customer subscriptions.
+ * Handles creating, retrieving, canceling, and upgrading/downgrading subscriptions.
+ *
+ * @example
+ * ```typescript
+ * const sub = await revstack.subscriptions.create({
+ *   customerId: "usr_abc",
+ *   planId: "plan_pro",
+ * });
+ * ```
+ */
+export class SubscriptionsClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * List subscriptions with optional filters.
+     *
+     * @param params - Filter and pagination parameters.
+     * @returns A paginated list of subscriptions.
+     */
+    async list(params) {
+        return this.request(`/subscriptions${this.buildQuery(params)}`, { method: "GET" });
+    }
+    /**
+     * Retrieve a subscription by ID.
+     *
+     * @param subscriptionId - The subscription's unique identifier.
+     * @returns The subscription record.
+     */
+    async get(subscriptionId) {
+        return this.request(`/subscriptions/${subscriptionId}`, {
+            method: "GET",
+        });
+    }
+    /**
+     * Create a new subscription for a customer.
+     *
+     * @param params - Subscription creation parameters (customerId, planId).
+     * @returns The newly created subscription.
+     */
+    async create(params) {
+        return this.request("/subscriptions", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    /**
+     * Cancel an active subscription. The subscription will remain active until
+     * the end of the current billing period.
+     *
+     * @param subscriptionId - The subscription to cancel.
+     * @returns The updated subscription with `canceled` status.
+     */
+    async cancel(subscriptionId) {
+        return this.request(`/subscriptions/${subscriptionId}/cancel`, { method: "POST" });
+    }
+    /**
+     * Change the plan of an existing subscription (upgrade or downgrade).
+     * Proration is handled automatically by the billing engine.
+     *
+     * @param subscriptionId - The subscription to modify.
+     * @param params - The new plan and optional price to switch to.
+     * @returns The updated subscription.
+     */
+    async changePlan(subscriptionId, params) {
+        return this.request(`/subscriptions/${subscriptionId}/change-plan`, {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+}

package/dist/src/modules/usage.d.ts

@@ -0,0 +1,64 @@
+import { BaseClient } from "@/modules/base";
+import { ReportUsageParams, RevertUsageParams, UsageMeter } from "@/types";
+/**
+ * Client for reporting and querying metered feature usage.
+ * Works in conjunction with {@link EntitlementsClient} — report usage after
+ * a successful entitlement check, and revert it if downstream operations fail.
+ *
+ * @example
+ * ```typescript
+ * // Optimistic usage pattern for AI applications
+ * const { allowed } = await revstack.entitlements.check(userId, "ai-tokens", { amount: 500 });
+ * if (!allowed) throw new Error("Limit exceeded");
+ *
+ * await revstack.usage.report({ customerId: userId, featureId: "ai-tokens", amount: 500 });
+ * try {
+ *   await openai.chat.completions.create({ ... });
+ * } catch {
+ *   await revstack.usage.revert({ customerId: userId, featureId: "ai-tokens", amount: 500 });
+ * }
+ * ```
+ */
+export declare class UsageClient extends BaseClient {
+    constructor(config: {
+        secretKey: string;
+        baseUrl: string;
+        timeout: number;
+    });
+    /**
+     * Report usage of a metered feature. Increments the customer's usage meter.
+     *
+     * @param params - Usage report parameters.
+     * @returns Confirmation of the reported usage.
+     */
+    report(params: ReportUsageParams): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Retrieve all usage meters for a customer (one per metered entitlement).
+     *
+     * @param customerId - The customer whose meters to retrieve.
+     * @returns Array of usage meters with current counts and reset times.
+     */
+    getMeters(customerId: string): Promise<UsageMeter[]>;
+    /**
+     * Retrieve a single usage meter for a specific customer and feature.
+     *
+     * @param customerId - The customer whose meter to retrieve.
+     * @param featureId - The entitlement slug or ID.
+     * @returns The usage meter with current count and reset time.
+     */
+    getMeter(customerId: string, featureId: string): Promise<UsageMeter>;
+    /**
+     * Revert (roll back) previously reported usage. Decrements the customer's
+     * usage meter. Essential for maintaining accurate billing when downstream
+     * operations fail after usage was already recorded.
+     *
+     * @param params - Revert parameters including reason for audit trail.
+     * @returns Confirmation of the reverted usage.
+     */
+    revert(params: RevertUsageParams): Promise<{
+        success: boolean;
+    }>;
+}
+//# sourceMappingURL=usage.d.ts.map

package/dist/src/modules/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/modules/usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,WAAY,SAAQ,UAAU;gBAC7B,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAYtE;;;;;OAKG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAM1D;;;;;;OAMG;IACG,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAO1E;;;;;;;OAOG;IACG,MAAM,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;CAYvE"}

package/dist/src/modules/usage.js

@@ -0,0 +1,83 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Client for reporting and querying metered feature usage.
+ * Works in conjunction with {@link EntitlementsClient} — report usage after
+ * a successful entitlement check, and revert it if downstream operations fail.
+ *
+ * @example
+ * ```typescript
+ * // Optimistic usage pattern for AI applications
+ * const { allowed } = await revstack.entitlements.check(userId, "ai-tokens", { amount: 500 });
+ * if (!allowed) throw new Error("Limit exceeded");
+ *
+ * await revstack.usage.report({ customerId: userId, featureId: "ai-tokens", amount: 500 });
+ * try {
+ *   await openai.chat.completions.create({ ... });
+ * } catch {
+ *   await revstack.usage.revert({ customerId: userId, featureId: "ai-tokens", amount: 500 });
+ * }
+ * ```
+ */
+export class UsageClient extends BaseClient {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Report usage of a metered feature. Increments the customer's usage meter.
+     *
+     * @param params - Usage report parameters.
+     * @returns Confirmation of the reported usage.
+     */
+    async report(params) {
+        return this.request("/usage/report", {
+            method: "POST",
+            idempotencyKey: params.idempotencyKey,
+            body: JSON.stringify({
+                customerId: params.customerId,
+                featureId: params.featureId,
+                amount: params.amount,
+            }),
+        });
+    }
+    /**
+     * Retrieve all usage meters for a customer (one per metered entitlement).
+     *
+     * @param customerId - The customer whose meters to retrieve.
+     * @returns Array of usage meters with current counts and reset times.
+     */
+    async getMeters(customerId) {
+        return this.request(`/usage/meters/${customerId}`, {
+            method: "GET",
+        });
+    }
+    /**
+     * Retrieve a single usage meter for a specific customer and feature.
+     *
+     * @param customerId - The customer whose meter to retrieve.
+     * @param featureId - The entitlement slug or ID.
+     * @returns The usage meter with current count and reset time.
+     */
+    async getMeter(customerId, featureId) {
+        return this.request(`/usage/meters/${customerId}/${featureId}`, { method: "GET" });
+    }
+    /**
+     * Revert (roll back) previously reported usage. Decrements the customer's
+     * usage meter. Essential for maintaining accurate billing when downstream
+     * operations fail after usage was already recorded.
+     *
+     * @param params - Revert parameters including reason for audit trail.
+     * @returns Confirmation of the reverted usage.
+     */
+    async revert(params) {
+        return this.request("/usage/revert", {
+            method: "POST",
+            idempotencyKey: params.idempotencyKey,
+            body: JSON.stringify({
+                customerId: params.customerId,
+                featureId: params.featureId,
+                amount: params.amount,
+                reason: params.reason,
+            }),
+        });
+    }
+}