@0xobelisk/client 0.4.7 → 1.2.0-pre.92

package/package.json

@@ -1,149 +1,88 @@
 {
   "name": "@0xobelisk/client",
-  "version": "0.4.7",
-  "description": "Tookit for interacting with move eps framework",
+  "version": "1.2.0-pre.92",
+  "description": "Unified client creation layer for Dubhe framework with multi-chain support",
   "keywords": [
+    "dubhe",
+    "client",
+    "blockchain",
     "sui",
-    "obelisk labs",
-    "move",
-    "blockchain"
+    "web3"
   ],
-  "author": "team@obelisk.build",
-  "homepage": "https://github.com/0xobelisk/obelisk-engine/tree/main/package/@0xobelisk/client#readme",
-  "bugs": "https://github.com/0xobelisk/obelisk-engine/issues",
+  "homepage": "https://github.com/0xobelisk/dubhe/tree/main/packages/client#readme",
+  "bugs": "https://github.com/0xobelisk/dubhe/issues",
   "repository": {
     "type": "git",
-    "url": "https://github.com/0xobelisk/obelisk-engine.git"
+    "url": "https://github.com/0xobelisk/dubhe.git"
   },
   "license": "Apache-2.0",
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.ts",
+  "author": "team@obelisk.build",
   "exports": {
-    ".": {
-      "source": "./src/index.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
+    "./sui": {
+      "source": "./src/sui/index.ts",
+      "import": "./dist/sui/index.mjs",
+      "require": "./dist/sui/index.js",
+      "types": "./dist/sui/index.d.ts"
     }
   },
+  "browser": "./dist/browser/obelisk-client.min.js",
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@mysten/bcs": "^0.7.3",
-    "@mysten/sui.js": "^0.41.0",
-    "@scure/bip39": "^1.2.1",
-    "assert": "^2.0.0",
-    "colorts": "^0.1.63",
-    "husky": "^8.0.3",
-    "keccak256": "^1.0.6",
-    "process": "^0.11.10",
-    "superstruct": "^1.0.3",
-    "tmp": "^0.2.1",
-    "ts-retry-promise": "^0.7.0"
-  },
-  "peerDependencies": {
-    "@mysten/sui.js": "^0.41.0"
+    "dotenv": "^17.2.3",
+    "@0xobelisk/ecs": "1.2.0-pre.92",
+    "@0xobelisk/graphql-client": "1.2.0-pre.92",
+    "@0xobelisk/grpc-client": "1.2.0-pre.92",
+    "@0xobelisk/sui-client": "1.2.0-pre.92"
   },
   "devDependencies": {
-    "@commitlint/cli": "^17.6.6",
-    "@commitlint/config-conventional": "^17.6.6",
-    "@commitlint/prompt-cli": "^17.6.6",
-    "@types/node": "^20.5.0",
-    "@types/tmp": "^0.2.3",
-    "@typescript-eslint/eslint-plugin": "^5.60.1",
-    "@typescript-eslint/parser": "^5.60.1",
-    "dotenv": "^16.3.1",
-    "eslint": "^8.43.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "lint-staged": "^13.2.3",
-    "prettier": "^2.8.8",
-    "ts-node": "^10.9.1",
-    "tsconfig-paths": "^4.2.0",
+    "@types/node": "^20.8.7",
+    "@typescript-eslint/eslint-plugin": "^6.8.0",
+    "@typescript-eslint/parser": "^6.8.0",
+    "@vitest/coverage-v8": "^1.0.4",
+    "@vitest/ui": "^1.0.4",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.0.1",
+    "prettier": "3.3.3",
+    "terser-webpack-plugin": "^5.3.10",
+    "ts-loader": "^9.5.1",
     "tsup": "^7.1.0",
-    "typedoc": "^0.24.8",
-    "typescript": "^5.0.4"
+    "tsx": "^4.20.6",
+    "typescript": "^5.2.2",
+    "vitest": "^1.0.4",
+    "webpack": "^5.94.0",
+    "webpack-cli": "^5.1.4"
   },
-  "lint-staged": {
-    "**/*.ts": [
-      "pnpm run format:fix",
-      "pnpm run lint:fix"
-    ],
-    "**/*.json|md": [
-      "pnpm run format:fix"
-    ]
-  },
-  "commitlint": {
-    "extends": [
-      "@commitlint/config-conventional"
-    ]
-  },
-  "prettier": {
-    "trailingComma": "es5",
-    "tabWidth": 2,
-    "semi": true,
-    "singleQuote": true,
-    "useTabs": false,
-    "quoteProps": "as-needed",
-    "bracketSpacing": true,
-    "arrowParens": "always",
-    "endOfLine": "lf"
+  "engines": {
+    "node": ">=18.0.0"
   },
-  "eslintConfig": {
-    "root": true,
-    "env": {
-      "browser": true,
-      "node": true,
-      "es2022": true
-    },
-    "extends": [
-      "eslint:recommended",
-      "plugin:@typescript-eslint/eslint-recommended",
-      "plugin:prettier/recommended"
-    ],
-    "plugins": [
-      "@typescript-eslint",
-      "prettier"
-    ],
-    "parser": "@typescript-eslint/parser",
-    "rules": {
-      "prettier/prettier": "warn",
-      "@typescript-eslint/no-explicit-any": "off",
-      "no-unused-vars": "off",
-      "@typescript-eslint/no-unused-vars": [
-        "error",
-        {
-          "argsIgnorePattern": "^_",
-          "varsIgnorePattern": "^_",
-          "caughtErrorsIgnorePattern": "^_"
-        }
-      ]
-    }
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
-    "clean": "rm -rf tsconfig.tsbuildinfo ./dist",
-    "build": "npm run build:types && npm run build:tsup",
-    "build:tsup": "tsup ./src/index.ts --format esm,cjs --sourcemap",
+    "build": "npm run build:types && npm run build:tsup && npm run build:browser",
+    "build:browser": "webpack --mode production",
+    "build:browser:dev": "webpack --mode development",
+    "build:tsup": "tsup",
     "build:types": "tsc --build",
-    "watch:tsup": "tsup ./src/index.ts --format esm,cjs --clean --splitting --watch",
-    "watch:types": "tsc --watch",
+    "clean": "rm -rf tsconfig.tsbuildinfo ./dist",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "format:fix": "prettier --write '**/*.{ts,json,md}'",
+    "lint": "eslint . --ext .ts",
+    "serve": "python3 -m http.server 8080",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:typecheck": "tsc --noEmit",
+    "test:ui": "vitest --ui",
+    "test:watch": "vitest watch",
+    "type-check": "tsc --noEmit",
+    "validate": "pnpm format:check && pnpm type-check && pnpm test",
     "watch": "pnpm run clean & pnpm run watch:types & pnpm run watch:tsup",
-    "test": "pnpm test:typecheck && pnpm test:unit",
-    "test:typecheck": "tsc -p ./test",
-    "format:fix": "prettier --ignore-path 'dist/* docs/*' --write '**/*.{ts,json,md}'",
-    "lint:fix": "eslint . --ignore-pattern dist --ext .ts --fix",
-    "commit": "commit",
-    "doc": "typedoc --out docs src/index.ts",
-    "chalk": "^5.0.1",
-    "prettier": "^2.8.4",
-    "prettier-plugin-rust": "^0.1.9"
+    "watch:tsup": "tsup --watch",
+    "watch:types": "tsc --watch"
   }
 }

package/src/index.ts

@@ -1,9 +1,31 @@
-export * from '@mysten/sui.js';
-export { Ed25519Keypair } from '@mysten/sui.js/keypairs/ed25519';
-export { BCS, getSuiMoveConfig } from '@mysten/bcs';
-export { Obelisk } from './obelisk';
-export { SuiAccountManager } from './libs/suiAccountManager';
-export { SuiTxBlock } from './libs/suiTxBuilder';
-export { SuiContractFactory } from './libs/suiContractFactory';
-export { loadMetadata } from './metadata';
-export type * from './types';
+/**
+ * @0xobelisk/client - Unified Client Creation Layer for Dubhe Framework
+ *
+ * This package provides a unified interface for creating blockchain clients
+ * across different chains. Currently supports Sui, with more chains coming soon.
+ *
+ * Usage:
+ * - For Sui: import from '@0xobelisk/client/sui'
+ * - For Aptos: import from '@0xobelisk/client/aptos' (coming soon)
+ * - For Initia: import from '@0xobelisk/client/initia' (coming soon)
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@0xobelisk/client/sui';
+ *
+ * const client = createClient({
+ *   network: 'devnet',
+ *   packageId: '0x123...',
+ *   metadata: contractMetadata,
+ *   credentials: { secretKey: '...' }
+ * });
+ * ```
+ */
+
+// Main entry point - currently redirects to Sui
+// In the future, this could export a chain-agnostic interface
+
+/**
+ * Note: Import chain-specific clients from their subpaths:
+ * - '@0xobelisk/client/sui'
+ */

package/src/sui/client.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createClient, isNetworkType, validateClientConfig } from './client';
+import type { ClientConfig } from './types';
+
+// Mock all dependencies
+vi.mock('@0xobelisk/sui-client', () => ({
+  Dubhe: vi.fn(function (this: any, config) {
+    this.networkType = config.networkType;
+    this.packageId = config.packageId;
+    this.tx = {};
+    this.query = {};
+    this.getAddress = () => '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef';
+    return this;
+  })
+}));
+
+vi.mock('@0xobelisk/graphql-client', () => ({
+  createDubheGraphqlClient: vi.fn((config) => ({
+    endpoint: config.endpoint,
+    query: vi.fn(),
+    subscribe: vi.fn()
+  }))
+}));
+
+vi.mock('@0xobelisk/grpc-client', () => ({
+  DubheGrpcClient: vi.fn(function (this: any, config) {
+    this.baseUrl = config.baseUrl;
+    this.getEntities = vi.fn();
+    this.getEntity = vi.fn();
+    return this;
+  })
+}));
+
+vi.mock('@0xobelisk/ecs', () => ({
+  createECSWorld: vi.fn(() => ({
+    getEntities: vi.fn(() => []),
+    getEntity: vi.fn(),
+    subscribe: vi.fn()
+  }))
+}));
+
+describe('createClient', () => {
+  const mockMetadata = {
+    name: 'test-package',
+    version: '1.0.0',
+    schemas: {}
+  };
+
+  const validConfig: ClientConfig = {
+    network: 'devnet',
+    packageId: '0x123',
+    metadata: mockMetadata
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  describe('Basic functionality', () => {
+    it('should create client with minimal valid config', () => {
+      const client = createClient(validConfig);
+
+      expect(client).toBeDefined();
+      expect(client.contract).toBeDefined();
+      expect(client.graphqlClient).toBeDefined();
+      expect(client.grpcClient).toBeDefined();
+      expect(client.ecsWorld).toBeDefined();
+      expect(client.metadata).toBe(mockMetadata);
+      expect(client.network).toBe('devnet');
+      expect(client.packageId).toBe('0x123');
+    });
+
+    it('should create client with full config', () => {
+      const fullConfig: ClientConfig = {
+        ...validConfig,
+        credentials: {
+          secretKey: 'test-secret-key',
+          mnemonics: 'test mnemonics'
+        },
+        endpoints: {
+          fullnodeUrls: ['https://fullnode.devnet.sui.io'],
+          graphql: 'http://localhost:4000/graphql',
+          websocket: 'ws://localhost:4000/graphql',
+          grpc: 'http://localhost:8080'
+        },
+        dubheMetadata: {
+          schemas: ['Counter'],
+          systems: ['counter_system']
+        },
+        dubheSchemaId: '0x456',
+        options: {
+          enableBatchOptimization: true,
+          cacheTimeout: 10000,
+          debounceMs: 200,
+          reconnectOnError: true
+        }
+      };
+
+      const client = createClient(fullConfig);
+
+      expect(client).toBeDefined();
+      expect(client.dubheSchemaId).toBe('0x456');
+      expect(client.options?.enableBatchOptimization).toBe(true);
+      expect(client.options?.cacheTimeout).toBe(10000);
+    });
+
+    it('should use default endpoints when not provided', () => {
+      const client = createClient(validConfig);
+
+      // The GraphQL and gRPC clients should be created with default endpoints
+      expect(client.graphqlClient).toBeDefined();
+      expect(client.grpcClient).toBeDefined();
+    });
+
+    it('should return address from contract', () => {
+      const client = createClient(validConfig);
+
+      expect(client.address).toBe(
+        '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef'
+      );
+    });
+  });
+
+  describe('Configuration validation', () => {
+    it('should throw error when network is missing', () => {
+      const invalidConfig = {
+        packageId: '0x123',
+        metadata: mockMetadata
+      } as ClientConfig;
+
+      expect(() => createClient(invalidConfig)).toThrow('ClientConfig: network is required');
+    });
+
+    it('should throw error when packageId is missing', () => {
+      const invalidConfig = {
+        network: 'devnet',
+        metadata: mockMetadata
+      } as ClientConfig;
+
+      expect(() => createClient(invalidConfig)).toThrow('ClientConfig: packageId is required');
+    });
+
+    it('should throw error when metadata is missing', () => {
+      const invalidConfig = {
+        network: 'devnet',
+        packageId: '0x123'
+      } as ClientConfig;
+
+      expect(() => createClient(invalidConfig)).toThrow('ClientConfig: metadata is required');
+    });
+  });
+
+  describe('Options handling', () => {
+    it('should use default options when not provided', () => {
+      const client = createClient(validConfig);
+
+      // Default options should be applied in the ecsWorld creation
+      expect(client.ecsWorld).toBeDefined();
+    });
+
+    it('should respect custom options', () => {
+      const configWithOptions: ClientConfig = {
+        ...validConfig,
+        options: {
+          enableBatchOptimization: false,
+          cacheTimeout: 15000,
+          debounceMs: 500,
+          reconnectOnError: false
+        }
+      };
+
+      const client = createClient(configWithOptions);
+
+      expect(client.options).toEqual({
+        enableBatchOptimization: false,
+        cacheTimeout: 15000,
+        debounceMs: 500,
+        reconnectOnError: false
+      });
+    });
+  });
+});
+
+describe('isNetworkType', () => {
+  it('should return true for valid network types', () => {
+    expect(isNetworkType('mainnet')).toBe(true);
+    expect(isNetworkType('testnet')).toBe(true);
+    expect(isNetworkType('devnet')).toBe(true);
+    expect(isNetworkType('localnet')).toBe(true);
+  });
+
+  it('should return false for invalid network types', () => {
+    expect(isNetworkType('invalid')).toBe(false);
+    expect(isNetworkType('production')).toBe(false);
+    expect(isNetworkType('')).toBe(false);
+    expect(isNetworkType('MAINNET')).toBe(false); // Case sensitive
+  });
+});
+
+describe('validateClientConfig', () => {
+  const mockMetadata = {
+    name: 'test-package',
+    version: '1.0.0',
+    schemas: {}
+  };
+
+  it('should validate correct config without throwing', () => {
+    const validConfig: Partial<ClientConfig> = {
+      network: 'devnet',
+      packageId: '0x123',
+      metadata: mockMetadata
+    };
+
+    expect(() => validateClientConfig(validConfig)).not.toThrow();
+  });
+
+  it('should throw when network is missing', () => {
+    const config = {
+      packageId: '0x123',
+      metadata: mockMetadata
+    };
+
+    expect(() => validateClientConfig(config)).toThrow(
+      'ClientConfig validation failed: network is required'
+    );
+  });
+
+  it('should throw when network type is invalid', () => {
+    const config = {
+      network: 'invalid-network' as ClientConfig['network'],
+      packageId: '0x123',
+      metadata: mockMetadata
+    };
+
+    expect(() => validateClientConfig(config)).toThrow(
+      'ClientConfig validation failed: invalid network type'
+    );
+  });
+
+  it('should throw when packageId is missing', () => {
+    const config: Partial<ClientConfig> = {
+      network: 'devnet',
+      metadata: mockMetadata
+    };
+
+    expect(() => validateClientConfig(config)).toThrow(
+      'ClientConfig validation failed: packageId is required'
+    );
+  });
+
+  it('should throw when packageId is empty string', () => {
+    const config: Partial<ClientConfig> = {
+      network: 'devnet',
+      packageId: '   ',
+      metadata: mockMetadata
+    };
+
+    expect(() => validateClientConfig(config)).toThrow(
+      'ClientConfig validation failed: packageId must be a non-empty string'
+    );
+  });
+
+  it('should throw when metadata is missing', () => {
+    const config: Partial<ClientConfig> = {
+      network: 'devnet',
+      packageId: '0x123'
+    };
+
+    expect(() => validateClientConfig(config)).toThrow(
+      'ClientConfig validation failed: metadata is required'
+    );
+  });
+});

package/src/sui/client.ts

@@ -0,0 +1,156 @@
+import { Dubhe } from '@0xobelisk/sui-client';
+import { createDubheGraphqlClient } from '@0xobelisk/graphql-client';
+import { createECSWorld } from '@0xobelisk/ecs';
+import { DubheGrpcClient } from '@0xobelisk/grpc-client';
+import type { ClientConfig, DubheClientBundle } from './types';
+
+/**
+ * Create a Dubhe client bundle with all necessary instances
+ *
+ * This factory function creates and initializes:
+ * - Dubhe contract client for on-chain interactions
+ * - GraphQL client for querying indexed data
+ * - gRPC client for high-performance queries
+ * - ECS World for entity-component-system queries
+ *
+ * @param config - Client configuration matching @0xobelisk/react interface
+ * @returns DubheClientBundle with all initialized client instances
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@0xobelisk/client/sui';
+ * import metadata from './metadata.json';
+ *
+ * const client = createClient({
+ *   network: 'devnet',
+ *   packageId: '0x123...',
+ *   metadata,
+ *   credentials: {
+ *     secretKey: process.env.PRIVATE_KEY
+ *   }
+ * });
+ *
+ * // Use the contract client
+ * const tx = new Transaction();
+ * await client.contract.tx.counter_system.inc({ tx });
+ *
+ * // Use GraphQL client
+ * const data = await client.graphqlClient.query(...);
+ *
+ * // Use ECS World
+ * const entities = client.ecsWorld.getEntities();
+ * ```
+ */
+export function createClient(config: ClientConfig): DubheClientBundle {
+  // Validate required fields
+  if (!config.network) {
+    throw new Error('ClientConfig: network is required');
+  }
+  if (!config.packageId) {
+    throw new Error('ClientConfig: packageId is required');
+  }
+  if (!config.metadata) {
+    throw new Error('ClientConfig: metadata is required');
+  }
+
+  // Initialize Dubhe contract client
+  const contract = new Dubhe({
+    networkType: config.network,
+    packageId: config.packageId,
+    metadata: config.metadata,
+    secretKey: config.credentials?.secretKey,
+    mnemonics: config.credentials?.mnemonics,
+    fullnodeUrls: config.endpoints?.fullnodeUrls
+  });
+
+  // Initialize GraphQL client with default localhost endpoint if not provided
+  const graphqlClient = createDubheGraphqlClient({
+    endpoint: config.endpoints?.graphql || 'http://localhost:4000/graphql',
+    subscriptionEndpoint: config.endpoints?.websocket || 'ws://localhost:4000/graphql',
+    dubheMetadata: config.dubheMetadata
+  });
+
+  // Initialize gRPC client with default localhost endpoint if not provided
+  const grpcClient = new DubheGrpcClient({
+    baseUrl: config.endpoints?.grpc || 'http://localhost:8080'
+  });
+
+  // Initialize ECS World (depends on GraphQL client)
+  const ecsWorld = createECSWorld(graphqlClient, {
+    dubheMetadata: config.dubheMetadata,
+    queryConfig: {
+      enableBatchOptimization: config.options?.enableBatchOptimization ?? true,
+      defaultCacheTimeout: config.options?.cacheTimeout ?? 5000
+    },
+    subscriptionConfig: {
+      defaultDebounceMs: config.options?.debounceMs ?? 100,
+      reconnectOnError: config.options?.reconnectOnError ?? true
+    }
+  });
+
+  // Get user address from contract
+  const address = contract.getAddress();
+
+  // Return complete client bundle
+  return {
+    contract,
+    graphqlClient,
+    grpcClient,
+    ecsWorld,
+    metadata: config.metadata,
+    network: config.network,
+    packageId: config.packageId,
+    dubheSchemaId: config.dubheSchemaId,
+    address,
+    options: config.options
+  };
+}
+
+/**
+ * Type guard to check if a value is a valid NetworkType
+ */
+export function isNetworkType(value: string): value is ClientConfig['network'] {
+  return ['mainnet', 'testnet', 'devnet', 'localnet'].includes(value);
+}
+
+/**
+ * Helper function to validate client configuration
+ * Throws descriptive errors for invalid configurations
+ */
+export function validateClientConfig(
+  config: Partial<ClientConfig>
+): asserts config is ClientConfig {
+  if (!config.network) {
+    throw new Error('ClientConfig validation failed: network is required');
+  }
+  if (!isNetworkType(config.network)) {
+    throw new Error(
+      `ClientConfig validation failed: invalid network type "${config.network}". ` +
+        'Must be one of: mainnet, testnet, devnet, localnet'
+    );
+  }
+  if (!config.packageId) {
+    throw new Error('ClientConfig validation failed: packageId is required');
+  }
+  if (typeof config.packageId !== 'string' || config.packageId.trim() === '') {
+    throw new Error('ClientConfig validation failed: packageId must be a non-empty string');
+  }
+  if (!config.metadata) {
+    throw new Error('ClientConfig validation failed: metadata is required');
+  }
+}
+
+/**
+ * Create client with configuration validation
+ * Useful when working with external configuration sources
+ *
+ * @example
+ * ```typescript
+ * const config = loadConfigFromFile(); // May be incomplete
+ * const client = createClientWithValidation(config); // Throws if invalid
+ * ```
+ */
+export function createClientWithValidation(config: Partial<ClientConfig>): DubheClientBundle {
+  validateClientConfig(config);
+  return createClient(config);
+}