TypeScript SDK

Run FlowMason pipelines from TypeScript/JavaScript applications with full streaming and async support.

FlowMason provides a TypeScript/JavaScript SDK for programmatic pipeline execution in Node.js and browser environments.

Installation

npm install @flowmason/sdk

Quick Start

import { FlowMason } from '@flowmason/sdk';

const fm = new FlowMason({
  studioUrl: 'http://localhost:8999/api/v1',
  apiKey: process.env.FLOWMASON_API_KEY,
});

// Run a pipeline
const result = await fm.run('pipeline-id', {
  query: 'Hello, world!',
});

console.log(result.output);

Configuration

const fm = new FlowMason({
  // Studio API URL (default: http://localhost:8999/api/v1)
  studioUrl: 'https://studio.example.com/api/v1',

  // API key for authentication
  apiKey: 'sk-...',

  // Organization ID for multi-tenant setups
  orgId: 'org-123',

  // Default timeout in milliseconds (default: 300000)
  timeout: 60000,

  // Custom headers for all requests
  headers: {
    'X-Custom-Header': 'value',
  },
});

Environment Variables

The SDK automatically reads these environment variables:

Running Pipelines

Basic Execution

const result = await fm.run('pipeline-id', {
  query: 'Generate content about AI',
  options: { temperature: 0.7 },
});

if (result.success) {
  console.log('Output:', result.output);
  console.log('Tokens used:', result.usage?.totalTokens);
  console.log('Cost:', result.usage?.totalCostUsd);
} else {
  console.error('Failed:', result.error);
}

Run by Name

// Latest version
const result = await fm.runByName('content-generator', { topic: 'AI' });

// Specific version
const result = await fm.runByName('[email protected]', { topic: 'AI' });

Run Options

const result = await fm.run('pipeline-id', { input: 'data' }, {
  // Trace ID for observability
  traceId: 'trace-123',

  // Override timeout
  timeout: 120000,

  // Callback URL for completion notification
  callbackUrl: 'https://myapp.com/webhook/flowmason',

  // Run asynchronously (returns immediately with run ID)
  async: true,

  // Output routing configuration
  outputConfig: {
    destinations: [
      {
        type: 'webhook',
        config: { url: 'https://myapp.com/data' },
        onSuccess: true,
      },
    ],
  },
});

Streaming Execution

Get real-time updates during pipeline execution:

const result = await fm.runWithStream(
  'pipeline-id',
  { input: 'data' },
  {
    onStageStart: (stage) => {
      console.log(`Starting stage: ${stage.stageName}`);
    },

    onStageComplete: (stage) => {
      console.log(`Completed: ${stage.stageId}`);
      console.log(`Duration: ${stage.durationMs}ms`);
    },

    onStageError: (stage) => {
      console.error(`Stage failed: ${stage.stageId}`);
      console.error(`Error: ${stage.error}`);
    },

    onProgress: (progress) => {
      console.log(`Progress: ${progress.percentComplete}%`);
    },

    onComplete: (result) => {
      console.log('Pipeline complete!');
      console.log('Output:', result.output);
    },

    onError: (error) => {
      console.error('Pipeline failed:', error.message);
    },
  }
);

Async Execution with Polling

// Start async run
const initialResult = await fm.run(
  'pipeline-id',
  { input: 'data' },
  { async: true }
);

console.log('Started run:', initialResult.runId);

// Poll for completion
const finalResult = await fm.waitForCompletion(initialResult.runId, {
  pollInterval: 2000,  // Check every 2 seconds
  timeout: 300000,     // 5 minute timeout
});

console.log('Completed:', finalResult.output);

Pipeline Management

List Pipelines

const { items, total, hasMore } = await fm.listPipelines({
  status: 'published',
  category: 'content',
  search: 'generator',
  limit: 20,
});

for (const pipeline of items) {
  console.log(`${pipeline.name} v${pipeline.version}`);
}

Get Pipeline Details

const pipeline = await fm.getPipeline('pipeline-id');

console.log('Name:', pipeline.name);
console.log('Stages:', pipeline.stages.length);
console.log('Input Schema:', pipeline.inputSchema);

Validate Input

const { valid, errors } = await fm.validatePipeline('pipeline-id', {
  query: 'test input',
});

if (!valid) {
  console.error('Validation errors:', errors);
}

Run History

const { items: runs } = await fm.listRuns({
  pipelineId: 'pipeline-id',
  status: 'completed',
  startDate: '2024-01-01',
  limit: 100,
});

for (const run of runs) {
  console.log(`${run.runId}: ${run.status} (${run.durationMs}ms)`);
}

// Get detailed run info
const run = await fm.getRun('run-id');
console.log('Output:', run.output);
console.log('Cost: $', run.usage.totalCostUsd.toFixed(4));

Error Handling

import { FlowMason, FlowMasonError } from '@flowmason/sdk';

try {
  const result = await fm.run('pipeline-id', { input: 'data' });
} catch (error) {
  if (error instanceof FlowMasonError) {
    console.error('Code:', error.code);
    console.error('Status:', error.status);
    console.error('Details:', error.details);

    switch (error.code) {
      case 'PIPELINE_NOT_FOUND':
        // Handle missing pipeline
        break;
      case 'VALIDATION_ERROR':
        // Handle invalid input
        break;
      case 'TIMEOUT':
        // Handle timeout
        break;
    }
  }
}

TypeScript Types

Full TypeScript support with exported types:

import type {
  FlowMasonConfig,
  Pipeline,
  PipelineResult,
  Component,
  StageResult,
  UsageMetrics,
  RunOptions,
  StreamCallbacks,
} from '@flowmason/sdk';

function handleResult(result: PipelineResult) {
  if (result.success) {
    processOutput(result.output);
  }
}

Advanced: Batch Execution

const pipelineIds = ['pipeline-1', 'pipeline-2', 'pipeline-3'];
const input = { query: 'Hello' };

const results = await Promise.all(
  pipelineIds.map(id => fm.run(id, input))
);

for (const result of results) {
  console.log(`${result.pipelineId}: ${result.success ? 'OK' : 'FAIL'}`);
}

Advanced: Rate Limiting

import pLimit from 'p-limit';

const limit = pLimit(5); // Max 5 concurrent requests

const tasks = pipelines.map(id =>
  limit(() => fm.run(id, { input: 'data' }))
);

const results = await Promise.all(tasks);

Health Check

const health = await fm.health();
console.log('Status:', health.status);
console.log('Version:', health.version);