@klappay/types 3.5.2 → 3.7.0

package/dist/index.js

@@ -42,6 +42,7 @@ __export(index_exports, {
   ChargesMetricFieldSchema: () => ChargesMetricFieldSchema,
   ChargesQueryFieldSchema: () => ChargesQueryFieldSchema,
   CheckChargeRequestSchema: () => CheckChargeRequestSchema,
+  CheckChargeResponseSchema: () => CheckChargeResponseSchema,
   CheckoutProductSchema: () => CheckoutProductSchema,
   CreateChargeSchema: () => CreateChargeSchema,
   CreateRecipientSchema: () => CreateRecipientSchema,
@@ -90,6 +91,7 @@ __export(index_exports, {
   PendingDistributionRecipientSchema: () => PendingDistributionRecipientSchema,
   PendingDistributionSchema: () => PendingDistributionSchema,
   RecipientSchema: () => RecipientSchema,
+  RefundEscrowRequestSchema: () => RefundEscrowRequestSchema,
   ReleaseEscrowRequestSchema: () => ReleaseEscrowRequestSchema,
   SandboxTriggerSchema: () => SandboxTriggerSchema,
   SetRecipientPayoutSchema: () => SetRecipientPayoutSchema,
@@ -369,6 +371,11 @@ var ReleaseEscrowRequestSchema = import_zod9.z.object({
     "The Safe transaction signature authorizing this release, produced by signing a transfer of the escrow's entire current token balance to the charge's already-frozen split address (the same split that would have received the payment on a normal, non-escrow charge) with the private key behind this charge's `escrowReleaserAddress` \u2014 never anything Klappay can produce itself. The destination is fixed by the charge's `splitConfig` (frozen at creation); the amount is read live on-chain at release time, not fixed in advance, so it always matches whatever actually arrived \u2014 reconstruct the exact transaction server-side computes (ERC-20 `transfer(splitAddress, balance)` from the escrow Safe, nonce 0) before signing. Independently verified on-chain before anything moves \u2014 the Safe contract itself rejects a signature that isn't from `escrowReleaserAddress`, never trusted at face value by Klappay."
   )
 });
+var RefundEscrowRequestSchema = import_zod9.z.object({
+  signature: import_zod9.z.string().regex(/^0x[0-9a-fA-F]+$/, "must be hex-encoded signature bytes").describe(
+    "The Safe transaction signature authorizing this refund, produced by signing a transfer of the escrow's entire current token balance back to the address that funded this charge (`Charge.payerAddress`, captured from the credited transfer) with the private key behind this charge's `escrowReleaserAddress` \u2014 never anything Klappay can produce itself. The amount is read live on-chain at refund time, not fixed in advance, so it always matches whatever actually arrived \u2014 reconstruct the exact transaction Klappay computes server-side (ERC-20 `transfer(payerAddress, balance)` from the escrow Safe, nonce 0) before signing. Independently verified on-chain before anything moves \u2014 the Safe contract itself rejects a signature that isn't from `escrowReleaserAddress`, never trusted at face value by Klappay."
+  )
+});
 
 // src/charges.ts
 var ChargeStatusSchema = import_zod10.z.enum(["pending", "partially_paid", "confirmed", "expired", "underpaid"]).describe(
@@ -523,7 +530,10 @@ var ChargeSchema = import_zod10.z.object({
   ),
   escrow: import_zod10.z.object({
     releaserAddress: import_zod10.z.string().describe("The only address that can ever release this escrow \u2014 never Klappay."),
-    releasedAt: import_zod10.z.string().datetime().nullable().describe("When the release actually executed on-chain. `null` until then.")
+    releasedAt: import_zod10.z.string().datetime().nullable().describe("When the release actually executed on-chain. `null` until then."),
+    refundedAt: import_zod10.z.string().datetime().nullable().describe(
+      "When the refund actually executed on-chain. `null` until then. Mutually exclusive with `releasedAt` \u2014 an escrow can only ever be released or refunded once, never both."
+    )
   }).nullable().describe(
     "Present only when this charge was created as an escrow (see `escrow` on the create request) \u2014 `null` for a normal charge."
   )
@@ -562,6 +572,11 @@ var CheckChargeRequestSchema = import_zod11.z.object({
 }).refine((data) => Boolean(data.txHash) === Boolean(data.network), {
   message: "`txHash` and `network` must be provided together, or both omitted"
 });
+var CheckChargeResponseSchema = ChargeSchema.extend({
+  transactionSender: import_zod11.z.string().nullable().describe(
+    "The `txHash` transaction's own sender (`from`) \u2014 who actually signed and submitted it on-chain, which stays the payer's own wallet even when the transaction swaps through a router/aggregator on the way to paying, unlike the credited transfer's `from` (which can be the router/pool contract, not the payer). `null` unless `txHash`/`network` was passed in the request and a successful receipt was found for it \u2014 a hint-less background scan, an unaccepted network, or a not-found/reverted transaction all leave this `null`."
+  )
+});
 
 // src/distributions.ts
 var import_zod12 = require("zod");
@@ -868,9 +883,10 @@ var ChargeWebhookEventTypeSchema = import_zod14.z.enum([
   "charge.settled",
   "charge.settlement_failed",
   "charge.overpaid",
-  "charge.escrow_released"
+  "charge.escrow_released",
+  "charge.escrow_refunded"
 ]).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`). `charge.escrow_released` fires once an escrow-configured charge\'s funds have been moved out of its Safe to the split address by `POST /v1/charges/{id}/release` \u2014 a normal `charge.settled` still follows once the split itself finishes distributing. Every event in this category carries the full `Charge` object as `data`.'
+  '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`). `charge.escrow_released` fires once an escrow-configured charge\'s funds have been moved out of its Safe to the split address by `POST /v1/charges/{id}/release` \u2014 a normal `charge.settled` still follows once the split itself finishes distributing. `charge.escrow_refunded` fires once an escrow-configured charge\'s funds have been moved out of its Safe back to the payer by `POST /v1/charges/{id}/refund` \u2014 mutually exclusive with `charge.escrow_released`, an escrow charge only ever emits one of the two. Every event in this category carries the full `Charge` object as `data`.'
 );
 var WebhookDeliveryEventTypeSchema = import_zod14.z.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`)."
@@ -901,9 +917,11 @@ var WEBHOOK_EVENT_CATEGORIES = {
   webhooks: WebhookDeliveryEventTypeSchema.options
 };
 var TriggerableChargeEventSchema = ChargeWebhookEventTypeSchema.exclude([
-  "charge.created"
+  "charge.created",
+  "charge.escrow_released",
+  "charge.escrow_refunded"
 ]).describe(
-  "Every charge event that represents a payment-progress state transition a sandbox charge can be pushed into \u2014 everything except `charge.created` (a charge already exists by the time you have an id to trigger against)."
+  "Every charge event that represents a payment-progress state transition a sandbox charge can be pushed into \u2014 everything except `charge.created` (a charge already exists by the time you have an id to trigger against) and the two escrow-terminal events, which are reached by actually calling `POST /v1/charges/{id}/release` or `POST /v1/charges/{id}/refund` on a test-environment escrow charge (a real Safe transaction on that network's testnet), not this generic trigger."
 );
 
 // src/webhooks.ts
@@ -1151,6 +1169,7 @@ var SwapQuoteSchema = import_zod21.z.object({
   ChargesMetricFieldSchema,
   ChargesQueryFieldSchema,
   CheckChargeRequestSchema,
+  CheckChargeResponseSchema,
   CheckoutProductSchema,
   CreateChargeSchema,
   CreateRecipientSchema,
@@ -1199,6 +1218,7 @@ var SwapQuoteSchema = import_zod21.z.object({
   PendingDistributionRecipientSchema,
   PendingDistributionSchema,
   RecipientSchema,
+  RefundEscrowRequestSchema,
   ReleaseEscrowRequestSchema,
   SandboxTriggerSchema,
   SetRecipientPayoutSchema,