@0xkaleab/sdk-js 0.2.7

package/README.e2e-browser.md

@@ -0,0 +1,209 @@
+# Browser E2E Test Harness (sn-api + Keplr + LEP-1)
+
+This README describes how to run the end-to-end browser test for the Lumera SDK.
+The harness drives the `examples/browser` app against a local `sn-api-server`
+and a real Keplr wallet in Chrome, exercising the full LEP-1 layout/index/auth
+signature flow and Cascade upload/download.
+
+## What this test does
+
+- Starts (or reuses) `sn-api-server` via the `snapi` binary.
+- Starts (or reuses) the browser example dev server (`pnpm run dev` in
+  `examples/browser`).
+- Launches Chrome with a persistent profile that has Keplr installed and
+  configured.
+- Automates:
+  - Connect Keplr wallet (unlock + approve).
+  - Upload a small test file to Cascade (including:
+    - SDK “Multiple Signatures Required” modal,
+    - Keplr layout/index/auth ADR-036 signatures,
+    - Transaction confirmation).
+  - Download the uploaded file back via sn-api and the Cascade downloader.
+- Fails with a non-zero exit code on any timeout or error.
+
+## Prerequisites
+
+From the repo root:
+
+1. **sn-api-server binary**
+
+   You need a usable `snapi` binary on disk.
+
+   - Obtain or build the `snapi` binary by whatever means makes sense for your
+     environment.
+   - Place it somewhere on your machine, for example:
+
+     ```bash
+     /opt/lumera/snapi
+     ```
+
+   - Set `E2E_SNAPI_BIN` in `e2e.env` to the **full path** of that binary:
+
+     ```bash
+     E2E_SNAPI_BIN=/opt/lumera/snapi
+     ```
+
+   The harness does **not** assume any particular repo layout; it only checks
+   that `E2E_SNAPI_BIN` points to an existing file and exits with a clear
+   message if it does not.
+
+2. **Local sn-api configuration**
+
+   Ensure you have `~/.snapi/.env` configured (HTTP_PORT, GRPC_ADDR, CHAIN_ID,
+   KEY_NAME, etc.) and that sn-api can reach your target Lumera network.
+
+3. **Chrome profile with Keplr**
+
+- Install Keplr in Chrome.
+- Create/use a profile that:
+  - Has the Keplr extension installed and enabled.
+  - Has a Lumera Testnet account set up and funded.
+- Find the **Profile Path**:
+  1. Open Chrome with the target profile (e.g., the profile named “Matee” in
+     the Chrome UI).
+  2. In the address bar, navigate to `chrome://version`.
+  3. Look for the line labeled **Profile Path**.
+  4. Copy that full path (e.g. `/home/you/.config/google-chrome/Profile 2` or
+     `/home/you/.config/google-chrome-playwright-matee`).
+  5. Use that value as `E2E_CHROME_PROFILE_DIR` in `e2e.env`.
+
+4. **Node deps for sdk-js**
+
+   ```bash
+   cd sdk-js
+   pnpm install
+   ```
+
+## One-time configuration (e2e.env)
+
+In `sdk-js`:
+
+```bash
+cd sdk-js
+cp e2e.env.example e2e.env
+```
+
+Edit `e2e.env` to match your environment. A simple, minimal configuration looks like:
+
+```bash
+E2E_CHROME_EXECUTABLE=/usr/bin/google-chrome
+# Paste the "Profile Path" from chrome://version here:
+E2E_CHROME_PROFILE_DIR=/home/you/.config/google-chrome/Profile 2
+
+E2E_SNAPI_BIN=/opt/lumera/snapi          # full path to snapi binary
+E2E_SNAPI_URL=http://localhost:3000
+
+E2E_BROWSER_URL=http://localhost:3001
+
+E2E_KEPLR_AUTO_APPROVE=1
+E2E_KEPLR_DEBUG=0
+
+# Keplr wallet password for unlocking (test environment only)
+E2E_KEPLR_PASSWORD=your_keplr_password_here
+```
+
+For advanced tuning (timeouts, profile name for logging, etc.), you can add
+extra `E2E_*` variables to `e2e.env` as needed. The harness supports:
+
+```bash
+# Optional: profile name for logging only
+E2E_CHROME_PROFILE_NAME=Matee
+
+# Optional timeout overrides (milliseconds)
+E2E_TIMEOUT_HTTP_STARTUP_MS=120000
+E2E_TIMEOUT_HTTP_PRECHECK_MS=5000
+E2E_TIMEOUT_CONNECT_MS=30000
+E2E_TIMEOUT_UPLOAD_MS=120000
+E2E_TIMEOUT_DOWNLOAD_MS=600000
+E2E_TIMEOUT_POST_UPLOAD_PAUSE_MS=5000
+E2E_TIMEOUT_SIGNATURE_POLL_MS=15000
+E2E_TIMEOUT_TX_MODAL_MS=60000
+E2E_TIMEOUT_POPUP_LOAD_MS=30000
+E2E_TIMEOUT_POPUP_RENDER_DELAY_MS=2000
+E2E_TIMEOUT_POPUP_BUTTON_MS=10000
+E2E_TIMEOUT_EXISTING_POPUP_BUTTON_MS=5000
+```
+
+## How to run the test
+
+From `sdk-js`:
+
+```bash
+cd sdk-js
+make e2e-browser
+```
+
+This will:
+
+- Load `e2e.env` and export all `E2E_*` variables.
+- Ensure sn-api is running (reusing an existing instance on `E2E_SNAPI_URL`
+  or starting `E2E_SNAPI_BIN serve`).
+- Ensure the browser example dev server is running on `E2E_BROWSER_URL`.
+- Launch Chrome with `E2E_CHROME_PROFILE_DIR`.
+- Drive the browser example through:
+  - Connect Keplr wallet.
+  - Upload test file (with all LEP-1 signatures).
+  - Download the file back.
+- Exit with code `0` on success, non-zero on failure.
+
+## What to expect in the logs
+
+The harness logs both its own steps and the browser’s console output:
+
+- `[e2e] ...` lines are from the Node/Playwright script.
+- `[e2e][browser-console] ...` lines mirror the browser’s console.
+- Keplr-specific logs look like:
+
+  ```text
+  [e2e] [keplr] New popup page created, waiting for navigation...
+  [e2e] [keplr] Popup navigated: url=chrome-extension://... title=Keplr
+  [e2e] [keplr] button[1] text='Approve'
+  [e2e] [keplr] Clicking button[1] with text='Approve'...
+  [e2e] [keplr] Total approvals clicked so far: N
+  ```
+
+- The browser example logs:
+
+  - Upload progress (`Starting upload`, `File loaded into memory`, `File hash`, etc.).
+  - Signature phases (`signature requested`, `signature received` for layout/index/auth).
+  - Transaction confirmation.
+  - Upload success (`Upload completed`).
+  - Download success (`File saved to browser downloads`).
+
+If `E2E_KEPLR_DEBUG=1`, Keplr popup HTML is dumped into
+`sdk-js/e2e-debug/keplr-popup-*.html` so you can inspect the exact DOM.
+
+## Common issues
+
+- **Keplr popups not auto-approved**
+
+  - Ensure `E2E_KEPLR_PASSWORD` is set and correct.
+  - Ensure the Chrome profile really has Keplr installed and enabled.
+  - Check `e2e-debug/keplr-popup-*.html` to see if button labels changed.
+
+- **Downloads not visible in ~/Downloads**
+
+  - The example only triggers a download via an `<a download>` link.
+  - The actual directory is controlled by Chrome’s download settings for the
+    selected profile (e.g. “Ask where to save each file”).
+  - Check Chrome’s Downloads page (Ctrl+J) to see where the file went.
+
+- **HTTP 500 during download**
+
+  - sn-api may not yet have created the cascade request row when download is
+    requested.
+  - The harness waits a few seconds after “Upload completed” before triggering
+    download; if you still see 500s, inspect sn-api logs and its SQLite state
+    under `~/.snapi`.
+
+## Adjusting timeouts
+
+To tune timeouts for slow/fast environments, add overrides to `e2e.env`, e.g.:
+
+```bash
+E2E_TIMEOUT_UPLOAD_MS=300000
+E2E_TIMEOUT_DOWNLOAD_MS=600000
+E2E_TIMEOUT_POST_UPLOAD_PAUSE_MS=10000
+```
+
+See `e2e.env.example` for the full list of supported `E2E_TIMEOUT_...` vars.

package/README.md

@@ -0,0 +1,295 @@
+# @lumera-protocol/sdk-js
+
+**Official JavaScript/TypeScript SDK for Lumera Protocol**
+
+A unified SDK providing seamless access to the Lumera blockchain and Cascade distributed storage network. Built with modern TypeScript, featuring comprehensive type safety, and designed for both Node.js and browser environments.
+
+## ✨ Features
+
+- **🔗 Unified Client Interface** - Single entry point for all Lumera operations
+- **⛓️ Blockchain Operations** - Complete CosmJS integration with LCD/REST queries
+  - Transaction simulation, signing, and broadcasting
+  - Action module queries and operations
+  - Supernode module queries
+  - Chain parameter queries
+- **📦 Cascade Storage** - Full-featured distributed file storage client
+  - Upload/download with progress tracking
+  - Automatic file chunking and Reed-Solomon encoding
+  - Task management with polling and status updates
+  - Stream-based downloads for memory efficiency
+- **🔐 Wallet Integration** - Support for multiple wallet types
+  - Keplr wallet integration
+  - Leap wallet integration  
+  - Programmatic signing with DirectSecp256k1HdWallet
+- **🎯 Type Safety** - Full TypeScript support with comprehensive types
+- **🌐 Cross-Platform** - Works in Node.js (v18+) and modern browsers
+- **📝 Extensive Documentation** - Complete API reference and examples
+
+## 📦 Installation
+
+```bash
+pnpm install @lumera-protocol/sdk-js
+```
+
+### Peer Dependencies
+
+For blockchain operations, you'll also need CosmJS packages:
+
+```bash
+pnpm install @cosmjs/proto-signing @cosmjs/stargate
+```
+
+## 🚀 Quick Start
+
+### 1. Initialize the Client
+
+```typescript
+import { createLumeraClient } from "@lumera-protocol/sdk-js";
+import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
+
+// Create a wallet
+const wallet = await DirectSecp256k1HdWallet.fromMnemonic(
+  "your mnemonic phrase here",
+  { prefix: "lumera" }
+);
+
+const [account] = await wallet.getAccounts();
+
+// Create the client using testnet preset
+const client = await createLumeraClient({
+  preset: "testnet",
+  signer: wallet,
+  address: account.address,
+  gasPrice: "0.025ulume"
+});
+```
+
+### 2. Query the Blockchain
+
+```typescript
+// Get chain information
+const chainId = await client.Blockchain.getChainId();
+console.log("Chain ID:", chainId);
+
+// Query action module parameters
+const actionParams = await client.Blockchain.Action.getParams();
+console.log("Action params:", actionParams);
+
+// Query supernode module parameters  
+const supernodeParams = await client.Blockchain.Supernode.getParams();
+console.log("Supernode params:", supernodeParams);
+```
+
+### 3. Upload a File to Cascade
+
+```typescript
+// Prepare your file
+const fileContent = "Hello, Lumera!";
+const fileBytes = new TextEncoder().encode(fileContent);
+
+// Upload to Cascade
+const uploadResult = await client.Cascade.uploader.uploadFile(fileBytes, {
+  actionId: `my-file-${Date.now()}`,
+  rq_ids_ic: 1000,
+  rq_ids_max: actionParams.rq_ids_max,
+  taskOptions: {
+    pollInterval: 2000,
+    timeout: 300000,
+  },
+});
+
+console.log("Upload completed:", uploadResult);
+```
+
+### 4. Download a File from Cascade
+
+```typescript
+// Download using the action ID
+const downloadStream = await client.Cascade.downloader.download(
+  uploadResult.actionId
+);
+
+// Read the stream
+const reader = downloadStream.getReader();
+const chunks: Uint8Array[] = [];
+
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  chunks.push(value);
+}
+
+// Combine chunks
+const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+const downloadedBytes = new Uint8Array(totalLength);
+let offset = 0;
+for (const chunk of chunks) {
+  downloadedBytes.set(chunk, offset);
+  offset += chunk.length;
+}
+
+const downloadedContent = new TextDecoder().decode(downloadedBytes);
+console.log("Downloaded:", downloadedContent);
+```
+
+## 📚 Documentation
+
+- **[Developer Guide](./docs/developer-guide.md)** - Environment setup, codegen, testing, and publishing workflows
+- **[API Reference](./docs/api/index.html)** - Complete TypeScript API documentation (Typedoc HTML output)
+- **[Migration Guide](./MIGRATION.md)** - Migrate from direct fetch/LCD calls to the SDK
+- **[Examples](./examples/)** - Working code examples
+  - [Node.js Examples](./examples/node/) - Full workflow and standalone examples
+  - [Browser Example](./examples/browser/) - Browser-based upload/download demo
+
+## 🎯 Core Concepts
+
+### Chain Presets
+
+The SDK includes built-in presets for quick setup:
+
+```typescript
+const client = await createLumeraClient({
+  preset: "testnet", // or "mainnet"
+  signer: wallet,
+  address: account.address,
+});
+```
+
+Available presets:
+
+- `testnet` - Lumera testnet configuration
+- `mainnet` - Lumera mainnet configuration
+
+### Manual Configuration
+
+For custom chains or advanced setups:
+
+```typescript
+const client = await createLumeraClient({
+  rpcUrl: "https://your-rpc-url.com",
+  lcdUrl: "https://your-lcd-url.com",
+  chainId: "your-chain-id",
+  signer: wallet,
+  address: account.address,
+  gasPrice: "0.025ulume",
+  cascade: {
+    snapiBaseUrl: "https://your-snapi-url.com"
+  }
+});
+```
+
+### Blockchain Client
+
+Direct access to blockchain operations:
+
+```typescript
+// Transaction operations
+const msgs = [...]; // Your messages
+const gas = await client.Blockchain.Tx.simulate(address, msgs);
+const result = await client.Blockchain.Tx.broadcast(signedTx);
+
+// Query operations
+const actionList = await client.Blockchain.Action.listActions();
+const supernodeList = await client.Blockchain.Supernode.listAll();
+```
+
+### Cascade Client
+
+File storage operations:
+
+```typescript
+// Upload with progress tracking
+const uploader = client.Cascade.uploader;
+const result = await uploader.uploadFile(fileBytes, {
+  actionId: "my-action",
+  rq_ids_ic: 1000,
+  rq_ids_max: 10000,
+});
+
+// Download as stream
+const downloader = client.Cascade.downloader;
+const stream = await downloader.download("action-id");
+```
+
+### LEP-1 Helpers & Deterministic IDs
+
+For low-level control over LEP-1 layout generation and ID derivation, the SDK exposes helpers:
+
+```typescript
+import {
+  createSingleBlockLayout,
+  generateIds,
+  buildIndexFile,
+} from "@lumera-protocol/sdk-js";
+
+// 1. Create a single-block RaptorQ layout from file bytes
+const layoutBytes = await createSingleBlockLayout(fileBytes);
+
+// 2. Sign the canonical JSON layout bytes with your wallet (ADR-036)
+//    and obtain the base64-encoded signature string.
+
+// 3. Derive deterministic layout IDs (must match on-chain validation)
+const layoutIds = await generateIds(
+  layoutFileB64,
+  layoutSignatureB64,
+  rq_ids_ic,
+  rq_ids_max,
+);
+
+// 4. Build the LEP-1 index file
+const index = buildIndexFile(layoutIds, layoutSignatureB64);
+```
+
+To debug or validate determinism across Go and JS implementations, use the
+[`lep1-id-lab`](../lep1-id-lab/README.md) golden-vector setup at the repo root.
+
+## 🧪 Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests with coverage
+pnpm run coverage
+
+# Build the SDK
+pnpm build
+
+# Generate API documentation
+pnpm run docs
+
+# Lint code
+pnpm lint
+```
+
+## 📋 Requirements
+
+- Node.js v18 or higher
+- TypeScript 5.x (for development)
+- Modern browser with ES2020+ support (for browser usage)
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## 📄 License
+
+Apache-2.0 - see LICENSE file for details.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/LumeraProtocol/sdk-js)
+- [Lumera Protocol](https://lumera.io)
+- [Documentation](./docs/api/README.md)
+
+## 💡 Support
+
+- For bug reports and feature requests, please open an issue on GitHub
+- For questions and discussions, join our community channels
+
+---
+
+**Built with ❤️ by the Lumera Protocol team**