@miradorlabs/parallax-web 2.2.0 → 2.3.1

package/README.md

@@ -11,6 +11,8 @@ npm install @miradorlabs/parallax-web
 ## Features
 
 - **Auto-Flush Mode** - Data automatically batches and sends after a configurable period of inactivity
+- **Keep-Alive** - Automatic periodic pings to maintain trace liveness (configurable interval)
+- **Trace Lifecycle** - Explicit close trace method with automatic cleanup
 - **Fluent Builder Pattern** - Method chaining for building traces
 - **Browser-optimized** - Automatic client metadata collection (browser, OS, etc.)
 - **Blockchain Integration** - Built-in support for correlating traces with blockchain transactions
@@ -75,6 +77,80 @@ trace.addEvent('transaction_signed'); // → UpdateTrace sent immediately
 trace.addTxHint('0x...', 'ethereum'); // → UpdateTrace sent immediately
 ```
 
+## Keep-Alive & Trace Lifecycle
+
+### Automatic Keep-Alive
+
+The SDK automatically sends keep-alive pings to the server every 10 seconds (configurable) to maintain trace liveness. This starts automatically after the first successful trace creation.
+
+```typescript
+// Use default 10-second interval
+const client = new ParallaxClient('your-api-key');
+
+// Or customize the interval
+const client = new ParallaxClient('your-api-key', {
+  keepAliveIntervalMs: 15000  // Ping every 15 seconds
+});
+
+const trace = client.trace({ name: 'MyTrace' });
+// Keep-alive starts automatically after first flush completes
+```
+
+### Closing Traces
+
+Always close traces when you're done to clean up resources and notify the server:
+
+```typescript
+const trace = client.trace({ name: 'UserSession' });
+
+// ... add events, attributes, etc ...
+
+// Close when done
+await trace.close('Session ended');
+
+// All subsequent operations are ignored
+trace.addEvent('ignored');  // Logs warning, does nothing
+```
+
+**Best Practices:**
+- Always call `close()` when you're done with a trace
+- Use try-catch blocks to ensure traces are closed even on errors
+- Provide a meaningful reason to help with debugging
+
+```typescript
+const trace = client.trace({ name: 'CheckoutFlow' });
+
+try {
+  // ... trace user checkout flow ...
+  await trace.close('Checkout completed');
+} catch (error) {
+  trace.addEvent('error', { message: error.message });
+  await trace.close('Checkout failed');
+}
+```
+
+### Auto-Close on Page Unload
+
+For browser-based applications, you can enable automatic trace closing when the user navigates away or closes the tab:
+
+```typescript
+const trace = client.trace({
+  name: 'UserSession',
+  autoClose: true  // Automatically close on page unload
+});
+
+// Trace will automatically close with reason "Page unload" when:
+// - User closes the tab/window
+// - User navigates to a different page
+// - Page is refreshed
+```
+
+**Important Notes:**
+- Auto-close uses the `beforeunload` event
+- The trace will be closed with the reason "Page unload"
+- You can still manually call `close()` before page unload
+- The event listener is automatically cleaned up when you manually close the trace
+
 ## API Reference
 
 ### ParallaxClient
@@ -96,7 +172,8 @@ new ParallaxClient(apiKey: string, options?: ParallaxClientOptions)
 
 ```typescript
 interface ParallaxClientOptions {
-  apiUrl?: string;  // Gateway URL (defaults to parallax-gateway-dev.mirador.org:443)
+  apiUrl?: string;              // Gateway URL (defaults to parallax-gateway-dev.mirador.org:443)
+  keepAliveIntervalMs?: number; // Keep-alive ping interval in milliseconds (default: 10000)
 }
 ```
 
@@ -120,6 +197,7 @@ const trace = client.trace({ autoFlush: false, flushPeriodMs: 100 });
 | `includeClientMeta` | `boolean` | `true` | Include browser/OS metadata |
 | `maxRetries` | `number` | `3` | Maximum retry attempts on network failure |
 | `retryBackoff` | `number` | `1000` | Base delay in ms for exponential backoff (doubles each retry) |
+| `autoClose` | `boolean` | `false` | Automatically close trace on page unload |
 
 Returns: `ParallaxTrace` builder instance
 
@@ -205,12 +283,43 @@ Get the trace ID (available after first flush completes).
 const traceId = trace.getTraceId();  // string | null
 ```
 
+#### `close(reason?)`
+
+Close the trace and stop all timers (flush timer and keep-alive timer). After calling this method, all subsequent operations will be ignored.
+
+```typescript
+await trace.close();
+await trace.close('User completed workflow');
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `reason` | `string` | Optional reason for closing the trace |
+
+Returns: `Promise<void>`
+
+**Important:** Once a trace is closed:
+- All method calls (`addAttribute`, `addEvent`, `addTag`, `addTxHint`, `flush`) will be ignored with a warning
+- The keep-alive timer will be stopped
+- A close request will be sent to the server
+
+#### `isClosed()`
+
+Check if the trace has been closed.
+
+```typescript
+const closed = trace.isClosed();  // boolean
+```
+
 ## Complete Example: Transaction Tracking
 
 ```typescript
 import { ParallaxClient } from '@miradorlabs/parallax-web';
 
-const client = new ParallaxClient('your-api-key');
+// Create client with custom keep-alive interval (optional)
+const client = new ParallaxClient('your-api-key', {
+  keepAliveIntervalMs: 15000  // Override default 10s interval
+});
 
 async function handleWalletTransaction(userAddress: string, recipientAddress: string, amount: string) {
   const trace = client.trace({ name: 'SendETH' })
@@ -220,14 +329,23 @@ async function handleWalletTransaction(userAddress: string, recipientAddress: st
     .addTags(['transaction', 'send', 'ethereum'])
     .addEvent('wallet_connected', { wallet: 'MetaMask' });
   // → CreateTrace sent automatically
+  // → Keep-alive timer starts automatically
 
   trace.addEvent('user_signed');
 
-  const receipt = await sendTransaction();
+  try {
+    const receipt = await sendTransaction();
+
+    trace.addEvent('transaction_sent', { txHash: receipt.hash })
+         .addTxHint(receipt.hash, 'ethereum');
+    // → UpdateTrace sent automatically
 
-  trace.addEvent('transaction_sent', { txHash: receipt.hash })
-       .addTxHint(receipt.hash, 'ethereum');
-  // → UpdateTrace sent automatically
+    // Close the trace when done
+    await trace.close('Transaction completed successfully');
+  } catch (error) {
+    trace.addEvent('transaction_failed', { error: error.message });
+    await trace.close('Transaction failed');
+  }
 }
 ```
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
-import { CreateTraceRequest, CreateTraceResponse, UpdateTraceRequest, UpdateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
+import { CreateTraceRequest, CreateTraceResponse, UpdateTraceRequest, UpdateTraceResponse, KeepAliveRequest, KeepAliveResponse, CloseTraceRequest, CloseTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
 export { CreateTraceRequest, CreateTraceResponse } from 'mirador-gateway-parallax-web/proto/gateway/parallax/v1/parallax_gateway_pb';
 
 /**
@@ -11,6 +11,8 @@ export { CreateTraceRequest, CreateTraceResponse } from 'mirador-gateway-paralla
 interface ParallaxClientOptions {
     /** Gateway URL (defaults to parallax-gateway-dev.mirador.org:443) */
     apiUrl?: string;
+    /** Keep-alive ping interval in milliseconds (default: 10000) */
+    keepAliveIntervalMs?: number;
 }
 /**
  * Options for creating a trace
@@ -28,6 +30,8 @@ interface TraceOptions {
     maxRetries?: number;
     /** Base delay in ms for exponential backoff between retries (default: 1000) */
     retryBackoff?: number;
+    /** Automatically close trace on page unload (default: false) */
+    autoClose?: boolean;
 }
 /**
  * Supported chain names (maps to Chain enum in proto)
@@ -45,6 +49,8 @@ type ChainName = 'ethereum' | 'polygon' | 'arbitrum' | 'base' | 'optimism' | 'bs
 interface TraceSubmitter {
     _sendTrace(request: CreateTraceRequest): Promise<CreateTraceResponse>;
     _updateTrace(request: UpdateTraceRequest): Promise<UpdateTraceResponse>;
+    _keepAlive(request: KeepAliveRequest): Promise<KeepAliveResponse>;
+    _closeTrace(request: CloseTraceRequest): Promise<CloseTraceResponse>;
 }
 /** Options passed to ParallaxTrace constructor (with defaults applied) */
 interface ResolvedTraceOptions {
@@ -54,6 +60,8 @@ interface ResolvedTraceOptions {
     includeClientMeta: boolean;
     maxRetries: number;
     retryBackoff: number;
+    keepAliveIntervalMs: number;
+    autoClose: boolean;
 }
 /**
  * Builder class for constructing traces with method chaining.
@@ -67,9 +75,14 @@ declare class ParallaxTrace {
     private autoFlush;
     private flushPeriodMs;
     private flushTimer;
+    private keepAliveIntervalMs;
+    private keepAliveTimer;
+    private autoClose;
+    private unloadHandler;
     private maxRetries;
     private retryBackoff;
     private traceId;
+    private closed;
     private pendingAttributes;
     private pendingTags;
     private pendingEvents;
@@ -156,11 +169,34 @@ declare class ParallaxTrace {
      * Clear all pending data
      */
     private clearPending;
+    /**
+     * Start the keep-alive timer to ping the server periodically
+     */
+    private startKeepAlive;
+    /**
+     * Send a keep-alive ping to the server
+     */
+    private sendKeepAlive;
+    /**
+     * Stop the keep-alive timer
+     */
+    private stopKeepAlive;
+    /**
+     * Close the trace and stop all timers.
+     * After calling this method, all subsequent operations (addAttribute, addEvent, etc.) will be ignored.
+     * @param reason Optional reason for closing the trace
+     */
+    close(reason?: string): Promise<void>;
     /**
      * Get the trace ID (available after first flush completes)
      * @returns The trace ID or null if not yet created
      */
     getTraceId(): string | null;
+    /**
+     * Check if the trace is closed
+     * @returns True if the trace is closed
+     */
+    isClosed(): boolean;
 }
 
 /**
@@ -169,6 +205,7 @@ declare class ParallaxTrace {
 declare class ParallaxClient {
     apiUrl: string;
     apiKey: string;
+    keepAliveIntervalMs: number;
     private client;
     /**
      * Create a new ParallaxClient instance
@@ -180,6 +217,10 @@ declare class ParallaxClient {
     _sendTrace(request: CreateTraceRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.CreateTraceResponse>;
     /** @internal */
     _updateTrace(request: UpdateTraceRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.UpdateTraceResponse>;
+    /** @internal */
+    _keepAlive(request: KeepAliveRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.KeepAliveResponse>;
+    /** @internal */
+    _closeTrace(request: CloseTraceRequest): Promise<mirador_gateway_parallax_web_proto_gateway_parallax_v1_parallax_gateway_pb.CloseTraceResponse>;
     /**
      * Create a new trace builder
      *