@settlemint/dalp-sdk 3.1.26-main.37116470199 → 3.1.26

package/README.md

@@ -1,273 +1,206 @@
-# 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. 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.
+<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
+```
 
-## Client
+## Quick Start
 
-```ts
+```typescript
 import { createDalpClient } from "@settlemint/dalp-sdk";
 
 const dalp = createDalpClient({
-  baseUrl: "https://dalp.example.com",
+  url: "https://dalp.example.com",
   apiKey: "sm_dalp_...",
+  organizationId: "org_...", // optional, for multi-org setups
 });
 
-const tokens = await dalp.api.token.list({ page: { limit: 25 } }, { signal });
+// Every method is fully typed with auto-complete
+const tokens = await dalp.token.list({ query: {} });
+const system = await dalp.system.read({});
 ```
 
-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 });
-```
+## Auth Client
 
-`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.
-
-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.
-
-### 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();
-```
+Use `createDalpAuthClient` for Better Auth operations such as sign-up, session listing, organization management, API
+keys, device authorization, and wallet verification setup.
 
-## Effect
+```typescript
+import { createDalpAuthClient } from "@settlemint/dalp-sdk";
 
-```ts
-import { createDalpEffectClient } from "@settlemint/dalp-sdk/effect";
+const auth = createDalpAuthClient({
+  url: "https://dalp.example.com",
+  apiKey: "sm_dalp_...",
+  organizationId: "org_...",
+});
 
-const dalp = createDalpEffectClient({ baseUrl, apiKey });
-const tokens = yield * dalp.api.token.list({ page: { limit: 25 } });
+const apiKeys = await auth.apiKey.list();
 ```
 
-The same routes, returning `Effect` values that fail with `DalpRequestError`
-rather than throwing. `execute` is typed by route id here too.
+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 route table
+```typescript
+import { createDalpPlatformClient } from "@settlemint/dalp-sdk";
 
-```ts
-import { routeIds, routeTable } from "@settlemint/dalp-sdk/routes";
-```
-
-`./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 platform = createDalpPlatformClient({
+  url: "https://dalp.example.com",
+});
 
-## TanStack Query
+await platform.auth.signUp.email({
+  email: "user@example.com",
+  password: "Password123!",
+  name: "Example User",
+});
 
-```ts
-const options = dalp.api.token.list.queryOptions({ page: { limit: 25 } });
-const transfer = dalp.api.token.transfer.mutationOptions();
+const sessionCookie = platform.cookieStore.header;
 ```
 
-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.
-
-## Auth
-
-```ts
-import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";
+### 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" });
 ```
 
-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 8 auth routes only. Each of them is a read:
-
-- `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`
-
-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) });
+```typescript
+// Enable wallet pincode protection
+await auth.wallet.pincode.enable({ pincode: "1234", password: "..." });
 ```
 
-- 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: [] }),
+## Configuration
+
+```typescript
+import { createDalpClient } from "@settlemint/dalp-sdk";
+
+const dalp = createDalpClient({
+  // Required
+  url: "https://dalp.example.com",
+
+  // Required for authenticated routes
+  apiKey: "sm_dalp_...",
+
+  // 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
 });
-const answer = await response.json(); // { jsonrpc: "2.0", id: 1, result: [...] } or { error: ... }
 ```
 
-## Webhooks and transaction wait
+## 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";
+```
+
+## Security
 
-- `./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.
+- **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
 
-## Package root
+## Errors
 
-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.
+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.
 
-## Documentation
+## License
 
-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.
+This project is licensed under the **SettleMint Commercial Customer Source License**. See the LICENSE file included in the package for full terms.