@sudobility/subscription_service 1.0.1

package/CLAUDE.md

@@ -0,0 +1,108 @@
+# Subscription Service
+
+Shared backend library for subscription management using RevenueCat.
+
+**npm**: `@sudobility/subscription_service` (public)
+
+## Tech Stack
+
+- **Language**: TypeScript (strict mode)
+- **Runtime**: Bun
+- **Build**: TypeScript compiler (ESM)
+- **Test**: vitest
+
+## Project Structure
+
+```
+src/
+├── index.ts                    # Main exports
+├── types/
+│   ├── index.ts                # Type re-exports
+│   ├── entitlements.ts         # RevenueCat API types
+│   └── subscription.ts         # SubscriptionInfo type
+└── helpers/
+    ├── index.ts                # Helper re-exports
+    └── SubscriptionHelper.ts   # RevenueCat API client
+tests/
+└── *.test.ts
+```
+
+## Commands
+
+```bash
+bun run build        # Build ESM
+bun run clean        # Remove dist/
+bun run dev          # Watch mode
+bun test             # Run tests
+bun run lint         # Run ESLint
+bun run typecheck    # TypeScript check
+bun run verify       # All checks + build (use before commit)
+```
+
+## Key Concepts
+
+### SubscriptionHelper
+
+Fetches user entitlements from RevenueCat API v1.
+
+- Uses RevenueCat secret API key (server-side only)
+- Supports testMode to include/exclude sandbox purchases
+- Returns `["none"]` if user has no active entitlements
+
+### testMode Parameter
+
+- `testMode=true`: Accept sandbox purchases (for testing)
+- `testMode=false` (default): Reject sandbox purchases (production)
+
+The helper checks each subscription's `sandbox` flag and filters accordingly.
+
+## Usage
+
+```typescript
+import { SubscriptionHelper, NONE_ENTITLEMENT } from "@sudobility/subscription_service";
+
+const helper = new SubscriptionHelper({
+  revenueCatApiKey: process.env.REVENUECAT_API_KEY!,
+});
+
+// Get entitlements (production mode - no sandbox)
+const entitlements = await helper.getEntitlements(userId);
+// Returns: ["pro"] or ["none"]
+
+// Get entitlements (test mode - includes sandbox)
+const entitlements = await helper.getEntitlements(userId, true);
+
+// Get full subscription info
+const info = await helper.getSubscriptionInfo(userId, testMode);
+// Returns: { entitlements: ["pro"], subscriptionStartedAt: Date | null }
+
+// Check if user has a subscription
+if (!info.entitlements.includes(NONE_ENTITLEMENT)) {
+  // User has active subscription
+}
+```
+
+## Architecture
+
+```
+subscription_service (this package)
+    ↑
+ratelimit_service (depends on this)
+    ↑
+shapeshyft_api, sudojo_api, etc.
+```
+
+## Consuming APIs
+
+APIs using this library:
+- shapeshyft_api
+- sudojo_api
+- whisperly_api
+- ratelimit_service
+
+## Publishing
+
+```bash
+bun run verify       # All checks
+npm publish          # Publish to npm
+```

package/dist/helpers/SubscriptionHelper.d.ts

@@ -0,0 +1,28 @@
+import type { SubscriptionInfo } from "../types/subscription";
+/**
+ * Configuration for SubscriptionHelper.
+ */
+export interface SubscriptionHelperConfig {
+    /** RevenueCat secret API key (for server-side use) */
+    revenueCatApiKey: string;
+    /** Base URL for RevenueCat API. Defaults to https://api.revenuecat.com/v1 */
+    baseUrl?: string;
+}
+/**
+ * Helper class for interacting with RevenueCat API to get user entitlements
+ * and subscription information.
+ */
+export declare class SubscriptionHelper {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: SubscriptionHelperConfig);
+    /**
+     * Get active entitlement names for a user.
+     */
+    getEntitlements(userId: string, testMode?: boolean): Promise<string[]>;
+    /**
+     * Get full subscription info including entitlements and subscription start date.
+     */
+    getSubscriptionInfo(userId: string, testMode?: boolean): Promise<SubscriptionInfo>;
+}
+//# sourceMappingURL=SubscriptionHelper.d.ts.map

package/dist/helpers/SubscriptionHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubscriptionHelper.d.ts","sourceRoot":"","sources":["../../src/helpers/SubscriptionHelper.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,gBAAgB,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,wBAAwB;IAK5C;;OAEG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,MAAM,EAAE,CAAC;IAKpB;;OAEG;IACG,mBAAmB,CACvB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,OAAe,GACxB,OAAO,CAAC,gBAAgB,CAAC;CAgE7B"}

package/dist/helpers/SubscriptionHelper.js

@@ -0,0 +1,72 @@
+import { NONE_ENTITLEMENT, } from "../types/entitlements";
+/**
+ * Helper class for interacting with RevenueCat API to get user entitlements
+ * and subscription information.
+ */
+export class SubscriptionHelper {
+    constructor(config) {
+        this.apiKey = config.revenueCatApiKey;
+        this.baseUrl = config.baseUrl ?? "https://api.revenuecat.com/v1";
+    }
+    /**
+     * Get active entitlement names for a user.
+     */
+    async getEntitlements(userId, testMode = false) {
+        const info = await this.getSubscriptionInfo(userId, testMode);
+        return info.entitlements;
+    }
+    /**
+     * Get full subscription info including entitlements and subscription start date.
+     */
+    async getSubscriptionInfo(userId, testMode = false) {
+        const url = `${this.baseUrl}/subscribers/${encodeURIComponent(userId)}`;
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (response.status === 404) {
+            return {
+                entitlements: [NONE_ENTITLEMENT],
+                subscriptionStartedAt: null,
+            };
+        }
+        if (!response.ok) {
+            throw new Error(`RevenueCat API error: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        const entitlements = data.subscriber?.entitlements ?? {};
+        const subscriptions = data.subscriber?.subscriptions ?? {};
+        const now = new Date();
+        const activeEntitlements = [];
+        let earliestPurchaseDate = null;
+        for (const [name, entitlement] of Object.entries(entitlements)) {
+            const isActive = !entitlement.expires_date || new Date(entitlement.expires_date) > now;
+            if (!isActive) {
+                continue;
+            }
+            const subscription = subscriptions[entitlement.product_identifier];
+            if (!testMode && subscription?.sandbox === true) {
+                continue;
+            }
+            activeEntitlements.push(name);
+            const purchaseDate = new Date(entitlement.purchase_date);
+            if (!earliestPurchaseDate || purchaseDate < earliestPurchaseDate) {
+                earliestPurchaseDate = purchaseDate;
+            }
+        }
+        if (activeEntitlements.length === 0) {
+            return {
+                entitlements: [NONE_ENTITLEMENT],
+                subscriptionStartedAt: null,
+            };
+        }
+        return {
+            entitlements: activeEntitlements,
+            subscriptionStartedAt: earliestPurchaseDate,
+        };
+    }
+}
+//# sourceMappingURL=SubscriptionHelper.js.map

package/dist/helpers/SubscriptionHelper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubscriptionHelper.js","sourceRoot":"","sources":["../../src/helpers/SubscriptionHelper.ts"],"names":[],"mappings":"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"}

package/dist/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export { SubscriptionHelper, type SubscriptionHelperConfig, } from "./SubscriptionHelper";
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,sBAAsB,CAAC"}

package/dist/helpers/index.js

@@ -0,0 +1,2 @@
+export { SubscriptionHelper, } from "./SubscriptionHelper";
+//# sourceMappingURL=index.js.map

package/dist/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,GAEnB,MAAM,sBAAsB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { NONE_ENTITLEMENT, type RevenueCatEntitlement, type RevenueCatSubscription, type RevenueCatSubscriberResponse, type SubscriptionInfo, } from "./types";
+export { SubscriptionHelper, type SubscriptionHelperConfig, } from "./helpers";
+//# 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":"AACA,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,GACtB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,kBAAkB,EAClB,KAAK,wBAAwB,GAC9B,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// Types
+export { NONE_ENTITLEMENT, } from "./types";
+// Helpers
+export { SubscriptionHelper, } from "./helpers";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,OAAO,EACL,gBAAgB,GAKjB,MAAM,SAAS,CAAC;AAEjB,UAAU;AACV,OAAO,EACL,kBAAkB,GAEnB,MAAM,WAAW,CAAC"}

package/dist/types/entitlements.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The special entitlement name for users without any subscription.
+ * This is returned when a user has no active entitlements in RevenueCat.
+ */
+export declare const NONE_ENTITLEMENT: "none";
+/**
+ * RevenueCat entitlement information from the subscriber API.
+ */
+export interface RevenueCatEntitlement {
+    /** Expiration date in ISO format, or null if lifetime */
+    expires_date: string | null;
+    /** Grace period expiration date */
+    grace_period_expires_date: string | null;
+    /** Product identifier in the app store */
+    product_identifier: string;
+    /** Purchase date in ISO format */
+    purchase_date: string;
+}
+/**
+ * RevenueCat subscription information from the subscriber API.
+ */
+export interface RevenueCatSubscription {
+    /** Expiration date in ISO format, or null if lifetime */
+    expires_date: string | null;
+    /** Purchase date in ISO format */
+    purchase_date: string;
+    /** Whether this is a sandbox purchase */
+    sandbox: boolean;
+    /** Store where the purchase was made */
+    store: string;
+}
+/**
+ * Response shape from RevenueCat's GET /subscribers/{user_id} endpoint.
+ */
+export interface RevenueCatSubscriberResponse {
+    subscriber: {
+        entitlements: {
+            [key: string]: RevenueCatEntitlement;
+        };
+        subscriptions: {
+            [key: string]: RevenueCatSubscription;
+        };
+    };
+}
+//# sourceMappingURL=entitlements.d.ts.map

package/dist/types/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../../src/types/entitlements.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAG,MAAe,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mCAAmC;IACnC,yBAAyB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kCAAkC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,yCAAyC;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE;QACV,YAAY,EAAE;YACZ,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAAC;SACtC,CAAC;QACF,aAAa,EAAE;YACb,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,CAAC;SACvC,CAAC;KACH,CAAC;CACH"}

package/dist/types/entitlements.js

@@ -0,0 +1,6 @@
+/**
+ * The special entitlement name for users without any subscription.
+ * This is returned when a user has no active entitlements in RevenueCat.
+ */
+export const NONE_ENTITLEMENT = "none";
+//# sourceMappingURL=entitlements.js.map

package/dist/types/entitlements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.js","sourceRoot":"","sources":["../../src/types/entitlements.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAe,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { NONE_ENTITLEMENT, type RevenueCatEntitlement, type RevenueCatSubscription, type RevenueCatSubscriberResponse, } from "./entitlements";
+export { type SubscriptionInfo } from "./subscription";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,GAClC,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export { NONE_ENTITLEMENT, } from "./entitlements";
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAIjB,MAAM,gBAAgB,CAAC"}

package/dist/types/subscription.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Subscription information returned by SubscriptionHelper.
+ */
+export interface SubscriptionInfo {
+    /** Array of active entitlement names */
+    entitlements: string[];
+    /** When the subscription started (earliest purchase date), or null if no subscription */
+    subscriptionStartedAt: Date | null;
+}
+//# sourceMappingURL=subscription.d.ts.map

package/dist/types/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../src/types/subscription.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,yFAAyF;IACzF,qBAAqB,EAAE,IAAI,GAAG,IAAI,CAAC;CACpC"}

package/dist/types/subscription.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=subscription.js.map

package/dist/types/subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.js","sourceRoot":"","sources":["../../src/types/subscription.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@sudobility/subscription_service",
+  "version": "1.0.1",
+  "description": "Shared subscription management library using RevenueCat for entitlements",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "verify": "bun run typecheck && bun run lint && bun run test && bun run build",
+    "prepublishOnly": "bun run clean && bun run verify"
+  },
+  "files": [
+    "dist/**/*",
+    "CLAUDE.md"
+  ],
+  "keywords": [
+    "subscription",
+    "revenuecat",
+    "entitlements",
+    "in-app-purchase"
+  ],
+  "author": "Sudobility",
+  "license": "MIT",
+  "peerDependencies": {},
+  "devDependencies": {
+    "vitest": "^4.0.4",
+    "@types/bun": "latest",
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "eslint": "^9.39.0",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.7.0",
+    "typescript": "^5.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}