@realtimex/folio 0.1.2

package/dist/api/src/utils/Actuator.js

@@ -0,0 +1,225 @@
+import { createLogger } from "./logger.js";
+import { getServiceRoleSupabase } from "../services/supabase.js";
+import { 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) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function toVariableString(value) {
+    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, key) {
+    const existing = container[key];
+    if (isRecord(existing)) {
+        return existing;
+    }
+    const next = {};
+    container[key] = next;
+    return next;
+}
+export class Actuator {
+    static handlers = 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, handler) {
+        this.handlers.set(type, handler);
+    }
+    static mergeActionOutputs(runtimeData, runtimeVariables, actionType, actionIndex, outputs) {
+        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 = {
+            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, userId, eventType, state, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    details, supabaseClient) {
+        // 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 }) => {
+            if (error)
+                logger.warn("Failed to stream actuator log", { error });
+        });
+    }
+    /**
+     * Executes an array of abstract action definitions.
+     */
+    static async execute(ingestionId, userId, actions, data, file, fields = [], supabase) {
+        const result = {
+            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 = { ...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 = {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    action: action,
+                    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 = {
+                        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) {
+                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/dist/api/src/utils/actions/ActionHandler.js

@@ -0,0 +1 @@
+export {};

package/dist/api/src/utils/actions/AppendToGSheetAction.js

@@ -0,0 +1,191 @@
+import { GoogleSheetsService } from "../../services/GoogleSheetsService.js";
+import { pickString, pickColumns, interpolate } from "./utils.js";
+import { Actuator } from "../Actuator.js";
+const HEADER_ALIASES = {
+    amount: ["total_amount", "amount", "amount_due"],
+    total: ["total_amount", "amount", "amount_due"],
+    total_amount: ["amount", "amount_due"],
+    vendor: ["issuer", "merchant", "store_name", "seller"],
+    merchant: ["issuer", "vendor", "store_name", "seller"],
+    supplier: ["issuer", "vendor", "merchant"],
+    store: ["issuer", "vendor", "merchant", "store_name"],
+    document: ["document_type"],
+    type: ["document_type"],
+    category: ["document_type"],
+    issued_on: ["date"],
+    invoice_date: ["date"],
+    receipt_date: ["date"],
+    image_link: ["file_url", "drive_file_url", "file_link", "document_link"],
+    file_link: ["file_url", "drive_file_url", "image_link", "document_link"],
+    document_link: ["file_url", "drive_file_url", "file_link", "image_link"],
+    link: ["file_url", "drive_file_url", "file_link", "document_link", "image_link"],
+};
+function normalizeKey(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+}
+function buildNormalizedVariableLookup(variables) {
+    const lookup = {};
+    for (const [key, value] of Object.entries(variables)) {
+        const normalized = normalizeKey(key);
+        if (normalized && !(normalized in lookup)) {
+            lookup[normalized] = value;
+        }
+    }
+    return lookup;
+}
+function resolveHeaderValue(header, variables, normalizedVariables) {
+    const trimmed = header.trim();
+    if (!trimmed)
+        return "";
+    if (variables[trimmed] !== undefined) {
+        return variables[trimmed];
+    }
+    const normalizedHeader = normalizeKey(trimmed);
+    if (!normalizedHeader)
+        return "";
+    if (normalizedVariables[normalizedHeader] !== undefined) {
+        return normalizedVariables[normalizedHeader];
+    }
+    const aliases = HEADER_ALIASES[normalizedHeader] ?? [];
+    for (const alias of aliases) {
+        if (normalizedVariables[alias] !== undefined) {
+            return normalizedVariables[alias];
+        }
+    }
+    return "";
+}
+function isDropdownValueAllowed(value, allowedValues) {
+    const candidate = value.trim().toLowerCase();
+    if (!candidate)
+        return true;
+    return allowedValues.some((allowed) => allowed.trim().toLowerCase() === candidate);
+}
+function applyStrictDropdownGuards(headers, values, headerDropdowns) {
+    const nextValues = [...values];
+    const skippedColumns = [];
+    const maxColumns = Math.min(headers.length, nextValues.length);
+    for (let index = 0; index < maxColumns; index += 1) {
+        const dropdown = headerDropdowns[index];
+        if (!dropdown || dropdown.strict !== true || dropdown.allowedValues.length === 0) {
+            continue;
+        }
+        const currentValue = nextValues[index] ?? "";
+        if (!currentValue.trim())
+            continue;
+        if (isDropdownValueAllowed(currentValue, dropdown.allowedValues))
+            continue;
+        nextValues[index] = "";
+        skippedColumns.push(headers[index] || `column_${index + 1}`);
+    }
+    return { values: nextValues, skippedColumns };
+}
+export class AppendToGSheetAction {
+    async execute(context) {
+        const { ingestionId, userId, supabase } = context;
+        const result = {
+            success: true,
+            logs: [],
+            trace: [],
+        };
+        const spreadsheetReference = pickString(context.action, "spreadsheet_id") ??
+            pickString(context.action, "spreadsheet_url");
+        if (!spreadsheetReference) {
+            result.success = false;
+            result.error = "Missing required Action configuration: 'spreadsheet_id'";
+            return result;
+        }
+        const configuredRange = pickString(context.action, "range");
+        const columnTemplates = pickColumns(context.action, []);
+        let rangeToAppend = configuredRange;
+        let values = [];
+        let usedDynamicMapping = false;
+        if (columnTemplates.length > 0) {
+            values = columnTemplates.map((template) => interpolate(template, context.variables, context.data));
+            const templateResult = await GoogleSheetsService.resolveTemplate(context.userId, spreadsheetReference, configuredRange, context.supabase);
+            if (templateResult.success && (templateResult.headers?.length ?? 0) > 0) {
+                const dropdownGuard = applyStrictDropdownGuards(templateResult.headers ?? [], values, (templateResult.headerDropdowns ?? []));
+                values = dropdownGuard.values;
+                if (dropdownGuard.skippedColumns.length > 0) {
+                    result.logs.push(`Left ${dropdownGuard.skippedColumns.length} strict dropdown column(s) blank for human selection.`);
+                    result.trace.push({
+                        timestamp: new Date().toISOString(),
+                        step: "Adjusted strict dropdown columns",
+                        details: {
+                            skippedColumns: dropdownGuard.skippedColumns,
+                        },
+                    });
+                }
+            }
+        }
+        else {
+            const templateResult = await GoogleSheetsService.resolveTemplate(context.userId, spreadsheetReference, configuredRange, context.supabase);
+            if (!templateResult.success) {
+                result.success = false;
+                result.error = templateResult.error || "Failed to read Google Sheet template headers";
+                if (templateResult.errorDetails) {
+                    result.errorDetails = templateResult.errorDetails;
+                }
+                return result;
+            }
+            const headers = templateResult.headers ?? [];
+            if (headers.length === 0) {
+                result.success = false;
+                result.error = "Google Sheet template has no header row. Add column names in row 1.";
+                return result;
+            }
+            rangeToAppend = templateResult.range;
+            const normalizedVariables = buildNormalizedVariableLookup(context.variables);
+            values = headers.map((header) => resolveHeaderValue(header, context.variables, normalizedVariables));
+            const dropdownGuard = applyStrictDropdownGuards(headers, values, (templateResult.headerDropdowns ?? []));
+            values = dropdownGuard.values;
+            if (dropdownGuard.skippedColumns.length > 0) {
+                result.logs.push(`Left ${dropdownGuard.skippedColumns.length} strict dropdown column(s) blank for human selection.`);
+                result.trace.push({
+                    timestamp: new Date().toISOString(),
+                    step: "Adjusted strict dropdown columns",
+                    details: {
+                        skippedColumns: dropdownGuard.skippedColumns,
+                    },
+                });
+            }
+            usedDynamicMapping = true;
+            result.trace.push({
+                timestamp: new Date().toISOString(),
+                step: "Resolved Google Sheet template",
+                details: {
+                    spreadsheetId: templateResult.spreadsheetId,
+                    range: templateResult.range,
+                    headersCount: headers.length,
+                },
+            });
+            if (values.every((value) => value.trim().length === 0)) {
+                result.success = false;
+                result.error = "Unable to map extracted fields to Google Sheet headers. Provide explicit columns mapping or align header names with extracted keys.";
+                return result;
+            }
+        }
+        result.trace.push({
+            timestamp: new Date().toISOString(),
+            step: "Appending to Google Sheet",
+            details: { spreadsheetReference, range: rangeToAppend || "Sheet1", columnsCount: values.length, dynamicMapping: usedDynamicMapping },
+        });
+        const appendResult = await GoogleSheetsService.appendRow(context.userId, spreadsheetReference, rangeToAppend, values, context.supabase);
+        if (!appendResult.success) {
+            result.success = false;
+            result.error = appendResult.error;
+            if (appendResult.errorDetails) {
+                result.errorDetails = appendResult.errorDetails;
+            }
+            return result;
+        }
+        Actuator.logEvent(ingestionId, userId, "action", "Action Execution", {
+            action: "append_to_google_sheet",
+            spreadsheetId: appendResult.spreadsheetId ?? spreadsheetReference,
+            range: appendResult.range ?? rangeToAppend ?? "Sheet1",
+            columnsCount: values.length,
+            dynamicMapping: usedDynamicMapping,
+        }, supabase);
+        result.logs.push(`Appended ${values.length} columns to Google Sheet ${appendResult.spreadsheetId ?? spreadsheetReference} at ${appendResult.range ?? rangeToAppend ?? "Sheet1"}`);
+        return result;
+    }
+}

package/dist/api/src/utils/actions/AutoRenameAction.js

@@ -0,0 +1,49 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveFilename } from "./utils.js";
+import { Actuator } from "../Actuator.js";
+import { getServiceRoleSupabase } from "../../services/supabase.js";
+import { createLogger } from "../logger.js";
+const logger = createLogger("AutoRenameAction");
+export class AutoRenameAction {
+    async execute(context) {
+        const { file, variables, data, userId, ingestionId, supabase } = context;
+        const ext = path.extname(file.path);
+        const dir = path.dirname(file.path);
+        const stem = file.name.slice(0, file.name.length - ext.length);
+        logger.info("AutoRename variables", {
+            suggested_filename: variables.suggested_filename ?? "(missing)",
+            date: variables.date ?? "(missing)",
+            issuer: variables.issuer ?? "(missing)",
+            document_type: variables.document_type ?? "(missing)",
+        });
+        const newName = resolveFilename("auto", variables, stem, ext, data);
+        const newPath = path.join(dir, newName);
+        await new Promise((resolve, reject) => {
+            fs.rename(file.path, newPath, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+        const trace = [{
+                timestamp: new Date().toISOString(),
+                step: `Auto-Renamed file to ${newName}`,
+                details: { original: file.name, new: newName }
+            }];
+        logger.info(`AutoRename: '${file.name}' → '${newName}'`);
+        Actuator.logEvent(ingestionId, userId, "action", "Action Execution", { action: "auto_rename", original: file.name, new: newName }, supabase);
+        // Update DB so re-runs don't break
+        const db = supabase ?? getServiceRoleSupabase();
+        if (db) {
+            await db.from("ingestions").update({ storage_path: newPath, filename: newName }).eq("id", ingestionId);
+        }
+        return {
+            success: true,
+            newFileState: { path: newPath, name: newName },
+            logs: [`Auto-Renamed to '${newName}'`],
+            trace
+        };
+    }
+}

package/dist/api/src/utils/actions/CopyAction.js

@@ -0,0 +1,112 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pickString, interpolate, resolveFilename } from "./utils.js";
+import { Actuator } from "../Actuator.js";
+import { GoogleDriveService } from "../../services/GoogleDriveService.js";
+export class CopyAction {
+    async execute(context) {
+        const { action, file, variables, data, userId, ingestionId, supabase } = context;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const destination = pickString(action, "destination");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const pattern = pickString(action, "pattern");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const filenameConfig = pickString(action, "filename");
+        if (!destination) {
+            return {
+                success: false,
+                logs: [],
+                trace: [{ timestamp: new Date().toISOString(), step: "Copy failed: missing destination" }],
+                error: "Copy action requires a 'destination' config"
+            };
+        }
+        const destDir = interpolate(destination, variables, data);
+        // Support legacy gdrive:// destinations before copy_to_gdrive existed.
+        if (destDir.startsWith("gdrive://")) {
+            const folderPath = destDir.slice("gdrive://".length) || undefined;
+            let gdriveFileName;
+            if (filenameConfig) {
+                const ext = path.extname(file.name);
+                const stem = file.name.slice(0, file.name.length - ext.length);
+                gdriveFileName = resolveFilename(filenameConfig, variables, stem, ext, data);
+            }
+            const uploadResult = await GoogleDriveService.uploadFile(userId, file.path, folderPath, supabase, gdriveFileName);
+            if (!uploadResult.success) {
+                return {
+                    success: false,
+                    logs: [],
+                    trace: [{ timestamp: new Date().toISOString(), step: "Copy to Google Drive failed", details: { error: uploadResult.error } }],
+                    error: uploadResult.error || "Failed to upload to Google Drive"
+                };
+            }
+            const trace = [{
+                    timestamp: new Date().toISOString(),
+                    step: "Copied file to Google Drive",
+                    details: { original: file.path, driveFileId: uploadResult.fileId, destinationFolderId: folderPath }
+                }];
+            Actuator.logEvent(ingestionId, userId, "action", "Action Execution", { action: "copy_to_gdrive", destinationFolderId: folderPath ?? null, fileId: uploadResult.fileId }, supabase);
+            const fileId = uploadResult.fileId;
+            const fileUrl = `https://drive.google.com/file/d/${fileId}/view`;
+            const outputs = {
+                provider: "google_drive",
+                file_id: fileId,
+                file_url: fileUrl,
+                drive_file_id: fileId,
+                drive_file_url: fileUrl,
+                destination_folder_id: folderPath ?? null,
+                uploaded_file_name: gdriveFileName ?? file.name,
+            };
+            if (/\.(jpg|jpeg|png|webp|gif|bmp|tiff|tif|heic)$/i.test(file.name)) {
+                outputs.image_link = fileUrl;
+            }
+            return {
+                success: true,
+                logs: [`Copied to Google Drive (ID: ${uploadResult.fileId})`],
+                trace,
+                outputs,
+            };
+        }
+        fs.mkdirSync(destDir, { recursive: true });
+        const ext = path.extname(file.name);
+        const stem = file.name.slice(0, file.name.length - ext.length);
+        let newName;
+        if (filenameConfig) {
+            newName = resolveFilename(filenameConfig, variables, stem, ext, data);
+        }
+        else if (pattern) {
+            // Backward-compat: treat pattern as a filename template
+            newName = interpolate(pattern, variables, data);
+            if (!newName.endsWith(ext))
+                newName += ext;
+        }
+        else {
+            newName = file.name;
+        }
+        const newPath = path.join(destDir, newName);
+        await new Promise((resolve, reject) => {
+            fs.copyFile(file.path, newPath, (err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+        const trace = [{
+                timestamp: new Date().toISOString(),
+                step: `Copied file to ${newPath}`,
+                details: { original: file.path, copy: newPath }
+            }];
+        Actuator.logEvent(ingestionId, userId, "action", "Action Execution", { action: "copy", destination: destDir, newName }, supabase);
+        return {
+            success: true,
+            logs: [`Copied to '${newPath}'`],
+            trace,
+            outputs: {
+                provider: "local",
+                destination: destDir,
+                copied_path: newPath,
+                copied_name: newName,
+            },
+        };
+    }
+}

package/dist/api/src/utils/actions/CopyToGDriveAction.js

@@ -0,0 +1,55 @@
+import path from "node:path";
+import { pickString, interpolate, resolveFilename } from "./utils.js";
+import { Actuator } from "../Actuator.js";
+import { GoogleDriveService } from "../../services/GoogleDriveService.js";
+export class CopyToGDriveAction {
+    async execute(context) {
+        const { action, file, variables, data, userId, ingestionId, supabase } = context;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const destination = pickString(action, "destination");
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const filenameConfig = pickString(action, "filename");
+        const destDirId = destination ? interpolate(destination, variables, data) : undefined;
+        let resolvedFileName;
+        if (filenameConfig) {
+            const ext = path.extname(file.name);
+            const stem = file.name.slice(0, file.name.length - ext.length);
+            resolvedFileName = resolveFilename(filenameConfig, variables, stem, ext, data);
+        }
+        const uploadResult = await GoogleDriveService.uploadFile(userId, file.path, destDirId, supabase, resolvedFileName);
+        if (!uploadResult.success) {
+            return {
+                success: false,
+                logs: [],
+                trace: [{ timestamp: new Date().toISOString(), step: "Copy to Google Drive failed", details: { error: uploadResult.error } }],
+                error: uploadResult.error || "Failed to upload to Google Drive"
+            };
+        }
+        const trace = [{
+                timestamp: new Date().toISOString(),
+                step: `Copied file to Google Drive`,
+                details: { original: file.path, driveFileId: uploadResult.fileId, destinationFolderId: destDirId }
+            }];
+        Actuator.logEvent(ingestionId, userId, "action", "Action Execution", { action: "copy_to_gdrive", destinationFolderId: destDirId ?? null, fileId: uploadResult.fileId }, supabase);
+        const fileId = uploadResult.fileId;
+        const fileUrl = `https://drive.google.com/file/d/${fileId}/view`;
+        const outputs = {
+            provider: "google_drive",
+            file_id: fileId,
+            file_url: fileUrl,
+            drive_file_id: fileId,
+            drive_file_url: fileUrl,
+            destination_folder_id: destDirId ?? null,
+            uploaded_file_name: resolvedFileName ?? file.name,
+        };
+        if (/\.(jpg|jpeg|png|webp|gif|bmp|tiff|tif|heic)$/i.test(file.name)) {
+            outputs.image_link = fileUrl;
+        }
+        return {
+            success: true,
+            logs: [`Copied to Google Drive (ID: ${uploadResult.fileId})`],
+            trace,
+            outputs,
+        };
+    }
+}