rebranding

tasks/kordant-unified-restructure/27-browser-extension-move.md

@@ -0,0 +1,125 @@
+# 27. Browser Extension — Move to browser-ext/ and Update API Client
+
+meta:
+  id: kordant-unified-restructure-27
+  feature: kordant-unified-restructure
+  priority: P1
+  depends_on: [kordant-unified-restructure-23]
+  tags: [extension, browser, api, migration]
+
+objective:
+- Move the browser extension from `packages/extension/` to `browser-ext/`, update its build configuration, and rewrite the API client to communicate with the unified monolith's tRPC endpoints instead of the legacy Fastify API.
+
+deliverables:
+- `browser-ext/` directory with all extension code:
+  - `src/background/index.ts` — Service worker (MV3)
+  - `src/content/index.ts` — Content script for phishing detection
+  - `src/popup/popup.html` + `popup.ts` — Extension popup UI
+  - `src/options/options.html` + `options.ts` — Options page
+  - `src/lib/api-client.ts` — Updated API client
+  - `src/lib/phishing-detector.ts` — Phishing detection logic (preserved)
+  - `src/lib/cache.ts` — Request caching (preserved)
+  - `src/lib/settings.ts` — Extension settings (preserved)
+  - `src/types/index.ts` — TypeScript types
+  - `public/manifest.json` — Manifest V3
+  - `public/icons/` — Extension icons
+  - `vite.config.ts` — Build config
+  - `package.json` — Dependencies
+- Updated `browser-ext/src/lib/api-client.ts`:
+  - Communicates with `https://api.kordant.com/api/trpc` (or local dev URL)
+  - Uses tRPC HTTP batch link for efficient requests
+  - Authenticates with API key (`x-api-key` header) or JWT
+  - Endpoints:
+    - `spamshield.checkNumber` — check phone number reputation
+    - `spamshield.classifySMS` — classify SMS text
+    - `extension.getAuthStatus` — check if user is linked
+    - `extension.linkDevice` — link extension to user account
+  - Error handling with retry logic
+- Updated `browser-ext/package.json`:
+  - Dependencies: `@trpc/client`, `superjson` (for serialization)
+  - Build scripts for Chrome/Firefox
+- Updated manifest:
+  - Permissions: `activeTab`, `storage`, `declarativeNetRequest`, `notifications`
+  - Host permissions: `https://api.kordant.com/*`, `https://*.kordant.com/*`
+
+steps:
+1. Create `browser-ext/` directory at project root.
+2. Move all files from `packages/extension/` to `browser-ext/`:
+   - `git mv packages/extension/src browser-ext/src`
+   - `git mv packages/extension/public browser-ext/public`
+   - `git mv packages/extension/vite.config.ts browser-ext/`
+   - `git mv packages/extension/package.json browser-ext/`
+   - Copy tests: `cp -r packages/extension/tests browser-ext/`
+3. Update `browser-ext/package.json`:
+   - Change name to `@kordant/browser-ext`
+   - Update dependencies: add `@trpc/client`, remove legacy API client deps
+   - Update build scripts
+4. Update `browser-ext/src/lib/api-client.ts`:
+   - Remove old Fastify REST client code
+   - Create tRPC proxy client:
+     ```ts
+     import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
+     import type { AppRouter } from '../../../web/src/server/api/root';
+     
+     export const api = createTRPCProxyClient<AppRouter>({
+       links: [httpBatchLink({ url: API_URL, headers: { 'x-api-key': API_KEY } })],
+     });
+     ```
+   - Note: Type import from web/ may need a shared types package or copy types. For now, use a generated type file.
+5. Update background script:
+   - On install: call `api.extension.linkDevice` with extension ID
+   - On SMS received (if API available): call `api.spamshield.classifySMS`
+   - On call received: call `api.spamshield.checkNumber`
+   - Cache results using existing `cache.ts`
+6. Update popup UI:
+   - Show auth status (linked/unlinked)
+   - Show recent spam detections
+   - Quick actions: "Check number", "Report spam"
+   - Use Kordant theme colors (import theme tokens or hardcode for now)
+7. Update content script:
+   - Preserve phishing detection logic
+   - Report detected phishing to `api.extension.reportPhishing`
+8. Update options page:
+   - Settings for API key, notification preferences
+   - Link/unlink account flow
+9. Update build config:
+   - `vite.config.ts` should output to `dist/` with correct manifest
+   - Add scripts for `build:chrome` and `build:firefox` if needed
+10. Test extension:
+    - Load unpacked extension in Chrome
+    - Verify popup renders
+    - Test API calls against local dev server
+
+steps:
+- Unit: API client creates correct tRPC requests
+- Unit: Background script caches API responses
+- Integration: Extension popup successfully calls `spamshield.checkNumber`
+- E2E: Install extension, link device, verify API key auth works
+
+acceptance_criteria:
+- [ ] Extension code lives in `browser-ext/` and builds successfully
+- [ ] API client uses tRPC instead of legacy REST endpoints
+- [ ] Background script handles install, SMS, and call events
+- [ ] Popup UI shows auth status and recent detections
+- [ ] Content script preserves phishing detection and reports to tRPC
+- [ ] Options page allows API key configuration and account linking
+- [ ] Extension works with both local dev and production API URLs
+- [ ] All existing tests pass after migration
+
+validation:
+- `cd browser-ext && pnpm build` completes without errors
+- Load `browser-ext/dist/` as unpacked extension in Chrome
+- Open popup and verify UI renders
+- Test API call by entering a phone number → verify tRPC request in Network tab
+- Run `cd browser-ext && pnpm test` for extension tests
+
+notes:
+- Reference legacy: `packages/extension/src/`
+- The extension cannot directly import from `web/` due to build isolation. Options for tRPC types:
+  1. Generate a standalone type file from the web app's router and copy it to `browser-ext/src/types/trpc.ts`
+  2. Create a shared `@kordant/types` package (but we're unifying, so avoid new packages)
+  3. Use `any` for the router type in extension (not recommended)
+  Recommended: Option 1 — generate types as part of web build.
+- The extension's popup UI is currently plain HTML/TS. Consider using a lightweight framework (e.g., SolidJS for popup) for consistency with the web app, but this is optional.
+- For Manifest V3, service workers have limited lifetime. Ensure API calls complete before worker sleeps.
+- The `declarativeNetRequest` API can block requests at the network level without a persistent background script. Consider using it for known phishing domains.