@klappay/types 1.0.0 → 1.0.1

package/docs/tokens-and-networks.md

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klappay/types",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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.",
   "main": "./dist/index.js",
@@ -12,19 +12,25 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist", "LICENSE", "README.md", "logo.png"],
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch"
-  },
   "dependencies": {
     "zod": "^3.23.0"
   },
   "devDependencies": {
     "tsup": "^8.3.0",
     "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
   }
-}
+}