From b9e37bb8b47b6039d499de8d9416d0e9ae98f547 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Fri, 20 Mar 2026 18:47:18 -0700 Subject: [PATCH] feat(telemetry-client,diagnostics-client): add createWebTelemetry + createWebDiagnostics convenience factories - telemetry-client: createWebTelemetry() wraps createTelemetryClient() with web defaults - diagnostics-client: createWebDiagnostics() wraps DiagnosticsClient with install ID + web defaults - Eliminates ~70 lines of boilerplate per web app - 11/11 telemetry tests pass, 21/21 diagnostics tests pass --- .../WINDSURF/.last-refresh.log | 12 +- docs/WORKSPACE_INVENTORY.md | 114 ++++-- docs/learning_ai_common_plat_INVENTORY.md | 367 ++++++++++++------ packages/diagnostics-client/src/index.ts | 22 +- packages/diagnostics-client/src/web.ts | 111 ++++++ packages/telemetry-client/src/index.ts | 1 + packages/telemetry-client/src/web.ts | 81 ++++ 7 files changed, 526 insertions(+), 182 deletions(-) create mode 100644 packages/diagnostics-client/src/web.ts create mode 100644 packages/telemetry-client/src/web.ts diff --git a/__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/.last-refresh.log b/__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/.last-refresh.log index 701ed28c..65872c08 100644 --- a/__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/.last-refresh.log +++ b/__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/.last-refresh.log @@ -1,9 +1,9 @@ -Last refresh: 2026-03-20T06:00:09Z (2026-03-19 23:00:09 PDT) -Cascade conversations: 50 (381M) -Memories: 89 +Last refresh: 2026-03-21T00:06:30Z (2026-03-20 17:06:30 PDT) +Cascade conversations: 50 (409M) +Memories: 91 Implicit context: 20 -Code tracker dirs: 90 -File edit history: 3209 entries -Workspace storage: 34 workspaces +Code tracker dirs: 100 +File edit history: 3324 entries +Workspace storage: 36 workspaces Repo docs: 7 files across 2 repos Repo workflows: 43 files across 10 repos diff --git a/docs/WORKSPACE_INVENTORY.md b/docs/WORKSPACE_INVENTORY.md index 0e977e4f..25bf76c2 100644 --- a/docs/WORKSPACE_INVENTORY.md +++ b/docs/WORKSPACE_INVENTORY.md @@ -3,23 +3,28 @@ > **Purpose:** Workspace-level inventory for the active multi-repo ByteLyst development environment. > **Workspace Root:** `~/code/mygh/` > **Canonical Repo List:** `.windsurf/workflows/repos.txt` -> **Last Updated:** 2026-03-11 +> **Last Updated:** 2026-03-20 --- ## 1. Active Workspace Repositories -| Repository | Product / Role | Primary Stack | Current Scope | -| ----------------------------------- | --------------- | ------------------------------------------------------- | ------------------------------------------------------------------- | -| `learning_ai_common_plat` | Shared platform | TypeScript, Fastify, Next.js, Swift, Kotlin | 36 shared packages, 4 services, 3 dashboards, MCP/A2A orchestration | -| `learning_voice_ai_agent` | LysnrAI | Python 3.12, Fastify, Next.js, Swift, Kotlin | Desktop app, product backend, user dashboard, mobile apps | -| `learning_multimodal_memory_agents` | MindLyst | Kotlin Multiplatform, SwiftUI, Jetpack Compose, Next.js | Shared KMP core, iOS, Android, web dashboard | -| `learning_ai_clock` | ChronoMind | Next.js, SwiftUI, Kotlin, Fastify | Timer/focus product across web, Apple, Android, backend | -| `learning_ai_fastgap` | NomGap | React Native (Expo), Fastify | Fasting engine, mobile UI, product backend | -| `learning_ai_jarvis_jr` | JarvisJr | SwiftUI, Next.js, Kotlin, Fastify | Voice-first coaching apps, marketplace/backend | -| `learning_ai_peakpulse` | PeakPulse | SwiftUI, Fastify | Sensor-driven tracking app and backend | -| `learning_ai_notes` | NoteLett | Fastify, Next.js, React Native (Expo) | Structured notes platform across backend, web, and mobile | -| `learning_ai_flowmonk` | FlowMonk | Fastify, Next.js, React Native (Expo) | Agent-first planning platform across backend, web, and mobile | +| Repository | Product / Role | Primary Stack | Current Scope | +| ----------------------------------- | ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------- | +| `learning_ai_common_plat` | Shared platform | TypeScript, Fastify, Next.js, Swift, Kotlin | 53 shared packages, 4 services, 3 dashboards, MCP/A2A orchestration | +| `learning_voice_ai_agent` | LysnrAI | Python 3.12, Fastify, Next.js, Swift, Kotlin | Desktop app, product backend, user dashboard, mobile apps | +| `learning_multimodal_memory_agents` | MindLyst | Kotlin Multiplatform, SwiftUI, Jetpack Compose, Next.js | Shared KMP core, iOS, Android, web dashboard, product backend | +| `learning_ai_clock` | ChronoMind | Next.js, SwiftUI, Kotlin, Fastify | Timer/focus product across web, Apple, Android, backend | +| `learning_ai_fastgap` | NomGap | React Native (Expo), Next.js, Fastify | Fasting engine, mobile UI, web app, product backend | +| `learning_ai_jarvis_jr` | JarvisJr | SwiftUI, Next.js, Kotlin, Fastify | Voice-first coaching apps, marketplace/backend | +| `learning_ai_peakpulse` | PeakPulse | SwiftUI, Fastify | Sensor-driven tracking app and backend | +| `learning_ai_notes` | NoteLett | Fastify, Next.js, React Native (Expo) | Structured notes platform across backend, web, and mobile | +| `learning_ai_flowmonk` | FlowMonk | Fastify, Next.js, React Native (Expo) | Agent-first planning platform across backend, web, and mobile | +| `learning_ai_trails` | ActionTrail | Fastify, Next.js | AI activity oversight: actions, alerts, approvals, SDK | +| `learning_ai_smart_auth` | SmartAuth | Docs + extends platform-service | Unified auth & identity design (OneAuth, OAuth, MFA, Passkeys) | +| `learning_ai_auth_app` | ByteLyst Auth App | SwiftUI, Jetpack Compose | Standalone auth companion app (iOS, Android, watchOS, widgets) | +| `learning_ai_productivity_web` | Productivity Tools | Next.js | Internal productivity web tools | +| `learning_ai_local_memory_gpt` | LocalMemoryGPT | React, Express | Local memory-augmented GPT prototype | --- @@ -27,25 +32,29 @@ `learning_ai_common_plat` is the shared infrastructure layer for the whole workspace. -### 2.1 Shared Packages +### 2.1 Shared Packages (53 total) -- `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/logger`, `@bytelyst/testing` -- `@bytelyst/auth`, `@bytelyst/auth-client`, `@bytelyst/api-client`, `@bytelyst/platform-client`, `@bytelyst/react-auth` -- `@bytelyst/blob`, `@bytelyst/blob-client`, `@bytelyst/datastore`, `@bytelyst/storage`, `@bytelyst/sync`, `@bytelyst/offline-queue` -- `@bytelyst/telemetry-client`, `@bytelyst/diagnostics-client`, `@bytelyst/swift-diagnostics` -- `@bytelyst/feature-flag-client`, `@bytelyst/feedback-client`, `@bytelyst/broadcast-client`, `@bytelyst/survey-client`, `@bytelyst/kill-switch-client` -- `@bytelyst/design-tokens`, `@bytelyst/dashboard-components` -- `@bytelyst/extraction`, `@bytelyst/llm`, `@bytelyst/speech` -- `@bytelyst/swift-platform-sdk`, `@bytelyst/kotlin-platform-sdk`, `@bytelyst/react-native-platform-sdk` +- **Core:** `config`, `cosmos`, `errors`, `logger`, `testing`, `datastore`, `storage` +- **Auth:** `auth`, `auth-client`, `auth-ui`, `react-auth` +- **API/Clients:** `api-client`, `platform-client`, `broadcast-client`, `survey-client`, `feedback-client`, `marketplace-client`, `org-client`, `referral-client`, `subscription-client` +- **Telemetry/Diagnostics:** `telemetry-client`, `diagnostics-client`, `swift-diagnostics` +- **Feature Control:** `feature-flag-client`, `kill-switch-client` +- **Storage/Data:** `blob`, `blob-client`, `sync`, `offline-queue` +- **Backend Framework:** `fastify-core`, `fastify-sse`, `events`, `event-store`, `monitoring`, `push`, `queue`, `webhook-dispatch` +- **AI/ML:** `extraction`, `llm`, `llm-router`, `speech` +- **UI/UX:** `design-tokens`, `dashboard-components`, `dashboard-shell`, `celebrations`, `gentle-notifications`, `quick-actions`, `time-references`, `accessibility`, `create-app` +- **Platform SDKs:** `swift-platform-sdk`, `kotlin-platform-sdk`, `react-native-platform-sdk` + +_(All under the `@bytelyst/` scope — consumed via `file:` or `workspace:_` refs)\* ### 2.2 Services -| Service | Purpose | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `platform-service` | Product-agnostic platform APIs: auth, flags, telemetry, diagnostics, jobs, analytics, A/B testing, changelog, webhooks, marketplace, predictive analytics, and more | -| `extraction-service` | LangExtract-based extraction tasks with Python sidecar | -| `mcp-server` | MCP tool registry, tool execution, product/operator tools, and A2A orchestration pipelines | -| `monitoring` | Loki/Grafana and health-check infrastructure | +| Service | Port | Purpose | +| -------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `platform-service` | 4003 | Product-agnostic platform APIs: auth, flags, telemetry, diagnostics, jobs, analytics, A/B testing, changelog, webhooks, marketplace, predictive analytics, orgs, SCIM, and more (63 modules) | +| `extraction-service` | 4005 | LangExtract-based extraction tasks with Python sidecar | +| `mcp-server` | 4007 | MCP tool registry, tool execution, product/operator tools, and A2A orchestration pipelines (14 tool namespaces) | +| `monitoring` | — | Loki/Grafana and health-check infrastructure | ### 2.3 Dashboards @@ -59,16 +68,19 @@ ## 3. Product Repos and Shared Platform Consumption -| Product | Shared Platform Dependencies | -| ---------- | --------------------------------------------------------------------------------- | -| LysnrAI | shared packages, platform-service, extraction-service, dashboards integration | -| MindLyst | shared packages, extraction integration, design tokens, platform-service patterns | -| ChronoMind | shared packages, design token flow, platform-service patterns | -| NomGap | React Native platform SDK, shared packages, platform-service patterns | -| JarvisJr | shared SDKs, platform-service, marketplace patterns | -| PeakPulse | Swift platform SDK, shared platform wrappers, design/system patterns | -| NoteLett | shared packages, platform-service, extraction-service, mobile/web client patterns | -| FlowMonk | shared packages, platform-service, offline queue, planning-platform patterns | +| Product | Port | Shared Platform Dependencies | +| ------------- | ---- | --------------------------------------------------------------------------------- | +| LysnrAI | 4015 | shared packages, platform-service, extraction-service, dashboards integration | +| MindLyst | 4014 | shared packages, extraction integration, design tokens, platform-service patterns | +| ChronoMind | 4011 | shared packages, design token flow, platform-service patterns | +| NomGap | 4013 | React Native platform SDK, shared packages, platform-service patterns | +| JarvisJr | 4012 | shared SDKs, platform-service, marketplace patterns | +| PeakPulse | 4010 | Swift platform SDK, shared platform wrappers, design/system patterns | +| NoteLett | 4016 | shared packages, platform-service, extraction-service, mobile/web client patterns | +| FlowMonk | 4017 | shared packages, platform-service, offline queue, planning-platform patterns | +| ActionTrail | 4018 | shared packages, platform-service, SSE/webhooks, SDK (@actiontrail/sdk) | +| SmartAuth | — | Extends platform-service auth module (no separate backend) | +| ByteLyst Auth | — | Consumes platform-service directly via Swift/Kotlin platform SDKs | --- @@ -82,7 +94,23 @@ --- -## 5. Recommended Source-of-Truth Docs +## 5. Test Count Summary + +| Component | Tests | +| -------------------- | ---------- | +| platform-service | ~1,050+ | +| extraction-service | ~47 | +| Product backends (9) | ~1,217 | +| ActionTrail SDK | 21 | +| ActionTrail E2E | 40 | +| Kotlin platform SDK | 57 | +| NomGap mobile tests | 505 | +| ChronoMind web tests | 373 | +| **Estimated total** | **3,500+** | + +--- + +## 6. Recommended Source-of-Truth Docs | Scope | Document | | ------------------------------ | --------------------------------------------- | @@ -91,11 +119,15 @@ | Agent implementation guidance | `AGENTS.md` | | High-level architecture | `docs/architecture/ECOSYSTEM_ARCHITECTURE.md` | | Canonical active repo list | `.windsurf/workflows/repos.txt` | +| MCP/A2A orchestration | `docs/MCP+A2A/README.md` | +| Azure resource inventory | `docs/devops/AZURE_RESOURCE_INVENTORY.md` | --- -## 6. Notes +## 7. Notes -- This document reflects the currently active nine-repo workspace rather than the earlier three-repo migration model. +- This document reflects the currently active 13-repo workspace (plus 1 prototype repo). - Product-specific backends now live in their product repositories, while `learning_ai_common_plat` remains product-agnostic. -- `mcp-server` and `ux-lab` are active capability surfaces and should be included in future inventory updates. +- `mcp-server` and `ux-lab` are active capability surfaces. +- `learning_ai_local_memory_gpt` is a standalone prototype, not part of the ByteLyst ecosystem. +- `learning_ai_productivity_web` is an internal tools site, not a consumer of platform-service. diff --git a/docs/learning_ai_common_plat_INVENTORY.md b/docs/learning_ai_common_plat_INVENTORY.md index a3b7145d..514f86d7 100644 --- a/docs/learning_ai_common_plat_INVENTORY.md +++ b/docs/learning_ai_common_plat_INVENTORY.md @@ -2,7 +2,7 @@ > **Purpose:** Comprehensive reference for all reusable components, services, SDKs, and tools available to ByteLyst product teams. > **Repo:** `learning_ai_common_plat` -> **Last Updated:** 2026-03-05 +> **Last Updated:** 2026-03-20 --- @@ -10,12 +10,15 @@ | Category | Count | Notes | | --------------------- | ------- | -------------------------------------------------------------------- | -| **Shared Packages** | 36 | `@bytelyst/*` — consumed via `file:` or `workspace:*` | +| **Shared Packages** | 53 | `@bytelyst/*` — consumed via `file:` or `workspace:*` | | **Platform Services** | 4 | `platform-service`, `extraction-service`, `mcp-server`, `monitoring` | | **Dashboards** | 3 | `admin-web`, `tracker-web`, `ux-lab` | | **Platform SDKs** | 3 | Swift, Kotlin, React Native | -| **Cosmos Containers** | ~50+ | Shared + product-specific | -| **Total Tests** | ~1,700+ | Service + package + SDK tests | +| **Platform Modules** | 63 | platform-service route modules | +| **MCP Namespaces** | 14 | mcp-server tool namespaces + A2A pipelines | +| **Product Configs** | 7 | `products/` manifests for each product | +| **Cosmos Containers** | ~65+ | Shared + product-specific | +| **Total Tests** | ~2,200+ | Service + package + SDK tests (platform + products) | --- @@ -33,26 +36,31 @@ ### 2.2 Auth & Identity -| Package | Purpose | Exports | Consumers | -| ----------------------- | -------------------------- | -------------------------------------------------------------------------------- | ------------------------- | -| `@bytelyst/auth` | JWT + password hashing | `createJwtUtils`, `hashPassword`, `verifyPassword`, `extractAuth`, `requireRole` | All services + dashboards | -| `@bytelyst/auth-client` | Client-side auth utilities | Token refresh, storage abstractions | Web + React Native | -| `@bytelyst/react-auth` | React auth context factory | `createAuthContext()` — typed provider + hook | Next.js dashboards | +| Package | Purpose | Exports | Consumers | +| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------- | ------------------------- | +| `@bytelyst/auth` | JWT + password hashing | `createJwtUtils`, `hashPassword`, `verifyPassword`, `extractAuth`, `requireRole` | All services + dashboards | +| `@bytelyst/auth-client` | Client-side auth utilities | Token refresh, storage abstractions | Web + React Native | +| `@bytelyst/auth-ui` | Pre-built auth UI components | Login, MFA challenge, passkey views (React) | Dashboards + auth app | +| `@bytelyst/react-auth` | React auth context factory | `createAuthContext()` — typed provider + hook | Next.js dashboards | ### 2.3 API & Clients -| Package | Purpose | Exports | Consumers | -| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------- | -| `@bytelyst/api-client` | Typed fetch wrapper | `createApiClient()` with auth injection | Web + RN | -| `@bytelyst/platform-client` | Platform service client | Typed fetch with 401 retry | Web + RN | -| `@bytelyst/broadcast-client` | Broadcast/survey client | Poll and broadcast APIs | iOS + Android | -| `@bytelyst/survey-client` | Survey response client | Submit survey responses | iOS + Android | -| `@bytelyst/telemetry-client` | Telemetry ingestion | `createTelemetryClient()` with batching | All platforms | -| `@bytelyst/feature-flag-client` | Feature flag polling | `createFeatureFlagClient()` | All platforms | -| `@bytelyst/kill-switch-client` | Kill switch check | `createKillSwitchClient()` (fail-open) | All platforms | -| `@bytelyst/offline-queue` | Persistent retry queue | Configurable storage adapter | Web + RN | -| `@bytelyst/diagnostics-client` | Admin-triggered remote debug sessions | Session polling, trace spans, breadcrumbs, network/console/error capture, batch flush | ✅ All 6 products (web + iOS + RN) | -| `@bytelyst/feedback-client` | In-app feedback | Submit feedback + attachments | iOS + Android | +| Package | Purpose | Exports | Consumers | +| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------- | +| `@bytelyst/api-client` | Typed fetch wrapper | `createApiClient()` with auth injection | Web + RN | +| `@bytelyst/platform-client` | Platform service client | Typed fetch with 401 retry | Web + RN | +| `@bytelyst/broadcast-client` | Broadcast/survey client | Poll and broadcast APIs | iOS + Android | +| `@bytelyst/survey-client` | Survey response client | Submit survey responses | iOS + Android | +| `@bytelyst/marketplace-client` | Marketplace listing/purchase client | Browse, purchase, listing CRUD | Web + RN | +| `@bytelyst/org-client` | Organization management client | Org CRUD, member management | Web + RN | +| `@bytelyst/referral-client` | Referral system client | Referral creation, tracking, redemption | Web + RN | +| `@bytelyst/subscription-client` | Subscription management client | Plan selection, subscription lifecycle | Web + RN | +| `@bytelyst/telemetry-client` | Telemetry ingestion | `createTelemetryClient()` with batching | All platforms | +| `@bytelyst/feature-flag-client` | Feature flag polling | `createFeatureFlagClient()` | All platforms | +| `@bytelyst/kill-switch-client` | Kill switch check | `createKillSwitchClient()` (fail-open) | All platforms | +| `@bytelyst/offline-queue` | Persistent retry queue | Configurable storage adapter | Web + RN | +| `@bytelyst/diagnostics-client` | Admin-triggered remote debug sessions | Session polling, trace spans, breadcrumbs, network/console/error capture, batch flush | All products (web + iOS + RN) | +| `@bytelyst/feedback-client` | In-app feedback | Submit feedback + attachments | iOS + Android | ### 2.4 Storage & Data @@ -65,34 +73,46 @@ ### 2.5 Backend Framework -| Package | Purpose | Exports | Consumers | -| ------------------------ | ------------------------- | -------------------------------------------------- | -------------------- | -| `@bytelyst/fastify-core` | Service bootstrap | `createServiceApp()`, `startService()`, Swagger UI | All Fastify services | -| `@bytelyst/events` | In-memory event bus | `EventBus`, typed event schemas, error isolation | platform-service | -| `@bytelyst/monitoring` | Health checks + telemetry | Health utilities, Loki/Grafana helpers | All services | -| `@bytelyst/push` | Push notification service | APNS, FCM integration | platform-service | +| Package | Purpose | Exports | Consumers | +| ---------------------------- | ------------------------- | -------------------------------------------------- | -------------------- | +| `@bytelyst/fastify-core` | Service bootstrap | `createServiceApp()`, `startService()`, Swagger UI | All Fastify services | +| `@bytelyst/fastify-sse` | Server-Sent Events plugin | SSE route helpers, event streaming | Services with SSE | +| `@bytelyst/events` | In-memory event bus | `EventBus`, typed event schemas, error isolation | platform-service | +| `@bytelyst/event-store` | Persistent event store | Event append, query, replay | Services | +| `@bytelyst/webhook-dispatch` | Webhook delivery engine | HMAC signing, retry, dispatch | platform-service | +| `@bytelyst/queue` | Job/task queue | Queue management, workers | Services | +| `@bytelyst/monitoring` | Health checks + telemetry | Health utilities, Loki/Grafana helpers | All services | +| `@bytelyst/push` | Push notification service | APNS, FCM integration | platform-service | ### 2.6 AI/ML & Extraction -| Package | Purpose | Exports | Consumers | -| ---------------------- | ---------------------- | ---------------------------------------- | ---------------- | -| `@bytelyst/extraction` | Text extraction client | `createExtractionClient()`, shared types | Web + dashboards | -| `@bytelyst/llm` | LLM utilities | Prompt templates, token counting | Services | -| `@bytelyst/speech` | Speech SDK wrappers | Azure Speech integration | Desktop + Mobile | +| Package | Purpose | Exports | Consumers | +| ---------------------- | ------------------------- | --------------------------------------------------- | ---------------- | +| `@bytelyst/extraction` | Text extraction client | `createExtractionClient()`, shared types | Web + dashboards | +| `@bytelyst/llm` | LLM utilities | Prompt templates, token counting | Services | +| `@bytelyst/llm-router` | Deterministic LLM routing | Provider/model selection, fallback, health tracking | Services + MCP | +| `@bytelyst/speech` | Speech SDK wrappers | Azure Speech integration | Desktop + Mobile | ### 2.7 Platform Experience & Sync | Package | Purpose | Exports / Surface | Consumers | | -------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------ | | `@bytelyst/dashboard-components` | Shared dashboard UI building blocks | Reusable admin/tracker UI primitives | Dashboards | +| `@bytelyst/dashboard-shell` | Dashboard layout + navigation shell | Sidebar, breadcrumbs, page wrappers | Dashboards | +| `@bytelyst/create-app` | App scaffolding CLI/templates | Project generator, template engine | New product setup | | `@bytelyst/sync` | Cross-platform sync helpers | Sync orchestration, queueing, merge helpers | SDKs + mobile apps | | `@bytelyst/swift-diagnostics` | Swift diagnostics support | Crash/error helpers, diagnostics capture | Apple platforms | -### 2.8 Design System +### 2.8 Design System & UX -| Package | Purpose | Exports | Consumers | -| ------------------------- | --------------------- | --------------------------------- | ------------- | -| `@bytelyst/design-tokens` | Cross-platform tokens | CSS, TS, Kotlin, Swift generation | All platforms | +| Package | Purpose | Exports | Consumers | +| -------------------------------- | ----------------------------- | ------------------------------------- | ------------- | +| `@bytelyst/design-tokens` | Cross-platform tokens | CSS, TS, Kotlin, Swift generation | All platforms | +| `@bytelyst/celebrations` | Achievement/milestone effects | Confetti, toasts, celebrations | Mobile + Web | +| `@bytelyst/gentle-notifications` | Non-intrusive notifications | Subtle notification patterns | Mobile + Web | +| `@bytelyst/quick-actions` | Shortcut/quick-action helpers | Action registration, command palette | Mobile + Web | +| `@bytelyst/time-references` | Familiar time references | Relative time, time blindness helpers | Web + Mobile | +| `@bytelyst/accessibility` | Accessibility utilities | VoiceOver, Dynamic Type, a11y checks | All platforms | ### 2.9 React Native @@ -108,7 +128,7 @@ Consolidated from billing-service, growth-service, tracker-service. -**Status:** Active | **Tests:** ~1,050+ | **Modules:** 45 +**Status:** Active | **Tests:** ~1,050+ | **Modules:** 63 **Route Note:** Route families below are shown in their deployed form. Most are registered under the `/api` prefix unless explicitly public. @@ -157,6 +177,26 @@ Consolidated from billing-service, growth-service, tracker-service. | **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` | | **changelog** | Product changelogs | `changelogs` | `/api/changelog`, `/api/admin/changelog` | | **ratelimit** | Rate limiting | `rate_limit_windows` | `/ratelimit/*` | +| **agent-evals** | Agent evaluation framework | `agent_evals` | `/api/agent-evals/*` | +| **agents** | Agent registry + prompt versioning | `agents` | `/api/agents/*` | +| **ai-budgets** | AI spend/budget governance | `ai_budgets` | `/api/ai-budgets/*` | +| **api-versioning** | API version management | `api_versions` | `/api/api-versioning/*` | +| **backups** | Backup/restore management | `backups` | Admin only | +| **billing-checkout** | Stripe Checkout session creation | — | `/api/billing-checkout/*` | +| **cdn** | CDN/asset pipeline management | `cdn_assets` | `/api/cdn/*` | +| **dunning** | Billing dunning/retry for failed payments | `dunning_attempts` | Internal | +| **event-subscriptions** | Durable event bus subscriptions | `event_subscriptions` | `/api/event-subscriptions/*` | +| **experiments** | Experiment management | `experiments` | `/api/experiments/*` | +| **knowledge** | Knowledge base / RAG content | `knowledge_articles` | `/api/knowledge/*` | +| **onboarding** | User onboarding flows | `onboarding_progress` | `/api/onboarding/*` | +| **orgs** | Organization/workspace management | `orgs`, `org_members` | `/api/orgs/*` | +| **retention** | Data retention policies | `retention_policies` | Admin only | +| **reviews** | Human review/approval queues | `reviews` | `/api/reviews/*` | +| **runs** | Agent run tracking + orchestration | `runs`, `run_steps` | `/api/runs/*` | +| **scim** | SCIM provisioning (enterprise SSO) | `scim_resources` | `/scim/v2/*` | +| **search** | Full-text search | `search_index` | `/api/search/*` | +| **support-cases** | Support case management | `support_cases` | `/api/support-cases/*` | +| **tenants** | Multi-tenant isolation | `tenants` | `/api/tenants/*` | ### 3.2 extraction-service (Port 4005) @@ -167,18 +207,26 @@ Consolidated from billing-service, growth-service, tracker-service. | **extract** | Text extraction (LangExtract) | Python + TypeScript hybrid | | **tasks** | Extraction task management | TypeScript | -### 3.3 mcp-server (Tooling + A2A orchestration) +### 3.3 mcp-server (Port 4007 — Tooling + A2A orchestration) -**Status:** Active | **Primary Role:** Tool registry + MCP tool execution + A2A orchestration layer +**Status:** Active | **Primary Role:** Tool registry + MCP tool execution + A2A orchestration layer | **Namespaces:** 14 -| Namespace / Area | Purpose | Surface | -| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | -| **tools** | Tool registry, schema exposure, execution routing | `/api/tools`, `/api/tools/call` | -| **platform** | Admin/operator tools for telemetry, diagnostics, secrets, experiments, SDK, webhooks, ops | MCP tools | -| **extraction** | MCP wrappers for extraction workflows | MCP tools | -| **a2a** | Cross-product agent-to-agent pipelines and orchestration flows | Pipeline tools | -| **dev** | Changelog generation, synthetic data generation, internal dev tooling | MCP tools | -| **product namespaces** | Product-specific tool entry points for LysnrAI, JarvisJr, ChronoMind, NomGap, PeakPulse, MindLyst, tracker | MCP tools | +| Namespace / Area | Purpose | Surface | +| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------- | +| **tools** | Tool registry, schema exposure, execution routing | `/api/tools`, `/api/tools/call` | +| **platform** | Admin/operator tools for telemetry, diagnostics, secrets, experiments, SDK, webhooks, ops | MCP tools (8 sub-modules) | +| **extraction** | MCP wrappers for extraction workflows | MCP tools | +| **a2a** | Cross-product agent-to-agent pipelines and orchestration flows | Pipeline tools (38 items) | +| **dev** | Changelog generation, synthetic data generation, internal dev tooling | MCP tools | +| **support** | Support case tools | MCP tools | +| **notes** | NoteLett-specific MCP tools | MCP tools | +| **lysnrai** | LysnrAI product tools | MCP tools | +| **jarvis** | JarvisJr product tools | MCP tools | +| **chronomind** | ChronoMind product tools | MCP tools | +| **nomgap** | NomGap product tools | MCP tools | +| **peakpulse** | PeakPulse product tools | MCP tools | +| **mindlyst** | MindLyst product tools | MCP tools | +| **tracker** | Tracker product tools | MCP tools | ### 3.4 monitoring @@ -231,10 +279,16 @@ Consolidated from billing-service, growth-service, tracker-service. **Stack:** Experimental/internal dashboard workbench for operations UI kits, scoped prototypes, and MCP-driven UX workflows. -| Area | Description | -| ------------------ | ---------------------------------------------------------------------------------- | -| `bolt-ops-ui-kit/` | Internal UI kit and scoping docs for ops/dashboard work | -| Prototypes | Workspace for UX exploration, MCP-assisted workflows, and internal experimentation | +| Area | Description | +| ----------------------------------- | ------------------------------------------------------- | +| `bolt-command-palette-kit/` | Command palette UX prototype | +| `bolt-ops-ui-kit/` | Internal UI kit and scoping docs for ops/dashboard work | +| `bolt-telemetry-explorer/` | Telemetry data exploration prototype | +| `bolt-timeline-studio/` | Timeline visualization prototype | +| `lovable-design-tokens-playground/` | Design token preview/playground | +| `lovable-notify-states-kit/` | Notification state patterns prototype | +| `lovable-onboarding-flow/` | Onboarding flow UX prototype | +| `lovable-settings-ux-kit/` | Settings page UX patterns prototype | --- @@ -319,6 +373,7 @@ Workflow scripts for AI agents and developers: | Workflow | Purpose | | -------------------------- | -------------------------------------- | +| `README.md` | Skills directory overview | | `architecture-patterns.md` | Common architectural patterns | | `backup-main-branch.md` | Smart backup with duplicate detection | | `debug-service.md` | Debug failing services | @@ -342,21 +397,26 @@ Workflow scripts for AI agents and developers: ## 7. Scripts (`scripts/`) -| Script | Purpose | -| ----------------------------- | ------------------------------------- | -| `backup-main.sh` | Backup main branches across repos | -| `cosmos-telemetry-indexes.sh` | Create Cosmos indexes for telemetry | -| `docker-prep.sh` | Prepare for Docker builds | -| `export-lysnr-kv.sh` | Export LysnrAI Key Vault secrets | -| `prep-consumer.sh` | Prepare consumer builds | -| `railway-deploy.sh` | Deploy to Railway | -| `secret-scan-repo.sh` | Scan repo for secrets | -| `secret-scan-staged.sh` | Scan staged files | -| `seed-keyvault.sh` | Seed Key Vault with required secrets | -| `seed-lysnr-kv.sh` | Seed LysnrAI Key Vault | -| `setup-husky.sh` | Setup Git hooks | -| `switch-network.sh` | Switch between corporate/home network | -| `sync-workflows.md` | Sync workflows across repos | +| Script | Purpose | +| ----------------------------- | -------------------------------------------- | +| `backup-main.sh` | Backup main branches across repos | +| `check-prototype-env.sh` | Validate prototype environment vars | +| `cosmos-telemetry-indexes.sh` | Create Cosmos indexes for telemetry | +| `docker-prep.sh` | Prepare for Docker builds | +| `export-lysnr-kv.sh` | Export LysnrAI Key Vault secrets | +| `prep-consumer.sh` | Prepare consumer builds | +| `prototype-self-test.sh` | Host-side prototype smoke test | +| `prototype-up.sh` | Start prototype Docker stack | +| `railway-deploy.sh` | Deploy to Railway | +| `railway-sync-env.sh` | Sync env vars to Railway | +| `secret-scan-repo.sh` | Scan repo for secrets | +| `secret-scan-staged.sh` | Scan staged files | +| `seed-keyvault.sh` | Seed Key Vault with required secrets | +| `seed-lysnr-kv.sh` | Seed LysnrAI Key Vault | +| `setup-husky.sh` | Setup Git hooks | +| `switch-network.sh` | Switch between corporate/home network | +| `sync-workflows.sh` | Sync workflows across repos | +| `update-agent-docs.sh` | Regenerate AGENTS.md, CLAUDE.md across repos | --- @@ -364,14 +424,15 @@ Workflow scripts for AI agents and developers: Each product has a `product.json` manifest: -| Product | File | Backend Port | -| ---------- | ------------------------- | ------------ | -| LysnrAI | `lysnrai/product.json` | 4015 | -| MindLyst | `mindlyst/product.json` | 4014 | -| ChronoMind | `chronomind/product.json` | 4011 | -| JarvisJr | `jarvisjr/product.json` | 4012 | -| NomGap | `nomgap/product.json` | 4013 | -| PeakPulse | `peakpulse/product.json` | 4010 | +| Product | File | Backend Port | Repo | +| ---------- | ------------------------- | ------------ | ----------------------------------- | +| LysnrAI | `lysnrai/product.json` | 4015 | `learning_voice_ai_agent` | +| MindLyst | `mindlyst/product.json` | 4014 | `learning_multimodal_memory_agents` | +| ChronoMind | `chronomind/product.json` | 4011 | `learning_ai_clock` | +| JarvisJr | `jarvisjr/product.json` | 4012 | `learning_ai_jarvis_jr` | +| NomGap | `nomgap/product.json` | 4013 | `learning_ai_fastgap` | +| PeakPulse | `peakpulse/product.json` | 4010 | `learning_ai_peakpulse` | +| NoteLett | `notelett/product.json` | 4016 | `learning_ai_notes` | --- @@ -386,7 +447,9 @@ Each product has a `product.json` manifest: | `mobile_ANDROID_PLATFORM_SDK.md` | Android SDK design | | `mobile_IOS_PLATFORM_SDK.md` | iOS SDK design | | `mobile_REACT_NATIVE_PLATFORM_SDK.md` | React Native SDK design | +| `platform_ACCELERATION_ROADMAP.md` | Platform acceleration initiatives | | `platform_BACKEND_MIGRATION.md` | Backend consolidation | +| `platform_BROADCAST_SURVEY_ROADMAP.md` | Broadcast + survey system | | `platform_COMMON_EXTRACTION_ROADMAP.md` | Shared extraction | | `platform_COMPONENTS_ROADMAP.md` | Platform components (23 of 25 built) | | `platform_SERVICE_CONSOLIDATION_ROADMAP.md` | Service merger (4001→4003) | @@ -398,18 +461,80 @@ Each product has a `product.json` manifest: ## 10. Active/Planned Roadmaps (`docs/roadmaps/`) +### 10.1 Active Roadmaps + | Roadmap | Status | | -------------------------------------------- | ----------- | | `AI_DIAGNOSTIC_ASSISTANT_ROADMAP.md` | In Progress | | `INTELLIGENT_AB_TESTING_ROADMAP.md` | Active | +| `P3_PLATFORM_DEEPENING_ROADMAP.md` | Active | | `PREDICTIVE_CHURN_HEALTH_SCORING_ROADMAP.md` | Active | -| `WORKSPACE_REVIEW_2026_03_03.md` | Active | +| `SHARED_CLIENT_PACKAGES_ROADMAP.md` | Active | +| `WORKSPACE_REVIEW_2026_03_19.md` | Active | + +### 10.2 Scaffolded Roadmaps (`docs/roadmaps/scaffolded/`) + +| Roadmap | Focus Area | +| ---------------------------------------------------------- | ---------------------------------- | +| `platform_AGENT_REGISTRY_PROMPT_VERSIONING_ROADMAP.md` | Agent registry + prompt versioning | +| `platform_AGENT_RUNTIME_ORCHESTRATION_ROADMAP.md` | Agent runtime orchestration | +| `platform_AI_BUDGET_COST_GOVERNANCE_ROADMAP.md` | AI spend/budget governance | +| `platform_AI_GOVERNANCE_EVALS_ROADMAP.md` | AI governance + evaluations | +| `platform_DURABLE_EVENT_BUS_AND_WORKER_RUNTIME_ROADMAP.md` | Durable event bus + worker runtime | +| `platform_ENTERPRISE_PROVISIONING_SCIM_ROADMAP.md` | Enterprise SCIM provisioning | +| `platform_HUMAN_REVIEW_APPROVAL_QUEUE_ROADMAP.md` | Human review/approval queues | +| `platform_KNOWLEDGE_RAG_SERVICE_ROADMAP.md` | Knowledge base / RAG service | +| `platform_ORG_WORKSPACE_RBAC_ROADMAP.md` | Org/workspace RBAC | +| `platform_SUPPORT_CASE_MANAGEMENT_ROADMAP.md` | Support case management | + +### 10.3 Not Started + +| Roadmap | Focus Area | +| ---------------------------------------------- | --------------------------------- | +| `platform_AGENT_PLATFORM_GAP_ROADMAP_INDEX.md` | Agent platform gap analysis index | --- -## 11. How to Consume +## 11. Documentation Directory (`docs/`) -### 11.1 TypeScript Packages (Services/Dashboards) +| Subdirectory / File | Purpose | +| -------------------------------------- | ------------------------------------------------------------------------------------------- | +| `architecture/` | Ecosystem architecture, cloud migration analysis | +| `audits/` | Security audit, auth analysis, Fastify-core audit, FlowMonk audit | +| `design/` | Agent prompts sync, client telemetry design, cross-product dashboard | +| `design-system/` | Design system documentation | +| `devops/` | Azure portal/resource/KV setup, Railway runbook, env audit, diagnostics | +| `guides/` | Migration guide, platform playbook, workflow sync, anti-patterns | +| `MCP+A2A/` | MCP server framework, A2A orchestration, domain docs, execution checklist, use-case catalog | +| `roadmaps/` | 16 completed, 6 active, 10 scaffolded, 1 not-started | +| `session-logs/` | Session history logs | +| `workstreams/` | Active workstream tracking | +| `BROADCAST_SURVEY_API_REFERENCE.md` | Broadcast + survey API reference | +| `PROTOTYPE_DEPLOYMENT.md` | Prototype deployment guide | +| `WORKSPACE_INVENTORY.md` | Workspace-level inventory (this repo + all products) | +| `learning_ai_common_plat_INVENTORY.md` | This file — common-plat repo inventory | + +--- + +## 12. Local LLMs Infrastructure (`__LOCAL_LLMs/`) + +| Area | Purpose | +| ------------------------ | --------------------------------------------------- | +| `dashboard/` | Next.js local LLM dashboard (Ollama chat UI) | +| `AI_IDE_CHAT_HISTORY/` | Windsurf chat history archive | +| `OPEN_CLAW/` | Personal AI assistant prototype | +| `VOICEBOX/` | Local TTS/voice setup | +| `oss_llm/` | Open-source LLM experiments (nanoGPT, model search) | +| `windows_specific/` | Windows-specific LLM setup scripts | +| `setup-tts.sh` | One-shot TTS model setup | +| `download-tts-models.sh` | Model weight downloader (hf-mirror for corp proxy) | +| `start-dashboard.sh` | Start local LLM dashboard | + +--- + +## 13. How to Consume + +### 13.1 TypeScript Packages (Services/Dashboards) ```json // package.json @@ -429,7 +554,7 @@ import { createJwtUtils } from '@bytelyst/auth'; import { loadProductIdentity } from '@bytelyst/config'; ``` -### 11.2 Swift SDK (iOS) +### 13.2 Swift SDK (iOS) ```swift // Package.swift @@ -442,7 +567,7 @@ import ByteLystPlatformSDK let config = BLPlatformConfig(productId: "myproduct", baseURL: "...") ``` -### 11.3 Kotlin SDK (Android) +### 13.3 Kotlin SDK (Android) ```kotlin // settings.gradle.kts @@ -456,7 +581,7 @@ import com.bytelyst.platform.BLPlatformConfig val config = BLPlatformConfig(productId = "myproduct", baseURL = "...") ``` -### 11.4 React Native SDK +### 13.4 React Native SDK ```json // package.json @@ -469,7 +594,7 @@ val config = BLPlatformConfig(productId = "myproduct", baseURL = "...") --- -## 12. Build Verification Commands +## 14. Build Verification Commands ```bash # Full platform build @@ -497,51 +622,55 @@ cd dashboards/tracker-web && npm run build --- -## 13. Architecture Diagram +## 15. Architecture Diagram ``` -┌─────────────────────────────────────────────────────────────┐ -│ PRODUCT APPS │ -│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐│ -│ │LysnrAI │ │MindLyst │ │ChronoM. │ │JarvisJr │ │NomGap ││ -│ │PeakPulse│ │ │ │ │ │ │ │ ││ -│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘│ -│ │ │ │ │ │ │ -│ └───────────┴───────────┴───────────┴───────────┘ │ -│ │ │ -│ ┌──────────┴──────────┐ │ -│ │ Platform SDKs │ │ -│ │ (Swift/Kotlin/RN) │ │ -│ └──────────┬──────────┘ │ -└─────────────────────────┼───────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────────────┐ +│ PRODUCT APPS (9) │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │LysnrAI │ │MindLyst │ │ChronoM. │ │JarvisJr │ │NomGap │ │ +│ │ :4015 │ │ :4014 │ │ :4011 │ │ :4012 │ │ :4013 │ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ +│ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │ +│ │PeakPulse│ │NoteLett │ │FlowMonk │ │Action │ │ +│ │ :4010 │ │ :4016 │ │ :4017 │ │Trail │ │ +│ │ │ │ │ │ │ │ :4018 │ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ +│ └───────────┴───────────┴───────────┘ │ +│ │ │ +│ ┌──────────┴──────────┐ │ +│ │ Platform SDKs (3) │ │ +│ │ Swift/Kotlin/RN │ │ +│ └──────────┬──────────┘ │ +└─────────────────────────┼────────────────────────────────────────────────┘ │ -┌─────────────────────────┼───────────────────────────────────┐ -│ ┌──────────┴──────────┐ │ -│ │ Shared Packages │ │ -│ │ (@bytelyst/*) │ │ -│ └──────────┬──────────┘ │ -│ │ │ -│ ┌──────────────────────┼────────────────────────────────┐ │ -│ │ platform-service (4003) │ │ -│ │ auth │ billing │ flags │ telemetry │ blob │ etc. │ │ -│ └──────────────────────┬────────────────────────────────┘ │ -│ │ │ -│ ┌──────────────────────┼────────────────────────────────┐ │ -│ │ extraction-service (4005) │ │ -│ │ Text extraction (LangExtract) │ │ -│ └──────────────────────┬────────────────────────────────┘ │ -│ │ │ -│ ┌──────────┴──────────┐ │ -│ │ Azure Cosmos DB │ │ -│ │ Azure Blob Storage │ │ -│ │ Azure Key Vault │ │ -│ └───────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ +┌─────────────────────────┼────────────────────────────────────────────────┐ +│ ┌──────────┴──────────┐ │ +│ │ Shared Packages (53)│ │ +│ │ (@bytelyst/*) │ │ +│ └──────────┬──────────┘ │ +│ │ │ +│ ┌──────────────────────┼──────────────────────────────────────────┐ │ +│ │ platform-service (4003) — 63 modules │ │ +│ │ auth │ flags │ telemetry │ blob │ orgs │ billing │ etc. │ │ +│ └──────────────────────┬──────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────────────────┼──────────────────────────────────────────┐ │ +│ │ extraction-service (4005) │ mcp-server (4007) │ │ +│ │ Text extraction (LangExtract) │ MCP tools + A2A (14 ns) │ │ +│ └──────────────────────┬──────────────────────────────────────────┘ │ +│ │ │ +│ ┌──────────┴──────────┐ │ +│ │ Azure Cosmos DB │ │ +│ │ Azure Blob Storage │ │ +│ │ Azure Key Vault │ │ +│ └─────────────────────┘ │ +└───────────────────────────────────────────────────────────────────────────┘ ``` --- -## 14. Contact & Contribution +## 16. Contact & Contribution - **Primary Repo:** `learning_ai_common_plat` - **Package Scope:** `@bytelyst/*` diff --git a/packages/diagnostics-client/src/index.ts b/packages/diagnostics-client/src/index.ts index 20d209dc..426000b2 100644 --- a/packages/diagnostics-client/src/index.ts +++ b/packages/diagnostics-client/src/index.ts @@ -35,25 +35,15 @@ * ``` */ -export { - DiagnosticsClient, - type DiagnosticsClientOptions, -} from './client.js'; +export { DiagnosticsClient, type DiagnosticsClientOptions } from './client.js'; -export { - BreadcrumbTrail, - type BreadcrumbTrailOptions, -} from './breadcrumbs.js'; +export { createWebDiagnostics, type WebDiagnosticsConfig } from './web.js'; -export { - NetworkInterceptor, - type NetworkInterceptorOptions, -} from './network.js'; +export { BreadcrumbTrail, type BreadcrumbTrailOptions } from './breadcrumbs.js'; -export { - collectDeviceState, - subscribeToConnectivity, -} from './device.js'; +export { NetworkInterceptor, type NetworkInterceptorOptions } from './network.js'; + +export { collectDeviceState, subscribeToConnectivity } from './device.js'; export type { LogLevel, diff --git a/packages/diagnostics-client/src/web.ts b/packages/diagnostics-client/src/web.ts new file mode 100644 index 00000000..25aac86c --- /dev/null +++ b/packages/diagnostics-client/src/web.ts @@ -0,0 +1,111 @@ +/** + * Convenience factory for web dashboard diagnostics. + * + * Eliminates ~40 lines of boilerplate per web app by wrapping + * DiagnosticsClient.getInstance() with sensible web defaults. + * + * @example + * ```ts + * import { createWebDiagnostics } from '@bytelyst/diagnostics-client'; + * + * const { init, stop } = createWebDiagnostics({ + * productId: 'nomgap', + * channel: 'nomgap_web', + * serverUrl: 'http://localhost:4003', + * getAuthToken: () => localStorage.getItem('nomgap_access_token') ?? '', + * }); + * export { init as initDiagnostics, stop as stopDiagnostics }; + * ``` + */ + +import { DiagnosticsClient } from './client.js'; + +export interface WebDiagnosticsConfig { + /** Product identifier (e.g. 'nomgap', 'chronomind'). */ + productId: string; + /** Channel identifier (e.g. 'nomgap_web', 'pwa'). */ + channel: string; + /** Platform-service origin URL (no trailing /api). */ + serverUrl: string; + /** Function that returns the current auth token. */ + getAuthToken: () => string; + /** App version string. Default: '0.1.0'. */ + appVersion?: string; + /** Build number. Default: '1'. */ + buildNumber?: string; + /** Release channel. Default: 'dev'. */ + releaseChannel?: string; + /** OS family. Default: 'unknown'. */ + osFamily?: string; + /** Poll interval in ms. Default: 30000. */ + pollIntervalMs?: number; + /** Capture console logs. Default: false. */ + captureConsole?: boolean; + /** Capture JS errors. Default: true. */ + captureErrors?: boolean; + /** Capture network requests. Default: false. */ + captureNetwork?: boolean; +} + +export interface WebDiagnostics { + /** Initialize diagnostics. Safe to call on server (no-ops). Idempotent. */ + init(): void; + /** Stop diagnostics polling. */ + stop(): void; +} + +function getOrCreateInstallId(productId: string): string { + const key = `${productId}_diag_install_id`; + let id = localStorage.getItem(key); + if (!id) { + id = + typeof crypto?.randomUUID === 'function' + ? crypto.randomUUID() + : Math.random().toString(36).slice(2) + Date.now().toString(36); + localStorage.setItem(key, id); + } + return id; +} + +export function createWebDiagnostics(config: WebDiagnosticsConfig): WebDiagnostics { + let started = false; + + function init(): void { + if (typeof window === 'undefined') return; + if (started) return; + + DiagnosticsClient.getInstance({ + productId: config.productId, + anonymousInstallId: getOrCreateInstallId(config.productId), + platform: 'web', + channel: config.channel, + osFamily: config.osFamily ?? 'unknown', + appVersion: config.appVersion ?? '0.1.0', + buildNumber: config.buildNumber ?? '1', + releaseChannel: config.releaseChannel ?? 'dev', + serverUrl: config.serverUrl, + getAuthToken: config.getAuthToken, + pollIntervalMs: config.pollIntervalMs ?? 30_000, + captureConsole: config.captureConsole ?? false, + captureErrors: config.captureErrors ?? true, + captureNetwork: config.captureNetwork ?? false, + }); + + DiagnosticsClient.getInstance() + .start() + .catch(() => { + // Diagnostics is best-effort + }); + started = true; + } + + function stop(): void { + try { + DiagnosticsClient.getInstance().stop(); + } catch { + // not initialized + } + } + + return { init, stop }; +} diff --git a/packages/telemetry-client/src/index.ts b/packages/telemetry-client/src/index.ts index 378b8e07..ee02c77a 100644 --- a/packages/telemetry-client/src/index.ts +++ b/packages/telemetry-client/src/index.ts @@ -1,4 +1,5 @@ export { createTelemetryClient } from './client.js'; +export { createWebTelemetry, type WebTelemetryConfig } from './web.js'; export type { TelemetryClient, TelemetryClientConfig, diff --git a/packages/telemetry-client/src/web.ts b/packages/telemetry-client/src/web.ts new file mode 100644 index 00000000..47468d98 --- /dev/null +++ b/packages/telemetry-client/src/web.ts @@ -0,0 +1,81 @@ +/** + * Convenience factory for web dashboard telemetry. + * + * Eliminates ~30 lines of boilerplate per web app by wrapping + * createTelemetryClient() with sensible web defaults. + * + * @example + * ```ts + * import { createWebTelemetry } from '@bytelyst/telemetry-client'; + * + * const { client, init, trackPageView } = createWebTelemetry({ + * productId: 'nomgap', + * channel: 'nomgap_web', + * }); + * export { client as telemetryClient, init as initTelemetry, trackPageView }; + * ``` + */ + +import { createTelemetryClient } from './client.js'; +import type { TelemetryClient } from './types.js'; + +export interface WebTelemetryConfig { + /** Product identifier (e.g. 'nomgap', 'chronomind'). */ + productId: string; + /** Channel identifier (e.g. 'nomgap_web', 'pwa'). */ + channel: string; + /** Platform-service base URL. Default: 'http://localhost:4003/api'. */ + baseUrl?: string; + /** Telemetry ingest endpoint path. Default: '/telemetry/events'. */ + endpoint?: string; + /** Transport: 'beacon' or 'fetch'. Default: 'fetch'. */ + transport?: 'beacon' | 'fetch'; + /** App version string. Default: '0.1.0'. */ + appVersion?: string; + /** Build number. Default: '1'. */ + buildNumber?: string; + /** Release channel. Default: 'dev'. */ + releaseChannel?: string; + /** OS family. Default: 'other'. */ + osFamily?: string; +} + +export interface WebTelemetry { + /** The underlying telemetry client instance. */ + client: TelemetryClient; + /** Initialize telemetry and track app_initialized event. Idempotent. */ + init(): TelemetryClient; + /** Track a page view event. */ + trackPageView(page: string): void; +} + +export function createWebTelemetry(config: WebTelemetryConfig): WebTelemetry { + let initialized = false; + + const client = createTelemetryClient({ + productId: config.productId, + baseUrl: config.baseUrl ?? 'http://localhost:4003/api', + endpoint: config.endpoint ?? '/telemetry/events', + platform: 'web', + channel: config.channel, + transport: config.transport ?? 'fetch', + appVersion: config.appVersion ?? '0.1.0', + buildNumber: config.buildNumber ?? '1', + releaseChannel: config.releaseChannel ?? 'dev', + osFamily: config.osFamily ?? 'other', + }); + + function init(): TelemetryClient { + if (initialized) return client; + client.init(); + client.trackEvent('info', 'app_shell', 'web_app_initialized'); + initialized = true; + return client; + } + + function trackPageView(page: string): void { + client.trackEvent('info', 'navigation', 'page_view', { feature: page }); + } + + return { client, init, trackPageView }; +}