@0xobelisk/react 1.2.0-pre.64

package/dist/sui/types.d.ts

@@ -0,0 +1,87 @@
+import { SuiMoveNormalizedModules, Dubhe } from '@0xobelisk/sui-client';
+import type { DubheGraphqlClient } from '@0xobelisk/graphql-client';
+import type { DubheECSWorld } from '@0xobelisk/ecs';
+/**
+ * Network type
+ */
+export type NetworkType = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+/**
+ * Modern Dubhe client configuration for auto-initialization
+ */
+export interface DubheConfig {
+    /** Network type */
+    network: NetworkType;
+    /** Contract package ID */
+    packageId: string;
+    /** Dubhe Schema ID (optional, for enhanced features) */
+    dubheSchemaId: string;
+    /** Contract metadata (required for contract instantiation) */
+    metadata: SuiMoveNormalizedModules;
+    /** Dubhe metadata (enables GraphQL/ECS features) */
+    dubheMetadata?: any;
+    /** Authentication credentials */
+    credentials?: {
+        secretKey?: string;
+        mnemonics?: string;
+    };
+    /** Service endpoints configuration */
+    endpoints?: {
+        graphql?: string;
+        websocket?: string;
+    };
+    /** Performance and behavior options */
+    options?: {
+        /** Enable batch query optimization */
+        enableBatchOptimization?: boolean;
+        /** Default cache timeout (milliseconds) */
+        cacheTimeout?: number;
+        /** Request debounce delay (milliseconds) */
+        debounceMs?: number;
+        /** Auto-reconnect on WebSocket errors */
+        reconnectOnError?: boolean;
+    };
+}
+/**
+ * Return type for the main useDubhe hook
+ */
+export interface DubheReturn {
+    /** Dubhe contract instance with enhanced methods */
+    contract: Dubhe & {
+        /** Enhanced transaction methods with options */
+        txWithOptions?: (system: string, method: string, options?: any) => (params: any) => Promise<any>;
+        /** Enhanced query methods with options */
+        queryWithOptions?: (system: string, method: string, options?: any) => (params: any) => Promise<any>;
+    };
+    /** GraphQL client (null if dubheMetadata not provided) */
+    graphqlClient: DubheGraphqlClient | null;
+    /** ECS World instance (null if GraphQL not available) */
+    ecsWorld: DubheECSWorld | null;
+    /** Contract metadata */
+    metadata: SuiMoveNormalizedModules;
+    /** Network type */
+    network: NetworkType;
+    /** Package ID */
+    packageId: string;
+    /** Dubhe Schema ID (if provided) */
+    dubheSchemaId?: string;
+    /** User address */
+    address: string;
+    /** Configuration options used */
+    options?: {
+        enableBatchOptimization?: boolean;
+        cacheTimeout?: number;
+        debounceMs?: number;
+        reconnectOnError?: boolean;
+    };
+    /** Performance metrics */
+    metrics?: {
+        initTime?: number;
+        requestCount?: number;
+        lastActivity?: number;
+    };
+}
+/**
+ * Compatibility alias for DubheReturn
+ * @deprecated Use DubheReturn instead for better consistency
+ */
+export type ContractReturn = DubheReturn;

package/dist/sui/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Utility Functions for Dubhe Configuration Management
+ *
+ * Features:
+ * - Configuration validation and error handling
+ * - Smart configuration merging with proper type safety
+ * - Type-safe configuration validation
+ */
+import type { DubheConfig } from './types';
+/**
+ * Merge multiple configuration objects with proper deep merging
+ * Later configurations override earlier ones
+ *
+ * @param baseConfig - Base configuration (usually defaults)
+ * @param overrideConfig - Override configuration (user provided)
+ * @returns Merged configuration
+ */
+export declare function mergeConfigurations(baseConfig: Partial<DubheConfig>, overrideConfig?: Partial<DubheConfig>): Partial<DubheConfig>;
+/**
+ * Validate configuration and ensure required fields are present
+ * Throws descriptive errors for missing required fields
+ *
+ * @param config - Configuration to validate
+ * @returns Validated and typed configuration
+ * @throws Error if required fields are missing or invalid
+ */
+export declare function validateConfig(config: Partial<DubheConfig>): DubheConfig;
+/**
+ * Generate a configuration summary for debugging
+ * Hides sensitive information like private keys
+ *
+ * @param config - Configuration to summarize
+ * @returns Safe configuration summary
+ */
+export declare function getConfigSummary(config: DubheConfig): object;

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@0xobelisk/react",
+  "version": "1.2.0-pre.64",
+  "description": "React integration for Dubhe framework with Sui blockchain support",
+  "keywords": [
+    "dubhe",
+    "react",
+    "blockchain",
+    "sui",
+    "web3"
+  ],
+  "homepage": "https://github.com/0xobelisk/dubhe/tree/main/packages/react#readme",
+  "bugs": "https://github.com/0xobelisk/dubhe/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xobelisk/dubhe.git"
+  },
+  "license": "Apache-2.0",
+  "author": "team@obelisk.build",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sui": {
+      "source": "./src/sui/index.ts",
+      "import": "./dist/sui/index.mjs",
+      "require": "./dist/sui/index.js",
+      "types": "./dist/sui/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@nanostores/react": "^0.8.0",
+    "nanostores": "^0.11.4",
+    "@0xobelisk/ecs": "1.2.0-pre.64",
+    "@0xobelisk/graphql-client": "1.2.0-pre.64"
+  },
+  "devDependencies": {
+    "@types/node": "^20.8.7",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.8.0",
+    "@typescript-eslint/parser": "^6.8.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.0.1",
+    "prettier": "3.3.3",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "tsup": "^7.1.0",
+    "typescript": "^5.2.2",
+    "@0xobelisk/sui-client": "1.2.0-pre.64"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "zod": "^3.25.0 || ^4.0.0",
+    "@0xobelisk/sui-client": "1.2.0-pre.64"
+  },
+  "peerDependenciesMeta": {
+    "@0xobelisk/sui-client": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "npm run build:types && npm run build:tsup",
+    "build:tsup": "tsup ./src/index.ts ./src/sui/index.ts --format esm,cjs --sourcemap --dts",
+    "build:types": "tsc --build",
+    "clean": "rm -rf tsconfig.tsbuildinfo ./dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write '**/*.{ts,tsx,json,md}'",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "test": "pnpm test:typecheck",
+    "test:typecheck": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "validate": "pnpm format:check && pnpm type-check",
+    "watch": "pnpm run clean & pnpm run watch:types & pnpm run watch:tsup",
+    "watch:tsup": "tsup ./src/index.ts ./src/sui/index.ts --format esm,cjs --clean --splitting --watch --dts",
+    "watch:types": "tsc --watch"
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @0xobelisk/react - Modern Dubhe React Integration
+ *
+ * 🚀 Provides simple, powerful React experience for multi-chain blockchain development
+ *
+ * Currently supported:
+ * - Sui blockchain ✅
+ * - Aptos blockchain (coming soon)
+ * - Initia blockchain (coming soon)
+ */
+
+// Sui integration
+export * from './sui/index';
+// TODO: Future extensions
+// export * from './aptos/index';
+// export * from './initia/index';

package/src/sui/config.ts

@@ -0,0 +1,90 @@
+/**
+ * Configuration Management for Dubhe React Integration
+ *
+ * Features:
+ * - Type-safe configuration interface
+ * - Configuration validation and error handling
+ * - Smart merging of defaults and explicit config
+ * - No environment variable handling (developers should handle environment variables themselves)
+ */
+
+import { useMemo } from 'react';
+import type { DubheConfig, NetworkType } from './types';
+import { mergeConfigurations, validateConfig } from './utils';
+
+/**
+ * Default configuration object with sensible defaults
+ */
+export const DEFAULT_CONFIG: Partial<DubheConfig> = {
+  endpoints: {
+    graphql: 'http://localhost:4000/graphql',
+    websocket: 'ws://localhost:4000/graphql'
+  },
+  options: {
+    enableBatchOptimization: true,
+    cacheTimeout: 5000,
+    debounceMs: 100,
+    reconnectOnError: true
+  }
+};
+
+/**
+ * Configuration Hook: useDubheConfig
+ *
+ * Merges defaults with explicit configuration provided by the developer
+ *
+ * Note: Environment variables should be handled by the developer before passing to this hook
+ *
+ * @param config - Complete or partial configuration object
+ * @returns Complete, validated DubheConfig
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with explicit config
+ * const config = useDubheConfig({
+ *   network: 'testnet',
+ *   packageId: '0x123...',
+ *   metadata: contractMetadata,
+ *   credentials: {
+ *     secretKey: process.env.NEXT_PUBLIC_PRIVATE_KEY // Handle env vars yourself
+ *   }
+ * });
+ *
+ * // With helper function to handle environment variables
+ * const getConfigFromEnv = () => ({
+ *   network: process.env.NEXT_PUBLIC_NETWORK as NetworkType,
+ *   packageId: process.env.NEXT_PUBLIC_PACKAGE_ID,
+ *   credentials: {
+ *     secretKey: process.env.NEXT_PUBLIC_PRIVATE_KEY
+ *   }
+ * });
+ *
+ * const config = useDubheConfig({
+ *   ...getConfigFromEnv(),
+ *   metadata: contractMetadata
+ * });
+ * ```
+ */
+export function useDubheConfig(config: Partial<DubheConfig>): DubheConfig {
+  // Memoize the stringified config to detect actual changes
+  const configKey = useMemo(() => {
+    return JSON.stringify(config);
+  }, [config]);
+
+  return useMemo(() => {
+    // Merge configurations: defaults -> user provided config
+    const mergedConfig = mergeConfigurations(DEFAULT_CONFIG, config);
+
+    // Validate the final configuration
+    const validatedConfig = validateConfig(mergedConfig);
+
+    // if (process.env.NODE_ENV === 'development') {
+    //   console.log('🔧 Dubhe Config:', {
+    //     ...validatedConfig,
+    //     credentials: validatedConfig.credentials?.secretKey ? '[REDACTED]' : undefined
+    //   });
+    // }
+
+    return validatedConfig;
+  }, [configKey]);
+}

package/src/sui/hooks.ts

@@ -0,0 +1,144 @@
+/**
+ * Modern Dubhe React Hooks - Provider Pattern
+ *
+ * Features:
+ * - 🎯 Simple API design with Provider pattern
+ * - ⚡ Single client initialization with useRef
+ * - 🔧 Configuration-driven setup (developers handle environment variables themselves)
+ * - 🛡️ Complete type safety with strict TypeScript
+ * - 📦 Context-based client sharing across components
+ */
+import { Dubhe } from '@0xobelisk/sui-client';
+
+import {
+  useDubheContext,
+  useDubheFromProvider,
+  useDubheContractFromProvider,
+  useDubheGraphQLFromProvider,
+  useDubheECSFromProvider
+} from './provider';
+import type { DubheConfig, DubheReturn } from './types';
+
+/**
+ * Primary Hook: useDubhe
+ *
+ * Uses Provider pattern to access shared Dubhe clients with guaranteed single initialization.
+ * Must be used within a DubheProvider.
+ *
+ * @returns Complete Dubhe ecosystem with contract, GraphQL, ECS, and metadata
+ *
+ * @example
+ * ```typescript
+ * // App setup with Provider
+ * function App() {
+ *   const config = {
+ *     network: 'devnet',
+ *     packageId: '0x123...',
+ *     metadata: contractMetadata,
+ *     credentials: {
+ *       secretKey: process.env.NEXT_PUBLIC_PRIVATE_KEY
+ *     }
+ *   };
+ *
+ *   return (
+ *     <DubheProvider config={config}>
+ *       <MyDApp />
+ *     </DubheProvider>
+ *   );
+ * }
+ *
+ * // Component usage
+ * function MyDApp() {
+ *   const { contract, address } = useDubhe();
+ *   return <div>Connected as {address}</div>;
+ * }
+ * ```
+ */
+export function useDubhe(): DubheReturn {
+  return useDubheFromProvider();
+}
+
+/**
+ * Individual Instance Hook: useDubheContract
+ *
+ * Returns only the Dubhe contract instance from Provider context.
+ * More efficient than useDubhe() when only contract access is needed.
+ *
+ * @returns Dubhe contract instance
+ *
+ * @example
+ * ```typescript
+ * function TransactionComponent() {
+ *   const contract = useDubheContract();
+ *
+ *   const handleTransaction = async () => {
+ *     const tx = new Transaction();
+ *     await contract.tx.my_system.my_method({ tx });
+ *   };
+ *
+ *   return <button onClick={handleTransaction}>Execute</button>;
+ * }
+ * ```
+ */
+export function useDubheContract(): Dubhe {
+  return useDubheContractFromProvider();
+}
+
+/**
+ * Individual Instance Hook: useDubheGraphQL
+ *
+ * Returns only the GraphQL client from Provider context.
+ * More efficient than useDubhe() when only GraphQL access is needed.
+ *
+ * @returns GraphQL client instance (null if dubheMetadata not provided)
+ *
+ * @example
+ * ```typescript
+ * function DataComponent() {
+ *   const graphqlClient = useDubheGraphQL();
+ *
+ *   useEffect(() => {
+ *     if (graphqlClient) {
+ *       graphqlClient.query({ ... }).then(setData);
+ *     }
+ *   }, [graphqlClient]);
+ *
+ *   return <div>{data && JSON.stringify(data)}</div>;
+ * }
+ * ```
+ */
+export function useDubheGraphQL(): any | null {
+  return useDubheGraphQLFromProvider();
+}
+
+/**
+ * Individual Instance Hook: useDubheECS
+ *
+ * Returns only the ECS World instance from Provider context.
+ * More efficient than useDubhe() when only ECS access is needed.
+ *
+ * @returns ECS World instance (null if GraphQL client not available)
+ *
+ * @example
+ * ```typescript
+ * function ECSComponent() {
+ *   const ecsWorld = useDubheECS();
+ *
+ *   useEffect(() => {
+ *     if (ecsWorld) {
+ *       ecsWorld.getComponent('MyComponent').then(setComponent);
+ *     }
+ *   }, [ecsWorld]);
+ *
+ *   return <div>ECS Component Data</div>;
+ * }
+ * ```
+ */
+export function useDubheECS(): any | null {
+  return useDubheECSFromProvider();
+}
+
+/**
+ * Compatibility alias for useDubhe
+ */
+export const useContract = useDubhe;

package/src/sui/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @0xobelisk/react/sui - Modern Dubhe React Integration
+ *
+ * 🚀 Simple, powerful, type-safe Sui blockchain development experience
+ *
+ * Features:
+ * - ⚡ Auto-initialization with environment variable support
+ * - 🔧 Configuration-driven setup with smart defaults
+ * - 🛡️ Complete type safety with strict TypeScript
+ * - 📦 Direct instance access without connection state management
+ * - 🎯 Intuitive API design following React best practices
+ */
+
+// ============ Type Exports ============
+export type { NetworkType, DubheConfig, DubheReturn, ContractReturn } from './types';
+
+// ============ Configuration Management ============
+export { useDubheConfig, DEFAULT_CONFIG } from './config';
+
+export { mergeConfigurations, validateConfig, getConfigSummary } from './utils';
+
+// ============ Provider Component ============
+export { DubheProvider } from './provider';
+
+// ============ Modern React Hooks ============
+export {
+  // Primary Hook - Provider pattern
+  useDubhe,
+
+  // Compatibility alias
+  useContract,
+
+  // Individual Instance Hooks - optimized for specific use cases
+  useDubheContract,
+  useDubheGraphQL,
+  useDubheECS
+} from './hooks';