bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
fcfb2b8a59
learning_ai_common_plat/.windsurf/workflows/implement-shared-packages.md
saravanakumardb1 c87a8e9ef1 docs: fix 17 bugs/gaps in shared client packages roadmap + add workflow 
Review findings and fixes:
- Fix subscription routes use :userId not :id
- Fix GET /plans returns { plans: [...] } wrapper
- Fix org routes require admin-only JWT role
- Flag missing POST /referrals/apply endpoint
- Flag missing POST /subscriptions/restore endpoint
- Expand org-client and marketplace-client with full API signatures
- Add x-product-id header requirement
- Add NomGap Migration Plan
- Add Known Backend Gaps appendix
- Add /implement-shared-packages workflow
2026-03-19 11:02:42 -07:00

299 lines
11 KiB
Markdown
Raw Blame History

---
description: Implement all 9 shared @bytelyst/* client packages from the SHARED_CLIENT_PACKAGES_ROADMAP
---
# Implement Shared @bytelyst/\* Client Packages
## Pre-requisites
// turbo
1. Read the full roadmap doc:
```bash
cat docs/roadmaps/SHARED_CLIENT_PACKAGES_ROADMAP.md
```
// turbo 2. Study the canonical reference package structure:
```bash
cat packages/feature-flag-client/package.json packages/feature-flag-client/tsconfig.json packages/feature-flag-client/src/index.ts packages/feature-flag-client/src/types.ts packages/feature-flag-client/src/client.ts packages/feature-flag-client/src/client.test.ts
```
## Critical Rules
- **Package manager is pnpm** — NEVER use npm
- **ESM everywhere** — `"type": "module"`, `.js` extensions in all imports
- **No Node.js deps** — use `globalThis.fetch`, not node-fetch
- **No React/RN deps** — pure TypeScript only
- **Factory pattern** for API clients: `createXxxClient(config)` returning an interface
- **No `console.log`**, no `any` type
- **Every request to platform-service MUST include headers:**
- `x-product-id` (from config.productId)
- `Authorization: Bearer <token>` (from config.getAccessToken())
- **Tests in `src/client.test.ts`** (co-located, same as `@bytelyst/feature-flag-client`)
- **tsconfig.json must include `"lib": ["ES2022", "DOM"]`** and `"exclude": ["src/**/*.test.ts"]`
- **All API interfaces, backend types, and ⚠️ warnings are in the roadmap doc** — follow them exactly
## Implementation (commit after each package)
### Package 1: `packages/referral-client/`
Create `packages/referral-client/` with:
- `package.json` — `@bytelyst/referral-client`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — ReferralDoc, ReferralClientConfig (from roadmap doc)
- `src/client.ts` — `createReferralClient(config)` factory
- `src/index.ts` — re-exports
- `src/client.test.ts` — 8+ Vitest tests
⚠️ There is NO `/referrals/apply` endpoint. Use `PUT /referrals/:id` for status updates.
// turbo 3. Verify package 1:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/referral-client build && pnpm --filter @bytelyst/referral-client test
```
4. Commit package 1:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/referral-client/ && git commit -m "feat(referral-client): add @bytelyst/referral-client shared package"
```
### Package 2: `packages/subscription-client/`
Create `packages/subscription-client/` with:
- `package.json` — `@bytelyst/subscription-client`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — SubscriptionDoc, PlanConfig, SubscriptionClientConfig (from roadmap doc)
- `src/client.ts` — `createSubscriptionClient(config)` factory with caching
- `src/index.ts` — re-exports
- `src/client.test.ts` — 10+ Vitest tests
⚠️ `GET /plans` returns `{ plans: [...] }` — unwrap `.plans` in client.
⚠️ Routes use `:userId` not `:id` — use `config.userId`.
⚠️ `PlanConfig` fields `words`, `dictations`, `tokens` are LysnrAI-specific legacy. Use `features: string[]` for entitlements.
// turbo 5. Verify package 2:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/subscription-client build && pnpm --filter @bytelyst/subscription-client test
```
6. Commit package 2:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/subscription-client/ && git commit -m "feat(subscription-client): add @bytelyst/subscription-client shared package"
```
### Package 3: `packages/celebrations/`
Create `packages/celebrations/` with:
- `package.json` — `@bytelyst/celebrations`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — CelebrationTrigger, Celebration, CelebrationConfig
- `src/client.ts` — `createCelebrationEngine(config?)` factory
- `src/index.ts` — re-exports
- `src/client.test.ts` — 8+ Vitest tests
Pure TS, no backend. Products register custom triggers via `customTriggers` config. Messages ALWAYS positive.
// turbo 7. Verify package 3:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/celebrations build && pnpm --filter @bytelyst/celebrations test
```
8. Commit package 3:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/celebrations/ && git commit -m "feat(celebrations): add @bytelyst/celebrations shared package"
```
### Package 4: `packages/gentle-notifications/`
Create `packages/gentle-notifications/` with:
- `package.json` — `@bytelyst/gentle-notifications`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — GentleNotificationConfig, GentleMessage
- `src/client.ts` — `createGentleNotificationEngine(config?)` factory + `FORBIDDEN_PHRASES` export
- `src/index.ts` — re-exports
- `src/client.test.ts` — 8+ Vitest tests
Pure TS, no backend. Export `FORBIDDEN_PHRASES` constant. Support `registerMessages()` for product-specific pools.
// turbo 9. Verify package 4:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/gentle-notifications build && pnpm --filter @bytelyst/gentle-notifications test
```
10. Commit package 4:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/gentle-notifications/ && git commit -m "feat(gentle-notifications): add @bytelyst/gentle-notifications shared package"
```
### Package 5: `packages/accessibility/`
Create `packages/accessibility/` with:
- `package.json` — `@bytelyst/accessibility`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — A11yProps interface
- `src/client.ts` — label generator functions (buttonLabel, timerLabel, progressLabel, etc.)
- `src/index.ts` — re-exports
- `src/client.test.ts` — 10+ Vitest tests
Pure TS, no backend. Return A11yProps objects compatible with React Native accessibilityLabel/Role.
// turbo 11. Verify package 5:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/accessibility build && pnpm --filter @bytelyst/accessibility test
```
12. Commit package 5:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/accessibility/ && git commit -m "feat(accessibility): add @bytelyst/accessibility shared package"
```
### Package 6: `packages/quick-actions/`
Create `packages/quick-actions/` with:
- `package.json` — `@bytelyst/quick-actions`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — QuickAction, ProgressiveSection, SmartDefault
- `src/client.ts` — getVisibleSections, getAvailableActions, pickSmartDefault
- `src/index.ts` — re-exports
- `src/client.test.ts` — 6+ Vitest tests
Pure TS, no backend.
// turbo 13. Verify package 6:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/quick-actions build && pnpm --filter @bytelyst/quick-actions test
```
14. Commit package 6:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/quick-actions/ && git commit -m "feat(quick-actions): add @bytelyst/quick-actions shared package"
```
### Package 7: `packages/time-references/`
Create `packages/time-references/` with:
- `package.json` — `@bytelyst/time-references`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — TimeReference interface
- `src/client.ts` — getTimeReference, getEpisodeComparison, getEncouragingMessage, registerReferences
- `src/index.ts` — re-exports
- `src/client.test.ts` — 6+ Vitest tests
Pure TS, no backend. Support `registerReferences()` for custom reference databases.
// turbo 15. Verify package 7:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/time-references build && pnpm --filter @bytelyst/time-references test
```
16. Commit package 7:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/time-references/ && git commit -m "feat(time-references): add @bytelyst/time-references shared package"
```
### Package 8: `packages/org-client/`
Create `packages/org-client/` with:
- `package.json` — `@bytelyst/org-client`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — OrganizationDoc, WorkspaceDoc, MembershipDoc, LicenseDoc, OrgClientConfig
- `src/client.ts` — `createOrgClient(config)` factory
- `src/index.ts` — re-exports
- `src/client.test.ts` — 10+ Vitest tests
⚠️ All org routes require admin JWT role (`super_admin` or `admin`). Regular user tokens get 403.
Covers orgs + workspaces + memberships + licenses (4 entity types).
// turbo 17. Verify package 8:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/org-client build && pnpm --filter @bytelyst/org-client test
```
18. Commit package 8:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/org-client/ && git commit -m "feat(org-client): add @bytelyst/org-client shared package"
```
### Package 9: `packages/marketplace-client/`
Create `packages/marketplace-client/` with:
- `package.json` — `@bytelyst/marketplace-client`, version 0.1.0
- `tsconfig.json` — extends ../../tsconfig.base.json, lib: ["ES2022", "DOM"]
- `src/types.ts` — MarketplaceListingDoc, MarketplaceReviewDoc, MarketplaceInstallDoc, MarketplaceClientConfig, CreateListingInput
- `src/client.ts` — `createMarketplaceClient(config)` factory
- `src/index.ts` — re-exports
- `src/client.test.ts` — 10+ Vitest tests
⚠️ NomGap's influencer.ts is product-specific. This is the GENERIC marketplace client.
Covers listings + reviews + installs + reports.
// turbo 19. Verify package 9:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/marketplace-client build && pnpm --filter @bytelyst/marketplace-client test
```
20. Commit package 9:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add packages/marketplace-client/ && git commit -m "feat(marketplace-client): add @bytelyst/marketplace-client shared package"
```
## Final Verification
// turbo 21. Run full workspace verification:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm build && pnpm test && pnpm typecheck
```
22. Update roadmap status — in `docs/roadmaps/SHARED_CLIENT_PACKAGES_ROADMAP.md`, change `> **Status:** Not Started` to `> **Status:** ✅ Complete — 9 packages, ~76 tests`
23. Final commit:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git add docs/roadmaps/SHARED_CLIENT_PACKAGES_ROADMAP.md && git commit -m "docs: mark shared client packages roadmap as complete"
```
24. Push all commits:
```bash
cd /Users/sd9235/code/mygh/learning_ai_common_plat && git push origin main
```
## DO NOT
- Do NOT modify any files outside `packages/` and the roadmap doc
- Do NOT create packages in any other directory
- Do NOT install external dependencies — these packages have zero deps
- Do NOT skip tests — every package must have passing Vitest tests
- Do NOT modify platform-service or any product repo
- Do NOT use npm — this is a pnpm workspace
Reference in New Issue View Git Blame Copy Permalink