@bliplogs/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+type BlipLevel = 'info' | 'warn' | 'error';
+interface BlipMetadata {
+    [key: string]: unknown;
+}
+interface BlipContext {
+    projectId?: string;
+    url?: string;
+    referrer?: string;
+    userAgent?: string;
+}
+interface BlipPayload {
+    event: string;
+    level: BlipLevel;
+    metadata?: BlipMetadata;
+    context: BlipContext;
+    timestamp: string;
+    session_id?: string;
+    timestamp_ms?: number;
+    api_key?: string;
+    anonymize_ip?: boolean;
+}
+interface BlipLogsError {
+    type: 'network' | 'rate_limit' | 'auth' | 'validation' | 'unknown';
+    message: string;
+    statusCode?: number;
+    originalError?: Error;
+}
+/**
+ * Privacy configuration options for GDPR compliance
+ */
+interface BlipPrivacyConfig {
+    /** Anonymize IP address on server (default: false) */
+    anonymizeIp?: boolean;
+    /** Collect page URL (default: true) */
+    collectUrl?: boolean;
+    /** Collect referrer URL (default: true) */
+    collectReferrer?: boolean;
+    /** Collect user agent string (default: true) */
+    collectUserAgent?: boolean;
+    /** Enable session tracking (default: true) */
+    collectSessionId?: boolean;
+}
+interface BlipLogsConfig {
+    apiKey: string;
+    projectId: string;
+    /** Enable debug mode to log errors to console (default: false) */
+    debug?: boolean;
+    /** Callback fired when an error occurs during event tracking */
+    onError?: (error: BlipLogsError) => void;
+    /** Privacy settings for GDPR compliance */
+    privacy?: BlipPrivacyConfig;
+}
+/**
+ * BlipLogs SDK - Zero-dependency event logging client
+ *
+ * @example
+ * ```ts
+ * // Global configuration (recommended for Astro/React apps)
+ * BlipLogs.configure({ apiKey: 'your-api-key', projectId: 'your-project-id' });
+ * BlipLogs.track('button_clicked', { buttonId: 'signup' });
+ *
+ * // Or use instance-based API
+ * const blip = new BlipLogs({ apiKey: 'your-api-key', projectId: 'your-project-id' });
+ * blip.track('error_occurred', { message: 'Failed to load' }, 'error');
+ * ```
+ */
+declare class BlipLogs {
+    private static globalInstance;
+    private static readonly API_ENDPOINT;
+    private apiKey;
+    private projectId;
+    private debug;
+    private onError?;
+    private privacy;
+    constructor(config: BlipLogsConfig);
+    /**
+     * Configure the global BlipLogs instance
+     * Call this once at the start of your application (e.g., in your Astro layout)
+     *
+     * @example
+     * ```ts
+     * // In Astro layout or initialization script
+     * BlipLogs.configure({
+     *   apiKey: import.meta.env.PUBLIC_BLIPLOGS_API_KEY,
+     *   projectId: import.meta.env.PUBLIC_BLIPLOGS_PROJECT_ID
+     * });
+     * ```
+     */
+    static configure(config: BlipLogsConfig): void;
+    /**
+     * Get the global BlipLogs instance
+     * Throws an error if not configured
+     */
+    private static getInstance;
+    /**
+     * Track an event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.track('button_clicked', { buttonId: 'signup' });
+     * ```
+     */
+    static track(event: string, metadata?: BlipMetadata, level?: BlipLevel): boolean;
+    /**
+     * Track an info-level event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.info('page_viewed', { page: '/dashboard' });
+     * ```
+     */
+    static info(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Track a warn-level event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.warn('slow_request', { duration: 5000 });
+     * ```
+     */
+    static warn(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Track an error-level event using the global instance
+     *
+     * @example
+     * ```ts
+     * BlipLogs.error('api_error', { message: 'Failed to fetch' });
+     * ```
+     */
+    static error(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Gets or creates a session ID from sessionStorage
+     * Sessions expire after 30 minutes of inactivity
+     */
+    private getSessionId;
+    /**
+     * Sensitive URL parameters that should be redacted
+     */
+    private static readonly SENSITIVE_PARAMS;
+    /**
+     * Sanitize a URL by removing sensitive query parameters
+     */
+    private sanitizeUrl;
+    /**
+     * Auto-captures browser context information with sensitive data sanitization
+     * Respects privacy configuration settings
+     */
+    private getContext;
+    /**
+     * Track an event with optional metadata and level
+     *
+     * @param event - The event name (e.g., 'signup_modal_opened')
+     * @param metadata - Optional custom data to attach to the event
+     * @param level - Event level: 'info' (default), 'warn', or 'error'
+     * @returns boolean - Whether the event was queued for delivery
+     */
+    track(event: string, metadata?: BlipMetadata, level?: BlipLevel): boolean;
+    /**
+     * Convenience method for info-level events
+     */
+    info(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Convenience method for warn-level events
+     */
+    warn(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Convenience method for error-level events
+     */
+    error(event: string, metadata?: BlipMetadata): boolean;
+    /**
+     * Sends the payload using sendBeacon for speed and reliability
+     * Falls back to fetch if sendBeacon is unavailable or blocked
+     */
+    private send;
+    /**
+     * Handle and report errors
+     */
+    private handleError;
+    /**
+     * Fallback method using fetch API
+     */
+    private sendWithFetch;
+}
+
+export { type BlipContext, type BlipLevel, BlipLogs, type BlipLogsConfig, type BlipLogsError, type BlipMetadata, type BlipPayload, type BlipPrivacyConfig, BlipLogs as default };

package/dist/index.js

@@ -0,0 +1,369 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BlipLogs: () => BlipLogs,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var _BlipLogs = class _BlipLogs {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("BlipLogs: apiKey is required");
+    }
+    if (!config.projectId) {
+      throw new Error("BlipLogs: projectId is required");
+    }
+    this.apiKey = config.apiKey;
+    this.projectId = config.projectId;
+    this.debug = config.debug ?? false;
+    this.onError = config.onError;
+    this.privacy = {
+      anonymizeIp: config.privacy?.anonymizeIp ?? false,
+      collectUrl: config.privacy?.collectUrl ?? true,
+      collectReferrer: config.privacy?.collectReferrer ?? true,
+      collectUserAgent: config.privacy?.collectUserAgent ?? true,
+      collectSessionId: config.privacy?.collectSessionId ?? true
+    };
+  }
+  /**
+   * Configure the global BlipLogs instance
+   * Call this once at the start of your application (e.g., in your Astro layout)
+   * 
+   * @example
+   * ```ts
+   * // In Astro layout or initialization script
+   * BlipLogs.configure({
+   *   apiKey: import.meta.env.PUBLIC_BLIPLOGS_API_KEY,
+   *   projectId: import.meta.env.PUBLIC_BLIPLOGS_PROJECT_ID
+   * });
+   * ```
+   */
+  static configure(config) {
+    _BlipLogs.globalInstance = new _BlipLogs(config);
+  }
+  /**
+   * Get the global BlipLogs instance
+   * Throws an error if not configured
+   */
+  static getInstance() {
+    if (!_BlipLogs.globalInstance) {
+      throw new Error("BlipLogs: Global instance not configured. Call BlipLogs.configure() first.");
+    }
+    return _BlipLogs.globalInstance;
+  }
+  /**
+   * Track an event using the global instance
+   * 
+   * @example
+   * ```ts
+   * BlipLogs.track('button_clicked', { buttonId: 'signup' });
+   * ```
+   */
+  static track(event, metadata, level = "info") {
+    return _BlipLogs.getInstance().track(event, metadata, level);
+  }
+  /**
+   * Track an info-level event using the global instance
+   * 
+   * @example
+   * ```ts
+   * BlipLogs.info('page_viewed', { page: '/dashboard' });
+   * ```
+   */
+  static info(event, metadata) {
+    return _BlipLogs.getInstance().info(event, metadata);
+  }
+  /**
+   * Track a warn-level event using the global instance
+   * 
+   * @example
+   * ```ts
+   * BlipLogs.warn('slow_request', { duration: 5000 });
+   * ```
+   */
+  static warn(event, metadata) {
+    return _BlipLogs.getInstance().warn(event, metadata);
+  }
+  /**
+   * Track an error-level event using the global instance
+   * 
+   * @example
+   * ```ts
+   * BlipLogs.error('api_error', { message: 'Failed to fetch' });
+   * ```
+   */
+  static error(event, metadata) {
+    return _BlipLogs.getInstance().error(event, metadata);
+  }
+  /**
+   * Gets or creates a session ID from sessionStorage
+   * Sessions expire after 30 minutes of inactivity
+   */
+  getSessionId() {
+    if (typeof window === "undefined" || typeof sessionStorage === "undefined") {
+      return void 0;
+    }
+    const SESSION_TIMEOUT = 30 * 60 * 1e3;
+    const STORAGE_KEY_ID = "blip_session_id";
+    const STORAGE_KEY_TS = "blip_session_ts";
+    try {
+      let sessionId = sessionStorage.getItem(STORAGE_KEY_ID);
+      const lastActivityStr = sessionStorage.getItem(STORAGE_KEY_TS);
+      const lastActivity = lastActivityStr ? parseInt(lastActivityStr, 10) : null;
+      const now = Date.now();
+      if (!sessionId || !lastActivity || now - lastActivity > SESSION_TIMEOUT) {
+        sessionId = crypto.randomUUID();
+        sessionStorage.setItem(STORAGE_KEY_ID, sessionId);
+      }
+      sessionStorage.setItem(STORAGE_KEY_TS, now.toString());
+      return sessionId;
+    } catch (error) {
+      return void 0;
+    }
+  }
+  /**
+   * Sanitize a URL by removing sensitive query parameters
+   */
+  sanitizeUrl(url) {
+    if (!url) return void 0;
+    try {
+      const urlObj = new URL(url);
+      const params = urlObj.searchParams;
+      const sensitiveSet = new Set(_BlipLogs.SENSITIVE_PARAMS.map((p) => p.toLowerCase()));
+      const paramsToRedact = [];
+      params.forEach((_, key) => {
+        if (sensitiveSet.has(key.toLowerCase())) {
+          paramsToRedact.push(key);
+        }
+      });
+      for (const key of paramsToRedact) {
+        params.set(key, "[REDACTED]");
+      }
+      return urlObj.toString();
+    } catch {
+      const queryIndex = url.indexOf("?");
+      if (queryIndex !== -1) {
+        return url.substring(0, queryIndex) + "?[QUERY_REDACTED]";
+      }
+      return url;
+    }
+  }
+  /**
+   * Auto-captures browser context information with sensitive data sanitization
+   * Respects privacy configuration settings
+   */
+  getContext() {
+    const baseContext = {
+      projectId: this.projectId
+    };
+    if (typeof window === "undefined") {
+      return baseContext;
+    }
+    return {
+      ...baseContext,
+      url: this.privacy.collectUrl ? this.sanitizeUrl(window.location?.href) : void 0,
+      referrer: this.privacy.collectReferrer ? this.sanitizeUrl(document.referrer) || void 0 : void 0,
+      userAgent: this.privacy.collectUserAgent ? navigator.userAgent : void 0
+    };
+  }
+  /**
+   * Track an event with optional metadata and level
+   *
+   * @param event - The event name (e.g., 'signup_modal_opened')
+   * @param metadata - Optional custom data to attach to the event
+   * @param level - Event level: 'info' (default), 'warn', or 'error'
+   * @returns boolean - Whether the event was queued for delivery
+   */
+  track(event, metadata, level = "info") {
+    if (!event) {
+      console.warn("BlipLogs: event name is required");
+      return false;
+    }
+    const now = Date.now();
+    const sessionId = this.privacy.collectSessionId ? this.getSessionId() : void 0;
+    const payload = {
+      event,
+      level,
+      metadata,
+      context: this.getContext(),
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      // Keep for backward compatibility
+      session_id: sessionId,
+      timestamp_ms: now,
+      // Numeric timestamp in milliseconds
+      anonymize_ip: this.privacy.anonymizeIp || void 0
+      // Only include if true
+    };
+    return this.send(payload);
+  }
+  /**
+   * Convenience method for info-level events
+   */
+  info(event, metadata) {
+    return this.track(event, metadata, "info");
+  }
+  /**
+   * Convenience method for warn-level events
+   */
+  warn(event, metadata) {
+    return this.track(event, metadata, "warn");
+  }
+  /**
+   * Convenience method for error-level events
+   */
+  error(event, metadata) {
+    return this.track(event, metadata, "error");
+  }
+  /**
+   * Sends the payload using sendBeacon for speed and reliability
+   * Falls back to fetch if sendBeacon is unavailable or blocked
+   */
+  send(payload) {
+    const payloadWithKey = {
+      ...payload,
+      api_key: this.apiKey
+    };
+    const body = JSON.stringify(payloadWithKey);
+    if (typeof navigator !== "undefined" && navigator.sendBeacon) {
+      try {
+        const blob = new Blob([body], { type: "application/json" });
+        const sent = navigator.sendBeacon(_BlipLogs.API_ENDPOINT, blob);
+        if (!sent) {
+          return this.sendWithFetch(body);
+        }
+        return true;
+      } catch (error) {
+        return this.sendWithFetch(body);
+      }
+    }
+    return this.sendWithFetch(body);
+  }
+  /**
+   * Handle and report errors
+   */
+  handleError(error) {
+    if (this.debug) {
+      console.error(`BlipLogs Error [${error.type}]:`, error.message, error);
+    }
+    if (this.onError) {
+      try {
+        this.onError(error);
+      } catch (callbackError) {
+        if (this.debug) {
+          console.error("BlipLogs: Error in onError callback:", callbackError);
+        }
+      }
+    }
+  }
+  /**
+   * Fallback method using fetch API
+   */
+  sendWithFetch(body) {
+    if (typeof fetch !== "undefined") {
+      fetch(_BlipLogs.API_ENDPOINT, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.apiKey
+        },
+        body,
+        keepalive: true,
+        credentials: "omit"
+      }).then((response) => {
+        if (!response.ok) {
+          let errorType = "unknown";
+          let message = `HTTP ${response.status}`;
+          if (response.status === 429) {
+            errorType = "rate_limit";
+            message = "Monthly event limit exceeded. Upgrade your plan to continue.";
+          } else if (response.status === 401) {
+            errorType = "auth";
+            message = "Invalid API key";
+          } else if (response.status === 400) {
+            errorType = "validation";
+            message = "Invalid request payload";
+          }
+          this.handleError({
+            type: errorType,
+            message,
+            statusCode: response.status
+          });
+        }
+      }).catch((err) => {
+        this.handleError({
+          type: "network",
+          message: err?.message || "Network request failed",
+          originalError: err instanceof Error ? err : void 0
+        });
+      });
+      return true;
+    }
+    this.handleError({
+      type: "unknown",
+      message: "No suitable transport available (fetch not defined)"
+    });
+    return false;
+  }
+};
+_BlipLogs.globalInstance = null;
+_BlipLogs.API_ENDPOINT = "https://api.bliplogs.co.uk";
+/**
+ * Sensitive URL parameters that should be redacted
+ */
+_BlipLogs.SENSITIVE_PARAMS = [
+  "token",
+  "access_token",
+  "refresh_token",
+  "id_token",
+  "apikey",
+  "api_key",
+  "api-key",
+  "key",
+  "password",
+  "pwd",
+  "pass",
+  "secret",
+  "auth",
+  "authorization",
+  "bearer",
+  "session",
+  "sessionid",
+  "session_id",
+  "code",
+  "state",
+  "nonce",
+  // OAuth params
+  "email",
+  "phone",
+  "ssn",
+  // PII
+  "credit_card",
+  "cc",
+  "cvv",
+  "card"
+];
+var BlipLogs = _BlipLogs;
+var index_default = BlipLogs;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BlipLogs
+});