@fantastic.dev/better-stripe 0.70.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 (112) hide show
  1. package/CHANGELOG.md +13 -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/readContracts.d.ts +1 -0
  19. package/dist/client/readContracts.d.ts.map +1 -1
  20. package/dist/client/readContracts.js.map +1 -1
  21. package/dist/client/settlement/authorization.fixture.d.ts +26 -0
  22. package/dist/client/settlement/authorization.fixture.d.ts.map +1 -1
  23. package/dist/client/settlement/execution.d.ts +2 -0
  24. package/dist/client/settlement/execution.d.ts.map +1 -1
  25. package/dist/client/settlement/execution.js.map +1 -1
  26. package/dist/client/usage/index.d.ts +1 -0
  27. package/dist/client/usage/index.d.ts.map +1 -1
  28. package/dist/client/usage/invoiceSale.d.ts +8 -0
  29. package/dist/client/usage/invoiceSale.d.ts.map +1 -1
  30. package/dist/client/usage/invoiceSale.js +3 -0
  31. package/dist/client/usage/invoiceSale.js.map +1 -1
  32. package/dist/client/usage/mixedInvoice.fixtures.d.ts +315 -0
  33. package/dist/client/usage/mixedInvoice.fixtures.d.ts.map +1 -0
  34. package/dist/client/usage/mixedInvoice.fixtures.js +55 -0
  35. package/dist/client/usage/mixedInvoice.fixtures.js.map +1 -0
  36. package/dist/client/usage/mixedInvoiceSale.d.ts +6 -0
  37. package/dist/client/usage/mixedInvoiceSale.d.ts.map +1 -0
  38. package/dist/client/usage/mixedInvoiceSale.js +160 -0
  39. package/dist/client/usage/mixedInvoiceSale.js.map +1 -0
  40. package/dist/client/usage/observationClient.d.ts +2 -2
  41. package/dist/client/usage/observationClient.d.ts.map +1 -1
  42. package/dist/client/usage/retainedInvoiceSource.d.ts +20 -0
  43. package/dist/client/usage/retainedInvoiceSource.d.ts.map +1 -0
  44. package/dist/client/usage/retainedInvoiceSource.js +92 -0
  45. package/dist/client/usage/retainedInvoiceSource.js.map +1 -0
  46. package/dist/client/usage/settlement.d.ts +5 -0
  47. package/dist/client/usage/settlement.d.ts.map +1 -1
  48. package/dist/client/usage/settlement.js +28 -9
  49. package/dist/client/usage/settlement.js.map +1 -1
  50. package/dist/component/_generated/component.d.ts +66 -0
  51. package/dist/component/_generated/component.d.ts.map +1 -1
  52. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  53. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  54. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  55. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  56. package/dist/component/earnings/triggers.d.ts +84 -6
  57. package/dist/component/earnings/triggers.d.ts.map +1 -1
  58. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  59. package/dist/component/products/queries.d.ts +1 -0
  60. package/dist/component/products/queries.d.ts.map +1 -1
  61. package/dist/component/products/queries.js +14 -8
  62. package/dist/component/products/queries.js.map +1 -1
  63. package/dist/component/recoveryWorkflow/helpers.d.ts +13 -0
  64. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
  65. package/dist/component/recoveryWorkflow/mutations.d.ts +13 -0
  66. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
  67. package/dist/component/recoveryWorkflow/queries.d.ts +26 -0
  68. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
  69. package/dist/component/recoveryWorkflow/schema.d.ts +464 -16
  70. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
  71. package/dist/component/schema.d.ts +246 -9
  72. package/dist/component/settlement/mutations.d.ts +26 -0
  73. package/dist/component/settlement/mutations.d.ts.map +1 -1
  74. package/dist/component/settlement/queries.d.ts +13 -0
  75. package/dist/component/settlement/queries.d.ts.map +1 -1
  76. package/dist/component/settlement/schema.d.ts +122 -3
  77. package/dist/component/settlement/schema.d.ts.map +1 -1
  78. package/dist/component/settlement/schema.js +2 -0
  79. package/dist/component/settlement/schema.js.map +1 -1
  80. package/dist/component/usage/allowance.fixtures.d.ts +262 -25
  81. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  82. package/dist/component/usageCredits/accounting.fixtures.d.ts +246 -9
  83. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  84. package/dist/shared/usageInvoiceLines.d.ts +32 -0
  85. package/dist/shared/usageInvoiceLines.d.ts.map +1 -0
  86. package/dist/shared/usageInvoiceLines.js +13 -0
  87. package/dist/shared/usageInvoiceLines.js.map +1 -0
  88. package/docs/evidence/native-metering/mixed-settlement-2026-10-20.json +284 -0
  89. package/docs/metering-setup.md +3 -2
  90. package/docs/read-contracts.md +9 -2
  91. package/docs/usage-example.md +24 -5
  92. package/docs/usage-settlement.md +74 -8
  93. package/docs/usage-verification.md +22 -2
  94. package/package.json +1 -1
  95. package/src/client/paymentSource/resolver.ts +80 -59
  96. package/src/client/processingCostReconciliation/provider.ts +20 -2
  97. package/src/client/readContracts.ts +1 -0
  98. package/src/client/readPagination.test.ts +21 -0
  99. package/src/client/settlement/execution.ts +2 -0
  100. package/src/client/usage/index.ts +2 -0
  101. package/src/client/usage/invoiceSale.ts +10 -0
  102. package/src/client/usage/mixedInvoice.fixtures.ts +54 -0
  103. package/src/client/usage/mixedInvoiceSale.test.ts +92 -0
  104. package/src/client/usage/mixedInvoiceSale.ts +196 -0
  105. package/src/client/usage/mixedSettlement.test.ts +187 -0
  106. package/src/client/usage/retainedInvoiceSource.ts +118 -0
  107. package/src/client/usage/settlement.ts +47 -9
  108. package/src/component/_generated/component.ts +51 -0
  109. package/src/component/products/provider-price-pagination.test.ts +174 -0
  110. package/src/component/products/queries.ts +24 -10
  111. package/src/component/settlement/schema.ts +2 -0
  112. 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
  }
@@ -7752,6 +7752,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7752
7752
  numItems: number;
7753
7753
  };
7754
7754
  productId?: string;
7755
+ stripeProductId?: string;
7755
7756
  },
7756
7757
  {
7757
7758
  continueCursor: string;
@@ -7913,6 +7914,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7913
7914
  }>;
7914
7915
  usageSource?: {
7915
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
+ }>;
7916
7927
  invoicePaymentId: string;
7917
7928
  livemode: boolean;
7918
7929
  meterId: string;
@@ -8045,6 +8056,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8045
8056
  }>;
8046
8057
  usageSource?: {
8047
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
+ }>;
8048
8069
  invoicePaymentId: string;
8049
8070
  livemode: boolean;
8050
8071
  meterId: string;
@@ -8685,6 +8706,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8685
8706
  }>;
8686
8707
  usageSource?: {
8687
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
+ }>;
8688
8719
  invoicePaymentId: string;
8689
8720
  livemode: boolean;
8690
8721
  meterId: string;
@@ -8730,6 +8761,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8730
8761
  }>;
8731
8762
  usageSource?: {
8732
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
+ }>;
8733
8774
  invoicePaymentId: string;
8734
8775
  livemode: boolean;
8735
8776
  meterId: string;
@@ -8795,6 +8836,16 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8795
8836
  }>;
8796
8837
  usageSource?: {
8797
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
+ }>;
8798
8849
  invoicePaymentId: string;
8799
8850
  livemode: boolean;
8800
8851
  meterId: string;
@@ -0,0 +1,174 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import {
4
+ makeFunctionReference,
5
+ type PaginationOptions,
6
+ type PaginationResult,
7
+ } from "convex/server";
8
+ import { expect, it } from "vitest";
9
+ import { schema, modules } from "../../test.js";
10
+ import { api } from "../_generated/api.js";
11
+ import type { Doc } from "../_generated/dataModel.js";
12
+
13
+ // Explicit desired public contract also exercises the old validator before codegen.
14
+ const providerPage = makeFunctionReference<
15
+ "query",
16
+ {
17
+ stripeProductId: string;
18
+ productId?: string;
19
+ active?: boolean;
20
+ paginationOpts: PaginationOptions;
21
+ },
22
+ PaginationResult<Doc<"prices">>
23
+ >("products/queries:paginatePrices");
24
+
25
+ function price(i: number, extra: Partial<Doc<"prices">> = {}) {
26
+ return {
27
+ stripePriceId: `price_${i}`,
28
+ productId: "component_selected",
29
+ stripeProductId: "prod_selected",
30
+ unitAmount: i,
31
+ currency: "usd",
32
+ type: "one_time" as const,
33
+ active: true,
34
+ ...extra,
35
+ };
36
+ }
37
+
38
+ it("pages the provider index completely, including inactive and contradictory component links", async () => {
39
+ const t = convexTest(schema, modules);
40
+ for (let i = 0; i < 101; i++)
41
+ await t.mutation(
42
+ api.products.mutations.upsertPrice,
43
+ price(i, {
44
+ active: i !== 50,
45
+ productId: i === 60 ? "component_foreign" : "component_selected",
46
+ }),
47
+ );
48
+ for (let i = 101; i < 222; i++)
49
+ await t.mutation(
50
+ api.products.mutations.upsertPrice,
51
+ price(i, { stripeProductId: "prod_foreign" }),
52
+ );
53
+ const first = await t.query(providerPage, {
54
+ stripeProductId: "prod_selected",
55
+ paginationOpts: { numItems: 100, cursor: null },
56
+ });
57
+ expect(first.page).toHaveLength(100);
58
+ expect(first.isDone).toBe(false);
59
+ const second = await t.query(providerPage, {
60
+ stripeProductId: "prod_selected",
61
+ paginationOpts: { numItems: 100, cursor: first.continueCursor },
62
+ });
63
+ expect(second.page).toHaveLength(1);
64
+ expect(second.isDone).toBe(true);
65
+ const rows = [...first.page, ...second.page];
66
+ expect(rows.map((row) => row.stripePriceId)).toEqual(
67
+ Array.from({ length: 101 }, (_, i) => `price_${100 - i}`),
68
+ );
69
+ expect(new Set(rows.map((row) => row._id)).size).toBe(101);
70
+ expect(rows.find((row) => row.stripePriceId === "price_50")?.active).toBe(
71
+ false,
72
+ );
73
+ expect(rows.find((row) => row.stripePriceId === "price_60")?.productId).toBe(
74
+ "component_foreign",
75
+ );
76
+ const component = await t.query(api.products.queries.paginatePrices, {
77
+ productId: "component_selected",
78
+ paginationOpts: { numItems: 100, cursor: null },
79
+ });
80
+ expect(
81
+ component.page.some((row) => row.stripeProductId === "prod_foreign"),
82
+ ).toBe(true);
83
+ expect(
84
+ await t.query(providerPage, {
85
+ stripeProductId: "missing",
86
+ paginationOpts: { numItems: 10, cursor: null },
87
+ }),
88
+ ).toMatchObject({ page: [], isDone: true });
89
+ });
90
+
91
+ it("rejects mixed selectors and either explicit active value", async () => {
92
+ const t = convexTest(schema, modules);
93
+ for (const extra of [
94
+ { productId: "component_selected" },
95
+ { active: true },
96
+ { active: false },
97
+ ])
98
+ await expect(
99
+ t.query(providerPage, {
100
+ stripeProductId: "prod_selected",
101
+ ...extra,
102
+ paginationOpts: { numItems: 10, cursor: null },
103
+ }),
104
+ ).rejects.toThrow("stripeProductId cannot be combined");
105
+ });
106
+
107
+ it("retains provider page size validation", async () => {
108
+ const t = convexTest(schema, modules);
109
+ for (const numItems of [0, -1, 101, 1.5])
110
+ await expect(
111
+ t.query(providerPage, {
112
+ stripeProductId: "prod_selected",
113
+ paginationOpts: { numItems, cursor: null },
114
+ }),
115
+ ).rejects.toThrow("Page size");
116
+ });
117
+
118
+ it("preserves pinned provider boundaries and native split hints", async () => {
119
+ const t = convexTest(schema, modules);
120
+ for (let i = 0; i < 20; i++)
121
+ await t.mutation(api.products.mutations.upsertPrice, price(i));
122
+ const first = await t.query(providerPage, {
123
+ stripeProductId: "prod_selected",
124
+ paginationOpts: { numItems: 10, cursor: null },
125
+ });
126
+ const second = await t.query(providerPage, {
127
+ stripeProductId: "prod_selected",
128
+ paginationOpts: { numItems: 10, cursor: first.continueCursor },
129
+ });
130
+ await t.mutation(api.products.mutations.upsertPrice, price(20));
131
+ const pinned = await t.query(providerPage, {
132
+ stripeProductId: "prod_selected",
133
+ paginationOpts: {
134
+ numItems: 10,
135
+ cursor: null,
136
+ endCursor: first.continueCursor,
137
+ },
138
+ });
139
+ expect(pinned.page).toHaveLength(11);
140
+ expect(
141
+ new Set([...pinned.page, ...second.page].map((row) => row._id)).size,
142
+ ).toBe(21);
143
+ for (let i = 21; i < 241; i++)
144
+ await t.mutation(api.products.mutations.upsertPrice, price(i));
145
+ const grown = await t.query(providerPage, {
146
+ stripeProductId: "prod_selected",
147
+ paginationOpts: {
148
+ numItems: 10,
149
+ cursor: null,
150
+ endCursor: first.continueCursor,
151
+ },
152
+ });
153
+ expect(grown.page).toHaveLength(200);
154
+ expect(grown.pageStatus).toBe("SplitRequired");
155
+ expect(grown.splitCursor).toBeTruthy();
156
+ });
157
+
158
+ it("preserves the native full hundred-row boundary and empty terminal continuation", async () => {
159
+ const t = convexTest(schema, modules);
160
+ for (let i = 0; i < 100; i++)
161
+ await t.mutation(api.products.mutations.upsertPrice, price(i));
162
+ const page = await t.query(providerPage, {
163
+ stripeProductId: "prod_selected",
164
+ paginationOpts: { numItems: 100, cursor: null },
165
+ });
166
+ expect(page.page).toHaveLength(100);
167
+ expect(page.isDone).toBe(false);
168
+ const terminal = await t.query(providerPage, {
169
+ stripeProductId: "prod_selected",
170
+ paginationOpts: { numItems: 100, cursor: page.continueCursor },
171
+ });
172
+ expect(terminal.page).toEqual([]);
173
+ expect(terminal.isDone).toBe(true);
174
+ });
@@ -191,6 +191,7 @@ export const paginateProducts = query({
191
191
  export const paginatePrices = query({
192
192
  args: {
193
193
  productId: v.optional(v.string()),
194
+ stripeProductId: v.optional(v.string()),
194
195
  active: v.optional(v.boolean()),
195
196
  paginationOpts: paginationOptsValidator,
196
197
  },
@@ -202,18 +203,31 @@ export const paginatePrices = query({
202
203
  args.paginationOpts.numItems > 100
203
204
  )
204
205
  throw new Error("Page size must be an integer from 1 to 100");
205
- const { productId, active } = args;
206
+ const { productId, stripeProductId, active } = args;
207
+ if (
208
+ stripeProductId !== undefined &&
209
+ (productId !== undefined || active !== undefined)
210
+ )
211
+ throw new Error(
212
+ "stripeProductId cannot be combined with productId or active",
213
+ );
206
214
  const rows = paginator(ctx.db, schema).query("prices");
207
215
  const scoped =
208
- productId !== undefined
209
- ? active !== undefined
210
- ? rows.withIndex("by_product_active", (q) =>
211
- q.eq("productId", productId).eq("active", active),
212
- )
213
- : rows.withIndex("by_product_id", (q) => q.eq("productId", productId))
214
- : active !== undefined
215
- ? rows.withIndex("by_active", (q) => q.eq("active", active))
216
- : rows;
216
+ stripeProductId !== undefined
217
+ ? rows.withIndex("by_stripe_product_id", (q) =>
218
+ q.eq("stripeProductId", stripeProductId),
219
+ )
220
+ : productId !== undefined
221
+ ? active !== undefined
222
+ ? rows.withIndex("by_product_active", (q) =>
223
+ q.eq("productId", productId).eq("active", active),
224
+ )
225
+ : rows.withIndex("by_product_id", (q) =>
226
+ q.eq("productId", productId),
227
+ )
228
+ : active !== undefined
229
+ ? rows.withIndex("by_active", (q) => q.eq("active", active))
230
+ : rows;
217
231
  return scoped.order("desc").paginate({
218
232
  ...args.paginationOpts,
219
233
  maximumRowsRead: 200,
@@ -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>;