PSA/ee/docs/plans/2026-03-09-tier-trials-annual-billing/SCRATCHPAD.md

# Scratchpad — Tier Trials, Annual Billing & Bug Fixes

- Plan slug: `tier-trials-annual`
- Created: `2026-03-09`
- Updated: `2026-03-09`

## What This Is

Rolling notes for implementing trials, annual billing, bug fixes, and documentation on top of the existing tier system.

## Decisions

- (2026-03-09) **Pricing confirmed**: Pro $89/mo base + $12/user/mo, Premium $349/mo base + $25/user/mo
- (2026-03-09) **Annual = pay for 10, get 12** (~17% discount, marketed as "2 months free")
- (2026-03-09) **Pro trial = 7 days**, CC upfront, Stripe auto-charges after
- (2026-03-09) **Premium trial = 30 days**, only for paying Pro customers (not during active Pro trial)
- (2026-03-09) **Premium trial is manual**: customer requests via form, Nine Minds processes via extension
- (2026-03-09) **Premium trial = auto-charge at end**: Stripe charges for Premium when trial ends. Customer must actively cancel to revert to Pro. No "commit" step needed — accepting the trial IS the commitment.
- (2026-03-09) **Cancel Premium Trial**: customer can cancel during trial → reverts to Pro. Cancel button on account page.
- (2026-03-09) **Payment failure = "banner of shame"**: persistent banner in header, not dismissible. No automated lockout — Nine Minds manually monitors and contacts delinquent accounts.
- (2026-03-09) **24-48hr grace period**: support policy only, not enforced in code
- (2026-03-09) **Annual cancellation refund**: case-by-case manual process via support, no automated refunds
- (2026-03-09) **Trial state from Stripe**: use subscription.trial_end and status, no custom trial tables
- (2026-03-09) **Trial request storage**: email notification only (no DB table for requests initially)

## Discoveries / Constraints

- (2026-03-09) Stripe subscription status already includes 'trialing' in schema enum
- (2026-03-09) No existing trial_end or trial columns in DB — need to pull from Stripe subscription
- (2026-03-09) JWT already refreshes plan every 5 min — trial_end and subscription_status can piggyback on same query
- (2026-03-09) Header component at `server/src/components/layout/Header.tsx` — trial banner goes next to tenant badge (left side)
- (2026-03-09) CancellationFeedbackModal at `ee/server/src/components/settings/account/CancellationFeedbackModal.tsx` — pattern for Premium trial request form
- (2026-03-09) NineMinds extension TenantManagementView at `ee/extensions/nineminds-reporting/src/iframe/main.tsx` (lines ~2908-3700)
- (2026-03-09) Extension API calls go through WASM proxy: UI → bridge → handler.ts → uiProxy → Next.js API
- (2026-03-09) All tenant management APIs require master billing tenant auth
- (2026-03-09) `sendEventEmail` at `server/src/lib/notifications/sendEventEmail.ts` — for trial request emails
- (2026-03-09) Existing `buildPhaseItems` price bug: picks first configured price ID, not tenant's actual tier

## Key File Paths

| File | Purpose |
|------|---------|
| `packages/types/src/constants/tenantTiers.ts` | Tier types + resolveTier (BF1) |
| `packages/types/src/constants/addOns.ts` | Add-ons scaffolding (BF8) |
| `ee/server/src/lib/stripe/StripeService.ts` | buildPhaseItems (BF2), upgradeTier, checkout |
| `ee/server/src/lib/stripe/stripeTierMapping.ts` | tierFromStripeProduct (BF5) |
| `packages/billing/src/actions/invoiceTemplates.ts` | saveInvoiceTemplate (BF3) |
| `packages/auth/src/lib/nextAuthOptions.ts` | JWT plan logic (BF4), trial fields (TR1-3) |
| `server/src/components/tier-gating/TierGate.tsx` | Loading state (BF6) |
| `server/src/context/TierContext.tsx` | Trial state (TR4-5) |
| `server/src/components/layout/Header.tsx` | Trial banner (TR7), payment banner (TR10) |
| `ee/server/src/components/settings/account/AccountManagement.tsx` | Trial status, request form |
| `ee/server/src/components/settings/account/CancellationFeedbackModal.tsx` | Pattern for request form |
| `ee/server/src/lib/actions/license-actions.ts` | Server actions for trials |
| `ee/extensions/nineminds-reporting/src/iframe/main.tsx` | Extension UI for trial management |
| `ee/extensions/nineminds-reporting/src/handler.ts` | Extension handler routing |

## Stripe Trial Implementation Notes

### How Stripe Trials Work
- `subscription_data.trial_period_days: 7` on checkout session = 7-day trial
- CC captured at checkout but not charged
- Stripe automatically charges when `trial_end` passes
- If charge fails → subscription goes to `past_due`
- `subscription.status` = `'trialing'` during trial, `'active'` after
- `subscription.trial_end` = Unix timestamp of trial end

### Premium Trial Activation (Manual via Extension)
`startPremiumTrialAction(tenantId)` detects tenant state and handles:

**Path A — Paying Pro customer:**
1. Creates Premium subscription with `trial_period_days: 30`
2. Sets `tenants.plan = 'premium'`

**Path B — Pro trial customer (wants Premium from day 1):**
1. Ends Pro trial: `stripe.subscriptions.update(sub, { trial_end: 'now' })` → triggers immediate charge for first month of Pro
2. Verifies Pro charge succeeded
3. Creates Premium subscription with `trial_period_days: 30`
4. Sets `tenants.plan = 'premium'`

Both paths end with: customer sees Premium features + countdown banner + pricing breakdown on account page.

**No direct plan override API** — manual overrides (courtesy access etc.) are done directly in DB.

### Premium Trial End States
- **Customer does nothing** → Stripe auto-charges at trial end → `trialing` → `active` → customer is paying Premium
- **Customer cancels** → Cancel Premium subscription → `trialing` → `canceled` → webhook reverts `tenants.plan` to `'pro'`
- **Charge fails** → `trialing` → `past_due` → banner of shame, Nine Minds contacts manually

## nm-store Dependency

The 7-day Pro trial and annual billing toggle both require changes in **nm-store** (separate repo at `/Users/natalliabukhtsik/Desktop/projects/nm-store`).

Existing plan: `/Users/natalliabukhtsik/Desktop/projects/nm-store/.ai/tier-checkout-plan.md`

nm-store changes needed (out of scope for this plan, but must coordinate):
1. **Trial**: Add `subscription_data: { trial_period_days: 7 }` to Stripe session creation in `src/utils/stripe.ts` for tiered products
2. **Annual billing**: Add monthly/annual toggle to `OrderForm.tsx`, pass annual price IDs when selected
3. **Annual env vars**: `STRIPE_PRO_BASE_ANNUAL_PRICE_ID`, `STRIPE_PRO_USER_ANNUAL_PRICE_ID`, `STRIPE_PREMIUM_BASE_ANNUAL_PRICE_ID`, `STRIPE_PREMIUM_USER_ANNUAL_PRICE_ID`

The alga-psa side (this plan) handles: receiving trial subscriptions via webhook, displaying trial state, managing trials post-creation. nm-store handles: creating the initial checkout session with trial + pricing.

## Implementation Log

### Phase 1: Bug Fixes & Documentation (2026-03-09)

**BF1** — Fixed JSDoc in `tenantTiers.ts`: replaced 'basic' with 'pro' in `ResolvedTier` and `resolveTier()` docstrings.

**BF2** — Fixed `buildPhaseItems` in `StripeService.ts`: now fetches `tenants.plan` and uses `getTierPriceIds()` to resolve the correct tier-specific prices for scheduled reductions, instead of blindly picking first configured price.

**BF3** — Verified: `saveInvoiceTemplate` serves both visual AND code templates. Can't blanket-gate the save action without distinguishing template type. The visual designer is already UI-gated via `canUseVisualDesigner` in `BillingPageClient.tsx`. Server-side enforcement of visual-only saves deferred — would require a `templateType` flag in the save payload.

**BF4** — Extracted `fetchTenantPlan(tenantId)` helper at module level in `nextAuthOptions.ts`. Replaced all 4 duplicated DB query blocks (2 initial sign-in + 2 throttled refresh) with calls to the shared helper.

**BF5** — Added `console.warn` in `tierFromStripeProduct()` when product name is null or doesn't match any known mapping. Includes the product name in the warning for debugging.

**BF6** — Replaced `return null` in `TierGate` loading state with animated skeleton (3 pulse bars using theme border colors).

**BF7** — Created migration `20260309100000_add_fk_stripe_base_price_id.cjs` adding FK from `stripe_subscriptions.stripe_base_price_id` to `stripe_prices.stripe_price_id` with CASCADE delete.

**BF8** — Added detailed JSDoc to `addOns.ts` explaining it's intentional scaffolding and how to wire it in when first add-on is defined.

**DOC1** — Created `docs/tier-gating-guide.md` with 7-step guide: enum → feature map → minimum tier → UI gate → server gate → display name → tests. Includes code examples from existing INVOICE_DESIGNER implementation, CE bypass docs, and key file reference table.

## Open Questions

- What if a paying Pro customer's card fails during Premium trial activation? (Premium trial is free, so this shouldn't matter — they keep Pro subscription active)
- Should we track trial request messages in a DB table for audit, or is email sufficient? (Starting with email only)