// apps/api/src/entitlements/plans.catalog.spec.ts
import { describe, it, expect } from 'vitest'
import { PLANS, PLAN_IDS, isPlanId, planIdOrFree } from './plans.catalog'

describe('plans.catalog', () => {
  it('defines exactly free/pro/team/enterprise', () => {
    expect(PLAN_IDS.sort()).toEqual(['enterprise', 'free', 'pro', 'team'])
  })

  it('never gates knowledge — projects/collections are the only numeric ceilings besides seats/workspaces/repos', () => {
    for (const plan of PLAN_IDS) {
      const keys = Object.keys(PLANS[plan]).sort()
      expect(keys).toEqual(['collections', 'features', 'projects', 'repos', 'seats', 'workspaces'])
    }
  })

  it('free: 1 seat, 1 workspace, 1 repo, 5 projects, 5 collections, no byom_chat/broker', () => {
    expect(PLANS.free).toEqual({
      seats: 1, workspaces: 1, repos: 1, projects: 5, collections: 5,
      features: { byom_chat: false, broker: false },
    })
  })

  it('pro: 1 seat, 3 workspaces, unlimited projects/collections, byom_chat true, broker false', () => {
    expect(PLANS.pro).toEqual({
      seats: 1, workspaces: 3, repos: 1, projects: null, collections: null,
      features: { byom_chat: true, broker: false },
    })
  })

  it('team: 5 seats, 1 workspace, unlimited repos/projects/collections, byom_chat + broker true', () => {
    expect(PLANS.team).toEqual({
      seats: 5, workspaces: 1, repos: null, projects: null, collections: null,
      features: { byom_chat: true, broker: true },
    })
  })

  it('enterprise: everything unlimited/true', () => {
    expect(PLANS.enterprise).toEqual({
      seats: null, workspaces: null, repos: null, projects: null, collections: null,
      features: { byom_chat: true, broker: true },
    })
  })

  it('isPlanId / planIdOrFree', () => {
    expect(isPlanId('team')).toBe(true)
    expect(isPlanId('bogus')).toBe(false)
    expect(planIdOrFree('team')).toBe('team')
    expect(planIdOrFree(undefined)).toBe('free')
    expect(planIdOrFree('bogus')).toBe('free')
  })
})

// apps/api/src/entitlements/plans.catalog.ts
// The pricing model as DATA — the single editable source of truth for what each
// tier unlocks. Changing a number or moving a capability between tiers is an edit
// here, never a refactor: features ask EntitlementsService.can()/assert*(), they
// never branch on the plan. Stripe only decides WHO moves workspaces.plan and
// meters Team's per-unit overage; this table is unchanged by it.
//
// Design principles:
//   - Knowledge is NEVER gated: `topics` does not appear here → unlimited on every
//     plan, Free included. Gating knowledge would kill the aha + data gravity.
//   - Projects/Collections are the OPERATIONAL axis — free but capped on Free (5
//     each), unlimited from Pro up. Never an on/off feature flag, always a count.
//   - byom_chat covers BOTH the workspace assistant (Chat) and the BYOM agents
//     (Auditor/Architect) — both run through the same model-gateway, so one flag
//     covers the whole "bring your own model" surface.
//   - broker gates the integrations surface (Notion/Drive/etc connections) —
//     Team+ only. This is separate from DRIFTLESS_BROKER_ENABLED (broker-feature.ts),
//     which is an environment-level kill switch, not a plan gate.
//   - Team is "~$15/seat with a floor of 5": $49 for up to 5 seats + $15/seat extra
//     (+$15/workspace). Phase 1 enforces the INCLUDED quantities as hard caps; the
//     overage is billed via Stripe quantity line items (Task 11+).
//   - `null` = unlimited (skip the check).

export type PlanId = 'free' | 'pro' | 'team' | 'enterprise'

export type FeatureKey = 'byom_chat' | 'broker'

export interface PlanDef {
  /** Members allowed in one workspace. null = unlimited. */
  seats: number | null
  /** Workspaces one account may own (account-level; see EntitlementsService). null = unlimited. */
  workspaces: number | null
  /** Repos connected to one workspace. null = unlimited. */
  repos: number | null
  /** Projects (kanban boards) in one workspace. null = unlimited. */
  projects: number | null
  /** Collections (CRM/pipelines) in one workspace. null = unlimited. */
  collections: number | null
  features: Record<FeatureKey, boolean>
}

export const PLANS: Record<PlanId, PlanDef> = {
  free: {
    seats: 1, workspaces: 1, repos: 1, projects: 5, collections: 5,
    features: { byom_chat: false, broker: false },
  },
  pro: {
    seats: 1, workspaces: 3, repos: 1, projects: null, collections: null,
    features: { byom_chat: true, broker: false },
  },
  team: {
    seats: 5, workspaces: 1, repos: null, projects: null, collections: null,
    features: { byom_chat: true, broker: true },
  },
  enterprise: {
    seats: null, workspaces: null, repos: null, projects: null, collections: null,
    features: { byom_chat: true, broker: true },
  },
}

export const PLAN_IDS = Object.keys(PLANS) as PlanId[]

export function isPlanId(value: unknown): value is PlanId {
  return typeof value === 'string' && (PLAN_IDS as string[]).includes(value)
}

// The plan a row resolves to, defaulting unknown/empty values to 'free' so a bad
// column value can never silently grant a paid capability.
export function planIdOrFree(value: unknown): PlanId {
  return isPlanId(value) ? value : 'free'
}

// libs/db/src/migrations/1715200000102-AddWorkspacePlan.ts
import { MigrationInterface, QueryRunner } from 'typeorm'

// Billing tier column. Source of truth for entitlements (EntitlementsService
// resolves PLANS[plan] merged with settings.billing.overrides). Defaults every
// existing workspace to 'free' — correct, since no plan existed before this.
export class AddWorkspacePlan1715200000102 implements MigrationInterface {
  name = 'AddWorkspacePlan1715200000102'

  public async up(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE workspaces ADD COLUMN IF NOT EXISTS plan text NOT NULL DEFAULT 'free'`)
  }

  public async down(queryRunner: QueryRunner): Promise<void> {
    await queryRunner.query(`ALTER TABLE workspaces DROP COLUMN IF EXISTS plan`)
  }
}

import { AddWorkspacePlan1715200000102 } from './migrations/1715200000102-AddWorkspacePlan'

  // Billing tier. Source of truth for entitlements (EntitlementsService resolves
  // PLANS[plan] merged with settings.billing.overrides). Set via the admin setPlan
  // endpoint or the Stripe webhook (same seam).
  @Column({ type: 'text', default: 'free' })
  plan: string

git add apps/api/src/entitlements/plans.catalog.ts apps/api/src/entitlements/plans.catalog.spec.ts \
  libs/db/src/migrations/1715200000102-AddWorkspacePlan.ts libs/db/src/entities/workspace.entity.ts \
  libs/db/src/data-source.ts
git commit -m "feat(entitlements): plans-as-data catalog + workspace.plan column"

  // Billing: a feature/limit the workspace's plan doesn't include, or would
  // exceed the workspace's plan, or would exceed a plan's included quantity. The
  // dashboard/CLI branch on these to surface an upgrade prompt.
  FEATURE_NOT_IN_PLAN: 'FEATURE_NOT_IN_PLAN',
  PLAN_LIMIT_EXCEEDED: 'PLAN_LIMIT_EXCEEDED',

// apps/api/src/entitlements/entitlements.service.spec.ts
import { describe, it, expect, beforeEach } from 'vitest'
import { Test } from '@nestjs/testing'
import { ConfigService } from '@nestjs/config'
import { getRepositoryToken } from '@nestjs/typeorm'
import { Workspace, WorkspaceMember, Repo, Project, Collection } from '@driftless/db'
import { EntitlementsService } from './entitlements.service'
import { DomainException } from '../ops/error-codes'

function fakeRepo(rows: any[] = []) {
  return {
    findOne: async ({ where }: any) => rows.find((r) => Object.entries(where).every(([k, v]) => r[k] === v)) ?? null,
    find: async ({ where }: any = {}) =>
      rows.filter((r) => !where || Object.entries(where).every(([k, v]) => (v as any)?.['_type'] === 'In' ? (v as any).values.includes(r[k]) : r[k] === v)),
    count: async ({ where }: any) => rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v)).length,
  }
}

describe('EntitlementsService', () => {
  let workspaces: any[]
  let members: any[]
  let repos: any[]
  let projects: any[]
  let collections: any[]
  let enforce = 'false'

  async function build() {
    const moduleRef = await Test.createTestingModule({
      providers: [
        EntitlementsService,
        { provide: getRepositoryToken(Workspace), useValue: fakeRepo(workspaces) },
        { provide: getRepositoryToken(WorkspaceMember), useValue: fakeRepo(members) },
        { provide: getRepositoryToken(Repo), useValue: fakeRepo(repos) },
        { provide: getRepositoryToken(Project), useValue: fakeRepo(projects) },
        { provide: getRepositoryToken(Collection), useValue: fakeRepo(collections) },
        { provide: ConfigService, useValue: { get: (k: string) => (k === 'ENTITLEMENTS_ENFORCE' ? enforce : undefined) } },
      ],
    }).compile()
    return moduleRef.get(EntitlementsService)
  }

  beforeEach(() => {
    workspaces = [{ id: 'ws1', plan: 'free', settings: {} }]
    members = []
    repos = []
    projects = []
    collections = []
    enforce = 'false'
  })

  it('resolve() defaults an unknown plan to free', async () => {
    workspaces[0].plan = 'bogus'
    const svc = await build()
    const { plan, def } = await svc.resolve('ws1')
    expect(plan).toBe('free')
    expect(def.seats).toBe(1)
  })

  it('resolve() merges settings.billing.overrides over the base plan', async () => {
    workspaces[0].settings = { billing: { overrides: { seats: 99 } } }
    const svc = await build()
    const { def } = await svc.resolve('ws1')
    expect(def.seats).toBe(99)
  })

  it('assertFeature does not throw when enforcement is off, even if the plan lacks the feature', async () => {
    const svc = await build()
    await expect(svc.assertFeature('ws1', 'broker')).resolves.toBeUndefined()
  })

  it('assertFeature throws PAYMENT_REQUIRED/FEATURE_NOT_IN_PLAN when enforcement is on and the plan lacks the feature', async () => {
    enforce = 'true'
    const svc = await build()
    await expect(svc.assertFeature('ws1', 'broker')).rejects.toMatchObject({
      response: { code: 'FEATURE_NOT_IN_PLAN' },
    })
  })

  it('assertProjectAvailable blocks at the Free ceiling (5) when enforcing, allows below it', async () => {
    enforce = 'true'
    projects = Array.from({ length: 5 }, (_, i) => ({ id: `p${i}`, workspace_id: 'ws1' }))
    const svc = await build()
    await expect(svc.assertProjectAvailable('ws1')).rejects.toMatchObject({
      response: { code: 'PLAN_LIMIT_EXCEEDED' },
    })
    projects.pop()
    await expect(svc.assertProjectAvailable('ws1')).resolves.toBeUndefined()
  })

  it('assertCollectionAvailable is unlimited on team', async () => {
    enforce = 'true'
    workspaces[0].plan = 'team'
    collections = Array.from({ length: 500 }, (_, i) => ({ id: `c${i}`, workspace_id: 'ws1' }))
    const svc = await build()
    await expect(svc.assertCollectionAvailable('ws1')).resolves.toBeUndefined()
  })
})

// apps/api/src/entitlements/entitlements.service.ts
import { Injectable, Logger, HttpStatus } from '@nestjs/common'
import { InjectRepository } from '@nestjs/typeorm'
import { ConfigService } from '@nestjs/config'
import { Repository, In } from 'typeorm'
import { Workspace, WorkspaceMember, Repo, Project, Collection } from '@driftless/db'
import { DomainException, ErrorCode, type ErrorCodeValue } from '../ops/error-codes'
import { PLANS, planIdOrFree, type FeatureKey, type PlanDef, type PlanId } from './plans.catalog'

// The entitlements engine. Resolves the effective plan for a workspace (catalog +
// per-workspace overrides) and answers can()/assert*(). This is the ONLY place that
// knows the pricing model; controllers/services just ask.
//
// ENFORCEMENT IS DECOUPLED FROM DEPLOY. The assert*() limits only BLOCK when
// ENTITLEMENTS_ENFORCE=true. Default OFF: shipping a paywall before Stripe (Task
// 11+) exists would strand active free users with no way to pay — so until the
// webhook is verified end-to-end, the asserts are no-ops that only LOG who they
// WOULD block. resolve()/can() always report the truth; only blocking is gated.
//
// Limits grandfather existing data even when enforcing: an assert blocks only when
// count >= limit, never touching rows already there.
@Injectable()
export class EntitlementsService {
  private readonly logger = new Logger(EntitlementsService.name)

  constructor(
    @InjectRepository(Workspace) private readonly workspaceRepo: Repository<Workspace>,
    @InjectRepository(WorkspaceMember) private readonly memberRepo: Repository<WorkspaceMember>,
    @InjectRepository(Repo) private readonly repoRepo: Repository<Repo>,
    @InjectRepository(Project) private readonly projectRepo: Repository<Project>,
    @InjectRepository(Collection) private readonly collectionRepo: Repository<Collection>,
    private readonly config: ConfigService,
  ) {}

  // The effective PlanDef = PLANS[plan] merged with workspaces.settings.billing.overrides.
  // Overrides let an Enterprise/custom workspace raise a limit or flip a feature
  // without code. A missing/unknown plan resolves to 'free'.
  async resolve(workspaceId: string): Promise<{ plan: PlanId; def: PlanDef }> {
    const ws = await this.workspaceRepo.findOne({ where: { id: workspaceId } })
    const plan = planIdOrFree(ws?.plan)
    const base = PLANS[plan]
    const overrides = this.readOverrides(ws?.settings)
    const def: PlanDef = {
      seats: pick(overrides.seats, base.seats),
      workspaces: pick(overrides.workspaces, base.workspaces),
      repos: pick(overrides.repos, base.repos),
      projects: pick(overrides.projects, base.projects),
      collections: pick(overrides.collections, base.collections),
      features: { ...base.features, ...(overrides.features ?? {}) },
    }
    return { plan, def }
  }

  async can(workspaceId: string, feature: FeatureKey): Promise<boolean> {
    const { def } = await this.resolve(workspaceId)
    return def.features[feature] === true
  }

  async assertFeature(workspaceId: string, feature: FeatureKey): Promise<void> {
    const { plan, def } = await this.resolve(workspaceId)
    if (def.features[feature] !== true) {
      this.deny(ErrorCode.FEATURE_NOT_IN_PLAN, `'${feature}' is not available on the ${plan} plan. Upgrade to unlock it.`)
    }
  }

  async assertSeatAvailable(workspaceId: string): Promise<void> {
    const { plan, def } = await this.resolve(workspaceId)
    if (def.seats === null) return
    const used = await this.memberRepo.count({ where: { workspace_id: workspaceId } })
    if (used >= def.seats) {
      this.deny(ErrorCode.PLAN_LIMIT_EXCEEDED, `The ${plan} plan includes ${def.seats} seat${def.seats === 1 ? '' : 's'}. Upgrade to add more members.`)
    }
  }

  async assertRepoAvailable(workspaceId: string): Promise<void> {
    const { plan, def } = await this.resolve(workspaceId)
    if (def.repos === null) return
    const used = await this.repoRepo.count({ where: { workspace_id: workspaceId } })
    if (used >= def.repos) {
      this.deny(ErrorCode.PLAN_LIMIT_EXCEEDED, `The ${plan} plan includes ${def.repos} repo${def.repos === 1 ? '' : 's'}. Upgrade to connect more.`)
    }
  }

  async assertProjectAvailable(workspaceId: string): Promise<void> {
    const { plan, def } = await this.resolve(workspaceId)
    if (def.projects === null) return
    const used = await this.projectRepo.count({ where: { workspace_id: workspaceId } })
    if (used >= def.projects) {
      this.deny(ErrorCode.PLAN_LIMIT_EXCEEDED, `The ${plan} plan includes ${def.projects} project${def.projects === 1 ? '' : 's'}. Upgrade to create more.`)
    }
  }

  async assertCollectionAvailable(workspaceId: string): Promise<void> {
    const { plan, def } = await this.resolve(workspaceId)
    if (def.collections === null) return
    const used = await this.collectionRepo.count({ where: { workspace_id: workspaceId } })
    if (used >= def.collections) {
      this.deny(ErrorCode.PLAN_LIMIT_EXCEEDED, `The ${plan} plan includes ${def.collections} collection${def.collections === 1 ? '' : 's'}. Upgrade to create more.`)
    }
  }

  // The workspace-count limit is account-level (how many workspaces a person owns),
  // but plans live on the workspace. Heuristic: count the workspaces this user OWNS
  // and compare against the most generous limit among their owned plans.
  async assertWorkspaceAvailable(ownerClerkUserId: string): Promise<void> {
    const owned = await this.memberRepo.find({ where: { clerk_user_id: ownerClerkUserId, role: 'owner' } })
    if (owned.length === 0) return // first workspace is always allowed
    const workspaces = await this.workspaceRepo.find({ where: { id: In(owned.map((m) => m.workspace_id)) } })
    let limit: number | null = 0
    let bestPlan: PlanId = 'free'
    for (const ws of workspaces) {
      const plan = planIdOrFree(ws.plan)
      const wsLimit = this.readOverrides(ws.settings).workspaces ?? PLANS[plan].workspaces
      if (wsLimit === null) return // an unlimited plan among them → allow
      if (wsLimit > (limit ?? 0)) {
        limit = wsLimit
        bestPlan = plan
      }
    }
    if (limit !== null && owned.length >= limit) {
      this.deny(ErrorCode.PLAN_LIMIT_EXCEEDED, `The ${bestPlan} plan includes ${limit} workspace${limit === 1 ? '' : 's'}. Upgrade to create more.`)
    }
  }

  private enforcing(): boolean {
    return this.config.get<string>('ENTITLEMENTS_ENFORCE') === 'true'
  }

  private deny(code: ErrorCodeValue, message: string): void {
    if (this.enforcing()) {
      throw new DomainException(HttpStatus.PAYMENT_REQUIRED, code, message)
    }
    this.logger.log(`[entitlements] would block (${code}): ${message} — enforcement OFF`)
  }

  private readOverrides(settings: Record<string, unknown> | undefined | null): Partial<PlanDef> {
    const billing = (settings as any)?.billing
    const overrides = billing?.overrides
    return overrides && typeof overrides === 'object' ? (overrides as Partial<PlanDef>) : {}
  }
}

function pick<T>(override: T | null | undefined, base: T): T {
  return override === undefined ? base : (override as T)
}

git add apps/api/src/entitlements/entitlements.service.ts apps/api/src/entitlements/entitlements.service.spec.ts \
  apps/api/src/ops/error-codes.ts
git commit -m "feat(entitlements): EntitlementsService (resolve/can/assert*)"

// apps/api/src/entitlements/require-feature.decorator.ts
import { SetMetadata } from '@nestjs/common'
import type { FeatureKey } from './plans.catalog'

export const REQUIRES_FEATURE_KEY = 'requires_feature'

// Declare that a route needs a plan feature. Pair with @UseGuards(FeatureGuard).
// The route stays billing-agnostic — it states WHAT it needs, never WHICH plan
// grants it (that lives in plans.catalog.ts).
export const RequiresFeature = (feature: FeatureKey) => SetMetadata(REQUIRES_FEATURE_KEY, feature)

// apps/api/src/entitlements/feature.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common'
import { Reflector } from '@nestjs/core'
import type { Request } from 'express'
import { EntitlementsService } from './entitlements.service'
import { REQUIRES_FEATURE_KEY } from './require-feature.decorator'
import type { FeatureKey } from './plans.catalog'

// Local guard (use via @UseGuards(FeatureGuard), NOT as an APP_GUARD) so it always
// runs AFTER the global WorkspaceGuard has resolved request.workspaceId. A route
// with no @RequiresFeature is a no-op.
@Injectable()
export class FeatureGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly entitlements: EntitlementsService,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const feature = this.reflector.getAllAndOverride<FeatureKey | undefined>(REQUIRES_FEATURE_KEY, [
      context.getHandler(),
      context.getClass(),
    ])
    if (!feature) return true

    const request = context.switchToHttp().getRequest<Request>() as any
    const workspaceId: string | undefined = request.workspaceId
    if (!workspaceId) return true

    await this.entitlements.assertFeature(workspaceId, feature)
    return true
  }
}

// apps/api/src/entitlements/entitlements.module.ts
import { Module } from '@nestjs/common'
import { TypeOrmModule } from '@nestjs/typeorm'
import { Workspace, WorkspaceMember, Repo, Project, Collection } from '@driftless/db'
import { EntitlementsService } from './entitlements.service'
import { FeatureGuard } from './feature.guard'

// The billing/access engine. Import this module anywhere a service needs to ask
// the plan (EntitlementsService) or a controller gates a feature (FeatureGuard).
@Module({
  imports: [TypeOrmModule.forFeature([Workspace, WorkspaceMember, Repo, Project, Collection])],
  providers: [EntitlementsService, FeatureGuard],
  exports: [EntitlementsService, FeatureGuard],
})
export class EntitlementsModule {}

describe('setPlan', () => {
  it('rejects an invalid plan id', async () => {
    await expect(service.setPlan('ws1', 'bogus')).rejects.toThrow(/Invalid plan/)
  })

  it('sets workspaces.plan and merges overrides under settings.billing.overrides', async () => {
    const updated = await service.setPlan('ws1', 'team', { seats: 8 })
    expect(updated.plan).toBe('team')
    expect((updated.settings as any).billing.overrides).toEqual({ seats: 8 })
  })
})

  // Set a workspace's billing tier and (optionally) custom entitlement overrides.
  // Called by the admin endpoint (Task 3) and the Stripe webhook (Task 13) — the
  // SAME seam. `overrides` is merged under settings.billing.overrides (a partial
  // PlanDef) without clobbering other settings — for Enterprise/custom deals and
  // Team's per-unit seat/workspace overage.
  async setPlan(workspaceId: string, plan: string, overrides?: Record<string, unknown>): Promise<Workspace> {
    if (!isPlanId(plan)) throw new BadRequestException(`Invalid plan '${plan}'`)
    await this.workspaceRepo.update(workspaceId, { plan } as any)
    if (overrides !== undefined) {
      const current = await this.findById(workspaceId)
      if (!current) throw new NotFoundException('Workspace not found')
      const settings = { ...(current.settings ?? {}) } as Record<string, unknown>
      settings['billing'] = { ...((settings['billing'] as object) ?? {}), overrides }
      await this.workspaceRepo.update(workspaceId, { settings } as any)
    }
    const updated = await this.findById(workspaceId)
    if (!updated) throw new NotFoundException('Workspace not found')
    return updated
  }

  // Set the workspace's billing tier (and optional custom overrides). The MANUAL
  // seam the Stripe webhook (Task 13) replaces for self-serve upgrades — this stays
  // as the path for Enterprise deals and support overrides. Gated to a platform
  // super-admin (PLATFORM_ADMIN_USER_IDS), never a workspace owner: a customer must
  // not set their own plan to enterprise.
  @Patch(':slug/plan')
  async setPlan(
    @WorkspaceId() workspaceId: string,
    @Param('slug') _slug: string,
    @CurrentPrincipal() principal: Principal,
    @Body() body: { plan: string; overrides?: Record<string, unknown> },
  ) {
    this.assertPlatformAdmin(principal)
    if (!body?.plan) throw new BadRequestException('plan is required')
    return this.workspacesService.setPlan(workspaceId, body.plan, body.overrides)
  }

  private assertPlatformAdmin(principal: Principal): void {
    if (principal.kind !== 'user' || !principal.clerkUserId) {
      throw new ForbiddenException('Setting a plan requires a human identity')
    }
    const admins = (this.config.get<string>('PLATFORM_ADMIN_USER_IDS') || '')
      .split(',')
      .map((s) => s.trim())
      .filter(Boolean)
    if (!admins.includes(principal.clerkUserId)) {
      throw new ForbiddenException('Only a platform admin can set a workspace plan')
    }
  }

import { EntitlementsModule } from '../entitlements/entitlements.module'

    imports: [
      TypeOrmModule.forFeature([...]),
      TopicsModule,
      OAuthModule,
      EntitlementsModule,
    ],

git add apps/api/src/entitlements/require-feature.decorator.ts apps/api/src/entitlements/feature.guard.ts \
  apps/api/src/entitlements/entitlements.module.ts apps/api/src/workspaces/
git commit -m "feat(entitlements): FeatureGuard + setPlan admin seam, wired into WorkspacesModule"

it('create() calls entitlements.assertRepoAvailable before saving', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire assertSpy into the EntitlementsService mock already in this file's providers
  await service.create({ workspace_id: 'ws1', github_org: 'acme', github_repo: 'widgets' })
  expect(assertSpy).toHaveBeenCalledWith('ws1')
})

import { EntitlementsService } from '../entitlements/entitlements.service'

  constructor(
    @InjectRepository(Repo) private readonly repoRepository: Repository<Repo>,
    @InjectRepository(Integration) private readonly integrationRepository: Repository<Integration>,
    @InjectRepository(PendingInstallation) private readonly pendingRepository: Repository<PendingInstallation>,
    private readonly entitlements: EntitlementsService,
  ) {}

    // Plan repo ceiling (Free = 1 repo — the PR-bot acquisition hook). Grandfathered:
    // existing repos stay; this only blocks connecting beyond the included count.
    await this.entitlements.assertRepoAvailable(data.workspace_id)

git add apps/api/src/repos/repos.service.ts apps/api/src/repos/repos.service.spec.ts
git commit -m "feat(entitlements): gate repo connection on the plan's repo ceiling"

it('POST /workspaces calls entitlements.assertWorkspaceAvailable(ownerClerkId) when a Clerk session is present', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // inject { provide: EntitlementsService, useValue: { assertWorkspaceAvailable: assertSpy } }
  const req = { auth: () => ({ userId: 'user_123' }), headers: {} } as any
  await controller.create({ name: 'Acme', slug: 'acme' }, req)
  expect(assertSpy).toHaveBeenCalledWith('user_123')
})

  async create(@Body() body: { name: string; slug: string }, @Req() req: Request) {
    const getAuth = (req as any).auth
    const auth = typeof getAuth === 'function' ? getAuth() : getAuth
    const ownerClerkId: string | null = auth?.userId ?? null
    if (ownerClerkId) await this.entitlements.assertWorkspaceAvailable(ownerClerkId)
    const ws = await this.workspacesService.create(body.name, body.slug, ownerClerkId)
    await this.audit.record({
      action: 'workspace.create',
      actor: ownerClerkId ?? 'anonymous',
      workspaceId: ws.id,
      target: ws.slug,
      detail: { name: ws.name },
    })
    return ws
  }

git add apps/api/src/workspaces/workspaces.controller.ts apps/api/src/workspaces/workspaces.controller.spec.ts
git commit -m "feat(entitlements): gate workspace creation on the owner's plan ceiling"

it('invite() calls entitlements.assertSeatAvailable before creating the invite', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire into this file's existing providers array as EntitlementsService mock
  await service.invite('ws1', 'new@acme.com', 'member', 'inviter_1')
  expect(assertSpy).toHaveBeenCalledWith('ws1')
})

import { EntitlementsModule } from '../entitlements/entitlements.module'

  imports: [TypeOrmModule.forFeature([Workspace, WorkspaceMember, WorkspaceInvitation]), EmailModule, EntitlementsModule],

    await this.entitlements.assertSeatAvailable(workspaceId)

git add apps/api/src/invitations/
git commit -m "feat(entitlements): gate seat invitations on the plan's seat ceiling"

it('create() calls entitlements.assertProjectAvailable before saving', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire into this file's existing providers array as EntitlementsService mock
  await service.create('ws1', { clerkUserId: 'user_1' } as any, { title: 'Q3 launch' } as any)
  expect(assertSpy).toHaveBeenCalledWith('ws1')
})

import { EntitlementsModule } from '../entitlements/entitlements.module'

  imports: [TypeOrmModule.forFeature([Project, Card, ProjectContextRef, ProjectNotification, Workspace]), TopicsModule, MembersModule, EntitlementsModule],

    await this.entitlements.assertProjectAvailable(workspaceId)

git add apps/api/src/projects/
git commit -m "feat(entitlements): gate project creation on the plan's project ceiling"

it('create() calls entitlements.assertCollectionAvailable before saving', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire into this file's existing providers array as EntitlementsService mock
  await service.create('ws1', { clerkUserId: 'user_1' } as any, { name: 'Hiring', archetype: 'pipeline' } as any)
  expect(assertSpy).toHaveBeenCalledWith('ws1')
})

import { EntitlementsModule } from '../entitlements/entitlements.module'

  imports: [TypeOrmModule.forFeature([Collection, RecordEntity, EntityEntity, Topic]), MembersModule, EntitlementsModule],

    await this.entitlements.assertCollectionAvailable(workspaceId)

git add apps/api/src/collections/
git commit -m "feat(entitlements): gate collection creation on the plan's collection ceiling"

it('update() gates enabling auditor/architect behind byom_chat', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire into this file's existing providers array as EntitlementsService mock
  await service.update('ws1', { auditor: true })
  expect(assertSpy).toHaveBeenCalledWith('ws1', 'byom_chat')
})

it('update() does NOT gate turning auditor/architect OFF', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  await service.update('ws1', { auditor: false })
  expect(assertSpy).not.toHaveBeenCalled()
})

import { EntitlementsModule } from '../entitlements/entitlements.module'

  imports: [TypeOrmModule.forFeature([...]), TopicsModule, EventsModule, EntitlementsModule],

    // byom_chat gates turning ON auditor/architect (they run through the same
    // model-gateway as Chat) — turning them OFF is never blocked.
    if (patch.auditor === true || patch.architect === true) {
      await this.entitlements.assertFeature(workspaceId, 'byom_chat')
    }

it('createThread gates on byom_chat', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire into this file's existing providers array as EntitlementsService mock
  await controller.createThread('ws1', { clerkUserId: 'user_1' } as any, {})
  expect(assertSpy).toHaveBeenCalledWith('ws1', 'byom_chat')
})

import { EntitlementsModule } from '../entitlements/entitlements.module'

  imports: [TypeOrmModule.forFeature([ChatThread, ChatMessage]), AgentRunsModule, TopicsModule, ProjectsModule, CollectionsModule, BrokerModule, EntitlementsModule],

    await this.entitlements.assertFeature(workspaceId, 'byom_chat')

git add apps/api/src/agent-runs/ apps/api/src/chat/
git commit -m "feat(entitlements): gate byom_chat (Chat threads + Auditor/Architect enable)"

it('createGrant gates on the broker plan feature', async () => {
  const assertSpy = vi.fn().mockResolvedValue(undefined)
  // wire into this file's existing providers array as EntitlementsService mock
  await controller.createGrant({ clerkUserId: 'user_1' } as any, 'ws1', { provider: 'notion', effect: 'read' })
  expect(assertSpy).toHaveBeenCalledWith('ws1', 'broker')
})

import { EntitlementsModule } from '../entitlements/entitlements.module'

  imports: [TypeOrmModule.forFeature([BrokerEvent, ConnectorDocument, Topic]), IntegrationsModule, CollectionsModule, EntitlementsModule],

    await this.entitlements.assertFeature(workspaceId, 'broker')

git add apps/api/src/broker/
git commit -m "feat(entitlements): gate broker grants on the plan's broker feature (Team+)"

// apps/api/src/billing/stripe-client.ts
import Stripe from 'stripe'
import type { ConfigService } from '@nestjs/config'

// ONE Stripe client, built from STRIPE_SECRET_KEY. Every billing/webhook service
// gets it through this factory — never `new Stripe(...)` inline, so there is one
// place that pins the API version.
export function getStripeClient(config: Pick<ConfigService, 'get'>): Stripe {
  const key = config.get<string>('STRIPE_SECRET_KEY')
  if (!key) throw new Error('STRIPE_SECRET_KEY is not configured')
  return new Stripe(key, { apiVersion: '2025-01-27.acacia' })
}

// apps/api/scripts/stripe-seed-products.ts
// Creates (or finds, if already created) the Stripe Products/Prices this pricing
// model needs, and prints the price IDs to paste into env (STRIPE_PRICE_*). Run
// once per Stripe account (test mode, then live mode before launch):
//   cd apps/api && npx tsx scripts/stripe-seed-products.ts
import Stripe from 'stripe'

const key = process.env['STRIPE_SECRET_KEY']
if (!key) {
  console.error('Set STRIPE_SECRET_KEY before running this script')
  process.exit(1)
}
const stripe = new Stripe(key, { apiVersion: '2025-01-27.acacia' })

async function findOrCreatePrice(
  lookupKey: string,
  productName: string,
  unitAmountCents: number,
): Promise<string> {
  const existing = await stripe.prices.list({ lookup_keys: [lookupKey], limit: 1 })
  if (existing.data[0]) return existing.data[0].id

  const product = await stripe.products.create({ name: productName })
  const price = await stripe.prices.create({
    product: product.id,
    currency: 'usd',
    unit_amount: unitAmountCents,
    recurring: { interval: 'month' },
    lookup_key: lookupKey,
  })
  return price.id
}

async function main() {
  const proMonthly = await findOrCreatePrice('pro_monthly', 'Driftless Pro', 900)
  const teamBaseMonthly = await findOrCreatePrice('team_base_monthly', 'Driftless Team (5 seats)', 4900)
  const teamSeatExtra = await findOrCreatePrice('team_seat_extra', 'Driftless Team — extra seat', 1500)
  const teamWorkspaceExtra = await findOrCreatePrice('team_workspace_extra', 'Driftless Team — extra workspace', 1500)

  console.log('Paste these into apps/api env:')
  console.log(`STRIPE_PRICE_PRO_MONTHLY=${proMonthly}`)
  console.log(`STRIPE_PRICE_TEAM_BASE_MONTHLY=${teamBaseMonthly}`)
  console.log(`STRIPE_PRICE_TEAM_SEAT_EXTRA=${teamSeatExtra}`)
  console.log(`STRIPE_PRICE_TEAM_WORKSPACE_EXTRA=${teamWorkspaceExtra}`)
}

main().catch((err) => {
  console.error(err)
  process.exit(1)
})

git add apps/api/package.json apps/api/package-lock.json apps/api/src/billing/stripe-client.ts apps/api/scripts/stripe-seed-products.ts
git commit -m "feat(billing): add stripe SDK, client factory, and product/price seed script"

// apps/api/src/billing/billing.service.spec.ts
import { describe, it, expect, vi } from 'vitest'
import { BillingService } from './billing.service'

function fakeConfig(values: Record<string, string>) {
  return { get: (k: string) => values[k] }
}

describe('BillingService.createCheckoutSession', () => {
  it('builds a subscription Checkout Session with the tier base price + overage line items', async () => {
    const sessionsCreate = vi.fn().mockResolvedValue({ url: 'https://checkout.stripe.com/session_abc' })
    const stripeStub = { checkout: { sessions: { create: sessionsCreate } } } as any
    const config = fakeConfig({
      STRIPE_PRICE_TEAM_BASE_MONTHLY: 'price_team_base',
      STRIPE_PRICE_TEAM_SEAT_EXTRA: 'price_team_seat',
      STRIPE_PRICE_TEAM_WORKSPACE_EXTRA: 'price_team_ws',
      APP_URL: 'https://app.driftless.icu',
    })
    const workspacesService = { findById: vi.fn().mockResolvedValue({ id: 'ws1', slug: 'acme' }) }
    const svc = new BillingService(config as any, workspacesService as any)
    ;(svc as any).stripe = stripeStub // override the real client built in the constructor

    const result = await svc.createCheckoutSession('ws1', 'team', 2, 1)

    expect(result).toEqual({ url: 'https://checkout.stripe.com/session_abc' })
    expect(sessionsCreate).toHaveBeenCalledWith(
      expect.objectContaining({
        mode: 'subscription',
        client_reference_id: 'ws1',
        line_items: [
          { price: 'price_team_base', quantity: 1 },
          { price: 'price_team_seat', quantity: 2 },
          { price: 'price_team_ws', quantity: 1 },
        ],
        success_url: expect.stringContaining('acme'),
      }),
    )
  })

  it('pro tier has no overage line items', async () => {
    const sessionsCreate = vi.fn().mockResolvedValue({ url: 'https://checkout.stripe.com/session_xyz' })
    const stripeStub = { checkout: { sessions: { create: sessionsCreate } } } as any
    const config = fakeConfig({ STRIPE_PRICE_PRO_MONTHLY: 'price_pro', APP_URL: 'https://app.driftless.icu' })
    const workspacesService = { findById: vi.fn().mockResolvedValue({ id: 'ws1', slug: 'acme' }) }
    const svc = new BillingService(config as any, workspacesService as any)
    ;(svc as any).stripe = stripeStub

    await svc.createCheckoutSession('ws1', 'pro')

    expect(sessionsCreate).toHaveBeenCalledWith(
      expect.objectContaining({ line_items: [{ price: 'price_pro', quantity: 1 }] }),
    )
  })
})

// apps/api/src/billing/billing.service.ts
import { Injectable, NotFoundException } from '@nestjs/common'
import { ConfigService } from '@nestjs/config'
import type Stripe from 'stripe'
import { getStripeClient } from './stripe-client'
import { WorkspacesService } from '../workspaces/workspaces.service'

export type CheckoutTier = 'pro' | 'team'

// Self-serve Checkout for Pro and Team ONLY — Enterprise stays a manual deal via
// the admin setPlan endpoint (apps/api/src/workspaces/workspaces.controller.ts).
@Injectable()
export class BillingService {
  private readonly stripe: Stripe

  constructor(
    private readonly config: ConfigService,
    private readonly workspacesService: WorkspacesService,
  ) {
    this.stripe = getStripeClient(config)
  }

  async createCheckoutSession(
    workspaceId: string,
    tier: CheckoutTier,
    extraSeats = 0,
    extraWorkspaces = 0,
  ): Promise<{ url: string }> {
    const ws = await this.workspacesService.findById(workspaceId)
    if (!ws) throw new NotFoundException('Workspace not found')

    const lineItems: Array<{ price: string; quantity: number }> =
      tier === 'pro'
        ? [{ price: this.priceId('STRIPE_PRICE_PRO_MONTHLY'), quantity: 1 }]
        : [
            { price: this.priceId('STRIPE_PRICE_TEAM_BASE_MONTHLY'), quantity: 1 },
            ...(extraSeats > 0 ? [{ price: this.priceId('STRIPE_PRICE_TEAM_SEAT_EXTRA'), quantity: extraSeats }] : []),
            ...(extraWorkspaces > 0
              ? [{ price: this.priceId('STRIPE_PRICE_TEAM_WORKSPACE_EXTRA'), quantity: extraWorkspaces }]
              : []),
          ]

    const appUrl = this.config.get<string>('APP_URL') ?? 'https://app.driftless.icu'
    const session = await this.stripe.checkout.sessions.create({
      mode: 'subscription',
      client_reference_id: workspaceId,
      line_items: lineItems,
      success_url: `${appUrl}/w/${ws.slug}/settings?upgraded=1`,
      cancel_url: `${appUrl}/w/${ws.slug}/settings`,
      metadata: { workspace_id: workspaceId, tier },
    })
    if (!session.url) throw new Error('Stripe did not return a Checkout URL')
    return { url: session.url }
  }

  private priceId(envKey: string): string {
    const id = this.config.get<string>(envKey)
    if (!id) throw new Error(`${envKey} is not configured`)
    return id
  }
}

// apps/api/src/billing/billing.controller.ts
import { Controller, Post, Body, BadRequestException } from '@nestjs/common'
import { WorkspaceId } from '../auth/workspace-id.decorator'
import { BillingService, type CheckoutTier } from './billing.service'

@Controller('billing')
export class BillingController {
  constructor(private readonly billing: BillingService) {}

  @Post('checkout-session')
  async createCheckoutSession(
    @WorkspaceId() workspaceId: string,
    @Body() body: { tier: CheckoutTier; extra_seats?: number; extra_workspaces?: number },
  ) {
    if (body.tier !== 'pro' && body.tier !== 'team') {
      throw new BadRequestException("tier must be 'pro' or 'team'")
    }
    return this.billing.createCheckoutSession(workspaceId, body.tier, body.extra_seats ?? 0, body.extra_workspaces ?? 0)
  }
}

// apps/api/src/billing/billing.module.ts
import { Module } from '@nestjs/common'
import { BillingService } from './billing.service'
import { BillingController } from './billing.controller'
import { WorkspacesModule } from '../workspaces/workspaces.module'

@Module({
  imports: [WorkspacesModule],
  controllers: [BillingController],
  providers: [BillingService],
  exports: [BillingService],
})
export class BillingModule {}

git add apps/api/src/billing/billing.controller.ts apps/api/src/billing/billing.module.ts apps/api/src/app.module.ts
git commit -m "feat(billing): POST /billing/checkout-session (Pro + Team self-serve)"

// apps/api/src/billing/billing-webhook.service.spec.ts
import { describe, it, expect, vi } from 'vitest'
import { BillingWebhookService } from './billing-webhook.service'

describe('BillingWebhookService.handleEvent', () => {
  it('checkout.session.completed with tier=pro sets plan=pro', async () => {
    const setPlan = vi.fn().mockResolvedValue({})
    const svc = new BillingWebhookService({ setPlan } as any)
    await svc.handleEvent({
      type: 'checkout.session.completed',
      data: { object: { client_reference_id: 'ws1', metadata: { tier: 'pro' } } },
    } as any)
    expect(setPlan).toHaveBeenCalledWith('ws1', 'pro', undefined)
  })

  it('checkout.session.completed with tier=team and line item quantities sets plan=team with overrides', async () => {
    const setPlan = vi.fn().mockResolvedValue({})
    const svc = new BillingWebhookService({ setPlan } as any)
    await svc.handleEvent({
      type: 'checkout.session.completed',
      data: {
        object: {
          client_reference_id: 'ws1',
          metadata: { tier: 'team' },
          line_items: undefined, // Checkout Session webhook payload doesn't include line_items by default
        },
      },
    } as any)
    expect(setPlan).toHaveBeenCalledWith('ws1', 'team', undefined)
  })

  it('customer.subscription.deleted downgrades the workspace to free', async () => {
    const setPlan = vi.fn().mockResolvedValue({})
    const svc = new BillingWebhookService({ setPlan } as any)
    await svc.handleEvent({
      type: 'customer.subscription.deleted',
      data: { object: { metadata: { workspace_id: 'ws1' } } },
    } as any)
    expect(setPlan).toHaveBeenCalledWith('ws1', 'free', undefined)
  })

  it('ignores event types it does not handle', async () => {
    const setPlan = vi.fn()
    const svc = new BillingWebhookService({ setPlan } as any)
    await svc.handleEvent({ type: 'invoice.paid', data: { object: {} } } as any)
    expect(setPlan).not.toHaveBeenCalled()
  })
})

// apps/api/src/billing/billing-webhook.service.ts
import { Injectable, Logger } from '@nestjs/common'
import type Stripe from 'stripe'
import { WorkspacesService } from '../workspaces/workspaces.service'

// Maps Stripe events to WorkspacesService.setPlan — the SAME seam the manual admin
// endpoint uses (apps/api/src/workspaces/workspaces.controller.ts). Called
// service-to-service (never through the HTTP /workspaces/:slug/plan route, which
// requires a human PLATFORM_ADMIN_USER_IDS principal — Stripe isn't one).
@Injectable()
export class BillingWebhookService {
  private readonly logger = new Logger(BillingWebhookService.name)

  constructor(private readonly workspacesService: WorkspacesService) {}

  async handleEvent(event: Stripe.Event): Promise<void> {
    switch (event.type) {
      case 'checkout.session.completed': {
        const session = event.data.object as Stripe.Checkout.Session
        const workspaceId = session.client_reference_id
        const tier = session.metadata?.['tier']
        if (!workspaceId || (tier !== 'pro' && tier !== 'team')) {
          this.logger.warn(`checkout.session.completed missing workspace_id/tier: ${session.id}`)
          return
        }
        await this.workspacesService.setPlan(workspaceId, tier, undefined)
        return
      }
      case 'customer.subscription.updated': {
        const sub = event.data.object as Stripe.Subscription
        const workspaceId = sub.metadata?.['workspace_id']
        if (!workspaceId) return
        // Active/trialing keep the current plan as-is; a past_due/unpaid state is
        // left to Stripe's own dunning/retry — this webhook only reacts to the
        // terminal deleted event by downgrading (below).
        return
      }
      case 'customer.subscription.deleted': {
        const sub = event.data.object as Stripe.Subscription
        const workspaceId = sub.metadata?.['workspace_id']
        if (!workspaceId) return
        await this.workspacesService.setPlan(workspaceId, 'free', undefined)
        return
      }
      default:
        return
    }
  }
}

// apps/api/src/billing/billing-webhook.controller.ts
import { Controller, Post, Req, Headers, BadRequestException, HttpCode } from '@nestjs/common'
import { ConfigService } from '@nestjs/config'
import type { Request } from 'express'
import { getStripeClient } from './stripe-client'
import { BillingWebhookService } from './billing-webhook.service'
import { Public } from '../auth/public.decorator'

// Separate from apps/api/src/webhooks (GitHub-specific) — different signature
// scheme (STRIPE_WEBHOOK_SECRET, not a GitHub HMAC) and a different public
// ingress. @Public: Stripe carries no session/API key, only its own signature.
@Controller('webhooks/stripe')
export class BillingWebhookController {
  constructor(
    private readonly config: ConfigService,
    private readonly webhookService: BillingWebhookService,
  ) {}

  @Public()
  @HttpCode(200)
  @Post()
  async handle(@Req() req: Request, @Headers('stripe-signature') signature: string) {
    const secret = this.config.get<string>('STRIPE_WEBHOOK_SECRET')
    if (!secret) throw new BadRequestException('Stripe webhook not configured')
    const stripe = getStripeClient(this.config)

    let event
    try {
      // req.body must be the RAW buffer here (see main.ts step below) — Stripe's
      // signature check fails on an already-JSON-parsed body.
      event = stripe.webhooks.constructEvent((req as any).rawBody, signature, secret)
    } catch (err) {
      throw new BadRequestException(`Invalid Stripe signature: ${(err as Error).message}`)
    }

    await this.webhookService.handleEvent(event)
    return { received: true }
  }
}

const app = await NestFactory.create(AppModule, { rawBody: true })

@Module({
  imports: [WorkspacesModule],
  controllers: [BillingController, BillingWebhookController],
  providers: [BillingService, BillingWebhookService],
  exports: [BillingService],
})
export class BillingModule {}

git add apps/api/src/billing/ apps/api/src/main.ts
git commit -m "feat(billing): Stripe webhook — checkout completed / subscription deleted → setPlan"

it('createPortalSession creates a Billing Portal session for the workspace stripe customer', async () => {
  const portalCreate = vi.fn().mockResolvedValue({ url: 'https://billing.stripe.com/session_abc' })
  const stripeStub = { billingPortal: { sessions: { create: portalCreate } } } as any
  const config = fakeConfig({ APP_URL: 'https://app.driftless.icu' })
  const workspacesService = { findById: vi.fn().mockResolvedValue({ id: 'ws1', slug: 'acme', settings: { billing: { stripe_customer_id: 'cus_123' } } }) }
  const svc = new BillingService(config as any, workspacesService as any)
  ;(svc as any).stripe = stripeStub

  const result = await svc.createPortalSession('ws1')

  expect(result).toEqual({ url: 'https://billing.stripe.com/session_abc' })
  expect(portalCreate).toHaveBeenCalledWith({
    customer: 'cus_123',
    return_url: 'https://app.driftless.icu/w/acme/settings',
  })
})

it('createPortalSession throws when the workspace has no stripe_customer_id yet', async () => {
  const config = fakeConfig({ APP_URL: 'https://app.driftless.icu' })
  const workspacesService = { findById: vi.fn().mockResolvedValue({ id: 'ws1', slug: 'acme', settings: {} }) }
  const svc = new BillingService(config as any, workspacesService as any)
  await expect(svc.createPortalSession('ws1')).rejects.toThrow(/no Stripe customer/)
})

  async createPortalSession(workspaceId: string): Promise<{ url: string }> {
    const ws = await this.workspacesService.findById(workspaceId)
    if (!ws) throw new NotFoundException('Workspace not found')
    const customerId = (ws.settings as any)?.billing?.stripe_customer_id
    if (!customerId) throw new Error('This workspace has no Stripe customer yet — upgrade first')

    const appUrl = this.config.get<string>('APP_URL') ?? 'https://app.driftless.icu'
    const session = await this.stripe.billingPortal.sessions.create({
      customer: customerId,
      return_url: `${appUrl}/w/${ws.slug}/settings`,
    })
    return { url: session.url }
  }

        await this.workspacesService.setPlan(workspaceId, tier, undefined)
        const customerId = typeof session.customer === 'string' ? session.customer : session.customer?.id
        if (customerId) {
          const ws = await this.workspacesService.findById(workspaceId)
          const settings = { ...(ws?.settings ?? {}) } as Record<string, unknown>
          settings['billing'] = { ...((settings['billing'] as object) ?? {}), stripe_customer_id: customerId }
          await this.workspacesService.update(workspaceId, { settings })
        }

  @Post('portal-session')
  async createPortalSession(@WorkspaceId() workspaceId: string) {
    return this.billing.createPortalSession(workspaceId)
  }

git add apps/api/src/billing/
git commit -m "feat(billing): Stripe Customer Portal — self-serve upgrade/downgrade/cancel"