@pylonsync/revenuecat 0.8.2

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@pylonsync/revenuecat",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.8.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noEmit",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@pylonsync/sdk": "0.8.2",
+    "@pylonsync/functions": "0.8.2"
+  },
+  "peerDependencies": {
+    "bun-types": "*"
+  },
+  "peerDependenciesMeta": {
+    "bun-types": {
+      "optional": true
+    }
+  }
+}

package/src/handlers/index.ts

@@ -0,0 +1,3 @@
+export { revenuecatWebhookHandler } from "./webhook";
+export { syncEntitlementsHandler } from "./sync";
+export { upsertEntitlementHandler, INTERNAL_UPSERT } from "./internal";

package/src/handlers/internal.ts

@@ -0,0 +1,74 @@
+/**
+ * Internal mutation the webhook and the sync action write through.
+ * Internal functions bypass entity policies (clients can never insert an
+ * entitlement) and are not callable over HTTP.
+ */
+
+import { mutation, v } from "@pylonsync/functions";
+
+import { entitlementEntityName } from "../manifest";
+import type { HandlerCtx, RevenueCatConfig } from "../types";
+
+export const INTERNAL_UPSERT = "_pylonRcUpsertEntitlement";
+
+export function resolveWebhookAuth(ctx: HandlerCtx, cfg: RevenueCatConfig): string | undefined {
+	if (cfg.getWebhookAuth) return cfg.getWebhookAuth(ctx);
+	return ctx.env.REVENUECAT_WEBHOOK_AUTH;
+}
+
+export function resolveApiKey(ctx: HandlerCtx, cfg: RevenueCatConfig): string | undefined {
+	if (cfg.getApiKey) return cfg.getApiKey(ctx);
+	return ctx.env.REVENUECAT_SECRET_KEY ?? ctx.env.REVENUECAT_PUBLIC_KEY;
+}
+
+export interface UpsertArgs {
+	userId: string;
+	entitlement: string;
+	productId: string;
+	status: "active" | "expired";
+	store: string;
+	environment?: string | null;
+	expiresAt?: string | null;
+}
+
+/** Upsert one (user, entitlement) row. Returns whether the row's status changed. */
+export function upsertEntitlementHandler(cfg: RevenueCatConfig) {
+	const entityName = entitlementEntityName(cfg);
+	return mutation({
+		internal: true,
+		args: {
+			userId: v.string(),
+			entitlement: v.string(),
+			productId: v.string(),
+			status: v.string(),
+			store: v.string(),
+			environment: v.optional(v.string()),
+			expiresAt: v.optional(v.string()),
+		},
+		async handler(ctx, args: UpsertArgs) {
+			const existing = (await ctx.db.query(entityName, {
+				userId: args.userId,
+				entitlement: args.entitlement,
+			})) as Array<{ id: string; status: string }>;
+			const patch = {
+				productId: args.productId,
+				status: args.status,
+				store: args.store,
+				environment: args.environment ?? null,
+				expiresAt: args.expiresAt ?? null,
+				updatedAt: new Date().toISOString(),
+			};
+			if (existing.length > 0) {
+				const before = existing[0];
+				await ctx.db.update(entityName, before.id, patch);
+				return { changed: before.status !== args.status, created: false };
+			}
+			await ctx.db.insert(entityName, {
+				userId: args.userId,
+				entitlement: args.entitlement,
+				...patch,
+			});
+			return { changed: args.status === "active", created: true };
+		},
+	});
+}

package/src/handlers/sync.ts

@@ -0,0 +1,86 @@
+import { action } from "@pylonsync/functions";
+
+import { INTERNAL_UPSERT, resolveApiKey } from "./internal";
+import type { HandlerCtx, RevenueCatConfig } from "../types";
+
+interface SubscriberResponse {
+	subscriber?: {
+		entitlements?: Record<
+			string,
+			{ expires_date?: string | null; product_identifier?: string }
+		>;
+	};
+}
+
+/** Pure mapping of a subscriber payload to row writes, exported for tests. */
+export function entitlementsFromSubscriber(
+	body: SubscriberResponse,
+	now: number,
+): Array<{ entitlement: string; productId: string; status: "active" | "expired"; expiresAt: string | null }> {
+	const out: Array<{
+		entitlement: string;
+		productId: string;
+		status: "active" | "expired";
+		expiresAt: string | null;
+	}> = [];
+	for (const [entitlement, info] of Object.entries(body.subscriber?.entitlements ?? {})) {
+		const expiresAt = info.expires_date ?? null;
+		const active = expiresAt == null || new Date(expiresAt).getTime() > now;
+		out.push({
+			entitlement,
+			productId: String(info.product_identifier ?? ""),
+			status: active ? "active" : "expired",
+			expiresAt,
+		});
+	}
+	return out;
+}
+
+/**
+ * Re-read the caller's entitlements from RevenueCat and write the rows.
+ *
+ * The webhook is the steady-state path; this closes the two gaps in it:
+ * the purchasing device wants to unlock the moment the sheet dismisses
+ * (the webhook may take seconds), and in local development RevenueCat
+ * cannot reach the machine at all.
+ *
+ * Server-verified: the server asks RevenueCat about `ctx.auth.userId`;
+ * a client can trigger the sync but never assert an entitlement.
+ */
+export function syncEntitlementsHandler(cfg: RevenueCatConfig) {
+	return action({
+		args: {},
+		async handler(ctx: HandlerCtx) {
+			const userId = ctx.auth.userId;
+			if (!userId) throw ctx.error("UNAUTHENTICATED", "sign in first");
+			const key = resolveApiKey(ctx, cfg);
+			if (!key) throw ctx.error("RC_NOT_CONFIGURED", "no RevenueCat API key on the server");
+
+			const res = await fetch(
+				`https://api.revenuecat.com/v1/subscribers/${encodeURIComponent(userId)}`,
+				{ headers: { Authorization: `Bearer ${key}`, Accept: "application/json" } },
+			);
+			if (!res.ok) {
+				throw ctx.error("RC_LOOKUP_FAILED", `RevenueCat returned ${res.status}`);
+			}
+			const body = (await res.json()) as SubscriberResponse;
+			const rows = entitlementsFromSubscriber(body, Date.now());
+			for (const row of rows) {
+				const result = await ctx.runMutation<{ changed: boolean }>(INTERNAL_UPSERT, {
+					userId,
+					entitlement: row.entitlement,
+					productId: row.productId,
+					status: row.status,
+					store: "sdk_sync",
+					expiresAt: row.expiresAt,
+				});
+				if (result.changed) {
+					const info = { userId, entitlement: row.entitlement, productId: row.productId, store: "sdk_sync" };
+					if (row.status === "active") await cfg.hooks?.onEntitlementActive?.(ctx, info);
+					else await cfg.hooks?.onEntitlementExpired?.(ctx, info);
+				}
+			}
+			return { applied: rows.length, active: rows.filter((r) => r.status === "active").map((r) => r.entitlement) };
+		},
+	});
+}

package/src/handlers/webhook.ts

@@ -0,0 +1,119 @@
+import { action } from "@pylonsync/functions";
+
+import { INTERNAL_UPSERT, resolveWebhookAuth } from "./internal";
+import type { HandlerCtx, RevenueCatConfig, RevenueCatEvent } from "../types";
+
+/** Event types after which the named entitlements are no longer active. */
+const ENDS_ACCESS = new Set(["EXPIRATION", "REFUND"]);
+
+/** Event types that carry no entitlement change. */
+const INFORMATIONAL = new Set(["TEST", "TRANSFER", "SUBSCRIBER_ALIAS"]);
+
+export interface WebhookOutcome {
+	ok: true;
+	type: string;
+	applied: number;
+	skipped?: string;
+}
+
+/**
+ * Pure event → row-status mapping, exported for tests.
+ *
+ * - INITIAL_PURCHASE / RENEWAL / NON_RENEWING_PURCHASE / UNCANCELLATION /
+ *   PRODUCT_CHANGE / BILLING_ISSUE (still in grace) → active
+ * - CANCELLATION → still active: auto-renew is off, access lasts until
+ *   the EXPIRATION event
+ * - EXPIRATION / REFUND → expired
+ */
+export function statusForEvent(type: string): "active" | "expired" | null {
+	if (INFORMATIONAL.has(type)) return null;
+	return ENDS_ACCESS.has(type) ? "expired" : "active";
+}
+
+export function entitlementIdsOf(event: RevenueCatEvent): string[] {
+	if (Array.isArray(event.entitlement_ids) && event.entitlement_ids.length > 0) {
+		return event.entitlement_ids.map(String);
+	}
+	if (event.entitlement_id) return [String(event.entitlement_id)];
+	return [];
+}
+
+/** Check the shared secret. Accepts the raw value or `Bearer <value>`. */
+export function webhookAuthorized(
+	headerValue: string | undefined,
+	expected: string | undefined,
+): boolean {
+	if (!expected) return false;
+	const got = headerValue ?? "";
+	return got === expected || got === `Bearer ${expected}`;
+}
+
+/**
+ * RevenueCat webhook receiver. Every App Store / Play Billing / Stripe
+ * event RevenueCat sees lands here and becomes entitlement rows.
+ *
+ * `app_user_id` must be the Pylon user id: the app calls
+ * `Purchases.logIn(userId)` before any purchase. Anonymous ids
+ * (`$RCAnonymousID:…`) are acknowledged and ignored.
+ */
+export function revenuecatWebhookHandler(cfg: RevenueCatConfig) {
+	return action({
+		auth: "public",
+		args: {},
+		async handler(ctx: HandlerCtx): Promise<WebhookOutcome> {
+			if (!ctx.request) {
+				throw ctx.error("BAD_INVOCATION", "revenuecatWebhook requires HTTP request context");
+			}
+			const expected = resolveWebhookAuth(ctx, cfg);
+			if (!expected) {
+				throw ctx.error("RC_NOT_CONFIGURED", "REVENUECAT_WEBHOOK_AUTH is not set");
+			}
+			if (!webhookAuthorized(ctx.request.headers["authorization"], expected)) {
+				throw ctx.error("FORBIDDEN", "bad webhook authorization");
+			}
+
+			let event: RevenueCatEvent;
+			try {
+				const body = JSON.parse(ctx.request.rawBody) as { event?: RevenueCatEvent };
+				event = body.event ?? ({ type: "" } as RevenueCatEvent);
+			} catch {
+				throw ctx.error("BAD_BODY", "invalid JSON");
+			}
+			const type = String(event.type ?? "");
+			const userId = String(event.app_user_id ?? "");
+			if (!userId || userId.startsWith("$RCAnonymous")) {
+				return { ok: true, type, applied: 0, skipped: "no app user id" };
+			}
+			const status = statusForEvent(type);
+			const entitlements = entitlementIdsOf(event);
+			if (!status || entitlements.length === 0) {
+				await cfg.hooks?.onEvent?.(ctx, event);
+				return { ok: true, type, applied: 0, skipped: "no entitlement change" };
+			}
+
+			const productId = String(event.product_id ?? "");
+			const store = String(event.store ?? "").toLowerCase();
+			const expiresAt = event.expiration_at_ms
+				? new Date(Number(event.expiration_at_ms)).toISOString()
+				: null;
+			for (const entitlement of entitlements) {
+				const result = await ctx.runMutation<{ changed: boolean }>(INTERNAL_UPSERT, {
+					userId,
+					entitlement,
+					productId,
+					status,
+					store,
+					environment: event.environment ?? null,
+					expiresAt,
+				});
+				if (result.changed) {
+					const info = { userId, entitlement, productId, store };
+					if (status === "active") await cfg.hooks?.onEntitlementActive?.(ctx, info);
+					else await cfg.hooks?.onEntitlementExpired?.(ctx, info);
+				}
+			}
+			await cfg.hooks?.onEvent?.(ctx, event);
+			return { ok: true, type, applied: entitlements.length };
+		},
+	});
+}

package/src/index.ts

@@ -0,0 +1,92 @@
+/**
+ * `@pylonsync/revenuecat` — native in-app purchases for Pylon apps.
+ *
+ * RevenueCat handles the App Store / Play Billing side (products,
+ * receipts, renewals, paywalls). This plugin turns its webhook events
+ * into an `RcEntitlement` row per (user, entitlement) that syncs to every
+ * device like any other row, so a purchase on the phone unlocks the
+ * tablet and the web app without a second receipt check.
+ *
+ * ```ts
+ * // lib/purchases.ts
+ * import { revenuecat } from "@pylonsync/revenuecat";
+ * export const purchases = revenuecat({ entitlements: ["pro"] });
+ * export const { revenuecatWebhook, syncEntitlements } = purchases.handlers;
+ * export const { _pylonRcUpsertEntitlement } = purchases.internals;
+ *
+ * // functions/revenuecatWebhook.ts
+ * export { revenuecatWebhook as default } from "../lib/purchases";
+ * // functions/syncEntitlements.ts
+ * export { syncEntitlements as default } from "../lib/purchases";
+ * // functions/_pylonRcUpsertEntitlement.ts
+ * export { _pylonRcUpsertEntitlement as default } from "../lib/purchases";
+ * ```
+ *
+ * Env:
+ *   REVENUECAT_WEBHOOK_AUTH   the Authorization value set on the dashboard webhook
+ *   REVENUECAT_SECRET_KEY     (or REVENUECAT_PUBLIC_KEY) for the subscriber read in syncEntitlements
+ *
+ * Point the RevenueCat webhook at `POST /api/fn/revenuecatWebhook`.
+ */
+
+import { buildRevenueCatManifest, type RevenueCatManifestFragment } from "./manifest";
+import {
+	INTERNAL_UPSERT,
+	revenuecatWebhookHandler,
+	syncEntitlementsHandler,
+	upsertEntitlementHandler,
+} from "./handlers";
+import type { RevenueCatConfig } from "./types";
+
+export type {
+	RevenueCatConfig,
+	RevenueCatHooks,
+	RevenueCatEvent,
+	RcEntitlementRow,
+	EntitlementChange,
+	HandlerCtx,
+} from "./types";
+export type { RevenueCatManifestFragment } from "./manifest";
+export { entitlementEntityName } from "./manifest";
+export { statusForEvent, entitlementIdsOf, webhookAuthorized } from "./handlers/webhook";
+export { entitlementsFromSubscriber } from "./handlers/sync";
+
+export interface RevenueCatPlugin {
+	manifest: RevenueCatManifestFragment;
+	handlers: {
+		revenuecatWebhook: ReturnType<typeof revenuecatWebhookHandler>;
+		syncEntitlements: ReturnType<typeof syncEntitlementsHandler>;
+	};
+	internals: Record<string, ReturnType<typeof upsertEntitlementHandler>>;
+}
+
+export function revenuecat(cfg: RevenueCatConfig): RevenueCatPlugin {
+	return {
+		manifest: buildRevenueCatManifest(cfg),
+		handlers: {
+			revenuecatWebhook: revenuecatWebhookHandler(cfg),
+			syncEntitlements: syncEntitlementsHandler(cfg),
+		},
+		internals: {
+			[INTERNAL_UPSERT]: upsertEntitlementHandler(cfg),
+		},
+	};
+}
+
+/**
+ * Client-side helper: is `entitlement` active in a list of rows the app
+ * read through sync? Treats a row with a past `expiresAt` as inactive even
+ * if the webhook has not delivered the expiration yet.
+ */
+export function hasEntitlement(
+	rows: ReadonlyArray<{ entitlement: string; status: string; expiresAt?: string | null }>,
+	entitlement: string,
+	now: number = Date.now(),
+): boolean {
+	return rows.some(
+		(r) =>
+			r.entitlement === entitlement &&
+			r.status === "active" &&
+			(r.expiresAt == null || new Date(r.expiresAt).getTime() > now),
+	);
+}

package/src/manifest.ts

@@ -0,0 +1,86 @@
+/**
+ * Manifest fragment: the entitlement entity, its read policy, and the
+ * action declarations. App code spreads these into `buildManifest()`.
+ */
+
+import {
+	type ActionDefinition,
+	type EntityDefinition,
+	type PolicyDefinition,
+	action,
+	entity,
+	field,
+	policy,
+} from "@pylonsync/sdk";
+
+import type { RevenueCatConfig } from "./types";
+
+export interface RevenueCatManifestFragment {
+	entities: EntityDefinition[];
+	actions: ActionDefinition[];
+	policies: PolicyDefinition[];
+}
+
+export function entitlementEntityName(cfg: RevenueCatConfig): string {
+	return cfg.entities?.entitlement ?? "RcEntitlement";
+}
+
+/**
+ * ```ts
+ * const purchases = revenuecat({ entitlements: ["pro"] });
+ * buildManifest({
+ *   entities: [User, ...purchases.manifest.entities],
+ *   actions:  [...fns.actions, ...purchases.manifest.actions],
+ *   policies: [...purchases.manifest.policies],
+ * });
+ * ```
+ */
+export function buildRevenueCatManifest(cfg: RevenueCatConfig): RevenueCatManifestFragment {
+	const name = entitlementEntityName(cfg);
+
+	// One row per (user, entitlement). Written only by the webhook and the
+	// server-side sync; clients read their own rows through sync, so a
+	// purchase on one device unlocks every device.
+	const Entitlement = entity(
+		name,
+		{
+			userId: field.id("User"),
+			entitlement: field.string(),
+			productId: field.string(),
+			// "active" | "expired"
+			status: field.string(),
+			// app_store | play_store | stripe | promotional | sdk_sync
+			store: field.string(),
+			environment: field.string().optional(),
+			expiresAt: field.string().optional(),
+			updatedAt: field.string(),
+		},
+		{
+			indexes: [
+				{ name: "by_user_entitlement", fields: ["userId", "entitlement"], unique: true },
+			],
+		},
+	);
+
+	const readOwn = policy({
+		name: `${name.toLowerCase()}_read_own`,
+		entity: name,
+		allowRead: "auth.userId == data.userId",
+		allowInsert: "false",
+		allowUpdate: "false",
+		allowDelete: "false",
+	});
+
+	return {
+		entities: [Entitlement],
+		policies: [readOwn],
+		actions: [
+			// Public by handler: RevenueCat posts anonymously; the shared
+			// Authorization header is the auth boundary.
+			action("revenuecatWebhook"),
+			// Signed-in user: re-read their entitlements from RevenueCat and
+			// write the rows. Called after a purchase or restore.
+			action("syncEntitlements"),
+		],
+	};
+}

package/src/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Public type surface for `@pylonsync/revenuecat`.
+ */
+
+export interface RevenueCatConfig {
+	/**
+	 * Entitlement identifiers the app gates on, as configured in the
+	 * RevenueCat dashboard (for example `["pro"]`). Unknown identifiers on
+	 * a webhook are still stored; this list documents what the app uses.
+	 */
+	entitlements: string[];
+	/**
+	 * The shared secret RevenueCat sends as the `Authorization` header on
+	 * every webhook (set the same value in the dashboard). Resolved from
+	 * `ctx.env.REVENUECAT_WEBHOOK_AUTH` unless overridden. When unset the
+	 * webhook answers 403, so a fresh deploy cannot be fed forged
+	 * entitlements.
+	 */
+	getWebhookAuth?: (ctx: HandlerCtx) => string | undefined;
+	/**
+	 * Key for `GET https://api.revenuecat.com/v1/subscribers/<id>`, used by
+	 * `syncEntitlements` to re-read a user's entitlements after a purchase
+	 * or restore. Resolved from `ctx.env.REVENUECAT_SECRET_KEY`, then
+	 * `ctx.env.REVENUECAT_PUBLIC_KEY` (the public SDK key is enough for
+	 * that read), unless overridden.
+	 */
+	getApiKey?: (ctx: HandlerCtx) => string | undefined;
+	/** Entity name override. Default `RcEntitlement`. */
+	entities?: { entitlement?: string };
+	hooks?: RevenueCatHooks;
+}
+
+export interface EntitlementChange {
+	userId: string;
+	entitlement: string;
+	productId: string;
+	store: string;
+}
+
+export interface RevenueCatHooks {
+	/** An entitlement became active for a user (purchase, renewal, restore). */
+	onEntitlementActive?: (ctx: HandlerCtx, info: EntitlementChange) => Promise<void> | void;
+	/** An entitlement ended (expiration, refund, or a billing issue past grace). */
+	onEntitlementExpired?: (ctx: HandlerCtx, info: EntitlementChange) => Promise<void> | void;
+	/** Every webhook event, after the rows were written. */
+	onEvent?: (ctx: HandlerCtx, event: RevenueCatEvent) => Promise<void> | void;
+}
+
+/**
+ * The subset of a RevenueCat webhook event this plugin reads.
+ * https://www.revenuecat.com/docs/integrations/webhooks/event-types-and-fields
+ */
+export interface RevenueCatEvent {
+	type: string;
+	app_user_id?: string;
+	original_app_user_id?: string;
+	/** Every id RevenueCat has aliased for this subscriber. */
+	aliases?: string[];
+	product_id?: string;
+	entitlement_id?: string | null;
+	entitlement_ids?: string[] | null;
+	store?: string;
+	environment?: string;
+	expiration_at_ms?: number | null;
+	purchased_at_ms?: number | null;
+	period_type?: string;
+	cancel_reason?: string;
+	new_product_id?: string;
+	transaction_id?: string;
+	id?: string;
+}
+
+/** One row of the entitlement entity. */
+export interface RcEntitlementRow {
+	id: string;
+	userId: string;
+	entitlement: string;
+	productId: string;
+	status: "active" | "expired";
+	store: string;
+	environment?: string | null;
+	expiresAt?: string | null;
+	updatedAt: string;
+}
+
+/** Function context shape the handlers use; structurally compatible with
+ *  `@pylonsync/functions`' ctx. */
+export interface HandlerCtx {
+	env: Record<string, string | undefined>;
+	auth: { userId?: string | null; tenantId?: string | null; isAdmin?: boolean };
+	request?: {
+		headers: Record<string, string | undefined>;
+		rawBody: string;
+	};
+	runQuery: <T>(name: string, args: Record<string, unknown>) => Promise<T>;
+	runMutation: <T = unknown>(name: string, args: Record<string, unknown>) => Promise<T>;
+	error: (code: string, message: string) => Error;
+}

package/src/webhook.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+
+import { entitlementsFromSubscriber } from "./handlers/sync";
+import { entitlementIdsOf, revenuecatWebhookHandler, statusForEvent, webhookAuthorized } from "./handlers/webhook";
+import { hasEntitlement } from "./index";
+import type { HandlerCtx } from "./types";
+
+describe("event mapping", () => {
+	test("purchase-like events are active, expiration and refund end access, cancellation keeps it", () => {
+		for (const t of ["INITIAL_PURCHASE", "RENEWAL", "NON_RENEWING_PURCHASE", "UNCANCELLATION", "PRODUCT_CHANGE", "BILLING_ISSUE", "CANCELLATION"]) {
+			expect(statusForEvent(t)).toBe("active");
+		}
+		expect(statusForEvent("EXPIRATION")).toBe("expired");
+		expect(statusForEvent("REFUND")).toBe("expired");
+		expect(statusForEvent("TEST")).toBeNull();
+		expect(statusForEvent("TRANSFER")).toBeNull();
+	});
+
+	test("entitlement ids come from the list, then the single field", () => {
+		expect(entitlementIdsOf({ type: "RENEWAL", entitlement_ids: ["pro", "coach"] })).toEqual(["pro", "coach"]);
+		expect(entitlementIdsOf({ type: "RENEWAL", entitlement_id: "pro" })).toEqual(["pro"]);
+		expect(entitlementIdsOf({ type: "RENEWAL" })).toEqual([]);
+	});
+
+	test("the shared secret is required and accepted bare or as a bearer", () => {
+		expect(webhookAuthorized("s3cret", "s3cret")).toBe(true);
+		expect(webhookAuthorized("Bearer s3cret", "s3cret")).toBe(true);
+		expect(webhookAuthorized("wrong", "s3cret")).toBe(false);
+		expect(webhookAuthorized("s3cret", undefined)).toBe(false);
+		expect(webhookAuthorized(undefined, "s3cret")).toBe(false);
+	});
+
+	test("subscriber payloads map to active or expired by expires_date", () => {
+		const now = Date.parse("2026-09-05T00:00:00Z");
+		const rows = entitlementsFromSubscriber(
+			{
+				subscriber: {
+					entitlements: {
+						pro: { expires_date: "2026-10-01T00:00:00Z", product_identifier: "pro_monthly" },
+						coach: { expires_date: "2026-01-01T00:00:00Z", product_identifier: "coach_10" },
+						lifetime: { expires_date: null, product_identifier: "lifetime" },
+					},
+				},
+			},
+			now,
+		);
+		expect(rows.map((r) => [r.entitlement, r.status])).toEqual([
+			["pro", "active"],
+			["coach", "expired"],
+			["lifetime", "active"],
+		]);
+	});
+
+	test("hasEntitlement ignores rows whose expiry has passed", () => {
+		const rows = [
+			{ entitlement: "pro", status: "active", expiresAt: "2026-01-01T00:00:00Z" },
+			{ entitlement: "coach", status: "active", expiresAt: null },
+		];
+		const now = Date.parse("2026-09-05T00:00:00Z");
+		expect(hasEntitlement(rows, "pro", now)).toBe(false);
+		expect(hasEntitlement(rows, "coach", now)).toBe(true);
+		expect(hasEntitlement(rows, "missing", now)).toBe(false);
+	});
+});
+
+function ctxWith(headers: Record<string, string>, body: unknown, env: Record<string, string>) {
+	const mutations: Array<Record<string, unknown>> = [];
+	const ctx = {
+		env,
+		auth: { userId: null },
+		request: { headers, rawBody: JSON.stringify(body) },
+		error: (code: string, message: string) => Object.assign(new Error(message), { code }),
+		runQuery: async () => [] as never,
+		runMutation: async (_name: string, args: Record<string, unknown>) => {
+			mutations.push(args);
+			return { changed: true } as never;
+		},
+	} as unknown as HandlerCtx;
+	return { ctx, mutations };
+}
+
+describe("webhook handler", () => {
+	const handler = revenuecatWebhookHandler({ entitlements: ["pro"] }) as unknown as {
+		handler: (ctx: HandlerCtx, args: Record<string, never>) => Promise<{ applied: number; skipped?: string }>;
+	};
+
+	test("refuses when the secret is unset or wrong", async () => {
+		const unset = ctxWith({ authorization: "x" }, { event: { type: "RENEWAL" } }, {});
+		await expect(handler.handler(unset.ctx, {})).rejects.toThrow("REVENUECAT_WEBHOOK_AUTH");
+		const wrong = ctxWith({ authorization: "nope" }, { event: { type: "RENEWAL" } }, { REVENUECAT_WEBHOOK_AUTH: "s3cret" });
+		await expect(handler.handler(wrong.ctx, {})).rejects.toThrow("bad webhook authorization");
+		expect(wrong.mutations).toHaveLength(0);
+	});
+
+	test("writes one active row per entitlement on a purchase", async () => {
+		const { ctx, mutations } = ctxWith(
+			{ authorization: "s3cret" },
+			{
+				event: {
+					type: "INITIAL_PURCHASE",
+					app_user_id: "user_1",
+					product_id: "pro_monthly",
+					entitlement_ids: ["pro"],
+					store: "APP_STORE",
+					environment: "SANDBOX",
+					expiration_at_ms: Date.parse("2026-10-05T00:00:00Z"),
+				},
+			},
+			{ REVENUECAT_WEBHOOK_AUTH: "s3cret" },
+		);
+		const out = await handler.handler(ctx, {});
+		expect(out.applied).toBe(1);
+		expect(mutations[0]).toMatchObject({
+			userId: "user_1",
+			entitlement: "pro",
+			productId: "pro_monthly",
+			status: "active",
+			store: "app_store",
+			environment: "SANDBOX",
+			expiresAt: "2026-10-05T00:00:00.000Z",
+		});
+	});
+
+	test("anonymous subscribers are acknowledged and ignored", async () => {
+		const { ctx, mutations } = ctxWith(
+			{ authorization: "s3cret" },
+			{ event: { type: "INITIAL_PURCHASE", app_user_id: "$RCAnonymousID:abc", entitlement_ids: ["pro"] } },
+			{ REVENUECAT_WEBHOOK_AUTH: "s3cret" },
+		);
+		const out = await handler.handler(ctx, {});
+		expect(out.skipped).toBe("no app user id");
+		expect(mutations).toHaveLength(0);
+	});
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "include": [
+    "src"
+  ]
+}