@realtimex/folio 0.1.2

package/api/src/services/SDKService.ts

@@ -0,0 +1,249 @@
+import { RealtimeXSDK, ProvidersResponse } from "@realtimex/sdk";
+
+import { createLogger } from "../utils/logger.js";
+
+const logger = createLogger("SDKService");
+
+export interface ProviderResult {
+  provider: string;
+  model: string;
+  isDefaultFallback?: boolean;
+}
+
+export class SDKService {
+  private static instance: RealtimeXSDK | null = null;
+  private static initAttempted = false;
+
+  // Default provider/model configuration
+  // realtimexai routes through RealTimeX Desktop to user's configured providers
+  static readonly DEFAULT_LLM_PROVIDER = "realtimexai";
+  static readonly DEFAULT_LLM_MODEL = "gpt-4o-mini";
+  static readonly DEFAULT_EMBED_PROVIDER = "realtimexai";
+  static readonly DEFAULT_EMBED_MODEL = "text-embedding-3-small";
+
+  static initialize(): RealtimeXSDK {
+    if (!this.instance && !this.initAttempted) {
+      this.initAttempted = true;
+
+      try {
+        this.instance = new RealtimeXSDK({
+          realtimex: {
+            // @ts-ignore Desktop dev bridge key
+            apiKey: "SXKX93J-QSWMB04-K9E0GRE-J5DA8J0"
+          },
+          permissions: [
+            "api.agents",       // List agents
+            "api.workspaces",   // List workspaces
+            "api.threads",      // List threads
+            "webhook.trigger",  // Trigger agents
+            "activities.read",  // Read activities
+            "activities.write", // Write activities
+            "llm.chat",         // Chat completion
+            "llm.embed",        // Generate embeddings
+            "llm.providers",    // List LLM providers (chat, embed)
+            "vectors.read",     // Query vectors
+            "vectors.write",    // Store vectors
+          ]
+        });
+
+        logger.info("RealTimeX SDK initialized successfully");
+
+        // @ts-ignore ping available in desktop bridge
+        this.instance.ping?.().catch(() => {
+          logger.warn("Desktop ping failed during startup");
+        });
+      } catch (error) {
+        logger.error("Failed to initialize SDK", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        this.instance = null;
+      }
+    }
+
+    return this.instance!;
+  }
+
+  static getSDK(): RealtimeXSDK | null {
+    if (!this.instance && !this.initAttempted) {
+      this.initialize();
+    }
+    return this.instance;
+  }
+
+  static async isAvailable(): Promise<boolean> {
+    try {
+      const sdk = this.getSDK();
+      if (!sdk) return false;
+
+      // Try to ping first (faster)
+      try {
+        // @ts-ignore ping available in desktop bridge
+        await sdk.ping();
+        return true;
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (e) {
+        // Fallback to providers check if ping not available/fails
+        await sdk.llm.chatProviders();
+        return true;
+      }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (error: any) {
+      logger.warn("SDK not available", { error: error.message });
+      return false;
+    }
+  }
+
+  /**
+   * Helper to wrap a promise with a timeout
+   */
+  static async withTimeout<T>(promise: Promise<T>, timeoutMs: number, errorMessage: string): Promise<T> {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let timeoutHandle: any;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutHandle = setTimeout(() => reject(new Error(errorMessage)), timeoutMs);
+    });
+
+    try {
+      const result = await Promise.race([promise, timeoutPromise]);
+      return result as T;
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  // Cache for default providers (avoid repeated SDK calls)
+  private static defaultChatProvider: ProviderResult | null = null;
+  private static defaultEmbedProvider: ProviderResult | null = null;
+
+  /**
+   * Get default chat provider/model from SDK dynamically
+   */
+  static async getDefaultChatProvider(): Promise<ProviderResult> {
+    // Return cached if available
+    if (this.defaultChatProvider) {
+      return this.defaultChatProvider;
+    }
+
+    const sdk = this.getSDK();
+    if (!sdk) {
+      return {
+        provider: this.DEFAULT_LLM_PROVIDER,
+        model: this.DEFAULT_LLM_MODEL,
+        isDefaultFallback: true
+      };
+    }
+
+    try {
+      const { providers } = await this.withTimeout<ProvidersResponse>(
+        sdk.llm.chatProviders(),
+        30000,
+        "Chat providers fetch timed out"
+      );
+
+      if (!providers || providers.length === 0) {
+        throw new Error("No LLM providers available");
+      }
+
+      const preferred = providers.find((item) => item.provider === this.DEFAULT_LLM_PROVIDER);
+      const chosen = preferred || providers[0];
+      const model = chosen.models?.[0]?.id || this.DEFAULT_LLM_MODEL;
+
+      this.defaultChatProvider = {
+        provider: chosen.provider,
+        model,
+        isDefaultFallback: !preferred
+      };
+      return this.defaultChatProvider;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (error: any) {
+      logger.warn("Failed to get default chat provider from SDK", error);
+      return {
+        provider: this.DEFAULT_LLM_PROVIDER,
+        model: this.DEFAULT_LLM_MODEL,
+        isDefaultFallback: true
+      };
+    }
+  }
+
+  /**
+   * Get default embedding provider/model from SDK dynamically
+   */
+  static async getDefaultEmbedProvider(): Promise<ProviderResult> {
+    if (this.defaultEmbedProvider) {
+      return this.defaultEmbedProvider;
+    }
+
+    const sdk = this.getSDK();
+    if (!sdk) {
+      return {
+        provider: this.DEFAULT_EMBED_PROVIDER,
+        model: this.DEFAULT_EMBED_MODEL,
+        isDefaultFallback: true
+      };
+    }
+
+    try {
+      const { providers } = await this.withTimeout<ProvidersResponse>(
+        sdk.llm.embedProviders(),
+        30000,
+        "Embed providers fetch timed out"
+      );
+
+      if (!providers || providers.length === 0) {
+        throw new Error("No embedding providers available");
+      }
+
+      const preferred = providers.find((p) => p.provider === this.DEFAULT_EMBED_PROVIDER);
+      const chosen = preferred || providers[0];
+      const model = chosen.models?.[0]?.id || this.DEFAULT_EMBED_MODEL;
+
+      this.defaultEmbedProvider = {
+        provider: chosen.provider,
+        model,
+        isDefaultFallback: !preferred
+      };
+      return this.defaultEmbedProvider;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    } catch (error: any) {
+      logger.warn("Failed to get default embed provider from SDK", error);
+      return {
+        provider: this.DEFAULT_EMBED_PROVIDER,
+        model: this.DEFAULT_EMBED_MODEL,
+        isDefaultFallback: true
+      };
+    }
+  }
+
+  /**
+   * Resolve LLM provider/model - use settings if available, otherwise use defaults
+   */
+  static async resolveChatProvider(settings: { llm_provider?: string; llm_model?: string }): Promise<ProviderResult> {
+    if (settings.llm_provider && settings.llm_model) {
+      return {
+        provider: settings.llm_provider,
+        model: settings.llm_model,
+        isDefaultFallback: false
+      };
+    }
+    return await this.getDefaultChatProvider();
+  }
+
+  /**
+   * Resolve embedding provider/model - use settings if available, otherwise use defaults
+   */
+  static async resolveEmbedProvider(settings: { embedding_provider?: string; embedding_model?: string }): Promise<ProviderResult> {
+    if (settings.embedding_provider && settings.embedding_model) {
+      return {
+        provider: settings.embedding_provider,
+        model: settings.embedding_model,
+        isDefaultFallback: false
+      };
+    }
+    return await this.getDefaultEmbedProvider();
+  }
+
+  static clearProviderCache(): void {
+    this.defaultChatProvider = null;
+    this.defaultEmbedProvider = null;
+  }
+}

package/api/src/services/supabase.ts

@@ -0,0 +1,113 @@
+import { createClient, SupabaseClient } from "@supabase/supabase-js";
+
+import { config } from "../config/index.js";
+import { createLogger } from "../utils/logger.js";
+
+const logger = createLogger("SupabaseService");
+
+let serverClient: SupabaseClient | null = null;
+let lastConfigHash = "";
+
+export function isValidUrl(url: string): boolean {
+  return url.startsWith("http://") || url.startsWith("https://");
+}
+
+function isValidAnonKey(key: string): boolean {
+  return key.startsWith("eyJ") || key.startsWith("sb_publishable_");
+}
+
+function getConfigHash() {
+  return `${config.supabase.url}_${config.supabase.anonKey}`;
+}
+
+export function getServerSupabase(forceRefresh = false): SupabaseClient | null {
+  const currentHash = getConfigHash();
+
+  if (serverClient && !forceRefresh && currentHash === lastConfigHash) {
+    return serverClient;
+  }
+
+  const url = config.supabase.url;
+  const key = config.supabase.anonKey;
+
+  if (!url || !key || !isValidUrl(url)) {
+    return null;
+  }
+
+  try {
+    serverClient = createClient(url, key, {
+      auth: {
+        autoRefreshToken: false,
+        persistSession: false
+      }
+    });
+    lastConfigHash = currentHash;
+    logger.info("Server Supabase client initialized");
+    return serverClient;
+  } catch (error) {
+    logger.error("Failed to initialize server Supabase client", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return null;
+  }
+}
+
+export function getServiceRoleSupabase(): SupabaseClient | null {
+  const url = config.supabase.url;
+  const key = config.supabase.serviceRoleKey;
+
+  if (!url || !key || !isValidUrl(url)) {
+    return null;
+  }
+
+  try {
+    return createClient(url, key, {
+      auth: {
+        autoRefreshToken: false,
+        persistSession: false
+      }
+    });
+  } catch (error) {
+    logger.error("Failed to initialize service-role Supabase client", {
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return null;
+  }
+}
+
+export function getSupabaseConfigFromHeaders(headers: Record<string, unknown>): {
+  url: string;
+  anonKey: string;
+} | null {
+  const url = String(headers["x-supabase-url"] || "");
+  const anonKey = String(headers["x-supabase-anon-key"] || "");
+
+  if (!url || !anonKey || !isValidUrl(url) || !isValidAnonKey(anonKey)) {
+    return null;
+  }
+
+  return { url, anonKey };
+}
+
+export interface UserSettings {
+  id: string;
+  user_id: string;
+  llm_provider: string | null;
+  llm_model: string | null;
+  vision_model_capabilities: Record<string, unknown> | null;
+  sync_interval_minutes: number;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface ProcessingJob {
+  id: string;
+  user_id: string;
+  status: "queued" | "running" | "completed" | "failed";
+  source_type: string;
+  payload: Record<string, unknown>;
+  runtime_key: string | null;
+  error_message: string | null;
+  created_at: string;
+  updated_at: string;
+}

package/api/src/utils/Actuator.ts

@@ -0,0 +1,284 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { createLogger } from "./logger.js";
+import type { ExtractField } from "../services/PolicyLoader.js";
+import { getServiceRoleSupabase } from "../services/supabase.js";
+import { ActionHandler, ActionContext } from "./actions/ActionHandler.js";
+import { ActionInput, ExtractedData, deriveVariables } from "./actions/utils.js";
+
+import { RenameAction } from "./actions/RenameAction.js";
+import { AutoRenameAction } from "./actions/AutoRenameAction.js";
+import { CopyAction } from "./actions/CopyAction.js";
+import { CopyToGDriveAction } from "./actions/CopyToGDriveAction.js";
+import { AppendToGSheetAction } from "./actions/AppendToGSheetAction.js";
+import { LogCsvAction } from "./actions/LogCsvAction.js";
+import { NotifyAction } from "./actions/NotifyAction.js";
+import { WebhookAction } from "./actions/WebhookAction.js";
+
+const logger = createLogger("Actuator");
+
+let warnedMissingServiceRole = false;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function toVariableString(value: unknown): string | undefined {
+    if (value == null) return undefined;
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    try {
+        return JSON.stringify(value);
+    } catch {
+        return undefined;
+    }
+}
+
+function ensureRecord(container: ExtractedData, key: string): Record<string, unknown> {
+    const existing = container[key];
+    if (isRecord(existing)) {
+        return existing;
+    }
+    const next: Record<string, unknown> = {};
+    container[key] = next;
+    return next;
+}
+
+export interface ActuatorResult {
+    success: boolean;
+    actionsExecuted: string[];
+    errors: string[];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    trace: { timestamp: string; step: string; details?: any }[];
+}
+
+export class Actuator {
+    private static handlers: Map<string, ActionHandler> = new Map([
+        ["rename", new RenameAction()],
+        ["auto_rename", new AutoRenameAction()],
+        ["copy", new CopyAction()],
+        ["copy_to_gdrive", new CopyToGDriveAction()],
+        ["append_to_google_sheet", new AppendToGSheetAction()],
+        ["log_csv", new LogCsvAction()],
+        ["notify", new NotifyAction()],
+        ["webhook", new WebhookAction()],
+    ]);
+
+    static registerAction(type: string, handler: ActionHandler) {
+        this.handlers.set(type, handler);
+    }
+
+    private static mergeActionOutputs(
+        runtimeData: ExtractedData,
+        runtimeVariables: Record<string, string>,
+        actionType: string,
+        actionIndex: number,
+        outputs: Record<string, unknown>
+    ): string[] {
+        const outputKeys = Object.keys(outputs);
+        if (outputKeys.length === 0) return outputKeys;
+
+        const actionsByType = ensureRecord(runtimeData, "_actions");
+        const previousByType = actionsByType[actionType];
+        const mergedByType = {
+            ...(isRecord(previousByType) ? previousByType : {}),
+            ...outputs,
+        };
+        actionsByType[actionType] = mergedByType;
+
+        const history = Array.isArray(runtimeData._action_history) ? [...runtimeData._action_history] : [];
+        const historyEntry: Record<string, unknown> = {
+            index: actionIndex,
+            type: actionType,
+            ...outputs,
+        };
+        history.push(historyEntry);
+        runtimeData._action_history = history;
+        runtimeData._last = historyEntry;
+        runtimeData._last_action_type = actionType;
+        runtimeVariables._last_action_type = actionType;
+
+        for (const key of outputKeys) {
+            const value = outputs[key];
+            const serialized = toVariableString(value);
+
+            if (runtimeData[key] === undefined) {
+                runtimeData[key] = value;
+            }
+
+            if (serialized === undefined) continue;
+
+            runtimeVariables[`${actionType}.${key}`] = serialized;
+            runtimeVariables[`_actions.${actionType}.${key}`] = serialized;
+            runtimeVariables[`_last.${key}`] = serialized;
+
+            if (runtimeVariables[key] === undefined) {
+                runtimeVariables[key] = serialized;
+            }
+        }
+
+        return outputKeys;
+    }
+
+    static async logEvent(
+        ingestionId: string | null,
+        userId: string | null,
+        eventType: "info" | "action" | "error" | "analysis",
+        state: string,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        details: any,
+        supabaseClient?: SupabaseClient | null
+    ) {
+        // Fire and forget, don't await blocking execution
+        const supabase = supabaseClient ?? getServiceRoleSupabase();
+        if (!supabase) {
+            if (!warnedMissingServiceRole) {
+                logger.warn("Service-role Supabase client unavailable; skipping processing_events stream writes.");
+                warnedMissingServiceRole = true;
+            }
+            return;
+        }
+
+        void supabase.from("processing_events").insert({
+            ingestion_id: ingestionId ?? null,
+            user_id: userId ?? null,
+            event_type: eventType,
+            agent_state: state,
+            details,
+        }).then(({ error }: { error: unknown }) => {
+            if (error) logger.warn("Failed to stream actuator log", { error });
+        });
+    }
+
+    /**
+     * Executes an array of abstract action definitions.
+     */
+    static async execute(
+        ingestionId: string,
+        userId: string,
+        actions: ActionInput[],
+        data: ExtractedData,
+        file: { path: string; name: string },
+        fields: ExtractField[] = [],
+        supabase?: SupabaseClient | null
+    ): Promise<ActuatorResult> {
+        const result: ActuatorResult = {
+            success: true,
+            actionsExecuted: [],
+            errors: [],
+            trace: [],
+        };
+
+        result.trace.push({ timestamp: new Date().toISOString(), step: "Initializing Actuator", details: { actionsCount: actions.length } });
+        Actuator.logEvent(ingestionId, userId, "info", "Actuator Initialized", { actionsCount: actions.length }, supabase);
+
+        // Convert the 13-digit Dropzone timestamp into a human-readable local time
+        // (e.g. "1772148849046-bill.pdf" -> "2026-02-26_15-34-09_bill.pdf")
+        // Note: only `currentFile.name` is normalized; `file.path` (disk path) is unchanged.
+        const tsMatch = file.name.match(/^(\d{13})-(.*)$/);
+        let currentFile = { ...file };
+        if (tsMatch) {
+            const date = new Date(parseInt(tsMatch[1], 10));
+            const yyyy = date.getFullYear();
+            const MM = String(date.getMonth() + 1).padStart(2, "0");
+            const dd = String(date.getDate()).padStart(2, "0");
+            const HH = String(date.getHours()).padStart(2, "0");
+            const mm = String(date.getMinutes()).padStart(2, "0");
+            const ss = String(date.getSeconds()).padStart(2, "0");
+            currentFile.name = `${yyyy}-${MM}-${dd}_${HH}-${mm}-${ss}_${tsMatch[2]}`;
+        }
+
+        const runtimeData: ExtractedData = { ...data };
+        const runtimeVariables = deriveVariables(runtimeData, fields);
+        runtimeData.current_file_name = currentFile.name;
+        runtimeData.current_file_path = currentFile.path;
+        runtimeVariables.current_file_name = currentFile.name;
+        runtimeVariables.current_file_path = currentFile.path;
+
+        for (const [actionIndex, action] of actions.entries()) {
+            const handler = this.handlers.get(action.type);
+
+            if (!handler) {
+                const msg = `Action failed: Unsupported action type '${action.type}'`;
+                logger.error(msg);
+                result.errors.push(msg);
+                result.success = false;
+                result.trace.push({ timestamp: new Date().toISOString(), step: `Unsupported action type`, details: { type: action.type } });
+                Actuator.logEvent(ingestionId, userId, "error", "Action Execution", { action: action.type, error: msg }, supabase);
+                continue;
+            }
+
+            try {
+                runtimeData.current_file_name = currentFile.name;
+                runtimeData.current_file_path = currentFile.path;
+                runtimeVariables.current_file_name = currentFile.name;
+                runtimeVariables.current_file_path = currentFile.path;
+
+                const context: ActionContext = {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    action: action as any,
+                    data: runtimeData,
+                    file: currentFile,
+                    variables: runtimeVariables,
+                    userId,
+                    ingestionId,
+                    supabase,
+                };
+
+                const handlerResult = await handler.execute(context);
+
+                result.trace.push(...handlerResult.trace);
+
+                if (handlerResult.success) {
+                    if (handlerResult.newFileState) {
+                        currentFile = handlerResult.newFileState;
+                        runtimeData.current_file_name = currentFile.name;
+                        runtimeData.current_file_path = currentFile.path;
+                        runtimeVariables.current_file_name = currentFile.name;
+                        runtimeVariables.current_file_path = currentFile.path;
+                    }
+                    if (handlerResult.outputs && Object.keys(handlerResult.outputs).length > 0) {
+                        const outputKeys = this.mergeActionOutputs(
+                            runtimeData,
+                            runtimeVariables,
+                            action.type,
+                            actionIndex,
+                            handlerResult.outputs
+                        );
+                        result.trace.push({
+                            timestamp: new Date().toISOString(),
+                            step: "Captured action outputs",
+                            details: {
+                                action: action.type,
+                                outputKeys,
+                            },
+                        });
+                    }
+                    result.actionsExecuted.push(...handlerResult.logs);
+                } else {
+                    const msg = `Action failed (${action.type}): ${handlerResult.error}`;
+                    logger.error(msg);
+                    result.errors.push(msg);
+                    result.success = false;
+                    const eventDetails: Record<string, unknown> = {
+                        action: action.type,
+                        error: handlerResult.error,
+                    };
+                    if (handlerResult.errorDetails && Object.keys(handlerResult.errorDetails).length > 0) {
+                        Object.assign(eventDetails, handlerResult.errorDetails);
+                    }
+                    Actuator.logEvent(ingestionId, userId, "error", "Action Execution", eventDetails, supabase);
+                }
+            } catch (err: unknown) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                const msg = `Action failed (${action.type}): ${errMsg}`;
+                logger.error(msg);
+                result.errors.push(msg);
+                result.success = false;
+                result.trace.push({ timestamp: new Date().toISOString(), step: `Action execution error`, details: { type: action.type, error: errMsg } });
+                Actuator.logEvent(ingestionId, userId, "error", "Action Execution", { action: action.type, error: errMsg }, supabase);
+            }
+        }
+
+        return result;
+    }
+}

package/api/src/utils/actions/ActionHandler.ts

@@ -0,0 +1,34 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import { PolicyAction } from "../../services/PolicyLoader.js";
+import type { ExtractedData } from "./utils.js";
+
+export interface TraceLog {
+    timestamp: string;
+    step: string;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    details?: any;
+}
+
+export interface ActionContext {
+    action: PolicyAction;
+    data: ExtractedData;
+    file: { path: string; name: string };
+    variables: Record<string, string>;
+    userId: string;
+    ingestionId: string;
+    supabase?: SupabaseClient | null;
+}
+
+export interface ActionResult {
+    success: boolean;
+    newFileState?: { path: string; name: string };
+    logs: string[];
+    trace: TraceLog[];
+    outputs?: Record<string, unknown>;
+    error?: string;
+    errorDetails?: Record<string, unknown>;
+}
+
+export interface ActionHandler {
+    execute(context: ActionContext): Promise<ActionResult>;
+}