@hatchet-dev/typescript-sdk 1.13.1 → 1.15.0

package/{v1 → src/v1}/client/features/webhooks.js

@@ -21,7 +21,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WebhooksClient = void 0;
-const data_contracts_1 = require("../../../clients/rest/generated/data-contracts");
+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;
@@ -43,16 +43,21 @@ function toCreateWebhookRequest(options) {
 /**
  * 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.
+ * 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;
     }
+    /**
+     * Lists all webhooks for the current tenant.
+     * @param options - The options for the list operation.
+     * @returns A promise that resolves to the list of webhooks.
+     */
     list(options) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.api.v1WebhookList(this.tenantId, {
@@ -64,12 +69,22 @@ class WebhooksClient {
             return response.data;
         });
     }
+    /**
+     * Gets a webhook by its name.
+     * @param webhookName - The name of the webhook to get.
+     * @returns A promise that resolves to the webhook.
+     */
     get(webhookName) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.api.v1WebhookGet(this.tenantId, webhookName);
             return response.data;
         });
     }
+    /**
+     * Creates a new webhook.
+     * @param request - The request options for the create operation.
+     * @returns A promise that resolves to the created webhook.
+     */
     create(request) {
         return __awaiter(this, void 0, void 0, function* () {
             const payload = toCreateWebhookRequest(request);
@@ -77,6 +92,12 @@ class WebhooksClient {
             return response.data;
         });
     }
+    /**
+     * Updates a webhook by its name.
+     * @param webhookName - The name of the webhook to update.
+     * @param options - The options for the update operation.
+     * @returns A promise that resolves to the updated webhook.
+     */
     update(webhookName_1) {
         return __awaiter(this, arguments, void 0, function* (webhookName, options = {}) {
             const response = yield this.api.v1WebhookUpdate(this.tenantId, webhookName, {
@@ -87,6 +108,11 @@ class WebhooksClient {
             return response.data;
         });
     }
+    /**
+     * Deletes a webhook by its name.
+     * @param webhookName - The name of the webhook to delete.
+     * @returns A promise that resolves to the deleted webhook.
+     */
     delete(webhookName) {
         return __awaiter(this, void 0, void 0, function* () {
             const response = yield this.api.v1WebhookDelete(this.tenantId, webhookName);

package/src/v1/client/features/workers.d.ts

@@ -0,0 +1,38 @@
+import { HatchetClient } from '../client';
+/**
+ * The workers client is a client for managing workers programmatically within Hatchet.
+ */
+export declare class WorkersClient {
+    api: HatchetClient['api'];
+    tenantId: string;
+    constructor(client: HatchetClient);
+    /**
+     * Get a worker by its ID.
+     * @param workerId - The ID of the worker to get.
+     * @returns A promise that resolves to the worker.
+     */
+    get(workerId: string): Promise<import("../../../clients/rest/generated/data-contracts").Worker>;
+    /**
+     * List all workers in the tenant.
+     * @returns A promise that resolves to the list of workers.
+     */
+    list(): Promise<import("../../../clients/rest/generated/data-contracts").WorkerList>;
+    /**
+     * Check if a worker is paused.
+     * @param workerId - The ID of the worker to check.
+     * @returns A promise that resolves to true if the worker is paused, false otherwise.
+     */
+    isPaused(workerId: string): Promise<boolean>;
+    /**
+     * Pause a worker.
+     * @param workerId - The ID of the worker to pause.
+     * @returns A promise that resolves to the paused worker.
+     */
+    pause(workerId: string): Promise<import("../../../clients/rest/generated/data-contracts").Worker>;
+    /**
+     * Unpause a worker.
+     * @param workerId - The ID of the worker to unpause.
+     * @returns A promise that resolves to the unpaused worker.
+     */
+    unpause(workerId: string): Promise<import("../../../clients/rest/generated/data-contracts").Worker>;
+}

package/{v1 → src/v1}/client/features/workers.js

@@ -11,31 +11,50 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkersClient = void 0;
 /**
- * WorkersClient is used to list and manage workers
+ * The workers client is a client for managing workers programmatically within Hatchet.
  */
 class WorkersClient {
     constructor(client) {
         this.api = client.api;
         this.tenantId = client.tenantId;
     }
+    /**
+     * Get a worker by its ID.
+     * @param workerId - The ID of the worker to get.
+     * @returns A promise that resolves to the worker.
+     */
     get(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerGet(workerId);
             return data;
         });
     }
+    /**
+     * List all workers in the tenant.
+     * @returns A promise that resolves to the list of workers.
+     */
     list() {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerList(this.tenantId);
             return data;
         });
     }
+    /**
+     * Check if a worker is paused.
+     * @param workerId - The ID of the worker to check.
+     * @returns A promise that resolves to true if the worker is paused, false otherwise.
+     */
     isPaused(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const wf = yield this.get(workerId);
             return wf.status === 'PAUSED';
         });
     }
+    /**
+     * Pause a worker.
+     * @param workerId - The ID of the worker to pause.
+     * @returns A promise that resolves to the paused worker.
+     */
     pause(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerUpdate(workerId, {
@@ -44,6 +63,11 @@ class WorkersClient {
             return data;
         });
     }
+    /**
+     * Unpause a worker.
+     * @param workerId - The ID of the worker to unpause.
+     * @returns A promise that resolves to the unpaused worker.
+     */
     unpause(workerId) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workerUpdate(workerId, {

package/src/v1/client/features/workflows.d.ts

@@ -0,0 +1,42 @@
+import { BaseWorkflowDeclaration, WorkflowDefinition } from '../../../../v1';
+import type { LegacyWorkflow } from '../../../../legacy/legacy-transformer';
+import { HatchetClient } from '../client';
+export declare const workflowNameString: (workflow: string | WorkflowDefinition | BaseWorkflowDeclaration<any, any> | LegacyWorkflow) => string;
+/**
+ * The workflows client is a client for managing workflows programmatically within Hatchet.
+ *
+ * NOTE: that workflows are the declaration, not the individual runs. If you're looking for runs, use the RunsClient instead.
+ *
+ */
+export declare class WorkflowsClient {
+    api: HatchetClient['api'];
+    tenantId: string;
+    private workflowCache;
+    private cacheTTL;
+    constructor(client: HatchetClient, cacheTTL?: number);
+    /**
+     * Gets the workflow ID from a workflow name, ID, or object.
+     * If the input is not a valid UUID, it will look up the workflow by name.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns The workflow ID as a string.
+     */
+    getWorkflowIdFromName(workflow: string | WorkflowDefinition | BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<string>;
+    /**
+     * Get a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the workflow.
+     */
+    get(workflow: string | BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<import("../../../clients/rest/generated/data-contracts").Workflow>;
+    /**
+     * List all workflows in the tenant.
+     * @param opts - The options for the list operation.
+     * @returns A promise that resolves to the list of workflows.
+     */
+    list(opts?: Parameters<typeof this.api.workflowList>[1]): Promise<import("../../../clients/rest/generated/data-contracts").WorkflowList>;
+    /**
+     * Delete a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the deleted workflow.
+     */
+    delete(workflow: string | BaseWorkflowDeclaration<any, any> | LegacyWorkflow): Promise<void>;
+}

package/{v1 → src/v1}/client/features/workflows.js

@@ -10,19 +10,27 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowsClient = exports.workflowNameString = void 0;
-const uuid_1 = require("../../../util/uuid");
+const legacy_transformer_1 = require("../../../../legacy/legacy-transformer");
+const uuid_1 = require("../../../../util/uuid");
 const workflowNameString = (workflow) => {
     if (typeof workflow === 'string') {
         return workflow;
     }
-    if (typeof workflow === 'object' && 'id' in workflow) {
+    if (typeof workflow === 'object' && 'name' in workflow) {
+        return workflow.name;
+    }
+    if ((0, legacy_transformer_1.isLegacyWorkflow)(workflow)) {
+        (0, legacy_transformer_1.warnLegacyWorkflow)();
         return workflow.id;
     }
-    return workflow.name;
+    throw new Error('Invalid workflow: must be a string, Workflow object, or WorkflowDefinition object');
 };
 exports.workflowNameString = workflowNameString;
 /**
- * WorkflowsClient is used to list and manage workflows
+ * The workflows client is a client for managing workflows programmatically within Hatchet.
+ *
+ * NOTE: that workflows are the declaration, not the individual runs. If you're looking for runs, use the RunsClient instead.
+ *
  */
 class WorkflowsClient {
     constructor(client, cacheTTL) {
@@ -52,12 +60,6 @@ class WorkflowsClient {
                 if (typeof workflow === 'object' && 'name' in workflow) {
                     return workflow.name;
                 }
-                if (typeof workflow === 'object' && 'id' in workflow) {
-                    if (!workflow.id) {
-                        throw new Error('Workflow ID is required');
-                    }
-                    return workflow.id;
-                }
                 throw new Error('Invalid workflow: must be a string, Workflow object, or WorkflowDefinition object');
             })();
             if (!(0, uuid_1.isValidUUID)(str)) {
@@ -70,6 +72,11 @@ class WorkflowsClient {
             return str;
         });
     }
+    /**
+     * Get a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the workflow.
+     */
     get(workflow) {
         return __awaiter(this, void 0, void 0, function* () {
             // Get workflow name string
@@ -104,12 +111,22 @@ class WorkflowsClient {
             }
         });
     }
+    /**
+     * List all workflows in the tenant.
+     * @param opts - The options for the list operation.
+     * @returns A promise that resolves to the list of workflows.
+     */
     list(opts) {
         return __awaiter(this, void 0, void 0, function* () {
             const { data } = yield this.api.workflowList(this.tenantId, opts);
             return data;
         });
     }
+    /**
+     * Delete a workflow by its name, ID, or object.
+     * @param workflow - The workflow name, ID, or object.
+     * @returns A promise that resolves to the deleted workflow.
+     */
     delete(workflow) {
         return __awaiter(this, void 0, void 0, function* () {
             const name = (0, exports.workflowNameString)(workflow);

package/{v1 → src/v1}/client/worker/context.d.ts

@@ -1,15 +1,24 @@
-import { Priority, RunOpts, TaskWorkflowDeclaration, BaseWorkflowDeclaration as WorkflowV1 } from '../../declaration';
+/**
+ * The Hatchet Context class provides helper methods and useful data to tasks at runtime. It is passed as the second argument to all tasks and durable tasks.
+ *
+ * There are two types of context classes you'll encounter:
+ *
+ * - Context - The standard context for regular tasks with methods for logging, task output retrieval, cancellation, and more.
+ * - DurableContext - An extended context for durable tasks that includes additional methods for durable execution.
+ * @module Context
+ */
+import { Priority, RunOpts, TaskWorkflowDeclaration, BaseWorkflowDeclaration as WorkflowV1 } from '../../../../v1/declaration';
 import { JsonObject } from '@bufbuild/protobuf';
-import { Action } from '../../../clients/dispatcher/action-listener';
-import { Logger, LogLevel } from '../../../util/logger';
-import WorkflowRunRef from '../../../util/workflow-run-ref';
-import { Conditions } from '../../conditions';
-import { CreateWorkflowDurableTaskOpts, CreateWorkflowTaskOpts } from '../../task';
-import { OutputType } from '../../types';
-import { Workflow } from '../../../workflow';
-import { HatchetClient } from '../..';
-import { ContextWorker, NextStep } from '../../../step';
-import { V1Worker } from './worker-internal';
+import { Action } from '../../../../clients/dispatcher/action-listener';
+import { Logger, LogLevel } from '../../../../util/logger';
+import WorkflowRunRef from '../../../../util/workflow-run-ref';
+import { Conditions } from '../../../../v1/conditions';
+import { CreateWorkflowDurableTaskOpts, CreateWorkflowTaskOpts } from '../../../../v1/task';
+import { OutputType } from '../../../../v1/types';
+import { HatchetClient } from '../../../../v1';
+import { WorkerLabels } from '../../../../clients/dispatcher/dispatcher-client';
+import { NextStep } from '../../../../legacy/step';
+import { InternalWorker } from './worker-internal';
 import { Duration } from '../duration';
 type TriggerData = Record<string, Record<string, any>>;
 type ChildRunOpts = RunOpts & {
@@ -28,6 +37,35 @@ interface ContextData<T, K> {
     user_data: K;
     step_run_errors: Record<string, string>;
 }
+/**
+ * ContextWorker is a wrapper around the V1Worker class that provides a more user-friendly interface for the worker from the context of a run.
+ */
+export declare class ContextWorker {
+    private worker;
+    constructor(worker: InternalWorker);
+    /**
+     * Gets the ID of the worker.
+     * @returns The ID of the worker.
+     */
+    id(): string | undefined;
+    /**
+     * Checks if the worker has a registered workflow.
+     * @param workflowName - The name of the workflow to check.
+     * @returns True if the workflow is registered, otherwise false.
+     */
+    hasWorkflow(workflowName: string): boolean;
+    /**
+     * Gets the current state of the worker labels.
+     * @returns The labels of the worker.
+     */
+    labels(): WorkerLabels;
+    /**
+     * Upserts the a set of labels on the worker.
+     * @param labels - The labels to upsert.
+     * @returns A promise that resolves when the labels have been upserted.
+     */
+    upsertLabels(labels: WorkerLabels): Promise<WorkerLabels>;
+}
 export declare class Context<T, K = {}> {
     data: ContextData<T, K>;
     input: T;
@@ -39,9 +77,19 @@ export declare class Context<T, K = {}> {
     _logger: Logger;
     spawnIndex: number;
     streamIndex: number;
-    constructor(action: Action, v1: HatchetClient, worker: V1Worker);
+    constructor(action: Action, v1: HatchetClient, worker: InternalWorker);
     get abortController(): AbortController;
     get cancelled(): boolean;
+    protected throwIfCancelled(): void;
+    /**
+     * Helper for broad `catch` blocks so cancellation isn't accidentally swallowed.
+     *
+     * Example:
+     * ```ts
+     * try { ... } catch (e) { ctx.rethrowIfCancelled(e); ... }
+     * ```
+     */
+    rethrowIfCancelled(err: unknown): void;
     cancel(): Promise<void>;
     /**
      * Retrieves the output of a parent task.
@@ -55,6 +103,7 @@ export declare class Context<T, K = {}> {
      * @returns A record mapping task names to error messages.
      * @throws A warning if no errors are found (this method should be used in on-failure tasks).
      * @deprecated use ctx.errors() instead
+     * @hidden
      */
     stepRunErrors(): Record<string, string>;
     /**
@@ -117,6 +166,7 @@ export declare class Context<T, K = {}> {
      * Gets the ID of the current task run.
      * @returns The task run ID.
      * @deprecated use taskRunExternalId() instead
+     * @hidden
      */
     taskRunId(): string;
     /**
@@ -129,6 +179,7 @@ export declare class Context<T, K = {}> {
      * @param message - The message to log.
      * @param level - The log level (optional).
      * @deprecated use ctx.logger.infoger.info, ctx.logger.infoger.debug, ctx.logger.infoger.warn, ctx.logger.infoger.error, ctx.logger.infoger.trace instead
+     * @hidden
      */
     log(message: string, level?: LogLevel, extra?: LogExtra): Promise<void> | Promise<void[]>;
     get logger(): {
@@ -165,7 +216,7 @@ export declare class Context<T, K = {}> {
      * @returns A list of workflow run references to the enqueued runs.
      */
     bulkRunNoWaitChildren<Q extends JsonObject = any, P extends JsonObject = any>(children: Array<{
-        workflow: string | Workflow | WorkflowV1<Q, P>;
+        workflow: string | WorkflowV1<Q, P>;
         input: Q;
         options?: ChildRunOpts;
     }>): Promise<WorkflowRunRef<P>[]>;
@@ -175,7 +226,7 @@ export declare class Context<T, K = {}> {
      * @returns A list of results from the children workflows.
      */
     bulkRunChildren<Q extends JsonObject = any, P extends JsonObject = any>(children: Array<{
-        workflow: string | Workflow | WorkflowV1<Q, P>;
+        workflow: string | WorkflowV1<Q, P>;
         input: Q;
         options?: ChildRunOpts;
     }>): Promise<P[]>;
@@ -187,7 +238,7 @@ export declare class Context<T, K = {}> {
      * @param options - An options object containing key, sticky, priority, and additionalMetadata.
      * @returns The result of the workflow.
      */
-    runChild<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>, input: Q, options?: ChildRunOpts): Promise<P>;
+    runChild<Q extends JsonObject, P extends JsonObject>(workflow: string | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>, input: Q, options?: ChildRunOpts): Promise<P>;
     /**
      * Enqueues a new workflow without waiting for its result.
      *
@@ -196,7 +247,7 @@ export declare class Context<T, K = {}> {
      * @param options - An options object containing key, sticky, priority, and additionalMetadata.
      * @returns A reference to the spawned workflow run.
      */
-    runNoWaitChild<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P>, input: Q, options?: ChildRunOpts): Promise<WorkflowRunRef<P>>;
+    runNoWaitChild<Q extends JsonObject, P extends JsonObject>(workflow: string | WorkflowV1<Q, P>, input: Q, options?: ChildRunOpts): Promise<WorkflowRunRef<P>>;
     /**
      * Retrieves additional metadata associated with the current workflow run.
      * @returns A record of metadata key-value pairs.
@@ -224,18 +275,21 @@ export declare class Context<T, K = {}> {
      * @returns The output of the task.
      * @throws An error if the task output is not found.
      * @deprecated use ctx.parentOutput instead
+     * @hidden
      */
     stepOutput<L = NextStep>(step: string): L;
     /**
      * Gets the input data for the current workflow.
      * @returns The input data for the workflow.
      * @deprecated use task input parameter instead
+     * @hidden
      */
     workflowInput(): T;
     /**
      * Gets the name of the current task.
      * @returns The name of the task.
      * @deprecated use ctx.taskName instead
+     * @hidden
      */
     stepName(): string;
     /**
@@ -244,9 +298,10 @@ export declare class Context<T, K = {}> {
      * @param workflows - An array of objects containing the workflow name, input data, and options for each workflow.
      * @returns A list of references to the spawned workflow runs.
      * @deprecated Use bulkRunNoWaitChildren or bulkRunChildren instead.
+     * @hidden
      */
     spawnWorkflows<Q extends JsonObject = any, P extends JsonObject = any>(workflows: Array<{
-        workflow: string | Workflow | WorkflowV1<Q, P>;
+        workflow: string | WorkflowV1<Q, P>;
         input: Q;
         options?: ChildRunOpts;
     }>): Promise<WorkflowRunRef<P>[]>;
@@ -258,10 +313,15 @@ export declare class Context<T, K = {}> {
      * @param options - Additional options for spawning the workflow.
      * @returns A reference to the spawned workflow run.
      * @deprecated Use runChild or runNoWaitChild instead.
+     * @hidden
      */
-    spawnWorkflow<Q extends JsonObject, P extends JsonObject>(workflow: string | Workflow | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>, input: Q, options?: ChildRunOpts): Promise<WorkflowRunRef<P>>;
+    spawnWorkflow<Q extends JsonObject, P extends JsonObject>(workflow: string | WorkflowV1<Q, P> | TaskWorkflowDeclaration<Q, P>, input: Q, options?: ChildRunOpts): Promise<WorkflowRunRef<P>>;
     _incrementStreamIndex(): number;
 }
+/**
+ * DurableContext provides helper methods and useful data to durable tasks at runtime.
+ * It extends the Context class and includes additional methods for durable execution like sleepFor and waitFor.
+ */
 export declare class DurableContext<T, K = {}> extends Context<T, K> {
     waitKey: number;
     /**