@klappay/types 1.0.0 → 1.0.1

package/docs/charges.md

@@ -0,0 +1,303 @@
+# Charges
+
+The core resource. Everything here is exported from `charges.ts` unless
+noted otherwise.
+
+## Creating a charge
+
+`CreateChargeSchema` / `CreateChargeInput` — the body of `POST
+/v1/charges`:
+
+```ts
+import { CreateChargeSchema, type CreateChargeInput } from '@klappay/types'
+
+const input: CreateChargeInput = {
+  amount: 49.9,
+  acceptedPayments: [
+    { token: 'USDC', network: 'base' },
+    { token: 'USDC', network: 'optimism' },
+    { token: 'USDT', network: 'base' },
+  ],
+}
+
+CreateChargeSchema.parse(input) // throws on anything invalid
+```
+
+Fields worth knowing about:
+
+- `mode` — optional, defaults to `standard`. `standard` is the usual
+  lifecycle: accumulates transfers toward one resolution
+  (`confirmed`/`expired`/`underpaid`), settles once.
+  `continuous` never resolves — `status` stays `pending` for the
+  charge's entire life, and every credited transfer settles
+  independently instead of accumulating toward one confirmation (see
+  `charge.contribution_received`/`charge.contribution_settled` below).
+  `mode: 'continuous'` requires both `amount` and `expiresIn` to be
+  omitted — rejected with `400 validation_error` otherwise — and is
+  never inferred just from omitting those two fields, a deliberate
+  choice so a charge's entire settlement lifecycle never silently
+  flips based on which optional fields happened to be left out.
+- `amount` — optional. Omit it entirely for a "pay what you want" charge
+  that accepts any positive amount — the first credited transfer of any
+  size confirms it (`ChargeSchema.amount` reads back `null`), and
+  `isOverpaid` never applies since there's no target to exceed. Combines
+  freely with `expiresIn`: keep it for the usual checkout amount, omit
+  both `amount` and `expiresIn` together for a `standard`-mode charge
+  with neither, or for a `continuous`-mode charge (required for that
+  mode — see `mode` above). When a value *is* given, the usual bounds
+  still apply (`.positive()`, up to `CHARGE_AMOUNT_MAX`).
+- `acceptedPayments` — `AcceptedPaymentSchema[]` (`{ token: Token,
+  network: Network }`), at least one entry, up to
+  `CHARGE_ACCEPTED_PAYMENTS_MAX` (`14` — 2 tokens × 7 operational
+  networks, the actual ceiling of distinct pairs that can exist today,
+  not an arbitrary round number). The payer can pay with *any* pair in
+  this list — the on-chain address is identical no matter which one they
+  use (0xSplits addresses are chain-agnostic), so offering more than one
+  is just a matter of listing more pairs, not generating more addresses.
+  Duplicate pairs in the array are rejected with `400 validation_error`
+  at the schema level. Each pair's `network` must be in
+  `OPERATIONAL_NETWORKS`, and the exact `(token, network)` combination
+  must have a real entry in `TOKEN_ADDRESSES` for your key's
+  `environment` — an unconfigured pair anywhere in the array rejects the
+  *whole* request with `422 token_not_supported`, naming the first bad
+  index (e.g. `param: "acceptedPayments[1]"`), not silently dropped. Not
+  every token is deployed on every `network`/`environment` — `USDT` has
+  no `test` deployment on `base`, `optimism`, or `ethereum` (Tether
+  doesn't issue an official Sepolia one, unlike Circle's `USDC`);
+  `arbitrum`, `polygon`, and `avalanche` have no `test` environment at
+  all yet, for either token (0xSplits itself has no Arbitrum Sepolia
+  deployment and no Polygon or Avalanche Fuji testnet support); `bnb`
+  has no `test` environment either, and its `USDC` (unlike every other
+  `TOKEN_ADDRESSES` entry) is Binance-Peg, not Circle-issued — see
+  `packages/types/docs/tokens-and-networks.md` for the full risk note.
+  Call `GET /v1/networks` to get the live matrix for your environment
+  instead of hardcoding it client-side — it reads the exact same
+  `TOKEN_ADDRESSES` lookup this validation does, so it can never list a
+  pair charge creation would then reject.
+- `currency` — always `"USD"` today (`z.literal('USD')`), the only
+  supported value. Present as a field (not hardcoded) so a second
+  currency can be added later without a breaking shape change.
+- `expiresIn` — seconds the charge stays open, `CHARGE_EXPIRES_IN_MIN_SECONDS`
+  (60) to `CHARGE_EXPIRES_IN_MAX_SECONDS` (365 days). Omit it entirely for
+  a charge that never expires — `expiresAt` is `null` and it stays
+  `PENDING`/`PARTIALLY_PAID` indefinitely, useful for donations,
+  investments, or anything with no natural deadline. Cannot be extended
+  or shortened after creation either way.
+- `idempotencyKey` — scoped to your organization. Replaying the same key
+  **with the exact same request body** returns the *original* charge
+  unchanged instead of creating a duplicate — the safe way to retry a
+  request after a timeout. Reusing a key with a *different* body (a
+  different `amount`, say) is a `409 idempotency_key_reused` error, not a
+  silent return of the original charge — an idempotency key means "retry
+  this exact request," not "look up a charge by this string."
+- `externalRef` — an opaque id from your own system (e.g. an order id),
+  echoed back on the charge and every webhook payload. Not interpreted
+  by Klap.
+- `source` — a free-form label for what created this charge (e.g.
+  `"checkout"`, `"invoice"`) if you create charges from more than one
+  flow. Not a fixed enum on purpose — use whatever values make sense to
+  you.
+- `metadata` — arbitrary key/value data, returned as-is on every read.
+
+`CHARGE_AMOUNT_MAX` (`999_999_999_999`) is exported too — it's the real
+ceiling `amount` is validated against, matching the `Decimal(18, 6)`
+column charges are stored in. That column also caps precision at 6
+decimal places — `amount` and, on reads, `amountReceived` support up to
+6 fractional digits; anything more precise is silently truncated.
+
+## The `Charge` shape
+
+`ChargeSchema` / `Charge` is what every read (`GET /v1/charges/{id}`,
+`GET /v1/charges`, and every webhook's `data` for a `charge.*` event)
+returns. A few fields that aren't self-explanatory:
+
+- `mode` (`ChargeModeSchema`) — `standard` or `continuous`, set at
+  creation, never changes. See `docs/payments.md`'s "Continuous mode"
+  for the full lifecycle difference — the short version: a
+  `continuous` charge's `status` never leaves `pending`, and it settles
+  via `charge.contribution_received`/`charge.contribution_settled`
+  instead of the usual `charge.confirmed`/`charge.settled` pair.
+- `amount` — the requested target, or `null` if the charge accepts any
+  amount (`amount` was omitted at creation, or `mode: 'continuous'`,
+  which requires it). Never changes after creation.
+- `acceptedPayments` — echoes exactly what was configured at creation;
+  never changes afterward, regardless of which pair actually ends up
+  paid.
+- `paidWith` (`AcceptedPayment[]`) — every distinct `(token, network)`
+  pair that has actually contributed a credited transfer so far. Empty
+  until the first transfer arrives — not `null`; a charge that's never
+  been paid returns `paidWith: []`. Every accepted pair sums: a charge
+  configured with `acceptedPayments: [USDC/base, USDT/base]` can be
+  confirmed by $9 in USDC plus $1 in USDT, and `paidWith` would then hold
+  both pairs. Only a transfer on a pair that's actually in
+  `acceptedPayments` is credited — one on any other pair is still
+  recorded (visible in the charge's timeline) but never counted toward
+  `amountReceived`.
+- `amountReceived` — cumulative amount actually received on-chain so
+  far. `null` until the first transfer arrives. Can exceed `amount` —
+  see `isOverpaid` — unless `amount` itself is `null`, in which case
+  `isOverpaid` never applies (there's no target to exceed).
+- `isOverpaid` — `true` once `amountReceived` ends up greater than
+  `amount`; always `false` for a charge with no `amount` at all. Klap
+  never auto-refunds the difference — the charge address is an immutable
+  split with the payer never a recipient, and Klap never custodies funds
+  to refund from — this field is how you detect an overpayment happened
+  so you can decide what to do about it yourself.
+- `status` (`ChargeStatusSchema`) — payment progress from the payer's
+  side only: `pending` → `partially_paid`/`confirmed` → (if it never
+  fully pays) `expired`/`underpaid`. Never reflects whether the
+  *merchant* actually got paid — that's `settlementStatus`.
+- `settlementStatus` (`SettlementStatusSchema`, nullable) — a
+  **separate** step from `status`. `status: confirmed` only means the
+  payment was detected on-chain; `settlementStatus: completed` means the
+  merchant's wallet actually has the funds. `null` on the parent
+  `Charge` means no payout has been attempted yet.
+- `settledAt` (nullable) — when `settlementStatus` first reached
+  `completed`, mirroring `confirmedAt`'s role for `status`. `null` while
+  `settlementStatus` is `pending`/`failed`/`null`.
+- `environment` (`EnvironmentSchema`) — `live` or `test`, matching the
+  API key used to create it. `live` settles on Base mainnet; `test`
+  settles on Base Sepolia, a real testnet — real on-chain activity, just
+  never real money.
+- `address` — the on-chain address the payer sends funds to, identical
+  no matter which `acceptedPayments` pair they use (0xSplits addresses
+  are chain-agnostic — CREATE2 with no `chainId` in the derivation).
+  Unique per charge, predicted at creation — funds sent here go directly
+  to the merchant; Klap never custodies them.
+- `lastActivityAt` — when a transfer was last credited toward this
+  charge, or `createdAt` if none has arrived yet. Only meaningful for a
+  charge with no `expiresAt` — see `pausedAt`.
+- `pausedAt` (nullable) — only ever set for a charge with no `expiresAt`.
+  `null` means Klap is actively watching the address in real time (the
+  normal case). A timestamp means no contribution arrived for longer
+  than the inactivity window (90 days with a goal `amount`, 365 without)
+  and real-time watching was stopped — the charge itself is never
+  closed, a transfer can still land and be credited, just detected on a
+  much slower fallback poll instead of instantly. Clears automatically
+  (watching resumes) the moment that happens — see `charge.paused`/
+  `charge.reactivated` in `webhooks.md`.
+
+## Listing charges
+
+`ListChargesSchema` / `ListChargesInput` — the query params for `GET
+/v1/charges`. Supports filtering by `status`/`environment`/`isOverpaid`,
+and `since` (filters on `createdAt`, not on when the status last
+changed — matters if you're polling as a fallback for missed webhooks:
+use a window at least as wide as your longest `expiresIn`, or a
+long-lived charge that changed status outside a narrower window gets
+missed; a never-expiring charge (`expiresIn` omitted) can change status
+arbitrarily far in the future, so no fixed `since` window fully covers
+it — pair polling with `GET /v1/charges/{id}/events` for those instead
+of relying on `since` alone). `token`/`network` filters are also
+supported, but filter on
+`paidWith` — "charges actually paid in X" — not on `acceptedPayments`;
+filtering by "charges that accept X" isn't supported yet. Cursor-paginated
+via `limit` (1–100, default 20) and `cursor`.
+
+`PaginatedChargesSchema` / `PaginatedCharges` is the response shape:
+`{ data: Charge[], nextCursor: string | null, hasMore: boolean }`.
+
+### The shared cursor pagination pattern
+
+Every list endpoint in the API (`GET /v1/charges`, `GET /v1/organizations`,
+`GET /v1/organizations/{id}/api-keys`, `GET /v1/organizations/{id}/users`,
+`GET /v1/webhooks/{id}/deliveries`) shares this exact
+same `{ limit, cursor }` → `{ data, nextCursor, hasMore }` shape, built
+from one pair of generic helpers in `pagination.ts`:
+`PaginationQuerySchema` (the `{ limit, cursor }` query params) and
+`paginatedSchema(itemSchema)` (wraps any item schema into the response
+envelope) — `ListChargesSchema`/`PaginatedChargesSchema` above are just
+`PaginationQuerySchema`/`paginatedSchema(ChargeSchema)` composed with
+charge-specific filters, and `ListApiKeysSchema`/`ListUsersSchema`/
+`ListWebhookDeliveriesSchema` (and their `Paginated*Schema` response
+counterparts, in `api-keys.ts`/`users.ts`/`webhooks.ts`) follow the same
+pattern with no filters of their own.
+
+`cursor` is always opaque — never construct or parse one yourself; pass
+the previous response's `nextCursor` back verbatim to get the next page,
+and stop once `hasMore` is `false` (`nextCursor` is `null` at that
+point). `GET /v1/webhooks` and `GET /v1/charges/{id}/timeline`
+deliberately stay unpaginated — the former is hard-capped at 20 active
+webhooks per organization, the latter is scoped to one charge's own
+events, both naturally small.
+
+## Live status without polling
+
+`ChargeStatusEventSchema` / `ChargeStatusEvent` is the **minimal**
+payload streamed by the public, unauthenticated
+`GET /v1/verify/{id}/events` SSE endpoint — `id`/`status`/
+`settlementStatus`/`amount`/`amountReceived`/`paidWith`, no
+`acceptedPayments`, fee-split, or address details. The authenticated
+`GET /v1/charges/{id}/events` endpoint streams the full `Charge` instead
+(no separate schema needed — it's the same `ChargeSchema` above).
+
+## Proof of payment — `verify.ts`
+
+`VerifyChargeSchema` / `VerifyCharge` is the response shape of the
+public `GET /v1/verify/{id}` endpoint — proof-of-payment for anyone
+holding a charge id, no API key required. Serves a `standard`-mode
+charge only once `status` reaches `confirmed`; a `mode: 'continuous'`
+charge is served as soon as it has received at least one contribution,
+since it never reaches `confirmed` at all — every other case (unknown
+id, a `standard` charge still pending, test-mode) returns an identical
+generic `404`. The charge-level fields
+(`id`/`amount`/`amountReceived`/`confirmedAt`/`splitAddress` — `amount`
+is `null` the same way it is on `Charge`, for a charge that accepted
+any amount; `confirmedAt` is `null` for a `continuous` charge, which
+never has a single confirmed moment — use each `payments[]` entry's own
+`settledAt` for per-contribution timing instead) sit alongside `payments`
+(`VerifyPaymentSchema[]`) — **one
+entry per contributing `(token, network)` pair**, since a charge accepting more
+than one pair can now be confirmed by a combination of them (e.g. $9 in
+USDC plus $1 in USDT), and each pair settles independently. Each
+`VerifyPaymentSchema` entry carries its own `token`/`network`/
+`amountReceived`/`txHash`/`explorerTxUrl`, its own exact fee-split
+breakdown (`split`: `VerifySplitEntrySchema[]`, `role`/`address`/
+`percentAllocation`/`amountUSD` per recipient — `role` is `'merchant' |
+'klap_fee' | 'distributor_incentive'`, `SplitRecipientRoleSchema`), and
+its own `splitTxHash`/`settledAt` (both `null` until that specific
+pair's settlement happens — one pair can be settled while another is
+still pending).
+
+## Audit trail — `timeline.ts`
+
+`TimelineEventSchema` / `TimelineEvent` is the shape of each entry in a
+charge's timeline (`GET /v1/charges/{id}/timeline`) — a read-only,
+assembled-at-request-time view, not a separately stored table. `type`
+(`TimelineEventTypeSchema`) is one of `charge.created`/`charge.expired`/
+`transaction.detected`/`split.distributed`/`webhook.dispatched`/
+`webhook.delivered`/`webhook.failed`; which other fields are present
+depends on `type` (e.g. `txHash`/`amount`/`source`/`token`/`network`/
+`causedTransition` only apply to `transaction.detected`, and `token`/
+`network` are also present on `split.distributed`).
+`TransactionSourceSchema` / `TransactionSource` (`'moralis_webhook' |
+'reconciliation_job' | 'sandbox'`) says *how* a transfer was detected.
+`token`/`network` on a `transaction.detected` event show which
+`acceptedPayments` pair that specific transfer used — useful since a
+charge can accept more than one pair, and every transfer on an accepted
+pair is credited (`causedTransition: true` marks specifically the
+transfer that flipped the charge's `status`, not every credited one — a
+charge paid in installments across two pairs has more than one credited
+`transaction.detected` event with `causedTransition: false`). A
+`split.distributed` event's own `token`/`network` say which pair that
+particular settlement was for — a charge settled across more than one
+pair emits one `split.distributed` event per pair, each independently.
+
+## Discovering what you can accept — `capabilities.ts`
+
+`CapabilitiesSchema` / `Capabilities` (`{ acceptedPayments:
+AcceptedPayment[] }`) is the response shape of `GET /v1/networks` — the
+live `(token, network)` matrix your API key's `environment` can accept
+right now. It's read from the exact same `TOKEN_ADDRESSES` lookup
+`POST /v1/charges` validates `acceptedPayments` against, so a pair this
+endpoint lists is always safe to submit, and one it doesn't list would
+always be rejected. Use it to build a payment-method picker instead of
+hardcoding the matrix client-side — it changes as new networks/tokens
+come online, with no code change needed on your end to pick that up.
+
+## See also
+
+- [`webhooks.md`](./webhooks.md) — the full `charge.*` event vocabulary
+  and the `WebhookPayload` envelope these events arrive in.
+- [`sandbox.md`](./sandbox.md) — triggering any charge state
+  transition without a real on-chain transfer.

package/docs/distributions.md

@@ -0,0 +1,93 @@
+# Distributions
+
+Exported from `distributions.ts`. These back `GET
+/v1/distributions/pending` and `GET /v1/distributions/pending/events` —
+the keeper feed for discovering splits with a settlement payout
+currently claimable via 0xSplits' permissionless `distribute()`. Not a
+typical merchant integration surface — this is for a bot/script calling
+`distribute()` directly to earn the (small) `distributorFeePercent`
+incentive. See `docs/payments.md`'s "Discovering a pending distribution"
+for the full design.
+
+## `PendingDistributionSchema`
+
+One entry in the array `GET /v1/distributions/pending` returns:
+
+```ts
+import { PendingDistributionSchema, type PendingDistribution } from '@klappay/types'
+
+const distribution: PendingDistribution = PendingDistributionSchema.parse({
+  splitAddress: '0x727cddb8a015f76c4e8a5c566c7e911761e268fe',
+  network: 'base',
+  token: 'USDC',
+  recipients: [
+    { address: '0x6EadA5173e0ad685455cEFbe4B3df023c0A598A8', percentAllocation: 99.0991 },
+    { address: '0x44Ef725cA64CDAf48fEdb2AED2b156ad32537d41', percentAllocation: 0.9009 },
+  ],
+  distributorFeePercent: 0.1,
+  estimatedRewardAmount: 0.001,
+  availableSince: '2026-07-28T23:45:52.382Z',
+  graceEndsAt: '2026-07-28T23:50:52.382Z',
+})
+```
+
+`recipients` is always the exact array to pass to `distribute()` —
+0xSplits only stores a hash of the recipient config on-chain, so a
+caller must supply the identical array to prove it matches; there's no
+partial/reconstructed version. `estimatedRewardAmount` is an estimate
+from the amount Klap detected on-chain, not a live balance read — always
+read the split's real balance yourself before submitting a transaction,
+the same way Klap's own settlement worker does. `graceEndsAt` is when
+Klap's own worker may claim it; calling `distribute()` after that point
+is still possible but increasingly likely to lose the race.
+
+## `PendingDistributionEventSchema`
+
+The shape of each Server-Sent Event's `data:` line from `GET
+/v1/distributions/pending/events` — a discriminated union on `type`:
+
+```ts
+import { PendingDistributionEventSchema, type PendingDistributionEvent } from '@klappay/types'
+
+const event: PendingDistributionEvent = PendingDistributionEventSchema.parse(
+  JSON.parse(sseEventData),
+)
+
+if (event.type === 'distribution.available') {
+  tryClaim(event.distribution) // PendingDistribution, fully typed
+} else {
+  cancelPendingAttempt(event.splitAddress) // already claimed by someone else, or by Klap
+}
+```
+
+`distribution.claimed` fires the moment Klap's own worker claims a row
+too — before it has actually finished calling `distribute()` — not only
+once settlement completes, so a keeper stops racing an attempt already
+in flight. If that attempt then fails and is scheduled for retry,
+`distribution.available` fires again with a refreshed `graceEndsAt`.
+
+The stream sends no initial snapshot — open it *before* calling `GET
+/v1/distributions/pending`, then treat both the snapshot response and
+every event received (before or after that call resolves) as an
+idempotent add/remove against one local `Map<splitAddress, PendingDistribution>`.
+Opening the stream *after* the snapshot call instead leaves a real, if
+small, gap where a delta between the two requests is never delivered.
+
+## Authentication and environment scoping
+
+Both endpoints require the same API key used everywhere else
+(`Authorization: Bearer klap_live_...`/`klap_test_...`) — unlike `GET
+/v1/verify/{id}`, this isn't public. A `test` key only ever sees `test`
+distributions, `live` only `live` — there is no `environment` field on
+either schema above, since the connection is already scoped by whichever
+key opened it.
+
+## See also
+
+- `docs/payments.md`'s "Discovering a pending distribution" — the full
+  design writeup: why authentication is required, why it's still not a
+  new on-chain capability, data minimization, and the three points that
+  publish `distribution.claimed`.
+- [`charges.md`](./charges.md) — `VerifyCharge`'s `split` array is the
+  same kind of recipient/percentage data as `PendingDistribution.recipients`,
+  just scoped to one charge instead of every currently-open grace period.

package/docs/errors-and-health.md

@@ -0,0 +1,52 @@
+# Errors and health
+
+Exported from `errors.ts` and `health.ts`.
+
+## Error responses — `ErrorPayloadSchema`
+
+Every non-2xx response from the API uses this shape:
+
+```ts
+import { ErrorPayloadSchema, type ErrorPayload } from '@klappay/types'
+
+const payload: ErrorPayload = {
+  error: {
+    code: 'validation_error',
+    message: 'amount must be positive',
+    param: 'amount',
+  },
+}
+```
+
+- `code` — a stable, machine-readable identifier (e.g.
+  `validation_error`, `invalid_credentials`, `invalid_trigger_state`).
+  Safe to branch on in code. There's no single enum of every possible
+  value here (it's a plain `string`, since the set is per-endpoint) —
+  the live OpenAPI/Scalar reference is the authoritative source for
+  which codes a specific endpoint can return: every response in its
+  `responses` block names the actual code(s) in parentheses at the end
+  of the description.
+- `message` — human-readable, safe to log or show a developer. Not meant
+  for end users verbatim.
+- `param` — which request field the error refers to, when applicable
+  (omitted for errors that aren't about a specific field).
+
+If you want a typed exception thrown automatically instead of parsing
+this shape yourself, an official SDK does that — available at
+[github.com/klappay](https://github.com/klappay); see the live API
+reference for details on the full list of error classes.
+
+## `GET /v1/health` — `HealthSchema`
+
+`HealthSchema`/`Health` is the response shape of the public health-check
+endpoint. `status`/the HTTP status code both mirror `db`: `error` (and
+`503`) when the database connectivity check fails, so a plain
+status-code-only uptime check still catches a DB outage without needing
+to inspect the JSON body.
+
+The other fields are operational signals, not just "is the process
+alive": `pendingWebhooks` (deliveries still awaiting a successful
+attempt), `oldestPendingChargeAgeSeconds` (age of the oldest still-unpaid
+charge, `null` if none), and `lastMoralisEventAgeSeconds` (seconds since
+the last on-chain payment notification was received — a cheap proxy for
+"is payment detection still working", `null` if none have ever arrived).

package/docs/getting-started.md

@@ -0,0 +1,96 @@
+# Getting started
+
+## Install
+
+```bash
+npm install @klappay/types zod
+```
+
+`zod` is a peer expectation, not bundled — every schema exported here
+*is* a `zod` schema, so if you already depend on any of them directly you
+already have it.
+
+## What this package actually is
+
+Two things, exported side by side for every resource:
+
+- A **Zod schema** (`ChargeSchema`, `CreateChargeSchema`,
+  `WebhookPayloadSchema`, ...) — use it to validate data at runtime, not
+  just to satisfy the type checker.
+- An **inferred TypeScript type** for the same shape (`Charge`,
+  `CreateChargeInput`, ...), exported alongside its schema.
+
+Both come from the same source — the schema is the source of truth, the
+type is `z.infer<typeof Schema>` on top of it. There is no separate
+hand-written type anywhere in this package that could drift from its
+schema.
+
+This package has **no HTTP client, no fetch, no networking of any
+kind** — it only describes shapes. If you want a client that actually
+calls the API for you (with typed errors, retries, real-time polling
+helpers), an official SDK is built on top of this package — available
+at [github.com/klappay](https://github.com/klappay); see the live API
+reference for details. Use `@klappay/types` directly when
+you're calling the API yourself (a different language's types, a
+codegen step, validating a
+webhook payload in a framework the SDK doesn't fit) and just want the
+contracts.
+
+## Typing an API response
+
+```ts
+import type { Charge } from '@klappay/types'
+
+async function getCharge(id: string): Promise<Charge> {
+  const res = await fetch(`${API_BASE_URL}/v1/charges/${id}`, {
+    headers: { Authorization: `Bearer ${process.env.KLAP_API_KEY}` },
+  })
+  return res.json()
+}
+```
+
+## Validating a response or webhook payload at runtime
+
+A type only helps at compile time — it says nothing about what actually
+came back over the wire. Parse anything you don't fully control through
+its schema:
+
+```ts
+import { WebhookPayloadSchema } from '@klappay/types'
+
+app.post('/webhooks/klap', (req, res) => {
+  const payload = WebhookPayloadSchema.parse(req.body)
+  // payload.data is `unknown` here — this schema only validates the
+  // envelope (id/event/createdAt). See webhooks.md for how to narrow
+  // `data` per event with TypedWebhookPayload.
+  res.sendStatus(200)
+})
+```
+
+This package only validates *shape* — it never verifies the
+`X-Klap-Signature` HMAC header on a webhook request. Do that yourself
+(or use an official SDK's `constructEvent()`, which does both at once —
+available at [github.com/klappay](https://github.com/klappay), see the
+live API reference for details) before trusting the payload
+came from Klap.
+
+## Finding the type you need
+
+Every exported schema/type lives in exactly one topic file below — if
+you're not sure where something is, it's one of these:
+
+| Doc | Covers |
+|---|---|
+| [`charges.md`](./charges.md) | `Charge`, `CreateChargeInput`, `ListChargesInput`, `PaginatedCharges`, `ChargeStatusEvent`, plus the read-only `VerifyCharge`/`TimelineEvent` views. Also covers the shared `PaginationQuerySchema`/`paginatedSchema()` primitives every list endpoint (charges, api keys, users, webhook deliveries) is built from |
+| [`webhooks.md`](./webhooks.md) | Every `WebhookEventType`, category grouping, `CreateWebhookInput`, `Webhook`, `WebhookPayload`, `TypedWebhookPayload`, `WebhookDelivery` |
+| [`sandbox.md`](./sandbox.md) | `SandboxTriggerInput`, `SandboxEventTriggerInput`, `TriggerableChargeEvent` |
+| [`auth-and-accounts.md`](./auth-and-accounts.md) | `SignupInput`/`LoginInput`/`AuthResponse`, `ApiKey`/`CreateApiKeyInput`, `User`/`UserRole`, `Organization` |
+| [`tokens-and-networks.md`](./tokens-and-networks.md) | `Token`, `Network`, `TOKEN_ADDRESSES`, `EVM_NETWORKS`, and every other chain/token constant |
+| [`errors-and-health.md`](./errors-and-health.md) | `ErrorPayload` (every non-2xx response shape) and `Health` |
+
+## Where to go next
+
+Read this package's own `README.md` first if you haven't — it covers
+install and the two usage patterns (typing vs. runtime validation) at a
+glance. This `docs/` folder is for finding a *specific* schema quickly
+once you already know roughly what you're looking for.

package/docs/sandbox.md

@@ -0,0 +1,80 @@
+# Sandbox
+
+Exported from `sandbox.ts`. These are the request bodies for
+`POST /v1/sandbox/*` — simulating events without any real on-chain
+activity, only usable with a `test` API key.
+
+## Triggering a charge event — `SandboxTriggerSchema`
+
+The body of `POST /v1/sandbox/charges/{id}/trigger`:
+
+```ts
+import { SandboxTriggerSchema, type TriggerableChargeEvent } from '@klappay/types'
+
+SandboxTriggerSchema.parse({ event: 'charge.confirmed' })
+SandboxTriggerSchema.parse({ event: 'charge.partially_paid', amount: 20 })
+```
+
+`event` is a `TriggerableChargeEvent` (exported from `webhook-events.ts`,
+re-used here rather than re-declared) — every charge event *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), and
+`charge.contribution_received`/`charge.contribution_settled`
+(exclusive to `mode: 'continuous'` charges, which this endpoint doesn't
+support simulating):
+
+```ts
+export const TriggerableChargeEventSchema = ChargeWebhookEventTypeSchema.exclude([
+  'charge.created',
+  'charge.paused',
+  'charge.reactivated',
+  'charge.contribution_received',
+  'charge.contribution_settled',
+])
+```
+
+Derived with `.exclude()` from the same enum `webhook-events.ts` already
+defines, not a second hand-maintained list — a future charge event added
+there is automatically excluded-or-included correctly here with no
+second place to remember to update.
+
+`amount` applies to two events: `charge.partially_paid` (the amount to
+simulate as received so far — must be less than the charge's full
+amount, defaults to half of it if omitted) and `charge.overpaid` (the
+amount received — must be greater than the charge's full amount,
+defaults to 1.5x it if omitted). Ignored for every other event. Every
+triggerable event has
+a real precondition on the charge's current state (e.g.
+`charge.underpaid` requires the charge to already be
+`partially_paid`) — triggering one out of order is a `422
+invalid_trigger_state` response, not a silent no-op. This schema only
+validates the request shape; the state-machine precondition is enforced
+server-side.
+
+## Triggering a non-charge event — `SandboxEventTriggerSchema`
+
+The body of `POST /v1/sandbox/events/trigger` — simulates any account,
+security, or webhook-delivery event with synthetic data against your own
+registered webhooks, no real charge or precondition involved (unlike the
+charge trigger above, which acts on a specific existing charge):
+
+```ts
+import { SandboxEventTriggerSchema } from '@klappay/types'
+
+SandboxEventTriggerSchema.parse({ event: 'payout_address.changed' })
+```
+
+`event` is a `NonChargeTriggerableEvent` — every `account`/`webhooks`/
+`security` category event (see [`webhooks.md`](./webhooks.md)'s category
+table), also exported from `webhook-events.ts`.
+
+## See also
+
+- [`webhooks.md`](./webhooks.md) — the full event vocabulary these two
+  schemas draw from.
+- An official SDK ([github.com/klappay](https://github.com/klappay))
+  offers ergonomic, named wrappers (`sandbox.confirm()`,
+  `sandbox.expire()`, ...) built on top of these two raw request shapes,
+  plus `charge.waitFor(event)` to await the result — see the live API
+  reference for details.