@healchain/sdk 0.5.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @healchain/sdk
 
-JavaScript SDK for [HealChain](https://healchain.org) — self-healing decentralized storage using Reed-Solomon erasure coding on Ethereum and Arbitrum.
+JavaScript SDK for [HealChain](https://healchain.org) — self-healing decentralized storage using Reed-Solomon erasure coding across multiple EVM chains.
 
 ## Install
 
@@ -13,7 +13,10 @@ npm install @healchain/sdk
 ```javascript
 import HealChain from '@healchain/sdk';
 
-const hc = new HealChain({ apiUrl: 'https://api.healchain.org' });
+const hc = new HealChain({
+  apiUrl: 'https://api.healchain.org',
+  apiKey: 'your-api-key',
+});
 
 // Store data — oracle fulfills automatically
 const { recordId, chainId } = await hc.store('Hello World', {
@@ -33,8 +36,9 @@ console.log(`Retrieved from chain ${retrievedFrom}: ${text}`);
 | 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'` |
+| `apiKey` | string | — | API key (required for store/retrieve) |
+| `chain` | string | `'auto'` | Chain: `'auto'`, `'sepolia'`, `'arbitrum'`, `'base'`, etc. |
+| `preference` | string | `''` | `'cheapest'` \| `'fastest'` \| `'redundant'` \| `''` (auto weighted) |
 | `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 |
@@ -49,156 +53,101 @@ 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
-}
-```
+- `options.chain` — override chain for this store
+- `options.preference` — override preference for this store
+- `options.onFulfilled` — callback when oracle fulfills: `(result) => void`
 
-**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}`);
-  },
-});
-```
+**Returns:** `{ recordId, tx, chainId, originalSize, encodedSize, ciDigestHash }`
 
 ---
 
 ### `hc.retrieve(id)`
 
-Retrieve a record by ID. Automatically queries the GlobalRegistry to find which chain holds the data and fetches from there.
+Retrieve data by record ID. Auto-discovers which chain the record lives on.
 
-**Parameters:**
-- `id` — `string` or `number`
+**Returns:** `{ text, hex, chainId, originalSize, label }`
 
-**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.estimateFee(sizeBytes, chain?)`
+
+Estimate the fee for storing data of a given size.
+
+**Returns:** `{ feeCents, feeUsd, sizeBytes, chain }`
+
+```javascript
+const fee = await hc.estimateFee(1024, 'auto');
+console.log(`Fee: ${fee.feeUsd}`); // e.g. "$0.05"
 ```
 
 ---
 
+### `hc.chainScores()`
+
+Get current chain scoring data (cost, reliability, latency).
+
+**Returns:** array of chain score objects
+
+---
+
 ### `hc.getMetadata(id)`
 
-Fetch record metadata without retrieving the full data payload.
+Get record metadata without retrieving the data.
 
-**Returns:** `Promise<object>` — label, owner, sizes, shards, timestamp, dataHash
+**Returns:** `{ id, label, originalSize, encodedSize, dataShards, parityShards, owner, timestamp, chainId }`
 
 ---
 
 ### `hc.list(page?, limit?)`
 
-List records with pagination.
+List stored records.
 
-**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
-}
-```
+**Returns:** `{ records, total, pages }`
+
+---
+
+### `hc.getBillingBalance(walletAddress)`
+
+Get testnet credit balance for a wallet.
 
 ---
 
 ### `hc.health()`
 
-Check service health.
+Check API health.
 
-**Returns:** `Promise<{ status, version, geth, lastBlock }>`
+**Returns:** `{ status, version, lastBlock }`
 
 ---
 
 ## Error Handling
 
-All methods throw `HealChainError` on failure:
-
 ```javascript
-import { HealChain, HealChainError } from '@healchain/sdk';
+import HealChain, { HealChainError } from '@healchain/sdk';
 
 try {
-  const result = await hc.retrieve(999);
+  const result = await hc.store('my data', { label: 'test' });
 } 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
+    console.error(err.message, err.status, err.code);
   }
 }
 ```
 
----
-
-## 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
+## Supported Chains
 
-| Network | Chain ID | Notes |
+| Chain | ID | Identifier |
 |---|---|---|
-| `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
+| Ethereum Sepolia | 11155111 | `sepolia` |
+| Arbitrum Sepolia | 421614 | `arbitrum` |
+| Base Sepolia | 84532 | `base` |
+| Optimism Sepolia | 11155420 | `optimism` |
+| Unichain Sepolia | 1301 | `unichain` |
+| Avalanche Fuji | 43113 | `avalanche` |
+| And 7 more testnets... | | `auto` selects best |
 
-- **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
-
----
+Use `chain: 'auto'` (default) to let the scoring engine pick the optimal chain.
 
 ## License
 
-MIT — see [LICENSE](LICENSE)
-
----
-
-*Built on [HealChain](https://healchain.org) · [GitHub](https://github.com/karmaxul/ci-quantum-storage)*
+MIT © [HealChain](https://healchain.org)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@healchain/sdk",
-  "version": "0.5.0",
+  "version": "1.0.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 v0.4.0
+ * HealChain SDK v1.0.0
  * REST API client for HealChain — self-healing decentralized storage.
  *
  * Browser (ESM) and Node.js compatible.
@@ -76,7 +76,10 @@ class HealChain {
     this.dataShards   = options.dataShards   ?? DEFAULT_DATA_SHARDS;
     this.parityShards = options.parityShards ?? DEFAULT_PARITY_SHARDS;
     this.chain        = options.chain ?? options.network ?? 'auto';
-    this.network      = this.chain; // backward compat
+    this.network      = this.chain; // backward compat — use chain instead
+    if (options.network && !options.chain) {
+      console.warn('[HealChain] options.network is deprecated — use options.chain instead');
+    }
     this.preference   = options.preference   ?? '';
   }