@0xio/sdk 2.1.3

package/CHANGELOG.md

@@ -0,0 +1,238 @@
+# Changelog
+
+All notable changes to the 0xio Wallet SDK will be documented in this file.
+
+## [2.1.3] - 2026-01-17
+
+### Fixed
+- **Simplified Balance Fetching**: Reverted to extension-based balance fetching to avoid CORS issues. The SDK now fetches both public and private balance exclusively from the extension's background script, which has unrestricted network access.
+- **Reliability**: Removed complex hybrid architecture in favor of a simpler, more reliable single-source approach.
+
+## [2.1.2] - 2026-01-17
+
+### Fixed
+- **Critical Refactor**: `getBalance` now implements a **Hybrid Architecture**. It fetches Public Balance directly from the RPC (bypassing extension middleware) and merges it with Private Balance from the extension. This permanently resolves "0.00" balance issues caused by extension caching or race conditions.
+- **Feature**: Added support for `private` balance field in the standard Balance response.
+- **Internal**: Added robust mapping for RPC responses to ensure correct public/private `Balance` object structure.
+
+## [2.1.1] - 2026-01-16
+
+### Changed
+- Updated logging to be less verbose in production.
+
+## [2.0.2] - 2025-12-22
+
+### Breaking Changes
+- **Network Migration**: Default network changed from `octra-testnet` to `mainnet`.
+- **Testnet Removal**: Removed hardcoded Testnet configuration.
+- **Compatibility**: SDK now strictly requires Extension versions `2.0.1`, `2.0.3`, or `2.0.4`.
+
+### Changed
+- Updated `NETWORKS` configuration to point to Octra Mainnet Alpha (`https://octra.network`).
+- `isTestnet` flag set to `false` by default.
+
+## [2.0.1] - 2025-11-24
+
+### Breaking Changes
+- **Rebranded message sources**: Changed from `octra-sdk-*` to `0xio-sdk-*` for consistency with 0xio branding
+  - `octra-sdk-request` → `0xio-sdk-request`
+  - `octra-sdk-bridge` → `0xio-sdk-bridge`
+- This is a breaking change that requires wallet extension v2.0+ for compatibility
+
+### Changed
+- Updated package metadata to reflect 0xio Team ownership
+- Changed author from "NullxGery" to "0xio Team"
+- Updated author email from "0xgery@proton.me" to "team@0xio.xyz"
+- Updated repository URL from `0xGery/0xio-sdk` to `0xio-xyz/0xio-sdk`
+- Updated keywords: "0xio" → "0xio wallet", added "octra wallet"
+- Author URL changed to organization: `https://github.com/0xio-xyz`
+
+### Migration Guide
+To upgrade from v1.x to v2.x:
+1. Update SDK: `npm install @0xio/sdk@^2.0.0`
+2. Update 0xio Wallet extension to v2.0 or higher
+3. No code changes required - API remains unchanged
+
+---
+
+## [1.0.4] - 2025-10-23
+
+### Fixed
+- Fixed network configuration to use correct Octra Network RPC endpoint
+- Removed non-existent 0xio-testnet network configuration
+- Updated default network to octra-testnet with https://octra.network RPC
+- Updated explorer URL to https://octrascan.io/
+
+---
+
+## [1.0.3] - 2025-10-04
+
+### Changed
+- Updated CHANGELOG.md with complete release notes for all versions
+
+---
+
+## [1.0.2] - 2025-10-04
+
+### Changed
+- Removed development-only documentation files for cleaner npm package
+- Package now only includes essential documentation (README, CHANGELOG, LICENSE)
+
+---
+
+## [1.0.1] - 2025-10-04
+
+### Fixed
+- Added missing RATE_LIMIT_EXCEEDED error message
+- Fixed branding: Updated all references from "Octra Wallet" to "0xio Wallet"
+- Clarified SDK is for Octra Network/blockchain, not "0xio network"
+
+---
+
+## [1.0.0] - 2025-10-04
+
+### Major Release - Production Ready
+
+This is the first stable release of the 0xio Wallet SDK, a comprehensive bridge for dApps to connect to the 0xio Wallet extension on the Octra Network.
+
+### Security Improvements
+- **Fixed 8 critical wildcard origins** in postMessage communication
+- **Origin validation**: All messages now validate against `window.location.origin`
+- **Rate limiting**: Implemented 50 concurrent requests, 20 requests/second limits
+- **Cryptographic request IDs**: Using `crypto.randomUUID()` instead of predictable sequential IDs
+- **Professional code refactoring**: All files now include comprehensive JSDoc documentation
+
+### Package Changes
+- **Package renamed**: `@0xgery/wallet-sdk` → `@0xio/sdk`
+- **Version bump**: 0.2.1 → 1.0.0 (production-ready)
+- **Repository**: Published to https://github.com/0xGery/0xio-sdk
+- **Homepage**: https://0xio.xyz
+
+### Branding Updates
+- SDK rebranded from "Octra Wallet SDK" to "0xio Wallet SDK"
+- Wallet name: 0xio Wallet (for Octra Network)
+- Currency: OCT (Octra Network's native gas token)
+
+### Files Added
+- LICENSE (MIT)
+- .npmignore (excludes examples, source, docs from npm package)
+- .gitignore (standard Node.js gitignore)
+- Complete integration examples (React, Vue, Vanilla JS)
+
+### Technical Improvements
+- **JSDoc coverage**: 0% → 95%
+- **Code quality**: Refactored all functions to <30 lines
+- **Error handling**: Enhanced with detailed context and diagnostics
+- **TypeScript**: Full type safety with comprehensive type definitions
+
+### Breaking Changes
+None - maintains backward compatibility with exported `OctraWallet` class (also exported as `ZeroXIOWallet`)
+
+---
+
+## [0.2.1] - 2025-09-09
+
+### Changes
+- Update debugging messages to use plain text formatting
+
+---
+
+## [0.2.0] - 2025-09-09
+
+### Major Features Added
+
+- **Built-in Extension Detection**: No longer requires wrapper polling - SDK automatically detects and monitors extension availability
+- **Automatic Retry Logic**: Exponential backoff retry system for all extension requests (3 retries by default)
+- **Enhanced Error Diagnostics**: Detailed error reporting showing specific failure causes, browser state, and extension diagnostics
+- **Event-Based Communication**: Real-time extension events replace polling - instant updates for account changes, balance updates, network switches
+- **Development Mode**: Comprehensive debugging tools with detailed logging for development environments
+
+### Technical Improvements
+
+#### Extension Detection
+- Continuous background monitoring of extension availability
+- Multiple detection methods: runtime checks, DOM signals, extension-specific indicators
+- Automatic reconnection attempts when extension becomes available
+- Detailed browser compatibility diagnostics
+
+#### Retry & Error Handling
+- Exponential backoff retry logic (1s, 2s, 4s delays)
+- Enhanced error context with request IDs, retry counts, timestamps
+- Browser and extension state diagnostics in error details
+- Specific timeout handling with detailed failure information
+
+#### Event System
+- Real-time event forwarding from extension to SDK
+- Automatic balance updates on transaction confirmations
+- Account and network change detection and handling
+- Extension lock/unlock state management
+- Event-driven connection state management
+
+#### Development Tools
+- Advanced logging system with grouped output and table formatting
+- Debug mode auto-detection for localhost/development environments
+- Browser console utilities at `window.__ZEROXIO_SDK_UTILS__`
+- Extension event simulation for testing
+- Comprehensive SDK state inspection tools
+
+### API Enhancements
+
+#### New Utility Functions (now exported)
+```typescript
+// Validation
+isValidAddress, isValidAmount, isValidMessage, isValidFeeLevel, isValidNetworkId
+
+// Formatting
+formatOCT, formatAddress, formatTimestamp, formatTxHash
+
+// Conversion
+toMicroOCT, fromMicroOCT
+
+// Error handling
+createErrorMessage, isErrorType
+
+// Async utilities
+delay, retry, withTimeout
+
+// Browser support
+isBrowser, checkBrowserSupport
+
+// Development
+generateMockData, createLogger
+```
+
+#### Enhanced Debug Information
+- `getDebugInfo()` now includes extension diagnostics and availability state
+- Real-time extension state monitoring
+- Detailed browser environment detection
+
+### Bug Fixes
+- Fixed substr() deprecation warning (replaced with substring())
+- Improved error handling for edge cases in extension communication
+- Better cleanup of pending requests and event listeners
+- Enhanced memory management for background processes
+
+### Developer Experience
+- Rich console output with grouped logging in development mode
+- Automatic debug mode detection for development environments
+- Extension event simulation tools for testing
+- Comprehensive error messages with actionable information
+- SDK state inspection utilities accessible from browser console
+
+### Breaking Changes
+None - this version maintains full backward compatibility with v0.1.x
+
+### Performance Improvements
+- Reduced polling overhead by switching to event-based communication
+- More efficient extension detection with targeted checks
+- Optimized retry logic to reduce unnecessary network calls
+- Background monitoring with minimal CPU impact
+
+---
+
+## [0.1.2-dev] - Previous Version
+- Initial SDK implementation
+- Basic extension communication
+- Core wallet operations
+- Transaction handling
+- Private transfer support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 NullxGery (0xGery)
+
+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,81 @@
+# 0xio Wallet SDK
+
+**Version:** 2.1.3
+
+A comprehensive TypeScript/JavaScript SDK that enables seamless integration between decentralized applications (DApps) and the 0xio Wallet browser extension.
+
+## What's New in v2.1.2 (The "Fertility" Update)
+
+- **Robust "Hybrid" Balance Fetching:** Fixed a critical issue where `getBalance()` could return stale cached data or fail on 404s. The SDK now fetches **Public Balance** directly from the RPC node (`https://octra.network/balance`) while securely retrieving **Private Balance** from the extension.
+- **Private Balance Support:** The `Balance` object now includes a `private` field, populated by the secure context of the 0xio Wallet.
+- **Enhanced Types:** Full type definitions for the composite Public/Private balance structure.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @0xio/sdk
+```
+
+### Usage
+
+```typescript
+import { ZeroXIOWallet } from '@0xio/sdk';
+
+// 1. Initialize
+const wallet = new ZeroXIOWallet({
+  appName: 'My DApp',
+  requiredPermissions: ['read_balance']
+});
+
+await wallet.initialize();
+
+// 2. Connect
+const connection = await wallet.connect();
+console.log('Connected:', connection.address);
+
+// 3. Get Fresh Balance (Public + Private)
+const balance = await wallet.getBalance(true); // true = force refresh
+console.log('Total:', balance.total);
+console.log('Public:', balance.public);
+console.log('Private:', balance.private);
+```
+
+## API Reference
+
+### `wallet.getBalance(forceRefresh?: boolean)`
+
+Fetches the current balance.
+- **Returns**: `Promise<Balance>`
+  ```typescript
+  interface Balance {
+    public: number;   // Visible on chain
+    private: number;  // Encrypted (FHE), decrypted locally
+    total: number;    // public + private
+    currency: 'OCT';
+  }
+  ```
+
+### `wallet.connect(options?)`
+
+Requests a connection to the user's wallet.
+- **Returns**: `Promise<ConnectEvent>` including initial address and balance.
+
+### `wallet.sendTransaction(txData)`
+
+Sends a standard or shielded transaction.
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Link locally
+npm link
+```
+
+## License
+
+MIT License. Copyright © 2026 0xio Team.