FRD: Billing Provider Wrapper

Document Summary

Field	Details
Feature Name	Billing Provider Wrapper
Status	Draft
Owner	David Holmes
Contributors	Engineering
Target Release	v2.0.0
Related Links	ADR-051 (Provider Pattern), `src/components/patterns/billing-history-table.tsx`, ADR-027 (Default Tech Stack), ADR-014 (Open Source First)
Last Updated	2026-06-02
Open Source Libraries	`stripe`
Documentation	Stripe API Docs · Node.js Quickstart · Billing Overview · Webhooks

This FRD ships @dmwd-io/billing as an optional package that re-exports stripe as the platform standard for subscription billing. The value is standards and drift prevention — not a custom abstraction. Platform conventions (env var names, event naming) are documented on top of the library’s own API.

Introduction

Overview

Per ADR-014 (Open Source First), the platform designates stripe as the community library for subscription billing. Rather than building a custom BillingProvider interface, @dmwd-io/billing re-exports stripe directly and documents the platform’s conventions: STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as the standard env var names, and billing.{resource}.{action} as the internal event naming convention per ADR-065. Each consuming app gets a single, consistent import path and a documented baseline — without the maintenance burden of a custom abstraction layer.

Goals

Designate stripe as the platform standard for subscription billing per ADR-014.
Re-export stripe via @dmwd-io/billing to give apps a single, stable import path.
Document STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as the platform env var conventions.
Normalize webhook event naming to billing.{resource}.{action} per ADR-065.
Include TypeScript examples showing package wiring, lifecycle flows, and widget integration.

Non-Goals

Building a custom provider interface or adapter layer — the library’s own API is the interface (per ADR-014).
Building a production vendor adapter from scratch (Stripe is the designated vendor).
Implementing payment method collection (see FRD: Payments Provider Wrapper).
Building billing-specific UI components beyond what already exists.
Supporting multi-currency conversion logic inside the package.
Acting as a tax calculation engine.

Scope

In Scope

Area	Description
Package re-export	`@dmwd-io/billing` re-exports `stripe` with `stripe` as a peer dependency
Env var conventions	Document `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` as platform standard names
Type re-exports	Re-export key stripe types (`Stripe.Subscription`, `Stripe.Invoice`, etc.) for consuming apps
Webhook event naming	Document `billing.{resource}.{action}` naming convention per ADR-065
Documentation	Storybook docs page with usage examples and integration guidance

Out of Scope

Area	Reason
Custom BillingProvider interface	ADR-014: library’s own API is the interface
Vendor adapter implementations	Not needed — stripe is the designated standard
Payment method CRUD	Covered by FRD: Payments Provider Wrapper
Tax calculation	Delegated to the billing vendor or a dedicated tax service
Billing UI components	Existing widgets are presentational; new widgets are a separate effort
Multi-tenant billing isolation	App-level concern, not a library contract responsibility

Users and Pain Points

User Groups

User	Description	Needs
App developers	Engineers building SaaS products on the design system	A single import for billing operations that works consistently across the platform
QA engineers	Testers validating subscription flows	Deterministic mock data for every subscription state
Design system maintainers	Contributors to the shared library	A clean, low-maintenance package that follows ADR-014

Pain Points

User	Pain Point	Impact
App developers	Each app imports stripe directly with inconsistent env var names and error handling	Duplicated effort; configuration drift across services
App developers	No shared entry point for billing operations	Difficult to apply platform-wide conventions (event naming, error handling)
QA engineers	Cannot reproduce specific subscription states (past-due, trialing, canceled) deterministically	Incomplete test coverage of billing edge cases

Definitions

Term	Definition
Plan	A product pricing tier with an ID, name, interval (monthly/yearly), and unit price
Subscription	A customer’s active relationship to a plan with a status lifecycle
Invoice	A billing document recording charges, discounts, tax, and payment status
Usage record	A metered event reported against a subscription for usage-based billing
Customer portal	A vendor-hosted page where customers manage payment methods and invoices
Billing event	A normalized internal event derived from a vendor webhook payload
Proration	Adjusting charges when a customer changes plans mid-cycle

Current State

Existing Behavior

The design system ships billing-history-table.tsx as a presentational pattern component. It accepts props for rendering invoice rows but has no data-fetching layer. Consuming apps import Stripe SDK directly in API routes, duplicating subscription CRUD, webhook verification, and invoice retrieval logic with inconsistent env var names.

Current Limitations

No shared entry point for billing — each app imports stripe independently.
No platform-standard env var names — apps use STRIPE_KEY, STRIPE_SECRET, STRIPE_SECRET_KEY interchangeably.
No webhook event naming convention — each app names internal events differently.
Storybook stories hard-code invoice data inline rather than using stripe’s own fixture patterns.

Existing Workarounds

Apps copy-paste Stripe integration code from a private template repo.
Storybook stories hard-code invoice data inline rather than using a shared fixture pattern.

Proposed Solution

Summary

Create packages/billing/ with a single src/index.ts that re-exports stripe. The package documents STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as the platform env var names and billing.{resource}.{action} as the internal event naming convention. No custom interface is built — the library’s API is the interface.

import Stripe, { type Stripe as StripeTypes } from '@dmwd-io/billing';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

Key Capabilities

Single import path (@dmwd-io/billing) for all stripe usage across the platform.
Platform-documented env var names: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET.
Re-exported stripe types for consuming apps — no need to install stripe separately.
Webhook event naming convention aligned to ADR-065 (billing.subscription.created, billing.invoice.paid, etc.).

User Experience

End users are not directly affected. The package powers billing UI components and API routes behind the scenes.

Developer Experience

Developers import from @dmwd-io/billing instead of directly from stripe. They get the full stripe API with platform conventions documented in one place. The package guarantees a consistent stripe version across all services and eliminates per-app configuration guesswork.

Requirements

ID	Requirement	Priority	Notes
FR-001	`@dmwd-io/billing` re-exports `stripe` as its default and named exports	Must	Per ADR-014 — library API is the interface
FR-002	Re-export key stripe TypeScript types for consuming apps	Must	-
FR-003	Document `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` as platform env var names	Must	-
FR-004	Document `billing.{resource}.{action}` webhook event naming convention	Should	Per ADR-065
FR-005	`stripe` listed as a peer dependency in `package.json`	Must	-
FR-006	Storybook docs page with usage examples	Must	-

Priority Definitions

Priority	Meaning
Must	Required for this feature to ship.
Should	Important, but can be deferred if needed.
Could	Nice to have. Not required for initial release.

Functional Requirements

ID	Requirement	User Benefit	Priority
FUNC-001	`import Stripe from '@dmwd-io/billing'` works identically to `import Stripe from 'stripe'`	Apps migrate with a one-line import change	Must
FUNC-002	Platform env var names are documented in the package README and Storybook docs	Teams configure consistently across services	Must
FUNC-003	Webhook event naming examples in docs show `billing.subscription.created`, `billing.invoice.paid` pattern	Teams name internal events consistently	Should
FUNC-004	`billing-history-table` Storybook story updated to show integration with stripe data shapes	Developers see a working end-to-end example	Must

Non-Functional Requirements

ID	Requirement	Category	Priority
NFR-001	Package adds no runtime code beyond re-exports	Performance	Must
NFR-002	`stripe` is a peer dependency, not a bundled dependency	Bundle size	Must
NFR-003	`pnpm typecheck` passes with zero errors	Maintainability	Must
NFR-004	Webhook event naming follows `billing.{resource}.{action}` per ADR-065	Maintainability	Should

API / Interface Requirements

Public API

Name	Type	Description	Required
`default`	`typeof Stripe`	The `stripe` constructor, re-exported as default	Yes
`Stripe`	namespace	The `stripe` type namespace, re-exported for consuming apps	Yes

Example Usage

import Stripe from '@dmwd-io/billing';

// Instantiate using platform env var convention
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

// Webhook verification using platform env var convention
const event = stripe.webhooks.constructEvent(
  body,
  sig,
  process.env.STRIPE_WEBHOOK_SECRET
);

// Map to internal billing event naming per ADR-065
// billing.subscription.created, billing.invoice.paid, etc.

API Notes

All monetary amounts follow stripe’s convention: integers in the smallest currency unit (cents for USD).
No custom wrapper types are added — use stripe’s own TypeScript types directly.
The package version pins a minimum stripe peer dependency version to ensure consistent API surface.

Accessibility Requirements

ID	Requirement	Notes
A11Y-001	Package is a data layer with no direct UI — accessibility requirements apply to consuming components	Billing UI widgets handle their own a11y
A11Y-002	Error messages from stripe must be surfaced as human-readable strings suitable for `aria-live` regions	Consuming components should surface errors without transformation

Checklist

Keyboard support is defined. (N/A — no UI)
Focus behavior is defined. (N/A — no UI)
Screen reader behavior is defined. (N/A — no UI)
Color contrast requirements are met. (N/A — no UI)
Reduced motion behavior is considered. (N/A — no UI)
Semantic HTML expectations are documented. (N/A — no UI)
ARIA usage is defined only where needed. (N/A — no UI)

Content and Documentation Requirements

ID	Requirement	Location	Priority
DOC-001	Storybook docs page explaining package purpose and platform conventions	Storybook	Must
DOC-002	Document `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` env var names	Storybook + README	Must
DOC-003	Example: wiring `billing-history-table` with stripe data shapes	Storybook	Must
DOC-004	Example: webhook handler using platform event naming convention	Storybook	Should
DOC-005	Example: subscription lifecycle flow (create → upgrade → cancel) using stripe directly	Storybook	Should

Dependencies

Dependency	Type	Owner	Status	Notes
ADR-014 Open Source First	Architecture	Engineering	Ready	Defines re-export-over-custom-interface principle
ADR-051 provider pattern	Architecture	Engineering	Ready	Context for how other platform packages are structured
ADR-065 webhook handling	Architecture	Engineering	Ready	Defines webhook event naming convention
`billing-history-table.tsx`	Component	Design system	Ready	Existing presentational component to show in integration example
Payments provider wrapper	Library	Engineering	Not Started	Handles payment method collection; billing package is complementary

Risks and Tradeoffs

Risk / Tradeoff	Impact	Mitigation
Stripe API changes require package version bump	Apps may lag on stripe API version	Pin peer dependency minimum version; document upgrade path
Thin re-export adds little value if teams still import stripe directly	Platform drift continues	Enforce `@dmwd-io/billing` import via lint rule; document in onboarding
No mock layer for tests — stripe must be mocked at the SDK level	Tests require explicit stripe mock setup	Document recommended mock patterns (e.g. `jest.mock('@dmwd-io/billing')`) in Storybook docs
Webhook timing edge cases are not abstracted	Integration tests may miss race conditions	Document that webhook integration tests should use a real vendor sandbox

Open Questions

ID	Question	Owner	Status	Resolution
Q-001	Should the package include a thin webhook event normalizer that maps stripe events to `billing.{resource}.{action}`?	David Holmes	Open	—
Q-002	Should `@dmwd-io/billing` also re-export Stripe’s `Webhook` helper as a named export for convenience?	David Holmes	Open	—
Q-003	Should the package include a `createStripeClient()` factory that reads env vars automatically?	David Holmes	Open	—
Q-004	Should the interface support multi-subscription customers (one customer, multiple active plans)?	David Holmes	Open	—

Acceptance Criteria

ID	Criteria	Related Requirement
AC-001	`import Stripe from '@dmwd-io/billing'` resolves to the `stripe` constructor	FR-001
AC-002	stripe TypeScript types are available via `import type { Stripe } from '@dmwd-io/billing'`	FR-002
AC-003	Package README and Storybook docs name `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` as platform env vars	FR-003
AC-004	Storybook docs include a webhook handler example using `billing.{resource}.{action}` event naming	FR-004
AC-005	`stripe` appears as a peer dependency in `packages/billing/package.json`	FR-005
AC-006	`pnpm typecheck` passes with zero errors	NFR-003
AC-007	Storybook example wires `billing-history-table` with stripe invoice data shapes	DOC-003
AC-008	No custom BillingProvider interface or adapter is implemented	ADR-014

LLM Handoff Instructions

Expected LLM Behavior

Create packages/billing/ if it does not exist.
Add packages/billing/package.json with stripe as a peer dependency and @dmwd-io/billing as the package name.
Create packages/billing/src/index.ts that does export { default } from 'stripe'; export type { Stripe } from 'stripe';.
Document STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as the platform env var names in the Storybook docs page.
Add a Storybook docs page showing import usage, env var names, and a webhook handler example with billing.{resource}.{action} event naming.
Run pnpm typecheck to confirm zero errors before declaring done.

LLM Should Not

Build a custom BillingProvider interface or adapter — ADR-014 says the library’s own API is the interface.
Implement a custom factory function wrapping stripe.
Modify existing UI components — the package is a data layer only.
Add runtime dependencies beyond stripe as a peer.
Create webhook HTTP handlers — only document the event naming convention.

Decision Log

Date	Decision	Reason	Owner
2026-05-26	Use integer cents for monetary amounts	Avoids floating-point precision issues; matches Stripe convention	David Holmes
2026-05-26	Model subscription status as a closed union, not an enum	Aligns with TypeScript best practices used elsewhere in the design system	David Holmes
2026-05-26	Include usage methods in the base interface (not a separate provider)	Usage billing is tightly coupled to subscriptions; splitting would fragment the API	David Holmes
2026-06-02	Reframed per ADR-014 (Open Source First): adopt stripe as thin re-export rather than building a custom provider interface. Library API is the interface.	ADR-014 eliminates the need for a custom abstraction when a well-maintained community library exists	David Holmes

Document History

Date	Author	Change
2026-05-26	David Holmes	Initial draft
2026-06-02	David Holmes	Reframed per ADR-014: ship as thin re-export of stripe, drop custom interface.