feat: emit real usage events across multiple marketplace dimensions

[dkirby-ms]

Summary

FastSaaS should include sample metering calls to demo marketplace api metering functions.

Motivation

Instead of building separate sample apps (#107), FastSaaS itself demonstrates metering patterns by dogfooding:

• Per-request count metering (API calls)
• Event-driven inbound metering (webhooks)
• Storage-style append metering (audit logs)
• Time-based entitlement metering (active tenants/seats)

Proposed Dimensions (First Wave)

Dimension	What it measures	Emit point	Pattern
marketplace_fulfillment_calls	Outbound SaaS Fulfillment API calls	marketplace-fulfillment.ts	Per-request count
marketplace_webhook_operations	Processed webhook operations	webhooks/marketplace.ts	Event-driven
product_ingestion_api_calls	Outbound Product Ingestion/Graph calls	product-ingestion-client.ts	Admin activity
audit_log_entries	Audit records written	audit-service.ts	Storage append
active_tenant_hours	Active provisioned tenant-hours	subscription reconciliation job	Time-based

Prerequisites (must fix before implementation)

1. Azure metering auth — current client sends raw secret instead of proper OAuth token
2. Hourly rollup layer — Azure accepts ONE event per resource+dimension+hour; need aggregation before outbox
3. Overage computation — must know plan-included quantities to only report billable excess
4. Subscription attribution — publisher-only flows need an attribution strategy

Implementation Approach

1. Define canonical meter dimension catalog in shared types
2. Build internal emitter + hourly rollup aggregator
3. Fix Azure metering OAuth (x-ms-requestid, x-ms-correlationid headers)
4. Instrument first-wave emit points
5. Add scheduled reconciliation for time-based dimensions (tenant-hours, seat-hours)
6. (Later) Self-meter the metering worker with recursion guard

Blast Radius

• packages/shared/src/index.ts (dimension types)
• packages/api/src/metering/* (emitter, rollup, client upgrade)
• packages/api/src/lib/marketplace-fulfillment.ts
• packages/api/src/lib/product-ingestion-client.ts
• packages/api/src/services/audit-service.ts
• packages/api/src/services/subscription-service.ts
• packages/api/src/server.ts (reconciliation job)
• New DB migration for hourly rollup table

Research

Full research document: .squad/decisions/inbox/eecom-metering-dogfood-research.md

Related

• Supersedes feat: add sample reference SaaS apps for marketplace flow testing #107 (sample reference SaaS apps) — FastSaaS IS the reference app