@hatchet-dev/typescript-sdk 1.34.0-alpha.1 → 1.34.0

package/clients/transport/index.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toConnectCallOptions = exports.metadataToHeaders = exports.headersToMetadata = exports.createTsProtoClient = exports.toProtobufEs = exports.fromProtobufEs = exports.createNodeTransport = exports.createAuthInterceptor = void 0;
+exports.toConnectCallOptions = exports.metadataToHeaders = exports.headersToMetadata = exports.createTsProtoClient = exports.toProtobufEs = exports.fromProtobufEs = exports.resolveServerUrl = exports.limitMessageSizes = exports.createFetchTransport = exports.createNodeTransport = exports.DEFAULT_MAX_MESSAGE_BYTES = exports.createAuthInterceptor = void 0;
 var transport_1 = require("./transport");
 Object.defineProperty(exports, "createAuthInterceptor", { enumerable: true, get: function () { return transport_1.createAuthInterceptor; } });
+Object.defineProperty(exports, "DEFAULT_MAX_MESSAGE_BYTES", { enumerable: true, get: function () { return transport_1.DEFAULT_MAX_MESSAGE_BYTES; } });
 var node_transport_1 = require("./node-transport");
 Object.defineProperty(exports, "createNodeTransport", { enumerable: true, get: function () { return node_transport_1.createNodeTransport; } });
+var fetch_transport_1 = require("./fetch-transport");
+Object.defineProperty(exports, "createFetchTransport", { enumerable: true, get: function () { return fetch_transport_1.createFetchTransport; } });
+Object.defineProperty(exports, "limitMessageSizes", { enumerable: true, get: function () { return fetch_transport_1.limitMessageSizes; } });
+Object.defineProperty(exports, "resolveServerUrl", { enumerable: true, get: function () { return fetch_transport_1.resolveServerUrl; } });
 var message_bridge_1 = require("./message-bridge");
 Object.defineProperty(exports, "fromProtobufEs", { enumerable: true, get: function () { return message_bridge_1.fromProtobufEs; } });
 Object.defineProperty(exports, "toProtobufEs", { enumerable: true, get: function () { return message_bridge_1.toProtobufEs; } });

package/clients/transport/node-transport.js

@@ -8,7 +8,6 @@ const fs_1 = require("fs");
 const connect_node_1 = require("@connectrpc/connect-node");
 const grpc_target_1 = require("./grpc-target");
 const transport_1 = require("./transport");
-const DEFAULT_MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
 /**
  * The largest message size Connect can enforce (a 32-bit length prefix). The config schema
  * accepts any positive integer, as grpc-js does, so a larger configured limit is clamped to it
@@ -16,7 +15,7 @@ const DEFAULT_MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
  */
 exports.MAX_MESSAGE_BYTES = 0xffffffff;
 function messageLimit(configured) {
-    return Math.min(configured !== null && configured !== void 0 ? configured : DEFAULT_MAX_MESSAGE_BYTES, exports.MAX_MESSAGE_BYTES);
+    return Math.min(configured !== null && configured !== void 0 ? configured : transport_1.DEFAULT_MAX_MESSAGE_BYTES, exports.MAX_MESSAGE_BYTES);
 }
 /**
  * The connection settings the `nice-grpc` channel uses (`grpc.keepalive_time_ms`,

package/clients/transport/transport.d.ts

@@ -5,6 +5,12 @@ import type { Interceptor, Transport } from '@connectrpc/connect';
  * interceptors that apply to every call.
  */
 export type { Transport };
+/**
+ * The largest message either transport accepts or sends unless configured otherwise: the
+ * grpc-js default the `grpc_max_recv_message_length` and `grpc_max_send_message_length`
+ * settings override.
+ */
+export declare const DEFAULT_MAX_MESSAGE_BYTES: number;
 /**
  * Sets the bearer token the engine authenticates every call with. The transport applies it to
  * each request, so callers never pass credentials per call. A token that cannot be carried in a

package/clients/transport/transport.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_MESSAGE_BYTES = void 0;
 exports.createAuthInterceptor = createAuthInterceptor;
+/**
+ * The largest message either transport accepts or sends unless configured otherwise: the
+ * grpc-js default the `grpc_max_recv_message_length` and `grpc_max_send_message_length`
+ * settings override.
+ */
+exports.DEFAULT_MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
 /**
  * The characters a token may contain and still travel in an HTTP header: the printable ASCII
  * range, which is also what grpc-js accepts in metadata. Anything else would make the header

package/clients/transport/ts-proto-client.js

@@ -111,6 +111,20 @@ function toConnectCallOptions(options) {
     }
     return connect;
 }
+/*
+ * Binary metadata is base64 on the wire. These use the standard `btoa`/`atob` rather than
+ * `Buffer`, since the fetch transport runs where `Buffer` does not exist.
+ */
+function bytesToBase64(bytes) {
+    let binary = '';
+    for (const byte of bytes) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary);
+}
+function base64ToBytes(base64) {
+    return Uint8Array.from(atob(base64), (char) => char.charCodeAt(0));
+}
 /**
  * gRPC metadata as HTTP headers: binary values (keys ending in `-bin`) are base64 encoded,
  * which is how they travel on the wire in every gRPC implementation.
@@ -119,7 +133,7 @@ function metadataToHeaders(metadata) {
     const headers = new Headers();
     for (const [key, values] of metadata) {
         for (const value of values) {
-            headers.append(key, typeof value === 'string' ? value : Buffer.from(value).toString('base64'));
+            headers.append(key, typeof value === 'string' ? value : bytesToBase64(value));
         }
     }
     return headers;
@@ -133,7 +147,7 @@ function headersToMetadata(headers) {
     const metadata = (0, nice_grpc_common_1.Metadata)();
     headers.forEach((value, key) => {
         if (key.endsWith('-bin')) {
-            metadata.set(key, value.split(',').map((part) => new Uint8Array(Buffer.from(part.trim(), 'base64'))));
+            metadata.set(key, value.split(',').map((part) => base64ToBytes(part.trim())));
         }
         else {
             metadata.set(key, value);

package/core/client.d.ts

@@ -0,0 +1,102 @@
+import type { Transport } from '@connectrpc/connect';
+import type { Logger } from '../util/logger/logger';
+import { BaseWorkflowDeclaration, type RunManyOpt } from '../v1/declaration';
+import type { InputType, OutputType, UnknownInputType } from '../v1/types';
+import { EventsClient } from './features/events';
+import { LogsClient } from './features/logs';
+import { RateLimitsClient } from './features/rate-limits';
+import { RunsClient } from './features/runs';
+import { StreamsClient } from './features/streams';
+import { WorkflowsClient } from './features/workflows';
+import { WorkflowRunRef } from './run-ref';
+import type { CoreClientConfig, TriggerRunOptions } from './types';
+/** A workflow to run: a declaration from `/edge`, anything with a `name`, or the name itself. */
+export type WorkflowRef<I extends InputType = UnknownInputType, O extends OutputType = void> = BaseWorkflowDeclaration<I, O> | {
+    name: string;
+} | string;
+/**
+ * The resolved client configuration: what the client was built with, plus the values derived
+ * from it.
+ */
+export interface ResolvedCoreConfig {
+    serverUrl: string;
+    tenantId: string;
+    namespace: string;
+    logLevel: CoreClientConfig['logLevel'];
+    retrier: CoreClientConfig['retrier'];
+}
+/**
+ * The application client for runtimes without gRPC: it triggers runs, pushes events, waits
+ * for results and manages workflows over unary Connect calls on a fetch transport, so it runs
+ * in Cloudflare Workers, Vercel Functions, Deno, Bun, browsers and Node alike.
+ *
+ * It is configured from an explicit object only. Nothing is read from the environment or a
+ * config file, and no worker can be started from it; workers stay on the Node client.
+ *
+ * ```typescript
+ * import { Hatchet } from './';
+ *
+ * const hatchet = new Hatchet({ token: env.HATCHET_CLIENT_TOKEN });
+ * const output = await hatchet.run('greet', { name: 'world' });
+ * ```
+ */
+export declare class HatchetCore {
+    readonly config: ResolvedCoreConfig;
+    /** The transport every call goes through. */
+    readonly transport: Transport;
+    readonly logger: Logger;
+    /** Pushes events. */
+    readonly events: EventsClient;
+    /** Gets, cancels and replays runs. */
+    readonly runs: RunsClient;
+    /** Registers workflows. */
+    readonly workflows: WorkflowsClient;
+    /** Creates and updates rate limits. */
+    readonly rateLimits: RateLimitsClient;
+    /** Writes task run log lines. */
+    readonly logs: LogsClient;
+    /** Publishes task run stream chunks. */
+    readonly streams: StreamsClient;
+    private readonly workflowsRpc;
+    private readonly adminRpc;
+    private readonly eventsRpc;
+    constructor(config: CoreClientConfig);
+    /** The same as `new HatchetCore(config)`, mirroring the Node client's `init`. */
+    static init(config: CoreClientConfig): HatchetCore;
+    /** The tenant the token belongs to. */
+    get tenantId(): string;
+    /**
+     * Triggers a run and returns a reference to it without waiting.
+     *
+     * The options are the Node client's `admin.runWorkflow` options and go to the engine as
+     * is: the workflow name is namespaced and lowercased and the input is JSON. A task
+     * declaration's reference resolves to the task's own output.
+     */
+    runNoWait<I extends InputType = UnknownInputType, O extends OutputType = void>(workflow: WorkflowRef<I, O>, input: I, options?: TriggerRunOptions): Promise<WorkflowRunRef<O>>;
+    /** Triggers a run and waits for its output; see `WorkflowRunRef.result()` for the wait. */
+    run<I extends InputType = UnknownInputType, O extends OutputType = void>(workflow: WorkflowRef<I, O>, input: I, options?: TriggerRunOptions): Promise<O>;
+    /**
+     * Triggers many runs of one workflow in batches of 500 (or 4 MB) over `BulkTriggerWorkflow`
+     * and returns their references in input order. `runs` takes the `RunManyOpt` entries the
+     * declarations' `runMany` takes.
+     *
+     * Each batch is one call, so a failure part way through leaves the earlier batches' runs
+     * created. That failure rejects with a `BulkTriggerPartialError` whose `refs` are those runs'
+     * references and whose `cause` is the batch's own error, so the caller can keep or cancel
+     * them instead of retrying the whole request and creating them twice. A failure of the
+     * first batch rejects with the batch's error itself: a
+     * `BulkTriggerIdempotencyCollisionError` on an idempotency key collision, otherwise a
+     * `HatchetError`.
+     */
+    runManyNoWait<I extends InputType = UnknownInputType, O extends OutputType = void>(workflow: WorkflowRef<I, O>, runs: RunManyOpt<I>[]): Promise<WorkflowRunRef<O>[]>;
+    /**
+     * Triggers many runs of one workflow and waits for all of their outputs, in input order.
+     *
+     * When any entry sets `opts.returnExceptions`, a failed run does not reject the whole
+     * wait: its slot holds an `Error` instead (a task error list is joined with `; `), the way
+     * a declaration's `runMany` behaves on the Node client.
+     */
+    runMany<I extends InputType = UnknownInputType, O extends OutputType = void>(workflow: WorkflowRef<I, O>, runs: RunManyOpt<I>[]): Promise<O[]>;
+    /** A reference to an existing run, to wait on, cancel or replay it. */
+    runRef<T = unknown>(id: string): WorkflowRunRef<T>;
+}

package/core/client.js

@@ -0,0 +1,250 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HatchetCore = void 0;
+const hatchet_error_1 = __importDefault(require("../util/errors/hatchet-error"));
+const idempotency_collision_error_1 = require("../util/errors/idempotency-collision-error");
+const bulk_trigger_partial_error_1 = require("../util/errors/bulk-trigger-partial-error");
+const fetch_transport_1 = require("../clients/transport/fetch-transport");
+const rpc_1 = require("../clients/admin/rpc");
+const trigger_request_1 = require("../clients/admin/trigger-request");
+const rpc_2 = require("../clients/event/rpc");
+const workflows_1 = require("../protoc/workflows");
+const token_1 = require("../util/config-loader/token");
+const batch_1 = require("../util/batch");
+const retrier_1 = require("../util/retrier");
+const declaration_1 = require("../v1/declaration");
+const events_1 = require("./features/events");
+const logs_1 = require("./features/logs");
+const rate_limits_1 = require("./features/rate-limits");
+const runs_1 = require("./features/runs");
+const streams_1 = require("./features/streams");
+const workflows_2 = require("./features/workflows");
+const logger_1 = require("./logger");
+const run_ref_1 = require("./run-ref");
+const BULK_TRIGGER_BATCH_SIZE = 500;
+const BULK_TRIGGER_MAX_BYTES = 4 * 1024 * 1024;
+/**
+ * The application client for runtimes without gRPC: it triggers runs, pushes events, waits
+ * for results and manages workflows over unary Connect calls on a fetch transport, so it runs
+ * in Cloudflare Workers, Vercel Functions, Deno, Bun, browsers and Node alike.
+ *
+ * It is configured from an explicit object only. Nothing is read from the environment or a
+ * config file, and no worker can be started from it; workers stay on the Node client.
+ *
+ * ```typescript
+ * import { Hatchet } from './index.js';
+ *
+ * const hatchet = new Hatchet({ token: env.HATCHET_CLIENT_TOKEN });
+ * const output = await hatchet.run('greet', { name: 'world' });
+ * ```
+ */
+class HatchetCore {
+    constructor(config) {
+        var _a, _b, _c;
+        if (!config.token) {
+            throw new hatchet_error_1.default('a token is required to create a Hatchet client');
+        }
+        const tenantId = (0, token_1.getTenantIdFromJWT)(config.token);
+        // a caller-supplied transport owns its base URL, auth and limits, so no address is resolved
+        const serverUrl = config.transport ? ((_a = config.serverUrl) !== null && _a !== void 0 ? _a : '') : resolveServerUrl(config);
+        const namespace = normalizeNamespace(config.namespace);
+        const logger = (_b = config.logger) !== null && _b !== void 0 ? _b : logger_1.consoleLogger;
+        this.config = {
+            serverUrl,
+            tenantId,
+            namespace,
+            logLevel: config.logLevel,
+            retrier: config.retrier,
+        };
+        this.logger = logger('HatchetCore', config.logLevel);
+        this.transport =
+            (_c = config.transport) !== null && _c !== void 0 ? _c : (0, fetch_transport_1.createFetchTransport)({
+                token: config.token,
+                serverUrl,
+                tls: config.tls,
+                fetch: config.fetch,
+                maxReceiveMessageBytes: config.maxReceiveMessageBytes,
+                maxSendMessageBytes: config.maxSendMessageBytes,
+            });
+        this.workflowsRpc = (0, rpc_1.createWorkflowsRpc)(this.transport);
+        this.adminRpc = (0, rpc_1.createV1AdminRpc)(this.transport);
+        this.eventsRpc = (0, rpc_2.createEventsRpc)(this.transport);
+        const shared = { logger: this.logger, namespace, retrier: config.retrier };
+        this.events = new events_1.EventsClient(Object.assign({ rpc: this.eventsRpc }, shared));
+        this.runs = new runs_1.RunsClient(this.adminRpc);
+        this.workflows = new workflows_2.WorkflowsClient(Object.assign({ rpc: this.adminRpc }, shared));
+        this.rateLimits = new rate_limits_1.RateLimitsClient(Object.assign({ rpc: this.workflowsRpc }, shared));
+        this.logs = new logs_1.LogsClient(this.eventsRpc);
+        this.streams = new streams_1.StreamsClient(this.eventsRpc);
+    }
+    /** The same as `new HatchetCore(config)`, mirroring the Node client's `init`. */
+    static init(config) {
+        return new HatchetCore(config);
+    }
+    /** The tenant the token belongs to. */
+    get tenantId() {
+        return this.config.tenantId;
+    }
+    /**
+     * Triggers a run and returns a reference to it without waiting.
+     *
+     * The options are the Node client's `admin.runWorkflow` options and go to the engine as
+     * is: the workflow name is namespaced and lowercased and the input is JSON. A task
+     * declaration's reference resolves to the task's own output.
+     */
+    runNoWait(workflow_1, input_1) {
+        return __awaiter(this, arguments, void 0, function* (workflow, input, options = {}) {
+            var _a;
+            const request = (0, trigger_request_1.buildTriggerWorkflowRequest)(workflowName(workflow), input, options, this.config.namespace);
+            try {
+                const response = yield (0, retrier_1.retrier)(() => this.workflowsRpc.triggerWorkflow(request), this.logger, Object.assign(Object.assign({}, this.config.retrier), { shouldRetry: (e) => !(0, trigger_request_1.isAlreadyExists)(e) }));
+                return new run_ref_1.WorkflowRunRef(response.workflowRunId, this.runs, options.parentId, (_a = options._standaloneTaskName) !== null && _a !== void 0 ? _a : standaloneTaskName(workflow));
+            }
+            catch (e) {
+                if ((0, trigger_request_1.isAlreadyExists)(e)) {
+                    throw new idempotency_collision_error_1.IdempotencyCollisionError((0, trigger_request_1.extractExistingRunId)(e));
+                }
+                throw new hatchet_error_1.default(e instanceof Error ? e.message : String(e));
+            }
+        });
+    }
+    /** Triggers a run and waits for its output; see `WorkflowRunRef.result()` for the wait. */
+    run(workflow_1, input_1) {
+        return __awaiter(this, arguments, void 0, function* (workflow, input, options = {}) {
+            const ref = yield this.runNoWait(workflow, input, options);
+            return ref.result();
+        });
+    }
+    /**
+     * Triggers many runs of one workflow in batches of 500 (or 4 MB) over `BulkTriggerWorkflow`
+     * and returns their references in input order. `runs` takes the `RunManyOpt` entries the
+     * declarations' `runMany` takes.
+     *
+     * Each batch is one call, so a failure part way through leaves the earlier batches' runs
+     * created. That failure rejects with a `BulkTriggerPartialError` whose `refs` are those runs'
+     * references and whose `cause` is the batch's own error, so the caller can keep or cancel
+     * them instead of retrying the whole request and creating them twice. A failure of the
+     * first batch rejects with the batch's error itself: a
+     * `BulkTriggerIdempotencyCollisionError` on an idempotency key collision, otherwise a
+     * `HatchetError`.
+     */
+    runManyNoWait(workflow, runs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const name = workflowName(workflow);
+            const taskName = standaloneTaskName(workflow);
+            const requests = runs.map((run) => (0, trigger_request_1.buildTriggerWorkflowRequest)(name, run.input, runOptsToTrigger(run.opts), this.config.namespace));
+            const batches = (0, batch_1.batch)(requests, BULK_TRIGGER_BATCH_SIZE, BULK_TRIGGER_MAX_BYTES);
+            const refs = [];
+            for (const { batchIndex, payloads } of batches) {
+                const request = workflows_1.BulkTriggerWorkflowRequest.create({ workflows: payloads });
+                let response;
+                try {
+                    response = yield (0, retrier_1.retrier)(() => this.workflowsRpc.bulkTriggerWorkflow(request), this.logger, Object.assign(Object.assign({}, this.config.retrier), { shouldRetry: (e) => !(0, trigger_request_1.isAlreadyExists)(e) }));
+                }
+                catch (e) {
+                    const error = bulkTriggerError(e);
+                    throw batchIndex === 0 ? error : new bulk_trigger_partial_error_1.BulkTriggerPartialError(refs, batchIndex, error);
+                }
+                refs.push(...response.workflowRunIds.map((id) => new run_ref_1.WorkflowRunRef(id, this.runs, undefined, taskName)));
+            }
+            return refs;
+        });
+    }
+    /**
+     * Triggers many runs of one workflow and waits for all of their outputs, in input order.
+     *
+     * When any entry sets `opts.returnExceptions`, a failed run does not reject the whole
+     * wait: its slot holds an `Error` instead (a task error list is joined with `; `), the way
+     * a declaration's `runMany` behaves on the Node client.
+     */
+    runMany(workflow, runs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const refs = yield this.runManyNoWait(workflow, runs);
+            const results = refs.map((ref) => ref.result());
+            if (runs.some((run) => { var _a; return (_a = run.opts) === null || _a === void 0 ? void 0 : _a.returnExceptions; })) {
+                const settled = yield Promise.allSettled(results);
+                return settled.map((s) => (s.status === 'fulfilled' ? s.value : asError(s.reason)));
+            }
+            return Promise.all(results);
+        });
+    }
+    /** A reference to an existing run, to wait on, cancel or replay it. */
+    runRef(id) {
+        return this.runs.runRef(id);
+    }
+}
+exports.HatchetCore = HatchetCore;
+function workflowName(workflow) {
+    return typeof workflow === 'string' ? workflow : workflow.name;
+}
+function standaloneTaskName(workflow) {
+    return workflow instanceof declaration_1.TaskWorkflowDeclaration ? workflow._standalone_task_name : undefined;
+}
+/**
+ * The error one bulk trigger batch raises: the collision details when the engine attached
+ * them, otherwise a `HatchetError`.
+ */
+function bulkTriggerError(e) {
+    if ((0, trigger_request_1.isAlreadyExists)(e)) {
+        const collision = (0, trigger_request_1.extractBulkTriggerCollision)(e);
+        if (collision)
+            return collision;
+    }
+    return new hatchet_error_1.default(e instanceof Error ? e.message : String(e));
+}
+/**
+ * The rejection of one run as `runMany` returns it under `returnExceptions`: an `Error` as is,
+ * a task error list joined with `; `, anything else as its string; the Node declaration's
+ * normalization.
+ */
+function asError(reason) {
+    if (reason instanceof Error)
+        return reason;
+    return new Error(Array.isArray(reason) ? reason.join('; ') : String(reason));
+}
+/**
+ * Maps a declaration's `RunOpts` onto the trigger options. `sticky` only means something
+ * inside a worker task and is dropped; `returnExceptions` is read by `runMany` itself.
+ */
+function runOptsToTrigger(opts) {
+    if (!opts)
+        return undefined;
+    return {
+        additionalMetadata: opts.additionalMetadata,
+        priority: opts.priority,
+        childKey: opts.childKey,
+        desiredWorkerLabels: opts.desiredWorkerLabels,
+    };
+}
+/**
+ * The engine's base URL: `serverUrl` checked against the TLS strategy, `hostPort` with the
+ * TLS strategy, or the `grpc_broadcast_address` the token was issued with.
+ */
+function resolveServerUrl(config) {
+    if (config.serverUrl || config.hostPort) {
+        return (0, fetch_transport_1.resolveServerUrl)(config);
+    }
+    const hostPort = (0, token_1.getGrpcBroadcastAddressFromJWT)(config.token);
+    if (!hostPort) {
+        throw new hatchet_error_1.default('the token carries no grpc_broadcast_address claim; set serverUrl or hostPort on the client config');
+    }
+    return (0, fetch_transport_1.resolveServerUrl)({ hostPort, tls: config.tls });
+}
+/** Namespaces end in an underscore and are lowercase, as the Node client's config loader makes them. */
+function normalizeNamespace(namespace) {
+    if (!namespace)
+        return '';
+    return (namespace.endsWith('_') ? namespace : `${namespace}_`).toLowerCase();
+}

package/core/features/events.d.ts

@@ -0,0 +1,25 @@
+import { type RetrierConfig } from '../../util/retrier';
+import type { Logger } from '../../util/logger/logger';
+import type { Event, Events, EventsServiceClient } from '../../protoc/events/events';
+import type { EventWithMetadata, PushEventOptions } from '../types';
+export interface EventsClientDeps {
+    rpc: EventsServiceClient;
+    logger: Logger;
+    namespace?: string;
+    retrier?: RetrierConfig;
+}
+/** Pushes events that trigger event-bound workflows. */
+export declare class EventsClient {
+    private readonly deps;
+    constructor(deps: EventsClientDeps);
+    /**
+     * Pushes one event. The key is namespaced the way the Node client namespaces it.
+     * @returns the stored event
+     */
+    push<T>(type: string, input: T, options?: PushEventOptions): Promise<Event>;
+    /**
+     * Pushes many events of one type in a single call.
+     * @returns the stored events
+     */
+    bulkPush<T>(type: string, inputs: EventWithMetadata<T>[], options?: PushEventOptions): Promise<Events>;
+}

package/core/features/events.js

@@ -0,0 +1,57 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventsClient = void 0;
+const hatchet_error_1 = require("../../util/errors/hatchet-error");
+const retrier_1 = require("../../util/retrier");
+const rpc_1 = require("../../clients/event/rpc");
+/** Pushes events that trigger event-bound workflows. */
+class EventsClient {
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Pushes one event. The key is namespaced the way the Node client namespaces it.
+     * @returns the stored event
+     */
+    push(type_1, input_1) {
+        return __awaiter(this, arguments, void 0, function* (type, input, options = {}) {
+            const request = (0, rpc_1.buildPushEventRequest)(type, input, options, this.deps.namespace);
+            try {
+                const event = yield (0, retrier_1.retrier)(() => this.deps.rpc.push(request), this.deps.logger, this.deps.retrier);
+                this.deps.logger.debug(`Event pushed: ${request.key}`);
+                return event;
+            }
+            catch (e) {
+                throw (0, hatchet_error_1.toHatchetError)(e);
+            }
+        });
+    }
+    /**
+     * Pushes many events of one type in a single call.
+     * @returns the stored events
+     */
+    bulkPush(type_1, inputs_1) {
+        return __awaiter(this, arguments, void 0, function* (type, inputs, options = {}) {
+            var _a, _b;
+            const request = (0, rpc_1.buildBulkPushEventRequest)(type, inputs, options, this.deps.namespace);
+            try {
+                const events = yield (0, retrier_1.retrier)(() => this.deps.rpc.bulkPush(request), this.deps.logger, this.deps.retrier);
+                this.deps.logger.debug(`Bulk events pushed for type: ${(_b = (_a = request.events[0]) === null || _a === void 0 ? void 0 : _a.key) !== null && _b !== void 0 ? _b : type}`);
+                return events;
+            }
+            catch (e) {
+                throw (0, hatchet_error_1.toHatchetError)(e);
+            }
+        });
+    }
+}
+exports.EventsClient = EventsClient;

package/core/features/logs.d.ts

@@ -0,0 +1,26 @@
+import { LogLevel } from '../../clients/event/rpc';
+import type { EventsServiceClient, PutLogResponse } from '../../protoc/events/events';
+/** The longest log line accepted, in characters; the Node client's `putLog` holds the same limit. */
+export declare const MAX_LOG_LINE_CHARS = 1000;
+export interface PutLogOptions {
+    /** Defaults to `INFO`. */
+    level?: LogLevel;
+    /** The attempt the line belongs to, when the task has retried. */
+    retryCount?: number;
+    metadata?: Record<string, unknown>;
+}
+/** Writes log lines against a task run, the way `ctx.log` does from a worker. */
+export declare class LogsClient {
+    private readonly rpc;
+    constructor(rpc: EventsServiceClient);
+    /**
+     * Stores one log line for a task run. Unlike the Node client's fire-and-forget `putLog`,
+     * this resolves once the engine has the line and rejects when it does not, since a
+     * serverless runtime may end the invocation as soon as the handler returns.
+     *
+     * A line over `MAX_LOG_LINE_CHARS` (1,000) characters rejects with a `HatchetError` that
+     * states the length, where the Node client warns and drops the line; the message itself is
+     * never part of the error.
+     */
+    put(taskRunExternalId: string, message: string, options?: PutLogOptions): Promise<PutLogResponse>;
+}

package/core/features/logs.js

@@ -0,0 +1,51 @@
+"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 __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogsClient = exports.MAX_LOG_LINE_CHARS = void 0;
+const rpc_1 = require("../../clients/event/rpc");
+const hatchet_error_1 = __importDefault(require("../../util/errors/hatchet-error"));
+/** The longest log line accepted, in characters; the Node client's `putLog` holds the same limit. */
+exports.MAX_LOG_LINE_CHARS = 1000;
+/** Writes log lines against a task run, the way `ctx.log` does from a worker. */
+class LogsClient {
+    constructor(rpc) {
+        this.rpc = rpc;
+    }
+    /**
+     * Stores one log line for a task run. Unlike the Node client's fire-and-forget `putLog`,
+     * this resolves once the engine has the line and rejects when it does not, since a
+     * serverless runtime may end the invocation as soon as the handler returns.
+     *
+     * A line over `MAX_LOG_LINE_CHARS` (1,000) characters rejects with a `HatchetError` that
+     * states the length, where the Node client warns and drops the line; the message itself is
+     * never part of the error.
+     */
+    put(taskRunExternalId_1, message_1) {
+        return __awaiter(this, arguments, void 0, function* (taskRunExternalId, message, options = {}) {
+            var _a;
+            if (message.length > exports.MAX_LOG_LINE_CHARS) {
+                throw new hatchet_error_1.default(`log line is ${message.length} characters, over the ${exports.MAX_LOG_LINE_CHARS}-character limit`);
+            }
+            return this.rpc.putLog({
+                taskRunExternalId,
+                createdAt: new Date(),
+                message,
+                level: (_a = options.level) !== null && _a !== void 0 ? _a : rpc_1.LogLevel.INFO,
+                taskRetryCount: options.retryCount,
+                metadata: options.metadata ? JSON.stringify(options.metadata) : undefined,
+            });
+        });
+    }
+}
+exports.LogsClient = LogsClient;

package/core/features/rate-limits.d.ts

@@ -0,0 +1,19 @@
+import { type RetrierConfig } from '../../util/retrier';
+import type { Logger } from '../../util/logger/logger';
+import type { WorkflowServiceClient } from '../../protoc/workflows/workflows';
+import type { CreateRateLimitOpts } from '../types';
+export interface RateLimitsClientDeps {
+    rpc: WorkflowServiceClient;
+    logger: Logger;
+    retrier?: RetrierConfig;
+}
+/** Tenant-wide rate limits that tasks declare against by key. */
+export declare class RateLimitsClient {
+    private readonly deps;
+    constructor(deps: RateLimitsClientDeps);
+    /**
+     * Creates or updates a rate limit.
+     * @returns the rate limit's key
+     */
+    put(opts: CreateRateLimitOpts): Promise<string>;
+}