@fantastic.dev/better-stripe 0.71.0 → 0.72.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 (100) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +524 -50
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +246 -9
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +524 -50
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +246 -9
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/paymentSource/resolver.d.ts +6 -1
  12. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  13. package/dist/client/paymentSource/resolver.js +49 -41
  14. package/dist/client/paymentSource/resolver.js.map +1 -1
  15. package/dist/client/processingCostReconciliation/provider.d.ts.map +1 -1
  16. package/dist/client/processingCostReconciliation/provider.js +14 -2
  17. package/dist/client/processingCostReconciliation/provider.js.map +1 -1
  18. package/dist/client/settlement/authorization.fixture.d.ts +26 -0
  19. package/dist/client/settlement/authorization.fixture.d.ts.map +1 -1
  20. package/dist/client/settlement/execution.d.ts +2 -0
  21. package/dist/client/settlement/execution.d.ts.map +1 -1
  22. package/dist/client/settlement/execution.js.map +1 -1
  23. package/dist/client/usage/index.d.ts +1 -0
  24. package/dist/client/usage/index.d.ts.map +1 -1
  25. package/dist/client/usage/invoiceSale.d.ts +8 -0
  26. package/dist/client/usage/invoiceSale.d.ts.map +1 -1
  27. package/dist/client/usage/invoiceSale.js +3 -0
  28. package/dist/client/usage/invoiceSale.js.map +1 -1
  29. package/dist/client/usage/mixedInvoice.fixtures.d.ts +315 -0
  30. package/dist/client/usage/mixedInvoice.fixtures.d.ts.map +1 -0
  31. package/dist/client/usage/mixedInvoice.fixtures.js +55 -0
  32. package/dist/client/usage/mixedInvoice.fixtures.js.map +1 -0
  33. package/dist/client/usage/mixedInvoiceSale.d.ts +6 -0
  34. package/dist/client/usage/mixedInvoiceSale.d.ts.map +1 -0
  35. package/dist/client/usage/mixedInvoiceSale.js +160 -0
  36. package/dist/client/usage/mixedInvoiceSale.js.map +1 -0
  37. package/dist/client/usage/observationClient.d.ts +2 -2
  38. package/dist/client/usage/observationClient.d.ts.map +1 -1
  39. package/dist/client/usage/retainedInvoiceSource.d.ts +20 -0
  40. package/dist/client/usage/retainedInvoiceSource.d.ts.map +1 -0
  41. package/dist/client/usage/retainedInvoiceSource.js +92 -0
  42. package/dist/client/usage/retainedInvoiceSource.js.map +1 -0
  43. package/dist/client/usage/settlement.d.ts +5 -0
  44. package/dist/client/usage/settlement.d.ts.map +1 -1
  45. package/dist/client/usage/settlement.js +28 -9
  46. package/dist/client/usage/settlement.js.map +1 -1
  47. package/dist/component/_generated/component.d.ts +65 -0
  48. package/dist/component/_generated/component.d.ts.map +1 -1
  49. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  50. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  51. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  52. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  53. package/dist/component/earnings/triggers.d.ts +84 -6
  54. package/dist/component/earnings/triggers.d.ts.map +1 -1
  55. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  56. package/dist/component/recoveryWorkflow/helpers.d.ts +13 -0
  57. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
  58. package/dist/component/recoveryWorkflow/mutations.d.ts +13 -0
  59. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
  60. package/dist/component/recoveryWorkflow/queries.d.ts +26 -0
  61. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
  62. package/dist/component/recoveryWorkflow/schema.d.ts +464 -16
  63. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
  64. package/dist/component/schema.d.ts +246 -9
  65. package/dist/component/settlement/mutations.d.ts +26 -0
  66. package/dist/component/settlement/mutations.d.ts.map +1 -1
  67. package/dist/component/settlement/queries.d.ts +13 -0
  68. package/dist/component/settlement/queries.d.ts.map +1 -1
  69. package/dist/component/settlement/schema.d.ts +122 -3
  70. package/dist/component/settlement/schema.d.ts.map +1 -1
  71. package/dist/component/settlement/schema.js +2 -0
  72. package/dist/component/settlement/schema.js.map +1 -1
  73. package/dist/component/usage/allowance.fixtures.d.ts +262 -25
  74. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  75. package/dist/component/usageCredits/accounting.fixtures.d.ts +246 -9
  76. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  77. package/dist/shared/usageInvoiceLines.d.ts +32 -0
  78. package/dist/shared/usageInvoiceLines.d.ts.map +1 -0
  79. package/dist/shared/usageInvoiceLines.js +13 -0
  80. package/dist/shared/usageInvoiceLines.js.map +1 -0
  81. package/docs/evidence/native-metering/mixed-settlement-2026-10-20.json +284 -0
  82. package/docs/metering-setup.md +3 -2
  83. package/docs/usage-example.md +24 -5
  84. package/docs/usage-settlement.md +74 -8
  85. package/docs/usage-verification.md +22 -2
  86. package/package.json +1 -1
  87. package/src/client/paymentSource/resolver.ts +80 -59
  88. package/src/client/processingCostReconciliation/provider.ts +20 -2
  89. package/src/client/settlement/execution.ts +2 -0
  90. package/src/client/usage/index.ts +2 -0
  91. package/src/client/usage/invoiceSale.ts +10 -0
  92. package/src/client/usage/mixedInvoice.fixtures.ts +54 -0
  93. package/src/client/usage/mixedInvoiceSale.test.ts +92 -0
  94. package/src/client/usage/mixedInvoiceSale.ts +196 -0
  95. package/src/client/usage/mixedSettlement.test.ts +187 -0
  96. package/src/client/usage/retainedInvoiceSource.ts +118 -0
  97. package/src/client/usage/settlement.ts +47 -9
  98. package/src/component/_generated/component.ts +50 -0
  99. package/src/component/settlement/schema.ts +2 -0
  100. package/src/shared/usageInvoiceLines.ts +14 -0
@@ -0,0 +1,118 @@
1
+ import type Stripe from "stripe";
2
+ import type { Component, RunCtx } from "../helpers.js";
3
+ import { componentRef } from "../webhooks/helpers.js";
4
+ import type { ResolvedSettlement } from "../settlement/execution.js";
5
+ import { resolveVerifiedPaymentSource } from "../paymentSource/resolver.js";
6
+ import type { VerifiedPaymentSourceOptions } from "../paymentSource/contracts.js";
7
+ /** Refund/dispute cost observations may reuse only the complete original, sealed line proof. */
8
+ export async function retainedInvoiceSource(
9
+ stripe: Stripe,
10
+ component: Component,
11
+ ctx: RunCtx,
12
+ input: VerifiedPaymentSourceOptions,
13
+ ) {
14
+ const payment = await stripe.paymentIntents.retrieve(input.paymentIntentId);
15
+ const chargeId =
16
+ typeof payment.latest_charge === "string"
17
+ ? payment.latest_charge
18
+ : payment.latest_charge?.id;
19
+ if (!chargeId) return null;
20
+ const claim = (await ctx.runQuery(
21
+ componentRef(component, "settlement/queries/getSettlementAllocation"),
22
+ { sourceChargeId: chargeId },
23
+ )) as ResolvedSettlement | null;
24
+ const usage = claim?.usageSource;
25
+ if (
26
+ !claim ||
27
+ !usage?.invoiceLines?.length ||
28
+ claim.paymentIntentId !== input.paymentIntentId ||
29
+ claim.gross !== input.gross ||
30
+ claim.currency !== input.currency ||
31
+ usage.customerAccount !== input.customerAccountId ||
32
+ usage.livemode !== payment.livemode ||
33
+ input.stripeAccountId ||
34
+ (input.invoiceId !== undefined &&
35
+ input.invoiceId !== claim.sourceInvoiceId) ||
36
+ (input.subscriptionId !== undefined &&
37
+ input.subscriptionId !== usage.subscriptionId)
38
+ )
39
+ return null;
40
+ const customerId =
41
+ typeof payment.customer === "string"
42
+ ? payment.customer
43
+ : payment.customer?.id;
44
+ if (!customerId) return null;
45
+ const realm = await stripe.accounts.retrieve(null);
46
+ if (realm.id !== usage.stripeAccountId) return null;
47
+ const result = await resolveVerifiedPaymentSource(
48
+ stripe,
49
+ {
50
+ ...input,
51
+ invoiceId: claim.sourceInvoiceId,
52
+ subscriptionId: usage.subscriptionId,
53
+ },
54
+ {
55
+ requirePayable: false,
56
+ customerId,
57
+ verifyInvoiceLines(invoice, lines) {
58
+ if (
59
+ invoice.id !== claim.sourceInvoiceId ||
60
+ (invoice.starting_balance ?? 0) !== 0 ||
61
+ (invoice.ending_balance ?? 0) !== 0 ||
62
+ (invoice.pre_payment_credit_notes_amount ?? 0) !== 0 ||
63
+ (invoice.post_payment_credit_notes_amount ?? 0) !== 0 ||
64
+ (invoice.total_discount_amounts ?? []).length ||
65
+ (invoice.total_taxes ?? []).length ||
66
+ lines.length !== usage.invoiceLines!.length
67
+ )
68
+ return null;
69
+ for (const line of lines) {
70
+ const saved = usage.invoiceLines!.find(
71
+ (row) => row.lineId === line.id,
72
+ ),
73
+ parent = line.parent?.subscription_item_details,
74
+ price = line.pricing?.price_details;
75
+ if (
76
+ !saved ||
77
+ line.object !== "line_item" ||
78
+ line.invoice !== invoice.id ||
79
+ line.currency !== claim.currency ||
80
+ line.livemode !== usage.livemode ||
81
+ !parent ||
82
+ parent.proration ||
83
+ parent.subscription !== usage.subscriptionId ||
84
+ parent.subscription_item !== saved.subscriptionItemId ||
85
+ line.pricing?.type !== "price_details" ||
86
+ price?.price !== saved.stripePriceId ||
87
+ price.product !== saved.stripeProductId ||
88
+ line.amount !== saved.amount ||
89
+ (line.quantity_decimal?.toString() ?? String(line.quantity)) !==
90
+ saved.quantity ||
91
+ line.period.start !== saved.period.start ||
92
+ line.period.end !== saved.period.end ||
93
+ (line.discount_amounts ?? []).length ||
94
+ (line.pretax_credit_amounts ?? []).length ||
95
+ (line.taxes ?? []).length
96
+ )
97
+ return null;
98
+ }
99
+ return {
100
+ stripePriceId: usage.stripePriceId,
101
+ stripeProductId: usage.stripeProductId,
102
+ };
103
+ },
104
+ },
105
+ );
106
+ if (
107
+ result.status === "ready" &&
108
+ (result.value.chargeId !== claim.sourceChargeId ||
109
+ result.value.invoicePaymentId !== usage.invoicePaymentId ||
110
+ result.value.processingFee !== claim.processingFee)
111
+ )
112
+ return {
113
+ status: "conflict" as const,
114
+ reason: "identity_changed" as const,
115
+ retryable: false as const,
116
+ };
117
+ return result;
118
+ }
@@ -1,3 +1,9 @@
1
+ import {
2
+ authorizeSettlement,
3
+ type SettlementAuthorization,
4
+ } from "../settlement/authorization.js";
5
+ import { assertPolicyContextMatches } from "../../shared/settlementPolicyContext.js";
6
+ import type { SettleSaleOptions } from "../settlement/settleSale.js";
1
7
  import { getUsageInvoiceSale } from "./invoiceSale.js";
2
8
  import { allocateSale } from "../settlement/allocation.js";
3
9
  import { selectCommissionInvoice } from "../settlement/commissions.js";
@@ -12,6 +18,9 @@ import type { SaleAllocationOptions } from "../settlement/allocation.js";
12
18
  import type { CommissionTerm } from "../settlement/commissions.js";
13
19
  import type { UsageInvoiceSaleOptions } from "./invoiceSale.js";
14
20
  export type UsageInvoiceSettlementOptions = UsageInvoiceSaleOptions & {
21
+ authorize?: SettlementAuthorization;
22
+ /** Optional host-resolved, conserved allocation including owned cost recovery. */
23
+ allocation?: SettleSaleOptions["allocation"];
15
24
  policy: Omit<SaleAllocationOptions, "gross" | "processingFee"> & {
16
25
  commissionTerm?: CommissionTerm;
17
26
  };
@@ -38,8 +47,13 @@ export async function settleUsageInvoice(
38
47
  throw new Error(
39
48
  "Retained allocation conflicts with verified invoice proceeds",
40
49
  );
50
+ if (prior)
51
+ assertPolicyContextMatches(
52
+ prior.policyContext,
53
+ input.allocation?.policyContext,
54
+ );
41
55
  let affiliate = input.policy.affiliate;
42
- if (affiliate) {
56
+ if (affiliate && !input.allocation) {
43
57
  const commission = await selectCommissionInvoice(stripe, component, ctx, {
44
58
  subscriptionId: input.subscription.subscriptionId,
45
59
  invoiceId: source.invoiceId,
@@ -49,17 +63,33 @@ export async function settleUsageInvoice(
49
63
  if (commission.status !== "ready") return commission;
50
64
  if (!commission.eligible) affiliate = undefined;
51
65
  }
52
- const allocation = allocateSale({
53
- ...input.policy,
54
- affiliate,
55
- gross: source.gross,
56
- processingFee: source.processingFee,
57
- });
58
- return executeResolvedTransfers(stripe, component, ctx, {
66
+ const allocation =
67
+ input.allocation ??
68
+ allocateSale({
69
+ ...input.policy,
70
+ affiliate,
71
+ gross: source.gross,
72
+ processingFee: source.processingFee,
73
+ });
74
+ if (
75
+ input.allocation &&
76
+ (input.allocation.gross !== source.gross ||
77
+ input.allocation.processingFee !== source.processingFee ||
78
+ input.allocation.currency !== source.currency)
79
+ )
80
+ throw new Error("Allocation conflicts with verified invoice proceeds");
81
+ const request: ResolvedSettlement = {
82
+ ...(input.allocation
83
+ ? {
84
+ policyContext: input.allocation.policyContext,
85
+ adjustmentAmount: input.allocation.adjustmentAmount,
86
+ }
87
+ : {}),
59
88
  sourceChargeId: source.chargeId,
60
89
  paymentIntentId: source.paymentIntentId,
61
90
  sourceInvoiceId: source.invoiceId,
62
91
  usageSource: {
92
+ ...(source.invoiceLines ? { invoiceLines: source.invoiceLines } : {}),
63
93
  stripeAccountId: input.scope.stripeAccountId,
64
94
  customerAccount: source.customerAccountId,
65
95
  livemode: source.livemode,
@@ -77,5 +107,13 @@ export async function settleUsageInvoice(
77
107
  processingFee: source.processingFee,
78
108
  platformNet: allocation.platformNet,
79
109
  transfers: allocation.transfers,
80
- });
110
+ };
111
+ await authorizeSettlement(input.authorize, prior ?? request);
112
+ return executeResolvedTransfers(
113
+ stripe,
114
+ component,
115
+ ctx,
116
+ request,
117
+ input.authorize,
118
+ );
81
119
  }
@@ -7914,6 +7914,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7914
7914
  }>;
7915
7915
  usageSource?: {
7916
7916
  customerAccount: string;
7917
+ invoiceLines?: Array<{
7918
+ amount: number;
7919
+ kind: "fixed" | "metered";
7920
+ lineId: string;
7921
+ period: { end: number; start: number };
7922
+ quantity: string;
7923
+ stripePriceId: string;
7924
+ stripeProductId: string;
7925
+ subscriptionItemId: string;
7926
+ }>;
7917
7927
  invoicePaymentId: string;
7918
7928
  livemode: boolean;
7919
7929
  meterId: string;
@@ -8046,6 +8056,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8046
8056
  }>;
8047
8057
  usageSource?: {
8048
8058
  customerAccount: string;
8059
+ invoiceLines?: Array<{
8060
+ amount: number;
8061
+ kind: "fixed" | "metered";
8062
+ lineId: string;
8063
+ period: { end: number; start: number };
8064
+ quantity: string;
8065
+ stripePriceId: string;
8066
+ stripeProductId: string;
8067
+ subscriptionItemId: string;
8068
+ }>;
8049
8069
  invoicePaymentId: string;
8050
8070
  livemode: boolean;
8051
8071
  meterId: string;
@@ -8686,6 +8706,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8686
8706
  }>;
8687
8707
  usageSource?: {
8688
8708
  customerAccount: string;
8709
+ invoiceLines?: Array<{
8710
+ amount: number;
8711
+ kind: "fixed" | "metered";
8712
+ lineId: string;
8713
+ period: { end: number; start: number };
8714
+ quantity: string;
8715
+ stripePriceId: string;
8716
+ stripeProductId: string;
8717
+ subscriptionItemId: string;
8718
+ }>;
8689
8719
  invoicePaymentId: string;
8690
8720
  livemode: boolean;
8691
8721
  meterId: string;
@@ -8731,6 +8761,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8731
8761
  }>;
8732
8762
  usageSource?: {
8733
8763
  customerAccount: string;
8764
+ invoiceLines?: Array<{
8765
+ amount: number;
8766
+ kind: "fixed" | "metered";
8767
+ lineId: string;
8768
+ period: { end: number; start: number };
8769
+ quantity: string;
8770
+ stripePriceId: string;
8771
+ stripeProductId: string;
8772
+ subscriptionItemId: string;
8773
+ }>;
8734
8774
  invoicePaymentId: string;
8735
8775
  livemode: boolean;
8736
8776
  meterId: string;
@@ -8796,6 +8836,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8796
8836
  }>;
8797
8837
  usageSource?: {
8798
8838
  customerAccount: string;
8839
+ invoiceLines?: Array<{
8840
+ amount: number;
8841
+ kind: "fixed" | "metered";
8842
+ lineId: string;
8843
+ period: { end: number; start: number };
8844
+ quantity: string;
8845
+ stripePriceId: string;
8846
+ stripeProductId: string;
8847
+ subscriptionItemId: string;
8848
+ }>;
8799
8849
  invoicePaymentId: string;
8800
8850
  livemode: boolean;
8801
8851
  meterId: string;
@@ -1,3 +1,4 @@
1
+ import { usageInvoiceLineProof } from "../../shared/usageInvoiceLines.js";
1
2
  import { defineTable } from "convex/server";
2
3
  import { v } from "convex/values";
3
4
  import { splitRecipientRoleValidator } from "../lib/fees.js";
@@ -18,6 +19,7 @@ export const allocationFields = {
18
19
  sourceInvoiceId: v.optional(v.string()),
19
20
  usageSource: v.optional(
20
21
  v.object({
22
+ invoiceLines: v.optional(v.array(usageInvoiceLineProof)),
21
23
  stripeAccountId: v.string(),
22
24
  customerAccount: v.string(),
23
25
  livemode: v.boolean(),
@@ -0,0 +1,14 @@
1
+ import { v } from "convex/values";
2
+ import type { Infer } from "convex/values";
3
+ /** Complete, canonical native invoice provenance retained with the charge allocation. */
4
+ export const usageInvoiceLineProof = v.object({
5
+ lineId: v.string(),
6
+ stripePriceId: v.string(),
7
+ stripeProductId: v.string(),
8
+ subscriptionItemId: v.string(),
9
+ period: v.object({ start: v.number(), end: v.number() }),
10
+ amount: v.number(),
11
+ quantity: v.string(),
12
+ kind: v.union(v.literal("fixed"), v.literal("metered")),
13
+ });
14
+ export type UsageInvoiceLineProof = Infer<typeof usageInvoiceLineProof>;