bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3fc0058d06
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

11 KiB
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:
cat docs/roadmaps/SHARED_CLIENT_PACKAGES_ROADMAP.md

// turbo 2. Study the canonical reference package structure:

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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/referral-client build && pnpm --filter @bytelyst/referral-client test
  1. Commit package 1:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/subscription-client build && pnpm --filter @bytelyst/subscription-client test
  1. Commit package 2:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/celebrations build && pnpm --filter @bytelyst/celebrations test
  1. Commit package 3:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/gentle-notifications build && pnpm --filter @bytelyst/gentle-notifications test
  1. Commit package 4:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/accessibility build && pnpm --filter @bytelyst/accessibility test
  1. Commit package 5:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/quick-actions build && pnpm --filter @bytelyst/quick-actions test
  1. Commit package 6:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/time-references build && pnpm --filter @bytelyst/time-references test
  1. Commit package 7:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/org-client build && pnpm --filter @bytelyst/org-client test
  1. Commit package 8:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm --filter @bytelyst/marketplace-client build && pnpm --filter @bytelyst/marketplace-client test
  1. Commit package 9:
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:

cd /Users/sd9235/code/mygh/learning_ai_common_plat && pnpm build && pnpm test && pnpm typecheck

  1. Update roadmap status — in docs/roadmaps/SHARED_CLIENT_PACKAGES_ROADMAP.md, change > **Status:** Not Started to > **Status:** ✅ Complete — 9 packages, ~76 tests

  2. Final commit:

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"
  1. Push all commits:
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