@dignetwork/dig-sdk 0.1.0 → 0.2.1

package/dist/{dig-client-entry-BIzuZ7Rs.d.ts → dig-client-entry-Bc95rd_t.d.ts}

@@ -105,6 +105,77 @@ interface ReadResult {
     /** Did the bytes decrypt+authenticate under this URN's derived key? */
     decrypted: boolean;
 }
+/**
+ * The on-chain CHIP-0007 metadata of a collection item, as returned by the dig RPC. Hashes are
+ * lowercase-hex 32-byte digests (or `null` when absent); URIs are the dig:// / https locations the
+ * bytes are served from. Mirrors the on-chain `NftMetadata` (the dig RPC decodes it from the NFT's
+ * metadata pointer). All fields optional/nullable so a non-standard metadata updater still parses.
+ */
+interface CollectionItemMetadata {
+    /** 1-based edition number within the series. */
+    edition_number?: number;
+    /** Total editions in the series. */
+    edition_total?: number;
+    /** Primary media URIs (dig:// first, https fallback by convention). */
+    data_uris?: string[];
+    /** `sha256(media_bytes)`, lowercase hex, or null. */
+    data_hash?: string | null;
+    /** CHIP-0007 metadata-JSON URIs. */
+    metadata_uris?: string[];
+    /** `sha256(metadata_json_bytes)`, lowercase hex, or null. */
+    metadata_hash?: string | null;
+    /** License document URIs. */
+    license_uris?: string[];
+    /** `sha256(license_bytes)`, lowercase hex, or null. */
+    license_hash?: string | null;
+}
+/**
+ * One NFT in a collection, resolved to its CURRENT on-chain state by `DigClient.listCollectionItems`
+ * (owner-independent: the reported owner is live, walked forward through the singleton lineage, not
+ * the mint-time owner). All hashes/ids are lowercase hex.
+ */
+interface CollectionItem {
+    /** The NFT's stable launcher id (its `nft1…` id encodes this), lowercase hex. */
+    launcher_id: string;
+    /** The current (unspent) coin id of the NFT singleton, lowercase hex. */
+    coin_id: string;
+    /** The current assigned owner DID launcher id (lowercase hex), or null when unattributed. */
+    owner_did: string | null;
+    /** The puzzle hash royalties are paid to in offer trades, lowercase hex. */
+    royalty_puzzle_hash: string;
+    /** Royalty as hundredths of a percent (300 = 3%). */
+    royalty_basis_points: number;
+    /** The CURRENT owner (p2) puzzle hash — where the NFT lives now, lowercase hex. */
+    owner_puzzle_hash: string;
+    /** The decoded on-chain CHIP-0007 metadata, or null when it does not decode. */
+    metadata: CollectionItemMetadata | null;
+}
+/** A deterministic, paginated page of collection items, from `DigClient.listCollectionItems`. */
+interface CollectionItemsPage {
+    /** This page's items, in the requested (input launcher-id) order. */
+    items: CollectionItem[];
+    /** The offset this page started at. */
+    offset: number;
+    /** The page size requested (clamped to the server cap of 200). */
+    limit: number;
+    /** Total launcher ids in the requested collection set. */
+    total: number;
+    /** The offset of the next page, or null when this is the last page. */
+    next_offset: number | null;
+}
+/** Collection-level facts from `DigClient.getCollection` — derived from the resolved item set. */
+interface CollectionMeta {
+    /** The creator DID launcher id the items AGREE on (lowercase hex), or null when mixed/none. */
+    did: string | null;
+    /** The DID the caller declared, echoed back (lowercase hex), or null. */
+    declared_did: string | null;
+    /** How many launcher ids were requested. */
+    item_count: number;
+    /** How many of those resolved to a live on-chain NFT. */
+    resolved_count: number;
+    /** The royalty (basis points) every item agrees on, or null when mixed. */
+    royalty_basis_points: number | null;
+}
 /** The two root-independent keys a URN maps to (derived client-side, nothing sent to the network). */
 interface UrnKeys {
     storeId: string;
@@ -187,13 +258,55 @@ declare class DigClient {
         root: string;
         salt?: string | null;
     }, opts?: ReadOptions): Promise<ReadResult>;
+    /**
+     * Read a collection's public, owner-independent facts (creator DID, item count, uniform royalty)
+     * from the dig RPC (`dig.getCollection`). The collection's item set is its NFT launcher ids — the
+     * authoritative, owner-independent anchor the mint produced (a DID-attributed NFT is hinted to its
+     * OWNER at mint, not to the creator DID, so launcher ids — not the DID — are the read key). Pass
+     * the optional `did` to have it echoed back and recorded as the declared creator.
+     *
+     * No wallet, no read-crypto wasm — a plain JSON-RPC read. Throws a coded {@link DigSdkError} on a
+     * transport/RPC failure (never a "not found": an empty/partly-confirmed set just resolves to fewer
+     * items).
+     *
+     * @example
+     * const meta = await dig.getCollection({ launcherIds: ["ab…", "cd…"], did: "ef…" });
+     * console.log(meta.resolved_count, meta.royalty_basis_points);
+     */
+    getCollection(input: {
+        launcherIds: string[];
+        did?: string | null;
+    }, opts?: ReadOptions): Promise<CollectionMeta>;
+    /**
+     * Read a deterministic, paginated page of a collection's items (`dig.listCollectionItems`), each
+     * resolved to its CURRENT on-chain state — current owner, royalty, and CHIP-0007 metadata — by the
+     * RPC walking the singleton lineage forward to the live tip (so the owner is never the stale
+     * mint-time owner). Items come back in the input launcher-id order. `limit` is clamped to the
+     * server cap (200); `offset` defaults to 0.
+     *
+     * Throws a coded {@link DigSdkError} on a transport/RPC failure.
+     *
+     * @example
+     * let page = await dig.listCollectionItems({ launcherIds, limit: 50 });
+     * for (const item of page.items) console.log(item.launcher_id, item.owner_puzzle_hash);
+     * // page.next_offset is null on the last page.
+     */
+    listCollectionItems(input: {
+        launcherIds: string[];
+        offset?: number;
+        limit?: number;
+    }, opts?: ReadOptions): Promise<CollectionItemsPage>;
     private fetchCiphertext;
     private rpcCall;
 }
 
-/** SHA-256 (lowercase hex) of vendor/dig_client_bg.wasm — the SRI digest. Fail closed on mismatch. */
-declare const DIG_CLIENT_WASM_SHA256 = "ff486be806f908a2a90780e499a04dbd34e10e3b97be0470cb9ee841a1e49e77";
-/** Optional explicit wasm inputs, for environments where auto-resolution can't find vendor/. */
+/**
+ * SHA-256 (lowercase hex) of `@dignetwork/dig-client`'s `dig_client_bg.wasm` — the SRI digest. It
+ * is the canonical trust anchor (pinned regardless of the npm semver), mirrored by the package's
+ * `integrity.json` `sha256`. Fail closed on a mismatch.
+ */
+declare const DIG_CLIENT_WASM_SHA256 = "8c983561eabca34778abf698ca7c2fba36117f87282ca649079599ef7d1b1156";
+/** Optional explicit wasm inputs, for environments where package resolution can't reach the wasm. */
 interface WasmConfig {
     /**
      * The wasm bytes (already loaded). When provided, SRI is still enforced unless `skipIntegrity`.
@@ -201,13 +314,13 @@ interface WasmConfig {
      */
     wasmBytes?: BufferSource;
     /**
-     * URL to the wasm-bindgen glue module (vendor/dig_client.mjs) for browser dynamic import. When
-     * omitted in a browser, the loader tries to import the glue relative to this module.
+     * URL to the wasm-bindgen `web` glue module for browser dynamic import. When omitted in a browser,
+     * the loader imports `@dignetwork/dig-client/web` (the bundler resolves it).
      */
     glueUrl?: string;
     /**
      * URL to fetch the wasm bytes from (browser) when `wasmBytes` is not supplied. The fetched bytes
-     * are SRI-verified before init.
+     * are SRI-verified before init. Defaults to the package's `dig_client_bg.wasm`.
      */
     wasmUrl?: string;
     /** Skip the SRI check. Only for tests / trusted custom builds — NOT recommended. */
@@ -260,4 +373,4 @@ declare function reconstructUrn(storeId: string, resourceKey: string): string;
  */
 declare function reconstructUrnWithRoot(storeId: string, root: string, resourceKey: string): string;
 
-export { DEFAULT_RPC as D, type InjectedChiaProvider as I, type ParsedUrn as P, type ReadOptions as R, type SignResult as S, type UrnKeys as U, type WalletBackend as W, type WalletSession as a, DIG_CLIENT_WASM_SHA256 as b, DigClient as c, type DigClientOptions as d, type DigClientWasm as e, type ReadResult as f, type WasmConfig as g, configureWasm as h, isUrn as i, reconstructUrnWithRoot as j, loadDigClientWasm as l, parseUrn as p, reconstructUrn as r };
+export { type CollectionItem as C, DEFAULT_RPC as D, type InjectedChiaProvider as I, type ParsedUrn as P, type ReadOptions as R, type SignResult as S, type UrnKeys as U, type WalletBackend as W, type WalletSession as a, type CollectionItemMetadata as b, type CollectionItemsPage as c, type CollectionMeta as d, DIG_CLIENT_WASM_SHA256 as e, DigClient as f, type DigClientOptions as g, type DigClientWasm as h, type ReadResult as i, type WasmConfig as j, configureWasm as k, isUrn as l, loadDigClientWasm as m, reconstructUrnWithRoot as n, parseUrn as p, reconstructUrn as r };

package/dist/dig-client.cjs

@@ -1,8 +1,28 @@
 'use strict';
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// src/errors.ts
+var DIG_SDK_ERROR_BRAND = "__dignetwork_dig_sdk_error__";
+var DigSdkError = class _DigSdkError extends Error {
+  constructor(code, message, context = {}, options = {}) {
+    super(message);
+    this.name = "DigSdkError";
+    this.code = code;
+    this.context = context;
+    if (options.cause !== void 0) {
+      this.cause = options.cause;
+    }
+    Object.defineProperty(this, DIG_SDK_ERROR_BRAND, { value: true, enumerable: false });
+    Object.setPrototypeOf(this, _DigSdkError.prototype);
+  }
+  /** A JSON-friendly view of the error: `{ code, message, context }`. */
+  toJSON() {
+    return { code: this.code, message: this.message, context: this.context };
+  }
+};
+
 // src/loader.ts
-var DIG_CLIENT_WASM_SHA256 = "ff486be806f908a2a90780e499a04dbd34e10e3b97be0470cb9ee841a1e49e77";
+var DIG_CLIENT_WASM_SHA256 = "8c983561eabca34778abf698ca7c2fba36117f87282ca649079599ef7d1b1156";
 var _config = {};
 var _ready = null;
 function configureWasm(config) {
@@ -26,49 +46,62 @@ async function sha256Hex(bytes) {
 function assertIntegrity(hex) {
   if (_config.skipIntegrity) return;
   if (hex !== DIG_CLIENT_WASM_SHA256) {
-    throw new Error(
-      `dig-client wasm integrity check failed \u2014 refusing to run unverified crypto (expected ${DIG_CLIENT_WASM_SHA256}, got ${hex}).`
+    throw new DigSdkError(
+      "WASM_INTEGRITY",
+      `dig-client wasm integrity check failed \u2014 refusing to run unverified crypto (expected ${DIG_CLIENT_WASM_SHA256}, got ${hex}).`,
+      { expected: DIG_CLIENT_WASM_SHA256, actual: hex }
     );
   }
 }
 async function loadNode() {
+  const { createRequire } = await import('module');
   const { readFile } = await import('fs/promises');
-  const { fileURLToPath, pathToFileURL } = await import('url');
-  const path = await import('path');
-  const here = path.dirname(fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('dig-client.cjs', document.baseURI).href))));
-  const vendorDir = path.resolve(here, "..", "vendor");
-  const wasmPath = path.join(vendorDir, "dig_client_bg.wasm");
-  const gluePath = path.join(vendorDir, "dig_client.mjs");
+  const require2 = createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('dig-client.cjs', document.baseURI).href)));
+  const wasmPath = require2.resolve("@dignetwork/dig-client/dig_client_bg.wasm");
   const buf = await readFile(wasmPath);
   const bytes = new Uint8Array(buf.byteLength);
   bytes.set(buf);
-  return { glueHref: pathToFileURL(gluePath).href, bytes };
+  assertIntegrity(await sha256Hex(bytes));
+  const mod = await import('@dignetwork/dig-client/node');
+  return mod;
 }
 async function loadBrowser() {
-  const glueHref = _config.glueUrl ?? new URL("../vendor/dig_client.mjs", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('dig-client.cjs', document.baseURI).href))).href;
-  let bytes;
-  if (_config.wasmBytes) {
-    bytes = _config.wasmBytes;
+  const glueHref = _config.glueUrl ?? "@dignetwork/dig-client/web";
+  const mod = await import(
+    /* @vite-ignore */
+    glueHref
+  );
+  if (typeof mod.default !== "function") {
+    throw new DigSdkError(
+      "WASM_LOAD_FAILED",
+      "dig-client web build exposed no init function (unexpected module shape)",
+      {}
+    );
+  }
+  if (_config.wasmBytes || _config.wasmUrl) {
+    let bytes;
+    if (_config.wasmBytes) {
+      bytes = _config.wasmBytes;
+    } else {
+      const wasmUrl = _config.wasmUrl;
+      const res = await fetch(wasmUrl);
+      if (!res.ok)
+        throw new DigSdkError("WASM_LOAD_FAILED", `dig-client wasm fetch failed (${res.status})`, {
+          httpStatus: res.status,
+          wasmUrl
+        });
+      bytes = await res.arrayBuffer();
+    }
+    assertIntegrity(await sha256Hex(bytes));
+    await mod.default({ module_or_path: bytes });
   } else {
-    const wasmUrl = _config.wasmUrl ?? new URL("../vendor/dig_client_bg.wasm", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('dig-client.cjs', document.baseURI).href))).href;
-    const res = await fetch(wasmUrl);
-    if (!res.ok) throw new Error(`dig-client wasm fetch failed (${res.status})`);
-    bytes = await res.arrayBuffer();
+    await mod.default();
   }
-  return { glueHref, bytes };
+  return mod;
 }
 function loadDigClientWasm() {
   if (_ready) return _ready;
-  _ready = (async () => {
-    const { glueHref, bytes } = isNode ? await loadNode() : await loadBrowser();
-    assertIntegrity(await sha256Hex(bytes));
-    const mod = await import(
-      /* @vite-ignore */
-      glueHref
-    );
-    await mod.default({ module_or_path: bytes });
-    return mod;
-  })().catch((e) => {
+  _ready = (isNode ? loadNode() : loadBrowser()).catch((e) => {
     _ready = null;
     throw e;
   });
@@ -81,8 +114,10 @@ function parseUrn(raw) {
   const s = String(raw ?? "").trim();
   const m = URN_RE.exec(s);
   if (!m) {
-    throw new Error(
-      "Not a valid dig URN (expected urn:dig:chia:<store-id>[:<root>]/<path>[?salt=<hex>])."
+    throw new DigSdkError(
+      "INVALID_ARGUMENT",
+      "Not a valid dig URN (expected urn:dig:chia:<store-id>[:<root>]/<path>[?salt=<hex>]).",
+      { value: s, expected: "urn:dig:chia:<store-id>[:<root>]/<path>[?salt=<hex>]" }
     );
   }
   return {
@@ -174,8 +209,10 @@ var DigClient = class {
     const effSalt = input.salt ?? parsed.salt ?? null;
     const effRoot = input.root ?? parsed.root ?? null;
     if (!effRoot) {
-      throw new Error(
-        "a confirmed on-chain root is required to read content (pass { root } or use a root-pinned URN)"
+      throw new DigSdkError(
+        "ROOT_REQUIRED",
+        "a confirmed on-chain root is required to read content (pass { root } or use a root-pinned URN)",
+        { urn: input.urn }
       );
     }
     return this.readResource(
@@ -187,8 +224,10 @@ var DigClient = class {
   async readText(input, opts = {}) {
     const r = await this.read(input, opts);
     if (!r.decrypted) {
-      throw new Error(
-        "resource did not decrypt under this URN \u2014 wrong store/key/salt, or a decoy response"
+      throw new DigSdkError(
+        "DECRYPT_FAILED",
+        "resource did not decrypt under this URN \u2014 wrong store/key/salt, or a decoy response",
+        { urn: input.urn }
       );
     }
     return new TextDecoder().decode(r.bytes);
@@ -237,6 +276,62 @@ var DigClient = class {
       };
     }
   }
+  /**
+   * Read a collection's public, owner-independent facts (creator DID, item count, uniform royalty)
+   * from the dig RPC (`dig.getCollection`). The collection's item set is its NFT launcher ids — the
+   * authoritative, owner-independent anchor the mint produced (a DID-attributed NFT is hinted to its
+   * OWNER at mint, not to the creator DID, so launcher ids — not the DID — are the read key). Pass
+   * the optional `did` to have it echoed back and recorded as the declared creator.
+   *
+   * No wallet, no read-crypto wasm — a plain JSON-RPC read. Throws a coded {@link DigSdkError} on a
+   * transport/RPC failure (never a "not found": an empty/partly-confirmed set just resolves to fewer
+   * items).
+   *
+   * @example
+   * const meta = await dig.getCollection({ launcherIds: ["ab…", "cd…"], did: "ef…" });
+   * console.log(meta.resolved_count, meta.royalty_basis_points);
+   */
+  async getCollection(input, opts = {}) {
+    const rpc = opts.rpc ?? this.rpc;
+    const params = { launcher_ids: input.launcherIds };
+    if (input.did) params.did = input.did;
+    const r = await this.rpcCall(rpc, "dig.getCollection", params);
+    if (!r)
+      throw new DigSdkError(
+        "RPC_MALFORMED_RESPONSE",
+        "The content network returned no collection facts for this request.",
+        { rpcMethod: "dig.getCollection" }
+      );
+    return r;
+  }
+  /**
+   * Read a deterministic, paginated page of a collection's items (`dig.listCollectionItems`), each
+   * resolved to its CURRENT on-chain state — current owner, royalty, and CHIP-0007 metadata — by the
+   * RPC walking the singleton lineage forward to the live tip (so the owner is never the stale
+   * mint-time owner). Items come back in the input launcher-id order. `limit` is clamped to the
+   * server cap (200); `offset` defaults to 0.
+   *
+   * Throws a coded {@link DigSdkError} on a transport/RPC failure.
+   *
+   * @example
+   * let page = await dig.listCollectionItems({ launcherIds, limit: 50 });
+   * for (const item of page.items) console.log(item.launcher_id, item.owner_puzzle_hash);
+   * // page.next_offset is null on the last page.
+   */
+  async listCollectionItems(input, opts = {}) {
+    const rpc = opts.rpc ?? this.rpc;
+    const params = { launcher_ids: input.launcherIds };
+    if (input.offset !== void 0) params.offset = input.offset;
+    if (input.limit !== void 0) params.limit = input.limit;
+    const r = await this.rpcCall(rpc, "dig.listCollectionItems", params);
+    if (!r)
+      throw new DigSdkError(
+        "RPC_MALFORMED_RESPONSE",
+        "The content network returned no collection items for this request.",
+        { rpcMethod: "dig.listCollectionItems" }
+      );
+    return r;
+  }
   // Stream the FULL ciphertext for a resource from the RPC by retrieval key, reassembling 3-MiB
   // chunks. A null result is a TRANSPORT failure, never a presence judgment.
   async fetchCiphertext(storeId, rk, root, rpc) {
@@ -253,7 +348,12 @@ var DigClient = class {
         offset,
         length: RPC_CHUNK_BYTES
       });
-      if (!r) throw new Error("The content network returned no data for this request.");
+      if (!r)
+        throw new DigSdkError(
+          "RPC_MALFORMED_RESPONSE",
+          "The content network returned no data for this request.",
+          { rpcMethod: "dig.getContent" }
+        );
       if (total === null) {
         total = r.total_length >>> 0;
         buf = new Uint8Array(total);
@@ -270,7 +370,8 @@ var DigClient = class {
     }
     return { ciphertext: buf ?? new Uint8Array(0), proof, chunkLens };
   }
-  // One JSON-RPC 2.0 call. Throws on transport failure or a JSON-RPC error; returns `result`.
+  // One JSON-RPC 2.0 call. Throws a coded DigSdkError on transport failure (RPC_TRANSPORT) or a
+  // JSON-RPC/HTTP error (RPC_ERROR, carrying rpcMethod/httpStatus/rpcCode context); returns `result`.
   async rpcCall(rpc, method, params) {
     let res;
     try {
@@ -279,12 +380,26 @@ var DigClient = class {
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
       });
-    } catch {
-      throw new Error("Could not reach the content network. Check your connection and try again.");
+    } catch (e) {
+      throw new DigSdkError(
+        "RPC_TRANSPORT",
+        "Could not reach the content network. Check your connection and try again.",
+        { rpcMethod: method },
+        { cause: e }
+      );
     }
-    if (!res.ok) throw new Error(`dig RPC ${method} failed (${res.status})`);
+    if (!res.ok)
+      throw new DigSdkError("RPC_ERROR", `dig RPC ${method} failed (${res.status})`, {
+        rpcMethod: method,
+        httpStatus: res.status
+      });
     const json = await res.json();
-    if (json && json.error) throw new Error(`dig RPC ${method}: ${json.error.message ?? "error"}`);
+    if (json && json.error)
+      throw new DigSdkError(
+        "RPC_ERROR",
+        `dig RPC ${method}: ${json.error.message ?? "error"}`,
+        { rpcMethod: method, rpcCode: json.error.code }
+      );
     return json ? json.result ?? null : null;
   }
 };
@@ -292,7 +407,11 @@ function decryptResourceChunks(wasm, keyHex, ciphertext, chunkLens) {
   const lens = chunkLens && chunkLens.length ? chunkLens : [ciphertext.length];
   const total = lens.reduce((a, n) => a + n, 0);
   if (total !== ciphertext.length) {
-    throw new Error("served ciphertext length does not match chunk lengths");
+    throw new DigSdkError(
+      "RPC_MALFORMED_RESPONSE",
+      "served ciphertext length does not match chunk lengths",
+      { rpcMethod: "dig.getContent", expected: String(total), actual: String(ciphertext.length) }
+    );
   }
   if (lens.length === 1) return wasm.decryptChunk(keyHex, ciphertext);
   const parts = [];
@@ -311,7 +430,8 @@ function decryptResourceChunks(wasm, keyHex, ciphertext, chunkLens) {
 }
 function undefinedFetch() {
   return (() => {
-    throw new Error(
+    throw new DigSdkError(
+      "INVALID_ARGUMENT",
       "No global fetch available. Pass { fetch } to DigClient (Node < 18 needs a fetch polyfill)."
     );
   });