@0xobelisk/react 1.2.0-pre.100

package/dist/sui/provider.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Dubhe Provider - useRef Pattern for Client Management
+ *
+ * Features:
+ * - 🎯 Single client instances across application lifecycle
+ * - ⚡ useRef-based storage (no re-initialization on re-renders)
+ * - 🔧 Provider pattern for dependency injection
+ * - 🛡️ Complete type safety with strict TypeScript
+ * - 📦 Context-based client sharing
+ */
+import { ReactNode } from 'react';
+import { Dubhe } from '@0xobelisk/sui-client';
+import { DubheGraphqlClient } from '@0xobelisk/graphql-client';
+import { DubheECSWorld } from '@0xobelisk/ecs';
+import { DubheGrpcClient } from '@0xobelisk/grpc-client';
+import type { DubheConfig, DubheReturn } from './types';
+/**
+ * Context interface for Dubhe client instances
+ * All clients are stored using useRef to ensure single initialization
+ */
+interface DubheContextValue {
+    getContract: () => Dubhe;
+    getGraphqlClient: () => DubheGraphqlClient;
+    getGrpcClient: () => DubheGrpcClient;
+    getEcsWorld: () => DubheECSWorld;
+    getAddress: () => string;
+    getMetrics: () => {
+        initTime: number;
+        requestCount: number;
+        lastActivity: number;
+    };
+    config: DubheConfig;
+    updateConfig: (newConfig: Partial<DubheConfig>) => void;
+    resetClients: (options?: {
+        resetContract?: boolean;
+        resetGraphql?: boolean;
+        resetGrpc?: boolean;
+        resetEcs?: boolean;
+    }) => void;
+}
+/**
+ * Props interface for DubheProvider component
+ */
+interface DubheProviderProps {
+    /** Configuration for Dubhe initialization */
+    config: Partial<DubheConfig>;
+    /** Child components that will have access to Dubhe clients */
+    children: ReactNode;
+}
+/**
+ * DubheProvider Component - useRef Pattern Implementation
+ *
+ * This Provider uses useRef to store client instances, ensuring they are:
+ * 1. Created only once during component lifecycle
+ * 2. Persisted across re-renders without re-initialization
+ * 3. Shared efficiently via React Context
+ *
+ * Key advantages over useMemo:
+ * - useRef guarantees single initialization (useMemo can re-run on dependency changes)
+ * - No dependency array needed (eliminates potential re-initialization bugs)
+ * - Better performance for heavy client objects
+ * - Clearer separation of concerns via Provider pattern
+ *
+ * @param props - Provider props containing config and children
+ * @returns Provider component wrapping children with Dubhe context
+ *
+ * @example
+ * ```typescript
+ * // App root setup
+ * function App() {
+ *   const dubheConfig = {
+ *     network: 'devnet',
+ *     packageId: '0x123...',
+ *     metadata: contractMetadata,
+ *     credentials: {
+ *       secretKey: process.env.NEXT_PUBLIC_PRIVATE_KEY
+ *     }
+ *   };
+ *
+ *   return (
+ *     <DubheProvider config={dubheConfig}>
+ *       <MyApplication />
+ *     </DubheProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function DubheProvider({ config, children }: DubheProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Custom hook to access Dubhe context
+ * Provides type-safe access to all Dubhe client instances
+ *
+ * @returns DubheContextValue with all client getters and config
+ * @throws Error if used outside of DubheProvider
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const dubheContext = useDubheContext();
+ *
+ *   const contract = dubheContext.getContract();
+ *   const graphqlClient = dubheContext.getGraphqlClient();
+ *   const ecsWorld = dubheContext.getEcsWorld();
+ *   const address = dubheContext.getAddress();
+ *
+ *   return <div>Connected as {address}</div>;
+ * }
+ * ```
+ */
+export declare function useDubheContext(): DubheContextValue;
+/**
+ * Enhanced hook that mimics the original useDubhe API
+ * Uses the Provider pattern internally but maintains backward compatibility
+ *
+ * @returns DubheReturn object with all instances and metadata
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { contract, graphqlClient, ecsWorld, address } = useDubheFromProvider();
+ *
+ *   const handleTransaction = async () => {
+ *     const tx = new Transaction();
+ *     await contract.tx.my_system.my_method({ tx });
+ *   };
+ *
+ *   return <button onClick={handleTransaction}>Execute</button>;
+ * }
+ * ```
+ */
+export declare function useDubheFromProvider(): DubheReturn;
+/**
+ * Individual client hooks for components that only need specific instances
+ * These are more efficient than useDubheFromProvider for single-client usage
+ */
+/**
+ * Hook for accessing only the Dubhe contract instance
+ */
+export declare function useDubheContractFromProvider(): Dubhe;
+/**
+ * Hook for accessing only the GraphQL client instance
+ */
+export declare function useDubheGraphQLFromProvider(): DubheGraphqlClient;
+/**
+ * Hook for accessing only the ECS World instance
+ */
+export declare function useDubheECSFromProvider(): DubheECSWorld;
+/**
+ * Hook for accessing only the gRPC client instance
+ */
+export declare function useDubheGrpcFromProvider(): DubheGrpcClient;
+/**
+ * Hook for accessing configuration update methods
+ *
+ * @returns Object with updateConfig and resetClients methods
+ *
+ * @example
+ * ```typescript
+ * function ConfigUpdater() {
+ *   const { updateConfig, resetClients, config } = useDubheConfigUpdate();
+ *
+ *   const switchNetwork = () => {
+ *     updateConfig({
+ *       network: 'testnet',
+ *       packageId: '0xnew...'
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Current network: {config.network}</p>
+ *       <button onClick={switchNetwork}>Switch to Testnet</button>
+ *       <button onClick={resetClients}>Reset Clients</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDubheConfigUpdate(): {
+    updateConfig: (newConfig: Partial<DubheConfig>) => void;
+    resetClients: (options?: {
+        resetContract?: boolean;
+        resetGraphql?: boolean;
+        resetGrpc?: boolean;
+        resetEcs?: boolean;
+    }) => void;
+    config: DubheConfig;
+};
+export {};

package/dist/sui/types.d.ts

@@ -0,0 +1,100 @@
+import { SuiMoveNormalizedModules, Dubhe } from '@0xobelisk/sui-client';
+import type { DubheGraphqlClient } from '@0xobelisk/graphql-client';
+import type { DubheECSWorld } from '@0xobelisk/ecs';
+import type { DubheGrpcClient } from '@0xobelisk/grpc-client';
+/**
+ * Network type
+ */
+export type NetworkType = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+/**
+ * Modern Dubhe client configuration for auto-initialization
+ * Aligned with @0xobelisk/client configuration for consistency
+ */
+export interface DubheConfig {
+    /** Network type */
+    network: NetworkType;
+    /** Contract package ID */
+    packageId: string;
+    /** Contract metadata (required for contract instantiation) */
+    metadata: any;
+    /** Dubhe Schema ID (optional, for enhanced features) */
+    dubheSchemaId?: string;
+    /** Dubhe metadata (enables GraphQL/ECS features) */
+    dubheMetadata?: any;
+    /** Authentication credentials */
+    credentials?: {
+        /** Private key (base64 or hex string) */
+        secretKey?: string;
+        /** Mnemonic phrase (12 or 24 words) */
+        mnemonics?: string;
+    };
+    /** Service endpoints configuration */
+    endpoints?: {
+        /** Full node RPC URLs (can provide multiple for redundancy) */
+        fullnodeUrls?: string[];
+        /** GraphQL endpoint URL */
+        graphql?: string;
+        /** WebSocket endpoint URL for subscriptions */
+        websocket?: string;
+        /** gRPC endpoint URL */
+        grpc?: string;
+        /** Dubhe Channel API URL */
+        channelUrl?: 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;
+    };
+}
+/**
+ * Type alias for consistency with @0xobelisk/client package
+ */
+export type ClientConfig = DubheConfig;
+/**
+ * Return type for the main useDubhe hook
+ */
+export interface DubheReturn {
+    /** Dubhe contract instance */
+    contract: Dubhe;
+    /** GraphQL client (always available, uses default localhost endpoint if not configured) */
+    graphqlClient: DubheGraphqlClient;
+    /** gRPC client (always available, uses default localhost endpoint if not configured) */
+    grpcClient: DubheGrpcClient;
+    /** ECS World instance (always available, depends on GraphQL client) */
+    ecsWorld: DubheECSWorld;
+    /** 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,104 @@
+{
+  "name": "@0xobelisk/react",
+  "version": "1.2.0-pre.100",
+  "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/grpc-client": "1.2.0-pre.100",
+    "@0xobelisk/sui-client": "1.2.0-pre.100",
+    "@0xobelisk/graphql-client": "1.2.0-pre.100",
+    "@0xobelisk/ecs": "1.2.0-pre.100"
+  },
+  "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": "^9.0.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"
+  },
+  "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.100"
+  },
+  "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": "eslint . --ext .ts --ext .tsx",
+    "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 } 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]);
+}