@healchain/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HealChain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,204 @@
+# @healchain/sdk
+
+JavaScript SDK for [HealChain](https://healchain.org) — self-healing decentralized storage using Reed-Solomon erasure coding on Ethereum and Arbitrum.
+
+## Install
+
+```bash
+npm install @healchain/sdk
+```
+
+## Quick Start
+
+```javascript
+import HealChain from '@healchain/sdk';
+
+const hc = new HealChain({ apiUrl: 'https://api.healchain.org' });
+
+// Store data — oracle fulfills automatically
+const { recordId, chainId } = await hc.store('Hello World', {
+  label: 'my first record',
+});
+console.log(`Stored as record #${recordId} on chain ${chainId}`);
+
+// Retrieve — auto-discovers chain from GlobalRegistry
+const { text, chainId: retrievedFrom } = await hc.retrieve(recordId);
+console.log(`Retrieved from chain ${retrievedFrom}: ${text}`);
+```
+
+## API
+
+### `new HealChain(options)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiUrl` | string | `https://api.healchain.org` | API base URL |
+| `apiKey` | string | — | Optional API key |
+| `network` | string | `'sepolia'` | Default network: `'sepolia'` or `'arbitrum'` |
+| `pollInterval` | number | `4000` | Oracle poll interval in ms |
+| `pollTimeout` | number | `120000` | Max wait for oracle fulfillment in ms |
+| `dataShards` | number | `10` | Default RS data shards |
+| `parityShards` | number | `4` | Default RS parity shards |
+
+---
+
+### `hc.store(data, options?)`
+
+Store data on-chain. Polls until the oracle fulfills the request.
+
+**Parameters:**
+- `data` — `string` or `Uint8Array`
+- `options.label` — record label (default: `'sdk upload'`)
+- `options.network` — override network for this call
+- `options.dataShards` / `options.parityShards` — override shard config
+- `options.onPending(info)` — callback when tx is submitted
+- `options.onFulfilled(result)` — callback when oracle fulfills
+
+**Returns:** `Promise<StoreResult>`
+
+```typescript
+{
+  recordId:     string   // on-chain record ID
+  requestId:    string   // oracle request ID
+  tx:           string   // submission transaction hash
+  chainId:      string   // chain where data is stored
+  originalSize: string   // original data size in bytes
+  encodedSize:  string   // encoded shard size in bytes
+}
+```
+
+**Example with progress callbacks:**
+
+```javascript
+const result = await hc.store('my data', {
+  label: 'important file',
+  network: 'arbitrum',           // ~75x cheaper than Sepolia
+  onPending: ({ requestId }) => {
+    console.log(`Submitted, oracle processing requestId=${requestId}...`);
+  },
+  onFulfilled: ({ recordId }) => {
+    console.log(`Fulfilled! Record ID: ${recordId}`);
+  },
+});
+```
+
+---
+
+### `hc.retrieve(id)`
+
+Retrieve a record by ID. Automatically queries the GlobalRegistry to find which chain holds the data and fetches from there.
+
+**Parameters:**
+- `id` — `string` or `number`
+
+**Returns:** `Promise<RetrieveResult>`
+
+```typescript
+{
+  recordId: string   // record ID
+  data:     string   // hex-encoded original data (0x...)
+  text:     string   // UTF-8 decoded text
+  bytes:    number   // original data size in bytes
+  chainId:  string   // chain where data was stored ('11155111' or '421614')
+}
+```
+
+---
+
+### `hc.getMetadata(id)`
+
+Fetch record metadata without retrieving the full data payload.
+
+**Returns:** `Promise<object>` — label, owner, sizes, shards, timestamp, dataHash
+
+---
+
+### `hc.list(page?, limit?)`
+
+List records with pagination.
+
+**Parameters:**
+- `page` — page number, 0-indexed (default: `0`)
+- `limit` — records per page, max 50 (default: `10`)
+
+**Returns:**
+```typescript
+{
+  records: object[]  // record summaries
+  total:   number    // total record count
+  pages:   number    // total page count
+  page:    number    // current page
+}
+```
+
+---
+
+### `hc.health()`
+
+Check service health.
+
+**Returns:** `Promise<{ status, version, geth, lastBlock }>`
+
+---
+
+## Error Handling
+
+All methods throw `HealChainError` on failure:
+
+```javascript
+import { HealChain, HealChainError } from '@healchain/sdk';
+
+try {
+  const result = await hc.retrieve(999);
+} catch (err) {
+  if (err instanceof HealChainError) {
+    console.error(err.message);   // human-readable message
+    console.error(err.status);    // HTTP status code (if applicable)
+    console.error(err.code);      // 'NETWORK_ERROR' | 'FULFILLMENT_TIMEOUT' | null
+  }
+}
+```
+
+---
+
+## Browser (ESM)
+
+```html
+<script type="module">
+  import HealChain from 'https://esm.sh/@healchain/sdk';
+
+  const hc = new HealChain({ apiUrl: 'https://api.healchain.org' });
+  const { text } = await hc.retrieve(0);
+  console.log(text);
+</script>
+```
+
+---
+
+## Networks
+
+| Network | Chain ID | Notes |
+|---|---|---|
+| `sepolia` | 11155111 | Ethereum Sepolia testnet |
+| `arbitrum` | 421614 | Arbitrum Sepolia testnet — ~75x cheaper gas |
+
+Store on Arbitrum for lower cost. Retrieve works automatically regardless of which chain the data is on — the SDK doesn't need to know.
+
+---
+
+## Roadmap
+
+- **v0.1** — REST API client (store, retrieve, list, health) ✅
+- **v0.2** — Direct wallet signing via ethers.js (no service required)
+- **v0.3** — Streaming large file support
+- **v1.0** — Mainnet support
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+---
+
+*Built on [HealChain](https://healchain.org) · [GitHub](https://github.com/karmaxul/ci-quantum-storage)*

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@healchain/sdk",
+  "version": "0.1.0",
+  "description": "JavaScript SDK for HealChain — self-healing decentralized storage via Reed-Solomon erasure coding",
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "type": "module",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules test/index.test.js"
+  },
+  "keywords": [
+    "healchain",
+    "blockchain",
+    "storage",
+    "reed-solomon",
+    "erasure-coding",
+    "ethereum",
+    "arbitrum",
+    "decentralized",
+    "self-healing"
+  ],
+  "author": "HealChain Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/karmaxul/ci-quantum-storage"
+  },
+  "homepage": "https://healchain.org",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,288 @@
+/**
+ * HealChain SDK v0.1.0
+ * REST API client for HealChain — self-healing decentralized storage.
+ *
+ * Browser (ESM) and Node.js compatible.
+ *
+ * @example
+ * const hc = new HealChain({ apiUrl: 'https://api.healchain.org' });
+ * const { recordId } = await hc.store('Hello World', { label: 'my record' });
+ * const { data }     = await hc.retrieve(recordId);
+ */
+
+'use strict';
+
+// ── Defaults ──────────────────────────────────────────────────────────────────
+
+const DEFAULT_API_URL       = 'https://api.healchain.org';
+const DEFAULT_POLL_INTERVAL = 4000;   // ms between fulfillment polls
+const DEFAULT_POLL_TIMEOUT  = 120000; // ms before giving up (2 minutes)
+const DEFAULT_DATA_SHARDS   = 10;
+const DEFAULT_PARITY_SHARDS = 4;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function toHex(input) {
+  if (typeof input === 'string') {
+    // Already hex
+    if (input.startsWith('0x')) return input;
+    // Plain text → hex
+    const bytes = new TextEncoder().encode(input);
+    return '0x' + Array.from(bytes).map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+  if (input instanceof Uint8Array || ArrayBuffer.isView(input)) {
+    return '0x' + Array.from(new Uint8Array(input.buffer ?? input))
+      .map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+  throw new HealChainError('store() data must be a string or Uint8Array');
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// ── Error class ───────────────────────────────────────────────────────────────
+
+class HealChainError extends Error {
+  constructor(message, { status, code, response } = {}) {
+    super(message);
+    this.name    = 'HealChainError';
+    this.status  = status  ?? null;
+    this.code    = code    ?? null;
+    this.response = response ?? null;
+  }
+}
+
+// ── Main class ────────────────────────────────────────────────────────────────
+
+class HealChain {
+  /**
+   * @param {object} options
+   * @param {string}  [options.apiUrl='https://api.healchain.org'] - API base URL
+   * @param {string}  [options.apiKey]        - Optional API key
+   * @param {number}  [options.pollInterval]  - Fulfillment poll interval in ms
+   * @param {number}  [options.pollTimeout]   - Fulfillment poll timeout in ms
+   * @param {number}  [options.dataShards]    - Default RS data shards
+   * @param {number}  [options.parityShards]  - Default RS parity shards
+   * @param {string}  [options.network]       - 'sepolia' | 'arbitrum' (for store routing)
+   */
+  constructor(options = {}) {
+    this.apiUrl       = (options.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, '');
+    this.apiKey       = options.apiKey       ?? null;
+    this.pollInterval = options.pollInterval ?? DEFAULT_POLL_INTERVAL;
+    this.pollTimeout  = options.pollTimeout  ?? DEFAULT_POLL_TIMEOUT;
+    this.dataShards   = options.dataShards   ?? DEFAULT_DATA_SHARDS;
+    this.parityShards = options.parityShards ?? DEFAULT_PARITY_SHARDS;
+    this.network      = options.network      ?? 'sepolia';
+  }
+
+  // ── Internal fetch wrapper ──────────────────────────────────────────────────
+
+  async _fetch(path, init = {}) {
+    const url     = `${this.apiUrl}${path}`;
+    const headers = { 'Content-Type': 'application/json', ...init.headers };
+    if (this.apiKey) headers['X-API-Key'] = this.apiKey;
+
+    let res;
+    try {
+      res = await fetch(url, { ...init, headers });
+    } catch (err) {
+      throw new HealChainError(`Network error: ${err.message}`, { code: 'NETWORK_ERROR' });
+    }
+
+    let body;
+    const ct = res.headers.get('content-type') ?? '';
+    if (ct.includes('application/json')) {
+      body = await res.json();
+    } else {
+      body = await res.text();
+    }
+
+    if (!res.ok) {
+      const msg = (typeof body === 'object' ? body.error : body) ?? res.statusText;
+      throw new HealChainError(msg, { status: res.status, response: body });
+    }
+
+    return body;
+  }
+
+  // ── health() ───────────────────────────────────────────────────────────────
+
+  /**
+   * Check service health.
+   * @returns {Promise<{status: string, version: string, geth: string, lastBlock: string}>}
+   */
+  async health() {
+    return this._fetch('/health');
+  }
+
+  // ── store() ────────────────────────────────────────────────────────────────
+
+  /**
+   * Store data on-chain. Polls until the oracle fulfills the request.
+   *
+   * @param {string|Uint8Array} data - Data to store
+   * @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.network]             - Override network for this call
+   * @param {function} [options.onPending]          - Called with requestId when submitted
+   * @param {function} [options.onFulfilled]        - Called when oracle fulfills
+   *
+   * @returns {Promise<StoreResult>}
+   *
+   * @typedef {object} StoreResult
+   * @property {string} recordId     - On-chain record ID
+   * @property {string} requestId    - Oracle request ID
+   * @property {string} tx           - Submission transaction hash
+   * @property {string} chainId      - Chain where data is stored
+   * @property {string} originalSize - Original data size in bytes
+   * @property {string} encodedSize  - Encoded shard size in bytes
+   */
+  async store(data, options = {}) {
+    const hex         = toHex(data);
+    const label       = options.label        ?? 'sdk upload';
+    const dataShards  = options.dataShards   ?? this.dataShards;
+    const parityShards = options.parityShards ?? this.parityShards;
+    const network     = options.network      ?? this.network;
+
+    // Submit store request
+    const submitted = await this._fetch('/storeOnChain', {
+      method: 'POST',
+      body: JSON.stringify({ data: hex, label, network, dataShards, parityShards }),
+    });
+
+    // Devnet returns synchronously
+    if (submitted.status === 'success' && submitted.recordId !== undefined) {
+      return {
+        recordId:     String(submitted.recordId),
+        requestId:    submitted.requestId ?? null,
+        tx:           submitted.tx,
+        chainId:      submitted.chainId ?? null,
+        originalSize: submitted.originalSize,
+        encodedSize:  submitted.encodedSize,
+      };
+    }
+
+    // Sepolia/Arbitrum: poll for oracle fulfillment
+    const { requestId, tx } = submitted;
+    if (!requestId) {
+      throw new HealChainError('No requestId returned from store', { response: submitted });
+    }
+
+    if (typeof options.onPending === 'function') {
+      options.onPending({ requestId, tx });
+    }
+
+    return this._pollFulfillment(requestId, tx, options.onFulfilled);
+  }
+
+  // ── _pollFulfillment() ─────────────────────────────────────────────────────
+
+  async _pollFulfillment(requestId, tx, onFulfilled) {
+    const deadline = Date.now() + this.pollTimeout;
+
+    while (Date.now() < deadline) {
+      await sleep(this.pollInterval);
+
+      let status;
+      try {
+        status = await this._fetch(`/sepoliaStatus?requestId=${encodeURIComponent(requestId)}`);
+      } catch {
+        // Transient error — keep polling
+        continue;
+      }
+
+      if (status.status === 'fulfilled') {
+        const result = {
+          recordId:     String(status.recordId ?? requestId),
+          requestId:    String(requestId),
+          tx,
+          chainId:      status.chainId ?? null,
+          originalSize: status.originalSize ?? null,
+          encodedSize:  status.encodedSize  ?? null,
+          totalRecords: status.totalRecords  ?? null,
+        };
+        if (typeof onFulfilled === 'function') onFulfilled(result);
+        return result;
+      }
+    }
+
+    throw new HealChainError(
+      `Oracle fulfillment timed out after ${this.pollTimeout / 1000}s (requestId=${requestId})`,
+      { code: 'FULFILLMENT_TIMEOUT' }
+    );
+  }
+
+  // ── retrieve() ─────────────────────────────────────────────────────────────
+
+  /**
+   * Retrieve a record by ID. Automatically routes to the correct chain
+   * via the GlobalRegistry.
+   *
+   * @param {string|number} id - Record ID
+   * @returns {Promise<RetrieveResult>}
+   *
+   * @typedef {object} RetrieveResult
+   * @property {string} recordId - Record ID
+   * @property {string} data     - Hex-encoded original data
+   * @property {string} text     - UTF-8 decoded text (if valid)
+   * @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 {
+      recordId: String(result.recordId),
+      data:     result.data,
+      text:     result.text,
+      bytes:    result.bytes,
+      chainId:  result.chainId ?? null,
+    };
+  }
+
+  // ── getMetadata() ──────────────────────────────────────────────────────────
+
+  /**
+   * Get record metadata without fetching the full data.
+   *
+   * @param {string|number} id - Record ID
+   * @returns {Promise<object>} Record metadata
+   */
+  async getMetadata(id) {
+    return this._fetch(`/getMetadata?id=${encodeURIComponent(String(id))}`);
+  }
+
+  // ── list() ─────────────────────────────────────────────────────────────────
+
+  /**
+   * List records with pagination.
+   *
+   * @param {number} [page=0]   - Page number (0-indexed)
+   * @param {number} [limit=10] - Records per page (max 50)
+   * @returns {Promise<ListResult>}
+   *
+   * @typedef {object} ListResult
+   * @property {object[]} records - Array of record summaries
+   * @property {number}   total   - Total record count
+   * @property {number}   pages   - Total page count
+   * @property {number}   page    - Current page
+   */
+  async list(page = 0, limit = 10) {
+    return this._fetch(`/listRecords?page=${page}&limit=${limit}`);
+  }
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+export { HealChain, HealChainError };
+export default HealChain;
+
+// CommonJS compatibility
+if (typeof module !== 'undefined') {
+  module.exports = HealChain;
+  module.exports.HealChain = HealChain;
+  module.exports.HealChainError = HealChainError;
+  module.exports.default = HealChain;
+}