@klappay/types 1.0.4 → 1.0.6

package/dist/index.js

@@ -35,9 +35,15 @@ __export(index_exports, {
   ChargeStatusEventSchema: () => ChargeStatusEventSchema,
   ChargeStatusSchema: () => ChargeStatusSchema,
   ChargeWebhookEventTypeSchema: () => ChargeWebhookEventTypeSchema,
+  ChargesDateFieldSchema: () => ChargesDateFieldSchema,
+  ChargesMetricFieldSchema: () => ChargesMetricFieldSchema,
+  ChargesQueryFieldSchema: () => ChargesQueryFieldSchema,
   CreateApiKeySchema: () => CreateApiKeySchema,
   CreateChargeSchema: () => CreateChargeSchema,
   CreateWebhookSchema: () => CreateWebhookSchema,
+  DistributionsDateFieldSchema: () => DistributionsDateFieldSchema,
+  DistributionsMetricFieldSchema: () => DistributionsMetricFieldSchema,
+  DistributionsQueryFieldSchema: () => DistributionsQueryFieldSchema,
   EVENT_CATEGORY_MAP: () => EVENT_CATEGORY_MAP,
   EVM_NETWORKS: () => EVM_NETWORKS,
   EnvironmentSchema: () => EnvironmentSchema,
@@ -52,7 +58,21 @@ __export(index_exports, {
   ListUsersSchema: () => ListUsersSchema,
   ListWebhookDeliveriesSchema: () => ListWebhookDeliveriesSchema,
   LoginSchema: () => LoginSchema,
+  MAX_METRICS_QUERY_DATE_RANGE_DAYS: () => MAX_METRICS_QUERY_DATE_RANGE_DAYS,
+  METRICS_QUERY_DEFAULT_ROW_LIMIT: () => METRICS_QUERY_DEFAULT_ROW_LIMIT,
+  METRICS_QUERY_MAX_FILTERS: () => METRICS_QUERY_MAX_FILTERS,
+  METRICS_QUERY_MAX_GROUP_BY: () => METRICS_QUERY_MAX_GROUP_BY,
+  METRICS_QUERY_MAX_METRICS: () => METRICS_QUERY_MAX_METRICS,
+  METRICS_QUERY_MAX_ROW_LIMIT: () => METRICS_QUERY_MAX_ROW_LIMIT,
   MessageResponseSchema: () => MessageResponseSchema,
+  MetricsAggregationSchema: () => MetricsAggregationSchema,
+  MetricsDateGranularitySchema: () => MetricsDateGranularitySchema,
+  MetricsFilterOperatorSchema: () => MetricsFilterOperatorSchema,
+  MetricsQueryResultRowSchema: () => MetricsQueryResultRowSchema,
+  MetricsQueryResultSchema: () => MetricsQueryResultSchema,
+  MetricsQuerySchema: () => MetricsQuerySchema,
+  MetricsQueryScopeSchema: () => MetricsQueryScopeSchema,
+  MetricsResourceSchema: () => MetricsResourceSchema,
   NETWORK_EXPLORERS: () => NETWORK_EXPLORERS,
   NETWORK_LABELS: () => NETWORK_LABELS,
   NetworkSchema: () => NetworkSchema,
@@ -79,6 +99,7 @@ __export(index_exports, {
   SecurityWebhookEventTypeSchema: () => SecurityWebhookEventTypeSchema,
   SettlementStatusSchema: () => SettlementStatusSchema,
   SignupSchema: () => SignupSchema,
+  SplitDistributionStatusSchema: () => SplitDistributionStatusSchema,
   SplitRecipientRoleSchema: () => SplitRecipientRoleSchema,
   TOKEN_ADDRESSES: () => TOKEN_ADDRESSES,
   TOKEN_DECIMALS: () => TOKEN_DECIMALS,
@@ -86,6 +107,9 @@ __export(index_exports, {
   TimelineEventTypeSchema: () => TimelineEventTypeSchema,
   TokenSchema: () => TokenSchema,
   TransactionSourceSchema: () => TransactionSourceSchema,
+  TransactionsDateFieldSchema: () => TransactionsDateFieldSchema,
+  TransactionsMetricFieldSchema: () => TransactionsMetricFieldSchema,
+  TransactionsQueryFieldSchema: () => TransactionsQueryFieldSchema,
   TriggerableChargeEventSchema: () => TriggerableChargeEventSchema,
   UpdateOrganizationSchema: () => UpdateOrganizationSchema,
   UpdateUserRoleSchema: () => UpdateUserRoleSchema,
@@ -193,7 +217,7 @@ function paginatedSchema(itemSchema) {
 // src/tokens.ts
 var import_zod5 = require("zod");
 var TokenSchema = import_zod5.z.enum(["USDC", "USDT"]).describe(
-  `Which stablecoin the payer will send. Support depends on both \`network\` and \`environment\` \u2014 not every token/network/environment combination is deployed; today, both \`USDC\` and \`USDT\` are deployed on every operational network's \`live\` side except BNB Chain (\`${OPERATIONAL_NETWORKS.join(", ")}\`), but \`test\` coverage varies per network \u2014 Base, Optimism, and Ethereum each have a \`test\` environment (\`USDC\` only; none has an official Sepolia USDT), Arbitrum, Polygon, Avalanche, and BNB Chain have none yet (0xSplits hasn't deployed on Arbitrum Sepolia and has no Polygon, Avalanche Fuji, or BNB testnet support at all). An unconfigured combination is rejected with \`422 token_not_supported\`, not silently accepted. **BNB Chain's \`USDC\` address is Binance-Peg USDC, not an official Circle deployment** \u2014 Circle does not issue native USDC on BNB Chain at all; this is a Binance-custodied, 1:1-pegged BEP-20 token, a materially different trust model than every other \`TOKEN_ADDRESSES\` entry (all verified directly against their real issuer). Accepted at the payer's own risk \u2014 Klap does not verify or guarantee Binance's collateral backing it. \`USDT\` on BNB Chain is Tether's own official issuance, same trust model as everywhere else. More tokens/networks are expected to be added over time \u2014 check \`TOKEN_ADDRESSES\` in \`@klappay/types\` (or a future \`GET /v1/networks\` capabilities endpoint) for the exact current matrix rather than assuming full coverage.`
+  `Which stablecoin the payer will send. Support depends on both \`network\` and \`environment\` \u2014 not every token/network/environment combination is deployed; today, both \`USDC\` and \`USDT\` are deployed on every operational network's \`live\` side except BNB Chain (\`${OPERATIONAL_NETWORKS.join(", ")}\`), but \`test\` coverage varies per network \u2014 Base, Optimism, and Ethereum each have a \`test\` environment (\`USDC\` only; none has an official Sepolia USDT), Arbitrum, Polygon, Avalanche, and BNB Chain have none yet (0xSplits hasn't deployed on Arbitrum Sepolia and has no Polygon, Avalanche Fuji, or BNB testnet support at all). An unconfigured combination is rejected with \`422 token_not_supported\`, not silently accepted. **BNB Chain's \`USDC\` address is Binance-Peg USDC, not an official Circle deployment** \u2014 Circle does not issue native USDC on BNB Chain at all; this is a Binance-custodied, 1:1-pegged BEP-20 token, a materially different trust model than every other \`TOKEN_ADDRESSES\` entry (all verified directly against their real issuer). Accepted at the payer's own risk \u2014 Klappay does not verify or guarantee Binance's collateral backing it. \`USDT\` on BNB Chain is Tether's own official issuance, same trust model as everywhere else. More tokens/networks are expected to be added over time \u2014 check \`TOKEN_ADDRESSES\` in \`@klappay/types\` (or a future \`GET /v1/networks\` capabilities endpoint) for the exact current matrix rather than assuming full coverage.`
 );
 var TOKEN_DECIMALS = 6;
 var TOKEN_ADDRESSES = {
@@ -282,7 +306,7 @@ var CreateChargeSchema = import_zod6.z.object({
     "Scoped to your organization. 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: import_zod6.z.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 Klap."
+    "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: import_zod6.z.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.'
@@ -298,7 +322,7 @@ var CreateChargeSchema = import_zod6.z.object({
   }
 });
 var ChargeSchema = import_zod6.z.object({
-  id: import_zod6.z.string().describe("Klap-generated id, e.g. `ch_...`. Use this to look up the charge later."),
+  id: import_zod6.z.string().describe("Klappay-generated id, e.g. `ch_...`. Use this to look up the charge later."),
   mode: ChargeModeSchema,
   amount: import_zod6.z.number().nullable().describe(
     "The amount originally requested, in `currency` units (up to 6 decimal places). `null` if `amount` was omitted at creation \u2014 this charge accepts any amount, and the first credited transfer confirms it."
@@ -307,7 +331,7 @@ var ChargeSchema = import_zod6.z.object({
     "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` \u2014 unless `amount` itself is `null`, in which case `isOverpaid` never applies."
   ),
   isOverpaid: import_zod6.z.boolean().describe(
-    "`true` if `amountReceived` ended up greater than `amount`. Klap never refunds the difference automatically \u2014 see the docs for why."
+    "`true` if `amountReceived` ended up greater than `amount`. Klappay never refunds the difference automatically \u2014 see the docs for why."
   ),
   currency: import_zod6.z.string().describe("Always `USD` today \u2014 the only supported currency."),
   acceptedPayments: import_zod6.z.array(AcceptedPaymentSchema).describe(
@@ -317,7 +341,7 @@ var ChargeSchema = import_zod6.z.object({
     "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: import_zod6.z.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, Klap never custodies them."
+    "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(),
@@ -343,7 +367,7 @@ var ChargeSchema = import_zod6.z.object({
     "When a transfer was last credited toward this charge, or `createdAt` if none has arrived yet. Only meaningful for a charge with no `expiresAt` \u2014 see `pausedAt`."
   ),
   pausedAt: import_zod6.z.string().datetime().nullable().describe(
-    "Only ever set for a charge with no `expiresAt`: `null` means Klap is actively watching this address in real time (the normal case). A timestamp means no contribution arrived for longer than the inactivity window (90 days for a charge with a goal `amount`, 365 days for one without), so real-time watching was stopped \u2014 the charge itself is never closed, a transfer can still arrive and land, just detected on a much slower fallback poll instead of instantly. Clears automatically (and real-time watching resumes) the moment that happens."
+    "Only ever set for a charge with no `expiresAt`: `null` means Klappay is actively watching this address in real time (the normal case). A timestamp means no contribution arrived for longer than the inactivity window (90 days for a charge with a goal `amount`, 365 days for one without), so real-time watching was stopped \u2014 the charge itself is never closed, a transfer can still arrive and land, just detected on a much slower fallback poll instead of instantly. Clears automatically (and real-time watching resumes) the moment that happens."
   )
 });
 var ListChargesSchema = import_zod6.z.object({
@@ -372,6 +396,9 @@ var ChargeStatusEventSchema = import_zod6.z.object({
 
 // src/distributions.ts
 var import_zod7 = require("zod");
+var SplitDistributionStatusSchema = import_zod7.z.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 = import_zod7.z.object({
   address: import_zod7.z.string().describe("On-chain recipient address."),
   percentAllocation: import_zod7.z.number().describe("This recipient's share of the split, as a percentage (e.g. `99.0991` = 99.0991%).")
@@ -387,11 +414,11 @@ var PendingDistributionSchema = import_zod7.z.object({
     "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: import_zod7.z.number().describe(
-    "Estimate only, in the charge's `currency` units, based on the amount Klap 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."
+    "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: import_zod7.z.string().datetime().describe("When this distribution entered its grace period."),
   graceEndsAt: import_zod7.z.string().datetime().describe(
-    "When Klap's own worker may claim this distribution. Racing to call `distribute()` after this timestamp is possible but increasingly likely to lose to the worker."
+    "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 PendingDistributionEventSchema = import_zod7.z.discriminatedUnion("type", [
@@ -405,9 +432,255 @@ var PendingDistributionEventSchema = import_zod7.z.discriminatedUnion("type", [
   })
 ]);
 
-// src/webhook-events.ts
+// src/metrics.ts
 var import_zod8 = require("zod");
-var ChargeWebhookEventTypeSchema = import_zod8.z.enum([
+var MetricsResourceSchema = import_zod8.z.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 = import_zod8.z.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 = import_zod8.z.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 = import_zod8.z.enum(["day", "week", "month"]).describe(
+  "Bucket width for a `date_bucket` `groupBy` entry \u2014 Postgres `date_trunc` semantics (UTC)."
+);
+var metricsQueryEnvironmentSchema = EnvironmentSchema.describe(
+  "Which environment's data to query \u2014 `live` or `test`. Independent of your session (a dashboard user isn't scoped to one environment the way an API key is) \u2014 scopes the query to charges/transactions/distributions created under a `live` or `test` API key respectively."
+);
+var MAX_METRICS_QUERY_DATE_RANGE_DAYS = 366;
+var METRICS_QUERY_MAX_ROW_LIMIT = 1e3;
+var METRICS_QUERY_DEFAULT_ROW_LIMIT = 100;
+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 = import_zod8.z.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 = import_zod8.z.union([
+  import_zod8.z.string().max(255),
+  import_zod8.z.number(),
+  import_zod8.z.boolean(),
+  import_zod8.z.array(import_zod8.z.union([import_zod8.z.string().max(255), import_zod8.z.number()])).min(1).max(50)
+]);
+var orderBySchema = import_zod8.z.object({
+  key: import_zod8.z.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: import_zod8.z.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 = import_zod8.z.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 = import_zod8.z.enum(["status", "mode", "source", "apiKeyId", "currency", "isOverpaid", "externalRef"]).describe(
+  "A `Charge` field to filter or group by \u2014 see `ChargeStatusSchema`/`ChargeModeSchema` for `status`/`mode`'s own possible values (charges.md). `source`/`externalRef` are free-form strings your own integration set at creation, not a fixed enum."
+);
+var ChargesMetricFieldSchema = import_zod8.z.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 = import_zod8.z.enum(["createdAt", "confirmedAt", "lastActivityAt"]).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."
+);
+var ChargesFilterSchema = import_zod8.z.object({
+  field: ChargesQueryFieldSchema,
+  operator: MetricsFilterOperatorSchema,
+  value: MetricsFilterValueSchema
+});
+var ChargesGroupBySchema = import_zod8.z.union([
+  import_zod8.z.object({ type: import_zod8.z.literal("field"), field: ChargesQueryFieldSchema }),
+  import_zod8.z.object({
+    type: import_zod8.z.literal("date_bucket"),
+    field: ChargesDateFieldSchema,
+    granularity: MetricsDateGranularitySchema
+  })
+]);
+var ChargesMetricSchema = import_zod8.z.object({
+  aggregation: MetricsAggregationSchema,
+  field: ChargesMetricFieldSchema.optional(),
+  alias: metricAliasSchema
+});
+var ChargesMetricsQuerySchema = import_zod8.z.object({
+  resource: import_zod8.z.literal("charges"),
+  environment: metricsQueryEnvironmentSchema,
+  dateRange: import_zod8.z.object({
+    field: ChargesDateFieldSchema,
+    from: import_zod8.z.string().max(64).datetime(),
+    to: import_zod8.z.string().max(64).datetime()
+  }),
+  groupBy: import_zod8.z.array(ChargesGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
+  metrics: import_zod8.z.array(ChargesMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
+  filters: import_zod8.z.array(ChargesFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
+  orderBy: orderBySchema.optional(),
+  limit: limitSchema
+});
+var TransactionsQueryFieldSchema = import_zod8.z.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 = import_zod8.z.enum(["amount"]).describe("The transfer amount, in the charge's `currency` units.");
+var TransactionsDateFieldSchema = import_zod8.z.enum(["detectedAt"]).describe("When Klappay detected this transfer on-chain (not when it was mined).");
+var TransactionsFilterSchema = import_zod8.z.object({
+  field: TransactionsQueryFieldSchema,
+  operator: MetricsFilterOperatorSchema,
+  value: MetricsFilterValueSchema
+});
+var TransactionsGroupBySchema = import_zod8.z.union([
+  import_zod8.z.object({ type: import_zod8.z.literal("field"), field: TransactionsQueryFieldSchema }),
+  import_zod8.z.object({
+    type: import_zod8.z.literal("date_bucket"),
+    field: TransactionsDateFieldSchema,
+    granularity: MetricsDateGranularitySchema
+  })
+]);
+var TransactionsMetricSchema = import_zod8.z.object({
+  aggregation: MetricsAggregationSchema,
+  field: TransactionsMetricFieldSchema.optional(),
+  alias: metricAliasSchema
+});
+var TransactionsMetricsQuerySchema = import_zod8.z.object({
+  resource: import_zod8.z.literal("transactions"),
+  environment: metricsQueryEnvironmentSchema,
+  dateRange: import_zod8.z.object({
+    field: TransactionsDateFieldSchema,
+    from: import_zod8.z.string().max(64).datetime(),
+    to: import_zod8.z.string().max(64).datetime()
+  }),
+  groupBy: import_zod8.z.array(TransactionsGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
+  metrics: import_zod8.z.array(TransactionsMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
+  filters: import_zod8.z.array(TransactionsFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
+  orderBy: orderBySchema.optional(),
+  limit: limitSchema
+});
+var DistributionsQueryFieldSchema = import_zod8.z.enum(["status", "network", "token"]).describe(
+  "A `SplitDistribution` field to filter or group by \u2014 see `SplitDistributionStatusSchema`/`NetworkSchema`/`TokenSchema` for their possible values."
+);
+var DistributionsMetricFieldSchema = import_zod8.z.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 = import_zod8.z.enum(["createdAt", "completedAt"]).describe(
+  "`createdAt`: when this settlement was queued. `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 = import_zod8.z.object({
+  field: DistributionsQueryFieldSchema,
+  operator: MetricsFilterOperatorSchema,
+  value: MetricsFilterValueSchema
+});
+var DistributionsGroupBySchema = import_zod8.z.union([
+  import_zod8.z.object({ type: import_zod8.z.literal("field"), field: DistributionsQueryFieldSchema }),
+  import_zod8.z.object({
+    type: import_zod8.z.literal("date_bucket"),
+    field: DistributionsDateFieldSchema,
+    granularity: MetricsDateGranularitySchema
+  })
+]);
+var DistributionsMetricSchema = import_zod8.z.object({
+  aggregation: MetricsAggregationSchema,
+  field: DistributionsMetricFieldSchema.optional(),
+  alias: metricAliasSchema
+});
+var DistributionsMetricsQuerySchema = import_zod8.z.object({
+  resource: import_zod8.z.literal("distributions"),
+  environment: metricsQueryEnvironmentSchema,
+  dateRange: import_zod8.z.object({
+    field: DistributionsDateFieldSchema,
+    from: import_zod8.z.string().max(64).datetime(),
+    to: import_zod8.z.string().max(64).datetime()
+  }),
+  groupBy: import_zod8.z.array(DistributionsGroupBySchema).max(METRICS_QUERY_MAX_GROUP_BY).default([]),
+  metrics: import_zod8.z.array(DistributionsMetricSchema).min(1).max(METRICS_QUERY_MAX_METRICS),
+  filters: import_zod8.z.array(DistributionsFilterSchema).max(METRICS_QUERY_MAX_FILTERS).default([]),
+  orderBy: orderBySchema.optional(),
+  limit: limitSchema
+});
+var ONE_DAY_MS = 24 * 60 * 60 * 1e3;
+var MetricsQuerySchema = import_zod8.z.discriminatedUnion("resource", [
+  ChargesMetricsQuerySchema,
+  TransactionsMetricsQuerySchema,
+  DistributionsMetricsQuerySchema
+]).superRefine((input, ctx) => {
+  const from = new Date(input.dateRange.from);
+  const to = new Date(input.dateRange.to);
+  if (from >= to) {
+    ctx.addIssue({
+      code: import_zod8.z.ZodIssueCode.custom,
+      message: "`dateRange.from` must be before `dateRange.to`.",
+      path: ["dateRange", "from"]
+    });
+  }
+  const spanDays = (to.getTime() - from.getTime()) / ONE_DAY_MS;
+  if (spanDays > MAX_METRICS_QUERY_DATE_RANGE_DAYS) {
+    ctx.addIssue({
+      code: import_zod8.z.ZodIssueCode.custom,
+      message: `\`dateRange\` cannot span more than ${MAX_METRICS_QUERY_DATE_RANGE_DAYS} days.`,
+      path: ["dateRange", "to"]
+    });
+  }
+  const dateBucketCount = input.groupBy.filter((entry) => entry.type === "date_bucket").length;
+  if (dateBucketCount > 1) {
+    ctx.addIssue({
+      code: import_zod8.z.ZodIssueCode.custom,
+      message: "At most one `date_bucket` entry is allowed in `groupBy`.",
+      path: ["groupBy"]
+    });
+  }
+  input.metrics.forEach((metric, index) => {
+    if (metric.aggregation !== "count" && metric.field === void 0) {
+      ctx.addIssue({
+        code: import_zod8.z.ZodIssueCode.custom,
+        message: "`field` is required unless `aggregation` is `count`.",
+        path: ["metrics", index, "field"]
+      });
+    }
+  });
+  const aliases = input.metrics.map((metric) => metric.alias).filter((alias) => alias !== void 0);
+  if (new Set(aliases).size !== aliases.length) {
+    ctx.addIssue({
+      code: import_zod8.z.ZodIssueCode.custom,
+      message: "Every `metrics[].alias` must be unique.",
+      path: ["metrics"]
+    });
+  }
+  const reservedNames = /* @__PURE__ */ new Set(["bucket", ...input.groupBy.map((entry) => entry.field)]);
+  input.metrics.forEach((metric, index) => {
+    if (metric.alias !== void 0 && reservedNames.has(metric.alias)) {
+      ctx.addIssue({
+        code: import_zod8.z.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 = import_zod8.z.record(
+  import_zod8.z.string(),
+  import_zod8.z.union([import_zod8.z.string(), import_zod8.z.number(), import_zod8.z.boolean(), import_zod8.z.null()])
+);
+var MetricsQueryScopeSchema = import_zod8.z.enum(["owner_admin", "member"]).describe(
+  "`member`: results were automatically restricted to data tied to API keys you personally created \u2014 rows with no resolvable creator were excluded, not counted, and not surfaced any other way. `owner_admin`: the full organization\u2019s data was queried, no restriction applied."
+);
+var MetricsQueryResultSchema = import_zod8.z.object({
+  data: import_zod8.z.array(MetricsQueryResultRowSchema),
+  meta: import_zod8.z.object({
+    resource: MetricsResourceSchema,
+    environment: EnvironmentSchema,
+    scope: MetricsQueryScopeSchema,
+    rowCount: import_zod8.z.number().int().describe("Number of rows in `data`."),
+    truncated: import_zod8.z.boolean().describe(
+      "`true` if more rows matched than `limit` allowed \u2014 `data` holds only the first `limit`."
+    )
+  })
+});
+
+// src/webhook-events.ts
+var import_zod9 = require("zod");
+var ChargeWebhookEventTypeSchema = import_zod9.z.enum([
   "charge.created",
   "charge.partially_paid",
   "charge.confirmed",
@@ -421,9 +694,9 @@ var ChargeWebhookEventTypeSchema = import_zod8.z.enum([
   "charge.contribution_received",
   "charge.contribution_settled"
 ]).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`, except `charge.paused`/`charge.reactivated`/`charge.contribution_received`/`charge.contribution_settled` (see below). `charge.paused` fires when a charge with no `expiresAt` has had no contribution for longer than its inactivity window (90 days for a charge with a goal `amount`, 365 days for one without) \u2014 Klap stops watching its address in real time, but the charge itself is never closed; `charge.reactivated` fires the moment a transfer lands on a paused charge, detected by the same fallback poller used for missed webhooks (so with much higher latency than normal \u2014 pausing trades that away deliberately, see `docs/payments.md`). `charge.contribution_received`/`charge.contribution_settled` are exclusive to `mode: continuous` charges (see `Charge.mode`) \u2014 a continuous charge never fires `charge.confirmed`/`charge.settled` at all, since `status` never leaves `pending`; instead every individual transfer fires `contribution_received` on detection and `contribution_settled` once its payout completes, one pair-scoped event per contribution instead of one event for the whole charge. `data` for `charge.paused`: `{ chargeId, lastActivityAt, pausedAt }`; for `charge.reactivated`: `{ chargeId, reactivatedAt }`; for `charge.contribution_received`: `{ chargeId, token, network, amount, txHash, payerAddress }`; for `charge.contribution_settled`: `{ chargeId, token, network, amount, txHash, distributorAddress }`.'
+  '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`, except `charge.paused`/`charge.reactivated`/`charge.contribution_received`/`charge.contribution_settled` (see below). `charge.paused` fires when a charge with no `expiresAt` has had no contribution for longer than its inactivity window (90 days for a charge with a goal `amount`, 365 days for one without) \u2014 Klappay stops watching its address in real time, but the charge itself is never closed; `charge.reactivated` fires the moment a transfer lands on a paused charge, detected by the same fallback poller used for missed webhooks (so with much higher latency than normal \u2014 pausing trades that away deliberately, see `docs/payments.md`). `charge.contribution_received`/`charge.contribution_settled` are exclusive to `mode: continuous` charges (see `Charge.mode`) \u2014 a continuous charge never fires `charge.confirmed`/`charge.settled` at all, since `status` never leaves `pending`; instead every individual transfer fires `contribution_received` on detection and `contribution_settled` once its payout completes, one pair-scoped event per contribution instead of one event for the whole charge. `data` for `charge.paused`: `{ chargeId, lastActivityAt, pausedAt }`; for `charge.reactivated`: `{ chargeId, reactivatedAt }`; for `charge.contribution_received`: `{ chargeId, token, network, amount, txHash, payerAddress }`; for `charge.contribution_settled`: `{ chargeId, token, network, amount, txHash, distributorAddress }`.'
 );
-var AccountWebhookEventTypeSchema = import_zod8.z.enum([
+var AccountWebhookEventTypeSchema = import_zod9.z.enum([
   "payout_address.changed",
   "api_key.created",
   "api_key.revoked",
@@ -437,10 +710,10 @@ var AccountWebhookEventTypeSchema = import_zod8.z.enum([
 ]).describe(
   "Account and configuration changes \u2014 not tied to any single charge. `data` per event: `payout_address.changed`: `{ organizationId, from, to }` (`from` nullable); `api_key.created`/`api_key.revoked`: `{ apiKeyId, name, environment, hint }`; `webhook.created`/`webhook.deleted`/`webhook.secret_rotated`: `{ webhookId, url }`; `fee_tier.updated`: `{ organizationId, previousFeePercent, newFeePercent }`; `member.removed`: `{ userId, email, role }`; `member.role_changed`: `{ userId, email, role, previousRole }`; `member.invited`: `{ organizationId, email, role, invitedByUserId }`."
 );
-var WebhookDeliveryEventTypeSchema = import_zod8.z.enum(["webhook.delivery_failed", "webhook.delivery_recovered", "webhook.endpoint_unhealthy"]).describe(
+var WebhookDeliveryEventTypeSchema = import_zod9.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`)."
 );
-var SecurityWebhookEventTypeSchema = import_zod8.z.enum([
+var SecurityWebhookEventTypeSchema = import_zod9.z.enum([
   "auth.login",
   "auth.login_failed",
   "auth.suspicious_activity",
@@ -450,13 +723,13 @@ var SecurityWebhookEventTypeSchema = import_zod8.z.enum([
 ]).describe(
   "Account security signals. `auth.suspicious_activity` is a soft heuristic (login from an IP not seen on this account before), not a block \u2014 evaluate it, not enforce against it. `auth.password_reset_requested` only ever dispatches when the requested email actually matches an account (there is nowhere to notify otherwise) \u2014 `POST /v1/auth/forgot-password` itself always returns the same generic response either way, so this event never becomes a second channel for the same enumeration question the endpoint response deliberately avoids answering. `data` per event: `auth.login`: `{ userId, ipAddress }`; `auth.login_failed`: `{ email, ipAddress }`; `auth.suspicious_activity`: `{ userId, ipAddress, previousIpAddress }`; `auth.email_verified`/`auth.password_reset_requested`/`auth.password_reset_completed`: `{ userId, email }`."
 );
-var WebhookEventTypeSchema = import_zod8.z.union([
+var WebhookEventTypeSchema = import_zod9.z.union([
   ChargeWebhookEventTypeSchema,
   AccountWebhookEventTypeSchema,
   WebhookDeliveryEventTypeSchema,
   SecurityWebhookEventTypeSchema
 ]);
-var WebhookCategorySchema = import_zod8.z.enum(["payments", "account", "webhooks", "security"]).describe(
+var WebhookCategorySchema = import_zod9.z.enum(["payments", "account", "webhooks", "security"]).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() {
@@ -483,99 +756,101 @@ var TriggerableChargeEventSchema = ChargeWebhookEventTypeSchema.exclude([
 ]).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), `charge.paused`/`charge.reactivated` (driven by a background worker on real inactivity, not a payment state \u2014 nothing meaningful to simulate or wait for on a fresh sandbox charge), and `charge.contribution_received`/`charge.contribution_settled` (exclusive to `mode: continuous` charges, which this trigger endpoint does not support simulating today \u2014 see `POST /v1/charges/{id}/trigger`'s own description)."
 );
-var NonChargeTriggerableEventSchema = import_zod8.z.union([
+var NonChargeTriggerableEventSchema = import_zod9.z.union([
   AccountWebhookEventTypeSchema,
   WebhookDeliveryEventTypeSchema,
   SecurityWebhookEventTypeSchema
 ]);
 
 // src/webhooks.ts
-var import_zod9 = require("zod");
+var import_zod10 = require("zod");
 var WEBHOOK_EVENTS_WILDCARD = "*";
-var CreateWebhookSchema = import_zod9.z.object({
-  url: import_zod9.z.string().max(2048).url().describe(
+var CreateWebhookSchema = import_zod10.z.object({
+  url: import_zod10.z.string().max(2048).url().describe(
     "Must be HTTPS and resolve to a public address \u2014 private/internal IPs are rejected."
   ),
-  events: import_zod9.z.array(import_zod9.z.union([WebhookEventTypeSchema, import_zod9.z.literal(WEBHOOK_EVENTS_WILDCARD)])).max(Object.keys(EVENT_CATEGORY_MAP).length + 1).default([]).describe(
+  events: import_zod10.z.array(import_zod10.z.union([WebhookEventTypeSchema, import_zod10.z.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: import_zod9.z.array(WebhookCategorySchema).max(WebhookCategorySchema.options.length).default([]).describe(
+  eventCategories: import_zod10.z.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: import_zod9.z.array(WebhookEventTypeSchema).max(Object.keys(EVENT_CATEGORY_MAP).length).default([]).describe(
+  excludeEvents: import_zod10.z.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 = import_zod9.z.object({
-  id: import_zod9.z.string(),
-  url: import_zod9.z.string(),
-  events: import_zod9.z.array(WebhookEventTypeSchema),
-  eventCategories: import_zod9.z.array(WebhookCategorySchema),
-  excludeEvents: import_zod9.z.array(WebhookEventTypeSchema),
-  isWildcard: import_zod9.z.boolean(),
-  secret: import_zod9.z.string().describe(
-    "The signing secret, used to verify the `X-Klap-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 Klap 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."
+var WebhookSchema = import_zod10.z.object({
+  id: import_zod10.z.string(),
+  url: import_zod10.z.string(),
+  events: import_zod10.z.array(WebhookEventTypeSchema),
+  eventCategories: import_zod10.z.array(WebhookCategorySchema),
+  excludeEvents: import_zod10.z.array(WebhookEventTypeSchema),
+  isWildcard: import_zod10.z.boolean(),
+  secret: import_zod10.z.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: import_zod9.z.string().datetime()
+  createdAt: import_zod10.z.string().datetime()
 });
 var WebhookListItemSchema = WebhookSchema.omit({ secret: true }).extend({
-  hint: import_zod9.z.string().describe("A truncated, safe-to-display form of the secret (e.g. `whsec_...ab12`).")
+  hint: import_zod10.z.string().describe("A truncated, safe-to-display form of the secret (e.g. `whsec_...ab12`).")
 });
-var WebhookPayloadSchema = import_zod9.z.object({
-  id: import_zod9.z.string().describe("Unique id for this specific delivery \u2014 also sent as the `X-Klap-Delivery` header."),
+var WebhookPayloadSchema = import_zod10.z.object({
+  id: import_zod10.z.string().describe(
+    "Unique id for this specific delivery \u2014 also sent as the `X-Klappay-Delivery` header."
+  ),
   event: WebhookEventTypeSchema,
-  createdAt: import_zod9.z.string().datetime(),
-  data: import_zod9.z.unknown().describe(
+  createdAt: import_zod10.z.string().datetime(),
+  data: import_zod10.z.unknown().describe(
     "Event-specific data. Charge events (`charge.*`) carry the full `Charge` object; account/security/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 = import_zod9.z.enum(["pending", "delivered", "failed"]);
-var WebhookDeliverySchema = import_zod9.z.object({
-  id: import_zod9.z.string(),
-  webhookId: import_zod9.z.string(),
+var WebhookDeliveryStatusSchema = import_zod10.z.enum(["pending", "delivered", "failed"]);
+var WebhookDeliverySchema = import_zod10.z.object({
+  id: import_zod10.z.string(),
+  webhookId: import_zod10.z.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: import_zod9.z.number(),
-  responseCode: import_zod9.z.number().nullable().describe(
+  attempts: import_zod10.z.number(),
+  responseCode: import_zod10.z.number().nullable().describe(
     "HTTP status your endpoint returned on the most recent attempt. `null` if every attempt failed to connect at all."
   ),
-  nextRetryAt: import_zod9.z.string().datetime().nullable(),
-  deliveredAt: import_zod9.z.string().datetime().nullable(),
-  createdAt: import_zod9.z.string().datetime()
+  nextRetryAt: import_zod10.z.string().datetime().nullable(),
+  deliveredAt: import_zod10.z.string().datetime().nullable(),
+  createdAt: import_zod10.z.string().datetime()
 });
 var ListWebhookDeliveriesSchema = PaginationQuerySchema;
 var PaginatedWebhookDeliveriesSchema = paginatedSchema(WebhookDeliverySchema);
 
 // src/api-keys.ts
-var import_zod10 = require("zod");
-var CreateApiKeySchema = import_zod10.z.object({
-  name: import_zod10.z.string().min(1).max(64).describe(
+var import_zod11 = require("zod");
+var CreateApiKeySchema = import_zod11.z.object({
+  name: import_zod11.z.string().min(1).max(64).describe(
     'A label to help you tell keys apart (e.g. `"production backend"`). Not used for anything functional.'
   ),
   environment: EnvironmentSchema.describe(
     "`live` keys move real funds on Base mainnet; `test` keys settle on Base Sepolia (a real testnet, no real money) and additionally unlock `POST /v1/sandbox/*` for simulating events with zero on-chain activity at all."
   )
 });
-var ApiKeySchema = import_zod10.z.object({
-  id: import_zod10.z.string(),
-  name: import_zod10.z.string(),
+var ApiKeySchema = import_zod11.z.object({
+  id: import_zod11.z.string(),
+  name: import_zod11.z.string(),
   environment: EnvironmentSchema.describe(
     "`live` keys authenticate real charges on Base mainnet; `test` keys authenticate the same charge lifecycle on Base Sepolia (a real testnet) and additionally unlock `/v1/sandbox/*` for synthetic event simulation."
   ),
-  key: import_zod10.z.string().optional().describe(
+  key: import_zod11.z.string().optional().describe(
     "The full secret key (`klap_live_...` / `klap_test_...`), used as the `Authorization: Bearer` value on `/v1/charges`, `/v1/webhooks`, and `/v1/sandbox` requests. Present only in the response to `POST /v1/api-keys` \u2014 never returned again afterward, so store it immediately."
   ),
-  hint: import_zod10.z.string().describe(
+  hint: import_zod11.z.string().describe(
     "A truncated, always-safe-to-display form of the key (e.g. `klap_live_...ab12`), returned everywhere the full key isn't."
   ),
-  createdAt: import_zod10.z.string().datetime(),
-  lastUsedAt: import_zod10.z.string().datetime().nullable().describe("Updated on every successful authenticated request. `null` if never used."),
-  createdByUserId: import_zod10.z.string().nullable().describe(
+  createdAt: import_zod11.z.string().datetime(),
+  lastUsedAt: import_zod11.z.string().datetime().nullable().describe("Updated on every successful authenticated request. `null` if never used."),
+  createdByUserId: import_zod11.z.string().nullable().describe(
     "Which member of the organization created this key. `null` for a key created before this field existed."
   )
 });
@@ -583,76 +858,78 @@ var ListApiKeysSchema = PaginationQuerySchema;
 var PaginatedApiKeysSchema = paginatedSchema(ApiKeySchema);
 
 // src/users.ts
-var import_zod11 = require("zod");
-var UserRoleSchema = import_zod11.z.enum(["owner", "admin", "member"]).describe(
+var import_zod12 = require("zod");
+var UserRoleSchema = import_zod12.z.enum(["owner", "admin", "member"]).describe(
   "`owner`: full access, and the organization must always keep at least one. `admin`: can manage `member`s but not other `admin`s. `member`: no management permissions. You can only manage a member with a strictly lower role than your own, unless you're an `owner`."
 );
-var UpdateUserRoleSchema = import_zod11.z.object({
+var UpdateUserRoleSchema = import_zod12.z.object({
   role: UserRoleSchema
 });
-var UserSchema = import_zod11.z.object({
-  id: import_zod11.z.string(),
-  email: import_zod11.z.string(),
-  name: import_zod11.z.string().nullable(),
+var UserSchema = import_zod12.z.object({
+  id: import_zod12.z.string(),
+  email: import_zod12.z.string(),
+  name: import_zod12.z.string().nullable(),
   role: UserRoleSchema.describe("Your role within the organization this user was fetched from."),
-  emailVerifiedAt: import_zod11.z.string().datetime().nullable().describe(
+  emailVerifiedAt: import_zod12.z.string().datetime().nullable().describe(
     "When this address was confirmed via the emailed verification link. `null` until then. Required (non-null) for two specific actions: creating a `live` API key (`POST /v1/api-keys`) and changing `Organization.payoutAddress` (`PATCH /v1/organization`) \u2014 everything else works regardless of verification status."
   ),
-  createdAt: import_zod11.z.string().datetime()
+  createdAt: import_zod12.z.string().datetime()
 });
 var ListUsersSchema = PaginationQuerySchema;
 var PaginatedUsersSchema = paginatedSchema(UserSchema);
 
 // src/auth.ts
-var import_zod12 = require("zod");
-var NormalizedEmailSchema = import_zod12.z.string().trim().max(255).toLowerCase().email().transform((email) => email.normalize("NFC")).describe(
+var import_zod13 = require("zod");
+var NormalizedEmailSchema = import_zod13.z.string().trim().max(255).toLowerCase().email().transform((email) => email.normalize("NFC")).describe(
   "Trimmed, lowercased, and NFC-normalized server-side before use \u2014 case/whitespace don't matter."
 );
-var SignupSchema = import_zod12.z.object({
+var SignupSchema = import_zod13.z.object({
   email: NormalizedEmailSchema,
-  password: import_zod12.z.string().min(8).max(128).describe("8-128 characters. No other complexity rule.")
+  password: import_zod13.z.string().min(8).max(128).describe("8-128 characters. No other complexity rule.")
 });
-var LoginSchema = import_zod12.z.object({
+var LoginSchema = import_zod13.z.object({
   email: NormalizedEmailSchema,
-  password: import_zod12.z.string().min(1).max(128)
+  password: import_zod13.z.string().min(1).max(128)
 });
-var VerifyEmailSchema = import_zod12.z.object({
-  token: import_zod12.z.string().min(1).describe("The token from the verification email \u2014 passed as-is, not the account email.")
+var VerifyEmailSchema = import_zod13.z.object({
+  token: import_zod13.z.string().min(1).describe("The token from the verification email \u2014 passed as-is, not the account email.")
 });
-var ForgotPasswordSchema = import_zod12.z.object({
+var ForgotPasswordSchema = import_zod13.z.object({
   email: NormalizedEmailSchema
 });
-var ResetPasswordSchema = import_zod12.z.object({
-  token: import_zod12.z.string().min(1).describe("The token from the password reset email."),
-  newPassword: import_zod12.z.string().min(8).max(128)
+var ResetPasswordSchema = import_zod13.z.object({
+  token: import_zod13.z.string().min(1).describe("The token from the password reset email."),
+  newPassword: import_zod13.z.string().min(8).max(128)
 });
-var MessageResponseSchema = import_zod12.z.object({
-  message: import_zod12.z.string().describe("Human-readable confirmation, safe to show a user directly.")
+var MessageResponseSchema = import_zod13.z.object({
+  message: import_zod13.z.string().describe("Human-readable confirmation, safe to show a user directly.")
 });
-var AuthResponseSchema = import_zod12.z.object({
-  token: import_zod12.z.string().describe(
+var AuthResponseSchema = import_zod13.z.object({
+  token: import_zod13.z.string().describe(
     "Session JWT, valid 7 days \u2014 use as `Authorization: Bearer <token>` on every `/v1/organizations/*` request (which nests API keys, members, and invitations \u2014 see `GET /v1/organizations`). This token identifies only you; it carries no organization or role \u2014 every `/v1/organizations/{id}/*` request is authorized fresh against your actual membership in that specific organization. This is a separate credential from an API key: it authenticates a human/dashboard session, not payment operations. Create an API key with it before you can create charges."
   ),
   user: UserSchema.omit({ createdAt: true, role: true })
 });
 
 // src/organization.ts
-var import_zod13 = require("zod");
-var UpdateOrganizationSchema = import_zod13.z.object({
-  name: import_zod13.z.string().min(1).max(255).optional().describe("The organization's display name."),
-  payoutAddress: import_zod13.z.string().regex(/^0x[a-fA-F0-9]{40}$/, "must be a valid EVM address").optional().describe(
+var import_zod14 = require("zod");
+var UpdateOrganizationSchema = import_zod14.z.object({
+  name: import_zod14.z.string().min(1).max(255).optional().describe("The organization's display name."),
+  payoutAddress: import_zod14.z.string().regex(/^0x[a-fA-F0-9]{40}$/, "must be a valid EVM address").optional().describe(
     "The wallet that receives the merchant's share of every future charge. Changing this only affects charges created after the change \u2014 an already-created charge's payout split is frozen from creation and is never retroactively affected. Required before you can create any charge. Any casing is accepted \u2014 EIP-55 checksum casing is not required or verified."
   )
 });
-var OrganizationSchema = import_zod13.z.object({
-  id: import_zod13.z.string(),
-  name: import_zod13.z.string(),
-  payoutAddress: import_zod13.z.string().nullable().describe("`null` until configured \u2014 `POST /v1/charges` fails until this is set."),
-  currentFeePercent: import_zod13.z.number().describe(
-    "Your current platform fee percentage, based on trailing monthly volume \u2014 lower volume tiers pay a higher percentage. `1.5` means 1.5%, not a 0\u20131 fraction. Frozen onto each charge at creation, so this can change between charges without affecting ones already created."
+var OrganizationSchema = import_zod14.z.object({
+  id: import_zod14.z.string(),
+  name: import_zod14.z.string(),
+  payoutAddress: import_zod14.z.string().nullable().describe("`null` until configured \u2014 `POST /v1/charges` fails until this is set."),
+  currentFeePercent: import_zod14.z.number().describe(
+    "Your current platform fee percentage \u2014 `1.5` means 1.5%, not a 0\u20131 fraction. Funds the infrastructure Klappay runs on your behalf (on-chain monitoring, settlement, webhook delivery, support) the same way any payment processor's fee does; this is not optional or removable. Dynamic, not fixed: it's based on your trailing monthly volume, with lower volume paying a higher percentage \u2014 higher-volume organizations, or ones with a specific negotiated arrangement, can be assigned a different rate at Klappay's discretion. Frozen onto each charge at creation, so a rate change never retroactively affects a charge already created; see `feeUpdatedAt` for when it last changed. Contact Klappay if you'd like your rate reviewed."
   ),
-  feeUpdatedAt: import_zod13.z.string().datetime().nullable(),
-  createdAt: import_zod13.z.string().datetime()
+  feeUpdatedAt: import_zod14.z.string().datetime().nullable().describe(
+    "When `currentFeePercent` last changed. `null` if it has never changed since this organization signed up."
+  ),
+  createdAt: import_zod14.z.string().datetime()
 });
 var OrganizationWithRoleSchema = OrganizationSchema.extend({
   role: UserRoleSchema.describe("Your own role within this specific organization.")
@@ -661,35 +938,35 @@ var PaginatedOrganizationsSchema = paginatedSchema(OrganizationWithRoleSchema);
 var ListOrganizationsSchema = PaginationQuerySchema;
 
 // src/invitations.ts
-var import_zod14 = require("zod");
-var InviteUserSchema = import_zod14.z.object({
+var import_zod15 = require("zod");
+var InviteUserSchema = import_zod15.z.object({
   email: NormalizedEmailSchema,
   role: UserRoleSchema.default("member").describe(
     "The role the invitee will hold once they accept \u2014 subject to the same management-hierarchy rule as `PATCH /v1/organizations/{id}/users/{userId}`: an `admin` inviter cannot invite an `admin` or `owner`."
   )
 });
-var AcceptInvitationSchema = import_zod14.z.object({
-  token: import_zod14.z.string().min(1).describe("The token from the invitation email."),
-  password: import_zod14.z.string().min(8).max(128).optional().describe(
-    "Required only if the invited email has no existing Klap account \u2014 a new account is created along with the membership. Ignored if the account already exists."
+var AcceptInvitationSchema = import_zod15.z.object({
+  token: import_zod15.z.string().min(1).describe("The token from the invitation email."),
+  password: import_zod15.z.string().min(8).max(128).optional().describe(
+    "Required only if the invited email has no existing Klappay account \u2014 a new account is created along with the membership. Ignored if the account already exists."
   )
 });
-var InvitationSchema = import_zod14.z.object({
-  id: import_zod14.z.string(),
-  organizationId: import_zod14.z.string(),
-  email: import_zod14.z.string(),
+var InvitationSchema = import_zod15.z.object({
+  id: import_zod15.z.string(),
+  organizationId: import_zod15.z.string(),
+  email: import_zod15.z.string(),
   role: UserRoleSchema,
-  invitedByUserId: import_zod14.z.string().describe("Which member of the organization sent this invitation."),
-  expiresAt: import_zod14.z.string().datetime(),
-  createdAt: import_zod14.z.string().datetime()
+  invitedByUserId: import_zod15.z.string().describe("Which member of the organization sent this invitation."),
+  expiresAt: import_zod15.z.string().datetime(),
+  createdAt: import_zod15.z.string().datetime()
 });
 
 // src/timeline.ts
-var import_zod15 = require("zod");
-var TransactionSourceSchema = import_zod15.z.enum(["moralis_webhook", "reconciliation_job", "sandbox"]).describe(
+var import_zod16 = require("zod");
+var TransactionSourceSchema = import_zod16.z.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 = import_zod15.z.enum([
+var TimelineEventTypeSchema = import_zod16.z.enum([
   "charge.created",
   "charge.expired",
   "transaction.detected",
@@ -700,11 +977,11 @@ var TimelineEventTypeSchema = import_zod15.z.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 = import_zod15.z.object({
+var TimelineEventSchema = import_zod16.z.object({
   type: TimelineEventTypeSchema,
-  at: import_zod15.z.string().datetime(),
-  txHash: import_zod15.z.string().optional().describe("Present for `transaction.detected` and `split.distributed` events only."),
-  amount: import_zod15.z.number().optional().describe(
+  at: import_zod16.z.string().datetime(),
+  txHash: import_zod16.z.string().optional().describe("Present for `transaction.detected` and `split.distributed` events only."),
+  amount: import_zod16.z.number().optional().describe(
     "Present for `transaction.detected` events only \u2014 the amount that specific transfer carried."
   ),
   source: TransactionSourceSchema.optional().describe(
@@ -716,100 +993,100 @@ var TimelineEventSchema = import_zod15.z.object({
   network: NetworkSchema.optional().describe(
     "Present for `transaction.detected` and `split.distributed` events \u2014 which network this specific transfer, or settlement, used."
   ),
-  causedTransition: import_zod15.z.boolean().optional().describe(
+  causedTransition: import_zod16.z.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: import_zod15.z.number().nullable().optional().describe(
+  responseCode: import_zod16.z.number().nullable().optional().describe(
     "Present for `webhook.*` events only \u2014 HTTP status your endpoint returned, or `null` if the request never connected."
   ),
-  attempts: import_zod15.z.number().optional().describe(
+  attempts: import_zod16.z.number().optional().describe(
     "Present for `webhook.*` events only \u2014 how many delivery attempts have been made so far."
   )
 });
 
 // src/verify.ts
-var import_zod16 = require("zod");
-var SplitRecipientRoleSchema = import_zod16.z.enum(["merchant", "klap_fee", "distributor_incentive"]).describe(
-  "`merchant`: the payout recipient. `klap_fee`: the platform fee. `distributor_incentive`: the (usually small) reward paid to whoever triggered the on-chain settlement \u2014 may be Klap or a third party, see `address`."
+var import_zod17 = require("zod");
+var SplitRecipientRoleSchema = import_zod17.z.enum(["merchant", "klap_fee", "distributor_incentive"]).describe(
+  "`merchant`: the payout recipient. `klap_fee`: the platform fee. `distributor_incentive`: the (usually small) reward paid to whoever triggered the on-chain settlement \u2014 may be Klappay or a third party, see `address`."
 );
-var VerifySplitEntrySchema = import_zod16.z.object({
+var VerifySplitEntrySchema = import_zod17.z.object({
   role: SplitRecipientRoleSchema,
-  address: import_zod16.z.string().nullable().describe(
+  address: import_zod17.z.string().nullable().describe(
     "On-chain recipient address for this share. For `distributor_incentive`, this is `null` until settlement actually happens \u2014 there is no fixed address, it goes to whoever calls the settlement transaction."
   ),
-  percentAllocation: import_zod16.z.number().describe("This entry's share of `amountReceived`, as a percentage (e.g. `99` = 99%)."),
-  amountUSD: import_zod16.z.number()
+  percentAllocation: import_zod17.z.number().describe("This entry's share of `amountReceived`, as a percentage (e.g. `99` = 99%)."),
+  amountUSD: import_zod17.z.number()
 });
-var VerifyPaymentSchema = import_zod16.z.object({
+var VerifyPaymentSchema = import_zod17.z.object({
   token: TokenSchema,
   network: NetworkSchema,
-  amountReceived: import_zod16.z.number().describe("Cumulative amount received on this specific `(token, network)` pair."),
-  txHash: import_zod16.z.string().describe("The on-chain transaction hash of the most recent transfer on this pair."),
-  explorerTxUrl: import_zod16.z.string().describe("Direct link to `txHash` on the relevant block explorer."),
-  split: import_zod16.z.array(VerifySplitEntrySchema).describe(
-    "The exact breakdown of where this pair's payment went \u2014 merchant's share, Klap's fee, and (once settled) the settlement incentive."
+  amountReceived: import_zod17.z.number().describe("Cumulative amount received on this specific `(token, network)` pair."),
+  txHash: import_zod17.z.string().describe("The on-chain transaction hash of the most recent transfer on this pair."),
+  explorerTxUrl: import_zod17.z.string().describe("Direct link to `txHash` on the relevant block explorer."),
+  split: import_zod17.z.array(VerifySplitEntrySchema).describe(
+    "The exact breakdown of where this pair's payment went \u2014 merchant's share, Klappay's fee, and (once settled) the settlement incentive."
   ),
-  splitTxHash: import_zod16.z.string().nullable().describe(
+  splitTxHash: import_zod17.z.string().nullable().describe(
     "Transaction hash of the payout to the merchant for this pair, once settlement has happened. `null` until then."
   ),
-  settledAt: import_zod16.z.string().datetime().nullable().describe(
+  settledAt: import_zod17.z.string().datetime().nullable().describe(
     "When settlement completed for this pair \u2014 the merchant's wallet actually has the funds. `null` until then."
   )
 });
-var VerifyChargeSchema = import_zod16.z.object({
-  id: import_zod16.z.string(),
-  amount: import_zod16.z.number().nullable().describe("The amount originally requested. `null` if the charge accepted any amount."),
-  amountReceived: import_zod16.z.number().describe(
+var VerifyChargeSchema = import_zod17.z.object({
+  id: import_zod17.z.string(),
+  amount: import_zod17.z.number().nullable().describe("The amount originally requested. `null` if the charge accepted any amount."),
+  amountReceived: import_zod17.z.number().describe(
     "The actual cumulative amount received across every contributing pair \u2014 can exceed `amount` on an overpayment."
   ),
-  confirmedAt: import_zod16.z.string().datetime().nullable().describe(
+  confirmedAt: import_zod17.z.string().datetime().nullable().describe(
     "When the charge reached `confirmed`. `null` for a `mode: continuous` charge \u2014 it never reaches a single confirmed moment (`status` stays `pending` for its whole life, see `Charge.mode`); use each entry in `payments[].settledAt` for per-contribution timing instead."
   ),
-  splitAddress: import_zod16.z.string().describe(
+  splitAddress: import_zod17.z.string().describe(
     "The on-chain address the payment was sent to \u2014 identical across every accepted network."
   ),
-  payments: import_zod16.z.array(VerifyPaymentSchema).describe(
+  payments: import_zod17.z.array(VerifyPaymentSchema).describe(
     "One entry per `(token, network)` pair that actually contributed funds \u2014 a charge accepting several pairs can be confirmed by a combination of them, each proven and settled independently."
   )
 });
 
 // src/health.ts
-var import_zod17 = require("zod");
-var HealthSchema = import_zod17.z.object({
-  status: import_zod17.z.enum(["ok", "error"]).describe(
+var import_zod18 = require("zod");
+var HealthSchema = import_zod18.z.object({
+  status: import_zod18.z.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: import_zod17.z.string(),
-  timestamp: import_zod17.z.string().datetime(),
-  db: import_zod17.z.enum(["ok", "error"]).describe("Result of a real database connectivity check, not just a process-alive check."),
-  pendingWebhooks: import_zod17.z.number().describe("Count of webhook deliveries still awaiting a successful attempt."),
-  oldestPendingChargeAgeSeconds: import_zod17.z.number().nullable().describe("Age of the oldest still-unpaid charge, in seconds. `null` if there are none."),
-  lastMoralisEventAgeSeconds: import_zod17.z.number().nullable().describe(
+  version: import_zod18.z.string(),
+  timestamp: import_zod18.z.string().datetime(),
+  db: import_zod18.z.enum(["ok", "error"]).describe("Result of a real database connectivity check, not just a process-alive check."),
+  pendingWebhooks: import_zod18.z.number().describe("Count of webhook deliveries still awaiting a successful attempt."),
+  oldestPendingChargeAgeSeconds: import_zod18.z.number().nullable().describe("Age of the oldest still-unpaid charge, in seconds. `null` if there are none."),
+  lastMoralisEventAgeSeconds: import_zod18.z.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
-var import_zod18 = require("zod");
-var SandboxTriggerSchema = import_zod18.z.object({
+var import_zod19 = require("zod");
+var SandboxTriggerSchema = import_zod19.z.object({
   event: TriggerableChargeEventSchema,
-  amount: import_zod18.z.number().positive().max(CHARGE_AMOUNT_MAX).optional().describe(
+  amount: import_zod19.z.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."
   )
 });
-var SandboxEventTriggerSchema = import_zod18.z.object({
+var SandboxEventTriggerSchema = import_zod19.z.object({
   event: NonChargeTriggerableEventSchema.describe(
     "Any account, security, or webhook-delivery event \u2014 simulates it with synthetic data against your own webhooks, no real state change or precondition required (unlike `POST /v1/sandbox/charges/{id}/trigger`, which acts on a real charge)."
   )
 });
 
 // src/capabilities.ts
-var import_zod19 = require("zod");
-var CapabilitiesSchema = import_zod19.z.object({
-  acceptedPayments: import_zod19.z.array(AcceptedPaymentSchema).describe(
+var import_zod20 = require("zod");
+var CapabilitiesSchema = import_zod20.z.object({
+  acceptedPayments: import_zod20.z.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."
   )
 });
@@ -830,9 +1107,15 @@ var CapabilitiesSchema = import_zod19.z.object({
   ChargeStatusEventSchema,
   ChargeStatusSchema,
   ChargeWebhookEventTypeSchema,
+  ChargesDateFieldSchema,
+  ChargesMetricFieldSchema,
+  ChargesQueryFieldSchema,
   CreateApiKeySchema,
   CreateChargeSchema,
   CreateWebhookSchema,
+  DistributionsDateFieldSchema,
+  DistributionsMetricFieldSchema,
+  DistributionsQueryFieldSchema,
   EVENT_CATEGORY_MAP,
   EVM_NETWORKS,
   EnvironmentSchema,
@@ -847,7 +1130,21 @@ var CapabilitiesSchema = import_zod19.z.object({
   ListUsersSchema,
   ListWebhookDeliveriesSchema,
   LoginSchema,
+  MAX_METRICS_QUERY_DATE_RANGE_DAYS,
+  METRICS_QUERY_DEFAULT_ROW_LIMIT,
+  METRICS_QUERY_MAX_FILTERS,
+  METRICS_QUERY_MAX_GROUP_BY,
+  METRICS_QUERY_MAX_METRICS,
+  METRICS_QUERY_MAX_ROW_LIMIT,
   MessageResponseSchema,
+  MetricsAggregationSchema,
+  MetricsDateGranularitySchema,
+  MetricsFilterOperatorSchema,
+  MetricsQueryResultRowSchema,
+  MetricsQueryResultSchema,
+  MetricsQuerySchema,
+  MetricsQueryScopeSchema,
+  MetricsResourceSchema,
   NETWORK_EXPLORERS,
   NETWORK_LABELS,
   NetworkSchema,
@@ -874,6 +1171,7 @@ var CapabilitiesSchema = import_zod19.z.object({
   SecurityWebhookEventTypeSchema,
   SettlementStatusSchema,
   SignupSchema,
+  SplitDistributionStatusSchema,
   SplitRecipientRoleSchema,
   TOKEN_ADDRESSES,
   TOKEN_DECIMALS,
@@ -881,6 +1179,9 @@ var CapabilitiesSchema = import_zod19.z.object({
   TimelineEventTypeSchema,
   TokenSchema,
   TransactionSourceSchema,
+  TransactionsDateFieldSchema,
+  TransactionsMetricFieldSchema,
+  TransactionsQueryFieldSchema,
   TriggerableChargeEventSchema,
   UpdateOrganizationSchema,
   UpdateUserRoleSchema,