@revstackhq/node 0.0.0-dev-20260226054346

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

@@ -0,0 +1,58 @@
+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 {
+    constructor(config: {
+        secretKey: string;
+        baseUrl: string;
+        timeout: number;
+    });
+    /**
+     * 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/src/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;gBAC/B,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAI3E;;;;;;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/src/modules/wallets.js

@@ -0,0 +1,72 @@
+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 {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * 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/src/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/src/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/src/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 };
+    }
+}