@healchain/sdk 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healchain/sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "JavaScript SDK for HealChain — self-healing decentralized storage via Reed-Solomon erasure coding",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * HealChain SDK v1.0.0
+ * HealChain SDK v1.1.0
  * REST API client for HealChain — self-healing decentralized storage.
  *
  * Browser (ESM) and Node.js compatible.
@@ -241,14 +241,82 @@ class HealChain {
    * @property {number} bytes    - Original data size in bytes
    * @property {string} chainId  - Chain where data was stored
    */
-  async retrieve(id) {
-    const result = await this._fetch(`/retrieve?id=${encodeURIComponent(String(id))}`);
-    return {
+  async retrieve(id, options = {}) {
+    const chain = options.chain ?? this.chain ?? 'auto';
+    const result = await this._fetch(
+      `/retrieve?id=${encodeURIComponent(String(id))}&chain=${encodeURIComponent(chain)}`
+    );
+    const record = {
       recordId: String(result.recordId),
       data:     result.data,
       text:     result.text,
       bytes:    result.bytes,
       chainId:  result.chainId ?? null,
+      storageType: result.storageType ?? 'on_chain',
+      shards:   result.shards ?? null,
+    };
+    // Fetch full ci-sha4096 digest — best-effort, non-blocking
+    try {
+      record.ciDigestHash = await this.getCiDigest(id);
+    } catch (_) {
+      // digest not yet available for old records — silently omit
+    }
+    return record;
+  }
+
+  // ── storeFile() ────────────────────────────────────────────────────────────
+
+  /**
+   * Store a file (raw bytes) on-chain or via IPFS hybrid (auto-detected by size).
+   * Files ≤1MB go on-chain. Files >1MB use IPFS hybrid storage.
+   *
+   * @param {Uint8Array|ArrayBuffer|Buffer} buffer - File bytes
+   * @param {object} [options]
+   * @param {string}  [options.label='sdk upload'] - Record label
+   * @param {number}  [options.dataShards]         - Override RS data shards
+   * @param {number}  [options.parityShards]       - Override RS parity shards
+   * @param {string}  [options.chain]              - Chain name or 'auto'
+   * @param {string}  [options.preference]         - Chain selection preference
+   * @returns {Promise<StoreResult>}
+   */
+  async storeFile(buffer, options = {}) {
+    const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+    return this.store(bytes, options);
+  }
+
+  // ── getCiDigest() ──────────────────────────────────────────────────────────
+
+  /**
+   * Get the full 512-byte ci-sha4096 digest hex for a record.
+   * This is the authoritative digest stored at oracle fulfillment time.
+   *
+   * @param {string|number} recordId - Record ID
+   * @returns {Promise<string>} Full digest hex (1024 hex chars = 512 bytes)
+   */
+  async getCiDigest(recordId) {
+    const result = await this._fetch(`/ciDigest?recordId=${encodeURIComponent(String(recordId))}`);
+    return result.ciDigestHash;
+  }
+
+  // ── verifyIntegrity() ──────────────────────────────────────────────────────
+
+  /**
+   * High-level audit helper: retrieve a record and its ci-sha4096 digest.
+   *
+   * @param {string|number} recordId - Record ID
+   * @param {object} [options]
+   * @param {string} [options.chain] - Chain name or 'auto'
+   * @returns {Promise<{record: RetrieveResult, ciDigestHash: string|null}>}
+   */
+  async verifyIntegrity(recordId, options = {}) {
+    const chain = options.chain ?? this.chain ?? 'auto';
+    const [record, ciDigestHash] = await Promise.allSettled([
+      this._fetch(`/retrieve?id=${encodeURIComponent(String(recordId))}&chain=${encodeURIComponent(chain)}`),
+      this.getCiDigest(recordId),
+    ]);
+    return {
+      record:       record.status === 'fulfilled' ? record.value : null,
+      ciDigestHash: ciDigestHash.status === 'fulfilled' ? ciDigestHash.value : null,
     };
   }