@settlemint/dalp-sdk 3.1.33-release.42636987002 → 3.2.0-rc.1

package/LICENSE

@@ -1,162 +1,8 @@
-# SETTLEMINT COMMERCIAL CUSTOMER SOURCE LICENSE
-
-**("License")**
-
----
-
-## TL;DR (NON-BINDING SUMMARY)
-
-- You may view, fork, modify, and run this code ONLY while you have an active, paid contract with SettleMint.
-- You may use it internally (cloud, on-prem, or hybrid) only as agreed in your contract.
-- You may NOT resell it, offer it as a service, publish it, or use it to build or operate a competing product.
-- When your contract ends, your right to use the software ends immediately. You must stop all deployments and delete active copies.
-- This is NOT open source.
-
-*This summary is informational only. The legal terms below control.*
-
----
+# SettleMint Commercial License
 
 Copyright © 2025 SettleMint NV
 All rights reserved.
 
-This License governs the use of the Software (as defined below) and is a proprietary, source-available license. It is not an open-source license.
-
-By accessing, copying, modifying, or using the Software, You agree to be bound by this License and confirm that You are a Customer with an Active Contract.
-
----
-
-## 1. DEFINITIONS
-
-**1.1 "Licensor"**
-SettleMint NV, a company incorporated under Belgian law, or any affiliated entity explicitly identified in the applicable Commercial Agreement.
-
-**1.2 "Customer" or "You"**
-The legal entity that has entered into an Active Contract with Licensor and whose employees or contractors access or use the Software.
-
-**1.3 "Commercial Agreement"**
-Any master services agreement, subscription agreement, order form, statement of work, or similar contract executed between Licensor and Customer governing commercial terms.
-
-**1.4 "Active Contract"**
-A Commercial Agreement that is in force, not terminated, and for which all undisputed fees due are paid.
-
-**1.5 "Software"**
-The source code, object code, build scripts, configuration files, documentation, and any other materials made available by Licensor in this repository, including all updates and modifications thereto.
-
-**1.6 "Derivative Works"**
-Any modification, adaptation, translation, or other work based on or incorporating the Software, as defined under Book XI of the Belgian Code of Economic Law.
-
-**1.7 "Authorized Use"**
-Use of the Software solely for Customer's internal business purposes and strictly within the scope permitted by the Active Contract.
-
-**1.8 "Authorized Deployment"**
-Any installation, environment, system, blockchain network, cluster, or runtime explicitly permitted under the Active Contract, whether cloud-based, on-premises, or hybrid.
-
-**1.9 "Competitive Use"**
-Any use of the Software or Derivative Works to develop, operate, market, or support a product or service that competes with Licensor's products or services, or that could reasonably substitute for them.
-
----
-
-## 2. LICENSE GRANT
-
-**2.1 Conditional License Grant**
-Subject to continuous compliance with this License and the existence of an Active Contract, Licensor grants Customer a limited, non-exclusive, non-transferable, non-sublicensable, revocable license to:
-
-(a) access and review the Software;
-(b) copy the Software for internal use;
-(c) modify the Software and create Derivative Works;
-(d) deploy and run the Software and Derivative Works solely for Authorized Use and only in Authorized Deployments.
-
-**2.2 Forking**
-Customer may create private forks of the Software solely for Authorized Use. All such forks remain subject to this License.
-
-**2.3 No Implied Rights**
-No rights are granted except as expressly stated. All rights not expressly granted are reserved by Licensor.
-
----
-
-## 3. RESTRICTIONS
-
-Customer shall not, directly or indirectly:
-
-(a) use the Software without an Active Contract;
-(b) deploy the Software outside Authorized Deployments;
-(c) provide the Software or any Derivative Work as a service, platform, or product to third parties, unless explicitly permitted in writing;
-(d) sublicense, distribute, sell, lease, or transfer the Software or any Derivative Work to any third party;
-(e) engage in any Competitive Use;
-(f) use the Software to benchmark, reverse-engineer, or analyze Licensor's products for competitive purposes;
-(g) publish, disclose, or make publicly available the Software or any fork thereof;
-(h) remove or obscure copyright, trademark, or proprietary notices.
-
----
-
-## 4. OWNERSHIP
-
-**4.1 Licensor IP**
-Licensor retains all right, title, and interest in and to the Software.
-
-**4.2 Customer Modifications**
-Customer retains ownership of original modifications it creates; however, Customer may not use, execute, deploy, or distribute any Derivative Work that includes or depends on the Software except as permitted under an Active Contract.
-
-**4.3 Feedback and Contributions**
-Any feedback, suggestions, or contributions provided by Customer may be used by Licensor without restriction. To the extent such contributions constitute copyrightable works, Customer grants Licensor a perpetual, worldwide, royalty-free, irrevocable license to use, modify, and distribute them.
-
----
-
-## 5. TERMINATION
-
-**5.1 Automatic Termination**
-This License automatically terminates upon termination or expiration of the Active Contract.
-
-**5.2 Effect of Termination**
-Upon termination, Customer must immediately:
-
-(a) cease all use and deployment of the Software and Derivative Works;
-(b) delete all running instances, binaries, containers, and deployments;
-(c) destroy or delete all copies of the Software, except that one archival copy of source code may be retained solely for legal or compliance purposes.
-
-No right to resume use or deployment survives termination.
-
-**5.3 Survival**
-Sections relating to ownership, restrictions, liability, governing law, and jurisdiction survive termination.
-
----
-
-## 6. WARRANTY DISCLAIMER
-
-THE SOFTWARE IS PROVIDED "AS IS". TO THE MAXIMUM EXTENT PERMITTED BY BELGIAN LAW, LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
-
----
-
-## 7. LIMITATION OF LIABILITY
-
-To the maximum extent permitted by Belgian law, Licensor shall not be liable for any indirect, incidental, consequential, or special damages, including loss of profits, data, or business interruption, even if advised of the possibility.
-
-Nothing in this License limits liability that cannot be limited under mandatory Belgian law.
-
----
-
-## 8. GOVERNING LAW AND JURISDICTION
-
-This License is governed by and construed in accordance with the laws of Belgium, excluding conflict-of-law rules.
-
-Any dispute arising out of or in connection with this License shall be subject to the exclusive jurisdiction of the courts of Brussels.
-
----
-
-## 9. MISCELLANEOUS
-
-**9.1 Entire Agreement**
-This License, together with the applicable Commercial Agreement, constitutes the entire agreement regarding the Software.
-
-**9.2 Conflict**
-In case of conflict, the Commercial Agreement prevails.
-
-**9.3 Severability**
-If any provision is held invalid, the remaining provisions remain in full force.
-
-**9.4 No Waiver**
-Failure to enforce any provision does not constitute a waiver.
-
----
+SettleMint distributes DALP as container images and Helm charts under SettleMint's commercial license. DALP is distributed without its source code.
 
-**END OF LICENSE**
+Access to the DALP source code, or escrow of it, can be agreed in a contract with SettleMint as a paid option.

package/README.md

@@ -1,206 +1,313 @@
-<p align="center">
-  <img src="https://github.com/settlemint/sdk/blob/main/logo.svg" width="200px" align="center" alt="SettleMint logo" />
-  <h1 align="center">DALP SDK</h1>
-  <p align="center">
-    <a href="https://settlemint.com">https://settlemint.com</a>
-    <br/>
-    Fully typed TypeScript SDK for the Digital Asset Lifecycle Platform API.
-  </p>
-</p>
-
-<p align="center">
-<a href="https://www.npmjs.com/package/@settlemint/dalp-sdk" rel="nofollow"><img src="https://img.shields.io/npm/v/@settlemint/dalp-sdk" alt="npm version"></a>
-<a href="https://www.npmjs.com/package/@settlemint/dalp-sdk" rel="nofollow"><img src="https://img.shields.io/npm/dw/@settlemint/dalp-sdk" alt="npm downloads"></a>
-</p>
-
-<div align="center">
-  <a href="https://settlemint.com">Website</a>
-  <span>&nbsp;&nbsp;&bull;&nbsp;&nbsp;</span>
-  <a href="https://www.npmjs.com/package/@settlemint/dalp-sdk">NPM</a>
-  <span>&nbsp;&nbsp;&bull;&nbsp;&nbsp;</span>
-  <a href="mailto:support@settlemint.com">Support</a>
-  <br />
-</div>
-
-## About
-
-The DALP SDK provides a fully typed client for the Digital Asset Lifecycle Platform API. Built on [oRPC](https://orpc.unnoq.com/) with contract-first types, it gives you auto-complete for every API namespace — tokens, identities, compliance, transactions, and more.
-
-## Installation
-
-```bash
-# npm
-npm install @settlemint/dalp-sdk
-
-# bun
-bun add @settlemint/dalp-sdk
-```
+# DALP SDK
+
+One typed client for the Platform API v2, derived from the platform's own route
+declaration. Calls are namespaced (`dalp.api.token.transfer(...)`), a queue
+backed write resolves once the chain has settled, and TanStack Query factories
+sit on the same nodes as the calls. The package ships no runtime schema
+library: the types are compile time only.
+
+Two interpreters over one route table: Promise and Effect. The package root
+returns promises. The `./effect` subpath returns Effect values with a typed
+failure channel. Neither pulls the other in, and a build gate keeps the root
+free of Effect.
 
-## Quick Start
+## Client
 
-```typescript
+```ts
 import { createDalpClient } from "@settlemint/dalp-sdk";
 
 const dalp = createDalpClient({
-  url: "https://dalp.example.com",
+  baseUrl: "https://dalp.example.com",
   apiKey: "sm_dalp_...",
-  organizationId: "org_...", // optional, for multi-org setups
 });
 
-// Every method is fully typed with auto-complete
-const tokens = await dalp.token.list({ query: {} });
-const system = await dalp.system.read({});
+const tokens = await dalp.api.token.list({ page: { limit: 25 } }, { signal });
 ```
 
-## Auth Client
+A call takes one flat object. The route table says which of its keys are path
+parameters and which are query or body fields, so a call site names what it
+means and never restates the transport. The build refuses any route whose path
+parameter would collide with a body or query key, which is what makes the
+merge safe.
+
+`createDalpClient` owns the shared transport policy once: the credential
+mechanism, the acting-context headers (`organizationId`, `participant`,
+`executor`, `chainId`, `selectedSigners`, `idempotencyKey`), conditional
+`If-None-Match` reuse, custom fetch injection, the settlement bound, and abort
+propagation.
+
+**An API key cannot reach a browser or an app.** `createDalpClient` and
+`createDalpAuthClient` throw at construction when a key is passed with
+`runtime: "browser"` or `runtime: "react-native"`, rather than at the first
+request. A key carries the
+full authority of the identity it belongs to, and anything bundled into a web
+page or an app ships to every user. There the client authenticates with the
+session cookie instead.
+
+### Dispatch by route id
+
+```ts
+const token = await dalp.execute("token/read", { assetId });
+```
 
-Use `createDalpAuthClient` for Better Auth operations such as sign-up, session listing, organization management, API
-keys, device authorization, and wallet verification setup.
+`execute` is typed against the id through the `DalpRouteTypes` registry, so a
+command surface built from route ids keeps the same request and response types
+the namespaced tree gives a call site. The CLI, the end-to-end harness, and the
+demo scripts are all built on it.
+
+### Settlement
+
+A queue-backed write carries a `Prefer` header derived from
+`settlementTimeoutMs`: undefined asks for `wait=15`, zero or less asks for
+`respond-async`, anything else asks for `wait=<seconds>`, clamped to the
+platform's 5 to 99 second range. `settlementTimeoutMs` sets that bound per
+client, and a call may override it.
+
+The platform does the waiting, not the client. When the write settles inside
+the wait, the call returns the route's HTTP 200 resource. When it does not, the
+call returns the declared HTTP 202 handle unchanged: a transaction write's
+`{ transactionId, status, statusUrl }`, or a custody write's `{ requestId,
+state, statusUrl }`. The client never polls a status URL on your behalf.
+
+User creation can return `{ requestId, state: "running", statusUrl }` when it
+exceeds the synchronous wait. Poll `statusUrl` with the same organization and
+chain headers. The read returns 202 while creation is running, 200 with the
+created user when it completes, or a named error when it fails. It can also
+return a custody handle to follow until the custody account settles. Do not
+submit another create while the original request is pending.
+
+Pass a transaction id to `waitForTransaction` to follow it to a terminal
+state. A write the funding gate parks on an operator payment reads as still
+queued for as long as the ask is open: the status row carries it as
+`activeRequirement`, and `waitForTransaction` restarts its own timeout on every
+status that reports one, so the wait it runs outlasts the pause. A caller that
+cannot wait that long ends the wait through `signal`, or passes
+`holdWhilePaused: false` to end on the first parked status instead. A custody
+handle has no equivalent helper: follow `statusUrl` yourself. A `DEAD_LETTER`
+status with `mayStillLand: true` is not terminal: the call can still reach the
+chain, so `waitForTransaction` keeps polling it and ends with reason `timeout`,
+not `terminal-failure`. Do not resend while `mayStillLand` is `true`.
+
+### Conditional requests and ETags
+
+The client reuses a held body when the server answers a matching ETag with 304.
+Server ETags must be **strong content digests** computed **after
+authorization** inside the requester's partition. Version-stamp ETags
+(generation counters, watermarks, table versions) are forbidden for conditional
+request adopters: a stamp can collide across tenants or lag a body change.
+
+Identity changes that do not ride this client (browser sign-out, organization
+switch) must clear the held bodies, so a later GET cannot send another
+session's `If-None-Match`.
+
+```ts
+dalp.conditionalRequests.clear();
+```
 
-```typescript
-import { createDalpAuthClient } from "@settlemint/dalp-sdk";
+## Effect
 
-const auth = createDalpAuthClient({
-  url: "https://dalp.example.com",
-  apiKey: "sm_dalp_...",
-  organizationId: "org_...",
-});
+```ts
+import { createDalpEffectClient } from "@settlemint/dalp-sdk/effect";
 
-const apiKeys = await auth.apiKey.list();
+const dalp = createDalpEffectClient({ baseUrl, apiKey });
+const tokens = yield * dalp.api.token.list({ page: { limit: 25 } });
 ```
 
-For Node-side session flows, use the platform client. It keeps Better Auth cookies in an SDK-owned store and exposes the
-DAPI client and auth client together.
+The same routes, returning `Effect` values that fail with `DalpRequestError<Code>`,
+where `Code` is the operation's own error codes,
+rather than throwing. `execute` is typed by route id here too.
 
-```typescript
-import { createDalpPlatformClient } from "@settlemint/dalp-sdk";
+## The route table
 
-const platform = createDalpPlatformClient({
-  url: "https://dalp.example.com",
-});
+```ts
+import { routeIds, routeTable } from "@settlemint/dalp-sdk/routes";
+```
 
-await platform.auth.signUp.email({
-  email: "user@example.com",
-  password: "Password123!",
-  name: "Example User",
-});
+`./routes` publishes the generated table both interpreters dispatch through:
+every v2 route's id, method, path template, statuses, and traits. It carries no
+client and no Effect, so a tool that only needs to know what the platform
+serves loads this rather than a client.
 
-const sessionCookie = platform.cookieStore.header;
-```
+## TanStack Query
 
-### Auth Namespaces
-
-All namespaces below are fully typed on `DalpAuthClient` — every operation has auto-complete and a typed return value.
-
-| Namespace             | Operations                                                                                                    | Description                                                |
-| --------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `signIn`              | `email`                                                                                                       | Sign in with email and password                            |
-| `signUp`              | `email`                                                                                                       | Register a new account                                     |
-| `getSession`          | —                                                                                                             | Fetch the current session                                  |
-| `listSessions`        | —                                                                                                             | List all active sessions                                   |
-| `revokeSession`       | —                                                                                                             | Revoke a specific session                                  |
-| `revokeOtherSessions` | —                                                                                                             | Revoke all sessions except the current one                 |
-| `apiKey`              | `create`, `list`, `delete`                                                                                    | Manage API keys                                            |
-| `organization`        | `create`, `list`, `setActive`, `inviteMember`, `acceptInvitation`, `listMembers`, `addMember`, `removeMember` | Manage organizations and membership                        |
-| `admin`               | `listUsers`, `createUser`, `removeUser`, `setRole`                                                            | Administrative user management                             |
-| `device`              | `code`, `token`, `approve`, `deny`                                                                            | Device authorization flow                                  |
-| `twoFactor`           | `enable`, `disable`, `verifyTotp`, `verifyBackupCode`, `generateBackupCodes`                                  | Account-level TOTP two-factor authentication               |
-| `wallet.pincode`      | `enable`, `disable`, `update`, `reset`                                                                        | Wallet pincode protection                                  |
-| `wallet.twoFactor`    | `enable`, `disable`, `verify`                                                                                 | Wallet two-factor verification                             |
-| `wallet.secretCodes`  | `generate`, `confirm`                                                                                         | Wallet secret (recovery) codes                             |
-| `passkey`             | —                                                                                                             | Account-level passkey registration (browser/WebAuthn only) |
-
-```typescript
-// Enable account-level 2FA and verify a TOTP code
-await auth.twoFactor.enable({ password: "..." });
-await auth.twoFactor.verifyTotp({ code: "123456" });
+```ts
+const options = dalp.api.token.list.queryOptions({ page: { limit: 25 } });
+const transfer = dalp.api.token.transfer.mutationOptions();
 ```
 
-```typescript
-// Enable wallet pincode protection
-await auth.wallet.pincode.enable({ pincode: "1234", password: "..." });
-```
+Every read node carries `queryOptions`; every write node carries
+`mutationOptions`. They are plain objects in the shapes TanStack
+Query expects, so nothing forces you into that library and nothing stops you
+using something else.
+
+Cache keys are derived from route identity plus canonicalized input, so two
+callers passing the same parameters in a different key order share one entry.
+`./react-query` exports `queryKeyFor` and `canonicalize` for building a
+matching invalidation filter, and `UI_SETTLEMENT_TIMEOUT_MS`, the bound the
+mutation factories default to.
+
+## Scalars
+
+Custom wire formats (BigDecimal amounts, EVM addresses, and the
+`OrganizationId` entity brand) are not expressed structurally in the generated
+OpenAPI document, so `./scalars` carries a decoder for each:
+`decodeBigDecimal`, `decodeEthereumAddress`, `decodeOrganizationId`, and the
+exchange-rate response transformer. The route table names which fields carry a
+scalar, keyed by dotted path, so a consumer applies a decoder where the
+declaration says one lives rather than guessing from a field name.
+`OrganizationId` is the only entity id branded end to end across the platform;
+every other identifier crossing this boundary is a plain string.
+
+Request and response types brand the wire scalars the API validates, so a raw
+string does not compile where the API wants an address, hash or amount. Build the
+brand with a constructor, which throws a `DalpSdkError` (code
+`sdk.scalar.EVM_ADDRESS_INVALID` for an address, `sdk.scalar.VALUE_INVALID` for
+the rest) when the value is not valid, or narrow with the matching guard:
+
+```ts
+import { evmAddress, integerString, isEvmAddress } from "@settlemint/dalp-sdk/scalars";
+
+await dalp.api.token.mint({
+  assetId: evmAddress("0x52908400098527886e0f7030069857d2e4169ee7"),
+  recipients: evmAddress("0x5A0b54D5dc17e0AadC383d2db43B0a0D3E029c4c"),
+  amounts: integerString(1000n),
+});
 
-## Configuration
+const value: unknown = await readFromSomewhere();
+if (isEvmAddress(value)) {
+  await dalp.api.token.mint({ assetId: value, recipients: value, amounts: "100" });
+}
+```
 
-```typescript
-import { createDalpClient } from "@settlemint/dalp-sdk";
+The constructors are `evmAddress`, `ethereumHash`, `ethereumHex`,
+`cantonPartyId`, `fiatCurrency`, `networkId`, `timestamp`, `integerString` and
+`decimalString`; each has an `is...` guard, such as `isEthereumHash`. Integer
+text is typed `${bigint}` and decimal text `${number}`.
 
-const dalp = createDalpClient({
-  // Required
-  url: "https://dalp.example.com",
+## Auth
 
-  // Required for authenticated routes
-  apiKey: "sm_dalp_...",
+```ts
+import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";
+```
 
-  // Optional
-  organizationId: "org_...", // multi-org scoping
-  headers: { "User-Agent": "MyApp" }, // override default headers
-  idempotencyKey: "req_abc123", // ⚠️ sent on EVERY request — use only for single-mutation clients
-  requestValidation: false, // validate requests client-side (default: false)
-  responseValidation: false, // validate responses client-side (default: false)
-  fetch: customFetch, // custom fetch implementation
-});
+The route surface already carries every auth REST route. `./auth` covers what a
+REST call cannot express: the session and cookie state machine, plugin actions
+that must run on the device (`passkeyClient` drives the WebAuthn ceremony
+through `navigator.credentials`, or through the `passkey` ceremony a React
+Native app passes), and the access-control model that evaluates a
+permission locally instead of round-tripping. It sits off the package root
+because it costs roughly 70 KiB of Better Auth that a consumer who only calls
+routes should not pay.
+
+Better Auth's client types reference zod, so `zod` is an optional peer
+dependency: install it if you use `./auth`, skip it otherwise. No code in this
+package imports zod at runtime.
+
+An API key works on 9 auth routes only. Eight of them are reads:
+
+- `GET /get-session`
+- `GET /organization/list`
+- `GET /organization/get-full-organization`
+- `GET /organization/list-members`
+- `POST /organization/has-permission`
+- `GET /api-key/list`
+- `GET /api-key/get`
+- `GET /passkey/list-user-passkeys`
+
+The ninth, `POST /api-key/delete`, deletes only the key that sends the request.
+
+Every other auth route answers a request that carries a key with HTTP 403 and
+the code `API_KEY_NOT_SUPPORTED_ON_ROUTE`. Use a session cookie for those
+routes. The API key guide in the DALP API reference has the details.
+
+## React Native
+
+Supported: Expo SDK 57 (React Native 0.86, React 19.2), with `fetch` from
+`expo/fetch` passed to both clients. The SDK detects React Native from
+`navigator.product` and then keeps the session in its own cookie store, sends
+`credentials: "omit"`, refuses an API key, and sends the platform's origin as
+`Origin` on every call.
+
+```ts
+import { createCookieStoreFetch, createDalpClient, makeCookieStore } from "@settlemint/dalp-sdk";
+import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";
+import { fetch } from "expo/fetch";
+
+const cookieStore = makeCookieStore((await SecureStore.getItemAsync("dalp.session")) ?? "");
+const auth = await createDalpAuthClient({ url, cookieStore, fetch, passkey: ceremony });
+const dalp = createDalpClient({ baseUrl: url, fetch: createCookieStoreFetch(cookieStore, fetch) });
 ```
 
-## API Namespaces
-
-| Namespace          | Description                |
-| ------------------ | -------------------------- |
-| `account`          | Manage accounts            |
-| `actions`          | Manage actions             |
-| `addons`           | Manage addons              |
-| `admin`            | Administrative operations  |
-| `contacts`         | Manage contacts            |
-| `exchangeRates`    | View exchange rates        |
-| `externalToken`    | Manage external tokens     |
-| `identityRecovery` | Recover lost identities    |
-| `monitoring`       | Platform monitoring        |
-| `search`           | Search across the platform |
-| `settings`         | Platform settings          |
-| `system`           | System administration      |
-| `token`            | Manage security tokens     |
-| `transaction`      | View transactions          |
-| `user`             | Manage platform users      |
-
-## Endpoint Coverage
-
-The SDK covers 100% of the v2 REST API: it is generated from the same oRPC contract that the server implements, and a
-CI check (`bun run check:sdk-coverage`) diffs every mounted API route against the contract on every change. Endpoints
-intentionally outside the SDK contract are named in a committed allowlist with a reason each, in these categories:
-
-- **v1-frozen** — the deliberately frozen v1 REST surface
-- **internal-ops** — health probes, CSP report sink, theme CSS, static manifests
-- **webhook-receiver** — provider webhook receivers (DFNS, Ripple, compliance providers)
-- **better-auth** — auth plumbing, covered by the SDK auth client instead
-- **docs / asset-delivery / bundler / orpc-mount** — API docs pages, binary asset delivery, the ERC-4337 bundler
-  JSON-RPC passthrough (covered by the SDK bundler client), and the oRPC transport mounts themselves
-
-## Subpath Exports
-
-```typescript
-// Main entry — client factory, error codes, serializers
-import { createDalpAuthClient, createDalpClient, createDalpPlatformClient } from "@settlemint/dalp-sdk";
-
-// Type-only — for function signatures without runtime code
-import type { DalpClient, DalpClientConfig } from "@settlemint/dalp-sdk/types";
-
-// Plugins — optional oRPC link plugins for advanced usage
-import { BatchLinkPlugin, RequestValidationPlugin } from "@settlemint/dalp-sdk/plugins";
+- React Native's built-in `fetch` works for calls but cannot read a stream; a
+  stream on it fails with `sdk.stream.UNREADABLE_BODY` before the request is
+  sent. Use `expo/fetch`.
+- React Native has no WebAuthn. Pass a `passkey` ceremony (`DalpPasskeyCeremony`:
+  `authenticate` and `register`, each taking the platform's options JSON and
+  returning the credential JSON) backed by a native passkey module.
+- Persist `cookieStore.header()` in secure storage yourself; the SDK holds it in
+  memory only.
+
+The SDK's tests run this wiring headless on the fetch and abort polyfills React
+Native ships and a model of `expo/fetch`. They do not run on Hermes, a
+simulator, or a device.
+
+## Bundler and paymaster
+
+Use JSON-RPC 2.0 over `POST https://dalp.example.com/bundler/{chainId}` for
+account-abstraction calls. `{chainId}` is the decimal EVM chain ID; this is
+not an `/api/v2` REST route and is not exposed through `dalp.api` or a separate
+SDK bundler client. From a server, send a write-capable API key in `x-api-key`;
+the key's active organization selects the tenant. Never put the key in browser
+code.
+
+The mount serves these standard methods:
+
+| Method                         | Params                                          |
+| ------------------------------ | ----------------------------------------------- |
+| `eth_chainId`                  | `[]`                                            |
+| `eth_sendUserOperation`        | `[userOperation, entryPoint]`                   |
+| `eth_estimateUserOperationGas` | `[userOperation, entryPoint]`                   |
+| `eth_getUserOperationByHash`   | `[userOperationHash]`                           |
+| `eth_getUserOperationReceipt`  | `[userOperationHash]`                           |
+| `eth_supportedEntryPoints`     | `[]`                                            |
+| `pm_getPaymasterData`          | `[userOperation, entryPoint, chainId, context]` |
+| `pm_getPaymasterStubData`      | `[userOperation, entryPoint, chainId, context]` |
+
+The UserOperation must be signed by your account-abstraction stack before
+`eth_sendUserOperation`. The mount accepts EntryPoint v0.7 UserOperations and
+returns JSON-RPC `result` or `error` envelopes, not REST `{ data, links }`
+resources. `eth_chainId` reports the chain selected by the URL. Consult the platform's bundler
+method policy before depending on a method being enabled for your credential.
+
+```ts
+const response = await fetch("https://dalp.example.com/bundler/1", {
+  method: "POST",
+  headers: {
+    "content-type": "application/json",
+    "x-api-key": apiKey,
+  },
+  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_supportedEntryPoints", params: [] }),
+});
+const answer = await response.json(); // { jsonrpc: "2.0", id: 1, result: [...] } or { error: ... }
 ```
 
-## Security
+## Webhooks and transaction wait
 
-- **API key authentication** — issued via the DALP dashboard (Settings → API Keys) or via `dalp login`
-- Public routes can be called without an API key; authenticated routes still require one
-- Security headers (`x-api-key`, `x-organization-id`) cannot be overridden by custom headers
-- Client-side request validation can be enabled to catch schema violations early
+- `./verify-webhook` verifies an inbound webhook signature.
+- `./sign-webhook-receipt` signs a webhook delivery receipt (Node only).
+- `./wait-for-transaction` is a bounded poll to a terminal state, for a
+  transaction id from any source, including the 202 handle a client write
+  returns when the platform's wait runs out.
 
-## Errors
+## Package root
 
-DAPI errors thrown by the SDK use `DalpSdkError` and include `message`, `why`, `fix`, `status`, `retryable`, and the
-public DAPI error id when the server returns one.
+The root stays small: the client factory, its options and errors, cookie-store
+transport, and the version constants. A consumer who only
+calls routes never pays for auth, TanStack Query, or webhook code.
 
-## License
+## Documentation
 
-This project is licensed under the **SettleMint Commercial Customer Source License**. See the LICENSE file included in the package for full terms.
+The integrator guide lives under Developer reference in the platform docs:
+install and credentials, calling routes, mutations and settlement, streaming,
+TanStack Query, server rendering in TanStack Start and Next.js, React Native,
+and the Effect surface.