@hatchet-dev/typescript-sdk 1.11.0 → 1.12.1

package/step.js

@@ -267,7 +267,7 @@ class V0Context {
      * @returns The name of the task.
      */
     taskName() {
-        return this.action.stepName;
+        return this.action.taskName;
     }
     /**
      * Gets the ID of the current workflow run.
@@ -280,8 +280,16 @@ class V0Context {
      * Gets the ID of the current task run.
      * @returns The task run ID.
      */
+    taskRunExternalId() {
+        return this.action.taskRunExternalId;
+    }
+    /**
+     * Gets the ID of the current task run.
+     * @returns The task run ID.
+     * @deprecated use taskRunExternalId() instead
+     */
     taskRunId() {
-        return this.action.stepRunId;
+        return this.taskRunExternalId();
     }
     /**
      * Gets the number of times the current task has been retried.
@@ -296,13 +304,13 @@ class V0Context {
      * @param level - The log level (optional).
      */
     log(message, level) {
-        const { stepRunId } = this.action;
-        if (!stepRunId) {
+        const { taskRunExternalId } = this.action;
+        if (!taskRunExternalId) {
             // log a warning
             this.logger.warn('cannot log from context without stepRunId');
             return;
         }
-        this.v0.event.putLog(stepRunId, message, level, this.retryCount());
+        this.v0.event.putLog(taskRunExternalId, message, level, this.retryCount());
     }
     /**
      * Refreshes the timeout for the current task.
@@ -311,13 +319,13 @@ class V0Context {
      */
     refreshTimeout(incrementBy) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { stepRunId } = this.action;
-            if (!stepRunId) {
+            const { taskRunExternalId } = this.action;
+            if (!taskRunExternalId) {
                 // log a warning
                 this.logger.warn('cannot refresh timeout from context without stepRunId');
                 return;
             }
-            yield this.v0.dispatcher.refreshTimeout(incrementBy, stepRunId);
+            yield this.v0.dispatcher.refreshTimeout(incrementBy, taskRunExternalId);
         });
     }
     /**
@@ -328,7 +336,7 @@ class V0Context {
     releaseSlot() {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.v0.dispatcher.client.releaseSlot({
-                stepRunId: this.action.stepRunId,
+                taskRunExternalId: this.action.taskRunExternalId,
             });
         });
     }
@@ -339,13 +347,13 @@ class V0Context {
      */
     putStream(data) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { stepRunId } = this.action;
-            if (!stepRunId) {
+            const { taskRunExternalId } = this.action;
+            if (!taskRunExternalId) {
                 // log a warning
                 this.logger.warn('cannot log from context without stepRunId');
                 return;
             }
-            yield this.v0.event.putStream(stepRunId, data, undefined);
+            yield this.v0.event.putStream(taskRunExternalId, data, undefined);
         });
     }
     /**
@@ -378,7 +386,7 @@ class V0Context {
      */
     spawnWorkflows(workflows) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { workflowRunId, stepRunId } = this.action;
+            const { workflowRunId, taskRunExternalId } = this.action;
             const workflowRuns = workflows.map(({ workflow, input, options }) => {
                 let workflowName;
                 if (typeof workflow === 'string') {
@@ -396,7 +404,7 @@ class V0Context {
                 const resp = {
                     workflowName: name,
                     input,
-                    options: Object.assign(Object.assign({}, opts), { parentId: workflowRunId, parentStepRunId: stepRunId, childIndex: this.spawnIndex, desiredWorkerId: sticky ? this.worker.id() : undefined }),
+                    options: Object.assign(Object.assign({}, opts), { parentId: workflowRunId, parentStepRunId: taskRunExternalId, childIndex: this.spawnIndex, desiredWorkerId: sticky ? this.worker.id() : undefined }),
                 };
                 this.spawnIndex += 1;
                 return resp;
@@ -463,7 +471,7 @@ class V0Context {
      */
     spawnWorkflow(workflow, input, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { workflowRunId, stepRunId } = this.action;
+            const { workflowRunId, taskRunExternalId } = this.action;
             let workflowName = '';
             if (typeof workflow === 'string') {
                 workflowName = workflow;
@@ -478,7 +486,7 @@ class V0Context {
                 throw new hatchet_error_1.default(`cannot run with sticky: workflow ${name} is not registered on the worker`);
             }
             try {
-                const resp = yield this.v0.admin.runWorkflow(name, input, Object.assign({ parentId: workflowRunId, parentStepRunId: stepRunId, childIndex: this.spawnIndex, desiredWorkerId: sticky ? this.worker.id() : undefined }, opts));
+                const resp = yield this.v0.admin.runWorkflow(name, input, Object.assign({ parentId: workflowRunId, parentStepRunId: taskRunExternalId, childIndex: this.spawnIndex, desiredWorkerId: sticky ? this.worker.id() : undefined }, opts));
                 this.spawnIndex += 1;
                 if (workflow instanceof declaration_1.TaskWorkflowDeclaration) {
                     resp._standaloneTaskName = workflow._standalone_task_name;
@@ -565,13 +573,13 @@ class V0DurableContext extends V0Context {
             // eslint-disable-next-line no-plusplus
             const key = `waitFor-${this.waitKey++}`;
             yield this.v0.durableListener.registerDurableEvent({
-                taskId: this.action.stepRunId,
+                taskId: this.action.taskRunExternalId,
                 signalKey: key,
                 sleepConditions: pbConditions.sleepConditions,
                 userEventConditions: pbConditions.userEventConditions,
             });
             const listener = this.v0.durableListener.subscribe({
-                taskId: this.action.stepRunId,
+                taskId: this.action.taskRunExternalId,
                 signalKey: key,
             });
             const event = yield listener.get();
@@ -646,7 +654,7 @@ function mapRateLimit(limits) {
     });
 }
 // Helper function to validate CEL expressions
-function validateCelExpression(expr) {
+function validateCelExpression(_expr) {
     // This is a placeholder. In a real implementation, you'd need to use a CEL parser or validator.
     // For now, we'll just return true to mimic the behavior.
     return true;

package/util/workflow-run-ref.js

@@ -126,7 +126,7 @@ class WorkflowRunRef {
                                     resolve(outputs[this._standaloneTaskName]);
                                     return;
                                 }
-                                const result = event.results.reduce((acc, r) => (Object.assign(Object.assign({}, acc), { [r.stepReadableId]: JSON.parse(r.output || '{}') })), {});
+                                const result = event.results.reduce((acc, r) => (Object.assign(Object.assign({}, acc), { [r.taskName]: JSON.parse(r.output || '{}') })), {});
                                 if (!this._standaloneTaskName) {
                                     resolve(result);
                                     return;

package/v1/client/admin.d.ts

@@ -10,6 +10,16 @@ export type WorkflowRun<T = object> = {
     input: T;
     options?: {
         parentId?: string | undefined;
+        /**
+         * (optional) the parent task run external id.
+         *
+         * This is the field understood by the workflows gRPC API (`parent_task_run_external_id`).
+         */
+        parentTaskRunExternalId?: string | undefined;
+        /**
+         * @deprecated Use `parentTaskRunExternalId` instead.
+         * Kept for backward compatibility; will be mapped to `parentTaskRunExternalId`.
+         */
         parentStepRunId?: string | undefined;
         childIndex?: number | undefined;
         childKey?: string | undefined;
@@ -33,6 +43,16 @@ export declare class AdminClient {
      */
     runWorkflow<Q = object, P = object>(workflowName: string, input: Q, options?: {
         parentId?: string | undefined;
+        /**
+         * (optional) the parent task run external id.
+         *
+         * This is the field understood by the workflows gRPC API (`parent_task_run_external_id`).
+         */
+        parentTaskRunExternalId?: string | undefined;
+        /**
+         * @deprecated Use `parentTaskRunExternalId` instead.
+         * Kept for backward compatibility; will be mapped to `parentTaskRunExternalId`.
+         */
         parentStepRunId?: string | undefined;
         childIndex?: number | undefined;
         childKey?: string | undefined;
@@ -52,6 +72,16 @@ export declare class AdminClient {
         input: Q;
         options?: {
             parentId?: string | undefined;
+            /**
+             * (optional) the parent task run external id.
+             *
+             * This is the field understood by the workflows gRPC API (`parent_task_run_external_id`).
+             */
+            parentTaskRunExternalId?: string | undefined;
+            /**
+             * @deprecated Use `parentTaskRunExternalId` instead.
+             * Kept for backward compatibility; will be mapped to `parentTaskRunExternalId`.
+             */
             parentStepRunId?: string | undefined;
             childIndex?: number | undefined;
             childKey?: string | undefined;

package/v1/client/admin.js

@@ -8,6 +8,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -43,9 +54,11 @@ class AdminClient {
             try {
                 const computedName = (0, apply_namespace_1.applyNamespace)(workflowName, this.config.namespace);
                 const inputStr = JSON.stringify(input);
-                const request = Object.assign(Object.assign({ name: computedName, input: inputStr }, options), { additionalMetadata: (options === null || options === void 0 ? void 0 : options.additionalMetadata)
-                        ? JSON.stringify(options === null || options === void 0 ? void 0 : options.additionalMetadata)
-                        : undefined, priority: options === null || options === void 0 ? void 0 : options.priority });
+                const opts = options !== null && options !== void 0 ? options : {};
+                const { additionalMetadata, parentStepRunId, parentTaskRunExternalId } = opts, rest = __rest(opts, ["additionalMetadata", "parentStepRunId", "parentTaskRunExternalId"]);
+                const request = Object.assign(Object.assign({ name: computedName, input: inputStr }, rest), { 
+                    // API expects `parentTaskRunExternalId`; accept old names as aliases.
+                    parentTaskRunExternalId: parentTaskRunExternalId !== null && parentTaskRunExternalId !== void 0 ? parentTaskRunExternalId : parentStepRunId, additionalMetadata: additionalMetadata ? JSON.stringify(additionalMetadata) : undefined, priority: opts.priority });
                 const resp = yield (0, retrier_1.retrier)(() => __awaiter(this, void 0, void 0, function* () { return this.grpc.triggerWorkflow(request); }), this.logger);
                 const id = resp.workflowRunId;
                 const ref = new workflow_run_ref_1.default(id, this.listenerClient, this.runs, options === null || options === void 0 ? void 0 : options.parentId, 
@@ -71,9 +84,11 @@ class AdminClient {
             const workflowRequests = workflowRuns.map(({ workflowName, input, options }) => {
                 const computedName = (0, apply_namespace_1.applyNamespace)(workflowName, this.config.namespace);
                 const inputStr = JSON.stringify(input);
-                return Object.assign(Object.assign({ name: computedName, input: inputStr }, options), { additionalMetadata: (options === null || options === void 0 ? void 0 : options.additionalMetadata)
-                        ? JSON.stringify(options.additionalMetadata)
-                        : undefined });
+                const opts = options !== null && options !== void 0 ? options : {};
+                const { additionalMetadata, parentStepRunId, parentTaskRunExternalId } = opts, rest = __rest(opts, ["additionalMetadata", "parentStepRunId", "parentTaskRunExternalId"]);
+                return Object.assign(Object.assign({ name: computedName, input: inputStr }, rest), { 
+                    // API expects `parentTaskRunExternalId`; accept old names as aliases.
+                    parentTaskRunExternalId: parentTaskRunExternalId !== null && parentTaskRunExternalId !== void 0 ? parentTaskRunExternalId : parentStepRunId, additionalMetadata: additionalMetadata ? JSON.stringify(additionalMetadata) : undefined });
             });
             const limit = 4 * 1024 * 1024; // FIXME configurable GRPC limit
             const batches = (0, batch_1.batch)(workflowRequests, batchSize, limit);

package/v1/client/client.d.ts

@@ -20,6 +20,7 @@ import { ScheduleClient } from './features/schedules';
 import { CronClient } from './features/crons';
 import { CELClient } from './features/cel';
 import { TenantClient } from './features/tenant';
+import { WebhooksClient } from './features/webhooks';
 /**
  * HatchetV1 implements the main client interface for interacting with the Hatchet workflow engine.
  * It provides methods for creating and executing workflows, as well as managing workers.
@@ -193,6 +194,12 @@ export declare class HatchetClient implements IHatchetClient {
      * @returns A tenant client instance
      */
     get tenant(): TenantClient;
+    private _webhooks;
+    /**
+     * Get the webhooks client for creating and managing webhooks
+     * @returns A webhooks client instance
+     */
+    get webhooks(): WebhooksClient;
     private _ratelimits;
     /**
      * Get the rate limits client for creating and managing rate limits
@@ -245,6 +252,6 @@ export declare class HatchetClient implements IHatchetClient {
      * @param workflows - The workflows to register on the webhooks
      * @returns A promise that resolves when the webhook is registered
      */
-    webhooks(workflows: V0Workflow[]): import("../../clients/worker/handler").WebhookHandler;
+    v0webhooks(workflows: V0Workflow[]): import("../../clients/worker/handler").WebhookHandler;
     runRef<T extends Record<string, any> = any>(id: string): WorkflowRunRef<T>;
 }

package/v1/client/client.js

@@ -37,6 +37,7 @@ const schedules_1 = require("./features/schedules");
 const crons_1 = require("./features/crons");
 const cel_1 = require("./features/cel");
 const tenant_1 = require("./features/tenant");
+const webhooks_1 = require("./features/webhooks");
 /**
  * HatchetV1 implements the main client interface for interacting with the Hatchet workflow engine.
  * It provides methods for creating and executing workflows, as well as managing workers.
@@ -94,7 +95,7 @@ class HatchetClient {
                         .warn('🚨⚠️‼️ YOU ARE USING A V0 ENGINE WITH A V1 SDK, WHICH IS NOT SUPPORTED. PLEASE UPGRADE YOUR ENGINE TO V1.🚨⚠️‼️');
                 }
             })
-                .catch((error) => {
+                .catch(() => {
                 // Do nothing here
             });
         }
@@ -289,6 +290,16 @@ class HatchetClient {
         }
         return this._tenant;
     }
+    /**
+     * Get the webhooks client for creating and managing webhooks
+     * @returns A webhooks client instance
+     */
+    get webhooks() {
+        if (!this._webhooks) {
+            this._webhooks = new webhooks_1.WebhooksClient(this);
+        }
+        return this._webhooks;
+    }
     /**
      * Get the rate limits client for creating and managing rate limits
      * @returns A rate limits client instance
@@ -374,7 +385,7 @@ class HatchetClient {
      * @param workflows - The workflows to register on the webhooks
      * @returns A promise that resolves when the webhook is registered
      */
-    webhooks(workflows) {
+    v0webhooks(workflows) {
         return this._v0.webhooks(workflows);
     }
     runRef(id) {

package/v1/client/features/runs.d.ts

@@ -40,12 +40,20 @@ export interface ListRunsOpts extends RunFilter {
     /** Whether to include DAGs or only to include tasks */
     onlyTasks: boolean;
     /**
-     * The parent task external id to filter by
+     * The parent task run external id to filter by
+     * @deprecated use parentTaskRunExternalId instead
      * @format uuid
      * @minLength 36
      * @maxLength 36
      */
     parentTaskExternalId?: string;
+    /**
+     * The parent task run external id to filter by
+     * @format uuid
+     * @minLength 36
+     * @maxLength 36
+     */
+    parentTaskRunExternalId?: string;
     /**
      * The triggering event external id to filter by
      * @format uuid

package/v1/client/features/runs.js

@@ -62,7 +62,9 @@ class RunsClient {
     }
     list(opts) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { data } = yield this.api.v1WorkflowRunList(this.tenantId, Object.assign({}, (yield this.prepareListFilter(opts || {}))));
+            const normalizedOpts = (opts === null || opts === void 0 ? void 0 : opts.parentTaskExternalId) && !(opts === null || opts === void 0 ? void 0 : opts.parentTaskRunExternalId)
+                ? Object.assign(Object.assign({}, opts), { parentTaskRunExternalId: opts.parentTaskExternalId }) : opts;
+            const { data } = yield this.api.v1WorkflowRunList(this.tenantId, Object.assign({}, (yield this.prepareListFilter(normalizedOpts || {}))));
             return data;
         });
     }
@@ -114,7 +116,7 @@ class RunsClient {
                 workflow_ids: yield Promise.all(((_b = opts.workflowNames) === null || _b === void 0 ? void 0 : _b.map((name) => __awaiter(this, void 0, void 0, function* () { return (yield this.workflows.get(name)).metadata.id; }))) || []),
                 additional_metadata: am,
                 only_tasks: opts.onlyTasks || false,
-                parent_task_external_id: opts.parentTaskExternalId,
+                parent_task_external_id: opts.parentTaskRunExternalId,
                 triggering_event_external_id: opts.triggeringEventExternalId,
                 include_payloads: opts.includePayloads,
             };

package/v1/client/features/webhooks.d.ts

@@ -0,0 +1,28 @@
+import { V1CreateWebhookRequestBase, V1UpdateWebhookRequest, V1Webhook, V1WebhookList, V1WebhookSourceName, V1WebhookAPIKeyAuth, V1WebhookBasicAuth, V1WebhookHMACAuth } from '../../../clients/rest/generated/data-contracts';
+import { HatchetClient } from '../client';
+export type CreateWebhookOptions = V1CreateWebhookRequestBase & {
+    auth: V1WebhookBasicAuth | V1WebhookAPIKeyAuth | V1WebhookHMACAuth;
+};
+/**
+ * Client for managing incoming webhooks in Hatchet.
+ *
+ * Webhooks allow external systems to trigger Hatchet workflows by sending HTTP
+ * requests to dedicated endpoints. This enables real-time integration with
+ * third-party services like GitHub, Stripe, Slack, or any system that can send
+ * webhook events.
+ */
+export declare class WebhooksClient {
+    api: HatchetClient['api'];
+    tenantId: string;
+    constructor(client: HatchetClient);
+    list(options?: {
+        limit?: number;
+        offset?: number;
+        webhookNames?: string[];
+        sourceNames?: V1WebhookSourceName[];
+    }): Promise<V1WebhookList>;
+    get(webhookName: string): Promise<V1Webhook>;
+    create(request: CreateWebhookOptions): Promise<V1Webhook>;
+    update(webhookName: string, options?: Partial<V1UpdateWebhookRequest>): Promise<V1Webhook>;
+    delete(webhookName: string): Promise<V1Webhook>;
+}

package/v1/client/features/webhooks.js

@@ -0,0 +1,97 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhooksClient = void 0;
+const data_contracts_1 = require("../../../clients/rest/generated/data-contracts");
+function getAuthType(auth) {
+    if ('username' in auth && 'password' in auth)
+        return data_contracts_1.V1WebhookAuthType.BASIC;
+    if ('headerName' in auth && 'apiKey' in auth)
+        return data_contracts_1.V1WebhookAuthType.API_KEY;
+    if ('signingSecret' in auth &&
+        'signatureHeaderName' in auth &&
+        'algorithm' in auth &&
+        'encoding' in auth) {
+        return data_contracts_1.V1WebhookAuthType.HMAC;
+    }
+    throw new Error('Invalid webhook auth');
+}
+function toCreateWebhookRequest(options) {
+    const { auth } = options, base = __rest(options, ["auth"]);
+    const authType = getAuthType(auth);
+    return Object.assign(Object.assign({}, base), { authType, auth });
+}
+/**
+ * Client for managing incoming webhooks in Hatchet.
+ *
+ * Webhooks allow external systems to trigger Hatchet workflows by sending HTTP
+ * requests to dedicated endpoints. This enables real-time integration with
+ * third-party services like GitHub, Stripe, Slack, or any system that can send
+ * webhook events.
+ */
+class WebhooksClient {
+    constructor(client) {
+        this.api = client.api;
+        this.tenantId = client.tenantId;
+    }
+    list(options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.api.v1WebhookList(this.tenantId, {
+                limit: options === null || options === void 0 ? void 0 : options.limit,
+                offset: options === null || options === void 0 ? void 0 : options.offset,
+                webhookNames: options === null || options === void 0 ? void 0 : options.webhookNames,
+                sourceNames: options === null || options === void 0 ? void 0 : options.sourceNames,
+            });
+            return response.data;
+        });
+    }
+    get(webhookName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.api.v1WebhookGet(this.tenantId, webhookName);
+            return response.data;
+        });
+    }
+    create(request) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const payload = toCreateWebhookRequest(request);
+            const response = yield this.api.v1WebhookCreate(this.tenantId, payload);
+            return response.data;
+        });
+    }
+    update(webhookName_1) {
+        return __awaiter(this, arguments, void 0, function* (webhookName, options = {}) {
+            const response = yield this.api.v1WebhookUpdate(this.tenantId, webhookName, {
+                eventKeyExpression: options.eventKeyExpression,
+                scopeExpression: options.scopeExpression,
+                staticPayload: options.staticPayload,
+            });
+            return response.data;
+        });
+    }
+    delete(webhookName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield this.api.v1WebhookDelete(this.tenantId, webhookName);
+            return response.data;
+        });
+    }
+}
+exports.WebhooksClient = WebhooksClient;

package/v1/client/worker/context.d.ts

@@ -112,6 +112,12 @@ export declare class Context<T, K = {}> {
      * Gets the ID of the current task run.
      * @returns The task run ID.
      */
+    taskRunExternalId(): string;
+    /**
+     * Gets the ID of the current task run.
+     * @returns The task run ID.
+     * @deprecated use taskRunExternalId() instead
+     */
     taskRunId(): string;
     /**
      * Gets the number of times the current task has been retried.