@fantastic.dev/better-stripe 0.34.0 → 0.35.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.
- package/CHANGELOG.md +35 -0
- package/README.md +1 -1
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +486 -2
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts +243 -1
- package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +486 -2
- package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +243 -1
- package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
- package/dist/client/connect/refundCommandEvidence.d.ts +14 -0
- package/dist/client/connect/refundCommandEvidence.d.ts.map +1 -0
- package/dist/client/connect/refundCommandEvidence.js +20 -0
- package/dist/client/connect/refundCommandEvidence.js.map +1 -0
- package/dist/client/connect/refundCommandNormalization.d.ts +11 -0
- package/dist/client/connect/refundCommandNormalization.d.ts.map +1 -0
- package/dist/client/connect/refundCommandNormalization.js +12 -0
- package/dist/client/connect/refundCommandNormalization.js.map +1 -0
- package/dist/client/financialObservations.d.ts +42 -0
- package/dist/client/financialObservations.d.ts.map +1 -0
- package/dist/client/financialObservations.js +58 -0
- package/dist/client/financialObservations.js.map +1 -0
- package/dist/client/financialOwnership.d.ts +52 -0
- package/dist/client/financialOwnership.d.ts.map +1 -0
- package/dist/client/financialOwnership.js +72 -0
- package/dist/client/financialOwnership.js.map +1 -0
- package/dist/client/index.d.ts +2 -2
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +2 -2
- package/dist/client/index.js.map +1 -1
- package/dist/client/observationPagination.d.ts +10 -0
- package/dist/client/observationPagination.d.ts.map +1 -0
- package/dist/client/observationPagination.js +12 -0
- package/dist/client/observationPagination.js.map +1 -0
- package/dist/client/publicTypes.d.ts +5 -0
- package/dist/client/publicTypes.d.ts.map +1 -1
- package/dist/client/readContracts.d.ts +29 -0
- package/dist/client/readContracts.d.ts.map +1 -1
- package/dist/client/readContracts.js +10 -0
- package/dist/client/readContracts.js.map +1 -1
- package/dist/client/transferObservations.d.ts +59 -0
- package/dist/client/transferObservations.d.ts.map +1 -0
- package/dist/client/transferObservations.js +82 -0
- package/dist/client/transferObservations.js.map +1 -0
- package/dist/component/_generated/component.d.ts +506 -0
- package/dist/component/_generated/component.d.ts.map +1 -1
- package/dist/component/affiliateRecovery/mutations.d.ts.map +1 -1
- package/dist/component/affiliateRecovery/mutations.js +4 -1
- package/dist/component/affiliateRecovery/mutations.js.map +1 -1
- package/dist/component/connect/mutations.d.ts.map +1 -1
- package/dist/component/connect/mutations.js +18 -2
- package/dist/component/connect/mutations.js.map +1 -1
- package/dist/component/connect/queries.d.ts +8 -0
- package/dist/component/connect/queries.d.ts.map +1 -1
- package/dist/component/connect/reversalClaims.d.ts.map +1 -1
- package/dist/component/connect/reversalClaims.js +7 -1
- package/dist/component/connect/reversalClaims.js.map +1 -1
- package/dist/component/connect/reversalReceipts.d.ts.map +1 -1
- package/dist/component/connect/reversalReceipts.js +2 -0
- package/dist/component/connect/reversalReceipts.js.map +1 -1
- package/dist/component/connect/schema.d.ts +11 -1
- package/dist/component/connect/schema.d.ts.map +1 -1
- package/dist/component/connect/schema.js +9 -1
- package/dist/component/connect/schema.js.map +1 -1
- package/dist/component/connect/validators.d.ts +9 -1
- package/dist/component/connect/validators.d.ts.map +1 -1
- package/dist/component/connect/validators.js +2 -0
- package/dist/component/connect/validators.js.map +1 -1
- package/dist/component/earnings/triggers.d.ts +426 -2
- package/dist/component/earnings/triggers.d.ts.map +1 -1
- package/dist/component/earnings/triggers.js +7 -1
- package/dist/component/earnings/triggers.js.map +1 -1
- package/dist/component/financialObservations/continuation.d.ts +7 -0
- package/dist/component/financialObservations/continuation.d.ts.map +1 -0
- package/dist/component/financialObservations/continuation.js +131 -0
- package/dist/component/financialObservations/continuation.js.map +1 -0
- package/dist/component/financialObservations/generations.d.ts +6 -0
- package/dist/component/financialObservations/generations.d.ts.map +1 -0
- package/dist/component/financialObservations/generations.js +46 -0
- package/dist/component/financialObservations/generations.js.map +1 -0
- package/dist/component/financialObservations/mutations.d.ts +62 -0
- package/dist/component/financialObservations/mutations.d.ts.map +1 -0
- package/dist/component/financialObservations/mutations.js +69 -0
- package/dist/component/financialObservations/mutations.js.map +1 -0
- package/dist/component/financialObservations/queries.d.ts +307 -0
- package/dist/component/financialObservations/queries.d.ts.map +1 -0
- package/dist/component/financialObservations/queries.js +219 -0
- package/dist/component/financialObservations/queries.js.map +1 -0
- package/dist/component/financialObservations/schema.d.ts +182 -0
- package/dist/component/financialObservations/schema.d.ts.map +1 -0
- package/dist/component/financialObservations/schema.js +53 -0
- package/dist/component/financialObservations/schema.js.map +1 -0
- package/dist/component/financialObservations/settlement.d.ts +7 -0
- package/dist/component/financialObservations/settlement.d.ts.map +1 -0
- package/dist/component/financialObservations/settlement.js +118 -0
- package/dist/component/financialObservations/settlement.js.map +1 -0
- package/dist/component/financialObservations/settlementHelpers.d.ts +46 -0
- package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -0
- package/dist/component/financialObservations/settlementHelpers.js +70 -0
- package/dist/component/financialObservations/settlementHelpers.js.map +1 -0
- package/dist/component/financialObservations/transferBatches.d.ts +12 -0
- package/dist/component/financialObservations/transferBatches.d.ts.map +1 -0
- package/dist/component/financialObservations/transferBatches.js +76 -0
- package/dist/component/financialObservations/transferBatches.js.map +1 -0
- package/dist/component/financialObservations/transferContinuation.d.ts +5 -0
- package/dist/component/financialObservations/transferContinuation.d.ts.map +1 -0
- package/dist/component/financialObservations/transferContinuation.js +35 -0
- package/dist/component/financialObservations/transferContinuation.js.map +1 -0
- package/dist/component/financialObservations/transferContinuationState.d.ts +8 -0
- package/dist/component/financialObservations/transferContinuationState.d.ts.map +1 -0
- package/dist/component/financialObservations/transferContinuationState.js +69 -0
- package/dist/component/financialObservations/transferContinuationState.js.map +1 -0
- package/dist/component/financialObservations/transferContinuationSteps.d.ts +5 -0
- package/dist/component/financialObservations/transferContinuationSteps.d.ts.map +1 -0
- package/dist/component/financialObservations/transferContinuationSteps.js +174 -0
- package/dist/component/financialObservations/transferContinuationSteps.js.map +1 -0
- package/dist/component/financialObservations/transferHelpers.d.ts +18 -0
- package/dist/component/financialObservations/transferHelpers.d.ts.map +1 -0
- package/dist/component/financialObservations/transferHelpers.js +37 -0
- package/dist/component/financialObservations/transferHelpers.js.map +1 -0
- package/dist/component/financialObservations/transferReferenceSchema.d.ts +56 -0
- package/dist/component/financialObservations/transferReferenceSchema.d.ts.map +1 -0
- package/dist/component/financialObservations/transferReferenceSchema.js +21 -0
- package/dist/component/financialObservations/transferReferenceSchema.js.map +1 -0
- package/dist/component/financialObservations/transferSchema.d.ts +237 -0
- package/dist/component/financialObservations/transferSchema.d.ts.map +1 -0
- package/dist/component/financialObservations/transferSchema.js +65 -0
- package/dist/component/financialObservations/transferSchema.js.map +1 -0
- package/dist/component/financialObservations/transfers.d.ts +7 -0
- package/dist/component/financialObservations/transfers.d.ts.map +1 -0
- package/dist/component/financialObservations/transfers.js +79 -0
- package/dist/component/financialObservations/transfers.js.map +1 -0
- package/dist/component/financialOwnership/helpers.d.ts +37 -0
- package/dist/component/financialOwnership/helpers.d.ts.map +1 -0
- package/dist/component/financialOwnership/helpers.js +76 -0
- package/dist/component/financialOwnership/helpers.js.map +1 -0
- package/dist/component/financialOwnership/mutations.d.ts +28 -0
- package/dist/component/financialOwnership/mutations.d.ts.map +1 -0
- package/dist/component/financialOwnership/mutations.js +74 -0
- package/dist/component/financialOwnership/mutations.js.map +1 -0
- package/dist/component/financialOwnership/queries.d.ts +57 -0
- package/dist/component/financialOwnership/queries.d.ts.map +1 -0
- package/dist/component/financialOwnership/queries.js +50 -0
- package/dist/component/financialOwnership/queries.js.map +1 -0
- package/dist/component/financialOwnership/schema.d.ts +140 -0
- package/dist/component/financialOwnership/schema.d.ts.map +1 -0
- package/dist/component/financialOwnership/schema.js +35 -0
- package/dist/component/financialOwnership/schema.js.map +1 -0
- package/dist/component/payoutRelease/queries.d.ts +2 -2
- package/dist/component/payoutRelease/queries.d.ts.map +1 -1
- package/dist/component/refundHistory/commandBinding.d.ts +17 -0
- package/dist/component/refundHistory/commandBinding.d.ts.map +1 -0
- package/dist/component/refundHistory/commandBinding.js +41 -0
- package/dist/component/refundHistory/commandBinding.js.map +1 -0
- package/dist/component/refundHistory/commandEvidence.d.ts +50 -0
- package/dist/component/refundHistory/commandEvidence.d.ts.map +1 -0
- package/dist/component/refundHistory/commandEvidence.js +54 -0
- package/dist/component/refundHistory/commandEvidence.js.map +1 -0
- package/dist/component/refundHistory/commandEvidenceValidator.d.ts +89 -0
- package/dist/component/refundHistory/commandEvidenceValidator.d.ts.map +1 -0
- package/dist/component/refundHistory/commandEvidenceValidator.js +8 -0
- package/dist/component/refundHistory/commandEvidenceValidator.js.map +1 -0
- package/dist/component/refundHistory/commandFields.d.ts +8 -0
- package/dist/component/refundHistory/commandFields.d.ts.map +1 -0
- package/dist/component/refundHistory/commandFields.js +9 -0
- package/dist/component/refundHistory/commandFields.js.map +1 -0
- package/dist/component/refundHistory/mutations.d.ts +8 -0
- package/dist/component/refundHistory/mutations.d.ts.map +1 -0
- package/dist/component/refundHistory/mutations.js +25 -0
- package/dist/component/refundHistory/mutations.js.map +1 -0
- package/dist/component/refundHistory/queries.d.ts +51 -0
- package/dist/component/refundHistory/queries.d.ts.map +1 -1
- package/dist/component/refundHistory/queries.js +14 -0
- package/dist/component/refundHistory/queries.js.map +1 -1
- package/dist/component/schema.d.ts +243 -1
- package/dist/component/schema.js +12 -0
- package/dist/component/schema.js.map +1 -1
- package/dist/component/settlement/mutations.d.ts.map +1 -1
- package/dist/component/settlement/mutations.js +5 -1
- package/dist/component/settlement/mutations.js.map +1 -1
- package/dist/shared/refundCommandScope.d.ts +10 -0
- package/dist/shared/refundCommandScope.d.ts.map +1 -0
- package/dist/shared/refundCommandScope.js +9 -0
- package/dist/shared/refundCommandScope.js.map +1 -0
- package/docs/financial-observations.md +159 -0
- package/docs/financial-ownership.md +54 -0
- package/docs/refund-command-evidence.md +49 -0
- package/package.json +5 -2
- package/src/client/connect/refundCommandEvidence.ts +41 -0
- package/src/client/connect/refundCommandNormalization.ts +28 -0
- package/src/client/financialObservations.test.ts +109 -0
- package/src/client/financialObservations.ts +106 -0
- package/src/client/financialOwnership.test.ts +80 -0
- package/src/client/financialOwnership.ts +116 -0
- package/src/client/index.ts +2 -2
- package/src/client/observationPagination.ts +11 -0
- package/src/client/publicTypes.ts +37 -0
- package/src/client/readContracts.ts +21 -0
- package/src/client/refund-command-evidence.test.ts +68 -0
- package/src/client/refund-command-normalization.test.ts +61 -0
- package/src/client/transferContinuation.test.ts +94 -0
- package/src/client/transferObservations.test.ts +98 -0
- package/src/client/transferObservations.ts +180 -0
- package/src/component/_generated/api.ts +44 -0
- package/src/component/_generated/component.ts +590 -0
- package/src/component/affiliateRecovery/mutations.ts +10 -1
- package/src/component/connect/mutations.ts +29 -2
- package/src/component/connect/reversalClaims.ts +19 -1
- package/src/component/connect/reversalReceipts.ts +2 -0
- package/src/component/connect/schema.ts +9 -1
- package/src/component/connect/validators.ts +2 -0
- package/src/component/core/reset.test.ts +8 -1
- package/src/component/earnings/earnings-totals.test.ts +14 -10
- package/src/component/earnings/triggers.ts +9 -1
- package/src/component/financialObservations/continuation.test.ts +445 -0
- package/src/component/financialObservations/continuation.ts +159 -0
- package/src/component/financialObservations/generations.ts +53 -0
- package/src/component/financialObservations/mutations.ts +75 -0
- package/src/component/financialObservations/observation-boundaries.test.ts +466 -0
- package/src/component/financialObservations/queries.ts +246 -0
- package/src/component/financialObservations/schema.ts +68 -0
- package/src/component/financialObservations/settlement-observations.test.ts +86 -0
- package/src/component/financialObservations/settlement.ts +142 -0
- package/src/component/financialObservations/settlementHelpers.ts +92 -0
- package/src/component/financialObservations/transfer-batches.test.ts +61 -0
- package/src/component/financialObservations/transfer-boundaries.test.ts +116 -0
- package/src/component/financialObservations/transfer-continuation-guards.test.ts +428 -0
- package/src/component/financialObservations/transfer-continuation.test.ts +154 -0
- package/src/component/financialObservations/transfer-observations.test.ts +212 -0
- package/src/component/financialObservations/transfer-overflow.test.ts +181 -0
- package/src/component/financialObservations/transfer-writers.test.ts +162 -0
- package/src/component/financialObservations/transferBatches.ts +96 -0
- package/src/component/financialObservations/transferContinuation.ts +53 -0
- package/src/component/financialObservations/transferContinuationState.ts +85 -0
- package/src/component/financialObservations/transferContinuationSteps.ts +232 -0
- package/src/component/financialObservations/transferHelpers.ts +38 -0
- package/src/component/financialObservations/transferReferenceSchema.ts +20 -0
- package/src/component/financialObservations/transferSchema.ts +74 -0
- package/src/component/financialObservations/transfers.ts +99 -0
- package/src/component/financialOwnership/financial-ownership.test.ts +102 -0
- package/src/component/financialOwnership/helpers.ts +98 -0
- package/src/component/financialOwnership/mutations.ts +83 -0
- package/src/component/financialOwnership/ownership-boundaries.test.ts +308 -0
- package/src/component/financialOwnership/queries.ts +65 -0
- package/src/component/financialOwnership/schema.ts +35 -0
- package/src/component/refundHistory/command-evidence.test.ts +288 -0
- package/src/component/refundHistory/command-normalization-resource.test.ts +77 -0
- package/src/component/refundHistory/command-normalization.test.ts +229 -0
- package/src/component/refundHistory/command-provenance.test.ts +59 -0
- package/src/component/refundHistory/commandBinding.ts +54 -0
- package/src/component/refundHistory/commandEvidence.ts +71 -0
- package/src/component/refundHistory/commandEvidenceValidator.ts +18 -0
- package/src/component/refundHistory/commandFields.ts +9 -0
- package/src/component/refundHistory/mutations.ts +33 -0
- package/src/component/refundHistory/queries.ts +15 -0
- package/src/component/schema.ts +22 -0
- package/src/component/settlement/mutations.ts +5 -1
- package/src/shared/refundCommandScope.ts +19 -0
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
# Financial bucket ownership provenance
|
|
2
|
+
|
|
3
|
+
`betterStripe.financialOwnership` records immutable host ownership of a financial bucket. It supports physical Stripe account keys and opaque logical keys, including affiliate earnings that have no provider account yet. This is provenance, not a second money ledger. Registration does not rewrite source keys, amounts, balances, transfers or payout history.
|
|
4
|
+
|
|
5
|
+
All registration, lookup and discovery responses report `coverage: "unknown"`. Exhausting discovery means only that the registered ownership rows for that exact scope were enumerated. It does not establish complete financial history, absence of outstanding work, current provider usability or permission to close an account. No API accepts a `complete` flag. Source observations, legacy backfill, financial attempt admission and host business-policy guards require separate accepted integrations.
|
|
6
|
+
|
|
7
|
+
## Trusted host boundary
|
|
8
|
+
|
|
9
|
+
Call this API only from an authorized server adapter. Authenticate the current host actor and derive its allowed owner scope before supplying `userId` and optional `orgId`. Neither a bucket key, cursor nor a claimed user identifier is authorization. Component lookup intentionally returns provenance for a trusted host; do not expose it as an unrestricted browser query.
|
|
10
|
+
|
|
11
|
+
For a new physical registration, the component verifies exact current reciprocal mapping through the unique personal resolver or bounded organization-scope proof. A historical registration requires one exact closed-account owner record. Duplicate mappings, duplicate closure records, foreign ownership, unresolved closure, ownerless history and malformed provider keys refuse registration. Pending capability/KYC is unrelated to ownership and is not interpreted as readiness.
|
|
12
|
+
|
|
13
|
+
Logical ownership is a host-domain fact. Before registering it, the host must verify the actual immutable source record and its owner, then supply its stable integration and record identity. Arbitrary key spelling such as `user:123` or `acct_example` never implies ownership. A proof reference records the host's verified source; it alone does not establish coverage. Unverified legacy keys remain unknown. An absent host migration/integration cannot be replaced with a guessed alias list or account timestamp.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
// Server only, after current-actor authorization and actual source-owner verification.
|
|
17
|
+
await betterStripe.financialOwnership.register(ctx, {
|
|
18
|
+
bucketKey: source.financialBucketKey,
|
|
19
|
+
kind: "logical",
|
|
20
|
+
userId: source.verifiedOwnerUserId,
|
|
21
|
+
source: {
|
|
22
|
+
integration: "host-affiliate-registration-v1",
|
|
23
|
+
recordId: source.id,
|
|
24
|
+
},
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
// Server-derived personal account selector; physical proof is component-owned.
|
|
28
|
+
await betterStripe.financialOwnership.register(ctx, {
|
|
29
|
+
bucketKey: verifiedAccountId,
|
|
30
|
+
kind: "stripe_account",
|
|
31
|
+
userId: authenticatedOwnerId,
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Immutable receipts and bounded discovery
|
|
36
|
+
|
|
37
|
+
Exact-key lookup returns `status: "unknown"` for an unregistered bucket or `status: "registered"` with its immutable registration. Matching registration retries reuse the same receipt. Changing its owner, kind or logical source identity rejects atomically. A previously verified physical receipt survives closure and active mapping removal; replay returns original ownership provenance, not a fresh current-account or readiness assertion.
|
|
38
|
+
|
|
39
|
+
Owner scope is the exact `userId` and optional `orgId` tuple. Organization-owned registrations never appear in a personal discovery query, even when they retain the same user identifier. Hosts must authorize both selectors and retain historical organization context rather than inheriting it into personal ownership.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
const page = await betterStripe.financialOwnership.discover(ctx, {
|
|
43
|
+
userId: authenticatedOwnerId,
|
|
44
|
+
paginationOpts: { numItems: 25, cursor: previousCursor },
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Pages use the component-compatible indexed paginator, at most 100 requested rows with fixed 200-row/1 MB read bounds. Preserve `continueCursor`, `isDone`, optional split metadata and native pagination identity. A full last page can require an empty continuation before `isDone` becomes true. Keep cursors scoped to the authorized owner query; a cursor is not an immutable snapshot.
|
|
49
|
+
|
|
50
|
+
The returned generation advances only when a new bucket is registered in that owner scope. Matching replay does not advance it. It is a registration provenance generation, not a financial revision. Registration itself has no financial writer observers. The separate [settlement source observations](./financial-observations.md) integration observes bounded raw allocation destinations only and has its own diagnostic generations; it does not establish complete financial coverage. Newly written or unmapped records outside that producer are still unobserved. No completeness claim is available at all.
|
|
51
|
+
|
|
52
|
+
## Verification boundary
|
|
53
|
+
|
|
54
|
+
Real-schema tests exercise current and closed ownership, explicit logical provenance, ambiguity/refusal, replay/conflict, organization isolation, pagination beyond 100 rows and unchanged financial records. Public SDK tests dispatch through the actual component without a Stripe secret. Native verification must use an isolated component runtime. These tests establish registration/discovery behavior only; they perform no provider closure, bank payout, settlement or live financial acceptance.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Refund-command evidence
|
|
2
|
+
|
|
3
|
+
The package provides a bounded component reader for an opaque host refund-command key. It observes synchronized refund records; it does not contact Stripe, prove provider absence, authorize a retry or certify completed money. Public artifact verification and host adoption are separate from source acceptance.
|
|
4
|
+
|
|
5
|
+
```ts
|
|
6
|
+
const evidence = await stripe.getRefundCommandEvidence(ctx, {
|
|
7
|
+
commandKey: originalCommand.providerIdempotencyKey,
|
|
8
|
+
stripeAccountId: originalCommand.originalMerchantAccount,
|
|
9
|
+
stripePaymentIntentId: originalCommand.stripePaymentIntentId,
|
|
10
|
+
stripeChargeId: originalCommand.stripeChargeId,
|
|
11
|
+
currency: originalCommand.currency,
|
|
12
|
+
});
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Authenticate and authorize the host caller before this call. Derive every selector from the original immutable command and verified payment routing. Current community owners or replacement accounts must not remap old payments. The server-only [Vite reference](../example/convex/connect/refundCommandEvidence.ts) verifies a reciprocal unique personal mapping against the original account; demo personas are not authentication. The host still qualifies the original command fingerprint, buyer, invoice allocation, amount/reason, permission and lifecycle.
|
|
16
|
+
|
|
17
|
+
## Result and bounds
|
|
18
|
+
|
|
19
|
+
The result is either `observed` with the refund document or `unavailable` with a reason: `missing`, `normalization_incomplete`, `ambiguous`, `correlation_conflict`, `scope_mismatch` or `invalid_receipt`.
|
|
20
|
+
|
|
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
|
+
|
|
23
|
+
`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
|
+
|
|
25
|
+
## Immutable correlation convention
|
|
26
|
+
|
|
27
|
+
Before the first provider execution, the host may put its existing stable opaque identity into `metadata.betterStripeRefundCommand` and its immutable fingerprint into a separate metadata field. For example, Dojo's already prepared identity `dojo-refund:<commandId>:v1` and original fingerprint can be reused without generating a replacement command or idempotency key. The package does not inject metadata or change `createRefund` parameters. Do not add this convention to an already prepared or executed provider payload if that would change parameters of a same-key replay; hold or reconcile such an older request under its actual original contract.
|
|
28
|
+
|
|
29
|
+
Command keys are 16–200 canonical ASCII letters, digits, colons, underscores or hyphens. They are correlation selectors, not credentials or authorization. Keep private data out of provider metadata. The host independently verifies the fingerprint and original terms; the reader does not equate matching metadata with permission.
|
|
30
|
+
|
|
31
|
+
Every current refund upsert normalizes existing metadata before applying incoming metadata. The first known key remains indexed. An omitted metadata field on a partial upsert adds no contradictory fact and preserves the binding. Explicitly present missing, invalid or different correlation metadata after a known binding latches a conflict, even if a later event restores the former raw metadata. Original raw provider fields are retained; correlation is a projection on the existing refund row, not another financial ledger.
|
|
32
|
+
|
|
33
|
+
`refundCommandObservedAt` is the time the normalizer first observed that binding. Neither it nor the row's insertion time proves original provider creation time. A legacy row's key is first-known component metadata, not a claim about what the original Stripe request contained. Unknown original request provenance remains the host's held reconciliation case.
|
|
34
|
+
|
|
35
|
+
## Legacy rollout hold
|
|
36
|
+
|
|
37
|
+
Any row without normalization version 1 keeps the reader unavailable globally. Otherwise an unindexed old metadata key plus an indexed newer duplicate could appear falsely unique. The indexed coverage hold is bounded and deliberately conservative, even for an unrelated legacy row.
|
|
38
|
+
|
|
39
|
+
Trusted host maintenance can drain the pending version index through `normalizeRefundCommandBindings(ctx, { limit })`, with an explicit integer limit from 1 to 100. Each transaction reads at most that many pending rows, patches only the reviewed correlation projection/version fields, then checks at most one remaining pending row. The result `{ normalized, hasMore }` reports this batch and current pending coverage. Processed rows leave the pending index, so repeat while `hasMore` is true without a full-history scan, cursor rewind or lifetime cap. Concurrent calls use Convex transactional conflict handling; a repeated call after drainage is an idempotent empty batch.
|
|
40
|
+
|
|
41
|
+
This global maintenance operation requires a trusted platform operator or internal deployment task. Never expose it to community sellers, demo personas or an unauthenticated browser. The [Vite maintenance reference](../example/convex/connect/refundCommandNormalization.ts) is deliberately an unregistered server helper. Host authentication and platform authorization must happen before calling it. Raw metadata, original account/PI/charge/currency/amount/status and financial fields remain unchanged; the same first-known-binding/conflict normalizer used by ingestion is reused. Rows without correlation become normalized unbound records; invalid reserved metadata latches a conflict. An old valid key plus an existing newer match becomes ambiguous after normalization, not falsely unique.
|
|
42
|
+
|
|
43
|
+
`hasMore: false` observes only the current trusted-writer component backlog at the transaction snapshot. It does not prove provider history is complete, prevent later legacy ingestion or authorize any refund request. A later pending row reactivates the reader’s global hold until another bounded drain. Current upserts can reobserve individual legacy rows with the same normalizer. Until all pending rows are normalized, this reader cannot report an observed unique match. Normalization coverage means only the current records written through the trusted component contract have been normalized. It does not establish complete historical Stripe ingestion, discover refunds never delivered to the component or authorize a provider retry.
|
|
44
|
+
|
|
45
|
+
## Native resource limits
|
|
46
|
+
|
|
47
|
+
The per-call limit bounds rows, not bytes. Large raw metadata can make a batch exceed native transaction read/write budgets even within the 100-row limit. Adding projection fields to an individual legacy document near the native document ceiling can also fail. This primitive does not promise capacity for every schema-legal legacy backlog.
|
|
48
|
+
|
|
49
|
+
A native failure rejects the mutation atomically: no partial normalization is committed and no completion result is returned. The unnormalized rows remain pending, so the exact reader stays held. A smaller limit can reduce batch bytes, but cannot solve an individual document ceiling. Keep that case held for investigation; do not skip/delete rows or rewrite raw metadata to manufacture completion. An empty native-dispatch check is not large-backlog capacity evidence.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fantastic.dev/better-stripe",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.35.0",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -68,7 +68,10 @@
|
|
|
68
68
|
"docs/invoice-payment-pages.md",
|
|
69
69
|
"docs/checkout-session-pages.md",
|
|
70
70
|
"docs/refund-context.md",
|
|
71
|
-
"docs/
|
|
71
|
+
"docs/refund-command-evidence.md",
|
|
72
|
+
"docs/personal-account-mapping.md",
|
|
73
|
+
"docs/financial-ownership.md",
|
|
74
|
+
"docs/financial-observations.md"
|
|
72
75
|
],
|
|
73
76
|
"scripts": {
|
|
74
77
|
"build": "tsc --project ./tsconfig.build.json",
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { Infer } from "convex/values";
|
|
2
|
+
import { z } from "zod";
|
|
3
|
+
import { assertRefundCommandScope } from "../../shared/refundCommandScope.js";
|
|
4
|
+
import type { refundCommandEvidenceValidator } from "../../component/refundHistory/commandEvidenceValidator.js";
|
|
5
|
+
import type { Component, RunCtx } from "../helpers.js";
|
|
6
|
+
import { componentRef } from "../webhooks/helpers.js";
|
|
7
|
+
|
|
8
|
+
export type RefundCommandEvidence = Infer<
|
|
9
|
+
typeof refundCommandEvidenceValidator
|
|
10
|
+
>;
|
|
11
|
+
export type RefundCommandEvidenceOptions = {
|
|
12
|
+
commandKey: string;
|
|
13
|
+
stripeAccountId: string;
|
|
14
|
+
stripePaymentIntentId: string;
|
|
15
|
+
stripeChargeId: string;
|
|
16
|
+
currency: string;
|
|
17
|
+
};
|
|
18
|
+
const optionsSchema = z
|
|
19
|
+
.object({
|
|
20
|
+
commandKey: z.string(),
|
|
21
|
+
stripeAccountId: z.string(),
|
|
22
|
+
stripePaymentIntentId: z.string(),
|
|
23
|
+
stripeChargeId: z.string(),
|
|
24
|
+
currency: z.string(),
|
|
25
|
+
})
|
|
26
|
+
.strict();
|
|
27
|
+
|
|
28
|
+
/** Host authorization and original command qualification are required before this observation. */
|
|
29
|
+
export async function getRefundCommandEvidence(
|
|
30
|
+
component: Component,
|
|
31
|
+
ctx: RunCtx,
|
|
32
|
+
input: RefundCommandEvidenceOptions,
|
|
33
|
+
): Promise<RefundCommandEvidence> {
|
|
34
|
+
const { stripeAccountId, ...options } = optionsSchema.parse(input);
|
|
35
|
+
const scope = { ...options, accountId: stripeAccountId };
|
|
36
|
+
assertRefundCommandScope(scope);
|
|
37
|
+
return ctx.runQuery(
|
|
38
|
+
componentRef(component, "refundHistory/queries/getRefundCommandEvidence"),
|
|
39
|
+
scope,
|
|
40
|
+
);
|
|
41
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { runMutationOrThrow, type RunCtx, type Component } from "../helpers.js";
|
|
3
|
+
import { componentRef } from "../webhooks/helpers.js";
|
|
4
|
+
export type RefundCommandNormalizationOptions = { limit: number };
|
|
5
|
+
export type RefundCommandNormalizationResult = {
|
|
6
|
+
normalized: number;
|
|
7
|
+
hasMore: boolean;
|
|
8
|
+
};
|
|
9
|
+
const optionsSchema = z
|
|
10
|
+
.object({ limit: z.number().int().min(1).max(100) })
|
|
11
|
+
.strict();
|
|
12
|
+
|
|
13
|
+
/** Trusted-host projection maintenance; a drained component backlog is not complete provider history. */
|
|
14
|
+
export async function normalizeRefundCommandBindings(
|
|
15
|
+
component: Component,
|
|
16
|
+
ctx: RunCtx,
|
|
17
|
+
opts: RefundCommandNormalizationOptions,
|
|
18
|
+
): Promise<RefundCommandNormalizationResult> {
|
|
19
|
+
const args = optionsSchema.parse(opts);
|
|
20
|
+
return runMutationOrThrow(
|
|
21
|
+
ctx,
|
|
22
|
+
componentRef(
|
|
23
|
+
component,
|
|
24
|
+
"refundHistory/mutations/normalizeRefundCommandBindings",
|
|
25
|
+
),
|
|
26
|
+
args,
|
|
27
|
+
);
|
|
28
|
+
}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
// @vitest-environment edge-runtime
|
|
2
|
+
import { componentRef } from "./webhooks/helpers.js";
|
|
3
|
+
import { expect, it, vi } from "vitest";
|
|
4
|
+
import schema from "../component/schema.js";
|
|
5
|
+
import { BetterStripe } from "./index.js";
|
|
6
|
+
import type { RunCtx } from "./helpers.js";
|
|
7
|
+
import { components, initConvexTest } from "./setup.test.js";
|
|
8
|
+
|
|
9
|
+
it("exposes UNKNOWN source and owner diagnostics through the actual component without Stripe credentials", 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
|
+
await client.financialOwnership.register(ctx, {
|
|
19
|
+
bucketKey: "opaque",
|
|
20
|
+
kind: "logical",
|
|
21
|
+
userId: "user",
|
|
22
|
+
source: { integration: "host", recordId: "fact" },
|
|
23
|
+
});
|
|
24
|
+
const row = await t.mutation(
|
|
25
|
+
componentRef(
|
|
26
|
+
components.betterStripe,
|
|
27
|
+
"settlement/mutations/reserveSettlementAllocation",
|
|
28
|
+
),
|
|
29
|
+
{
|
|
30
|
+
sourceChargeId: "ch_sdk",
|
|
31
|
+
gross: 3,
|
|
32
|
+
currency: "usd",
|
|
33
|
+
processingFee: 1,
|
|
34
|
+
platformNet: 1,
|
|
35
|
+
transfers: [{ destinationAccountId: "opaque", role: "store", amount: 1 }],
|
|
36
|
+
},
|
|
37
|
+
);
|
|
38
|
+
expect(
|
|
39
|
+
await client.financialObservations.source(ctx, { allocationId: row._id }),
|
|
40
|
+
).toMatchObject({ coverage: "unknown", observation: { generation: 1 } });
|
|
41
|
+
const paginationOpts = { numItems: 25, cursor: null, id: 7 };
|
|
42
|
+
expect(
|
|
43
|
+
await client.financialObservations.owner(ctx, {
|
|
44
|
+
userId: "user",
|
|
45
|
+
paginationOpts,
|
|
46
|
+
}),
|
|
47
|
+
).toMatchObject({
|
|
48
|
+
coverage: "unknown",
|
|
49
|
+
generation: 1,
|
|
50
|
+
page: [expect.objectContaining({ bucketKey: "opaque", userId: "user" })],
|
|
51
|
+
});
|
|
52
|
+
});
|
|
53
|
+
it.each([0, 101])(
|
|
54
|
+
"refuses page size %i before trusted dispatch",
|
|
55
|
+
async (numItems) => {
|
|
56
|
+
const client = new BetterStripe(components.betterStripe);
|
|
57
|
+
const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
|
|
58
|
+
await expect(
|
|
59
|
+
client.financialObservations.bucket(ctx, {
|
|
60
|
+
bucketKey: "opaque",
|
|
61
|
+
paginationOpts: { numItems, cursor: null },
|
|
62
|
+
}),
|
|
63
|
+
).rejects.toThrow();
|
|
64
|
+
expect(ctx.runQuery).not.toHaveBeenCalled();
|
|
65
|
+
},
|
|
66
|
+
);
|
|
67
|
+
it("drains oversized raw reservations through the installed public client", async () => {
|
|
68
|
+
const t = initConvexTest();
|
|
69
|
+
t.registerComponent(
|
|
70
|
+
"betterStripe",
|
|
71
|
+
schema,
|
|
72
|
+
import.meta.glob("../component/**/*.ts"),
|
|
73
|
+
);
|
|
74
|
+
const client = new BetterStripe(components.betterStripe);
|
|
75
|
+
const ctx = { runQuery: t.query, runMutation: t.mutation } as RunCtx;
|
|
76
|
+
const row = await t.mutation(
|
|
77
|
+
componentRef(
|
|
78
|
+
components.betterStripe,
|
|
79
|
+
"settlement/mutations/reserveSettlementAllocation",
|
|
80
|
+
),
|
|
81
|
+
{
|
|
82
|
+
sourceChargeId: "ch_sdk_continue",
|
|
83
|
+
gross: 303,
|
|
84
|
+
currency: "usd",
|
|
85
|
+
processingFee: 1,
|
|
86
|
+
platformNet: 1,
|
|
87
|
+
transfers: Array.from({ length: 301 }, (_, i) => ({
|
|
88
|
+
destinationAccountId: `logical_${i}`,
|
|
89
|
+
role: "store",
|
|
90
|
+
amount: 1,
|
|
91
|
+
})),
|
|
92
|
+
},
|
|
93
|
+
);
|
|
94
|
+
let result = await client.financialObservations.source(ctx, {
|
|
95
|
+
allocationId: row._id,
|
|
96
|
+
});
|
|
97
|
+
while (result.observation?.continuation?.state !== "complete")
|
|
98
|
+
result = await client.financialObservations.resume(ctx, {
|
|
99
|
+
allocationId: row._id,
|
|
100
|
+
expectedGeneration: result.observation!.generation,
|
|
101
|
+
});
|
|
102
|
+
expect(result).toMatchObject({
|
|
103
|
+
coverage: "unknown",
|
|
104
|
+
observation: {
|
|
105
|
+
indexedLegCount: 301,
|
|
106
|
+
continuation: { state: "complete", validatedLegs: 301 },
|
|
107
|
+
},
|
|
108
|
+
});
|
|
109
|
+
});
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { TransferObservationsClient } from "./transferObservations.js";
|
|
2
|
+
import { observationPagination } from "./observationPagination.js";
|
|
3
|
+
import type { PaginationOptions, PaginationResult } from "convex/server";
|
|
4
|
+
import type { Infer } from "convex/values";
|
|
5
|
+
import { z } from "zod";
|
|
6
|
+
import {
|
|
7
|
+
assertOwner,
|
|
8
|
+
assertSelector,
|
|
9
|
+
} from "../component/financialOwnership/helpers.js";
|
|
10
|
+
import type {
|
|
11
|
+
legDoc,
|
|
12
|
+
sourceDoc,
|
|
13
|
+
} from "../component/financialObservations/schema.js";
|
|
14
|
+
import { InvoiceReadClient } from "./invoiceReads.js";
|
|
15
|
+
import type { Component, RunCtx } from "./helpers.js";
|
|
16
|
+
import { runMutationOrThrow } from "./helpers.js";
|
|
17
|
+
import { componentRef } from "./webhooks/helpers.js";
|
|
18
|
+
|
|
19
|
+
export type FinancialSourceObservation = Infer<typeof sourceDoc>;
|
|
20
|
+
export type FinancialSourceLeg = Infer<typeof legDoc>;
|
|
21
|
+
export type FinancialSourceResult = {
|
|
22
|
+
coverage: "unknown";
|
|
23
|
+
observation: FinancialSourceObservation | null;
|
|
24
|
+
};
|
|
25
|
+
export type FinancialObservationPage = PaginationResult<FinancialSourceLeg> & {
|
|
26
|
+
coverage: "unknown";
|
|
27
|
+
generation: number | null;
|
|
28
|
+
};
|
|
29
|
+
export type FinancialObservationOwner = { userId: string; orgId?: string };
|
|
30
|
+
/** Trusted host diagnostics only; neither caller selectors nor exhausted pages authorize closure. */
|
|
31
|
+
export class FinancialObservationsClient extends TransferObservationsClient {
|
|
32
|
+
constructor(component: Component) {
|
|
33
|
+
super(component);
|
|
34
|
+
}
|
|
35
|
+
async source(
|
|
36
|
+
ctx: RunCtx,
|
|
37
|
+
input: { allocationId: string },
|
|
38
|
+
): Promise<FinancialSourceResult> {
|
|
39
|
+
const args = z
|
|
40
|
+
.object({ allocationId: z.string().min(1).max(256) })
|
|
41
|
+
.strict()
|
|
42
|
+
.parse(input);
|
|
43
|
+
return ctx.runQuery(
|
|
44
|
+
componentRef(this.component, "financialObservations/queries/source"),
|
|
45
|
+
args,
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
async resume(
|
|
49
|
+
ctx: RunCtx,
|
|
50
|
+
input: { allocationId: string; expectedGeneration: number },
|
|
51
|
+
): Promise<FinancialSourceResult> {
|
|
52
|
+
const args = z
|
|
53
|
+
.object({
|
|
54
|
+
allocationId: z.string().min(1).max(256),
|
|
55
|
+
expectedGeneration: z
|
|
56
|
+
.number()
|
|
57
|
+
.int()
|
|
58
|
+
.min(1)
|
|
59
|
+
.max(Number.MAX_SAFE_INTEGER),
|
|
60
|
+
})
|
|
61
|
+
.strict()
|
|
62
|
+
.parse(input);
|
|
63
|
+
return runMutationOrThrow(
|
|
64
|
+
ctx,
|
|
65
|
+
componentRef(this.component, "financialObservations/mutations/resume"),
|
|
66
|
+
args,
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
async bucket(
|
|
70
|
+
ctx: RunCtx,
|
|
71
|
+
input: { bucketKey: string; paginationOpts: PaginationOptions },
|
|
72
|
+
): Promise<FinancialObservationPage> {
|
|
73
|
+
const args = z
|
|
74
|
+
.object({ bucketKey: z.string(), paginationOpts: observationPagination })
|
|
75
|
+
.strict()
|
|
76
|
+
.parse(input);
|
|
77
|
+
assertSelector(args.bucketKey);
|
|
78
|
+
return ctx.runQuery(
|
|
79
|
+
componentRef(this.component, "financialObservations/queries/bucket"),
|
|
80
|
+
args,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
async owner(
|
|
84
|
+
ctx: RunCtx,
|
|
85
|
+
input: FinancialObservationOwner & { paginationOpts: PaginationOptions },
|
|
86
|
+
): Promise<FinancialObservationPage> {
|
|
87
|
+
const args = z
|
|
88
|
+
.object({
|
|
89
|
+
userId: z.string(),
|
|
90
|
+
orgId: z.string().optional(),
|
|
91
|
+
paginationOpts: observationPagination,
|
|
92
|
+
})
|
|
93
|
+
.strict()
|
|
94
|
+
.parse(input);
|
|
95
|
+
assertOwner(args);
|
|
96
|
+
return ctx.runQuery(
|
|
97
|
+
componentRef(this.component, "financialObservations/queries/owner"),
|
|
98
|
+
args,
|
|
99
|
+
);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
export abstract class FinancialObservationsHost extends InvoiceReadClient {
|
|
103
|
+
readonly financialObservations = new FinancialObservationsClient(
|
|
104
|
+
this.component,
|
|
105
|
+
);
|
|
106
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
// @vitest-environment edge-runtime
|
|
2
|
+
import { describe, 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
|
+
|
|
8
|
+
const modules = import.meta.glob("../component/**/*.ts");
|
|
9
|
+
function fixture() {
|
|
10
|
+
const t = initConvexTest();
|
|
11
|
+
t.registerComponent("betterStripe", schema, modules);
|
|
12
|
+
return {
|
|
13
|
+
client: new BetterStripe(components.betterStripe),
|
|
14
|
+
ctx: { runQuery: t.query, runMutation: t.mutation } as RunCtx,
|
|
15
|
+
};
|
|
16
|
+
}
|
|
17
|
+
describe("public financial ownership client", () => {
|
|
18
|
+
it("registers and reads actual component provenance without configuring Stripe", async () => {
|
|
19
|
+
const { client, ctx } = fixture();
|
|
20
|
+
expect(
|
|
21
|
+
await client.financialOwnership.lookup(ctx, { bucketKey: "opaque" }),
|
|
22
|
+
).toEqual({ status: "unknown", coverage: "unknown" });
|
|
23
|
+
const registered = await client.financialOwnership.register(ctx, {
|
|
24
|
+
bucketKey: "opaque",
|
|
25
|
+
kind: "logical",
|
|
26
|
+
userId: "user_one",
|
|
27
|
+
source: { integration: "trusted-host", recordId: "award_42" },
|
|
28
|
+
});
|
|
29
|
+
expect(
|
|
30
|
+
await client.financialOwnership.lookup(ctx, { bucketKey: "opaque" }),
|
|
31
|
+
).toEqual(registered);
|
|
32
|
+
expect(
|
|
33
|
+
await client.financialOwnership.discover(ctx, {
|
|
34
|
+
userId: "user_one",
|
|
35
|
+
paginationOpts: { numItems: 10, cursor: null },
|
|
36
|
+
}),
|
|
37
|
+
).toMatchObject({
|
|
38
|
+
coverage: "unknown",
|
|
39
|
+
generation: 1,
|
|
40
|
+
isDone: true,
|
|
41
|
+
page: [registered.registration],
|
|
42
|
+
});
|
|
43
|
+
});
|
|
44
|
+
it("preserves native pagination identity on trusted discovery callbacks", async () => {
|
|
45
|
+
const { client, ctx } = fixture();
|
|
46
|
+
const paginationOpts = { numItems: 10, cursor: null, id: 7 };
|
|
47
|
+
expect(
|
|
48
|
+
await client.financialOwnership.discover(ctx, {
|
|
49
|
+
userId: "user_one",
|
|
50
|
+
paginationOpts,
|
|
51
|
+
}),
|
|
52
|
+
).toMatchObject({ coverage: "unknown", page: [] });
|
|
53
|
+
});
|
|
54
|
+
it.each(["", " leading", "x".repeat(257)])(
|
|
55
|
+
"rejects invalid selector %j before dispatch",
|
|
56
|
+
async (bucketKey) => {
|
|
57
|
+
const { client } = fixture();
|
|
58
|
+
const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
|
|
59
|
+
await expect(
|
|
60
|
+
client.financialOwnership.lookup(ctx, { bucketKey }),
|
|
61
|
+
).rejects.toThrow();
|
|
62
|
+
expect(ctx.runQuery).not.toHaveBeenCalled();
|
|
63
|
+
},
|
|
64
|
+
);
|
|
65
|
+
it("rejects caller complete flags and physical proof fields before dispatch", async () => {
|
|
66
|
+
const { client } = fixture();
|
|
67
|
+
const ctx = { runQuery: vi.fn(), runMutation: vi.fn() };
|
|
68
|
+
const input = {
|
|
69
|
+
bucketKey: "acct_one",
|
|
70
|
+
kind: "stripe_account" as const,
|
|
71
|
+
userId: "user_one",
|
|
72
|
+
source: { integration: "forged", recordId: "forged" },
|
|
73
|
+
complete: true,
|
|
74
|
+
};
|
|
75
|
+
await expect(
|
|
76
|
+
client.financialOwnership.register(ctx, input),
|
|
77
|
+
).rejects.toThrow();
|
|
78
|
+
expect(ctx.runMutation).not.toHaveBeenCalled();
|
|
79
|
+
});
|
|
80
|
+
});
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
import type { PaginationOptions, PaginationResult } from "convex/server";
|
|
2
|
+
import type { Infer } from "convex/values";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
import {
|
|
5
|
+
assertOwner,
|
|
6
|
+
assertSelector,
|
|
7
|
+
} from "../component/financialOwnership/helpers.js";
|
|
8
|
+
import type { registrationDoc } from "../component/financialOwnership/schema.js";
|
|
9
|
+
import { FinancialObservationsHost } from "./financialObservations.js";
|
|
10
|
+
import type { Component, RunCtx } from "./helpers.js";
|
|
11
|
+
import { runMutationOrThrow } from "./helpers.js";
|
|
12
|
+
import { componentRef } from "./webhooks/helpers.js";
|
|
13
|
+
|
|
14
|
+
export type FinancialOwnershipRegistration = Infer<typeof registrationDoc>;
|
|
15
|
+
export type FinancialOwnershipResult =
|
|
16
|
+
| {
|
|
17
|
+
status: "registered";
|
|
18
|
+
coverage: "unknown";
|
|
19
|
+
registration: FinancialOwnershipRegistration;
|
|
20
|
+
}
|
|
21
|
+
| { status: "unknown"; coverage: "unknown" };
|
|
22
|
+
export type FinancialOwnershipOwner = { userId: string; orgId?: string };
|
|
23
|
+
export type RegisterFinancialOwnershipOptions = FinancialOwnershipOwner & {
|
|
24
|
+
bucketKey: string;
|
|
25
|
+
} & (
|
|
26
|
+
| { kind: "stripe_account" }
|
|
27
|
+
| { kind: "logical"; source: { integration: string; recordId: string } }
|
|
28
|
+
);
|
|
29
|
+
export type FinancialOwnershipPage =
|
|
30
|
+
PaginationResult<FinancialOwnershipRegistration> & {
|
|
31
|
+
coverage: "unknown";
|
|
32
|
+
generation: number;
|
|
33
|
+
};
|
|
34
|
+
const owner = { userId: z.string(), orgId: z.string().optional() };
|
|
35
|
+
const registrationInput = z.discriminatedUnion("kind", [
|
|
36
|
+
z
|
|
37
|
+
.object({
|
|
38
|
+
...owner,
|
|
39
|
+
bucketKey: z.string(),
|
|
40
|
+
kind: z.literal("stripe_account"),
|
|
41
|
+
})
|
|
42
|
+
.strict(),
|
|
43
|
+
z
|
|
44
|
+
.object({
|
|
45
|
+
...owner,
|
|
46
|
+
bucketKey: z.string(),
|
|
47
|
+
kind: z.literal("logical"),
|
|
48
|
+
source: z
|
|
49
|
+
.object({ integration: z.string(), recordId: z.string() })
|
|
50
|
+
.strict(),
|
|
51
|
+
})
|
|
52
|
+
.strict(),
|
|
53
|
+
]);
|
|
54
|
+
|
|
55
|
+
/** Trusted host-server provenance only. Authenticate the actor and verify logical source ownership first. */
|
|
56
|
+
export class FinancialOwnershipClient {
|
|
57
|
+
constructor(private component: Component) {}
|
|
58
|
+
async register(
|
|
59
|
+
ctx: RunCtx,
|
|
60
|
+
input: RegisterFinancialOwnershipOptions,
|
|
61
|
+
): Promise<Extract<FinancialOwnershipResult, { status: "registered" }>> {
|
|
62
|
+
const args = registrationInput.parse(input);
|
|
63
|
+
assertOwner(args);
|
|
64
|
+
assertSelector(args.bucketKey);
|
|
65
|
+
if (args.kind === "logical") {
|
|
66
|
+
assertSelector(args.source.integration);
|
|
67
|
+
assertSelector(args.source.recordId);
|
|
68
|
+
}
|
|
69
|
+
return runMutationOrThrow(
|
|
70
|
+
ctx,
|
|
71
|
+
componentRef(this.component, "financialOwnership/mutations/register"),
|
|
72
|
+
args,
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
async lookup(
|
|
76
|
+
ctx: RunCtx,
|
|
77
|
+
input: { bucketKey: string },
|
|
78
|
+
): Promise<FinancialOwnershipResult> {
|
|
79
|
+
const args = z.object({ bucketKey: z.string() }).strict().parse(input);
|
|
80
|
+
assertSelector(args.bucketKey);
|
|
81
|
+
return ctx.runQuery(
|
|
82
|
+
componentRef(this.component, "financialOwnership/queries/lookup"),
|
|
83
|
+
args,
|
|
84
|
+
);
|
|
85
|
+
}
|
|
86
|
+
async discover(
|
|
87
|
+
ctx: RunCtx,
|
|
88
|
+
input: FinancialOwnershipOwner & { paginationOpts: PaginationOptions },
|
|
89
|
+
): Promise<FinancialOwnershipPage> {
|
|
90
|
+
const args = z
|
|
91
|
+
.object({
|
|
92
|
+
...owner,
|
|
93
|
+
paginationOpts: z
|
|
94
|
+
.object({
|
|
95
|
+
numItems: z.number().int().min(1).max(100),
|
|
96
|
+
cursor: z.string().nullable(),
|
|
97
|
+
id: z.number().optional(),
|
|
98
|
+
endCursor: z.string().nullable().optional(),
|
|
99
|
+
maximumRowsRead: z.number().optional(),
|
|
100
|
+
maximumBytesRead: z.number().optional(),
|
|
101
|
+
})
|
|
102
|
+
.strict(),
|
|
103
|
+
})
|
|
104
|
+
.strict()
|
|
105
|
+
.parse(input);
|
|
106
|
+
assertOwner(args);
|
|
107
|
+
return ctx.runQuery(
|
|
108
|
+
componentRef(this.component, "financialOwnership/queries/discover"),
|
|
109
|
+
args,
|
|
110
|
+
);
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
/** Extends the existing facade without expanding its frozen entry-file budget. */
|
|
114
|
+
export abstract class FinancialOwnershipHost extends FinancialObservationsHost {
|
|
115
|
+
readonly financialOwnership = new FinancialOwnershipClient(this.component);
|
|
116
|
+
}
|
package/src/client/index.ts
CHANGED
|
@@ -18,7 +18,7 @@ import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js"
|
|
|
18
18
|
export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
|
|
19
19
|
import * as intentsImpl from "./billing/intents.js";
|
|
20
20
|
export type * from "./billing/intents.js";
|
|
21
|
-
import {
|
|
21
|
+
import { FinancialOwnershipHost } from "./financialOwnership.js";
|
|
22
22
|
import { CostRecoveryClient } from "./costRecovery.js";
|
|
23
23
|
export * from "./charge-currency.js";
|
|
24
24
|
export * from "./costRecovery.js";
|
|
@@ -202,7 +202,7 @@ export type BetterStripeComponent = ComponentApi;
|
|
|
202
202
|
|
|
203
203
|
// BETTER STRIPE CLIENT
|
|
204
204
|
|
|
205
|
-
export class BetterStripe extends
|
|
205
|
+
export class BetterStripe extends FinancialOwnershipHost {
|
|
206
206
|
readonly stripeApiVersion: SupportedStripeApiVersion;
|
|
207
207
|
private _apiKey?: string;
|
|
208
208
|
private _triggers?: SyncTriggers;
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
export const observationPagination = z
|
|
3
|
+
.object({
|
|
4
|
+
numItems: z.number().int().min(1).max(100),
|
|
5
|
+
cursor: z.string().nullable(),
|
|
6
|
+
id: z.number().optional(),
|
|
7
|
+
endCursor: z.string().nullable().optional(),
|
|
8
|
+
maximumRowsRead: z.number().optional(),
|
|
9
|
+
maximumBytesRead: z.number().optional(),
|
|
10
|
+
})
|
|
11
|
+
.strict();
|