Jason Woltje
231a799a46
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
- Rewrite README with quick start, config table, prediction usage, API version note - Add docs/integration-guide.md with Next.js and Node.js examples, env-specific config, error handling patterns, batch behavior, and API version compatibility - Add docs/api-reference.md with full reference for all exported classes, methods, types, and enums - Add .woodpecker.yml with quality gates (lint, typecheck, format, security audit, test with coverage) and npm publish to Gitea registry - Add AGENTS.md and update CLAUDE.md with project conventions Fixes #1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
83 lines
2.6 KiB
Markdown
83 lines
2.6 KiB
Markdown
# @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
|
|
|