gatefit 0.0.0-stage → 0.5.0

package/src/live-scenarios.ts

@@ -0,0 +1,191 @@
+import type { AccessAdapter, AccessSnapshot, BillingEvent } from "./access-adapter.ts";
+import { compareAccess } from "./access-adapter.ts";
+import { advanceUntilReady, withTestClock, type ClockWaitOpts } from "./clock-driver.ts";
+import {
+  MAX_CUSTOMERS_PER_CLOCK,
+  MAX_SUBSCRIPTIONS_PER_CLOCK,
+  type StripeClockClient,
+  type StripeInvoice,
+  type StripeSubscription,
+} from "./stripe-clock.ts";
+
+export const LIVE_SCENARIO_IDS = [
+  "paid_grants_access",
+  "cancel_revokes_access",
+  "trial_to_paid_grants",
+] as const;
+
+export type LiveScenarioId = (typeof LIVE_SCENARIO_IDS)[number];
+
+export type LiveScenarioResult = {
+  id: LiveScenarioId;
+  ok: boolean;
+  mismatches: string[];
+  customerId?: string;
+};
+
+export function billingEventsFromStripe(input: {
+  customerId: string;
+  plan: string;
+  subscription: StripeSubscription;
+  invoices: StripeInvoice[];
+  stripeHttpStatus?: number;
+  now?: number;
+}): BillingEvent[] {
+  void input.stripeHttpStatus;
+  const events: BillingEvent[] = [];
+  const quantity = input.subscription.items?.data?.[0]?.quantity;
+  if (input.subscription.status === "trialing") {
+    events.push({
+      id: `${input.subscription.id}:trialing`,
+      type: "customer.subscription.updated",
+      customerId: input.customerId,
+      status: "trialing",
+      plan: input.plan,
+    });
+    return events;
+  }
+  for (const invoice of input.invoices) {
+    if (invoice.paid === true || invoice.status === "paid") {
+      events.push({
+        id: invoice.id,
+        type: "invoice.paid",
+        customerId: input.customerId,
+        plan: input.plan,
+        paid: true,
+        ...(quantity !== undefined ? { seats: quantity } : {}),
+      });
+    }
+  }
+  if (input.subscription.status === "canceled" || input.subscription.status === "incomplete_expired") {
+    events.push({
+      id: `${input.subscription.id}:canceled`,
+      type: "customer.subscription.deleted",
+      customerId: input.customerId,
+      canceled: true,
+    });
+    return events;
+  }
+  if (input.subscription.cancel_at_period_end === true) {
+    events.push({
+      id: `${input.subscription.id}:cape`,
+      type: "customer.subscription.updated",
+      customerId: input.customerId,
+      plan: input.plan,
+      cancel_at_period_end: true,
+      period_end: input.subscription.current_period_end,
+      now: input.now,
+      ...(quantity !== undefined ? { seats: quantity } : {}),
+    });
+  }
+  return events;
+}
+
+export function expectedAccess(_id: LiveScenarioId, phase: "trial" | "paid" | "canceled"): AccessSnapshot {
+  if (phase === "paid") return { locked: false, plan: "pro" };
+  return { locked: true };
+}
+
+export async function runLiveLane(
+  adapter: AccessAdapter,
+  client: StripeClockClient,
+  opts: {
+    scenarios?: LiveScenarioId[];
+    now?: () => number;
+    wait?: ClockWaitOpts;
+  } = {},
+): Promise<{ ok: boolean; results: LiveScenarioResult[] }> {
+  const ids = opts.scenarios ?? [...LIVE_SCENARIO_IDS];
+  const results: LiveScenarioResult[] = [];
+  for (const id of ids) {
+    results.push(await runLiveScenario(adapter, client, id, { now: opts.now, wait: opts.wait }));
+  }
+  return { ok: results.every((row) => row.ok), results };
+}
+
+export async function runLiveScenario(
+  adapter: AccessAdapter,
+  client: StripeClockClient,
+  id: LiveScenarioId,
+  opts: { now?: () => number; wait?: ClockWaitOpts } = {},
+): Promise<LiveScenarioResult> {
+  if (!LIVE_SCENARIO_IDS.includes(id)) {
+    throw new Error(`unknown live scenario: ${id}`);
+  }
+  const frozenTime = opts.now?.() ?? Math.floor(Date.now() / 1000);
+  return withTestClock(client, { frozenTime, name: `gatefit-${id}` }, async (clock) => {
+    let customers = 0;
+    let subscriptions = 0;
+    const customer = await client.createCustomer({ testClock: clock.id });
+    customers += 1;
+    if (customers > MAX_CUSTOMERS_PER_CLOCK) {
+      throw new Error("too many customers on this clock");
+    }
+
+    if (id === "trial_to_paid_grants") {
+      const sub = await client.createSubscription({ customer: customer.id, trialPeriodDays: 14 });
+      subscriptions += 1;
+      assertSubCap(subscriptions);
+      await applyAndCheck(adapter, client, customer.id, sub, expectedAccess(id, "trial"), {
+        now: clock.frozen_time,
+      });
+      const ready = await advanceUntilReady(client, clock.id, frozenTime + 15 * 24 * 60 * 60, opts.wait);
+      const after = await client.retrieveSubscription(sub.id);
+      return applyAndCheck(adapter, client, customer.id, after, expectedAccess(id, "paid"), {
+        id,
+        now: ready.frozen_time,
+      });
+    }
+
+    const sub = await client.createSubscription({ customer: customer.id });
+    subscriptions += 1;
+    assertSubCap(subscriptions);
+    if (id === "paid_grants_access") {
+      return applyAndCheck(adapter, client, customer.id, sub, expectedAccess(id, "paid"), {
+        id,
+        now: clock.frozen_time,
+      });
+    }
+    await applyAndCheck(adapter, client, customer.id, sub, expectedAccess(id, "paid"), {
+      now: clock.frozen_time,
+    });
+    const canceled = await client.cancelSubscription(sub.id);
+    return applyAndCheck(adapter, client, customer.id, canceled, expectedAccess(id, "canceled"), {
+      id,
+      now: clock.frozen_time,
+    });
+  });
+}
+
+function assertSubCap(subscriptions: number): void {
+  if (subscriptions > MAX_SUBSCRIPTIONS_PER_CLOCK) {
+    throw new Error("too many subscriptions on this clock");
+  }
+}
+
+async function applyAndCheck(
+  adapter: AccessAdapter,
+  client: StripeClockClient,
+  customerId: string,
+  subscription: StripeSubscription,
+  expect: AccessSnapshot,
+  meta: { id?: LiveScenarioId; now?: number } = {},
+): Promise<LiveScenarioResult> {
+  if (adapter.reset) await adapter.reset();
+  const invoices = await client.listInvoices(customerId);
+  const events = billingEventsFromStripe({
+    customerId,
+    plan: "pro",
+    subscription,
+    invoices,
+    now: meta.now,
+  });
+  for (const event of events) await adapter.apply(event);
+  const actual = await adapter.snapshot(customerId);
+  const cmp = compareAccess(actual, expect);
+  if (!meta.id) {
+    if (!cmp.ok) throw new Error(cmp.mismatches.join("; "));
+    return { id: "paid_grants_access", ok: true, mismatches: [], customerId };
+  }
+  return { id: meta.id, ok: cmp.ok, mismatches: cmp.mismatches, customerId };
+}

package/src/packs.ts

@@ -0,0 +1,27 @@
+/**
+ * Pro pack registry. Chaos mode registers here and runs only after the license gate.
+ * The stub has no runner and is not a user-facing feature.
+ */
+export type ProPack = {
+  id: string;
+  run?: (ctx: { adapterPath: string; seed: string }) => Promise<number>;
+};
+
+const proPacks = new Map<string, ProPack>();
+
+export function registerProPack(pack: ProPack): void {
+  if (!pack.id || proPacks.has(pack.id)) {
+    throw new Error(`pro pack id is missing or already registered: ${pack.id}`);
+  }
+  proPacks.set(pack.id, pack);
+}
+
+export function getProPack(id: string): ProPack | undefined {
+  return proPacks.get(id);
+}
+
+export function isProPack(id: string): boolean {
+  return proPacks.has(id);
+}
+
+registerProPack({ id: "pro-stub" });

package/src/paths.ts

@@ -0,0 +1,31 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function packageRoot(): string {
+  return process.env.GATEFIT_PACKAGE_ROOT ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function userCwd(): string {
+  return process.env.INIT_CWD ?? process.cwd();
+}
+
+export function goldenDir(): string {
+  return path.join(packageRoot(), "tests/entitlements/goldens");
+}
+
+export function readPackageVersion(): string {
+  const raw = fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8");
+  const pkg = JSON.parse(raw) as { version?: string };
+  if (!pkg.version) throw new Error("package.json missing version");
+  return pkg.version;
+}
+
+export function resolveUserOrPackage(spec: string): string {
+  if (path.isAbsolute(spec) && fs.existsSync(spec)) return spec;
+  const fromUser = path.resolve(userCwd(), spec);
+  if (fs.existsSync(fromUser)) return fromUser;
+  const fromPkg = path.resolve(packageRoot(), spec);
+  if (fs.existsSync(fromPkg)) return fromPkg;
+  throw new Error(`path not found: ${spec}`);
+}

package/src/stripe-clock.ts

@@ -0,0 +1,153 @@
+import { assertNoLiveStripeSecret } from "./access-adapter.ts";
+
+export const STRIPE_API_VERSION = "2025-10-29.clover";
+export const TEST_PAYMENT_METHOD = "pm_card_visa";
+export const MONTH_SECONDS = 30 * 24 * 60 * 60;
+export const MAX_ADVANCE_INTERVALS = 2;
+export const MAX_CUSTOMERS_PER_CLOCK = 3;
+export const MAX_SUBSCRIPTIONS_PER_CLOCK = 3;
+
+export type TestClock = {
+  id: string;
+  status: string;
+  frozen_time: number;
+};
+
+export type StripeCustomer = { id: string };
+export type StripeSubscription = {
+  id: string;
+  status: string;
+  customer: string;
+  cancel_at_period_end?: boolean;
+  current_period_end?: number;
+  items?: { data?: Array<{ quantity?: number }> };
+};
+export type StripeInvoice = { id: string; status: string; paid: boolean; customer: string };
+
+export type StripeClockClient = {
+  createClock(input: { frozenTime: number; name?: string }): Promise<TestClock>;
+  retrieveClock(id: string): Promise<TestClock>;
+  advanceClock(id: string, frozenTime: number): Promise<TestClock>;
+  deleteClock(id: string): Promise<{ id: string; deleted: boolean }>;
+  createCustomer(input: { testClock: string; paymentMethod?: string }): Promise<StripeCustomer>;
+  createSubscription(input: { customer: string; trialPeriodDays?: number }): Promise<StripeSubscription>;
+  retrieveSubscription(id: string): Promise<StripeSubscription>;
+  cancelSubscription(id: string): Promise<StripeSubscription>;
+  listInvoices(customerId: string): Promise<StripeInvoice[]>;
+};
+
+export function requireLiveClockEnabled(env: NodeJS.ProcessEnv = process.env): void {
+  if (env.GATEFIT_LIVE_CLOCK !== "1") {
+    throw new Error("live lane is opt-in: set GATEFIT_LIVE_CLOCK=1");
+  }
+}
+
+export function requireTestModeSecret(env: NodeJS.ProcessEnv = process.env): string {
+  assertNoLiveStripeSecret(JSON.stringify(env));
+  const secret = env.STRIPE_SECRET_KEY ?? env.STRIPE_API_KEY ?? "";
+  assertNoLiveStripeSecret(secret);
+  if (!secret) {
+    throw new Error("live lane requires STRIPE_SECRET_KEY or STRIPE_API_KEY (sk_test_ only)");
+  }
+  if (!secret.startsWith("sk_test_")) {
+    throw new Error("refuse non-test Stripe secret: live lane requires sk_test_");
+  }
+  return secret;
+}
+
+export function assertAdvanceWithinTwoIntervals(
+  from: number,
+  to: number,
+  intervalSeconds: number = MONTH_SECONDS,
+): void {
+  if (to <= from) {
+    throw new Error("advance frozen_time must be after current frozen_time");
+  }
+  if (to > from + MAX_ADVANCE_INTERVALS * intervalSeconds) {
+    throw new Error("advance exceeds two billing intervals");
+  }
+}
+
+export function createStripeClockClient(opts: {
+  secret: string;
+  fetchImpl?: typeof fetch;
+  apiVersion?: string;
+  baseUrl?: string;
+}): StripeClockClient {
+  requireTestModeSecret({ STRIPE_SECRET_KEY: opts.secret });
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const apiVersion = opts.apiVersion ?? STRIPE_API_VERSION;
+  const baseUrl = (opts.baseUrl ?? "https://api.stripe.com").replace(/\/$/, "");
+
+  async function request<T>(method: string, path: string, form?: Record<string, string>): Promise<T> {
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${opts.secret}`,
+      "Stripe-Version": apiVersion,
+    };
+    const init: RequestInit = { method, headers };
+    if (form) {
+      headers["Content-Type"] = "application/x-www-form-urlencoded";
+      init.body = new URLSearchParams(form).toString();
+    }
+    const res = await fetchImpl(`${baseUrl}${path}`, init);
+    const json = (await res.json()) as T & { error?: { message?: string } };
+    if (!res.ok) {
+      const message = json.error?.message ?? `stripe ${method} ${path} failed`;
+      throw new Error(message);
+    }
+    return json;
+  }
+
+  return {
+    createClock(input) {
+      const form: Record<string, string> = { frozen_time: String(input.frozenTime) };
+      if (input.name) form.name = input.name;
+      return request<TestClock>("POST", "/v1/test_helpers/test_clocks", form);
+    },
+    retrieveClock(id) {
+      return request<TestClock>("GET", `/v1/test_helpers/test_clocks/${id}`);
+    },
+    advanceClock(id, frozenTime) {
+      return request<TestClock>("POST", `/v1/test_helpers/test_clocks/${id}/advance`, {
+        frozen_time: String(frozenTime),
+      });
+    },
+    deleteClock(id) {
+      return request<{ id: string; deleted: boolean }>("DELETE", `/v1/test_helpers/test_clocks/${id}`);
+    },
+    createCustomer(input) {
+      const form: Record<string, string> = {
+        test_clock: input.testClock,
+        payment_method: input.paymentMethod ?? TEST_PAYMENT_METHOD,
+        "invoice_settings[default_payment_method]": input.paymentMethod ?? TEST_PAYMENT_METHOD,
+      };
+      return request<StripeCustomer>("POST", "/v1/customers", form);
+    },
+    createSubscription(input) {
+      const form: Record<string, string> = {
+        customer: input.customer,
+        "items[0][price_data][currency]": "usd",
+        "items[0][price_data][product_data][name]": "gatefit-pro",
+        "items[0][price_data][recurring][interval]": "month",
+        "items[0][price_data][unit_amount]": "2000",
+      };
+      if (input.trialPeriodDays !== undefined) {
+        form.trial_period_days = String(input.trialPeriodDays);
+      }
+      return request<StripeSubscription>("POST", "/v1/subscriptions", form);
+    },
+    retrieveSubscription(id) {
+      return request<StripeSubscription>("GET", `/v1/subscriptions/${id}`);
+    },
+    cancelSubscription(id) {
+      return request<StripeSubscription>("DELETE", `/v1/subscriptions/${id}`);
+    },
+    async listInvoices(customerId) {
+      const payload = await request<{ data: StripeInvoice[] }>(
+        "GET",
+        `/v1/invoices?customer=${encodeURIComponent(customerId)}`,
+      );
+      return payload.data ?? [];
+    },
+  };
+}

package/tests/entitlements/goldens/cancel_at_period_end_keeps_access_until_end.yaml

@@ -0,0 +1,36 @@
+id: cancel_at_period_end_keeps_access_until_end
+subject: cus_h6_cape
+steps:
+  - event:
+      id: evt_h6_cape_paid
+      type: invoice.paid
+      customerId: cus_h6_cape
+      plan: pro
+      seats: 1
+    expect:
+      locked: false
+      plan: pro
+      seats: 1
+  - event:
+      id: evt_h6_cape_set
+      type: customer.subscription.updated
+      customerId: cus_h6_cape
+      cancel_at_period_end: true
+      period_end: 1577923200
+      now: 1577836800
+      plan: pro
+      seats: 1
+    expect:
+      locked: false
+      plan: pro
+      seats: 1
+  - event:
+      id: evt_h6_cape_period_end
+      type: customer.subscription.updated
+      customerId: cus_h6_cape
+      cancel_at_period_end: true
+      period_end: 1577923200
+      now: 1577923200
+      plan: pro
+    expect:
+      locked: true

package/tests/entitlements/goldens/cancel_revokes_access.yaml

@@ -0,0 +1,18 @@
+id: cancel_revokes_access
+subject: cus_s2
+steps:
+  - event:
+      id: evt_s2_invoice_paid
+      type: invoice.paid
+      customerId: cus_s2
+      plan: pro
+    expect:
+      locked: false
+      plan: pro
+  - event:
+      id: evt_s2_subscription_deleted
+      type: customer.subscription.deleted
+      customerId: cus_s2
+      canceled: true
+    expect:
+      locked: true

package/tests/entitlements/goldens/dispute_revokes_or_flags.yaml

@@ -0,0 +1,29 @@
+# Assumed policy: charge.dispute.created revokes access (locked: true)
+# and flags the row by clearing features. Plan/seats stay. Fixture-only;
+# dispute + Stripe Test Clocks flake (auto-cancel delay).
+id: dispute_revokes_or_flags
+subject: cus_h7_dispute
+steps:
+  - event:
+      id: evt_h7_dispute_paid
+      type: invoice.paid
+      customerId: cus_h7_dispute
+      plan: pro
+      seats: 1
+      features:
+        - team
+    expect:
+      locked: false
+      plan: pro
+      seats: 1
+      features:
+        - team
+  - event:
+      id: evt_h7_dispute_created
+      type: charge.dispute.created
+      customerId: cus_h7_dispute
+    expect:
+      locked: true
+      plan: pro
+      seats: 1
+      features: []

package/tests/entitlements/goldens/duplicate_webhook_idempotent.yaml

@@ -0,0 +1,33 @@
+id: duplicate_webhook_idempotent
+subject: cus_s6
+steps:
+  - event:
+      id: evt_s6_invoice_paid
+      type: invoice.paid
+      customerId: cus_s6
+      plan: pro
+    expect:
+      locked: false
+      plan: pro
+  - event:
+      id: evt_s6_invoice_paid
+      type: invoice.paid
+      customerId: cus_s6
+      plan: pro
+    expect:
+      locked: false
+      plan: pro
+  - event:
+      id: evt_s6_subscription_deleted
+      type: customer.subscription.deleted
+      customerId: cus_s6
+      canceled: true
+    expect:
+      locked: true
+  - event:
+      id: evt_s6_invoice_paid
+      type: invoice.paid
+      customerId: cus_s6
+      plan: pro
+    expect:
+      locked: true

package/tests/entitlements/goldens/paid_grants_access.yaml

@@ -0,0 +1,11 @@
+id: paid_grants_access
+subject: cus_s1
+steps:
+  - event:
+      id: evt_s1_invoice_paid
+      type: invoice.paid
+      customerId: cus_s1
+      plan: pro
+    expect:
+      locked: false
+      plan: pro

package/tests/entitlements/goldens/past_due_denies_until_recovery.yaml

@@ -0,0 +1,26 @@
+id: past_due_denies_until_recovery
+subject: cus_s5
+steps:
+  - event:
+      id: evt_s5_invoice_paid
+      type: invoice.paid
+      customerId: cus_s5
+      plan: pro
+    expect:
+      locked: false
+      plan: pro
+  - event:
+      id: evt_s5_payment_failed
+      type: invoice.payment_failed
+      customerId: cus_s5
+      status: past_due
+    expect:
+      locked: true
+  - event:
+      id: evt_s5_recovered
+      type: invoice.paid
+      customerId: cus_s5
+      plan: pro
+    expect:
+      locked: false
+      plan: pro

package/tests/entitlements/goldens/refund_revokes_access.yaml

@@ -0,0 +1,18 @@
+id: refund_revokes_access
+subject: cus_s3
+steps:
+  - event:
+      id: evt_s3_invoice_paid
+      type: invoice.paid
+      customerId: cus_s3
+      plan: pro
+    expect:
+      locked: false
+      plan: pro
+  - event:
+      id: evt_s3_charge_refunded
+      type: charge.refunded
+      customerId: cus_s3
+      refunded: true
+    expect:
+      locked: true

package/tests/entitlements/goldens/seat_qty_vs_db_cap.yaml

@@ -0,0 +1,29 @@
+id: seat_qty_vs_db_cap
+subject: cus_h6_seats
+steps:
+  - event:
+      id: evt_h6_seats_paid_10
+      type: invoice.paid
+      customerId: cus_h6_seats
+      plan: pro
+      seats: 10
+      features:
+        - team
+    expect:
+      locked: false
+      plan: pro
+      seats: 10
+      features:
+        - team
+  - event:
+      id: evt_h6_seats_qty_3
+      type: customer.subscription.updated
+      customerId: cus_h6_seats
+      plan: pro
+      seats: 3
+    expect:
+      locked: false
+      plan: pro
+      seats: 3
+      features:
+        - team

package/tests/entitlements/goldens/trial_to_paid_grants.yaml

@@ -0,0 +1,19 @@
+id: trial_to_paid_grants
+subject: cus_s4
+steps:
+  - event:
+      id: evt_s4_trialing
+      type: customer.subscription.updated
+      customerId: cus_s4
+      status: trialing
+      plan: pro
+    expect:
+      locked: true
+  - event:
+      id: evt_s4_invoice_paid
+      type: invoice.paid
+      customerId: cus_s4
+      plan: pro
+    expect:
+      locked: false
+      plan: pro

package/tests/entitlements/goldens/unpaid_after_retries_revokes.yaml

@@ -0,0 +1,40 @@
+# Assumed policy: past_due denies, then unpaid after retries exhaust
+# revokes (locked: true). Immediate cancel stays locked. Fixture-only.
+id: unpaid_after_retries_revokes
+subject: cus_h7_unpaid
+steps:
+  - event:
+      id: evt_h7_unpaid_paid
+      type: invoice.paid
+      customerId: cus_h7_unpaid
+      plan: pro
+      seats: 1
+    expect:
+      locked: false
+      plan: pro
+      seats: 1
+  - event:
+      id: evt_h7_unpaid_past_due
+      type: invoice.payment_failed
+      customerId: cus_h7_unpaid
+      status: past_due
+    expect:
+      locked: true
+  - event:
+      id: evt_h7_unpaid_exhaust
+      type: customer.subscription.updated
+      customerId: cus_h7_unpaid
+      status: unpaid
+      plan: pro
+      seats: 1
+    expect:
+      locked: true
+      plan: pro
+      seats: 1
+  - event:
+      id: evt_h7_unpaid_canceled
+      type: customer.subscription.deleted
+      customerId: cus_h7_unpaid
+      canceled: true
+    expect:
+      locked: true