zerc20-client-sdk 0.1.13 → 0.1.14

package/dist/ic/connections.d.ts

@@ -14,15 +14,110 @@ export interface CachedStealthClientOptions extends StealthClientConnectionOptio
     cacheKey?: string;
     cache?: Map<string, Promise<StealthCanisterClient>>;
 }
-export declare function isLocalReplica(url: string): boolean;
-export declare function createStealthClient(options: StealthClientConnectionOptions): Promise<StealthCanisterClient>;
-export declare function getStealthClientFromConfig(options: CachedStealthClientOptions): Promise<StealthCanisterClient>;
-export declare function clearStealthClientCache(cache?: Map<string, Promise<StealthCanisterClient>>, key?: string): void;
 export interface DeciderClientConfig extends DeciderClientOptions {
     baseUrl: string;
     cacheKey?: string;
     cache?: Map<string, HttpDeciderClient>;
 }
+export declare function isLocalReplica(url: string): boolean;
+/**
+ * Manager for caching StealthCanisterClient instances.
+ */
+export declare class StealthClientCacheManager {
+    private readonly cache;
+    /**
+     * Gets or creates a cached stealth client.
+     * If creation fails, the failed promise is removed from the cache to allow retry.
+     */
+    getOrCreate(options: StealthClientConnectionOptions, cacheKey?: string): Promise<StealthCanisterClient>;
+    /**
+     * Clears a specific entry or all entries from the cache.
+     */
+    clear(key?: string): void;
+    /**
+     * Resets the cache to its initial empty state.
+     * Alias for clear() - useful for testing.
+     */
+    reset(): void;
+    /**
+     * Returns the number of cached entries.
+     */
+    size(): number;
+    /**
+     * Returns true if the cache contains an entry for the given key.
+     */
+    has(key: string): boolean;
+}
+/**
+ * Manager for caching HttpDeciderClient instances.
+ */
+export declare class DeciderClientCacheManager {
+    private readonly cache;
+    /**
+     * Gets or creates a cached decider client.
+     */
+    getOrCreate(baseUrl: string, options?: DeciderClientOptions, cacheKey?: string): HttpDeciderClient;
+    /**
+     * Clears a specific entry or all entries from the cache.
+     */
+    clear(key?: string): void;
+    /**
+     * Resets the cache to its initial empty state.
+     * Alias for clear() - useful for testing.
+     */
+    reset(): void;
+    /**
+     * Returns the number of cached entries.
+     */
+    size(): number;
+    /**
+     * Returns true if the cache contains an entry for the given key.
+     */
+    has(key: string): boolean;
+}
+/**
+ * Creates a new stealth client without caching.
+ */
+export declare function createStealthClient(options: StealthClientConnectionOptions): Promise<StealthCanisterClient>;
+/**
+ * Gets a stealth client from cache or creates a new one.
+ * Supports custom cache via options.
+ * If creation fails, the failed promise is removed from the cache to allow retry.
+ */
+export declare function getStealthClientFromConfig(options: CachedStealthClientOptions): Promise<StealthCanisterClient>;
+/**
+ * Clears the stealth client cache.
+ * @param cache Optional custom cache to clear. Defaults to the global cache.
+ * @param key Optional specific key to clear. If not provided, clears all entries.
+ */
+export declare function clearStealthClientCache(cache?: Map<string, Promise<StealthCanisterClient>>, key?: string): void;
+/**
+ * Resets the default stealth client cache to its initial state.
+ * Useful for testing.
+ */
+export declare function resetStealthClientCache(): void;
+/**
+ * Returns the default stealth client cache manager.
+ */
+export declare function getDefaultStealthClientCacheManager(): StealthClientCacheManager;
+/**
+ * Gets a decider client from cache or creates a new one.
+ * Supports custom cache via config.
+ */
 export declare function getDeciderClient(config: DeciderClientConfig): HttpDeciderClient;
+/**
+ * Clears the decider client cache.
+ * @param cache Optional custom cache to clear. Defaults to the global cache.
+ * @param key Optional specific key to clear. If not provided, clears all entries.
+ */
 export declare function clearDeciderClientCache(cache?: Map<string, HttpDeciderClient>, key?: string): void;
+/**
+ * Resets the default decider client cache to its initial state.
+ * Useful for testing.
+ */
+export declare function resetDeciderClientCache(): void;
+/**
+ * Returns the default decider client cache manager.
+ */
+export declare function getDefaultDeciderClientCacheManager(): DeciderClientCacheManager;
 //# sourceMappingURL=connections.d.ts.map

package/dist/ic/connections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/ic/connections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAI9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,8BAA8B;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,0BAA2B,SAAQ,8BAA8B;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC,CAAC;CACrD;AAID,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEnD;AA0BD,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,qBAAqB,CAAC,CAEhC;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAmBhC;AAED,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC,EACnD,GAAG,CAAC,EAAE,MAAM,GACX,IAAI,CAON;AAED,MAAM,WAAW,mBAAoB,SAAQ,oBAAoB;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CACxC;AAID,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,mBAAmB,GAAG,iBAAiB,CAQ/E;AAED,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,EACtC,GAAG,CAAC,EAAE,MAAM,GACX,IAAI,CAON"}
+{"version":3,"file":"connections.d.ts","sourceRoot":"","sources":["../../src/ic/connections.ts"],"names":[],"mappings":"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"}

package/dist/ic/connections.js

@@ -2,7 +2,9 @@ import { HttpAgent } from "@dfinity/agent";
 import { Principal } from "@dfinity/principal";
 import { HttpDeciderClient } from "../decider/prover.js";
 import { StealthCanisterClient } from "./client.js";
-const defaultStealthCache = new Map();
+// ============================================================================
+// Utilities
+// ============================================================================
 export function isLocalReplica(url) {
     return /localhost|127\.0\.0\.1/.test(url);
 }
@@ -26,49 +28,239 @@ async function instantiateStealthClient(options) {
     const keyManagerId = Principal.fromText(options.keyManagerCanisterId);
     return new StealthCanisterClient(agent, storageId, keyManagerId);
 }
+// ============================================================================
+// StealthClientCacheManager
+// ============================================================================
+/**
+ * Manager for caching StealthCanisterClient instances.
+ */
+export class StealthClientCacheManager {
+    cache = new Map();
+    /**
+     * Gets or creates a cached stealth client.
+     * If creation fails, the failed promise is removed from the cache to allow retry.
+     */
+    async getOrCreate(options, cacheKey) {
+        const key = cacheKey ??
+            `${options.icReplicaUrl}|${options.storageCanisterId}|${options.keyManagerCanisterId}`;
+        if (!this.cache.has(key)) {
+            const promise = instantiateStealthClient(options).catch((error) => {
+                this.cache.delete(key);
+                throw error;
+            });
+            this.cache.set(key, promise);
+        }
+        return this.cache.get(key);
+    }
+    /**
+     * Clears a specific entry or all entries from the cache.
+     */
+    clear(key) {
+        if (key) {
+            this.cache.delete(key);
+            return;
+        }
+        this.cache.clear();
+    }
+    /**
+     * Resets the cache to its initial empty state.
+     * Alias for clear() - useful for testing.
+     */
+    reset() {
+        this.cache.clear();
+    }
+    /**
+     * Returns the number of cached entries.
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Returns true if the cache contains an entry for the given key.
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+}
+// ============================================================================
+// DeciderClientCacheManager
+// ============================================================================
+/**
+ * Manager for caching HttpDeciderClient instances.
+ */
+export class DeciderClientCacheManager {
+    cache = new Map();
+    /**
+     * Gets or creates a cached decider client.
+     */
+    getOrCreate(baseUrl, options, cacheKey) {
+        const key = cacheKey ?? baseUrl;
+        if (!this.cache.has(key)) {
+            this.cache.set(key, new HttpDeciderClient(baseUrl, options));
+        }
+        return this.cache.get(key);
+    }
+    /**
+     * Clears a specific entry or all entries from the cache.
+     */
+    clear(key) {
+        if (key) {
+            this.cache.delete(key);
+            return;
+        }
+        this.cache.clear();
+    }
+    /**
+     * Resets the cache to its initial empty state.
+     * Alias for clear() - useful for testing.
+     */
+    reset() {
+        this.cache.clear();
+    }
+    /**
+     * Returns the number of cached entries.
+     */
+    size() {
+        return this.cache.size;
+    }
+    /**
+     * Returns true if the cache contains an entry for the given key.
+     */
+    has(key) {
+        return this.cache.has(key);
+    }
+}
+// ============================================================================
+// Default Singletons
+// ============================================================================
+const defaultStealthCacheManager = new StealthClientCacheManager();
+const defaultDeciderCacheManager = new DeciderClientCacheManager();
+// ============================================================================
+// Backward-Compatible Functions (Stealth Client)
+// ============================================================================
+/**
+ * Creates a new stealth client without caching.
+ */
 export async function createStealthClient(options) {
     return instantiateStealthClient(options);
 }
+/**
+ * Gets a stealth client from cache or creates a new one.
+ * Supports custom cache via options.
+ * If creation fails, the failed promise is removed from the cache to allow retry.
+ */
 export async function getStealthClientFromConfig(options) {
-    const cache = options.cache ?? defaultStealthCache;
-    const cacheKey = options.cacheKey ??
-        `${options.icReplicaUrl}|${options.storageCanisterId}|${options.keyManagerCanisterId}`;
-    if (!cache.has(cacheKey)) {
-        cache.set(cacheKey, instantiateStealthClient({
-            icReplicaUrl: options.icReplicaUrl,
-            storageCanisterId: options.storageCanisterId,
-            keyManagerCanisterId: options.keyManagerCanisterId,
-            agent: options.agent,
-            agentOptions: options.agentOptions,
-            fetchRootKey: options.fetchRootKey,
-        }));
-    }
-    return cache.get(cacheKey);
+    // If custom cache is provided, use direct Map operations for backward compatibility
+    if (options.cache) {
+        const cache = options.cache;
+        const cacheKey = options.cacheKey ??
+            `${options.icReplicaUrl}|${options.storageCanisterId}|${options.keyManagerCanisterId}`;
+        if (!cache.has(cacheKey)) {
+            const promise = instantiateStealthClient({
+                icReplicaUrl: options.icReplicaUrl,
+                storageCanisterId: options.storageCanisterId,
+                keyManagerCanisterId: options.keyManagerCanisterId,
+                agent: options.agent,
+                agentOptions: options.agentOptions,
+                fetchRootKey: options.fetchRootKey,
+            }).catch((error) => {
+                cache.delete(cacheKey);
+                throw error;
+            });
+            cache.set(cacheKey, promise);
+        }
+        return cache.get(cacheKey);
+    }
+    // Use default manager
+    return defaultStealthCacheManager.getOrCreate({
+        icReplicaUrl: options.icReplicaUrl,
+        storageCanisterId: options.storageCanisterId,
+        keyManagerCanisterId: options.keyManagerCanisterId,
+        agent: options.agent,
+        agentOptions: options.agentOptions,
+        fetchRootKey: options.fetchRootKey,
+    }, options.cacheKey);
 }
+/**
+ * Clears the stealth client cache.
+ * @param cache Optional custom cache to clear. Defaults to the global cache.
+ * @param key Optional specific key to clear. If not provided, clears all entries.
+ */
 export function clearStealthClientCache(cache, key) {
-    const target = cache ?? defaultStealthCache;
-    if (key) {
-        target.delete(key);
+    if (cache) {
+        if (key) {
+            cache.delete(key);
+        }
+        else {
+            cache.clear();
+        }
         return;
     }
-    target.clear();
+    defaultStealthCacheManager.clear(key);
 }
-const defaultDeciderCache = new Map();
+/**
+ * Resets the default stealth client cache to its initial state.
+ * Useful for testing.
+ */
+export function resetStealthClientCache() {
+    defaultStealthCacheManager.reset();
+}
+/**
+ * Returns the default stealth client cache manager.
+ */
+export function getDefaultStealthClientCacheManager() {
+    return defaultStealthCacheManager;
+}
+// ============================================================================
+// Backward-Compatible Functions (Decider Client)
+// ============================================================================
+/**
+ * Gets a decider client from cache or creates a new one.
+ * Supports custom cache via config.
+ */
 export function getDeciderClient(config) {
-    const cache = config.cache ?? defaultDeciderCache;
-    const cacheKey = config.cacheKey ?? config.baseUrl;
-    if (!cache.has(cacheKey)) {
-        const { baseUrl, cacheKey: _cacheKey, cache: _cache, ...options } = config;
-        cache.set(cacheKey, new HttpDeciderClient(baseUrl, options));
+    // If custom cache is provided, use direct Map operations for backward compatibility
+    if (config.cache) {
+        const cache = config.cache;
+        const cacheKey = config.cacheKey ?? config.baseUrl;
+        if (!cache.has(cacheKey)) {
+            const { baseUrl, cacheKey: _cacheKey, cache: _cache, ...options } = config;
+            cache.set(cacheKey, new HttpDeciderClient(baseUrl, options));
+        }
+        return cache.get(cacheKey);
     }
-    return cache.get(cacheKey);
+    // Use default manager
+    const { baseUrl, cacheKey, cache: _cache, ...options } = config;
+    return defaultDeciderCacheManager.getOrCreate(baseUrl, options, cacheKey);
 }
+/**
+ * Clears the decider client cache.
+ * @param cache Optional custom cache to clear. Defaults to the global cache.
+ * @param key Optional specific key to clear. If not provided, clears all entries.
+ */
 export function clearDeciderClientCache(cache, key) {
-    const target = cache ?? defaultDeciderCache;
-    if (key) {
-        target.delete(key);
+    if (cache) {
+        if (key) {
+            cache.delete(key);
+        }
+        else {
+            cache.clear();
+        }
         return;
     }
-    target.clear();
+    defaultDeciderCacheManager.clear(key);
+}
+/**
+ * Resets the default decider client cache to its initial state.
+ * Useful for testing.
+ */
+export function resetDeciderClientCache() {
+    defaultDeciderCacheManager.reset();
+}
+/**
+ * Returns the default decider client cache manager.
+ */
+export function getDefaultDeciderClientCacheManager() {
+    return defaultDeciderCacheManager;
 }
 //# sourceMappingURL=connections.js.map

package/dist/ic/connections.js.map

@@ -1 +1 @@
-{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../src/ic/connections.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"connections.js","sourceRoot":"","sources":["../../src/ic/connections.ts"],"names":[],"mappings":"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"}

package/dist/ic/encryption.d.ts

@@ -1,15 +1,48 @@
 import { VetKey } from "@dfinity/vetkeys";
 import { Announcement, AnnouncementInput, DecryptedAnnouncement } from "./types.js";
+/**
+ * Encryption and decryption helpers for stealth announcements.
+ * @remarks
+ * - Requires WebCrypto (AES-GCM). In Node.js this uses `node:crypto`'s `webcrypto`.
+ * - Announcement payloads use:
+ *   - IBE to encrypt the session key (`ibeCiphertext`)
+ *   - AES-GCM to encrypt the plaintext (`ciphertext`, `nonce`)
+ * - Decryption may throw {@link AnnouncementIgnoredError} for announcements not intended for the given view key.
+ */
 export interface EncryptPayloadOptions {
+    /** Optional IBE identity bytes (defaults to empty). */
     identity?: Uint8Array;
+    /** Optional seed bytes used by IBE encryption (defaults to random 32 bytes). */
     seed?: Uint8Array;
+    /** Optional RNG for tests (must return the requested length). */
     randomBytes?: (length: number) => Uint8Array;
 }
+/**
+ * Encrypt a plaintext announcement.
+ * @param viewPublicKey - Recipient's view public key (vetKD derived public key bytes).
+ * @param plaintext - Announcement plaintext bytes or UTF-8 string.
+ * @returns Announcement input suitable for {@link StealthCanisterClient.submitAnnouncement}.
+ * @throws {@link StealthError} if WebCrypto is unavailable or inputs are invalid.
+ */
 export declare function encryptAnnouncement(viewPublicKey: Uint8Array, plaintext: Uint8Array | string, options?: EncryptPayloadOptions): Promise<AnnouncementInput>;
+/**
+ * Encrypt a plaintext announcement and return the session key used.
+ * @remarks The returned `sessionKey` is a copy; internal buffers are zeroed when possible.
+ */
 export declare function encryptAnnouncementWithArtifacts(viewPublicKey: Uint8Array, plaintextInput: Uint8Array | string, options?: EncryptPayloadOptions): Promise<{
     announcement: AnnouncementInput;
     sessionKey: Uint8Array;
 }>;
+/**
+ * Decrypt an announcement using a vetKD view key.
+ * @throws {@link AnnouncementIgnoredError} when the announcement cannot be decrypted for this key
+ * (vet key mismatch, invalid ciphertext, invalid nonce length, or authentication failure).
+ * @throws {@link StealthError} if WebCrypto is unavailable.
+ */
 export declare function decryptAnnouncement(vetKey: VetKey, announcement: Announcement): Promise<DecryptedAnnouncement>;
+/**
+ * Attempt to decrypt many announcements, ignoring those not intended for the provided key.
+ * @remarks Only {@link AnnouncementIgnoredError} is swallowed; all other errors are rethrown.
+ */
 export declare function scanAnnouncements(vetKey: VetKey, announcements: Announcement[]): Promise<DecryptedAnnouncement[]>;
 //# sourceMappingURL=encryption.d.ts.map

package/dist/ic/encryption.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/ic/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEjG,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKpF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;CAC9C;AAED,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,UAAU,EACzB,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,UAAU,EACzB,cAAc,EAAE,UAAU,GAAG,MAAM,EACnC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC;IAAE,YAAY,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,CA4DtE;AAED,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,qBAAqB,CAAC,CA6ChC;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAalC"}
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../src/ic/encryption.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyD,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEjG,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKpF;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,gFAAgF;IAChF,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,iEAAiE;IACjE,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,aAAa,EAAE,UAAU,EACzB,SAAS,EAAE,UAAU,GAAG,MAAM,EAC9B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;GAGG;AACH,wBAAsB,gCAAgC,CACpD,aAAa,EAAE,UAAU,EACzB,cAAc,EAAE,UAAU,GAAG,MAAM,EACnC,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC;IAAE,YAAY,EAAE,iBAAiB,CAAC;IAAC,UAAU,EAAE,UAAU,CAAA;CAAE,CAAC,CA4DtE;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,qBAAqB,CAAC,CA6ChC;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,YAAY,EAAE,GAC5B,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAalC"}

package/dist/ic/encryption.js

@@ -2,10 +2,21 @@ import { DerivedPublicKey, IbeCiphertext, IbeIdentity, IbeSeed } from "@dfinity/
 import { AnnouncementIgnoredError, StealthError } from "./errors.js";
 const SESSION_KEY_LEN = 32;
 const NONCE_LEN = 12;
+/**
+ * Encrypt a plaintext announcement.
+ * @param viewPublicKey - Recipient's view public key (vetKD derived public key bytes).
+ * @param plaintext - Announcement plaintext bytes or UTF-8 string.
+ * @returns Announcement input suitable for {@link StealthCanisterClient.submitAnnouncement}.
+ * @throws {@link StealthError} if WebCrypto is unavailable or inputs are invalid.
+ */
 export async function encryptAnnouncement(viewPublicKey, plaintext, options = {}) {
     const { announcement } = await encryptAnnouncementWithArtifacts(viewPublicKey, plaintext, options);
     return announcement;
 }
+/**
+ * Encrypt a plaintext announcement and return the session key used.
+ * @remarks The returned `sessionKey` is a copy; internal buffers are zeroed when possible.
+ */
 export async function encryptAnnouncementWithArtifacts(viewPublicKey, plaintextInput, options = {}) {
     const crypto = await resolveCrypto();
     const plaintext = typeof plaintextInput === "string" ? new TextEncoder().encode(plaintextInput) : plaintextInput;
@@ -41,6 +52,12 @@ export async function encryptAnnouncementWithArtifacts(viewPublicKey, plaintextI
         sessionKey: sessionKeyCopy,
     };
 }
+/**
+ * Decrypt an announcement using a vetKD view key.
+ * @throws {@link AnnouncementIgnoredError} when the announcement cannot be decrypted for this key
+ * (vet key mismatch, invalid ciphertext, invalid nonce length, or authentication failure).
+ * @throws {@link StealthError} if WebCrypto is unavailable.
+ */
 export async function decryptAnnouncement(vetKey, announcement) {
     const crypto = await resolveCrypto();
     const { ibeCiphertext, ciphertext, nonce } = announcement;
@@ -74,6 +91,10 @@ export async function decryptAnnouncement(vetKey, announcement) {
         throw new AnnouncementIgnoredError("ciphertext authentication failed");
     }
 }
+/**
+ * Attempt to decrypt many announcements, ignoring those not intended for the provided key.
+ * @remarks Only {@link AnnouncementIgnoredError} is swallowed; all other errors are rethrown.
+ */
 export async function scanAnnouncements(vetKey, announcements) {
     const decrypted = [];
     for (const announcement of announcements) {

package/dist/ic/encryption.js.map

@@ -1 +1 @@
-{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/ic/encryption.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"encryption.js","sourceRoot":"","sources":["../../src/ic/encryption.ts"],"names":[],"mappings":"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"}

package/dist/ic/errors.d.ts

@@ -1,6 +1,21 @@
+/**
+ * Base error type for IC-related and stealth client operations.
+ * @remarks
+ * SDK consumers can `instanceof StealthError` to distinguish SDK failures from other thrown errors.
+ */
 export declare class StealthError extends Error {
     constructor(message: string);
 }
+/**
+ * Error thrown when an announcement should be ignored during scanning/decryption.
+ * @remarks
+ * This is used for expected failures such as:
+ * - view key mismatch
+ * - invalid ciphertext for this recipient
+ * - AES-GCM authentication failure
+ *
+ * Scanners typically swallow this error and continue with other announcements.
+ */
 export declare class AnnouncementIgnoredError extends StealthError {
     constructor(reason: string);
 }

package/dist/ic/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/ic/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,wBAAyB,SAAQ,YAAY;gBAC5C,MAAM,EAAE,MAAM;CAI3B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/ic/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;GASG;AACH,qBAAa,wBAAyB,SAAQ,YAAY;gBAC5C,MAAM,EAAE,MAAM;CAI3B"}

package/dist/ic/errors.js

@@ -1,9 +1,24 @@
+/**
+ * Base error type for IC-related and stealth client operations.
+ * @remarks
+ * SDK consumers can `instanceof StealthError` to distinguish SDK failures from other thrown errors.
+ */
 export class StealthError extends Error {
     constructor(message) {
         super(message);
         this.name = "StealthError";
     }
 }
+/**
+ * Error thrown when an announcement should be ignored during scanning/decryption.
+ * @remarks
+ * This is used for expected failures such as:
+ * - view key mismatch
+ * - invalid ciphertext for this recipient
+ * - AES-GCM authentication failure
+ *
+ * Scanners typically swallow this error and continue with other announcements.
+ */
 export class AnnouncementIgnoredError extends StealthError {
     constructor(reason) {
         super(`announcement ignored: ${reason}`);

package/dist/ic/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ic/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,YAAY;IACxD,YAAY,MAAc;QACxB,KAAK,CAAC,yBAAyB,MAAM,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/ic/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,wBAAyB,SAAQ,YAAY;IACxD,YAAY,MAAc;QACxB,KAAK,CAAC,yBAAyB,MAAM,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF"}

package/dist/ic/idl.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Candid IDL factory definitions for ICP canisters.
+ * @remarks
+ * These factories must remain in sync with the deployed canister interfaces.
+ * SDK consumers typically should not depend on this module directly.
+ */
+import { IDL } from "@dfinity/candid";
+/**
+ * IDL factory for the Key Manager canister.
+ * Provides view key derivation and encrypted key request functionality.
+ *
+ * @remarks
+ * The canister returns a Result variant. Some deployments may use `Ok/Err` and others `ok/err`;
+ * the SDK unwrap logic handles both at the boundary (`ic/candid.ts`).
+ */
+export declare const keyManagerIdlFactory: IDL.InterfaceFactory;
+/**
+ * IDL factory for the Storage canister.
+ * Provides announcement and invoice storage functionality.
+ *
+ * @remarks
+ * Pagination methods use `Opt` cursors (`next_id`, `next_ts`). The SDK maps these to `bigint | null`
+ * for consumer convenience.
+ */
+export declare const storageIdlFactory: IDL.InterfaceFactory;
+//# sourceMappingURL=idl.d.ts.map

package/dist/ic/idl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idl.d.ts","sourceRoot":"","sources":["../../src/ic/idl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,GAAG,CAAC,gBAuBtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,GAAG,CAAC,gBAqDnC,CAAC"}