@klappay/types 4.1.0 → 5.1.0

package/dist/index.mjs

@@ -4,14 +4,21 @@ import {
   CHAIN_IDS,
   EVM_NETWORKS,
   NETWORK_EXPLORERS,
+  NETWORK_FAMILIES,
   NETWORK_LABELS,
   OPERATIONAL_NETWORKS,
+  SplitAddressSchema,
   TOKEN_ADDRESSES,
   TOKEN_DECIMALS,
   TOKEN_DEPLOYMENTS,
+  addressesEqual,
   getTokenDeployment,
-  isPaymentDeploymentEnabled
-} from "./chunk-WKIOAEJ3.mjs";
+  isEvmAddress,
+  isPaymentDeploymentEnabled,
+  isSplitAddress,
+  isTronAddress,
+  tronAddress
+} from "./chunk-UEXXRQL3.mjs";
 
 // src/errors.ts
 import { z } from "zod";
@@ -68,7 +75,7 @@ function findConflictingScopes(scopes) {
 
 // src/networks.ts
 import { z as z4 } from "zod";
-var NetworkSchema = z4.enum(["base", "optimism", "polygon", "ethereum", "arbitrum", "avalanche", "bnb"]).describe("The blockchain a charge/payment is on.");
+var NetworkSchema = z4.enum(["base", "optimism", "polygon", "ethereum", "arbitrum", "avalanche", "bnb", "tron", "arc"]).describe("The blockchain a charge/payment is on.");
 
 // src/pagination.ts
 import { z as z5 } from "zod";
@@ -99,8 +106,8 @@ var TokenSchema = z6.enum(["USDC", "USDT"]).describe(
 
 // 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 AltTokenSchema = z7.enum(["ETH", "BNB", "POL", "AVAX", "BTC", "LINK", "ARB", "OP", "CBETH"]).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. Trusted on a given network only when it has deep, reputably-issued/custodied liquidity there: each network's own native currency, `BTC` (wrapped) on the networks with a trusted deployment, `LINK` (Chainlink's own official per-chain deployment, except Avalanche's bridged `LINK.e`), and a small set of chain-specific blue chips (`ARB` on Arbitrum, `OP` on Optimism, `CBETH` on Base) \u2014 see `ALT_TOKEN_ADDRESSES` for the authoritative per-network list, never assume every value here is available on every network. `POL` replaced `MATIC` as Polygon's native currency name (Polygon's own token migration, 2024) \u2014 this schema tracks the network's current native asset, not the deprecated ticker."
 );
 var SwapAlternativeSchema = z7.object({
   token: AltTokenSchema,
@@ -178,7 +185,7 @@ var ChargeFeePayerSchema = z11.enum(["merchant", "payer"]).describe(
 );
 var CHARGE_EXPIRES_IN_MIN_SECONDS = 60;
 var CHARGE_EXPIRES_IN_MAX_SECONDS = 3600;
-var CHARGE_ACCEPTED_PAYMENTS_MAX = 14;
+var CHARGE_ACCEPTED_PAYMENTS_MAX = 18;
 var AcceptedPaymentSchema = z11.object({
   token: TokenSchema,
   network: NetworkSchema
@@ -203,12 +210,21 @@ var AcceptedPaymentsSchema = z11.array(AcceptedPaymentSchema).min(1, "At least o
       });
     }
   });
+  const families = new Set(pairs.map((pair) => NETWORK_FAMILIES[pair.network]));
+  if (families.size > 1) {
+    ctx.addIssue({
+      code: z11.ZodIssueCode.custom,
+      message: `acceptedPayments mixes networks from different split families (${[...families].sort().join(", ")}) \u2014 every network in this list must share the same underlying split factory, so a charge can only ever accept networks from one family at a time.`
+    });
+  }
 }).describe(
-  `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\`.`
+  `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\`. Every network listed must also share the same split family (which networks are grouped together is an implementation detail, not part of this API's contract) \u2014 a charge predicts one split address up front and reuses it across every accepted network, which is only safe within one family; mixing families is rejected with \`400 validation_error\`.`
 );
 var CHARGE_SPLIT_RECIPIENTS_MAX = 5;
 var SplitRecipientSchema = z11.object({
-  address: z11.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."),
+  address: SplitAddressSchema.describe(
+    "Address to send a slice of this charge to \u2014 an EVM 0x... address or a TRON T... address, matching whichever network family the charge accepts (acceptedPayments can only ever list networks from one split family at a time, so this always matches that same family)."
+  ),
   percent: z11.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."
   ),
@@ -268,8 +284,21 @@ var CreateChargeSchema = z11.object({
   ),
   splitRecipients: SplitRecipientsInputSchema.optional(),
   escrow: EscrowConfigSchema.optional().describe(
-    "Configure this charge as an escrow instead of a normal payment. Funds land in a dedicated, non-custodial Safe (not the usual split address) and only `releaserAddress` (or, if omitted, your API key's own `payoutAddress`) can ever release them \u2014 via `POST /v1/charges/{id}/release`, signed on their end, never something Klappay can trigger or redirect. Omit this field entirely for a normal charge."
+    "Configure this charge as an escrow instead of a normal payment. Funds land in a dedicated, non-custodial Safe (not the usual split address) and only `releaserAddress` (or, if omitted, your API key's own `payoutAddress`) can ever release them \u2014 via `POST /v1/charges/{id}/release`, signed on their end, never something Klappay can trigger or redirect. Omit this field entirely for a normal charge. **Requires every accepted network to be EVM** (Safe \u2014 the underlying custody contract \u2014 isn't deployed on Tron, and can never be; it's not an EVM chain) \u2014 rejected with `400 validation_error` otherwise."
   )
+}).superRefine((data, ctx) => {
+  if (!data.escrow) return;
+  const evmNetworks = EVM_NETWORKS;
+  const hasUnsupportedNetwork = data.acceptedPayments.some(
+    (pair) => !evmNetworks.includes(pair.network)
+  );
+  if (hasUnsupportedNetwork) {
+    ctx.addIssue({
+      code: z11.ZodIssueCode.custom,
+      message: "Escrow is not supported for this charge's network \u2014 Safe (the underlying custody contract) isn't an EVM chain there. Remove `escrow`, or accept payment on an EVM network instead.",
+      path: ["escrow"]
+    });
+  }
 });
 var ChargeSchema = z11.object({
   id: z11.string().describe("Klappay-generated id, e.g. `ch_...`. Use this to look up the charge later."),
@@ -488,6 +517,7 @@ var MetricsFilterValueSchema = z15.union([
   z15.string().max(255),
   z15.number(),
   z15.boolean(),
+  z15.null(),
   z15.array(z15.union([z15.string().max(255), z15.number()])).min(1).max(50)
 ]);
 var orderBySchema = z15.object({
@@ -827,9 +857,10 @@ var PaginatedWebhookDeliveriesSchema = paginatedSchema(WebhookDeliverySchema);
 
 // src/recipients.ts
 import { z as z18 } from "zod";
-var EVM_ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
 var CreateRecipientSchema = z18.object({
-  address: z18.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."),
+  address: SplitAddressSchema.describe(
+    "Address to register as a trusted split recipient for your organization \u2014 an EVM 0x... address or a TRON T... address."
+  ),
   label: z18.string().min(1).max(64).optional().describe('Free-form label for your own bookkeeping (e.g. `"supplier"`) \u2014 never interpreted.')
 });
 var RecipientSchema = z18.object({
@@ -844,14 +875,15 @@ var RecipientSchema = z18.object({
   ),
   createdAt: z18.string().datetime()
 });
+var PaginatedRecipientsSchema = paginatedSchema(RecipientSchema);
 var SetRecipientPayoutSchema = z18.object({
   payout: z18.boolean().describe("New payout-eligibility value for this recipient.")
 });
 
 // src/timeline.ts
 import { z as z19 } from "zod";
-var TransactionSourceSchema = z19.enum(["contract_watcher", "reconciliation_job", "sandbox"]).describe(
-  "How this transfer was detected: `contract_watcher` (the normal path \u2014 a real-time on-chain event subscription), `reconciliation_job` (a fallback poller caught it after the watcher missed or delayed it), or `sandbox` (simulated via `POST /v1/sandbox/charges/{id}/trigger`, no real on-chain transfer)."
+var TransactionSourceSchema = z19.enum(["contract_watcher", "reconciliation_job", "sandbox", "tron_watcher"]).describe(
+  "How this transfer was detected: `contract_watcher` (the normal path for EVM networks \u2014 a real-time WebSocket log subscription), `tron_watcher` (the TRON equivalent \u2014 a real-time ZeroMQ event subscription against a self-hosted node, a different underlying mechanism since TRON has no WebSocket log subscription), `reconciliation_job` (a fallback poller caught it after the watcher missed or delayed it), or `sandbox` (simulated via `POST /v1/sandbox/charges/{id}/trigger`, no real on-chain transfer)."
 );
 var TimelineEventTypeSchema = z19.enum([
   "charge.created",
@@ -985,13 +1017,13 @@ var SwapQuoteSchema = z23.object({
     to: z23.string().describe("Contract address the payer's wallet must send this transaction to."),
     data: z23.string().describe("Calldata \u2014 opaque, must be sent unmodified."),
     value: z23.string().describe(
-      "Native currency (ETH/BNB/MATIC/AVAX) to attach, in wei \u2014 `\"0\"` when `inputToken` isn't this network's native currency."
+      "Native currency (ETH/BNB/POL/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: z23.object({ eip712: z23.record(z23.unknown()) }).nullish().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. `null` (never omitted, in a genuine 0x-backed quote) 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."
+    "Present only when `inputToken` is an ERC-20 (BTC, LINK, or a chain-specific blue chip like ARB/OP/CBETH) \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. `null` (never omitted, in a genuine 0x-backed quote) when `inputToken` is a network's own native currency (ETH/BNB/POL/AVAX) \u2014 `transaction` is then ready to sign and send directly, no extra step."
   )
 });
 export {
@@ -1054,6 +1086,7 @@ export {
   MetricsQuerySchema,
   MetricsResourceSchema,
   NETWORK_EXPLORERS,
+  NETWORK_FAMILIES,
   NETWORK_LABELS,
   NetworkSchema,
   OPERATIONAL_NETWORKS,
@@ -1062,6 +1095,7 @@ export {
   PAGINATION_LIMIT_MIN,
   PaginatedChargesSchema,
   PaginatedPendingDistributionsSchema,
+  PaginatedRecipientsSchema,
   PaginatedWebhookDeliveriesSchema,
   PaginationQuerySchema,
   PendingDistributionEventSchema,
@@ -1073,6 +1107,7 @@ export {
   SandboxTriggerSchema,
   SetRecipientPayoutSchema,
   SettlementStatusSchema,
+  SplitAddressSchema,
   SplitDistributionStatusSchema,
   SplitRecipientInputSchema,
   SplitRecipientSchema,
@@ -1099,10 +1134,15 @@ export {
   WebhookListItemSchema,
   WebhookPayloadSchema,
   WebhookSchema,
+  addressesEqual,
   findConflictingScopes,
   getTokenDeployment,
+  isEvmAddress,
   isPaymentDeploymentEnabled,
+  isSplitAddress,
+  isTronAddress,
   listSwapAlternatives,
-  paginatedSchema
+  paginatedSchema,
+  tronAddress
 };
 //# sourceMappingURL=index.mjs.map