toncorp-wallet-connect-sdk 0.1.1 → 0.1.3

package/README.md

@@ -8,6 +8,12 @@ Connect TonPass, OneDollar and more wallets from any DApp or website.
 npm install toncorp-wallet-connect-sdk
 ```
 
+Or via CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/toncorp-wallet-connect-sdk@latest/dist/index.umd.js"></script>
+```
+
 ## Usage
 
 ### Specific wallet
@@ -15,25 +21,26 @@ npm install toncorp-wallet-connect-sdk
 ```typescript
 import { TonPassConnect } from 'toncorp-wallet-connect-sdk';
 
-const wallet = new TonPassConnect({
-  appId: 'your_app_id',
-  registryUrl: 'https://api.example.com/connect/wallets',
-});
+const wallet = new TonPassConnect({ appId: 'your_app_id' });
 
 const result = await wallet.connect();
-console.log(result.wallets); // [{ address: '0x...', chain: 'TON' }]
+console.log(result.wallet);  // { address: 'UQ...', chain: 'TON' }
 console.log(result.user);    // { username: 'john', avatar: '...' }
+
+// Access via window global
+window.tonpass.isConnected()  // true
+window.tonpass.getWallet()    // same result
 ```
 
 ```typescript
 import { OneDollarConnect } from 'toncorp-wallet-connect-sdk';
 
-const wallet = new OneDollarConnect({
-  appId: 'your_app_id',
-  registryUrl: 'https://api.example.com/connect/wallets',
-});
-
+const wallet = new OneDollarConnect({ appId: 'your_app_id' });
 const result = await wallet.connect();
+
+// Access via window global
+window.onedollar.isConnected()
+window.onedollar.getWallet()
 ```
 
 ### All wallets (show picker)
@@ -43,7 +50,6 @@ import { BaseWalletConnect } from 'toncorp-wallet-connect-sdk';
 
 const wallet = new BaseWalletConnect({
   appId: 'your_app_id',
-  registryUrl: 'https://api.example.com/connect/wallets',
   // walletId: ['tonpass', 'onedollar'],  // optional filter
 });
 
@@ -53,17 +59,21 @@ const result = await wallet.connect();
 ### Script tag (UMD)
 
 ```html
-<script src="https://unpkg.com/toncorp-wallet-connect-sdk/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/toncorp-wallet-connect-sdk@latest/dist/index.umd.js"></script>
 <script>
-  const wallet = new WalletConnectSDK.TonPassConnect({
+  const wallet = new WalletConnectSDK.OneDollarConnect({
     appId: 'your_app_id',
-    registryUrl: 'https://api.example.com/connect/wallets',
   });
 
   document.getElementById('connect-btn').onclick = async () => {
     const result = await wallet.connect();
     console.log(result);
   };
+
+  // Available globally after instantiation
+  // window.onedollar.isConnected()
+  // window.onedollar.getWallet()
+  // window.onedollar.disconnect()
 </script>
 ```
 
@@ -74,7 +84,7 @@ const result = await wallet.connect();
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
 | `appId` | `string` | Yes | Your registered app ID |
-| `registryUrl` | `string` | Yes | URL to fetch available wallets |
+| `registryUrl` | `string` | No | Override wallet registry URL (defaults to CDN) |
 | `walletId` | `string \| string[]` | No | Filter wallets (only for `BaseWalletConnect`) |
 | `theme` | `'light' \| 'dark'` | No | Modal theme (default: `light`) |
 
@@ -83,75 +93,233 @@ const result = await wallet.connect();
 | Method | Returns | Description |
 |--------|---------|-------------|
 | `connect()` | `Promise<ConnectResult>` | Open modal and wait for user to approve |
-| `disconnect()` | `void` | Disconnect and clear session |
+| `disconnect()` | `void` | Disconnect, clear session and call API |
 | `isConnected()` | `boolean` | Check connection status |
 | `getWallet()` | `ConnectResult \| null` | Get current connection info |
 | `on(event, cb)` | `void` | Listen to events |
 | `off(event, cb)` | `void` | Remove listener |
 
+### ConnectResult
+
+```typescript
+{
+  wallet: {
+    address: string;   // friendly TON address
+    chain: string;     // 'TON'
+  } | null;
+  user: {
+    username?: string;
+    avatar?: string;
+  };
+  session?: {
+    sessionToken: string;
+    walletId: string;
+    apiUrl: string;
+  };
+}
+```
+
 ### Events
 
 | Event | Data | Description |
 |-------|------|-------------|
 | `connect` | `ConnectResult` | Connected successfully |
-| `disconnect` | — | Disconnected |
+| `disconnect` | - | Disconnected |
 | `error` | `string` | Transport error |
-| `session_expired` | — | Session timed out |
+| `session_expired` | - | Session timed out |
 
-## Publish to npm
+### Window globals
 
-### Prerequisites
+Each wallet instance auto-registers on `window`:
 
-```bash
-# Login to npm (one-time)
-npm login
+| Class | Window global |
+|-------|--------------|
+| `TonPassConnect` | `window.tonpass` |
+| `OneDollarConnect` | `window.onedollar` |
+| `BaseWalletConnect` | `window.walletconnect` |
+
+## Integrate into TMA Wallet App (Telegram Bot)
+
+This section is for **wallet app developers** who want their Telegram Mini App (TMA) to support connect requests from DApps using this SDK.
 
-# If using scoped package (@aspect-wallet), make sure the org exists on npmjs.com
-# Or change the name in package.json to an unscoped name
+### How it works
+
+```
+DApp (SDK)                    Your Backend              TMA (Telegram)
+──────────────────────────────────────────────────────────────────────
+1. SDK calls POST /connect/init
+   ← { sessionToken, deeplink }
+
+2. User clicks deeplink / scans QR
+   ────────────────────────────────────────────────→ TMA opens
+                                                     parse startapp param
+
+3.                              ← POST /connect/verify   TMA sends initData
+                                  verify Telegram HMAC
+                                → { appId, origin }
+
+4.                                                     TMA shows confirm UI
+
+5. User taps Approve
+                                ← POST /connect/confirm  TMA sends JWT + approved
+                                  get user wallet
+                                  emit WS event ──────→ SDK receives result
+                                                        modal shows success
 ```
 
-### Build & Publish
+### Step 1: Parse `startapp` param in your TMA
 
-```bash
-# Navigate to SDK folder
-cd src/blockchain/walletconnect/sdk
+When a DApp initiates a connect request, the user is redirected to your TMA via deeplink. The `startapp` parameter contains the session token.
 
-# Install build dependencies
-npm install
+```typescript
+// In your TMA (React / vanilla JS)
+const tg = window.Telegram.WebApp;
+const startParam = tg.initDataUnsafe?.start_param; // "sessionToken_abc123..."
+
+if (startParam && startParam.startsWith('sessionToken_')) {
+  const sessionToken = startParam.replace('sessionToken_', '');
+  // → proceed to Step 2
+}
+```
 
-# Build (outputs to dist/)
-npm run build
+### Step 2: Verify session with your backend
 
-# Check what will be published
-npm pack --dry-run
+Call your backend to verify the session and get DApp info to show the user.
 
-# Publish (first time — scoped packages default to private)
-npm publish --access public
+```typescript
+const response = await fetch('https://your-api.com/connect/verify', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    sessionToken,
+    initData: tg.initData,   // Telegram initData for HMAC verification
+    botId: 'your_bot_id',
+  }),
+});
 
-# Publish subsequent versions
-# 1. Bump version first:
-npm version patch   # 0.1.0 → 0.1.1 (bug fixes)
-npm version minor   # 0.1.1 → 0.2.0 (new features)
-npm version major   # 0.2.0 → 1.0.0 (breaking changes)
-# 2. Then publish:
-npm publish --access public
+const { appId, appName, origin, walletId } = await response.json();
+// → Show confirm UI to user
 ```
 
-### Verify
+### Step 3: Show confirm popup
+
+Display the DApp info and let the user approve or reject.
+
+```tsx
+// React example
+function ConnectConfirm({ appName, origin, onApprove, onReject }) {
+  return (
+    <div className="confirm-popup">
+      <h2>{appName} wants to connect</h2>
+      <p>Origin: {origin}</p>
+      <button onClick={onApprove}>Approve</button>
+      <button onClick={onReject}>Reject</button>
+    </div>
+  );
+}
+```
 
-```bash
-# Check the published package
-npm info toncorp-wallet-connect-sdk
+### Step 4: Confirm or reject
 
-# Install in another project to test
-npm install toncorp-wallet-connect-sdk
+When the user taps Approve/Reject, call the confirm endpoint with their JWT token.
+
+```typescript
+const token = 'user_jwt_token'; // from your TMA auth flow
+
+const result = await fetch('https://your-api.com/connect/confirm', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`,
+  },
+  body: JSON.stringify({
+    sessionToken,
+    approved: true, // or false to reject
+  }),
+});
+
+const data = await result.json();
+// {
+//   success: true,
+//   status: 'CONFIRMED',
+//   wallet: { address: 'UQ...', chain: 'TON' },
+//   user: { username: 'john', avatar: '...' }
+// }
+
+// The SDK on the DApp side receives this automatically via WebSocket/polling
+// → DApp modal shows "Connection Successful"
 ```
 
-### CDN (auto-available after publish)
+### Step 5: In-app QR scanner (optional)
 
+Allow users already in your TMA to scan a QR code from a DApp to connect.
+
+```typescript
+// User scans QR → gets deeplink URL
+const scannedUrl = 'https://t.me/YourBot/app?startapp=sessionToken_abc123...';
+
+// Parse sessionToken from URL
+const url = new URL(scannedUrl);
+const startapp = url.searchParams.get('startapp') || '';
+const sessionToken = startapp.replace('sessionToken_', '');
+
+// → Same flow: verify → confirm popup → approve/reject
 ```
-https://unpkg.com/toncorp-wallet-connect-sdk/dist/index.umd.js
-https://cdn.jsdelivr.net/npm/toncorp-wallet-connect-sdk/dist/index.umd.js
+
+### Step 6: Manage connected DApps
+
+Let users view and disconnect DApps from your TMA.
+
+```typescript
+// List connected DApps
+const dapps = await fetch('https://your-api.com/connect/dapps', {
+  headers: { 'Authorization': `Bearer ${token}` },
+}).then(r => r.json());
+
+// Disconnect a specific DApp
+await fetch('https://your-api.com/connect/disconnect', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token}`,
+  },
+  body: JSON.stringify({
+    appId: 'the_app_id',
+    walletId: 'onedollar',
+  }),
+});
+```
+
+### Backend API endpoints
+
+Your backend needs these endpoints:
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| `GET` | `/connect/wallets` | No | List supported wallets (SDK fetches this) |
+| `POST` | `/connect/init` | No | Create connect session (SDK calls this) |
+| `GET` | `/connect/status?token=` | No | Poll session status (SDK fallback) |
+| `POST` | `/connect/verify` | initData | Verify session + Telegram user (TMA calls) |
+| `POST` | `/connect/confirm` | JWT | Approve/reject session (TMA calls) |
+| `POST` | `/connect/disconnect` | JWT | Disconnect a DApp (TMA calls) |
+| `POST` | `/connect/disconnect-by-token` | No | Disconnect by session token (SDK calls) |
+| `GET` | `/connect/dapps` | JWT | List connected DApps (TMA calls) |
+
+### Register your wallet in the registry
+
+To make your wallet available to all DApps using the SDK, add it to `registry.json`:
+
+```json
+{
+  "walletId": "yourwallet",
+  "name": "Your Wallet",
+  "icon": "https://your-cdn.com/icon.png",
+  "botUsername": "YourBot",
+  "appName": "app",
+  "apiUrl": "https://your-api.com",
+  "description": "Your wallet description",
+  "order": 0
+}
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toncorp-wallet-connect-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Wallet Connect SDK — connect TonPass, OneDollar and more wallets from any DApp",
   "author": "PlaygroundVina",
   "license": "MIT",