@0xobelisk/react 1.2.0-pre.100

package/dist/sui/config.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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 type { DubheConfig } from './types';
+/**
+ * Default configuration object with sensible defaults
+ */
+export declare const DEFAULT_CONFIG: Partial<DubheConfig>;
+/**
+ * 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 declare function useDubheConfig(config: Partial<DubheConfig>): DubheConfig;

package/dist/sui/hooks.d.ts

@@ -0,0 +1,159 @@
+/**
+ * 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 type { DubheGraphqlClient } from '@0xobelisk/graphql-client';
+import type { DubheECSWorld } from '@0xobelisk/ecs';
+import type { 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 declare function useDubhe(): DubheReturn;
+/**
+ * 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 declare function useDubheContract(): Dubhe;
+/**
+ * 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 (always available with default localhost endpoint)
+ *
+ * @example
+ * ```typescript
+ * function DataComponent() {
+ *   const graphqlClient = useDubheGraphQL();
+ *
+ *   useEffect(() => {
+ *     graphqlClient.query({ ... }).then(setData);
+ *   }, [graphqlClient]);
+ *
+ *   return <div>{data && JSON.stringify(data)}</div>;
+ * }
+ * ```
+ */
+export declare function useDubheGraphQL(): DubheGraphqlClient;
+/**
+ * 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 (always available, depends on GraphQL client)
+ *
+ * @example
+ * ```typescript
+ * function ECSComponent() {
+ *   const ecsWorld = useDubheECS();
+ *
+ *   useEffect(() => {
+ *     ecsWorld.getComponent('MyComponent').then(setComponent);
+ *   }, [ecsWorld]);
+ *
+ *   return <div>ECS Component Data</div>;
+ * }
+ * ```
+ */
+export declare function useDubheECS(): DubheECSWorld;
+/**
+ * Hook for dynamic configuration updates
+ *
+ * Provides methods to update provider configuration at runtime
+ *
+ * @returns Object with updateConfig, resetClients methods and current config
+ *
+ * @example
+ * ```typescript
+ * function NetworkSwitcher() {
+ *   const { updateConfig, config } = useDubheConfigUpdate();
+ *
+ *   const switchToTestnet = () => {
+ *     updateConfig({
+ *       network: 'testnet',
+ *       packageId: '0xTestnetPackageId...'
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Network: {config.network}</p>
+ *       <button onClick={switchToTestnet}>Switch to Testnet</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDubheConfigUpdate(): {
+    updateConfig: (newConfig: Partial<import("./types").DubheConfig>) => void;
+    resetClients: (options?: {
+        resetContract?: boolean;
+        resetGraphql?: boolean;
+        resetGrpc?: boolean;
+        resetEcs?: boolean;
+    }) => void;
+    config: import("./types").DubheConfig;
+};
+/**
+ * Compatibility alias for useDubhe
+ */
+export declare const useContract: typeof useDubhe;

package/dist/sui/index.d.mts

@@ -0,0 +1,389 @@
+import { Dubhe, SuiMoveNormalizedModules } from '@0xobelisk/sui-client';
+import { DubheGraphqlClient } from '@0xobelisk/graphql-client';
+import { DubheECSWorld } from '@0xobelisk/ecs';
+import { DubheGrpcClient } from '@0xobelisk/grpc-client';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Network type
+ */
+type NetworkType = 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+/**
+ * Modern Dubhe client configuration for auto-initialization
+ * Aligned with @0xobelisk/client configuration for consistency
+ */
+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
+ */
+type ClientConfig = DubheConfig;
+/**
+ * Return type for the main useDubhe hook
+ */
+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
+ */
+type ContractReturn = DubheReturn;
+
+/**
+ * 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)
+ */
+
+/**
+ * Default configuration object with sensible defaults
+ */
+declare const DEFAULT_CONFIG: Partial<DubheConfig>;
+/**
+ * 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
+ * });
+ * ```
+ */
+declare function useDubheConfig(config: Partial<DubheConfig>): DubheConfig;
+
+/**
+ * Utility Functions for Dubhe Configuration Management
+ *
+ * Features:
+ * - Configuration validation and error handling
+ * - Smart configuration merging with proper type safety
+ * - Type-safe configuration validation
+ */
+
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+declare function getConfigSummary(config: DubheConfig): object;
+
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function DubheProvider({ config, children }: DubheProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDubhe(): DubheReturn;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useDubheContract(): Dubhe;
+/**
+ * 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 (always available with default localhost endpoint)
+ *
+ * @example
+ * ```typescript
+ * function DataComponent() {
+ *   const graphqlClient = useDubheGraphQL();
+ *
+ *   useEffect(() => {
+ *     graphqlClient.query({ ... }).then(setData);
+ *   }, [graphqlClient]);
+ *
+ *   return <div>{data && JSON.stringify(data)}</div>;
+ * }
+ * ```
+ */
+declare function useDubheGraphQL(): DubheGraphqlClient;
+/**
+ * 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 (always available, depends on GraphQL client)
+ *
+ * @example
+ * ```typescript
+ * function ECSComponent() {
+ *   const ecsWorld = useDubheECS();
+ *
+ *   useEffect(() => {
+ *     ecsWorld.getComponent('MyComponent').then(setComponent);
+ *   }, [ecsWorld]);
+ *
+ *   return <div>ECS Component Data</div>;
+ * }
+ * ```
+ */
+declare function useDubheECS(): DubheECSWorld;
+/**
+ * Hook for dynamic configuration updates
+ *
+ * Provides methods to update provider configuration at runtime
+ *
+ * @returns Object with updateConfig, resetClients methods and current config
+ *
+ * @example
+ * ```typescript
+ * function NetworkSwitcher() {
+ *   const { updateConfig, config } = useDubheConfigUpdate();
+ *
+ *   const switchToTestnet = () => {
+ *     updateConfig({
+ *       network: 'testnet',
+ *       packageId: '0xTestnetPackageId...'
+ *     });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <p>Network: {config.network}</p>
+ *       <button onClick={switchToTestnet}>Switch to Testnet</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useDubheConfigUpdate(): {
+    updateConfig: (newConfig: Partial<DubheConfig>) => void;
+    resetClients: (options?: {
+        resetContract?: boolean;
+        resetGraphql?: boolean;
+        resetGrpc?: boolean;
+        resetEcs?: boolean;
+    }) => void;
+    config: DubheConfig;
+};
+/**
+ * Compatibility alias for useDubhe
+ */
+declare const useContract: typeof useDubhe;
+
+export { type ClientConfig, type ContractReturn, DEFAULT_CONFIG, type DubheConfig, DubheProvider, type DubheReturn, type NetworkType, getConfigSummary, mergeConfigurations, useContract, useDubhe, useDubheConfig, useDubheConfigUpdate, useDubheContract, useDubheECS, useDubheGraphQL, validateConfig };