Pipelines

A pipeline is a named, versioned sequence of steps that executes a governed action. Define a pipeline once; trigger it by name wherever needed.

triggerPipelineByName()

The primary method for triggering an execution. Requires a pipeline to exist with the given name.

const execution = await hdb.triggerPipelineByName(
  name:  string,
  input: TriggerByNameInput
): Promise<PipelineExecution>

Input

interface TriggerByNameInput {
  input?:          Record<string, unknown>;  // payload passed to pipeline steps
  decisionId?:     string;                   // approved decision ID (strongly recommended)
  triggerEvent?:   string;                   // event type that caused this trigger
  idempotencyKey?: string;                   // deduplication key
}

Example

const execution = await hdb.triggerPipelineByName('payment.execute.standard', {
  decisionId: decision.decisionId,
  input: {
    amount:     15000,
    currency:   'USD',
    to:         'acct_9k2x',
    reference:  'order_7abc',
  },
  idempotencyKey: `exec-${orderId}`,
});

console.log(execution.id);        // 'exec_abc123'
console.log(execution.status);    // 'completed' | 'running' | 'failed' | ...
console.log(execution.steps);     // step-level trace

---

triggerPipeline()

Trigger by pipeline UUID instead of name. Useful when you have the pipeline ID from a previous pipelines.create() call.

const execution = await hdb.triggerPipeline(input: TriggerPipelineInput): Promise<PipelineExecution>

Input

interface TriggerPipelineInput {
  pipelineId:      string;                   // UUID
  input:           Record<string, unknown>;
  decisionId?:     string;
  triggerEvent?:   string;
  idempotencyKey?: string;
}

---

getPipelineExecution()

Poll or inspect an execution after triggering.

const execution = await hdb.getPipelineExecution(executionId: string): Promise<PipelineExecution>

Response

interface PipelineExecution {
  id:                string;
  pipelineId:        string;
  actorId:           string;
  decisionId:        string | null;
  status:            'pending' | 'running' | 'completed' | 'failed' | 'compensated' | 'replaying';
  input:             Record<string, unknown>;
  output:            Record<string, unknown> | null;
  error:             string | null;
  steps:             PipelineStepRecord[];
  startedAt:         string;   // ISO 8601
  completedAt:       string | null;
  parentExecutionId: string | null;  // set when this is a replay
}

interface PipelineStepRecord {
  id:           string;
  stepName:     string;
  stepType:     string;
  status:       'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'compensated';
  input:        Record<string, unknown> | null;
  output:       Record<string, unknown> | null;
  error:        string | null;
  attemptCount: number;
  startedAt:    string | null;
  completedAt:  string | null;
}

Example

// Poll until complete
async function waitForExecution(execId: string) {
  while (true) {
    const exec = await hdb.getPipelineExecution(execId);
    if (['completed', 'failed', 'compensated'].includes(exec.status)) return exec;
    await new Promise(r => setTimeout(r, 500));
  }
}

---

pipelines.create()

Register a new pipeline definition. Pipelines are versioned — updating an existing name creates a new version without invalidating running executions.

const pipeline = await hdb.pipelines.create(input: CreatePipelineInput): Promise<PipelineDefinition>

Input

interface CreatePipelineInput {
  name:          string;
  description?:  string;
  steps:         CreatePipelineStepInput[];
  inputSchema?:  Record<string, unknown>;   // JSON Schema for input validation
  outputSchema?: Record<string, unknown>;
}

interface CreatePipelineStepInput {
  id:                string;   // unique within this pipeline
  name:              string;
  type:              'action' | 'decision' | 'webhook' | 'delay' | 'branch';
  config?:           Record<string, unknown>;
  dependsOn?:        string[];  // step IDs this step waits for
  compensationStep?: string;    // step ID to run on rollback
  timeout?:          number;    // ms, default 30000
  retryPolicy?: {
    maxAttempts: number;
    backoffMs:   number;
  };
}

Example

await hdb.pipelines.create({
  name:        'payment.execute.standard',
  description: 'Standard payment execution with fraud check',
  steps: [
    {
      id:   'validate',
      name: 'Validate payload',
      type: 'action',
    },
    {
      id:        'fraud-check',
      name:      'Fraud signal check',
      type:      'action',
      dependsOn: ['validate'],
    },
    {
      id:                'execute',
      name:              'Execute payment',
      type:              'action',
      dependsOn:         ['fraud-check'],
      compensationStep:  'reverse-payment',   // runs on rollback
    },
    {
      id:        'reverse-payment',
      name:      'Reverse payment',
      type:      'action',
    },
    {
      id:        'record',
      name:      'Record outcome',
      type:      'action',
      dependsOn: ['execute'],
    },
  ],
});

---

Execution status reference

Status	Meaning
pending	Queued, not yet started
running	Steps are executing
completed	All steps succeeded
failed	One or more steps failed; compensation may be running
compensated	Rollback complete — all steps reversed
replaying	Being replayed from a checkpoint