@klappay/types 2.0.4 → 3.0.1

package/dist/index.mjs

@@ -30,11 +30,26 @@ var ApiKeyScopeSchema = z3.enum([
   "metrics:charges:read",
   "metrics:transactions:read",
   "metrics:distributions:read",
-  "sandbox:trigger"
+  "sandbox:trigger",
+  "charges:split_write",
+  "recipients:read",
+  "recipients:write",
+  "recipients:manage_payout"
 ]).describe(
-  "What an API key is allowed to do, independent of `tenantId`/`environment` (which scope *whose* data, not *what actions*). A key with none of these can still authenticate but every scoped route rejects it with `403 insufficient_scope`. `metrics:read` alone grants every metrics resource; `metrics:{resource}:read` grants only that one \u2014 a key can hold either or both."
+  "What an API key is allowed to do, independent of `tenantId`/`environment` (which scope *whose* data, not *what actions*). A key with none of these can still authenticate but every scoped route rejects it with `403 insufficient_scope`. `metrics:read` alone grants every metrics resource; `metrics:{resource}:read` grants only that one \u2014 a key can hold either or both. `charges:split_write` is required on top of `charges:write` whenever a charge request includes `splitRecipients` \u2014 a key without it can create ordinary charges but never redirect part of the payout. `recipients:write` registers/revokes recipients (addresses eligible to be *referenced* in a split); `recipients:manage_payout` is separate and strictly more sensitive \u2014 it is what lets a recipient actually become an API key's `payoutAddress`, and should be granted only to a key that already went through out-of-band approval for that (Dashboard's own internal key, never a merchant-facing or third-party integration key like a marketplace's). `charges:split_write` can never be combined with `recipients:write`/`recipients:manage_payout` on the same key (see `CONFLICTING_SCOPE_PAIRS`) \u2014 Core rejects such a key outright, before any route runs."
 );
 var API_KEY_SCOPES = ApiKeyScopeSchema.options;
+var CONFLICTING_SCOPE_PAIRS = [
+  ["charges:split_write", "recipients:write"],
+  ["charges:split_write", "recipients:manage_payout"]
+];
+function findConflictingScopes(scopes) {
+  const held = new Set(scopes);
+  for (const [a, b] of CONFLICTING_SCOPE_PAIRS) {
+    if (held.has(a) && held.has(b)) return [a, b];
+  }
+  return null;
+}
 
 // src/networks.ts
 import { z as z4 } from "zod";
@@ -133,51 +148,82 @@ var TOKEN_ADDRESSES = {
   }
 };
 
+// src/alt-tokens.ts
+import { z as z7 } from "zod";
+var AltTokenSchema = z7.enum(["ETH", "BNB", "MATIC", "AVAX", "BTC"]).describe(
+  "A non-stablecoin cryptocurrency Klappay trusts as swap input for a charge, via the 0x Swap API \u2014 swapped to one of the charge's `acceptedPayments` tokens before it ever reaches the merchant, so the merchant always receives USDC/USDT regardless of what the payer sent. Only a network's own native currency, plus `BTC` (wrapped) on the networks with deep, reputably-custodied liquidity, is trusted today (see `ALT_TOKEN_ADDRESSES`) \u2014 never assume every value here is available on every network."
+);
+var ALT_TOKEN_DECIMALS = {
+  ETH: 18,
+  BNB: 18,
+  MATIC: 18,
+  AVAX: 18,
+  BTC: 8
+};
+var ALT_TOKEN_ADDRESSES = {
+  base: { ETH: "native", BTC: "0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf" },
+  optimism: { ETH: "native", BTC: "0x68f180fcCe6836688e9084f035309E29Bf0A2095" },
+  ethereum: { ETH: "native", BTC: "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599" },
+  arbitrum: { ETH: "native", BTC: "0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f" },
+  polygon: { MATIC: "native", BTC: "0x1BFD67037B42Cf73acF2047067bd4F2C47D9BfD6" },
+  avalanche: { AVAX: "native" },
+  bnb: { BNB: "native" }
+};
+function listAltTokensForNetworks(networks) {
+  const found = /* @__PURE__ */ new Set();
+  for (const network of networks) {
+    for (const token of Object.keys(ALT_TOKEN_ADDRESSES[network] ?? {})) {
+      found.add(token);
+    }
+  }
+  return [...found];
+}
+
 // src/charges.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 
 // src/checkout-metadata.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var CHECKOUT_PRODUCTS_MAX = 20;
-var CheckoutProductSchema = z7.object({
-  name: z7.string().min(1).max(200).describe("What the payer is buying, shown as-is on the hosted checkout page."),
-  quantity: z7.number().int().positive().max(9999).optional().describe("How many of this item. Omit for a single, unquantified item."),
-  imageUrl: z7.string().url().max(2048).refine((value) => /^https?:\/\//.test(value), "must use http or https").optional().describe(
+var CheckoutProductSchema = z8.object({
+  name: z8.string().min(1).max(200).describe("What the payer is buying, shown as-is on the hosted checkout page."),
+  quantity: z8.number().int().positive().max(9999).optional().describe("How many of this item. Omit for a single, unquantified item."),
+  imageUrl: z8.string().url().max(2048).refine((value) => /^https?:\/\//.test(value), "must use http or https").optional().describe(
     "Product image, fetched only by the payer's own browser \u2014 Klappay never fetches it server-side. Must be `http(s)`."
   )
 });
-var KlappayCheckoutMetadataSchema = z7.object({
-  products: z7.array(CheckoutProductSchema).max(CHECKOUT_PRODUCTS_MAX).optional().describe(
+var KlappayCheckoutMetadataSchema = z8.object({
+  products: z8.array(CheckoutProductSchema).max(CHECKOUT_PRODUCTS_MAX).optional().describe(
     `What the payer is buying, shown on the hosted checkout page \u2014 up to ${CHECKOUT_PRODUCTS_MAX} items. Purely informational: never validated against \`amount\`, never used by any payment or distribution logic.`
   )
 }).describe(
   "Reserved for Klappay \u2014 the one namespace inside `metadata` whose format is defined and enforced by Klappay, not by you. A `metadata.klappay` that does not match this shape is rejected outright (`400 validation_error`), unlike every other key in `metadata`, which accepts absolutely anything and never fails validation."
 );
-var MetadataWithKlappaySchema = z7.object({ klappay: KlappayCheckoutMetadataSchema.optional() }).catchall(z7.unknown()).describe(
+var MetadataWithKlappaySchema = z8.object({ klappay: KlappayCheckoutMetadataSchema.optional() }).catchall(z8.unknown()).describe(
   "Arbitrary key/value data, returned as-is on every read. Put whatever you want in here \u2014 none of it is validated, except the `klappay` key, which is reserved for Klappay: if present, it must match `KlappayCheckoutMetadataSchema` exactly, or the whole request is rejected with `400 validation_error`."
 );
 
 // src/charges.ts
-var ChargeStatusSchema = z8.enum(["pending", "partially_paid", "confirmed", "expired", "underpaid"]).describe(
+var ChargeStatusSchema = z9.enum(["pending", "partially_paid", "confirmed", "expired", "underpaid"]).describe(
   "Payment progress, from the payer side. `pending`: created, nothing received yet. `partially_paid`: some funds received, less than `amount`. `confirmed`: full amount received (or more \u2014 see `isOverpaid`). `expired`: `expiresAt` passed with zero funds received. `underpaid`: `expiresAt` passed while `partially_paid`. Every status is reached automatically, on its own timeline \u2014 there is no merchant-initiated cancellation. This never reflects whether funds actually reached the merchant \u2014 see `settlementStatus` for that."
 );
-var SettlementStatusSchema = z8.enum(["pending", "completed", "failed"]).describe(
+var SettlementStatusSchema = z9.enum(["pending", "completed", "failed"]).describe(
   "Progress of the payout to the merchant's wallet, a separate step from `status` \u2014 `status: confirmed` only means the payment was detected on-chain, not that the merchant has been paid yet. `pending`: payment detected, payout not yet attempted. `completed`: the merchant's wallet has the funds. `failed`: the payout attempt failed and retries were exhausted (rare; contact support). `null` on the parent `Charge` means no payout has been attempted yet \u2014 nothing has been received, or the charge is still in progress."
 );
 var CHARGE_EXPIRES_IN_MIN_SECONDS = 60;
 var CHARGE_EXPIRES_IN_MAX_SECONDS = 3600;
 var CHARGE_ACCEPTED_PAYMENTS_MAX = 14;
-var AcceptedPaymentSchema = z8.object({
+var AcceptedPaymentSchema = z9.object({
   token: TokenSchema,
   network: NetworkSchema
 });
-var AcceptedPaymentsSchema = z8.array(AcceptedPaymentSchema).min(1, "At least one accepted payment is required.").max(CHARGE_ACCEPTED_PAYMENTS_MAX).superRefine((pairs, ctx) => {
+var AcceptedPaymentsSchema = z9.array(AcceptedPaymentSchema).min(1, "At least one accepted payment is required.").max(CHARGE_ACCEPTED_PAYMENTS_MAX).superRefine((pairs, ctx) => {
   const seen = /* @__PURE__ */ new Set();
   pairs.forEach((pair, index) => {
     const key = `${pair.token}:${pair.network}`;
     if (seen.has(key)) {
       ctx.addIssue({
-        code: z8.ZodIssueCode.custom,
+        code: z9.ZodIssueCode.custom,
         message: `Duplicate accepted payment: ${pair.token} on ${pair.network}.`,
         path: [index]
       });
@@ -185,7 +231,7 @@ var AcceptedPaymentsSchema = z8.array(AcceptedPaymentSchema).min(1, "At least on
     seen.add(key);
     if (!OPERATIONAL_NETWORKS.includes(pair.network)) {
       ctx.addIssue({
-        code: z8.ZodIssueCode.custom,
+        code: z9.ZodIssueCode.custom,
         message: `Network "${pair.network}" isn't live yet \u2014 only ${OPERATIONAL_NETWORKS.join(", ")} today.`,
         path: [index, "network"]
       });
@@ -195,105 +241,118 @@ var AcceptedPaymentsSchema = z8.array(AcceptedPaymentSchema).min(1, "At least on
   `Every \`(token, network)\` pair the payer is allowed to pay with \u2014 at least one, up to ${CHARGE_ACCEPTED_PAYMENTS_MAX}. This list is also the only restriction knob: the payer can use any combination of the pairs listed here, and every transfer on one of them is credited and sums toward the charge total (see \`paidWith\`) \u2014 e.g. a charge accepting USDC and USDT can be confirmed by $9 in USDC plus $1 in USDT, or by USDC arriving on two different accepted networks. To require payment in one specific token on one specific network, list only that single pair \u2014 a transfer on any pair not in this list is still recorded (for audit) but never credited. Each network must be live (see \`GET /v1/networks\` for the current matrix) \u2014 an unconfigured \`(token, network)\` combination for your environment is rejected with \`422 token_not_supported\`.`
 );
 var CHARGE_SPLIT_RECIPIENTS_MAX = 5;
-var SplitRecipientSchema = z8.object({
-  address: z8.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be a 20-byte hex address").describe("EVM address to send a slice of this charge to."),
-  percent: z8.number().positive().max(100).describe(
+var SplitRecipientSchema = z9.object({
+  address: z9.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be a 20-byte hex address").describe("EVM address to send a slice of this charge to."),
+  percent: z9.number().positive().max(100).describe(
     "Percent of *your own* net share (i.e. of `100 - feePercent`, not of the charge's gross `amount`) to route to this address instead of your own payout wallet. Klappay's fee is computed on the gross amount first and is never diluted by how you choose to split what's left \u2014 see `docs/payments.md`'s \"Settling the payout\" section for the exact math."
   ),
-  label: z8.string().min(1).max(64).optional().describe(
+  label: z9.string().min(1).max(64).optional().describe(
     'Free-form label for your own bookkeeping (e.g. `"supplier"`, `"sales rep"`) \u2014 echoed back unchanged, never interpreted by Klappay.'
   )
 });
-var SplitRecipientsSchema = z8.array(SplitRecipientSchema).max(CHARGE_SPLIT_RECIPIENTS_MAX).superRefine((recipients, ctx) => {
+var SplitRecipientInputSchema = z9.object({
+  recipientId: z9.string().describe(
+    "id of a `Recipient` you already registered via `POST /v1/recipients` (not a raw address) \u2014 see `recipients:write`/`charges:split_write` scopes. A leaked `charges:write`-only key can never redirect payout to a brand new address this way, only reference one already trusted."
+  ),
+  percent: z9.number().positive().max(100).describe(
+    "Percent of *your own* net share (i.e. of `100 - feePercent`, not of the charge's gross `amount`) to route to this recipient instead of your own payout wallet. Klappay's fee is computed on the gross amount first and is never diluted by how you choose to split what's left \u2014 see `docs/payments.md`'s \"Settling the payout\" section for the exact math."
+  ),
+  label: z9.string().min(1).max(64).optional().describe(
+    'Free-form label for your own bookkeeping (e.g. `"supplier"`, `"sales rep"`) \u2014 echoed back unchanged, never interpreted by Klappay. Independent of the label the recipient was registered with.'
+  )
+});
+var SplitRecipientsInputSchema = z9.array(SplitRecipientInputSchema).max(CHARGE_SPLIT_RECIPIENTS_MAX).superRefine((recipients, ctx) => {
   const seen = /* @__PURE__ */ new Set();
   recipients.forEach((recipient, index) => {
-    const key = recipient.address.toLowerCase();
-    if (seen.has(key)) {
+    if (seen.has(recipient.recipientId)) {
       ctx.addIssue({
-        code: z8.ZodIssueCode.custom,
-        message: `Duplicate split recipient address: ${recipient.address}.`,
-        path: [index, "address"]
+        code: z9.ZodIssueCode.custom,
+        message: `Duplicate split recipientId: ${recipient.recipientId}.`,
+        path: [index, "recipientId"]
       });
     }
-    seen.add(key);
+    seen.add(recipient.recipientId);
   });
 }).describe(
-  `Optional extra recipients for this charge's split \u2014 e.g. a supplier or the sales rep who closed the deal \u2014 up to ${CHARGE_SPLIT_RECIPIENTS_MAX}. Frozen at creation exactly like everything else that shapes the split address; cannot be changed afterward. The sum of every \`percent\` here must fit within \`100 - feePercent\` (your own net share) \u2014 a request that doesn't is rejected with \`422 split_recipients_exceed_available_percent\`.`
+  `Optional extra recipients for this charge's split \u2014 e.g. a supplier or the sales rep who closed the deal \u2014 up to ${CHARGE_SPLIT_RECIPIENTS_MAX}, each referenced by \`recipientId\` (see \`POST /v1/recipients\`), never a raw address. Requires the \`charges:split_write\` scope in addition to \`charges:write\`. Frozen at creation exactly like everything else that shapes the split address; cannot be changed afterward. The sum of every \`percent\` here must fit within \`100 - feePercent\` (your own net share) \u2014 a request that doesn't is rejected with \`422 split_recipients_exceed_available_percent\`.`
 );
 var CHARGE_AMOUNT_MAX = 999999999999;
-var CreateChargeSchema = z8.object({
-  amount: z8.number().positive().max(CHARGE_AMOUNT_MAX).describe(
+var CreateChargeSchema = z9.object({
+  amount: z9.number().positive().max(CHARGE_AMOUNT_MAX).describe(
     "Amount to charge, in `currency` units (e.g. `49.9` = $49.90) \u2014 up to 6 decimal places; anything more precise is silently truncated. Required \u2014 every charge has a target amount, the first credited transfer that reaches it confirms the charge."
   ),
-  currency: z8.literal("USD").default("USD").describe("Always `USD` today \u2014 the only supported currency."),
+  currency: z9.literal("USD").default("USD").describe("Always `USD` today \u2014 the only supported currency."),
   acceptedPayments: AcceptedPaymentsSchema,
-  expiresIn: z8.number().int().min(CHARGE_EXPIRES_IN_MIN_SECONDS).max(CHARGE_EXPIRES_IN_MAX_SECONDS).describe(
+  expiresIn: z9.number().int().min(CHARGE_EXPIRES_IN_MIN_SECONDS).max(CHARGE_EXPIRES_IN_MAX_SECONDS).describe(
     "Seconds, not minutes or milliseconds \u2014 how long the charge stays open before it expires. Required, min 60, max 3600 (60 minutes) \u2014 sized off the slowest chain Klappay supports today (Ethereum mainnet, where a safely-confirmed transfer takes up to ~15 minutes), leaving real margin for payer-side delay (gas spikes, wallet friction) on top of that. Cannot be extended or shortened after creation."
   ),
-  idempotencyKey: z8.string().min(1).max(255).optional().describe(
+  idempotencyKey: z9.string().min(1).max(255).optional().describe(
     "Scoped to your tenant. Replaying the same key returns the original charge unchanged instead of creating a duplicate \u2014 safe to retry a request after a timeout without double-charging."
   ),
-  externalRef: z8.string().min(1).max(255).optional().describe(
+  externalRef: z9.string().min(1).max(255).optional().describe(
     "An opaque correlation id from your own system (e.g. an order id) \u2014 echoed back on the charge and in every webhook payload. Not interpreted or validated by Klappay."
   ),
-  source: z8.string().min(1).max(64).optional().describe(
+  source: z9.string().min(1).max(64).optional().describe(
     'Free-form label for what created this charge (e.g. `"checkout"`, `"invoice"`) \u2014 useful if you create charges from more than one flow and want to tell them apart later. Not a fixed enum; use whatever values make sense to you.'
   ),
   metadata: MetadataWithKlappaySchema.optional(),
-  redirectUrl: z8.string().url().refine((value) => /^https?:\/\//.test(value), "must use http or https").optional().describe(
+  redirectUrl: z9.string().url().refine((value) => /^https?:\/\//.test(value), "must use http or https").optional().describe(
     "Where to send the payer once this charge resolves, if you use Klappay's hosted checkout page (see `checkoutUrl` on the read shape) \u2014 ignored otherwise. Must be `http(s)` \u2014 a browser will navigate here, so `javascript:`/`data:` and other non-navigational schemes are rejected. Otherwise not validated beyond being well-formed; what happens at that destination is yours to build."
   ),
-  splitRecipients: SplitRecipientsSchema.optional()
+  splitRecipients: SplitRecipientsInputSchema.optional()
 });
-var ChargeSchema = z8.object({
-  id: z8.string().describe("Klappay-generated id, e.g. `ch_...`. Use this to look up the charge later."),
-  amount: z8.number().describe("The amount originally requested, in `currency` units (up to 6 decimal places)."),
-  amountReceived: z8.number().nullable().describe(
+var ChargeSchema = z9.object({
+  id: z9.string().describe("Klappay-generated id, e.g. `ch_...`. Use this to look up the charge later."),
+  amount: z9.number().describe("The amount originally requested, in `currency` units (up to 6 decimal places)."),
+  amountReceived: z9.number().nullable().describe(
     "Cumulative amount actually received on-chain so far, in `currency` units (up to 6 decimal places). `null` until the first transfer arrives. Can exceed `amount` \u2014 see `isOverpaid`."
   ),
-  isOverpaid: z8.boolean().describe(
+  isOverpaid: z9.boolean().describe(
     "`true` if `amountReceived` ended up greater than `amount`. Klappay never refunds the difference automatically \u2014 see the docs for why."
   ),
-  currency: z8.string().describe("Always `USD` today \u2014 the only supported currency."),
-  acceptedPayments: z8.array(AcceptedPaymentSchema).describe(
+  currency: z9.string().describe("Always `USD` today \u2014 the only supported currency."),
+  acceptedPayments: z9.array(AcceptedPaymentSchema).describe(
     "Every `(token, network)` pair this charge was configured to accept, unchanged after creation."
   ),
-  paidWith: z8.array(AcceptedPaymentSchema).describe(
+  paidWith: z9.array(AcceptedPaymentSchema).describe(
     "Every distinct `(token, network)` pair that has actually contributed a credited transfer so far \u2014 empty until the first one arrives. Can hold more than one entry: a charge accepting several pairs can be paid across a combination of them, and every entry here sums toward `amountReceived`."
   ),
-  address: z8.string().describe(
+  swapAlternatives: z9.array(AltTokenSchema).describe(
+    "Non-stablecoin cryptocurrencies the payer can pay with instead, via `POST /v1/charges/{id}/quote` \u2014 derived from the networks in `acceptedPayments` (e.g. a charge accepting USDC on Base lists `ETH` here, since Base's native currency is trusted as swap input). Recomputed on every read against Klappay's current trusted list, not frozen at creation \u2014 empty if this charge's networks have no trusted alt-token, or if swap-to-pay isn't configured on this deployment."
+  ),
+  address: z9.string().describe(
     "The on-chain address the payer must send funds to \u2014 identical across every accepted network (0xSplits addresses are chain-agnostic). Unique per charge, predicted at creation time \u2014 funds sent here go directly to the merchant, Klappay never custodies them."
   ),
   status: ChargeStatusSchema,
   settlementStatus: SettlementStatusSchema.nullable(),
   environment: EnvironmentSchema,
-  apiKeyId: z8.string().nullable().describe(
+  apiKeyId: z9.string().nullable().describe(
     "Which of your API keys created this charge. `null` for a charge created before this field existed."
   ),
-  txHash: z8.string().nullable().describe(
+  txHash: z9.string().nullable().describe(
     "Transaction hash of the most recent transfer detected for this charge. `null` until a payment is detected."
   ),
-  externalRef: z8.string().nullable(),
-  source: z8.string().nullable(),
+  externalRef: z9.string().nullable(),
+  source: z9.string().nullable(),
   metadata: MetadataWithKlappaySchema.nullable(),
-  redirectUrl: z8.string().nullable().describe("Echoes the `redirectUrl` set at creation, if any. `null` if none was set."),
-  checkoutUrl: z8.string().nullable().describe(
+  redirectUrl: z9.string().nullable().describe("Echoes the `redirectUrl` set at creation, if any. `null` if none was set."),
+  checkoutUrl: z9.string().nullable().describe(
     "Link to Klappay's hosted checkout page for this charge. `null` if this deployment has no hosted checkout configured \u2014 build your own payment UI from `address`/`acceptedPayments` instead."
   ),
-  splitRecipients: z8.array(SplitRecipientSchema).describe("Echoes whatever extra split recipients were set at creation \u2014 empty array if none."),
-  createdAt: z8.string().datetime(),
-  expiresAt: z8.string().datetime().describe(
+  splitRecipients: z9.array(SplitRecipientSchema).describe("Echoes whatever extra split recipients were set at creation \u2014 empty array if none."),
+  createdAt: z9.string().datetime(),
+  expiresAt: z9.string().datetime().describe(
     "When this charge stops accepting payment, if still `pending`/`partially_paid` by then."
   ),
-  confirmedAt: z8.string().datetime().nullable().describe("When `status` first reached `confirmed`. `null` until then."),
-  settledAt: z8.string().datetime().nullable().describe(
+  confirmedAt: z9.string().datetime().nullable().describe("When `status` first reached `confirmed`. `null` until then."),
+  settledAt: z9.string().datetime().nullable().describe(
     "When `settlementStatus` first reached `completed` \u2014 the merchant's wallet actually has the funds. `null` until then, including while `settlementStatus` is `pending`/`failed`."
   ),
-  lastActivityAt: z8.string().datetime().describe(
+  lastActivityAt: z9.string().datetime().describe(
     "When a transfer was last credited toward this charge, or `createdAt` if none has arrived yet."
   )
 });
-var ListChargesSchema = z8.object({
+var ListChargesSchema = z9.object({
   status: ChargeStatusSchema.optional(),
   token: TokenSchema.optional().describe(
     "Filters on `paidWith.token` \u2014 the pair actually paid, not accepted."
@@ -302,13 +361,13 @@ var ListChargesSchema = z8.object({
     "Filters on `paidWith.network` \u2014 the pair actually paid, not accepted."
   ),
   environment: EnvironmentSchema.optional(),
-  since: z8.string().datetime().optional().describe(
+  since: z9.string().datetime().optional().describe(
     "Only return charges created at or after this timestamp (filters on `createdAt`, not on when the status last changed). If polling as a fallback for missed webhooks, use a window at least as wide as the longest `expiresIn` your charges use, or you can miss a long-lived charge that changed status outside a narrower window."
   ),
-  isOverpaid: z8.enum(["true", "false"]).transform((v) => v === "true").optional()
+  isOverpaid: z9.enum(["true", "false"]).transform((v) => v === "true").optional()
 }).extend(PaginationQuerySchema.shape);
 var PaginatedChargesSchema = paginatedSchema(ChargeSchema);
-var GetChargeQrCodeQuerySchema = z8.object({
+var GetChargeQrCodeQuerySchema = z9.object({
   token: TokenSchema.optional().describe(
     "Which accepted `(token, network)` pair to encode in the QR \u2014 required if `acceptedPayments` has more than one pair, since there is no single unambiguous default to fall back to. Ignored (and unnecessary) when the charge accepts exactly one pair."
   ),
@@ -316,61 +375,61 @@ var GetChargeQrCodeQuerySchema = z8.object({
 });
 
 // src/distributions.ts
-import { z as z9 } from "zod";
-var SplitDistributionStatusSchema = z9.enum(["pending", "processing", "completed", "failed"]).describe(
+import { z as z10 } from "zod";
+var SplitDistributionStatusSchema = z10.enum(["pending", "processing", "completed", "failed"]).describe(
   "Status of one payout attempt to the merchant, for a single `(token, network)` pair \u2014 a charge that settles across more than one pair has one of these per pair. `pending`: queued, not yet claimed by a distributor. `processing`: a distributor (Klappay's own worker, or anyone racing to call `distribute()` first, see `PendingDistributionSchema`) has claimed it and is submitting the on-chain transaction. `completed`: the merchant's wallet has the funds. `failed`: every automatic retry was exhausted."
 );
-var PendingDistributionRecipientSchema = z9.object({
-  address: z9.string().describe("On-chain recipient address."),
-  percentAllocation: z9.number().describe("This recipient's share of the split, as a percentage (e.g. `99.0991` = 99.0991%).")
+var PendingDistributionRecipientSchema = z10.object({
+  address: z10.string().describe("On-chain recipient address."),
+  percentAllocation: z10.number().describe("This recipient's share of the split, as a percentage (e.g. `99.0991` = 99.0991%).")
 });
-var PendingDistributionSchema = z9.object({
-  splitAddress: z9.string().describe("The on-chain 0xSplits address to call `distribute()` on."),
+var PendingDistributionSchema = z10.object({
+  splitAddress: z10.string().describe("The on-chain 0xSplits address to call `distribute()` on."),
   network: NetworkSchema,
   token: TokenSchema,
-  recipients: z9.array(PendingDistributionRecipientSchema).describe(
+  recipients: z10.array(PendingDistributionRecipientSchema).describe(
     "The exact recipient list to pass to `distribute()` \u2014 the split contract only stores a hash of this config, so the caller must supply the identical array to prove it matches. Always present, never reconstructed from partial data."
   ),
-  distributorFeePercent: z9.number().describe(
+  distributorFeePercent: z10.number().describe(
     "Percentage of the split balance paid to whoever calls `distribute()` first (e.g. `0.1` = 0.1%). Frozen at charge creation, same for every distribution today."
   ),
-  estimatedRewardAmount: z9.number().describe(
+  estimatedRewardAmount: z10.number().describe(
     "Estimate only, in the charge's `currency` units, based on the amount Klappay detected on-chain \u2014 not a live read of the split's current balance. Read the balance yourself before submitting a transaction; a stale estimate is harmless (see the docs), never a reason to skip that check."
   ),
-  availableSince: z9.string().datetime().describe("When this distribution entered its grace period."),
-  graceEndsAt: z9.string().datetime().describe(
+  availableSince: z10.string().datetime().describe("When this distribution entered its grace period."),
+  graceEndsAt: z10.string().datetime().describe(
     "When Klappay's own worker may claim this distribution. Racing to call `distribute()` after this timestamp is possible but increasingly likely to lose to the worker."
   )
 });
 var PaginatedPendingDistributionsSchema = paginatedSchema(PendingDistributionSchema);
-var ListenPendingDistributionsQuerySchema = z9.object({
-  limit: z9.coerce.number().int().min(0).max(PAGINATION_LIMIT_MAX).default(0).describe(
+var ListenPendingDistributionsQuerySchema = z10.object({
+  limit: z10.coerce.number().int().min(0).max(PAGINATION_LIMIT_MAX).default(0).describe(
     "How many currently-claimable distributions to emit as an initial snapshot right after connecting \u2014 each as a synthetic `distribution.available` event \u2014 before continuing with real-time deltas. `0` (the default, same as omitting it) sends no snapshot at all, matching this endpoint's original behavior: connect first, then call `GET /v1/distributions/pending` yourself to bootstrap. Not a page \u2014 there is no cursor for this snapshot, so if more than `limit` are claimable at connect time, the excess is simply not sent; call `GET /v1/distributions/pending` directly for a complete, paginated listing."
   )
 });
-var PendingDistributionEventSchema = z9.discriminatedUnion("type", [
-  z9.object({
-    type: z9.literal("distribution.available"),
+var PendingDistributionEventSchema = z10.discriminatedUnion("type", [
+  z10.object({
+    type: z10.literal("distribution.available"),
     distribution: PendingDistributionSchema
   }),
-  z9.object({
-    type: z9.literal("distribution.claimed"),
-    splitAddress: z9.string().describe("No longer claimable \u2014 either settled by someone, or picked up by the worker.")
+  z10.object({
+    type: z10.literal("distribution.claimed"),
+    splitAddress: z10.string().describe("No longer claimable \u2014 either settled by someone, or picked up by the worker.")
   })
 ]);
 
 // src/metrics.ts
-import { z as z10 } from "zod";
-var MetricsResourceSchema = z10.enum(["charges", "transactions", "distributions"]).describe(
+import { z as z11 } from "zod";
+var MetricsResourceSchema = z11.enum(["charges", "transactions", "distributions"]).describe(
   "Which underlying dataset to query. `charges`: one row per charge. `transactions`: one row per detected on-chain transfer \u2014 a charge paid in installments has more than one. `distributions`: one row per payout attempt to the merchant, one per `(token, network)` pair a charge settled across."
 );
-var MetricsAggregationSchema = z10.enum(["count", "sum", "avg", "min", "max"]).describe(
+var MetricsAggregationSchema = z11.enum(["count", "sum", "avg", "min", "max"]).describe(
   "`count` counts matching rows and never takes `field`. `sum`/`avg`/`min`/`max` require `field` to be set to one of the resource\u2019s numeric fields."
 );
-var MetricsFilterOperatorSchema = z10.enum(["eq", "neq", "in", "gt", "gte", "lt", "lte"]).describe(
+var MetricsFilterOperatorSchema = z11.enum(["eq", "neq", "in", "gt", "gte", "lt", "lte"]).describe(
   "`in` expects an array value (max 50 entries); every other operator expects a single scalar."
 );
-var MetricsDateGranularitySchema = z10.enum(["day", "week", "month", "year"]).describe(
+var MetricsDateGranularitySchema = z11.enum(["day", "week", "month", "year"]).describe(
   "Bucket width for a `date_bucket` `groupBy` entry \u2014 Postgres `date_trunc` semantics (UTC)."
 );
 var metricsQueryEnvironmentSchema = EnvironmentSchema.describe(
@@ -383,151 +442,151 @@ var METRICS_QUERY_MAX_GROUP_BY = 3;
 var METRICS_QUERY_MAX_FILTERS = 20;
 var METRICS_QUERY_MAX_METRICS = 10;
 var METRIC_ALIAS_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
-var metricAliasSchema = z10.string().min(1).max(64).regex(
+var metricAliasSchema = z11.string().min(1).max(64).regex(
   METRIC_ALIAS_PATTERN,
   "Must start with a letter or underscore, and contain only letters, digits, and underscores \u2014 this becomes a SQL column alias."
 ).optional();
-var MetricsFilterValueSchema = z10.union([
-  z10.string().max(255),
-  z10.number(),
-  z10.boolean(),
-  z10.array(z10.union([z10.string().max(255), z10.number()])).min(1).max(50)
+var MetricsFilterValueSchema = z11.union([
+  z11.string().max(255),
+  z11.number(),
+  z11.boolean(),
+  z11.array(z11.union([z11.string().max(255), z11.number()])).min(1).max(50)
 ]);
-var orderBySchema = z10.object({
-  key: z10.string().min(1).max(64).regex(
+var orderBySchema = z11.object({
+  key: z11.string().min(1).max(64).regex(
     METRIC_ALIAS_PATTERN,
     "Must start with a letter or underscore, and contain only letters, digits, and underscores \u2014 every valid output column name already looks like this."
   ).describe(
     "An output column name from this same query \u2014 either a `groupBy` field name, or a metric\u2019s `alias` (or its default name: `${aggregation}` for `count`, `${aggregation}_${field}` otherwise, e.g. `sum_amount`). Must match `^[a-zA-Z_][a-zA-Z0-9_]*$` \u2014 every real output column name already does, so this only ever rejects a value that could never have been one."
   ),
-  direction: z10.enum(["asc", "desc"])
+  direction: z11.enum(["asc", "desc"])
 }).describe(
   "Sort the result rows by any output column \u2014 including the bucket field itself for a `date_bucket` query (e.g. `createdAt`). Omit to get ascending-by-bucket order for a date-bucketed query, or implementation-defined (not guaranteed stable) order otherwise."
 );
-var limitSchema = z10.number().int().min(1).max(METRICS_QUERY_MAX_ROW_LIMIT).default(METRICS_QUERY_DEFAULT_ROW_LIMIT).describe(
+var limitSchema = z11.number().int().min(1).max(METRICS_QUERY_MAX_ROW_LIMIT).default(METRICS_QUERY_DEFAULT_ROW_LIMIT).describe(
   `Max rows to return, ${1}\u2013${METRICS_QUERY_MAX_ROW_LIMIT}, default ${METRICS_QUERY_DEFAULT_ROW_LIMIT}. If more rows matched, \`meta.truncated\` is \`true\` on the response \u2014 narrow the query instead of just raising this.`
 );
-var ChargesQueryFieldSchema = z10.enum(["status", "source", "apiKeyId", "currency", "isOverpaid", "externalRef"]).describe(
+var ChargesQueryFieldSchema = z11.enum(["status", "source", "apiKeyId", "currency", "isOverpaid", "externalRef"]).describe(
   "A `Charge` field to filter or group by \u2014 see `ChargeStatusSchema` for `status`'s own possible values (charges.md). `source`/`externalRef` are free-form strings your own integration set at creation, not a fixed enum."
 );
-var ChargesMetricFieldSchema = z10.enum(["amount", "amountReceived", "feePercent"]).describe(
+var ChargesMetricFieldSchema = z11.enum(["amount", "amountReceived", "feePercent"]).describe(
   "A `Charge` numeric field to aggregate. `amount`/`amountReceived` are decimal currency amounts (requested vs. actually received \u2014 see `charges.md`). `feePercent` is the platform fee frozen on the charge at creation, e.g. `1.5` means 1.5%."
 );
-var ChargesDateFieldSchema = z10.enum(["createdAt", "confirmedAt", "lastActivityAt", "expiresAt"]).describe(
+var ChargesDateFieldSchema = z11.enum(["createdAt", "confirmedAt", "lastActivityAt", "expiresAt"]).describe(
   "A `Charge` timestamp to filter/bucket by. `confirmedAt` is `null` until the charge reaches `confirmed` \u2014 a `dateRange`/`date_bucket` on it implicitly excludes every charge that never confirmed. `expiresAt` is always present (set at creation), useful for e.g. finding charges expiring soon or measuring how close to expiry charges typically resolve."
 );
-var ChargesFilterSchema = z10.object({
+var ChargesFilterSchema = z11.object({
   field: ChargesQueryFieldSchema,
   operator: MetricsFilterOperatorSchema,
   value: MetricsFilterValueSchema
 });
-var ChargesGroupBySchema = z10.union([
-  z10.object({ type: z10.literal("field"), field: ChargesQueryFieldSchema }),
-  z10.object({
-    type: z10.literal("date_bucket"),
+var ChargesGroupBySchema = z11.union([
+  z11.object({ type: z11.literal("field"), field: ChargesQueryFieldSchema }),
+  z11.object({
+    type: z11.literal("date_bucket"),
     field: ChargesDateFieldSchema,
     granularity: MetricsDateGranularitySchema
   })
 ]);
-var ChargesMetricSchema = z10.object({
+var ChargesMetricSchema = z11.object({
   aggregation: MetricsAggregationSchema,
   field: ChargesMetricFieldSchema.optional(),
   alias: metricAliasSchema
 });
-var ChargesMetricsQuerySchema = z10.object({
-  resource: z10.literal("charges"),
+var ChargesMetricsQuerySchema = z11.object({
+  resource: z11.literal("charges"),
   environment: metricsQueryEnvironmentSchema,
-  dateRange: z10.object({
+  dateRange: z11.object({
     field: ChargesDateFieldSchema,
-    from: z10.string().max(64).datetime(),
-    to: z10.string().max(64).datetime()
+    from: z11.string().max(64).datetime(),
+    to: z11.string().max(64).datetime()
   }),
-  groupBy: z10.array(ChargesGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
-  metrics: z10.array(ChargesMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
-  filters: z10.array(ChargesFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
+  groupBy: z11.array(ChargesGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
+  metrics: z11.array(ChargesMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
+  filters: z11.array(ChargesFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
   orderBy: orderBySchema.optional(),
   limit: limitSchema
 });
-var TransactionsQueryFieldSchema = z10.enum(["network", "token", "source", "causedTransition"]).describe(
+var TransactionsQueryFieldSchema = z11.enum(["network", "token", "source", "causedTransition"]).describe(
   "A `Transaction` field to filter or group by \u2014 see `NetworkSchema`/`TokenSchema`/`TransactionSourceSchema` for their possible values. `causedTransition` is `true` only for the transfer(s) that actually flipped the charge's `status` \u2014 a charge paid in installments can have more than one; filtering/grouping on it excludes no-op duplicate transfers (see `TimelineEvent.causedTransition` in charges.md for the full explanation)."
 );
-var TransactionsMetricFieldSchema = z10.enum(["amount"]).describe("The transfer amount, in the charge's `currency` units.");
-var TransactionsDateFieldSchema = z10.enum(["detectedAt"]).describe("When Klappay detected this transfer on-chain (not when it was mined).");
-var TransactionsFilterSchema = z10.object({
+var TransactionsMetricFieldSchema = z11.enum(["amount"]).describe("The transfer amount, in the charge's `currency` units.");
+var TransactionsDateFieldSchema = z11.enum(["detectedAt"]).describe("When Klappay detected this transfer on-chain (not when it was mined).");
+var TransactionsFilterSchema = z11.object({
   field: TransactionsQueryFieldSchema,
   operator: MetricsFilterOperatorSchema,
   value: MetricsFilterValueSchema
 });
-var TransactionsGroupBySchema = z10.union([
-  z10.object({ type: z10.literal("field"), field: TransactionsQueryFieldSchema }),
-  z10.object({
-    type: z10.literal("date_bucket"),
+var TransactionsGroupBySchema = z11.union([
+  z11.object({ type: z11.literal("field"), field: TransactionsQueryFieldSchema }),
+  z11.object({
+    type: z11.literal("date_bucket"),
     field: TransactionsDateFieldSchema,
     granularity: MetricsDateGranularitySchema
   })
 ]);
-var TransactionsMetricSchema = z10.object({
+var TransactionsMetricSchema = z11.object({
   aggregation: MetricsAggregationSchema,
   field: TransactionsMetricFieldSchema.optional(),
   alias: metricAliasSchema
 });
-var TransactionsMetricsQuerySchema = z10.object({
-  resource: z10.literal("transactions"),
+var TransactionsMetricsQuerySchema = z11.object({
+  resource: z11.literal("transactions"),
   environment: metricsQueryEnvironmentSchema,
-  dateRange: z10.object({
+  dateRange: z11.object({
     field: TransactionsDateFieldSchema,
-    from: z10.string().max(64).datetime(),
-    to: z10.string().max(64).datetime()
+    from: z11.string().max(64).datetime(),
+    to: z11.string().max(64).datetime()
   }),
-  groupBy: z10.array(TransactionsGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
-  metrics: z10.array(TransactionsMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
-  filters: z10.array(TransactionsFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
+  groupBy: z11.array(TransactionsGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
+  metrics: z11.array(TransactionsMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
+  filters: z11.array(TransactionsFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
   orderBy: orderBySchema.optional(),
   limit: limitSchema
 });
-var DistributionsQueryFieldSchema = z10.enum(["status", "network", "token", "distributorAddress"]).describe(
+var DistributionsQueryFieldSchema = z11.enum(["status", "network", "token", "distributorAddress"]).describe(
   "A `SplitDistribution` field to filter or group by \u2014 see `SplitDistributionStatusSchema`/`NetworkSchema`/`TokenSchema` for their possible values. `distributorAddress` is the public on-chain address that actually called `distribute()` for a `completed` distribution \u2014 Klappay's own operator address if settled by Klappay's own worker, a community keeper's address if settled externally (or `null` on the rare case that lookup failed), `null` for every non-`completed` status."
 );
-var DistributionsMetricFieldSchema = z10.enum(["attempts"]).describe(
+var DistributionsMetricFieldSchema = z11.enum(["attempts"]).describe(
   "How many times a payout was attempted for this settlement so far \u2014 incremented on every attempt, whether it succeeded or is being retried after failing. A high `attempts` alongside `status: 'failed'` means every automatic retry was exhausted."
 );
-var DistributionsDateFieldSchema = z10.enum(["createdAt", "processingStartedAt", "completedAt"]).describe(
+var DistributionsDateFieldSchema = z11.enum(["createdAt", "processingStartedAt", "completedAt"]).describe(
   "`createdAt`: when this settlement was queued. `processingStartedAt`: when a worker began its most recent attempt at the payout \u2014 `null` until the first attempt, then overwritten on every subsequent retry, so it reflects the *latest* attempt's start, not the first. `completedAt`: when it actually paid out \u2014 `null` until `status` reaches `completed`, so a `dateRange`/`date_bucket` on it implicitly excludes every distribution still pending/processing/failed."
 );
-var DistributionsFilterSchema = z10.object({
+var DistributionsFilterSchema = z11.object({
   field: DistributionsQueryFieldSchema,
   operator: MetricsFilterOperatorSchema,
   value: MetricsFilterValueSchema
 });
-var DistributionsGroupBySchema = z10.union([
-  z10.object({ type: z10.literal("field"), field: DistributionsQueryFieldSchema }),
-  z10.object({
-    type: z10.literal("date_bucket"),
+var DistributionsGroupBySchema = z11.union([
+  z11.object({ type: z11.literal("field"), field: DistributionsQueryFieldSchema }),
+  z11.object({
+    type: z11.literal("date_bucket"),
     field: DistributionsDateFieldSchema,
     granularity: MetricsDateGranularitySchema
   })
 ]);
-var DistributionsMetricSchema = z10.object({
+var DistributionsMetricSchema = z11.object({
   aggregation: MetricsAggregationSchema,
   field: DistributionsMetricFieldSchema.optional(),
   alias: metricAliasSchema
 });
-var DistributionsMetricsQuerySchema = z10.object({
-  resource: z10.literal("distributions"),
+var DistributionsMetricsQuerySchema = z11.object({
+  resource: z11.literal("distributions"),
   environment: metricsQueryEnvironmentSchema,
-  dateRange: z10.object({
+  dateRange: z11.object({
     field: DistributionsDateFieldSchema,
-    from: z10.string().max(64).datetime(),
-    to: z10.string().max(64).datetime()
+    from: z11.string().max(64).datetime(),
+    to: z11.string().max(64).datetime()
   }),
-  groupBy: z10.array(DistributionsGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
-  metrics: z10.array(DistributionsMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
-  filters: z10.array(DistributionsFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
+  groupBy: z11.array(DistributionsGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
+  metrics: z11.array(DistributionsMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
+  filters: z11.array(DistributionsFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
   orderBy: orderBySchema.optional(),
   limit: limitSchema
 });
 var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
-var MetricsQuerySchema = z10.discriminatedUnion("resource", [
+var MetricsQuerySchema = z11.discriminatedUnion("resource", [
   ChargesMetricsQuerySchema,
   TransactionsMetricsQuerySchema,
   DistributionsMetricsQuerySchema
@@ -536,7 +595,7 @@ var MetricsQuerySchema = z10.discriminatedUnion("resource", [
   const to = new Date(input.dateRange.to);
   if (from >= to) {
     ctx.addIssue({
-      code: z10.ZodIssueCode.custom,
+      code: z11.ZodIssueCode.custom,
       message: "`dateRange.from` must be before `dateRange.to`.",
       path: ["dateRange", "from"]
     });
@@ -544,7 +603,7 @@ var MetricsQuerySchema = z10.discriminatedUnion("resource", [
   const spanDays = (to.getTime() - from.getTime()) / ONE_DAY_MS;
   if (spanDays > MAX_METRICS_QUERY_DATE_RANGE_DAYS) {
     ctx.addIssue({
-      code: z10.ZodIssueCode.custom,
+      code: z11.ZodIssueCode.custom,
       message: `\`dateRange\` cannot span more than ${MAX_METRICS_QUERY_DATE_RANGE_DAYS} days.`,
       path: ["dateRange", "to"]
     });
@@ -552,7 +611,7 @@ var MetricsQuerySchema = z10.discriminatedUnion("resource", [
   const dateBucketCount = input.groupBy.filter((entry) => entry.type === "date_bucket").length;
   if (dateBucketCount > 1) {
     ctx.addIssue({
-      code: z10.ZodIssueCode.custom,
+      code: z11.ZodIssueCode.custom,
       message: "At most one `date_bucket` entry is allowed in `groupBy`.",
       path: ["groupBy"]
     });
@@ -560,7 +619,7 @@ var MetricsQuerySchema = z10.discriminatedUnion("resource", [
   input.metrics.forEach((metric, index) => {
     if (metric.aggregation !== "count" && metric.field === void 0) {
       ctx.addIssue({
-        code: z10.ZodIssueCode.custom,
+        code: z11.ZodIssueCode.custom,
         message: "`field` is required unless `aggregation` is `count`.",
         path: ["metrics", index, "field"]
       });
@@ -569,7 +628,7 @@ var MetricsQuerySchema = z10.discriminatedUnion("resource", [
   const aliases = input.metrics.map((metric) => metric.alias).filter((alias) => alias !== void 0);
   if (new Set(aliases).size !== aliases.length) {
     ctx.addIssue({
-      code: z10.ZodIssueCode.custom,
+      code: z11.ZodIssueCode.custom,
       message: "Every `metrics[].alias` must be unique.",
       path: ["metrics"]
     });
@@ -578,32 +637,32 @@ var MetricsQuerySchema = z10.discriminatedUnion("resource", [
   input.metrics.forEach((metric, index) => {
     if (metric.alias !== void 0 && reservedNames.has(metric.alias)) {
       ctx.addIssue({
-        code: z10.ZodIssueCode.custom,
+        code: z11.ZodIssueCode.custom,
         message: `\`alias\` "${metric.alias}" collides with a \`groupBy\` field name (or the reserved word "bucket") \u2014 choose a different alias.`,
         path: ["metrics", index, "alias"]
       });
     }
   });
 });
-var MetricsQueryResultRowSchema = z10.record(
-  z10.string(),
-  z10.union([z10.string(), z10.number(), z10.boolean(), z10.null()])
+var MetricsQueryResultRowSchema = z11.record(
+  z11.string(),
+  z11.union([z11.string(), z11.number(), z11.boolean(), z11.null()])
 );
-var MetricsQueryResultSchema = z10.object({
-  data: z10.array(MetricsQueryResultRowSchema),
-  meta: z10.object({
+var MetricsQueryResultSchema = z11.object({
+  data: z11.array(MetricsQueryResultRowSchema),
+  meta: z11.object({
     resource: MetricsResourceSchema,
     environment: EnvironmentSchema,
-    rowCount: z10.number().int().describe("Number of rows in `data`."),
-    truncated: z10.boolean().describe(
+    rowCount: z11.number().int().describe("Number of rows in `data`."),
+    truncated: z11.boolean().describe(
       "`true` if more rows matched than `limit` allowed \u2014 `data` holds only the first `limit`."
     )
   })
 });
 
 // src/webhook-events.ts
-import { z as z11 } from "zod";
-var ChargeWebhookEventTypeSchema = z11.enum([
+import { z as z12 } from "zod";
+var ChargeWebhookEventTypeSchema = z12.enum([
   "charge.created",
   "charge.partially_paid",
   "charge.confirmed",
@@ -615,14 +674,14 @@ var ChargeWebhookEventTypeSchema = z11.enum([
 ]).describe(
   'Note the distinction between `charge.confirmed` and `charge.settled`: `confirmed` means the payment was detected on-chain; `settled` means the merchant\'s wallet actually received the funds \u2014 a separate, later step. Subscribe to `confirmed` if you only need "will I get paid," or `settled` if you need "has the money actually arrived." `charge.overpaid` fires alongside `charge.confirmed`/`charge.partially_paid` whenever the cumulative amount received ends up above `amount` (see `Charge.isOverpaid`). Every event in this category carries the full `Charge` object as `data`.'
 );
-var WebhookDeliveryEventTypeSchema = z11.enum(["webhook.delivery_failed", "webhook.delivery_recovered", "webhook.endpoint_unhealthy"]).describe(
+var WebhookDeliveryEventTypeSchema = z12.enum(["webhook.delivery_failed", "webhook.delivery_recovered", "webhook.endpoint_unhealthy"]).describe(
   "Meta-events about the health of your own webhook endpoints \u2014 useful for monitoring without polling `GET /v1/webhooks/{id}/deliveries`. `webhook.endpoint_unhealthy` fires once when a webhook's failure rate over the trailing 24h crosses 20%, and `webhook.delivery_recovered` fires once when a delivery to that webhook next succeeds. `data` for every event in this category: `{ webhookId, url, failureRatio? }` (`failureRatio` only present on `webhook.endpoint_unhealthy`)."
 );
-var WebhookEventTypeSchema = z11.union([
+var WebhookEventTypeSchema = z12.union([
   ChargeWebhookEventTypeSchema,
   WebhookDeliveryEventTypeSchema
 ]);
-var WebhookCategorySchema = z11.enum(["payments", "webhooks"]).describe(
+var WebhookCategorySchema = z12.enum(["payments", "webhooks"]).describe(
   "Subscribe to every event in a category via `eventCategories` instead of listing events one by one \u2014 new events added to a category later arrive automatically, no subscription update needed."
 );
 function buildCategoryMap() {
@@ -650,78 +709,101 @@ var TriggerableChargeEventSchema = ChargeWebhookEventTypeSchema.exclude([
 );
 
 // src/webhooks.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var WEBHOOK_EVENTS_WILDCARD = "*";
-var CreateWebhookSchema = z12.object({
-  url: z12.string().max(2048).url().describe(
+var CreateWebhookSchema = z13.object({
+  url: z13.string().max(2048).url().describe(
     "Must be HTTPS and resolve to a public address \u2014 private/internal IPs are rejected."
   ),
-  events: z12.array(z12.union([WebhookEventTypeSchema, z12.literal(WEBHOOK_EVENTS_WILDCARD)])).max(Object.keys(EVENT_CATEGORY_MAP).length + 1).default([]).describe(
+  events: z13.array(z13.union([WebhookEventTypeSchema, z13.literal(WEBHOOK_EVENTS_WILDCARD)])).max(Object.keys(EVENT_CATEGORY_MAP).length + 1).default([]).describe(
     'Individual event types to receive, or `"*"` for every event (combine with `excludeEvents` to opt back out of specific ones). Omit in favor of `eventCategories` if you want whole categories instead.'
   ),
-  eventCategories: z12.array(WebhookCategorySchema).max(WebhookCategorySchema.options.length).default([]).describe(
+  eventCategories: z13.array(WebhookCategorySchema).max(WebhookCategorySchema.options.length).default([]).describe(
     "Subscribe to every event in these categories. At least one of `events` or `eventCategories` is required."
   ),
-  excludeEvents: z12.array(WebhookEventTypeSchema).max(Object.keys(EVENT_CATEGORY_MAP).length).default([]).describe(
+  excludeEvents: z13.array(WebhookEventTypeSchema).max(Object.keys(EVENT_CATEGORY_MAP).length).default([]).describe(
     'Event types to exclude even if selected via `events: ["*"]` or `eventCategories`.'
   )
 }).refine((v) => v.events.length > 0 || v.eventCategories.length > 0, {
   message: "must select at least one event via `events` or `eventCategories`",
   path: ["events"]
 });
-var WebhookSchema = z12.object({
-  id: z12.string(),
+var WebhookSchema = z13.object({
+  id: z13.string(),
   environment: EnvironmentSchema.nullable().describe(
     "Which environment's API key created this webhook \u2014 `live` or `test`. Every event is only ever delivered to a webhook whose `environment` matches the event's own (or to a webhook with `environment: null`, which receives every environment \u2014 the case for every webhook created before this field existed)."
   ),
-  url: z12.string(),
-  events: z12.array(WebhookEventTypeSchema),
-  eventCategories: z12.array(WebhookCategorySchema),
-  excludeEvents: z12.array(WebhookEventTypeSchema),
-  isWildcard: z12.boolean(),
-  secret: z12.string().describe(
+  url: z13.string(),
+  events: z13.array(WebhookEventTypeSchema),
+  eventCategories: z13.array(WebhookCategorySchema),
+  excludeEvents: z13.array(WebhookEventTypeSchema),
+  isWildcard: z13.boolean(),
+  secret: z13.string().describe(
     "The signing secret, used to verify the `X-Klappay-Signature` header on every delivery. Returned in full only this once \u2014 store it now, it is not recoverable afterward. Header format: `t=<unix-seconds>,v1=<hex-encoded HMAC-SHA256>`. Compute the expected signature as `HMAC-SHA256(secret, \"${t}.${raw request body}\")` (hex-encoded) and compare it to `v1` using a constant-time comparison; as a replay-protection measure, also reject if `t` is too far from the current time \u2014 Klappay does not enforce or check any particular tolerance server-side, so the exact threshold is entirely the receiver's own policy call. An official SDK's `constructEvent()`/`verifySignature()` do this for you, defaulting to a 300-second tolerance, overridable via `constructEvent`'s `toleranceSeconds` option \u2014 see github.com/klappay for available SDKs."
   ),
-  createdAt: z12.string().datetime()
+  createdAt: z13.string().datetime()
 });
 var WebhookListItemSchema = WebhookSchema.omit({ secret: true }).extend({
-  hint: z12.string().describe("A truncated, safe-to-display form of the secret (e.g. `whsec_...ab12`).")
+  hint: z13.string().describe("A truncated, safe-to-display form of the secret (e.g. `whsec_...ab12`).")
 });
-var WebhookPayloadSchema = z12.object({
-  id: z12.string().describe(
+var WebhookPayloadSchema = z13.object({
+  id: z13.string().describe(
     "Unique id for this specific delivery \u2014 also sent as the `X-Klappay-Delivery` header."
   ),
   event: WebhookEventTypeSchema,
-  createdAt: z12.string().datetime(),
-  data: z12.unknown().describe(
+  createdAt: z13.string().datetime(),
+  data: z13.unknown().describe(
     "Event-specific data. Charge events (`charge.*`) carry the full `Charge` object; webhook-delivery events carry a smaller, event-specific object \u2014 see `WebhookEventDataMap`/`TypedWebhookPayload` for the exact shape per event, or docs/webhooks.md."
   )
 });
-var WebhookDeliveryStatusSchema = z12.enum(["pending", "delivered", "failed"]);
-var WebhookDeliverySchema = z12.object({
-  id: z12.string(),
-  webhookId: z12.string(),
+var WebhookDeliveryStatusSchema = z13.enum(["pending", "delivered", "failed"]);
+var WebhookDeliverySchema = z13.object({
+  id: z13.string(),
+  webhookId: z13.string(),
   event: WebhookEventTypeSchema,
   status: WebhookDeliveryStatusSchema.describe(
     "`pending`: still retrying. `delivered`: got a 2xx response. `failed`: retries exhausted (5 attempts over ~24h) \u2014 use `POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry` to try again manually."
   ),
-  attempts: z12.number(),
-  responseCode: z12.number().nullable().describe(
+  attempts: z13.number(),
+  responseCode: z13.number().nullable().describe(
     "HTTP status your endpoint returned on the most recent attempt. `null` if every attempt failed to connect at all."
   ),
-  nextRetryAt: z12.string().datetime().nullable(),
-  deliveredAt: z12.string().datetime().nullable(),
-  createdAt: z12.string().datetime()
+  nextRetryAt: z13.string().datetime().nullable(),
+  deliveredAt: z13.string().datetime().nullable(),
+  createdAt: z13.string().datetime()
 });
 var ListWebhookDeliveriesSchema = PaginationQuerySchema;
 var PaginatedWebhookDeliveriesSchema = paginatedSchema(WebhookDeliverySchema);
 
+// src/recipients.ts
+import { z as z14 } from "zod";
+var EVM_ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
+var CreateRecipientSchema = z14.object({
+  address: z14.string().regex(EVM_ADDRESS_REGEX, "must be a 20-byte hex address").describe("EVM address to register as a trusted split recipient for your organization."),
+  label: z14.string().min(1).max(64).optional().describe('Free-form label for your own bookkeeping (e.g. `"supplier"`) \u2014 never interpreted.')
+});
+var RecipientSchema = z14.object({
+  id: z14.string().describe(
+    "Klappay-generated id, e.g. `rc_...` \u2014 this, not the raw address, is what a charge's `splitRecipients[].recipientId` references."
+  ),
+  environment: EnvironmentSchema,
+  address: z14.string(),
+  label: z14.string().nullable(),
+  payout: z14.boolean().describe(
+    "Whether this recipient is eligible to be used as an API key's `payoutAddress` (in addition to being referenceable in a split, which every non-revoked recipient already is). Set via `PATCH /v1/recipients/{id}` \u2014 requires the `recipients:manage_payout` scope, deliberately separate from `recipients:write`."
+  ),
+  createdAt: z14.string().datetime()
+});
+var SetRecipientPayoutSchema = z14.object({
+  payout: z14.boolean().describe("New payout-eligibility value for this recipient.")
+});
+
 // src/timeline.ts
-import { z as z13 } from "zod";
-var TransactionSourceSchema = z13.enum(["moralis_webhook", "reconciliation_job", "sandbox"]).describe(
+import { z as z15 } from "zod";
+var TransactionSourceSchema = z15.enum(["moralis_webhook", "reconciliation_job", "sandbox"]).describe(
   "How this transfer was detected: `moralis_webhook` (the normal path), `reconciliation_job` (a fallback poller caught it after the webhook was missed or delayed), or `sandbox` (simulated via `POST /v1/sandbox/charges/{id}/trigger`, no real on-chain transfer)."
 );
-var TimelineEventTypeSchema = z13.enum([
+var TimelineEventTypeSchema = z15.enum([
   "charge.created",
   "charge.expired",
   "transaction.detected",
@@ -732,11 +814,11 @@ var TimelineEventTypeSchema = z13.enum([
 ]).describe(
   "`charge.created`: the charge was created. `charge.expired`: `expiresAt` passed with no full payment. `transaction.detected`: a raw on-chain transfer was seen (see the `event`-shaped fields below for details \u2014 a charge can have more than one, e.g. a partial payment followed by the rest). `split.distributed`: a payout to the merchant completed on-chain, for one contributing `(token, network)` pair \u2014 a charge settled across more than one pair emits one of these per pair (see the `token`/`network` fields below). `webhook.dispatched`/`webhook.delivered`/`webhook.failed`: one specific delivery *attempt* for one webhook subscription \u2014 `failed` here means this single attempt failed, not that all retries were exhausted (see `WebhookDeliveryStatusSchema` for the exhausted-all-retries state)."
 );
-var TimelineEventSchema = z13.object({
+var TimelineEventSchema = z15.object({
   type: TimelineEventTypeSchema,
-  at: z13.string().datetime(),
-  txHash: z13.string().optional().describe("Present for `transaction.detected` and `split.distributed` events only."),
-  amount: z13.number().optional().describe(
+  at: z15.string().datetime(),
+  txHash: z15.string().optional().describe("Present for `transaction.detected` and `split.distributed` events only."),
+  amount: z15.number().optional().describe(
     "Present for `transaction.detected` events only \u2014 the amount that specific transfer carried."
   ),
   source: TransactionSourceSchema.optional().describe(
@@ -748,55 +830,111 @@ var TimelineEventSchema = z13.object({
   network: NetworkSchema.optional().describe(
     "Present for `transaction.detected` and `split.distributed` events \u2014 which network this specific transfer, or settlement, used."
   ),
-  causedTransition: z13.boolean().optional().describe(
+  causedTransition: z15.boolean().optional().describe(
     "Present for `transaction.detected` events only. `true` if this specific transfer changed the charge's status (e.g. PENDING\u2192CONFIRMED) \u2014 a charge paid in installments can have more than one such event."
   ),
   event: WebhookEventTypeSchema.optional().describe(
     "Present for `webhook.*` events only \u2014 which event type this delivery was for."
   ),
-  responseCode: z13.number().nullable().optional().describe(
+  responseCode: z15.number().nullable().optional().describe(
     "Present for `webhook.*` events only \u2014 HTTP status your endpoint returned, or `null` if the request never connected."
   ),
-  attempts: z13.number().optional().describe(
+  attempts: z15.number().optional().describe(
     "Present for `webhook.*` events only \u2014 how many delivery attempts have been made so far."
   )
 });
 
 // src/health.ts
-import { z as z14 } from "zod";
-var HealthSchema = z14.object({
-  status: z14.enum(["ok", "error"]).describe(
+import { z as z16 } from "zod";
+var HealthSchema = z16.object({
+  status: z16.enum(["ok", "error"]).describe(
     "`error` when the database connectivity check fails \u2014 the HTTP status code mirrors this (503 instead of 200), so a plain uptime check (not just a JSON-aware one) still catches a DB outage."
   ),
-  version: z14.string(),
-  timestamp: z14.string().datetime(),
-  db: z14.enum(["ok", "error"]).describe("Result of a real database connectivity check, not just a process-alive check."),
-  pendingWebhooks: z14.number().describe("Count of webhook deliveries still awaiting a successful attempt."),
-  oldestPendingChargeAgeSeconds: z14.number().nullable().describe("Age of the oldest still-unpaid charge, in seconds. `null` if there are none."),
-  lastMoralisEventAgeSeconds: z14.number().nullable().describe(
+  version: z16.string(),
+  timestamp: z16.string().datetime(),
+  db: z16.enum(["ok", "error"]).describe("Result of a real database connectivity check, not just a process-alive check."),
+  pendingWebhooks: z16.number().describe("Count of webhook deliveries still awaiting a successful attempt."),
+  oldestPendingChargeAgeSeconds: z16.number().nullable().describe("Age of the oldest still-unpaid charge, in seconds. `null` if there are none."),
+  lastMoralisEventAgeSeconds: z16.number().nullable().describe(
     "Seconds since the last on-chain payment notification was received \u2014 a cheap signal for whether payment detection is currently working. `null` if none have ever been received."
   )
 });
 
 // src/sandbox.ts
-import { z as z15 } from "zod";
-var SandboxTriggerSchema = z15.object({
+import { z as z17 } from "zod";
+var SandboxTriggerSchema = z17.object({
   event: TriggerableChargeEventSchema,
-  amount: z15.number().positive().max(CHARGE_AMOUNT_MAX).optional().describe(
+  amount: z17.number().positive().max(CHARGE_AMOUNT_MAX).optional().describe(
     "Used with `charge.partially_paid` (amount to simulate as received so far \u2014 must be less than the charge amount, defaults to half of it if omitted) and with `charge.overpaid` (amount received \u2014 must be greater than the charge amount, defaults to 1.5x it if omitted). Ignored for every other event."
   )
 });
 
 // src/capabilities.ts
-import { z as z16 } from "zod";
-var CapabilitiesSchema = z16.object({
-  acceptedPayments: z16.array(AcceptedPaymentSchema).describe(
+import { z as z18 } from "zod";
+var CapabilitiesSchema = z18.object({
+  acceptedPayments: z18.array(AcceptedPaymentSchema).describe(
     "Every `(token, network)` pair actually configured for your environment right now \u2014 read straight from the same lookup `POST /v1/charges` validates `acceptedPayments` against, so it can never list a pair that charge creation would then reject. Use this to build a picker UI instead of hardcoding the matrix client-side."
   )
 });
+
+// src/swap.ts
+import { z as z19 } from "zod";
+var CreateSwapQuoteSchema = z19.object({
+  inputToken: AltTokenSchema.describe(
+    "Which alt-cryptocurrency the payer wants to send \u2014 must be one of this charge's `swapAlternatives`, or `422 token_not_supported`."
+  ),
+  inputNetwork: NetworkSchema.describe(
+    "Which network the payer will send `inputToken` on. Also picks which of this charge's `acceptedPayments` pairs the swap resolves to \u2014 a charge accepting USDC on both Base and Optimism resolves to whichever `inputNetwork` you pass. If the charge accepts more than one token on that same network, Klappay breaks the tie using its own trust ranking for that network (e.g. USDT over USDC on BNB Chain, where \"USDC\" is a third-party Binance-Peg token, not Circle's) \u2014 never a token the charge doesn't actually accept."
+  ),
+  takerAddress: z19.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be a 20-byte hex address").describe(
+    "The payer's own wallet address \u2014 the account that will sign and submit the swap transaction. Not validated against anything else; any well-formed address is accepted, since Klappay never custodies these funds."
+  )
+});
+var SwapQuoteSchema = z19.object({
+  inputToken: AltTokenSchema,
+  inputNetwork: NetworkSchema,
+  inputAmount: z19.number().describe(
+    "The ceiling of `inputToken` the payer needs available to sign for, in whole units (not wei/base units) \u2014 not necessarily the exact final cost. Any `inputToken` beyond what the swap actually needs (price moved favorably, less slippage than budgeted) is swapped back and refunded to the payer automatically, in the same transaction \u2014 never a separate step or a Klappay-side refund."
+  ),
+  outputToken: TokenSchema.describe(
+    "Which of this charge's `acceptedPayments` tokens the swap resolves to."
+  ),
+  outputNetwork: NetworkSchema,
+  outputAmount: z19.number().describe(
+    "The exact remaining amount owed on this charge (`amount - amountReceived`), in `currency` units \u2014 always what the merchant's split address receives, regardless of `inputAmount`."
+  ),
+  fees: z19.object({
+    klappayFee: z19.number().describe(
+      "Klappay's own swap fee (1% today), in `outputToken` units \u2014 paid by the payer, on top of `inputAmount`, separate from the merchant's own `feePercent`. Never subtracted from `outputAmount`."
+    ),
+    zeroExFee: z19.number().nullable().describe(
+      "0x's own protocol fee for this specific token pair, in `outputToken` units, or `null` when this pair isn't currently one 0x charges on. Also paid by the payer on top of `inputAmount`, also never subtracted from `outputAmount` \u2014 Klappay never sees this fee, it goes straight to 0x."
+    )
+  }).describe(
+    "Every fee the payer is charged for using swap-to-pay, broken out by who collects it \u2014 both already reflected in `inputAmount`, shown here separately for transparency. Neither ever reduces `outputAmount`."
+  ),
+  expiresAt: z19.string().datetime().describe(
+    "When this quote's price is no longer safely valid \u2014 a rough guide for the payer's UI countdown only. The actual price guarantee is enforced on-chain by the swap transaction itself (a signed Permit2 deadline, or a minimum-output check for a native-currency sell), not by this timestamp \u2014 submitting after it expires either reverts on-chain or simply gets re-quoted at the current price, never silently executes at a stale rate."
+  ),
+  transaction: z19.object({
+    to: z19.string().describe("Contract address the payer's wallet must send this transaction to."),
+    data: z19.string().describe("Calldata \u2014 opaque, must be sent unmodified."),
+    value: z19.string().describe(
+      "Native currency (ETH/BNB/MATIC/AVAX) to attach, in wei \u2014 `\"0\"` when `inputToken` isn't this network's native currency."
+    )
+  }).describe(
+    "Pass this directly to the payer's wallet (e.g. viem/ethers `sendTransaction`) \u2014 Klappay never touches the payer's private key or submits anything on their behalf. If `permit2` is present on this response, sign that first and append the signature to this `data` before sending; if `permit2` is absent, send `transaction` as-is with no extra step."
+  ),
+  permit2: z19.object({ eip712: z19.record(z19.unknown()) }).optional().describe(
+    "Present only when `inputToken` is an ERC-20 (today, only `BTC`) \u2014 the payer's wallet must sign this EIP-712 message and append the signature to `transaction.data` before sending, since an ERC-20 sell needs a Permit2 allowance signature that a native-currency sell doesn't. Absent when `inputToken` is a network's own native currency (ETH/BNB/MATIC/AVAX) \u2014 `transaction` is then ready to sign and send directly, no extra step."
+  )
+});
 export {
+  ALT_TOKEN_ADDRESSES,
+  ALT_TOKEN_DECIMALS,
   API_KEY_SCOPES,
   AcceptedPaymentSchema,
+  AltTokenSchema,
   ApiKeyScopeSchema,
   CHARGE_ACCEPTED_PAYMENTS_MAX,
   CHARGE_AMOUNT_MAX,
@@ -804,6 +942,7 @@ export {
   CHARGE_EXPIRES_IN_MIN_SECONDS,
   CHARGE_SPLIT_RECIPIENTS_MAX,
   CHECKOUT_PRODUCTS_MAX,
+  CONFLICTING_SCOPE_PAIRS,
   CapabilitiesSchema,
   ChargeSchema,
   ChargeStatusSchema,
@@ -813,6 +952,8 @@ export {
   ChargesQueryFieldSchema,
   CheckoutProductSchema,
   CreateChargeSchema,
+  CreateRecipientSchema,
+  CreateSwapQuoteSchema,
   CreateWebhookSchema,
   DistributionsDateFieldSchema,
   DistributionsMetricFieldSchema,
@@ -855,10 +996,14 @@ export {
   PendingDistributionEventSchema,
   PendingDistributionRecipientSchema,
   PendingDistributionSchema,
+  RecipientSchema,
   SandboxTriggerSchema,
+  SetRecipientPayoutSchema,
   SettlementStatusSchema,
   SplitDistributionStatusSchema,
+  SplitRecipientInputSchema,
   SplitRecipientSchema,
+  SwapQuoteSchema,
   TOKEN_ADDRESSES,
   TOKEN_DECIMALS,
   TimelineEventSchema,
@@ -879,6 +1024,8 @@ export {
   WebhookListItemSchema,
   WebhookPayloadSchema,
   WebhookSchema,
+  findConflictingScopes,
+  listAltTokensForNetworks,
   paginatedSchema
 };
 //# sourceMappingURL=index.mjs.map