feat: ws (#31)

* feat: ws

* refactor: error handling

* refactor: helper

* chore: update readme

* fix: timeout

* chore: update readme

Author: pedrocrvz

.changeset/beige-plants-strive.md

@@ -0,0 +1,5 @@
+---
+"@gelatocloud/gasless": patch
+---
+
+feat: ws

.changeset/config.json

@@ -9,7 +9,10 @@
     "bundler-gelato-sponsored-payment",
     "bundler-kernel-sponsored-payment",
     "relayer-sponsored-payment",
-    "account-sponsored-payment"
+    "account-sponsored-payment",
+    "account-ws",
+    "relayer-ws",
+    "bundler-ws"
   ],
   "linked": [],
   "updateInternalDependencies": "patch"

README.md

@@ -14,6 +14,7 @@
 - **2D nonce support** - Advanced nonce management using both `nonce` and `nonceKey` for parallelized execution.
 - **Type-safe** - Implemented on top of [viem](https://viem.sh), offering complete TypeScript type safety and developer ergonomics.
 - **Synchronous methods**: Send transaction and get the receipt in a single call
+- **WebSockets**: Live notifications and updates via WebSockets
 
 ### Learn more in our [docs](https://docs.gelato.cloud)
 
@@ -62,27 +63,25 @@ console.log(`Transaction hash: ${receipt.transactionHash}`);
 
 **Asynchronous:**
 ```typescript
-import { createGelatoEvmRelayerClient, StatusCode } from '@gelatocloud/gasless';
+import { createGelatoEvmRelayerClient } from '@gelatocloud/gasless';
 import { baseSepolia } from 'viem/chains';
 
 const relayer = createGelatoEvmRelayerClient({
   apiKey: process.env.GELATO_API_KEY,
   testnet: true
 });
 
-// Send transaction (returns immediately with task ID)
-const taskId = await relayer.sendTransaction({
+// Send transaction (returns immediately with ID)
+const id = await relayer.sendTransaction({
   chainId: baseSepolia.id,
   to: '0xTargetContract...',
   data: '0xCalldata...'
 });
 
 // Poll for status separately
-const { status, receipt } = await relayer.waitForStatus({ id: taskId });
+const receipt = await relayer.waitForReceipt({ id });
 
-if (status.status === StatusCode.Success) {
-  console.log(`Transaction hash: ${receipt.transactionHash}`);
-}
+console.log(`Transaction hash: ${receipt.transactionHash}`);
 ```
 
 ### Account (Gelato Smart Account)
@@ -129,21 +128,18 @@ console.log(`Transaction hash: ${receipt.transactionHash}`);
 ```typescript
 import {
   createGelatoSmartAccountClient,
-  toGelatoSmartAccount,
-  StatusCode } from '@gelatocloud/gasless';
+  toGelatoSmartAccount } from '@gelatocloud/gasless';
 
 // ... same setup as above ...
 
-// Send transaction (returns immediately with task ID)
-const taskId = await client.sendTransaction({
+// Send transaction (returns immediately with ID)
+const id = await client.sendTransaction({
   calls: [{ to: '0xContract...', data: '0xCalldata...' }] });
 
 // Poll for status separately
-const status = await client.waitForStatus({ id: taskId });
+const receipt = await client.waitForReceipt({ id });
 
-if (status.status === StatusCode.Success) {
-  console.log(`Transaction hash: ${status.receipt.transactionHash}`);
-}
+console.log(`Transaction hash: ${receipt.transactionHash}`);
 ```
 
 
@@ -190,6 +186,102 @@ const { receipt } = await bundler.waitForUserOperationReceipt({ hash });
 console.log(`Transaction hash: ${receipt.transactionHash}`);
 ```
 
+### WebSocket Subscriptions
+
+WebSockets are enabled by default. Methods automatically race WebSocket notifications against HTTP polling for the fastest result. To disable:
+
+```typescript
+const relayer = createGelatoEvmRelayerClient({
+  apiKey: process.env.GELATO_API_KEY,
+  ws: { disable: true }
+});
+```
+
+**Relayer — single transaction:**
+```typescript
+const id = await relayer.sendTransaction({
+  chainId: baseSepolia.id,
+  to: '0xTargetContract...',
+  data: '0xCalldata...'
+});
+
+const subscription = await relayer.ws.subscribe({ id });
+
+subscription.on('success', (data) => {
+  console.log(`Included in block ${data.receipt.blockNumber}`);
+});
+
+subscription.on('reverted', (data) => {
+  console.log(`Reverted: ${data.receipt.blockNumber}`);
+});
+
+// Cleanup when done
+await relayer.ws.unsubscribe(subscription.subscriptionId);
+relayer.ws.disconnect();
+```
+
+**Relayer — global (all transactions):**
+```typescript
+const subscription = await relayer.ws.subscribe();
+
+subscription.on('submitted', (data) => console.log(`${data.id} submitted`));
+subscription.on('success', (data) => console.log(`${data.id} success`));
+subscription.on('rejected', (data) => console.log(`${data.id} rejected`));
+```
+
+**Bundler** — same patterns apply via `bundler.ws`:
+```typescript
+const subscription = await bundler.ws.subscribe({ id: userOpHash });
+subscription.on('success', (data) => console.log(data.receipt));
+```
+
+**Events:**
+
+| Event | Description |
+|-------------|-------------------------------------|
+| `pending` | Transaction pending |
+| `submitted` | Submitted to network |
+| `success` | Successfully included on-chain |
+| `rejected` | Rejected by relayer |
+| `reverted` | Reverted on-chain |
+
+**Cleanup:**
+```typescript
+await relayer.ws.unsubscribe(subscription.subscriptionId);
+relayer.ws.disconnect();
+```
+
+## Sync vs Async
+
+The SDK offers two ways to send transactions:
+
+| | Sync (`sendTransactionSync`) | Async (`sendTransaction` + WS) |
+|---|---|---|
+| Returns | Final `TransactionReceipt` | ID (`Hex`) immediately |
+| Lifecycle events | None (handled internally) | All: `pending`, `submitted`, `success`, `rejected`, `reverted` |
+| Tx hash on (re)submission | Not exposed | `hash` field on every `submitted` event |
+| Control | Minimal — fire and forget | Full — react to each status change via WS subscription |
+
+**Sync** — call `sendTransactionSync` to send the transaction and get the receipt in the same call. If the transaction is not included, the SDK will handle it internally and return a final `TransactionReceipt` by racing http polls and ws updates. Simplest approach when you just need the result:
+
+```typescript
+const receipt = await relayer.sendTransactionSync({ chainId, to, data });
+```
+
+**Async** — call `sendTransaction` to get a ID immediately, then subscribe via WebSocket for granular status updates. **WS subscriptions give you full control over the transaction lifecycle** — you can react to resubmissions, display tx hashes to users in real time, handle rejections immediately, and more. The `submitted` event includes the transaction `hash` each time the relay (re)submits the transaction (e.g. with bumped gas):
+
+```typescript
+const id = await relayer.sendTransaction({ chainId, to, data });
+const subscription = await relayer.ws.subscribe({ id });
+
+subscription.on('submitted', (data) => {
+  console.log(`Tx hash: ${data.hash}`); // available on every (re)submission
+});
+
+subscription.on('success', (data) => {
+  console.log(`Confirmed in block ${data.receipt.blockNumber}`);
+});
+```
 
 ## API Reference
 
@@ -211,10 +303,9 @@ const client = createGelatoEvmRelayerClient({
 | Method | Parameters | Returns | Description |
 |--------|------------|---------|-------------|
 | `sendTransaction` | `{ chainId, to, data, authorizationList?, context? }` | `Promise<Hex>` | Submit a transaction |
-| `sendTransactionSync` | `{ chainId, to, data, timeout?, pollingInterval?, ... }` | `Promise<TransactionReceipt>` | Send and wait for receipt |
+| `sendTransactionSync` | `{ chainId, to, data, timeout?, pollingInterval?, throwOnReverted?, ... }` | `Promise<TransactionReceipt>` | Send and wait for receipt |
 | `getStatus` | `{ id: string }` | `Promise<Status>` | Get transaction status |
-| `waitForStatus` | `{ id: string, timeout?, pollingInterval? }` | `Promise<TerminalStatus>` | Wait for final status |
-| `waitForReceipt` | `{ id: string, timeout?, pollingInterval? }` | `Promise<TransactionReceipt>` | Wait for receipt, throws on failure |
+| `waitForReceipt` | `{ id: string, timeout?, pollingInterval?, throwOnReverted? }` | `Promise<TransactionReceipt>` | Wait for receipt, throws on failure |
 | `getCapabilities` | - | `Promise<Capabilities>` | Get supported chains |
 | `getFeeData` | `{ chainId, gas, l1Fee? }` | `Promise<FeeData>` | Get network fee data |
 
@@ -249,10 +340,9 @@ const client = await createGelatoSmartAccountClient({
 | Method | Parameters | Returns | Description |
 |--------|------------|---------|-------------|
 | `sendTransaction` | `{ calls, nonce?, nonceKey?}` | `Promise<Hex>` | Send transaction(s) |
-| `sendTransactionSync` | `{ calls, nonce?, nonceKey?, timeout?, pollingInterval?, ... }` | `Promise<TransactionReceipt>` | Send and wait for receipt |
+| `sendTransactionSync` | `{ calls, nonce?, nonceKey?, timeout?, pollingInterval?, throwOnReverted?, ... }` | `Promise<TransactionReceipt>` | Send and wait for receipt |
 | `getStatus` | `{ id: string }` | `Promise<Status>` | Get transaction status |
-| `waitForStatus` | `{ id: string, timeout?, pollingInterval? }` | `Promise<TerminalStatus>` | Wait for final status |
-| `waitForReceipt` | `{ id: string, timeout?, pollingInterval? }` | `Promise<TransactionReceipt>` | Wait for receipt, throws on failure |
+| `waitForReceipt` | `{ id: string, timeout?, pollingInterval?, throwOnReverted? }` | `Promise<TransactionReceipt>` | Wait for receipt, throws on failure |
 | `getCapabilities` | - | `Promise<Capabilities>` | Get supported chains |
 
 **Nonce Options:**
@@ -261,7 +351,7 @@ const client = await createGelatoSmartAccountClient({
 
 **Polling Configuration:**
 
-All synchronous methods (`sendTransactionSync`, `sendUserOperationSync`, `waitForStatus`, `waitForReceipt`) support customizable polling behavior:
+All synchronous methods (`sendTransactionSync`, `sendUserOperationSync`, `waitForReceipt`) support customizable polling behavior:
 
 - `timeout` (optional): Maximum wait time in milliseconds
   - Default: `120000` (2 minutes)
@@ -370,9 +460,7 @@ type Call = {
 ## Status Handling
 
 ```typescript
-import { StatusCode } from '@gelatocloud/gasless';
-
-const status = await client.waitForStatus({ id: hash });
+const status = await client.getStatus({ id: hash });
 
 switch (status.status) {
   case StatusCode.Success:
@@ -391,7 +479,7 @@ switch (status.status) {
 
 ### Timeout Errors
 
-Synchronous methods (`sendTransactionSync`, `waitForStatus`, `waitForReceipt`) throw `TimeoutError` when operations don't complete within the configured timeout:
+Synchronous methods (`sendTransactionSync`, `waitForReceipt`) throw `TimeoutError` when operations don't complete within the configured timeout:
 
 ```typescript
 import { TimeoutError } from '@gelatocloud/gasless';
@@ -414,57 +502,84 @@ try {
 }
 ```
 
-### Automatic Fallback on Timeout
+### Revert Handling
 
-When `sendTransactionSync` times out, it automatically falls back to polling for the transaction status. If you see a warning message like:
+By default, `sendTransactionSync` and `waitForReceipt` return the receipt even when a transaction reverts on-chain. Set `throwOnReverted: true` to throw a `TransactionRevertedError` instead:
 
-```
-Transaction 0x... sync call timed out, falling back to polling for completion. DO NOT RETRY this transaction.
+```typescript
+import { TransactionRevertedError } from '@gelatocloud/gasless';
+
+try {
+  const receipt = await relayer.sendTransactionSync({
+    chainId: baseSepolia.id,
+    to: '0xTargetContract...',
+    data: '0xCalldata...',
+    throwOnReverted: true
+  });
+} catch (error) {
+  if (error instanceof TransactionRevertedError) {
+    console.error('Transaction reverted:', error.receipt.transactionHash);
+    console.error('Error message:', error.erroMessage);
+    console.error('Error data:', error.errorData);
+    // Also available: error.id, error.chainId, error.createdAt
+  }
+}
 ```
 
-This means your transaction was successfully submitted but the sync method timed out. The SDK will continue polling for completion automatically. **Do not retry the operation** as this could result in duplicate transactions.
+Available on both relayer and account clients via `sendTransactionSync` and `waitForReceipt`. Properties on `TransactionRevertedError`: `receipt`, `id`, `chainId`, `createdAt`, `errorData`, `errorMessage`.
 
-### Recovery Strategies
+### Simulation Errors
 
-If a timeout occurs:
-1. **Wait for automatic fallback**: `sendTransactionSync` automatically polls after timeout
-2. **Check status manually**: Use `getStatus({ id })` to check if transaction is still processing
-3. **Retry with longer timeout**: Increase `timeout` and call `waitForStatus` again
-4. **Use async methods**: Switch to async pattern for more control
+When the relayer simulates a transaction before submission and the simulation reverts, a `SimulationFailedRpcError` is thrown with error code `4211`. This happens _before_ the transaction is sent on-chain:
 
 ```typescript
+import { SimulationFailedRpcError } from '@gelatocloud/gasless';
+
 try {
-  // Try with default 10s timeout
   const receipt = await relayer.sendTransactionSync({
     chainId: baseSepolia.id,
     to: '0xTargetContract...',
-    data: '0xCalldata...',
+    data: '0xCalldata...'
   });
 } catch (error) {
-  if (error instanceof TimeoutError) {
-    // Retry with 60s timeout
-    const taskId = await relayer.sendTransaction({
-      chainId: baseSepolia.id,
-      to: '0xTargetContract...',
-      data: '0xCalldata...',
-    });
-
-    const status = await relayer.waitForStatus({
-      id: taskId,
-      timeout: 60000
-    });
-
-    console.log('Transaction completed:', status);
+  if (error instanceof SimulationFailedRpcError) {
+    console.error('Simulation reverted:', error.message);
+    console.error('Revert data:', error.revertData);
+    // error.params contains the original { to, chainId, data } sent
   }
 }
 ```
 
+Properties on `SimulationFailedRpcError`: `revertData`, `params`, `code` (`4211`).
+
+### Automatic Fallback on Timeout
+
+When `sendTransactionSync` rpc request times out, the SDK automatically falls back to polling for the transaction status. If you see a warning message like:
+
+```
+Transaction 0x... sync call timed out, falling back to polling for completion. DO NOT RETRY this transaction.
+```
+
+This means your transaction was successfully submitted but the sync method timed out. The SDK will continue polling for completion automatically. **Do not retry the operation** as this could result in duplicate transactions.
+
+### Recovery Strategies
+
+If a timeout occurs:
+1. **Wait for automatic fallback**: `sendTransactionSync` automatically polls after timeout
+2. **Check status manually**: Use `getStatus({ id })` to check if transaction is still processing if needed
+3. **Retry with longer timeout**: Increase `timeout` and call `waitForReceipt` again
+4. **Use async methods**: Switch to async pattern for more control
+
+
 ### Configuration Limits
 
 The SDK enforces the following limits to prevent denial of service:
 
 ```typescript
 import {
+  TimeoutError,
+  TransactionRevertedError,
+  SimulationFailedRpcError,
   MIN_TIMEOUT,
   MAX_TIMEOUT,
   MIN_POLLING_INTERVAL,
@@ -508,6 +623,9 @@ See the [`/examples`](./examples) directory for complete working examples:
 - [`examples/relayer/sponsored`](./examples/relayer/sponsored) - Direct relayer usage
 - [`examples/account/sponsored`](./examples/account/sponsored) - Gelato smart account
 - [`examples/bundler/sponsored`](./examples/bundler/sponsored) - ERC-4337 bundler
+- [`examples/relayer/ws`](./examples/relayer/ws) - Relayer WebSocket usage
+- [`examples/bundler/ws`](./examples/bundler/ws) - Bundler WebSocket usage
+- [`examples/account/ws`](./examples/account/ws) - Account WebSocket usage
 
 Run an example: