@revstackhq/node 0.0.0-dev-20260226054346

package/dist/modules/subscriptions.d.ts

@@ -0,0 +1,55 @@
+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 {
+    /**
+     * 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/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;IACjD;;;;;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/modules/subscriptions.js

@@ -0,0 +1,71 @@
+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 {
+    /**
+     * 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/modules/usage.d.ts

@@ -0,0 +1,59 @@
+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 {
+    /**
+     * 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/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;IACzC;;;;;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/modules/usage.js

@@ -0,0 +1,80 @@
+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 {
+    /**
+     * 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,
+            }),
+        });
+    }
+}

package/dist/modules/wallets.d.ts

@@ -0,0 +1,53 @@
+import { BaseClient } from "@/modules/base";
+import { BalanceResponse, GrantBalanceParams, RevokeBalanceParams } from "@/types";
+/**
+ * Client for managing customer wallet balances.
+ * Supports granting credits (bonuses, top-ups) and revoking them (refunds, penalties).
+ *
+ * @example
+ * ```typescript
+ * // Grant a welcome bonus
+ * await revstack.wallets.grantBalance({
+ *   customerId: "usr_abc",
+ *   currency: "USD",
+ *   amount: 10.00,
+ *   description: "Welcome bonus",
+ * });
+ *
+ * // Check remaining balance
+ * const { amount } = await revstack.wallets.getBalance("usr_abc", "USD");
+ * ```
+ */
+export declare class WalletsClient extends BaseClient {
+    /**
+     * Retrieve a customer's balance for a specific currency.
+     *
+     * @param customerId - The customer whose balance to query.
+     * @param currency - ISO 4217 currency code (e.g. `USD`).
+     * @returns The balance response with currency and amount.
+     */
+    getBalance(customerId: string, currency: string): Promise<BalanceResponse>;
+    /**
+     * List all balances across all currencies for a customer.
+     *
+     * @param customerId - The customer whose balances to list.
+     * @returns Array of balance responses (one per currency).
+     */
+    listBalances(customerId: string): Promise<BalanceResponse[]>;
+    /**
+     * Grant (add) credit to a customer's wallet.
+     *
+     * @param params - Grant parameters including amount, currency, and description.
+     * @returns The updated balance after the grant.
+     */
+    grantBalance(params: GrantBalanceParams): Promise<BalanceResponse>;
+    /**
+     * Revoke (deduct) credit from a customer's wallet.
+     * Used for manual deductions, penalties, or credit refunds.
+     *
+     * @param params - Revoke parameters including amount, currency, and audit reason.
+     * @returns The updated balance after the deduction.
+     */
+    revokeBalance(params: RevokeBalanceParams): Promise<BalanceResponse>;
+}
+//# sourceMappingURL=wallets.d.ts.map

package/dist/modules/wallets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallets.d.ts","sourceRoot":"","sources":["../../src/modules/wallets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C;;;;;;OAMG;IACG,UAAU,CACd,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,eAAe,CAAC;IAM3B;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAMlE;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAOxE;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;CAM3E"}

package/dist/modules/wallets.js

@@ -0,0 +1,69 @@
+import { BaseClient } from "@/modules/base";
+/**
+ * Client for managing customer wallet balances.
+ * Supports granting credits (bonuses, top-ups) and revoking them (refunds, penalties).
+ *
+ * @example
+ * ```typescript
+ * // Grant a welcome bonus
+ * await revstack.wallets.grantBalance({
+ *   customerId: "usr_abc",
+ *   currency: "USD",
+ *   amount: 10.00,
+ *   description: "Welcome bonus",
+ * });
+ *
+ * // Check remaining balance
+ * const { amount } = await revstack.wallets.getBalance("usr_abc", "USD");
+ * ```
+ */
+export class WalletsClient extends BaseClient {
+    /**
+     * Retrieve a customer's balance for a specific currency.
+     *
+     * @param customerId - The customer whose balance to query.
+     * @param currency - ISO 4217 currency code (e.g. `USD`).
+     * @returns The balance response with currency and amount.
+     */
+    async getBalance(customerId, currency) {
+        return this.request(`/wallets/${customerId}/${currency}`, {
+            method: "GET",
+        });
+    }
+    /**
+     * List all balances across all currencies for a customer.
+     *
+     * @param customerId - The customer whose balances to list.
+     * @returns Array of balance responses (one per currency).
+     */
+    async listBalances(customerId) {
+        return this.request(`/wallets/${customerId}`, {
+            method: "GET",
+        });
+    }
+    /**
+     * Grant (add) credit to a customer's wallet.
+     *
+     * @param params - Grant parameters including amount, currency, and description.
+     * @returns The updated balance after the grant.
+     */
+    async grantBalance(params) {
+        return this.request("/wallets/grant", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    /**
+     * Revoke (deduct) credit from a customer's wallet.
+     * Used for manual deductions, penalties, or credit refunds.
+     *
+     * @param params - Revoke parameters including amount, currency, and audit reason.
+     * @returns The updated balance after the deduction.
+     */
+    async revokeBalance(params) {
+        return this.request("/wallets/revoke", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+}

package/dist/modules/webhooks.d.ts

@@ -0,0 +1,51 @@
+import type { WebhookEvent } from "@/types";
+/**
+ * Client for verifying inbound webhooks from Revstack Cloud.
+ * Uses HMAC-SHA256 with constant-time comparison to prevent timing attacks,
+ * plus timestamp validation for replay protection.
+ *
+ * @example
+ * ```typescript
+ * // Express.js webhook handler
+ * app.post("/webhooks/revstack", express.raw({ type: "application/json" }), (req, res) => {
+ *   try {
+ *     const event = revstack.webhooks.constructEvent(
+ *       req.body,
+ *       req.headers["revstack-signature"] as string,
+ *       process.env.REVSTACK_WEBHOOK_SECRET!
+ *     );
+ *     console.log(`Received event: ${event.type}`);
+ *     res.sendStatus(200);
+ *   } catch (error) {
+ *     if (error instanceof SignatureVerificationError) {
+ *       res.status(400).send("Invalid signature");
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare class WebhooksClient {
+    /**
+     * Verify the signature of an incoming webhook and parse the event payload.
+     *
+     * @param payload - Raw request body (`Buffer` or `string`). **Must NOT be parsed JSON.**
+     * @param signature - Value of the `revstack-signature` HTTP header.
+     * @param secret - Webhook signing secret (from the Revstack Dashboard).
+     * @param tolerance - Maximum age of the webhook in seconds. Defaults to `300` (5 min). Set to `0` to disable replay protection.
+     * @returns The verified and parsed webhook event.
+     *
+     * @throws {SignatureVerificationError} If the signature is invalid, the header is malformed, or the timestamp exceeds the tolerance.
+     */
+    constructEvent(payload: string | Buffer, signature: string, secret: string, tolerance?: number): WebhookEvent;
+    /**
+     * Parse the `revstack-signature` header into its component parts.
+     *
+     * @param header - Raw header value in the format `t=<timestamp>,v1=<signature>`.
+     * @returns Parsed timestamp and v1 signature.
+     *
+     * @throws {SignatureVerificationError} If the header format is invalid.
+     * @internal
+     */
+    private parseSignatureHeader;
+}
+//# sourceMappingURL=webhooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/modules/webhooks.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,cAAc;IACzB;;;;;;;;;;OAUG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,MAAkC,GAC5C,YAAY;IAoCf;;;;;;;;OAQG;IACH,OAAO,CAAC,oBAAoB;CAsB7B"}

package/dist/modules/webhooks.js

@@ -0,0 +1,90 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { SignatureVerificationError } from "@/errors";
+/** Default maximum age for webhook timestamps (5 minutes). */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/**
+ * Client for verifying inbound webhooks from Revstack Cloud.
+ * Uses HMAC-SHA256 with constant-time comparison to prevent timing attacks,
+ * plus timestamp validation for replay protection.
+ *
+ * @example
+ * ```typescript
+ * // Express.js webhook handler
+ * app.post("/webhooks/revstack", express.raw({ type: "application/json" }), (req, res) => {
+ *   try {
+ *     const event = revstack.webhooks.constructEvent(
+ *       req.body,
+ *       req.headers["revstack-signature"] as string,
+ *       process.env.REVSTACK_WEBHOOK_SECRET!
+ *     );
+ *     console.log(`Received event: ${event.type}`);
+ *     res.sendStatus(200);
+ *   } catch (error) {
+ *     if (error instanceof SignatureVerificationError) {
+ *       res.status(400).send("Invalid signature");
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export class WebhooksClient {
+    /**
+     * Verify the signature of an incoming webhook and parse the event payload.
+     *
+     * @param payload - Raw request body (`Buffer` or `string`). **Must NOT be parsed JSON.**
+     * @param signature - Value of the `revstack-signature` HTTP header.
+     * @param secret - Webhook signing secret (from the Revstack Dashboard).
+     * @param tolerance - Maximum age of the webhook in seconds. Defaults to `300` (5 min). Set to `0` to disable replay protection.
+     * @returns The verified and parsed webhook event.
+     *
+     * @throws {SignatureVerificationError} If the signature is invalid, the header is malformed, or the timestamp exceeds the tolerance.
+     */
+    constructEvent(payload, signature, secret, tolerance = DEFAULT_TOLERANCE_SECONDS) {
+        const rawBody = typeof payload === "string" ? payload : payload.toString("utf8");
+        const parts = this.parseSignatureHeader(signature);
+        // Compute expected HMAC-SHA256 signature
+        const expectedSignature = createHmac("sha256", secret)
+            .update(`${parts.timestamp}.${rawBody}`)
+            .digest("hex");
+        // Constant-time comparison to prevent timing attacks
+        const expectedBuffer = Buffer.from(expectedSignature, "utf8");
+        const receivedBuffer = Buffer.from(parts.v1, "utf8");
+        if (expectedBuffer.length !== receivedBuffer.length ||
+            !timingSafeEqual(expectedBuffer, receivedBuffer)) {
+            throw new SignatureVerificationError("Webhook signature does not match the expected signature");
+        }
+        // Replay protection: reject stale timestamps
+        if (tolerance > 0) {
+            const timestampAge = Math.floor(Date.now() / 1000) - parts.timestamp;
+            if (timestampAge > tolerance) {
+                throw new SignatureVerificationError(`Webhook timestamp too old (${timestampAge}s > ${tolerance}s tolerance)`);
+            }
+        }
+        return JSON.parse(rawBody);
+    }
+    /**
+     * Parse the `revstack-signature` header into its component parts.
+     *
+     * @param header - Raw header value in the format `t=<timestamp>,v1=<signature>`.
+     * @returns Parsed timestamp and v1 signature.
+     *
+     * @throws {SignatureVerificationError} If the header format is invalid.
+     * @internal
+     */
+    parseSignatureHeader(header) {
+        const pairs = header.split(",");
+        let timestamp = 0;
+        let v1 = "";
+        for (const pair of pairs) {
+            const [key, value] = pair.trim().split("=");
+            if (key === "t")
+                timestamp = parseInt(value, 10);
+            if (key === "v1")
+                v1 = value;
+        }
+        if (!timestamp || !v1) {
+            throw new SignatureVerificationError("Invalid signature header format. Expected: t=<timestamp>,v1=<signature>");
+        }
+        return { timestamp, v1 };
+    }
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @module @revstackhq/node/errors
+ * @description Typed error hierarchy for the Revstack SDK. All errors thrown by the
+ * SDK extend {@link RevstackError}, enabling precise error handling with `instanceof`.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError, RevstackAPIError } from "@revstackhq/node";
+ *
+ * try {
+ *   await revstack.entitlements.check(userId, "api-calls");
+ * } catch (error) {
+ *   if (error instanceof RateLimitError) {
+ *     console.log(`Rate limited. Retry after ${error.retryAfter}s`);
+ *   } else if (error instanceof RevstackAPIError) {
+ *     console.log(`API error ${error.status}: ${error.code}`);
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Base class for all Revstack SDK errors.
+ * Use `instanceof RevstackError` to catch any SDK-originated error.
+ */
+export declare class RevstackError extends Error {
+    constructor(message: string);
+}
+/** Shape of the JSON error body returned by the Revstack API. */
+export interface APIErrorResponse {
+    /** Human-readable error message. */
+    message?: string;
+    /** Machine-readable error code (e.g. `INSUFFICIENT_BALANCE`). */
+    code?: string;
+    /** Unique request identifier for debugging and support tickets. */
+    requestId?: string;
+    /** Seconds to wait before retrying (for 429 responses). */
+    retryAfter?: number;
+    /** List of conflicts in case of a 409 response */
+    conflicts?: any[];
+}
+/**
+ * Thrown when the Revstack API returns a non-2xx HTTP response.
+ * Contains structured fields for programmatic error handling.
+ */
+export declare class RevstackAPIError extends RevstackError {
+    /** HTTP status code (e.g. `400`, `401`, `404`, `500`). */
+    readonly status: number;
+    /** Machine-readable error code (e.g. `INSUFFICIENT_BALANCE`, `NOT_FOUND`). */
+    readonly code: string;
+    /** Unique request ID for tracing. Include this in support tickets. */
+    readonly requestId?: string;
+    constructor(message: string, status: number, code: string, requestId?: string);
+}
+/**
+ * Thrown when the API returns HTTP 429 (Too Many Requests).
+ * The `retryAfter` field indicates how long to wait before retrying.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await revstack.usage.report(params);
+ * } catch (error) {
+ *   if (error instanceof RateLimitError) {
+ *     await sleep(error.retryAfter * 1000);
+ *     await revstack.usage.report(params); // retry
+ *   }
+ * }
+ * ```
+ */
+export declare class RateLimitError extends RevstackAPIError {
+    /** Number of seconds to wait before retrying the request. */
+    readonly retryAfter: number;
+    constructor(message: string, retryAfter: number, requestId?: string);
+}
+/**
+ * Thrown when webhook signature verification fails.
+ * This indicates the webhook payload was tampered with, the signing secret is wrong,
+ * or the webhook timestamp has expired (replay protection).
+ */
+export declare class SignatureVerificationError extends RevstackError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the system sync endpoint detects a conflict (HTTP 409).
+ */
+export declare class SyncConflictError extends RevstackAPIError {
+    /** The conflicts discovered during sync attempts. */
+    readonly conflicts: any[];
+    constructor(message: string, conflicts: any[], requestId?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;GAGG;AACH,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,EAAE,MAAM;CAI5B;AAID,iEAAiE;AACjE,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,aAAa;IACjD,0DAA0D;IAC1D,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,8EAA8E;IAC9E,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;gBAGjC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,SAAS,CAAC,EAAE,MAAM;CAQrB;AAID;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,cAAe,SAAQ,gBAAgB;IAClD,6DAA6D;IAC7D,SAAgB,UAAU,EAAE,MAAM,CAAC;gBAEvB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAKpE;AAID;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,aAAa;gBAC/C,OAAO,GAAE,MAAgD;CAItE;AAID;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;IACrD,qDAAqD;IACrD,SAAgB,SAAS,EAAE,GAAG,EAAE,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM;CAKlE"}