@fantastic.dev/better-stripe 0.35.0 → 0.37.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 (94) hide show
  1. package/CHANGELOG.md +225 -0
  2. package/README.md +1 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +178 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +89 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +178 -0
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +89 -0
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/operationEvidence.d.ts +37 -0
  12. package/dist/client/operationEvidence.d.ts.map +1 -0
  13. package/dist/client/operationEvidence.js +44 -0
  14. package/dist/client/operationEvidence.js.map +1 -0
  15. package/dist/client/publicTypes.d.ts +1 -0
  16. package/dist/client/publicTypes.d.ts.map +1 -1
  17. package/dist/client/readContracts.d.ts +2 -0
  18. package/dist/client/readContracts.d.ts.map +1 -1
  19. package/dist/client/readContracts.js +4 -0
  20. package/dist/client/readContracts.js.map +1 -1
  21. package/dist/component/_generated/component.d.ts +181 -0
  22. package/dist/component/_generated/component.d.ts.map +1 -1
  23. package/dist/component/earnings/pairedAdjustment.d.ts +12 -0
  24. package/dist/component/earnings/pairedAdjustment.d.ts.map +1 -0
  25. package/dist/component/earnings/pairedAdjustment.js +46 -0
  26. package/dist/component/earnings/pairedAdjustment.js.map +1 -0
  27. package/dist/component/earnings/triggers.d.ts +120 -0
  28. package/dist/component/earnings/triggers.d.ts.map +1 -1
  29. package/dist/component/earnings/triggers.js +10 -2
  30. package/dist/component/earnings/triggers.js.map +1 -1
  31. package/dist/component/operationEvidence/canonical.d.ts +4 -0
  32. package/dist/component/operationEvidence/canonical.d.ts.map +1 -0
  33. package/dist/component/operationEvidence/canonical.js +8 -0
  34. package/dist/component/operationEvidence/canonical.js.map +1 -0
  35. package/dist/component/operationEvidence/helpers.d.ts +87 -0
  36. package/dist/component/operationEvidence/helpers.d.ts.map +1 -0
  37. package/dist/component/operationEvidence/helpers.js +49 -0
  38. package/dist/component/operationEvidence/helpers.js.map +1 -0
  39. package/dist/component/operationEvidence/maintenance.d.ts +88 -0
  40. package/dist/component/operationEvidence/maintenance.d.ts.map +1 -0
  41. package/dist/component/operationEvidence/maintenance.js +59 -0
  42. package/dist/component/operationEvidence/maintenance.js.map +1 -0
  43. package/dist/component/operationEvidence/mutations.d.ts +97 -0
  44. package/dist/component/operationEvidence/mutations.d.ts.map +1 -0
  45. package/dist/component/operationEvidence/mutations.js +14 -0
  46. package/dist/component/operationEvidence/mutations.js.map +1 -0
  47. package/dist/component/operationEvidence/queries.d.ts +205 -0
  48. package/dist/component/operationEvidence/queries.d.ts.map +1 -0
  49. package/dist/component/operationEvidence/queries.js +75 -0
  50. package/dist/component/operationEvidence/queries.js.map +1 -0
  51. package/dist/component/operationEvidence/schema.d.ts +536 -0
  52. package/dist/component/operationEvidence/schema.d.ts.map +1 -0
  53. package/dist/component/operationEvidence/schema.js +53 -0
  54. package/dist/component/operationEvidence/schema.js.map +1 -0
  55. package/dist/component/payoutRelease/queries.d.ts +2 -2
  56. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  57. package/dist/component/refundHistory/commandEvidence.d.ts +1 -1
  58. package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -1
  59. package/dist/component/refundHistory/commandEvidence.js +6 -2
  60. package/dist/component/refundHistory/commandEvidence.js.map +1 -1
  61. package/dist/component/refundHistory/originalSeller.d.ts +5 -0
  62. package/dist/component/refundHistory/originalSeller.d.ts.map +1 -0
  63. package/dist/component/refundHistory/originalSeller.js +35 -0
  64. package/dist/component/refundHistory/originalSeller.js.map +1 -0
  65. package/dist/component/refundHistory/queries.d.ts +1 -1
  66. package/dist/component/schema.d.ts +89 -0
  67. package/dist/component/schema.js +3 -0
  68. package/dist/component/schema.js.map +1 -1
  69. package/docs/financial-observations.md +85 -0
  70. package/docs/refund-command-evidence.md +6 -0
  71. package/package.json +1 -1
  72. package/src/client/operationEvidence.test.ts +110 -0
  73. package/src/client/operationEvidence.ts +92 -0
  74. package/src/client/publicTypes.ts +8 -0
  75. package/src/client/readContracts.ts +4 -0
  76. package/src/component/_generated/api.ts +10 -0
  77. package/src/component/_generated/component.ts +207 -0
  78. package/src/component/earnings/paired-adjustment.test.ts +258 -0
  79. package/src/component/earnings/pairedAdjustment.ts +77 -0
  80. package/src/component/earnings/triggers.ts +14 -10
  81. package/src/component/operationEvidence/canonical.ts +10 -0
  82. package/src/component/operationEvidence/helpers.ts +65 -0
  83. package/src/component/operationEvidence/integrity.test.ts +257 -0
  84. package/src/component/operationEvidence/maintenance.test.ts +152 -0
  85. package/src/component/operationEvidence/maintenance.ts +89 -0
  86. package/src/component/operationEvidence/mutations.ts +14 -0
  87. package/src/component/operationEvidence/queries.ts +108 -0
  88. package/src/component/operationEvidence/reads.test.ts +140 -0
  89. package/src/component/operationEvidence/schema.ts +62 -0
  90. package/src/component/refundHistory/commandEvidence.ts +7 -2
  91. package/src/component/refundHistory/original-seller-boundaries.test.ts +138 -0
  92. package/src/component/refundHistory/original-seller.test.ts +175 -0
  93. package/src/component/refundHistory/originalSeller.ts +48 -0
  94. package/src/component/schema.ts +6 -0
@@ -31,7 +31,7 @@ export declare function readRefundCommandEvidence(ctx: QueryCtx, scope: RefundCo
31
31
  refund: {
32
32
  _creationTime: number;
33
33
  _id: import("convex/values").GenericId<"refunds">;
34
- accountId?: string | undefined;
34
+ accountId: string;
35
35
  amount: number;
36
36
  currency: string;
37
37
  failureReason?: string | undefined;
@@ -1 +1 @@
1
- {"version":3,"file":"commandEvidence.d.ts","sourceRoot":"","sources":["../../../src/component/refundHistory/commandEvidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAE5C,iGAAiG;AACjG,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,kBAAkB;YAWb,aAAa;YACb,0BAA0B;;;YASnB,aAAa;YAAmB,WAAW;;;YAG3C,aAAa;YAAmB,SAAS;;;YAGhD,aAAa;YACb,sBAAsB;;;YAStB,aAAa;YACb,gBAAgB;;;YAWhB,aAAa;YACb,iBAAiB;;;;YAUZ,UAAU;;;;;;;;;;;;;;;;;;;GAC5B"}
1
+ {"version":3,"file":"commandEvidence.d.ts","sourceRoot":"","sources":["../../../src/component/refundHistory/commandEvidence.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,oCAAoC,CAAC;AAE5C,iGAAiG;AACjG,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,kBAAkB;YAWb,aAAa;YACb,0BAA0B;;;YASnB,aAAa;YAAmB,WAAW;;;YAG3C,aAAa;YAAmB,SAAS;;;YAGhD,aAAa;YACb,sBAAsB;;;YAatB,aAAa;YACb,gBAAgB;;;YAWhB,aAAa;YACb,iBAAiB;;;;YAUZ,UAAU;;;;;;;;;;;;;;;;;;;GAC5B"}
@@ -1,3 +1,4 @@
1
+ import { originalRefundSeller } from "./originalSeller.js";
1
2
  import { assertRefundCommandScope, } from "../../shared/refundCommandScope.js";
2
3
  /** Bounded global normalization and exact-key proof, never a provider history or retry claim. */
3
4
  export async function readRefundCommandEvidence(ctx, scope) {
@@ -25,7 +26,10 @@ export async function readRefundCommandEvidence(ctx, scope) {
25
26
  status: "unavailable",
26
27
  reason: "correlation_conflict",
27
28
  };
28
- if (row.accountId !== scope.accountId ||
29
+ const accountId = row.accountId === undefined
30
+ ? await originalRefundSeller(ctx, scope)
31
+ : row.accountId;
32
+ if (accountId !== scope.accountId ||
29
33
  row.stripePaymentIntentId !== scope.stripePaymentIntentId ||
30
34
  row.stripeChargeId !== scope.stripeChargeId ||
31
35
  row.currency !== scope.currency)
@@ -49,6 +53,6 @@ export async function readRefundCommandEvidence(ctx, scope) {
49
53
  .take(2);
50
54
  if (identity.length !== 1 || identity[0]?._id !== row._id)
51
55
  return { status: "unavailable", reason: "ambiguous" };
52
- return { status: "observed", refund: row };
56
+ return { status: "observed", refund: { ...row, accountId } };
53
57
  }
54
58
  //# sourceMappingURL=commandEvidence.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"commandEvidence.js","sourceRoot":"","sources":["../../../src/component/refundHistory/commandEvidence.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"commandEvidence.js","sourceRoot":"","sources":["../../../src/component/refundHistory/commandEvidence.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,5 @@
1
+ import type { QueryCtx } from "../_generated/server.js";
2
+ import type { RefundCommandScope } from "../../shared/refundCommandScope.js";
3
+ /** At most two exact-charge allocations; mutable payments never establish original ownership. */
4
+ export declare function originalRefundSeller(ctx: QueryCtx, scope: RefundCommandScope): Promise<string | undefined>;
5
+ //# sourceMappingURL=originalSeller.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"originalSeller.d.ts","sourceRoot":"","sources":["../../../src/component/refundHistory/originalSeller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAyB7E,iGAAiG;AACjG,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B"}
@@ -0,0 +1,35 @@
1
+ const account = (value) => /^acct_[A-Za-z0-9_]{1,128}$/.test(value);
2
+ /** Immutable allocation routing only. Observation does not authorize a refund. */
3
+ function seller(allocation) {
4
+ const destinations = new Set();
5
+ let store;
6
+ for (const recipient of allocation.transfers) {
7
+ if (!account(recipient.destinationAccountId) ||
8
+ destinations.has(recipient.destinationAccountId) ||
9
+ !Number.isSafeInteger(recipient.amount) ||
10
+ recipient.amount < 0)
11
+ return undefined;
12
+ destinations.add(recipient.destinationAccountId);
13
+ if (recipient.role === "store") {
14
+ if (store !== undefined)
15
+ return undefined;
16
+ store = recipient.destinationAccountId;
17
+ }
18
+ }
19
+ return store;
20
+ }
21
+ /** At most two exact-charge allocations; mutable payments never establish original ownership. */
22
+ export async function originalRefundSeller(ctx, scope) {
23
+ const allocations = await ctx.db
24
+ .query("settlementAllocations")
25
+ .withIndex("by_source_charge", (q) => q.eq("sourceChargeId", scope.stripeChargeId))
26
+ .take(2);
27
+ const allocation = allocations[0];
28
+ if (allocations.length !== 1 ||
29
+ !allocation ||
30
+ allocation.paymentIntentId !== scope.stripePaymentIntentId ||
31
+ allocation.currency !== scope.currency)
32
+ return undefined;
33
+ return seller(allocation);
34
+ }
35
+ //# sourceMappingURL=originalSeller.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"originalSeller.js","sourceRoot":"","sources":["../../../src/component/refundHistory/originalSeller.ts"],"names":[],"mappings":"AAIA,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAE5E,kFAAkF;AAClF,SAAS,MAAM,CAAC,UAAwC;IACtD,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,IAAI,KAAyB,CAAC;IAC9B,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,SAAS,EAAE,CAAC;QAC7C,IACE,CAAC,OAAO,CAAC,SAAS,CAAC,oBAAoB,CAAC;YACxC,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,oBAAoB,CAAC;YAChD,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,MAAM,CAAC;YACvC,SAAS,CAAC,MAAM,GAAG,CAAC;YAEpB,OAAO,SAAS,CAAC;QACnB,YAAY,CAAC,GAAG,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QACjD,IAAI,SAAS,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC/B,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC1C,KAAK,GAAG,SAAS,CAAC,oBAAoB,CAAC;QACzC,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAa,EACb,KAAyB;IAEzB,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,EAAE;SAC7B,KAAK,CAAC,uBAAuB,CAAC;SAC9B,SAAS,CAAC,kBAAkB,EAAE,CAAC,CAAC,EAAE,EAAE,CACnC,CAAC,CAAC,EAAE,CAAC,gBAAgB,EAAE,KAAK,CAAC,cAAc,CAAC,CAC7C;SACA,IAAI,CAAC,CAAC,CAAC,CAAC;IACX,MAAM,UAAU,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAClC,IACE,WAAW,CAAC,MAAM,KAAK,CAAC;QACxB,CAAC,UAAU;QACX,UAAU,CAAC,eAAe,KAAK,KAAK,CAAC,qBAAqB;QAC1D,UAAU,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ;QAEtC,OAAO,SAAS,CAAC;IACnB,OAAO,MAAM,CAAC,UAAU,CAAC,CAAC;AAC5B,CAAC"}
@@ -60,7 +60,7 @@ export declare const getRefundCommandEvidence: import("convex/server").Registere
60
60
  refund: {
61
61
  _creationTime: number;
62
62
  _id: import("convex/values").GenericId<"refunds">;
63
- accountId?: string | undefined;
63
+ accountId: string;
64
64
  amount: number;
65
65
  currency: string;
66
66
  failureReason?: string | undefined;
@@ -1,4 +1,93 @@
1
1
  declare const _default: import("convex/server").SchemaDefinition<{
2
+ operationEvidencePayloads: import("convex/server").TableDefinition<import("convex/values").VObject<{
3
+ commissionExposure?: {
4
+ chargeAmount: number;
5
+ disputeId?: string | undefined;
6
+ disputeState?: "lost" | "open" | "won" | undefined;
7
+ finalized: boolean;
8
+ kind: "dispute" | "refund";
9
+ principal: number;
10
+ refundId?: string | undefined;
11
+ refundedPrincipal?: number | undefined;
12
+ } | undefined;
13
+ operationId: string;
14
+ slices: {
15
+ from: number;
16
+ stripeTransferId: string;
17
+ to: number;
18
+ }[];
19
+ sourceChargeId: string;
20
+ }, {
21
+ operationId: import("convex/values").VString<string, "required">;
22
+ sourceChargeId: import("convex/values").VString<string, "required">;
23
+ slices: import("convex/values").VArray<{
24
+ from: number;
25
+ stripeTransferId: string;
26
+ to: number;
27
+ }[], import("convex/values").VObject<{
28
+ from: number;
29
+ stripeTransferId: string;
30
+ to: number;
31
+ }, {
32
+ stripeTransferId: import("convex/values").VString<string, "required">;
33
+ from: import("convex/values").VFloat64<number, "required">;
34
+ to: import("convex/values").VFloat64<number, "required">;
35
+ }, "required", "from" | "stripeTransferId" | "to">, "required">;
36
+ commissionExposure: import("convex/values").VObject<{
37
+ chargeAmount: number;
38
+ disputeId?: string | undefined;
39
+ disputeState?: "lost" | "open" | "won" | undefined;
40
+ finalized: boolean;
41
+ kind: "dispute" | "refund";
42
+ principal: number;
43
+ refundId?: string | undefined;
44
+ refundedPrincipal?: number | undefined;
45
+ } | undefined, {
46
+ kind: import("convex/values").VUnion<"dispute" | "refund", [import("convex/values").VLiteral<"refund", "required">, import("convex/values").VLiteral<"dispute", "required">], "required", never>;
47
+ chargeAmount: import("convex/values").VFloat64<number, "required">;
48
+ principal: import("convex/values").VFloat64<number, "required">;
49
+ finalized: import("convex/values").VBoolean<boolean, "required">;
50
+ disputeState: import("convex/values").VUnion<"lost" | "open" | "won" | undefined, [import("convex/values").VLiteral<"open", "required">, import("convex/values").VLiteral<"lost", "required">, import("convex/values").VLiteral<"won", "required">], "optional", never>;
51
+ disputeId: import("convex/values").VString<string | undefined, "optional">;
52
+ refundedPrincipal: import("convex/values").VFloat64<number | undefined, "optional">;
53
+ refundId: import("convex/values").VString<string | undefined, "optional">;
54
+ }, "optional", "chargeAmount" | "disputeId" | "disputeState" | "finalized" | "kind" | "principal" | "refundId" | "refundedPrincipal">;
55
+ }, "required", "commissionExposure" | "commissionExposure.chargeAmount" | "commissionExposure.disputeId" | "commissionExposure.disputeState" | "commissionExposure.finalized" | "commissionExposure.kind" | "commissionExposure.principal" | "commissionExposure.refundId" | "commissionExposure.refundedPrincipal" | "operationId" | "slices" | "sourceChargeId">, {}, {}, {}>;
56
+ operationEvidenceHeaders: import("convex/server").TableDefinition<import("convex/values").VObject<{
57
+ firstObservedAt: number;
58
+ generation: number;
59
+ isContradictory: boolean;
60
+ latestFingerprint: string;
61
+ latestPayloadId: import("convex/values").GenericId<"operationEvidencePayloads">;
62
+ operationDigest: string;
63
+ originalFingerprint: string;
64
+ originalIdentityFingerprint: string;
65
+ originalPayloadId: import("convex/values").GenericId<"operationEvidencePayloads">;
66
+ producer: "trusted_host_maintenance";
67
+ producerVersion: 1;
68
+ sourceChargeDigest: string;
69
+ sourceCreatedAt: number;
70
+ sourceId: import("convex/values").GenericId<"transferReversalOps">;
71
+ }, {
72
+ sourceId: import("convex/values").VId<import("convex/values").GenericId<"transferReversalOps">, "required">;
73
+ originalPayloadId: import("convex/values").VId<import("convex/values").GenericId<"operationEvidencePayloads">, "required">;
74
+ latestPayloadId: import("convex/values").VId<import("convex/values").GenericId<"operationEvidencePayloads">, "required">;
75
+ producer: import("convex/values").VLiteral<"trusted_host_maintenance", "required">;
76
+ producerVersion: import("convex/values").VLiteral<1, "required">;
77
+ firstObservedAt: import("convex/values").VFloat64<number, "required">;
78
+ sourceCreatedAt: import("convex/values").VFloat64<number, "required">;
79
+ originalFingerprint: import("convex/values").VString<string, "required">;
80
+ latestFingerprint: import("convex/values").VString<string, "required">;
81
+ originalIdentityFingerprint: import("convex/values").VString<string, "required">;
82
+ operationDigest: import("convex/values").VString<string, "required">;
83
+ sourceChargeDigest: import("convex/values").VString<string, "required">;
84
+ generation: import("convex/values").VFloat64<number, "required">;
85
+ isContradictory: import("convex/values").VBoolean<boolean, "required">;
86
+ }, "required", "firstObservedAt" | "generation" | "isContradictory" | "latestFingerprint" | "latestPayloadId" | "operationDigest" | "originalFingerprint" | "originalIdentityFingerprint" | "originalPayloadId" | "producer" | "producerVersion" | "sourceChargeDigest" | "sourceCreatedAt" | "sourceId">, {
87
+ by_operation_digest: ["operationDigest", "_creationTime"];
88
+ by_source_charge_digest: ["sourceChargeDigest", "_creationTime"];
89
+ by_source_id: ["sourceId", "_creationTime"];
90
+ }, {}, {}>;
2
91
  financialTransferObservations: import("convex/server").TableDefinition<import("convex/values").VObject<{
3
92
  bucketKey: string;
4
93
  fingerprint: string;
@@ -1,3 +1,4 @@
1
+ import { payloadsTable as operationEvidencePayloads, headersTable as operationEvidenceHeaders, } from "./operationEvidence/schema.js";
1
2
  import { transferBatchReferencesTable } from "./financialObservations/transferReferenceSchema.js";
2
3
  import { transferObservationsTable, transferBatchesTable, } from "./financialObservations/transferSchema.js";
3
4
  import { sourceObservationsTable, sourceLegsTable, observationGenerationsTable, } from "./financialObservations/schema.js";
@@ -20,6 +21,8 @@ import { accountsTable } from "./core/schema";
20
21
  import { pricesTable, productsTable } from "./products/schema";
21
22
  import { webhookEventsTable } from "./webhooks/schema";
22
23
  export default defineSchema({
24
+ operationEvidencePayloads,
25
+ operationEvidenceHeaders,
23
26
  financialTransferObservations: transferObservationsTable,
24
27
  financialTransferBatches: transferBatchesTable,
25
28
  financialTransferBatchReferences: transferBatchReferencesTable,
@@ -1 +1 @@
1
- {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,4BAA4B,EAAE,MAAM,oDAAoD,CAAC;AAClG,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,2BAA2B,GAC5B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,cAAc,EACd,gBAAgB,GACjB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,SAAS,IAAI,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,IAAI,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EACL,mBAAmB,IAAI,uBAAuB,EAC9C,eAAe,IAAI,mBAAmB,EACtC,aAAa,IAAI,iBAAiB,EAClC,YAAY,IAAI,gBAAgB,EAChC,aAAa,IAAI,iBAAiB,GACnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,gBAAgB,IAAI,sBAAsB,EAC1C,WAAW,IAAI,wBAAwB,EACvC,YAAY,IAAI,4BAA4B,GAC7C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EACL,WAAW,EACX,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,EACL,qBAAqB,EACrB,aAAa,EACb,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,sBAAsB,EACtB,YAAY,EACZ,wBAAwB,EACxB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,eAAe,YAAY,CAAC;IAC1B,6BAA6B,EAAE,yBAAyB;IACxD,wBAAwB,EAAE,oBAAoB;IAC9C,gCAAgC,EAAE,4BAA4B;IAC9D,2BAA2B,EAAE,uBAAuB;IACpD,mBAAmB,EAAE,eAAe;IACpC,+BAA+B,EAAE,2BAA2B;IAC5D,kBAAkB,EAAE,cAAc;IAClC,6BAA6B,EAAE,gBAAgB;IAC/C,gBAAgB,EAAE,qBAAqB;IACvC,wBAAwB,EAAE,uBAAuB;IACjD,gBAAgB,EAAE,eAAe;IACjC,mBAAmB,EAAE,kBAAkB;IACvC,eAAe,EAAE,cAAc;IAC/B,qBAAqB,EAAE,oBAAoB;IAC3C,oBAAoB,EAAE,mBAAmB;IACzC,kBAAkB,EAAE,iBAAiB;IACrC,oBAAoB,EAAE,yBAAyB;IAC/C,2BAA2B,EAAE,mBAAmB;IAChD,uBAAuB;IACvB,iBAAiB;IACjB,gBAAgB;IAChB,yBAAyB,EAAE,iBAAiB;IAC5C,yBAAyB,EAAE,8BAA8B;IACzD,gBAAgB,EAAE,qBAAqB;IACvC,iBAAiB,EAAE,sBAAsB;IACzC,mBAAmB,EAAE,wBAAwB;IAC7C,uBAAuB,EAAE,4BAA4B;IACrD,cAAc,EAAE,aAAa;IAC7B,sBAAsB,EAAE,eAAe;IACvC,cAAc,EAAE,mBAAmB;IACnC,cAAc,EAAE,WAAW;IAC3B,gBAAgB,EAAE,aAAa;IAC/B,cAAc,EAAE,WAAW;IAC3B,oBAAoB,EAAE,iBAAiB;IACvC,qBAAqB,EAAE,gBAAgB;IACvC,eAAe,EAAE,oBAAoB;IACrC,mBAAmB,EAAE,wBAAwB;IAC7C,OAAO;IACP,QAAQ,EAAE,aAAa;IACvB,eAAe,EAAE,oBAAoB;IAErC,WAAW;IACX,QAAQ,EAAE,aAAa;IACvB,MAAM,EAAE,WAAW;IAEnB,UAAU;IACV,aAAa,EAAE,kBAAkB;IACjC,gBAAgB,EAAE,qBAAqB;IACvC,QAAQ,EAAE,aAAa;IAEvB,UAAU;IACV,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;IACrB,iBAAiB,EAAE,sBAAsB;IACzC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,aAAa;IACvB,SAAS,EAAE,cAAc;IACzB,mBAAmB,EAAE,wBAAwB;IAE7C,WAAW;IACX,aAAa,EAAE,kBAAkB;CAClC,CAAC,CAAC"}
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/component/schema.ts"],"names":[],"mappings":"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"}
@@ -157,3 +157,88 @@ reference from an actual old-public 1,001-transfer claim/release and a current
157
157
  1,000-transfer mixed-owner claim across separate committed calls, while retaining
158
158
  all financial rows and amounts. No provider operation or financial-attempt
159
159
  admission is part of this continuation API.
160
+
161
+ ## Lossless operation evidence maintenance
162
+
163
+ `stripe.operationEvidence` is explicit trusted-host maintenance for actual
164
+ persisted reversal-operation documents. Authenticate the host actor and derive
165
+ the authorized source document before calling it. A source ID, selector, digest
166
+ or cursor is not end-user authorization. The host selects an existing document;
167
+ it cannot supply invented financial bytes.
168
+
169
+ ```ts
170
+ const observed = await stripe.operationEvidence.capture(ctx, {
171
+ sourceId: authorizedPersistedOperation._id,
172
+ });
173
+ const page = await stripe.operationEvidence.headers(ctx, {
174
+ paginationOpts: { numItems: 25, cursor: previousCursor },
175
+ });
176
+ if (observed.header) {
177
+ const original = await stripe.operationEvidence.original(ctx, {
178
+ headerId: observed.header._id,
179
+ });
180
+ const latestObserved = await stripe.operationEvidence.latest(ctx, {
181
+ headerId: observed.header._id,
182
+ });
183
+ }
184
+ ```
185
+
186
+ Original means the first trusted observation, not provider creation or
187
+ historical owner proof. Separate headerless documents retain the exact admitted
188
+ source fields for original and latest observed data. Compact headers retain the
189
+ original source reference, first-observed provenance, fingerprints and
190
+ generation. Payload documents add no annotation or duplicated exposure envelope:
191
+ a legal source can already be exactly the native 1 MiB document limit. Canonical
192
+ Convex encoding preserves special floats, optional presence and array order
193
+ while normalizing recursive object-key order.
194
+
195
+ Stable maintenance replay changes no evidence generation. Changed source data
196
+ updates the latest observed payload and global operation generation atomically;
197
+ original data and identity never redirect. Contradictory original identity stays
198
+ explicit, with actual latest bytes retained. Deletion after observation does not
199
+ erase the retained payloads. A source missing before observation creates no
200
+ evidence. Missing or damaged evidence is not silently recreated.
201
+
202
+ Header pages contain compact references only, up to 100 per request with fixed
203
+ read bounds. They never fan out to payloads. Original and latest hydration are
204
+ separate one-payload reads. `resolve(ctx, { selector, value })` accepts either
205
+ `operationId` or `sourceChargeId`, without narrowing admitted financial strings.
206
+ It reads at most two compact digest candidates and hydrates only one unique
207
+ original payload to verify raw selector equality. Missing, reused, colliding or
208
+ otherwise ambiguous selectors return a null header and UNKNOWN. A source charge
209
+ with multiple observed operations is ambiguous for this unique resolver; it is
210
+ not an exact-scope page. There is no full-payload fallback scan or repin.
211
+
212
+ Every response reports `coverage: "unknown"` and the current maintenance
213
+ `evidenceGeneration`. This is the current maintenance-evidence generation only.
214
+ Latest means latest **observed** data. Financial claim,
215
+ release and exposure writers do not invoke this maintenance automatically.
216
+ Changes that have not been explicitly captured therefore need not change its
217
+ generation. No drained-page or source-generation token certifies complete
218
+ history, current financial state, liabilities, ownership or closure readiness.
219
+
220
+ Maintenance is atomic and can abort at native aggregate read/write or rate
221
+ limits. It does not change financial source rows, swallow a resource abort as
222
+ success, or promise unlimited backlog capacity. Per-document lossless storage
223
+ does not prove that adding future hooks preserves aggregate financial
224
+ transaction capacity. That requires separate baseline-versus-hook measurement
225
+ before lifecycle integration. No financial writer hooks, destination/owner slice
226
+ index, provider operations, admission fence or automatic backfill is included.
227
+ Lifecycle/frontier integrations need separate raw-writer hooks and both financial
228
+ fact and evidence invalidators before claiming destination or owner coverage.
229
+
230
+ ## Same-bucket earnings summary updates
231
+
232
+ When a transfer stays in the same destination and currency, its derived earnings
233
+ update reads the unique summary once. It still validates subtraction, zero-count
234
+ reset/reapplication and safe integer/net arithmetic before deciding whether to
235
+ persist the result. Only an exactly unchanged existing nonzero summary can avoid
236
+ a final patch; zero-count deletion and malformed-summary errors remain required.
237
+ Moved buckets, unrecorded transfers, payout summaries and financial/risk callbacks
238
+ retain their existing behavior.
239
+
240
+ This is a private derived-summary optimization. Accepted and earnings-only
241
+ candidates still exceed the native read limit for 1,000 distinct destinations.
242
+ It does not lower the admitted financial maximum, establish complete observation
243
+ coverage or prove aggregate financial-hook capacity. Distinct-destination source
244
+ read reuse and complete capacity verification remain separate work.
@@ -20,6 +20,12 @@ The result is either `observed` with the refund document or `unavailable` with a
20
20
 
21
21
  The reader first checks one indexed legacy normalization row, then reads at most two rows for the exact global command key and at most two for the candidate provider refund ID. Command-key duplicate detection precedes account/PI/charge/currency qualification; a foreign duplicate cannot be filtered into apparent uniqueness. Duplicated provider refund IDs under different command keys also remain ambiguous. A unique observed row must match the original scope and retain positive safe integer original units and a canonical refund ID. Pending, failed and succeeded states remain distinct. Currency shape validation does not establish supported currency or input precision; the host uses the public currency helpers and original-charge contract.
22
22
 
23
+ For a receipt whose persisted `accountId` is absent, the reader additionally reads at most two settlement allocations by the exact original charge. Exactly one allocation must have the original payment-intent ID and currency, exactly one store and canonical unique recipient accounts with safe nonnegative integer transfer amounts. Multiple allocations or stores, affiliate-only routing, missing original PI and malformed or duplicate destinations stay unavailable. The existing public allocation reservation inserts the original transfer routing once and returns it unchanged on compatible replay; changed PI, currency or invoice identity rejects. Current mutable payment routing never establishes original merchant provenance. A normal same-PI payment update to another store cannot remap the allocation's original store.
24
+
25
+ An explicitly persisted refund account is never replaced by this fallback, including an empty or foreign value. Existing persisted-account destination receipts retain their prior semantics. Payment-only ownerless legacy receipts and ownerless destination history without an immutable allocation remain unavailable: current routing cannot reconstruct unknown original merchant identity. There is no migration, first-read ownership pin or metadata-based ownership guess.
26
+
27
+ The fallback returns a qualified account only in the observed result; it does not patch the refund, allocation or payment, change historical account indexes, select current user/community account mappings or backfill old records. Original PI, charge, currency and command selectors still match the receipt and allocation. The host must retain verified original provider-charge, immutable merchant/command/fingerprint and authorization contracts. Existing ingestion seller heuristics and the bounded 100-row late owner backfill are unchanged. Ownerless records can therefore remain absent from account-filtered history while this exact reader qualifies their immutable original allocation. Bounds are on documents rather than routing bytes; a rejected native read never establishes observed evidence or retry authority.
28
+
23
29
  `missing` is unknown synchronized evidence, never permission to create another refund. `observed` is also not financial completion or an assertion that every provider receipt has arrived. Reobserve when relevant data changes; the exact index discovers later inserts and metadata enrichment independently of a previously exhausted history cursor. Existing `paginateRefunds` retains its history semantics, including pinned cursors; a ten-page budget is per invocation, not a lifetime absence proof.
24
30
 
25
31
  ## Immutable correlation convention
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.35.0",
3
+ "version": "0.37.0",
4
4
  "description": "A Convex component for Stripe V2 Accounts API integration.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -0,0 +1,110 @@
1
+ // @vitest-environment edge-runtime
2
+ import { expect, it, vi } from "vitest";
3
+ import schema from "../component/schema.js";
4
+ import { BetterStripe } from "./index.js";
5
+ import type { RunCtx } from "./helpers.js";
6
+ import { components, initConvexTest } from "./setup.test.js";
7
+ import { componentRef } from "./webhooks/helpers.js";
8
+
9
+ it("captures and reads lossless evidence through the actual public SDK and component", async () => {
10
+ const t = initConvexTest();
11
+ t.registerComponent(
12
+ "betterStripe",
13
+ schema,
14
+ import.meta.glob("../component/**/*.ts"),
15
+ );
16
+ const client = new BetterStripe(components.betterStripe);
17
+ const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
18
+ const operationId = "\u0000".repeat(5000);
19
+ await t.mutation(
20
+ componentRef(
21
+ components.betterStripe,
22
+ "connect/mutations/claimReversalSlices",
23
+ ),
24
+ { operationId, sourceChargeId: "charge", mode: { kind: "full" } },
25
+ );
26
+ const source = await t.query(
27
+ componentRef(components.betterStripe, "connect/queries/getReversalOp"),
28
+ { operationId },
29
+ );
30
+ const saved = await client.operationEvidence.capture(ctx, {
31
+ sourceId: source._id,
32
+ });
33
+ expect(saved).toMatchObject({
34
+ coverage: "unknown",
35
+ status: "captured",
36
+ evidenceGeneration: 1,
37
+ });
38
+ expect(
39
+ (
40
+ await client.operationEvidence.original(ctx, {
41
+ headerId: saved.header!._id,
42
+ })
43
+ ).payload?.operationId,
44
+ ).toBe(operationId);
45
+ expect(
46
+ (
47
+ await client.operationEvidence.latest(ctx, {
48
+ headerId: saved.header!._id,
49
+ })
50
+ ).payload?.slices,
51
+ ).toEqual([]);
52
+ expect(
53
+ (
54
+ await client.operationEvidence.resolve(ctx, {
55
+ selector: "operationId",
56
+ value: operationId,
57
+ })
58
+ ).header?._id,
59
+ ).toBe(saved.header!._id);
60
+ expect(
61
+ (
62
+ await client.operationEvidence.headers(ctx, {
63
+ paginationOpts: { numItems: 1, cursor: null, id: 9 },
64
+ })
65
+ ).page,
66
+ ).toHaveLength(1);
67
+ });
68
+
69
+ it("rejects invented source bytes and page expansion before dispatch while retaining admitted selectors", async () => {
70
+ const client = new BetterStripe(components.betterStripe);
71
+ const ctx = {
72
+ runQuery: vi.fn().mockResolvedValue({
73
+ coverage: "unknown",
74
+ evidenceGeneration: 0,
75
+ header: null,
76
+ }),
77
+ runMutation: vi.fn(),
78
+ };
79
+ await expect(
80
+ client.operationEvidence.capture(ctx, {
81
+ sourceId: "source",
82
+ payload: { operationId: "invented" },
83
+ } as never),
84
+ ).rejects.toThrow();
85
+ await expect(
86
+ client.operationEvidence.capture(ctx, { sourceId: "" }),
87
+ ).rejects.toThrow();
88
+ await expect(
89
+ client.operationEvidence.original(ctx, {
90
+ headerId: "",
91
+ payloadIds: ["one", "two"],
92
+ } as never),
93
+ ).rejects.toThrow();
94
+ await expect(
95
+ client.operationEvidence.headers(ctx, {
96
+ paginationOpts: { numItems: 101, cursor: null },
97
+ }),
98
+ ).rejects.toThrow();
99
+ expect(ctx.runMutation).not.toHaveBeenCalled();
100
+ expect(ctx.runQuery).not.toHaveBeenCalled();
101
+ await client.operationEvidence.resolve(ctx, {
102
+ selector: "operationId",
103
+ value: "",
104
+ });
105
+ await client.operationEvidence.resolve(ctx, {
106
+ selector: "operationId",
107
+ value: "\u0000".repeat(5000),
108
+ });
109
+ expect(ctx.runQuery).toHaveBeenCalledTimes(2);
110
+ });
@@ -0,0 +1,92 @@
1
+ import type { Infer } from "convex/values";
2
+ import type { PaginationOptions, PaginationResult } from "convex/server";
3
+ import { z } from "zod";
4
+ import type {
5
+ captureResult,
6
+ headerDoc,
7
+ headerResult,
8
+ payloadDoc,
9
+ payloadResult,
10
+ } from "../component/operationEvidence/schema.js";
11
+ import { runMutationOrThrow, type Component, type RunCtx } from "./helpers.js";
12
+ import { observationPagination } from "./observationPagination.js";
13
+ import { componentRef } from "./webhooks/helpers.js";
14
+
15
+ export type OperationEvidenceHeader = Infer<typeof headerDoc>;
16
+ export type OperationEvidencePayload = Infer<typeof payloadDoc>;
17
+ export type OperationEvidenceHeaderResult = Infer<typeof headerResult>;
18
+ export type OperationEvidencePayloadResult = Infer<typeof payloadResult>;
19
+ export type OperationEvidenceCaptureResult = Infer<typeof captureResult>;
20
+ export type OperationEvidencePage =
21
+ PaginationResult<OperationEvidenceHeader> & {
22
+ coverage: "unknown";
23
+ evidenceGeneration: number | null;
24
+ };
25
+ const headerInput = z.object({ headerId: z.string().min(1).max(256) }).strict();
26
+
27
+ /** Trusted-host evidence maintenance/readers. No financial or provider operation. */
28
+ export class OperationEvidenceClient {
29
+ constructor(private component: Component) {}
30
+ async capture(
31
+ ctx: RunCtx,
32
+ input: { sourceId: string },
33
+ ): Promise<OperationEvidenceCaptureResult> {
34
+ const args = z
35
+ .object({ sourceId: z.string().min(1).max(256) })
36
+ .strict()
37
+ .parse(input);
38
+ return runMutationOrThrow(
39
+ ctx,
40
+ componentRef(this.component, "operationEvidence/mutations/capture"),
41
+ args,
42
+ );
43
+ }
44
+ async headers(
45
+ ctx: RunCtx,
46
+ input: { paginationOpts: PaginationOptions & { id?: number } },
47
+ ): Promise<OperationEvidencePage> {
48
+ const args = z
49
+ .object({ paginationOpts: observationPagination })
50
+ .strict()
51
+ .parse(input);
52
+ return ctx.runQuery(
53
+ componentRef(this.component, "operationEvidence/queries/headers"),
54
+ args,
55
+ );
56
+ }
57
+ async original(
58
+ ctx: RunCtx,
59
+ input: { headerId: string },
60
+ ): Promise<OperationEvidencePayloadResult> {
61
+ return ctx.runQuery(
62
+ componentRef(this.component, "operationEvidence/queries/original"),
63
+ headerInput.parse(input),
64
+ );
65
+ }
66
+ async latest(
67
+ ctx: RunCtx,
68
+ input: { headerId: string },
69
+ ): Promise<OperationEvidencePayloadResult> {
70
+ return ctx.runQuery(
71
+ componentRef(this.component, "operationEvidence/queries/latest"),
72
+ headerInput.parse(input),
73
+ );
74
+ }
75
+ async resolve(
76
+ ctx: RunCtx,
77
+ input: { selector: "operationId" | "sourceChargeId"; value: string },
78
+ ): Promise<OperationEvidenceHeaderResult> {
79
+ // Financial selectors are schema-admitted strings, not bounded account/user IDs.
80
+ const args = z
81
+ .object({
82
+ selector: z.enum(["operationId", "sourceChargeId"]),
83
+ value: z.string(),
84
+ })
85
+ .strict()
86
+ .parse(input);
87
+ return ctx.runQuery(
88
+ componentRef(this.component, "operationEvidence/queries/resolve"),
89
+ args,
90
+ );
91
+ }
92
+ }
@@ -70,3 +70,11 @@ export type {
70
70
  RefundCommandNormalizationOptions,
71
71
  RefundCommandNormalizationResult,
72
72
  } from "./connect/refundCommandNormalization.js";
73
+ export type {
74
+ OperationEvidenceHeader,
75
+ OperationEvidencePayload,
76
+ OperationEvidenceHeaderResult,
77
+ OperationEvidencePayloadResult,
78
+ OperationEvidenceCaptureResult,
79
+ OperationEvidencePage,
80
+ } from "./operationEvidence.js";
@@ -1,3 +1,4 @@
1
+ import { OperationEvidenceClient } from "./operationEvidence.js";
1
2
  import {
2
3
  normalizeRefundCommandBindings,
3
4
  type RefundCommandNormalizationOptions,
@@ -23,6 +24,9 @@ import { componentRef } from "./webhooks/helpers.js";
23
24
  /** Shared component readers inherited by BetterStripe. */
24
25
  export class ReadContractClient {
25
26
  constructor(public component: Component) {}
27
+ get operationEvidence() {
28
+ return new OperationEvidenceClient(this.component);
29
+ }
26
30
 
27
31
  /** Trusted-host projection maintenance; never a financial or provider operation. */
28
32
  normalizeRefundCommandBindings(
@@ -67,6 +67,11 @@ import type * as lib_idempotency from "../lib/idempotency.js";
67
67
  import type * as lib_paymentSeller from "../lib/paymentSeller.js";
68
68
  import type * as lib_reversals from "../lib/reversals.js";
69
69
  import type * as lib_stripeFactory from "../lib/stripeFactory.js";
70
+ import type * as operationEvidence_canonical from "../operationEvidence/canonical.js";
71
+ import type * as operationEvidence_helpers from "../operationEvidence/helpers.js";
72
+ import type * as operationEvidence_maintenance from "../operationEvidence/maintenance.js";
73
+ import type * as operationEvidence_mutations from "../operationEvidence/mutations.js";
74
+ import type * as operationEvidence_queries from "../operationEvidence/queries.js";
70
75
  import type * as payoutPolicy_adoption from "../payoutPolicy/adoption.js";
71
76
  import type * as payoutPolicy_expiry from "../payoutPolicy/expiry.js";
72
77
  import type * as payoutPolicy_helpers from "../payoutPolicy/helpers.js";
@@ -184,6 +189,11 @@ const fullApi: ApiFromModules<{
184
189
  "lib/paymentSeller": typeof lib_paymentSeller;
185
190
  "lib/reversals": typeof lib_reversals;
186
191
  "lib/stripeFactory": typeof lib_stripeFactory;
192
+ "operationEvidence/canonical": typeof operationEvidence_canonical;
193
+ "operationEvidence/helpers": typeof operationEvidence_helpers;
194
+ "operationEvidence/maintenance": typeof operationEvidence_maintenance;
195
+ "operationEvidence/mutations": typeof operationEvidence_mutations;
196
+ "operationEvidence/queries": typeof operationEvidence_queries;
187
197
  "payoutPolicy/adoption": typeof payoutPolicy_adoption;
188
198
  "payoutPolicy/expiry": typeof payoutPolicy_expiry;
189
199
  "payoutPolicy/helpers": typeof payoutPolicy_helpers;