@inversealtruism/cairn-sdk 0.1.4 → 0.2.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ __export(index_exports, {
   Http: () => Http,
   HttpError: () => HttpError,
   IndexerClient: () => IndexerClient,
+  NamesClient: () => NamesClient,
   NotInstalledError: () => NotInstalledError,
   RegistryClient: () => RegistryClient,
   SDK_VERSION: () => SDK_VERSION,
@@ -49,7 +50,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.1.4";
+var SDK_VERSION = "0.2.0";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -124,7 +125,12 @@ var ContentVerificationError = class extends CairnError {
     this.expected = expected;
   }
 };
-function mapProviderError(error) {
+var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+function mapProviderError(error, code) {
+  if (code === "USER_REJECTED" || code === "APPROVAL_CLOSED") return new UserRejectedError(error);
+  if (code === "WALLET_LOCKED") return new WalletLockedError(error);
+  if (code === "UNSUPPORTED_METHOD" || code === "UNKNOWN_KIND") return new UnsupportedMethodError(error);
+  if (code && NATIVE_CODES.has(code)) return new CairnError(error || code, { code });
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
   if (e.includes("wallet locked")) return new WalletLockedError(error);
@@ -179,6 +185,7 @@ var Http = class {
   timeoutMs;
   maxBytes;
   headers;
+  retries;
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
     const f = opts.fetch ?? globalThis.fetch;
@@ -187,6 +194,7 @@ var Http = class {
     this.timeoutMs = opts.timeoutMs ?? 15e3;
     this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
     this.headers = opts.headers ?? {};
+    this.retries = Math.min(10, Math.max(0, Math.floor(opts.retries ?? 0)));
   }
   /** Build an absolute URL from a path + optional query params. */
   url(path, query) {
@@ -223,15 +231,38 @@ var Http = class {
       clearTimeout(timer);
     }
   }
+  // A malformed 2xx body must surface as a TYPED HttpError, not a leaked SyntaxError (B10: dApp
+  // code branches on `instanceof CairnError`; a raw parse error escaped that contract).
+  parseJson(res, text, url) {
+    try {
+      return JSON.parse(text);
+    } catch (e) {
+      throw new HttpError(res.status, url, `invalid JSON body: ${text.slice(0, 120)}`);
+    }
+  }
   async getJson(path, query) {
-    const res = await this.raw("GET", path, { query });
-    if (!res.ok) throw new HttpError(res.status, this.url(path, query), await safeText(res));
-    return JSON.parse(new TextDecoder().decode(await readCapped(res, this.maxBytes)));
+    const url = this.url(path, query);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const res = await this.raw("GET", path, { query });
+        if (!res.ok) {
+          const err = new HttpError(res.status, url, await safeText(res));
+          if (!(res.status >= 500 && attempt < this.retries)) throw err;
+        } else {
+          return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
+        }
+      } catch (e) {
+        if (e instanceof HttpError && e.status < 500) throw e;
+        if (attempt >= this.retries) throw e;
+      }
+      await new Promise((r) => setTimeout(r, Math.floor(Math.random() * Math.min(4e3, 250 * 2 ** attempt))));
+    }
   }
   async postJson(path, body, headers) {
+    const url = this.url(path);
     const res = await this.raw("POST", path, { body, headers });
-    if (!res.ok) throw new HttpError(res.status, this.url(path), await safeText(res));
-    return JSON.parse(new TextDecoder().decode(await readCapped(res, this.maxBytes)));
+    if (!res.ok) throw new HttpError(res.status, url, await safeText(res));
+    return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
   }
   /** GET raw bytes (for content retrieval). Returns null on 404. */
   async getBytes(path) {
@@ -690,7 +721,7 @@ var IndexerClient = class {
           handlers.onError?.(err);
         }
         if (closed) return;
-        await new Promise((r) => setTimeout(r, 2e3));
+        await new Promise((r) => setTimeout(r, 1e3 + Math.floor(Math.random() * 2e3)));
       }
     };
     void run();
@@ -840,6 +871,96 @@ var RegistryClient = class {
   }
 };
 
+// src/names.ts
+var import_cairnx_core = require("@inversealtruism/cairnx-core");
+var nameOk = (n) => typeof n === "string" && import_cairnx_core.NAME_RE.test(n) && !import_cairnx_core.RESERVED_NAMES.has(n);
+var NamesClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Resolve a .csd name for DISPLAY (server-trusted; see the module trust note). null = unknown/invalid name. */
+  async resolve(name) {
+    if (!nameOk(name)) return null;
+    try {
+      return await this.http.getJson(`/trade/api/cairnx/resolve/${name}`);
+    } catch (e) {
+      if (e?.status === 404) return null;
+      throw e;
+    }
+  }
+  /** Full detail for one name (lease, lock, resting offer, recapture). null = not registered/invalid. */
+  async name(name) {
+    if (!nameOk(name)) return null;
+    try {
+      return await this.http.getJson(`/trade/api/cairnx/name/${name}`);
+    } catch (e) {
+      if (e?.status === 404) return null;
+      throw e;
+    }
+  }
+  /** The event history of one name (registrations, transfers, sets, renewals). null = invalid name. */
+  async nameHistory(name) {
+    if (!nameOk(name)) return null;
+    try {
+      return await this.http.getJson(`/trade/api/cairnx/name-history/${name}`);
+    } catch (e) {
+      if (e?.status === 404) return null;
+      throw e;
+    }
+  }
+  /** Reverse lookup: an address's chosen primary .csd name (null name = none set). */
+  async primary(addr) {
+    if (typeof addr !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(addr)) return null;
+    try {
+      return await this.http.getJson(`/trade/api/cairnx/primary/${addr.toLowerCase()}`);
+    } catch (e) {
+      if (e?.status === 404) return null;
+      throw e;
+    }
+  }
+  /** All names an address owns (plus its primary), as served by `/cairnx/address/:addr`. */
+  async namesOf(addr) {
+    if (typeof addr !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(addr)) return null;
+    try {
+      return await this.http.getJson(`/trade/api/cairnx/address/${addr.toLowerCase()}`);
+    } catch (e) {
+      if (e?.status === 404) return null;
+      throw e;
+    }
+  }
+  /** All registered names (display list; short-edge-cached server-side). */
+  names() {
+    return this.http.getJson(`/trade/api/cairnx/names`);
+  }
+  /** All deployed tokens. */
+  tokens() {
+    return this.http.getJson(`/trade/api/cairnx/tokens`);
+  }
+  /** One token by ticker. null = unknown/invalid ticker. */
+  async token(ticker) {
+    if (typeof ticker !== "string" || !/^[A-Z][A-Z0-9]{2,11}$/.test(ticker)) return null;
+    try {
+      return await this.http.getJson(`/trade/api/cairnx/token/${ticker}`);
+    } catch (e) {
+      if (e?.status === 404) return null;
+      throw e;
+    }
+  }
+  /** Open offers (the market's display list). */
+  offers() {
+    return this.http.getJson(`/trade/api/cairnx/offers`);
+  }
+  /** Open bids. */
+  bids() {
+    return this.http.getJson(`/trade/api/cairnx/bids`);
+  }
+  /** The full canonical CairnX state (large; prefer the scoped reads above). */
+  state() {
+    return this.http.getJson(`/trade/api/cairnx/state`);
+  }
+};
+
 // src/connect.ts
 function discoverProviders(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 1e3;
@@ -908,7 +1029,7 @@ function isInstalled() {
 }
 function unwrap(reply) {
   if (reply && reply.ok) return reply.result;
-  throw mapProviderError(reply?.error ?? "Unknown wallet error");
+  throw mapProviderError(reply?.error ?? "Unknown wallet error", reply?.code);
 }
 var WalletConnection = class {
   provider;
@@ -942,6 +1063,9 @@ var WalletConnection = class {
    * Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx).
    */
   signIn() {
+    if (typeof this.provider.signIn !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
+    }
     return Promise.resolve(this.provider.signIn()).then(unwrap);
   }
   /**
@@ -975,6 +1099,9 @@ var WalletConnection = class {
   }
   /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
   fillOffer(params) {
+    if (typeof this.provider.fillOffer !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
+    }
     return Promise.resolve(this.provider.fillOffer(params)).then(unwrap);
   }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
@@ -1129,7 +1256,7 @@ var CairnController = class {
 };
 
 // src/index.ts
-var DEFAULT_SPV_CHECKPOINT = { height: 31310, hash: "0x000000000000138bd3eee4b8d2fbacb8d5433ac3040ddbf1c45a5e3e0cc9e814" };
+var DEFAULT_SPV_CHECKPOINT = { height: 38142, hash: "0x00000000000140f023cc0ee1457a40833f2fcb4de44291b9d373e50f17b97232" };
 var DEFAULT_CAIRN = "https://cairn-substrate.com";
 var Cairn = class {
   config;
@@ -1137,6 +1264,8 @@ var Cairn = class {
   index;
   content;
   registry;
+  /** .csd names + CairnX market READS (server-trusted display reads; see names.ts trust note). */
+  names;
   board;
   wallet;
   cairnHttp;
@@ -1165,6 +1294,7 @@ var Cairn = class {
     });
     this.content = new ContentClient({ swarm: swarmHttp, indexer: indexerHttp, cairn: this.cairnHttp });
     this.registry = new RegistryClient({ baseUrl: indexer, fetch });
+    this.names = new NamesClient(this.cairnHttp);
   }
   /**
    * PoW-VERIFIED header merkle at a height (audit M3 — the no-PoW half). Lazily seeds a light
@@ -1221,6 +1351,7 @@ var Cairn = class {
   Http,
   HttpError,
   IndexerClient,
+  NamesClient,
   NotInstalledError,
   RegistryClient,
   SDK_VERSION,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FetchLike } from './http-CQsNL8w9.cjs';
-export { H as Http, a as HttpOptions } from './http-CQsNL8w9.cjs';
+import { H as Http, F as FetchLike } from './http-C9C4L4hz.cjs';
+export { a as HttpOptions } from './http-C9C4L4hz.cjs';
 import { Chain } from './chain.cjs';
 import { BoardClient } from './board.cjs';
 export { BoardItemContent, BoardWindow, ProposeInput, ProposeResult, RankedItem, SupportInput } from './board.cjs';
@@ -18,9 +18,95 @@ import '@inversealtruism/csd-crypto';
 import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
+/** `/cairnx/resolve/:name` — the display-path name→address resolution. */
+interface NameResolution {
+    ok: boolean;
+    name: string;
+    /** Resolved recipient address (owner, or the nset target). ABSENT/undefined when not resolvable. */
+    addr?: string;
+    /** How the address was derived (e.g. "owner", "nset"). */
+    via?: string;
+    lapsed?: boolean;
+    owner?: string;
+    tipHeight?: number;
+}
+/** `/cairnx/name/:name` — full name detail (lease, lock, resting offer, recapture window). */
+interface NameDetail {
+    name: string;
+    owner: string;
+    claimId: string;
+    height: number;
+    effectiveHeight: number;
+    locked: boolean;
+    paidThroughEpoch: number;
+    offer: unknown | null;
+    recapture: unknown | null;
+    tipHeight: number;
+    tipEpoch: number;
+    /** v2.5+: a revealed-but-unfinalized registration (no lease yet; not actionable). */
+    pending?: boolean;
+    lease: {
+        leased: boolean;
+        paidThroughEpoch: number;
+        graceEndEpoch: number;
+        epochsLeft: number;
+        graceEpochsLeft: number;
+        inGrace: boolean;
+        lapsed: boolean;
+    } | null;
+}
+/** One row of `/cairnx/tokens`. Amounts are DECIMAL STRINGS of base units (may exceed 2^53). */
+interface TokenInfo {
+    ticker: string;
+    deployId: string;
+    deployer: string;
+    name?: string;
+    decimals: number;
+    supply: string;
+    minted: string;
+    mint?: string;
+    mintLimit?: string;
+    height: number;
+}
+interface PrimaryName {
+    ok: boolean;
+    address: string;
+    name?: string | null;
+}
+/**
+ * Read client for the CairnX convention (names + token market) over a Cairn front door.
+ * Construct via the main `Cairn` class (`cairn.names`); all methods are read-only.
+ */
+declare class NamesClient {
+    private readonly http;
+    constructor(http: Http);
+    /** Resolve a .csd name for DISPLAY (server-trusted; see the module trust note). null = unknown/invalid name. */
+    resolve(name: string): Promise<NameResolution | null>;
+    /** Full detail for one name (lease, lock, resting offer, recapture). null = not registered/invalid. */
+    name(name: string): Promise<NameDetail | null>;
+    /** The event history of one name (registrations, transfers, sets, renewals). null = invalid name. */
+    nameHistory(name: string): Promise<unknown[] | null>;
+    /** Reverse lookup: an address's chosen primary .csd name (null name = none set). */
+    primary(addr: string): Promise<PrimaryName | null>;
+    /** All names an address owns (plus its primary), as served by `/cairnx/address/:addr`. */
+    namesOf(addr: string): Promise<unknown | null>;
+    /** All registered names (display list; short-edge-cached server-side). */
+    names(): Promise<unknown[]>;
+    /** All deployed tokens. */
+    tokens(): Promise<TokenInfo[]>;
+    /** One token by ticker. null = unknown/invalid ticker. */
+    token(ticker: string): Promise<TokenInfo | null>;
+    /** Open offers (the market's display list). */
+    offers(): Promise<unknown[]>;
+    /** Open bids. */
+    bids(): Promise<unknown[]>;
+    /** The full canonical CairnX state (large; prefer the scoped reads above). */
+    state(): Promise<unknown>;
+}
+
 /** Stable machine-readable error codes (branch on these, not the message text). */
-type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "UNKNOWN";
-declare const SDK_VERSION = "0.1.4";
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "UNKNOWN";
+declare const SDK_VERSION = "0.2.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -34,7 +120,7 @@ declare class CairnError extends Error {
     /** Relative docs path (under the SDK docs base), if any. */
     readonly docsPath?: string;
     /** The cairn-sdk version that produced this error. */
-    readonly version = "0.1.4";
+    readonly version = "0.2.0";
     constructor(shortMessage: string, opts?: CairnErrorOptions);
     /**
      * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
@@ -70,11 +156,7 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
-/**
- * Map a provider error string (from the wallet's `{ ok:false, error }`) onto a typed error. The
- * wallet's strings are stable: "rejected by user", "wallet locked", "unsupported dApp method: …".
- */
-declare function mapProviderError(error: string): CairnError;
+declare function mapProviderError(error: string, code?: string): CairnError;
 /** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
 declare function errorCode(err: unknown): CairnErrorCode;
 
@@ -132,6 +214,8 @@ declare class Cairn {
     readonly index: IndexerClient;
     readonly content: ContentClient;
     readonly registry: RegistryClient;
+    /** .csd names + CairnX market READS (server-trusted display reads; see names.ts trust note). */
+    readonly names: NamesClient;
     board: BoardClient;
     wallet?: WalletConnection;
     private readonly cairnHttp;
@@ -159,4 +243,4 @@ declare class Cairn {
     get connected(): boolean;
 }
 
-export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, SDK_VERSION, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type PrimaryName, RegistryClient, SDK_VERSION, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FetchLike } from './http-CQsNL8w9.js';
-export { H as Http, a as HttpOptions } from './http-CQsNL8w9.js';
+import { H as Http, F as FetchLike } from './http-C9C4L4hz.js';
+export { a as HttpOptions } from './http-C9C4L4hz.js';
 import { Chain } from './chain.js';
 import { BoardClient } from './board.js';
 export { BoardItemContent, BoardWindow, ProposeInput, ProposeResult, RankedItem, SupportInput } from './board.js';
@@ -18,9 +18,95 @@ import '@inversealtruism/csd-crypto';
 import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
+/** `/cairnx/resolve/:name` — the display-path name→address resolution. */
+interface NameResolution {
+    ok: boolean;
+    name: string;
+    /** Resolved recipient address (owner, or the nset target). ABSENT/undefined when not resolvable. */
+    addr?: string;
+    /** How the address was derived (e.g. "owner", "nset"). */
+    via?: string;
+    lapsed?: boolean;
+    owner?: string;
+    tipHeight?: number;
+}
+/** `/cairnx/name/:name` — full name detail (lease, lock, resting offer, recapture window). */
+interface NameDetail {
+    name: string;
+    owner: string;
+    claimId: string;
+    height: number;
+    effectiveHeight: number;
+    locked: boolean;
+    paidThroughEpoch: number;
+    offer: unknown | null;
+    recapture: unknown | null;
+    tipHeight: number;
+    tipEpoch: number;
+    /** v2.5+: a revealed-but-unfinalized registration (no lease yet; not actionable). */
+    pending?: boolean;
+    lease: {
+        leased: boolean;
+        paidThroughEpoch: number;
+        graceEndEpoch: number;
+        epochsLeft: number;
+        graceEpochsLeft: number;
+        inGrace: boolean;
+        lapsed: boolean;
+    } | null;
+}
+/** One row of `/cairnx/tokens`. Amounts are DECIMAL STRINGS of base units (may exceed 2^53). */
+interface TokenInfo {
+    ticker: string;
+    deployId: string;
+    deployer: string;
+    name?: string;
+    decimals: number;
+    supply: string;
+    minted: string;
+    mint?: string;
+    mintLimit?: string;
+    height: number;
+}
+interface PrimaryName {
+    ok: boolean;
+    address: string;
+    name?: string | null;
+}
+/**
+ * Read client for the CairnX convention (names + token market) over a Cairn front door.
+ * Construct via the main `Cairn` class (`cairn.names`); all methods are read-only.
+ */
+declare class NamesClient {
+    private readonly http;
+    constructor(http: Http);
+    /** Resolve a .csd name for DISPLAY (server-trusted; see the module trust note). null = unknown/invalid name. */
+    resolve(name: string): Promise<NameResolution | null>;
+    /** Full detail for one name (lease, lock, resting offer, recapture). null = not registered/invalid. */
+    name(name: string): Promise<NameDetail | null>;
+    /** The event history of one name (registrations, transfers, sets, renewals). null = invalid name. */
+    nameHistory(name: string): Promise<unknown[] | null>;
+    /** Reverse lookup: an address's chosen primary .csd name (null name = none set). */
+    primary(addr: string): Promise<PrimaryName | null>;
+    /** All names an address owns (plus its primary), as served by `/cairnx/address/:addr`. */
+    namesOf(addr: string): Promise<unknown | null>;
+    /** All registered names (display list; short-edge-cached server-side). */
+    names(): Promise<unknown[]>;
+    /** All deployed tokens. */
+    tokens(): Promise<TokenInfo[]>;
+    /** One token by ticker. null = unknown/invalid ticker. */
+    token(ticker: string): Promise<TokenInfo | null>;
+    /** Open offers (the market's display list). */
+    offers(): Promise<unknown[]>;
+    /** Open bids. */
+    bids(): Promise<unknown[]>;
+    /** The full canonical CairnX state (large; prefer the scoped reads above). */
+    state(): Promise<unknown>;
+}
+
 /** Stable machine-readable error codes (branch on these, not the message text). */
-type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "UNKNOWN";
-declare const SDK_VERSION = "0.1.4";
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "ACCOUNT_CHANGED" | "FIRST_PARTY_ONLY" | "RATE_LIMITED" | "APPROVAL_CLOSED" | "FORBIDDEN" | "INTERNAL" | "UNKNOWN";
+declare const SDK_VERSION = "0.2.0";
 interface CairnErrorOptions {
     code?: CairnErrorCode;
     docsPath?: string;
@@ -34,7 +120,7 @@ declare class CairnError extends Error {
     /** Relative docs path (under the SDK docs base), if any. */
     readonly docsPath?: string;
     /** The cairn-sdk version that produced this error. */
-    readonly version = "0.1.4";
+    readonly version = "0.2.0";
     constructor(shortMessage: string, opts?: CairnErrorOptions);
     /**
      * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
@@ -70,11 +156,7 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
-/**
- * Map a provider error string (from the wallet's `{ ok:false, error }`) onto a typed error. The
- * wallet's strings are stable: "rejected by user", "wallet locked", "unsupported dApp method: …".
- */
-declare function mapProviderError(error: string): CairnError;
+declare function mapProviderError(error: string, code?: string): CairnError;
 /** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
 declare function errorCode(err: unknown): CairnErrorCode;
 
@@ -132,6 +214,8 @@ declare class Cairn {
     readonly index: IndexerClient;
     readonly content: ContentClient;
     readonly registry: RegistryClient;
+    /** .csd names + CairnX market READS (server-trusted display reads; see names.ts trust note). */
+    readonly names: NamesClient;
     board: BoardClient;
     wallet?: WalletConnection;
     private readonly cairnHttp;
@@ -159,4 +243,4 @@ declare class Cairn {
     get connected(): boolean;
 }
 
-export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, SDK_VERSION, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, Http, HttpError, IndexerClient, type NameDetail, type NameResolution, NamesClient, NotInstalledError, type PrimaryName, RegistryClient, SDK_VERSION, type TokenInfo, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };