@nexus-cross/crossx-sdk-wagmi 2.0.2-beta.1 → 2.0.2-beta.3

package/README.md

@@ -0,0 +1,250 @@
+# @nexus-cross/crossx-sdk-wagmi
+
+[wagmi](https://wagmi.sh/) connector for the CROSSx Embedded Wallet — use standard wagmi hooks (`useAccount`, `useConnect`, `useSendTransaction`, etc.) with CROSSx OAuth-based wallet.
+
+## Installation
+
+```bash
+npm install @nexus-cross/crossx-sdk-wagmi @nexus-cross/crossx-sdk-core
+# or
+pnpm add @nexus-cross/crossx-sdk-wagmi @nexus-cross/crossx-sdk-core
+```
+
+**Peer dependencies:** `wagmi >=2.0.0`, `viem >=2.0.0`
+
+## Quick Start
+
+### Simple Mode
+
+Pass SDK config directly — the connector creates the SDK instance internally.
+
+```ts
+import { createConfig, http } from 'wagmi';
+import { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi';
+import type { Chain } from 'viem';
+
+const crossMainnet = {
+  id: 612055,
+  name: 'CROSS Mainnet',
+  nativeCurrency: { name: 'CROSS', symbol: 'CROSS', decimals: 18 },
+  rpcUrls: { default: { http: ['https://rpc.crossmainnet.io'] } },
+} as const satisfies Chain;
+
+const config = createConfig({
+  chains: [crossMainnet],
+  connectors: [
+    crossxConnector({
+      projectId: 'your-project-id',
+      appName: 'My DApp',
+    }),
+  ],
+  transports: {
+    [crossMainnet.id]: http(),
+  },
+});
+```
+
+### Advanced Mode
+
+Create the SDK yourself for full control over configuration, then inject it.
+
+```ts
+import { createConfig, http } from 'wagmi';
+import { createCROSSxSDK, ChainId } from '@nexus-cross/crossx-sdk-core';
+import { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi';
+
+const sdk = createCROSSxSDK({
+  projectId: 'your-project-id',
+  appName: 'My DApp',
+  theme: 'dark',
+});
+
+const config = createConfig({
+  chains: [crossMainnet],
+  connectors: [
+    createCROSSxConnector({
+      sdk,
+      defaultChainId: ChainId.CROSS_MAINNET,
+    }),
+  ],
+  transports: {
+    [crossMainnet.id]: http(),
+  },
+});
+```
+
+### Use with React
+
+```tsx
+import { WagmiProvider } from 'wagmi';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { useAccount, useConnect, useDisconnect, useSendTransaction } from 'wagmi';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <WagmiProvider config={config}>
+      <QueryClientProvider client={queryClient}>
+        <Wallet />
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+}
+
+function Wallet() {
+  const { address, isConnected } = useAccount();
+  const { connect, connectors } = useConnect();
+  const { disconnect } = useDisconnect();
+  const { sendTransaction } = useSendTransaction();
+
+  if (isConnected) {
+    return (
+      <div>
+        <p>Connected: {address}</p>
+        <button onClick={() => disconnect()}>Disconnect</button>
+        <button onClick={() => sendTransaction({
+          to: '0x...',
+          value: 10000000000000000n, // 0.01 CROSS
+        })}>
+          Send
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <button onClick={() => connect({ connector: connectors[0] })}>
+      Connect CROSSx
+    </button>
+  );
+}
+```
+
+---
+
+## API Reference
+
+### `crossxConnector(options)` — Simple Mode
+
+Creates a wagmi connector with automatic SDK creation.
+
+```ts
+crossxConnector({
+  // SDKConfig fields
+  projectId: 'your-project-id',   // Required
+  appName: 'My DApp',             // Required
+  theme: 'light',
+  themeTokens: { /* ... */ },
+  locale: 'en',
+
+  // Connector options
+  defaultChainId: 'eip155:612055',
+  getStoredWalletIndex: () => number,
+  onWalletIndexChanged: (index: number) => void,
+  getStoredWalletAddress: () => string | null,
+  onWalletAddressChanged: (address: string) => void,
+  openConnectOtherWallet: () => void,
+})
+```
+
+### `createCROSSxConnector(options)` — Advanced Mode
+
+Creates a wagmi connector with an existing SDK instance.
+
+```ts
+createCROSSxConnector({
+  sdk: CROSSxSDK,                   // Required — pre-created SDK instance
+  defaultChainId: 'eip155:612055',  // Default chain (CROSS Mainnet)
+  getStoredWalletIndex: () => number,
+  onWalletIndexChanged: (index: number) => void,
+  getStoredWalletAddress: () => string | null,
+  onWalletAddressChanged: (address: string) => void,
+  openConnectOtherWallet: () => void,
+})
+```
+
+---
+
+## Options
+
+### Common Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultChainId` | `string \| number` | `'eip155:612055'` | Default chain ID (CAIP-2 or numeric) |
+| `getStoredWalletIndex` | `() => number` | localStorage | Callback to retrieve persisted wallet index |
+| `onWalletIndexChanged` | `(index) => void` | localStorage | Callback when active wallet index changes |
+| `getStoredWalletAddress` | `() => string \| null` | localStorage | Callback to retrieve persisted wallet address |
+| `onWalletAddressChanged` | `(address) => void` | localStorage | Callback when active wallet address changes |
+| `openConnectOtherWallet` | `() => void` | — | Called when user clicks an external wallet row in the login modal |
+
+By default, the connector uses `localStorage` for wallet index/address persistence. Override with custom callbacks for alternative storage (e.g., cookies, state management).
+
+### External Wallet Integration
+
+When `openConnectOtherWallet` is provided, the SDK login modal shows external wallet options (Binance, MetaMask, CROSSx). Clicking a row triggers this callback, where you can open your own connect modal.
+
+```ts
+crossxConnector({
+  projectId: '...',
+  appName: 'MyDApp',
+  openConnectOtherWallet: () => {
+    // Open your wagmi/RainbowKit/Web3Modal connect dialog
+    openConnectModal();
+  },
+})
+```
+
+To show only specific wallets, use `connectOtherWallets`:
+
+```ts
+crossxConnector({
+  projectId: '...',
+  appName: 'MyDApp',
+  connectOtherWallets: ['metamask', 'binance'],
+  openConnectOtherWallet: () => openConnectModal(),
+})
+```
+
+---
+
+## Connector Behavior
+
+| Feature | Behavior |
+|---------|----------|
+| `connect()` | Opens OAuth sign-in → creates/restores wallet → returns accounts |
+| `disconnect()` | Calls `sdk.signOut()` → clears stored wallet data |
+| `switchChain()` | Updates internal chain ID, emits `change` event |
+| `isAuthorized()` | Waits for SDK ready, then checks `sdk.isAuthenticated()` |
+| Auto-sync | Listens to SDK `authChanged` / `addressChanged` events |
+
+---
+
+## Exports
+
+```ts
+// Connectors
+export { crossxConnector } from '@nexus-cross/crossx-sdk-wagmi';
+export { createCROSSxConnector } from '@nexus-cross/crossx-sdk-wagmi';
+
+// EIP-1193 Provider (advanced use)
+export { CROSSxEIP1193Provider } from '@nexus-cross/crossx-sdk-wagmi';
+
+// Types
+export type { CrossxConnectorOptions } from '@nexus-cross/crossx-sdk-wagmi';
+export type { CROSSxConnectorOptions } from '@nexus-cross/crossx-sdk-wagmi';
+```
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@nexus-cross/crossx-sdk-core`](https://www.npmjs.com/package/@nexus-cross/crossx-sdk-core) | Core SDK (vanilla JS) |
+| [`@nexus-cross/crossx-sdk-react`](https://www.npmjs.com/package/@nexus-cross/crossx-sdk-react) | React hooks (without wagmi) |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexus-cross/crossx-sdk-wagmi",
-  "version": "2.0.2-beta.1",
+  "version": "2.0.2-beta.3",
   "description": "CROSSx SDK wagmi Connector — OAuth 임베디드 지갑을 wagmi에 통합",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -17,9 +17,10 @@
     "dist"
   ],
   "dependencies": {
-    "@nexus-cross/crossx-sdk-core": "2.0.2-beta.1"
+    "@nexus-cross/crossx-sdk-core": "^2.0.2-beta.3"
   },
   "peerDependencies": {
+    "@nexus-cross/crossx-sdk-core": "^2.0.0",
     "viem": ">=2.0.0",
     "wagmi": ">=2.0.0"
   },