@fantastic.dev/better-stripe 0.75.0 → 0.77.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,182 @@
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
+ ## Authorized Vite receipt read
74
+
75
+ The Vite reference exposes two functions under
76
+ `example/convex/billing/capturedReceipt/`:
77
+
78
+ - `queries.context({ stripeSessionId })` authenticates through the existing
79
+ `historyActor` mapping and returns only `{ actorId, accountId, sessionId }`.
80
+ The original cached Session must be payment-mode, belong to that actor and
81
+ reference a unique personal account owned by the same actor. Missing, foreign
82
+ or organization-scoped Sessions, and missing, foreign, ambiguous or
83
+ organization-scoped account mappings receive the same generic authorization
84
+ rejection. The cached Session reader does not establish Session uniqueness.
85
+ - `actions.read({ stripeSessionId })` calls that same query on the server for
86
+ each read. It does not accept an actor or account supplied by the browser.
87
+ After the example's test-mode key guard, it retrieves the original Session
88
+ with `payment_intent.latest_charge` expanded and calls the public
89
+ `qualifyCapturedCheckoutPayment` helper.
90
+
91
+ The action returns `status: "ready"` with the original Session, PaymentIntent,
92
+ charge and account IDs, livemode, integer minor-unit amount and currency. It
93
+ omits both metadata records, client secrets, URLs and raw provider errors. For an
94
+ authorized actor, incomplete or unavailable provider evidence returns
95
+ `{ status: "unavailable" }`. Authorization failures remain rejections; they do
96
+ not become successful empty reads or evidence that a payment is pending.
97
+
98
+ The default demo is anonymous. Choosing a demonstration buyer or account does
99
+ not authenticate it, and this integration does not install an authentication
100
+ provider. A host must supply verified Convex authentication and the existing
101
+ unique token-to-user mapping before an authorized receipt read is available.
102
+
103
+ For the mounted receipt workflow, use the authoritative context triple as the
104
+ public `useWorkflowAction` scope and keyed child identity. Loading, absent or
105
+ rejected context must remove the previous receipt. Actor or account changes
106
+ must invalidate it even if the Session ID and authenticated boolean stay the
107
+ same. A late response or retry belongs only to its original scope. Show a fixed,
108
+ sanitized unavailable view for query/action failures, never the raw error.
109
+
110
+ Only a `ready` result maps to the public `PaymentReceipt` presentation
111
+ `{ status: "succeeded", amount, currency }`. Do not pass `ready` directly as a
112
+ payment status, invent a zero amount or default currency, or infer capture from
113
+ a cached Session's `complete` status. Host components retain their styles and
114
+ routing; the SDK workflow and receipt remain the shared presentation primitives.
115
+
116
+ This reader performs no fulfillment or access write. It is separate from the
117
+ signed-adapter sketch below and does not turn a provider read into signed-original
118
+ purchase evidence.
119
+
120
+ ## Reuse from a real signed adapter
121
+
122
+ The Vite receipt reader does **not** implement a durable signed-original Checkout
123
+ fulfillment consumer. The following is a host integration sketch, not an
124
+ implemented example handler or an additional package API:
125
+
126
+ ```ts
127
+ import {
128
+ qualifyCapturedCheckoutPayment,
129
+ registerRoutes,
130
+ } from "@fantastic.dev/better-stripe";
131
+
132
+ registerRoutes(http, components.betterStripe, {
133
+ stripeSecretKey,
134
+ webhookSecret,
135
+ onEvent: async (ctx, event) => {
136
+ // registerRoutes has verified the real webhook signature before this hook.
137
+ if (!("data" in event) || event.type !== "checkout.session.completed")
138
+ return;
139
+
140
+ // These two functions are host-owned: resolve the immutable original, then
141
+ // apply its transactional acceptance/replay policy. They are not SDK APIs.
142
+ const original = await readOriginalForVerifiedEvent(ctx, {
143
+ eventId: event.id,
144
+ stripeSessionId: event.data.object.id,
145
+ });
146
+ const session = await stripe.getCheckoutSessionFromStripe(ctx, {
147
+ stripeSessionId: original.stripeSessionId,
148
+ expand: ["payment_intent.latest_charge"],
149
+ });
150
+ const observation = qualifyCapturedCheckoutPayment(session, {
151
+ stripeSessionId: original.stripeSessionId,
152
+ customerAccountId: original.customerAccountId,
153
+ livemode: original.livemode,
154
+ });
155
+ if (observation.status !== "ready") return;
156
+ await acceptOriginalPayment(ctx, {
157
+ eventId: event.id,
158
+ original,
159
+ observation,
160
+ });
161
+ },
162
+ });
163
+ ```
164
+
165
+ The host must retain the actual verified event identity, reconcile it with the
166
+ original purchase, and make acceptance and entitlement writes under its existing
167
+ atomic/replay rules. The fetched Session remains a read-time provider
168
+ observation; the qualifier does not assert that it was the signed event payload.
169
+ Do not construct a `Stripe.Event` from a receipt read or invoke webhook-only
170
+ processing merely to qualify a captured payment. Existing applications can share
171
+ the qualifier between their authorized reader and their genuine signed adapter
172
+ without duplicating the generic capture validator.
173
+
174
+ ## Receipt presentation
175
+
176
+ For receipt presentation, keep the public React `PaymentReceipt` workflow and
177
+ host render props. Supply an authoritative server payment projection only after
178
+ the host's receipt policy accepts it. A successful browser `confirm()` means
179
+ confirmation was submitted; it does not establish paid status or access. The
180
+ host retains authorization, receipt refresh, entitlement decisions, localization
181
+ and styling. See [React workflows](react-workflows.md) and
182
+ [refund context](refund-context.md) for their separate contracts.
@@ -30,6 +30,12 @@ missing, foreign or organization mappings, and overrides any browser-supplied
30
30
  account selector. Existing React `Checkout` workflows remain responsible for
31
31
  checkout presentation; hosts such as Dojo retain their own styles and routing.
32
32
 
33
+ For an individual payment-mode Session, the separate
34
+ [authorized captured-receipt reference](captured-checkout-payment.md#authorized-vite-receipt-read)
35
+ rechecks the authenticated original Session/account before an expanded provider
36
+ read. Its context and receipt workflow do not authorize access from a demo
37
+ persona or treat a cached `complete` Session as payment confirmation.
38
+
33
39
  ## Selectors and results
34
40
 
35
41
  - `customerAccount` must be a V2 `acct_…` identifier. Legacy customer selectors
@@ -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.77.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",