@settlemint/dalp-sdk 3.1.10 → 3.1.11-main.33556892334

package/README.md

@@ -1,206 +1,140 @@
-<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
+
+The DALP SDK is a Promise-based client generated from the canonical v2 OpenAPI
+declaration ([Hey API](https://heyapi.dev/)), validated at runtime with
+[zod](https://zod.dev/). It is Effect-free: no `Effect` values, no branded
+Effect Schema identifiers on the wire.
 
-## 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.token.list({ query: {} }, { signal });
 ```
 
-## Auth Client
-
-Use `createDalpAuthClient` for Better Auth operations such as sign-up, session listing, organization management, API
-keys, device authorization, and wallet verification setup.
+`createDalpClient` owns shared transport policy once: the credential mechanism
+(session cookie in the browser and on SSR, or an `X-Api-Key` header for
+server/CLI callers — never both from the same runtime), organization headers,
+idempotency keys, `Prefer`, conditional `If-None-Match` / ETag reuse, custom fetch
+injection, and abort propagation. See the "Credential ownership matrix" JSDoc
+on `createDalpClient` in `src/client/factory.ts` for which runtime may use
+which credential.
 
-```typescript
-import { createDalpAuthClient } from "@settlemint/dalp-sdk";
+Response decoding is strict: every generated operation parses its response
+against the declared zod schema and throws on a mismatch.
 
-const auth = createDalpAuthClient({
-  url: "https://dalp.example.com",
-  apiKey: "sm_dalp_...",
-  organizationId: "org_...",
-});
+### Conditional requests and ETags
 
-const apiKeys = await auth.apiKey.list();
-```
+`createDalpClient` installs `If-None-Match` / 304 interceptors that reuse a
+held body when the server returns a matching ETag. Server ETags must be
+**strong content digests** computed **after authorization** inside the
+requester's partition. The dapi response cache guarantees this: it hashes the
+serialized body after the request-context middleware has authenticated the
+session. 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.
 
-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.
+Identity changes that do not ride this client (browser sign-out, organization
+switch) must call `clearConditionalRequestStore(client)` so a later GET cannot
+send another session's `If-None-Match`.
 
-```typescript
-import { createDalpPlatformClient } from "@settlemint/dalp-sdk";
+```ts
+import { clearConditionalRequestStore, createDalpClient } from "@settlemint/dalp-sdk";
 
-const platform = createDalpPlatformClient({
-  url: "https://dalp.example.com",
-});
-
-await platform.auth.signUp.email({
-  email: "user@example.com",
-  password: "Password123!",
-  name: "Example User",
-});
-
-const sessionCookie = platform.cookieStore.header;
+clearConditionalRequestStore(dalp);
 ```
 
-### 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" });
-```
+## Generated operations
 
-```typescript
-// Enable wallet pincode protection
-await auth.wallet.pincode.enable({ pincode: "1234", password: "..." });
+```ts
+import { createClient } from "@settlemint/dalp-sdk/operations";
 ```
 
-## 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
-});
+`./operations` re-exports the generated v2 operation functions and generated
+client primitives (585 operations) on their own subpath, so a consumer who
+only signs webhooks or builds a client never loads that module. Pair it with
+`createDalpClient` from the package root.
+
+## Scalars
+
+Custom wire formats — BigDecimal amounts, EVM addresses, and the
+`OrganizationId` entity brand — are not expressed structurally in the
+generated OpenAPI spec (it carries no `format:`/`x-` extension for them), so
+each has a hand-maintained wrapper under `src/scalars/`:
+`big-decimal.ts`, `ethereum-address.ts`, `exchange-rates.ts`,
+`organization-id.ts`. `OrganizationId` is the only entity ID branded
+end-to-end across the platform (see `AGENTS.md`); every other identifier
+crossing this SDK's boundary is a plain string. `tools/scripts/src/check-sdk-scalar-coverage.ts`
+gates new generated scalar-shaped symbols against a curated allowlist so a
+spec change that introduces a new custom scalar fails the build instead of
+shipping unwrapped.
+
+## React Query
+
+```ts
+import { tokenListOptions } from "@settlemint/dalp-sdk/react-query";
 ```
 
-## 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-query` re-exports the generated TanStack Query option factories
+(`queryOptions`, `infiniteOptions`, `mutationOptions`) — spread into your own
+hooks; the generator emits no hooks itself. This is the only module that
+imports `@tanstack/react-query`, so that peer dependency stays optional for
+non-React consumers.
 
-## Security
+## Auth
 
-- **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
+```ts
+import { createDalpAuthClient } from "@settlemint/dalp-sdk/auth";
+```
 
-## Errors
+The generated SDK already exposes every auth REST operation; `./auth` covers
+what a REST call cannot express — the session/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 `has-permission`. Off
+the package root because it costs roughly 70 KiB of Better Auth a
+pure-operations consumer should not pay.
 
-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.
+## Bundler and paymaster
 
-## License
+```ts
+import { createDalpBundlerClient } from "@settlemint/dalp-sdk/bundler";
+```
 
-This project is licensed under the **SettleMint Commercial Customer Source License**. See the LICENSE file included in the package for full terms.
+`createDalpBundlerClient` retains the eight established ERC-4337 method names
+while calling the generated v2 REST resources underneath. The SDK accepts
+EntryPoint v0.9 `viem` shapes and returns the corresponding typed values.
+
+## Webhooks and transaction wait
+
+- `./verify-webhook` — verify an inbound webhook signature.
+- `./sign-webhook-receipt` — sign a webhook delivery receipt (Node-only).
+- `./wait-for-transaction` — bounded poll for on-chain transaction settlement;
+  calls a generated operation and so inherits the generated validator
+  module's full weight.
+
+## Package root
+
+The package root (`@settlemint/dalp-sdk`) stays deliberately small — the
+client factory, its config and errors, cookie-store transport, SSE lifecycle
+handling, and SDK version constants — so a consumer
+who only needs to call operations never pays for auth, bundler, react-query,
+or webhook code. See the `@module` doc at the top of `src/index.ts` for the
+current weight breakdown per subpath.
+
+## Migrating from the Effect client
+
+Prior major versions exposed an `Effect`-returning client
+(`makeDalpEffectClient`, `makeDalpApiLayer`, `DalpEffectClient`) alongside the
+Promise client. That dual surface, the `contracts/` schema re-exports, and
+`makeDalpPlatformClient`/`waitForTransactionEffect` are removed — see
+`CHANGELOG.md` and the
+[v2 migration guide](../docs/content/docs/api-reference/reference/v2-migration.mdx).
+No published consumer depended on the Effect surface, so this ships without a
+major version bump.

package/dist/auth/client.d.ts

@@ -0,0 +1,115 @@
+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/types.gen.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 extends {
+    readonly body?: unknown;
+}> = NonNullable<TData["body"]>;
+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>;