@sapiom/orchestration-core 0.1.1

package/dist/esm/check.d.ts

@@ -0,0 +1,10 @@
+export interface CheckOptions {
+    sourceDir: string;
+}
+export interface CheckResult {
+    name: string;
+    stepCount: number;
+    warnings: string[];
+    manifest: unknown;
+}
+export declare function check(opts: CheckOptions): Promise<CheckResult>;

package/dist/esm/check.js

@@ -0,0 +1,115 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { assertValidGraph, buildManifest, isOrchestrationDefinition, workflowManifestSchema } from '@sapiom/orchestration';
+import * as esbuild from 'esbuild';
+import { OrchestrationError } from './errors.js';
+function runTypecheck(sourceDir) {
+    const tscBin = path.join(sourceDir, 'node_modules', '.bin', 'tsc');
+    if (!existsSync(tscBin)) {
+        return 'typecheck skipped — TypeScript is not installed (run npm install first)';
+    }
+    try {
+        execFileSync(tscBin, ['--noEmit'], { cwd: sourceDir, stdio: ['ignore', 'pipe', 'pipe'] });
+        return null;
+    }
+    catch (err) {
+        const e = err;
+        const output = (e.stdout?.toString() ?? '').trim() || (e.stderr?.toString() ?? '').trim();
+        throw new OrchestrationError({
+            code: 'TYPECHECK_FAILED',
+            message: 'The orchestration has type errors.',
+            hint: output || 'Run `tsc --noEmit` for details.',
+        });
+    }
+}
+const LOCAL_SDK_VERSION = '0.0.0-local';
+export async function check(opts) {
+    const { sourceDir } = opts;
+    const entryFile = path.join(sourceDir, 'index.ts');
+    if (!existsSync(entryFile)) {
+        throw new OrchestrationError({
+            code: 'NO_ENTRY',
+            message: `No index.ts found in ${sourceDir}.`,
+            hint: 'Run this from an orchestration project, or pass its directory.',
+        });
+    }
+    const warnings = [];
+    const typecheckSkip = runTypecheck(sourceDir);
+    if (typecheckSkip)
+        warnings.push(typecheckSkip);
+    const tmp = mkdtempSync(path.join(tmpdir(), 'sapiom-check-'));
+    const bundlePath = path.join(tmp, 'definition.mjs');
+    try {
+        try {
+            await esbuild.build({
+                entryPoints: [entryFile],
+                outfile: bundlePath,
+                bundle: true,
+                platform: 'node',
+                target: 'node20',
+                format: 'esm',
+                logLevel: 'silent',
+            });
+        }
+        catch (err) {
+            throw new OrchestrationError({
+                code: 'BUNDLE_FAILED',
+                message: 'Failed to bundle the orchestration.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const mod = await import(`file://${bundlePath}?t=${Date.now()}`);
+        const defs = [];
+        for (const value of Object.values(mod)) {
+            if (isOrchestrationDefinition(value) && !defs.includes(value))
+                defs.push(value);
+        }
+        if (defs.length === 0) {
+            throw new OrchestrationError({
+                code: 'NO_DEFINITION',
+                message: 'No orchestration was exported from index.ts.',
+                hint: 'Export the result of defineOrchestration({ … }).',
+            });
+        }
+        if (defs.length > 1) {
+            throw new OrchestrationError({
+                code: 'MULTIPLE_DEFINITIONS',
+                message: 'index.ts exports more than one orchestration.',
+                hint: 'Export exactly one defineOrchestration({ … }) result.',
+            });
+        }
+        const def = defs[0];
+        const sha256 = createHash('sha256').update(readFileSync(bundlePath)).digest('hex');
+        let manifest;
+        try {
+            manifest = workflowManifestSchema.parse(buildManifest(def, { sdkVersion: LOCAL_SDK_VERSION, artifact: { sha256, entryFile: 'definition.mjs' } }));
+        }
+        catch (err) {
+            throw new OrchestrationError({
+                code: 'MANIFEST_INVALID',
+                message: 'The orchestration produced an invalid manifest.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        try {
+            warnings.push(...assertValidGraph(manifest));
+        }
+        catch (err) {
+            throw new OrchestrationError({
+                code: 'GRAPH_INVALID',
+                message: 'The orchestration graph is invalid.',
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const steps = manifest.steps;
+        const stepCount = Array.isArray(steps) ? steps.length : Object.keys(steps ?? {}).length;
+        const name = manifest.name ?? 'orchestration';
+        return { name, stepCount, warnings, manifest };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/esm/client.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_WORKFLOWS_HOST = "https://api.sapiom.ai";
+export interface ClientOptions {
+    host?: string;
+    apiKey: string;
+}
+export interface GatewayErrorBody {
+    message?: string | string[];
+}
+export declare class GatewayClient {
+    private readonly base;
+    private readonly apiKey;
+    constructor(opts: ClientOptions);
+    request<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;
+    get<T = unknown>(path: string): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+}
+export declare function createClient(opts: ClientOptions): GatewayClient;

package/dist/esm/client.js

@@ -0,0 +1,65 @@
+import { OrchestrationError } from './errors.js';
+export const DEFAULT_WORKFLOWS_HOST = 'https://api.sapiom.ai';
+export class GatewayClient {
+    constructor(opts) {
+        const host = (opts.host ?? DEFAULT_WORKFLOWS_HOST).replace(/\/$/, '');
+        this.base = `${host}/v1/workflows`;
+        this.apiKey = opts.apiKey;
+    }
+    async request(method, path, body) {
+        let res;
+        try {
+            res = await fetch(`${this.base}${path}`, {
+                method,
+                headers: { 'x-api-key': this.apiKey, 'content-type': 'application/json' },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new OrchestrationError({
+                code: 'NETWORK',
+                message: `Could not reach ${this.base}.`,
+                hint: err instanceof Error ? err.message : String(err),
+            });
+        }
+        const text = await res.text();
+        const data = text ? safeParse(text) : undefined;
+        if (!res.ok) {
+            throw new OrchestrationError({
+                code: `HTTP_${res.status}`,
+                message: messageFrom(data) ?? `Request failed (${res.status} ${res.statusText}).`,
+                hint: res.status === 401 || res.status === 403
+                    ? 'Check your API key (`sapiom login` or SAPIOM_API_KEY) and that it has access to this orchestration.'
+                    : undefined,
+            });
+        }
+        return data;
+    }
+    get(path) {
+        return this.request('GET', path);
+    }
+    post(path, body) {
+        return this.request('POST', path, body);
+    }
+}
+export function createClient(opts) {
+    return new GatewayClient(opts);
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function messageFrom(data) {
+    if (data && typeof data === 'object' && 'message' in data) {
+        const m = data.message;
+        if (Array.isArray(m))
+            return m.join('; ');
+        if (typeof m === 'string')
+            return m;
+    }
+    return undefined;
+}

package/dist/esm/config.d.ts

@@ -0,0 +1,9 @@
+export declare const CONFIG_FILE = "sapiom.json";
+export interface SapiomConfig {
+    definitionId: string;
+    name: string;
+    host?: string;
+}
+export declare function readConfig(dir: string): SapiomConfig | null;
+export declare function requireConfig(dir: string): SapiomConfig;
+export declare function writeConfig(dir: string, cfg: SapiomConfig): void;

package/dist/esm/config.js

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { OrchestrationError } from './errors.js';
+export const CONFIG_FILE = 'sapiom.json';
+export function readConfig(dir) {
+    const file = path.join(dir, CONFIG_FILE);
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new OrchestrationError({ code: 'BAD_CONFIG', message: `${CONFIG_FILE} is not valid JSON.` });
+    }
+}
+export function requireConfig(dir) {
+    const cfg = readConfig(dir);
+    if (!cfg?.definitionId) {
+        throw new OrchestrationError({
+            code: 'NOT_LINKED',
+            message: 'This project is not linked to a Sapiom orchestration.',
+            hint: 'Run: sapiom orchestrations link <name>',
+        });
+    }
+    return cfg;
+}
+export function writeConfig(dir, cfg) {
+    writeFileSync(path.join(dir, CONFIG_FILE), JSON.stringify(cfg, null, 2) + '\n');
+}

package/dist/esm/deploy.d.ts

@@ -0,0 +1,12 @@
+import { GatewayClient } from './client.js';
+export interface DeployOptions {
+    projectDir: string;
+    definitionId: string;
+    branch?: string;
+}
+export interface DeployResult {
+    definitionId: string;
+    buildRunId: string;
+    status: string;
+}
+export declare function deploy(opts: DeployOptions, client: GatewayClient): Promise<DeployResult>;

package/dist/esm/deploy.js

@@ -0,0 +1,48 @@
+import { OrchestrationError } from './errors.js';
+import { assertDeployable, pushHead } from './git.js';
+const TERMINAL = new Set(['ready', 'failed', 'cancelled', 'superseded']);
+const POLL_DELAYS_MS = [1000, 2000, 3000, 5000, 5000, 8000, 10000];
+const POLL_BUDGET_MS = 300000;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export async function deploy(opts, client) {
+    const { projectDir, definitionId, branch = 'main' } = opts;
+    assertDeployable(projectDir);
+    const { pushUrl } = await client.post(`/definitions/${definitionId}/push-credentials`, {});
+    pushHead(projectDir, pushUrl, branch);
+    const triggered = await client.post(`/definitions/${definitionId}/builds`, {});
+    const buildRunId = triggered.buildRunId ?? triggered.id;
+    if (!buildRunId) {
+        throw new OrchestrationError({
+            code: 'BUILD_NO_ID',
+            message: 'The build was triggered but no build id was returned.',
+        });
+    }
+    const final = await pollBuild(client, definitionId, buildRunId);
+    if (final.status !== 'ready') {
+        throw new OrchestrationError({
+            code: 'BUILD_FAILED',
+            message: `Build ${final.status}.`,
+            step: 'build',
+            hint: final.error?.stack || final.error?.message,
+        });
+    }
+    return { definitionId, buildRunId, status: final.status };
+}
+async function pollBuild(client, definitionId, buildRunId) {
+    let elapsed = 0;
+    let i = 0;
+    while (elapsed < POLL_BUDGET_MS) {
+        const build = await client.get(`/definitions/${definitionId}/builds/${buildRunId}`);
+        if (TERMINAL.has(build.status))
+            return build;
+        const delay = POLL_DELAYS_MS[Math.min(i++, POLL_DELAYS_MS.length - 1)];
+        await sleep(delay);
+        elapsed += delay;
+    }
+    throw new OrchestrationError({
+        code: 'BUILD_TIMEOUT',
+        message: 'Build did not finish in time.',
+        step: 'build',
+        hint: `Check it later via the logs API for build ${buildRunId}`,
+    });
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,15 @@
+export interface StructuredError {
+    code: string;
+    message: string;
+    step?: string;
+    hint?: string;
+    docsUrl?: string;
+}
+export declare class OrchestrationError extends Error {
+    readonly code: string;
+    readonly step?: string;
+    readonly hint?: string;
+    readonly docsUrl?: string;
+    constructor(err: StructuredError);
+    toStructured(): StructuredError;
+}

package/dist/esm/errors.js

@@ -0,0 +1,19 @@
+export class OrchestrationError extends Error {
+    constructor(err) {
+        super(err.message);
+        this.name = 'OrchestrationError';
+        this.code = err.code;
+        this.step = err.step;
+        this.hint = err.hint;
+        this.docsUrl = err.docsUrl;
+    }
+    toStructured() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.step ? { step: this.step } : {}),
+            ...(this.hint ? { hint: this.hint } : {}),
+            ...(this.docsUrl ? { docsUrl: this.docsUrl } : {}),
+        };
+    }
+}

package/dist/esm/git.d.ts

@@ -0,0 +1,2 @@
+export declare function assertDeployable(dir: string): void;
+export declare function pushHead(dir: string, pushUrl: string, branch: string): void;

package/dist/esm/git.js

@@ -0,0 +1,40 @@
+import { execFileSync } from 'node:child_process';
+import { OrchestrationError } from './errors.js';
+function git(args, cwd) {
+    try {
+        return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    }
+    catch (err) {
+        const stderr = err.stderr?.toString().trim();
+        throw new OrchestrationError({
+            code: 'GIT',
+            message: `git ${args[0]} failed.`,
+            hint: stderr || (err instanceof Error ? err.message : String(err)),
+        });
+    }
+}
+export function assertDeployable(dir) {
+    try {
+        execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, stdio: 'ignore' });
+    }
+    catch {
+        throw new OrchestrationError({
+            code: 'NOT_GIT',
+            message: 'Not a git repository.',
+            hint: 'Initialize one: git init && git add -A && git commit -m "init"',
+        });
+    }
+    try {
+        execFileSync('git', ['rev-parse', 'HEAD'], { cwd: dir, stdio: 'ignore' });
+    }
+    catch {
+        throw new OrchestrationError({
+            code: 'NO_COMMITS',
+            message: 'This repository has no commits yet.',
+            hint: 'Commit your work: git add -A && git commit -m "…"',
+        });
+    }
+}
+export function pushHead(dir, pushUrl, branch) {
+    git(['push', '--force', pushUrl, `HEAD:${branch}`], dir);
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,29 @@
+export { OrchestrationError } from './errors.js';
+export type { StructuredError } from './errors.js';
+export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST } from './client.js';
+export type { ClientOptions, GatewayErrorBody } from './client.js';
+export { readConfig, requireConfig, writeConfig, CONFIG_FILE } from './config.js';
+export type { SapiomConfig } from './config.js';
+export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE } from './scaffold.js';
+export type { ScaffoldOptions, ScaffoldResult, ResolvedVersions } from './scaffold.js';
+export { check } from './check.js';
+export type { CheckOptions, CheckResult } from './check.js';
+export { link } from './link.js';
+export type { LinkOptions, LinkResult, DefinitionSummary } from './link.js';
+export { deploy } from './deploy.js';
+export type { DeployOptions, DeployResult } from './deploy.js';
+export { run, parseJsonInput } from './run.js';
+export type { RunOptions, RunResult } from './run.js';
+export { inspect, listExecutions, inspectBuild } from './inspect.js';
+export type { InspectOptions, InspectResult, ListExecutionsResult, InspectBuildOptions, InspectBuildResult, ExecutionDetail, StepRecord, BuildDetail, } from './inspect.js';
+export { signal, parseSignalPayload } from './signal.js';
+export type { SignalOptions, SignalResult } from './signal.js';
+export { assertDeployable, pushHead } from './git.js';
+export { parseStubFile, STUB_FILE_VERSION } from './local/stubs.js';
+export type { StubFile, StepStubs, StubResponse } from './local/stubs.js';
+export { runLocal, runLocalFromDir, STUBS_FILE } from './local/run-local.js';
+export type { RunLocalOptions, LocalRunResult, LocalRunOutcome } from './local/run-local.js';
+export { loadDefinition } from './local/load.js';
+export type { LoadedDefinition } from './local/load.js';
+export { LocalStubDispatcher } from './local/dispatcher.js';
+export type { LocalStepTrace, LogEntry } from './local/dispatcher.js';

package/dist/esm/index.js

@@ -0,0 +1,15 @@
+export { OrchestrationError } from './errors.js';
+export { GatewayClient, createClient, DEFAULT_WORKFLOWS_HOST } from './client.js';
+export { readConfig, requireConfig, writeConfig, CONFIG_FILE } from './config.js';
+export { scaffold, resolveVersions, resolveTemplate, listTemplates, DEFAULT_TEMPLATE } from './scaffold.js';
+export { check } from './check.js';
+export { link } from './link.js';
+export { deploy } from './deploy.js';
+export { run, parseJsonInput } from './run.js';
+export { inspect, listExecutions, inspectBuild } from './inspect.js';
+export { signal, parseSignalPayload } from './signal.js';
+export { assertDeployable, pushHead } from './git.js';
+export { parseStubFile, STUB_FILE_VERSION } from './local/stubs.js';
+export { runLocal, runLocalFromDir, STUBS_FILE } from './local/run-local.js';
+export { loadDefinition } from './local/load.js';
+export { LocalStubDispatcher } from './local/dispatcher.js';

package/dist/esm/inspect.d.ts

@@ -0,0 +1,41 @@
+import { GatewayClient } from './client.js';
+export interface StepRecord {
+    stepName: string;
+    attempt: number;
+    status: string;
+    error?: {
+        message?: string;
+        stack?: string;
+    } | null;
+}
+export interface ExecutionDetail {
+    id: string;
+    status: string;
+    currentStep?: string | null;
+    error?: unknown;
+    steps?: StepRecord[];
+}
+export interface BuildDetail {
+    id?: string;
+    status: string;
+    error?: unknown;
+}
+export interface InspectOptions {
+    executionId: string;
+}
+export interface InspectResult {
+    execution: ExecutionDetail;
+}
+export declare function inspect(opts: InspectOptions, client: GatewayClient): Promise<InspectResult>;
+export interface ListExecutionsResult {
+    executions: ExecutionDetail[];
+}
+export declare function listExecutions(client: GatewayClient): Promise<ListExecutionsResult>;
+export interface InspectBuildOptions {
+    definitionId: string;
+    buildRunId: string;
+}
+export interface InspectBuildResult {
+    build: BuildDetail;
+}
+export declare function inspectBuild(opts: InspectBuildOptions, client: GatewayClient): Promise<InspectBuildResult>;

package/dist/esm/inspect.js

@@ -0,0 +1,12 @@
+export async function inspect(opts, client) {
+    const execution = await client.get(`/executions/${opts.executionId}`);
+    return { execution };
+}
+export async function listExecutions(client) {
+    const executions = await client.get('/executions');
+    return { executions };
+}
+export async function inspectBuild(opts, client) {
+    const build = await client.get(`/definitions/${opts.definitionId}/builds/${opts.buildRunId}`);
+    return { build };
+}

package/dist/esm/link.d.ts

@@ -0,0 +1,15 @@
+import { GatewayClient } from './client.js';
+export interface DefinitionSummary {
+    id: string;
+    name: string;
+    slug?: string;
+}
+export interface LinkOptions {
+    name: string;
+    create?: boolean;
+}
+export interface LinkResult {
+    definitionId: string;
+    name: string;
+}
+export declare function link(opts: LinkOptions, client: GatewayClient): Promise<LinkResult>;

package/dist/esm/link.js

@@ -0,0 +1,16 @@
+import { OrchestrationError } from './errors.js';
+export async function link(opts, client) {
+    const list = await client.get('/definitions');
+    let def = list.find((d) => d.name === opts.name || d.slug === opts.name);
+    if (!def) {
+        if (!opts.create) {
+            throw new OrchestrationError({
+                code: 'NOT_FOUND',
+                message: `No orchestration named '${opts.name}'.`,
+                hint: 'Create it with { create: true }, or pass the name of an existing one.',
+            });
+        }
+        def = await client.post('/definitions', { name: opts.name });
+    }
+    return { definitionId: def.id, name: def.name };
+}

package/dist/esm/local/dispatcher.d.ts

@@ -0,0 +1,35 @@
+import { type NextStepDirective, type OrchestrationDefinition } from '@sapiom/orchestration';
+import { type StepDispatcher, type StepDispatchRequest, type WorkflowRunnerCore } from '@sapiom/orchestration-runtime';
+import type { StubFile } from './stubs.js';
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    msg: string;
+    meta?: Record<string, unknown>;
+}
+export interface LocalStepTrace {
+    step: string;
+    attempt: number;
+    input: unknown;
+    status: 'succeeded' | 'threw';
+    output?: unknown;
+    directive?: NextStepDirective;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    logs: LogEntry[];
+}
+export declare class LocalStubDispatcher implements StepDispatcher {
+    private readonly definition;
+    private readonly stubs;
+    private core;
+    private maxAttemptsPerStep;
+    private signals;
+    readonly trace: LocalStepTrace[];
+    constructor(definition: OrchestrationDefinition, stubs: StubFile);
+    setCore(core: WorkflowRunnerCore): void;
+    setMaxAttempts(max: number): void;
+    setSignals(signals: Map<string, unknown>): void;
+    dispatch(request: StepDispatchRequest): Promise<void>;
+}