@restatedev/restate-sdk-integration-client 0.0.0-stage → 1.18.0

package/dist/client.cjs

@@ -0,0 +1,101 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_package = require('./package.cjs');
+const require_ingestion_svc_pb = require('./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.cjs');
+const require_producer = require('./producer.cjs');
+let __connectrpc_connect = require("@connectrpc/connect");
+__connectrpc_connect = require_rolldown_runtime.__toESM(__connectrpc_connect);
+let __connectrpc_connect_node = require("@connectrpc/connect-node");
+__connectrpc_connect_node = require_rolldown_runtime.__toESM(__connectrpc_connect_node);
+
+//#region src/client.ts
+const MAX_INTEGRATION_BYTES = 64;
+const MAX_PRODUCER_ID_BYTES = 256;
+const DEFAULT_INTEGRATION = `restate-integration-client-ts/${require_package.version}`;
+const encoder = new TextEncoder();
+/**
+* Creates a client for the Restate ingestion API, the API to turn any source of events into
+* Restate invocations.
+*
+* ```ts
+* const client = connect({ url: "http://localhost:8080" });
+* const producer = client.producer({
+*   defaults: { service: "Orders", handler: "ingest" },
+* });
+* for (const order of orders) {
+*   await producer.send({ key: order.id, body: JSON.stringify(order) });
+* }
+* await producer.close();
+* await client.close();
+* ```
+*
+* @experimental
+*/
+function connect(opts) {
+	let transport = opts.transport;
+	let sessionManager;
+	if (transport === void 0) {
+		const url = parseIngressUrl(opts.url);
+		sessionManager = new __connectrpc_connect_node.Http2SessionManager(url);
+		transport = (0, __connectrpc_connect_node.createGrpcTransport)({
+			baseUrl: url.href,
+			sessionManager
+		});
+	}
+	const authToken = opts.authToken?.trim();
+	return new IntegrationClientImpl((0, __connectrpc_connect.createClient)(require_ingestion_svc_pb.IngestionSvc, transport), authToken ? { authorization: `Bearer ${authToken}` } : void 0, truncateUtf8(opts.integration !== void 0 ? `${opts.integration.name}/${opts.integration.version}` : DEFAULT_INTEGRATION, MAX_INTEGRATION_BYTES), sessionManager);
+}
+var IntegrationClientImpl = class {
+	#rpc;
+	#headers;
+	#integration;
+	#sessionManager;
+	#closed = false;
+	constructor(rpc, headers, integration, sessionManager) {
+		this.#rpc = rpc;
+		this.#headers = headers;
+		this.#integration = integration;
+		this.#sessionManager = sessionManager;
+	}
+	producer(opts = {}) {
+		return this.#newProducer("", false, opts);
+	}
+	exactlyOnceProducer(producerId, opts = {}) {
+		if (typeof producerId !== "string" || producerId.trim() === "") throw new TypeError("producerId must be a non-empty string");
+		if (encoder.encode(producerId).byteLength > MAX_PRODUCER_ID_BYTES) throw new RangeError(`producerId must be at most ${MAX_PRODUCER_ID_BYTES} bytes`);
+		return this.#newProducer(producerId, true, opts);
+	}
+	close() {
+		this.#closed = true;
+		this.#sessionManager?.abort();
+		return Promise.resolve();
+	}
+	#newProducer(producerId, exactlyOnce, options) {
+		if (this.#closed) throw new Error("The integration client is closed");
+		return new require_producer.ProducerImpl({
+			rpc: this.#rpc,
+			headers: this.#headers,
+			integration: this.#integration,
+			producerId,
+			exactlyOnce,
+			options
+		});
+	}
+};
+function parseIngressUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch (e) {
+		throw new TypeError(`The ingress url is not a valid URL: '${raw}'`, { cause: e });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new TypeError(`The ingress url must use the http or https scheme, got '${raw}'`);
+	return url;
+}
+/** Truncates to at most `maxBytes` of UTF-8, without splitting a character. */
+function truncateUtf8(value, maxBytes) {
+	const { read } = encoder.encodeInto(value, new Uint8Array(maxBytes));
+	return value.slice(0, read);
+}
+
+//#endregion
+exports.connect = connect;

package/dist/client.d.cts

@@ -0,0 +1,26 @@
+import { IntegrationClient, IntegrationClientOptions } from "./api.cjs";
+
+//#region src/client.d.ts
+
+/**
+ * Creates a client for the Restate ingestion API, the API to turn any source of events into
+ * Restate invocations.
+ *
+ * ```ts
+ * const client = connect({ url: "http://localhost:8080" });
+ * const producer = client.producer({
+ *   defaults: { service: "Orders", handler: "ingest" },
+ * });
+ * for (const order of orders) {
+ *   await producer.send({ key: order.id, body: JSON.stringify(order) });
+ * }
+ * await producer.close();
+ * await client.close();
+ * ```
+ *
+ * @experimental
+ */
+declare function connect(opts: IntegrationClientOptions): IntegrationClient;
+//#endregion
+export { connect };
+//# sourceMappingURL=client.d.cts.map

package/dist/client.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.cts","names":[],"sources":["../src/client.ts"],"sourcesContent":[],"mappings":";;;;;;AAuDA;;;;;;;;;;;;;;;;iBAAgB,OAAA,OAAc,2BAA2B"}

package/dist/client.d.ts

@@ -0,0 +1,26 @@
+import { IntegrationClient, IntegrationClientOptions } from "./api.js";
+
+//#region src/client.d.ts
+
+/**
+ * Creates a client for the Restate ingestion API, the API to turn any source of events into
+ * Restate invocations.
+ *
+ * ```ts
+ * const client = connect({ url: "http://localhost:8080" });
+ * const producer = client.producer({
+ *   defaults: { service: "Orders", handler: "ingest" },
+ * });
+ * for (const order of orders) {
+ *   await producer.send({ key: order.id, body: JSON.stringify(order) });
+ * }
+ * await producer.close();
+ * await client.close();
+ * ```
+ *
+ * @experimental
+ */
+declare function connect(opts: IntegrationClientOptions): IntegrationClient;
+//#endregion
+export { connect };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"sourcesContent":[],"mappings":";;;;;;AAuDA;;;;;;;;;;;;;;;;iBAAgB,OAAA,OAAc,2BAA2B"}

package/dist/client.js

@@ -0,0 +1,99 @@
+import { version } from "./package.js";
+import { IngestionSvc } from "./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.js";
+import { ProducerImpl } from "./producer.js";
+import { createClient } from "@connectrpc/connect";
+import { Http2SessionManager, createGrpcTransport } from "@connectrpc/connect-node";
+
+//#region src/client.ts
+const MAX_INTEGRATION_BYTES = 64;
+const MAX_PRODUCER_ID_BYTES = 256;
+const DEFAULT_INTEGRATION = `restate-integration-client-ts/${version}`;
+const encoder = new TextEncoder();
+/**
+* Creates a client for the Restate ingestion API, the API to turn any source of events into
+* Restate invocations.
+*
+* ```ts
+* const client = connect({ url: "http://localhost:8080" });
+* const producer = client.producer({
+*   defaults: { service: "Orders", handler: "ingest" },
+* });
+* for (const order of orders) {
+*   await producer.send({ key: order.id, body: JSON.stringify(order) });
+* }
+* await producer.close();
+* await client.close();
+* ```
+*
+* @experimental
+*/
+function connect(opts) {
+	let transport = opts.transport;
+	let sessionManager;
+	if (transport === void 0) {
+		const url = parseIngressUrl(opts.url);
+		sessionManager = new Http2SessionManager(url);
+		transport = createGrpcTransport({
+			baseUrl: url.href,
+			sessionManager
+		});
+	}
+	const authToken = opts.authToken?.trim();
+	return new IntegrationClientImpl(createClient(IngestionSvc, transport), authToken ? { authorization: `Bearer ${authToken}` } : void 0, truncateUtf8(opts.integration !== void 0 ? `${opts.integration.name}/${opts.integration.version}` : DEFAULT_INTEGRATION, MAX_INTEGRATION_BYTES), sessionManager);
+}
+var IntegrationClientImpl = class {
+	#rpc;
+	#headers;
+	#integration;
+	#sessionManager;
+	#closed = false;
+	constructor(rpc, headers, integration, sessionManager) {
+		this.#rpc = rpc;
+		this.#headers = headers;
+		this.#integration = integration;
+		this.#sessionManager = sessionManager;
+	}
+	producer(opts = {}) {
+		return this.#newProducer("", false, opts);
+	}
+	exactlyOnceProducer(producerId, opts = {}) {
+		if (typeof producerId !== "string" || producerId.trim() === "") throw new TypeError("producerId must be a non-empty string");
+		if (encoder.encode(producerId).byteLength > MAX_PRODUCER_ID_BYTES) throw new RangeError(`producerId must be at most ${MAX_PRODUCER_ID_BYTES} bytes`);
+		return this.#newProducer(producerId, true, opts);
+	}
+	close() {
+		this.#closed = true;
+		this.#sessionManager?.abort();
+		return Promise.resolve();
+	}
+	#newProducer(producerId, exactlyOnce, options) {
+		if (this.#closed) throw new Error("The integration client is closed");
+		return new ProducerImpl({
+			rpc: this.#rpc,
+			headers: this.#headers,
+			integration: this.#integration,
+			producerId,
+			exactlyOnce,
+			options
+		});
+	}
+};
+function parseIngressUrl(raw) {
+	let url;
+	try {
+		url = new URL(raw);
+	} catch (e) {
+		throw new TypeError(`The ingress url is not a valid URL: '${raw}'`, { cause: e });
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new TypeError(`The ingress url must use the http or https scheme, got '${raw}'`);
+	return url;
+}
+/** Truncates to at most `maxBytes` of UTF-8, without splitting a character. */
+function truncateUtf8(value, maxBytes) {
+	const { read } = encoder.encodeInto(value, new Uint8Array(maxBytes));
+	return value.slice(0, read);
+}
+
+//#endregion
+export { connect };
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":["pkg.version","sessionManager: Http2SessionManager | undefined","#rpc","#headers","#integration","#sessionManager","#newProducer","#closed","url: URL"],"sources":["../src/client.ts"],"sourcesContent":["/*\n * Copyright (c) 2023-2026 - Restate Software, Inc., Restate GmbH\n *\n * This file is part of the Restate SDK for Node.js/TypeScript,\n * which is released under the MIT license.\n *\n * You can find a copy of the license in file LICENSE in the root\n * directory of this repository or package, or at\n * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE\n */\n\nimport { type Client, createClient } from \"@connectrpc/connect\";\nimport {\n  createGrpcTransport,\n  Http2SessionManager,\n} from \"@connectrpc/connect-node\";\nimport pkg from \"../package.json\" with { type: \"json\" };\nimport type {\n  ExactlyOnceInvocation,\n  ExactlyOnceProducer,\n  IntegrationClient,\n  IntegrationClientOptions,\n  Invocation,\n  Producer,\n  ProducerOptions,\n} from \"./api.js\";\nimport { IngestionSvc } from \"./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.js\";\nimport { ProducerImpl } from \"./producer.js\";\n\n// Limits enforced by Restate on the Start frame.\nconst MAX_INTEGRATION_BYTES = 64;\nconst MAX_PRODUCER_ID_BYTES = 256;\n\nconst DEFAULT_INTEGRATION = `restate-integration-client-ts/${pkg.version}`;\n\nconst encoder = new TextEncoder();\n\n/**\n * Creates a client for the Restate ingestion API, the API to turn any source of events into\n * Restate invocations.\n *\n * ```ts\n * const client = connect({ url: \"http://localhost:8080\" });\n * const producer = client.producer({\n *   defaults: { service: \"Orders\", handler: \"ingest\" },\n * });\n * for (const order of orders) {\n *   await producer.send({ key: order.id, body: JSON.stringify(order) });\n * }\n * await producer.close();\n * await client.close();\n * ```\n *\n * @experimental\n */\nexport function connect(opts: IntegrationClientOptions): IntegrationClient {\n  let transport = opts.transport;\n  let sessionManager: Http2SessionManager | undefined;\n  if (transport === undefined) {\n    const url = parseIngressUrl(opts.url);\n    sessionManager = new Http2SessionManager(url);\n    transport = createGrpcTransport({ baseUrl: url.href, sessionManager });\n  }\n  const authToken = opts.authToken?.trim();\n  return new IntegrationClientImpl(\n    createClient(IngestionSvc, transport),\n    authToken ? { authorization: `Bearer ${authToken}` } : undefined,\n    truncateUtf8(\n      opts.integration !== undefined\n        ? `${opts.integration.name}/${opts.integration.version}`\n        : DEFAULT_INTEGRATION,\n      MAX_INTEGRATION_BYTES\n    ),\n    sessionManager\n  );\n}\n\nclass IntegrationClientImpl implements IntegrationClient {\n  readonly #rpc: Client<typeof IngestionSvc>;\n  readonly #headers: Record<string, string> | undefined;\n  readonly #integration: string;\n  readonly #sessionManager: Http2SessionManager | undefined;\n  #closed = false;\n\n  constructor(\n    rpc: Client<typeof IngestionSvc>,\n    headers: Record<string, string> | undefined,\n    integration: string,\n    sessionManager: Http2SessionManager | undefined\n  ) {\n    this.#rpc = rpc;\n    this.#headers = headers;\n    this.#integration = integration;\n    this.#sessionManager = sessionManager;\n  }\n\n  producer(opts: ProducerOptions = {}): Producer {\n    return this.#newProducer<Invocation>(\"\", false, opts);\n  }\n\n  exactlyOnceProducer(\n    producerId: string,\n    opts: ProducerOptions = {}\n  ): ExactlyOnceProducer {\n    if (typeof producerId !== \"string\" || producerId.trim() === \"\") {\n      throw new TypeError(\"producerId must be a non-empty string\");\n    }\n    if (encoder.encode(producerId).byteLength > MAX_PRODUCER_ID_BYTES) {\n      throw new RangeError(\n        `producerId must be at most ${MAX_PRODUCER_ID_BYTES} bytes`\n      );\n    }\n    return this.#newProducer<ExactlyOnceInvocation>(producerId, true, opts);\n  }\n\n  close(): Promise<void> {\n    this.#closed = true;\n    this.#sessionManager?.abort();\n    return Promise.resolve();\n  }\n\n  #newProducer<R extends Invocation>(\n    producerId: string,\n    exactlyOnce: boolean,\n    options: ProducerOptions\n  ): ProducerImpl<R> {\n    if (this.#closed) {\n      throw new Error(\"The integration client is closed\");\n    }\n    return new ProducerImpl<R>({\n      rpc: this.#rpc,\n      headers: this.#headers,\n      integration: this.#integration,\n      producerId,\n      exactlyOnce,\n      options,\n    });\n  }\n}\n\nfunction parseIngressUrl(raw: string): URL {\n  let url: URL;\n  try {\n    url = new URL(raw);\n  } catch (e) {\n    throw new TypeError(`The ingress url is not a valid URL: '${raw}'`, {\n      cause: e,\n    });\n  }\n  if (url.protocol !== \"http:\" && url.protocol !== \"https:\") {\n    throw new TypeError(\n      `The ingress url must use the http or https scheme, got '${raw}'`\n    );\n  }\n  return url;\n}\n\n/** Truncates to at most `maxBytes` of UTF-8, without splitting a character. */\nfunction truncateUtf8(value: string, maxBytes: number): string {\n  const { read } = encoder.encodeInto(value, new Uint8Array(maxBytes));\n  return value.slice(0, read);\n}\n"],"mappings":";;;;;;;AA8BA,MAAM,wBAAwB;AAC9B,MAAM,wBAAwB;AAE9B,MAAM,sBAAsB,iCAAiCA;AAE7D,MAAM,UAAU,IAAI,aAAa;;;;;;;;;;;;;;;;;;;AAoBjC,SAAgB,QAAQ,MAAmD;CACzE,IAAI,YAAY,KAAK;CACrB,IAAIC;AACJ,KAAI,cAAc,QAAW;EAC3B,MAAM,MAAM,gBAAgB,KAAK,IAAI;AACrC,mBAAiB,IAAI,oBAAoB,IAAI;AAC7C,cAAY,oBAAoB;GAAE,SAAS,IAAI;GAAM;GAAgB,CAAC;;CAExE,MAAM,YAAY,KAAK,WAAW,MAAM;AACxC,QAAO,IAAI,sBACT,aAAa,cAAc,UAAU,EACrC,YAAY,EAAE,eAAe,UAAU,aAAa,GAAG,QACvD,aACE,KAAK,gBAAgB,SACjB,GAAG,KAAK,YAAY,KAAK,GAAG,KAAK,YAAY,YAC7C,qBACJ,sBACD,EACD,eACD;;AAGH,IAAM,wBAAN,MAAyD;CACvD,CAASC;CACT,CAASC;CACT,CAASC;CACT,CAASC;CACT,UAAU;CAEV,YACE,KACA,SACA,aACA,gBACA;AACA,QAAKH,MAAO;AACZ,QAAKC,UAAW;AAChB,QAAKC,cAAe;AACpB,QAAKC,iBAAkB;;CAGzB,SAAS,OAAwB,EAAE,EAAY;AAC7C,SAAO,MAAKC,YAAyB,IAAI,OAAO,KAAK;;CAGvD,oBACE,YACA,OAAwB,EAAE,EACL;AACrB,MAAI,OAAO,eAAe,YAAY,WAAW,MAAM,KAAK,GAC1D,OAAM,IAAI,UAAU,wCAAwC;AAE9D,MAAI,QAAQ,OAAO,WAAW,CAAC,aAAa,sBAC1C,OAAM,IAAI,WACR,8BAA8B,sBAAsB,QACrD;AAEH,SAAO,MAAKA,YAAoC,YAAY,MAAM,KAAK;;CAGzE,QAAuB;AACrB,QAAKC,SAAU;AACf,QAAKF,gBAAiB,OAAO;AAC7B,SAAO,QAAQ,SAAS;;CAG1B,aACE,YACA,aACA,SACiB;AACjB,MAAI,MAAKE,OACP,OAAM,IAAI,MAAM,mCAAmC;AAErD,SAAO,IAAI,aAAgB;GACzB,KAAK,MAAKL;GACV,SAAS,MAAKC;GACd,aAAa,MAAKC;GAClB;GACA;GACA;GACD,CAAC;;;AAIN,SAAS,gBAAgB,KAAkB;CACzC,IAAII;AACJ,KAAI;AACF,QAAM,IAAI,IAAI,IAAI;UACX,GAAG;AACV,QAAM,IAAI,UAAU,wCAAwC,IAAI,IAAI,EAClE,OAAO,GACR,CAAC;;AAEJ,KAAI,IAAI,aAAa,WAAW,IAAI,aAAa,SAC/C,OAAM,IAAI,UACR,2DAA2D,IAAI,GAChE;AAEH,QAAO;;;AAIT,SAAS,aAAa,OAAe,UAA0B;CAC7D,MAAM,EAAE,SAAS,QAAQ,WAAW,OAAO,IAAI,WAAW,SAAS,CAAC;AACpE,QAAO,MAAM,MAAM,GAAG,KAAK"}

package/dist/errors.cjs

@@ -0,0 +1,52 @@
+const require_ingestion_svc_pb = require('./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.cjs');
+
+//#region src/errors.ts
+/**
+* The error producer operations reject with when the ingestion stream fails.
+*
+* Restate tears the stream down after any error. A record-scoped error carries the
+* {@link IntegrationClientError.offset} of the rejected record; to recover, an exactly-once
+* producer resumes from the last committed offset and skips (or fixes) that record.
+*
+* @experimental
+*/
+var IntegrationClientError = class extends Error {
+	/** Classification of the failure. */
+	kind;
+	/**
+	* Offset of the record the error is about, or `undefined` when the error concerns the
+	* stream as a whole.
+	*/
+	offset;
+	constructor(kind, message, options) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "IntegrationClientError";
+		this.kind = kind;
+		if (options?.offset !== void 0) this.offset = options.offset;
+	}
+};
+function errorFromProto(error) {
+	const kind = kindFromProto(error.kind);
+	const message = error.message || kind;
+	if (error.invocationOffset === void 0) return new IntegrationClientError(kind, message);
+	return new IntegrationClientError(kind, `[offset=${error.invocationOffset}] ${message}`, { offset: toSafeNumber(error.invocationOffset) });
+}
+/** Converts a uint64 from the wire, saturating at `Number.MAX_SAFE_INTEGER`. */
+function toSafeNumber(value) {
+	return value > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(value);
+}
+function kindFromProto(kind) {
+	switch (kind) {
+		case require_ingestion_svc_pb.ErrorKind.SHUTTING_DOWN: return "shutting_down";
+		case require_ingestion_svc_pb.ErrorKind.GO_AWAY: return "go_away";
+		case require_ingestion_svc_pb.ErrorKind.NOT_FOUND: return "not_found";
+		case require_ingestion_svc_pb.ErrorKind.BAD_REQUEST: return "bad_request";
+		case require_ingestion_svc_pb.ErrorKind.UNAVAILABLE: return "unavailable";
+		default: return "unknown";
+	}
+}
+
+//#endregion
+exports.IntegrationClientError = IntegrationClientError;
+exports.errorFromProto = errorFromProto;
+exports.toSafeNumber = toSafeNumber;

package/dist/errors.d.cts

@@ -0,0 +1,42 @@
+import "./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.cjs";
+
+//#region src/errors.d.ts
+
+/**
+ * Classification of an ingestion stream failure.
+ *
+ * - `unknown`: transport failure, unexpected end of the stream, or an unclassified error.
+ * - `shutting_down`: the Restate node is shutting down.
+ * - `go_away`: protocol violation.
+ * - `not_found`: unknown target service or handler.
+ * - `bad_request`: invalid record, e.g. a missing or unexpected key.
+ * - `unavailable`: Restate cannot process the request yet; retry later.
+ *
+ * @experimental
+ */
+type IntegrationClientErrorKind = "unknown" | "shutting_down" | "go_away" | "not_found" | "bad_request" | "unavailable";
+/**
+ * The error producer operations reject with when the ingestion stream fails.
+ *
+ * Restate tears the stream down after any error. A record-scoped error carries the
+ * {@link IntegrationClientError.offset} of the rejected record; to recover, an exactly-once
+ * producer resumes from the last committed offset and skips (or fixes) that record.
+ *
+ * @experimental
+ */
+declare class IntegrationClientError extends Error {
+  /** Classification of the failure. */
+  readonly kind: IntegrationClientErrorKind;
+  /**
+   * Offset of the record the error is about, or `undefined` when the error concerns the
+   * stream as a whole.
+   */
+  readonly offset?: number;
+  constructor(kind: IntegrationClientErrorKind, message: string, options?: {
+    offset?: number;
+    cause?: unknown;
+  });
+}
+//#endregion
+export { IntegrationClientError, IntegrationClientErrorKind };
+//# sourceMappingURL=errors.d.cts.map

package/dist/errors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.cts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;AA4BA;AAiBA;;;;;;;;;KAjBY,0BAAA;;;;;;;;;;cAiBC,sBAAA,SAA+B,KAAA;;iBAE3B;;;;;;oBASP"}

package/dist/errors.d.ts

@@ -0,0 +1,42 @@
+import "./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.js";
+
+//#region src/errors.d.ts
+
+/**
+ * Classification of an ingestion stream failure.
+ *
+ * - `unknown`: transport failure, unexpected end of the stream, or an unclassified error.
+ * - `shutting_down`: the Restate node is shutting down.
+ * - `go_away`: protocol violation.
+ * - `not_found`: unknown target service or handler.
+ * - `bad_request`: invalid record, e.g. a missing or unexpected key.
+ * - `unavailable`: Restate cannot process the request yet; retry later.
+ *
+ * @experimental
+ */
+type IntegrationClientErrorKind = "unknown" | "shutting_down" | "go_away" | "not_found" | "bad_request" | "unavailable";
+/**
+ * The error producer operations reject with when the ingestion stream fails.
+ *
+ * Restate tears the stream down after any error. A record-scoped error carries the
+ * {@link IntegrationClientError.offset} of the rejected record; to recover, an exactly-once
+ * producer resumes from the last committed offset and skips (or fixes) that record.
+ *
+ * @experimental
+ */
+declare class IntegrationClientError extends Error {
+  /** Classification of the failure. */
+  readonly kind: IntegrationClientErrorKind;
+  /**
+   * Offset of the record the error is about, or `undefined` when the error concerns the
+   * stream as a whole.
+   */
+  readonly offset?: number;
+  constructor(kind: IntegrationClientErrorKind, message: string, options?: {
+    offset?: number;
+    cause?: unknown;
+  });
+}
+//#endregion
+export { IntegrationClientError, IntegrationClientErrorKind };
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;;;;;AA4BA;AAiBA;;;;;;;;;KAjBY,0BAAA;;;;;;;;;;cAiBC,sBAAA,SAA+B,KAAA;;iBAE3B;;;;;;oBASP"}

package/dist/errors.js

@@ -0,0 +1,51 @@
+import { ErrorKind } from "./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.js";
+
+//#region src/errors.ts
+/**
+* The error producer operations reject with when the ingestion stream fails.
+*
+* Restate tears the stream down after any error. A record-scoped error carries the
+* {@link IntegrationClientError.offset} of the rejected record; to recover, an exactly-once
+* producer resumes from the last committed offset and skips (or fixes) that record.
+*
+* @experimental
+*/
+var IntegrationClientError = class extends Error {
+	/** Classification of the failure. */
+	kind;
+	/**
+	* Offset of the record the error is about, or `undefined` when the error concerns the
+	* stream as a whole.
+	*/
+	offset;
+	constructor(kind, message, options) {
+		super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
+		this.name = "IntegrationClientError";
+		this.kind = kind;
+		if (options?.offset !== void 0) this.offset = options.offset;
+	}
+};
+function errorFromProto(error) {
+	const kind = kindFromProto(error.kind);
+	const message = error.message || kind;
+	if (error.invocationOffset === void 0) return new IntegrationClientError(kind, message);
+	return new IntegrationClientError(kind, `[offset=${error.invocationOffset}] ${message}`, { offset: toSafeNumber(error.invocationOffset) });
+}
+/** Converts a uint64 from the wire, saturating at `Number.MAX_SAFE_INTEGER`. */
+function toSafeNumber(value) {
+	return value > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(value);
+}
+function kindFromProto(kind) {
+	switch (kind) {
+		case ErrorKind.SHUTTING_DOWN: return "shutting_down";
+		case ErrorKind.GO_AWAY: return "go_away";
+		case ErrorKind.NOT_FOUND: return "not_found";
+		case ErrorKind.BAD_REQUEST: return "bad_request";
+		case ErrorKind.UNAVAILABLE: return "unavailable";
+		default: return "unknown";
+	}
+}
+
+//#endregion
+export { IntegrationClientError, errorFromProto, toSafeNumber };
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/*\n * Copyright (c) 2023-2026 - Restate Software, Inc., Restate GmbH\n *\n * This file is part of the Restate SDK for Node.js/TypeScript,\n * which is released under the MIT license.\n *\n * You can find a copy of the license in file LICENSE in the root\n * directory of this repository or package, or at\n * https://github.com/restatedev/sdk-typescript/blob/main/LICENSE\n */\n\nimport {\n  ErrorKind,\n  type Error as ProtoError,\n} from \"./generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.js\";\n\n/**\n * Classification of an ingestion stream failure.\n *\n * - `unknown`: transport failure, unexpected end of the stream, or an unclassified error.\n * - `shutting_down`: the Restate node is shutting down.\n * - `go_away`: protocol violation.\n * - `not_found`: unknown target service or handler.\n * - `bad_request`: invalid record, e.g. a missing or unexpected key.\n * - `unavailable`: Restate cannot process the request yet; retry later.\n *\n * @experimental\n */\nexport type IntegrationClientErrorKind =\n  | \"unknown\"\n  | \"shutting_down\"\n  | \"go_away\"\n  | \"not_found\"\n  | \"bad_request\"\n  | \"unavailable\";\n\n/**\n * The error producer operations reject with when the ingestion stream fails.\n *\n * Restate tears the stream down after any error. A record-scoped error carries the\n * {@link IntegrationClientError.offset} of the rejected record; to recover, an exactly-once\n * producer resumes from the last committed offset and skips (or fixes) that record.\n *\n * @experimental\n */\nexport class IntegrationClientError extends Error {\n  /** Classification of the failure. */\n  readonly kind: IntegrationClientErrorKind;\n\n  /**\n   * Offset of the record the error is about, or `undefined` when the error concerns the\n   * stream as a whole.\n   */\n  readonly offset?: number;\n\n  constructor(\n    kind: IntegrationClientErrorKind,\n    message: string,\n    options?: { offset?: number; cause?: unknown }\n  ) {\n    super(\n      message,\n      options?.cause !== undefined ? { cause: options.cause } : undefined\n    );\n    this.name = \"IntegrationClientError\";\n    this.kind = kind;\n    if (options?.offset !== undefined) {\n      this.offset = options.offset;\n    }\n  }\n}\n\nexport function errorFromProto(error: ProtoError): IntegrationClientError {\n  const kind = kindFromProto(error.kind);\n  const message = error.message || kind;\n  if (error.invocationOffset === undefined) {\n    return new IntegrationClientError(kind, message);\n  }\n  return new IntegrationClientError(\n    kind,\n    `[offset=${error.invocationOffset}] ${message}`,\n    { offset: toSafeNumber(error.invocationOffset) }\n  );\n}\n\n/** Converts a uint64 from the wire, saturating at `Number.MAX_SAFE_INTEGER`. */\nexport function toSafeNumber(value: bigint): number {\n  return value > BigInt(Number.MAX_SAFE_INTEGER)\n    ? Number.MAX_SAFE_INTEGER\n    : Number(value);\n}\n\nfunction kindFromProto(kind: ErrorKind): IntegrationClientErrorKind {\n  switch (kind) {\n    case ErrorKind.SHUTTING_DOWN:\n      return \"shutting_down\";\n    case ErrorKind.GO_AWAY:\n      return \"go_away\";\n    case ErrorKind.NOT_FOUND:\n      return \"not_found\";\n    case ErrorKind.BAD_REQUEST:\n      return \"bad_request\";\n    case ErrorKind.UNAVAILABLE:\n      return \"unavailable\";\n    default:\n      return \"unknown\";\n  }\n}\n"],"mappings":";;;;;;;;;;;;AA6CA,IAAa,yBAAb,cAA4C,MAAM;;CAEhD,AAAS;;;;;CAMT,AAAS;CAET,YACE,MACA,SACA,SACA;AACA,QACE,SACA,SAAS,UAAU,SAAY,EAAE,OAAO,QAAQ,OAAO,GAAG,OAC3D;AACD,OAAK,OAAO;AACZ,OAAK,OAAO;AACZ,MAAI,SAAS,WAAW,OACtB,MAAK,SAAS,QAAQ;;;AAK5B,SAAgB,eAAe,OAA2C;CACxE,MAAM,OAAO,cAAc,MAAM,KAAK;CACtC,MAAM,UAAU,MAAM,WAAW;AACjC,KAAI,MAAM,qBAAqB,OAC7B,QAAO,IAAI,uBAAuB,MAAM,QAAQ;AAElD,QAAO,IAAI,uBACT,MACA,WAAW,MAAM,iBAAiB,IAAI,WACtC,EAAE,QAAQ,aAAa,MAAM,iBAAiB,EAAE,CACjD;;;AAIH,SAAgB,aAAa,OAAuB;AAClD,QAAO,QAAQ,OAAO,OAAO,iBAAiB,GAC1C,OAAO,mBACP,OAAO,MAAM;;AAGnB,SAAS,cAAc,MAA6C;AAClE,SAAQ,MAAR;EACE,KAAK,UAAU,cACb,QAAO;EACT,KAAK,UAAU,QACb,QAAO;EACT,KAAK,UAAU,UACb,QAAO;EACT,KAAK,UAAU,YACb,QAAO;EACT,KAAK,UAAU,YACb,QAAO;EACT,QACE,QAAO"}

package/dist/generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.cjs

@@ -0,0 +1,137 @@
+const require_rolldown_runtime = require('../../../../../../_virtual/rolldown_runtime.cjs');
+let __bufbuild_protobuf_codegenv2 = require("@bufbuild/protobuf/codegenv2");
+__bufbuild_protobuf_codegenv2 = require_rolldown_runtime.__toESM(__bufbuild_protobuf_codegenv2);
+
+//#region src/generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.ts
+/**
+* Describes the file dev/restate/ingress/ingestion/v1/ingestion_svc.proto.
+*/
+const file_dev_restate_ingress_ingestion_v1_ingestion_svc = /* @__PURE__ */ (0, __bufbuild_protobuf_codegenv2.fileDesc)("CjRkZXYvcmVzdGF0ZS9pbmdyZXNzL2luZ2VzdGlvbi92MS9pbmdlc3Rpb25fc3ZjLnByb3RvEiBkZXYucmVzdGF0ZS5pbmdyZXNzLmluZ2VzdGlvbi52MSLSAQoOSW5nZXN0aW9uU3RhcnQSEwoLcHJvZHVjZXJfaWQYASABKAkSEwoLaW50ZWdyYXRpb24YAiABKAkSTwoSZGVkdXBsaWNhdGlvbl9tb2RlGAMgASgOMjMuZGV2LnJlc3RhdGUuaW5ncmVzcy5pbmdlc3Rpb24udjEuRGVkdXBsaWNhdGlvbk1vZGUSRQoIZGVmYXVsdHMYBCABKAsyMy5kZXYucmVzdGF0ZS5pbmdyZXNzLmluZ2VzdGlvbi52MS5Jbmdlc3Rpb25EZWZhdWx0cyK+AgoRSW5nZXN0aW9uRGVmYXVsdHMSEgoFc2NvcGUYAiABKAlIAIgBARIWCglsaW1pdF9rZXkYAyABKAlIAYgBARIUCgdzZXJ2aWNlGAQgASgJSAKIAQESFAoHaGFuZGxlchgFIAEoCUgDiAEBEhAKA2tleRgGIAEoCUgEiAEBElEKB2hlYWRlcnMYCCADKAsyQC5kZXYucmVzdGF0ZS5pbmdyZXNzLmluZ2VzdGlvbi52MS5Jbmdlc3Rpb25EZWZhdWx0cy5IZWFkZXJzRW50cnkaLgoMSGVhZGVyc0VudHJ5EgsKA2tleRgBIAEoCRINCgV2YWx1ZRgCIAEoCToCOAFCCAoGX3Njb3BlQgwKCl9saW1pdF9rZXlCCgoIX3NlcnZpY2VCCgoIX2hhbmRsZXJCBgoEX2tleUoECAcQCCK2BAoTSW5nZXN0aW9uSW52b2NhdGlvbhIOCgZvZmZzZXQYASABKAQSEgoFc2NvcGUYAiABKAlIAIgBARIWCglsaW1pdF9rZXkYAyABKAlIAYgBARIUCgdzZXJ2aWNlGAQgASgJSAKIAQESFAoHaGFuZGxlchgFIAEoCUgDiAEBEhAKA2tleRgGIAEoCUgEiAEBEhwKD2lkZW1wb3RlbmN5X2tleRgHIAEoCUgFiAEBEmgKEmFkZGl0aW9uYWxfaGVhZGVycxgIIAMoCzJMLmRldi5yZXN0YXRlLmluZ3Jlc3MuaW5nZXN0aW9uLnYxLkluZ2VzdGlvbkludm9jYXRpb24uQWRkaXRpb25hbEhlYWRlcnNFbnRyeRIeChFpbnZva2VfdGltZV90c19tcxgKIAEoBEgGiAEBEhgKC3RyYWNlcGFyZW50GAsgASgJSAeIAQESFwoKdHJhY2VzdGF0ZRgMIAEoCUgIiAEBEg8KB3BheWxvYWQYDSABKAwaOAoWQWRkaXRpb25hbEhlYWRlcnNFbnRyeRILCgNrZXkYASABKAkSDQoFdmFsdWUYAiABKAk6AjgBQggKBl9zY29wZUIMCgpfbGltaXRfa2V5QgoKCF9zZXJ2aWNlQgoKCF9oYW5kbGVyQgYKBF9rZXlCEgoQX2lkZW1wb3RlbmN5X2tleUIUChJfaW52b2tlX3RpbWVfdHNfbXNCDgoMX3RyYWNlcGFyZW50Qg0KC190cmFjZXN0YXRlIvMBChBJbmdlc3Rpb25SZXF1ZXN0EkEKBXN0YXJ0GAEgASgLMjAuZGV2LnJlc3RhdGUuaW5ncmVzcy5pbmdlc3Rpb24udjEuSW5nZXN0aW9uU3RhcnRIABJHCghkZWZhdWx0cxgCIAEoCzIzLmRldi5yZXN0YXRlLmluZ3Jlc3MuaW5nZXN0aW9uLnYxLkluZ2VzdGlvbkRlZmF1bHRzSAASSwoKaW52b2NhdGlvbhgDIAEoCzI1LmRldi5yZXN0YXRlLmluZ3Jlc3MuaW5nZXN0aW9uLnYxLkluZ2VzdGlvbkludm9jYXRpb25IAEIGCgRraW5kIicKDFdpbmRvd1VwZGF0ZRIXCg9pbmNyZW1lbnRfYnl0ZXMYASABKA0iiQEKBUVycm9yEh4KEWludm9jYXRpb25fb2Zmc2V0GAEgASgESACIAQESOQoEa2luZBgCIAEoDjIrLmRldi5yZXN0YXRlLmluZ3Jlc3MuaW5nZXN0aW9uLnYxLkVycm9yS2luZBIPCgdtZXNzYWdlGAMgASgJQhQKEl9pbnZvY2F0aW9uX29mZnNldCLSAQoRSW5nZXN0aW9uUmVzcG9uc2USGwoObGFzdF9jb21taXR0ZWQYASABKARIAYgBARJHCg13aW5kb3dfdXBkYXRlGAIgASgLMi4uZGV2LnJlc3RhdGUuaW5ncmVzcy5pbmdlc3Rpb24udjEuV2luZG93VXBkYXRlSAASOAoFZXJyb3IYAyABKAsyJy5kZXYucmVzdGF0ZS5pbmdyZXNzLmluZ2VzdGlvbi52MS5FcnJvckgAQgoKCHJlc3BvbnNlQhEKD19sYXN0X2NvbW1pdHRlZCozChFEZWR1cGxpY2F0aW9uTW9kZRIMCghESVNBQkxFRBAAEhAKDE9GRlNFVF9CQVNFRBABKqsBCglFcnJvcktpbmQSFgoSRVJST1JfS0lORF9VTktOT1dOEAASHAoYRVJST1JfS0lORF9TSFVUVElOR19ET1dOEAESFgoSRVJST1JfS0lORF9HT19BV0FZEAISGAoURVJST1JfS0lORF9OT1RfRk9VTkQQAxIaChZFUlJPUl9LSU5EX0JBRF9SRVFVRVNUEAQSGgoWRVJST1JfS0lORF9VTkFWQUlMQUJMRRAFMoUBCgxJbmdlc3Rpb25TdmMSdQoGSW5nZXN0EjIuZGV2LnJlc3RhdGUuaW5ncmVzcy5pbmdlc3Rpb24udjEuSW5nZXN0aW9uUmVxdWVzdBozLmRldi5yZXN0YXRlLmluZ3Jlc3MuaW5nZXN0aW9uLnYxLkluZ2VzdGlvblJlc3BvbnNlKAEwAUIsChhkZXYucmVzdGF0ZS5pbmdlc3Rpb24udjFCDkluZ2VzdGlvblByb3RvUAFiBnByb3RvMw");
+/**
+* Describes the message dev.restate.ingress.ingestion.v1.IngestionDefaults.
+* Use `create(IngestionDefaultsSchema)` to create a new message.
+*/
+const IngestionDefaultsSchema = /* @__PURE__ */ (0, __bufbuild_protobuf_codegenv2.messageDesc)(file_dev_restate_ingress_ingestion_v1_ingestion_svc, 1);
+/**
+* Describes the message dev.restate.ingress.ingestion.v1.IngestionInvocation.
+* Use `create(IngestionInvocationSchema)` to create a new message.
+*/
+const IngestionInvocationSchema = /* @__PURE__ */ (0, __bufbuild_protobuf_codegenv2.messageDesc)(file_dev_restate_ingress_ingestion_v1_ingestion_svc, 2);
+/**
+* Describes the message dev.restate.ingress.ingestion.v1.IngestionRequest.
+* Use `create(IngestionRequestSchema)` to create a new message.
+*/
+const IngestionRequestSchema = /* @__PURE__ */ (0, __bufbuild_protobuf_codegenv2.messageDesc)(file_dev_restate_ingress_ingestion_v1_ingestion_svc, 3);
+/**
+* How the server deduplicates the records of a stream.
+*
+* The mode is fixed for the lifetime of the stream: it is chosen once in the
+* `Start` frame and cannot be changed by a later `IngestionDefaults` frame.
+*
+* Note that this only controls deduplication. Regardless of the mode, every
+* `Invocation` must still carry an `offset`, offsets must still increase
+* monotonically within a stream, and `Response.last_committed` still reports
+* progress in terms of those offsets.
+*
+* @generated from enum dev.restate.ingress.ingestion.v1.DeduplicationMode
+*/
+let DeduplicationMode = /* @__PURE__ */ function(DeduplicationMode$1) {
+	/**
+	* Disable deduplication: every record accepted by the server becomes an
+	* invocation.
+	*
+	* Nothing is tracked across streams, so resending records after a
+	* reconnect duplicates them. Pick this mode only when the producer cannot
+	* supply a stable ID, or when duplicates are acceptable or already
+	* suppressed elsewhere (for example by an `idempotency_key`).
+	*
+	* `producer_id` is optional in this mode, but is still recorded on traces
+	* and metrics when set.
+	*
+	* @generated from enum value: DISABLED = 0;
+	*/
+	DeduplicationMode$1[DeduplicationMode$1["DISABLED"] = 0] = "DISABLED";
+	/**
+	* Deduplicate on `(producer_id, offset)`.
+	*
+	* The server tracks the highest committed offset per producer ID and
+	* silently drops any record whose offset is not above it, which makes
+	* resending a range of records after a reconnect safe: records the server
+	* already committed do not become duplicate invocations.
+	*
+	* This mode requires `producer_id` to be set; using it with an empty
+	* producer ID fails the stream with `GO_AWAY`. It also requires the
+	* producer to reuse the same ID across streams, since a new ID starts
+	* from a fresh deduplication state.
+	*
+	* @generated from enum value: OFFSET_BASED = 1;
+	*/
+	DeduplicationMode$1[DeduplicationMode$1["OFFSET_BASED"] = 1] = "OFFSET_BASED";
+	return DeduplicationMode$1;
+}({});
+/**
+* @generated from enum dev.restate.ingress.ingestion.v1.ErrorKind
+*/
+let ErrorKind = /* @__PURE__ */ function(ErrorKind$1) {
+	/**
+	* @generated from enum value: ERROR_KIND_UNKNOWN = 0;
+	*/
+	ErrorKind$1[ErrorKind$1["UNKNOWN"] = 0] = "UNKNOWN";
+	/**
+	* The server is shutting down and can't accept more
+	* records. The caller must switch to a new ingress
+	* node and respect the reported last_committed.
+	*
+	* @generated from enum value: ERROR_KIND_SHUTTING_DOWN = 1;
+	*/
+	ErrorKind$1[ErrorKind$1["SHUTTING_DOWN"] = 1] = "SHUTTING_DOWN";
+	/**
+	* A protocol violation, for example sending another
+	* Start message after the initial one or not
+	* respecting the send window.
+	*
+	* @generated from enum value: ERROR_KIND_GO_AWAY = 2;
+	*/
+	ErrorKind$1[ErrorKind$1["GO_AWAY"] = 2] = "GO_AWAY";
+	/**
+	* The invocation target was not found (unknown
+	* service or handler).
+	*
+	* @generated from enum value: ERROR_KIND_NOT_FOUND = 3;
+	*/
+	ErrorKind$1[ErrorKind$1["NOT_FOUND"] = 3] = "NOT_FOUND";
+	/**
+	* Covers a wide range of client errors, including:
+	* - unexpected key
+	* - missing key
+	* - invalid scope format
+	* and similar errors. The `Error.message` should
+	* carry more details.
+	*
+	* @generated from enum value: ERROR_KIND_BAD_REQUEST = 4;
+	*/
+	ErrorKind$1[ErrorKind$1["BAD_REQUEST"] = 4] = "BAD_REQUEST";
+	/**
+	* The server can't process the request yet, for
+	* example because it has not loaded the schema.
+	* The caller should retry later (possibly on a
+	* different ingress node) without changing the
+	* request.
+	*
+	* @generated from enum value: ERROR_KIND_UNAVAILABLE = 5;
+	*/
+	ErrorKind$1[ErrorKind$1["UNAVAILABLE"] = 5] = "UNAVAILABLE";
+	return ErrorKind$1;
+}({});
+/**
+* @generated from service dev.restate.ingress.ingestion.v1.IngestionSvc
+*/
+const IngestionSvc = /* @__PURE__ */ (0, __bufbuild_protobuf_codegenv2.serviceDesc)(file_dev_restate_ingress_ingestion_v1_ingestion_svc, 0);
+
+//#endregion
+exports.DeduplicationMode = DeduplicationMode;
+exports.ErrorKind = ErrorKind;
+exports.IngestionDefaultsSchema = IngestionDefaultsSchema;
+exports.IngestionInvocationSchema = IngestionInvocationSchema;
+exports.IngestionRequestSchema = IngestionRequestSchema;
+exports.IngestionSvc = IngestionSvc;

package/dist/generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.d.cts

@@ -0,0 +1 @@
+import "@bufbuild/protobuf";

package/dist/generated/dev/restate/ingress/ingestion/v1/ingestion_svc_pb.d.ts

@@ -0,0 +1,2 @@
+import "@bufbuild/protobuf/codegenv2";
+import "@bufbuild/protobuf";