@perceo/supabase 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,707 @@
+import { SupabaseClient, RealtimeChannel } from '@supabase/supabase-js';
+
+/**
+ * Perceo Supabase Database Types
+ * Auto-generated from database schema
+ */
+type UUID = string;
+type Timestamp = string;
+type ProjectRole = "owner" | "admin" | "member" | "viewer";
+type FlowPriority = "critical" | "high" | "medium" | "low";
+type TestStatus = "pending" | "running" | "passed" | "failed" | "error" | "skipped";
+type TestTrigger = "pr" | "watch" | "manual" | "schedule" | "ci";
+type InsightType = "discrepancy" | "coverage-gap" | "ux-issue" | "prediction" | "performance" | "regression";
+type InsightSeverity = "critical" | "high" | "medium" | "low" | "info";
+type InsightStatus = "open" | "acknowledged" | "in_progress" | "resolved" | "dismissed" | "false_positive";
+type PredictionBasis = "ml-model" | "heuristic" | "pattern" | "historical";
+type RiskLevel = "critical" | "high" | "medium" | "low";
+type EventSource = "observer" | "coordinator" | "analyzer" | "analytics" | "cli" | "dashboard";
+type AnalyticsProvider = "ga4" | "mixpanel" | "amplitude" | "posthog" | "custom";
+type SyncStatus = "success" | "failed" | "partial";
+type ApiKeyScope = "ci:analyze" | "ci:test" | "flows:read" | "flows:write" | "insights:read" | "events:publish" | "workflows:start";
+interface Project {
+    id: UUID;
+    name: string;
+    framework: string | null;
+    config: Record<string, unknown>;
+    git_remote_url: string | null;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+interface ProjectMember {
+    project_id: UUID;
+    user_id: UUID;
+    role: ProjectRole;
+    created_at: Timestamp;
+}
+interface Persona {
+    id: UUID;
+    project_id: UUID;
+    name: string;
+    description: string | null;
+    behaviors: Record<string, unknown>;
+    source: "user_configured" | "auto_generated";
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+interface Flow {
+    id: UUID;
+    project_id: UUID;
+    persona_id: UUID | null;
+    name: string;
+    description: string | null;
+    priority: FlowPriority;
+    entry_point: string | null;
+    graph_data: Record<string, unknown>;
+    affected_by_changes: string[];
+    risk_score: number;
+    coverage_score: number | null;
+    is_active: boolean;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+interface StepAction {
+    type: "click" | "fill" | "navigate" | "wait" | "scroll" | "hover" | "assert" | "screenshot";
+    target?: string;
+    value?: string;
+    options?: Record<string, unknown>;
+}
+interface StepExpectedState {
+    url?: string;
+    visible?: string[];
+    hidden?: string[];
+    text?: Record<string, string>;
+    attributes?: Record<string, Record<string, string>>;
+}
+interface Step {
+    id: UUID;
+    flow_id: UUID;
+    sequence_order: number;
+    name: string;
+    actions: StepAction[];
+    expected_state: StepExpectedState;
+    timeout_ms: number;
+    retry_count: number;
+    next_step_id: UUID | null;
+    branch_config: {
+        condition: string;
+        trueStepId: UUID;
+        falseStepId: UUID;
+    } | null;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+interface FlowMetrics {
+    id: UUID;
+    flow_id: UUID;
+    synthetic_success_rate: number | null;
+    synthetic_avg_duration_ms: number | null;
+    synthetic_p50_duration_ms: number | null;
+    synthetic_p95_duration_ms: number | null;
+    synthetic_last_run: Timestamp | null;
+    synthetic_run_count: number;
+    prod_success_rate: number | null;
+    prod_daily_users: number | null;
+    prod_weekly_users: number | null;
+    prod_avg_duration_ms: number | null;
+    prod_top_exit_step: string | null;
+    prod_conversion_rate: number | null;
+    prod_device_breakdown: Record<string, number>;
+    prod_cohort_performance: Record<string, {
+        success_rate: number;
+    }>;
+    prod_last_updated: Timestamp | null;
+    gap_score: number | null;
+    updated_at: Timestamp;
+}
+interface TestRun {
+    id: UUID;
+    flow_id: UUID | null;
+    project_id: UUID;
+    status: TestStatus;
+    duration_ms: number | null;
+    error_message: string | null;
+    error_stack: string | null;
+    failed_step_id: UUID | null;
+    screenshots: string[];
+    video_url: string | null;
+    logs: unknown[];
+    triggered_by: TestTrigger | null;
+    pr_number: number | null;
+    commit_sha: string | null;
+    branch_name: string | null;
+    agent_id: string | null;
+    agent_type: string | null;
+    created_at: Timestamp;
+    started_at: Timestamp | null;
+    completed_at: Timestamp | null;
+}
+interface AnalyticsEvent {
+    id: UUID;
+    project_id: UUID;
+    event_type: string;
+    event_name: string | null;
+    user_id: string | null;
+    session_id: string | null;
+    anonymous_id: string | null;
+    flow_id: UUID | null;
+    flow_step: string | null;
+    flow_confidence: number | null;
+    url: string | null;
+    page_path: string | null;
+    referrer: string | null;
+    device_type: string | null;
+    browser: string | null;
+    os: string | null;
+    screen_resolution: string | null;
+    metadata: Record<string, unknown>;
+    provider: AnalyticsProvider | null;
+    provider_event_id: string | null;
+    created_at: Timestamp;
+}
+interface Insight {
+    id: UUID;
+    project_id: UUID;
+    flow_id: UUID | null;
+    type: InsightType;
+    severity: InsightSeverity;
+    title: string;
+    message: string;
+    suggested_action: string | null;
+    evidence: Record<string, unknown>;
+    revenue_impact: {
+        estimated_monthly_loss?: number;
+        confidence?: number;
+        affected_users?: number;
+    } | null;
+    status: InsightStatus;
+    resolved_by: UUID | null;
+    resolution_notes: string | null;
+    created_at: Timestamp;
+    acknowledged_at: Timestamp | null;
+    resolved_at: Timestamp | null;
+}
+interface Prediction {
+    id: UUID;
+    project_id: UUID;
+    flow_id: UUID;
+    pr_number: number | null;
+    commit_sha: string | null;
+    branch_name: string | null;
+    probability: number;
+    confidence: number;
+    reasoning: string | null;
+    based_on: PredictionBasis | null;
+    model_version: string | null;
+    features: Record<string, unknown>;
+    actual_result: TestStatus | null;
+    prediction_correct: boolean | null;
+    created_at: Timestamp;
+    validated_at: Timestamp | null;
+}
+interface PerceoEvent {
+    id: UUID;
+    project_id: UUID | null;
+    type: string;
+    payload: Record<string, unknown>;
+    source: EventSource | null;
+    processed: boolean;
+    processed_at: Timestamp | null;
+    created_at: Timestamp;
+}
+interface CodeChange {
+    id: UUID;
+    project_id: UUID;
+    base_sha: string;
+    head_sha: string;
+    branch_name: string | null;
+    pr_number: number | null;
+    files: {
+        path: string;
+        status: "added" | "modified" | "deleted" | "renamed";
+        additions?: number;
+        deletions?: number;
+    }[];
+    risk_level: RiskLevel | null;
+    risk_score: number | null;
+    affected_flow_ids: UUID[];
+    llm_analysis: {
+        summary?: string;
+        impacted_areas?: string[];
+        recommendations?: string[];
+    } | null;
+    created_at: Timestamp;
+    analyzed_at: Timestamp | null;
+}
+interface AnalyticsConnection {
+    id: UUID;
+    project_id: UUID;
+    provider: AnalyticsProvider;
+    provider_account_id: string | null;
+    config: Record<string, unknown>;
+    last_sync_at: Timestamp | null;
+    last_sync_status: SyncStatus | null;
+    last_sync_error: string | null;
+    events_synced_count: number;
+    sync_interval_seconds: number;
+    sync_enabled: boolean;
+    created_at: Timestamp;
+    updated_at: Timestamp;
+}
+interface ProjectApiKey {
+    id: UUID;
+    project_id: UUID;
+    name: string;
+    key_hash: string;
+    key_prefix: string;
+    scopes: ApiKeyScope[];
+    created_by: UUID | null;
+    created_at: Timestamp;
+    last_used_at: Timestamp | null;
+    last_used_ip: string | null;
+    expires_at: Timestamp | null;
+    revoked_at: Timestamp | null;
+    revoked_by: UUID | null;
+    revocation_reason: string | null;
+}
+interface ProjectApiKeyAudit {
+    id: UUID;
+    key_id: UUID;
+    action: "created" | "used" | "revoked" | "expired";
+    actor_id: UUID | null;
+    ip_address: string | null;
+    user_agent: string | null;
+    metadata: Record<string, unknown>;
+    created_at: Timestamp;
+}
+type ProjectInsert = Omit<Project, "id" | "created_at" | "updated_at"> & {
+    id?: UUID;
+};
+type PersonaInsert = Omit<Persona, "id" | "created_at" | "updated_at"> & {
+    id?: UUID;
+    behaviors?: Record<string, unknown>;
+};
+type FlowInsert = Omit<Flow, "id" | "created_at" | "updated_at" | "affected_by_changes" | "risk_score"> & {
+    id?: UUID;
+    affected_by_changes?: string[];
+    risk_score?: number;
+    graph_data?: Record<string, unknown>;
+    priority?: FlowPriority;
+    is_active?: boolean;
+};
+type StepInsert = Omit<Step, "id" | "created_at" | "updated_at"> & {
+    id?: UUID;
+    actions?: StepAction[];
+    expected_state?: StepExpectedState;
+    timeout_ms?: number;
+    retry_count?: number;
+};
+type TestRunInsert = Omit<TestRun, "id" | "created_at"> & {
+    id?: UUID;
+    screenshots?: string[];
+    logs?: unknown[];
+};
+type InsightInsert = Omit<Insight, "id" | "created_at" | "acknowledged_at" | "resolved_at"> & {
+    id?: UUID;
+    evidence?: Record<string, unknown>;
+    status?: InsightStatus;
+};
+type CodeChangeInsert = {
+    project_id: UUID;
+    base_sha: string;
+    head_sha: string;
+    files: {
+        path: string;
+        status: "added" | "modified" | "deleted" | "renamed";
+        additions?: number;
+        deletions?: number;
+    }[];
+    id?: UUID;
+    branch_name?: string | null;
+    pr_number?: number | null;
+    risk_level?: RiskLevel | null;
+    risk_score?: number | null;
+    affected_flow_ids?: UUID[];
+    llm_analysis?: {
+        summary?: string;
+        impacted_areas?: string[];
+        recommendations?: string[];
+    } | null;
+};
+type PerceoEventInsert = Omit<PerceoEvent, "id" | "created_at" | "processed" | "processed_at"> & {
+    id?: UUID;
+};
+type ProjectApiKeyInsert = {
+    project_id: UUID;
+    name: string;
+    key_hash: string;
+    key_prefix: string;
+    scopes: ApiKeyScope[];
+    created_by?: UUID | null;
+    expires_at?: Timestamp | null;
+};
+type ProjectApiKeyUpdate = {
+    name?: string;
+    scopes?: ApiKeyScope[];
+    expires_at?: Timestamp | null;
+    revoked_at?: Timestamp | null;
+    revoked_by?: UUID | null;
+    revocation_reason?: string | null;
+};
+type FlowUpdate = Partial<Omit<Flow, "id" | "project_id" | "created_at">>;
+type TestRunUpdate = Partial<Omit<TestRun, "id" | "project_id" | "created_at">>;
+type InsightUpdate = Partial<Omit<Insight, "id" | "project_id" | "created_at">>;
+interface FlowWithSteps extends Flow {
+    steps: Step[];
+}
+interface FlowWithMetrics extends Flow {
+    metrics: FlowMetrics | null;
+}
+interface TestRunWithFlow extends TestRun {
+    flow: Flow | null;
+}
+interface InsightWithFlow extends Insight {
+    flow: Flow | null;
+}
+type RealtimeEventType = "INSERT" | "UPDATE" | "DELETE";
+interface RealtimePayload<T> {
+    eventType: RealtimeEventType;
+    new: T;
+    old: T | null;
+    schema: string;
+    table: string;
+    commit_timestamp: string;
+}
+interface Database {
+    public: {
+        Tables: {
+            projects: {
+                Row: Project;
+                Insert: ProjectInsert;
+                Update: Partial<ProjectInsert>;
+            };
+            project_members: {
+                Row: ProjectMember;
+                Insert: Omit<ProjectMember, "created_at">;
+                Update: Partial<Omit<ProjectMember, "project_id" | "user_id" | "created_at">>;
+            };
+            personas: {
+                Row: Persona;
+                Insert: PersonaInsert;
+                Update: Partial<PersonaInsert>;
+            };
+            flows: {
+                Row: Flow;
+                Insert: FlowInsert;
+                Update: FlowUpdate;
+            };
+            steps: {
+                Row: Step;
+                Insert: StepInsert;
+                Update: Partial<StepInsert>;
+            };
+            flow_metrics: {
+                Row: FlowMetrics;
+                Insert: Omit<FlowMetrics, "id" | "updated_at">;
+                Update: Partial<Omit<FlowMetrics, "id" | "flow_id" | "updated_at">>;
+            };
+            test_runs: {
+                Row: TestRun;
+                Insert: TestRunInsert;
+                Update: TestRunUpdate;
+            };
+            analytics_events: {
+                Row: AnalyticsEvent;
+                Insert: Omit<AnalyticsEvent, "id" | "created_at">;
+                Update: never;
+            };
+            insights: {
+                Row: Insight;
+                Insert: InsightInsert;
+                Update: InsightUpdate;
+            };
+            predictions: {
+                Row: Prediction;
+                Insert: Omit<Prediction, "id" | "created_at" | "validated_at">;
+                Update: Partial<Omit<Prediction, "id" | "project_id" | "flow_id" | "created_at">>;
+            };
+            events: {
+                Row: PerceoEvent;
+                Insert: PerceoEventInsert;
+                Update: Partial<Omit<PerceoEvent, "id" | "created_at">>;
+            };
+            code_changes: {
+                Row: CodeChange;
+                Insert: CodeChangeInsert;
+                Update: Partial<Omit<CodeChange, "id" | "project_id" | "created_at">>;
+            };
+            analytics_connections: {
+                Row: AnalyticsConnection;
+                Insert: Omit<AnalyticsConnection, "id" | "created_at" | "updated_at">;
+                Update: Partial<Omit<AnalyticsConnection, "id" | "project_id" | "created_at">>;
+            };
+            project_api_keys: {
+                Row: ProjectApiKey;
+                Insert: ProjectApiKeyInsert;
+                Update: ProjectApiKeyUpdate;
+            };
+        };
+    };
+}
+
+/**
+ * Perceo Supabase Data Client
+ *
+ * Provides typed CRUD operations and realtime subscriptions for all Perceo tables.
+ * This client is used by the Observer Engine, CLI, and Dashboard.
+ */
+
+interface PerceoClientConfig {
+    supabaseUrl: string;
+    supabaseKey: string;
+    projectId?: string;
+}
+interface PerceoClientFromSupabaseConfig {
+    supabase: SupabaseClient;
+    projectId?: string;
+}
+declare class PerceoDataClient {
+    private readonly supabase;
+    private readonly projectId;
+    private channels;
+    constructor(config: PerceoClientConfig | PerceoClientFromSupabaseConfig);
+    /**
+     * Create a client from environment variables
+     */
+    static fromEnv(projectId?: string): PerceoDataClient;
+    /**
+     * Create a client that uses a specific user session for auth.
+     * All queries made through this client will run as that user.
+     */
+    static fromUserSession(params: {
+        supabaseUrl: string;
+        supabaseKey: string;
+        accessToken: string;
+        refreshToken: string;
+        projectId?: string;
+    }): Promise<PerceoDataClient>;
+    /**
+     * Get the underlying Supabase client (for advanced operations)
+     */
+    getSupabaseClient(): SupabaseClient;
+    /**
+     * Alias for getSupabaseClient() for backward compatibility
+     */
+    getClient(): SupabaseClient;
+    /**
+     * Store or update a project secret (LLM API keys, etc.)
+     * Only accessible with service role or by project admins
+     */
+    upsertProjectSecret(projectId: UUID, keyName: string, value: string, createdBy?: UUID): Promise<UUID>;
+    /**
+     * Get a project secret (service role only)
+     * This is typically called by backend services, not by end users
+     */
+    getProjectSecret(projectId: UUID, keyName: string): Promise<string | null>;
+    getProject(id: UUID): Promise<Project | null>;
+    getProjectByName(name: string): Promise<Project | null>;
+    createProject(project: ProjectInsert): Promise<Project>;
+    upsertProject(project: ProjectInsert): Promise<Project>;
+    updateProject(projectId: UUID, updates: Partial<ProjectInsert>): Promise<Project>;
+    /**
+     * Delete a project and all associated data (cascades to flows, steps, personas, API keys, etc.).
+     * Requires project admin/owner (enforced by RLS).
+     */
+    deleteProject(projectId: UUID): Promise<void>;
+    /**
+     * Get the current user's role for a project, or null if not a member.
+     * Use with a client that has user session set (e.g. fromUserSession).
+     */
+    getProjectMemberRole(projectId: UUID): Promise<ProjectRole | null>;
+    /**
+     * List members of a project. Requires project membership to view.
+     */
+    getProjectMembers(projectId?: string): Promise<ProjectMember[]>;
+    /**
+     * Add a user as a project member. Requires project admin or owner role.
+     */
+    addProjectMember(projectId: UUID, userId: UUID, role: ProjectRole): Promise<ProjectMember>;
+    /**
+     * Remove a member from a project. Requires project admin or owner role.
+     */
+    removeProjectMember(projectId: UUID, userId: UUID): Promise<void>;
+    getPersonas(projectId?: string): Promise<Persona[]>;
+    createPersona(persona: PersonaInsert): Promise<Persona>;
+    getPersonasBySource(source: "user_configured" | "auto_generated", projectId?: string): Promise<Persona[]>;
+    createUserConfiguredPersonas(personas: PersonaInsert[], projectId?: string): Promise<Persona[]>;
+    deleteAutoGeneratedPersonas(projectId?: string): Promise<void>;
+    getFlows(projectId?: string): Promise<Flow[]>;
+    getFlow(id: UUID): Promise<Flow | null>;
+    getFlowByName(name: string, projectId?: string): Promise<Flow | null>;
+    getFlowWithSteps(id: UUID): Promise<FlowWithSteps | null>;
+    getFlowWithMetrics(id: UUID): Promise<FlowWithMetrics | null>;
+    createFlow(flow: FlowInsert): Promise<Flow>;
+    updateFlow(id: UUID, updates: FlowUpdate): Promise<Flow>;
+    upsertFlow(flow: FlowInsert): Promise<Flow>;
+    upsertFlows(flows: FlowInsert[]): Promise<Flow[]>;
+    /**
+     * Get flows affected by recent code changes
+     */
+    getAffectedFlows(projectId?: string): Promise<Flow[]>;
+    /**
+     * Mark flows as affected by a code change
+     */
+    markFlowsAffected(flowIds: UUID[], changeId: string, riskScoreIncrement?: number): Promise<void>;
+    /**
+     * Clear affected changes from flows (e.g., after tests pass)
+     */
+    clearAffectedFlows(flowIds: UUID[]): Promise<void>;
+    getSteps(flowId: UUID): Promise<Step[]>;
+    createStep(step: StepInsert): Promise<Step>;
+    createSteps(steps: StepInsert[]): Promise<Step[]>;
+    getTestRuns(flowId: UUID, limit?: number): Promise<TestRun[]>;
+    getRecentTestRuns(projectId?: string, limit?: number): Promise<TestRun[]>;
+    createTestRun(testRun: TestRunInsert): Promise<TestRun>;
+    updateTestRun(id: UUID, updates: TestRunUpdate): Promise<TestRun>;
+    getInsights(projectId?: string, status?: string): Promise<Insight[]>;
+    getOpenInsights(projectId?: string): Promise<Insight[]>;
+    createInsight(insight: InsightInsert): Promise<Insight>;
+    updateInsight(id: UUID, updates: InsightUpdate): Promise<Insight>;
+    createCodeChange(change: CodeChangeInsert): Promise<CodeChange>;
+    getCodeChange(baseSha: string, headSha: string, projectId?: string): Promise<CodeChange | null>;
+    updateCodeChangeAnalysis(id: UUID, analysis: {
+        risk_level?: string;
+        risk_score?: number;
+        affected_flow_ids?: UUID[];
+        llm_analysis?: Record<string, unknown>;
+    }): Promise<CodeChange>;
+    publishEvent(event: Omit<PerceoEventInsert, "project_id"> & {
+        project_id?: UUID;
+    }): Promise<PerceoEvent>;
+    /**
+     * Publish a flow change event
+     */
+    publishFlowsAffected(changeId: string, affectedFlows: {
+        id: UUID;
+        name: string;
+        riskScore: number;
+    }[], source?: EventSource): Promise<PerceoEvent>;
+    /**
+     * Publish a test status event
+     */
+    publishTestStatus(testRunId: UUID, flowId: UUID, status: string, source?: EventSource): Promise<PerceoEvent>;
+    createPrediction(prediction: Omit<Prediction, "id" | "created_at" | "validated_at">): Promise<Prediction>;
+    getUnvalidatedPredictions(flowId: UUID): Promise<Prediction[]>;
+    getFlowMetrics(flowId: UUID): Promise<FlowMetrics | null>;
+    upsertFlowMetrics(flowId: UUID, metrics: Partial<Omit<FlowMetrics, "id" | "flow_id">>): Promise<FlowMetrics>;
+    /**
+     * Generate a new API key for a project
+     * Returns the full key (only shown once) and the created key record
+     */
+    createApiKey(projectId: UUID, options: {
+        name: string;
+        scopes: ApiKeyScope[];
+        expiresAt?: Date;
+        createdBy?: UUID;
+    }): Promise<{
+        key: string;
+        keyRecord: ProjectApiKey;
+    }>;
+    /**
+     * Get all API keys for a project (metadata only, no hashes)
+     */
+    getApiKeys(projectId?: string): Promise<Omit<ProjectApiKey, "key_hash">[]>;
+    /**
+     * Get active (non-revoked, non-expired) API keys for a project
+     */
+    getActiveApiKeys(projectId?: string): Promise<Omit<ProjectApiKey, "key_hash">[]>;
+    /**
+     * Validate an API key and return the project info if valid
+     */
+    validateApiKey(key: string): Promise<{
+        projectId: UUID;
+        scopes: ApiKeyScope[];
+        keyId: UUID;
+    } | null>;
+    /**
+     * Revoke an API key
+     */
+    revokeApiKey(keyId: UUID, options?: {
+        revokedBy?: UUID;
+        reason?: string;
+    }): Promise<ProjectApiKey>;
+    /**
+     * Delete an API key permanently
+     */
+    deleteApiKey(keyId: UUID): Promise<void>;
+    /**
+     * Check if an API key has a specific scope
+     */
+    hasApiKeyScope(keyId: UUID, scope: ApiKeyScope): Promise<boolean>;
+    /**
+     * Subscribe to flow changes (via Postgres CDC)
+     */
+    subscribeToFlows(projectId: string, callback: (payload: RealtimePayload<Flow>) => void): RealtimeChannel;
+    /**
+     * Subscribe to test run updates
+     */
+    subscribeToTestRuns(projectId: string, callback: (payload: RealtimePayload<TestRun>) => void): RealtimeChannel;
+    /**
+     * Subscribe to new insights
+     */
+    subscribeToInsights(projectId: string, callback: (payload: RealtimePayload<Insight>) => void): RealtimeChannel;
+    /**
+     * Subscribe to events (event bus)
+     */
+    subscribeToEvents(projectId: string, eventTypes: string[] | null, callback: (payload: RealtimePayload<PerceoEvent>) => void): RealtimeChannel;
+    /**
+     * Broadcast ephemeral messages (not persisted)
+     */
+    broadcast(channelName: string, event: string, payload: unknown): void;
+    /**
+     * Subscribe to broadcast messages
+     */
+    subscribeToBroadcast(channelName: string, event: string, callback: (payload: unknown) => void): RealtimeChannel;
+    /**
+     * Unsubscribe from a channel
+     */
+    unsubscribe(channelName: string): Promise<void>;
+    /**
+     * Unsubscribe from all channels
+     */
+    unsubscribeAll(): Promise<void>;
+    /**
+     * Cleanup - call when done with the client
+     */
+    cleanup(): Promise<void>;
+}
+
+/**
+ * Session data returned from magic-link auth flow.
+ * Callers add scope (project/global) when persisting.
+ */
+interface SupabaseAuthSession {
+    access_token: string;
+    refresh_token: string;
+    expires_at: number;
+    supabaseUrl: string;
+}
+declare function getSupabaseUrl(): string;
+declare function getSupabaseAnonKey(): string;
+declare function getSupabaseServiceRoleKey(): string | undefined;
+/**
+ * Create a Supabase client for auth. Uses PERCEO_SUPABASE_URL and PERCEO_SUPABASE_ANON_KEY.
+ */
+declare function createSupabaseAuthClient(): SupabaseClient;
+/**
+ * Exchange a redirect URL (with hash) from the magic link for a session and return session data for storage.
+ */
+declare function sessionFromRedirectUrl(supabase: SupabaseClient, redirectUrl: string): Promise<SupabaseAuthSession>;
+/**
+ * Send a magic link to the given email. Redirect will go to redirectUrl (must be allowed in Supabase dashboard).
+ */
+declare function sendMagicLink(supabase: SupabaseClient, email: string, redirectUrl: string): Promise<{
+    error: Error | null;
+}>;
+
+export { type AnalyticsConnection, type AnalyticsEvent, type AnalyticsProvider, type ApiKeyScope, type CodeChange, type CodeChangeInsert, type Database, type EventSource, type Flow, type FlowInsert, type FlowMetrics, type FlowPriority, type FlowUpdate, type FlowWithMetrics, type FlowWithSteps, type Insight, type InsightInsert, type InsightSeverity, type InsightStatus, type InsightType, type InsightUpdate, type InsightWithFlow, type PerceoClientConfig, PerceoDataClient, type PerceoEvent, type PerceoEventInsert, type Persona, type PersonaInsert, type Prediction, type PredictionBasis, type Project, type ProjectApiKey, type ProjectApiKeyAudit, type ProjectApiKeyInsert, type ProjectApiKeyUpdate, type ProjectInsert, type ProjectMember, type ProjectRole, type RealtimeEventType, type RealtimePayload, type RiskLevel, type Step, type StepAction, type StepExpectedState, type StepInsert, type SupabaseAuthSession, type SyncStatus, type TestRun, type TestRunInsert, type TestRunUpdate, type TestRunWithFlow, type TestStatus, type TestTrigger, type Timestamp, type UUID, createSupabaseAuthClient, getSupabaseAnonKey, getSupabaseServiceRoleKey, getSupabaseUrl, sendMagicLink, sessionFromRedirectUrl };