193 lines
8.1 KiB
Markdown
193 lines
8.1 KiB
Markdown
---
|
|
phase: 03-operator-experience
|
|
plan: 03
|
|
type: execute
|
|
wave: 2
|
|
depends_on: ["03-01"]
|
|
files_modified:
|
|
- packages/portal/app/(dashboard)/billing/page.tsx
|
|
- packages/portal/components/subscription-card.tsx
|
|
- packages/portal/components/billing-status.tsx
|
|
- packages/portal/lib/queries.ts
|
|
autonomous: false
|
|
requirements:
|
|
- PRTA-05
|
|
|
|
must_haves:
|
|
truths:
|
|
- "Operator can subscribe to a per-agent monthly plan via Stripe Checkout"
|
|
- "Operator can upgrade (add agents) and downgrade (remove agents) their subscription"
|
|
- "Operator can cancel their subscription"
|
|
- "Operator can manage payment methods and view invoices via Stripe Billing Portal"
|
|
- "Feature limits are enforced based on subscription state (agents deactivated on cancellation)"
|
|
- "14-day free trial with full access is available"
|
|
artifacts:
|
|
- path: "packages/portal/app/(dashboard)/billing/page.tsx"
|
|
provides: "Billing management page with subscription status and actions"
|
|
- path: "packages/portal/components/subscription-card.tsx"
|
|
provides: "Card showing current plan, agent count, status, trial info"
|
|
- path: "packages/portal/components/billing-status.tsx"
|
|
provides: "Status badge for subscription state (trialing, active, past_due, canceled)"
|
|
key_links:
|
|
- from: "packages/portal/app/(dashboard)/billing/page.tsx"
|
|
to: "/api/portal/billing/checkout"
|
|
via: "POST to create Checkout Session, then redirect to Stripe"
|
|
pattern: "billing/checkout"
|
|
- from: "packages/portal/app/(dashboard)/billing/page.tsx"
|
|
to: "/api/portal/billing/portal"
|
|
via: "POST to create Billing Portal session, then redirect"
|
|
pattern: "billing/portal"
|
|
---
|
|
|
|
<objective>
|
|
Billing management page with Stripe subscription integration -- subscribe, upgrade, downgrade, cancel, and manage payment via Stripe Billing Portal.
|
|
|
|
Purpose: Operators can self-serve their subscription lifecycle through the portal, with per-agent monthly pricing that matches the "hire an employee" metaphor.
|
|
Output: Billing page with subscription card, Checkout redirect, Billing Portal redirect, status display.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@/home/adelorenzo/.claude/get-shit-done/workflows/execute-plan.md
|
|
@/home/adelorenzo/.claude/get-shit-done/templates/summary.md
|
|
</execution_context>
|
|
|
|
<context>
|
|
@.planning/PROJECT.md
|
|
@.planning/ROADMAP.md
|
|
@.planning/STATE.md
|
|
@.planning/phases/03-operator-experience/03-CONTEXT.md
|
|
@.planning/phases/03-operator-experience/03-RESEARCH.md
|
|
@.planning/phases/03-operator-experience/03-01-SUMMARY.md
|
|
|
|
<interfaces>
|
|
<!-- From Plan 01 backend APIs -->
|
|
|
|
From packages/shared/shared/api/billing.py (created in Plan 01):
|
|
```python
|
|
# POST /api/portal/billing/checkout -> { "checkout_url": "https://checkout.stripe.com/..." }
|
|
# Body: { "tenant_id": str, "agent_count": int }
|
|
# POST /api/portal/billing/portal -> { "portal_url": "https://billing.stripe.com/..." }
|
|
# Body: { "tenant_id": str }
|
|
# POST /api/webhooks/stripe -> webhook handler (no portal UI interaction)
|
|
```
|
|
|
|
From packages/shared/shared/models/tenant.py (updated in Plan 01):
|
|
```python
|
|
class Tenant(Base):
|
|
# New billing fields:
|
|
stripe_customer_id: Mapped[str | None]
|
|
stripe_subscription_id: Mapped[str | None]
|
|
stripe_subscription_item_id: Mapped[str | None]
|
|
subscription_status: Mapped[str] # "none" | "trialing" | "active" | "past_due" | "canceled" | "unpaid"
|
|
trial_ends_at: Mapped[datetime | None]
|
|
agent_quota: Mapped[int]
|
|
```
|
|
|
|
Established portal patterns:
|
|
- shadcn/ui components (Card, Badge, Button, Dialog)
|
|
- TanStack Query for data fetching
|
|
- API client in lib/api.ts
|
|
</interfaces>
|
|
</context>
|
|
|
|
<tasks>
|
|
|
|
<task type="auto">
|
|
<name>Task 1: Billing page with subscription management</name>
|
|
<files>
|
|
packages/portal/app/(dashboard)/billing/page.tsx,
|
|
packages/portal/components/subscription-card.tsx,
|
|
packages/portal/components/billing-status.tsx,
|
|
packages/portal/lib/queries.ts
|
|
</files>
|
|
<action>
|
|
1. Create `packages/portal/components/billing-status.tsx`:
|
|
- Badge component showing subscription status with color coding:
|
|
- "trialing" -> blue badge with trial end date
|
|
- "active" -> green badge
|
|
- "past_due" -> amber badge with "Payment required" text
|
|
- "canceled" -> red badge
|
|
- "none" -> gray badge "No subscription"
|
|
- Uses shadcn/ui Badge component
|
|
|
|
2. Create `packages/portal/components/subscription-card.tsx`:
|
|
- shadcn/ui Card displaying:
|
|
- BillingStatus badge (top right)
|
|
- Plan name: "AI Employee Plan" (per-agent monthly)
|
|
- Price: "$49/agent/month" (from user decision)
|
|
- Current agent count vs quota
|
|
- Trial info: if trialing, show "Trial ends {date}" with days remaining
|
|
- Agent count adjuster: +/- buttons to change quantity (triggers Stripe subscription item update)
|
|
- Action buttons:
|
|
- If status="none": "Subscribe" button -> creates Checkout Session -> redirects to Stripe
|
|
- If status="trialing" or "active": "Manage Billing" button -> creates Billing Portal session -> redirects to Stripe hosted portal
|
|
- If status="past_due": "Update Payment" button -> Billing Portal redirect
|
|
- If status="canceled": "Resubscribe" button -> new Checkout Session
|
|
|
|
3. Create `packages/portal/app/(dashboard)/billing/page.tsx`:
|
|
- Reads tenant_id from query or session
|
|
- Fetches tenant data (includes billing fields) via existing useTenant() hook
|
|
- Renders SubscriptionCard
|
|
- Handles ?session_id= searchParam (Stripe Checkout success redirect): show success toast, refetch tenant
|
|
- If subscription_status is "past_due": show a top banner warning about payment failure
|
|
- Per user decision: per-agent monthly pricing ($49/agent/month), 14-day free trial with full access, credit card required upfront
|
|
|
|
4. Add TanStack Query hooks to `packages/portal/lib/queries.ts`:
|
|
- useCreateCheckoutSession() — mutation POST /billing/checkout, returns { checkout_url }
|
|
- useCreateBillingPortalSession() — mutation POST /billing/portal, returns { portal_url }
|
|
- useUpdateSubscriptionQuantity() — mutation (if needed for +/- agent count)
|
|
|
|
5. Add "Billing" link to dashboard navigation/sidebar.
|
|
</action>
|
|
<verify>
|
|
<automated>cd /home/adelorenzo/repos/konstruct/packages/portal && npx next build 2>&1 | tail -20</automated>
|
|
</verify>
|
|
<done>
|
|
- Billing page renders subscription card with current status
|
|
- Subscribe button creates Checkout Session and redirects to Stripe
|
|
- Manage Billing button redirects to Stripe Billing Portal
|
|
- Status badges show correct colors for all subscription states
|
|
- Trial info displayed when status is "trialing"
|
|
- Past due banner shown when payment has failed
|
|
- Portal builds without errors
|
|
</done>
|
|
</task>
|
|
|
|
<task type="checkpoint:human-verify" gate="blocking">
|
|
<name>Task 2: Verify billing page and subscription UI</name>
|
|
<files>n/a</files>
|
|
<action>
|
|
Human verifies the billing management page:
|
|
1. Start the portal: `cd packages/portal && npm run dev`
|
|
2. Navigate to /billing — verify subscription card renders
|
|
3. Verify status badge shows "No subscription" for new tenant
|
|
4. Verify "Subscribe" button is present
|
|
5. Verify pricing shows "$49/agent/month" and "14-day free trial"
|
|
6. Verify "Billing" link appears in dashboard navigation
|
|
7. Check that agent count +/- controls are present
|
|
</action>
|
|
<verify>Human visual inspection of billing page</verify>
|
|
<done>Operator confirms billing page renders correctly with subscription card, pricing, and action buttons</done>
|
|
</task>
|
|
|
|
</tasks>
|
|
|
|
<verification>
|
|
- Portal builds: `cd packages/portal && npx next build`
|
|
- Billing page renders without errors
|
|
- All subscription states display correctly
|
|
- Navigation to billing page works
|
|
</verification>
|
|
|
|
<success_criteria>
|
|
- Operator can see subscription status and pricing on billing page
|
|
- Subscribe flow initiates Stripe Checkout redirect
|
|
- Billing Portal accessible for managing payment/invoices
|
|
- Status badges accurately reflect subscription_status field
|
|
- Portal builds successfully
|
|
</success_criteria>
|
|
|
|
<output>
|
|
After completion, create `.planning/phases/03-operator-experience/03-03-SUMMARY.md`
|
|
</output>
|