@symbo.ls/sdk 2.32.11 → 2.32.13

package/README.md

@@ -377,6 +377,147 @@ const ai = sdk.getService('ai')
 const response = await ai.prompt(query, options)
 ```
 
+### Tracking Service (Grafana Faro)
+```javascript
+// 1) Initialize SDK with tracking config (early in app startup)
+const sdk = new SDK({
+  useNewServices: true,
+  apiUrl: 'https://api.symbols.app',
+  // Tracking configuration mirrors TrackingService options
+  tracking: {
+    url: 'https://<your-faro-receiver-url>', // FO ingest/collector URL
+    appName: 'Symbols Platform',
+    environment: 'development',              // 'production' | 'staging' | 'testing' | 'development'
+    appVersion: '1.0.0',
+    sessionTracking: true,
+    enableTracing: true,                     // adds browser tracing when available
+    globalAttributes: { region: 'us-east-1' }
+  }
+})
+await sdk.initialize()
+
+// 2) Get the tracking service
+const tracking = sdk.getService('tracking')
+
+// 3) Send signals
+tracking.trackEvent('purchase', { amount: 42, currency: 'USD' })
+tracking.trackMeasurement('cart_value', { value: 42 })
+tracking.logError('checkout failed', { step: 'payment' })
+tracking.trackView('Checkout', { stage: 'payment' })
+tracking.setUser({ id: 'u_123', email: 'user@example.com' })
+```
+
+#### Configuration
+Provide these under `tracking` when creating the `SDK` (or later via `tracking.configureTracking()`):
+
+- `url` string: Frontend Observability/Faro ingestion URL. If omitted and no custom transports are provided, tracking is disabled.
+- `appName` string: Logical application name used in Grafana dashboards.
+- `appVersion` string: App version shown in Grafana.
+- `environment` string: One of your environments; default resolves from runtime (`production`, `staging`, `testing`, `development`).
+- `sessionTracking` boolean: Enable Faro session tracking. Default: `true`.
+- `enableTracing` boolean: Enable web tracing and send to Tempo (if collector configured). Default: `true`.
+- `globalAttributes` object: Key/values merged into every signal.
+- `user` object: Initial user attributes.
+- `maxQueueSize` number: Max queued calls before client setup. Default: `100`.
+- `isolate` boolean: Create an isolated Faro instance.
+- `transports` array | `transport` any: Custom transports (advanced).
+- `instrumentations` array | `instrumentationsFactory(runtime) => Promise<array>` | `webInstrumentationOptions` object: Control Faro web instrumentations.
+
+Note:
+- Tracking is automatically disabled in non‑browser environments.
+- Calls are queued until the Faro client is ready. For specific calls, pass `{ queue: false }` to skip queuing.
+
+#### Method reference
+The following methods are available via `sdk.getService('tracking')` and map to `utils/services.js`:
+
+- `configureTracking(trackingOptions)` / `configure(trackingOptions)`: Merge/override runtime tracking options (supports all config keys above).
+- `trackEvent(name, attributes?, options?)`
+  - `name` string (required)
+  - `attributes` object merged with global attributes
+  - `options` object:
+    - `domain` string | null
+    - `queue` boolean (whether to queue if client not ready)
+    - Additional transport options are forwarded to Faro
+  - Example:
+  ```javascript
+  tracking.trackEvent('signup_attempt', { method: 'email' }, { domain: 'auth' })
+  ```
+- `trackError(error, options?)` / `captureException(error, options?)`
+  - `error` Error | string
+  - `options` can be:
+    - object with Faro error options (`context`, `type`, `stackFrames`, `skipDedupe`, `timestampOverwriteMs`, etc.)
+    - or a plain context object (shorthand)
+    - `queue` boolean supported
+  - Example:
+  ```javascript
+  tracking.trackError(new Error('Login failed'), { context: { screen: 'Login' } })
+  ```
+- `logMessage(message, level='info', context?)`
+  - Convenience wrappers: `logDebug`, `logInfo`, `logWarning`/`logWarn`, `logErrorMessage`/`logError`
+  - `message` string | string[]
+  - `context` object merged with global attributes
+  - Example:
+  ```javascript
+  tracking.logWarning('Slow response', { route: '/checkout', ttfbMs: 900 })
+  ```
+- `addBreadcrumb(message, attributes?)`
+  - Adds a low‑cost breadcrumb via `trackEvent('breadcrumb', ...)`
+  - Example:
+  ```javascript
+  tracking.addBreadcrumb('Open modal', { id: 'planLimits' })
+  ```
+- `trackMeasurement(type, values, options?)`
+  - `type` string (required)
+  - `values` object | number. If number, it becomes `{ value: <number> }`.
+  - `options`:
+    - `attributes` object (merged into payload.attributes)
+    - `context` object (transport context)
+    - `queue` boolean
+    - Any additional transport options
+  - Example:
+  ```javascript
+  tracking.trackMeasurement('cart_value', 42, { context: { currency: 'USD' } })
+  ```
+- `trackView(name, attributes?)`
+  - Sets the current view/page in Faro
+  - Example:
+  ```javascript
+  tracking.trackView('Dashboard', { section: 'Analytics' })
+  ```
+- `setUser(user, options?)` / `clearUser()`
+  - `user` object with arbitrary attributes; supports `{ queue: boolean }`
+  - Example:
+  ```javascript
+  tracking.setUser({ id: 'u_123', role: 'admin' })
+  ```
+- `setSession(session, options?)` / `clearSession()`
+  - Attach custom session data; supports `{ queue: boolean, ...sessionOptions }`
+- `setGlobalAttributes(attributes)` / `setGlobalAttribute(key, value)` / `removeGlobalAttribute(key)`
+  - Manage the global attributes merged into every signal
+- `flushQueue()`
+  - Immediately runs all queued calls (no‑op if client not ready)
+- `getClient()`
+  - Returns the underlying Faro client (or `null` if not ready)
+- `isEnabled()` / `isInitialized()`
+  - Status helpers
+
+#### Example: auth error tracking from services
+The SDK’s services automatically send errors to tracking:
+```javascript
+try {
+  await auth.login(email, password)
+} catch (error) {
+  // BaseService forwards details to tracking.trackError(...)
+}
+```
+
+#### Visualizing in Grafana
+- Use the Frontend Observability (Faro) data source and pick:
+  - Service = your `appName`
+  - Environment = your `environment`
+- Panels for page loads and Web Vitals require web instrumentations and real page traffic.
+- If self‑hosting with a Faro collector → Loki/Tempo, ensure the FO app is installed and the dashboard uses the FO data source; otherwise create custom panels with LogQL over Loki.
+
 ## Error Handling
 ```javascript
 try {

package/dist/cjs/config/environment.js

@@ -30,7 +30,9 @@ const CONFIG = {
     // Feature toggles that apply across all environments by default
     features: {
       newUserOnboarding: true,
-      betaFeatures: false
+      betaFeatures: false,
+      // Tracking is enabled by default unless overridden per environment
+      trackingEnabled: true
     }
   },
   // Environment-specific configurations
@@ -48,13 +50,17 @@ const CONFIG = {
     // For based api
     githubClientId: "Ov23liAFrsR0StbAO6PO",
     // For github api
-    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/aef64330db80bdfeaac084317bf72f99",
+    grafanaUrl: "",
     // For grafana tracing
-    grafanaAppName: "Localhost Symbols",
+    grafanaAppName: "Symbols Localhost",
     // Environment-specific feature toggles (override common)
     features: {
-      betaFeatures: true
+      // Disable tracking by default on localhost/dev machines
+      trackingEnabled: false,
       // Enable beta features in local dev
+      betaFeatures: true,
+      // Preserve common defaults explicitly for local
+      newUserOnboarding: true
     },
     typesenseCollectionName: "docs",
     typesenseApiKey: "vZya3L2zpq8L6iI5WWMUZJZABvT63VDb",
@@ -82,7 +88,7 @@ const CONFIG = {
     basedProject: "platform-v2-sm",
     basedOrg: "symbols",
     githubClientId: "Ov23liHxyWFBxS8f1gnF",
-    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/7a3ba473cee2025c68513667024316b8",
+    grafanaUrl: "",
     // For grafana tracing
     grafanaAppName: "Symbols Test",
     typesenseCollectionName: "docs",
@@ -95,7 +101,7 @@ const CONFIG = {
     socketUrl: "https://upcoming.api.symbols.app",
     apiUrl: "https://upcoming.api.symbols.app",
     githubClientId: "Ov23liWF7NvdZ056RV5J",
-    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/7a3ba473cee2025c68513667024316b8",
+    grafanaUrl: "",
     // For grafana tracing
     grafanaAppName: "Symbols Upcoming",
     typesenseCollectionName: "docs",
@@ -111,7 +117,7 @@ const CONFIG = {
     basedProject: "platform-v2-sm",
     basedOrg: "symbols",
     githubClientId: "Ov23ligwZDQVD0VfuWNa",
-    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/7a3ba473cee2025c68513667024316b8",
+    grafanaUrl: "",
     // For grafana tracing
     grafanaAppName: "Symbols Staging",
     typesenseCollectionName: "docs",
@@ -151,6 +157,11 @@ const getConfig = () => {
     const envConfig = { ...CONFIG.common, ...CONFIG[env] };
     const finalConfig = {
       ...envConfig,
+      // Deep-merge feature flags so env-specific overrides don't drop common defaults
+      features: {
+        ...CONFIG.common.features || {},
+        ...CONFIG[env] && CONFIG[env].features || {}
+      },
       socketUrl: process.env.SYMBOLS_APP_SOCKET_URL || envConfig.socketUrl,
       apiUrl: process.env.SYMBOLS_APP_API_URL || envConfig.apiUrl,
       basedEnv: process.env.SYMBOLS_APP_BASED_ENV || envConfig.basedEnv,

package/dist/cjs/index.js

@@ -32,7 +32,6 @@ __export(index_exports, {
   createAuthService: () => import_services3.createAuthService,
   createBranchService: () => import_services3.createBranchService,
   createCollabService: () => import_services3.createCollabService,
-  createCoreService: () => import_services3.createCoreService,
   createDnsService: () => import_services3.createDnsService,
   createFileService: () => import_services3.createFileService,
   createPaymentService: () => import_services3.createPaymentService,
@@ -40,8 +39,10 @@ __export(index_exports, {
   createProjectService: () => import_services3.createProjectService,
   createPullRequestService: () => import_services3.createPullRequestService,
   createSubscriptionService: () => import_services3.createSubscriptionService,
+  createTrackingService: () => import_services3.createTrackingService,
   default: () => index_default,
-  environment: () => import_environment2.default
+  environment: () => import_environment2.default,
+  isLocalhost: () => isLocalhost
 });
 module.exports = __toCommonJS(index_exports);
 var import_services = require("./services/index.js");
@@ -50,6 +51,14 @@ var import_environment = __toESM(require("./config/environment.js"), 1);
 var import_rootEventBus = require("./state/rootEventBus.js");
 var import_services3 = require("./services/index.js");
 var import_environment2 = __toESM(require("./config/environment.js"), 1);
+const isBrowserEnvironment = () => typeof window !== "undefined";
+const isLocalhost = () => {
+  if (!isBrowserEnvironment()) {
+    return false;
+  }
+  const host = window.location && window.location.hostname;
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "" || !host;
+};
 class SDK {
   constructor(options = {}) {
     this._services = /* @__PURE__ */ new Map();
@@ -72,13 +81,6 @@ class SDK {
           options: this._options
         })
       ),
-      this._initService(
-        "core",
-        (0, import_services.createCoreService)({
-          context: this._context,
-          options: this._options
-        })
-      ),
       this._initService(
         "collab",
         (0, import_services.createCollabService)({
@@ -156,6 +158,13 @@ class SDK {
           context: this._context,
           options: this._options
         })
+      ),
+      this._initService(
+        "tracking",
+        (0, import_services.createTrackingService)({
+          context: this._context,
+          options: this._options
+        })
       )
     ]);
     return this;
@@ -173,6 +182,8 @@ class SDK {
     this._services.set(name, service);
   }
   _validateOptions(options) {
+    const onLocalhost = isLocalhost();
+    const hasGrafanaUrl = Boolean(import_environment.default.grafanaUrl);
     const defaults = {
       useNewServices: true,
       // Use new service implementations by default
@@ -180,9 +191,24 @@ class SDK {
       socketUrl: import_environment.default.socketUrl,
       timeout: 3e4,
       retryAttempts: 3,
-      debug: false
+      debug: false,
+      tracking: {
+        // Force-disabled on localhost or when no Grafana URL is configured
+        enabled: onLocalhost ? false : hasGrafanaUrl ? import_environment.default.features.trackingEnabled : false
+      }
+    };
+    const merged = {
+      ...defaults,
+      ...options,
+      tracking: {
+        ...defaults.tracking,
+        ...options.tracking || {}
+      }
     };
-    return { ...defaults, ...options };
+    if (onLocalhost || !hasGrafanaUrl) {
+      merged.tracking.enabled = false;
+    }
+    return merged;
   }
   // Get service instance
   getService(name) {
@@ -193,7 +219,7 @@ class SDK {
   }
   // Update context
   updateContext(newContext) {
-    const { authToken, ...sanitized } = newContext || {};
+    const { ...sanitized } = newContext || {};
     this._context = {
       ...this._context,
       ...sanitized

package/dist/cjs/services/BaseService.js

@@ -88,6 +88,39 @@ class BaseService {
     this._ready = false;
     this._error = error;
   }
+  _getTrackingService() {
+    var _a;
+    const services = (_a = this._context) == null ? void 0 : _a.services;
+    const tracking = services == null ? void 0 : services.tracking;
+    if (!tracking || typeof tracking.trackError !== "function") {
+      return null;
+    }
+    return tracking;
+  }
+  _shouldTrackErrors() {
+    var _a;
+    const name = (_a = this == null ? void 0 : this.constructor) == null ? void 0 : _a.name;
+    return name !== "TrackingService";
+  }
+  _trackServiceError(error, details = {}) {
+    var _a;
+    if (!this._shouldTrackErrors()) {
+      return;
+    }
+    try {
+      const tracking = this._getTrackingService();
+      if (!tracking) {
+        return;
+      }
+      const context = {
+        service: ((_a = this == null ? void 0 : this.constructor) == null ? void 0 : _a.name) || "UnknownService",
+        apiUrl: this._apiUrl || null,
+        ...details
+      };
+      tracking.trackError(error instanceof Error ? error : new Error(String(error)), context);
+    } catch {
+    }
+  }
   _requireAuth() {
     if (!this._context.authToken) {
       throw new Error("Authentication required");
@@ -137,10 +170,23 @@ class BaseService {
           error = await response.json();
         } catch {
         }
+        this._trackServiceError(
+          new Error(error.message || error.error || `HTTP ${response.status}: ${response.statusText}`),
+          {
+            endpoint,
+            methodName: options.methodName,
+            status: response.status,
+            statusText: response.statusText
+          }
+        );
         throw new Error(error.message || error.error || "Request failed", { cause: error });
       }
       return response.status === 204 ? null : response.json();
     } catch (error) {
+      this._trackServiceError(error, {
+        endpoint,
+        methodName: options.methodName
+      });
       throw new Error(`Request failed: ${error.message}`, { cause: error });
     }
   }

package/dist/cjs/services/DnsService.js

@@ -75,7 +75,7 @@ class DnsService extends import_BaseService.BaseService {
       }
       throw new Error(response.message);
     } catch (error) {
-      throw new Error(`Failed to get custom host: ${error.message}`);
+      throw new Error(`Failed to get custom host: ${error.message}`, { cause: error });
     }
   }
   async removeDnsRecord(domain) {
@@ -143,7 +143,8 @@ class DnsService extends import_BaseService.BaseService {
       throw new Error(response.message);
     } catch (error) {
       throw new Error(
-        `Failed to update project custom domains: ${error.message}`
+        `Failed to update project custom domains: ${error.message}`,
+        { cause: error }
       );
     }
   }
@@ -301,7 +302,7 @@ class DnsService extends import_BaseService.BaseService {
         needsVerification: false
       };
     } catch (error) {
-      throw new Error(`Failed to verify domain ownership: ${error.message}`);
+      throw new Error(`Failed to verify domain ownership: ${error.message}`, { cause: error });
     }
   }
   /**
@@ -322,7 +323,7 @@ class DnsService extends import_BaseService.BaseService {
       }
       throw new Error(response.message);
     } catch (error) {
-      throw new Error(`Failed to get project domains: ${error.message}`);
+      throw new Error(`Failed to get project domains: ${error.message}`, { cause: error });
     }
   }
   /**
@@ -346,7 +347,7 @@ class DnsService extends import_BaseService.BaseService {
       }
       throw new Error(response.message);
     } catch (error) {
-      throw new Error(`Failed to remove project custom domain: ${error.message}`);
+      throw new Error(`Failed to remove project custom domain: ${error.message}`, { cause: error });
     }
   }
   /**