@fantastic.dev/better-stripe 0.50.1 → 0.50.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -26,6 +26,12 @@
26
26
  - Remove internal tracker references from public documentation and add a
27
27
  regression check that prevents their reintroduction.
28
28
 
29
+ ## [0.50.2](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.1...v0.50.2) (2026-10-18)
30
+
31
+ ### Documentation
32
+
33
+ - start metered billing provider feasibility ([844fb74](https://github.com/FantasticDevHQ/better-stripe/commit/844fb74c30081baac16a8275a1ae73a98a5b3753))
34
+
29
35
  ## [0.50.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.50.0...v0.50.1) (2026-10-17)
30
36
 
31
37
  ### Bug Fixes
package/README.md CHANGED
@@ -72,7 +72,7 @@ claim execution are completed.
72
72
 
73
73
  ## Status
74
74
 
75
- **Version**: `0.50.1` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
75
+ **Version**: `0.50.2` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
76
76
 
77
77
  Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
78
78
 
@@ -1835,3 +1835,7 @@ Automatic combined payouts use a complete paginated ledger collection above 100
1835
1835
  Resolve recovery-backed payout liabilities with `stripe.costRecovery.payoutQuote(ctx, authorizedScope)` and pass its amount/version together to preview or automatic release. The example does this for seller refund/dispute costs; stale or missing required versions fail safely. See [versioned liability guidance](docs/settlement.md#versioned-recovery-liabilities).
1836
1836
 
1837
1837
  Historical payout adoption and funded-account activation also use complete paginated collections beyond the small direct snapshot path. They revalidate complete financial membership atomically, preserve paid principal and holding age, and reject stale funding or recovery changes. See [historical import guidance](docs/settlement.md#historical-import-and-funded-activation).
1838
+
1839
+ ## Metered usage
1840
+
1841
+ Metered billing is under investigation. See the [provider comparison and sandbox acceptance matrix](docs/metered-usage.md) for current status and integration requirements. Public usage APIs are not available yet.
@@ -0,0 +1,123 @@
1
+ # Metered usage feasibility
2
+
3
+ Status: investigation in progress, reviewed 2026-10-18. BetterStripe does not yet
4
+ expose metered billing APIs. The provider, first billable unit and pricing model
5
+ must be selected before implementing provider-specific catalog, delivery or UI.
6
+ This document records the compatibility questions and repeatable access preflight.
7
+ It does not claim a successful billing sandbox run.
8
+
9
+ ## Existing integration constraints
10
+
11
+ BetterStripe subscriptions use Accounts v2 `customer_account` identities through
12
+ the platform Stripe client. See `src/client/billing/subscriptions.ts` and
13
+ [financial ownership](financial-ownership.md). Adding a separate v1 Customer is a
14
+ new identity/payment-method mapping contract, not an interchangeable identifier.
15
+ Existing fixed-price subscriptions, checkout and settlement must keep working.
16
+
17
+ Hosts authorize actors, payers and sellers and decide which activity is billable.
18
+ BetterStripe will own durable acceptance, deduplication, delivery and reconciliation.
19
+ A provider receipt cannot authorize a tenant or prove that usage was invoiced.
20
+ Seller and affiliate settlement must continue to use verified paid-invoice
21
+ proceeds and original payment provenance.
22
+
23
+ ## Provider comparison
24
+
25
+ | Concern | Stripe Billing Meters | Metronome with Stripe |
26
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
27
+ | Provider guidance | Stripe directs new usage integrations to Metronome, including existing flat-rate subscriptions adding usage | Recommended evaluation path for new usage integrations |
28
+ | Credentials | Existing Stripe key, subject to permissions and API access | Separate Metronome sandbox/account token and explicit Stripe integration enrollment |
29
+ | Payer identity | Guide maps meter payloads to Stripe Customer IDs; installed Stripe 23.0.0 meter types expose `by_id` only | Documented invoice delivery configuration uses `stripe_customer_id` with a `cus_` ID |
30
+ | Accounts v2 | `acct_` payer ingestion and invoice identity remain unverified | `customer_account` invoice delivery remains unverified; ingest aliases alone do not establish payment identity |
31
+ | Connect | Stripe documents connected-account requests and different rate limits; this does not prove a platform-owned Accounts v2 payer works in that realm | Multi-entity connections are documented; equivalence to Connect destination charges or separate transfers remains unverified |
32
+ | Catalog | Meter attached to recurring metered price | Billable metric, product, rate card and customer contract |
33
+ | Invoices | Stripe owns subscription invoicing | Metronome rates usage and pushes separate invoices to Stripe, including when recurring subscriptions coexist |
34
+ | Cost/access | Confirm account eligibility and current Billing pricing before selection | Confirm enrollment, commercial terms and extra credential acceptance before selection |
35
+
36
+ No provider is selected. Evaluate Metronome first because it is Stripe's current
37
+ recommendation. Adopt it only after proving the Accounts v2 and settlement
38
+ contracts and explicitly accepting the additional service credentials. Keep Billing
39
+ Meters as a comparison candidate, not an automatic fallback if access fails.
40
+ Neither candidate currently has proven end-to-end support in this repository.
41
+
42
+ ## Pricing-model decision
43
+
44
+ The product owner must choose pay-as-you-go, included monthly units with overages,
45
+ or prepaid credits, and name the first billable unit. Pay-as-you-go is the proposed
46
+ smallest starting scope. This proposal is not approval. Other models remain
47
+ unselected. In particular, do not create a second wallet or infer prepaid access
48
+ rules from the existing balance-funding integration.
49
+
50
+ Record the unit, decimal precision, aggregation formula, billing interval, currency,
51
+ price/version and payer/seller scope with the decision. Host limits and entitlement
52
+ rules are separate from an eventually consistent provider usage total.
53
+
54
+ ## Access preflight
55
+
56
+ From the repository root, inject a sandbox key as `STRIPE_SECRET_KEY` and run:
57
+
58
+ ```sh
59
+ node scripts/metering-feasibility.mjs
60
+ ```
61
+
62
+ Use `op run` from one persistent authorized terminal when the key is in 1Password.
63
+ Do not print or save the key. The script rejects non-test secret keys before making
64
+ any request. It makes one platform-realm GET to `/v1/billing/meters?limit=1`, pins
65
+ the repository's Stripe version and prints only status and verification flags.
66
+ It creates no meters, customers, events, subscriptions, invoices or charges.
67
+
68
+ A successful response establishes endpoint access only. A 401 or 403 is an access
69
+ failure, not evidence that a billing identity or model is unsupported. The script
70
+ has no connected-account selector and does not test that realm. It is a development
71
+ tool in the repository, not a public package API.
72
+
73
+ ## Sandbox acceptance matrix
74
+
75
+ Run the following after credentials and product decisions are available. Capture
76
+ sanitized request shapes, API versions, timestamps, status codes and assertions.
77
+ Keep secrets and raw customer/provider payloads out of evidence and workflow state.
78
+
79
+ | Scenario | Required proof | Current result |
80
+ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
81
+ | Platform Accounts v2 payer | Meter/contract creation, ingestion, aggregate and invoice all refer to the authorized payer | Unverified |
82
+ | Connected seller | Prove catalog/event realm and payer ownership, destination/transfer economics and paid-invoice provenance | Unverified |
83
+ | Non-Connect account | Prove identity and invoice flow without silently provisioning an alternative payer | Unverified |
84
+ | Duplicate delivery | Same source event and provider identifier produce one aggregate contribution | Unverified |
85
+ | Shared meter | Two subscriptions for one customer show the actual aggregation boundary; no inferred per-subscription event targeting | Unverified |
86
+ | Correction | Original event, reason and receipt retained; provider cancellation window and finalized-invoice behavior demonstrated | Unverified |
87
+ | Invoice closeout | Original event time, delayed aggregate, finalized invoice line and payment/processing costs reconcile | Unverified |
88
+ | Test clocks | Determine which provider clock drives event timestamps and invoice periods, without assuming virtual time advances ingestion | Unverified |
89
+ | Packed consumer | Verify eventual public contracts from the built tarball with linked guides present | Deferred until public APIs exist |
90
+
91
+ For Billing Meters, event uniqueness is enforced for at least a rolling 24-hour
92
+ window. Acceptance permits timestamps within 35 calendar days in the past or five
93
+ minutes in the future. Cancellation is limited to events sent within 24 hours.
94
+ Aggregation is asynchronous. Accepted late events can appear in summaries without
95
+ changing a finalized invoice. Preserve local deduplication and an explicit unknown
96
+ delivery state beyond the safe retry window. Events have no subscription selector.
97
+
98
+ Metronome's quickstart uses a customer UUID or ingest alias and transaction ID,
99
+ string-valued numerical properties and a 34-day backdating window. Confirm exact
100
+ retention, correction and retry guarantees for the chosen API and account before
101
+ encoding them as constants. Its invoice integration documentation and Stripe's
102
+ integration overview use different metadata names for invoice mapping. Inspect the
103
+ actual sandbox invoice rather than trusting a single assumed metadata key.
104
+
105
+ ## Evidence recorded so far
106
+
107
+ The repository uses Stripe 23.0.0 and pins `2026-09-30.endive`. Its installed meter
108
+ creation types permit `customer_mapping.type: 'by_id'`; this is a type inspection,
109
+ not proof that Accounts v2 ingestion is supported or unsupported. The access probe
110
+ has automated tests covering rejection of live/missing keys, a single read-only
111
+ request and sanitization of provider errors. Actual provider access, usage delivery,
112
+ aggregation, invoices, payment provenance and Metronome access remain unverified.
113
+
114
+ ## Primary sources
115
+
116
+ - [Stripe usage-based billing](https://docs.stripe.com/billing/usage-based)
117
+ - [Stripe's guidance on recording usage](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage)
118
+ - [Record usage with the API](https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api)
119
+ - [Create a meter event](https://docs.stripe.com/api/billing/meter-event/create)
120
+ - [Configure meters and corrections](https://docs.stripe.com/billing/subscriptions/usage-based/meters/configure)
121
+ - [How Metronome works with Stripe](https://docs.stripe.com/billing/how-metronome-works-with-stripe)
122
+ - [Metronome API quickstart](https://docs.metronome.com/guides/get-started/api-quickstart)
123
+ - [Metronome invoice integration](https://docs.metronome.com/integrations/invoice-integrations/stripe)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.50.1",
3
+ "version": "0.50.2",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -84,7 +84,8 @@
84
84
  "docs/example-recovery-cutover.md",
85
85
  "docs/releasing.md",
86
86
  "docs/release-handoff.md",
87
- "docs/setup-intent-recovery.md"
87
+ "docs/setup-intent-recovery.md",
88
+ "docs/metered-usage.md"
88
89
  ],
89
90
  "scripts": {
90
91
  "build": "tsc --project ./tsconfig.build.json && node scripts/check-public-exports.mjs",