@dimcool/sdk 0.1.22 → 0.1.26

package/README.md

@@ -935,16 +935,23 @@ The wallet module provides functionality for managing Solana wallets, checking b
 
 ### WalletSigner Interface
 
-The SDK exposes a `WalletSigner` interface for transaction and message signing:
+The SDK exposes a `WalletSigner` interface for transaction and message signing. A signer provides exactly one of `signTransaction` or `signAndSendTransaction`:
 
 ```typescript
 interface WalletSigner {
+  address?: string;
   signMessage: (message: string) => Promise<Uint8Array | string>;
-  signTransaction: (transaction: Transaction) => Promise<Transaction>;
+  signTransaction?: (transaction: Transaction) => Promise<Transaction>;
+  signAndSendTransaction?: (transaction: Transaction) => Promise<string>;
 }
 ```
 
-This allows the SDK to remain agnostic about how signing is implemented - you can use Phantom wallet for browser apps, or a Keypair for bot applications.
+**Two signing modes:**
+
+- **`signTransaction`** (server-sent) — the signer returns signed bytes; the server submits the transaction to the network. Used by `@dimcool/wallet` (keypair agents) and Phantom browser extensions.
+- **`signAndSendTransaction`** (client-sent) — the signer signs AND submits the transaction, returning the signature. The SDK then calls a `confirm-signature` endpoint so the backend can track and confirm it via the queue. Used by Phantom embedded wallets (Google/Apple login).
+
+The SDK detects the mode via `sdk.wallet.isSignAndSendMode()` and automatically routes `send()` and `depositForLobby()` through the correct path.
 
 If you're building agents, you can use `@dimcool/wallet` and pass `wallet.getSigner()` directly:
 
@@ -964,12 +971,9 @@ sdk.wallet.setSigner(wallet.getSigner());
 Configure the wallet signer. This must be called before any signing operations.
 
 ```typescript
-// Example: Using Phantom wallet (in apps/web)
-import { useSolana } from '@phantom/react-sdk';
-
-const { solana } = useSolana();
-
+// Example: Phantom extension (signTransaction — server submits)
 sdk.wallet.setSigner({
+  address: connectedAddress,
   signMessage: async (message: string) => {
     return solana.signMessage(new TextEncoder().encode(message));
   },
@@ -980,13 +984,28 @@ sdk.wallet.setSigner({
 ```
 
 ```typescript
-// Example: Using a Keypair (for bots/Node.js)
+// Example: Phantom embedded / Google/Apple (signAndSendTransaction — client submits)
+sdk.wallet.setSigner({
+  address: connectedAddress,
+  signMessage: async (message: string) => {
+    return solana.signMessage(new TextEncoder().encode(message));
+  },
+  signAndSendTransaction: async (transaction: Transaction) => {
+    const result = await solana.signAndSendTransaction(transaction);
+    return typeof result === 'string' ? result : result.signature;
+  },
+});
+```
+
+```typescript
+// Example: Using a Keypair (for bots/Node.js — signTransaction)
 import { Keypair } from '@solana/web3.js';
 import * as nacl from 'tweetnacl';
 
 const keypair = Keypair.fromSecretKey(/* ... */);
 
 sdk.wallet.setSigner({
+  address: keypair.publicKey.toBase58(),
   signMessage: async (message: string) => {
     const messageBytes = new TextEncoder().encode(message);
     return nacl.sign.detached(messageBytes, keypair.secretKey);
@@ -1080,40 +1099,37 @@ const signature = await sdk.wallet.signMessage('Hello, world!');
 
 ### `signTransaction(transaction: Transaction): Promise<Transaction>`
 
-Sign a Solana transaction using the configured signer.
+Sign a Solana transaction using the configured signer. Only available when the signer provides `signTransaction`.
 
 ```typescript
-import { Transaction } from '@solana/web3.js';
-
-const unsignedTransaction = Transaction.from(/* ... */);
 const signedTransaction = await sdk.wallet.signTransaction(unsignedTransaction);
 ```
 
-**Parameters:**
+**Throws** if the signer does not support `signTransaction` (i.e., it only has `signAndSendTransaction`).
 
-- `transaction: Transaction` - The unsigned Solana transaction to sign
+### `signAndSendTransaction(transaction: Transaction): Promise<string>`
 
-**Returns:**
+Sign and send a Solana transaction in one step. Only available when the signer provides `signAndSendTransaction`. Returns the transaction signature.
+
+```typescript
+const signature = await sdk.wallet.signAndSendTransaction(unsignedTransaction);
+```
 
-- `Promise<Transaction>` - The signed transaction
+**Throws** if the signer does not support `signAndSendTransaction`.
 
-**Example:**
+### `isSignAndSendMode(): boolean`
 
-```typescript
-// Transaction should be prepared by the backend first
-const { unsignedTransaction } = await sdk.http.post(
-  '/transactions/prepare-deposit',
-  {
-    lobbyId: 'lobby-id',
-    amount: 100,
-  },
-);
+Check which signing mode the current signer uses.
 
-const tx = Transaction.from(Buffer.from(unsignedTransaction, 'base64'));
-const signedTx = await sdk.wallet.signTransaction(tx);
+```typescript
+if (sdk.wallet.isSignAndSendMode()) {
+  // Client-sent path: signer signs AND sends
+} else {
+  // Server-sent path: signer returns signed bytes
+}
 ```
 
-**Note:** A signer must be configured first using `setSigner()`.
+**Note:** `send()` and `depositForLobby()` use this internally to route automatically.
 
 ### `send(recipient, amount, token?)`
 
@@ -1187,7 +1203,23 @@ Use these only when you explicitly need manual control of signing/submission.
 
 ## Escrow Module (`sdk.escrow`)
 
-The escrow module provides functionality for managing deposits, checking deposit status, and handling the escrow flow for game lobbies. This module works in conjunction with the wallet module to enable secure, blockchain-based deposits.
+The escrow module provides functionality for managing deposits, checking deposit status, and handling the escrow flow for game lobbies. It is constructed with `http` and `wallet` (the wallet is used for signing in `depositForLobby`). Use the wallet module to set a signer via `sdk.wallet.setSigner(...)` before calling `depositForLobby`.
+
+### One-call lobby deposit
+
+For the common case of depositing into a paid lobby in one step, use **`depositForLobby(lobbyId: string): Promise<DepositForLobbyResponse>`**. It starts deposits, prepares the transaction, signs with the configured wallet, submits, and polls until the current user's deposit is confirmed (or all deposits are confirmed for multi-player). Requires a signer to be set (`sdk.wallet.setSigner(...)`).
+
+```typescript
+const result = await sdk.escrow.depositForLobby(lobbyId);
+// result: { signature: string; status: string; canProceedToQueue: boolean }
+if (result.canProceedToQueue) {
+  await sdk.lobbies.joinQueue(lobbyId);
+}
+```
+
+**Response:** `{ signature, status, canProceedToQueue }`. When `canProceedToQueue` is true, call `sdk.lobbies.joinQueue(lobbyId)` to enter matchmaking.
+
+**Throws:** If no signer is configured: "No signer configured. Use sdk.wallet.setSigner(...) first."
 
 ### `startDeposits(lobbyId: string): Promise<void>`