@vertesia/workflow 1.0.0-dev.20260203.130115Z → 1.0.0-dev.20260225.024852Z

package/src/activities/media/transcribeMediaWithGladia.ts

@@ -9,6 +9,7 @@ import { TextExtractionResult, TextExtractionStatus } from "../../index.js";
 export interface TranscriptMediaParams {
     environmentId?: string;
     force?: boolean;
+    output_storage_path?: string;
 }
 
 export interface TranscriptMedia extends DSLActivitySpec<TranscriptMediaParams> {
@@ -28,39 +29,59 @@ const GLADIA_URL = "https://api.gladia.io/v2";
 
 export async function transcribeMedia(payload: DSLActivityExecutionPayload<TranscriptMediaParams>): Promise<TranscriptMediaResult> {
 
-    const { params, client, objectId } = await setupActivity<TranscriptMediaParams>(payload);
+    const context = await setupActivity<TranscriptMediaParams>(payload);
+    const { params, client, inputType } = context;
 
     const gladiaConfig = await client.projects.integrations.retrieve(payload.project_id, SupportedIntegrations.gladia) as GladiaConfiguration | undefined;
     if (!gladiaConfig || !gladiaConfig.enabled) {
         return {
             hasText: false,
-            objectId,
+            objectId: inputType === 'objectIds' ? context.objectId : undefined,
             status: TextExtractionStatus.error,
             error: "Gladia integration not enabled",
         }
     }
 
-    const object = await client.objects.retrieve(objectId, "+text");
     const gladiaClient = new FetchClient(gladiaConfig.url ?? GLADIA_URL);
     gladiaClient.withHeaders({ "x-gladia-key": gladiaConfig.api_key });
 
-    if (object.text && !params.force) {
-        return { hasText: true, objectId, status: TextExtractionStatus.skipped, message: "text already present and force not enabled" }
-    }
+    let mediaSource: string;
+    let storageId: string;
 
-    if (!object.content?.source) {
-        throw new DocumentNotFoundError(`No source found for object ${objectId}`);
-    }
+    if (inputType === 'objectIds') {
+        // Object mode: fetch from object store
+        const objectId = context.objectId;
+        const object = await client.objects.retrieve(objectId, "+text");
+
+        if (object.text && !params.force) {
+            return { hasText: true, objectId, status: TextExtractionStatus.skipped, message: "text already present and force not enabled" }
+        }
+
+        if (!object.content?.source) {
+            throw new DocumentNotFoundError(`No source found for object ${objectId}`);
+        }
 
-    // Check for audio rendition in video metadata (preferred for videos)
-    let mediaSource: string = object.content.source;
-    if (object.metadata?.type === ContentNature.Video) {
-        const videoMetadata = object.metadata as VideoMetadata;
-        const audioRendition = videoMetadata.renditions?.find(r => r.name === AUDIO_RENDITION_NAME);
-        if (audioRendition?.content?.source) {
-            mediaSource = audioRendition.content.source;
-            log.info(`Found audio rendition for video object ${objectId}`, { mediaSource });
+        // Check for audio rendition in video metadata (preferred for videos)
+        mediaSource = object.content.source;
+        if (object.metadata?.type === ContentNature.Video) {
+            const videoMetadata = object.metadata as VideoMetadata;
+            const audioRendition = videoMetadata.renditions?.find(r => r.name === AUDIO_RENDITION_NAME);
+            if (audioRendition?.content?.source) {
+                mediaSource = audioRendition.content.source;
+                log.info(`Found audio rendition for video object ${objectId}`, { mediaSource });
+            }
         }
+
+        storageId = objectId;
+    } else {
+        // File mode: use file input
+        const file = context.file;
+        if (!params.output_storage_path) {
+            throw new DocumentNotFoundError("output_storage_path is required when using file input");
+        }
+
+        mediaSource = file.url;
+        storageId = params.output_storage_path;
     }
 
     // Get download URL for the media source
@@ -70,12 +91,12 @@ export async function transcribeMedia(payload: DSLActivityExecutionPayload<Trans
         throw new DocumentNotFoundError(`Error fetching media URL for ${mediaSource}`);
     }
 
-    log.info(`Using media URL for transcription`, { objectId, mediaUrl: mediaSource });
+    log.info(`Using media URL for transcription`, { storageId, mediaUrl: mediaSource });
 
     const taskToken = Buffer.from(activityInfo().taskToken).toString('base64url');
-    const callbackUrl = generateCallbackUrlForGladia(client.store.baseUrl, taskToken, objectId);
+    const callbackUrl = generateCallbackUrlForGladia(client.store.baseUrl, taskToken);
 
-    log.info(`Transcribing media ${mediaUrl} with Gladia`, { objectId, callbackUrl });
+    log.info(`Transcribing media ${mediaUrl} with Gladia`, { storageId, callbackUrl });
 
     try {
         const res = await gladiaClient.post("/transcription", {
@@ -90,25 +111,25 @@ export async function transcribeMedia(payload: DSLActivityExecutionPayload<Trans
                 }
             }
         }) as GladiaTranscriptRequestResponse;
-        log.info(`Transcription request sent to Gladia`, { objectId, res });
+        log.info(`Transcription request sent to Gladia`, { storageId, res });
     } catch (error: any) {
         if (error instanceof RequestError && error.status === 422) {
             return {
                 hasText: false,
-                objectId,
+                objectId: storageId,
                 status: TextExtractionStatus.error,
                 error: `Gladia transcription error: ${error.message}`,
             }
         }
-        log.error(`Error sending transcription request to Gladia for object ${objectId}`, { error });
+        log.error(`Error sending transcription request to Gladia for storage ${storageId}`, { error });
         throw error;
     }
 
     throw new CompleteAsyncError();
 }
 
-function generateCallbackUrlForGladia(baseUrl: string, taskToken: string, objectId: string) {
-    return `${baseUrl}/webhooks/gladia/${objectId}?task_token=${taskToken}`;
+function generateCallbackUrlForGladia(baseUrl: string, taskToken: string) {
+    return `${baseUrl}/webhooks/gladia?task_token=${taskToken}`;
 }
 
 interface GladiaTranscriptRequestResponse {

package/src/activities/notifyWebhook.test.ts

@@ -1,9 +1,9 @@
 import {
   MockActivityEnvironment,
 } from "@temporalio/testing";
-import { ContentEventName, DSLActivityExecutionPayload } from "@vertesia/common";
+import { ApiVersions, ContentEventName, DSLActivityExecutionPayload, WebHookSpec } from "@vertesia/common";
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
-import { notifyWebhook, NotifyWebhookParams } from "./notifyWebhook.js";
+import { notifyWebhook, NotifyWebhookParams, WebhookNotificationPayload } from "./notifyWebhook.js";
 
 // Mock fetch globally
 vi.stubGlobal('fetch', vi.fn());
@@ -63,10 +63,15 @@ describe("Webhook should be notified", () => {
     const payload = createTestPayload();
     const res = await testEnv.run(notifyWebhook, payload);
 
-    // Verify fetch was called with correct parameters
+    // Verify fetch was called with correct parameters (old format wraps detail in result)
     expect(mockFetch).toHaveBeenCalledWith(defaultParams.webhook, {
       method: 'POST',
-      body: JSON.stringify({ message: 'Hello World' }),
+      body: JSON.stringify({
+        workflowId: 'wf_id',
+        runId: 'wf_run_id',
+        status: 'completed',
+        result: { message: 'Hello World' }
+      }),
       headers: {
         'Content-Type': 'application/json',
       },
@@ -98,10 +103,15 @@ describe("Webhook should be notified", () => {
       `Webhook Notification to ${defaultParams.webhook} failed with status: 500 Internal Server Error - Response: {"error": "Database connection failed", "code": "DB_ERROR"}`
     );
 
-    // Verify fetch was called with correct parameters
+    // Verify fetch was called with correct parameters (old format wraps detail in result)
     expect(mockFetch).toHaveBeenCalledWith(defaultParams.webhook, {
       method: 'POST',
-      body: JSON.stringify({ message: 'Hello World' }),
+      body: JSON.stringify({
+        workflowId: 'wf_id',
+        runId: 'wf_run_id',
+        status: 'completed',
+        result: { message: 'Hello World' }
+      }),
       headers: {
         'Content-Type': 'application/json',
       },
@@ -121,14 +131,117 @@ describe("Webhook should be notified", () => {
     // Expect the function to throw the network error
     await expect(testEnv.run(notifyWebhook, payload)).rejects.toThrow('Network request failed');
 
-    // Verify fetch was called with correct parameters
+    // Verify fetch was called with correct parameters (old format wraps detail in result)
     expect(mockFetch).toHaveBeenCalledWith(defaultParams.webhook, {
       method: 'POST',
-      body: JSON.stringify({ message: 'Hello World' }),
+      body: JSON.stringify({
+        workflowId: 'wf_id',
+        runId: 'wf_run_id',
+        status: 'completed',
+        result: { message: 'Hello World' }
+      }),
       headers: {
         'Content-Type': 'application/json',
       },
     });
   });
 
+  it("test POST with undefined detail still sends body with workflow info (new format)", async () => {
+    // Mock successful response
+    const mockResponse = {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      url: 'https://vertesia.test'
+    };
+    mockFetch.mockResolvedValueOnce(mockResponse as Response);
+
+    // Create webhook spec with version to use new format
+    const webhookSpec: WebHookSpec = {
+      url: 'https://vertesia.test',
+      version: ApiVersions.COMPLETION_RESULT_V1
+    };
+
+    // Create payload with undefined detail (like workflow_failed events)
+    const payload = createTestPayload({
+      webhook: webhookSpec,
+      detail: undefined,
+      event_name: 'workflow_failed'
+    });
+
+    const res = await testEnv.run(notifyWebhook, payload);
+
+    // Verify fetch was called
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [_url, options] = mockFetch.mock.calls[0];
+
+    // Verify the body parameter is NOT undefined
+    expect(options?.body).toBeDefined();
+
+    // Verify the body contains workflow info
+    const bodyData = JSON.parse(options?.body as string) as WebhookNotificationPayload;
+    expect(bodyData.workflow_id).toBe('wf_id');
+    expect(bodyData.workflow_name).toBe('wfFuncName');
+    expect(bodyData.workflow_run_id).toBe('wf_run_id');
+    expect(bodyData.event_name).toBe('workflow_failed');
+    // detail should not be present when undefined (JSON.stringify omits it)
+    expect(bodyData.detail).toBeUndefined();
+
+    // Verify Content-Type header is set
+    const headers = options?.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBe('application/json');
+
+    // Verify response
+    expect(res).toEqual({
+      status: 200,
+      message: 'OK',
+      url: webhookSpec.url
+    });
+  });
+
+  it("test POST with undefined detail still sends body with workflow info (old format)", async () => {
+    // Mock successful response
+    const mockResponse = {
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      url: 'https://vertesia.test'
+    };
+    mockFetch.mockResolvedValueOnce(mockResponse as Response);
+
+    // Create payload with string webhook (old format) and undefined detail
+    const payload = createTestPayload({
+      webhook: 'https://vertesia.test',
+      detail: undefined,
+      event_name: 'workflow_completed'
+    });
+
+    const res = await testEnv.run(notifyWebhook, payload);
+
+    // Verify fetch was called
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [_url, options] = mockFetch.mock.calls[0];
+
+    // Verify the body parameter is NOT undefined
+    expect(options?.body).toBeDefined();
+
+    // Verify the body contains workflow info in old format
+    const bodyData = JSON.parse(options?.body as string);
+    expect(bodyData.workflowId).toBe('wf_id');
+    expect(bodyData.runId).toBe('wf_run_id');
+    expect(bodyData.status).toBe('completed');
+    expect(bodyData.result).toBeNull(); // null when detail is undefined
+
+    // Verify Content-Type header is set
+    const headers = options?.headers as Record<string, string>;
+    expect(headers['Content-Type']).toBe('application/json');
+
+    // Verify response
+    expect(res).toEqual({
+      status: 200,
+      message: 'OK',
+      url: 'https://vertesia.test'
+    });
+  });
+
 });

package/src/activities/notifyWebhook.ts

@@ -45,7 +45,7 @@ export async function notifyWebhook(payload: DSLActivityExecutionPayload<NotifyW
 
     if (!target_url) throw new WorkflowParamNotFoundError('target_url');
 
-    const hasBody = params.detail && method === 'POST'; //body is sent only for POST
+    const hasBody = method === 'POST'; //body is sent only for POST, always includes workflow info
 
     const headers = {
         ...defaultHeaders,
@@ -194,6 +194,14 @@ async function createOldRequestBody(payload: WorkflowExecutionBaseParams, params
                 result: result || null
             }
         };
+    } else {
+        // Always include workflow metadata in old format, even when detail is undefined
+        data = {
+            workflowId: params.workflow_id,
+            runId: params.workflow_run_id,
+            status: params.event_name === 'workflow_completed' ? 'completed' : params.event_name,
+            result: data || null
+        };
     }
-    return JSON.stringify(data || {});
+    return JSON.stringify(data);
 }

package/src/activities/renditions/generateImageRendition.ts

@@ -31,7 +31,7 @@ export async function generateImageRendition(
         format: originParams.format || (originParams as any).format_output || "png", // Default to png if format is missing
     };
 
-    log.info(`Generating image rendition for ${objectId}`, {
+    log.debug(`Generating image rendition for ${objectId}`, {
         originParams,
         params,
     });
@@ -79,7 +79,7 @@ export async function generateImageRendition(
         client,
         inputObject.content.source,
     );
-    log.info(`Image ${objectId} copied to ${imageFile}`);
+    log.debug(`Image ${objectId} copied to ${imageFile}`);
     renditionPages.push(imageFile);
 
 

package/src/conversion/image.test.ts

@@ -7,6 +7,7 @@ import { expect, test, vi, describe } from "vitest";
 // Mock Temporal activity context
 vi.mock("@temporalio/activity", () => ({
     log: {
+        debug: vi.fn(),
         info: vi.fn(),
         warn: vi.fn(),
         error: vi.fn(),

package/src/conversion/image.ts

@@ -24,7 +24,7 @@ export async function imageResizer(
     colorspaceCorrection: boolean = true,
     colorspace: 'RGB' | 'LAB' | 'LUV' | 'sigmoidal' = 'RGB'
 ): Promise<string> {
-    log.info(`[image-resizer] Resizing image: ${inputPath} to max_hw: ${max_hw}, format: ${format}, progressive: ${progressive}, colorspaceCorrection: ${colorspaceCorrection ? colorspace : 'disabled'}`);
+    log.debug(`[image-resizer] Resizing image: ${inputPath} to max_hw: ${max_hw}, format: ${format}, progressive: ${progressive}, colorspaceCorrection: ${colorspaceCorrection ? colorspace : 'disabled'}`);
 
     const allowedFormats = ["jpg", "jpeg", "png", "webp"];
 
@@ -63,17 +63,17 @@ export async function imageResizer(
             const lowerFormat = format.toLowerCase();
             if (lowerFormat === "jpg" || lowerFormat === "jpeg") {
                 conversionOption = "-interlace JPEG";
-                log.info(`Enabling interlaced ${lowerFormat.toUpperCase()} format`);
+                log.debug(`Enabling interlaced ${lowerFormat.toUpperCase()} format`);
             } else if (lowerFormat === "png") {
                 conversionOption = "-interlace PNG";
-                log.info(`Enabling interlaced ${lowerFormat.toUpperCase()} format`);
+                log.debug(`Enabling interlaced ${lowerFormat.toUpperCase()} format`);
             } else if (lowerFormat === "gif") {
                 conversionOption = "-interlace GIF";
-                log.info(`Enabling interlaced ${lowerFormat.toUpperCase()} format`);
+                log.debug(`Enabling interlaced ${lowerFormat.toUpperCase()} format`);
             }
         }
 
-        log.info(`Resizing image using ImageMagick: ${inputPath} -> ${outputPath}`);
+        log.debug(`Resizing image using ImageMagick: ${inputPath} -> ${outputPath}`);
 
         const command = `convert`
         let args = [inputPath];
@@ -92,26 +92,26 @@ export async function imageResizer(
                     // Linear light, recommended default
                     // Convert from sRGB to linear RGB for processing
                     args.push("-colorspace", "RGB");
-                    log.info("Using linear RGB colorspace for resize processing");
+                    log.debug("Using linear RGB colorspace for resize processing");
                     break;
                 case 'LAB':
                     // Perceptual linear light
                     // Use LAB colorspace which separates intensity from color
                     // Better for avoiding color clipping and distortion
                     args.push("-colorspace", "LAB");
-                    log.info("Using LAB colorspace for resize processing");
+                    log.debug("Using LAB colorspace for resize processing");
                     break;
                 case 'LUV':
                     // Perceptual linear light
                     // Alternative to LAB with perceptually uniform color deltas
                     args.push("-colorspace", "LUV");
-                    log.info("Using LUV colorspace for resize processing");
+                    log.debug("Using LUV colorspace for resize processing");
                     break;
                 case 'sigmoidal':
                     // Sigmoidal colorspace modification to reduce ringing artifacts
                     args.push("-colorspace", "RGB");
                     args.push("+sigmoidal-contrast", "6.5,50%");
-                    log.info("Using sigmoidal contrast modification for resize processing");
+                    log.debug("Using sigmoidal contrast modification for resize processing");
                     break;
             }
         }
@@ -144,7 +144,7 @@ export async function imageResizer(
         // Output path
         args.push(outputPath);
 
-        log.info(`ImageMagick command: ${command} ${args.join(" ")}`);
+        log.debug(`ImageMagick command: ${command} ${args.join(" ")}`);
 
         const { stderr } = await execFile(command, args);
 

package/src/dsl/dsl-workflow.ts

@@ -20,14 +20,15 @@ import {
     DSLWorkflowSpec,
     getDocumentIds,
     getTenantId,
-    WorkflowExecutionPayload
+    WorkflowExecutionPayload,
+    WorkflowInputFile
 } from "@vertesia/common";
 import ms, { StringValue } from 'ms';
 import { HandleDslErrorParams } from "../activities/handleError.js";
 import * as activities from "../activities/index.js";
+import { RateLimitParams } from "../activities/rateLimiter.js";
 import { WF_NON_RETRYABLE_ERRORS, WorkflowParamNotFoundError } from "../errors.js";
 import { Vars } from "./vars.js";
-import { RateLimitParams } from "../activities/rateLimiter.js";
 
 
 interface BaseActivityPayload extends WorkflowExecutionPayload {
@@ -49,6 +50,23 @@ export async function dslWorkflow(payload: DSLWorkflowExecutionPayload) {
     if (!definition) {
         throw new WorkflowParamNotFoundError("workflow");
     }
+
+    // Normalize input: convert legacy objectIds format to new input format
+    if (!payload.input && payload.objectIds) {
+        payload.input = {
+            inputType: 'objectIds',
+            objectIds: payload.objectIds
+        };
+    }
+
+    // Validate that workflow has input
+    if (!payload.input && !payload.objectIds) {
+        throw new WorkflowParamNotFoundError(
+            "input",
+            definition
+        );
+    }
+
     // the base payload will be used to create the activities payload
     const basePayload: BaseActivityPayload = {
         ...payload,
@@ -73,12 +91,33 @@ export async function dslWorkflow(payload: DSLWorkflowExecutionPayload) {
     });
     const defaultProxy = proxyActivities(defaultOptions);
     log.debug("Default activity proxy is ready");
-    // merge default vars with the payload vars and add objectIds and objectId
+
+    // Merge default vars with the payload vars and add input variables
+    const inputType = payload.input?.inputType || 'objectIds';
+
+    // Extract objectIds and files based on input type
+    let objectIds: string[] = [];
+    let files: WorkflowInputFile[] = [];
+
+    if (payload.input) {
+        if (payload.input.inputType === 'objectIds') {
+            objectIds = payload.input.objectIds;
+        } else if (payload.input.inputType === 'files') {
+            files = payload.input.files;
+        }
+    }
+
     const vars = new Vars({
         ...definition.vars,
         ...payload.vars,
-        objectIds: payload.objectIds || [],
-        objectId: payload.objectIds ? payload.objectIds[0] : undefined
+        // Add input type variables
+        inputType,
+        // Add objectIds variables (for objectIds input or backward compatibility)
+        objectIds,
+        objectId: objectIds[0],
+        // Add files variables (for files input)
+        files,
+        file: files[0],
     });
 
     log.info("Executing workflow", { payload });
@@ -290,9 +329,10 @@ async function runActivity(activity: DSLActivitySpec, basePayload: BaseActivityP
         log.info("Activity skipped: condition not satisfied", activity.condition);
         return;
     }
+
     const importParams = vars.createImportVars(activity.import);
     const executionPayload = dslActivityPayload(basePayload, activity, importParams);
-    log.info("Executing activity: " + activity.name, { payload: executionPayload });
+    log.debug("Executing activity: " + activity.name, { payload: executionPayload });
 
     let proxy = defaultProxy;
     if (activity.options) {
@@ -324,7 +364,7 @@ async function runActivity(activity: DSLActivitySpec, basePayload: BaseActivityP
     ];
 
     if (activity.name && rateLimitedActivities.includes(activity.name)) {
-        log.info(`Applying rate limit for activity ${activity.name}`);
+        log.debug(`Applying rate limit for activity ${activity.name}`);
         // Apply rate limiting logic here
          // Check rate limit first - loop until no delay
         const rateLimitParams = buildRateLimitParams(activity, executionPayload);
@@ -333,7 +373,7 @@ async function runActivity(activity: DSLActivitySpec, basePayload: BaseActivityP
         let rateLimitResult = await proxy.checkRateLimit(rateLimitPayload);
     
         while (rateLimitResult.delayMs > 0) {
-            log.info(`Rate limit delay applied: ${rateLimitResult.delayMs}ms`);
+            log.debug(`Rate limit delay applied: ${rateLimitResult.delayMs}ms`);
             await sleep(rateLimitResult.delayMs);
 
             // Check again after sleeping
@@ -346,7 +386,7 @@ async function runActivity(activity: DSLActivitySpec, basePayload: BaseActivityP
         //TODO execute in parallel
         log.info("Parallel execution not yet implemented");
     } else {
-        log.info("Executing activity: " + activity.name, { importParams });
+        log.debug("Executing activity: " + activity.name, { importParams });
         const result = await fn(executionPayload);
         if (activity.output) {
             vars.setValue(activity.output, result);

package/src/dsl/setup/ActivityContext.ts

@@ -5,10 +5,13 @@ import {
     DSLWorkflowExecutionPayload,
     Project,
     WorkflowExecutionPayload,
+    WorkflowInputType,
+    WorkflowInputFile,
 } from "@vertesia/common";
 import {
     DocumentNotFoundError,
     WorkflowParamNotFoundError,
+    WorkflowExecutionError,
 } from "../../errors.js";
 import { getProjectFromToken } from "../../utils/auth.js";
 import { getVertesiaClient } from "../../utils/client.js";
@@ -99,6 +102,76 @@ export class ActivityContext<ParamsT extends Record<string, any>> {
         return workflowId;
     }
 
+    /**
+     * Get the workflow input type (objectIds or files).
+     * Defaults to 'objectIds' for backward compatibility with legacy format.
+     */
+    get inputType(): WorkflowInputType {
+        return this.payload.input?.inputType || 'objectIds';
+    }
+
+    /**
+     * Get the first file from the workflow input.
+     * Only available when workflow input type is 'files'.
+     * @throws {WorkflowExecutionError} If input type is not 'files'
+     * @throws {WorkflowParamNotFoundError} If files array is empty
+     */
+    get file(): WorkflowInputFile {
+        const input = this.payload.input;
+        if (!input || input.inputType !== 'files') {
+            throw new WorkflowExecutionError(
+                'Activity expects files but received objectIds'
+            );
+        }
+        // TypeScript now knows input is { inputType: 'files', files: WorkflowInputFile[] }
+        const files = input.files;
+        if (!files || files.length === 0) {
+            log.error("No files found in payload");
+            throw new WorkflowParamNotFoundError(
+                "files[0]",
+                (
+                    this
+                        .payload as WorkflowExecutionPayload as DSLWorkflowExecutionPayload
+                ).workflow,
+            );
+        }
+        return files[0];
+    }
+
+    /**
+     * Get all files from the workflow input.
+     * Only available when workflow input type is 'files'.
+     * @throws {WorkflowExecutionError} If input type is not 'files'
+     */
+    get files(): WorkflowInputFile[] {
+        const input = this.payload.input;
+        if (!input || input.inputType !== 'files') {
+            throw new WorkflowExecutionError(
+                'Activity expects files but received objectIds'
+            );
+        }
+        // TypeScript now knows input is { inputType: 'files', files: WorkflowInputFile[] }
+        return input.files;
+    }
+
+    /**
+     * Generic accessor for the first input (objectId or file URL).
+     * Use this in dual-mode activities that support both input types.
+     * For files, returns the URL of the first file.
+     */
+    get input(): string {
+        return this.inputType === 'objectIds' ? this.objectId : this.file.url;
+    }
+
+    /**
+     * Generic accessor for all inputs (objectIds or file URLs).
+     * Use this in dual-mode activities that support both input types.
+     * For files, returns an array of URLs.
+     */
+    get inputs(): string[] {
+        return this.inputType === 'objectIds' ? (this.objectIds || []) : this.files.map(f => f.url);
+    }
+
     fetchProject() {
         if (!this._project) {
             this._project = _fetchProject(this.client, this.payload);

package/src/dsl.ts

@@ -1,3 +1,4 @@
 export * from "./dsl/dslProxyActivities.js";
 export * from "./errors.js";
 export * from "./result-types.js";
+

package/src/errors.ts

@@ -91,6 +91,19 @@ export class TokenExpiredError extends ApplicationFailure {
     }
 }
 
+export class WorkflowExecutionError extends ApplicationFailure {
+    constructor(
+        message: string,
+        public workflow?: DSLWorkflowSpec,
+    ) {
+        super(
+            message,
+            "WorkflowExecutionError",
+            true, // non-retryable
+        );
+    }
+}
+
 export const WF_NON_RETRYABLE_ERRORS = [
     "DocumentNotFoundError",
     "ActivityParamInvalidError",
@@ -99,4 +112,5 @@ export const WF_NON_RETRYABLE_ERRORS = [
     "InvalidContentTypeError",
     "TokenExpiredError",
     "ZenoClientNotFoundError",
+    "WorkflowExecutionError",
 ];