@auth-gate/testing 0.9.2 → 0.10.0

package/README.md

@@ -0,0 +1,182 @@
+<p align="center">
+  <img src="icon.png" alt="AuthGate" width="120" height="120" />
+</p>
+
+# @auth-gate/testing
+
+Testing utilities for [AuthGate](https://www.authgate.dev) — E2E helpers (Playwright/Cypress), in-memory billing test harness, and RBAC permission testing.
+
+## Installation
+
+```bash
+npm install -D @auth-gate/testing
+```
+
+**Optional peer dependencies:** `@playwright/test >= 1.40`, `cypress >= 12`, `@auth-gate/billing >= 0.1.0`, `@auth-gate/rbac >= 0.1.0`
+
+## Core API
+
+```ts
+import { AuthGateTest } from "@auth-gate/testing";
+
+const testing = new AuthGateTest({
+  apiKey: process.env.AUTHGATE_API_KEY!,
+  baseUrl: process.env.AUTHGATE_URL!,
+});
+
+// Create a test user with an immediate session
+const user = await testing.createUser({
+  email: "alice@test.authgate.dev",
+  password: "test-password-123",
+  name: "Alice Test",
+});
+// Returns: { id, email, name, token, refreshToken, expiresAt }
+
+// Create a new session for an existing user
+const session = await testing.createSession(user.id);
+
+// Create a test organization
+const org = await testing.createOrg({ name: "Acme Corp" });
+
+// Create a test role
+const role = await testing.createRole({
+  key: "editor",
+  name: "Editor",
+  permissions: ["documents:read", "documents:write"],
+});
+
+// Add a member to an organization
+const member = await testing.addMember(org.id, user.id, "editor");
+
+// Clean up all test users
+const result = await testing.cleanup();
+// { deleted: 3 }
+```
+
+## Playwright
+
+```ts
+import { AuthGateTest } from "@auth-gate/testing/playwright";
+
+// In your test setup
+const testing = new AuthGateTest({
+  apiKey: process.env.AUTHGATE_API_KEY!,
+  baseUrl: process.env.AUTHGATE_URL!,
+});
+
+test("authenticated user sees dashboard", async ({ page }) => {
+  const user = await testing.createUser({
+    email: "test@test.authgate.dev",
+    password: "password123",
+  });
+
+  // Inject the session cookie
+  await testing.injectSession(page, user);
+
+  await page.goto("/dashboard");
+  await expect(page.locator("h1")).toContainText("Dashboard");
+});
+
+test.afterAll(async () => {
+  await testing.cleanup();
+});
+```
+
+## Cypress
+
+```ts
+import { AuthGateTest } from "@auth-gate/testing/cypress";
+
+const testing = new AuthGateTest({
+  apiKey: Cypress.env("AUTHGATE_API_KEY"),
+  baseUrl: Cypress.env("AUTHGATE_URL"),
+});
+
+beforeEach(() => {
+  cy.wrap(
+    testing.createUser({
+      email: "test@test.authgate.dev",
+      password: "password123",
+    })
+  ).then((user) => {
+    testing.injectSession(user);
+  });
+});
+
+afterEach(() => {
+  cy.wrap(testing.cleanup());
+});
+```
+
+## Test Users
+
+Test user emails must end with `@test.authgate.dev`. The OTP code for test users is always `000000`.
+
+```ts
+import { TEST_EMAIL_DOMAIN, TEST_OTP_CODE } from "@auth-gate/testing";
+
+// TEST_EMAIL_DOMAIN = "test.authgate.dev"
+// TEST_OTP_CODE = "000000"
+```
+
+## API Reference
+
+### `AuthGateTest`
+
+| Method | Description |
+|--------|-------------|
+| `createUser(options)` | Create a test user with immediate session |
+| `createSession(userId)` | Create a new session for an existing user |
+| `deleteUser(userId)` | Delete a single test user |
+| `cleanup()` | Delete all test users in the project |
+| `createOrg(options)` | Create a test organization |
+| `createRole(options)` | Create a test role with permissions |
+| `addMember(orgId, userId, roleKey)` | Add a user to an organization |
+
+## Billing test utilities (`@auth-gate/testing/billing`)
+
+In-memory billing harness for unit-testing subscription logic, entitlement checks, and usage-based billing.
+
+```bash
+npm install -D @auth-gate/testing @auth-gate/billing
+```
+
+```ts
+import { createTestBilling } from "@auth-gate/testing/billing";
+import { billing } from "./authgate.billing";
+
+const t = createTestBilling({ billing });
+
+t.subscribe("user_1", "pro");
+t.reportUsage("user_1", "api_calls", 500);
+t.advanceTime({ months: 1 });
+
+const check = t.checkEntitlement("user_1", "api_calls");
+// { type: "metered", allowed: true, limit: 100000, used: 0, remaining: 100000 }
+```
+
+## RBAC test utilities (`@auth-gate/testing/rbac`)
+
+Config builders, in-memory permission checker, and assertion helpers for RBAC configurations.
+
+```bash
+npm install -D @auth-gate/testing @auth-gate/rbac
+```
+
+```ts
+import { defineRbac } from "@auth-gate/rbac";
+import { RbacChecker, expectPermission, expectNoPermission } from "@auth-gate/testing/rbac";
+
+const rbac = defineRbac({ /* ... */ });
+const checker = new RbacChecker(rbac);
+
+checker.hasPermission("admin", "documents:delete"); // true
+checker.getPermissions("viewer"); // Set { "documents:read" }
+
+expectPermission(rbac, "admin", "documents:write");
+expectNoPermission(rbac, "viewer", "documents:delete");
+```
+
+## License
+
+MIT

package/dist/billing/index.cjs

@@ -0,0 +1,282 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/billing/index.ts
+var billing_exports = {};
+__export(billing_exports, {
+  EntitlementChecker: () => EntitlementChecker,
+  InMemoryStore: () => InMemoryStore,
+  TestClock: () => TestClock,
+  computeDiff: () => import_billing.computeDiff,
+  createTestBilling: () => createTestBilling,
+  priceConfigKey: () => import_billing.priceConfigKey
+});
+module.exports = __toCommonJS(billing_exports);
+
+// src/billing/clock.ts
+var TestClock = class {
+  constructor(startDate) {
+    this._now = startDate ? new Date(startDate) : /* @__PURE__ */ new Date("2025-01-01T00:00:00Z");
+  }
+  now() {
+    return new Date(this._now);
+  }
+  advance(options) {
+    const next = new Date(this._now);
+    if (options.days) {
+      next.setUTCDate(next.getUTCDate() + options.days);
+    }
+    if (options.months) {
+      next.setUTCMonth(next.getUTCMonth() + options.months);
+    }
+    this._now = next;
+    return this.now();
+  }
+  /**
+   * Check if advancing from `before` to `after` crosses a billing boundary.
+   */
+  crossesBoundary(before, after, boundary) {
+    if (boundary === "month_end") {
+      return before.getUTCMonth() !== after.getUTCMonth() || before.getUTCFullYear() !== after.getUTCFullYear();
+    }
+    if (boundary === "year_end") {
+      return before.getUTCFullYear() !== after.getUTCFullYear();
+    }
+    return false;
+  }
+};
+
+// src/billing/store.ts
+var InMemoryStore = class {
+  constructor() {
+    this.subscriptions = /* @__PURE__ */ new Map();
+    this.usage = [];
+    this.nextId = 1;
+  }
+  createSubscription(params) {
+    var _a, _b;
+    const id = `sub_${this.nextId++}`;
+    const sub = {
+      id,
+      userId: params.userId,
+      planKey: params.planKey,
+      priceIndex: (_a = params.priceIndex) != null ? _a : 0,
+      status: (_b = params.status) != null ? _b : "active",
+      currentPeriodStart: params.periodStart,
+      currentPeriodEnd: params.periodEnd,
+      cancelAtPeriodEnd: false,
+      createdAt: new Date(params.periodStart)
+    };
+    this.subscriptions.set(id, sub);
+    return sub;
+  }
+  getSubscription(id) {
+    return this.subscriptions.get(id);
+  }
+  getSubscriptionByUser(userId) {
+    for (const sub of this.subscriptions.values()) {
+      if (sub.userId === userId && sub.status !== "canceled") return sub;
+    }
+    return void 0;
+  }
+  updateSubscription(id, updates) {
+    const sub = this.subscriptions.get(id);
+    if (!sub) return void 0;
+    Object.assign(sub, updates);
+    return sub;
+  }
+  listSubscriptions(filter) {
+    let subs = [...this.subscriptions.values()];
+    if (filter == null ? void 0 : filter.status) subs = subs.filter((s) => s.status === filter.status);
+    if (filter == null ? void 0 : filter.planKey) subs = subs.filter((s) => s.planKey === filter.planKey);
+    return subs;
+  }
+  recordUsage(userId, metric, quantity, timestamp) {
+    this.usage.push({ userId, metric, quantity, timestamp });
+  }
+  getUsage(userId, metric, periodStart, periodEnd) {
+    return this.usage.filter(
+      (r) => r.userId === userId && r.metric === metric && r.timestamp >= periodStart && r.timestamp < periodEnd
+    ).reduce((sum, r) => sum + r.quantity, 0);
+  }
+  subscriberCount(planKey) {
+    return this.listSubscriptions({ planKey, status: "active" }).length;
+  }
+  clear() {
+    this.subscriptions.clear();
+    this.usage = [];
+    this.nextId = 1;
+  }
+};
+
+// src/billing/entitlements.ts
+var EntitlementChecker = class {
+  constructor(config, store) {
+    this.config = config;
+    this.store = store;
+  }
+  check(userId, feature) {
+    var _a;
+    const sub = this.store.getSubscriptionByUser(userId);
+    if (!sub) {
+      return { type: "boolean", feature, allowed: false };
+    }
+    const plan = this.config.plans[sub.planKey];
+    if (!plan) {
+      return { type: "boolean", feature, allowed: false };
+    }
+    if (plan.entitlements) {
+      const value = plan.entitlements[feature];
+      if (value === void 0) {
+        return { type: "boolean", feature, allowed: false };
+      }
+      if (value === true) {
+        return { type: "boolean", feature, allowed: true };
+      }
+      if (typeof value === "object" && "limit" in value) {
+        const used = this.store.getUsage(
+          userId,
+          feature,
+          sub.currentPeriodStart,
+          sub.currentPeriodEnd
+        );
+        const limit = value.limit;
+        return {
+          type: "metered",
+          feature,
+          allowed: used < limit,
+          used,
+          limit,
+          remaining: Math.max(0, limit - used)
+        };
+      }
+    }
+    if ((_a = plan.features) == null ? void 0 : _a.includes(feature)) {
+      return { type: "boolean", feature, allowed: true };
+    }
+    return { type: "boolean", feature, allowed: false };
+  }
+  checkAll(userId) {
+    const sub = this.store.getSubscriptionByUser(userId);
+    if (!sub) return {};
+    const plan = this.config.plans[sub.planKey];
+    if (!plan) return {};
+    const result = {};
+    if (plan.entitlements) {
+      for (const feature of Object.keys(plan.entitlements)) {
+        result[feature] = this.check(userId, feature);
+      }
+    }
+    if (plan.features) {
+      for (const feature of plan.features) {
+        if (!result[feature]) {
+          result[feature] = { type: "boolean", feature, allowed: true };
+        }
+      }
+    }
+    return result;
+  }
+};
+
+// src/billing/test-billing.ts
+function getPeriodEnd(start, interval) {
+  const end = new Date(start);
+  if (interval === "monthly") {
+    end.setUTCMonth(end.getUTCMonth() + 1);
+  } else {
+    end.setUTCFullYear(end.getUTCFullYear() + 1);
+  }
+  return end;
+}
+function buildTestBilling(config, startDate) {
+  const clock = new TestClock(startDate);
+  const store = new InMemoryStore();
+  const checker = new EntitlementChecker(config, store);
+  return {
+    clock,
+    store,
+    checker,
+    subscribe(userId, planKey, priceIndex = 0) {
+      const plan = config.plans[planKey];
+      if (!plan) throw new Error(`Plan "${planKey}" not found in config`);
+      if (!plan.prices[priceIndex]) throw new Error(`Price index ${priceIndex} not found on plan "${planKey}"`);
+      const existing = store.getSubscriptionByUser(userId);
+      if (existing) throw new Error(`User "${userId}" already has an active subscription (${existing.planKey})`);
+      const now = clock.now();
+      const interval = plan.prices[priceIndex].interval;
+      return store.createSubscription({
+        userId,
+        planKey,
+        priceIndex,
+        periodStart: now,
+        periodEnd: getPeriodEnd(now, interval)
+      });
+    },
+    changePlan(userId, newPlanKey, priceIndex = 0) {
+      const sub = store.getSubscriptionByUser(userId);
+      if (!sub) throw new Error(`User "${userId}" has no active subscription`);
+      const plan = config.plans[newPlanKey];
+      if (!plan) throw new Error(`Plan "${newPlanKey}" not found in config`);
+      if (!plan.prices[priceIndex]) throw new Error(`Price index ${priceIndex} not found on plan "${newPlanKey}"`);
+      store.updateSubscription(sub.id, { planKey: newPlanKey, priceIndex });
+      return store.getSubscription(sub.id);
+    },
+    cancel(userId) {
+      const sub = store.getSubscriptionByUser(userId);
+      if (!sub) throw new Error(`User "${userId}" has no active subscription`);
+      store.updateSubscription(sub.id, { cancelAtPeriodEnd: true });
+      return store.getSubscription(sub.id);
+    },
+    reportUsage(userId, metric, quantity) {
+      store.recordUsage(userId, metric, quantity, clock.now());
+    },
+    checkEntitlement(userId, feature) {
+      return checker.check(userId, feature);
+    },
+    getSubscription(userId) {
+      return store.getSubscriptionByUser(userId);
+    },
+    advanceTime(options) {
+      return clock.advance(options);
+    },
+    subscriberCounts() {
+      const counts = {};
+      for (const planKey of Object.keys(config.plans)) {
+        counts[planKey] = store.subscriberCount(planKey);
+      }
+      return counts;
+    }
+  };
+}
+function createTestBilling(options) {
+  const config = "billing" in options ? options.billing._config : options.config;
+  return buildTestBilling(config, options.startDate);
+}
+
+// src/billing/index.ts
+var import_billing = require("@auth-gate/billing");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EntitlementChecker,
+  InMemoryStore,
+  TestClock,
+  computeDiff,
+  createTestBilling,
+  priceConfigKey
+});

package/dist/billing/index.d.cts

@@ -0,0 +1,129 @@
+import { BillingConfig, TypedBilling, PlanKey, FeatureKey } from '@auth-gate/billing';
+export { computeDiff, priceConfigKey } from '@auth-gate/billing';
+
+interface AdvanceOptions {
+    days?: number;
+    months?: number;
+}
+type BillingBoundary = "month_end" | "year_end";
+declare class TestClock {
+    private _now;
+    constructor(startDate?: Date);
+    now(): Date;
+    advance(options: AdvanceOptions): Date;
+    /**
+     * Check if advancing from `before` to `after` crosses a billing boundary.
+     */
+    crossesBoundary(before: Date, after: Date, boundary: BillingBoundary): boolean;
+}
+
+interface Subscription {
+    id: string;
+    userId: string;
+    planKey: string;
+    priceIndex: number;
+    status: "active" | "canceled" | "past_due" | "trialing";
+    currentPeriodStart: Date;
+    currentPeriodEnd: Date;
+    cancelAtPeriodEnd: boolean;
+    createdAt: Date;
+}
+interface UsageRecord {
+    userId: string;
+    metric: string;
+    quantity: number;
+    timestamp: Date;
+}
+declare class InMemoryStore {
+    private subscriptions;
+    private usage;
+    private nextId;
+    createSubscription(params: {
+        userId: string;
+        planKey: string;
+        priceIndex?: number;
+        status?: Subscription["status"];
+        periodStart: Date;
+        periodEnd: Date;
+    }): Subscription;
+    getSubscription(id: string): Subscription | undefined;
+    getSubscriptionByUser(userId: string): Subscription | undefined;
+    updateSubscription(id: string, updates: Partial<Pick<Subscription, "planKey" | "priceIndex" | "status" | "cancelAtPeriodEnd" | "currentPeriodStart" | "currentPeriodEnd">>): Subscription | undefined;
+    listSubscriptions(filter?: {
+        status?: Subscription["status"];
+        planKey?: string;
+    }): Subscription[];
+    recordUsage(userId: string, metric: string, quantity: number, timestamp: Date): void;
+    getUsage(userId: string, metric: string, periodStart: Date, periodEnd: Date): number;
+    subscriberCount(planKey: string): number;
+    clear(): void;
+}
+
+interface BooleanCheck {
+    type: "boolean";
+    feature: string;
+    allowed: boolean;
+}
+interface MeteredCheck {
+    type: "metered";
+    feature: string;
+    allowed: boolean;
+    used: number;
+    limit: number;
+    remaining: number;
+}
+type EntitlementCheck = BooleanCheck | MeteredCheck;
+declare class EntitlementChecker {
+    private config;
+    private store;
+    constructor(config: BillingConfig, store: InMemoryStore);
+    check(userId: string, feature: string): EntitlementCheck;
+    checkAll(userId: string): Record<string, EntitlementCheck>;
+}
+
+interface TestBillingOptions {
+    config: BillingConfig;
+    startDate?: Date;
+}
+interface TestBilling {
+    clock: TestClock;
+    store: InMemoryStore;
+    checker: EntitlementChecker;
+    subscribe(userId: string, planKey: string, priceIndex?: number): Subscription;
+    changePlan(userId: string, newPlanKey: string, priceIndex?: number): Subscription;
+    cancel(userId: string): Subscription;
+    reportUsage(userId: string, metric: string, quantity: number): void;
+    checkEntitlement(userId: string, feature: string): EntitlementCheck;
+    getSubscription(userId: string): Subscription | undefined;
+    advanceTime(options: {
+        days?: number;
+        months?: number;
+    }): Date;
+    subscriberCounts(): Record<string, number>;
+}
+interface TypedTestBillingOptions<B extends TypedBilling<any>> {
+    billing: B;
+    startDate?: Date;
+}
+interface TypedTestBilling<B extends TypedBilling<any>> {
+    clock: TestClock;
+    store: InMemoryStore;
+    checker: EntitlementChecker;
+    subscribe(userId: string, planKey: PlanKey<B>, priceIndex?: number): Subscription;
+    changePlan(userId: string, newPlanKey: PlanKey<B>, priceIndex?: number): Subscription;
+    cancel(userId: string): Subscription;
+    reportUsage(userId: string, metric: FeatureKey<B>, quantity: number): void;
+    checkEntitlement(userId: string, feature: FeatureKey<B>): EntitlementCheck;
+    getSubscription(userId: string): Subscription | undefined;
+    advanceTime(options: {
+        days?: number;
+        months?: number;
+    }): Date;
+    subscriberCounts(): Record<PlanKey<B>, number>;
+}
+/** Create typed test billing from a `defineBilling()` config. */
+declare function createTestBilling<B extends TypedBilling<any>>(options: TypedTestBillingOptions<B>): TypedTestBilling<B>;
+/** Create untyped test billing (legacy). */
+declare function createTestBilling(options: TestBillingOptions): TestBilling;
+
+export { type AdvanceOptions, type BillingBoundary, type BooleanCheck, type EntitlementCheck, EntitlementChecker, InMemoryStore, type MeteredCheck, type Subscription, type TestBilling, type TestBillingOptions, TestClock, type TypedTestBilling, type TypedTestBillingOptions, type UsageRecord, createTestBilling };