@klappay/types 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @klappay/types
 
+## 1.0.2
+
+### Patch Changes
+
+- 00dd00a: No code changes — updates package metadata and docs links so npm shows
+  them correctly:
+
+  - Adds `keywords` for npm search discoverability.
+  - `README.md`'s documentation table now links to
+    [api.klappay.com/docs](https://api.klappay.com/docs) (a dedicated
+    public docs site) instead of relative `./docs/*.md` paths, which never
+    rendered as navigable links on npmjs.com.
+  - `docs/` is no longer bundled in the published tarball — the public
+    docs site above is now the canonical place to read it.
+
 ## 1.0.1
 
 ### Patch Changes

package/README.md

@@ -54,16 +54,21 @@ API itself (open the API's base URL in a browser once you have access).
 
 ## Documentation
 
+Full docs (with search and navigation) are published at
+[api.klappay.com/docs](https://api.klappay.com/docs) — generated from
+this same package's `docs/` source, so they never drift from what's
+actually exported.
+
 | Doc | Covers |
 |---|---|
-| [`docs/getting-started.md`](./docs/getting-started.md) | Install, what's in this package, typing vs. runtime validation |
-| [`docs/charges.md`](./docs/charges.md) | `Charge`, `CreateChargeInput`, `AcceptedPayment`, `Capabilities` (`GET /v1/networks`), listing/pagination, `VerifyCharge`, `TimelineEvent` |
-| [`docs/webhooks.md`](./docs/webhooks.md) | Every `WebhookEventType`, categories, `Webhook`, `WebhookPayload`, `TypedWebhookPayload` |
-| [`docs/sandbox.md`](./docs/sandbox.md) | `SandboxTriggerInput`, `SandboxEventTriggerInput`, `TriggerableChargeEvent` |
-| [`docs/distributions.md`](./docs/distributions.md) | `PendingDistribution`, `PendingDistributionEvent` — the 0xSplits keeper feed |
-| [`docs/auth-and-accounts.md`](./docs/auth-and-accounts.md) | Signup/login, email verification, password reset, `ApiKey`, `User`/`UserRole`, `Organization` |
-| [`docs/tokens-and-networks.md`](./docs/tokens-and-networks.md) | `Token`, `Network`, and every chain/token constant |
-| [`docs/errors-and-health.md`](./docs/errors-and-health.md) | `ErrorPayload` (every non-2xx response shape), `Health` |
+| [Getting started](https://api.klappay.com/docs/getting-started) | Install, what's in this package, typing vs. runtime validation |
+| [Charges](https://api.klappay.com/docs/charges) | `Charge`, `CreateChargeInput`, `AcceptedPayment`, `Capabilities` (`GET /v1/networks`), listing/pagination, `VerifyCharge`, `TimelineEvent` |
+| [Webhooks](https://api.klappay.com/docs/webhooks) | Every `WebhookEventType`, categories, `Webhook`, `WebhookPayload`, `TypedWebhookPayload` |
+| [Sandbox](https://api.klappay.com/docs/sandbox) | `SandboxTriggerInput`, `SandboxEventTriggerInput`, `TriggerableChargeEvent` |
+| [Distributions](https://api.klappay.com/docs/distributions) | `PendingDistribution`, `PendingDistributionEvent` — the 0xSplits keeper feed |
+| [Auth & accounts](https://api.klappay.com/docs/auth-and-accounts) | Signup/login, email verification, password reset, `ApiKey`, `User`/`UserRole`, `Organization` |
+| [Tokens & networks](https://api.klappay.com/docs/tokens-and-networks) | `Token`, `Network`, and every chain/token constant |
+| [Errors & health](https://api.klappay.com/docs/errors-and-health) | `ErrorPayload` (every non-2xx response shape), `Health` |
 
 ## Usage
 

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "@klappay/types",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "license": "MIT",
   "description": "TypeScript types and Zod schemas for the Klap Core API — the request/response contracts, published separately so integrators get them without needing access to the (closed-source) API implementation.",
+  "keywords": [
+    "klap",
+    "payments",
+    "crypto-payments",
+    "web3",
+    "blockchain",
+    "non-custodial",
+    "0xsplits",
+    "usdc",
+    "usdt",
+    "typescript",
+    "zod",
+    "types"
+  ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -14,7 +28,6 @@
   },
   "files": [
     "dist",
-    "docs",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/docs/auth-and-accounts.md

@@ -1,188 +0,0 @@
-# Auth and accounts
-
-Everything here needs a **session token** (a JWT, sent as
-`Authorization: Bearer <token>`), not an API key — a separate credential
-from the one used on `/v1/charges`/`/v1/webhooks`/`/v1/sandbox`. See
-[`tokens-and-networks.md`](./tokens-and-networks.md) for `Token`/
-`Network`, which are unrelated to this auth split despite the similar
-name.
-
-**A session token identifies only the signed-in user — never a single
-organization or role.** A user can belong to any number of
-organizations, each with its own role, so nothing below assumes "the"
-organization; every organization-scoped endpoint takes its id as an
-explicit `{id}` path segment, and `GET /v1/organizations` is how you
-discover which id(s) you have.
-
-## Signup and login — `auth.ts`
-
-`SignupSchema`/`SignupInput` and `LoginSchema`/`LoginInput` — both
-`{ email, password }`, bodies of `POST /v1/auth/signup` and
-`POST /v1/auth/login`. `email` is trimmed, lowercased, and
-NFC-normalized before validation (internally, via a shared
-`NormalizedEmailSchema` not exported on its own) — `"User@x.com"` and
-`"user@x.com"` are treated as the same account, matching the API's own
-case-insensitive uniqueness check. `signup` also creates a brand-new
-organization, with the new user as its `owner`; `login` doesn't select
-an organization at all.
-
-`AuthResponseSchema`/`AuthResponse` is what `signup`, `login`, and
-`POST /v1/invitations/accept` (below) all return: `{ token, user }`.
-`token` is a session JWT valid 7 days — this authenticates a
-human/dashboard session, not payment operations. `user` is pure identity
-— `UserSchema` (see below) minus `createdAt` **and** `role`, since role
-only means something once you've picked which organization. Call
-`GET /v1/organizations` right after to find out which organization(s)
-you belong to and your role in each, then create an API key
-(`POST /v1/organizations/{id}/api-keys`, below) before you can create
-charges.
-
-## Email verification and password reset — `auth.ts`
-
-`VerifyEmailSchema`/`VerifyEmailInput` — `{ token }`, body of
-`POST /v1/auth/verify-email`. The token comes from the email `POST
-/v1/auth/signup` sends in the background (or a fresh one from
-`POST /v1/auth/resend-verification`, session-authenticated, no body) —
-single-use, expires 24h after issuance. Two things are gated on it:
-creating a `live` API key (`POST /v1/organizations/{id}/api-keys`,
-below) and changing `payoutAddress`
-(`PATCH /v1/organizations/{id}`, below) both require a verified email,
-returning `403 email_not_verified` otherwise — `test` API keys have no
-such requirement. `User.emailVerifiedAt` (see `UserSchema` below)
-reflects the current state.
-
-`ForgotPasswordSchema`/`ForgotPasswordInput` — `{ email }`, body of
-`POST /v1/auth/forgot-password`. Always get the same generic
-`MessageResponse` back regardless of whether the email matches an
-account — this is the one endpoint in the API that actually closes
-account enumeration, rather than accepting it as a tradeoff (unlike
-signup's `422 email_taken`).
-
-`ResetPasswordSchema`/`ResetPasswordInput` — `{ token, newPassword }`,
-body of `POST /v1/auth/reset-password`. The token expires 1 hour after a
-`forgot-password` call. A successful reset invalidates every other
-outstanding reset token for that account, **and every session token
-issued before the reset** — the next request with an old session gets
-`401 invalid_session`, even though the JWT itself hasn't reached its
-7-day expiry.
-
-`MessageResponseSchema`/`MessageResponse` — `{ message }`, the shared
-response shape for all four of the endpoints above (chosen over an
-empty `204` since a human-readable confirmation is more useful to show
-directly in a UI for these specifically).
-
-## Organizations — `organization.ts`
-
-`ListOrganizationsSchema`/`PaginatedOrganizationsSchema` are the
-query/response shapes for `GET /v1/organizations` — every organization
-the caller belongs to, each entry an `OrganizationWithRoleSchema` (see
-below). Same shared `{ limit, cursor }` → `{ data, nextCursor, hasMore }`
-cursor pagination every list endpoint uses, see
-[`charges.md`](./charges.md#the-shared-cursor-pagination-pattern). This
-is the starting point for every other endpoint on this page — there's no
-other way to learn which organization id(s) a session token can act on.
-
-`UpdateOrganizationSchema`/`UpdateOrganizationInput` — `{ name?,
-payoutAddress? }`, body of `PATCH /v1/organizations/{id}`.
-`payoutAddress` is an EVM address, regex-validated
-(`/^0x[a-fA-F0-9]{40}$/`); required before that organization can create
-any charge, and requires a verified email when actually changing
-(`403 email_not_verified` otherwise — see the email verification section
-above). Changing it only affects charges created **after** the change —
-an already-created charge's payout split is frozen at creation time and
-is never retroactively affected. `name` has no such gate.
-
-`OrganizationSchema`/`Organization` is the read shape returned by
-`GET`/`PATCH /v1/organizations/{id}` — notably `currentFeePercent`, the
-organization's platform fee based on trailing monthly volume, which is
-likewise frozen onto each charge at creation (so it can change between
-charges without affecting ones already made).
-`OrganizationWithRoleSchema`/`OrganizationWithRole` extends it with
-`role` — only present on the `GET /v1/organizations` list response,
-where "your role in *this* one" is meaningful; the single-organization
-`GET`/`PATCH` endpoints don't repeat it.
-
-## Members and roles — `users.ts`
-
-`UserRoleSchema`/`UserRole` — `'owner' | 'admin' | 'member'`. An
-organization must always keep at least one `owner`. An `admin` can
-manage `member`s but not other `admin`s; you can only manage a user with
-a strictly lower role than your own, unless you're an `owner` — this
-applies identically to changing a role and to inviting one (see
-"Invitations" below).
-
-`UpdateUserRoleSchema`/`UpdateUserRoleInput` — `{ role }`, body of
-`PATCH /v1/organizations/{id}/users/{userId}`, for changing an existing
-member's role *within that organization*. `UserSchema`/`User` is the
-read shape returned there and by `GET /v1/organizations/{id}/users` —
-`role` is that member's role in the organization the request was scoped
-to (a `User` has no single global role, since the same person can be a
-`member` of one organization and an `owner` of another).
-`emailVerifiedAt` (nullable timestamp) reflects whether the address was
-confirmed via `POST /v1/auth/verify-email` — it gates two things
-elsewhere in the API (creating a `live` API key, changing
-`payoutAddress` — see above) but doesn't restrict a `member` based on
-role by itself; it's there for your own integration's policy to read
-too.
-
-`ListUsersSchema`/`PaginatedUsersSchema` are the query/response shapes
-for `GET /v1/organizations/{id}/users` — same shared cursor pagination
-as `GET /v1/organizations` above.
-
-## Invitations — `invitations.ts`
-
-`InviteUserSchema`/`InviteUserInput` — `{ email, role }` (`role` defaults
-to `member`), body of `POST /v1/organizations/{id}/invitations`. Subject
-to the identical role-hierarchy rule as `UpdateUserRoleSchema` above —
-an `admin` inviter can't invite an `admin` or `owner`. Sends a
-single-use, plain-text email code (via Resend, no clickable link — same
-pattern as email verification/password reset), valid 7 days.
-`InvitationSchema`/`Invitation` is the response shape — `{ id,
-organizationId, email, role, invitedByUserId, expiresAt, createdAt }`,
-no token (the raw code only ever reaches the invitee, via email). Keep
-the returned `id` if you need to
-`DELETE /v1/organizations/{id}/invitations/{invitationId}` later.
-
-`AcceptInvitationSchema`/`AcceptInvitationInput` — `{ token,
-password? }`, body of `POST /v1/invitations/accept`. **No session
-token required** — the code itself is the proof, same model as
-`VerifyEmailSchema` above. If the invited email already has a Klap
-account, `password` is ignored and the membership is just added to it
-(any other organizations that account already belongs to are
-untouched); if it doesn't, `password` is required (same `8-128`-char
-rule as `SignupSchema`) and a new account is created along with the
-membership, in one step. Returns an `AuthResponse` either way.
-
-## API keys — `api-keys.ts`
-
-`CreateApiKeySchema`/`CreateApiKeyInput` — `{ name, environment }`, the
-body of `POST /v1/organizations/{id}/api-keys`. `environment`
-(`live`/`test`, see [`charges.md`](./charges.md)'s `EnvironmentSchema`)
-decides everything about the resulting key: `live` keys move real funds
-on Base mainnet; `test` keys settle the same charge lifecycle on Base
-Sepolia (a real testnet — real on-chain activity, never real money) and
-additionally unlock `POST /v1/sandbox/*` (see [`sandbox.md`](./sandbox.md))
-for simulating events with zero on-chain activity at all. Creating a
-`live` key requires a verified email (`403 email_not_verified`
-otherwise) — `test` keys have no such requirement.
-
-`ApiKeySchema`/`ApiKey` is the response shape. `key` (the full secret,
-`klap_live_.../klap_test_...`) is present **only** in the response to
-creation — every later read/list returns `hint` instead (a
-truncated, always-safe-to-display form like `klap_live_...ab12`). Store
-`key` immediately; it cannot be retrieved again.
-
-`ListApiKeysSchema`/`PaginatedApiKeysSchema` are the query/response
-shapes for `GET /v1/organizations/{id}/api-keys` — same shared
-`{ limit, cursor }` → `{ data, nextCursor, hasMore }` cursor pagination
-every list endpoint uses, see
-[`charges.md`](./charges.md#the-shared-cursor-pagination-pattern).
-
-## See also
-
-- [`charges.md`](./charges.md) — `EnvironmentSchema` (`live`/`test`),
-  referenced by both API keys and charges.
-- [`webhooks.md`](./webhooks.md) — the `account`/`security` category
-  events these resources emit (`payout_address.changed`,
-  `api_key.created`, `member.role_changed`, `member.invited`,
-  `auth.login`, ...).

package/docs/charges.md

@@ -1,303 +0,0 @@
-# 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

@@ -1,93 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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

@@ -1,80 +0,0 @@
-# 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.

package/docs/tokens-and-networks.md

@@ -1,108 +0,0 @@
-# Tokens and networks
-
-Exported from `tokens.ts` and `networks.ts`.
-
-## `Token`
-
-`TokenSchema`/`Token` — currently `'USDC' | 'USDT'`. This is today's
-supported list, not a permanent ceiling — more tokens are expected to be
-added over time as new networks and assets come online. Support depends
-on both `network` and `environment`, and not every combination is
-symmetric: `live` has both `USDC` and `USDT` on every operational
-network *except* `bnb` (see the `USDC`/`bnb` note below), and `test`
-coverage varies per network for different reasons — `base`, `optimism`,
-and `ethereum` each have a `test` environment with `USDC` only (none has
-an official Sepolia USDT, since Tether doesn't issue one), while
-`arbitrum`, `polygon`, and `avalanche` have no `test` environment at all
-yet, for any token (0xSplits hasn't deployed its split factory on
-Arbitrum Sepolia, and has no Polygon or Avalanche Fuji testnet support at
-all — a network-level gap, not a token-level one), and `bnb` has none
-either (no BNB testnet support in 0xSplits). An unconfigured combination
-is rejected with `422 token_not_supported`, not silently accepted. See
-`TOKEN_ADDRESSES` below for the exact current matrix rather than
-assuming full coverage.
-
-`TOKEN_DECIMALS` (`6`) — both tokens Klap supports use 6 decimals on
-every network they're deployed on. A fact about these specific tokens,
-not a per-network setting, so it's one shared constant rather than
-something you'd look up per-`Network`.
-
-`TOKEN_ADDRESSES: Record<Token, Partial<Record<Network, Partial<Record<Environment, `0x${string}`>>>>>`
-— the real on-chain contract address for each token/network/environment
-combination that's actually deployed. Three levels deep because `test`
-and `live` are genuinely different chains for at least one network today
-(`base` → Base mainnet for `live`, Base Sepolia for `test` — see
-[`charges.md`](./charges.md) for `Environment`), so the same token can
-have a different contract address per environment, not just per network.
-`Partial` at every level matters: index it as
-`TOKEN_ADDRESSES[token][network]?.[environment]` and check for
-`undefined`, since a combination that doesn't exist (e.g. no official
-Base Sepolia USDT, or any `arbitrum` `test` entry at all) has no entry
-rather than a placeholder value. One naming quirk on `arbitrum`: the
-`USDT` contract there is real and Tether-backed, but reports its
-on-chain name/`symbol()` as `"USD₮0"` (Tether's "USDT0" cross-chain
-standard, migrated in place in Jan 2025) — this codebase always verifies
-by address, never by `symbol()`, so it doesn't matter functionally, but
-don't be surprised seeing "USD₮0" instead of "USDT" on a block explorer.
-
-**`USDC` on `bnb` is Binance-Peg USDC, not a Circle deployment.** Circle
-issues no native USDC on BNB Chain at all — it's absent from both
-Circle's own address list and its CCTP-supported chain list. The address
-in `TOKEN_ADDRESSES` is a Binance-custodied, 1:1-pegged BEP-20 token
-instead (Binance locks real USDC/equivalent collateral in its own wallet
-and mints this against it) — real liquidity and adoption (it's what
-"USDC" means on BNB Chain in practice), but a centralized-custody trust
-model, not the direct-issuer verification every other `USDC`/`USDT`
-entry in this table has. See `docs/payments.md`'s note on it before
-building anything that treats every `TOKEN_ADDRESSES` entry as
-equally trusted. `USDT` on `bnb` is Tether's own official BEP-20
-issuance — same trust model as everywhere else.
-
-## `Network`
-
-`NetworkSchema`/`Network` — `'base' | 'optimism' | 'polygon' |
-'ethereum' | 'arbitrum' | 'avalanche' | 'bnb'`. This is the full type —
-every one of these values is a valid `Network` for reading/filtering
-(e.g. `ListChargesInput.network`). `solana` used to be part of this type
-but was removed entirely (not just left non-operational) once there was
-no near-term plan to wire it — see `docs/security.md`'s finding #13.
-
-`OPERATIONAL_NETWORKS` (`readonly ['base', 'arbitrum', 'optimism',
-'polygon', 'ethereum', 'avalanche', 'bnb']`) and its matching
-`OperationalNetwork` type — the narrower list of networks actually
-wired end-to-end today, which right now is exactly every `Network`
-value. `CreateChargeSchema.network` enforces this at creation: `POST
-/v1/charges` with any `network` outside this list is rejected with
-`400 validation_error` naming the network and what's currently
-supported, not silently accepted and left to strand funds. Not a
-permanent ceiling and not guaranteed to stay in lockstep with
-`Network` — the day a genuinely new chain is added to the type before
-its wiring lands, this list will again be the narrower one. Being in
-`OPERATIONAL_NETWORKS` means `live` works; it says nothing about `test`
-on its own — see `Token` above for why
-`arbitrum`/`polygon`/`avalanche`/`bnb` specifically have no `test`
-environment yet (`optimism`/`ethereum` do).
-
-`EVM_NETWORKS` (`readonly ['base', 'optimism', 'polygon', 'ethereum',
-'arbitrum', 'avalanche', 'bnb']`) and its matching `EvmNetwork` type —
-every current `Network` value (all EVM-based, now that `solana` is
-gone). Use this to guard any logic that assumes an EVM-style
-address/RPC — a future non-EVM network would reintroduce a real gap
-here.
-
-`NETWORK_LABELS: Record<Network, string>` — display names (`'Base'`,
-`'Optimism'`, ...) for UI use.
-
-`NETWORK_EXPLORERS: Record<Network, string>` — each network's block
-explorer base URL (e.g. `https://basescan.org`), used to build a direct
-transaction link (see `explorerTxUrl` on `VerifyCharge`, in
-[`charges.md`](./charges.md)).
-
-## See also
-
-- [`charges.md`](./charges.md) — where `Token`/`Network` are actually
-  used (`CreateChargeInput.acceptedPayments`, `Charge.acceptedPayments`/
-  `paidWith`, `VerifyCharge`), and `GET /v1/networks`
-  (`CapabilitiesSchema`) — the live version of this same matrix, scoped
-  to your API key's `environment`, rather than the full type-level
-  listing on this page.

package/docs/webhooks.md

@@ -1,165 +0,0 @@
-# Webhooks
-
-Everything here is exported from `@klappay/types`'s webhook-related
-modules (`webhook-events.ts`, `webhooks.ts`, `webhook-event-data.ts`) —
-import from the package root either way, this split is an internal
-implementation detail.
-
-## Event types, and the four categories
-
-Every event Klap can send is one `WebhookEventTypeSchema` value, built
-from four sub-enums (each independently exported, useful if you only
-ever care about one group):
-
-| Sub-schema | Category | Events |
-|---|---|---|
-| `ChargeWebhookEventTypeSchema` | `payments` | `charge.created`, `charge.partially_paid`, `charge.confirmed`, `charge.expired`, `charge.underpaid`, `charge.settled`, `charge.settlement_failed`, `charge.overpaid`, `charge.paused`, `charge.reactivated`, `charge.contribution_received`, `charge.contribution_settled` |
-| `AccountWebhookEventTypeSchema` | `account` | `payout_address.changed`, `api_key.created`, `api_key.revoked`, `webhook.created`, `webhook.deleted`, `webhook.secret_rotated`, `fee_tier.updated`, `member.removed`, `member.role_changed`, `member.invited` |
-| `WebhookDeliveryEventTypeSchema` | `webhooks` | `webhook.delivery_failed`, `webhook.delivery_recovered`, `webhook.endpoint_unhealthy` |
-| `SecurityWebhookEventTypeSchema` | `security` | `auth.login`, `auth.login_failed`, `auth.suspicious_activity`, `auth.email_verified`, `auth.password_reset_requested`, `auth.password_reset_completed` |
-
-`EVENT_CATEGORY_MAP` (`Record<WebhookEventType, WebhookCategory>`) is the
-single source of truth for which category an event belongs to —
-generated from the four enums above, never hand-duplicated. Its inverse,
-`WEBHOOK_EVENT_CATEGORIES` (`Record<WebhookCategory, readonly
-WebhookEventType[]>`), gives you every event in a category, e.g. for
-building a subscription UI.
-
-Two events worth calling out specifically:
-
-- **`charge.confirmed` vs. `charge.settled`** — `confirmed` means the
-  payment was *detected on-chain*; `settled` means the merchant's wallet
-  *actually received* the funds, a separate, later step (see
-  `settlementStatus` in [`charges.md`](./charges.md)). 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` — it's an additional signal, not a replacement
-  status.
-- **`charge.paused`/`charge.reactivated`/`charge.contribution_received`/
-  `charge.contribution_settled`** are the only events in this category
-  that don't carry the full `Charge` object as `data`. `paused`/
-  `reactivated` only ever fire for a charge with no `expiresAt` that's
-  gone inactive for longer than its inactivity window, carrying
-  `{ chargeId, lastActivityAt, pausedAt }` / `{ chargeId,
-  reactivatedAt }`. `contribution_received`/`contribution_settled` are
-  exclusive to `mode: 'continuous'` charges (see `mode` in
-  [`charges.md`](./charges.md)) — 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, carrying `{ chargeId, token, network, amount,
-  txHash, payerAddress }` / `{ chargeId, token, network, amount,
-  txHash, distributorAddress }` — one pair-scoped event per
-  contribution instead of one event for the whole charge.
-
-`member.invited` does not exist — there's no invite endpoint in the API
-today.
-
-## Subscribing — `CreateWebhookSchema`
-
-`POST /v1/webhooks`'s body. At least one of `events` or `eventCategories`
-is required (enforced by a `.refine()`, not just documentation):
-
-```ts
-import { CreateWebhookSchema } from '@klappay/types'
-
-CreateWebhookSchema.parse({
-  url: 'https://example.com/webhooks/klap',
-  eventCategories: ['payments'],
-})
-```
-
-- `events` — individual event types, or `"*"` (`WEBHOOK_EVENTS_WILDCARD`)
-  for every event.
-- `eventCategories` — subscribe to a whole category at once (see the
-  table above) — new events added to that category later arrive
-  automatically, no subscription update needed.
-- `excludeEvents` — opt back out of specific events even under a `"*"`
-  or category subscription.
-- `url` must be HTTPS and resolve to a public address — private/internal
-  IPs are rejected server-side.
-
-`WebhookSchema` / `Webhook` is the response to creating one — critically,
-`secret` (the HMAC signing secret) is only ever present in **this**
-response. `WebhookListItemSchema` / `WebhookListItem` is what every
-subsequent list/read returns instead: the same shape minus `secret`,
-plus `hint` (a truncated, safe-to-display form, e.g. `whsec_...ab12`).
-
-## The payload envelope
-
-`WebhookPayloadSchema` / `WebhookPayload` is the wire shape of every
-delivery: `{ id, event, createdAt, data }`. `data` is typed `unknown`
-here on purpose — its real shape depends on `event`, which a single flat
-schema can't express. `id` is also sent as the `X-Klap-Delivery` header,
-distinct from the delivery-id-per-registered-webhook used internally.
-
-For the *typed*, narrowed version, use `TypedWebhookPayload` — a
-discriminated union over `event` (same pattern as Stripe's
-`Event.data.object`):
-
-```ts
-import type { TypedWebhookPayload } from '@klappay/types'
-
-function handle(payload: TypedWebhookPayload) {
-  if (payload.event === 'charge.confirmed') {
-    payload.data.amountReceived // typed as Charge, no cast needed
-  } else if (payload.event === 'payout_address.changed') {
-    payload.data.to // typed as PayoutAddressChangedData
-  }
-}
-```
-
-`WebhookEventDataMap` is the underlying `{ event: dataShape }` mapping
-`TypedWebhookPayload` is built from — every `charge.*` event carries a
-full `Charge`; every other event carries a small, event-specific object
-(all plain TypeScript types, not Zod schemas, since they're never
-validated standalone, only as part of `TypedWebhookPayload`):
-
-| Event(s) | `data` shape |
-|---|---|
-| `payout_address.changed` | `PayoutAddressChangedData` — `{ organizationId, from, to }` (`from` nullable) |
-| `api_key.created` / `api_key.revoked` | `ApiKeyEventData` — `{ apiKeyId, name, environment, hint }` |
-| `webhook.created` / `webhook.deleted` / `webhook.secret_rotated` | `WebhookConfigEventData` — `{ webhookId, url }` |
-| `webhook.delivery_failed` / `webhook.delivery_recovered` / `webhook.endpoint_unhealthy` | `WebhookHealthEventData` — `{ webhookId, url, failureRatio? }` (`failureRatio` only on `endpoint_unhealthy`) |
-| `fee_tier.updated` | `FeeTierUpdatedData` — `{ organizationId, previousFeePercent, newFeePercent }` |
-| `member.removed` | `MemberEventData` — `{ userId, email, role }` |
-| `member.role_changed` | `MemberRoleChangedData` — `MemberEventData & { previousRole }` |
-| `member.invited` | `MemberInvitedData` — `{ organizationId, email, role, invitedByUserId }` |
-| `auth.login` | `AuthLoginData` — `{ userId, ipAddress }` |
-| `auth.login_failed` | `AuthLoginFailedData` — `{ email, ipAddress }` |
-| `auth.suspicious_activity` | `AuthSuspiciousActivityData` — `AuthLoginData & { previousIpAddress }` |
-| `auth.email_verified` | `AuthEmailVerifiedData` — `{ userId, email }` |
-| `auth.password_reset_requested` | `AuthPasswordResetRequestedData` — `{ userId, email }` |
-| `auth.password_reset_completed` | `AuthPasswordResetCompletedData` — `{ userId, email }` |
-
-## Delivery health
-
-`WebhookDeliveryStatusSchema` / `WebhookDeliveryStatus` —
-`'pending' | 'delivered' | 'failed'` (`failed` means all 5 retry
-attempts over ~24h were exhausted; retry manually via
-`POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry`).
-`WebhookDeliverySchema` / `WebhookDelivery` is one entry from `GET
-/v1/webhooks/{id}/deliveries` — `responseCode: null` means every attempt
-failed to connect at all, not just a non-2xx response.
-`ListWebhookDeliveriesSchema`/`PaginatedWebhookDeliveriesSchema` are the
-query/response shapes for that endpoint — same shared cursor pagination
-as `GET /v1/charges`/`GET /v1/organizations/{id}/api-keys`/
-`GET /v1/organizations/{id}/users`, see
-[`charges.md`](./charges.md#the-shared-cursor-pagination-pattern). `GET
-/v1/webhooks` itself (listing the webhooks, not their deliveries) stays
-unpaginated — it's hard-capped at 20 active webhooks per organization.
-
-The `webhook.*` meta-events (`WebhookDeliveryEventTypeSchema`) let you
-monitor this without polling: `webhook.endpoint_unhealthy` fires once
-when a webhook's trailing-24h failure rate crosses 20%,
-`webhook.delivery_recovered` fires once when a delivery next succeeds
-afterward.
-
-## See also
-
-- [`charges.md`](./charges.md) — the `Charge` shape carried by every
-  `charge.*` event's `data`.
-- [`sandbox.md`](./sandbox.md) — `TriggerableChargeEvent`, the subset of
-  charge events you can simulate without a real on-chain transfer.