descrybe/docs/plan-permissions/02-plans-permissions-current.md

# 02 — Plans / packages / permissions (current system)

Inventory of how plans (“packages”) work today in descrybe-v2.  
Sibling folder `docs/plan-permissions/` was empty at write time (no `01-*` / `03-*` artifacts yet). Aligns with existing product docs: `docs/free-tier.md`, `docs/billing-credits-audit.md`.

ASSUMPTION: “packages” in product language maps 1:1 to DB table `plans` + assignment via `company_plans`. There is no separate `packages` table.

---

## 1. Models, tables, DTOs, seeders

### Tables (`apps/api/sql/schema/001_platform.sql`, Stripe extras in `016_stripe_billing.sql`)

| Table | Role |
|---|---|
| `plans` | Catalog of packages: meters + flags |
| `company_plans` | Per-company assignment (active row, trial, Stripe ids, unused override columns) |
| `credit_balances` | Wallet: `total_credits`, `used_credits` |
| `billing_cycles` | Cycle usage counters / invoicing |
| `processing_costs` | Per-feature credit unit costs (`product_processing`, `openai_token_k`, `seo_meta_ai`, `campaign_copy`) |
| `companies.stripe_customer_id` | Stripe customer link |
| `company_plans.stripe_subscription_id` / `stripe_price_id` | Subscription linkage |

**`plans` columns**

- `id`, `name`, `description`
- `monthly_credits`, `yearly_credits` (nullable)
- `max_products` (nullable = unlimited SKU cap)
- `is_custom` (boolean, default false)
- `term` (default `'monthly'`)
- timestamps

**`company_plans` columns (assignment + overrides)**

- `plan_id`, `is_active`, billing/contract dates
- `custom_monthly_credits`, `custom_max_products` — **present in schema, unused by Go billing gates**
- `total_credits_allocated`, `contract_reference`, `notes`
- `is_trial`, `trial_ends_at`, `trial_credits`
- Stripe subscription/price ids (migration 016)

### Go DTOs / types (`apps/api/internal/billing/`)

| Symbol | File | Purpose |
|---|---|---|
| `Plan` | `service.go` | JSON DTO for catalog CRUD/list |
| `CreditsOverview` | `service.go` | Wallet + plan snapshot + entitlement booleans for `/api/billing/credits` and `/api/auth/me` |
| `Entitlements` | `entitlements.go` | Pure capability snapshot (`can_use_ai`, `can_use_eprel`, free/paid/trial) |
| `ProcessingGateOpts` | `service.go` | `{RequiresAI, RequiresEPREL}` for start-job gate |
| Web `Plan` / credits types | `apps/web/src/lib/types.ts`, `billing-display.ts`, admin page local types | Mirror API shapes |

### Seed / bootstrap (not SQL seeders)

| Mechanism | Symbol / path | What it does |
|---|---|---|
| Public ladder upsert | `defaultPublicPlans` → `EnsureDefaultPlans` | Free / Starter / Growth / Business / Enterprise by name |
| Signup Free | `ProvisionFreePlan` | Assign Free if present |
| Credit cost rows | `EnsureDefaultCosts` | Idempotent `processing_costs` insert |
| Demo seed | `apps/api/cmd/seed-demo` | `EnsureDefaultPlans` then assign **Enterprise** to Local Demo Co; asserts Free stays at 0 credits |
| Migrator ETL | `apps/api/cmd/migrator` (`loadPlans`, `loadCompanyPlans`, `company_plans_repair.go`) | MySQL → Postgres plans + repair missing assignments |
| On-demand | Admin/public list handlers call `EnsureDefaultPlans` before list |

**Default public packaging** (`defaultPublicPlans`):

| Name | Monthly credits | Max products | `is_custom` |
|---|---|---|---|
| Free | 0 | 100 | false |
| Starter | 300 | 1_000 | false |
| Growth | 2_000 | 10_000 | false |
| Business | 10_000 | 100_000 | false |
| Enterprise | 1_000_000 (`EnterpriseUnlimitedCredits`) | `null` (unlimited) | **true** |

---

## 2. Existing feature / limit / permission fields

There is **no** plan-scoped permission matrix (no per-tab / per-section toggles, no `plan_permissions` table, no feature-flag JSON on `plans`).

Capabilities today are **derived** or **metered**:

### Entitlement booleans (`ComputeEntitlements` / `CreditsOverview`)

| Field | Meaning (current code) |
|---|---|
| `is_free_plan` / `is_paid_plan` | Name equals `"free"` (or empty) vs not |
| `is_trial` | From active `company_plans.is_trial` |
| `monthly_credits` | From `plans.monthly_credits` |
| `remaining_credits` | `max(0, total - used)` wallet |
| `can_use_ai` | `remaining > 0` **OR** paid plan (not Free). Paid with empty wallet still has `can_use_ai=true`, but AI **jobs** require remaining ≥ batch size |
| `can_use_eprel` | **Always `true`** in code (EU public data). Platform can still disable enricher via settings/env. Note: `docs/free-tier.md` still describes paid-only EPREL — **docs lag code** |

### Hard limits

| Limit | Source | Enforced by |
|---|---|---|
| SKU / product cap | `plans.max_products` (null/≤0 = unlimited) | `AssertCanStartProcessing` vs `count(processed_products)` |
| AI credit wallet | `credit_balances` | Gate on AI job types + `ConsumeCredits` / batch |
| Brand voice in AI | Paid or trial | `AIBrandApplyAllowed` |

### Credit feature keys (`processing_costs.feature_name`)

Metering only (cost per unit), **not** allow/deny:

- `product_processing`
- `openai_token_k`
- `seo_meta_ai`
- `campaign_copy`

### AI-only vs free-path processing types

- `ProcessingTypeRequiresAI`: `enhance`, `enhance_only`, `title`, `description`, `seo`, `seo_ai`
- `ProcessingTypeRequiresEPREL`: `eprel`, `eprel_only`
- Non-AI types (normalize/specs/fill/full with step policy) can run on Free with 0 credits; pipeline may skip AI/EPREL steps

### Membership / platform roles (orthogonal to plans)

Company `admin` / member roles and `users.is_platform_admin` gate **who** can call admin APIs — not which product tabs a plan unlocks.

---

## 3. Default vs custom packages

Two **different** notions exist; do not conflate them.

### A. Public product ladder vs client deals (listing / checkout)

- **Public**: name ∈ `{Free, Starter, Growth, Business, Enterprise}` via `IsPublicProductPlan`
- Exposed to tenants: `GET /api/billing/plans` → `ListPublicPlans`
- Stripe self-serve checkout also keys off public names
- **Client / custom deals** (A1, Merkur trial, legacy names, admin-created packages): remain in `plans`, visible only via **admin** `GET /api/admin/plans` → `ListPlans` (all rows)

`EnsureDefaultPlans` syncs only names in `defaultPublicPlans`; named client deals are left untouched.

### B. `plans.is_custom` flag

- Boolean on the row; admin UI Badge “Custom” vs “Standard”
- Admin create dialog defaults `is_custom: true`
- Public **Enterprise** is seeded with `is_custom: true` even though it is a public ladder plan
- **Not** used by `ListPublicPlans` (name whitelist wins)
- **Not** used by entitlement/gates

### Per-company overrides

Schema columns `company_plans.custom_monthly_credits` / `custom_max_products` exist for deal overrides, but **billing Go code does not read them** today. Assignment always copies `plans.monthly_credits` (or trial credits) into the wallet; SKU gate reads `plans.max_products` only.

---

## 4. Admin UI for editing packages

| Path | Role |
|---|---|
| `apps/web/src/routes/admin/billing/+page.svelte` | Platform billing admin page |
| `apps/web/src/lib/components/AdminNav.svelte` | Nav link “Platform billing” → `/admin/billing` |
| Gate | `requirePlatformAdmin` (`$lib/admin-gate`) |

**Capabilities on the page**

- List all plans (`GET /api/admin/plans`)
- **Create** plan dialog (`POST /api/admin/plans`) — body: `name`, `monthly_credits`, `is_custom` (no `max_products` / description / term in UI)
- Assign plan to company (`POST /api/admin/plans/assign`)
- Add credits (`POST /api/admin/credits`)
- Run due billing cycles (`POST /api/admin/billing/run-cycles`)
- Companies tab shows wallet totals from `GET /api/admin/companies`

**Gaps in admin UI**

- No in-place **edit** of existing plan meters (API `UpsertPlan` supports update when `id > 0`, UI never sends `id`)
- No delete plan
- No editors for `max_products`, description, term, yearly credits
- No UI for `company_plans` custom override columns or permission toggles

Related tenant-facing (not admin edit): `/plans`, `/billing`, `/pricing` + `billing-display.ts`.

---

## 5. API endpoints that enforce plan limits

### Catalog / admin (mutate packages & assignment)

Mounted under `/api/admin` with `RequireSession` + `RequirePlatformAdmin` (`server.go`):

| Method | Path | Handler |
|---|---|---|
| GET | `/api/admin/plans` | `handleListPlans` |
| POST | `/api/admin/plans` | `handleUpsertPlan` |
| POST | `/api/admin/plans/assign` | `handleAssignPlan` |
| POST | `/api/admin/credits` | `handleAddCredits` |
| POST | `/api/admin/billing/run-cycles` | `handleRunBillingCycles` |

### Tenant billing read / Stripe

Under `/api` + session + company:

| Method | Path | Notes |
|---|---|---|
| GET | `/api/billing/credits` | `CreditsOverview` (includes entitlement flags + SKU usage) |
| GET | `/api/billing/usage` | Usage summary |
| GET | `/api/billing/plans` | Public ladder only |
| POST | `/api/billing/checkout` / `portal` | Stripe; public plans |
| GET | `/api/auth/me` | Embeds `credits` overview |

### Enforcement call sites (402 Payment Required pattern)

Central gate: `Service.AssertCanStartProcessing` → called from `processing.Pipeline.StartJob`.

| Surface | How limits apply |
|---|---|
| `POST` processing jobs (`processing_handlers`, `v1_process_handlers`) | StartJob → AssertCanStartProcessing; maps `ErrInsufficientCredits` / `ErrProductLimitExceeded` / `ErrAIRequiresUpgrade` / `ErrEPRELRequiresUpgrade` → **402** + `upgrade_url` |
| Pipeline `processOne` | Step policy: AI only if `CanUseAI && RemainingCredits > 0`; `ConsumeCredits` |
| SEO AI apply (`seo/service.go` + handlers) | Entitlements + `ConsumeCredits("seo_meta_ai")` |
| Campaign AI generate (`campaigns/generate_send.go`) | Entitlements; Free blocked; `ConsumeCredits("campaign_copy")` |
| Brand kit (`brand_handlers.go`) | `ai_apply_allowed` via `AIBrandApplyAllowed` (edit kit allowed on Free; AI inject gated) |
| Feed sample sync+process | Shares StartJob path (`handleSyncAndProcessSample`) |

Wallet debit: `ConsumeCredits` / `ConsumeCreditsBatch` (atomic remaining check).

---

## 6. Gaps vs per-tab / section permission toggles

| Need | Current state |
|---|---|
| Toggle “Feeds / Products / SEO / Campaigns / Exports / …” per plan | **Missing** — nav is role-based, not plan-based |
| Boolean feature flags on `plans` | **Missing** — only meters + `is_custom` + name heuristics |
| Per-company override of feature set | Schema has unused credit/SKU override columns; **no** feature override |
| Distinguish marketing “custom package” vs Enterprise `is_custom` | Confusing: Enterprise is public **and** `is_custom` |
| Admin edit of full plan surface | Create-only UI; no permission matrix editor |
| Server enforcement for “section disabled” | Only AI/SKU/credit gates — disabled sections would still be reachable unless added |
| Docs drift | `free-tier.md` EPREL paid-only vs code `CanUseEPREL=true` |

---

## 7. Recommended extension points (reuse, don’t duplicate)

Prefer extending the existing entitlements + plan catalog path over a parallel permissions subsystem.

1. **Catalog shape** — Extend `plans` (or a JSON `features` / `permissions` column) and `billing.Plan` + `UpsertPlan` / `EnsureDefaultPlans` / migrator load. Keep `is_custom` as “deal packaging” metadata; use **name whitelist or a new `is_public`** for self-serve listing if `is_custom` remains overloaded.

2. **Capability resolution** — Extend `Entitlements` + `ComputeEntitlements` / `EntitlementsForCompany` so one function remains the source of truth. Expose via `CreditsOverview` and `/api/auth/me` (web already reads `can_use_*` from credits).

3. **Server enforcement** — Add small helpers next to `AssertCanStartProcessing` / `AIBrandApplyAllowed` (e.g. `AssertFeature(ctx, companyID, "seo")`) and call from handlers that own each surface (processing, seo, campaigns, feeds, exports). Reuse 402 + `planGateCode` mapping in `processing_handlers.go`.

4. **Optional per-company overrides** — Wire `company_plans.custom_*` (and any new feature override) **into** `EntitlementsForCompany` / SKU query instead of inventing a second assignment table.

5. **Admin UI** — Extend `admin/billing/+page.svelte` create/edit dialog and table (send full `Plan` including `id` for update). Add toggle group UI bound to the same fields `UpsertPlan` persists.

6. **Web UX** — Gate nav/sections from `me.credits` / entitlements in `Nav.svelte` + page loads; keep display helpers in `billing-display.ts`.

7. **Do not** invent a second “packages” model, duplicate Free/paid heuristics outside `IsFreePlanName` / `ComputeEntitlements`, or add ad-hoc flags only in the frontend.

---

## Quick reference — key files

| Area | Path |
|---|---|
| Schema | `apps/api/sql/schema/001_platform.sql`, `016_stripe_billing.sql` |
| Service / Plan / gates | `apps/api/internal/billing/service.go` |
| Entitlements | `apps/api/internal/billing/entitlements.go` |
| HTTP billing/admin | `apps/api/internal/httpapi/billing_handlers.go`, `server.go` |
| Processing gate | `apps/api/internal/processing/pipeline.go` |
| Admin UI | `apps/web/src/routes/admin/billing/+page.svelte` |
| Display helpers | `apps/web/src/lib/billing-display.ts` |
| Seed | `apps/api/cmd/seed-demo/main.go` |