@fantastic.dev/better-stripe 0.66.0 → 0.67.1

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 (90) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +17 -20
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +126 -12
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +79 -22
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +158 -44
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +63 -6
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +1 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/index.js.map +1 -1
  14. package/dist/client/recoveryWorkflow/provider.fixture.d.ts +21 -0
  15. package/dist/client/recoveryWorkflow/provider.fixture.d.ts.map +1 -0
  16. package/dist/client/recoveryWorkflow/provider.fixture.js +125 -0
  17. package/dist/client/recoveryWorkflow/provider.fixture.js.map +1 -0
  18. package/dist/client/settlement/authorization.d.ts.map +1 -1
  19. package/dist/client/settlement/authorization.fixture.d.ts +10 -0
  20. package/dist/client/settlement/authorization.fixture.d.ts.map +1 -1
  21. package/dist/client/settlement/authorization.js +1 -0
  22. package/dist/client/settlement/authorization.js.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 +3 -0
  26. package/dist/client/settlement/execution.js.map +1 -1
  27. package/dist/client/settlement/settleSale.d.ts +2 -0
  28. package/dist/client/settlement/settleSale.d.ts.map +1 -1
  29. package/dist/client/settlement/settleSale.js +4 -0
  30. package/dist/client/settlement/settleSale.js.map +1 -1
  31. package/dist/client/usage/observationClient.d.ts +2 -2
  32. package/dist/client/usage/observationClient.d.ts.map +1 -1
  33. package/dist/component/_generated/component.d.ts +25 -0
  34. package/dist/component/_generated/component.d.ts.map +1 -1
  35. package/dist/component/balanceFunding/mutations.d.ts +27 -27
  36. package/dist/component/balanceFunding/queries.d.ts +1 -1
  37. package/dist/component/earnings/triggers.d.ts +36 -6
  38. package/dist/component/earnings/triggers.d.ts.map +1 -1
  39. package/dist/component/payoutRelease/queries.d.ts +2 -2
  40. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  41. package/dist/component/recoveryWorkflow/helpers.d.ts +5 -0
  42. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
  43. package/dist/component/recoveryWorkflow/mutations.d.ts +5 -0
  44. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
  45. package/dist/component/recoveryWorkflow/mutations.js +2 -0
  46. package/dist/component/recoveryWorkflow/mutations.js.map +1 -1
  47. package/dist/component/recoveryWorkflow/queries.d.ts +10 -0
  48. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
  49. package/dist/component/recoveryWorkflow/schema.d.ts +114 -10
  50. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
  51. package/dist/component/schema.d.ts +63 -6
  52. package/dist/component/settlement/mutations.d.ts +10 -0
  53. package/dist/component/settlement/mutations.d.ts.map +1 -1
  54. package/dist/component/settlement/mutations.js +3 -0
  55. package/dist/component/settlement/mutations.js.map +1 -1
  56. package/dist/component/settlement/queries.d.ts +5 -0
  57. package/dist/component/settlement/queries.d.ts.map +1 -1
  58. package/dist/component/settlement/schema.d.ts +24 -1
  59. package/dist/component/settlement/schema.d.ts.map +1 -1
  60. package/dist/component/settlement/schema.js +5 -0
  61. package/dist/component/settlement/schema.js.map +1 -1
  62. package/dist/component/usage/allowance.fixtures.d.ts +79 -22
  63. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  64. package/dist/component/usageCredits/accounting.fixtures.d.ts +63 -6
  65. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  66. package/dist/shared/settlementPolicyContext.d.ts +10 -0
  67. package/dist/shared/settlementPolicyContext.d.ts.map +1 -0
  68. package/dist/shared/settlementPolicyContext.js +40 -0
  69. package/dist/shared/settlementPolicyContext.js.map +1 -0
  70. package/docs/README.md +2 -1
  71. package/docs/metered-usage.md +174 -356
  72. package/docs/metering-setup.md +175 -168
  73. package/docs/settlement.md +38 -0
  74. package/docs/usage-catalog.md +1 -1
  75. package/docs/usage-ledger.md +9 -8
  76. package/docs/usage-rollout.md +147 -0
  77. package/package.json +3 -2
  78. package/src/client/index.ts +1 -0
  79. package/src/client/recoveryWorkflow/provider.fixture.ts +143 -0
  80. package/src/client/recoveryWorkflow/provider.test.ts +83 -140
  81. package/src/client/settlement/authorization.ts +1 -0
  82. package/src/client/settlement/execution.ts +7 -0
  83. package/src/client/settlement/policy-context.test.ts +277 -0
  84. package/src/client/settlement/settleSale.ts +12 -0
  85. package/src/component/_generated/component.ts +25 -0
  86. package/src/component/recoveryWorkflow/mutations.ts +2 -0
  87. package/src/component/settlement/mutations.ts +6 -0
  88. package/src/component/settlement/schema.ts +7 -0
  89. package/src/component/tsconfig.json +5 -0
  90. package/src/shared/settlementPolicyContext.ts +62 -0
@@ -1,3 +1,8 @@
1
+ import {
2
+ policyContextBinding,
3
+ assertPolicyContextMatches,
4
+ type SettlementPolicyContext,
5
+ } from "../../shared/settlementPolicyContext.js";
1
6
  import type Stripe from "stripe";
2
7
  import type { SplitTransfer } from "../core/fees.js";
3
8
  import type { Component, RunCtx } from "../helpers.js";
@@ -14,6 +19,7 @@ import {
14
19
  } from "./execution.js";
15
20
  export type SettleSaleOptions = VerifiedSaleOptions & {
16
21
  allocation: {
22
+ policyContext?: SettlementPolicyContext;
17
23
  gross: number;
18
24
  currency: string;
19
25
  processingFee: number;
@@ -35,6 +41,7 @@ export async function settleSale(
35
41
  | SettlementResult
36
42
  | Exclude<Awaited<ReturnType<typeof getVerifiedSale>>, { status: "ready" }>
37
43
  > {
44
+ policyContextBinding(opts.allocation.policyContext);
38
45
  const sale = await getVerifiedSale(stripe, opts);
39
46
  if (sale.status !== "ready") return sale;
40
47
  const prior = (await ctx.runQuery(
@@ -43,6 +50,11 @@ export async function settleSale(
43
50
  sourceChargeId: sale.chargeId,
44
51
  },
45
52
  )) as SettlementResult | null;
53
+ if (prior)
54
+ assertPolicyContextMatches(
55
+ prior.policyContext,
56
+ opts.allocation.policyContext,
57
+ );
46
58
  const allocation = prior ?? opts.allocation;
47
59
  if (
48
60
  allocation.gross !== sale.gross ||
@@ -7851,6 +7851,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7851
7851
  paymentId?: string;
7852
7852
  paymentIntentId?: string;
7853
7853
  platformNet: number;
7854
+ policyContext?: {
7855
+ fields: Record<string, string>;
7856
+ namespace: string;
7857
+ version: 1;
7858
+ };
7854
7859
  processingFee: number;
7855
7860
  sourceChargeId: string;
7856
7861
  sourceInvoiceId?: string;
@@ -7978,6 +7983,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
7978
7983
  paymentId?: string;
7979
7984
  paymentIntentId?: string;
7980
7985
  platformNet: number;
7986
+ policyContext?: {
7987
+ fields: Record<string, string>;
7988
+ namespace: string;
7989
+ version: 1;
7990
+ };
7981
7991
  processingFee: number;
7982
7992
  sourceChargeId: string;
7983
7993
  sourceInvoiceId?: string;
@@ -8613,6 +8623,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8613
8623
  paymentId?: string;
8614
8624
  paymentIntentId?: string;
8615
8625
  platformNet: number;
8626
+ policyContext?: {
8627
+ fields: Record<string, string>;
8628
+ namespace: string;
8629
+ version: 1;
8630
+ };
8616
8631
  processingFee: number;
8617
8632
  sourceChargeId: string;
8618
8633
  sourceInvoiceId?: string;
@@ -8653,6 +8668,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8653
8668
  paymentId?: string;
8654
8669
  paymentIntentId?: string;
8655
8670
  platformNet: number;
8671
+ policyContext?: {
8672
+ fields: Record<string, string>;
8673
+ namespace: string;
8674
+ version: 1;
8675
+ };
8656
8676
  processingFee: number;
8657
8677
  sourceChargeId: string;
8658
8678
  sourceInvoiceId?: string;
@@ -8713,6 +8733,11 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
8713
8733
  paymentId?: string;
8714
8734
  paymentIntentId?: string;
8715
8735
  platformNet: number;
8736
+ policyContext?: {
8737
+ fields: Record<string, string>;
8738
+ namespace: string;
8739
+ version: 1;
8740
+ };
8716
8741
  processingFee: number;
8717
8742
  sourceChargeId: string;
8718
8743
  sourceInvoiceId?: string;
@@ -1,3 +1,4 @@
1
+ import { policyContextBinding } from "../../shared/settlementPolicyContext.js";
1
2
  import { allocationFields } from "../settlement/schema.js";
2
3
  import { anyApi, type FunctionReference } from "convex/server";
3
4
  import type { WorkflowId } from "@convex-dev/workflow";
@@ -21,6 +22,7 @@ export const start = mutation({
21
22
  returns: startResult,
22
23
  handler: async (ctx, args) => {
23
24
  validateScope(args);
25
+ policyContextBinding(args.allocation?.policyContext);
24
26
  if (
25
27
  !args.requestKey ||
26
28
  !args.provider ||
@@ -1,3 +1,7 @@
1
+ import {
2
+ policyContextBinding,
3
+ assertPolicyContextMatches,
4
+ } from "../../shared/settlementPolicyContext.js";
1
5
  import { canonicalFingerprint } from "../operationEvidence/canonical.js";
2
6
  import { observeSettlementAllocation } from "../financialObservations/settlement.js";
3
7
  import { paginator } from "convex-helpers/server/pagination";
@@ -17,6 +21,7 @@ export const reserveSettlementAllocation = mutation({
17
21
  args: allocationFields,
18
22
  returns: doc,
19
23
  handler: async (ctx, args) => {
24
+ policyContextBinding(args.policyContext);
20
25
  if (args.usageSource && args.creditSource)
21
26
  throw new Error(
22
27
  "Settlement cannot combine invoice and credit purchase sources",
@@ -28,6 +33,7 @@ export const reserveSettlementAllocation = mutation({
28
33
  )
29
34
  .first();
30
35
  if (existing) {
36
+ assertPolicyContextMatches(existing.policyContext, args.policyContext);
31
37
  if (
32
38
  existing.currency !== args.currency ||
33
39
  existing.paymentIntentId !== args.paymentIntentId ||
@@ -6,6 +6,13 @@ export const termValidator = v.union(
6
6
  v.literal("one_time"),
7
7
  );
8
8
  export const allocationFields = {
9
+ policyContext: v.optional(
10
+ v.object({
11
+ namespace: v.string(),
12
+ version: v.literal(1),
13
+ fields: v.record(v.string(), v.string()),
14
+ }),
15
+ ),
9
16
  sourceChargeId: v.string(),
10
17
  paymentIntentId: v.optional(v.string()),
11
18
  sourceInvoiceId: v.optional(v.string()),
@@ -0,0 +1,5 @@
1
+ {
2
+ "extends": "../../tsconfig.json",
3
+ "include": ["./**/*"],
4
+ "exclude": ["./_generated"]
5
+ }
@@ -0,0 +1,62 @@
1
+ /** Nonsecret host provenance. The SDK never interprets this as authorization. */
2
+ export type SettlementPolicyContext = Readonly<{
3
+ namespace: string;
4
+ version: 1;
5
+ fields: Readonly<Record<string, string>>;
6
+ }>;
7
+
8
+ /** Canonical, bounded binding shared by SDK entry and component reservation. */
9
+ export function policyContextBinding(
10
+ context?: SettlementPolicyContext,
11
+ ): string {
12
+ if (context === undefined) return "absent";
13
+ if (
14
+ !context ||
15
+ typeof context !== "object" ||
16
+ ![Object.prototype, null].includes(Object.getPrototypeOf(context)) ||
17
+ Object.keys(context).some(
18
+ (key) => !["namespace", "version", "fields"].includes(key),
19
+ ) ||
20
+ typeof context.namespace !== "string" ||
21
+ context.namespace.length < 1 ||
22
+ context.namespace.length > 80 ||
23
+ context.version !== 1 ||
24
+ !context.fields ||
25
+ typeof context.fields !== "object" ||
26
+ Array.isArray(context.fields) ||
27
+ ![Object.prototype, null].includes(Object.getPrototypeOf(context.fields))
28
+ )
29
+ throw new Error("Invalid settlement policy context.");
30
+ const entries = Object.entries(context.fields).sort(([a], [b]) =>
31
+ a < b ? -1 : a > b ? 1 : 0,
32
+ );
33
+ if (
34
+ entries.length > 32 ||
35
+ entries.some(
36
+ ([key, value]) =>
37
+ key.length < 1 ||
38
+ key.length > 64 ||
39
+ key.startsWith("$") ||
40
+ !/^[ -~]+$/.test(key) ||
41
+ typeof value !== "string" ||
42
+ value.length > 512,
43
+ )
44
+ )
45
+ throw new Error("Invalid settlement policy context fields.");
46
+ const binding = JSON.stringify({
47
+ namespace: context.namespace,
48
+ version: context.version,
49
+ fields: Object.fromEntries(entries),
50
+ });
51
+ if (new TextEncoder().encode(binding).byteLength > 8192)
52
+ throw new Error("Settlement policy context exceeds 8 KiB.");
53
+ return binding;
54
+ }
55
+
56
+ export function assertPolicyContextMatches(
57
+ saved: SettlementPolicyContext | undefined,
58
+ requested: SettlementPolicyContext | undefined,
59
+ ) {
60
+ if (policyContextBinding(saved) !== policyContextBinding(requested))
61
+ throw new Error("Settlement policy context cannot change.");
62
+ }