# @mosaicstack/telemetry-client

TypeScript/JavaScript client SDK for Mosaic Stack Telemetry. Zero runtime dependencies.

## Commands

```bash
npm install          # Install dependencies
npm run typecheck    # Type check
npm run lint         # Lint
npm run format:check # Format check
npm test             # Run tests
npm run test:coverage # Tests with coverage (85% threshold)
npm run build        # Build to dist/
```

## Architecture

- `client.ts` — TelemetryClient (main public API, setInterval-based background flush)
- `queue.ts` — EventQueue (bounded FIFO array)
- `submitter.ts` — BatchSubmitter (native fetch, exponential backoff, Retry-After)
- `prediction-cache.ts` — PredictionCache (Map + TTL)
- `event-builder.ts` — EventBuilder (auto-generates event_id, timestamp)
- `types/` — Standalone type definitions matching server API schema v1.0

## Key Patterns

- `track()` never throws — catches everything, routes to `onError` callback
- Zero runtime deps: uses native `fetch` (Node 18+), `crypto.randomUUID()`, `setInterval`
- All types are standalone — no dependency on the telemetry server package

## Conditional Documentation Loading

**Read the relevant guide before starting work:**

| Task Type | Guide |
|-----------|-------|
| Bootstrapping a new project | `~/.claude/agent-guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.claude/agent-guides/orchestrator.md` |
| Ralph autonomous development | `~/.claude/agent-guides/ralph-autonomous.md` |
| Frontend development | `~/.claude/agent-guides/frontend.md` |
| Backend/API development | `~/.claude/agent-guides/backend.md` |
| TypeScript strict typing | `~/.claude/agent-guides/typescript.md` |
| Code review | `~/.claude/agent-guides/code-review.md` |
| Authentication/Authorization | `~/.claude/agent-guides/authentication.md` |
| Infrastructure/DevOps | `~/.claude/agent-guides/infrastructure.md` |
| QA/Testing | `~/.claude/agent-guides/qa-testing.md` |
| Secrets management (Vault) | `~/.claude/agent-guides/vault-secrets.md` |


## Commits

```
<type>(#issue): Brief description

Detailed explanation if needed.

Fixes #123
```

Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`


## Secrets Management

**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.

```bash
# .env.example is committed (with placeholders)
# .env is NOT committed (contains real values)
```

Ensure `.gitignore` includes `.env*` (except `.env.example`).


## Multi-Agent Coordination

When multiple agents work on this project:
1. `git pull --rebase` before editing
2. `git pull --rebase` before pushing
3. If conflicts, **alert the user** — don't auto-resolve data conflicts