@klappay/types

@klappay/types ​

6.3.0 ​

Minor Changes ​

  • c69348f: Adds RecipientTransferabilitySchema (with RecipientTransferabilityPairSchema and TransferRestrictionStatusSchema), the response of the new GET /v1/recipients/{id}/transferability endpoint (recipients:read). For each token/network pair enabled in the calling key's environment, it reports what the token issuer's own contract says about the recipient's address. receive says whether it can be credited and send whether it can move funds out; each is allowed, restricted or unknown. The only source is the token contract's on-chain view function (USDC isBlacklisted, USDT isBlackListed/isBlocked). USDT only restricts senders, so its receive is always allowed. POST /v1/charges can now answer 422 recipient_transfer_restricted (param: acceptedPayments) when the issuer restricts an address the charge pays from receiving on an accepted pair. The message lists only the affected pairs.

6.2.0 ​

Minor Changes ​

  • 233f79f: Adds EscrowSafeTransactionSchema (and EscrowTypedDataSchema), the response of the new GET /v1/charges/{id}/release/prepare and GET /v1/charges/{id}/refund/prepare endpoints: the exact Safe transaction Klappay will execute for an escrow release or refund — destination, token, amount in base units, chain id, Safe nonce, its EIP-712 typedData and safeTxHash — so an integrator signs typedData with any EIP-712 signer instead of reconstructing the Safe transaction themselves. toSignableEscrowTypedData turns that JSON into the shape viem's typings expect (bigint numbers, literal field types from ESCROW_SAFE_TX_TYPES). ReleaseEscrowRequestSchema/RefundEscrowRequestSchema descriptions now point at the prepare endpoints, and EscrowConfigSchema.releaserAddress documents that the releaser must be an externally-owned account, can move escrowed funds directly on-chain, and can't be rotated for an existing charge. Escrow release, refund and prepare can now answer 422 escrow_safe_mismatch when the escrow's Safe can't be rebuilt at the charge's address.

6.1.0 ​

Minor Changes ​

  • a1f63ca: CheckChargeResponseSchema gains two required fields, tokenSenders and userOperationSenders, alongside transactionSender. They carry on-chain evidence of who paid when the payer didn't sign the transaction itself: the from of the paying accepted-token transfers (an EIP-7702 wallet behind a gas-sponsoring relayer), and the ERC-4337 account whose own user operation paid (a bundler-submitted transaction, swaps included). Both are [] whenever transactionSender is null. transactionSender's description no longer claims it is always the payer's wallet.

6.0.1 ​

Patch Changes ​

  • 795085e: Documents the narrowed transactionSender semantics on CheckChargeResponseSchema: it is now only populated when the hinted txHash actually paid the charge. On a still-open charge, the receipt must contain a Transfer of an accepted token to the charge's address. On an already-confirmed/underpaid charge, the hash must be a transfer already credited to it on that network — previously such a charge always returned null, which made a re-check after an SSE confirmed event unable to learn the sender. Also updates confirmationProgress's description, since a terminal charge with a matching hint now makes one receipt read instead of none.

    Description-only change; no schema shape changes.

6.0.0 ​

Major Changes ​

  • d4f77e4: Arc now settles through official 0xSplits v2.2, the same Push split factory every other EVM network uses, instead of a separate self-hosted split deployment. NETWORK_FAMILIES.arc is now 'evm-official', so an Arc charge's split address is the same one predicted for Base, Arbitrum and the other EVM networks, and acceptedPayments can now mix arc with any other EVM network. Mixing TRON with any EVM network (Arc included) is still rejected.

    Breaking: 'arc' has been removed from the NetworkFamily union (and from NETWORK_FAMILIES' value type). Code that switches or branches on NetworkFamily === 'arc' must treat Arc as 'evm-official' instead.

5.2.0 ​

Minor Changes ​

  • 200aaeb: Re-enables USDC/USDT payments on BNB Chain (live) — isPaymentDeploymentEnabled no longer hardcodes bnb+live to false. A charge can now accept BNB the same as any other operational network, and GET /v1/networks lists it accordingly.

    This lifts the SEG-01 containment introduced 2026-09-14 after a decimals bug (BNB's contracts use 18 decimals; the previous payment-preparation path assumed 6) — that bug was fixed in the same release that added the containment; today's change only removes the policy block kept on top of the already-fixed decimals-handling path. Existing charges held by that containment (Charge.paymentIntegrityHold) are unaffected by this change — each still needs its own reviewed release through POST /internal/payment-integrity/corrections before its hold clears, regardless of this policy flip. See docs/security.md#seg-01 and docs/operations.md#seg-01-deployment-and-historical-review for the full history and the release mechanism.

    Additive, non-breaking for any existing integration: a bnb+USDC/USDT acceptedPayments pair that was previously rejected with 422 token_not_supported or 503 payment_temporarily_unavailable is now accepted — no previously-valid request changes behavior.

5.1.1 ​

Patch Changes ​

  • 6bf30ef: Fixes a bundle-size regression in @klappay/types/constants introduced by the Arc/TRON onboarding changesets: tokens.constants.ts's new tron deployment (TOKEN_DEPLOYMENTS.USDT.tron) called tronAddress(), which lived in addresses.ts — the same file as the zod-based SplitAddressSchema. Importing that one pure function pulled the whole zod dependency into any consumer of the zero-zod /constants subpath, ballooning it from ~2.4KB to ~120KB once bundled (verified with an isolated esbuild probe importing only EVM_NETWORKS).

    Splits addresses.ts into addresses.constants.ts (the pure types/functions: EvmAddress, TronAddress, SplitAddress, isEvmAddress, isTronAddress, isSplitAddress, tronAddress, addressesEqual — no zod import) and addresses.ts (just SplitAddressSchema, re-exporting the constants file), mirroring the existing tokens.ts/tokens.constants.ts split. tokens.constants.ts now imports tronAddress from addresses.constants instead. No public API change — addresses.ts/the main @klappay/types export still re-export everything exactly as before; only the /constants subpath's actual bundled weight changes.

5.1.0 ​

Minor Changes ​

  • 7ea60e6: Adds arc to Network/EVM_NETWORKS/OPERATIONAL_NETWORKS/CHAIN_IDS (live chain 5042, test chain 5042002) and its USDC deployment (TOKEN_DEPLOYMENTS/TOKEN_ADDRESSES, both environments) — Arc's own native gas asset, exposed through an optional ERC-20-compatible interface rather than a separately-deployed contract. Adds cirBTC, Circle's own BTC-backed token, as Arc's swap-to-pay trusted alt-token (live only, matching every other alt-token entry).

    Also adds NETWORK_FAMILIES, grouping every Network into 'evm-official' | 'tron' | 'arc' — a charge predicts one split address up front and reuses it across every accepted network, which is only safe when every accepted network resolves that address through the same split factory. Arc runs its own, self-hosted 0xSplits fork (@klappay/arc-splits) with a different factory than every officially-supported network, so AcceptedPaymentsSchema now rejects (400 validation_error) a request whose acceptedPayments mixes networks across families. Escrow is also supported on Arc — Safe's canonical proxy-factory/singleton deployment was independently verified live against both rpc.mainnet.arc.io and rpc.testnet.arc.network.

    Additive, non-breaking: existing Network values, TOKEN_ADDRESSES entries, and previously-valid acceptedPayments/escrow combinations are unchanged — no prior request could have included arc, since it didn't exist in Network before this.

5.0.0 ​

Major Changes ​

  • bef5535: Expand the swap-to-pay trusted alt-token set with established, deeply-liquid cryptocurrencies per network: LINK (Ethereum, Arbitrum, Optimism, Polygon, Base, Avalanche's bridged LINK.e), ARB (Arbitrum), OP (Optimism), CBETH (Base), and BTC.b filling Avalanche's previously-empty BTC slot. BNB Chain is intentionally untouched — its payment methods remain disabled by the SEG-01 containment, so there is no accepted-payment pair to swap into there yet.

    Breaking: AltTokenSchema's 'MATIC' literal is renamed to 'POL', matching Polygon's own 2024 native-currency rename — same asset, same 18 decimals, only the accepted string changed. Any integration reading 'MATIC' off swapAlternatives/CreateSwapQuoteSchema.inputToken/SwapQuoteSchema.inputToken needs to switch to 'POL'.

4.1.0 ​

Minor Changes ​

  • 7114359: Add per-network/environment token deployment metadata and availability helpers. Preserve TOKEN_ADDRESSES as a derived compatibility view and the legacy TOKEN_DECIMALS export; integrations should use each deployment's own decimals instead. Both cataloged BNB Chain tokens have 18 decimals and their payment pairs are currently disabled.

    Add optional exact decimal-string amounts and fees to charge and swap responses, plus an optional charge payment-availability flag. Existing numeric fields remain available for compatibility.

4.0.0 ​

Major Changes ​

  • db02385: Renames the moralis_webhook TransactionSource value to contract_watcher, and HealthSchema.lastMoralisEventAgeSeconds to lastContractWatcherEventAgeSeconds — Core's payment-detection push path moved from a third-party webhook (Moralis Streams) to a self-hosted on-chain event subscription (contract-watcher.ts), so the value/field names describing that path changed to match. No behavior change for the confirmation-depth/trust model itself: every detected transfer was always independently re-verified on-chain and re-derived against the current block, regardless of which path detected it first.

    Any integrator branching on TransactionSource === 'moralis_webhook' or reading lastMoralisEventAgeSeconds from GET /v1/health needs to update to the new names.

3.8.0 ​

Minor Changes ​

  • 924abc3: Adds ChargeFeePayerSchema (ChargeFeePayer, 'merchant' | 'payer') and a feePayer field on CreateChargeSchema/ChargeSchema — set feePayer: 'payer' at creation to gross up amount so the payer covers Klappay's fee instead of it being deducted from your payout. ChargeSchema also gains feePercent (now public, was internal-only), feeAmount, and merchantAmount so a client can render a price breakdown without reimplementing the fee math itself.
  • 56385aa: Adds ConfirmationProgressSchema (ConfirmationProgress) — { network, blocksSeen, blocksRequired, percent }, reporting how close an already-detected transfer is to its network's required confirmation depth before it's credited. CheckChargeResponseSchema now carries it as confirmationProgress (present while a detected transfer isn't deep enough yet, null otherwise), and GET /v1/charges/{id}/events streams the same shape as a new event: confirmation_progress SSE event alongside the existing event: charge.

3.7.0 ​

Minor Changes ​

  • 1cb8f20: Add RefundEscrowRequestSchema, the charge.escrow_refunded webhook event, and escrow.refundedAt on ChargeSchema — support for POST /v1/charges/{id}/refund, which returns an escrow's full balance to the payer instead of the split address.

3.6.0 ​

Minor Changes ​

  • ff085f9: POST /v1/charges/{id}/check's response now carries transactionSender — the txHash transaction's own signer/sender, which stays the payer's real wallet even when the payment routes through a swap/aggregator, unlike the credited transfer's own from. Adds CheckChargeResponseSchema (ChargeSchema plus transactionSender), matching what POST /internal/charges/{id}/check already returned.

3.5.2 ​

Patch Changes ​

  • d9dec69: CreateChargeSchema.idempotencyKey's description now documents the 409 idempotency_key_reused error a caller gets when reusing a key with a different request body, instead of only describing the successful-replay case.

3.5.1 ​

Patch Changes ​

  • ec700f3: Update the escrow section of docs/charges.md — escrow is now enabled on POST /v1/charges (Core's creation guard was lifted after live end-to-end verification). No schema change.

3.5.0 ​

Minor Changes ​

  • 703d59c: Add charge.escrow_released to ChargeWebhookEventTypeSchema, fired once an escrow-configured charge's funds move from its Safe to the split address via the newly-implemented POST /v1/charges/{id}/release. Also corrects ReleaseEscrowRequestSchema's description, which previously (inaccurately) said the release amount was fixed at escrow creation — it's actually the escrow's live on-chain balance at release time, since the destination is fixed but the amount received can vary (underpay/overpay/installments).

3.4.0 ​

Minor Changes ​

  • 16e5271: Add escrowReleaserAddress, escrowFeePercent, and escrowReleasedAt to the charges resource's queryable dimension, metric, and date fields in the metrics query schema (ChargesQueryFieldSchema, ChargesMetricFieldSchema, ChargesDateFieldSchema), so escrow-configured charges can be filtered and aggregated through POST /v1/metrics/query.

3.3.0 ​

Minor Changes ​

  • cec1236: Adds EscrowConfigSchema (escrow field on CreateChargeSchema/ChargeSchema) and ReleaseEscrowRequestSchema — the request/response shapes for creating an escrow-configured charge, where funds lock in a dedicated non-custodial Safe until a signature from escrow.releaserAddress releases them. releaserAddress is optional and defaults to the API key's own payoutAddress when omitted.

    Not yet usable end to end: POST /v1/charges currently rejects any request carrying escrow with 503 escrow_unavailable, since the release endpoint these schemas exist for hasn't shipped yet. The schemas are published ahead of that so integrators building against @klappay/types don't hit a moving target once it does.

3.2.0 ​

Minor Changes ​

  • bedfcd7: Adds CheckChargeRequestSchema (CheckChargeRequest) — the optional txHash/network request body for the new POST /v1/charges/{id}/check on-demand payment check endpoint. Lets a caller that already has a transaction hash (e.g. right after a swap-to-pay or wallet-connect transaction is sent) point the check at that specific transaction directly instead of a broader block-range scan. Both fields are optional and only ever accepted together — omitting them falls back to the existing scan.

3.1.1 ​

Patch Changes ​

  • 25f6b44: Fix SwapQuoteSchema.permit2 rejecting a native-currency (ETH/BNB/MATIC/AVAX) swap quote with a ZodError. 0x's own API sends permit2: null explicitly for a native-currency sell, not an omitted key — .optional() only ever accepted undefined, so a genuinely valid quote crashed the route with a 500 before it ever reached a consumer. permit2 is now .nullish(), accepting null (the real shape) alongside undefined for backwards compatibility.

3.1.0 ​

Minor Changes ​

  • a2ca627: Add CHAIN_IDS, a canonical Record<EvmNetwork, Partial<Record<Environment, number>>> mapping each network/environment pair to its EVM chain ID (e.g. 8453 for Base mainnet, 84532 for Base Sepolia) — the same IDs a wallet's wallet_switchEthereumChain or an RPC provider expects.

    Also adds a second entry point, @klappay/types/constants, that re-exports every plain-object constant this package already had (TOKEN_ADDRESSES, ALT_TOKEN_ADDRESSES, NETWORK_LABELS, NETWORK_EXPLORERS, EVM_NETWORKS, OPERATIONAL_NETWORKS, TOKEN_DECIMALS, ALT_TOKEN_DECIMALS) plus the new CHAIN_IDS, with zero zod in its bundle — for a browser/wallet-side app that only needs the plain values and doesn't want to pay for the schema-validation code that ships with the main @klappay/types entry.

    Both are additive: the root @klappay/types entry point is unaffected — every existing import keeps working exactly as before, with identical values.

3.0.2 ​

Patch Changes ​

  • 5f30729: Fixes Charge.swapAlternatives, shipped incomplete in the previous release: it was returning a flat list of tokens (e.g. ['ETH', 'BTC']), which loses the network a charge accepting payment on more than one chain actually needs the payer to send on — a token like BTC also resolves to a materially different contract per network (cbBTC vs WBTC). It now returns { token, network } pairs (SwapAlternativeSchema) — pass an entry's token/network straight through as inputToken/inputNetwork on POST /v1/charges/{id}/quote. listAltTokensForNetworks is renamed listSwapAlternatives to match, returning the same pairs.

    Also fixes: Charge.swapAlternatives is now always empty for a test-environment charge, even when swap-to-pay is configured and the charge's networks have a trusted alt-token — 0x, who powers POST /v1/charges/{id}/quote (klap-core), has no testnet support at all, confirmed live against the real API (it rejects every testnet chain id outright). That endpoint now also fails fast with 422 swap_test_environment_unsupported for a test charge, before spending a rate-limit slot or an upstream 0x call on a request that could never succeed.

3.0.1 ​

Patch Changes ​

  • 44a3c7c: Adds swap-to-pay support — a payer can now settle a charge with a non-stablecoin cryptocurrency, swapped into one of the charge's own acceptedPayments tokens via POST /v1/charges/{id}/quote (klap-core). ChargeSchema.swapAlternatives lists which cryptocurrencies are trusted as swap input for a given charge, derived from its acceptedPayments networks. New exports: AltTokenSchema/AltToken (ETH, BNB, MATIC, AVAX, BTC), ALT_TOKEN_ADDRESSES, ALT_TOKEN_DECIMALS, listAltTokensForNetworks (alt-tokens.ts), and CreateSwapQuoteSchema/SwapQuoteSchema (swap.ts). BTC is backed by WBTC (Ethereum, Arbitrum, Optimism, Polygon) or cbBTC (Base) — SwapQuoteSchema.permit2 is present only for this kind of ERC-20 input, since it needs a Permit2 allowance signature that a network's own native currency (ETH/BNB/MATIC/AVAX) never does. SwapQuoteSchema.fees breaks out both Klappay's own swap fee and 0x's separate protocol fee (when it applies), so a client can show the payer exactly who's charging what — neither ever reduces outputAmount, the merchant's full amount owed. See docs/payments.md (klap-core)'s "Swap-to-pay" section for the full flow.

3.0.0 ​

Major Changes ​

  • 0cb9c1d: splitRecipients now references a pre-registered Recipient by id instead of a raw address — closes the same redirect risk the 2.0.0 payoutAddress-in-the-JWT change closed for the primary payout destination, reopened through this field. See docs/security.md's finding #50 (klap-core).

    Breaking:

    • CreateChargeSchema.splitRecipients entries are now { recipientId, percent, label? } — address is no longer accepted. SplitRecipientInputSchema replaces the old input shape of SplitRecipientSchema; SplitRecipientSchema itself is now the response-only shape echoed on ChargeSchema.splitRecipients (still { address, percent, label? }, since a merchant reading their own charge back needs the resolved address, not the id they submitted).
    • POST /v1/charges requires the new charges:split_write scope in addition to charges:write whenever splitRecipients is present — a key with only charges:write can no longer create a charge with a split at all, even one referencing an already-registered recipient.

    Added:

    • POST /v1/recipients, GET /v1/recipients, PATCH /v1/recipients/{id}, DELETE /v1/recipients/{id} — register, list, and revoke trusted split-recipient addresses. CreateRecipientSchema, RecipientSchema, SetRecipientPayoutSchema.
    • Four new ApiKeyScope values: charges:split_write, recipients:read, recipients:write, recipients:manage_payout. The last is deliberately stricter than recipients:write — it's the only way a recipient becomes eligible to be used as an API key's own payoutAddress, meant to be held only by a key that's already gone through its own out-of-band approval (e.g. Dashboard's internal key), never a merchant-facing or third-party integration key.
    • CONFLICTING_SCOPE_PAIRS/findConflictingScopes — charges:split_write can never be granted to the same key as recipients:write/recipients:manage_payout; Core rejects such a key outright (403 conflicting_api_key_scopes) on every request, not just at mint time.

    See packages/types/docs/api-keys.md and docs/payments.md (klap-core) for the full detail, including why recipients:write alone can never disable another key even though revoking a payout: true recipient does.

    Also declares engines.node: ">=24", matching the rest of the monorepo (CI already builds/tests/publishes this package on Node 24).

2.0.4 ​

Patch Changes ​

  • d7319e6: Fixes CheckoutProductSchema/KlappayCheckoutMetadataSchema/ MetadataWithKlappaySchema (checkout-metadata.ts) not being exported from the package's entry point — they existed and were correctly wired into Charge.metadata's shape, but couldn't be imported by name.

2.0.3 ​

Patch Changes ​

  • e13fd8e: Adds KlappayCheckoutMetadataSchema (checkout-metadata.ts) — validates the klappay key inside Charge.metadata, today carrying an optional products list (name, quantity, imageUrl) shown on Klappay's hosted checkout page. Every other key in metadata stays exactly as free-form and unvalidated as before. See packages/types/docs/charges.md.

2.0.2 ​

Patch Changes ​

  • b6086dd: Adds splitRecipients to CreateChargeSchema — optional, up to 5 extra addresses (e.g. a supplier, or whoever closed the sale) to route a slice of a charge's split to. Each percent is of the merchant's own net share (100 - feePercent), never the gross amount. Echoed back on ChargeSchema.splitRecipients. See packages/types/docs/charges.md.

2.0.1 ​

Patch Changes ​

  • e95240d: Adds redirectUrl to CreateChargeSchema — optional, where to send the payer once a charge resolves if you use Klappay's hosted checkout page. Echoed back on ChargeSchema.redirectUrl, alongside a new ChargeSchema.checkoutUrl (nullable — null if the deployment has no hosted checkout configured). See packages/types/docs/charges.md.

2.0.0 ​

Major Changes ​

  • cc2697e: Major surface reduction: Core now covers only charges, webhooks, distributions, networks, and metrics. Account signup/login, organization/member management, API key issuance, and platform administration all moved to a separate Dashboard service. Charge cancellation and continuous/dormant charge modes are gone — every charge now resolves automatically on a short, fixed timeline. The public/redacted charge-lookup surface is gone — that integration is being built separately, outside this repo. In exchange, API keys gained granular scopes.

    Removed:

    • auth.ts, users.ts, organization.ts, invitations.ts, api-keys.ts — every Signup/Login/AuthResponse, User/UserRole, Organization, ApiKey/CreateApiKeyInput, invitation schema.
    • public-charges.ts — PublicChargeSchema/PublicCharge. GET /v1/public/charges/{id} and its SSE/QR-code siblings no longer exist.
    • Charge cancellation — POST /v1/charges/{id}/cancel is gone. 'canceled' is removed from ChargeStatusSchema; Charge.canceledAt is removed. 'charge.canceled'/'charge.paid_after_cancel' are removed from ChargeWebhookEventTypeSchema and TimelineEventTypeSchema; ChargePaidAfterCancelData is removed.
    • Continuous/dormant charge mode — ChargeModeSchema/ChargeMode and the mode field on CreateChargeSchema/ChargeSchema are gone. ChargeSchema.pausedAt is gone. 'charge.contribution_received'/'charge.contribution_settled'/'charge.paused'/'charge.reactivated' are removed from ChargeWebhookEventTypeSchema. ChargesQueryFieldSchema (metrics query) drops mode.
    • SandboxEventTriggerSchema/SandboxEventTriggerInput/NonChargeTriggerableEventSchema — the generic non-charge sandbox trigger endpoint is gone. SandboxTriggerSchema (charge-event triggers) is unchanged.
    • MetricsQueryScopeSchema/MetricsQueryScope — MetricsQueryResultSchema.meta no longer has a scope field; there's no member-vs-org access split left to report.
    • WebhookEventTypeSchema's account/security categories — AccountWebhookEventTypeSchema/SecurityWebhookEventTypeSchema and every auth.*/member.*/payout_address.changed/api_key.*/webhook.created/webhook.deleted/webhook.secret_rotated/fee_tier.updated event (plus their *Data types in webhook-event-data.ts) are gone. Only payments and webhooks categories remain — 11 events total, down from 36. WebhookCategorySchema is now 'payments' | 'webhooks'.

    Changed:

    • CreateChargeSchema.amount/.expiresIn are no longer optional — every charge now has a real target amount and a real deadline.
    • CHARGE_EXPIRES_IN_MAX_SECONDS drops from 365 days to 3600 (60 minutes), sized off real on-chain confirmation latency across every chain Klappay supports. Min stays 60 seconds.
    • Business metrics querying moves from POST /v1/organizations/{id}/metrics/query (session-authenticated) to POST /v1/metrics/query (API-key-authenticated, no organization in the path) — every valid key gets access to its own tenant's data, no member/role sub-scoping.

    Added:

    • ApiKeyScopeSchema/ApiKeyScope/API_KEY_SCOPES — the fixed set of permissions an API key can carry (charges:read, charges:write, webhooks:read, webhooks:write, webhooks:manage_secret, metrics:read, metrics:charges:read, metrics:transactions:read, metrics:distributions:read, sandbox:trigger).
    • MetricsQuerySchema gains a year date-bucket granularity, expiresAt as a charges date field, distributorAddress as a distributions dimension field, and processingStartedAt as a distributions date field.

1.1.2 ​

Patch Changes ​

  • aa3fe9f: Simplified — public charge endpoints no longer require ?environment=. GET /v1/public/charges/{id}, its SSE sibling, and GET /v1/public/charges/{id}/qrcode now look a charge up by id alone — already a global primary key, not scoped by organization or environment, so there was nothing left to disambiguate. environment comes back as a field on the response instead of being a required input; callers who want to assert it matches an expectation do so themselves. GetPublicChargeQuerySchema and GetPublicChargeQrCodeQuerySchema are removed — the QR endpoint now takes the same GetChargeQrCodeQuerySchema ({ token?, network? }) the authenticated one already used. No real consumer of the removed schemas yet, hence patch rather than a version bump reflecting a breaking change.

1.1.1 ​

Patch Changes ​

  • b6c5206: Added — public, unauthenticated QR code: GET /v1/public/charges/{id}/qrcode is the unauthenticated sibling of GET /v1/charges/{id}/qrcode — identical EIP-681 QR code, no API key required, new GetPublicChargeQrCodeQuerySchema (GetPublicChargeQuerySchema extended with the same token/network selectors the authenticated endpoint already has). Nothing new to redact: the QR only ever encodes address/acceptedPayments/amount, already exposed by GET /v1/public/charges/{id}. The authenticated endpoint stays — klap-app's dashboard genuinely uses it today, and keeping that trusted, low-volume traffic off the public endpoint's rate limit (sized to absorb anonymous, potentially abusive traffic) is a real reason to keep both, not just inertia.

1.1.0 ​

Minor Changes ​

  • 3d37a04: API surface cleanup and additions. Bundled as one release, minor rather than major despite three technically breaking changes below — a deliberate call: there are no real production consumers of any of them yet, so this was treated as pre-1.0-style flexibility rather than forcing a major bump for changes nobody is actually depending on.

    Removed — /v1/verify (breaking): the public, unauthenticated proof-of-payment surface (GET /v1/verify/{id}, GET /v1/verify/{id}/events) is gone, along with its exported schemas (VerifyChargeSchema, VerifyPaymentSchema, VerifySplitEntrySchema, SplitRecipientRoleSchema) and the now-unused ChargeStatusEventSchema/ ChargeStatusEvent. It had no real integrator depending on it — every first-party consumer already reads charge status through the authenticated GET /v1/charges/{id}/GET /v1/charges/{id}/events instead.

    Moved — /v1/cli/listen → /v1/webhooks/listen (breaking URL change): same endpoint, same behavior, relocated because it's a generic "stream every webhook event live" capability, not something exclusive to the official CLI. @klappay/cli needs the corresponding update.

    Changed — GET /v1/distributions/pending now paginated (breaking response shape): was a flat array capped at 200 rows; now returns the same { data, nextCursor, hasMore } envelope every other list endpoint uses (PaginatedPendingDistributionsSchema), removing the hard cap. GET /v1/distributions/pending/events gained an optional ?limit= for a self-contained snapshot+live connection (new ListenPendingDistributionsQuerySchema) — omitting it keeps the original connect-then-fetch behavior unchanged.

    Added — cancel a charge: POST /v1/charges/{id}/cancel marks a pending/partially_paid, mode: standard charge canceled — the one terminal ChargeStatus value that's merchant-initiated rather than reached automatically. New Charge.canceledAt field, two new webhook events (charge.canceled, and charge.paid_after_cancel for the rare case a payment still lands on a canceled charge's address afterward).

    Added — public, unauthenticated charge lookup: GET /v1/public/charges/{id} and its SSE sibling GET /v1/public/charges/{id}/events return a new, redacted PublicCharge shape (PublicChargeSchema) — no API key required, for a consumer with no per-org key at all (e.g. a hosted checkout). This is the public, unauthenticated use case /v1/verify used to serve, brought back in a different, safer shape now that a real consumer exists: safety comes from redacting the response (apiKeyId/externalRef/ source always dropped; metadata filtered to only the reserved klappay key, if present, null otherwise), not from a scoped credential. Both endpoints require ?environment= (GetPublicChargeQuerySchema) — there's no key to infer it from, and a mismatch is indistinguishable from the charge not existing (404), so the endpoint can't be used to probe an id's real environment. Draws from its own rate limit and, for the SSE variant, its own small connection budget, independent of every authenticated endpoint.

1.0.9 ​

Patch Changes ​

  • 627868c: Adds GetChargeQrCodeQuerySchema for GET /v1/charges/{id}/qrcode — a new endpoint returning a scannable EIP-681 payment QR code (SVG) for a charge. token/network query params select which accepted (token, network) pair to encode when a charge accepts more than one.

1.0.8 ​

Patch Changes ​

  • 055606b: Adds schemas for three new self-service account endpoints: ChangeNameSchema (PATCH /v1/auth/me), ChangePasswordSchema (POST /v1/auth/change-password, requires the current password), and ChangeEmailSchema/ConfirmEmailChangeSchema (POST /v1/auth/change-email → POST /v1/auth/confirm-email-change, confirmed via the current email address before it takes effect). Also exports SelfUserSchema (the "pure identity" shape AuthResponseSchema.user already used) and three new security-category webhook events: auth.password_changed, auth.email_change_requested, auth.email_changed.

1.0.7 ​

Patch Changes ​

  • 4f2d3e5: WebhookSchema/WebhookListItem gain environment ('live' | 'test' | null) — set automatically from whichever API key created the webhook, null for a webhook created before this field existed. charges/webhooks-category events are now only delivered to a webhook whose environment matches the event's own (or to a null-environment webhook, which still receives every environment); account/security events have no environment concept and are unaffected. See docs/webhooks.md's "Environment scoping" section.

1.0.6 ​

Patch Changes ​

  • db8177e: MetricsQuerySchema's orderBy.key now requires the same safe-identifier pattern (^[a-zA-Z_][a-zA-Z0-9_]*$) as metrics[].alias — every legitimate output column name (a groupBy field, a metric's default name, or its alias) already matches this shape, so this only rejects a value that could never have been a real column reference in the first place.

1.0.5 ​

Patch Changes ​

  • 97e02a5: Adds MetricsQuerySchema and its supporting types — the request/response contract for a new session-authenticated, org-scoped ad-hoc metrics query endpoint (charges/transactions/distributions resources, with per-resource typed field enums for filters/groupBy/aggregation). A metrics[].alias must match ^[a-zA-Z_][a-zA-Z0-9_]*$ and must not collide with a groupBy field name or the reserved word bucket (it can become a SQL column alias server-side). See docs/metrics.md and packages/types/docs/metrics-query.md for the endpoint itself.
  • 36b2d49: Documents Organization.currentFeePercent/feeUpdatedAt more fully — why the platform fee exists, that it's dynamic (volume-based by default, but Klappay may assign a specific organization a different rate), and that it's frozen onto each charge at creation. No exact tier thresholds/percentages are published — those stay internal by design.
  • a06fecf: Renames the brand name from "Klap" to "Klappay" wherever it appears in schema descriptions and docs, for consistency with the @klappay package scope and domain.

1.0.4 ​

Patch Changes ​

  • b9cd132: Adds a *Request type — z.input<typeof Schema> — alongside every *Input type (z.infer<typeof Schema>) for a schema with a default or transform, for SDKs and other callers that build a request object before it's parsed:

    • CreateChargeRequest, ListChargesRequest
    • InviteUserRequest
    • CreateWebhookRequest, ListWebhookDeliveriesRequest
    • ListApiKeysRequest
    • ListUsersRequest
    • ListOrganizationsRequest
    • PaginationQueryRequest

    *Input guarantees every defaulted/transformed field is present (mode, limit, etc.) since it describes an already-parsed value — that made it the wrong type for a caller building a request, where those same fields are meant to be optional. docs/charges.md's CreateChargeInput example actually failed to type-check for exactly this reason (missing mode/currency); it and the other affected docs now use the matching *Request type instead.

1.0.3 ​

Patch Changes ​

  • 1d3e9b1: No code changes — updates package metadata and README.md so npm shows everything correctly:

    • Adds keywords for npm search discoverability.
    • README.md's documentation table, CHANGELOG.md link, and LICENSE link all now point at real, working URLs — a public docs site at api.klappay.com/types (including a changelog page) for the first, unpkg.com for the second — instead of relative paths, which never rendered as navigable links on npmjs.com.
    • docs/ is no longer bundled in the published tarball — the public docs site above is now the canonical place to read it.
    • docs/*.md had five stray references to this repo's own internal (private, unpublished) documentation by bare path — removed, since an external reader could never reach them.

1.0.2 ​

Patch Changes ​

  • 00dd00a: No code changes — updates package metadata and docs links so npm shows them correctly:

    • Adds keywords for npm search discoverability.
    • README.md's documentation table now links to api.klappay.com/docs (a dedicated public docs site) instead of relative ./docs/*.md paths, which never rendered as navigable links on npmjs.com.
    • docs/ is no longer bundled in the published tarball — the public docs site above is now the canonical place to read it.

1.0.1 ​

Patch Changes ​

  • 2dbda30: Test changeset to verify the version/publish pipeline end to end (OIDC trusted publishing, the "Version Packages" PR flow, CHANGELOG.md generation). No functional change to the package.

1.0.0 ​

Initial public release.

TypeScript types and Zod schemas for the Klappay Core API's full request/response surface:

  • Charges — create/read charges, with an optional amount (pay-what-you-want) and optional expiresIn (never-expiring charges), a continuous collection mode alongside the default standard mode, activity/pause tracking (lastActivityAt/pausedAt), and creator attribution (apiKeyId, createdByUserId, invitedByUserId).
  • Organizations — multi-org membership, each with its own role, plus an invite/accept flow by email.
  • Webhooks — registration, delivery inspection, and the full event vocabulary across payments/account/webhooks/security categories.
  • Sandbox — simulate charge and account events with test API keys, no real transactions.
  • Verify — public, unauthenticated proof-of-payment lookup.
  • Distributions — discover settlement payouts claimable within their grace period.
  • Auth & accounts, tokens & networks, errors & health — see packages/types/docs (published at api.klappay.com/types) for the full topic-split reference.

See packages/types/README.md for usage.

Public docs for @klappay/types, mirrored from this package's own docs/ folder.