@fantastic.dev/better-stripe 0.40.0 → 0.41.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 (98) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +442 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +237 -16
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +442 -0
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +237 -16
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/costRecovery-invoices.d.ts +2 -2
  12. package/dist/client/costRecovery-invoices.d.ts.map +1 -1
  13. package/dist/client/costRecovery-invoices.js +4 -1
  14. package/dist/client/costRecovery-invoices.js.map +1 -1
  15. package/dist/client/costRecovery.d.ts +5 -2
  16. package/dist/client/costRecovery.d.ts.map +1 -1
  17. package/dist/client/costRecovery.js +3 -1
  18. package/dist/client/costRecovery.js.map +1 -1
  19. package/dist/client/recoveryWorkflow/client.d.ts +14 -0
  20. package/dist/client/recoveryWorkflow/client.d.ts.map +1 -0
  21. package/dist/client/recoveryWorkflow/client.js +34 -0
  22. package/dist/client/recoveryWorkflow/client.js.map +1 -0
  23. package/dist/client/recoveryWorkflow/contracts.d.ts +63 -0
  24. package/dist/client/recoveryWorkflow/contracts.d.ts.map +1 -0
  25. package/dist/client/recoveryWorkflow/contracts.js +11 -0
  26. package/dist/client/recoveryWorkflow/contracts.js.map +1 -0
  27. package/dist/client/recoveryWorkflow/provider.d.ts +10 -0
  28. package/dist/client/recoveryWorkflow/provider.d.ts.map +1 -0
  29. package/dist/client/recoveryWorkflow/provider.js +80 -0
  30. package/dist/client/recoveryWorkflow/provider.js.map +1 -0
  31. package/dist/client/recoveryWorkflow/settlement.d.ts +6 -0
  32. package/dist/client/recoveryWorkflow/settlement.d.ts.map +1 -0
  33. package/dist/client/recoveryWorkflow/settlement.js +43 -0
  34. package/dist/client/recoveryWorkflow/settlement.js.map +1 -0
  35. package/dist/component/_generated/api.d.ts +12 -0
  36. package/dist/component/_generated/api.d.ts.map +1 -1
  37. package/dist/component/_generated/api.js.map +1 -1
  38. package/dist/component/_generated/component.d.ts +164 -0
  39. package/dist/component/_generated/component.d.ts.map +1 -1
  40. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  41. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  42. package/dist/component/earnings/triggers.d.ts +210 -16
  43. package/dist/component/earnings/triggers.d.ts.map +1 -1
  44. package/dist/component/payoutRelease/queries.d.ts +2 -2
  45. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  46. package/dist/component/recoveryWorkflow/bridge.d.ts +21 -0
  47. package/dist/component/recoveryWorkflow/bridge.d.ts.map +1 -0
  48. package/dist/component/recoveryWorkflow/bridge.js +52 -0
  49. package/dist/component/recoveryWorkflow/bridge.js.map +1 -0
  50. package/dist/component/recoveryWorkflow/helpers.d.ts +83 -0
  51. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -0
  52. package/dist/component/recoveryWorkflow/helpers.js +48 -0
  53. package/dist/component/recoveryWorkflow/helpers.js.map +1 -0
  54. package/dist/component/recoveryWorkflow/mutations.d.ts +91 -0
  55. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -0
  56. package/dist/component/recoveryWorkflow/mutations.js +177 -0
  57. package/dist/component/recoveryWorkflow/mutations.js.map +1 -0
  58. package/dist/component/recoveryWorkflow/queries.d.ts +118 -0
  59. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -0
  60. package/dist/component/recoveryWorkflow/queries.js +20 -0
  61. package/dist/component/recoveryWorkflow/queries.js.map +1 -0
  62. package/dist/component/recoveryWorkflow/schema.d.ts +653 -0
  63. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -0
  64. package/dist/component/recoveryWorkflow/schema.js +81 -0
  65. package/dist/component/recoveryWorkflow/schema.js.map +1 -0
  66. package/dist/component/recoveryWorkflow/steps.d.ts +70 -0
  67. package/dist/component/recoveryWorkflow/steps.d.ts.map +1 -0
  68. package/dist/component/recoveryWorkflow/steps.js +94 -0
  69. package/dist/component/recoveryWorkflow/steps.js.map +1 -0
  70. package/dist/component/recoveryWorkflow/workflow.d.ts +22 -0
  71. package/dist/component/recoveryWorkflow/workflow.d.ts.map +1 -0
  72. package/dist/component/recoveryWorkflow/workflow.js +56 -0
  73. package/dist/component/recoveryWorkflow/workflow.js.map +1 -0
  74. package/dist/component/schema.d.ts +221 -0
  75. package/dist/component/schema.js +3 -0
  76. package/dist/component/schema.js.map +1 -1
  77. package/package.json +1 -1
  78. package/src/client/costRecovery-invoices.ts +6 -0
  79. package/src/client/costRecovery.ts +8 -3
  80. package/src/client/recoveryWorkflow/client.test.ts +37 -0
  81. package/src/client/recoveryWorkflow/client.ts +76 -0
  82. package/src/client/recoveryWorkflow/contracts.ts +72 -0
  83. package/src/client/recoveryWorkflow/provider.test.ts +424 -0
  84. package/src/client/recoveryWorkflow/provider.ts +119 -0
  85. package/src/client/recoveryWorkflow/settlement.ts +67 -0
  86. package/src/component/_generated/api.ts +12 -0
  87. package/src/component/_generated/component.ts +222 -0
  88. package/src/component/recoveryWorkflow/bridge.test.ts +481 -0
  89. package/src/component/recoveryWorkflow/bridge.ts +66 -0
  90. package/src/component/recoveryWorkflow/helpers.ts +58 -0
  91. package/src/component/recoveryWorkflow/journal.test.ts +104 -0
  92. package/src/component/recoveryWorkflow/mutations.ts +224 -0
  93. package/src/component/recoveryWorkflow/queries.ts +19 -0
  94. package/src/component/recoveryWorkflow/schema.ts +92 -0
  95. package/src/component/recoveryWorkflow/state.test.ts +191 -0
  96. package/src/component/recoveryWorkflow/steps.ts +97 -0
  97. package/src/component/recoveryWorkflow/workflow.ts +73 -0
  98. package/src/component/schema.ts +6 -0
@@ -0,0 +1,119 @@
1
+ import Stripe from "stripe";
2
+ import type { Component, RunCtx } from "../helpers.js";
3
+ import { runMutationOrThrow } from "../helpers.js";
4
+ import { componentRef } from "../webhooks/helpers.js";
5
+ import { attachRecoveryInvoice } from "../costRecovery-invoices.js";
6
+ import type { RecoveryGroup } from "../costRecovery.js";
7
+ import { executeResolvedTransfers } from "../settlement/execution.js";
8
+ import { reconcileRecoverySettlement } from "./settlement.js";
9
+ import { operationRef } from "./contracts.js";
10
+ import type {
11
+ RecoveryProviderRequest,
12
+ RecoveryProviderReceipt,
13
+ RecoverySnapshot,
14
+ } from "./contracts.js";
15
+ export type RecoveryProviderOptions = {
16
+ /** Runtime-only secret, supplied inside the registered internal host action. */
17
+ stripeSecretKey: string;
18
+ httpClient?: NonNullable<
19
+ ConstructorParameters<typeof Stripe>[1]
20
+ >["httpClient"];
21
+ };
22
+ export async function executeRecoveryProvider(
23
+ component: Component,
24
+ ctx: RunCtx,
25
+ request: RecoveryProviderRequest,
26
+ options: RecoveryProviderOptions,
27
+ ): Promise<RecoveryProviderReceipt> {
28
+ const unknown = {
29
+ ...operationRef(request),
30
+ phase: request.phase,
31
+ providerApiVersion: request.providerApiVersion,
32
+ definitionVersion: request.definitionVersion,
33
+ sourceId: "",
34
+ status: "unknown",
35
+ reason: "provider_outcome_unknown",
36
+ } as const;
37
+ try {
38
+ const op = (await ctx.runQuery(
39
+ componentRef(component, "recoveryWorkflow/queries/snapshot"),
40
+ operationRef(request),
41
+ )) as RecoverySnapshot;
42
+ const base = {
43
+ ...operationRef(request),
44
+ phase: request.phase,
45
+ providerApiVersion: request.providerApiVersion,
46
+ definitionVersion: request.definitionVersion,
47
+ sourceId: op.sourceId,
48
+ };
49
+ if (
50
+ op.status !== "running" ||
51
+ !op.providerStarted ||
52
+ op.activePhase !== request.phase ||
53
+ op.providerApiVersion !== request.providerApiVersion ||
54
+ op.definitionVersion !== request.definitionVersion ||
55
+ request.definitionVersion !== 1 ||
56
+ (request.phase !== "execute" && request.phase !== "reconcile")
57
+ )
58
+ return { ...base, status: "unknown", reason: "provider_outcome_unknown" };
59
+ const stripe = new Stripe(options.stripeSecretKey, {
60
+ apiVersion: request.providerApiVersion as Stripe.LatestApiVersion,
61
+ maxNetworkRetries: 0,
62
+ ...(options.httpClient ? { httpClient: options.httpClient } : {}),
63
+ });
64
+ if (op.sourceKind === "settlement") {
65
+ if (!op.allocation)
66
+ return {
67
+ ...base,
68
+ status: "unknown",
69
+ reason: "provider_outcome_unknown",
70
+ };
71
+ if (request.phase === "execute")
72
+ await executeResolvedTransfers(stripe, component, ctx, op.allocation);
73
+ else if (
74
+ !(await reconcileRecoverySettlement(
75
+ stripe,
76
+ component,
77
+ ctx,
78
+ op.allocation,
79
+ ))
80
+ )
81
+ return {
82
+ ...base,
83
+ status: "unknown",
84
+ reason: "provider_outcome_unknown",
85
+ };
86
+ return { ...base, status: "ready", outcome: "collect" };
87
+ }
88
+ const group = (await ctx.runQuery(
89
+ componentRef(component, "costRecovery/queries/group"),
90
+ { groupKey: op.groupKey },
91
+ )) as RecoveryGroup | null;
92
+ const bind = (invoiceItemId: string) =>
93
+ runMutationOrThrow(
94
+ ctx,
95
+ componentRef(component, "costRecovery/mutations/bindInvoiceItem"),
96
+ { groupKey: op.groupKey, invoiceItemId },
97
+ ) as Promise<RecoveryGroup>;
98
+ const create =
99
+ request.phase === "execute" &&
100
+ (await stripe.invoices.retrieve(op.sourceId)).status === "draft";
101
+ const receipt = create
102
+ ? await attachRecoveryInvoice(stripe, group, op, bind, true, 10000)
103
+ : await attachRecoveryInvoice(stripe, group, op, bind, false, 10000);
104
+ const outcome =
105
+ receipt.invoiceStatus === "paid"
106
+ ? "collect"
107
+ : receipt.invoiceStatus === "void" ||
108
+ (receipt.invoiceStatus === "uncollectible" &&
109
+ op.releaseUncollectible)
110
+ ? "release"
111
+ : null;
112
+ return outcome
113
+ ? { ...base, status: "ready", outcome }
114
+ : { ...base, status: "not_ready", reason: "provider_pending" };
115
+ } catch {
116
+ // Returning a closed outcome also prevents the host action from logging raw SDK failures.
117
+ return unknown;
118
+ }
119
+ }
@@ -0,0 +1,67 @@
1
+ import type Stripe from "stripe";
2
+ import type { Component, RunCtx } from "../helpers.js";
3
+ import { runMutationOrThrow } from "../helpers.js";
4
+ import { componentRef } from "../webhooks/helpers.js";
5
+ import {
6
+ matchingTransfer,
7
+ sourceTransfers,
8
+ recordSettlementTransfer,
9
+ } from "../settlement/reconciliation.js";
10
+ import type { ResolvedSettlement } from "../settlement/execution.js";
11
+ /** Read-only provider recovery: missing legs never create a second money attempt. */
12
+ export async function reconcileRecoverySettlement(
13
+ stripe: Stripe,
14
+ component: Component,
15
+ ctx: RunCtx,
16
+ claim: ResolvedSettlement,
17
+ ): Promise<boolean> {
18
+ const effective = [];
19
+ for (const leg of claim.transfers) {
20
+ const earning =
21
+ leg.role === "affiliate" && leg.amount > 0
22
+ ? ((await ctx.runQuery(
23
+ componentRef(component, "affiliateRecovery/queries/getEarning"),
24
+ {
25
+ sourceChargeId: claim.sourceChargeId,
26
+ affiliateAccountId: leg.destinationAccountId,
27
+ },
28
+ )) as { _id: string; releaseAmount: number } | null)
29
+ : null;
30
+ if (leg.role === "affiliate" && leg.amount > 0 && !earning) return false;
31
+ effective.push({
32
+ leg: { ...leg, amount: earning?.releaseAmount ?? leg.amount },
33
+ earning,
34
+ });
35
+ }
36
+ let provider = await sourceTransfers(stripe, claim.sourceChargeId);
37
+ if (
38
+ effective.some(
39
+ ({ leg }) => leg.amount > 0 && !matchingTransfer(provider, claim, leg),
40
+ )
41
+ )
42
+ provider = [
43
+ ...new Map(
44
+ [
45
+ ...provider,
46
+ ...(await sourceTransfers(stripe, claim.sourceChargeId, true)),
47
+ ].map((t) => [t.id, t]),
48
+ ).values(),
49
+ ];
50
+ for (const { leg, earning } of effective) {
51
+ const transfer =
52
+ leg.amount > 0 ? matchingTransfer(provider, claim, leg) : undefined;
53
+ if (leg.amount > 0 && !transfer) return false;
54
+ if (transfer)
55
+ await recordSettlementTransfer(component, ctx, claim, leg, transfer);
56
+ if (earning)
57
+ await runMutationOrThrow(
58
+ ctx,
59
+ componentRef(component, "affiliateEarnings/mutations/confirmEarning"),
60
+ {
61
+ earningId: earning._id,
62
+ ...(transfer ? { stripeTransferId: transfer.id } : {}),
63
+ },
64
+ );
65
+ }
66
+ return true;
67
+ }
@@ -119,6 +119,12 @@ import type * as payoutWorker_queries from "../payoutWorker/queries.js";
119
119
  import type * as products_mutations from "../products/mutations.js";
120
120
  import type * as products_queries from "../products/queries.js";
121
121
  import type * as products_validators from "../products/validators.js";
122
+ import type * as recoveryWorkflow_bridge from "../recoveryWorkflow/bridge.js";
123
+ import type * as recoveryWorkflow_helpers from "../recoveryWorkflow/helpers.js";
124
+ import type * as recoveryWorkflow_mutations from "../recoveryWorkflow/mutations.js";
125
+ import type * as recoveryWorkflow_queries from "../recoveryWorkflow/queries.js";
126
+ import type * as recoveryWorkflow_steps from "../recoveryWorkflow/steps.js";
127
+ import type * as recoveryWorkflow_workflow from "../recoveryWorkflow/workflow.js";
122
128
  import type * as refundHistory_commandBinding from "../refundHistory/commandBinding.js";
123
129
  import type * as refundHistory_commandEvidence from "../refundHistory/commandEvidence.js";
124
130
  import type * as refundHistory_commandEvidenceValidator from "../refundHistory/commandEvidenceValidator.js";
@@ -253,6 +259,12 @@ const fullApi: ApiFromModules<{
253
259
  "products/mutations": typeof products_mutations;
254
260
  "products/queries": typeof products_queries;
255
261
  "products/validators": typeof products_validators;
262
+ "recoveryWorkflow/bridge": typeof recoveryWorkflow_bridge;
263
+ "recoveryWorkflow/helpers": typeof recoveryWorkflow_helpers;
264
+ "recoveryWorkflow/mutations": typeof recoveryWorkflow_mutations;
265
+ "recoveryWorkflow/queries": typeof recoveryWorkflow_queries;
266
+ "recoveryWorkflow/steps": typeof recoveryWorkflow_steps;
267
+ "recoveryWorkflow/workflow": typeof recoveryWorkflow_workflow;
256
268
  "refundHistory/commandBinding": typeof refundHistory_commandBinding;
257
269
  "refundHistory/commandEvidence": typeof refundHistory_commandEvidence;
258
270
  "refundHistory/commandEvidenceValidator": typeof refundHistory_commandEvidenceValidator;
@@ -6420,6 +6420,228 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
6420
6420
  >;
6421
6421
  };
6422
6422
  };
6423
+ recoveryWorkflow: {
6424
+ mutations: {
6425
+ requestCancel: FunctionReference<
6426
+ "mutation",
6427
+ "internal",
6428
+ {
6429
+ accountId: string;
6430
+ currency: string;
6431
+ groupKey: string;
6432
+ operationId: string;
6433
+ scopeKey: string;
6434
+ version: number;
6435
+ },
6436
+ {
6437
+ accountId: string;
6438
+ cancelRequested: boolean;
6439
+ currency: string;
6440
+ groupKey: string;
6441
+ operationId: string;
6442
+ outcome?: "collect" | "release";
6443
+ scopeKey: string;
6444
+ sourceId: string;
6445
+ sourceKind: "settlement" | "invoice";
6446
+ status:
6447
+ | "queued"
6448
+ | "running"
6449
+ | "waiting"
6450
+ | "unknown"
6451
+ | "completed"
6452
+ | "canceled";
6453
+ version: number;
6454
+ },
6455
+ Name
6456
+ >;
6457
+ resume: FunctionReference<
6458
+ "mutation",
6459
+ "internal",
6460
+ {
6461
+ accountId: string;
6462
+ currency: string;
6463
+ groupKey: string;
6464
+ operationId: string;
6465
+ scopeKey: string;
6466
+ version: number;
6467
+ },
6468
+ {
6469
+ accountId: string;
6470
+ cancelRequested: boolean;
6471
+ currency: string;
6472
+ groupKey: string;
6473
+ operationId: string;
6474
+ outcome?: "collect" | "release";
6475
+ scopeKey: string;
6476
+ sourceId: string;
6477
+ sourceKind: "settlement" | "invoice";
6478
+ status:
6479
+ | "queued"
6480
+ | "running"
6481
+ | "waiting"
6482
+ | "unknown"
6483
+ | "completed"
6484
+ | "canceled";
6485
+ version: number;
6486
+ },
6487
+ Name
6488
+ >;
6489
+ start: FunctionReference<
6490
+ "mutation",
6491
+ "internal",
6492
+ {
6493
+ accountId: string;
6494
+ allocation?: {
6495
+ adjustmentAmount?: number;
6496
+ currency: string;
6497
+ gross: number;
6498
+ paymentId?: string;
6499
+ paymentIntentId?: string;
6500
+ platformNet: number;
6501
+ processingFee: number;
6502
+ sourceChargeId: string;
6503
+ sourceInvoiceId?: string;
6504
+ transfers: Array<{
6505
+ amount: number;
6506
+ destinationAccountId: string;
6507
+ role: "store" | "affiliate" | "other";
6508
+ }>;
6509
+ };
6510
+ completion?: string;
6511
+ currency: string;
6512
+ definitionVersion: number;
6513
+ groupKey: string;
6514
+ maxAttempts: number;
6515
+ provider: string;
6516
+ providerApiVersion: string;
6517
+ releaseUncollectible: boolean;
6518
+ requestKey: string;
6519
+ retryDelayMs: number;
6520
+ scopeKey: string;
6521
+ },
6522
+ | {
6523
+ accountId: string;
6524
+ cancelRequested: boolean;
6525
+ currency: string;
6526
+ groupKey: string;
6527
+ operationId: string;
6528
+ outcome?: "collect" | "release";
6529
+ scopeKey: string;
6530
+ sourceId: string;
6531
+ sourceKind: "settlement" | "invoice";
6532
+ status:
6533
+ | "queued"
6534
+ | "running"
6535
+ | "waiting"
6536
+ | "unknown"
6537
+ | "completed"
6538
+ | "canceled";
6539
+ version: number;
6540
+ }
6541
+ | { reason: "identity_changed"; retryable: false; status: "conflict" }
6542
+ | {
6543
+ reason: "history_incomplete";
6544
+ retryable: true;
6545
+ status: "not_ready";
6546
+ },
6547
+ Name
6548
+ >;
6549
+ };
6550
+ queries: {
6551
+ get: FunctionReference<
6552
+ "query",
6553
+ "internal",
6554
+ {
6555
+ accountId: string;
6556
+ currency: string;
6557
+ groupKey: string;
6558
+ operationId: string;
6559
+ scopeKey: string;
6560
+ version: number;
6561
+ },
6562
+ {
6563
+ accountId: string;
6564
+ cancelRequested: boolean;
6565
+ currency: string;
6566
+ groupKey: string;
6567
+ operationId: string;
6568
+ outcome?: "collect" | "release";
6569
+ scopeKey: string;
6570
+ sourceId: string;
6571
+ sourceKind: "settlement" | "invoice";
6572
+ status:
6573
+ | "queued"
6574
+ | "running"
6575
+ | "waiting"
6576
+ | "unknown"
6577
+ | "completed"
6578
+ | "canceled";
6579
+ version: number;
6580
+ },
6581
+ Name
6582
+ >;
6583
+ snapshot: FunctionReference<
6584
+ "query",
6585
+ "internal",
6586
+ {
6587
+ accountId: string;
6588
+ currency: string;
6589
+ groupKey: string;
6590
+ operationId: string;
6591
+ scopeKey: string;
6592
+ version: number;
6593
+ },
6594
+ {
6595
+ _creationTime: number;
6596
+ _id: string;
6597
+ accountId: string;
6598
+ activePhase?: "execute" | "reconcile";
6599
+ allocation?: {
6600
+ adjustmentAmount?: number;
6601
+ currency: string;
6602
+ gross: number;
6603
+ paymentId?: string;
6604
+ paymentIntentId?: string;
6605
+ platformNet: number;
6606
+ processingFee: number;
6607
+ sourceChargeId: string;
6608
+ sourceInvoiceId?: string;
6609
+ transfers: Array<{
6610
+ amount: number;
6611
+ destinationAccountId: string;
6612
+ role: "store" | "affiliate" | "other";
6613
+ }>;
6614
+ };
6615
+ cancelRequested: boolean;
6616
+ completion?: string;
6617
+ currency: string;
6618
+ definitionVersion: number;
6619
+ groupKey: string;
6620
+ maxAttempts: number;
6621
+ outcome?: "collect" | "release";
6622
+ provider: string;
6623
+ providerApiVersion: string;
6624
+ providerStarted: boolean;
6625
+ releaseUncollectible: boolean;
6626
+ resumeQueued: boolean;
6627
+ retryDelayMs: number;
6628
+ scopeKey: string;
6629
+ sourceId: string;
6630
+ sourceKind: "settlement" | "invoice";
6631
+ status:
6632
+ | "queued"
6633
+ | "running"
6634
+ | "waiting"
6635
+ | "unknown"
6636
+ | "completed"
6637
+ | "canceled";
6638
+ version: number;
6639
+ workflowId?: string;
6640
+ },
6641
+ Name
6642
+ >;
6643
+ };
6644
+ };
6423
6645
  refundHistory: {
6424
6646
  mutations: {
6425
6647
  normalizeRefundCommandBindings: FunctionReference<