@fantastic.dev/better-stripe 0.59.0 → 0.60.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 (124) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +3 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +650 -44
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +309 -6
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +618 -12
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +325 -22
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +4 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/paymentSource/resolver.d.ts +12 -1
  14. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  15. package/dist/client/paymentSource/resolver.fixtures.d.ts +220 -0
  16. package/dist/client/paymentSource/resolver.fixtures.d.ts.map +1 -0
  17. package/dist/client/paymentSource/resolver.fixtures.js +189 -0
  18. package/dist/client/paymentSource/resolver.fixtures.js.map +1 -0
  19. package/dist/client/paymentSource/resolver.js +28 -3
  20. package/dist/client/paymentSource/resolver.js.map +1 -1
  21. package/dist/client/settlement/execution.d.ts +25 -0
  22. package/dist/client/settlement/execution.d.ts.map +1 -1
  23. package/dist/client/settlement/execution.js +2 -0
  24. package/dist/client/settlement/execution.js.map +1 -1
  25. package/dist/client/usage/catalogPrices.d.ts +1 -1
  26. package/dist/client/usage/catalogPrices.d.ts.map +1 -1
  27. package/dist/client/usage/catalogPrices.js +4 -4
  28. package/dist/client/usage/catalogPrices.js.map +1 -1
  29. package/dist/client/usage/client.d.ts +2 -2
  30. package/dist/client/usage/client.js +2 -2
  31. package/dist/client/usage/creditRevenue.d.ts +22 -0
  32. package/dist/client/usage/creditRevenue.d.ts.map +1 -0
  33. package/dist/client/usage/creditRevenue.js +118 -0
  34. package/dist/client/usage/creditRevenue.js.map +1 -0
  35. package/dist/client/usage/creditSettlement.d.ts +29 -0
  36. package/dist/client/usage/creditSettlement.d.ts.map +1 -0
  37. package/dist/client/usage/creditSettlement.fixtures.d.ts +215 -0
  38. package/dist/client/usage/creditSettlement.fixtures.d.ts.map +1 -0
  39. package/dist/client/usage/creditSettlement.fixtures.js +59 -0
  40. package/dist/client/usage/creditSettlement.fixtures.js.map +1 -0
  41. package/dist/client/usage/creditSettlement.js +70 -0
  42. package/dist/client/usage/creditSettlement.js.map +1 -0
  43. package/dist/client/usage/creditTransport.fixtures.d.ts +7 -1
  44. package/dist/client/usage/creditTransport.fixtures.d.ts.map +1 -1
  45. package/dist/client/usage/creditTransport.fixtures.js +25 -4
  46. package/dist/client/usage/creditTransport.fixtures.js.map +1 -1
  47. package/dist/client/usage/index.d.ts +4 -0
  48. package/dist/client/usage/index.d.ts.map +1 -1
  49. package/dist/client/usage/invoiceSale.d.ts +22 -0
  50. package/dist/client/usage/invoiceSale.d.ts.map +1 -0
  51. package/dist/client/usage/invoiceSale.fixtures.d.ts +285 -0
  52. package/dist/client/usage/invoiceSale.fixtures.d.ts.map +1 -0
  53. package/dist/client/usage/invoiceSale.fixtures.js +104 -0
  54. package/dist/client/usage/invoiceSale.fixtures.js.map +1 -0
  55. package/dist/client/usage/invoiceSale.js +117 -0
  56. package/dist/client/usage/invoiceSale.js.map +1 -0
  57. package/dist/client/usage/observationClient.d.ts +2 -2
  58. package/dist/client/usage/observationClient.d.ts.map +1 -1
  59. package/dist/client/usage/settlement.d.ts +32 -0
  60. package/dist/client/usage/settlement.d.ts.map +1 -0
  61. package/dist/client/usage/settlement.js +60 -0
  62. package/dist/client/usage/settlement.js.map +1 -0
  63. package/dist/client/usage/settlementClient.d.ts +51 -0
  64. package/dist/client/usage/settlementClient.d.ts.map +1 -0
  65. package/dist/client/usage/settlementClient.js +35 -0
  66. package/dist/client/usage/settlementClient.js.map +1 -0
  67. package/dist/component/_generated/component.d.ts +125 -0
  68. package/dist/component/_generated/component.d.ts.map +1 -1
  69. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  70. package/dist/component/balanceFunding/mutations.d.ts +27 -27
  71. package/dist/component/earnings/triggers.d.ts +156 -6
  72. package/dist/component/earnings/triggers.d.ts.map +1 -1
  73. package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -1
  74. package/dist/component/financialObservations/settlementHelpers.js +2 -0
  75. package/dist/component/financialObservations/settlementHelpers.js.map +1 -1
  76. package/dist/component/recoveryWorkflow/helpers.d.ts +25 -0
  77. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
  78. package/dist/component/recoveryWorkflow/mutations.d.ts +25 -0
  79. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
  80. package/dist/component/recoveryWorkflow/queries.d.ts +50 -0
  81. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
  82. package/dist/component/recoveryWorkflow/schema.d.ts +566 -10
  83. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
  84. package/dist/component/schema.d.ts +309 -6
  85. package/dist/component/settlement/mutations.d.ts +50 -0
  86. package/dist/component/settlement/mutations.d.ts.map +1 -1
  87. package/dist/component/settlement/mutations.js +8 -1
  88. package/dist/component/settlement/mutations.js.map +1 -1
  89. package/dist/component/settlement/queries.d.ts +25 -0
  90. package/dist/component/settlement/queries.d.ts.map +1 -1
  91. package/dist/component/settlement/schema.d.ts +128 -1
  92. package/dist/component/settlement/schema.d.ts.map +1 -1
  93. package/dist/component/settlement/schema.js +22 -0
  94. package/dist/component/settlement/schema.js.map +1 -1
  95. package/docs/README.md +2 -0
  96. package/docs/settlement.md +4 -0
  97. package/docs/usage-settlement.md +162 -0
  98. package/package.json +2 -1
  99. package/src/client/index.ts +9 -0
  100. package/src/client/paymentSource/resolver.fixtures.ts +216 -0
  101. package/src/client/paymentSource/resolver.test.ts +11 -207
  102. package/src/client/paymentSource/resolver.ts +54 -2
  103. package/src/client/settlement/execution.ts +24 -0
  104. package/src/client/usage/catalogPrices.ts +4 -2
  105. package/src/client/usage/client.ts +2 -2
  106. package/src/client/usage/creditRevenue.test.ts +105 -0
  107. package/src/client/usage/creditRevenue.ts +163 -0
  108. package/src/client/usage/creditSettlement.fixtures.ts +70 -0
  109. package/src/client/usage/creditSettlement.test.ts +66 -0
  110. package/src/client/usage/creditSettlement.ts +94 -0
  111. package/src/client/usage/creditSettlementRecovery.test.ts +173 -0
  112. package/src/client/usage/creditTransport.fixtures.ts +29 -4
  113. package/src/client/usage/index.ts +9 -0
  114. package/src/client/usage/invoiceSale.fixtures.ts +103 -0
  115. package/src/client/usage/invoiceSale.test.ts +184 -0
  116. package/src/client/usage/invoiceSale.ts +155 -0
  117. package/src/client/usage/settlement.test.ts +179 -0
  118. package/src/client/usage/settlement.ts +81 -0
  119. package/src/client/usage/settlementClient.ts +84 -0
  120. package/src/component/_generated/component.ts +110 -0
  121. package/src/component/financialObservations/settlementHelpers.ts +2 -0
  122. package/src/component/settlement/mutations.ts +10 -1
  123. package/src/component/settlement/schema.ts +26 -0
  124. package/src/component/settlement/settlement-claims.test.ts +54 -0
@@ -4,6 +4,15 @@ export declare const getSettlementAllocation: import("convex/server").Registered
4
4
  _creationTime: number;
5
5
  _id: import("convex/values").GenericId<"settlementAllocations">;
6
6
  adjustmentAmount?: number | undefined;
7
+ creditSource?: {
8
+ creditGrantId: string;
9
+ customerAccount: string;
10
+ livemode: boolean;
11
+ purchaseId: string;
12
+ stripeAccountId: string;
13
+ stripePriceId: string;
14
+ stripeProductId: string;
15
+ } | undefined;
7
16
  currency: string;
8
17
  gross: number;
9
18
  paymentId?: string | undefined;
@@ -17,6 +26,22 @@ export declare const getSettlementAllocation: import("convex/server").Registered
17
26
  destinationAccountId: string;
18
27
  role: "affiliate" | "other" | "store";
19
28
  }[];
29
+ usageSource?: {
30
+ customerAccount: string;
31
+ invoicePaymentId: string;
32
+ livemode: boolean;
33
+ meterId: string;
34
+ model: "included_overage" | "pay_as_you_go";
35
+ period: {
36
+ end: number;
37
+ start: number;
38
+ };
39
+ stripeAccountId: string;
40
+ stripePriceId: string;
41
+ stripeProductId: string;
42
+ subscriptionId: string;
43
+ subscriptionItemId: string;
44
+ } | undefined;
20
45
  } | null>>;
21
46
  export declare const getCommissionTerm: import("convex/server").RegisteredQuery<"public", {
22
47
  subscriptionId: string;
@@ -1 +1 @@
1
- {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/settlement/queries.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;UAUlC,CAAC;AACH,eAAO,MAAM,iBAAiB;;;;;;;UAkB5B,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyBnC,CAAC"}
1
+ {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/settlement/queries.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAUlC,CAAC;AACH,eAAO,MAAM,iBAAiB;;;;;;;UAkB5B,CAAC;AAEH,iFAAiF;AACjF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAyBnC,CAAC"}
@@ -3,6 +3,57 @@ export declare const allocationFields: {
3
3
  sourceChargeId: import("convex/values").VString<string, "required">;
4
4
  paymentIntentId: import("convex/values").VString<string | undefined, "optional">;
5
5
  sourceInvoiceId: import("convex/values").VString<string | undefined, "optional">;
6
+ usageSource: import("convex/values").VObject<{
7
+ customerAccount: string;
8
+ invoicePaymentId: string;
9
+ livemode: boolean;
10
+ meterId: string;
11
+ model: "included_overage" | "pay_as_you_go";
12
+ period: {
13
+ end: number;
14
+ start: number;
15
+ };
16
+ stripeAccountId: string;
17
+ stripePriceId: string;
18
+ stripeProductId: string;
19
+ subscriptionId: string;
20
+ subscriptionItemId: string;
21
+ } | undefined, {
22
+ stripeAccountId: import("convex/values").VString<string, "required">;
23
+ customerAccount: import("convex/values").VString<string, "required">;
24
+ livemode: import("convex/values").VBoolean<boolean, "required">;
25
+ meterId: import("convex/values").VString<string, "required">;
26
+ stripePriceId: import("convex/values").VString<string, "required">;
27
+ stripeProductId: import("convex/values").VString<string, "required">;
28
+ subscriptionId: import("convex/values").VString<string, "required">;
29
+ subscriptionItemId: import("convex/values").VString<string, "required">;
30
+ invoicePaymentId: import("convex/values").VString<string, "required">;
31
+ period: import("convex/values").VObject<{
32
+ end: number;
33
+ start: number;
34
+ }, {
35
+ start: import("convex/values").VFloat64<number, "required">;
36
+ end: import("convex/values").VFloat64<number, "required">;
37
+ }, "required", "end" | "start">;
38
+ model: import("convex/values").VUnion<"included_overage" | "pay_as_you_go", [import("convex/values").VLiteral<"pay_as_you_go", "required">, import("convex/values").VLiteral<"included_overage", "required">], "required", never>;
39
+ }, "optional", "customerAccount" | "invoicePaymentId" | "livemode" | "meterId" | "model" | "period" | "period.end" | "period.start" | "stripeAccountId" | "stripePriceId" | "stripeProductId" | "subscriptionId" | "subscriptionItemId">;
40
+ creditSource: import("convex/values").VObject<{
41
+ creditGrantId: string;
42
+ customerAccount: string;
43
+ livemode: boolean;
44
+ purchaseId: string;
45
+ stripeAccountId: string;
46
+ stripePriceId: string;
47
+ stripeProductId: string;
48
+ } | undefined, {
49
+ stripeAccountId: import("convex/values").VString<string, "required">;
50
+ customerAccount: import("convex/values").VString<string, "required">;
51
+ livemode: import("convex/values").VBoolean<boolean, "required">;
52
+ purchaseId: import("convex/values").VString<string, "required">;
53
+ creditGrantId: import("convex/values").VString<string, "required">;
54
+ stripePriceId: import("convex/values").VString<string, "required">;
55
+ stripeProductId: import("convex/values").VString<string, "required">;
56
+ }, "optional", "creditGrantId" | "customerAccount" | "livemode" | "purchaseId" | "stripeAccountId" | "stripePriceId" | "stripeProductId">;
6
57
  gross: import("convex/values").VFloat64<number, "required">;
7
58
  currency: import("convex/values").VString<string, "required">;
8
59
  processingFee: import("convex/values").VFloat64<number, "required">;
@@ -25,6 +76,15 @@ export declare const allocationFields: {
25
76
  };
26
77
  export declare const allocationsTable: import("convex/server").TableDefinition<import("convex/values").VObject<{
27
78
  adjustmentAmount?: number | undefined;
79
+ creditSource?: {
80
+ creditGrantId: string;
81
+ customerAccount: string;
82
+ livemode: boolean;
83
+ purchaseId: string;
84
+ stripeAccountId: string;
85
+ stripePriceId: string;
86
+ stripeProductId: string;
87
+ } | undefined;
28
88
  currency: string;
29
89
  gross: number;
30
90
  paymentId?: string | undefined;
@@ -38,10 +98,77 @@ export declare const allocationsTable: import("convex/server").TableDefinition<i
38
98
  destinationAccountId: string;
39
99
  role: "affiliate" | "other" | "store";
40
100
  }[];
101
+ usageSource?: {
102
+ customerAccount: string;
103
+ invoicePaymentId: string;
104
+ livemode: boolean;
105
+ meterId: string;
106
+ model: "included_overage" | "pay_as_you_go";
107
+ period: {
108
+ end: number;
109
+ start: number;
110
+ };
111
+ stripeAccountId: string;
112
+ stripePriceId: string;
113
+ stripeProductId: string;
114
+ subscriptionId: string;
115
+ subscriptionItemId: string;
116
+ } | undefined;
41
117
  }, {
42
118
  sourceChargeId: import("convex/values").VString<string, "required">;
43
119
  paymentIntentId: import("convex/values").VString<string | undefined, "optional">;
44
120
  sourceInvoiceId: import("convex/values").VString<string | undefined, "optional">;
121
+ usageSource: import("convex/values").VObject<{
122
+ customerAccount: string;
123
+ invoicePaymentId: string;
124
+ livemode: boolean;
125
+ meterId: string;
126
+ model: "included_overage" | "pay_as_you_go";
127
+ period: {
128
+ end: number;
129
+ start: number;
130
+ };
131
+ stripeAccountId: string;
132
+ stripePriceId: string;
133
+ stripeProductId: string;
134
+ subscriptionId: string;
135
+ subscriptionItemId: string;
136
+ } | undefined, {
137
+ stripeAccountId: import("convex/values").VString<string, "required">;
138
+ customerAccount: import("convex/values").VString<string, "required">;
139
+ livemode: import("convex/values").VBoolean<boolean, "required">;
140
+ meterId: import("convex/values").VString<string, "required">;
141
+ stripePriceId: import("convex/values").VString<string, "required">;
142
+ stripeProductId: import("convex/values").VString<string, "required">;
143
+ subscriptionId: import("convex/values").VString<string, "required">;
144
+ subscriptionItemId: import("convex/values").VString<string, "required">;
145
+ invoicePaymentId: import("convex/values").VString<string, "required">;
146
+ period: import("convex/values").VObject<{
147
+ end: number;
148
+ start: number;
149
+ }, {
150
+ start: import("convex/values").VFloat64<number, "required">;
151
+ end: import("convex/values").VFloat64<number, "required">;
152
+ }, "required", "end" | "start">;
153
+ model: import("convex/values").VUnion<"included_overage" | "pay_as_you_go", [import("convex/values").VLiteral<"pay_as_you_go", "required">, import("convex/values").VLiteral<"included_overage", "required">], "required", never>;
154
+ }, "optional", "customerAccount" | "invoicePaymentId" | "livemode" | "meterId" | "model" | "period" | "period.end" | "period.start" | "stripeAccountId" | "stripePriceId" | "stripeProductId" | "subscriptionId" | "subscriptionItemId">;
155
+ creditSource: import("convex/values").VObject<{
156
+ creditGrantId: string;
157
+ customerAccount: string;
158
+ livemode: boolean;
159
+ purchaseId: string;
160
+ stripeAccountId: string;
161
+ stripePriceId: string;
162
+ stripeProductId: string;
163
+ } | undefined, {
164
+ stripeAccountId: import("convex/values").VString<string, "required">;
165
+ customerAccount: import("convex/values").VString<string, "required">;
166
+ livemode: import("convex/values").VBoolean<boolean, "required">;
167
+ purchaseId: import("convex/values").VString<string, "required">;
168
+ creditGrantId: import("convex/values").VString<string, "required">;
169
+ stripePriceId: import("convex/values").VString<string, "required">;
170
+ stripeProductId: import("convex/values").VString<string, "required">;
171
+ }, "optional", "creditGrantId" | "customerAccount" | "livemode" | "purchaseId" | "stripeAccountId" | "stripePriceId" | "stripeProductId">;
45
172
  gross: import("convex/values").VFloat64<number, "required">;
46
173
  currency: import("convex/values").VString<string, "required">;
47
174
  processingFee: import("convex/values").VFloat64<number, "required">;
@@ -61,7 +188,7 @@ export declare const allocationsTable: import("convex/server").TableDefinition<i
61
188
  role: import("convex/values").VUnion<"affiliate" | "other" | "store", [import("convex/values").VLiteral<"store", "required">, import("convex/values").VLiteral<"affiliate", "required">, import("convex/values").VLiteral<"other", "required">], "required", never>;
62
189
  amount: import("convex/values").VFloat64<number, "required">;
63
190
  }, "required", "amount" | "destinationAccountId" | "role">, "required">;
64
- }, "required", "adjustmentAmount" | "currency" | "gross" | "paymentId" | "paymentIntentId" | "platformNet" | "processingFee" | "sourceChargeId" | "sourceInvoiceId" | "transfers">, {
191
+ }, "required", "adjustmentAmount" | "creditSource" | "creditSource.creditGrantId" | "creditSource.customerAccount" | "creditSource.livemode" | "creditSource.purchaseId" | "creditSource.stripeAccountId" | "creditSource.stripePriceId" | "creditSource.stripeProductId" | "currency" | "gross" | "paymentId" | "paymentIntentId" | "platformNet" | "processingFee" | "sourceChargeId" | "sourceInvoiceId" | "transfers" | "usageSource" | "usageSource.customerAccount" | "usageSource.invoicePaymentId" | "usageSource.livemode" | "usageSource.meterId" | "usageSource.model" | "usageSource.period" | "usageSource.period.end" | "usageSource.period.start" | "usageSource.stripeAccountId" | "usageSource.stripePriceId" | "usageSource.stripeProductId" | "usageSource.subscriptionId" | "usageSource.subscriptionItemId">, {
65
192
  by_source_charge: ["sourceChargeId", "_creationTime"];
66
193
  }, {}, {}>;
67
194
  export declare const commissionFields: {
@@ -1 +1 @@
1
- {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/component/settlement/schema.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,gMAGzB,CAAC;AACF,eAAO,MAAM,gBAAgB;IAC3B,cAAc;IACd,eAAe;IACf,eAAe;IACf,KAAK;IACL,QAAQ;IACR,aAAa;IACb,WAAW;IACX,gBAAgB;IAChB,SAAS;IACT,SAAS;;;;;;;;;;;;;CAOV,CAAC;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAG5B,CAAC;AACF,eAAO,MAAM,gBAAgB;IAC3B,cAAc;IACd,IAAI;IACJ,kBAAkB;IAClB,kBAAkB;CACnB,CAAC;AACF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;UAGhC,CAAC;AACF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;UAK+B,CAAC"}
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/component/settlement/schema.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,aAAa,gMAGzB,CAAC;AACF,eAAO,MAAM,gBAAgB;IAC3B,cAAc;IACd,eAAe;IACf,eAAe;IACf,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAeX,YAAY;;;;;;;;;;;;;;;;;IAWZ,KAAK;IACL,QAAQ;IACR,aAAa;IACb,WAAW;IACX,gBAAgB;IAChB,SAAS;IACT,SAAS;;;;;;;;;;;;;CAOV,CAAC;AACF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAG5B,CAAC;AACF,eAAO,MAAM,gBAAgB;IAC3B,cAAc;IACd,IAAI;IACJ,kBAAkB;IAClB,kBAAkB;CACnB,CAAC;AACF,eAAO,MAAM,oBAAoB;;;;;;;;;;;;UAGhC,CAAC;AACF,eAAO,MAAM,wBAAwB;;;;;;;;;;;;UAK+B,CAAC"}
@@ -6,6 +6,28 @@ export const allocationFields = {
6
6
  sourceChargeId: v.string(),
7
7
  paymentIntentId: v.optional(v.string()),
8
8
  sourceInvoiceId: v.optional(v.string()),
9
+ usageSource: v.optional(v.object({
10
+ stripeAccountId: v.string(),
11
+ customerAccount: v.string(),
12
+ livemode: v.boolean(),
13
+ meterId: v.string(),
14
+ stripePriceId: v.string(),
15
+ stripeProductId: v.string(),
16
+ subscriptionId: v.string(),
17
+ subscriptionItemId: v.string(),
18
+ invoicePaymentId: v.string(),
19
+ period: v.object({ start: v.number(), end: v.number() }),
20
+ model: v.union(v.literal("pay_as_you_go"), v.literal("included_overage")),
21
+ })),
22
+ creditSource: v.optional(v.object({
23
+ stripeAccountId: v.string(),
24
+ customerAccount: v.string(),
25
+ livemode: v.boolean(),
26
+ purchaseId: v.string(),
27
+ creditGrantId: v.string(),
28
+ stripePriceId: v.string(),
29
+ stripeProductId: v.string(),
30
+ })),
9
31
  gross: v.number(),
10
32
  currency: v.string(),
11
33
  processingFee: v.number(),
@@ -1 +1 @@
1
- {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/component/settlement/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAC7D,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAClC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,EACpB,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CACtB,CAAC;AACF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvC,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACvC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;IACzB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,gBAAgB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACxC,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IACjC,SAAS,EAAE,CAAC,CAAC,KAAK,CAChB,CAAC,CAAC,MAAM,CAAC;QACP,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE;QAChC,IAAI,EAAE,2BAA2B;QACjC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;KACnB,CAAC,CACH;CACF,CAAC;AACF,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC,KAAK,CACjE,kBAAkB,EAClB,CAAC,gBAAgB,CAAC,CACnB,CAAC;AACF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,IAAI,EAAE,aAAa;IACnB,kBAAkB,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1C,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE;CAC/B,CAAC;AACF,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAC,gBAAgB,CAAC,CAAC,KAAK,CACrE,iBAAiB,EACjB,CAAC,gBAAgB,CAAC,CACnB,CAAC;AACF,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;IAClD,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE;IAC1B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;CACrB,CAAC,CAAC,KAAK,CAAC,yBAAyB,EAAE,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC,CAAC"}
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/component/settlement/schema.ts"],"names":[],"mappings":"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"}
package/docs/README.md CHANGED
@@ -72,3 +72,5 @@ Start with the [native Stripe setup guide](metering-setup.md), then read the
72
72
  - [Included usage and limits](./usage-limits.md) covers atomic caps, reservations, period resets and exact overage estimates.
73
73
 
74
74
  - [Usage corrections](./usage-corrections.md) covers native cancellation, quantity restoration and verified invoice adjustments.
75
+
76
+ - [Native usage settlement](./usage-settlement.md) covers original paid invoices, issuer-service credit purchases and affiliate recovery.
@@ -985,3 +985,7 @@ The example's worker and preview adapters do this automatically. Old unattempted
985
985
  claims are canceled on replay, rather than retroactively supplied with a guessed
986
986
  quote. Restart obsolete read-only collections after upgrading their fingerprint
987
987
  format; never clear unresolved financial claims to bypass validation.
988
+
989
+ ## Native metered and prepaid sales
990
+
991
+ Use the [usage settlement guide](usage-settlement.md) for original metered-invoice provenance and issuer-service paid-credit purchases. The usage facade reuses the existing allocation, transfer and recovery ledgers and keeps usage consumption separate from cash settlement.
@@ -0,0 +1,162 @@
1
+ # Native usage revenue and settlement
2
+
3
+ Usage, allowance estimates and prepaid consumption are quantity accounting.
4
+ Settle only a verified original cash payment. These methods reuse BetterStripe's
5
+ existing allocation, transfer, refund/dispute, processing-cost and affiliate
6
+ recovery contracts. They require the existing Stripe credentials; no Metronome
7
+ account is needed.
8
+
9
+ ## Authorize the original sale
10
+
11
+ Authenticate the caller on your server. Resolve the complete Stripe realm, mode,
12
+ Accounts v2 payer, mapped Customer, original meter, subscription item, price and
13
+ billing period from your trusted records. Authorize the native product's seller,
14
+ affiliate and fee settings before applying them. Browser input, current
15
+ subscription prices and Stripe metadata do not establish ownership.
16
+
17
+ Pass runtime credentials only to the provider options. The package pins the
18
+ original binding's API version, uses a 15-second HTTP timeout and disables SDK
19
+ network retries. It sends no connected-account header: the configured key must
20
+ own the requested realm. Use the ordinary direct billing read when you only need
21
+ revenue evidence. Creating recipient transfers additionally requires a supported
22
+ Stripe Connect separate-charges-and-transfers configuration.
23
+
24
+ ## Pay as you go and included overages
25
+
26
+ ```ts
27
+ const original = {
28
+ scope, // Server-authorized realm, payer, meter and mode
29
+ binding, // Immutable plan, API version and native price/customer binding
30
+ subscription, // Original subscription/item/price and monthly period
31
+ period: subscription.period,
32
+ invoiceId,
33
+ paymentIntentId,
34
+ gross, // Expected paid amount in integer minor currency units
35
+ };
36
+ const provider = { stripeSecretKey: process.env.STRIPE_SECRET_KEY };
37
+ const source = await stripe.usage.getInvoiceSale(ctx, original, provider);
38
+ if (source.status !== "ready") return source;
39
+ // Authorize source.value.stripeProductId and all recipient policy on the server.
40
+ return stripe.usage.settleInvoice(
41
+ ctx,
42
+ {
43
+ ...original,
44
+ policy: {
45
+ creatorAccountId: authorizedSellerAccount,
46
+ feeBasisPoints: authorizedFeeBasisPoints,
47
+ affiliate: authorizedAffiliate, // Omit when no affiliate applies
48
+ commissionTerm: "one_time", // Or "forever"; default is forever
49
+ collaborators: authorizedCollaborators,
50
+ },
51
+ },
52
+ provider,
53
+ );
54
+ ```
55
+
56
+ `getInvoiceSale` is read-only. It verifies the realm/mode, payer mapping, native
57
+ sum meter, immutable native price and original finalized invoice line. Complete
58
+ bidirectional InvoicePayment history must link exactly one full PaymentIntent
59
+ payment to the invoice. The original Charge and BalanceTransaction must reconcile
60
+ gross, actual processing fee, currency and net. The returned source retains the
61
+ original product/price, meter, subscription/item, period and InvoicePayment ID;
62
+ it never substitutes the current subscription's price. Exact native decimal
63
+ quantities are checked without converting them to JavaScript floating point.
64
+ An archived original price remains valid for historical settlement.
65
+
66
+ `settleInvoice` repeats those reads, selects commission eligibility, allocates
67
+ with the existing fee-first helper and executes through the existing transfer
68
+ ledger. The inclusive selling fee has actual processing cost as its floor.
69
+ Original native provenance becomes part of the immutable settlement identity.
70
+ Retries retain the original allocation even after fee changes. A native transfer
71
+ whose persistence failed is recovered before another transfer can be created.
72
+
73
+ A zero initial invoice creates no commission decision. `one_time` uses the first
74
+ paid nonzero invoice from complete native history; delayed webhook delivery does
75
+ not turn a later renewal into a second first payment. `forever` applies per paid
76
+ invoice. Refunds and disputes do not reset eligibility.
77
+
78
+ An unpaid draft/open invoice returns `not_ready/provider_pending`. Missing fees
79
+ remain `not_ready/fee_pending`. Zero paid invoices and refunded/disputed sources
80
+ are not payable. Incomplete or ambiguous funding, credit-funded/partial/multiple
81
+ payments, multiple priced invoice lines, proration, mismatched original periods,
82
+ converted settlement currencies and automatic destination/on-behalf-of charges
83
+ are held through explicit non-ready outcomes. The method does not guess a
84
+ multi-product allocation or take over existing destination-charge fee handling.
85
+ Fixed-plus-metered invoices remain readable with the ordinary invoice APIs, but
86
+ this automatic settlement method requires one original priced line. Treat these
87
+ limits as unsupported settlement combinations, not as zero proceeds.
88
+
89
+ ## Prepaid issuer-service revenue
90
+
91
+ Native Stripe billing credits are for the issuing business's own products and
92
+ services. Stripe prohibits using them as third-party payments or stored-value
93
+ wallets. See [Stripe's approved and prohibited uses](https://docs.stripe.com/billing/subscriptions/usage-based/billing-credits).
94
+
95
+ ```ts
96
+ const revenue = await stripe.usage.getCreditPurchaseRevenue(
97
+ ctx,
98
+ originalPurchase,
99
+ provider,
100
+ );
101
+ if (revenue.status !== "ready") return revenue;
102
+ return stripe.usage.settleCreditPurchase(
103
+ ctx,
104
+ {
105
+ ...originalPurchase,
106
+ policy: {
107
+ affiliate: authorizedIssuerServiceAffiliate,
108
+ feeBasisPoints: authorizedFeeBasisPoints,
109
+ },
110
+ },
111
+ provider,
112
+ );
113
+ ```
114
+
115
+ `originalPurchase` is the original `UsageCreditPurchaseOptions`, including
116
+ `ownership: "issuer"`, quantity and immutable price. A verified paid purchase and
117
+ retained grant must already exist. The reader rechecks original purchase
118
+ identity, native payer/realm, payment success, refund/dispute eligibility and the
119
+ actual processing cost. It returns the original PaymentIntent, Charge, grant,
120
+ product/price and purchase ID. It performs no financial writes.
121
+
122
+ `settleCreditPurchase` keeps the issuer's remaining revenue on its own platform
123
+ balance after actual processing costs and any server-authorized affiliate share.
124
+ It creates no seller or reseller transfer. Affiliate policy applies to this
125
+ original paid purchase/top-up, with exact original-charge replay protection.
126
+ A prepaid purchase is a one-time sale rather than an invoice subscription award;
127
+ the host decides whether an affiliate applies to each top-up. Consumption,
128
+ reservation, cancellation, credit expiry and invoice credit application never
129
+ create a second cash sale or affiliate award. An extra seller/collaborator policy
130
+ or non-issuer ownership returns `rejected/unsupported_source`.
131
+
132
+ A pending payment/grant is not revenue available for settlement. A missing
133
+ processing fee is not zero. Refunded/disputed purchase proceeds cannot initiate a
134
+ new settlement. A ready revenue read is not accounting advice about revenue
135
+ recognition or a promise that a native credit may fund another business.
136
+
137
+ ## Recovery and operation boundaries
138
+
139
+ Continue to use the existing refund/dispute webhooks and [affiliate recovery](affiliate-clawbacks.md).
140
+ Both invoice and prepaid purchase settlements retain the original charge and
141
+ recipient legs in the same component ledger. Partial refunds accumulate against
142
+ those original legs; disputes and won-dispute reinstatement use the existing
143
+ recovery reservations. Never calculate clawbacks from current rates or issue a
144
+ second commission to compensate for a usage correction.
145
+
146
+ Before refunding a prepaid purchase, follow [paid-credit recovery](usage-credits.md):
147
+ reconcile consumption and disable refundable unspent native credit before using
148
+ the original cash-refund API. A usage correction can restore proven quantity
149
+ without creating cash. A finalized invoice adjustment uses the [correction and
150
+ verified credit-note/refund workflow](usage-corrections.md); it does not erase
151
+ valid usage or reopen affiliate eligibility.
152
+
153
+ Keep original bindings, settlement claims, transfers, grants and recovery history
154
+ while any operation can be retried or reversed. Unsupported account combinations
155
+ require operator resolution. There is no automatic production migration, live
156
+ billing activation, marketplace credit redemption or package publication.
157
+
158
+ The co-located SDK transport and Convex transaction tests cover original invoice
159
+ provenance, fractional quantity, included tiers, zero-first-invoice commission,
160
+ transfer-success/persistence-failure, replay, prepaid purchase consumption and
161
+ refund guards. These tests are not a new native financial sandbox execution;
162
+ project-wide native acceptance is recorded separately.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.59.0",
3
+ "version": "0.60.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -109,6 +109,7 @@
109
109
  "docs/usage-credits.md",
110
110
  "docs/usage-limits.md",
111
111
  "docs/usage-corrections.md",
112
+ "docs/usage-settlement.md",
112
113
  "docs/evidence/native-metering"
113
114
  ],
114
115
  "scripts": {
@@ -1811,3 +1811,12 @@ export type {
1811
1811
  } from "./billing/subscription-payment-method.js";
1812
1812
 
1813
1813
  export * from "./usageExports.js";
1814
+
1815
+ export type {
1816
+ UsageInvoiceSaleOptions,
1817
+ VerifiedUsageInvoiceSale,
1818
+ } from "./usage/invoiceSale.js";
1819
+ export type { UsageInvoiceSettlementOptions } from "./usage/settlement.js";
1820
+ export type { UsageCreditRevenue } from "./usage/creditRevenue.js";
1821
+
1822
+ export type { UsageCreditSettlementOptions } from "./usage/creditSettlement.js";