@revstackhq/node 0.0.0-dev-20260226054346

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Revstack Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @revstackhq/node
+
+The official Node.js / TypeScript server SDK for [Revstack](https://revstack.dev) — billing infrastructure for SaaS.
+
+Provides a single `Revstack` client with two namespaces:
+
+- **Data Plane** (`revstack.*`) — Daily backend operations: entitlement checks, usage reporting, subscriptions, customers, wallets, plans, invoices, and webhook verification.
+- **Control Plane** (`revstack.admin.*`) — Infrastructure management: plan CRUD, entitlement CRUD, integrations, and environments.
+
+## Installation
+
+```bash
+npm install @revstackhq/node
+```
+
+## Quick Start
+
+```typescript
+import { Revstack } from "@revstackhq/node";
+
+const revstack = new Revstack({
+  secretKey: process.env.REVSTACK_SECRET_KEY!,
+});
+```
+
+### Check Feature Access
+
+```typescript
+const { allowed, limit, usage } = await revstack.entitlements.check(
+  "cus_abc123",
+  "api-calls",
+);
+
+if (!allowed) {
+  return res.status(403).json({ error: "Upgrade required" });
+}
+```
+
+### Report Usage
+
+```typescript
+await revstack.usage.report({
+  customer_id: "cus_abc123",
+  feature_id: "api-calls",
+  delta: 1,
+});
+```
+
+### Manage Subscriptions
+
+```typescript
+// Create a subscription
+const sub = await revstack.subscriptions.create({
+  customer_id: "cus_abc123",
+  plan_id: "plan_pro",
+});
+
+// Change plan
+await revstack.subscriptions.changePlan(sub.id, {
+  plan_id: "plan_enterprise",
+});
+```
+
+### Verify Webhooks
+
+```typescript
+const event = revstack.webhooks.constructEvent(
+  requestBody,
+  signatureHeader,
+  webhookSecret,
+);
+```
+
+## API Reference
+
+### Data Plane Modules
+
+| Module          | Description                                 |
+| --------------- | ------------------------------------------- |
+| `customers`     | Create, update, and query customer records  |
+| `subscriptions` | Create, cancel, and manage subscriptions    |
+| `entitlements`  | Check feature access and query entitlements |
+| `usage`         | Report and query metered feature usage      |
+| `wallets`       | Manage customer wallet balances             |
+| `webhooks`      | Verify inbound webhook signatures           |
+| `plans`         | Query billing plans (read-only)             |
+| `invoices`      | Query billing invoices (read-only)          |
+
+### Control Plane (`admin`)
+
+| Module               | Description                          |
+| -------------------- | ------------------------------------ |
+| `admin.plans`        | CRUD operations for billing plans    |
+| `admin.entitlements` | CRUD operations for entitlements     |
+| `admin.integrations` | Manage payment provider integrations |
+| `admin.environments` | Manage deployment environments       |
+
+### Error Hierarchy
+
+The SDK provides a structured error hierarchy for precise error handling:
+
+```typescript
+import { Revstack, RateLimitError, RevstackAPIError } from "@revstackhq/node";
+
+try {
+  await revstack.entitlements.check("cus_abc", "api-calls");
+} catch (error) {
+  if (error instanceof RateLimitError) {
+    // Retry after error.retryAfter seconds
+  } else if (error instanceof RevstackAPIError) {
+    // API returned a non-2xx status
+    console.error(error.status, error.message);
+  }
+}
+```
+
+| Error                        | Description                                 |
+| ---------------------------- | ------------------------------------------- |
+| `RevstackError`              | Base error class for all SDK errors         |
+| `RevstackAPIError`           | API returned a non-2xx response             |
+| `RateLimitError`             | Rate limit exceeded (includes `retryAfter`) |
+| `SignatureVerificationError` | Webhook signature verification failed       |
+
+### Constructor Options
+
+```typescript
+new Revstack({
+  secretKey: "sk_live_...", // Required — your Revstack Secret Key
+  baseUrl: "https://...", // Optional — API base URL (default: https://app.revstack.dev/api/v1)
+  timeout: 10000, // Optional — request timeout in ms (default: 10000)
+});
+```
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @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 (for 409 sync responses). */
+    conflicts?: SyncConflict[];
+}
+/**
+ * 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);
+}
+/** Describes a single field-level conflict detected during a sync operation. */
+export interface SyncConflict {
+    /** The type of resource that has a conflict. */
+    resource: string;
+    /** The slug (natural key) of the conflicting resource. */
+    slug: string;
+    /** The field that has a conflicting value. */
+    field: string;
+    /** The value from the sync config. */
+    expected: unknown;
+    /** The current value in the database. */
+    actual: unknown;
+}
+/**
+ * Thrown when `admin.system.sync()` detects a conflict (HTTP 409).
+ * This means the remote state has drifted from the expected state.
+ * Inspect the `conflicts` array to understand what changed.
+ */
+export declare class SyncConflictError extends RevstackAPIError {
+    /** Detailed list of field-level conflicts between local config and remote state. */
+    readonly conflicts: SyncConflict[];
+    constructor(message: string, conflicts: SyncConflict[], requestId?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/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,YAAY,EAAE,CAAC;CAC5B;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,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,gBAAgB;IACrD,oFAAoF;IACpF,SAAgB,SAAS,EAAE,YAAY,EAAE,CAAC;gBAE9B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM;CAK3E"}

package/dist/errors.js

@@ -0,0 +1,102 @@
+/**
+ * @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 Error ──────────────────────────────────────────────
+/**
+ * Base class for all Revstack SDK errors.
+ * Use `instanceof RevstackError` to catch any SDK-originated error.
+ */
+export class RevstackError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RevstackError";
+    }
+}
+/**
+ * Thrown when the Revstack API returns a non-2xx HTTP response.
+ * Contains structured fields for programmatic error handling.
+ */
+export class RevstackAPIError extends RevstackError {
+    /** HTTP status code (e.g. `400`, `401`, `404`, `500`). */
+    status;
+    /** Machine-readable error code (e.g. `INSUFFICIENT_BALANCE`, `NOT_FOUND`). */
+    code;
+    /** Unique request ID for tracing. Include this in support tickets. */
+    requestId;
+    constructor(message, status, code, requestId) {
+        super(message);
+        this.name = "RevstackAPIError";
+        this.status = status;
+        this.code = code;
+        this.requestId = requestId;
+    }
+}
+// ─── Rate Limit ──────────────────────────────────────────────
+/**
+ * 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 class RateLimitError extends RevstackAPIError {
+    /** Number of seconds to wait before retrying the request. */
+    retryAfter;
+    constructor(message, retryAfter, requestId) {
+        super(message, 429, "RATE_LIMIT_EXCEEDED", requestId);
+        this.name = "RateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+// ─── Webhook Signature ──────────────────────────────────────
+/**
+ * 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 class SignatureVerificationError extends RevstackError {
+    constructor(message = "Webhook signature verification failed") {
+        super(message);
+        this.name = "SignatureVerificationError";
+    }
+}
+/**
+ * Thrown when `admin.system.sync()` detects a conflict (HTTP 409).
+ * This means the remote state has drifted from the expected state.
+ * Inspect the `conflicts` array to understand what changed.
+ */
+export class SyncConflictError extends RevstackAPIError {
+    /** Detailed list of field-level conflicts between local config and remote state. */
+    conflicts;
+    constructor(message, conflicts, requestId) {
+        super(message, 409, "SYNC_CONFLICT", requestId);
+        this.name = "SyncConflictError";
+        this.conflicts = conflicts;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module @revstackhq/node
+ * @description Official Node.js SDK for Revstack — billing infrastructure for SaaS.
+ *
+ * The SDK provides two namespaces:
+ * - **Data Plane** (`revstack.*`) — Daily backend operations: entitlement checks, usage reporting, subscriptions.
+ * - **Control Plane** (`revstack.admin.*`) — Infrastructure management: plan CRUD, Billing as Code sync.
+ *
+ * @example
+ * ```typescript
+ * import { Revstack, RateLimitError } from "@revstackhq/node";
+ *
+ * const revstack = new Revstack({ secretKey: "sk_live_..." });
+ *
+ * // Data Plane: check if a customer can use a feature
+ * const { allowed } = await revstack.entitlements.check("usr_abc", "api-calls");
+ *
+ * // Control Plane: sync billing config from code
+ * await revstack.admin.system.sync({ plans: [...], entitlements: [...] });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { RevstackOptions } from "@/types";
+import { EntitlementsClient } from "@/modules/entitlements";
+import { WalletsClient } from "@/modules/wallets";
+import { CustomersClient } from "@/modules/customers";
+import { UsageClient } from "@/modules/usage";
+import { SubscriptionsClient } from "@/modules/subscriptions";
+import { PlansClient } from "@/modules/plans";
+import { InvoicesClient } from "@/modules/invoices";
+import { WebhooksClient } from "@/modules/webhooks";
+import { AdminClient } from "@/modules/admin";
+/**
+ * Main SDK client. Initialize with your secret key to access all modules.
+ *
+ * @example
+ * ```typescript
+ * const revstack = new Revstack({
+ *   secretKey: process.env.REVSTACK_SECRET_KEY!,
+ * });
+ * ```
+ */
+export declare class Revstack {
+    /** Manage end-user (customer) records. */
+    readonly customers: CustomersClient;
+    /** Create, cancel, and manage subscriptions. */
+    readonly subscriptions: SubscriptionsClient;
+    /** Check feature access and query entitlements. */
+    readonly entitlements: EntitlementsClient;
+    /** Report and query metered feature usage. */
+    readonly usage: UsageClient;
+    /** Manage customer wallet balances. */
+    readonly wallets: WalletsClient;
+    /** Verify inbound webhook signatures. */
+    readonly webhooks: WebhooksClient;
+    /** Query billing plans (read-only). */
+    readonly plans: PlansClient;
+    /** Query billing invoices (read-only). */
+    readonly invoices: InvoicesClient;
+    /** Administrative operations for plans, entitlements, integrations, and environments. */
+    readonly admin: AdminClient;
+    private readonly config;
+    /**
+     * Create a new Revstack SDK instance.
+     *
+     * @param options - Configuration options including the secret API key.
+     * @throws {Error} If `secretKey` is missing.
+     */
+    constructor(options: RevstackOptions);
+}
+export { RevstackError, RevstackAPIError, RateLimitError, SignatureVerificationError, SyncConflictError, } from "@/errors";
+export type { SyncConflict } from "@/errors";
+export type { RevstackOptions, Customer, IdentifyCustomerParams, UpdateCustomerParams, Subscription, CreateSubscriptionParams, ChangePlanParams, ListSubscriptionsParams, Entitlement, EntitlementCheckOptions, EntitlementCheckResult, UsageMeter, ReportUsageParams, RevertUsageParams, BalanceResponse, GrantBalanceParams, RevokeBalanceParams, Plan, Price, PlanEntitlement, ListPlansParams, Invoice, ListInvoicesParams, WebhookEvent, ListParams, PaginatedResponse, CreatePlanParams, UpdatePlanParams, UpsertPlanParams, UpsertPriceInput, UpsertPlanEntitlementInput, CreateEntitlementParams, UpdateEntitlementParams, UpsertEntitlementParams, Integration, CreateIntegrationParams, UpdateIntegrationParams, ProviderEvent, IntegrationMetric, ListIntegrationsParams, ListProviderEventsParams, ListMetricsParams, Environment, CreateEnvironmentParams, UpdateEnvironmentParams, SyncConfig, SyncPreview, SyncChange, SyncResult, } from "@/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IAGnB,0CAA0C;IAC1C,SAAgB,SAAS,EAAE,eAAe,CAAC;IAC3C,gDAAgD;IAChD,SAAgB,aAAa,EAAE,mBAAmB,CAAC;IACnD,mDAAmD;IACnD,SAAgB,YAAY,EAAE,kBAAkB,CAAC;IACjD,8CAA8C;IAC9C,SAAgB,KAAK,EAAE,WAAW,CAAC;IACnC,uCAAuC;IACvC,SAAgB,OAAO,EAAE,aAAa,CAAC;IACvC,yCAAyC;IACzC,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,uCAAuC;IACvC,SAAgB,KAAK,EAAE,WAAW,CAAC;IACnC,0CAA0C;IAC1C,SAAgB,QAAQ,EAAE,cAAc,CAAC;IAIzC,yFAAyF;IACzF,SAAgB,KAAK,EAAE,WAAW,CAAC;IAEnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAIrB;IAEF;;;;;OAKG;gBACS,OAAO,EAAE,eAAe;CA0BrC;AAGD,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,UAAU,CAAC;AAElB,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAG7C,YAAY,EACV,eAAe,EACf,QAAQ,EACR,sBAAsB,EACtB,oBAAoB,EACpB,YAAY,EACZ,wBAAwB,EACxB,gBAAgB,EAChB,uBAAuB,EACvB,WAAW,EACX,uBAAuB,EACvB,sBAAsB,EACtB,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,IAAI,EACJ,KAAK,EACL,eAAe,EACf,eAAe,EACf,OAAO,EACP,kBAAkB,EAClB,YAAY,EACZ,UAAU,EACV,iBAAiB,EAGjB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,WAAW,EACX,uBAAuB,EACvB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,EACX,uBAAuB,EACvB,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,94 @@
+/**
+ * @module @revstackhq/node
+ * @description Official Node.js SDK for Revstack — billing infrastructure for SaaS.
+ *
+ * The SDK provides two namespaces:
+ * - **Data Plane** (`revstack.*`) — Daily backend operations: entitlement checks, usage reporting, subscriptions.
+ * - **Control Plane** (`revstack.admin.*`) — Infrastructure management: plan CRUD, Billing as Code sync.
+ *
+ * @example
+ * ```typescript
+ * import { Revstack, RateLimitError } from "@revstackhq/node";
+ *
+ * const revstack = new Revstack({ secretKey: "sk_live_..." });
+ *
+ * // Data Plane: check if a customer can use a feature
+ * const { allowed } = await revstack.entitlements.check("usr_abc", "api-calls");
+ *
+ * // Control Plane: sync billing config from code
+ * await revstack.admin.system.sync({ plans: [...], entitlements: [...] });
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { EntitlementsClient } from "@/modules/entitlements";
+import { WalletsClient } from "@/modules/wallets";
+import { CustomersClient } from "@/modules/customers";
+import { UsageClient } from "@/modules/usage";
+import { SubscriptionsClient } from "@/modules/subscriptions";
+import { PlansClient } from "@/modules/plans";
+import { InvoicesClient } from "@/modules/invoices";
+import { WebhooksClient } from "@/modules/webhooks";
+import { AdminClient } from "@/modules/admin";
+/**
+ * Main SDK client. Initialize with your secret key to access all modules.
+ *
+ * @example
+ * ```typescript
+ * const revstack = new Revstack({
+ *   secretKey: process.env.REVSTACK_SECRET_KEY!,
+ * });
+ * ```
+ */
+export class Revstack {
+    // ─── Data Plane (S2S) ──────────────────────────
+    /** Manage end-user (customer) records. */
+    customers;
+    /** Create, cancel, and manage subscriptions. */
+    subscriptions;
+    /** Check feature access and query entitlements. */
+    entitlements;
+    /** Report and query metered feature usage. */
+    usage;
+    /** Manage customer wallet balances. */
+    wallets;
+    /** Verify inbound webhook signatures. */
+    webhooks;
+    /** Query billing plans (read-only). */
+    plans;
+    /** Query billing invoices (read-only). */
+    invoices;
+    // ─── Control Plane (CLI / Admin) ───────────────
+    /** Administrative operations for plans, entitlements, integrations, and environments. */
+    admin;
+    config;
+    /**
+     * Create a new Revstack SDK instance.
+     *
+     * @param options - Configuration options including the secret API key.
+     * @throws {Error} If `secretKey` is missing.
+     */
+    constructor(options) {
+        if (!options.secretKey) {
+            throw new Error("Revstack: Secret Key is required. Get yours at https://app.revstack.dev");
+        }
+        this.config = {
+            secretKey: options.secretKey,
+            baseUrl: options.baseUrl || "https://app.revstack.dev/api/v1",
+            timeout: options.timeout || 10000,
+        };
+        // Data Plane
+        this.customers = new CustomersClient(this.config);
+        this.subscriptions = new SubscriptionsClient(this.config);
+        this.entitlements = new EntitlementsClient(this.config);
+        this.usage = new UsageClient(this.config);
+        this.wallets = new WalletsClient(this.config);
+        this.webhooks = new WebhooksClient();
+        this.plans = new PlansClient(this.config);
+        this.invoices = new InvoicesClient(this.config);
+        // Control Plane
+        this.admin = new AdminClient(this.config);
+    }
+}
+// ─── Errors ──────────────────────────────────────
+export { RevstackError, RevstackAPIError, RateLimitError, SignatureVerificationError, SyncConflictError, } from "@/errors";

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

@@ -0,0 +1,68 @@
+import { BaseClient } from "@/modules/base";
+import { Entitlement, CreateEntitlementParams, UpdateEntitlementParams, UpsertEntitlementParams, ListParams, PaginatedResponse } from "@/types";
+/**
+ * Admin client for managing entitlement definitions (CRUD + upsert).
+ * Entitlements define the features and capabilities that can be gated behind plans.
+ *
+ * The `upsert()` method is idempotent by `slug`, making it safe for repeated
+ * CLI deployments without creating duplicates.
+ *
+ * @example
+ * ```typescript
+ * await revstack.admin.entitlements.upsert({
+ *   slug: "api-calls",
+ *   name: "API Calls",
+ *   type: "metered",
+ *   unitType: "count",
+ * });
+ * ```
+ */
+export declare class AdminEntitlementsClient extends BaseClient {
+    /**
+     * List all entitlement definitions with optional pagination.
+     *
+     * @param params - Pagination parameters.
+     * @returns A paginated list of entitlements.
+     */
+    list(params?: ListParams): Promise<PaginatedResponse<Entitlement>>;
+    /**
+     * Retrieve a single entitlement definition by ID.
+     *
+     * @param entitlementId - The entitlement's unique identifier.
+     * @returns The entitlement definition.
+     */
+    get(entitlementId: string): Promise<Entitlement>;
+    /**
+     * Create a new entitlement definition.
+     *
+     * @param params - Entitlement creation parameters.
+     * @returns The newly created entitlement.
+     */
+    create(params: CreateEntitlementParams): Promise<Entitlement>;
+    /**
+     * Partially update an existing entitlement definition.
+     *
+     * @param entitlementId - The entitlement's unique identifier.
+     * @param params - Fields to update.
+     * @returns The updated entitlement.
+     */
+    update(entitlementId: string, params: UpdateEntitlementParams): Promise<Entitlement>;
+    /**
+     * Delete an entitlement definition. Fails if any active plans reference it.
+     *
+     * @param entitlementId - The entitlement's unique identifier.
+     * @returns Confirmation of deletion.
+     */
+    delete(entitlementId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Idempotently create or update an entitlement by its `slug`.
+     * If an entitlement with the given slug exists, it is updated; otherwise, it is created.
+     *
+     * @param params - Full entitlement state.
+     * @returns The created or updated entitlement.
+     */
+    upsert(params: UpsertEntitlementParams): Promise<Entitlement>;
+}
+//# sourceMappingURL=entitlements.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../../../src/modules/admin/entitlements.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EACL,WAAW,EACX,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,UAAU,EACV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,uBAAwB,SAAQ,UAAU;IACrD;;;;;OAKG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAOxE;;;;;OAKG;IACG,GAAG,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAMtD;;;;;OAKG;IACG,MAAM,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOnE;;;;;;OAMG;IACG,MAAM,CACV,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,uBAAuB,GAC9B,OAAO,CAAC,WAAW,CAAC;IAOvB;;;;;OAKG;IACG,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAOlE;;;;;;OAMG;IACG,MAAM,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC;CAMpE"}