---
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