@onesub/server 0.11.4 → 0.12.1

package/README.md

@@ -9,11 +9,17 @@ npm install @onesub/server
 ## Requirements
 
 - Node.js **>= 20**
-- **Express** as a peer dependency — `^4.17.0 || ^5.0.0`. Install in your app:
+- **Express** as a peer dependency — `^4.17.0 || ^5.0.0`:
   ```bash
   npm install @onesub/server express
   ```
-- PostgreSQL **12+** (optional, for production stores)
+- Optional peer dependencies (install only what you use):
+  ```bash
+  npm install ioredis        # Redis stores, cache, webhook idempotency
+  npm install bullmq         # Durable webhook queue with dead-letter list
+  npm install pg             # Postgres stores
+  npm install @opentelemetry/api   # Distributed tracing
+  ```
 
 ## Quick start
 
@@ -59,6 +65,9 @@ app.listen(4100);
 | `DELETE /onesub/purchase/admin/:userId/:productId` | Wipe a non-consumable (requires `adminSecret`) |
 | `POST /onesub/purchase/admin/grant` | Manually grant a purchase (requires `adminSecret`) |
 | `POST /onesub/purchase/admin/transfer` | Reassign a `transactionId` to a new `userId` (requires `adminSecret`) |
+| `GET  /onesub/admin/webhook-deadletters` | List failed webhook jobs in DLQ (requires `adminSecret` + BullMQ) |
+| `POST /onesub/admin/webhook-replay/:id` | Replay a dead-letter job (requires `adminSecret` + BullMQ) |
+| `GET  /openapi.json` | OpenAPI 3.1 spec (opt-in via `openapiHandler()`) |
 
 ## Lifecycle states (`0.4.0+`)
 
@@ -134,6 +143,114 @@ google: {
 }
 ```
 
+## Multi-instance deployments (`0.12.0+`)
+
+By default every option uses in-process memory — zero config, zero infra. For multi-node clusters, swap in the Redis-backed equivalents:
+
+```ts
+import Redis from 'ioredis';
+import {
+  createOneSubMiddleware,
+  RedisSubscriptionStore,
+  RedisPurchaseStore,
+  RedisCacheAdapter,
+  RedisWebhookEventStore,
+} from '@onesub/server';
+
+const redis = new Redis(process.env.REDIS_URL!);
+
+app.use(createOneSubMiddleware({
+  // ...apple / google / database config...
+  store:              new RedisSubscriptionStore(redis),
+  purchaseStore:      new RedisPurchaseStore(redis),
+  cache:              new RedisCacheAdapter(redis),      // share Apple JWT + Google OAuth tokens across nodes
+  webhookEventStore:  new RedisWebhookEventStore(redis), // atomic SET NX dedup — one node handles each event
+}));
+```
+
+| Class | Replaces | What it does |
+|-------|----------|--------------|
+| `RedisSubscriptionStore` | `InMemorySubscriptionStore` | Sorted-set index, newest-first pagination |
+| `RedisPurchaseStore` | `InMemoryPurchaseStore` | Cross-node purchase ownership |
+| `RedisCacheAdapter` | `InMemoryCacheAdapter` | Shared Apple JWT / Google OAuth token cache |
+| `RedisWebhookEventStore` | `InMemoryWebhookEventStore` | Atomic `SET NX` dedup (no get→set race) |
+
+### Webhook queue with durable retries
+
+Replace the default in-process queue with BullMQ for decoupled retries and a dead-letter list:
+
+```ts
+import { BullMQWebhookQueue } from '@onesub/server';
+import Redis from 'ioredis';
+
+const connection = new Redis(process.env.REDIS_URL!, { maxRetriesPerRequest: null });
+const webhookQueue = new BullMQWebhookQueue({ connection });
+
+app.use(createOneSubMiddleware({
+  // ...
+  webhookQueue,
+  adminSecret: process.env.ADMIN_SECRET, // required for DLQ endpoints
+}));
+```
+
+The webhook route 200s immediately once the job is enqueued. The BullMQ worker retries up to 5× (exponential backoff, 1 s base) before moving the job to the dead-letter list. Inspect and replay via the admin endpoints above.
+
+## Cache adapter (`0.12.0+`)
+
+The `cache` option controls how Apple JWT assertions and Google OAuth access tokens are cached between requests. Default is `InMemoryCacheAdapter` (process-local). Shared Redis cache prevents every cluster node from minting its own token:
+
+```ts
+import { InMemoryCacheAdapter, RedisCacheAdapter } from '@onesub/server';
+
+// single instance (default — no config needed)
+cache: new InMemoryCacheAdapter()
+
+// multi-instance
+cache: new RedisCacheAdapter(redis)
+cache: new RedisCacheAdapter(redis, 'myapp:cache:') // custom key prefix
+```
+
+You can also pass any object implementing `CacheAdapter`:
+
+```ts
+export interface CacheAdapter {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+  del(key: string): Promise<void>;
+}
+```
+
+## OpenAPI (`0.12.0+`)
+
+The full OpenAPI 3.1 document is exported as `ONESUB_OPENAPI`. Self-host it on your existing Express app:
+
+```ts
+import { openapiHandler } from '@onesub/server';
+
+app.get('/openapi.json', openapiHandler());
+```
+
+Or import the spec directly for client generation:
+
+```ts
+import { ONESUB_OPENAPI } from '@onesub/server';
+// use with openapi-typescript, swagger-ui-express, etc.
+```
+
+## OpenTelemetry tracing (`0.12.0+`)
+
+Install `@opentelemetry/api` alongside an OTel SDK and spans appear automatically for receipt validation and webhook processing. The helper is zero-overhead when the package is absent — no `require` error, no performance hit.
+
+You can wrap your own code in the same tracer:
+
+```ts
+import { withSpan } from '@onesub/server';
+
+const result = await withSpan('my-operation', { 'user.id': userId }, async () => {
+  return await doWork();
+});
+```
+
 ## Schema
 
 Canonical Postgres DDL shipped at [`sql/schema.sql`](./sql/schema.sql). Apply with `psql -f` or let `store.initSchema()` run it for you on startup.

package/dist/__tests__/cache.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cache.test.d.ts.map

package/dist/__tests__/cache.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/cache.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/openapi.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=openapi.test.d.ts.map

package/dist/__tests__/openapi.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/openapi.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/redis-store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=redis-store.test.d.ts.map

package/dist/__tests__/redis-store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-store.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/redis-store.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/webhook-apple.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unit tests for webhook-apple.ts handler behaviors.
+ *
+ * Covers gaps not reached by lifecycle-scenarios or webhook-refund:
+ *   - Input validation (missing / malformed signedPayload)
+ *   - Webhook event deduplication via WebhookEventStore
+ *   - DID_FAIL_TO_RENEW without GRACE_PERIOD subtype → on_hold
+ *   - Notification type mappings: DID_RECOVER, OFFER_REDEEMED → active; EXPIRED → expired
+ *   - Unknown notification type falls through to JWS transaction status
+ */
+export {};
+//# sourceMappingURL=webhook-apple.test.d.ts.map

package/dist/__tests__/webhook-apple.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-apple.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/webhook-apple.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/__tests__/webhook-events.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=webhook-events.test.d.ts.map

package/dist/__tests__/webhook-events.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-events.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/webhook-events.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/webhook-google.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Unit tests for webhook-google.ts handler behaviors.
+ *
+ * Covers gaps not reached by google-paused, google-price-change, or webhook-refund:
+ *   - Input validation (missing message.data)
+ *   - Webhook event deduplication via WebhookEventStore
+ *   - pushAudience JWT authentication (missing / invalid token → 401)
+ *   - Package name mismatch for subscription notifications
+ *   - Notification type mappings: CANCELED, REVOKED, EXPIRED, IN_GRACE_PERIOD, unknown fallback
+ *   - verifyGooglePushToken unit (no network required for invalid tokens)
+ */
+export {};
+//# sourceMappingURL=webhook-google.test.d.ts.map

package/dist/__tests__/webhook-google.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-google.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/webhook-google.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/__tests__/webhook-queue.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=webhook-queue.test.d.ts.map

package/dist/__tests__/webhook-queue.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-queue.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/webhook-queue.test.ts"],"names":[],"mappings":""}

package/dist/cache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Pluggable cache adapter.
+ *
+ * Used internally by the Apple JWT minter, Google OAuth token minter, and any
+ * future per-process cache. The default `InMemoryCacheAdapter` matches the
+ * pre-adapter behavior — module-level state, lost on restart, not shared
+ * between cluster nodes.
+ *
+ * For multi-instance deployments, pass a `RedisCacheAdapter` in
+ * `OneSubMiddlewareConfig.cache` so all nodes share the same JWKS / token
+ * cache and avoid every node re-minting on its own schedule.
+ */
+export interface CacheAdapter {
+    get<T = unknown>(key: string): Promise<T | null>;
+    /** TTL in seconds. Pass 0 / undefined for no expiry. */
+    set<T = unknown>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    del(key: string): Promise<void>;
+}
+/**
+ * Process-local in-memory cache. Default for single-instance deployments.
+ */
+export declare class InMemoryCacheAdapter implements CacheAdapter {
+    private readonly entries;
+    get<T>(key: string): Promise<T | null>;
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    del(key: string): Promise<void>;
+    /** Test helper — clear everything. Not part of the public CacheAdapter contract. */
+    clear(): void;
+}
+export declare function getDefaultCache(): CacheAdapter;
+export declare function setDefaultCache(adapter: CacheAdapter): void;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACjD,wDAAwD;IACxD,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAQD;;GAEG;AACH,qBAAa,oBAAqB,YAAW,YAAY;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IAE9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAUtC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrC,oFAAoF;IACpF,KAAK,IAAI,IAAI;CAGd;AAQD,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAE3D"}