14 KiB
14 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-operator-experience | 02 | execute | 2 |
|
|
false |
|
|
Purpose: Operators can connect their messaging channels and onboard their AI employee through a guided wizard, plus manage their own LLM API keys -- all from the portal UI. Output: Onboarding wizard (connect channel -> configure agent -> test message), Slack OAuth callback handler, WhatsApp manual connect form, BYO key settings page.
<execution_context> @/home/adelorenzo/.claude/get-shit-done/workflows/execute-plan.md @/home/adelorenzo/.claude/get-shit-done/templates/summary.md </execution_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.mdFrom packages/shared/shared/api/channels.py (created in Plan 01):
# GET /api/portal/channels/slack/install?tenant_id={id} -> { "authorize_url": "https://slack.com/oauth/v2/authorize?..." }
# GET /api/portal/channels/slack/callback?code={code}&state={state} -> { "success": true, "workspace_name": "..." }
# POST /api/portal/channels/whatsapp/connect -> { "success": true } (body: { tenant_id, phone_number_id, waba_id, system_user_token })
# POST /api/portal/channels/{tenant_id}/test -> { "success": true, "message": "Test message sent" } (body: { channel_type })
From packages/shared/shared/api/llm_keys.py (created in Plan 01 Task 3):
# GET /api/portal/tenants/{tenant_id}/llm-keys -> [{ id, provider, label, key_hint, created_at }]
# POST /api/portal/tenants/{tenant_id}/llm-keys -> { id, provider, label, key_hint, created_at } (body: { provider, label, api_key })
# DELETE /api/portal/tenants/{tenant_id}/llm-keys/{key_id} -> 204
From packages/shared/shared/api/billing.py (created in Plan 01):
# POST /api/portal/billing/checkout -> { "checkout_url": "https://checkout.stripe.com/..." }
# POST /api/portal/billing/portal -> { "portal_url": "https://billing.stripe.com/..." }
From packages/shared/shared/crypto.py (created in Plan 01):
class KeyEncryptionService:
def encrypt(self, plaintext: str) -> str: ...
def decrypt(self, ciphertext: str) -> str: ...
def rotate(self, ciphertext: str) -> str: ...
From packages/portal/lib/api.ts:
// API client for FastAPI backend — use this for all portal API calls
From packages/portal/lib/queries.ts:
// TanStack Query hooks — add new hooks for channels, billing, usage here
Established patterns:
- shadcn/ui components
- react-hook-form + zod v4 + standardSchemaResolver
- TanStack Query for data fetching
- App Router with (dashboard) route group
- proxy.ts for auth protection (Next.js 16 pattern)
2. Create `packages/portal/components/onboarding-stepper.tsx`:
- 3-step stepper component using shadcn/ui: "Connect Channel" -> "Configure Agent" -> "Test Message"
- Visual progress indicator (numbered steps with active/complete/pending states)
- Step state managed via URL searchParams (step=1|2|3) for shareable/refreshable URLs
- Each step renders the corresponding step component
3. Create `packages/portal/app/(dashboard)/onboarding/page.tsx`:
- Reads `step` from searchParams (default 1)
- Reads `tenant_id` from session or query param
- Renders OnboardingStepper with the appropriate step component
- Guards: if no tenant selected, redirect to tenant selection
4. Create `packages/portal/app/(dashboard)/onboarding/steps/connect-channel.tsx`:
- Two cards: "Add to Slack" and "Connect WhatsApp"
- **Slack card:** Button that fetches /api/portal/channels/slack/install?tenant_id={id}, then does window.location.href = authorize_url (external redirect to Slack)
- **WhatsApp card:** Expandable form with 3 fields (Phone Number ID, WhatsApp Business Account ID, System User Token) + step-by-step instructions text
- On submit: POST /api/portal/channels/whatsapp/connect
- Validation with zod + react-hook-form
- On successful connection (either channel): advance to step 2 automatically
- If returning from Slack OAuth (connected=true in searchParams): show success toast and advance
5. Create `packages/portal/app/(dashboard)/onboarding/steps/configure-agent.tsx`:
- If tenant already has an agent: show existing agent summary with "Edit" link to Agent Designer
- If no agent: redirect to Agent Designer page with return URL back to onboarding?step=3
- Minimal step — the Agent Designer (from Phase 1) handles all agent configuration
- "Next" button enabled only when at least one active agent exists for the tenant
6. Create `packages/portal/app/(dashboard)/onboarding/steps/test-message.tsx`:
- Shows connected channel(s) with a "Send Test Message" button per channel
- On click: POST /api/portal/channels/{tenant_id}/test with {channel_type}
- Shows loading state while test runs, then success/failure result
- On success: show "Your AI employee is live!" celebration message
- Agent goes live automatically (is_active already true by default) — NO separate "Go Live" button per user decision
- Per user decision: test message step is REQUIRED, not skippable
7. Add TanStack Query hooks to `packages/portal/lib/queries.ts`:
- useSlackInstallUrl(tenantId) — GET /channels/slack/install
- useConnectWhatsApp() — mutation POST /channels/whatsapp/connect
- useSendTestMessage() — mutation POST /channels/{tenantId}/test
- useChannelConnections(tenantId) — GET to list existing connections
2. Add TanStack Query hooks to `packages/portal/lib/queries.ts`:
- useLlmKeys(tenantId) — GET /api/portal/tenants/{tenant_id}/llm-keys
- useAddLlmKey() — mutation POST /api/portal/tenants/{tenant_id}/llm-keys
- useDeleteLlmKey() — mutation DELETE /api/portal/tenants/{tenant_id}/llm-keys/{keyId}
3. Add navigation link to settings/api-keys in the dashboard layout sidebar (if sidebar exists) or in the tenant detail page.
<success_criteria>
- Operator can initiate Slack OAuth from the portal
- Operator can paste WhatsApp credentials via guided form
- Onboarding wizard completes in 3 steps: connect -> configure -> test
- Agent goes live automatically after successful test message
- Operator can manage BYO API keys from settings page (backed by Plan 01 Task 3 endpoints)
- Portal builds without errors </success_criteria>