Workflows

A workflow is a directed graph of jobs. Each job takes a source — an uploaded file or the output of an upstream job — applies an ordered list of operations, and produces downloadable output. The whole graph runs server-side and reaches a single terminal state.

You rarely build that graph by hand. The file-first API (client.file(path) for one input, client.files([paths]) for many) hides upload, workflow construction, and waiting behind a fluent chain — it is the recommended path. createWorkflow(...) is the low-level escape hatch for hand-built job DAGs.

File-first hides the graph

The fluent chain builds and submits the workflow for you:

TypeScript
PHP
Python
Rust

const result = await client
  .file('./photo.jpg')
  .compress(OptimizeFor.Balanced)
  .run({ maxWait: '5m' });

$result = $client
    ->file('./photo.jpg')
    ->compress(OptimizeFor::Balanced)
    ->run(new RunOptions(maxWait: '5m'));

Jobs and sources

When you need full control over the payload, the low-level surface composes a workflow out of jobs, each with an explicit source. Source factories cover the common shapes:

TypeScript factory	PHP factory	Use when the source is…
`uploadSource(fileId)`	`Sources::upload($fileId)`	one freshly uploaded file
`jobOutputSource(from, operation?)`	`Sources::jobOutput($from, $operation)`	the output of an earlier job in the same workflow (chaining)
`externalImportSource(externalSourceId)`	`Sources::externalImport($externalSourceId)`	a one-shot external-import token
`connectionSource(connectionId, path)`	`Sources::connection($connectionId, $path)`	a file on a configured storage connection

You label a job with an optional id so a downstream jobOutputSource(from) / Sources::jobOutput($from) can reference it. The server echoes that label back as ref on response and download objects, so you read results back by ref. Omit id and the server generates one.

TypeScript
PHP
Python
Rust

import { OperationType, uploadSource } from '@giveitsmaller/sdk';

const upload = await client.uploadFile('./photo.jpg');
const workflow = await client.createWorkflow({
  jobs: [
    {
      id: 'out',
      source: uploadSource(upload.fileId),
      operations: [{ type: OperationType.compress, options: { quality: 80 } }],
    },
  ],
});

use Gisl\Sdk\Sources;
use Gisl\Sdk\Generated\SdkSpec\Enums\OperationType;

$upload = $client->uploadFile('./photo.jpg');
$workflow = $client->createWorkflow([
    'jobs' => [
        [
            'id' => 'out',
            'source' => Sources::upload($upload->fileId),
            'operations' => [
                ['type' => OperationType::compress, 'options' => ['quality' => 80]],
            ],
        ],
    ],
]);

Getting results back

A workflow can return results in increasing order of decoupling:

Wait — run() blocks until the workflow reaches a terminal state and projects the outputs for you.
Stream — subscribe to live progress over Server-Sent Events.
Poll — submit() returns a handle you re-check later, or fetch the per-job download URLs once the workflow is terminal.
Webhook — register a callback_url and the API posts to it at lifecycle events; nothing keeps your process alive.

File-first hides the graph​

Jobs and sources​

Getting results back​

See also​

File-first hides the graph

Jobs and sources

Getting results back

See also