gatefit 0.0.0-stage → 0.4.0

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

package/tests/entitlements/goldens/upgrade_plus_cape_race.yaml

@@ -0,0 +1,46 @@
+id: upgrade_plus_cape_race
+subject: cus_h6_race
+steps:
+  - event:
+      id: evt_h6_race_starter
+      type: invoice.paid
+      customerId: cus_h6_race
+      plan: starter
+      seats: 1
+    expect:
+      locked: false
+      plan: starter
+      seats: 1
+  - event:
+      id: evt_h6_race_cape
+      type: customer.subscription.updated
+      customerId: cus_h6_race
+      cancel_at_period_end: true
+      period_end: 1577923200
+      now: 1577836800
+      plan: starter
+      seats: 1
+    expect:
+      locked: false
+      plan: starter
+      seats: 1
+  - event:
+      id: evt_h6_race_upgrade
+      type: invoice.paid
+      customerId: cus_h6_race
+      plan: pro
+      seats: 5
+      paid: true
+    expect:
+      locked: false
+      plan: pro
+      seats: 5
+  - event:
+      id: evt_h6_race_period_end
+      type: customer.subscription.updated
+      customerId: cus_h6_race
+      cancel_at_period_end: true
+      period_end: 1577923200
+      now: 1577923200
+    expect:
+      locked: true