@happyrobot-ai/sdk 0.1.8 → 0.1.10

package/helpers/index.d.ts

@@ -10,5 +10,7 @@ export { createVoiceAgent } from "./voice-agent";
 export type { CreateVoiceAgentOptions, CreateVoiceAgentResult } from "./voice-agent";
 export { triggerAndWait } from "./trigger-and-wait";
 export type { TriggerAndWaitOptions, TriggerAndWaitResult } from "./trigger-and-wait";
+export { triggerAndWaitForNodeOutput } from "./trigger-and-wait-for-node-output";
+export type { TriggerAndWaitForNodeOutputOptions, TriggerAndWaitForNodeOutputResult, } from "./trigger-and-wait-for-node-output";
 export { createFromTemplate } from "./template-workflows";
 export type { CreateFromTemplateOptions, CreateFromTemplateResult } from "./template-workflows";

package/helpers/index.js

@@ -8,11 +8,13 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createFromTemplate = exports.triggerAndWait = exports.createVoiceAgent = void 0;
+exports.createFromTemplate = exports.triggerAndWaitForNodeOutput = exports.triggerAndWait = exports.createVoiceAgent = void 0;
 var voice_agent_1 = require("./voice-agent");
 Object.defineProperty(exports, "createVoiceAgent", { enumerable: true, get: function () { return voice_agent_1.createVoiceAgent; } });
 var trigger_and_wait_1 = require("./trigger-and-wait");
 Object.defineProperty(exports, "triggerAndWait", { enumerable: true, get: function () { return trigger_and_wait_1.triggerAndWait; } });
+var trigger_and_wait_for_node_output_1 = require("./trigger-and-wait-for-node-output");
+Object.defineProperty(exports, "triggerAndWaitForNodeOutput", { enumerable: true, get: function () { return trigger_and_wait_for_node_output_1.triggerAndWaitForNodeOutput; } });
 var template_workflows_1 = require("./template-workflows");
 Object.defineProperty(exports, "createFromTemplate", { enumerable: true, get: function () { return template_workflows_1.createFromTemplate; } });
 //# sourceMappingURL=index.js.map

package/helpers/index.mjs

@@ -1,3 +1,3 @@
 import * as _cjs from "./index.js";
-const { createVoiceAgent, triggerAndWait, createFromTemplate } = _cjs;
-export { createVoiceAgent, triggerAndWait, createFromTemplate };
+const { createVoiceAgent, triggerAndWait, triggerAndWaitForNodeOutput, createFromTemplate } = _cjs;
+export { createVoiceAgent, triggerAndWait, triggerAndWaitForNodeOutput, createFromTemplate };

package/helpers/trigger-and-wait-for-node-output.d.ts

@@ -0,0 +1,18 @@
+import type { HappyRobotClient } from "../client";
+import type { RunNodeOutput } from "../types/runs.types";
+export interface TriggerAndWaitForNodeOutputOptions {
+    workflowId: string;
+    payload?: Record<string, unknown>;
+    environment?: "production" | "staging" | "development";
+    nodePersistentId: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+export interface TriggerAndWaitForNodeOutputResult {
+    ok: boolean;
+    runId: string;
+    status: string;
+    nodeOutput: RunNodeOutput;
+    completedAt: string | null;
+}
+export declare function triggerAndWaitForNodeOutput(client: HappyRobotClient, options: TriggerAndWaitForNodeOutputOptions): Promise<TriggerAndWaitForNodeOutputResult>;

package/helpers/trigger-and-wait-for-node-output.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.triggerAndWaitForNodeOutput = triggerAndWaitForNodeOutput;
+const errors_1 = require("../core/errors");
+const RUN_TERMINAL_STATUSES = new Set([
+    "completed",
+    "succeeded",
+    "failed",
+    "canceled",
+    "skipped",
+]);
+const NODE_READY_STATUSES = new Set([
+    "completed",
+    "succeeded",
+    "failed",
+    "canceled",
+    "skipped",
+]);
+async function triggerAndWaitForNodeOutput(client, options) {
+    const { workflowId, payload, environment = "production", nodePersistentId, timeoutMs = 300_000, pollIntervalMs = 2_000, } = options;
+    const triggerResponse = await client.workflows.triggerRun(workflowId, {
+        payload,
+        environment,
+    });
+    // NOTE: V3 trigger responses use `run_id`, while some V2 workflows return
+    // `queued_run_ids`. We support both for now and can remove the fallback once
+    // all workflows are upgraded.
+    const run_id = triggerResponse.run_id ??
+        (Array.isArray(triggerResponse.queued_run_ids)
+            ? triggerResponse.queued_run_ids[0]
+            : undefined);
+    if (!run_id) {
+        throw new Error("No run_id returned from trigger");
+    }
+    const deadline = Date.now() + timeoutMs;
+    let lastRunStatus = null;
+    let lastRunCompletedAt = null;
+    while (Date.now() < deadline) {
+        const nodes = await client.runs.listNodes(run_id, {
+            node_persistent_id: nodePersistentId,
+            sort: "asc",
+        });
+        const matchingNodes = nodes.data.filter((item) => item.node_persistent_id === nodePersistentId);
+        const node = pickLatestNodeExecution(matchingNodes);
+        if (node?.output_id && node.status && NODE_READY_STATUSES.has(node.status)) {
+            const output = await client.runs.getOutput(run_id, node.output_id);
+            return {
+                ok: true,
+                runId: run_id,
+                status: lastRunStatus ?? node.status,
+                nodeOutput: output.data,
+                completedAt: lastRunCompletedAt,
+            };
+        }
+        // TODO: 2 HTTP calls per poll (listNodes + get(run)). Future fix: include
+        // run_status in listNodes response to eliminate get(run) entirely.
+        const run = await client.runs.get(run_id);
+        lastRunStatus = run.status;
+        lastRunCompletedAt = run.completed_at;
+        if (RUN_TERMINAL_STATUSES.has(run.status)) {
+            const finalNodes = await client.runs.listNodes(run_id, {
+                node_persistent_id: nodePersistentId,
+                sort: "asc",
+            });
+            const finalMatchingNodes = finalNodes.data.filter((item) => item.node_persistent_id === nodePersistentId);
+            const finalNode = pickLatestNodeExecution(finalMatchingNodes);
+            if (finalNode?.output_id &&
+                finalNode.status &&
+                NODE_READY_STATUSES.has(finalNode.status)) {
+                const output = await client.runs.getOutput(run_id, finalNode.output_id);
+                return {
+                    ok: true,
+                    runId: run_id,
+                    status: run.status,
+                    nodeOutput: output.data,
+                    completedAt: run.completed_at,
+                };
+            }
+            throw new Error(`Run reached terminal status '${run.status}' before node '${nodePersistentId}' became ready`);
+        }
+        // TODO: add response-node mode when is_response_node filtering is implemented server-side.
+        await sleep(pollIntervalMs);
+    }
+    throw new errors_1.TimeoutError(timeoutMs);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function pickLatestNodeExecution(nodes) {
+    // TODO: should return FIRST completed execution by default.
+    // Consider adding executionStrategy: "first" | "latest" to options.
+    if (nodes.length === 0) {
+        return undefined;
+    }
+    return nodes.reduce((latest, current) => {
+        const latestTs = Date.parse(latest.timestamp);
+        const currentTs = Date.parse(current.timestamp);
+        if (Number.isNaN(latestTs) || Number.isNaN(currentTs)) {
+            return current.output_id > latest.output_id ? current : latest;
+        }
+        if (currentTs > latestTs) {
+            return current;
+        }
+        if (currentTs < latestTs) {
+            return latest;
+        }
+        return current.output_id > latest.output_id ? current : latest;
+    });
+}
+//# sourceMappingURL=trigger-and-wait-for-node-output.js.map

package/helpers/trigger-and-wait-for-node-output.mjs

@@ -0,0 +1,3 @@
+import * as _cjs from "./trigger-and-wait-for-node-output.js";
+const { triggerAndWaitForNodeOutput } = _cjs;
+export { triggerAndWaitForNodeOutput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyrobot-ai/sdk",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "TypeScript SDK for the HappyRobot Public API",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -59,4 +59,4 @@
     "directory": "packages/public_api"
   },
   "dependencies": {}
-}
+}

package/resources/runs.d.ts

@@ -4,6 +4,8 @@
  * Maps to:
  *   GET    /runs
  *   GET    /runs/:run_id
+ *   GET    /runs/:run_id/nodes
+ *   GET    /runs/:run_id/outputs/:output_id
  *   GET    /runs/:run_id/sessions
  *   GET    /runs/:run_id/recordings
  *   GET    /runs/:run_id/flags
@@ -11,13 +13,17 @@
  *   POST   /runs/:run_id/mark
  */
 import type { HttpClient } from "../core/http";
-import type { RunDetail, MarkRunBody, MarkRunResponse, ListFlagsQuery, PaginatedFlagsResponse } from "../types/runs.types";
+import type { RunDetail, MarkRunBody, MarkRunResponse, ListFlagsQuery, PaginatedFlagsResponse, GetRunOutputResponse, ListRunNodesQuery, RunNodesResponse } from "../types/runs.types";
 import type { PaginatedSessionsResponse, ListSessionsQuery } from "../types/sessions.types";
 export declare class RunsResource {
     private readonly http;
     constructor(http: HttpClient);
     /** Get a run by ID. */
     get(runId: string): Promise<RunDetail>;
+    /** List node executions for a run in timestamp order. */
+    listNodes(runId: string, query?: ListRunNodesQuery): Promise<RunNodesResponse>;
+    /** Get one output payload by output ID within a run. */
+    getOutput(runId: string, outputId: string): Promise<GetRunOutputResponse>;
     /** Get sessions for a run. */
     getSessions(runId: string, query?: ListSessionsQuery): Promise<PaginatedSessionsResponse>;
     /** Get recordings for a run. */

package/resources/runs.js

@@ -5,6 +5,8 @@
  * Maps to:
  *   GET    /runs
  *   GET    /runs/:run_id
+ *   GET    /runs/:run_id/nodes
+ *   GET    /runs/:run_id/outputs/:output_id
  *   GET    /runs/:run_id/sessions
  *   GET    /runs/:run_id/recordings
  *   GET    /runs/:run_id/flags
@@ -25,6 +27,21 @@ class RunsResource {
             path: `/runs/${enc(runId)}`,
         });
     }
+    /** List node executions for a run in timestamp order. */
+    async listNodes(runId, query) {
+        return this.http.request({
+            method: "GET",
+            path: `/runs/${enc(runId)}/nodes`,
+            query: query,
+        });
+    }
+    /** Get one output payload by output ID within a run. */
+    async getOutput(runId, outputId) {
+        return this.http.request({
+            method: "GET",
+            path: `/runs/${enc(runId)}/outputs/${enc(outputId)}`,
+        });
+    }
     /** Get sessions for a run. */
     async getSessions(runId, query) {
         return this.http.request({

package/types/runs.types.d.ts

@@ -2,7 +2,7 @@
  * Run types extracted from Zod schemas.
  */
 import type { z } from "zod";
-import type { RunDetailSchema, MarkRunBodySchema, MarkRunResponseSchema, ListFlagsQuerySchema, PaginatedFlagsResponseSchema, FlagItemSchema } from "../../routes/runs/schemas";
+import type { RunDetailSchema, MarkRunBodySchema, MarkRunResponseSchema, ListFlagsQuerySchema, PaginatedFlagsResponseSchema, FlagItemSchema, GetRunOutputResponseSchema, ListRunNodesQuerySchema, ListRunNodesResponseSchema, RunNodeOutputSchema } from "../../routes/runs/schemas";
 import type { WorkflowRunsQuerySchema, PaginatedWorkflowRunsResponseSchema, TriggerRunBodySchema, TriggerRunResponseSchema } from "../../routes/workflows/:workflow_id/runs/schemas";
 export type WorkflowRunsQuery = z.input<typeof WorkflowRunsQuerySchema>;
 export type PaginatedWorkflowRunsResponse = z.infer<typeof PaginatedWorkflowRunsResponseSchema>;
@@ -14,3 +14,7 @@ export type MarkRunResponse = z.infer<typeof MarkRunResponseSchema>;
 export type ListFlagsQuery = z.input<typeof ListFlagsQuerySchema>;
 export type PaginatedFlagsResponse = z.infer<typeof PaginatedFlagsResponseSchema>;
 export type FlagItem = z.infer<typeof FlagItemSchema>;
+export type ListRunNodesQuery = z.input<typeof ListRunNodesQuerySchema>;
+export type RunNodesResponse = z.infer<typeof ListRunNodesResponseSchema>;
+export type GetRunOutputResponse = z.infer<typeof GetRunOutputResponseSchema>;
+export type RunNodeOutput = z.infer<typeof RunNodeOutputSchema>;

package/types/workflows.types.d.ts

@@ -4,7 +4,7 @@
  */
 import type { z } from "zod";
 import type { ListWorkflowsQuerySchema, WorkflowListItemSchema, PaginatedWorkflowsResponseSchema, CreateWorkflowBodySchema, CreateWorkflowResponseSchema, WorkflowDetailResponseSchema, UpdateWorkflowBodySchema, UpdateWorkflowResponseSchema, DuplicateWorkflowBodySchema, DuplicateWorkflowResponseSchema, PaginatedTemplatesResponseSchema, ListTemplatesQuerySchema, WorkflowPublishResponseSchema, WorkflowPublishErrorResponseSchema, WorkflowUnpublishResponseSchema, CancelRunsResponseSchema, ListWorkflowVersionsQuerySchema, PaginatedWorkflowVersionsResponseSchema } from "../../routes/workflows/schemas";
-export type ListWorkflowsQuery = z.input<typeof ListWorkflowsQuerySchema>;
+export type ListWorkflowsQuery = z.output<typeof ListWorkflowsQuerySchema>;
 export type WorkflowListItem = z.infer<typeof WorkflowListItemSchema>;
 export type PaginatedWorkflowsResponse = z.infer<typeof PaginatedWorkflowsResponseSchema>;
 export type CreateWorkflowBody = z.input<typeof CreateWorkflowBodySchema>;