# Shared Alignment: augint_billing_lib ↔ augint-billing-infra

## Responsibility split
- **Library (`augint_billing_lib`)**: all business logic (Stripe decisions, usage reporting, plan moves, DDB persistence).
- **Infra (SAM)**: triggers (EventBridge, Schedule), env, IAM, DLQs, and tiny handlers that call the library.

## Env contract (Lambda → Library)
- Required: `STACK_NAME`, `AWS_REGION`, `TABLE_NAME`, `STRIPE_SECRET_ARN`
- Optional overrides: `FREE_USAGE_PLAN_ID`, `METERED_USAGE_PLAN_ID`
- Secret JSON: `{ "STRIPE_SECRET_KEY":"...", "STRIPE_PRICE_ID_METERED":"price_..." }`

## Flow: Stripe event → plan update
```mermaid
flowchart LR
  Stripe[Stripe Event Destinations] --> EB[(EventBridge Partner Bus)]
  EB --> L[(Lambda: StripeEventHandler shim)]
  L -->|import| Lib[augint_billing_lib.bootstrap.process_event_and_apply_plan_moves]
  Lib --> DDB[(DynamoDB: customer_links)]
  Lib --> APIGW[API Gateway Usage Plans]
```

## Flow: Hourly usage reporting
```mermaid
flowchart LR
  Cron[EventBridge Schedule] --> UR[(Lambda: UsageReporter shim)]
  UR -->|import| Svc[augint_billing_lib.bootstrap.build_service().reconcile_usage_window]
  Svc --> APIGW[API Gateway GetUsage]
  Svc --> Stripe[Stripe UsageRecords]
  Svc --> DDB[(DynamoDB updates)]
```

## Table (customer_links) minimal schema
- PK: `api_key_id` (string)
- Attributes: `stripe_customer_id` (string), `cognito_user_id` (string, optional), `plan` ("free"|"metered"), `usage_plan_id` ("FREE_10K"|"METERED"), `metered_subscription_item_id` (string), `last_reported_usage_ts` (ISO), `current_month_reported_units` (number)
- GSI `gsi_stripe_customer`: HASH=`stripe_customer_id`

## Release
- Publish **library** as a versioned Layer; update `LibraryLayerArn` only.
- No handler code changes required.
