@intellia/workflow-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,524 @@
+import { z } from 'zod/v4';
+export { z } from 'zod/v4';
+
+type JSONSchemaTypeName = "string" | "number" | "integer" | "boolean" | "object" | "array" | "null" | "any";
+type JSONSchemaType = string | number | boolean | JSONSchemaObject | JSONSchemaArray | null;
+interface JSONSchemaObject {
+    [key: string]: JSONSchemaType;
+}
+interface JSONSchemaArray extends Array<JSONSchemaType> {
+}
+interface JSONSchema {
+    title?: string;
+    description?: string;
+    default?: JSONSchemaType;
+    multipleOf?: number;
+    maximum?: number;
+    exclusiveMaximum?: number;
+    minimum?: number;
+    exclusiveMinimum?: number;
+    maxLength?: number;
+    minLength?: number;
+    pattern?: string;
+    additionalItems?: boolean | JSONSchema;
+    items?: JSONSchema;
+    maxItems?: number;
+    minItems?: number;
+    uniqueItems?: boolean;
+    maxProperties?: number;
+    minProperties?: number;
+    required?: string[];
+    additionalProperties?: boolean | JSONSchema;
+    definitions?: {
+        [k: string]: JSONSchema;
+    };
+    properties?: {
+        [k: string]: JSONSchema;
+    };
+    enum?: JSONSchemaType[];
+    type?: JSONSchemaTypeName;
+    allOf?: JSONSchema[];
+    anyOf?: JSONSchema[];
+    oneOf?: JSONSchema[];
+    not?: JSONSchema;
+    format?: string;
+    [k: string]: any;
+}
+
+type WorkflowNodeType = "trigger" | "approval" | "conditional" | "end" | "noop" | "agent" | "tool-call" | "function" | "bash" | "parallel" | "repeat" | "wait-for-callback" | "set-output" | "execute-workflow";
+type Condition = {
+    variable: string;
+    dataType: "String" | "Boolean" | "Numeric" | "Timestamp";
+    comparison: "Equals" | "GreaterThan" | "GreaterThanEquals" | "LessThan" | "LessThanEquals" | "IsNull" | "IsPresent" | "Contains";
+    value: string | number | boolean;
+};
+type WaitForCallbackResume = {
+    /** Stable scope for the lookup key (e.g. "concierge:signing"). */
+    namespace: string;
+    /** Composed at runtime via JSONata. Resumer reads the same key. */
+    lookupKey: string;
+    /** Forwarded to the resumer verbatim. */
+    metadata?: Record<string, unknown>;
+    /** Default `"generic"`. Set `"feature"` to refuse the generic resume endpoint + tool. */
+    by?: "generic" | "feature";
+    /**
+     * Opt-in: makes this wait discoverable via workflow.listPendingWaits.
+     * JSONata-resolved to a user identifier (e.g. `$.results.trigger.hankoUserId`).
+     * Scoping to the organization is applied server-side.
+     */
+    pendingFor?: string;
+};
+
+interface VaultItemCredentialsValue {
+    email?: string;
+    username?: string;
+    password: string;
+    totpSecret?: string;
+}
+interface VaultItem {
+    value: string | VaultItemCredentialsValue;
+}
+interface HttpResponse<T = unknown> {
+    data: T;
+    status: number;
+}
+type MemoryScope = "organization" | "user";
+interface HutlyApi {
+    vault: {
+        getItem(id: string): Promise<VaultItem | undefined>;
+        getForApp(appName: string): Promise<VaultItem | undefined>;
+    };
+    memory: {
+        get(agentId: string, userId: string, scope: MemoryScope, key: string): Promise<unknown>;
+        set(agentId: string, userId: string, scope: MemoryScope, key: string, value: unknown): Promise<void>;
+        list(agentId: string, userId: string, scope: MemoryScope, nextToken?: unknown): Promise<{
+            items: unknown[];
+            nextToken?: unknown;
+        }>;
+        delete(agentId: string, userId: string, scope: MemoryScope, key: string): Promise<void>;
+    };
+    http: {
+        get<T = unknown>(url: string, config?: Record<string, unknown>): Promise<HttpResponse<T>>;
+        post<T = unknown>(url: string, body?: unknown, config?: Record<string, unknown>): Promise<HttpResponse<T>>;
+        put<T = unknown>(url: string, body?: unknown, config?: Record<string, unknown>): Promise<HttpResponse<T>>;
+        delete<T = unknown>(url: string, config?: Record<string, unknown>): Promise<HttpResponse<T>>;
+        patch<T = unknown>(url: string, body?: unknown, config?: Record<string, unknown>): Promise<HttpResponse<T>>;
+        request<T = unknown>(config: Record<string, unknown>): Promise<HttpResponse<T>>;
+    };
+    secrets: {
+        get(name: string): Promise<string>;
+    };
+    moment: unknown;
+    askAI<T = unknown>(question: string, responseSchema: unknown, model?: "gpt5.1" | "gpt5.2" | "gpt5.4" | "gpt5.6-luna" | "gpt5.6-terra" | "gpt5.6-sol" | "gpt4.1"): Promise<T>;
+}
+
+declare const toJsonSchema: (t: z.ZodType) => JSONSchema;
+declare const artifact: () => z.ZodObject<{
+    artifactId: z.ZodString;
+    filename: z.ZodString;
+}, z.core.$strip>;
+
+declare const REF: unique symbol;
+declare const TPL: unique symbol;
+declare const PHANTOM: unique symbol;
+interface RefLike {
+    readonly [REF]: string;
+}
+interface TplLike {
+    readonly [TPL]: string;
+}
+type Handle<T> = RefLike & {
+    readonly [PHANTOM]?: T;
+} & (T extends readonly unknown[] | string | number | boolean | null | undefined ? unknown : {
+    [K in keyof T]-?: Handle<T[K]>;
+});
+declare const isRef: (v: unknown) => v is RefLike;
+declare const refPath: (r: RefLike) => string;
+declare const isTpl: (v: unknown) => v is TplLike;
+declare const tplText: (t: TplLike) => string;
+declare const handleFor: <T>(basePath: string) => Handle<T>;
+declare const tpl: (strings: TemplateStringsArray, ...vals: unknown[]) => TplLike;
+declare const encodeValue: (v: unknown) => unknown;
+
+interface FunctionDef<I, O> {
+    name: string;
+    input: z.ZodType<I>;
+    output: z.ZodType<O>;
+    run: (input: I, hutly: HutlyApi) => Promise<O>;
+}
+declare const defineFunction: <I, O>(spec: FunctionDef<I, O>) => FunctionDef<I, O>;
+interface WholeStateFunctionDef<O> {
+    name: string;
+    output: z.ZodType<O>;
+    run: (payload: unknown, hutly: HutlyApi) => Promise<O>;
+}
+declare const defineWholeStateFunction: <O>(spec: WholeStateFunctionDef<O>) => WholeStateFunctionDef<O>;
+interface BashSpec<O> {
+    name: string;
+    id?: string;
+    output: z.ZodType<O>;
+    secrets?: Record<string, string>;
+    timeoutSeconds?: number;
+    async?: boolean;
+}
+
+interface ToolDef<Id extends string = string> {
+    id: Id;
+    toolCode: string;
+    description: string;
+    config: Record<string, unknown>;
+}
+interface ToolConfigRegistry {
+}
+type ToolConfigFor<Code extends string> = Code extends keyof ToolConfigRegistry ? ToolConfigRegistry[Code] : Record<string, unknown>;
+interface ToolInstanceRegistry {
+}
+interface ToolInstanceShape {
+    input: Record<string, unknown>;
+    output: Record<string, unknown>;
+}
+type ToolInstancesFor<Id extends string> = Id extends keyof ToolInstanceRegistry ? ToolInstanceRegistry[Id] extends Record<string, ToolInstanceShape> ? ToolInstanceRegistry[Id] : Record<string, ToolInstanceShape> : Record<string, ToolInstanceShape>;
+declare const defineTool: <Code extends string, Id extends string>(spec: {
+    id: Id;
+    toolCode: Code;
+    description: string;
+    config: ToolConfigFor<Code>;
+}) => ToolDef<Id>;
+
+interface KnowledgeBaseDef {
+    id: string;
+    name: string;
+    description: string;
+    knowledgeBaseId: string;
+    instructions?: string;
+}
+declare const defineKnowledgeBase: (spec: KnowledgeBaseDef) => KnowledgeBaseDef;
+
+interface AgentRefDef {
+    id: string;
+    name: string;
+    description: string;
+    agentId: string;
+    instructions?: string;
+}
+declare const defineAgentRef: (spec: AgentRefDef) => AgentRefDef;
+
+type Cond = {
+    kind: "comparison";
+    condition: Condition;
+} | {
+    kind: "jsonata";
+    expression: string;
+};
+declare const eq: <T extends string | number | boolean>(t: Handle<T>, v: T) => Cond;
+declare const gt: (t: Handle<number>, v: number) => Cond;
+declare const gte: (t: Handle<number>, v: number) => Cond;
+declare const lt: (t: Handle<number>, v: number) => Cond;
+declare const lte: (t: Handle<number>, v: number) => Cond;
+declare const contains: (t: Handle<string>, v: string) => Cond;
+declare const isNull: (t: RefLike) => Cond;
+declare const isPresent: (t: RefLike) => Cond;
+declare const jsonata: (strings: TemplateStringsArray, ...vals: unknown[]) => Cond;
+
+interface Scope {
+    nodes: NodeSpec[];
+}
+interface NodeSpecBase {
+    id: string;
+    name: string;
+    onFailure?: Scope | "continue";
+    onFailureRejoin?: string | null;
+}
+type NodeSpec = (NodeSpecBase & {
+    kind: "function";
+    def: FunctionDef<unknown, unknown> | WholeStateFunctionDef<unknown>;
+    modulePath: string;
+    input: Record<string, unknown> | "whole-state";
+}) | (NodeSpecBase & {
+    kind: "bash";
+    scriptPath: string;
+    output: z.ZodType;
+    secrets?: Record<string, string>;
+    timeoutSeconds?: number;
+    async?: boolean;
+}) | (NodeSpecBase & {
+    kind: "tool-call";
+    tool: ToolDef;
+    toolName: string;
+    input: Record<string, unknown>;
+    output: z.ZodType;
+}) | (NodeSpecBase & {
+    kind: "agent";
+    agentId?: string;
+    instructions: string;
+    input?: z.ZodType;
+    output: z.ZodType;
+    reasoning?: "none" | "low" | "medium" | "high";
+    enabled?: boolean;
+    description?: string;
+    showWholeChainState?: boolean;
+    failBeforeRunningIf?: string;
+    failAfterRunningIf?: string;
+    toolChoice?: string;
+    tools?: ToolDef[];
+    knowledgeBases?: KnowledgeBaseDef[];
+    otherAgents?: AgentRefDef[];
+}) | (NodeSpecBase & {
+    kind: "execute-workflow";
+    workflow: WorkflowModule;
+    modulePath: string;
+    organizationId?: string;
+    input: Record<string, unknown> | string;
+    output: z.ZodType;
+}) | (NodeSpecBase & {
+    kind: "approval";
+    notificationType: "Email" | "SMS";
+    callbackURL: string;
+    emailAddress?: string;
+    otherEmails?: string[] | string;
+    phoneNumber?: string;
+    message: string;
+    output: z.ZodType;
+    defaultValues?: JSONSchemaType;
+}) | (NodeSpecBase & {
+    kind: "wait-for-callback";
+    output: z.ZodType;
+    timeoutSeconds?: number;
+    resume?: WaitForCallbackResume;
+}) | (NodeSpecBase & {
+    kind: "noop";
+}) | (NodeSpecBase & {
+    kind: "set-output";
+    output: Record<string, unknown>;
+}) | (NodeSpecBase & {
+    kind: "conditional";
+    choices: {
+        id: string;
+        name?: string;
+        cond: Cond;
+        scope: Scope;
+    }[];
+    defaultPath: Scope;
+}) | (NodeSpecBase & {
+    kind: "parallel";
+    branches: {
+        id: string;
+        scope: Scope;
+    }[];
+}) | (NodeSpecBase & {
+    kind: "repeat";
+    numberOrList: number | string;
+    scope: Scope;
+});
+interface TriggerSpec {
+    type: "json" | "kb-file" | "canvas";
+    name?: string;
+    input?: z.ZodType;
+}
+interface WorkflowModule {
+    record(): RecordedWorkflow;
+}
+interface RecordedWorkflow {
+    name: string;
+    description: string;
+    slug: string;
+    kind: "standard" | "tool";
+    trigger: TriggerSpec;
+    scope: Scope;
+    output?: Record<string, unknown>;
+    outputSchema?: z.ZodType;
+    onFailure?: Scope;
+    ids: IdAllocator;
+    endNodeId?: string | null;
+    endNodeName?: string;
+    outputNodeId?: string;
+    outputNodeName?: string;
+}
+
+type OnFailure = ((b: Builder) => void) | "continue";
+type NodeInput<I> = {
+    [K in keyof I]: I[K] | Handle<I[K]>;
+};
+type ToolCallInput<I> = {
+    [K in keyof I]: I[K] | Handle<I[K]> | TplLike;
+};
+interface AgentSpec<O> {
+    name: string;
+    id?: string;
+    agentId?: string | Handle<string>;
+    instructions: string | Handle<string>;
+    input?: z.ZodType;
+    output: z.ZodType<O>;
+    reasoning?: "none" | "low" | "medium" | "high";
+    enabled?: boolean;
+    description?: string | Handle<string>;
+    showWholeChainState?: boolean;
+    failBeforeRunningIf?: string | Handle<string>;
+    failAfterRunningIf?: string | Handle<string>;
+    toolChoice?: "auto" | "required" | "none" | string | Handle<string>;
+    tools?: ToolDef[];
+    knowledgeBases?: KnowledgeBaseDef[];
+    otherAgents?: AgentRefDef[];
+    onFailure?: OnFailure;
+    onFailureRejoin?: string | null;
+}
+interface ExecuteWorkflowSpec<O> {
+    name: string;
+    id?: string;
+    workflow: WorkflowModule;
+    input: NodeInput<Record<string, unknown>> | Handle<unknown>;
+    output: z.ZodType<O>;
+    organizationId?: string;
+    onFailure?: OnFailure;
+    onFailureRejoin?: string | null;
+}
+interface ApprovalSpec<O> {
+    name: string;
+    id?: string;
+    notificationType: "Email" | "SMS";
+    callbackURL: string | Handle<string>;
+    emailAddress?: string | Handle<string>;
+    otherEmails?: string[] | string | Handle<string[] | string>;
+    phoneNumber?: string | Handle<string>;
+    message: string | Handle<string>;
+    output: z.ZodType<O>;
+    defaultValues?: NodeInput<Record<string, unknown>> | Handle<unknown>;
+    onFailure?: OnFailure;
+    onFailureRejoin?: string | null;
+}
+interface WaitForCallbackSpec<O> {
+    name: string;
+    id?: string;
+    output: z.ZodType<O>;
+    timeoutSeconds?: number;
+    resume?: {
+        namespace: string | Handle<string>;
+        lookupKey: string | Handle<string>;
+        metadata?: NodeInput<Record<string, unknown>>;
+        by?: "generic" | "feature";
+        pendingFor?: string | Handle<string>;
+    };
+    onFailure?: OnFailure;
+    onFailureRejoin?: string | null;
+}
+declare class IdAllocator {
+    private used;
+    allocate(name: string): string;
+    reserve(id: string): string;
+}
+declare class Builder {
+    protected readonly ids: IdAllocator;
+    readonly scope: Scope;
+    constructor(ids: IdAllocator);
+    protected push<T>(node: NodeSpec): Handle<T>;
+    private resolveId;
+    function<I, O>(def: FunctionDef<I, O>, input: NodeInput<I>, opts?: {
+        id?: string;
+        onFailure?: OnFailure;
+        onFailureRejoin?: string | null;
+    }): Handle<O>;
+    function<O>(def: WholeStateFunctionDef<O>, opts?: {
+        id?: string;
+        onFailure?: OnFailure;
+        onFailureRejoin?: string | null;
+    }): Handle<O>;
+    bash<O>(scriptPath: string, spec: BashSpec<O> & {
+        onFailure?: OnFailure;
+        onFailureRejoin?: string | null;
+    }): Handle<O>;
+    toolCall<Id extends string, Name extends keyof ToolInstancesFor<Id> & string>(tool: ToolDef<Id>, instanceName: Name, spec: {
+        id?: string;
+        name?: string;
+        input: ToolCallInput<ToolInstancesFor<Id>[Name]["input"]>;
+        output: z.ZodType<ToolInstancesFor<Id>[Name]["output"]>;
+        onFailure?: OnFailure;
+        onFailureRejoin?: string | null;
+    }): Handle<ToolInstancesFor<Id>[Name]["output"]>;
+    agent<O>(spec: AgentSpec<O>): Handle<O>;
+    executeWorkflow<O>(spec: ExecuteWorkflowSpec<O>): Handle<O>;
+    approval<O>(spec: ApprovalSpec<O>): Handle<O>;
+    waitForCallback<O>(spec: WaitForCallbackSpec<O>): Handle<O>;
+    output(shape: Record<string, unknown>): Record<string, unknown>;
+    setOutput(shape: Record<string, unknown>, opts?: {
+        id?: string;
+        name?: string;
+    }): void;
+    noop(name: string, opts?: {
+        id?: string;
+    }): void;
+    if(cond: Cond, branches: {
+        then: (b: Builder) => void;
+        else?: (b: Builder) => void;
+    }, opts?: {
+        id?: string;
+        name?: string;
+        choiceId?: string;
+        choiceName?: string;
+    }): void;
+    choice(branches: {
+        id?: string;
+        name?: string;
+        cond: Cond;
+        then: (b: Builder) => void;
+    }[], opts?: {
+        else?: (b: Builder) => void;
+        id?: string;
+        name?: string;
+    }): void;
+    parallel(branches: Record<string, (b: Builder) => void>, opts?: {
+        id?: string;
+        name?: string;
+    }): void;
+    forEach(items: unknown, body: (b: Builder) => void, opts?: {
+        id?: string;
+        name?: string;
+    }): void;
+    recordBranch(fn?: (b: Builder) => void): Scope | undefined;
+    private resolveOnFailure;
+}
+
+interface WorkflowSpec<TInput> {
+    name: string;
+    description?: string;
+    slug: string;
+    trigger: {
+        type: "json" | "kb-file" | "canvas";
+        name?: string;
+        input?: z.ZodType<TInput>;
+    };
+    onFailure?: (b: Builder) => void;
+    endNodeId?: string | null;
+    endNodeName?: string;
+    outputNodeId?: string;
+    outputNodeName?: string;
+    build: (wf: Builder, trigger: Handle<TInput>) => Record<string, unknown> | void;
+}
+declare const defineWorkflow: <TInput>(spec: WorkflowSpec<TInput>) => WorkflowModule;
+
+type ToolBuilder = Omit<Builder, "bash">;
+interface ToolWorkflowSpec<TInput, TOutput> {
+    name: string;
+    description?: string;
+    slug: string;
+    triggerName?: string;
+    endNodeId?: string | null;
+    endNodeName?: string;
+    outputNodeId?: string;
+    outputNodeName?: string;
+    input: z.ZodType<TInput>;
+    output: z.ZodType<TOutput>;
+    build: (wf: ToolBuilder, trigger: Handle<TInput>) => Record<string, unknown>;
+}
+declare const defineToolWorkflow: <TInput, TOutput>(spec: ToolWorkflowSpec<TInput, TOutput>) => WorkflowModule;
+
+type NodeTypeSupport = {
+    readonly status: "expressible";
+    readonly builder: unknown;
+} | {
+    readonly status: "not-expressible";
+    readonly reason: string;
+};
+declare const NODE_TYPE_SUPPORT: Record<WorkflowNodeType, NodeTypeSupport>;
+
+export { Builder, IdAllocator, NODE_TYPE_SUPPORT, artifact, contains, defineAgentRef, defineFunction, defineKnowledgeBase, defineTool, defineToolWorkflow, defineWholeStateFunction, defineWorkflow, encodeValue, eq, gt, gte, handleFor, isNull, isPresent, isRef, isTpl, jsonata, lt, lte, refPath, toJsonSchema, tpl, tplText };
+export type { AgentRefDef, AgentSpec, ApprovalSpec, BashSpec, Cond, ExecuteWorkflowSpec, FunctionDef, Handle, HutlyApi, KnowledgeBaseDef, NodeInput, NodeSpec, NodeTypeSupport, OnFailure, RecordedWorkflow, RefLike, Scope, ToolBuilder, ToolCallInput, ToolConfigFor, ToolConfigRegistry, ToolDef, ToolInstanceRegistry, ToolInstanceShape, ToolInstancesFor, ToolWorkflowSpec, TplLike, TriggerSpec, WaitForCallbackSpec, WholeStateFunctionDef, WorkflowModule, WorkflowSpec };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@intellia/workflow-sdk",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "TypeScript authoring surface for Hutly workflows",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./tsconfig.base.json": "./tsconfig.base.json"
+  },
+  "files": [
+    "dist",
+    "tsconfig.base.json",
+    "README.md"
+  ],
+  "scripts": {
+    "compile": "yarn compile:cjs && yarn compile:esm && yarn mark:esm && yarn bundle:dts",
+    "compile:cjs": "tsc --project tsconfig.json",
+    "compile:esm": "tsc --project tsconfig.module.json",
+    "mark:esm": "node -e \"require('fs').writeFileSync('dist/esm/package.json', JSON.stringify({ type: 'module' }) + '\\n')\"",
+    "bundle:dts": "node scripts/bundle-dts.mjs",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@intellia/workflow-translator": "*",
+    "@intellia/workflow-types": "*",
+    "@types/jest": "^29.5.4",
+    "jest": "^29.6.4",
+    "rollup": "^4.62.2",
+    "rollup-plugin-dts": "^6.1.0",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.2.2"
+  }
+}

package/tsconfig.base.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "module": "commonjs",
+    "target": "es2020",
+    "lib": ["es2020"],
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}