Skip to content

feat(api-sync): enum and nested-object coverage checks, delivery manifest verification #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericviana merged 1 commit into from
Aug 4, 2026
Merged

feat(api-sync): enum and nested-object coverage checks, delivery manifest verification #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
108 changes: 108 additions & 0 deletions .api-sync/known-divergences.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,114 @@
"field": "expires_at",
"reason": "Same pre-existing mismatch as QuoteOut.expires_at, on the payin-quote equivalent (CreatePayinQuoteResponse). Here the field IS cast, `expiresAt: (int) $data['expires_at']`, so a fractional value would silently truncate rather than throw -- a real risk in disguise if the API ever returns one.",
"owner": "eric@blindpay.com"
},
{
"schema": "BankAccountOut",
"field": "spei_protocol",
"reason": "Spec constrains spei_protocol to an enum (clabe/debitcard/phonenum). BankAccountListItem models it as a plain `?string`, not the SpeiProtocol backed enum that CreateSpeiInput/CreateSpeiResponse already use on the same rail -- so every spec value still parses without error, just without case-completeness checking on this shape. Recorded for visibility only.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayinOut",
"field": "status",
"reason": "Covers PayinOut/CreatePayinOut's inline tracking_transaction.status (failed/completed) and tracking_transaction.status is a DIFFERENT, smaller enum than PayinOut's own top-level status (TransactionStatus, already mapped). TrackingTransaction models this sub-field as a plain `string`, not a backed enum.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayinOut",
"field": "currency",
"reason": "Spec constrains currency to the Currency enum. Payin models it as a plain `string`; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayinOut",
"field": "payment_method",
"reason": "Spec constrains payment_method to the PaymentMethod enum (already mapped for other shapes). Payin models it as a plain `string`, not PaymentMethod; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayinOut",
"field": "pse_document_type",
"reason": "Spec constrains pse_document_type to a 2-value enum (CC/NIT). Payin models it as a plain `?string`; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayinOut",
"field": "type",
"reason": "Spec constrains type (deposit method) to an enum. Payin models it as a plain `string`; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "OfframpWallet",
"field": "network",
"reason": "Spec constrains network to the Network enum (already mapped for other shapes, e.g. WalletOut). OfframpWallet models it as a plain `string`, not Network; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayoutOut",
"field": "status",
"reason": "Covers PayoutOut/PayoutOnEvmOut's inline tracking_transaction.status (failed/found) and tracking_complete.status (tokens_refunded/paid) -- two DIFFERENT, smaller enums than PayoutOut's own top-level status (TransactionStatus, already mapped). TrackingTransaction/TrackingComplete model these sub-fields as plain `string`, not backed enums.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayoutOut",
"field": "estimated_time_of_arrival",
"reason": "Covers PayoutOut/PayoutOnEvmOut's inline tracking_payment.estimated_time_of_arrival and tracking_liquidity.estimated_time_of_arrival. Both are spec enums (5_min/5_30_min/30_min/2_hours/1_business_day/2_business_days/5_business_days); PayoutTrackingPayment and TrackingLiquidity model them as plain `?string`/`string`, not backed enums.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayoutOut",
"field": "provider_status",
"reason": "Covers PayoutOut/PayoutOnEvmOut's inline tracking_payment.provider_status and tracking_liquidity.provider_status. Both are spec enums; PayoutTrackingPayment and TrackingLiquidity model them as plain `?string`/`string`, not backed enums.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayoutOut",
"field": "provider_name",
"reason": "Covers PayoutOut/PayoutOnEvmOut's inline tracking_payment.provider_name, a spec enum of bank-provider display names. PayoutTrackingPayment models it as a plain `?string`, not a backed enum.",
"owner": "eric@blindpay.com"
},
{
"schema": "PayoutOut",
"field": "ach_cop_document_type",
"reason": "Spec constrains ach_cop_document_type to an enum. Payout models it as a plain `?string`, not the AchCopDocument backed enum that BankAccounts already uses on the same rail; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "VirtualAccountOut",
"field": "kyc_status",
"reason": "Same shape of divergence as CustomerOut.kyc_status above: spec constrains kyc_status to an enum, VirtualAccount models it as a plain `?string`, not a backed enum. Every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "VirtualAccountOut",
"field": "account_type",
"reason": "Spec constrains us.account_type to an enum (checking/saving). VirtualAccountUsDetails models it as a plain `string`, not BankAccountType; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "WebhookEndpoint",
"field": "events",
"reason": "Spec constrains each item of the events array to the webhook-topic enum (WebhookEvents, already mapped). WebhookEndpoint models the whole array as plain `?array`, not a typed list of WebhookEvents; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "WebhookEndpointIn",
"field": "events",
"reason": "Same divergence as WebhookEndpoint.events, on the create-input side (CreateWebhookEndpointInput).",
"owner": "eric@blindpay.com"
},
{
"schema": "PayinOut",
"field": "provider_name",
"reason": "Covers PayinOut/CreatePayinOut's inline tracking_transaction.provider_name, a spec enum of payment-provider names. TrackingTransaction models it as a plain `?string`, not a backed enum; every spec value still parses without error.",
"owner": "eric@blindpay.com"
},
{
"schema": "CreatePayinQuoteIn",
"field": "pse_document_type",
"reason": "Spec constrains payer_rules.pse_document_type to a 2-value enum (CC/NIT). PayerRules models it as a plain `?string`; every spec value still parses without error.",
"owner": "eric@blindpay.com"
}
]
}
140 changes: 137 additions & 3 deletions .api-sync/spec-map.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,7 @@
},
{
"spec": { "schema": "BankAccountOut", "property": "account_type" },
"sdk": { "file": "src/Types/BankAccountType.php", "class": "BankAccountType" },
"note": "KNOWN DIVERGENCE, see .api-sync/known-divergences.json: spec value 'saving' vs SDK case value 'savings'. Do not blind-add a new case for 'saving'; that would create a duplicate near-identical case instead of fixing the real one. Kept mapped on purpose so the divergence stays visible."
"sdk": { "file": "src/Types/BankAccountType.php", "class": "BankAccountType" }
},
{
"spec": { "schema": "VirtualAccountOut", "property": "banking_partner" },
Expand Down Expand Up @@ -89,6 +88,58 @@
"spec": { "schema": "PayoutOut", "property": "status" },
"sdk": { "file": "src/Types/TransactionStatus.php", "class": "TransactionStatus" },
"note": "union of PayoutOut/PayinOut/TransferOut.status; SDK's PENDING_REVIEW case has no counterpart in any of the three today, which is fine (SDK may accept a superset)."
},
{
"spec": { "schema": "BankAccountOut", "property": "ach_cop_document_type" },
"sdk": { "file": "src/Resources/BankAccounts/BankAccounts.php", "class": "AchCopDocument" }
},
{
"spec": { "schema": "BankAccountOut", "property": "transfers_type" },
"sdk": { "file": "src/Resources/BankAccounts/BankAccounts.php", "class": "ArgentinaTransfers" }
},
{
"spec": { "schema": "PayoutOut", "property": "transfers_type" },
"sdk": { "file": "src/Resources/Payouts/Payouts.php", "class": "ArgentinaTransferType" }
},
{
"spec": { "schema": "CustomerLimitIncreaseIn", "property": "supporting_document_type" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "LimitIncreaseRequestSupportingDocumentType" }
},
{
"spec": { "schema": "GetCustomerLimitIncreaseOut", "property": "status" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "LimitIncreaseRequestStatus" }
},
{
"spec": { "schema": "GetCustomerLimitIncreaseOut", "property": "supporting_document_type" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "LimitIncreaseRequestSupportingDocumentType" }
},
{
"spec": { "schema": "PayinOut", "property": "manual_execution_status" },
"sdk": { "file": "src/Types/ManualExecutionStatus.php", "class": "ManualExecutionStatus" }
},
{
"spec": { "schema": "PayoutOut", "property": "spei_protocol" },
"sdk": { "file": "src/Resources/Payouts/Payouts.php", "class": "SpeiProtocol" }
},
{
"spec": { "schema": "UpdateCustomerIn", "property": "id_doc_type" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "IdentificationDocument" }
},
{
"spec": { "schema": "UpdateCustomerIn", "property": "proof_of_address_doc_type" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "ProofOfAddressDocType" }
},
{
"spec": { "schema": "UpdateCustomerIn", "property": "purpose_of_transactions" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "PurposeOfTransactions" }
},
{
"spec": { "schema": "UpdateCustomerIn", "property": "source_of_funds_doc_type" },
"sdk": { "file": "src/Resources/Customers/Customers.php", "class": "SourceOfFundsDocType" }
},
{
"spec": { "schema": "UploadIn", "property": "bucket" },
"sdk": { "file": "src/Resources/Upload/Upload.php", "class": "UploadBucket" }
}
],
"typesNote": "Class-per-file below always refers to src/Resources/**/*.php unless the file starts with src/Types/.",
Expand Down Expand Up @@ -139,6 +190,7 @@
{ "spec": "QuoteIn", "sdk": [ { "file": "src/Resources/Quotes/Quotes.php", "class": "CreateQuoteInput" } ] },
{ "spec": "QuoteOut", "sdk": [ { "file": "src/Resources/Quotes/Quotes.php", "class": "CreateQuoteResponse" } ] },
{ "spec": "CreatePayinQuoteIn", "sdk": [ { "file": "src/Resources/Payins/Quotes.php", "class": "CreatePayinQuoteInput" } ] },
{ "spec": "CreatePayinQuoteIn", "path": "payer_rules", "sdk": [ { "file": "src/Resources/Payins/Quotes.php", "class": "PayerRules" } ] },
{ "spec": "CreatePayinQuoteOut", "sdk": [ { "file": "src/Resources/Payins/Quotes.php", "class": "CreatePayinQuoteResponse" } ] },
{ "spec": "CreateTransferQuoteIn", "sdk": [ { "file": "src/Resources/Transfers/Transfers.php", "class": "CreateTransferQuoteInput" } ] },
{ "spec": "CreateTransferQuoteOut", "sdk": [ { "file": "src/Resources/Transfers/Transfers.php", "class": "CreateTransferQuoteResponse" } ] },
Expand Down Expand Up @@ -174,14 +226,96 @@
"note": "inline object, not a $ref'd component schema (no `Tracking*` schema exists in components.schemas); the same 20-property shape also recurs verbatim, unchecked here, in PayoutNewWebhookOut/PayoutUpdateWebhookOut/PayoutCompleteWebhookOut/PayoutPartnerFeeWebhookOut, which this SDK never deserializes (see 'webhook payloads' note below)."
},
{
"spec": "PayinOut",
"spec": ["PayoutOut", "PayoutOnEvmOut"],
"path": "tracking_transaction",
"sdk": [ { "file": "src/Types/TrackingTransaction.php", "class": "TrackingTransaction" } ]
},
{
"spec": ["PayoutOut", "PayoutOnEvmOut"],
"path": "tracking_complete",
"sdk": [ { "file": "src/Types/TrackingComplete.php", "class": "TrackingComplete" } ]
},
{
"spec": ["PayoutOut", "PayoutOnEvmOut"],
"path": "tracking_liquidity",
"sdk": [ { "file": "src/Types/TrackingLiquidity.php", "class": "TrackingLiquidity" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "tracking_payment",
"sdk": [ { "file": "src/Types/PayinTrackingPayment.php", "class": "PayinTrackingPayment" } ],
"note": "PayinOut's inline tracking_payment is a DIFFERENT, smaller shape (step/provider_name/completed_at/review_source/review_context/approved_risk_sources) than the payout one; previously shared with the payout-side TrackingPayment class, which threw a TypeError on payin fetch. Split into a payin-specific class (step/provider_name/completed_at) and PayoutTrackingPayment (step/provider_name/provider_transaction_id/provider_status/estimated_time_of_arrival/completed_at)."
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "tracking_transaction",
"sdk": [ { "file": "src/Types/TrackingTransaction.php", "class": "TrackingTransaction" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "tracking_complete",
"sdk": [ { "file": "src/Types/TrackingComplete.php", "class": "TrackingComplete" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "blindpay_bank_details",
"sdk": [ { "file": "src/Resources/Payins/Payins.php", "class": "BankDetails" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "blindpay_bank_details.ach",
"sdk": [ { "file": "src/Resources/Payins/Payins.php", "class": "BankAch" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "blindpay_bank_details.wire",
"sdk": [ { "file": "src/Resources/Payins/Payins.php", "class": "BankWire" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "blindpay_bank_details.rtp",
"sdk": [ { "file": "src/Resources/Payins/Payins.php", "class": "BankRtp" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "blindpay_bank_details.beneficiary",
"sdk": [ { "file": "src/Resources/Payins/Payins.php", "class": "BankBeneficiary" } ]
},
{
"spec": ["PayinOut", "CreatePayinOut"],
"path": "blindpay_bank_details.receiving_bank",
"sdk": [ { "file": "src/Resources/Payins/Payins.php", "class": "BankReceivingBank" } ]
},
{
"spec": ["TransferOut", "CreateTransferOut"],
"path": "tracking_complete",
"sdk": [ { "file": "src/Types/TrackingComplete.php", "class": "TrackingComplete" } ]
},
{
"spec": ["TransferOut", "CreateTransferOut"],
"path": "tracking_paymaster",
"sdk": [ { "file": "src/Resources/Transfers/Transfers.php", "class": "TransferTrackingPaymaster" } ]
},
{
"spec": ["TransferOut", "CreateTransferOut"],
"path": "tracking_bridge_swap",
"sdk": [ { "file": "src/Resources/Transfers/Transfers.php", "class": "TransferTrackingBridgeSwap" } ]
},
{
"spec": ["TransferOut", "CreateTransferOut"],
"path": "tracking_transaction_monitoring",
"sdk": [ { "file": "src/Resources/Transfers/Transfers.php", "class": "TransferTrackingTransactionMonitoring" } ]
},
{ "spec": "CreateVirtualAccountIn", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "CreateVirtualAccountInput" } ] },
{ "spec": "UpdateVirtualAccountIn", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "UpdateVirtualAccountInput" } ] },
{ "spec": "VirtualAccountOut", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccount" } ] },
{ "spec": "VirtualAccountOut", "path": "us", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountUsDetails" } ] },
{ "spec": "VirtualAccountOut", "path": "us.ach", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountUsAch" } ] },
{ "spec": "VirtualAccountOut", "path": "us.wire", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountUsWire" } ] },
{ "spec": "VirtualAccountOut", "path": "us.rtp", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountUsRtp" } ] },
{ "spec": "VirtualAccountOut", "path": "us.beneficiary", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountBeneficiary" } ] },
{ "spec": "VirtualAccountOut", "path": "us.receiving_bank", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountReceivingBank" } ] },
{ "spec": "VirtualAccountOut", "path": "us.swift_receiving_bank", "sdk": [ { "file": "src/Resources/VirtualAccounts/VirtualAccounts.php", "class": "VirtualAccountSwiftReceivingBank" } ] },
{
"spec": "CreateBlockchainWalletIn",
"discriminator": { "note": "body-shape discriminated: address vs signature hash", "sdkMethods": ["createWithAddress", "createWithHash"] },
Expand Down
Loading
Loading