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

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

@@ -0,0 +1,143 @@
+"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.createTsProtoClient = createTsProtoClient;
+exports.toConnectCallOptions = toConnectCallOptions;
+exports.metadataToHeaders = metadataToHeaders;
+exports.headersToMetadata = headersToMetadata;
+const connect_1 = require("@connectrpc/connect");
+const abort_controller_x_1 = require("abort-controller-x");
+const nice_grpc_common_1 = require("nice-grpc-common");
+const message_bridge_1 = require("./message-bridge");
+/**
+ * Builds the client a `ts-proto` service definition describes, with every method served by a
+ * Connect client for the matching protobuf-es service on `transport`. The result has the exact
+ * surface `nice-grpc`'s `ClientFactory.create(definition, channel)` produced: every RPC of the
+ * service as `(request, options?) => Promise<response>` with the SDK's `ts-proto` message types,
+ * so a caller holding one of the public client properties sees no difference.
+ *
+ * Both bindings are generated from the same proto, so a method's client name is the same in
+ * each and the protobuf-es descriptor can be looked up by it.
+ */
+function createTsProtoClient(definition, service, transport) {
+    const connectClient = (0, connect_1.createClient)(service, transport);
+    const client = {};
+    for (const [key, method] of Object.entries(definition.methods)) {
+        const desc = service.method[key];
+        if (!desc) {
+            throw new Error(`${definition.fullName}.${method.name} has no protobuf-es descriptor; regenerate src/protoc-es`);
+        }
+        if (method.requestStream || method.responseStream) {
+            client[key] = () => {
+                throw new Error(`${definition.fullName}.${method.name} is a streaming RPC, which the unary transport does not serve`);
+            };
+            continue;
+        }
+        const requestCodec = method.requestType;
+        const responseCodec = method.responseType;
+        client[key] = (request, options) => unaryCall(() => connectClient[key]((0, message_bridge_1.toProtobufEs)(desc.input, requestCodec, request), toConnectCallOptions(options)), responseCodec, desc.output, options);
+    }
+    return client;
+}
+/**
+ * Runs one unary call with `nice-grpc`'s cancellation and deadline semantics: a signal that
+ * is already aborted rejects before anything is sent, an abort during the call rejects with the
+ * signal's reason (an `AbortError`) rather than the transport's cancellation error, and a
+ * deadline that has already passed rejects with `DEADLINE_EXCEEDED` without sending.
+ */
+function unaryCall(send, responseCodec, responseSchema, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const signal = options === null || options === void 0 ? void 0 : options.signal;
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            throw abortReason(signal);
+        }
+        if ((options === null || options === void 0 ? void 0 : options.deadline) !== undefined && remainingMs(options.deadline) <= 0) {
+            throw new connect_1.ConnectError('the operation timed out', connect_1.Code.DeadlineExceeded);
+        }
+        let response;
+        try {
+            response = yield send();
+        }
+        catch (e) {
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+                throw abortReason(signal);
+            }
+            throw e;
+        }
+        return (0, message_bridge_1.fromProtobufEs)(responseCodec, responseSchema, response);
+    });
+}
+function abortReason(signal) {
+    var _a;
+    return (_a = signal.reason) !== null && _a !== void 0 ? _a : new abort_controller_x_1.AbortError();
+}
+function remainingMs(deadline) {
+    const at = deadline instanceof Date ? deadline.getTime() : deadline;
+    return at - Date.now();
+}
+/**
+ * Translates `nice-grpc` call options to Connect's: the signal passes through, an absolute
+ * deadline becomes the remaining time, request metadata becomes headers and the header and
+ * trailer callbacks receive `Metadata` built from the response headers.
+ */
+function toConnectCallOptions(options) {
+    if (!options) {
+        return undefined;
+    }
+    const { signal, deadline, metadata, onHeader, onTrailer } = options;
+    const connect = {};
+    if (signal) {
+        connect.signal = signal;
+    }
+    if (deadline !== undefined) {
+        connect.timeoutMs = Math.max(1, remainingMs(deadline));
+    }
+    if (metadata) {
+        connect.headers = metadataToHeaders(metadata);
+    }
+    if (onHeader) {
+        connect.onHeader = (headers) => onHeader(headersToMetadata(headers));
+    }
+    if (onTrailer) {
+        connect.onTrailer = (headers) => onTrailer(headersToMetadata(headers));
+    }
+    return connect;
+}
+/**
+ * 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.
+ */
+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'));
+        }
+    }
+    return headers;
+}
+/**
+ * Response headers as gRPC metadata, the inverse of `metadataToHeaders`. `Headers` joins
+ * repeated values with a comma, so a binary header is split back into its values before each
+ * is decoded.
+ */
+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'))));
+        }
+        else {
+            metadata.set(key, value);
+        }
+    });
+    return metadata;
+}

package/core/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The core entry point: the application client for runtimes without gRPC, built on the
+ * Connect transport seam. The entry resolves today so that `@hatchet-dev/typescript-sdk/core`
+ * is a stable import path; the client it exports is added on top.
+ *
+ * @module Core
+ */
+/** Bumped whenever the surface exported from this entry changes incompatibly. */
+export declare const CORE_ENTRY_VERSION = 0;

package/core/index.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * The core entry point: the application client for runtimes without gRPC, built on the
+ * Connect transport seam. The entry resolves today so that `@hatchet-dev/typescript-sdk/core`
+ * is a stable import path; the client it exports is added on top.
+ *
+ * @module Core
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CORE_ENTRY_VERSION = void 0;
+/** Bumped whenever the surface exported from this entry changes incompatibly. */
+exports.CORE_ENTRY_VERSION = 0;

package/dist/check-exports.mjs

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// Verifies the package's `exports` map against the built `dist/`: every documented import
+// path resolves from both a native ESM module and a CommonJS module, every directory that
+// ships an `index.js` has an explicit entry (a wildcard cannot map a bare directory to its
+// index), every entry's target exists, and a TypeScript consumer compiles against the
+// declarations, including an explicit `.d.ts` import path.
+//
+// The published package root is `dist/` (`publish:ci` copies package.json there and publishes
+// from it), so the map is checked from a scratch package whose node_modules links to `dist/`.
+// Run after `pnpm run tsc:build` (the `check:exports` script does both).
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const PACKAGE = '@hatchet-dev/typescript-sdk';
+
+// Import paths users and the serverless package rely on, with and without the `.js` suffix.
+const DOCUMENTED_SUBPATHS = [
+  '.',
+  './v1',
+  './edge',
+  './edge/index.js',
+  './core',
+  './clients/hatchet-client',
+  './v1/client/client.js',
+  './protoc/dispatcher/dispatcher',
+];
+
+// Type-only imports a consumer's TypeScript may use: the explicit declaration-file path a
+// `types` condition cannot produce on its own (`./*` would append `.d.ts` twice), next to the
+// bare, `.js`-suffixed and directory-entry forms.
+const TYPE_CONSUMER = [
+  "import type { ClientConfig } from '@hatchet-dev/typescript-sdk/clients/hatchet-client/client-config.d.ts';",
+  "import type { HatchetClient } from '@hatchet-dev/typescript-sdk/v1';",
+  "import type { AdminClient } from '@hatchet-dev/typescript-sdk/v1/client/admin';",
+  "import type { EventClient } from '@hatchet-dev/typescript-sdk/clients/event/event-client.js';",
+  'export type Consumer = [ClientConfig, HatchetClient, AdminClient, EventClient];',
+  '',
+].join('\n');
+const TYPE_RESOLUTIONS = ['node16', 'bundler'];
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const dist = join(root, 'dist');
+const tsc = join(root, 'node_modules', 'typescript', 'bin', 'tsc');
+
+if (!existsSync(join(dist, 'index.js'))) {
+  console.error(`dist is not built: ${dist}/index.js is missing. Run \`pnpm run tsc:build\` first.`);
+  process.exit(1);
+}
+
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const exportsMap = pkg.exports ?? {};
+const explicitSubpaths = Object.keys(exportsMap).filter((k) => !k.includes('*'));
+const failures = [];
+
+function indexDirectories(dir, prefix = '.') {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const sub = `${prefix}/${entry.name}`;
+    if (existsSync(join(dir, entry.name, 'index.js'))) out.push(sub);
+    out.push(...indexDirectories(join(dir, entry.name), sub));
+  }
+  return out;
+}
+
+for (const sub of indexDirectories(dist)) {
+  if (!(sub in exportsMap)) {
+    failures.push(`${sub} ships an index.js but has no explicit "exports" entry`);
+  }
+}
+
+for (const sub of explicitSubpaths) {
+  const target = exportsMap[sub];
+  const files = typeof target === 'string' ? [target] : Object.values(target);
+  for (const file of files) {
+    if (file !== './package.json' && !existsSync(join(dist, file))) {
+      failures.push(`"${sub}" target ${file} does not exist in dist`);
+    }
+  }
+}
+
+const scratch = mkdtempSync(join(tmpdir(), 'hatchet-check-exports-'));
+try {
+  // The published layout: package.json next to the build output, reached through node_modules.
+  cpSync(join(root, 'package.json'), join(dist, 'package.json'));
+  mkdirSync(join(scratch, 'node_modules', '@hatchet-dev'), { recursive: true });
+  symlinkSync(dist, join(scratch, 'node_modules', '@hatchet-dev', 'typescript-sdk'), 'dir');
+
+  const esmDir = join(scratch, 'esm');
+  const cjsDir = join(scratch, 'cjs');
+  mkdirSync(esmDir);
+  mkdirSync(cjsDir);
+  writeFileSync(join(esmDir, 'package.json'), '{ "type": "module" }\n');
+  writeFileSync(join(cjsDir, 'package.json'), '{ "type": "commonjs" }\n');
+  const cjsRequire = createRequire(join(cjsDir, 'probe.js'));
+
+  const subpaths = [...new Set([...DOCUMENTED_SUBPATHS, ...explicitSubpaths])];
+  for (const [i, sub] of subpaths.entries()) {
+    const specifier = sub === '.' ? PACKAGE : `${PACKAGE}/${sub.slice(2)}`;
+
+    const probe = join(esmDir, `probe-${i}.mjs`);
+    const attributes = sub === './package.json' ? ' with { type: "json" }' : '';
+    writeFileSync(probe, `import ${JSON.stringify(specifier)}${attributes};\n`);
+    try {
+      await import(pathToFileURL(probe).href);
+    } catch (e) {
+      failures.push(`ESM import of ${specifier} failed: ${e.message}`);
+    }
+
+    try {
+      cjsRequire(specifier);
+    } catch (e) {
+      failures.push(`CJS require of ${specifier} failed: ${e.message}`);
+    }
+  }
+
+  const typesDir = join(scratch, 'types');
+  mkdirSync(typesDir);
+  writeFileSync(join(typesDir, 'consumer.ts'), TYPE_CONSUMER);
+  for (const moduleResolution of TYPE_RESOLUTIONS) {
+    const tsconfig = join(typesDir, `tsconfig.${moduleResolution}.json`);
+    writeFileSync(
+      tsconfig,
+      JSON.stringify({
+        compilerOptions: {
+          target: 'ES2022',
+          module: moduleResolution === 'bundler' ? 'ESNext' : moduleResolution,
+          moduleResolution,
+          strict: true,
+          noEmit: true,
+          skipLibCheck: true,
+          types: [],
+        },
+        files: ['consumer.ts'],
+      })
+    );
+    const result = spawnSync(process.execPath, [tsc, '-p', tsconfig], { encoding: 'utf8' });
+    if (result.status !== 0) {
+      failures.push(
+        `type consumer (moduleResolution ${moduleResolution}) failed:\n${result.stdout}${result.stderr}`
+      );
+    }
+  }
+} finally {
+  rmSync(scratch, { recursive: true, force: true });
+}
+
+if (failures.length) {
+  console.error('exports map check failed:');
+  for (const f of failures) console.error(`  ${f}`);
+  process.exit(1);
+}
+
+console.log(
+  `exports map resolves ${DOCUMENTED_SUBPATHS.length} documented and ${explicitSubpaths.length} explicit subpaths from ESM and CJS, and a type consumer compiles under ${TYPE_RESOLUTIONS.join(' and ')}`
+);

package/legacy/legacy-client.d.ts

@@ -9,9 +9,13 @@ import { ClientConfig } from '../clients/hatchet-client/client-config';
 import { RunListenerClient } from '../clients/listeners/run-listener/child-listener-client';
 import { Api } from '../clients/rest/generated/Api';
 import { DurableListenerClient } from '../clients/listeners/durable-listener/durable-listener-client';
+import { type Transport } from '../clients/transport';
 export interface HatchetClientOptions {
     config_path?: string;
+    /** Credentials for the streaming gRPC channel. Unary calls derive their TLS settings from `tls_config`. */
     credentials?: ChannelCredentials;
+    /** The transport unary calls go over; defaults to the Node gRPC transport built from the config. */
+    transport?: Transport;
 }
 export declare class LegacyHatchetClient {
     config: ClientConfig;

package/legacy/legacy-client.js

@@ -16,11 +16,12 @@ const client_config_1 = require("../clients/hatchet-client/client-config");
 const child_listener_client_1 = require("../clients/listeners/run-listener/child-listener-client");
 const rest_1 = __importDefault(require("../clients/rest"));
 const durable_listener_client_1 = require("../clients/listeners/durable-listener/durable-listener-client");
+const transport_1 = require("../clients/transport");
 class LegacyHatchetClient {
     constructor(config, options, axiosOpts, runs, listener, event, dispatcher, logger, durableListener) {
         // Initializes a new Client instance.
         // Loads config in the following order: config param > yaml file > env vars
-        var _a;
+        var _a, _b;
         this.runs = runs;
         const loaded = config_loader_1.ConfigLoader.loadClientConfig(config, {
             path: options === null || options === void 0 ? void 0 : options.config_path,
@@ -42,18 +43,19 @@ class LegacyHatchetClient {
         this.credentials =
             (_a = options === null || options === void 0 ? void 0 : options.credentials) !== null && _a !== void 0 ? _a : config_loader_1.ConfigLoader.createCredentials(this.config.tls_config);
         const clientFactory = (0, nice_grpc_1.createClientFactory)().use((0, grpc_helpers_1.addTokenMiddleware)(this.config.token));
+        const transport = (_b = options === null || options === void 0 ? void 0 : options.transport) !== null && _b !== void 0 ? _b : (0, transport_1.createNodeTransport)(this.config);
         this.tenantId = this.config.tenant_id;
         this.api = (0, rest_1.default)(this.config.api_url, this.config.token, axiosOpts);
         this.event =
             event ||
-                new event_client_1.EventClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory, this.api);
+                new event_client_1.EventClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory, this.api, transport);
         this.dispatcher =
             dispatcher ||
                 new dispatcher_client_1.DispatcherClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory);
         this.listener =
             listener ||
                 new child_listener_client_1.RunListenerClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory, this.api);
-        this.admin = new admin_client_1.AdminClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory, this.api, this.tenantId, this.listener, this.runs);
+        this.admin = new admin_client_1.AdminClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory, this.api, this.tenantId, this.listener, this.runs, transport);
         this.durableListener =
             durableListener ||
                 new durable_listener_client_1.DurableListenerClient(this.config, (0, grpc_helpers_1.channelFactory)(this.config, this.credentials), clientFactory);

package/package.json

@@ -1,11 +1,99 @@
 {
   "name": "@hatchet-dev/typescript-sdk",
-  "version": "1.33.2",
+  "version": "1.34.0-alpha.1",
   "engines": {
     "node": ">=20"
   },
   "description": "Background task orchestration & visibility for developers",
   "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./v1": {
+      "types": "./v1/index.d.ts",
+      "default": "./v1/index.js"
+    },
+    "./edge": {
+      "types": "./edge/index.d.ts",
+      "default": "./edge/index.js"
+    },
+    "./core": {
+      "types": "./core/index.d.ts",
+      "default": "./core/index.js"
+    },
+    "./clients/admin": {
+      "types": "./clients/admin/index.d.ts",
+      "default": "./clients/admin/index.js"
+    },
+    "./clients/hatchet-client": {
+      "types": "./clients/hatchet-client/index.d.ts",
+      "default": "./clients/hatchet-client/index.js"
+    },
+    "./clients/rest": {
+      "types": "./clients/rest/index.d.ts",
+      "default": "./clients/rest/index.js"
+    },
+    "./clients/transport": {
+      "types": "./clients/transport/index.d.ts",
+      "default": "./clients/transport/index.js"
+    },
+    "./opentelemetry": {
+      "types": "./opentelemetry/index.d.ts",
+      "default": "./opentelemetry/index.js"
+    },
+    "./protoc/dispatcher": {
+      "types": "./protoc/dispatcher/index.d.ts",
+      "default": "./protoc/dispatcher/index.js"
+    },
+    "./protoc/events": {
+      "types": "./protoc/events/index.d.ts",
+      "default": "./protoc/events/index.js"
+    },
+    "./protoc/workflows": {
+      "types": "./protoc/workflows/index.d.ts",
+      "default": "./protoc/workflows/index.js"
+    },
+    "./util/config-loader": {
+      "types": "./util/config-loader/index.d.ts",
+      "default": "./util/config-loader/index.js"
+    },
+    "./util/logger": {
+      "types": "./util/logger/index.d.ts",
+      "default": "./util/logger/index.js"
+    },
+    "./v1/client/features": {
+      "types": "./v1/client/features/index.d.ts",
+      "default": "./v1/client/features/index.js"
+    },
+    "./v1/client/worker/deprecated": {
+      "types": "./v1/client/worker/deprecated/index.d.ts",
+      "default": "./v1/client/worker/deprecated/index.js"
+    },
+    "./v1/client/worker/eviction": {
+      "types": "./v1/client/worker/eviction/index.d.ts",
+      "default": "./v1/client/worker/eviction/index.js"
+    },
+    "./v1/conditions": {
+      "types": "./v1/conditions/index.d.ts",
+      "default": "./v1/conditions/index.js"
+    },
+    "./package.json": "./package.json",
+    "./*.d.ts": "./*.d.ts",
+    "./*.js": {
+      "types": "./*.d.ts",
+      "default": "./*.js"
+    },
+    "./*/index": {
+      "types": "./*/index.d.ts",
+      "default": "./*/index.js"
+    },
+    "./*": {
+      "types": "./*.d.ts",
+      "default": "./*.js"
+    }
+  },
   "files": [
     "*",
     "!**/*.test.js",
@@ -38,6 +126,7 @@
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.148",
     "@aws-sdk/client-s3": "^3.1042.0",
+    "@bufbuild/protoc-gen-es": "^2.15.0",
     "@eslint/js": "^10.0.1",
     "@grpc/grpc-js": "^1.14.3",
     "@modelcontextprotocol/sdk": "^1.29.0",
@@ -77,7 +166,9 @@
     "typescript-eslint": "^8.56.1"
   },
   "dependencies": {
-    "@bufbuild/protobuf": "^2.11.0",
+    "@bufbuild/protobuf": "^2.15.0",
+    "@connectrpc/connect": "~2.1.2",
+    "@connectrpc/connect-node": "~2.1.2",
     "@types/qs": "^6.15.0",
     "abort-controller-x": "^0.5.0",
     "axios": "^1.15.2",
@@ -145,11 +236,13 @@
     "tsc:build": "pnpm run dump-version && tsc && resolve-tspaths",
     "test:unit": "jest --testMatch='**/*.test.ts'",
     "check:edge": "pnpm run tsc:build && node scripts/check-edge-entry.mjs",
+    "check:exports": "pnpm run tsc:build && node scripts/check-exports.mjs",
     "test:e2e": "jest --config jest.e2e.config.ts --silent --forceExit --runInBand",
     "test:unit:watch": "jest --testMatch='**/*.test.ts' --watch",
     "generate": "pnpm run '/generate-.*/'",
     "generate-api": "npx swagger-typescript-api@13.2.7 generate -p ../../bin/oas/openapi.yaml -o ./src/clients/rest/generated -n hatchet.ts --modular --axios",
     "generate-protoc": "./generate-protoc.sh",
+    "generate-protoc-es": "./generate-protoc-es.sh",
     "lint:check": "pnpm run eslint:check && pnpm run prettier:check",
     "lint:fix": "pnpm run eslint:fix && pnpm run prettier:fix",
     "eslint:check": "eslint \"{src,tests}/**/*.{ts,tsx,js}\"",