@fantastic.dev/better-stripe 0.75.0 → 0.76.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.
@@ -22,6 +22,14 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
22
22
  requestKey: string;
23
23
  scopeKey: string;
24
24
  }, Promise<{
25
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
26
+ retryable: false;
27
+ status: "conflict";
28
+ } | {
29
+ reason: "policy_invalid";
30
+ retryable: false;
31
+ status: "rejected";
32
+ } | {
25
33
  operation: {
26
34
  accountId: string;
27
35
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -32,14 +40,6 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
32
40
  } | {
33
41
  enabled: boolean;
34
42
  status: "unchanged";
35
- } | {
36
- reason: "identity_changed" | "revision_changed" | "scope_busy";
37
- retryable: false;
38
- status: "conflict";
39
- } | {
40
- reason: "policy_invalid";
41
- retryable: false;
42
- status: "rejected";
43
43
  } | {
44
44
  reason: "provider_pending";
45
45
  retryable: true;
@@ -395,6 +395,14 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
395
395
  requestKey: string;
396
396
  scopeKey: string;
397
397
  }, Promise<{
398
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
399
+ retryable: false;
400
+ status: "conflict";
401
+ } | {
402
+ reason: "policy_invalid";
403
+ retryable: false;
404
+ status: "rejected";
405
+ } | {
398
406
  operation: {
399
407
  accountId: string;
400
408
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -405,14 +413,6 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
405
413
  } | {
406
414
  enabled: boolean;
407
415
  status: "unchanged";
408
- } | {
409
- reason: "identity_changed" | "revision_changed" | "scope_busy";
410
- retryable: false;
411
- status: "conflict";
412
- } | {
413
- reason: "policy_invalid";
414
- retryable: false;
415
- status: "rejected";
416
416
  } | {
417
417
  reason: "provider_pending";
418
418
  retryable: true;
@@ -595,22 +595,6 @@ export declare const startWorkflow: import("convex/server").RegisteredMutation<"
595
595
  } & {
596
596
  providerAction: string;
597
597
  }, Promise<{
598
- reason: "history_incomplete" | "provider_outcome_unknown";
599
- retryable: false;
600
- status: "unknown";
601
- } | {
602
- reason: "identity_changed" | "revision_changed" | "scope_busy";
603
- retryable: false;
604
- status: "conflict";
605
- } | {
606
- reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
607
- retryable: false;
608
- status: "rejected";
609
- } | {
610
- reason: "provider_pending";
611
- retryable: true;
612
- status: "not_ready";
613
- } | {
614
598
  operation: {
615
599
  accountId: string;
616
600
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -627,16 +611,7 @@ export declare const startWorkflow: import("convex/server").RegisteredMutation<"
627
611
  version: number;
628
612
  };
629
613
  status: "canceled";
630
- }>>;
631
- export declare const resumeWorkflow: import("convex/server").RegisteredMutation<"public", {
632
- accountId: string;
633
- definitionVersion: string;
634
- operationId: import("convex/values").GenericId<"balanceFundingOperations">;
635
- providerApiVersion: string;
636
- scopeKey: string;
637
- stripeSubscriptionId: string;
638
- version: number;
639
- }, Promise<{
614
+ } | {
640
615
  reason: "history_incomplete" | "provider_outcome_unknown";
641
616
  retryable: false;
642
617
  status: "unknown";
@@ -652,7 +627,16 @@ export declare const resumeWorkflow: import("convex/server").RegisteredMutation<
652
627
  reason: "provider_pending";
653
628
  retryable: true;
654
629
  status: "not_ready";
655
- } | {
630
+ }>>;
631
+ export declare const resumeWorkflow: import("convex/server").RegisteredMutation<"public", {
632
+ accountId: string;
633
+ definitionVersion: string;
634
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
635
+ providerApiVersion: string;
636
+ scopeKey: string;
637
+ stripeSubscriptionId: string;
638
+ version: number;
639
+ }, Promise<{
656
640
  operation: {
657
641
  accountId: string;
658
642
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -669,6 +653,22 @@ export declare const resumeWorkflow: import("convex/server").RegisteredMutation<
669
653
  version: number;
670
654
  };
671
655
  status: "canceled";
656
+ } | {
657
+ reason: "history_incomplete" | "provider_outcome_unknown";
658
+ retryable: false;
659
+ status: "unknown";
660
+ } | {
661
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
662
+ retryable: false;
663
+ status: "conflict";
664
+ } | {
665
+ reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
666
+ retryable: false;
667
+ status: "rejected";
668
+ } | {
669
+ reason: "provider_pending";
670
+ retryable: true;
671
+ status: "not_ready";
672
672
  }>>;
673
673
  export declare const cancelWorkflow: import("convex/server").RegisteredMutation<"public", {
674
674
  accountId: string;
@@ -2,6 +2,14 @@ import type { Infer } from "convex/values";
2
2
  import type { MutationCtx } from "../_generated/server.js";
3
3
  import { prepareArgs, finishPreparationArgs } from "./mutationValidators.js";
4
4
  export declare function prepareHandler(ctx: MutationCtx, args: Infer<typeof prepareArgs>): Promise<{
5
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
6
+ retryable: false;
7
+ status: "conflict";
8
+ } | {
9
+ reason: "policy_invalid";
10
+ retryable: false;
11
+ status: "rejected";
12
+ } | {
5
13
  operation: {
6
14
  accountId: string;
7
15
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -12,14 +20,6 @@ export declare function prepareHandler(ctx: MutationCtx, args: Infer<typeof prep
12
20
  } | {
13
21
  enabled: boolean;
14
22
  status: "unchanged";
15
- } | {
16
- reason: "identity_changed" | "revision_changed" | "scope_busy";
17
- retryable: false;
18
- status: "conflict";
19
- } | {
20
- reason: "policy_invalid";
21
- retryable: false;
22
- status: "rejected";
23
23
  } | {
24
24
  reason: "provider_pending";
25
25
  retryable: true;
@@ -60,22 +60,6 @@ export declare const phaseRef: import("convex/values").VObject<{
60
60
  }, "required", "accountId" | "definitionVersion" | "operationId" | "phase" | "providerApiVersion" | "providerKey" | "scopeKey" | "stripeSubscriptionId" | "version">;
61
61
  export type FundingPhaseRef = Infer<typeof phaseRef>;
62
62
  export declare const workflowStartResult: import("convex/values").VUnion<{
63
- reason: "history_incomplete" | "provider_outcome_unknown";
64
- retryable: false;
65
- status: "unknown";
66
- } | {
67
- reason: "identity_changed" | "revision_changed" | "scope_busy";
68
- retryable: false;
69
- status: "conflict";
70
- } | {
71
- reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
72
- retryable: false;
73
- status: "rejected";
74
- } | {
75
- reason: "provider_pending";
76
- retryable: true;
77
- status: "not_ready";
78
- } | {
79
63
  operation: {
80
64
  accountId: string;
81
65
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -92,6 +76,22 @@ export declare const workflowStartResult: import("convex/values").VUnion<{
92
76
  version: number;
93
77
  };
94
78
  status: "canceled";
79
+ } | {
80
+ reason: "history_incomplete" | "provider_outcome_unknown";
81
+ retryable: false;
82
+ status: "unknown";
83
+ } | {
84
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
85
+ retryable: false;
86
+ status: "conflict";
87
+ } | {
88
+ reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
89
+ retryable: false;
90
+ status: "rejected";
91
+ } | {
92
+ reason: "provider_pending";
93
+ retryable: true;
94
+ status: "not_ready";
95
95
  }, [import("convex/values").VObject<{
96
96
  operation: {
97
97
  accountId: string;
@@ -2351,14 +2351,6 @@ export declare function setupAllowance(): Promise<{
2351
2351
  preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
2352
2352
  requestKey: string;
2353
2353
  result?: {
2354
- reason: "identity_changed" | "revision_changed" | "scope_busy";
2355
- retryable: false;
2356
- status: "conflict";
2357
- } | {
2358
- reason: "policy_invalid";
2359
- retryable: false;
2360
- status: "rejected";
2361
- } | {
2362
2354
  operation: {
2363
2355
  accountId: string;
2364
2356
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -2369,6 +2361,14 @@ export declare function setupAllowance(): Promise<{
2369
2361
  } | {
2370
2362
  enabled: boolean;
2371
2363
  status: "unchanged";
2364
+ } | {
2365
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
2366
+ retryable: false;
2367
+ status: "conflict";
2368
+ } | {
2369
+ reason: "policy_invalid";
2370
+ retryable: false;
2371
+ status: "rejected";
2372
2372
  } | {
2373
2373
  reason: "provider_pending";
2374
2374
  retryable: true;
@@ -2379,14 +2379,6 @@ export declare function setupAllowance(): Promise<{
2379
2379
  payload: import("convex/values").VString<string, "required">;
2380
2380
  preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
2381
2381
  result: import("convex/values").VUnion<{
2382
- reason: "identity_changed" | "revision_changed" | "scope_busy";
2383
- retryable: false;
2384
- status: "conflict";
2385
- } | {
2386
- reason: "policy_invalid";
2387
- retryable: false;
2388
- status: "rejected";
2389
- } | {
2390
2382
  operation: {
2391
2383
  accountId: string;
2392
2384
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -2397,6 +2389,14 @@ export declare function setupAllowance(): Promise<{
2397
2389
  } | {
2398
2390
  enabled: boolean;
2399
2391
  status: "unchanged";
2392
+ } | {
2393
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
2394
+ retryable: false;
2395
+ status: "conflict";
2396
+ } | {
2397
+ reason: "policy_invalid";
2398
+ retryable: false;
2399
+ status: "rejected";
2400
2400
  } | {
2401
2401
  reason: "provider_pending";
2402
2402
  retryable: true;
package/docs/README.md CHANGED
@@ -20,6 +20,7 @@ guide for your integration.
20
20
  - [Billing history](billing-history.md).
21
21
  - [Invoice payment pages](invoice-payment-pages.md).
22
22
  - [Checkout session pages](checkout-session-pages.md).
23
+ - [Captured Checkout payment observations](captured-checkout-payment.md), expanded provider evidence without fee or access authority.
23
24
  - [Subscription payment methods](subscription-payment-methods.md).
24
25
  - [SetupIntent recovery](setup-intent-recovery.md).
25
26
  - [Balance funding state](balance-funding-state.md) and [workflow](balance-funding-workflow.md).
@@ -0,0 +1,136 @@
1
+ # Captured Checkout payment observations
2
+
3
+ `qualifyCapturedCheckoutPayment` is a server-side, read-only qualifier for an
4
+ already retrieved, expanded payment-mode Checkout Session. It makes no provider
5
+ request and performs no component or database write.
6
+
7
+ Retrieve the original Session with its PaymentIntent and latest charge expanded:
8
+
9
+ ```ts
10
+ import { qualifyCapturedCheckoutPayment } from "@fantastic.dev/better-stripe";
11
+
12
+ // Authenticate the caller and resolve these values from the host's original
13
+ // purchase binding before retrieving provider data. Browser selectors and
14
+ // provider metadata do not authorize this read.
15
+ const session = await stripe.getCheckoutSessionFromStripe(ctx, {
16
+ stripeSessionId: original.stripeSessionId,
17
+ expand: ["payment_intent.latest_charge"],
18
+ });
19
+
20
+ const observation = qualifyCapturedCheckoutPayment(session, {
21
+ stripeSessionId: original.stripeSessionId,
22
+ customerAccountId: original.customerAccountId,
23
+ livemode: original.livemode,
24
+ });
25
+
26
+ if (observation.status === "unavailable") {
27
+ // Keep purchase/access verification pending or unavailable. Do not infer a
28
+ // payment from the browser return URL or manufacture a webhook event.
29
+ return { status: "unavailable", reason: observation.reason };
30
+ }
31
+
32
+ // Correlate these generic provider facts with the authorized original request.
33
+ return observation;
34
+ ```
35
+
36
+ The qualifier requires a completed, paid, payment-mode Session, an expanded
37
+ succeeded PaymentIntent and its expanded paid, succeeded, fully captured charge.
38
+ Session, PaymentIntent and charge identities, buyer account, livemode, positive
39
+ safe-integer amounts and currency must agree. Missing or unexpanded objects,
40
+ partial capture and contradictory evidence cannot return `ready`.
41
+
42
+ The result is a discriminated union:
43
+
44
+ - `status: "ready"` includes `stripeSessionId`, `stripePaymentIntentId`,
45
+ `stripeChargeId`, `customerAccountId`, `livemode`, `amount`, `currency`,
46
+ `sessionMetadata` and `paymentIntentMetadata`.
47
+ - `status: "unavailable"` includes a reason of `invalid_context`,
48
+ `invalid_evidence` or `identity_mismatch`.
49
+
50
+ `amount` remains an integer in Stripe's original-currency **minor units**. It is
51
+ not a decimal amount in major units: do not divide every currency by 100 or round
52
+ the provider value. Keep the currency with the amount and use the public currency
53
+ formatting helpers for display. Session and PaymentIntent metadata remain
54
+ separate string records for host correlation; they are not authentication.
55
+
56
+ ## Historical capture is separate from authority
57
+
58
+ `ready` describes coherent evidence that the original payment was fully captured.
59
+ It does not require an invoice, processing fee or balance transaction. Delayed
60
+ fees do not make that captured payment unavailable, and a later refund does not
61
+ erase its historical capture. Current refund eligibility, dispute exposure,
62
+ settlement, payable balance and payout authority require their own APIs and
63
+ current policy checks.
64
+
65
+ This observation is not a reservation, verified webhook signature, durable
66
+ fulfillment receipt or access grant. The host still authenticates the actor,
67
+ binds the immutable request and original buyer/account, checks application
68
+ eligibility and decides whether to accept signed-original evidence and fulfill
69
+ the purchase. A signed webhook adapter may reuse this same qualifier after its
70
+ real signature verification and original correlation. Calling the qualifier does
71
+ not create a signed event or replace that adapter's transaction and replay rules.
72
+
73
+ ## Reuse from a real signed adapter
74
+
75
+ The current Vite example does **not** implement an authenticated captured-receipt
76
+ adapter or a durable signed-original Checkout fulfillment consumer. The following
77
+ is a host integration sketch, not an implemented example handler or an additional
78
+ package API:
79
+
80
+ ```ts
81
+ import {
82
+ qualifyCapturedCheckoutPayment,
83
+ registerRoutes,
84
+ } from "@fantastic.dev/better-stripe";
85
+
86
+ registerRoutes(http, components.betterStripe, {
87
+ stripeSecretKey,
88
+ webhookSecret,
89
+ onEvent: async (ctx, event) => {
90
+ // registerRoutes has verified the real webhook signature before this hook.
91
+ if (!("data" in event) || event.type !== "checkout.session.completed")
92
+ return;
93
+
94
+ // These two functions are host-owned: resolve the immutable original, then
95
+ // apply its transactional acceptance/replay policy. They are not SDK APIs.
96
+ const original = await readOriginalForVerifiedEvent(ctx, {
97
+ eventId: event.id,
98
+ stripeSessionId: event.data.object.id,
99
+ });
100
+ const session = await stripe.getCheckoutSessionFromStripe(ctx, {
101
+ stripeSessionId: original.stripeSessionId,
102
+ expand: ["payment_intent.latest_charge"],
103
+ });
104
+ const observation = qualifyCapturedCheckoutPayment(session, {
105
+ stripeSessionId: original.stripeSessionId,
106
+ customerAccountId: original.customerAccountId,
107
+ livemode: original.livemode,
108
+ });
109
+ if (observation.status !== "ready") return;
110
+ await acceptOriginalPayment(ctx, {
111
+ eventId: event.id,
112
+ original,
113
+ observation,
114
+ });
115
+ },
116
+ });
117
+ ```
118
+
119
+ The host must retain the actual verified event identity, reconcile it with the
120
+ original purchase, and make acceptance and entitlement writes under its existing
121
+ atomic/replay rules. The fetched Session remains a read-time provider
122
+ observation; the qualifier does not assert that it was the signed event payload.
123
+ Do not construct a `Stripe.Event` from a receipt read or invoke webhook-only
124
+ processing merely to qualify a captured payment. Existing applications can share
125
+ the qualifier between their authorized reader and their genuine signed adapter
126
+ without duplicating the generic capture validator.
127
+
128
+ ## Receipt presentation
129
+
130
+ For receipt presentation, keep the public React `PaymentReceipt` workflow and
131
+ host render props. Supply an authoritative server payment projection only after
132
+ the host's receipt policy accepts it. A successful browser `confirm()` means
133
+ confirmation was submitted; it does not establish paid status or access. The
134
+ host retains authorization, receipt refresh, entitlement decisions, localization
135
+ and styling. See [React workflows](react-workflows.md) and
136
+ [refund context](refund-context.md) for their separate contracts.
@@ -201,9 +201,12 @@ keep it editable if a payment attempt fails.
201
201
  The lower-level `CheckoutElementsForm`, `PaymentIntentForm`, and `CheckoutForm`
202
202
  are also exported for an existing client secret.
203
203
 
204
- Only a server-confirmed payment or checkout session should grant access to the
205
- product. Use `PaymentReceipt` or `CheckoutStatus` with webhook-backed query data;
206
- a browser return URL alone does not prove payment.
204
+ Use `PaymentReceipt` or `CheckoutStatus` with authoritative server-backed data.
205
+ A completed Checkout Session or a
206
+ [captured payment observation](captured-checkout-payment.md) does not itself
207
+ grant access. The host still authenticates the buyer, correlates the original
208
+ purchase and applies its fulfillment and entitlement policy. A browser return
209
+ URL or successful confirmation submission alone does not prove payment.
207
210
 
208
211
  ## Via API, BetterStripe components, or Stripe embedded
209
212
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.75.0",
3
+ "version": "0.76.0",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",