Client Overview

The workflows-client library provides an easy way to interact with the Workflows API.

Initialization

To use the client, you need to create an instance of WorkflowsClient.

import { WorkflowsClient } from '@picsart/workflows-client';

const workflows = new WorkflowsClient({
    apiKey: 'Bearer <YOUR_API_KEY>'
})

Example in Miniapp SDK context

import { WorkflowsClient } from '@picsart/workflows-client';

const workflows = new WorkflowsClient({
    baseUrl: apiprocess.env.REACT_APP_API_URL,
    fetch: getContext().utils.api.fetch,
    getRemoteSettings: getContext().handlers.getRemoteSettings
})

Basic Usage

The below example will execute the example-task workflow and return its result

const params = {}; // request body
const result = await workflows.run<MyResponseType>('example-task', params);

Execution Modes

The service supports three execution modes:

Asynchronous Mode (Default)

Async is the default mode, where the task executed asynchronously with polling to check for completion.

const result = await workflows.run<MyResponseType>(
    'example-task',
    params,
    {
        mode: ExecutionMode.ASYNC, // Optional: Execution mode 
        pollingInterval: 300, // Optional: Custom polling interval in ms
        retriesCount: 150,    // Optional: Number of max polling attempts
        onAccepted: (taskId) => console.log('Task accepted:', taskId), // optional 
        onPartialResult: (response) => console.log('Progress:', response) // optional
    }
);

Synchronous Mode

Use sync mode if the task is expected to complete quickly (typically under 5 seconds).

const result = await workflows.run<MyResponseType>(
    'example-task',
    params,
    {mode: ExecutionMode.SYNC}
);

Stream Mode

Stream mode maintains a persistent connection and provides intermediate results in real-time. This mode is ideal when updates need to be delivered with minimal delay

import { WorkflowEvent } from '@picsart/workflows-client';

const result = await workflows.run<MyResponseType>(
    'example-task',
    params,
    {
        mode: ExecutionMode.STREAM,
        onEvent: (event: WorkflowEvent) => console.log('Event received: ', event)
    },
);

Here onEvent is triggered whenever the task fires custom event (it is not triggered by framework-native events) Consequently, the redundant event. prefix is omitted from the event.type

Please note that the return value might differ from the one returned in sync/async modes as due to specifics of streaming implementations, some tasks don't compute the final aggregated result and return empty result instead.

Settings Integration

The executeTask method supports an optional executionOptions.remoteSettingName parameter, which allows you to specify the name of the Remote Setting where your workflow configuration is defined.

If not provided, the default setting name will be: ${taskName}_api

By default, the execution options defined in the Remote Setting will override the options explicitly passed to the executeTask method.