@settlemint/dalp-sdk 3.1.18 → 3.1.19-main.34482536277

package/README.md

@@ -1,206 +1,193 @@
-<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. 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({ 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.
 
-Use `createDalpAuthClient` for Better Auth operations such as sign-up, session listing, organization management, API
-keys, device authorization, and wallet verification setup.
+`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.
 
-```typescript
-import { createDalpAuthClient } from "@settlemint/dalp-sdk";
+**An API key cannot reach a browser.** `createDalpClient` throws at
+construction when a key is passed with `runtime: "browser"`, rather than at the
+first request. A key carries the full authority of the identity it belongs to.
+In a browser the client authenticates with the session cookie instead.
 
-const auth = createDalpAuthClient({
-  url: "https://dalp.example.com",
-  apiKey: "sm_dalp_...",
-  organizationId: "org_...",
-});
+### Dispatch by route id
 
-const apiKeys = await auth.apiKey.list();
+```ts
+const token = await dalp.execute("token/read", { assetId });
 ```
 
-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.
+`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();
+```
 
-```typescript
-import { createDalpPlatformClient } from "@settlemint/dalp-sdk";
+## Effect
 
-const platform = createDalpPlatformClient({
-  url: "https://dalp.example.com",
-});
+```ts
+import { createDalpEffectClient } from "@settlemint/dalp-sdk/effect";
 
-await platform.auth.signUp.email({
-  email: "user@example.com",
-  password: "Password123!",
-  name: "Example User",
-});
-
-const sessionCookie = platform.cookieStore.header;
+const dalp = createDalpEffectClient({ baseUrl, apiKey });
+const tokens = yield * dalp.api.token.list({ limit: 25 });
 ```
 
-### 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 same routes, returning `Effect` values that fail with `DalpRequestError`
+rather than throwing. `execute` is typed by route id here too.
+
+## The route table
+
+```ts
+import { routeIds, routeTable } from "@settlemint/dalp-sdk/routes";
 ```
 
-```typescript
-// Enable wallet pincode protection
-await auth.wallet.pincode.enable({ pincode: "1234", password: "..." });
+`./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.
+
+## TanStack Query
+
+```ts
+const options = dalp.api.token.list.queryOptions({ limit: 25 });
+const transfer = dalp.api.token.transfer.mutationOptions();
 ```
 
-## Configuration
+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";
+```
 
-```typescript
-import { createDalpClient } from "@settlemint/dalp-sdk";
+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 in the browser (`passkeyClient` drives the WebAuthn ceremony
+through `navigator.credentials`), 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.
 
-const dalp = createDalpClient({
-  // Required
-  url: "https://dalp.example.com",
+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.
 
-  // Required for authenticated routes
-  apiKey: "sm_dalp_...",
+## Bundler and paymaster
 
-  // 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
-});
+```ts
+import { createDalpBundlerClient } from "@settlemint/dalp-sdk/bundler";
 ```
 
-## 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";
-```
+`createDalpBundlerClient` keeps the eight established ERC-4337 method names
+while calling the v2 REST resources underneath. It accepts EntryPoint v0.9
+`viem` shapes and returns the corresponding typed values.
 
-## 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, bundler, 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, and the Effect
+surface.

package/dist/auth/client.d.ts

@@ -0,0 +1,113 @@
+import type { DalpFetch } from "../client/ssr-fetch.ts";
+import type { AuthGetApiKeyListResponse, AuthGetOrganizationListResponse, AuthPostApiKeyCreateData, AuthPostApiKeyCreateResponse, AuthPostApiKeyDeleteData, AuthPostApiKeyDeleteResponse, AuthPostDeviceApproveData, AuthPostDeviceApproveResponse, AuthPostDeviceDenyData, AuthPostDeviceDenyResponse, AuthPostOrganizationAcceptInvitationData, AuthPostOrganizationAcceptInvitationResponse, AuthPostOrganizationCreateData, AuthPostOrganizationCreateResponse, AuthPostOrganizationRemoveMemberData, AuthPostOrganizationRemoveMemberResponse, AuthPostRevokeOtherSessionsResponse, AuthPostRevokeSessionData, AuthPostRevokeSessionResponse, AuthPostTwoFactorDisableData, AuthPostTwoFactorDisableResponse, AuthPostTwoFactorEnableData, AuthPostTwoFactorEnableResponse, AuthPostTwoFactorGenerateBackupCodesData, AuthPostTwoFactorGenerateBackupCodesResponse, AuthPostTwoFactorVerifyBackupCodeData, AuthPostTwoFactorVerifyBackupCodeResponse, AuthPostTwoFactorVerifyTotpData, AuthPostTwoFactorVerifyTotpResponse, CreateOrganizationInvitationData, CreateOrganizationInvitationResponse, GetSessionResponse, ListUserSessionsResponse, Member, SetActiveOrganizationData, SetActiveOrganizationResponse } from "../generated/api-types.d.ts";
+import { Secret } from "../secret.ts";
+import type { CookieStoreShape } from "../transport/cookie-store.ts";
+export interface DalpAuthClientConfig {
+    readonly url: string;
+    readonly apiKey?: string;
+    readonly sessionToken?: string;
+    readonly cookie?: string;
+    readonly cookieStore?: CookieStoreShape;
+    readonly organizationId?: string;
+    readonly headers?: Record<string, string>;
+    readonly fetch?: DalpFetch;
+}
+export interface DecodedDalpAuthClientConfig extends Omit<DalpAuthClientConfig, "apiKey" | "sessionToken" | "cookie"> {
+    readonly apiKey?: Secret;
+    readonly sessionToken?: Secret;
+    readonly cookie?: Secret;
+}
+export interface DalpAuthError {
+    readonly code?: string;
+    readonly message?: string;
+    readonly status?: number;
+    readonly statusText?: string;
+    readonly [key: string]: unknown;
+}
+export interface DalpAuthResult<TData = unknown, TError = DalpAuthError> {
+    readonly data: TData | null;
+    readonly error: TError | null;
+}
+export type DalpAuthOperation<TInput, TData = unknown> = (input?: TInput, options?: unknown) => Promise<DalpAuthResult<TData>>;
+export type DalpRequiredAuthOperation<TInput, TData> = (input: TInput, options?: unknown) => Promise<DalpAuthResult<TData>>;
+export type DalpNoInputAuthOperation<TData> = (options?: unknown) => Promise<DalpAuthResult<TData>>;
+export type RequestBody<TData> = TData;
+export interface DalpOrganizationMember extends Member {
+    readonly user: {
+        readonly id: string;
+        readonly email: string;
+        readonly name: string;
+        readonly image?: string;
+    };
+}
+export interface DalpOrganizationMembersQuery {
+    readonly limit?: string | number;
+    readonly offset?: string | number;
+    readonly sortBy?: string;
+    readonly sortDirection?: "asc" | "desc";
+    readonly filterField?: string;
+    readonly filterValue?: string | number | boolean | ReadonlyArray<string> | ReadonlyArray<number>;
+    readonly filterOperator?: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in" | "not_in" | "contains" | "starts_with" | "ends_with";
+    readonly organizationId?: string;
+    readonly organizationSlug?: string;
+}
+/** Invitation row from Better Auth `listInvitations` / `listUserInvitations`. */
+export interface DalpOrganizationInvitation {
+    readonly id: string;
+    readonly organizationId: string;
+    readonly email: string;
+    readonly role?: string;
+    readonly status: string;
+    readonly expiresAt: string | Date;
+}
+export interface DalpOrganizationInvitationsQuery {
+    readonly organizationId?: string;
+}
+/**
+ * Stable Better Auth operation types composed into `DalpAuthClient`.
+ *
+ * This is not a separate runtime client — `createDalpAuthClient` returns
+ * `DalpAuthClient`, which also includes wallet plugins. Keep this interface as
+ * the typed non-wallet surface so inference stays explicit; do not construct it.
+ */
+export interface DalpCliAuthClient {
+    readonly getSession: DalpNoInputAuthOperation<GetSessionResponse>;
+    readonly listSessions: DalpNoInputAuthOperation<ListUserSessionsResponse>;
+    readonly revokeSession: DalpRequiredAuthOperation<RequestBody<AuthPostRevokeSessionData>, AuthPostRevokeSessionResponse>;
+    readonly revokeOtherSessions: DalpNoInputAuthOperation<AuthPostRevokeOtherSessionsResponse>;
+    readonly apiKey: {
+        readonly list: DalpNoInputAuthOperation<AuthGetApiKeyListResponse>;
+        readonly create: DalpRequiredAuthOperation<RequestBody<AuthPostApiKeyCreateData>, AuthPostApiKeyCreateResponse>;
+        readonly delete: DalpRequiredAuthOperation<RequestBody<AuthPostApiKeyDeleteData>, AuthPostApiKeyDeleteResponse>;
+    };
+    readonly organization: {
+        readonly list: DalpNoInputAuthOperation<AuthGetOrganizationListResponse>;
+        readonly setActive: DalpRequiredAuthOperation<RequestBody<SetActiveOrganizationData>, SetActiveOrganizationResponse>;
+        readonly create: DalpRequiredAuthOperation<RequestBody<AuthPostOrganizationCreateData>, AuthPostOrganizationCreateResponse>;
+        readonly inviteMember: DalpRequiredAuthOperation<RequestBody<CreateOrganizationInvitationData>, CreateOrganizationInvitationResponse>;
+        readonly removeMember: DalpRequiredAuthOperation<RequestBody<AuthPostOrganizationRemoveMemberData>, AuthPostOrganizationRemoveMemberResponse>;
+        readonly acceptInvitation: DalpRequiredAuthOperation<RequestBody<AuthPostOrganizationAcceptInvitationData>, AuthPostOrganizationAcceptInvitationResponse>;
+        readonly listMembers: DalpRequiredAuthOperation<{
+            readonly query?: DalpOrganizationMembersQuery;
+        }, {
+            readonly members: ReadonlyArray<DalpOrganizationMember>;
+            readonly total: number;
+        }>;
+        readonly listInvitations: DalpAuthOperation<{
+            readonly query?: DalpOrganizationInvitationsQuery;
+        }, ReadonlyArray<DalpOrganizationInvitation>>;
+        readonly listUserInvitations: DalpNoInputAuthOperation<ReadonlyArray<DalpOrganizationInvitation>>;
+    };
+    readonly twoFactor: {
+        readonly enable: DalpRequiredAuthOperation<RequestBody<AuthPostTwoFactorEnableData>, AuthPostTwoFactorEnableResponse>;
+        readonly disable: DalpRequiredAuthOperation<RequestBody<AuthPostTwoFactorDisableData>, AuthPostTwoFactorDisableResponse>;
+        readonly verifyTotp: DalpRequiredAuthOperation<RequestBody<AuthPostTwoFactorVerifyTotpData>, AuthPostTwoFactorVerifyTotpResponse>;
+        readonly verifyBackupCode: DalpRequiredAuthOperation<RequestBody<AuthPostTwoFactorVerifyBackupCodeData>, AuthPostTwoFactorVerifyBackupCodeResponse>;
+        readonly generateBackupCodes: DalpRequiredAuthOperation<RequestBody<AuthPostTwoFactorGenerateBackupCodesData>, AuthPostTwoFactorGenerateBackupCodesResponse>;
+    };
+    readonly device: {
+        readonly approve: DalpRequiredAuthOperation<RequestBody<AuthPostDeviceApproveData>, AuthPostDeviceApproveResponse>;
+        readonly deny: DalpRequiredAuthOperation<RequestBody<AuthPostDeviceDenyData>, AuthPostDeviceDenyResponse>;
+    };
+}
+export declare function decodeDalpAuthClientConfig(input: DalpAuthClientConfig): Promise<DecodedDalpAuthClientConfig>;