@pylonsync/stripe 0.10.1 → 0.11.1

package/package.json

@@ -1,26 +1,37 @@
 {
-  "name": "@pylonsync/stripe",
-  "publishConfig": {
-    "access": "public"
-  },
-  "version": "0.10.1",
-  "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
-  "scripts": {
-    "build": "tsc -p tsconfig.json --noEmit",
-    "check": "tsc -p tsconfig.json --noEmit"
-  },
-  "dependencies": {
-    "@pylonsync/sdk": "0.10.1",
-    "@pylonsync/functions": "0.10.1"
-  },
-  "peerDependencies": {
-    "bun-types": "*"
-  },
-  "peerDependenciesMeta": {
-    "bun-types": {
-      "optional": true
-    }
-  }
+	"name": "@pylonsync/stripe",
+	"publishConfig": {
+		"access": "public"
+	},
+	"version": "0.11.1",
+	"type": "module",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"scripts": {
+		"build": "tsc -p tsconfig.json --noEmit",
+		"check": "tsc -p tsconfig.json --noEmit"
+	},
+	"dependencies": {
+		"@pylonsync/sdk": "0.11.1",
+		"@pylonsync/functions": "0.11.1"
+	},
+	"peerDependencies": {
+		"bun-types": "*"
+	},
+	"peerDependenciesMeta": {
+		"bun-types": {
+			"optional": true
+		}
+	},
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"default": "./src/index.ts"
+		},
+		"./entitlement": {
+			"types": "./src/entitlement.ts",
+			"default": "./src/entitlement.ts"
+		},
+		"./package.json": "./package.json"
+	}
 }

package/src/entitlement.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from "bun:test";
+import { hasStripeSubscription } from "./entitlement";
+
+const NOW = Date.parse("2026-09-12T00:00:00Z");
+const future = "2026-10-01T00:00:00Z";
+const past = "2026-09-01T00:00:00Z";
+
+describe("stripe entitlement, read from synced rows", () => {
+	test("an active subscription inside its period carries access", () => {
+		expect(hasStripeSubscription([{ status: "active", currentPeriodEnd: future }], NOW)).toBe(true);
+	});
+
+	test("a trial is access", () => {
+		expect(hasStripeSubscription([{ status: "trialing", currentPeriodEnd: future }], NOW)).toBe(
+			true,
+		);
+	});
+
+	test("past_due keeps access until the paid period actually ends", () => {
+		// Every card retry takes days. Cutting a paying customer off over a
+		// payment that will clear tomorrow costs more than the days it saves.
+		expect(hasStripeSubscription([{ status: "past_due", currentPeriodEnd: future }], NOW)).toBe(
+			true,
+		);
+		expect(hasStripeSubscription([{ status: "past_due", currentPeriodEnd: past }], NOW)).toBe(false);
+	});
+
+	test("an unpaid first invoice is not access", () => {
+		// `incomplete` is how someone would otherwise subscribe by abandoning
+		// a card form.
+		expect(hasStripeSubscription([{ status: "incomplete", currentPeriodEnd: future }], NOW)).toBe(
+			false,
+		);
+	});
+
+	test("an elapsed period is inactive even before the webhook says so", () => {
+		expect(hasStripeSubscription([{ status: "active", currentPeriodEnd: past }], NOW)).toBe(false);
+	});
+
+	test("a row with no period end grants nothing", () => {
+		// An undated subscription is a bug upstream; granting on it forever is
+		// the wrong way to find out.
+		expect(hasStripeSubscription([{ status: "active" }], NOW)).toBe(false);
+		expect(hasStripeSubscription([{ status: "active", currentPeriodEnd: null }], NOW)).toBe(false);
+		expect(hasStripeSubscription([{ status: "active", currentPeriodEnd: "soon" }], NOW)).toBe(false);
+	});
+
+	test("a lapsed row does not hide a live one", () => {
+		expect(
+			hasStripeSubscription(
+				[
+					{ status: "canceled", currentPeriodEnd: past },
+					{ status: "active", currentPeriodEnd: future },
+				],
+				NOW,
+			),
+		).toBe(true);
+	});
+
+	test("no rows is no access", () => {
+		expect(hasStripeSubscription([], NOW)).toBe(false);
+	});
+});

package/src/entitlement.ts

@@ -0,0 +1,54 @@
+/**
+ * `@pylonsync/stripe/entitlement` — the part of the plugin that runs in app
+ * code (browser, React Native).
+ *
+ * No server imports, so Metro and browser bundlers can take it. The package
+ * root and `./client` are server-only: `client.ts` is the REST client and
+ * carries the secret key.
+ *
+ * This exists because an app that sells on the web AND through the stores
+ * has two sources of truth — a StripeSubscription row for a web purchase and
+ * an RcEntitlement row for a store purchase — and a subscriber has exactly
+ * one of them. Reading only the store's rows is how someone pays on the web
+ * and gets nothing on their phone.
+ */
+
+/** One row of the subscription entity, as the client reads it through sync. */
+export interface StripeSubscriptionRow {
+	id: string;
+	referenceId: string;
+	plan: string;
+	/** Stripe's own status: active, trialing, past_due, canceled, … */
+	status: string;
+	currentPeriodEnd?: string | null;
+	cancelAtPeriodEnd?: boolean | null;
+}
+
+/**
+ * Statuses that still carry access.
+ *
+ * `past_due` does: every card retry takes days, and cutting a paying
+ * customer off over a payment that will clear tomorrow costs more than the
+ * few days it saves. `trialing` does, because a trial is access. Nothing
+ * else — in particular `incomplete`, where the first payment never cleared,
+ * which is how someone gets a subscription by abandoning a card form.
+ */
+const LIVE_STATUSES = new Set(["active", "trialing", "past_due"]);
+
+/**
+ * Is there a live Stripe subscription in a list of rows read through sync?
+ *
+ * A row whose paid period has elapsed is treated as inactive even if the
+ * webhook carrying that news has not arrived yet.
+ */
+export function hasStripeSubscription(
+	rows: ReadonlyArray<{ status: string; currentPeriodEnd?: string | null }>,
+	now: number = Date.now(),
+): boolean {
+	return rows.some((r) => {
+		if (!LIVE_STATUSES.has(r.status)) return false;
+		if (r.currentPeriodEnd == null) return false;
+		const end = new Date(r.currentPeriodEnd).getTime();
+		return Number.isFinite(end) && end > now;
+	});
+}

package/src/handlers/checkout.ts

@@ -33,6 +33,14 @@ export function createCheckoutSessionHandler(cfg: StripeConfig) {
 			cancelUrl: v.string(),
 			annual: v.optional(v.boolean()),
 			seats: v.optional(v.number()),
+			/**
+			 * An analytics visitor id, carried to Stripe as the session's
+			 * client_reference_id so the eventual payment attributes back to
+			 * the visit that caused it. Without it every purchase looks like
+			 * it came from nowhere, since the webhook arrives from Stripe
+			 * rather than from a browser with a session.
+			 */
+			clientReferenceId: v.optional(v.string()),
 		},
 		async handler(
 			ctx: HandlerCtx,
@@ -43,6 +51,7 @@ export function createCheckoutSessionHandler(cfg: StripeConfig) {
 				cancelUrl: string;
 				annual?: boolean;
 				seats?: number;
+				clientReferenceId?: string;
 			},
 		) {
 			const referenceId = args.referenceId ?? defaultReferenceId(ctx, cfg);
@@ -105,7 +114,9 @@ export function createCheckoutSessionHandler(cfg: StripeConfig) {
 					},
 				],
 				allow_promotion_codes: true,
-				client_reference_id: referenceId,
+				// The caller's id when given: attribution wants the visitor,
+				// not the account, because the visit came first.
+				client_reference_id: args.clientReferenceId ?? referenceId,
 				metadata: { referenceId, plan: plan.name },
 				subscription_data: {
 					metadata: { referenceId, plan: plan.name },