@bbearai/core 0.5.4 → 0.6.0

package/dist/index.d.mts

@@ -132,12 +132,39 @@ interface HostUserInfo {
     name?: string;
 }
 interface BugBearConfig {
-    /** Your BugBear project ID */
-    projectId: string;
-    /** Supabase URL for the BugBear backend */
-    supabaseUrl: string;
-    /** Supabase anon key for the BugBear backend */
-    supabaseAnonKey: string;
+    /**
+     * BugBear API key (recommended).
+     * When provided, the SDK resolves projectId, supabaseUrl, and supabaseAnonKey
+     * automatically from the BugBear API. This is the simplest config path —
+     * only one env var needed.
+     *
+     * Get yours at https://app.bugbear.ai/settings/projects
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the BugBear dashboard API.
+     * Defaults to 'https://app.bugbear.ai'. Only change this for
+     * self-hosted or local development environments.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Your BugBear project ID.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    projectId?: string;
+    /**
+     * Supabase URL for the BugBear backend.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    supabaseUrl?: string;
+    /**
+     * Supabase anon key for the BugBear backend.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    supabaseAnonKey?: string;
     /** Enable voice input */
     enableVoice?: boolean;
     /** Enable screenshot capture */
@@ -778,7 +805,38 @@ declare class BugBearClient {
     private _queue;
     /** Active Realtime channel references for cleanup. */
     private realtimeChannels;
+    /**
+     * Resolves when the client is ready to make requests.
+     * For the explicit config path (supabaseUrl + supabaseAnonKey), this is immediate.
+     * For the apiKey path, this resolves after credentials are fetched from /api/v1/config.
+     */
+    private pendingInit;
+    /** Whether the client has been successfully initialized. */
+    private initialized;
+    /** Initialization error, if any. */
+    private initError;
     constructor(config: BugBearConfig);
+    /** Whether the client is ready for requests. */
+    get isReady(): boolean;
+    /** Wait until the client is ready. Throws if initialization failed. */
+    ready(): Promise<void>;
+    /**
+     * Resolve Supabase credentials from a BugBear API key.
+     * Checks localStorage cache first, falls back to /api/v1/config.
+     */
+    private resolveFromApiKey;
+    /** Apply resolved credentials and create the Supabase client. */
+    private applyResolvedConfig;
+    /** Initialize offline queue if configured. Shared by both init paths. */
+    private initOfflineQueue;
+    /** Read cached config from localStorage if available and not expired. */
+    private readConfigCache;
+    /** Write resolved config to localStorage cache. */
+    private writeConfigCache;
+    /** Simple string hash for cache keys — avoids storing raw API keys. */
+    private hashKey;
+    /** Ensure the client is initialized before making requests. */
+    private ensureReady;
     /**
      * Access the offline queue (if enabled).
      * Use this to check queue.count, subscribe to changes, or trigger flush.
@@ -1173,6 +1231,7 @@ declare class ContextCaptureManager {
     private navigationHistory;
     private originalConsole;
     private originalFetch?;
+    private fetchHost;
     private originalPushState?;
     private originalReplaceState?;
     private popstateHandler?;

package/dist/index.d.ts

@@ -132,12 +132,39 @@ interface HostUserInfo {
     name?: string;
 }
 interface BugBearConfig {
-    /** Your BugBear project ID */
-    projectId: string;
-    /** Supabase URL for the BugBear backend */
-    supabaseUrl: string;
-    /** Supabase anon key for the BugBear backend */
-    supabaseAnonKey: string;
+    /**
+     * BugBear API key (recommended).
+     * When provided, the SDK resolves projectId, supabaseUrl, and supabaseAnonKey
+     * automatically from the BugBear API. This is the simplest config path —
+     * only one env var needed.
+     *
+     * Get yours at https://app.bugbear.ai/settings/projects
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the BugBear dashboard API.
+     * Defaults to 'https://app.bugbear.ai'. Only change this for
+     * self-hosted or local development environments.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Your BugBear project ID.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    projectId?: string;
+    /**
+     * Supabase URL for the BugBear backend.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    supabaseUrl?: string;
+    /**
+     * Supabase anon key for the BugBear backend.
+     * Required when using the explicit config path (without apiKey).
+     * Automatically resolved when apiKey is provided.
+     */
+    supabaseAnonKey?: string;
     /** Enable voice input */
     enableVoice?: boolean;
     /** Enable screenshot capture */
@@ -778,7 +805,38 @@ declare class BugBearClient {
     private _queue;
     /** Active Realtime channel references for cleanup. */
     private realtimeChannels;
+    /**
+     * Resolves when the client is ready to make requests.
+     * For the explicit config path (supabaseUrl + supabaseAnonKey), this is immediate.
+     * For the apiKey path, this resolves after credentials are fetched from /api/v1/config.
+     */
+    private pendingInit;
+    /** Whether the client has been successfully initialized. */
+    private initialized;
+    /** Initialization error, if any. */
+    private initError;
     constructor(config: BugBearConfig);
+    /** Whether the client is ready for requests. */
+    get isReady(): boolean;
+    /** Wait until the client is ready. Throws if initialization failed. */
+    ready(): Promise<void>;
+    /**
+     * Resolve Supabase credentials from a BugBear API key.
+     * Checks localStorage cache first, falls back to /api/v1/config.
+     */
+    private resolveFromApiKey;
+    /** Apply resolved credentials and create the Supabase client. */
+    private applyResolvedConfig;
+    /** Initialize offline queue if configured. Shared by both init paths. */
+    private initOfflineQueue;
+    /** Read cached config from localStorage if available and not expired. */
+    private readConfigCache;
+    /** Write resolved config to localStorage cache. */
+    private writeConfigCache;
+    /** Simple string hash for cache keys — avoids storing raw API keys. */
+    private hashKey;
+    /** Ensure the client is initialized before making requests. */
+    private ensureReady;
     /**
      * Access the offline queue (if enabled).
      * Use this to check queue.count, subscribe to changes, or trigger flush.
@@ -1173,6 +1231,7 @@ declare class ContextCaptureManager {
     private navigationHistory;
     private originalConsole;
     private originalFetch?;
+    private fetchHost;
     private originalPushState?;
     private originalReplaceState?;
     private popstateHandler?;

package/dist/index.js

@@ -52,6 +52,7 @@ var ContextCaptureManager = class {
     this.networkRequests = [];
     this.navigationHistory = [];
     this.originalConsole = {};
+    this.fetchHost = null;
     this.isCapturing = false;
   }
   /**
@@ -74,8 +75,9 @@ var ContextCaptureManager = class {
     if (this.originalConsole.warn) console.warn = this.originalConsole.warn;
     if (this.originalConsole.error) console.error = this.originalConsole.error;
     if (this.originalConsole.info) console.info = this.originalConsole.info;
-    if (this.originalFetch && typeof window !== "undefined") {
-      window.fetch = this.originalFetch;
+    if (this.originalFetch && this.fetchHost) {
+      this.fetchHost.fetch = this.originalFetch;
+      this.fetchHost = null;
     }
     if (typeof window !== "undefined" && typeof history !== "undefined") {
       if (this.originalPushState) {
@@ -184,15 +186,19 @@ var ContextCaptureManager = class {
     });
   }
   captureFetch() {
-    if (typeof window === "undefined" || typeof fetch === "undefined" || typeof document === "undefined") return;
-    this.originalFetch = window.fetch;
+    if (typeof fetch === "undefined") return;
+    const host = typeof window !== "undefined" && typeof window.fetch === "function" ? window : typeof globalThis !== "undefined" && typeof globalThis.fetch === "function" ? globalThis : null;
+    if (!host) return;
+    const canCloneResponse = typeof document !== "undefined";
+    this.fetchHost = host;
+    this.originalFetch = host.fetch;
     const self = this;
-    window.fetch = async function(input, init) {
+    host.fetch = async function(input, init) {
       const startTime = Date.now();
       const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
       const method = init?.method || "GET";
       try {
-        const response = await self.originalFetch.call(window, input, init);
+        const response = await self.originalFetch.call(host, input, init);
         const requestEntry = {
           method,
           url: url.slice(0, 200),
@@ -201,7 +207,7 @@ var ContextCaptureManager = class {
           duration: Date.now() - startTime,
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         };
-        if (response.status >= 400) {
+        if (canCloneResponse && response.status >= 400) {
           try {
             const cloned = response.clone();
             const body = await cloned.text();
@@ -449,6 +455,9 @@ var formatPgError = (e) => {
   const { message, code, details, hint } = e;
   return { message, code, details, hint };
 };
+var DEFAULT_API_BASE_URL = "https://app.bugbear.ai";
+var CONFIG_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var CONFIG_CACHE_PREFIX = "bugbear_config_";
 var BugBearClient = class {
   constructor(config) {
     this.navigationHistory = [];
@@ -458,23 +467,133 @@ var BugBearClient = class {
     /** Active Realtime channel references for cleanup. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this.realtimeChannels = [];
-    if (!config.supabaseUrl) {
-      throw new Error("BugBear: supabaseUrl is required. Get it from your BugBear project settings.");
-    }
-    if (!config.supabaseAnonKey) {
-      throw new Error("BugBear: supabaseAnonKey is required. Get it from your BugBear project settings.");
-    }
+    /** Whether the client has been successfully initialized. */
+    this.initialized = false;
+    /** Initialization error, if any. */
+    this.initError = null;
     this.config = config;
-    this.supabase = (0, import_supabase_js.createClient)(config.supabaseUrl, config.supabaseAnonKey);
-    if (config.offlineQueue?.enabled) {
+    if (config.apiKey) {
+      this.pendingInit = this.resolveFromApiKey(config.apiKey);
+    } else if (config.supabaseUrl && config.supabaseAnonKey) {
+      if (!config.projectId) {
+        throw new Error(
+          "BugBear: projectId is required when using explicit Supabase credentials. Tip: Use apiKey instead for simpler setup \u2014 it resolves everything automatically."
+        );
+      }
+      this.supabase = (0, import_supabase_js.createClient)(config.supabaseUrl, config.supabaseAnonKey);
+      this.initialized = true;
+      this.pendingInit = Promise.resolve();
+      this.initOfflineQueue();
+    } else {
+      throw new Error(
+        "BugBear: Missing configuration. Provide either:\n  \u2022 apiKey (recommended) \u2014 resolves everything automatically\n  \u2022 projectId + supabaseUrl + supabaseAnonKey \u2014 explicit credentials\n\nGet your API key at https://app.bugbear.ai/settings/projects"
+      );
+    }
+  }
+  /** Whether the client is ready for requests. */
+  get isReady() {
+    return this.initialized;
+  }
+  /** Wait until the client is ready. Throws if initialization failed. */
+  async ready() {
+    await this.pendingInit;
+    if (this.initError) throw this.initError;
+  }
+  /**
+   * Resolve Supabase credentials from a BugBear API key.
+   * Checks localStorage cache first, falls back to /api/v1/config.
+   */
+  async resolveFromApiKey(apiKey) {
+    try {
+      const cached = this.readConfigCache(apiKey);
+      if (cached) {
+        this.applyResolvedConfig(cached);
+        return;
+      }
+      const baseUrl = (this.config.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, "");
+      const response = await fetch(`${baseUrl}/api/v1/config`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({}));
+        const message = body.error || `HTTP ${response.status}`;
+        throw new Error(
+          `BugBear: Invalid API key \u2014 ${message}. Get yours at https://app.bugbear.ai/settings/projects`
+        );
+      }
+      const data = await response.json();
+      this.writeConfigCache(apiKey, data);
+      this.applyResolvedConfig(data);
+    } catch (err) {
+      this.initError = err instanceof Error ? err : new Error(String(err));
+      this.config.onError?.(this.initError, { context: "apikey_resolution_failed" });
+      throw this.initError;
+    }
+  }
+  /** Apply resolved credentials and create the Supabase client. */
+  applyResolvedConfig(resolved) {
+    this.config = {
+      ...this.config,
+      projectId: resolved.projectId,
+      supabaseUrl: resolved.supabaseUrl,
+      supabaseAnonKey: resolved.supabaseAnonKey
+    };
+    this.supabase = (0, import_supabase_js.createClient)(resolved.supabaseUrl, resolved.supabaseAnonKey);
+    this.initialized = true;
+    this.initOfflineQueue();
+  }
+  /** Initialize offline queue if configured. Shared by both init paths. */
+  initOfflineQueue() {
+    if (this.config.offlineQueue?.enabled) {
       this._queue = new OfflineQueue({
         enabled: true,
-        maxItems: config.offlineQueue.maxItems,
-        maxRetries: config.offlineQueue.maxRetries
+        maxItems: this.config.offlineQueue.maxItems,
+        maxRetries: this.config.offlineQueue.maxRetries
       });
       this.registerQueueHandlers();
     }
   }
+  /** Read cached config from localStorage if available and not expired. */
+  readConfigCache(apiKey) {
+    if (typeof localStorage === "undefined") return null;
+    try {
+      const key = CONFIG_CACHE_PREFIX + this.hashKey(apiKey);
+      const raw = localStorage.getItem(key);
+      if (!raw) return null;
+      const cached = JSON.parse(raw);
+      if (Date.now() - cached.cachedAt > CONFIG_CACHE_TTL_MS) {
+        localStorage.removeItem(key);
+        return null;
+      }
+      return cached;
+    } catch {
+      return null;
+    }
+  }
+  /** Write resolved config to localStorage cache. */
+  writeConfigCache(apiKey, data) {
+    if (typeof localStorage === "undefined") return;
+    try {
+      const key = CONFIG_CACHE_PREFIX + this.hashKey(apiKey);
+      const cached = { ...data, cachedAt: Date.now() };
+      localStorage.setItem(key, JSON.stringify(cached));
+    } catch {
+    }
+  }
+  /** Simple string hash for cache keys — avoids storing raw API keys. */
+  hashKey(apiKey) {
+    let hash = 0;
+    for (let i = 0; i < apiKey.length; i++) {
+      hash = (hash << 5) - hash + apiKey.charCodeAt(i) | 0;
+    }
+    return hash.toString(36);
+  }
+  /** Ensure the client is initialized before making requests. */
+  async ensureReady() {
+    if (this.initialized) return;
+    await this.pendingInit;
+    if (this.initError) throw this.initError;
+  }
   // ── Offline Queue ─────────────────────────────────────────
   /**
    * Access the offline queue (if enabled).
@@ -630,6 +749,7 @@ var BugBearClient = class {
    * Get current user info from host app or BugBear's own auth
    */
   async getCurrentUserInfo() {
+    await this.ensureReady();
     if (this.config.getCurrentUser) {
       return await this.config.getCurrentUser();
     }
@@ -849,6 +969,7 @@ var BugBearClient = class {
    */
   async getAssignment(assignmentId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("test_assignments").select(`
           id,
           status,
@@ -920,6 +1041,7 @@ var BugBearClient = class {
    */
   async updateAssignmentStatus(assignmentId, status, options) {
     try {
+      await this.ensureReady();
       const { data: currentAssignment, error: fetchError } = await this.supabase.from("test_assignments").select("status, started_at").eq("id", assignmentId).single();
       if (fetchError || !currentAssignment) {
         console.error("BugBear: Assignment not found", {
@@ -1006,6 +1128,7 @@ var BugBearClient = class {
    */
   async reopenAssignment(assignmentId) {
     try {
+      await this.ensureReady();
       const { data: current, error: fetchError } = await this.supabase.from("test_assignments").select("status").eq("id", assignmentId).single();
       if (fetchError || !current) {
         return { success: false, error: "Assignment not found" };
@@ -1045,6 +1168,7 @@ var BugBearClient = class {
       actualNotes = notes;
     }
     try {
+      await this.ensureReady();
       const updateData = {
         status: "skipped",
         skip_reason: actualReason,
@@ -1214,6 +1338,7 @@ var BugBearClient = class {
    */
   async getTesterInfo() {
     try {
+      await this.ensureReady();
       const userInfo = await this.getCurrentUserInfo();
       if (!userInfo?.email) return null;
       if (!this.isValidEmail(userInfo.email)) {
@@ -1505,6 +1630,7 @@ var BugBearClient = class {
    */
   async isQAEnabled() {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("check_qa_enabled", {
         p_project_id: this.config.projectId
       });
@@ -1536,6 +1662,7 @@ var BugBearClient = class {
    */
   async uploadScreenshot(file, filename, bucket = "screenshots") {
     try {
+      await this.ensureReady();
       const contentType = file.type || "image/png";
       const ext = contentType.includes("png") ? "png" : "jpg";
       const name = filename || `screenshot-${Date.now()}.${ext}`;
@@ -1576,6 +1703,7 @@ var BugBearClient = class {
    */
   async uploadImageFromUri(uri, filename, bucket = "screenshots") {
     try {
+      await this.ensureReady();
       const response = await fetch(uri);
       const blob = await response.blob();
       const contentType = blob.type || "image/jpeg";
@@ -1670,6 +1798,7 @@ var BugBearClient = class {
    */
   async getFixRequests(options) {
     try {
+      await this.ensureReady();
       let query = this.supabase.from("fix_requests").select("*").eq("project_id", this.config.projectId).order("created_at", { ascending: false }).limit(options?.limit || 20);
       if (options?.status) {
         query = query.eq("status", options.status);
@@ -1741,6 +1870,7 @@ var BugBearClient = class {
    */
   async getThreadMessages(threadId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("discussion_messages").select(`
           id,
           thread_id,
@@ -1943,6 +2073,7 @@ var BugBearClient = class {
    */
   async endSession(sessionId, options = {}) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("end_qa_session", {
         p_session_id: sessionId,
         p_notes: options.notes || null,
@@ -1980,6 +2111,7 @@ var BugBearClient = class {
    */
   async getSession(sessionId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("qa_sessions").select("*").eq("id", sessionId).single();
       if (error || !data) return null;
       return this.transformSession(data);
@@ -2011,6 +2143,7 @@ var BugBearClient = class {
    */
   async addFinding(sessionId, options) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("add_session_finding", {
         p_session_id: sessionId,
         p_type: options.type,
@@ -2041,6 +2174,7 @@ var BugBearClient = class {
    */
   async getSessionFindings(sessionId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("qa_findings").select("*").eq("session_id", sessionId).order("created_at", { ascending: true }).limit(100);
       if (error) {
         console.error("BugBear: Failed to fetch findings", formatPgError(error));
@@ -2057,6 +2191,7 @@ var BugBearClient = class {
    */
   async convertFindingToBug(findingId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("convert_finding_to_bug", {
         p_finding_id: findingId
       });
@@ -2076,6 +2211,7 @@ var BugBearClient = class {
    */
   async dismissFinding(findingId, reason) {
     try {
+      await this.ensureReady();
       const { error } = await this.supabase.from("qa_findings").update({
         dismissed: true,
         dismissed_reason: reason || null,

package/dist/index.mjs

@@ -18,6 +18,7 @@ var ContextCaptureManager = class {
     this.networkRequests = [];
     this.navigationHistory = [];
     this.originalConsole = {};
+    this.fetchHost = null;
     this.isCapturing = false;
   }
   /**
@@ -40,8 +41,9 @@ var ContextCaptureManager = class {
     if (this.originalConsole.warn) console.warn = this.originalConsole.warn;
     if (this.originalConsole.error) console.error = this.originalConsole.error;
     if (this.originalConsole.info) console.info = this.originalConsole.info;
-    if (this.originalFetch && typeof window !== "undefined") {
-      window.fetch = this.originalFetch;
+    if (this.originalFetch && this.fetchHost) {
+      this.fetchHost.fetch = this.originalFetch;
+      this.fetchHost = null;
     }
     if (typeof window !== "undefined" && typeof history !== "undefined") {
       if (this.originalPushState) {
@@ -150,15 +152,19 @@ var ContextCaptureManager = class {
     });
   }
   captureFetch() {
-    if (typeof window === "undefined" || typeof fetch === "undefined" || typeof document === "undefined") return;
-    this.originalFetch = window.fetch;
+    if (typeof fetch === "undefined") return;
+    const host = typeof window !== "undefined" && typeof window.fetch === "function" ? window : typeof globalThis !== "undefined" && typeof globalThis.fetch === "function" ? globalThis : null;
+    if (!host) return;
+    const canCloneResponse = typeof document !== "undefined";
+    this.fetchHost = host;
+    this.originalFetch = host.fetch;
     const self = this;
-    window.fetch = async function(input, init) {
+    host.fetch = async function(input, init) {
       const startTime = Date.now();
       const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
       const method = init?.method || "GET";
       try {
-        const response = await self.originalFetch.call(window, input, init);
+        const response = await self.originalFetch.call(host, input, init);
         const requestEntry = {
           method,
           url: url.slice(0, 200),
@@ -167,7 +173,7 @@ var ContextCaptureManager = class {
           duration: Date.now() - startTime,
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         };
-        if (response.status >= 400) {
+        if (canCloneResponse && response.status >= 400) {
           try {
             const cloned = response.clone();
             const body = await cloned.text();
@@ -415,6 +421,9 @@ var formatPgError = (e) => {
   const { message, code, details, hint } = e;
   return { message, code, details, hint };
 };
+var DEFAULT_API_BASE_URL = "https://app.bugbear.ai";
+var CONFIG_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
+var CONFIG_CACHE_PREFIX = "bugbear_config_";
 var BugBearClient = class {
   constructor(config) {
     this.navigationHistory = [];
@@ -424,23 +433,133 @@ var BugBearClient = class {
     /** Active Realtime channel references for cleanup. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     this.realtimeChannels = [];
-    if (!config.supabaseUrl) {
-      throw new Error("BugBear: supabaseUrl is required. Get it from your BugBear project settings.");
-    }
-    if (!config.supabaseAnonKey) {
-      throw new Error("BugBear: supabaseAnonKey is required. Get it from your BugBear project settings.");
-    }
+    /** Whether the client has been successfully initialized. */
+    this.initialized = false;
+    /** Initialization error, if any. */
+    this.initError = null;
     this.config = config;
-    this.supabase = createClient(config.supabaseUrl, config.supabaseAnonKey);
-    if (config.offlineQueue?.enabled) {
+    if (config.apiKey) {
+      this.pendingInit = this.resolveFromApiKey(config.apiKey);
+    } else if (config.supabaseUrl && config.supabaseAnonKey) {
+      if (!config.projectId) {
+        throw new Error(
+          "BugBear: projectId is required when using explicit Supabase credentials. Tip: Use apiKey instead for simpler setup \u2014 it resolves everything automatically."
+        );
+      }
+      this.supabase = createClient(config.supabaseUrl, config.supabaseAnonKey);
+      this.initialized = true;
+      this.pendingInit = Promise.resolve();
+      this.initOfflineQueue();
+    } else {
+      throw new Error(
+        "BugBear: Missing configuration. Provide either:\n  \u2022 apiKey (recommended) \u2014 resolves everything automatically\n  \u2022 projectId + supabaseUrl + supabaseAnonKey \u2014 explicit credentials\n\nGet your API key at https://app.bugbear.ai/settings/projects"
+      );
+    }
+  }
+  /** Whether the client is ready for requests. */
+  get isReady() {
+    return this.initialized;
+  }
+  /** Wait until the client is ready. Throws if initialization failed. */
+  async ready() {
+    await this.pendingInit;
+    if (this.initError) throw this.initError;
+  }
+  /**
+   * Resolve Supabase credentials from a BugBear API key.
+   * Checks localStorage cache first, falls back to /api/v1/config.
+   */
+  async resolveFromApiKey(apiKey) {
+    try {
+      const cached = this.readConfigCache(apiKey);
+      if (cached) {
+        this.applyResolvedConfig(cached);
+        return;
+      }
+      const baseUrl = (this.config.apiBaseUrl || DEFAULT_API_BASE_URL).replace(/\/$/, "");
+      const response = await fetch(`${baseUrl}/api/v1/config`, {
+        headers: { Authorization: `Bearer ${apiKey}` }
+      });
+      if (!response.ok) {
+        const body = await response.json().catch(() => ({}));
+        const message = body.error || `HTTP ${response.status}`;
+        throw new Error(
+          `BugBear: Invalid API key \u2014 ${message}. Get yours at https://app.bugbear.ai/settings/projects`
+        );
+      }
+      const data = await response.json();
+      this.writeConfigCache(apiKey, data);
+      this.applyResolvedConfig(data);
+    } catch (err) {
+      this.initError = err instanceof Error ? err : new Error(String(err));
+      this.config.onError?.(this.initError, { context: "apikey_resolution_failed" });
+      throw this.initError;
+    }
+  }
+  /** Apply resolved credentials and create the Supabase client. */
+  applyResolvedConfig(resolved) {
+    this.config = {
+      ...this.config,
+      projectId: resolved.projectId,
+      supabaseUrl: resolved.supabaseUrl,
+      supabaseAnonKey: resolved.supabaseAnonKey
+    };
+    this.supabase = createClient(resolved.supabaseUrl, resolved.supabaseAnonKey);
+    this.initialized = true;
+    this.initOfflineQueue();
+  }
+  /** Initialize offline queue if configured. Shared by both init paths. */
+  initOfflineQueue() {
+    if (this.config.offlineQueue?.enabled) {
       this._queue = new OfflineQueue({
         enabled: true,
-        maxItems: config.offlineQueue.maxItems,
-        maxRetries: config.offlineQueue.maxRetries
+        maxItems: this.config.offlineQueue.maxItems,
+        maxRetries: this.config.offlineQueue.maxRetries
       });
       this.registerQueueHandlers();
     }
   }
+  /** Read cached config from localStorage if available and not expired. */
+  readConfigCache(apiKey) {
+    if (typeof localStorage === "undefined") return null;
+    try {
+      const key = CONFIG_CACHE_PREFIX + this.hashKey(apiKey);
+      const raw = localStorage.getItem(key);
+      if (!raw) return null;
+      const cached = JSON.parse(raw);
+      if (Date.now() - cached.cachedAt > CONFIG_CACHE_TTL_MS) {
+        localStorage.removeItem(key);
+        return null;
+      }
+      return cached;
+    } catch {
+      return null;
+    }
+  }
+  /** Write resolved config to localStorage cache. */
+  writeConfigCache(apiKey, data) {
+    if (typeof localStorage === "undefined") return;
+    try {
+      const key = CONFIG_CACHE_PREFIX + this.hashKey(apiKey);
+      const cached = { ...data, cachedAt: Date.now() };
+      localStorage.setItem(key, JSON.stringify(cached));
+    } catch {
+    }
+  }
+  /** Simple string hash for cache keys — avoids storing raw API keys. */
+  hashKey(apiKey) {
+    let hash = 0;
+    for (let i = 0; i < apiKey.length; i++) {
+      hash = (hash << 5) - hash + apiKey.charCodeAt(i) | 0;
+    }
+    return hash.toString(36);
+  }
+  /** Ensure the client is initialized before making requests. */
+  async ensureReady() {
+    if (this.initialized) return;
+    await this.pendingInit;
+    if (this.initError) throw this.initError;
+  }
   // ── Offline Queue ─────────────────────────────────────────
   /**
    * Access the offline queue (if enabled).
@@ -596,6 +715,7 @@ var BugBearClient = class {
    * Get current user info from host app or BugBear's own auth
    */
   async getCurrentUserInfo() {
+    await this.ensureReady();
     if (this.config.getCurrentUser) {
       return await this.config.getCurrentUser();
     }
@@ -815,6 +935,7 @@ var BugBearClient = class {
    */
   async getAssignment(assignmentId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("test_assignments").select(`
           id,
           status,
@@ -886,6 +1007,7 @@ var BugBearClient = class {
    */
   async updateAssignmentStatus(assignmentId, status, options) {
     try {
+      await this.ensureReady();
       const { data: currentAssignment, error: fetchError } = await this.supabase.from("test_assignments").select("status, started_at").eq("id", assignmentId).single();
       if (fetchError || !currentAssignment) {
         console.error("BugBear: Assignment not found", {
@@ -972,6 +1094,7 @@ var BugBearClient = class {
    */
   async reopenAssignment(assignmentId) {
     try {
+      await this.ensureReady();
       const { data: current, error: fetchError } = await this.supabase.from("test_assignments").select("status").eq("id", assignmentId).single();
       if (fetchError || !current) {
         return { success: false, error: "Assignment not found" };
@@ -1011,6 +1134,7 @@ var BugBearClient = class {
       actualNotes = notes;
     }
     try {
+      await this.ensureReady();
       const updateData = {
         status: "skipped",
         skip_reason: actualReason,
@@ -1180,6 +1304,7 @@ var BugBearClient = class {
    */
   async getTesterInfo() {
     try {
+      await this.ensureReady();
       const userInfo = await this.getCurrentUserInfo();
       if (!userInfo?.email) return null;
       if (!this.isValidEmail(userInfo.email)) {
@@ -1471,6 +1596,7 @@ var BugBearClient = class {
    */
   async isQAEnabled() {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("check_qa_enabled", {
         p_project_id: this.config.projectId
       });
@@ -1502,6 +1628,7 @@ var BugBearClient = class {
    */
   async uploadScreenshot(file, filename, bucket = "screenshots") {
     try {
+      await this.ensureReady();
       const contentType = file.type || "image/png";
       const ext = contentType.includes("png") ? "png" : "jpg";
       const name = filename || `screenshot-${Date.now()}.${ext}`;
@@ -1542,6 +1669,7 @@ var BugBearClient = class {
    */
   async uploadImageFromUri(uri, filename, bucket = "screenshots") {
     try {
+      await this.ensureReady();
       const response = await fetch(uri);
       const blob = await response.blob();
       const contentType = blob.type || "image/jpeg";
@@ -1636,6 +1764,7 @@ var BugBearClient = class {
    */
   async getFixRequests(options) {
     try {
+      await this.ensureReady();
       let query = this.supabase.from("fix_requests").select("*").eq("project_id", this.config.projectId).order("created_at", { ascending: false }).limit(options?.limit || 20);
       if (options?.status) {
         query = query.eq("status", options.status);
@@ -1707,6 +1836,7 @@ var BugBearClient = class {
    */
   async getThreadMessages(threadId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("discussion_messages").select(`
           id,
           thread_id,
@@ -1909,6 +2039,7 @@ var BugBearClient = class {
    */
   async endSession(sessionId, options = {}) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("end_qa_session", {
         p_session_id: sessionId,
         p_notes: options.notes || null,
@@ -1946,6 +2077,7 @@ var BugBearClient = class {
    */
   async getSession(sessionId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("qa_sessions").select("*").eq("id", sessionId).single();
       if (error || !data) return null;
       return this.transformSession(data);
@@ -1977,6 +2109,7 @@ var BugBearClient = class {
    */
   async addFinding(sessionId, options) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("add_session_finding", {
         p_session_id: sessionId,
         p_type: options.type,
@@ -2007,6 +2140,7 @@ var BugBearClient = class {
    */
   async getSessionFindings(sessionId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.from("qa_findings").select("*").eq("session_id", sessionId).order("created_at", { ascending: true }).limit(100);
       if (error) {
         console.error("BugBear: Failed to fetch findings", formatPgError(error));
@@ -2023,6 +2157,7 @@ var BugBearClient = class {
    */
   async convertFindingToBug(findingId) {
     try {
+      await this.ensureReady();
       const { data, error } = await this.supabase.rpc("convert_finding_to_bug", {
         p_finding_id: findingId
       });
@@ -2042,6 +2177,7 @@ var BugBearClient = class {
    */
   async dismissFinding(findingId, reason) {
     try {
+      await this.ensureReady();
       const { error } = await this.supabase.from("qa_findings").update({
         dismissed: true,
         dismissed_reason: reason || null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bbearai/core",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Core utilities and types for BugBear QA platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",