@auth-gate/billing

Billing as code for AuthGate — define plans, prices, and features in TypeScript and sync them to AuthGate + Stripe with a single CLI command.

Installation

npm install @auth-gate/billing

Optional peer dependency: stripe >= 14 (required for Stripe sync)

Quick Start

1. Generate a starter config

npx @auth-gate/billing init

2. Define your billing config

// authgate.billing.ts
import { defineBilling } from "@auth-gate/billing";

export const billing = defineBilling({
  features: {
    api_calls: { type: "metered" },
    analytics: { type: "boolean" },
    seats: { type: "metered" },
  },
  plans: {
    free: {
      name: "Free",
      prices: [{ amount: 0, interval: "monthly" }],
      entitlements: {
        api_calls: { limit: 1000 },
        analytics: false,
      },
    },
    pro: {
      name: "Pro",
      prices: [
        { amount: 2900, interval: "monthly" },
        { amount: 29000, interval: "yearly" },
      ],
      entitlements: {
        api_calls: { limit: 100000 },
        analytics: true,
        seats: { limit: 10 },
      },
    },
  },
});

3. Sync to AuthGate + Stripe

export AUTHGATE_API_KEY=ag_...
export AUTHGATE_BASE_URL=https://www.authgate.dev

npx @auth-gate/billing diff   # Preview changes
npx @auth-gate/billing sync   # Apply changes

Type Safety

defineBilling() infers plan and feature keys as literal types for full IDE autocomplete.

billing.plans.pro.key           // "pro" (literal type)
billing.plans.pro.name          // "Pro"
billing.plans.pro.entitlements  // { api_calls: { limit: 100000 }, ... }
billing.features.api_calls.key  // "api_calls"
billing.features.api_calls.type // "metered"

CLI Commands

| Command | Description | |---------|-------------| | npx @auth-gate/billing init | Generate a starter config file | | npx @auth-gate/billing diff | Preview changes without applying | | npx @auth-gate/billing sync | Apply changes to AuthGate and Stripe | | npx @auth-gate/billing pull | Pull server state into a local config | | npx @auth-gate/billing sync --json | Output JSON for CI/CD integration |

Features

• Type-safe plans — plan and feature keys are literal types
• Multiple price models — recurring, per-seat, metered, and tiered pricing
• Feature entitlements — boolean and metered feature gates per plan
• Diff before sync — preview all plan and price changes before applying
• Revenue impact — see estimated revenue impact of plan changes
• Rename migrations — rename plans without losing subscribers via renamedFrom
• Grandfathering — configure how existing subscribers are handled on plan changes
• Pull workflow — import existing Stripe products as a local config
• Coexists with dashboard — plans created in the dashboard are preserved

Related Packages

• @auth-gate/testing/billing — test utilities with in-memory store and simulated time (via @auth-gate/testing)
• @auth-gate/billing-action — GitHub Action for CI/CD billing sync

License

MIT