@symbo.ls/sdk 3.2.3 → 3.2.6

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
@@ -46,18 +48,38 @@ const CONFIG = {
     // For based api
     basedOrg: "symbols",
     // For based api
-    githubClientId: "Ov23liHxyWFBxS8f1gnF",
+    githubClientId: "Ov23liAFrsR0StbAO6PO",
     // For github api
+    grafanaUrl: "",
+    // For grafana tracing
+    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",
+    typesenseHost: "localhost",
+    typesensePort: "8108",
+    typesenseProtocol: "http"
   },
   development: {
     socketUrl: "https://dev.api.symbols.app",
     apiUrl: "https://dev.api.symbols.app",
-    githubClientId: "Ov23liHxyWFBxS8f1gnF"
+    githubClientId: "Ov23liHxyWFBxS8f1gnF",
+    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/7a3ba473cee2025c68513667024316b8",
+    // For grafana tracing
+    grafanaAppName: "Symbols Dev",
+    typesenseCollectionName: "docs",
+    typesenseApiKey: "awmcVpbWqZi9IUgmvslp1C5LKDU8tMjA",
+    typesenseHost: "tl2qpnwxev4cjm36p-1.a1.typesense.net",
+    typesensePort: "443",
+    typesenseProtocol: "https"
   },
   testing: {
     socketUrl: "https://test.api.symbols.app",
@@ -65,12 +87,28 @@ const CONFIG = {
     basedEnv: "testing",
     basedProject: "platform-v2-sm",
     basedOrg: "symbols",
-    githubClientId: "Ov23liHxyWFBxS8f1gnF"
+    githubClientId: "Ov23liHxyWFBxS8f1gnF",
+    grafanaUrl: "",
+    // For grafana tracing
+    grafanaAppName: "Symbols Test",
+    typesenseCollectionName: "docs",
+    typesenseApiKey: "awmcVpbWqZi9IUgmvslp1C5LKDU8tMjA",
+    typesenseHost: "tl2qpnwxev4cjm36p-1.a1.typesense.net",
+    typesensePort: "443",
+    typesenseProtocol: "https"
   },
   upcoming: {
     socketUrl: "https://upcoming.api.symbols.app",
     apiUrl: "https://upcoming.api.symbols.app",
-    githubClientId: "Ov23liWF7NvdZ056RV5J"
+    githubClientId: "Ov23liWF7NvdZ056RV5J",
+    grafanaUrl: "",
+    // For grafana tracing
+    grafanaAppName: "Symbols Upcoming",
+    typesenseCollectionName: "docs",
+    typesenseApiKey: "awmcVpbWqZi9IUgmvslp1C5LKDU8tMjA",
+    typesenseHost: "tl2qpnwxev4cjm36p-1.a1.typesense.net",
+    typesensePort: "443",
+    typesenseProtocol: "https"
   },
   staging: {
     socketUrl: "https://staging.api.symbols.app",
@@ -78,7 +116,31 @@ const CONFIG = {
     basedEnv: "staging",
     basedProject: "platform-v2-sm",
     basedOrg: "symbols",
-    githubClientId: "Ov23ligwZDQVD0VfuWNa"
+    githubClientId: "Ov23ligwZDQVD0VfuWNa",
+    grafanaUrl: "",
+    // For grafana tracing
+    grafanaAppName: "Symbols Staging",
+    typesenseCollectionName: "docs",
+    typesenseApiKey: "awmcVpbWqZi9IUgmvslp1C5LKDU8tMjA",
+    typesenseHost: "tl2qpnwxev4cjm36p-1.a1.typesense.net",
+    typesensePort: "443",
+    typesenseProtocol: "https"
+  },
+  preview: {
+    socketUrl: "https://api.symbols.app",
+    apiUrl: "https://api.symbols.app",
+    basedEnv: "production",
+    basedProject: "platform-v2-sm",
+    basedOrg: "symbols",
+    githubClientId: "Ov23liFAlOEIXtX3dBtR",
+    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/5c1089f3c3eea4ec5658e05c3f53baae",
+    // For grafana tracing
+    grafanaAppName: "Symbols Preview",
+    typesenseCollectionName: "docs",
+    typesenseApiKey: "awmcVpbWqZi9IUgmvslp1C5LKDU8tMjA",
+    typesenseHost: "tl2qpnwxev4cjm36p-1.a1.typesense.net",
+    typesensePort: "443",
+    typesenseProtocol: "https"
   },
   production: {
     socketUrl: "https://api.symbols.app",
@@ -86,7 +148,15 @@ const CONFIG = {
     basedEnv: "production",
     basedProject: "platform-v2-sm",
     basedOrg: "symbols",
-    githubClientId: "Ov23liFAlOEIXtX3dBtR"
+    githubClientId: "Ov23liFAlOEIXtX3dBtR",
+    grafanaUrl: "https://faro-collector-prod-us-east-0.grafana.net/collect/5c1089f3c3eea4ec5658e05c3f53baae",
+    // For grafana tracing
+    grafanaAppName: "Symbols",
+    typesenseCollectionName: "docs",
+    typesenseApiKey: "awmcVpbWqZi9IUgmvslp1C5LKDU8tMjA",
+    typesenseHost: "tl2qpnwxev4cjm36p-1.a1.typesense.net",
+    typesensePort: "443",
+    typesenseProtocol: "https"
   }
 };
 const getEnvironment = () => {
@@ -103,15 +173,27 @@ 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,
       basedProject: process.env.SYMBOLS_APP_BASED_PROJECT || envConfig.basedProject,
       basedOrg: process.env.SYMBOLS_APP_BASED_ORG || envConfig.basedOrg,
       githubClientId: process.env.SYMBOLS_APP_GITHUB_CLIENT_ID || envConfig.githubClientId,
+      grafanaUrl: process.env.SYMBOLS_APP_GRAFANA_URL || envConfig.grafanaUrl,
+      typesenseCollectionName: process.env.TYPESENSE_COLLECTION_NAME || envConfig.typesenseCollectionName,
+      typesenseApiKey: process.env.TYPESENSE_API_KEY || envConfig.typesenseApiKey,
+      typesenseHost: process.env.TYPESENSE_HOST || envConfig.typesenseHost,
+      typesensePort: process.env.TYPESENSE_PORT || envConfig.typesensePort,
+      typesenseProtocol: process.env.TYPESENSE_PROTOCOL || envConfig.typesenseProtocol,
       isDevelopment: (0, import_utils.isDevelopment)(env),
       isTesting: env === "testing",
       isStaging: env === "staging",
+      isPreview: env === "preview",
       isProduction: env === "production"
       // Store all environment variables for potential future use
     };
@@ -128,11 +210,13 @@ const getConfig = () => {
       );
     }
     if (finalConfig.isDevelopment) {
-      console.log(
+      console.warn(
         "environment in SDK:",
         env || process.env.NODE_ENV || process.env.NODE_ENV
       );
       console.log(finalConfig);
+    } else if (global.window) {
+      global.window.finalConfig = finalConfig;
     }
     return finalConfig;
   } catch (error) {

package/dist/cjs/index.js

@@ -28,23 +28,48 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SDK: () => SDK,
+  createAdminService: () => import_services3.createAdminService,
   createAuthService: () => import_services3.createAuthService,
+  createBranchService: () => import_services3.createBranchService,
   createCollabService: () => import_services3.createCollabService,
-  createCoreService: () => import_services3.createCoreService,
+  createDnsService: () => import_services3.createDnsService,
+  createFeatureFlagService: () => import_services3.createFeatureFlagService,
+  createFileService: () => import_services3.createFileService,
+  createIntegrationService: () => import_services3.createIntegrationService,
+  createMetricsService: () => import_services3.createMetricsService,
+  createPaymentService: () => import_services3.createPaymentService,
+  createPlanService: () => import_services3.createPlanService,
+  createProjectService: () => import_services3.createProjectService,
+  createPullRequestService: () => import_services3.createPullRequestService,
+  createSubscriptionService: () => import_services3.createSubscriptionService,
+  createTrackingService: () => import_services3.createTrackingService,
+  createWaitlistService: () => import_services3.createWaitlistService,
   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");
 var import_services2 = require("./utils/services.js");
 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();
     this._context = {};
     this._options = this._validateOptions(options);
+    this.environment = import_environment.default;
+    this.rootBus = import_rootEventBus.rootBus;
     this._createServiceProxies();
   }
   // Initialize SDK with context
@@ -62,15 +87,114 @@ class SDK {
         })
       ),
       this._initService(
-        "core",
-        (0, import_services.createCoreService)({
+        "collab",
+        (0, import_services.createCollabService)({
           context: this._context,
           options: this._options
         })
       ),
+      // Initialize new modular services
       this._initService(
-        "collab",
-        (0, import_services.createCollabService)({
+        "project",
+        (0, import_services.createProjectService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "plan",
+        (0, import_services.createPlanService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "subscription",
+        (0, import_services.createSubscriptionService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "file",
+        (0, import_services.createFileService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "payment",
+        (0, import_services.createPaymentService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "dns",
+        (0, import_services.createDnsService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "branch",
+        (0, import_services.createBranchService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "pullRequest",
+        (0, import_services.createPullRequestService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "admin",
+        (0, import_services.createAdminService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "screenshot",
+        (0, import_services.createScreenshotService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "tracking",
+        (0, import_services.createTrackingService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "waitlist",
+        (0, import_services.createWaitlistService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "metrics",
+        (0, import_services.createMetricsService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "integration",
+        (0, import_services.createIntegrationService)({
+          context: this._context,
+          options: this._options
+        })
+      ),
+      this._initService(
+        "featureFlag",
+        (0, import_services.createFeatureFlagService)({
           context: this._context,
           options: this._options
         })
@@ -91,6 +215,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
@@ -98,9 +224,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
+      }
     };
-    return { ...defaults, ...options };
+    const merged = {
+      ...defaults,
+      ...options,
+      tracking: {
+        ...defaults.tracking,
+        ...options.tracking || {}
+      }
+    };
+    if (onLocalhost || !hasGrafanaUrl) {
+      merged.tracking.enabled = false;
+    }
+    return merged;
   }
   // Get service instance
   getService(name) {
@@ -111,9 +252,10 @@ class SDK {
   }
   // Update context
   updateContext(newContext) {
+    const { ...sanitized } = newContext || {};
     this._context = {
       ...this._context,
-      ...newContext
+      ...sanitized
     };
     for (const service of this._services.values()) {
       service.updateContext(this._context);
@@ -122,9 +264,7 @@ class SDK {
   // Check if SDK is ready
   isReady() {
     const sdkServices = Array.from(this._services.values());
-    return sdkServices.length > 0 && sdkServices.every(
-      (service) => service.isReady()
-    );
+    return sdkServices.length > 0 && sdkServices.every((service) => service.isReady());
   }
   // Get SDK status
   getStatus() {