Step API Reference

import { defineStep } from '@zoopflow/core';
 
const stringTransformer = defineStep({
  id: 'examples.string.transform',
  version: '1.0.0',
  description: 'Transforms a string based on the specified operation',
  
  inputSchema: { /* JSON Schema for input validation */ },
  outputSchema: { /* JSON Schema for output validation */ },
  
  execute: async (input, context) => {
    // Step implementation
    return output;
  }
});

interface StepDefinition<TInput, TOutput> {
  // Required properties
  id: string;
  version: string;
  description?: string;
  displayName?: string;
  inputSchema: JSONSchema7;
  outputSchema: JSONSchema7;
  execute: (input: TInput, context: StepContext) => Promise<TOutput>;
  
  // Optional properties
  retryConfig?: RetryConfig;
  timeoutSeconds?: number;
  tags?: string[];
  metadata?: Record<string, unknown>;
}

interface StepContext {
  // Execution metadata
  info: ExecutionInfo;
  stepMetadata: StepMetadata;
  readonly executionMetadata: StepExecutionMetadata;
  readonly history: StepHistoryEntry[];
  
  // State management
  getState<T>(key: string): Promise<T | undefined>;
  setState<T>(key: string, value: T): Promise<void>;
  getStateObject(): Promise<Record<string, unknown>>;
  updateState(stateUpdates: Record<string, unknown>): Promise<void>;
  
  // Checkpointing and recovery
  createCheckpoint(metadata?: Record<string, unknown>): Promise<string>;
  restoreFromCheckpoint(checkpointId: string): Promise<void>;
  getCheckpointInfo(checkpointId: string): Promise<CheckpointInfo | undefined>;
  getAllCheckpoints(): Promise<CheckpointInfo[]>;
  
  // Logging and history
  log(message: string, metadata?: Record<string, unknown>): void;
  addHistoryEntry(type: 'custom', details: Record<string, unknown>): void;
  
  // Lifecycle management
  complete(details?: Record<string, unknown>): Promise<void>;
  fail(reason: string, details?: Record<string, unknown>): Promise<void>;
  
  // Service access
  getService<T>(name: string, options?: Record<string, unknown>): T;
}

interface ExecutionInfo {
  stepId: string;
  flowId: string;
  executionId: string;
  attemptNumber: number;
}

interface StepExecutionMetadata {
  executionId: string;
  status: StepExecutionStatus;
  startedAt: Date;
  completedAt?: Date;
  succeeded?: boolean;
  failureReason?: string;
  attemptNumber: number;
  [key: string]: unknown;
}

type StepExecutionStatus =
  | 'pending'
  | 'executing'
  | 'completed'
  | 'failed'
  | 'skipped';

interface StepHistoryEntry {
  timestamp: Date;
  type: 'started' | 'checkpoint' | 'completed' | 'failed' | 'state_change' | 'custom';
  details?: Record<string, unknown>;
}

interface CheckpointInfo {
  id: string;
  createdAt: Date;
  state: Record<string, unknown>;
  metadata?: Record<string, unknown>;
}

import { executeStep } from '@zoopflow/core';
 
const result = await executeStep(stringTransformer, {
  text: 'Hello, World!',
  operation: 'uppercase'
});

interface ExecuteStepOptions {
  context?: StepContext;
  validateInput?: boolean;
  validateOutput?: boolean;
  retryConfig?: RetryConfig;
  timeoutSeconds?: number;
}

import { registerStep } from '@zoopflow/core';
 
registerStep(stringTransformer);

import { getStep } from '@zoopflow/core';
 
const step = getStep('examples.string.transform');
// or with version
const specificVersion = getStep('examples.string.transform', '1.0.0');

import { listSteps } from '@zoopflow/core';
 
// List all steps
const allSteps = listSteps();
 
// List steps with specific tag
const dataSteps = listSteps({ tags: ['data-processing'] });

interface ListStepsOptions {
  domain?: string;
  tags?: string[];
  includeDeprecated?: boolean;
}

interface RetryConfig {
  maxAttempts: number;
  backoffCoefficient?: number;
  initialIntervalSeconds?: number;
  maxIntervalSeconds?: number;
  retryableErrors?: string[];
}