Files

ci/woodpecker/push/woodpecker Pipeline failed

Details

docs(#1 ): SDK integration guide, API reference, and CI pipeline

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

2026-02-14 22:38:19 -06:00

2.6 KiB

Raw Permalink Blame History

@mosaicstack/telemetry-client

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

Commands

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.

# .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:

git pull --rebase before editing
git pull --rebase before pushing
If conflicts, alert the user — don't auto-resolve data conflicts

2.6 KiB Raw Permalink Blame History