@klappay/types 2.0.3 → 3.0.0

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";
@@ -204,21 +219,31 @@ var SplitRecipientSchema = z8.object({
     '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 = z8.object({
+  recipientId: z8.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: z8.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: z8.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 = z8.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"]
+        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({
@@ -243,7 +268,7 @@ var CreateChargeSchema = z8.object({
   redirectUrl: z8.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."),
@@ -716,12 +741,35 @@ var WebhookDeliverySchema = z12.object({
 var ListWebhookDeliveriesSchema = PaginationQuerySchema;
 var PaginatedWebhookDeliveriesSchema = paginatedSchema(WebhookDeliverySchema);
 
-// src/timeline.ts
+// src/recipients.ts
 import { z as z13 } from "zod";
-var TransactionSourceSchema = z13.enum(["moralis_webhook", "reconciliation_job", "sandbox"]).describe(
+var EVM_ADDRESS_REGEX = /^0x[0-9a-fA-F]{40}$/;
+var CreateRecipientSchema = z13.object({
+  address: z13.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: z13.string().min(1).max(64).optional().describe('Free-form label for your own bookkeeping (e.g. `"supplier"`) \u2014 never interpreted.')
+});
+var RecipientSchema = z13.object({
+  id: z13.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: z13.string(),
+  label: z13.string().nullable(),
+  payout: z13.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: z13.string().datetime()
+});
+var SetRecipientPayoutSchema = z13.object({
+  payout: z13.boolean().describe("New payout-eligibility value for this recipient.")
+});
+
+// src/timeline.ts
+import { z as z14 } from "zod";
+var TransactionSourceSchema = z14.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 = z14.enum([
   "charge.created",
   "charge.expired",
   "transaction.detected",
@@ -732,11 +780,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 = z14.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: z14.string().datetime(),
+  txHash: z14.string().optional().describe("Present for `transaction.detected` and `split.distributed` events only."),
+  amount: z14.number().optional().describe(
     "Present for `transaction.detected` events only \u2014 the amount that specific transfer carried."
   ),
   source: TransactionSourceSchema.optional().describe(
@@ -748,49 +796,49 @@ 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: z14.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: z14.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: z14.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 z15 } from "zod";
+var HealthSchema = z15.object({
+  status: z15.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: z15.string(),
+  timestamp: z15.string().datetime(),
+  db: z15.enum(["ok", "error"]).describe("Result of a real database connectivity check, not just a process-alive check."),
+  pendingWebhooks: z15.number().describe("Count of webhook deliveries still awaiting a successful attempt."),
+  oldestPendingChargeAgeSeconds: z15.number().nullable().describe("Age of the oldest still-unpaid charge, in seconds. `null` if there are none."),
+  lastMoralisEventAgeSeconds: z15.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 z16 } from "zod";
+var SandboxTriggerSchema = z16.object({
   event: TriggerableChargeEventSchema,
-  amount: z15.number().positive().max(CHARGE_AMOUNT_MAX).optional().describe(
+  amount: z16.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 z17 } from "zod";
+var CapabilitiesSchema = z17.object({
+  acceptedPayments: z17.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."
   )
 });
@@ -803,6 +851,8 @@ export {
   CHARGE_EXPIRES_IN_MAX_SECONDS,
   CHARGE_EXPIRES_IN_MIN_SECONDS,
   CHARGE_SPLIT_RECIPIENTS_MAX,
+  CHECKOUT_PRODUCTS_MAX,
+  CONFLICTING_SCOPE_PAIRS,
   CapabilitiesSchema,
   ChargeSchema,
   ChargeStatusSchema,
@@ -810,7 +860,9 @@ export {
   ChargesDateFieldSchema,
   ChargesMetricFieldSchema,
   ChargesQueryFieldSchema,
+  CheckoutProductSchema,
   CreateChargeSchema,
+  CreateRecipientSchema,
   CreateWebhookSchema,
   DistributionsDateFieldSchema,
   DistributionsMetricFieldSchema,
@@ -821,6 +873,7 @@ export {
   ErrorPayloadSchema,
   GetChargeQrCodeQuerySchema,
   HealthSchema,
+  KlappayCheckoutMetadataSchema,
   ListChargesSchema,
   ListWebhookDeliveriesSchema,
   ListenPendingDistributionsQuerySchema,
@@ -830,6 +883,7 @@ export {
   METRICS_QUERY_MAX_GROUP_BY,
   METRICS_QUERY_MAX_METRICS,
   METRICS_QUERY_MAX_ROW_LIMIT,
+  MetadataWithKlappaySchema,
   MetricsAggregationSchema,
   MetricsDateGranularitySchema,
   MetricsFilterOperatorSchema,
@@ -851,9 +905,12 @@ export {
   PendingDistributionEventSchema,
   PendingDistributionRecipientSchema,
   PendingDistributionSchema,
+  RecipientSchema,
   SandboxTriggerSchema,
+  SetRecipientPayoutSchema,
   SettlementStatusSchema,
   SplitDistributionStatusSchema,
+  SplitRecipientInputSchema,
   SplitRecipientSchema,
   TOKEN_ADDRESSES,
   TOKEN_DECIMALS,
@@ -875,6 +932,7 @@ export {
   WebhookListItemSchema,
   WebhookPayloadSchema,
   WebhookSchema,
+  findConflictingScopes,
   paginatedSchema
 };
 //# sourceMappingURL=index.mjs.map