jblyons15-research-sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import type { ResearchRequest, ResearchResult, ResearchJob, ResearchJobStatus, ResearchError, CacheEntry, RetryPolicy } from '@crossover/research-types';
+export declare class ResearchErrorHandler {
+    static create(type: ResearchError['type'], code: string, message: string, details?: Record<string, any>, retryable?: boolean): ResearchError;
+    static fromPerplexityError(error: any): ResearchError;
+    static fromFirecrawlError(error: any): ResearchError;
+    static isRetryable(error: ResearchError): boolean;
+}
+export declare class RetryEngine {
+    private policy;
+    constructor(policy?: RetryPolicy);
+    execute<T>(fn: () => Promise<T>, context?: string): Promise<T>;
+    private calculateDelay;
+    private sleep;
+}
+export declare class CacheClient {
+    private cache;
+    get(queryHash: string): Promise<CacheEntry | null>;
+    set(queryHash: string, result: ResearchResult, ttlMs?: any): Promise<void>;
+    clear(): Promise<void>;
+    getStats(): {
+        size: number;
+        totalHits: number;
+    };
+}
+export declare class PerplexityClient {
+    private apiKey;
+    private retryEngine;
+    constructor(apiKey: string);
+    search(query: string, options?: {
+        domainFilter?: {
+            allow?: string[];
+            deny?: string[];
+        };
+        recency?: 'day' | 'week' | 'month';
+    }): Promise<{
+        sources: Array<{
+            url: string;
+            title: string;
+            snippet: string;
+        }>;
+        totalResults: number;
+        executionMs: number;
+    }>;
+    agent(request: {
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+        model?: string;
+        tools?: any[];
+        systemPrompt?: string;
+    }): Promise<{
+        synthesis: string;
+        citations: string[];
+        executionMs: number;
+    }>;
+}
+export declare class FirecrawlClient {
+    private apiKey;
+    private retryEngine;
+    constructor(apiKey: string);
+    scrape(url: string, schema?: Record<string, any>): Promise<{
+        data: Record<string, any>;
+        markdown: string;
+        executionMs: number;
+    }>;
+    batchScrape(urls: string[]): Promise<Array<{
+        url: string;
+        data: Record<string, any>;
+        error?: string;
+    }>>;
+}
+export declare class CortexClient {
+    private supabase;
+    constructor(supabase: SupabaseClient);
+    createResearchRequest(request: Omit<ResearchRequest, 'id' | 'status' | 'createdAt' | 'updatedAt'>): Promise<string>;
+    getResearchJob(jobId: string): Promise<ResearchJob | null>;
+    updateResearchJob(jobId: string, updates: Partial<ResearchJob>): Promise<void>;
+    createReport(report: {
+        entityType: string;
+        reportType: string;
+        content: string;
+        model: string;
+        cost: number;
+        latencyMs: number;
+    }): Promise<string>;
+    subscribe(jobId: string, callback: (status: ResearchJobStatus) => void): void;
+}
+export declare class ResearchOrchestrator {
+    private perplexity;
+    private firecrawl;
+    private cortex;
+    private cache;
+    private retryEngine;
+    constructor(config: {
+        perplexityApiKey: string;
+        firecrawlApiKey: string;
+        supabaseUrl: string;
+        supabaseAnonKey: string;
+    });
+    submitRequest(request: Omit<ResearchRequest, 'id' | 'status' | 'createdAt' | 'updatedAt'>): Promise<string>;
+    getStatus(jobId: string): Promise<ResearchJobStatus | null>;
+    getResults(jobId: string): Promise<ResearchResult | null>;
+    onStatusChange(jobId: string, callback: (status: ResearchJobStatus) => void): void;
+    getCacheStats(): {
+        size: number;
+        totalHits: number;
+    };
+}
+declare const _default: {
+    ResearchOrchestrator: typeof ResearchOrchestrator;
+    ResearchErrorHandler: typeof ResearchErrorHandler;
+    RetryEngine: typeof RetryEngine;
+    CacheClient: typeof CacheClient;
+    PerplexityClient: typeof PerplexityClient;
+    FirecrawlClient: typeof FirecrawlClient;
+    CortexClient: typeof CortexClient;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,377 @@
+// @crossover/research-sdk - Complete Package Definition
+// Client libraries for Supabase, Perplexity, Firecrawl, error handling, caching
+import { createClient } from '@supabase/supabase-js';
+// ============================================================================
+// ERROR HANDLER - Canonical error handling (SSOT)
+// ============================================================================
+export class ResearchErrorHandler {
+    static create(type, code, message, details = {}, retryable = false) {
+        return {
+            type,
+            code,
+            message,
+            retryable,
+            details,
+            timestamp: new Date(),
+        };
+    }
+    static fromPerplexityError(error) {
+        if (error?.status === 429) {
+            return this.create('RATE_LIMIT', 'PERPLEXITY_RATE_LIMITED', error.message, { error }, true);
+        }
+        if (error?.status === 401) {
+            return this.create('AUTH', 'PERPLEXITY_AUTH_FAILED', error.message, { error }, false);
+        }
+        if (error?.status >= 500) {
+            return this.create('API', 'PERPLEXITY_SERVER_ERROR', error.message, { error }, true);
+        }
+        return this.create('API', 'PERPLEXITY_ERROR', error.message, { error }, false);
+    }
+    static fromFirecrawlError(error) {
+        if (error?.status === 429) {
+            return this.create('RATE_LIMIT', 'FIRECRAWL_RATE_LIMITED', error.message, { error }, true);
+        }
+        if (error?.status === 401) {
+            return this.create('AUTH', 'FIRECRAWL_AUTH_FAILED', error.message, { error }, false);
+        }
+        if (error?.status >= 500) {
+            return this.create('API', 'FIRECRAWL_SERVER_ERROR', error.message, { error }, true);
+        }
+        return this.create('API', 'FIRECRAWL_ERROR', error.message, { error }, false);
+    }
+    static isRetryable(error) {
+        return error.retryable && error.type !== 'VALIDATION';
+    }
+}
+// ============================================================================
+// RETRY ENGINE - Canonical retry logic (SSOT)
+// ============================================================================
+export class RetryEngine {
+    constructor(policy = CANONICAL_RETRY_POLICY) {
+        this.policy = policy;
+    }
+    async execute(fn, context = 'operation') {
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.policy.maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (attempt === this.policy.maxRetries) {
+                    throw lastError;
+                }
+                const delayMs = this.calculateDelay(attempt);
+                console.log(`${context} failed, retrying in ${delayMs}ms (attempt ${attempt + 1}/${this.policy.maxRetries})`);
+                await this.sleep(delayMs);
+            }
+        }
+        throw lastError;
+    }
+    calculateDelay(attempt) {
+        const exponential = this.policy.initialDelayMs * Math.pow(this.policy.backoffMultiplier, attempt);
+        return Math.min(exponential, this.policy.maxDelayMs);
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+// ============================================================================
+// CACHE CLIENT - Canonical caching (SSOT)
+// ============================================================================
+export class CacheClient {
+    constructor() {
+        this.cache = new Map();
+    }
+    async get(queryHash) {
+        const entry = this.cache.get(queryHash);
+        if (!entry)
+            return null;
+        if (entry.expiresAt < new Date()) {
+            this.cache.delete(queryHash);
+            return null;
+        }
+        // Record hit
+        entry.hitCount += 1;
+        return entry;
+    }
+    async set(queryHash, result, ttlMs = CANONICAL_CACHE_TTL_MS) {
+        const entry = {
+            queryHash,
+            query: '', // Would be populated in real implementation
+            result,
+            hitCount: 0,
+            createdAt: new Date(),
+            expiresAt: new Date(Date.now() + ttlMs),
+        };
+        this.cache.set(queryHash, entry);
+    }
+    async clear() {
+        this.cache.clear();
+    }
+    getStats() {
+        const totalHits = Array.from(this.cache.values()).reduce((sum, e) => sum + e.hitCount, 0);
+        return { size: this.cache.size, totalHits };
+    }
+}
+// ============================================================================
+// PERPLEXITY CLIENT - Canonical Perplexity integration
+// ============================================================================
+export class PerplexityClient {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        this.retryEngine = new RetryEngine();
+    }
+    async search(query, options) {
+        const startTime = Date.now();
+        return this.retryEngine.execute(async () => {
+            const response = await fetch('https://api.perplexity.ai/search', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    query,
+                    search_type: 'web',
+                    search_domain_filter: options?.domainFilter,
+                    recency: options?.recency || 'month',
+                }),
+            });
+            if (!response.ok) {
+                throw ResearchErrorHandler.fromPerplexityError({
+                    status: response.status,
+                    message: `HTTP ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            const executionMs = Date.now() - startTime;
+            return {
+                sources: data.results?.map((r) => ({
+                    url: r.url,
+                    title: r.title,
+                    snippet: r.snippet,
+                })) || [],
+                totalResults: data.total_results || 0,
+                executionMs,
+            };
+        }, 'Perplexity search');
+    }
+    async agent(request) {
+        const startTime = Date.now();
+        return this.retryEngine.execute(async () => {
+            const response = await fetch('https://api.perplexity.ai/chat/completions', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    model: request.model || 'sonar-pro',
+                    messages: request.messages,
+                    tools: request.tools,
+                    system: request.systemPrompt,
+                    temperature: 0.7,
+                    top_p: 1,
+                }),
+            });
+            if (!response.ok) {
+                throw ResearchErrorHandler.fromPerplexityError({
+                    status: response.status,
+                    message: `HTTP ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            const executionMs = Date.now() - startTime;
+            return {
+                synthesis: data.choices?.[0]?.message?.content || '',
+                citations: data.citations || [],
+                executionMs,
+            };
+        }, 'Perplexity agent');
+    }
+}
+// ============================================================================
+// FIRECRAWL CLIENT - Canonical web scraping
+// ============================================================================
+export class FirecrawlClient {
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        this.retryEngine = new RetryEngine();
+    }
+    async scrape(url, schema) {
+        const startTime = Date.now();
+        return this.retryEngine.execute(async () => {
+            const response = await fetch('https://api.firecrawl.dev/v1/scrape', {
+                method: 'POST',
+                headers: {
+                    'Authorization': `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    url,
+                    extractorOptions: schema ? {
+                        mode: 'llm-extraction',
+                        extractionSchema: schema,
+                    } : undefined,
+                }),
+            });
+            if (!response.ok) {
+                throw ResearchErrorHandler.fromFirecrawlError({
+                    status: response.status,
+                    message: `HTTP ${response.status}`,
+                });
+            }
+            const data = await response.json();
+            const executionMs = Date.now() - startTime;
+            return {
+                data: data.data || {},
+                markdown: data.markdown || '',
+                executionMs,
+            };
+        }, `Firecrawl scrape ${url}`);
+    }
+    async batchScrape(urls) {
+        return Promise.all(urls.map(async (url) => {
+            try {
+                const result = await this.scrape(url);
+                return { url, data: result.data };
+            }
+            catch (error) {
+                return {
+                    url,
+                    data: {},
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }));
+    }
+}
+// ============================================================================
+// CORTEX CLIENT - Supabase integration
+// ============================================================================
+export class CortexClient {
+    constructor(supabase) {
+        this.supabase = supabase;
+    }
+    async createResearchRequest(request) {
+        const { data, error } = await this.supabase
+            .from('cortex.client_research_requests')
+            .insert({
+            ...request,
+            status: 'pending',
+            created_at: new Date(),
+            updated_at: new Date(),
+        })
+            .select('id')
+            .single();
+        if (error)
+            throw error;
+        return data.id;
+    }
+    async getResearchJob(jobId) {
+        const { data, error } = await this.supabase
+            .from('cortex.research_jobs')
+            .select('*')
+            .eq('id', jobId)
+            .single();
+        if (error && error.code !== 'PGRST116')
+            throw error;
+        return data || null;
+    }
+    async updateResearchJob(jobId, updates) {
+        const { error } = await this.supabase
+            .from('cortex.research_jobs')
+            .update({
+            ...updates,
+            updated_at: new Date(),
+        })
+            .eq('id', jobId);
+        if (error)
+            throw error;
+    }
+    async createReport(report) {
+        const { data, error } = await this.supabase
+            .from('ai_reports')
+            .insert({
+            entity_type: report.entityType,
+            report_type: report.reportType,
+            content: report.content,
+            model: report.model,
+            cost: report.cost,
+            latency_ms: report.latencyMs,
+            generated_at: new Date(),
+        })
+            .select('id')
+            .single();
+        if (error)
+            throw error;
+        return data.id;
+    }
+    subscribe(jobId, callback) {
+        this.supabase
+            .from(`cortex.research_jobs:id=eq.${jobId}`)
+            .on('*', (payload) => {
+            callback({
+                jobId,
+                status: payload.new.status,
+                progress: payload.new.progress || 0,
+                error: payload.new.error,
+                lastUpdate: new Date(),
+            });
+        })
+            .subscribe();
+    }
+}
+// ============================================================================
+// RESEARCH ORCHESTRATOR - Main entry point
+// ============================================================================
+export class ResearchOrchestrator {
+    constructor(config) {
+        this.perplexity = new PerplexityClient(config.perplexityApiKey);
+        this.firecrawl = new FirecrawlClient(config.firecrawlApiKey);
+        this.cortex = new CortexClient(createClient(config.supabaseUrl, config.supabaseAnonKey));
+        this.cache = new CacheClient();
+        this.retryEngine = new RetryEngine();
+    }
+    async submitRequest(request) {
+        // This just creates the request record
+        // The actual execution happens in the Edge Function
+        const jobId = await this.cortex.createResearchRequest(request);
+        return jobId;
+    }
+    async getStatus(jobId) {
+        const job = await this.cortex.getResearchJob(jobId);
+        if (!job)
+            return null;
+        return {
+            jobId,
+            status: job.status,
+            progress: job.progress || 0,
+            error: job.error,
+            lastUpdate: job.updatedAt,
+        };
+    }
+    async getResults(jobId) {
+        const job = await this.cortex.getResearchJob(jobId);
+        return job?.result || null;
+    }
+    onStatusChange(jobId, callback) {
+        this.cortex.subscribe(jobId, callback);
+    }
+    getCacheStats() {
+        return this.cache.getStats();
+    }
+}
+// ============================================================================
+// EXPORTS
+// ============================================================================
+export default {
+    ResearchOrchestrator,
+    ResearchErrorHandler,
+    RetryEngine,
+    CacheClient,
+    PerplexityClient,
+    FirecrawlClient,
+    CortexClient,
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "jblyons15-research-sdk",
+  "version": "1.0.0",
+  "description": "Research orchestration SDK for CommandCenter",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "research",
+    "orchestration",
+    "perplexity",
+    "firecrawl",
+    "supabase"
+  ],
+  "author": "Crossover Research",
+  "license": "MIT",
+  "dependencies": {
+    "@supabase/supabase-js": "^2.38.0",
+    "jblyons15-research-types": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,496 @@
+// @crossover/research-sdk - Complete Package Definition
+// Client libraries for Supabase, Perplexity, Firecrawl, error handling, caching
+
+import { createClient, SupabaseClient } from '@supabase/supabase-js'
+import type {
+  ResearchRequest,
+  ResearchResult,
+  ResearchJob,
+  ResearchJobStatus,
+  ResearchError,
+  CacheEntry,
+  RetryPolicy,
+  CANONICAL_RETRY_POLICY,
+  CANONICAL_CACHE_TTL_MS,
+} from '@crossover/research-types'
+
+// ============================================================================
+// ERROR HANDLER - Canonical error handling (SSOT)
+// ============================================================================
+
+export class ResearchErrorHandler {
+  static create(
+    type: ResearchError['type'],
+    code: string,
+    message: string,
+    details: Record<string, any> = {},
+    retryable = false
+  ): ResearchError {
+    return {
+      type,
+      code,
+      message,
+      retryable,
+      details,
+      timestamp: new Date(),
+    }
+  }
+
+  static fromPerplexityError(error: any): ResearchError {
+    if (error?.status === 429) {
+      return this.create('RATE_LIMIT', 'PERPLEXITY_RATE_LIMITED', error.message, { error }, true)
+    }
+    if (error?.status === 401) {
+      return this.create('AUTH', 'PERPLEXITY_AUTH_FAILED', error.message, { error }, false)
+    }
+    if (error?.status >= 500) {
+      return this.create('API', 'PERPLEXITY_SERVER_ERROR', error.message, { error }, true)
+    }
+    return this.create('API', 'PERPLEXITY_ERROR', error.message, { error }, false)
+  }
+
+  static fromFirecrawlError(error: any): ResearchError {
+    if (error?.status === 429) {
+      return this.create('RATE_LIMIT', 'FIRECRAWL_RATE_LIMITED', error.message, { error }, true)
+    }
+    if (error?.status === 401) {
+      return this.create('AUTH', 'FIRECRAWL_AUTH_FAILED', error.message, { error }, false)
+    }
+    if (error?.status >= 500) {
+      return this.create('API', 'FIRECRAWL_SERVER_ERROR', error.message, { error }, true)
+    }
+    return this.create('API', 'FIRECRAWL_ERROR', error.message, { error }, false)
+  }
+
+  static isRetryable(error: ResearchError): boolean {
+    return error.retryable && error.type !== 'VALIDATION'
+  }
+}
+
+// ============================================================================
+// RETRY ENGINE - Canonical retry logic (SSOT)
+// ============================================================================
+
+export class RetryEngine {
+  constructor(private policy: RetryPolicy = CANONICAL_RETRY_POLICY) {}
+
+  async execute<T>(
+    fn: () => Promise<T>,
+    context: string = 'operation'
+  ): Promise<T> {
+    let lastError: Error | null = null
+
+    for (let attempt = 0; attempt <= this.policy.maxRetries; attempt++) {
+      try {
+        return await fn()
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+
+        if (attempt === this.policy.maxRetries) {
+          throw lastError
+        }
+
+        const delayMs = this.calculateDelay(attempt)
+        console.log(`${context} failed, retrying in ${delayMs}ms (attempt ${attempt + 1}/${this.policy.maxRetries})`)
+        await this.sleep(delayMs)
+      }
+    }
+
+    throw lastError
+  }
+
+  private calculateDelay(attempt: number): number {
+    const exponential = this.policy.initialDelayMs * Math.pow(this.policy.backoffMultiplier, attempt)
+    return Math.min(exponential, this.policy.maxDelayMs)
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}
+
+// ============================================================================
+// CACHE CLIENT - Canonical caching (SSOT)
+// ============================================================================
+
+export class CacheClient {
+  private cache = new Map<string, CacheEntry>()
+
+  async get(queryHash: string): Promise<CacheEntry | null> {
+    const entry = this.cache.get(queryHash)
+
+    if (!entry) return null
+    if (entry.expiresAt < new Date()) {
+      this.cache.delete(queryHash)
+      return null
+    }
+
+    // Record hit
+    entry.hitCount += 1
+    return entry
+  }
+
+  async set(
+    queryHash: string,
+    result: ResearchResult,
+    ttlMs = CANONICAL_CACHE_TTL_MS
+  ): Promise<void> {
+    const entry: CacheEntry = {
+      queryHash,
+      query: '', // Would be populated in real implementation
+      result,
+      hitCount: 0,
+      createdAt: new Date(),
+      expiresAt: new Date(Date.now() + ttlMs),
+    }
+
+    this.cache.set(queryHash, entry)
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear()
+  }
+
+  getStats(): { size: number; totalHits: number } {
+    const totalHits = Array.from(this.cache.values()).reduce((sum, e) => sum + e.hitCount, 0)
+    return { size: this.cache.size, totalHits }
+  }
+}
+
+// ============================================================================
+// PERPLEXITY CLIENT - Canonical Perplexity integration
+// ============================================================================
+
+export class PerplexityClient {
+  private retryEngine = new RetryEngine()
+
+  constructor(private apiKey: string) {}
+
+  async search(query: string, options?: {
+    domainFilter?: { allow?: string[]; deny?: string[] }
+    recency?: 'day' | 'week' | 'month'
+  }): Promise<{
+    sources: Array<{ url: string; title: string; snippet: string }>
+    totalResults: number
+    executionMs: number
+  }> {
+    const startTime = Date.now()
+
+    return this.retryEngine.execute(async () => {
+      const response = await fetch('https://api.perplexity.ai/search', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          query,
+          search_type: 'web',
+          search_domain_filter: options?.domainFilter,
+          recency: options?.recency || 'month',
+        }),
+      })
+
+      if (!response.ok) {
+        throw ResearchErrorHandler.fromPerplexityError({
+          status: response.status,
+          message: `HTTP ${response.status}`,
+        })
+      }
+
+      const data = await response.json()
+      const executionMs = Date.now() - startTime
+
+      return {
+        sources: data.results?.map((r: any) => ({
+          url: r.url,
+          title: r.title,
+          snippet: r.snippet,
+        })) || [],
+        totalResults: data.total_results || 0,
+        executionMs,
+      }
+    }, 'Perplexity search')
+  }
+
+  async agent(request: {
+    messages: Array<{ role: string; content: string }>
+    model?: string
+    tools?: any[]
+    systemPrompt?: string
+  }): Promise<{
+    synthesis: string
+    citations: string[]
+    executionMs: number
+  }> {
+    const startTime = Date.now()
+
+    return this.retryEngine.execute(async () => {
+      const response = await fetch('https://api.perplexity.ai/chat/completions', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          model: request.model || 'sonar-pro',
+          messages: request.messages,
+          tools: request.tools,
+          system: request.systemPrompt,
+          temperature: 0.7,
+          top_p: 1,
+        }),
+      })
+
+      if (!response.ok) {
+        throw ResearchErrorHandler.fromPerplexityError({
+          status: response.status,
+          message: `HTTP ${response.status}`,
+        })
+      }
+
+      const data = await response.json()
+      const executionMs = Date.now() - startTime
+
+      return {
+        synthesis: data.choices?.[0]?.message?.content || '',
+        citations: data.citations || [],
+        executionMs,
+      }
+    }, 'Perplexity agent')
+  }
+}
+
+// ============================================================================
+// FIRECRAWL CLIENT - Canonical web scraping
+// ============================================================================
+
+export class FirecrawlClient {
+  private retryEngine = new RetryEngine()
+
+  constructor(private apiKey: string) {}
+
+  async scrape(url: string, schema?: Record<string, any>): Promise<{
+    data: Record<string, any>
+    markdown: string
+    executionMs: number
+  }> {
+    const startTime = Date.now()
+
+    return this.retryEngine.execute(async () => {
+      const response = await fetch('https://api.firecrawl.dev/v1/scrape', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          url,
+          extractorOptions: schema ? {
+            mode: 'llm-extraction',
+            extractionSchema: schema,
+          } : undefined,
+        }),
+      })
+
+      if (!response.ok) {
+        throw ResearchErrorHandler.fromFirecrawlError({
+          status: response.status,
+          message: `HTTP ${response.status}`,
+        })
+      }
+
+      const data = await response.json()
+      const executionMs = Date.now() - startTime
+
+      return {
+        data: data.data || {},
+        markdown: data.markdown || '',
+        executionMs,
+      }
+    }, `Firecrawl scrape ${url}`)
+  }
+
+  async batchScrape(urls: string[]): Promise<Array<{
+    url: string
+    data: Record<string, any>
+    error?: string
+  }>> {
+    return Promise.all(
+      urls.map(async url => {
+        try {
+          const result = await this.scrape(url)
+          return { url, data: result.data }
+        } catch (error) {
+          return {
+            url,
+            data: {},
+            error: error instanceof Error ? error.message : String(error),
+          }
+        }
+      })
+    )
+  }
+}
+
+// ============================================================================
+// CORTEX CLIENT - Supabase integration
+// ============================================================================
+
+export class CortexClient {
+  constructor(private supabase: SupabaseClient) {}
+
+  async createResearchRequest(request: Omit<ResearchRequest, 'id' | 'status' | 'createdAt' | 'updatedAt'>): Promise<string> {
+    const { data, error } = await this.supabase
+      .from('cortex.client_research_requests')
+      .insert({
+        ...request,
+        status: 'pending',
+        created_at: new Date(),
+        updated_at: new Date(),
+      })
+      .select('id')
+      .single()
+
+    if (error) throw error
+    return data.id
+  }
+
+  async getResearchJob(jobId: string): Promise<ResearchJob | null> {
+    const { data, error } = await this.supabase
+      .from('cortex.research_jobs')
+      .select('*')
+      .eq('id', jobId)
+      .single()
+
+    if (error && error.code !== 'PGRST116') throw error
+    return data || null
+  }
+
+  async updateResearchJob(jobId: string, updates: Partial<ResearchJob>): Promise<void> {
+    const { error } = await this.supabase
+      .from('cortex.research_jobs')
+      .update({
+        ...updates,
+        updated_at: new Date(),
+      })
+      .eq('id', jobId)
+
+    if (error) throw error
+  }
+
+  async createReport(report: {
+    entityType: string
+    reportType: string
+    content: string
+    model: string
+    cost: number
+    latencyMs: number
+  }): Promise<string> {
+    const { data, error } = await this.supabase
+      .from('ai_reports')
+      .insert({
+        entity_type: report.entityType,
+        report_type: report.reportType,
+        content: report.content,
+        model: report.model,
+        cost: report.cost,
+        latency_ms: report.latencyMs,
+        generated_at: new Date(),
+      })
+      .select('id')
+      .single()
+
+    if (error) throw error
+    return data.id
+  }
+
+  subscribe(jobId: string, callback: (status: ResearchJobStatus) => void): void {
+    this.supabase
+      .from(`cortex.research_jobs:id=eq.${jobId}`)
+      .on('*', (payload) => {
+        callback({
+          jobId,
+          status: payload.new.status,
+          progress: payload.new.progress || 0,
+          error: payload.new.error,
+          lastUpdate: new Date(),
+        })
+      })
+      .subscribe()
+  }
+}
+
+// ============================================================================
+// RESEARCH ORCHESTRATOR - Main entry point
+// ============================================================================
+
+export class ResearchOrchestrator {
+  private perplexity: PerplexityClient
+  private firecrawl: FirecrawlClient
+  private cortex: CortexClient
+  private cache: CacheClient
+  private retryEngine: RetryEngine
+
+  constructor(config: {
+    perplexityApiKey: string
+    firecrawlApiKey: string
+    supabaseUrl: string
+    supabaseAnonKey: string
+  }) {
+    this.perplexity = new PerplexityClient(config.perplexityApiKey)
+    this.firecrawl = new FirecrawlClient(config.firecrawlApiKey)
+    this.cortex = new CortexClient(
+      createClient(config.supabaseUrl, config.supabaseAnonKey)
+    )
+    this.cache = new CacheClient()
+    this.retryEngine = new RetryEngine()
+  }
+
+  async submitRequest(request: Omit<ResearchRequest, 'id' | 'status' | 'createdAt' | 'updatedAt'>): Promise<string> {
+    // This just creates the request record
+    // The actual execution happens in the Edge Function
+    const jobId = await this.cortex.createResearchRequest(request)
+    return jobId
+  }
+
+  async getStatus(jobId: string): Promise<ResearchJobStatus | null> {
+    const job = await this.cortex.getResearchJob(jobId)
+    if (!job) return null
+
+    return {
+      jobId,
+      status: job.status,
+      progress: job.progress || 0,
+      error: job.error,
+      lastUpdate: job.updatedAt,
+    }
+  }
+
+  async getResults(jobId: string): Promise<ResearchResult | null> {
+    const job = await this.cortex.getResearchJob(jobId)
+    return job?.result || null
+  }
+
+  onStatusChange(jobId: string, callback: (status: ResearchJobStatus) => void): void {
+    this.cortex.subscribe(jobId, callback)
+  }
+
+  getCacheStats(): { size: number; totalHits: number } {
+    return this.cache.getStats()
+  }
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export default {
+  ResearchOrchestrator,
+  ResearchErrorHandler,
+  RetryEngine,
+  CacheClient,
+  PerplexityClient,
+  FirecrawlClient,
+  CortexClient,
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "bundler"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}