stripemeter

# StripeMeter StripeMeter is a Stripe-native usage metering system that ensures correct usage totals for usage-based billing. It dedupes retries, handles late events with watermarks, keeps running counters, and pushes only deltas to Stripe. ## Quick Start ```bash git clone https://github.com/geminimir/stripemeter && cd stripemeter cp .env.example .env && docker compose up -d && pnpm -r build pnpm db:migrate && pnpm dev ``` ## Core Concepts ### Events (Immutable Ledger) Every usage event stored with deterministic idempotency key. Events are never deleted or modified. ### Counters (Materialized Aggregations) Pre-computed aggregations (sum/max/last) by tenant, metric, customer, and period. Updated in near-real-time. ### Watermarks (Late Event Handling) Each counter maintains a watermark timestamp. Events within lateness window (default 48h) trigger re-aggregation. ### Delta Push (Stripe Synchronization) Tracks `pushed_total` per subscription item and only sends delta to Stripe. ## API Endpoints ### Ingest Events ```bash curl -X POST http://localhost:3000/v1/events/ingest \ -H "Content-Type: application/json" \ -d '{ "events": [{ "tenantId": "your-tenant-id", "metric": "api_calls", "customerRef": "cus_ABC123", "quantity": 100, "ts": "2025-01-16T14:30:00Z" }] }' ``` ### Get Cost Projection ```bash curl -X POST http://localhost:3000/v1/usage/projection \ -H "Content-Type: application/json" \ -d '{"tenantId": "your-tenant-id", "customerRef": "cus_ABC123"}' ``` ### Health & Metrics - Readiness: `GET /health/ready` - Metrics: `GET /metrics` - Events: `GET /v1/events?tenantId=X&limit=10` ## Node.js SDK ```typescript import { createClient } from '@stripemeter/sdk-node'; const client = createClient({ apiUrl: 'http://localhost:3000', tenantId: 'your-tenant-id', customerId: 'cus_ABC123' }); // Track usage await client.track({ metric: 'api_calls', customerRef: 'cus_ABC123', quantity: 100, meta: { endpoint: '/v1/search' } }); // Get live usage const usage = await client.getUsage('cus_ABC123'); const projection = await client.getProjection('cus_ABC123'); ``` ## Python SDK ```python from stripemeter import StripeMeterClient client = StripeMeterClient( api_url="http://localhost:3000", tenant_id="your-tenant-id", customer_id="cus_ABC123" ) client.track( metric="api_calls", customer_ref="cus_ABC123", quantity=100 ) ``` ## Stripe Billing Driver For direct Stripe integration, use the stripe-driver package: ```typescript import { StripeBillingDriverImpl } from '@stripemeter/stripe-driver'; const driver = new StripeBillingDriverImpl({ liveKey: process.env.STRIPE_SECRET_KEY, testKey: process.env.STRIPE_TEST_SECRET_KEY }); // Record usage to Stripe await driver.recordUsage({ mode: 'live', stripeAccount: 'default', subscriptionItemId: 'si_xxx', quantity: 100, periodStart: '2025-01-01', idempotencyKey: 'unique-key' }); // Get usage summary const summary = await driver.getUsageSummary( 'si_xxx', '2025-01-01', 'default' ); ``` ## Shadow Mode Test Stripe usage posting without affecting live invoices: 1. Set `STRIPE_TEST_SECRET_KEY` in environment 2. Mark price mapping with `shadow=true` 3. Provide `shadowStripeAccount`, `shadowPriceId` 4. Live invoices remain unaffected ## Pricing Simulator ```typescript import { InvoiceSimulator } from '@stripemeter/pricing-lib'; const simulator = new InvoiceSimulator(); const result = simulator.simulate({ customerId: 'test', periodStart: '2024-01-01', periodEnd: '2024-02-01', usageItems: [{ metric: 'api_calls', quantity: 25000, priceConfig: { model: 'tiered', currency: 'USD', tiers: [ { upTo: 10000, unitPrice: 0.01 }, { upTo: 50000, unitPrice: 0.008 }, { upTo: null, unitPrice: 0.005 } ] } }] }); ``` ## Project Structure ``` stripemeter/ ├── packages/ │ ├── core/ # Shared types, schemas │ ├── database/ # Drizzle ORM + Redis │ ├── pricing-lib/ # Pricing calculator │ ├── stripe-driver/ # Direct Stripe API driver │ ├── sdk-node/ # Node.js SDK │ └── sdk-python/ # Python SDK ├── apps/ │ ├── api/ # REST API (Fastify) │ ├── workers/ # Background workers (BullMQ) │ ├── admin-ui/ # Admin dashboard │ └── customer-widget/# Embeddable widget ``` ## Environment Variables ```bash STRIPE_SECRET_KEY=sk_live_xxx # Live Stripe key STRIPE_TEST_SECRET_KEY=sk_test_xxx # Test Stripe key (for shadow mode) DATABASE_URL=postgres://... # PostgreSQL connection REDIS_URL=redis://... # Redis connection ``` ## Common Tasks ### Verify Idempotency ```bash # Send same event twice - counts once TENANT_ID=$(uuidgen) bash examples/api-calls/send.sh curl http://localhost:3000/metrics | grep ingest ``` ### Run Reconciliation Check drift between local totals and Stripe: - Differences beyond 0.5% epsilon trigger investigation - See [RECONCILIATION.md](RECONCILIATION.md) for runbook ### Replay Late Events ```bash curl -X POST http://localhost:3000/v1/replay \ -H "Content-Type: application/json" \ -d '{"tenantId": "X", "dryRun": true}' ``` ## Additional Resources - [API Documentation](docs/welcome.md) - [Simulator Guide](docs/simulator-getting-started.md) - [Reconciliation Runbook](RECONCILIATION.md) - [Alert Configuration](ops/ALERTS.md)