@klappay/types 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Klappay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,120 @@
+<img src="./logo.png" alt="Klap" width="80" />
+
+# @klappay/types
+
+TypeScript types and [Zod](https://zod.dev) schemas for the Klap Core
+API — the request/response contracts for creating charges, managing
+webhooks, and everything else the API exposes. Published separately from
+the API implementation itself (which is closed-source) so integrators get
+accurate, versioned types without needing access to Klap's own codebase.
+
+Klap is a non-custodial crypto payments API — a merchant creates a
+charge, Klap predicts a deterministic on-chain address for it, the payer
+sends funds directly to that address, and Klap detects and distributes the
+payment without ever holding the funds itself.
+
+## Install
+
+```bash
+npm install @klappay/types zod
+```
+
+`zod` is a peer expectation — every schema here is a `zod` schema, so you
+already have it if you use any of them directly.
+
+## What's in here
+
+- **Zod schemas** for every request/response body (e.g. `ChargeSchema`,
+  `CreateChargeSchema`, `WebhookPayloadSchema`) — use these to validate
+  data at runtime, not just for compile-time types.
+- **Inferred TypeScript types** for the same shapes (e.g. `Charge`,
+  `CreateChargeInput`), exported alongside each schema.
+- **Shared enums** used across multiple endpoints (`Network`, `Token`,
+  `ChargeStatus`, `SettlementStatus`, `WebhookEventType`, ...) —
+  including `WebhookCategory`/`EVENT_CATEGORY_MAP` (every event's
+  `payments`/`account`/`webhooks`/`security` grouping), and
+  `TriggerableChargeEvent`, the subset of charge events that
+  `POST /v1/sandbox/charges/{id}/trigger` (and an official SDK's
+  `charge.waitFor()`) accepts — every charge event except
+  `charge.created`. `TypedWebhookPayload`/`WebhookEventDataMap` give the
+  exact `data` shape per event, keyed by `event` (a discriminated union —
+  see the webhook example below).
+- A handful of small constants (`TOKEN_ADDRESSES`, `NETWORK_EXPLORERS`,
+  `EVM_NETWORKS`, `OPERATIONAL_NETWORKS`, `CHARGE_ACCEPTED_PAYMENTS_MAX`)
+  that mirror values the API itself uses.
+- `AcceptedPaymentSchema`/`AcceptedPayment` (`{ token, network }`) — a
+  charge accepts a *list* of these, not a single `token`/`network` pair;
+  `CapabilitiesSchema`/`Capabilities` is the response shape of
+  `GET /v1/networks`, the live matrix of pairs your key's environment
+  can currently accept.
+
+Every schema field carries a `.describe()` — read them in your editor's
+hover tooltips, or via the full interactive API reference served by the
+API itself (open the API's base URL in a browser once you have access).
+
+## Documentation
+
+| 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` |
+
+## Usage
+
+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 an inbound webhook payload (recommended — don't just trust the
+shape of what you receive):
+
+```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), since `data`'s shape depends on
+  // `event` (see WebhookEventDataMap/TypedWebhookPayload above).
+
+  res.sendStatus(200)
+})
+```
+
+Note: this package only validates the *shape* of a webhook payload — it
+does not verify the `X-Klap-Signature` HMAC header, which you must still
+check yourself against the signing secret returned when you created the
+webhook. Validating shape without verifying the signature means anyone
+who can reach your endpoint can send you a structurally-valid payload.
+If you'd rather not hand-roll HTTP calls and signature verification, an
+official SDK ([github.com/klappay](https://github.com/klappay)) wraps
+this package with a full client, typed errors, and a `constructEvent()`
+helper that verifies the signature and returns a `TypedWebhookPayload`
+— `data` narrows automatically from `event` in a `switch`/`if`, no cast
+needed. See the live API reference for details.
+
+## Versioning
+
+This package follows the API's own versioning. A breaking change to a
+schema here means a breaking change to the corresponding API contract —
+check the changelog before upgrading across a major version.
+
+## License
+
+MIT — see [`LICENSE`](./LICENSE). This applies to this package only; the
+Klap Core API implementation itself is closed-source.