@fantastic.dev/better-stripe 0.50.2 → 0.51.0

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.
Files changed (49) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +39 -1748
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  4. package/dist/client/connect/payoutAdoptionTestHelpers.js +12 -1
  5. package/dist/client/connect/payoutAdoptionTestHelpers.js.map +1 -1
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutExecutionTestHelpers.js +12 -1
  8. package/dist/client/connect/payoutExecutionTestHelpers.js.map +1 -1
  9. package/dist/client/usage/boundaries.d.ts +132 -0
  10. package/dist/client/usage/boundaries.d.ts.map +1 -0
  11. package/dist/client/usage/boundaries.js +43 -0
  12. package/dist/client/usage/boundaries.js.map +1 -0
  13. package/dist/client/usage/contracts.d.ts +59 -0
  14. package/dist/client/usage/contracts.d.ts.map +1 -0
  15. package/dist/client/usage/contracts.js +63 -0
  16. package/dist/client/usage/contracts.js.map +1 -0
  17. package/dist/client/usage/index.d.ts +7 -0
  18. package/dist/client/usage/index.d.ts.map +1 -0
  19. package/dist/client/usage/index.js +4 -0
  20. package/dist/client/usage/index.js.map +1 -0
  21. package/dist/client/usage/records.d.ts +50 -0
  22. package/dist/client/usage/records.d.ts.map +1 -0
  23. package/dist/client/usage/records.js +54 -0
  24. package/dist/client/usage/records.js.map +1 -0
  25. package/docs/README.md +58 -0
  26. package/docs/architecture.md +80 -0
  27. package/docs/client-api.md +586 -0
  28. package/docs/configuration.md +51 -0
  29. package/docs/development.md +114 -0
  30. package/docs/marketplace.md +165 -0
  31. package/docs/metered-usage.md +289 -37
  32. package/docs/metering-setup.md +183 -0
  33. package/docs/overview.md +140 -0
  34. package/docs/react-api.md +284 -0
  35. package/docs/releasing.md +19 -0
  36. package/docs/testing.md +52 -0
  37. package/docs/webhooks.md +259 -0
  38. package/package.json +17 -2
  39. package/src/client/connect/payoutAdoptionTestHelpers.ts +17 -1
  40. package/src/client/connect/payoutExecutionTestHelpers.ts +17 -1
  41. package/src/client/transferContinuation.test.ts +2 -6
  42. package/src/client/usage/boundaries.test.ts +136 -0
  43. package/src/client/usage/boundaries.ts +182 -0
  44. package/src/client/usage/contracts.test.ts +145 -0
  45. package/src/client/usage/contracts.ts +79 -0
  46. package/src/client/usage/index.ts +34 -0
  47. package/src/client/usage/records.ts +76 -0
  48. package/src/test.ts +17 -1
  49. package/src/vite-env.d.ts +5 -1
@@ -0,0 +1,54 @@
1
+ import { z } from "zod";
2
+ import { STRIPE_API_VERSION } from "../constants.js";
3
+ import { STRIPE_CUSTOMER_PREVIEW_API_VERSION } from "../apiVersion.js";
4
+ import { defineUsagePlan, parseUsageQuantity, } from "./contracts.js";
5
+ const scopeSchema = z.strictObject({
6
+ stripeAccountId: z.string().regex(/^acct_[a-zA-Z0-9]+$/),
7
+ customerAccount: z.string().regex(/^acct_[a-zA-Z0-9]+$/),
8
+ meterId: z.string().regex(/^mtr_[a-zA-Z0-9_]+$/),
9
+ livemode: z.boolean(),
10
+ });
11
+ const recordSchema = z.strictObject({
12
+ scope: scopeSchema,
13
+ binding: z.strictObject({
14
+ stripeCustomerId: z.string().regex(/^cus_[a-zA-Z0-9]+$/),
15
+ stripePriceId: z.string().regex(/^price_[a-zA-Z0-9]+$/),
16
+ eventName: z.string().min(1).max(100),
17
+ apiVersion: z
18
+ .enum([STRIPE_API_VERSION, STRIPE_CUSTOMER_PREVIEW_API_VERSION])
19
+ .default(STRIPE_API_VERSION),
20
+ plan: z.unknown(),
21
+ }),
22
+ sourceEventId: z.string().min(1).max(200),
23
+ quantity: z.unknown(),
24
+ occurredAt: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
25
+ });
26
+ /**
27
+ * Validate and snapshot a record before acceptance. This pure helper does not
28
+ * authorize an actor, verify provider ownership, persist or deliver anything.
29
+ * Occurrence time is Unix seconds; native provider windows are enforced by the
30
+ * acceptance/delivery implementation, not by changing historical event time.
31
+ */
32
+ export function prepareUsageRecord(input) {
33
+ const record = recordSchema.parse(input);
34
+ const plan = defineUsagePlan(record.binding.plan);
35
+ const quantity = parseUsageQuantity(record.quantity, plan.unit.precision);
36
+ const scope = record.scope;
37
+ return {
38
+ ...record,
39
+ schemaVersion: 1,
40
+ quantity: quantity.quantity,
41
+ scaledQuantity: quantity.scaledQuantity,
42
+ binding: { ...record.binding, plan },
43
+ // A plan/version/quantity change must conflict with the original source
44
+ // event, so these are deliberately outside the deduplication identity.
45
+ identity: JSON.stringify([
46
+ scope.livemode,
47
+ scope.stripeAccountId,
48
+ scope.customerAccount,
49
+ scope.meterId,
50
+ record.sourceEventId,
51
+ ]),
52
+ };
53
+ }
54
+ //# sourceMappingURL=records.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"records.js","sourceRoot":"","sources":["../../../src/client/usage/records.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,mCAAmC,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EACL,eAAe,EACf,kBAAkB,GAEnB,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC;IACjC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACxD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACxD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,CAAC;IAChD,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;CACtB,CAAC,CAAC;AACH,MAAM,YAAY,GAAG,CAAC,CAAC,YAAY,CAAC;IAClC,KAAK,EAAE,WAAW;IAClB,OAAO,EAAE,CAAC,CAAC,YAAY,CAAC;QACtB,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC;QACxD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,sBAAsB,CAAC;QACvD,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACrC,UAAU,EAAE,CAAC;aACV,IAAI,CAAC,CAAC,kBAAkB,EAAE,mCAAmC,CAAC,CAAC;aAC/D,OAAO,CAAC,kBAAkB,CAAC;QAC9B,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE;KAClB,CAAC;IACF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IACzC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC;CACxE,CAAC,CAAC;AAmBH;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,OAAO;QACL,GAAG,MAAM;QACT,aAAa,EAAE,CAAC;QAChB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,cAAc,EAAE,QAAQ,CAAC,cAAc;QACvC,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE;QACpC,wEAAwE;QACxE,uEAAuE;QACvE,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC;YACvB,KAAK,CAAC,QAAQ;YACd,KAAK,CAAC,eAAe;YACrB,KAAK,CAAC,eAAe;YACrB,KAAK,CAAC,OAAO;YACb,MAAM,CAAC,aAAa;SACrB,CAAC;KACH,CAAC;AACJ,CAAC"}
package/docs/README.md ADDED
@@ -0,0 +1,58 @@
1
+ # Documentation
2
+
3
+ Start with the [package quick start](../README.md#quick-start), then choose the
4
+ guide for your integration.
5
+
6
+ ## Setup and API references
7
+
8
+ - [Package overview](overview.md), capabilities, known limits, and Accounts v2 compatibility.
9
+ - [Accounts v2 customer preview](accounts-v2-preview.md), eligibility and webhook migration.
10
+ - [Configuration](configuration.md), environment variables, component wiring, and API versions.
11
+ - [Client API reference](client-api.md), server methods, intent creation, and recovery claims.
12
+ - [Webhooks and triggers](webhooks.md), destinations, supported events, and callbacks.
13
+ - [React API reference](react-api.md), hooks, providers, and headless components.
14
+ - [React workflows](react-workflows.md), integration examples and host responsibilities.
15
+ - [React workflow audit](react-workflows-audit.md), UI reuse and coverage.
16
+
17
+ ## Billing and purchase history
18
+
19
+ - [Read contracts](read-contracts.md), pagination, currency summaries, and backfill.
20
+ - [Billing history](billing-history.md).
21
+ - [Invoice payment pages](invoice-payment-pages.md).
22
+ - [Checkout session pages](checkout-session-pages.md).
23
+ - [Subscription payment methods](subscription-payment-methods.md).
24
+ - [SetupIntent recovery](setup-intent-recovery.md).
25
+ - [Balance funding state](balance-funding-state.md) and [workflow](balance-funding-workflow.md).
26
+ - [Example balance funding cutover](example-balance-funding-cutover.md).
27
+ - [Metered usage investigation](metered-usage.md), provider comparison and acceptance requirements. Public usage APIs are not available yet.
28
+
29
+ ## Marketplace, settlement, and recovery
30
+
31
+ - [Marketplace economics](marketplace.md), fees, splits, refunds, and disputes.
32
+ - [Settlement and payouts](settlement.md), verified receipts, payout policies, and automatic workers.
33
+ - [Affiliate commission clawbacks](affiliate-clawbacks.md).
34
+ - [Refund context](refund-context.md) and [refund command evidence](refund-command-evidence.md).
35
+ - [Processing cost reconciliation](processing-cost-reconciliation.md).
36
+ - [Personal account mapping](personal-account-mapping.md).
37
+ - [Financial ownership](financial-ownership.md) and [financial observations](financial-observations.md).
38
+ - [Example recovery cutover](example-recovery-cutover.md).
39
+
40
+ ## Architecture and contributing
41
+
42
+ - [Component architecture](architecture.md), data ownership, trigger flow, and errors.
43
+ - [Component extraction](architecture/component-extraction.md).
44
+ - [Durable execution](architecture/durable-execution.md).
45
+ - [Recovery workflow architecture](architecture/recovery-workflow.md).
46
+ - [Development guide](development.md), local setup, quality gates, and code generation.
47
+ - [Testing utilities](testing.md), fixtures and mock webhook events.
48
+ - [Release guide](releasing.md), publishing and release PR descriptions.
49
+ - [Migration guide](../MIGRATION.md) and [release handoff](release-handoff.md).
50
+ - [Changelog](../CHANGELOG.md).
51
+
52
+ The [example app setup guide](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md)
53
+ covers sandbox configuration, checkout comparisons, and test flows.
54
+
55
+ ## Metered usage
56
+
57
+ Start with the [native Stripe setup guide](metering-setup.md), then read the
58
+ [shared contracts and sandbox evidence](metered-usage.md).
@@ -0,0 +1,80 @@
1
+ # Component architecture
2
+
3
+ ### Component-Owned Tables
4
+
5
+ The component manages 8 domain tables and 1 internal table:
6
+
7
+ | Table | Description |
8
+ | ------------------ | -------------------------------------------------------- |
9
+ | `accounts` | V2 account records with identity and configuration state |
10
+ | `products` | Stripe products with optional trial day management |
11
+ | `prices` | Stripe prices linked to products |
12
+ | `subscriptions` | Subscription lifecycle with first-class trial tracking |
13
+ | `checkoutSessions` | Checkout session state (embedded and redirect) |
14
+ | `invoices` | Invoice records with subscription metadata |
15
+ | `payments` | Payment intent records |
16
+ | `payouts` | Payout records for Connect/marketplace |
17
+ | `webhookEvents` | Internal ledger for replay protection and observability |
18
+
19
+ ### App-Layer Tables
20
+
21
+ The consuming app maintains its own tables for business context. The component never reads or writes app tables directly. App tables are updated via sync triggers that run in the same transaction as component writes.
22
+
23
+ Example app-layer tables (from a typical integration):
24
+
25
+ - Linking products to app-specific entities (e.g., communities, teams)
26
+ - Linking subscriptions to app-specific purchase types
27
+ - Payout percentage configurations
28
+
29
+ ### Trigger Flow
30
+
31
+ ```
32
+ Stripe Webhook Event
33
+ |
34
+ v
35
+ Webhook handler: Verify signature + check ledger
36
+ |
37
+ v
38
+ syncWebhook (one mutation transaction)
39
+ - Upsert component domain table
40
+ - Run sync trigger --> App updates its own tables
41
+ | Throwing rolls back the upsert;
42
+ | Stripe retries and the failed
43
+ | ledger row is reprocessed
44
+ v
45
+ Mark ledger row processed
46
+ |
47
+ v
48
+ Async hook (scheduled action) --> App calls external APIs
49
+ Failures do not roll back;
50
+ hooks should be idempotent
51
+ ```
52
+
53
+ ### Package Entry Points
54
+
55
+ | Entry Point | Contents |
56
+ | -------------------------------------------- | -------------------------------------------------------- |
57
+ | `@fantastic.dev/better-stripe` | `BetterStripe` class, `registerRoutes`, TypeScript types |
58
+ | `@fantastic.dev/better-stripe/react` | React hooks, headless UI components, formatting helpers |
59
+ | `@fantastic.dev/better-stripe/testing` | Test fixtures, mock webhooks, `assertTestEnvironment` |
60
+ | `@fantastic.dev/better-stripe/convex.config` | Convex component registration |
61
+
62
+ ### Error Handling
63
+
64
+ Structured errors are thrown as `ConvexError` with a `BetterStripeError` payload:
65
+
66
+ ```typescript
67
+ interface BetterStripeError {
68
+ code: BetterStripeErrorCode;
69
+ message: string;
70
+ stripeError?: {
71
+ type: string;
72
+ code?: string;
73
+ message: string;
74
+ };
75
+ }
76
+ ```
77
+
78
+ Error codes: `ACCOUNT_NOT_FOUND`, `ACCOUNT_CREATE_FAILED`, `PRODUCT_NOT_FOUND`, `PRICE_NOT_FOUND`, `SUBSCRIPTION_NOT_FOUND`, `SUBSCRIPTION_UPDATE_FAILED`, `CHECKOUT_CREATE_FAILED`, `CHECKOUT_NOT_FOUND`, `PAYMENT_METHOD_FAILED`, `WEBHOOK_VERIFICATION_FAILED`, `WEBHOOK_DUPLICATE_EVENT`, `STRIPE_API_ERROR`, `TEST_ENV_REQUIRED`, `INVALID_CONFIGURATION`.
79
+
80
+ > **Note:** All methods that throw their own errors or catch-and-rethrow now use structured `ConvexError(BetterStripeError)` payloads. Methods that let uncaught Stripe SDK errors propagate are a separate policy decision and not yet aligned.