@miradorlabs/parallax-web 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miradorlabs/parallax-web",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Parallax Web Client Side SDK ",
   "main": "dist/index.umd.js",
   "module": "dist/index.esm.js",
@@ -44,7 +44,7 @@
     "typescript-eslint": "^8.47.0"
   },
   "dependencies": {
-    "google-protobuf": "^4.0.1",
+    "google-protobuf": "^3.21.4",
     "grpc-web": "^2.0.2",
     "mirador-gateway-parallax-web": "https://storage.googleapis.com/mirador-shd-packages/gateway/parallax/grpc-web/mirador-gateway-parallax-grpc-web-1.0.9.tgz",
     "rxjs": "^7.8.2"

package/src/parallax/index.ts

@@ -38,6 +38,129 @@ class ParallaxClient {
     this.client = new ParallaxGatewayServiceClient(this.apiUrl, credentials);
   }
 
+  /**
+   * Gather client metadata for traces/spans
+   * Returns a metadata object with client environment details
+   * This includes browser, OS, screen size, IP address, and more
+   * @returns metadata
+   */
+  async getClientMetadata(): Promise<{ [key: string]: string }> {
+    const metadata: { [key: string]: string } = {};
+    // Browser info
+    metadata.userAgent = navigator.userAgent;
+    metadata.platform = navigator.platform;
+    metadata.language = navigator.language;
+
+    // Screen info
+    metadata.screenWidth = window.screen.width.toString();
+    metadata.screenHeight = window.screen.height.toString();
+    metadata.viewportWidth = window.innerWidth.toString();
+    metadata.viewportHeight = window.innerHeight.toString();
+
+    // Try to get IP address (non-blocking)
+    // Note: This may be blocked by Content Security Policy (CSP)
+    // If blocked, the backend should capture IP from request headers instead
+    try {
+      // Use ipify API (simple and fast JSON response)
+      const ipResponse: Response | Error = await fetch('https://api.ipify.org?format=json');
+
+      if (ipResponse && ipResponse.ok) {
+        const data = await ipResponse.json();
+        if (data && data.ip) {
+          metadata.ip = data.ip;
+        } else {
+          metadata.ip = 'client_unavailable';
+        }
+      } else {
+        metadata.ip = 'client_unavailable';
+      }
+    } catch (error) {
+      // IP lookup failed (CSP block, timeout, or network error)
+      // This is expected if CSP blocks external requests
+      // Backend should capture IP from request headers instead
+      if (error instanceof Error && error.message.includes('Content Security Policy')) {
+        console.debug('IP fetch blocked by CSP - backend will capture from headers');
+      } else {
+        console.debug('Could not fetch IP address');
+      }
+      metadata.ip = 'client_unavailable';
+    }
+
+    // Browser details (parse from user agent)
+    const ua = navigator.userAgent;
+    if (ua.includes('Chrome')) {
+      metadata.browser = 'Chrome';
+    } else if (ua.includes('Firefox')) {
+      metadata.browser = 'Firefox';
+    } else if (ua.includes('Safari')) {
+      metadata.browser = 'Safari';
+    } else if (ua.includes('Edge')) {
+      metadata.browser = 'Edge';
+    } else {
+      metadata.browser = 'Unknown';
+    }
+
+    // OS detection
+    if (ua.includes('Windows')) {
+      metadata.os = 'Windows';
+    } else if (ua.includes('Mac')) {
+      metadata.os = 'macOS';
+    } else if (ua.includes('Linux')) {
+      metadata.os = 'Linux';
+    } else if (ua.includes('Android')) {
+      metadata.os = 'Android';
+    } else if (ua.includes('iOS')) {
+      metadata.os = 'iOS';
+    } else {
+      metadata.os = 'Unknown';
+    }
+
+    // Timezone
+    metadata.timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    metadata.timezoneOffset = new Date().getTimezoneOffset().toString();
+
+    // Page info
+    metadata.url = window.location.href;
+    metadata.referrer = document.referrer || 'direct';
+
+    return metadata;
+  }
+
+  /**
+   * Creates a CreateTraceRequest with optional attributes and client metadata
+   * @param name name of the trace
+   * @param tags optional tags for trace
+   * @param attr optional attributes for trace
+   * @param includeClientMeta optional flag to include client metadata (ip, browser, os, etc)
+   * @returns a CreateTraceRequest object to be used for the createTrace request
+   */
+  async createTraceRequest({name, tags, attr, includeClientMeta = false}: {name: string, tags?: string[], attr?: { [key: string]: string }, includeClientMeta?: boolean}): Promise<CreateTraceRequest> {
+    const createTraceReq = new CreateTraceRequest();
+    createTraceReq.setName(name);
+    if (tags) {
+      createTraceReq.setTagsList(tags);
+    }
+    const traceAttrs = createTraceReq.getAttributesMap();
+
+    if (attr) {
+      Object.entries(attr).forEach(([key, value]) => {
+        if (key.includes('client.')) {
+          console.warn(`Attribute key "${key}" is reserved for client metadata. It will be prefixed with "custom."`);
+        } else {
+          traceAttrs.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+        }
+      });
+    }
+    if (includeClientMeta) {
+      const clientMetadata = await this.getClientMetadata();
+      Object.entries(clientMetadata).forEach(([key, value]) => {
+        traceAttrs.set(`client.${key}`, value);
+      });
+    }
+    return createTraceReq;
+  }
+
+
   /**
    * Create a new trace
    * @param params Parameters to create a new trace
@@ -52,6 +175,46 @@ class ParallaxClient {
     }
   }
 
+  /**
+   * Create a StartSpanRequest with optional attributes and client metadata
+   * @param traceId trace id to associate the span with
+   * @param name name of the span
+   * @param parentSpanId (optional) create a span off a parent span id
+   * @param attr (optional) attributes to add to the span
+   * @param includeClientMeta (optional) flag to include client metadata (ip, browser, os, etc)
+   * @returns 
+   */
+  async createStartSpanRequest({ traceId, name, parentSpanId, attr, includeClientMeta = false}: {traceId: string, name: string, parentSpanId?: string, attr?: { [key: string]: string }, includeClientMeta?: boolean}): Promise<StartSpanRequest> {
+    const startSpanReq = new StartSpanRequest();
+    startSpanReq.setTraceId(traceId);
+    startSpanReq.setName(name);
+    if (parentSpanId) {
+      startSpanReq.setParentSpanId(parentSpanId);
+    }
+    const spanAttrs = startSpanReq.getAttributesMap();
+
+    if (attr) {
+      Object.entries(attr).forEach(([key, value]) => {
+        if (key.includes('client.')) {
+          console.warn(`Attribute key "${key}" is reserved for client metadata. It will be prefixed with "custom."`);
+        } else {
+          spanAttrs.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+        }
+      });
+    }
+    try {
+      if (includeClientMeta) {
+        const clientMetadata = await this.getClientMetadata();
+        Object.entries(clientMetadata).forEach(([key, value]) => {
+          spanAttrs.set(`client.${key}`, value);
+        });
+      }
+    } catch (error) {
+      console.error('Error gathering client metadata for span:', error);
+    }
+    return startSpanReq;
+  }
+
   /**
    * Start a new span within a trace
    * @param params Parameters to start a new span
@@ -65,6 +228,26 @@ class ParallaxClient {
     }
   }
 
+  /**
+   * Create a FinishSpanRequest
+   * @param params Parameters to finish a span - traceId, spanId, status (optional) (success, errorMessage) 
+   * @returns FinishSpanRequest
+   */
+  createFinishSpanRequest({ traceId, spanId, status }: { traceId: string, spanId: string, status?: { success: boolean, errorMessage: string } }): FinishSpanRequest {
+    const request = new FinishSpanRequest();
+    request.setTraceId(traceId);
+    request.setSpanId(spanId);
+    if (status !== undefined) {
+      const spanStatus = new FinishSpanRequest.SpanStatus();
+      spanStatus.setCode(status.success ? FinishSpanRequest.SpanStatus.StatusCode.STATUS_CODE_OK : FinishSpanRequest.SpanStatus.StatusCode.STATUS_CODE_ERROR);
+      if (status.errorMessage) {
+        spanStatus.setMessage(status.errorMessage);
+      }
+      request.setStatus(spanStatus);
+    }
+    return request;
+  }
+
   /**
    * Finish a span within a trace
    * @param params Parameters to finish a span
@@ -78,6 +261,26 @@ class ParallaxClient {
     }
   }
 
+  /**
+   * Creates the add span event request
+   * @param params - Parameters to create an AddSpanEventRequest - traceId, spanId, eventName, attr (optional) 
+   * @returns AddSpanEventRequest
+   */
+  createAddSpanEventRequest({ traceId, spanId, eventName, attr }: { traceId: string, spanId: string, eventName: string,  attr?: { [key: string]: string } }): AddSpanEventRequest {
+    const request = new AddSpanEventRequest();
+    request.setTraceId(traceId);
+    request.setSpanId(spanId);
+    request.setEventName(eventName);
+    const eventAttrs = request.getAttributesMap();
+    if (attr) {
+      Object.entries(attr).forEach(([key, value]) => {
+        eventAttrs.set(key, typeof value === 'object' ? JSON.stringify(value) : String(value));
+      });
+    }
+    eventAttrs.set('timestamp', new Date().toISOString());
+    return request;
+  }
+
   /**
    * Add an event to a span
    * @param params Parameters to add an event to a span
@@ -91,6 +294,25 @@ class ParallaxClient {
     }
   }
 
+  /**
+   * Creates the add span error request
+   * @param params - params used to generate the error request ( traceid, span id, error message, error type, stack trace)
+   * @returns AddSpanErrorRequest
+   */
+  createAddSpanErrorRequest({ traceId, spanId, errorMessage, errorType, stackTrace }: { traceId: string, spanId: string, errorMessage: string, errorType?: string, stackTrace?: string }): AddSpanErrorRequest {
+    const request = new AddSpanErrorRequest();
+    request.setTraceId(traceId);
+    request.setSpanId(spanId);
+    request.setMessage(errorMessage);
+    if (errorType) {
+      request.setErrorType(errorType);
+    }
+    if (stackTrace) {
+      request.setStackTrace(stackTrace);
+    }
+    return request;
+  }
+
   /**
    * Add an error to a span
    * @param params Parameters to add an error to a span
@@ -104,6 +326,25 @@ class ParallaxClient {
     }
   }
 
+  /**
+   * Creates the add span hint request
+   * @param params - params used to generate the span hint (trace id, parentSpanId, txHash and chainId)
+   * @returns AddSpanHintRequest
+   */
+  createAddSpanHintRequest({ traceId, parentSpanId, txHash, chainId }: { traceId: string, parentSpanId: string, txHash?: string, chainId?: number }): AddSpanHintRequest {
+    const hintReq = new AddSpanHintRequest();
+    hintReq.setTraceId(traceId);
+    hintReq.setParentSpanId(parentSpanId);
+
+    if (txHash && chainId !== undefined) {
+      const chainTxReq = new AddSpanHintRequest.ChainTransaction();
+      chainTxReq.setTxHash(txHash);
+      chainTxReq.setChainId(chainId);
+      hintReq.setChainTransaction(chainTxReq);
+    }
+    return hintReq;
+  }
+
   /**
    * Add a hint to a span
    * @param params Parameters to add a hint to a span