v0.4.0 — Production-readiness pack

This release focuses on correctness and operability: end-of-cycle parity, safe replays for late/backfilled events, first-class metrics/dashboards/alerts, and a concrete operator runbook.

Highlights

• Test Clocks parity demo — prove end-of-cycle invoice parity (drift ≈ 0 within ε).
• Replay API — POST /v1/replay with dry-run/apply and watermark/cursor semantics (safe, idempotent reprocessing).
• Shadow Mode (per meter) — push to Stripe test with deterministic idempotency keys; live invoices unaffected.
• Observability pack — /metrics labels, Prometheus scrape example, Grafana dashboard JSON.
• ALERTS.md — PromQL recipes (drift, p95 latency, queue lag, 5xx) + Alertmanager sample.
• RECONCILIATION.md — triage & repair runbook; copy-paste commands and drift report.

Try in 5 minutes → Verify in 30 seconds

git clone https://github.com/geminimir/stripemeter && cd stripemeter
cp .env.example .env && docker compose up -d && pnpm -r build && pnpm dev
curl -fsS http://localhost:3000/health/ready | jq . || true
TENANT_ID=$(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid) bash examples/api-calls/send.sh
curl -fsS http://localhost:3000/metrics | head -n 30  # duplicate counted once

Baseline (laptop) numbers

• p95 ingest: ~10–25 ms
• Re-aggregate 10k late events: ≤ 2 s
• Idempotency window 24 h: 0 double-counts

Upgrade notes

• Replay via API: POST /v1/replay (dry-run → apply). See README and docs/api/replay.md.
• Grafana dashboard JSON provided under ops/grafana/.
• See ALERTS.md and RECONCILIATION.md for production guardrails.

Thanks

Thanks to our contributors @coryli and @louispy!
If you can share attribution: “We caught a ~3% drift before invoice close.” — <team/company>

Links:

• README banner and quick demo at the top of the repo
• Full notes: docs/RELEASE_NOTES_v0.4.0.md

v0.3.0 - Usage History, Event Replay & Enhanced Developer Experience

Highlights

• Usage History API — Time-series data to visualize counter changes before/after replay
• Event Replay System — Dry-run/apply mode with watermark/cursor semantics for historical event processing
• Reconciliation Summary API — Pre-invoice drift detection and counter validation
• Idempotency Support — Idempotency-Key header support for reliable event ingestion
• Enhanced Developer Experience — Per-event results, relaxed tenant validation, and improved error handling

Why This Matters

This release transforms StripeMeter from a basic usage tracking system into a comprehensive reconciliation platform. You can now:

• Prove accuracy with time-series usage history and reconciliation summaries
• Handle late events safely with the new replay system
• Ensure reliability with idempotency support and per-event status tracking
• Simplify integration with relaxed tenant ID validation

Upgrade Guide

New APIs Available

• GET /v1/usage/history - Retrieve time-series usage data
• POST /v1/replay - Replay historical events with dry-run/apply modes
• GET /v1/reconciliation/summary - Get drift analysis and counter validation

Enhanced Ingest API

• Add Idempotency-Key header to prevent duplicate processing
• Response now includes per-event statuses and requestId for tracking
• tenantId validation relaxed from UUID to string (server-normalized)

Deprecated Endpoints

• /v1/events/backfill endpoints are deprecated in favor of POST /v1/replay

Breaking Changes

None - this is a fully backward-compatible release.

Full Changelog

Added

• Usage History API — GET /v1/usage/history returns time-series plus totals to visualize counters before/after replay. (#61)
• Reconciliation Summary API — GET /v1/reconciliation/summary reports drift and counters so you can prove pre-invoice parity. (#62)
• Backfill & Event Replay System — POST /v1/replay with dry-run/apply and watermark/cursor semantics (single worker MVP). (#44)
• Readiness checks — minimal health probes for Stripe ping + Redis ping. (#38)
• Production Auth / Tenancy / RBAC / API keys (initial) — base capabilities landed and tracked under a single issue. (#45)

Developer Experience

• Idempotency on ingest — Idempotency-Key header accepted on POST /v1/events/ingest. (#58)
• Per-event ingest results — response now includes per-event statuses and a requestId. (#59)
• Tenant ID DX — relaxed tenantId validation from UUID to string (server-normalized). (#60)

Documentation & Demos

• Operator runbook — reconciliation triage/repair steps for the "first 5 minutes." (#57)
• Stripe Test Clocks Parity Walkthrough — end-to-end demo that proves drift → 0 before Stripe closes the invoice. (#53)

Contributors

Thank you to all the contributors who made v0.3.0 possible:

• @louispy
• @coryli

Want to contribute? Check out our Contributing Guide and join the discussion in GitHub Discussions.

Highlights

• Events API: GET /v1/events with pagination, filters, sorting, and time range
• Admin UI: Settings persistence with validation and tests
• Operational Readiness: /health/ready and Prometheus /metrics in API and workers
• Simulator UX: Getting-started docs and CLI workflow examples

Why it matters

• Faster integration: Query usage events from your app/UI immediately
• Better DX: Admin settings persist across reloads
• Production-friendly: Health checks and metrics ready for monitoring
• Repeatable testing: Documented simulator flows for reliable scenarios

What changed

• API: apps/api/src/routes/events.ts adds GET /v1/events
• Core types/schemas: @stripemeter/core
• Database repository: @stripemeter/database
• Docs: docs/api/events.md, docs/simulator/getting-started.md, docs/simulation-api.md

Upgrade guide

• No breaking changes.
• Pull latest, then:

pnpm install
pnpm build

Packages

• @stripemeter/[email protected]
• @stripemeter/[email protected]

Thanks

• Huge thanks to our contributors: @louispy, @coryli
• We welcome new contributors—check CONTRIBUTING.md and open a PR!

StripeMeter v0.1.0 (Alpha)

This is the first tagged release of StripeMeter focused on a smooth local demo and a clear operator story. It is suitable for evaluation and prototypes.

Scope

• Works locally with Docker (Postgres + Redis)
• Core apps: API, Workers, Admin UI, Customer Widget, Pricing Simulator
• Demo: CloudAPI SaaS showcase under demo/cloudapi-saas

Stability

• Stability: Alpha. Expect breaking changes before v1.0.

What’s in

• Usage ingestion API and usage/projection endpoints
• Workers: aggregation, reconciliation, alert monitor, Stripe writer (best-effort)
• Reconciliation loop with epsilon threshold
• Admin UI and customer widget for basic flows
• Pricing simulator library and docs

What’s out (for now)

• High-availability/multi-region guidance
• Advanced authz/SSO, RBAC hardening
• Performance SLO guarantees at scale
• Kubernetes/Helm production guidance

Known limitations

• Single-node, developer setup focused
• Best-effort reconciliation; manual review recommended for large drifts
• Limited observability; basic logs and health checks only

Requirements

• Node.js 20+
• pnpm 8+
• Docker Desktop

Try in 5 minutes

git clone https://github.com/geminimir/stripemeter.git
cd stripemeter
pnpm i -w
docker compose up -d
pnpm -r build && pnpm dev

# optional demo
cd demo/cloudapi-saas && ./demo-start.sh

Health check: curl -sS http://localhost:3000/health

Reconciliation (operator playbook)

See RECONCILIATION.md for drift epsilon policy (0.5%), watermarks, delta push, hourly compare, and triage steps.

Roadmap (next)

• Observability: metrics, dashboards, alerting
• Hardening: auth/tenant scoping, retries/backoff across services
• Performance baselines and benchmarks
• Packaging: container images and production guides

Acknowledgements

MIT licensed. Built by the community for transparent usage-based billing.