revenuecat-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 despia-native
+
+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,213 @@
+# revenuecat-server
+
+A lightweight server-side SDK for the [RevenueCat v2 REST API](https://www.revenuecat.com/docs/api-v2). Makes entitlement checks and offering/package management simple — so you can follow security best practices without wrestling with webhooks or complex API calls.
+
+**Works with:** Node.js 18+, Deno, Bun — and any backend (Express, Fastify, Hono, Next.js API routes, Lambda, etc.). Zero dependencies.
+
+> **Server-side only.** API keys must **never** be on the frontend. Use this SDK in your backend only. Build secure API proxies: your frontend calls *your* backend; your backend uses this SDK to fetch offerings, check entitlements, etc. Never expose RevenueCat API keys to the client.
+
+## Install
+
+```bash
+npm install revenuecat-server
+```
+
+```bash
+pnpm add revenuecat-server
+```
+
+```bash
+yarn add revenuecat-server
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`), or Deno/Bun
+
+## Setup
+
+```js
+const { RevenueCatClient } = require("revenuecat-server");
+
+const rc = new RevenueCatClient({
+  apiKey: process.env.REVENUECAT_API_KEY, // v2 secret key
+  projectId: process.env.REVENUECAT_PROJECT_ID,
+});
+```
+
+---
+
+## API
+
+### Customers
+
+#### `getCustomer(customerId, options?)`
+
+Fetch a single customer. `active_entitlements` is always included.
+
+```js
+const customer = await rc.getCustomer("user-uuid");
+
+// With attributes expanded
+const customer = await rc.getCustomer("user-uuid", {
+  expand: ["attributes"],
+});
+```
+
+---
+
+#### `getActiveEntitlements(customerId)`
+
+Returns all active entitlements as a flat array (auto-paginates).
+
+```js
+const entitlements = await rc.getActiveEntitlements("user-uuid");
+// [{ entitlement_id: "premium", expires_at: 1234567890000 }, ...]
+```
+
+---
+
+#### `hasEntitlement(customerId, entitlementId)`
+
+Quick boolean check for a specific entitlement.
+
+```js
+const isPremium = await rc.hasEntitlement("user-uuid", "premium");
+// true | false
+```
+
+---
+
+#### `requireEntitlement(customerId, entitlementId)`
+
+Throws `AccessDeniedError` if the customer lacks the entitlement. Ideal for API route guards.
+
+```js
+try {
+  await rc.requireEntitlement("user-uuid", "premium");
+  // User has access — serve premium content or proceed with operation
+} catch (err) {
+  if (err instanceof AccessDeniedError) {
+    return res.status(403).json({ error: "Premium required" });
+  }
+  throw err;
+}
+```
+
+---
+
+#### `requireAnyEntitlement(customerId, entitlementIds)`
+
+Throws `AccessDeniedError` if the customer has **none** of the given entitlements. Use for "any premium tier" checks.
+
+```js
+await rc.requireAnyEntitlement("user-uuid", ["premium", "pro", "enterprise"]);
+```
+
+---
+
+### Server-side access control
+
+| Need | Use |
+|------|-----|
+| Gate an API route or operation | `requireEntitlement(customerId, "premium")` |
+| Conditional logic / custom UI | `hasEntitlement(customerId, "premium")` |
+| "Any of these tiers" check | `requireAnyEntitlement(customerId, ["premium", "pro"])` |
+| Sync entitlements to your DB (cron) | `getActiveEntitlements(customerId)` |
+| Handle access denied | `catch (err) { if (err instanceof AccessDeniedError) { ... } }` |
+
+You can rely on live checks instead of webhooks if that fits your stack better — this SDK keeps the flow simple.
+
+---
+
+### Offerings
+
+#### `getOffering(offeringId, options?)`
+
+Fetch a raw offering. Defaults to `expand=["package.product"]`.
+
+```js
+const offering = await rc.getOffering("ofrnge1a2b3c4d5");
+```
+
+---
+
+#### `getProductsByPlatform(offeringId, packageId)`
+
+Get products for a specific package, grouped by platform.
+
+```js
+const products = await rc.getProductsByPlatform(
+  "ofrnge1a2b3c4d5",
+  "pkge1a2b3c4d5"
+);
+// {
+//   ios:     [{ store_identifier: "com.app.monthly", display_name: "...", ... }],
+//   android: [{ store_identifier: "com.app.monthly.android", ... }],
+//   other:   []
+// }
+```
+
+---
+
+#### `getOfferingPackages(offeringId)`
+
+All packages in an offering, each with products grouped by platform. Auto-paginates both packages and products.
+
+```js
+const packages = await rc.getOfferingPackages("ofrnge1a2b3c4d5");
+// [
+//   {
+//     id: "pkge1a2b3c4d5",
+//     lookup_key: "monthly",
+//     display_name: "Monthly",
+//     position: 1,
+//     products: { ios: [...], android: [...], other: [...] }
+//   }
+// ]
+```
+
+---
+
+## Error Handling
+
+- **RevenueCatError** — Thrown on API errors (4xx, 5xx). Has `status` and `body`.
+- **AccessDeniedError** — Thrown by `requireEntitlement` and `requireAnyEntitlement` when access is denied. Has `customerId` and `entitlementIds`.
+
+```js
+const { RevenueCatError, AccessDeniedError } = require("revenuecat-server");
+
+try {
+  const customer = await rc.getCustomer("bad-id");
+} catch (err) {
+  if (err instanceof RevenueCatError) {
+    console.error(err.status); // 404
+    console.error(err.body); // { message: "Not found" }
+  }
+  if (err instanceof AccessDeniedError) {
+    console.error(err.customerId, err.entitlementIds);
+  }
+}
+```
+
+---
+
+## Notes
+
+- **Server-side only** — Run this SDK in your backend. Expose data to your frontend via secure proxy endpoints (e.g. `GET /api/offerings`, `GET /api/me/entitlements`). Your frontend never touches RevenueCat directly.
+- **Prices are not available** via RevenueCat — fetch those from Apple StoreKit / Google Play Billing directly using `store_identifier`.
+- Your API key must have the correct permissions:
+  - `customer_information:customers:read` — for customer/entitlement endpoints
+  - `project_configuration:packages:read` — for packages
+  - `project_configuration:products:read` — for products
+- Rate limits: **480 req/min** for customer endpoints, **60 req/min** for offering/project config endpoints.
+
+## Run Tests
+
+```bash
+npm test
+# or
+pnpm test
+# or
+yarn test
+```

package/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * revenuecat-server — Server-side SDK for RevenueCat v2 API
+ * @see https://www.revenuecat.com/docs/api-v2
+ */
+
+export interface RevenueCatClientConfig {
+  apiKey: string;
+  projectId: string;
+}
+
+export interface GetCustomerOptions {
+  expand?: string[];
+}
+
+export interface GetOfferingOptions {
+  expand?: string[];
+}
+
+export interface ProductsByPlatform {
+  ios: Product[];
+  android: Product[];
+  other: Product[];
+}
+
+export interface PackageWithProducts {
+  id: string;
+  lookup_key: string;
+  display_name: string;
+  position: number;
+  products: ProductsByPlatform;
+}
+
+export interface ActiveEntitlement {
+  entitlement_id: string;
+  expires_at?: number;
+  [key: string]: unknown;
+}
+
+export interface Product {
+  id: string;
+  store_identifier: string;
+  display_name?: string;
+  type?: string;
+  app?: { type?: string };
+  subscription?: { duration?: string; trial_duration?: string | null };
+  eligibility_criteria?: string;
+  [key: string]: unknown;
+}
+
+export class RevenueCatClient {
+  constructor(config: RevenueCatClientConfig);
+
+  getCustomer(customerId: string, options?: GetCustomerOptions): Promise<Record<string, unknown>>;
+  getActiveEntitlements(customerId: string): Promise<ActiveEntitlement[]>;
+  hasEntitlement(customerId: string, entitlementId: string): Promise<boolean>;
+  requireEntitlement(customerId: string, entitlementId: string): Promise<void>;
+  requireAnyEntitlement(customerId: string, entitlementIds: string[]): Promise<void>;
+
+  getOffering(offeringId: string, options?: GetOfferingOptions): Promise<Record<string, unknown>>;
+  getProductsByPlatform(offeringId: string, packageId: string): Promise<ProductsByPlatform>;
+  getOfferingPackages(offeringId: string): Promise<PackageWithProducts[]>;
+}
+
+export class RevenueCatError extends Error {
+  status: number;
+  body: Record<string, unknown>;
+  constructor(status: number, body: Record<string, unknown>);
+}
+
+export class AccessDeniedError extends Error {
+  customerId: string;
+  entitlementIds: string[];
+  constructor(customerId: string, entitlementIdOrIds: string | string[]);
+}

package/index.js

@@ -0,0 +1,7 @@
+const {
+  RevenueCatClient,
+  RevenueCatError,
+  AccessDeniedError,
+} = require("./src/RevenueCatClient");
+
+module.exports = { RevenueCatClient, RevenueCatError, AccessDeniedError };

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "revenuecat-server",
+  "version": "1.0.0",
+  "description": "Lightweight server-side SDK for the RevenueCat v2 API. Entitlement checks, offerings, packages — works with any backend (Node, Deno, Bun).",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "require": "./index.js",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src"
+  ],
+  "scripts": {
+    "test": "node tests/client.test.js"
+  },
+  "keywords": [
+    "revenuecat",
+    "subscriptions",
+    "entitlements",
+    "iap",
+    "in-app-purchase",
+    "server",
+    "backend",
+    "paywall"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/revenuecat-server"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/revenuecat-server/issues"
+  },
+  "homepage": "https://github.com/yourusername/revenuecat-server#readme",
+  "sideEffects": false
+}

package/src/RevenueCatClient.js

@@ -0,0 +1,242 @@
+const BASE_URL = "https://api.revenuecat.com/v2";
+
+class RevenueCatClient {
+  constructor({ apiKey, projectId }) {
+    if (!apiKey) throw new Error("RevenueCatClient: apiKey is required");
+    if (!projectId) throw new Error("RevenueCatClient: projectId is required");
+
+    this.apiKey = apiKey;
+    this.projectId = projectId;
+  }
+
+  // ─── Internal ────────────────────────────────────────────────────────────────
+
+  get #headers() {
+    return {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+    };
+  }
+
+  async #get(path, params = {}) {
+    const url = new URL(`${BASE_URL}${path}`);
+    for (const [key, value] of Object.entries(params)) {
+      if (Array.isArray(value)) {
+        value.forEach((v) => url.searchParams.append(key, v));
+      } else {
+        url.searchParams.set(key, value);
+      }
+    }
+
+    const response = await fetch(url.toString(), { headers: this.#headers });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new RevenueCatError(response.status, error);
+    }
+
+    return response.json();
+  }
+
+  async #paginate(firstPage, getItems, getNextPage) {
+    const items = [...getItems(firstPage)];
+    let nextPage = getNextPage(firstPage);
+
+    while (nextPage) {
+      const page = await this.#get(nextPage);
+      items.push(...getItems(page));
+      nextPage = getNextPage(page);
+    }
+
+    return items;
+  }
+
+  // ─── Customers ───────────────────────────────────────────────────────────────
+
+  /**
+   * Get a customer by ID.
+   * @param {string} customerId
+   * @param {{ expand?: string[] }} options
+   */
+  async getCustomer(customerId, { expand = [] } = {}) {
+    const params = expand.length ? { expand } : {};
+    return this.#get(
+      `/projects/${this.projectId}/customers/${customerId}`,
+      params
+    );
+  }
+
+  /**
+   * Get all active entitlements for a customer (auto-paginates).
+   * @param {string} customerId
+   * @returns {Promise<ActiveEntitlement[]>}
+   */
+  async getActiveEntitlements(customerId) {
+    const customer = await this.getCustomer(customerId);
+    return this.#paginate(
+      customer.active_entitlements,
+      (page) => page.items,
+      (page) => page.next_page
+    );
+  }
+
+  /**
+   * Check if a customer has a specific entitlement active.
+   * @param {string} customerId
+   * @param {string} entitlementId
+   * @returns {Promise<boolean>}
+   */
+  async hasEntitlement(customerId, entitlementId) {
+    const entitlements = await this.getActiveEntitlements(customerId);
+    return entitlements.some((e) => e.entitlement_id === entitlementId);
+  }
+
+  /**
+   * Require a specific entitlement — throws AccessDeniedError if the customer
+   * does not have it. Use in API route guards or before protected operations.
+   * @param {string} customerId
+   * @param {string} entitlementId
+   * @throws {AccessDeniedError} when customer lacks the entitlement
+   */
+  async requireEntitlement(customerId, entitlementId) {
+    const has = await this.hasEntitlement(customerId, entitlementId);
+    if (!has) {
+      throw new AccessDeniedError(customerId, entitlementId);
+    }
+  }
+
+  /**
+   * Require at least one of the given entitlements — throws AccessDeniedError
+   * if the customer has none. Useful for "any premium tier" checks.
+   * @param {string} customerId
+   * @param {string[]} entitlementIds
+   * @throws {AccessDeniedError} when customer lacks all entitlements
+   */
+  async requireAnyEntitlement(customerId, entitlementIds) {
+    const entitlements = await this.getActiveEntitlements(customerId);
+    const ids = new Set(entitlements.map((e) => e.entitlement_id));
+    const hasAny = entitlementIds.some((id) => ids.has(id));
+    if (!hasAny) {
+      throw new AccessDeniedError(customerId, entitlementIds);
+    }
+  }
+
+  // ─── Offerings ───────────────────────────────────────────────────────────────
+
+  /**
+   * Get a full offering with packages and products.
+   * @param {string} offeringId
+   * @param {{ expand?: string[] }} options
+   */
+  async getOffering(offeringId, { expand = ["package.product"] } = {}) {
+    return this.#get(
+      `/projects/${this.projectId}/offerings/${offeringId}`,
+      { expand }
+    );
+  }
+
+  /**
+   * Get products for a specific package, grouped by platform.
+   * @param {string} offeringId
+   * @param {string} packageId
+   * @returns {Promise<{ ios: Product[], android: Product[], other: Product[] }>}
+   */
+  async getProductsByPlatform(offeringId, packageId) {
+    const offering = await this.getOffering(offeringId);
+
+    const pkg = offering.packages.items.find((p) => p.id === packageId);
+    if (!pkg) {
+      throw new Error(
+        `Package "${packageId}" not found in offering "${offeringId}"`
+      );
+    }
+
+    // Paginate products if needed
+    const products = await this.#paginate(
+      pkg.products,
+      (page) => page.items,
+      (page) => page.next_page
+    );
+
+    return groupProductsByPlatform(products);
+  }
+
+  /**
+   * Get all packages in an offering, each with products grouped by platform.
+   * @param {string} offeringId
+   * @returns {Promise<PackageWithProducts[]>}
+   */
+  async getOfferingPackages(offeringId) {
+    const offering = await this.getOffering(offeringId);
+
+    // Paginate packages if needed
+    const packages = await this.#paginate(
+      offering.packages,
+      (page) => page.items,
+      (page) => page.next_page
+    );
+
+    return Promise.all(
+      packages.map(async (pkg) => {
+        const products = await this.#paginate(
+          pkg.products,
+          (page) => page.items,
+          (page) => page.next_page
+        );
+        return {
+          id: pkg.id,
+          lookup_key: pkg.lookup_key,
+          display_name: pkg.display_name,
+          position: pkg.position,
+          products: groupProductsByPlatform(products),
+        };
+      })
+    );
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function groupProductsByPlatform(productItems) {
+  const result = { ios: [], android: [], other: [] };
+
+  for (const { product, eligibility_criteria } of productItems) {
+    const appType = product.app?.type;
+    const entry = { ...product, eligibility_criteria };
+
+    if (appType === "app_store" || appType === "mac_app_store") {
+      result.ios.push(entry);
+    } else if (appType === "play_store") {
+      result.android.push(entry);
+    } else {
+      result.other.push(entry);
+    }
+  }
+
+  return result;
+}
+
+class RevenueCatError extends Error {
+  constructor(status, body) {
+    super(`RevenueCat API error ${status}: ${JSON.stringify(body)}`);
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class AccessDeniedError extends Error {
+  constructor(customerId, entitlementIdOrIds) {
+    const ids =
+      typeof entitlementIdOrIds === "string"
+        ? entitlementIdOrIds
+        : entitlementIdOrIds.join(", ");
+    super(`Access denied: customer ${customerId} lacks entitlement(s) [${ids}]`);
+    this.customerId = customerId;
+    this.entitlementIds =
+      typeof entitlementIdOrIds === "string"
+        ? [entitlementIdOrIds]
+        : entitlementIdOrIds;
+  }
+}
+
+module.exports = { RevenueCatClient, RevenueCatError, AccessDeniedError };