toncorp-wallet-connect-sdk 0.1.2 → 0.1.4

package/README.md

@@ -138,6 +138,190 @@ Each wallet instance auto-registers on `window`:
 | `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.
+
+### 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
+```
+
+### Step 1: Parse `startapp` param in your TMA
+
+When a DApp initiates a connect request, the user is redirected to your TMA via deeplink. The `startapp` parameter contains the session token.
+
+```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
+}
+```
+
+### Step 2: Verify session with your backend
+
+Call your backend to verify the session and get DApp info to show the user.
+
+```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',
+  }),
+});
+
+const { appId, appName, origin, walletId } = await response.json();
+// → Show confirm UI to user
+```
+
+### 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>
+  );
+}
+```
+
+### Step 4: Confirm or reject
+
+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"
+```
+
+### 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
+```
+
+### 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
 
 MIT

package/package.json

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

package/registry.json

@@ -3,7 +3,7 @@
     "walletId": "onedollar",
     "name": "OneDollar Wallet",
     "icon": "https://img.icons8.com/color/96/us-dollar-circled.png",
-    "botUsername": "OneDollarBot",
+    "botUsername": "onedollar_wallet_bot",
     "appName": "app",
     "apiUrl": "https://1dollar-api-dev.motcaigido.xyz",
     "description": "OneDollar wallet on Telegram",