@wandelbots/nova-js 3.13.0-pr.307.ea0533d → 3.13.0

package/dist/converters-DnG1fX23.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters-DnG1fX23.mjs","names":[],"sources":["../src/lib/converters.ts"],"sourcesContent":["export type URLParseOptions = {\n  /**\n   * Ignore any scheme in the input string and force this scheme instead.\n   */\n  scheme?: \"http\" | \"https\"\n  /**\n   * If the input string does not include a scheme, use this as the default\n   * scheme.\n   */\n  defaultScheme?: \"http\" | \"https\"\n}\n\n/**\n * Parse a string as a URL, with options to enforce or default the scheme.\n */\nexport function parseUrl(url: string, options: URLParseOptions = {}): URL {\n  const { scheme, defaultScheme } = options\n\n  const schemeRegex = /^[a-zA-Z]+:\\/\\//\n\n  if (scheme) {\n    // Force the scheme by removing any existing scheme and prepending the desired one\n    url = url.replace(schemeRegex, \"\")\n    url = `${scheme}://${url}`\n  } else if (defaultScheme && !schemeRegex.test(url)) {\n    // No scheme is present, add the default one\n    url = `${defaultScheme}://${url}`\n  }\n\n  return new URL(url)\n}\n\n/**\n * Attempt to parse a string as a URL; return undefined if we can't\n */\nexport function tryParseUrl(\n  url: string,\n  options: URLParseOptions = {},\n): URL | undefined {\n  try {\n    return parseUrl(url, options)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Permissively parse a NOVA instance URL from a config variable.\n * If scheme is not specified, defaults to https for *.wandelbots.io hosts,\n * and http otherwise.\n * Throws an error if a valid URL could not be determined.\n */\nexport function parseNovaInstanceUrl(url: string): URL {\n  const testUrl = tryParseUrl(url, { defaultScheme: \"http\" })\n  if (testUrl?.host.endsWith(\".wandelbots.io\")) {\n    return parseUrl(url, { defaultScheme: \"https\" })\n  } else {\n    return parseUrl(url, { defaultScheme: \"http\" })\n  }\n}\n\n/** Try to parse something as JSON; return undefined if we can't */\n// biome-ignore lint/suspicious/noExplicitAny: it's json\nexport function tryParseJson(json: unknown): any {\n  try {\n    return JSON.parse(json as string)\n  } catch {\n    return undefined\n  }\n}\n\n/** Try to turn something into JSON; return undefined if we can't */\nexport function tryStringifyJson(json: unknown): string | undefined {\n  try {\n    return JSON.stringify(json)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Converts object parameters to query string.\n * e.g. { a: \"1\", b: \"2\" } => \"?a=1&b=2\"\n *      {} => \"\"\n */\nexport function makeUrlQueryString(obj: Record<string, string>): string {\n  const str = new URLSearchParams(obj).toString()\n  return str ? `?${str}` : \"\"\n}\n\n/** Convert radians to degrees */\nexport function radiansToDegrees(radians: number): number {\n  return radians * (180 / Math.PI)\n}\n\n/** Convert degrees to radians */\nexport function degreesToRadians(degrees: number): number {\n  return degrees * (Math.PI / 180)\n}\n\n/**\n * Check for coordinate system id equivalence, accounting for the \"world\" default\n * on empty/undefined values.\n */\nexport function isSameCoordinateSystem(\n  firstCoordSystem: string | undefined,\n  secondCoordSystem: string | undefined,\n) {\n  if (!firstCoordSystem) firstCoordSystem = \"world\"\n  if (!secondCoordSystem) secondCoordSystem = \"world\"\n\n  return firstCoordSystem === secondCoordSystem\n}\n\n/**\n * Helpful const for converting {x, y, z} to [x, y, z] and vice versa\n */\nexport const XYZ_TO_VECTOR = { x: 0, y: 1, z: 2 }\n"],"mappings":";;;;AAeA,SAAgB,SAAS,KAAa,UAA2B,CAAC,GAAQ;CACxE,MAAM,EAAE,QAAQ,kBAAkB;CAElC,MAAM,cAAc;CAEpB,IAAI,QAAQ;EAEV,MAAM,IAAI,QAAQ,aAAa,EAAE;EACjC,MAAM,GAAG,OAAO,KAAK;CACvB,OAAO,IAAI,iBAAiB,CAAC,YAAY,KAAK,GAAG,GAE/C,MAAM,GAAG,cAAc,KAAK;CAG9B,OAAO,IAAI,IAAI,GAAG;AACpB;;;;AAKA,SAAgB,YACd,KACA,UAA2B,CAAC,GACX;CACjB,IAAI;EACF,OAAO,SAAS,KAAK,OAAO;CAC9B,QAAQ;EACN;CACF;AACF;;;;;;;AAQA,SAAgB,qBAAqB,KAAkB;CAErD,IADgB,YAAY,KAAK,EAAE,eAAe,OAAO,CAC/C,GAAG,KAAK,SAAS,gBAAgB,GACzC,OAAO,SAAS,KAAK,EAAE,eAAe,QAAQ,CAAC;MAE/C,OAAO,SAAS,KAAK,EAAE,eAAe,OAAO,CAAC;AAElD;;AAIA,SAAgB,aAAa,MAAoB;CAC/C,IAAI;EACF,OAAO,KAAK,MAAM,IAAc;CAClC,QAAQ;EACN;CACF;AACF;;AAGA,SAAgB,iBAAiB,MAAmC;CAClE,IAAI;EACF,OAAO,KAAK,UAAU,IAAI;CAC5B,QAAQ;EACN;CACF;AACF;;;;;;AAOA,SAAgB,mBAAmB,KAAqC;CACtE,MAAM,MAAM,IAAI,gBAAgB,GAAG,EAAE,SAAS;CAC9C,OAAO,MAAM,IAAI,QAAQ;AAC3B;;AAGA,SAAgB,iBAAiB,SAAyB;CACxD,OAAO,WAAW,MAAM,KAAK;AAC/B;;AAGA,SAAgB,iBAAiB,SAAyB;CACxD,OAAO,WAAW,KAAK,KAAK;AAC9B;;;;;AAMA,SAAgB,uBACd,kBACA,mBACA;CACA,IAAI,CAAC,kBAAkB,mBAAmB;CAC1C,IAAI,CAAC,mBAAmB,oBAAoB;CAE5C,OAAO,qBAAqB;AAC9B;;;;AAKA,MAAa,gBAAgB;CAAE,GAAG;CAAG,GAAG;CAAG,GAAG;AAAE"}

package/dist/converters-EYS27XJE.cjs

@@ -0,0 +1,146 @@
+//#region src/lib/converters.ts
+/**
+* Parse a string as a URL, with options to enforce or default the scheme.
+*/
+function parseUrl(url, options = {}) {
+	const { scheme, defaultScheme } = options;
+	const schemeRegex = /^[a-zA-Z]+:\/\//;
+	if (scheme) {
+		url = url.replace(schemeRegex, "");
+		url = `${scheme}://${url}`;
+	} else if (defaultScheme && !schemeRegex.test(url)) url = `${defaultScheme}://${url}`;
+	return new URL(url);
+}
+/**
+* Attempt to parse a string as a URL; return undefined if we can't
+*/
+function tryParseUrl(url, options = {}) {
+	try {
+		return parseUrl(url, options);
+	} catch {
+		return;
+	}
+}
+/**
+* Permissively parse a NOVA instance URL from a config variable.
+* If scheme is not specified, defaults to https for *.wandelbots.io hosts,
+* and http otherwise.
+* Throws an error if a valid URL could not be determined.
+*/
+function parseNovaInstanceUrl(url) {
+	if (tryParseUrl(url, { defaultScheme: "http" })?.host.endsWith(".wandelbots.io")) return parseUrl(url, { defaultScheme: "https" });
+	else return parseUrl(url, { defaultScheme: "http" });
+}
+/** Try to parse something as JSON; return undefined if we can't */
+function tryParseJson(json) {
+	try {
+		return JSON.parse(json);
+	} catch {
+		return;
+	}
+}
+/** Try to turn something into JSON; return undefined if we can't */
+function tryStringifyJson(json) {
+	try {
+		return JSON.stringify(json);
+	} catch {
+		return;
+	}
+}
+/**
+* Converts object parameters to query string.
+* e.g. { a: "1", b: "2" } => "?a=1&b=2"
+*      {} => ""
+*/
+function makeUrlQueryString(obj) {
+	const str = new URLSearchParams(obj).toString();
+	return str ? `?${str}` : "";
+}
+/** Convert radians to degrees */
+function radiansToDegrees(radians) {
+	return radians * (180 / Math.PI);
+}
+/** Convert degrees to radians */
+function degreesToRadians(degrees) {
+	return degrees * (Math.PI / 180);
+}
+/**
+* Check for coordinate system id equivalence, accounting for the "world" default
+* on empty/undefined values.
+*/
+function isSameCoordinateSystem(firstCoordSystem, secondCoordSystem) {
+	if (!firstCoordSystem) firstCoordSystem = "world";
+	if (!secondCoordSystem) secondCoordSystem = "world";
+	return firstCoordSystem === secondCoordSystem;
+}
+/**
+* Helpful const for converting {x, y, z} to [x, y, z] and vice versa
+*/
+const XYZ_TO_VECTOR = {
+	x: 0,
+	y: 1,
+	z: 2
+};
+//#endregion
+Object.defineProperty(exports, "XYZ_TO_VECTOR", {
+	enumerable: true,
+	get: function() {
+		return XYZ_TO_VECTOR;
+	}
+});
+Object.defineProperty(exports, "degreesToRadians", {
+	enumerable: true,
+	get: function() {
+		return degreesToRadians;
+	}
+});
+Object.defineProperty(exports, "isSameCoordinateSystem", {
+	enumerable: true,
+	get: function() {
+		return isSameCoordinateSystem;
+	}
+});
+Object.defineProperty(exports, "makeUrlQueryString", {
+	enumerable: true,
+	get: function() {
+		return makeUrlQueryString;
+	}
+});
+Object.defineProperty(exports, "parseNovaInstanceUrl", {
+	enumerable: true,
+	get: function() {
+		return parseNovaInstanceUrl;
+	}
+});
+Object.defineProperty(exports, "parseUrl", {
+	enumerable: true,
+	get: function() {
+		return parseUrl;
+	}
+});
+Object.defineProperty(exports, "radiansToDegrees", {
+	enumerable: true,
+	get: function() {
+		return radiansToDegrees;
+	}
+});
+Object.defineProperty(exports, "tryParseJson", {
+	enumerable: true,
+	get: function() {
+		return tryParseJson;
+	}
+});
+Object.defineProperty(exports, "tryParseUrl", {
+	enumerable: true,
+	get: function() {
+		return tryParseUrl;
+	}
+});
+Object.defineProperty(exports, "tryStringifyJson", {
+	enumerable: true,
+	get: function() {
+		return tryStringifyJson;
+	}
+});
+
+//# sourceMappingURL=converters-EYS27XJE.cjs.map

package/dist/converters-EYS27XJE.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"converters-EYS27XJE.cjs","names":[],"sources":["../src/lib/converters.ts"],"sourcesContent":["export type URLParseOptions = {\n  /**\n   * Ignore any scheme in the input string and force this scheme instead.\n   */\n  scheme?: \"http\" | \"https\"\n  /**\n   * If the input string does not include a scheme, use this as the default\n   * scheme.\n   */\n  defaultScheme?: \"http\" | \"https\"\n}\n\n/**\n * Parse a string as a URL, with options to enforce or default the scheme.\n */\nexport function parseUrl(url: string, options: URLParseOptions = {}): URL {\n  const { scheme, defaultScheme } = options\n\n  const schemeRegex = /^[a-zA-Z]+:\\/\\//\n\n  if (scheme) {\n    // Force the scheme by removing any existing scheme and prepending the desired one\n    url = url.replace(schemeRegex, \"\")\n    url = `${scheme}://${url}`\n  } else if (defaultScheme && !schemeRegex.test(url)) {\n    // No scheme is present, add the default one\n    url = `${defaultScheme}://${url}`\n  }\n\n  return new URL(url)\n}\n\n/**\n * Attempt to parse a string as a URL; return undefined if we can't\n */\nexport function tryParseUrl(\n  url: string,\n  options: URLParseOptions = {},\n): URL | undefined {\n  try {\n    return parseUrl(url, options)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Permissively parse a NOVA instance URL from a config variable.\n * If scheme is not specified, defaults to https for *.wandelbots.io hosts,\n * and http otherwise.\n * Throws an error if a valid URL could not be determined.\n */\nexport function parseNovaInstanceUrl(url: string): URL {\n  const testUrl = tryParseUrl(url, { defaultScheme: \"http\" })\n  if (testUrl?.host.endsWith(\".wandelbots.io\")) {\n    return parseUrl(url, { defaultScheme: \"https\" })\n  } else {\n    return parseUrl(url, { defaultScheme: \"http\" })\n  }\n}\n\n/** Try to parse something as JSON; return undefined if we can't */\n// biome-ignore lint/suspicious/noExplicitAny: it's json\nexport function tryParseJson(json: unknown): any {\n  try {\n    return JSON.parse(json as string)\n  } catch {\n    return undefined\n  }\n}\n\n/** Try to turn something into JSON; return undefined if we can't */\nexport function tryStringifyJson(json: unknown): string | undefined {\n  try {\n    return JSON.stringify(json)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Converts object parameters to query string.\n * e.g. { a: \"1\", b: \"2\" } => \"?a=1&b=2\"\n *      {} => \"\"\n */\nexport function makeUrlQueryString(obj: Record<string, string>): string {\n  const str = new URLSearchParams(obj).toString()\n  return str ? `?${str}` : \"\"\n}\n\n/** Convert radians to degrees */\nexport function radiansToDegrees(radians: number): number {\n  return radians * (180 / Math.PI)\n}\n\n/** Convert degrees to radians */\nexport function degreesToRadians(degrees: number): number {\n  return degrees * (Math.PI / 180)\n}\n\n/**\n * Check for coordinate system id equivalence, accounting for the \"world\" default\n * on empty/undefined values.\n */\nexport function isSameCoordinateSystem(\n  firstCoordSystem: string | undefined,\n  secondCoordSystem: string | undefined,\n) {\n  if (!firstCoordSystem) firstCoordSystem = \"world\"\n  if (!secondCoordSystem) secondCoordSystem = \"world\"\n\n  return firstCoordSystem === secondCoordSystem\n}\n\n/**\n * Helpful const for converting {x, y, z} to [x, y, z] and vice versa\n */\nexport const XYZ_TO_VECTOR = { x: 0, y: 1, z: 2 }\n"],"mappings":";;;;AAeA,SAAgB,SAAS,KAAa,UAA2B,CAAC,GAAQ;CACxE,MAAM,EAAE,QAAQ,kBAAkB;CAElC,MAAM,cAAc;CAEpB,IAAI,QAAQ;EAEV,MAAM,IAAI,QAAQ,aAAa,EAAE;EACjC,MAAM,GAAG,OAAO,KAAK;CACvB,OAAO,IAAI,iBAAiB,CAAC,YAAY,KAAK,GAAG,GAE/C,MAAM,GAAG,cAAc,KAAK;CAG9B,OAAO,IAAI,IAAI,GAAG;AACpB;;;;AAKA,SAAgB,YACd,KACA,UAA2B,CAAC,GACX;CACjB,IAAI;EACF,OAAO,SAAS,KAAK,OAAO;CAC9B,QAAQ;EACN;CACF;AACF;;;;;;;AAQA,SAAgB,qBAAqB,KAAkB;CAErD,IADgB,YAAY,KAAK,EAAE,eAAe,OAAO,CAC/C,GAAG,KAAK,SAAS,gBAAgB,GACzC,OAAO,SAAS,KAAK,EAAE,eAAe,QAAQ,CAAC;MAE/C,OAAO,SAAS,KAAK,EAAE,eAAe,OAAO,CAAC;AAElD;;AAIA,SAAgB,aAAa,MAAoB;CAC/C,IAAI;EACF,OAAO,KAAK,MAAM,IAAc;CAClC,QAAQ;EACN;CACF;AACF;;AAGA,SAAgB,iBAAiB,MAAmC;CAClE,IAAI;EACF,OAAO,KAAK,UAAU,IAAI;CAC5B,QAAQ;EACN;CACF;AACF;;;;;;AAOA,SAAgB,mBAAmB,KAAqC;CACtE,MAAM,MAAM,IAAI,gBAAgB,GAAG,EAAE,SAAS;CAC9C,OAAO,MAAM,IAAI,QAAQ;AAC3B;;AAGA,SAAgB,iBAAiB,SAAyB;CACxD,OAAO,WAAW,MAAM,KAAK;AAC/B;;AAGA,SAAgB,iBAAiB,SAAyB;CACxD,OAAO,WAAW,KAAK,KAAK;AAC9B;;;;;AAMA,SAAgB,uBACd,kBACA,mBACA;CACA,IAAI,CAAC,kBAAkB,mBAAmB;CAC1C,IAAI,CAAC,mBAAmB,oBAAoB;CAE5C,OAAO,qBAAqB;AAC9B;;;;AAKA,MAAa,gBAAgB;CAAE,GAAG;CAAG,GAAG;CAAG,GAAG;AAAE"}

package/dist/experimental/nats/index.cjs

@@ -1,18 +1,59 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_converters = require("../../converters-EYS27XJE.cjs");
 let _nats_io_nats_core = require("@nats-io/nats-core");
+//#region src/lib/experimental/nats/buildNatsServerUrl.ts
+/**
+* Builds the WebSocket URL for a NOVA instance's NATS gateway from its
+* instance URL, e.g. `https://foo.instance.wandelbots.io` becomes
+* `wss://foo.instance.wandelbots.io/api/nats`.
+*
+* Pass the result as `servers` in the `NovaNatsClientConfig` passed to
+* `NovaNatsClient`.
+*/
+function buildNatsServerUrl(instanceUrl) {
+	const url = require_converters.parseNovaInstanceUrl(instanceUrl);
+	return `${url.protocol === "https:" ? "wss:" : "ws:"}//${url.host}/api/nats`;
+}
+//#endregion
 //#region src/lib/experimental/nats/buildSubject.ts
 /**
 * Builds a NATS subject from an AsyncAPI-style channel address template
 * (e.g. `"{instance}.v2.cells.{cell}"`) by substituting each `{param}`
 * placeholder with the corresponding value from `params`.
 */
+function isValidSubjectChar(char) {
+	const code = char.charCodeAt(0);
+	return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122 || char === "-" || char === "_";
+}
+function isValidSubjectValue(value) {
+	if (value === "*") return true;
+	if (value.length === 0) return false;
+	for (const char of value) if (!isValidSubjectChar(char)) return false;
+	return true;
+}
 function buildSubject(template, params) {
-	return template.replace(/\{([^}]+)\}/g, (match, paramName) => {
+	let result = "";
+	let cursor = 0;
+	while (cursor < template.length) {
+		const openIndex = template.indexOf("{", cursor);
+		if (openIndex === -1) {
+			result += template.slice(cursor);
+			break;
+		}
+		const closeIndex = template.indexOf("}", openIndex + 1);
+		if (closeIndex === -1) {
+			result += template.slice(cursor);
+			break;
+		}
+		result += template.slice(cursor, openIndex);
+		const paramName = template.slice(openIndex + 1, closeIndex);
 		const value = params[paramName];
 		if (value === void 0) throw new Error(`Missing value for subject parameter "${paramName}" in template "${template}"`);
-		if (value === "" || /[\s.>*]/.test(value)) throw new Error(`Invalid value for subject parameter "${paramName}": "${value}" (must be non-empty and must not contain whitespace or the NATS special characters ".", ">", "*")`);
-		return value;
-	});
+		if (!isValidSubjectValue(value)) throw new Error(`Invalid value for subject parameter "${paramName}": "${value}" (must be non-empty and contain only letters, digits, "-", and "_")`);
+		result += value;
+		cursor = closeIndex + 1;
+	}
+	return result;
 }
 //#endregion
 //#region src/lib/experimental/nats/NovaNatsClient.ts
@@ -24,19 +65,34 @@ function buildSubject(template, params) {
 */
 var NovaNatsClient = class {
 	config;
-	connection = null;
-	constructor(config) {
-		this.config = config;
+	connectionPromise = null;
+	constructor(nova, config = {}) {
+		this.config = {
+			servers: buildNatsServerUrl(nova.instanceUrl.href),
+			...nova.accessToken ? { token: nova.accessToken } : {},
+			...config
+		};
 	}
-	/** Connects to NATS if not already connected, and returns the connection. */
-	async connect() {
-		if (!this.connection) this.connection = await (0, _nats_io_nats_core.wsconnect)(this.config);
-		return this.connection;
+	/**
+	* Connects to NATS if not already connected or connecting, and returns the
+	* connection. Safe to call concurrently: all callers share the same
+	* in-flight connection attempt instead of each starting their own.
+	*/
+	connect() {
+		if (!this.connectionPromise) this.connectionPromise = (0, _nats_io_nats_core.wsconnect)(this.config).catch((err) => {
+			this.connectionPromise = null;
+			throw err;
+		});
+		return this.connectionPromise;
 	}
-	/** Closes the underlying NATS connection, if open. */
+	/** Closes the underlying NATS connection, if open or connecting. */
 	async close() {
-		await this.connection?.close();
-		this.connection = null;
+		const connectionPromise = this.connectionPromise;
+		this.connectionPromise = null;
+		if (!connectionPromise) return;
+		try {
+			await (await connectionPromise).close();
+		} catch {}
 	}
 	/**
 	* Subscribes to a NATS subject published by the server, invoking `handler`
@@ -46,16 +102,25 @@ var NovaNatsClient = class {
 	* `"nova.v2.cells.{cell}"`, with `{param}` placeholders filled in from
 	* `params`.
 	*
+	* Errors decoding a message or thrown/rejected by `handler` are caught and
+	* logged per-message, so one bad message doesn't stop later messages on
+	* the same subscription from being handled.
+	*
 	* Returns a function that unsubscribes when called.
 	*/
-	async subscribe(subject, params, handler) {
+	async subscribe(subject, ...args) {
+		const [params, handler] = args.length === 1 ? [{}, args[0]] : [args[0], args[1]];
 		const nc = await this.connect();
 		const resolvedSubject = buildSubject(subject, params);
 		const sub = nc.subscribe(resolvedSubject);
 		(async () => {
-			for await (const msg of sub) handler(msg.json(), msg);
+			for await (const msg of sub) try {
+				await handler(msg.json(), msg);
+			} catch (err) {
+				console.error(`Error handling NATS message on subject "${resolvedSubject}"`, err);
+			}
 		})().catch((err) => {
-			console.error(`Error handling NATS subscription for "${resolvedSubject}"`, err);
+			console.error(`NATS subscription iterator failed for "${resolvedSubject}"`, err);
 		});
 		return () => sub.unsubscribe();
 	}
@@ -72,8 +137,22 @@ var NovaNatsClient = class {
 		const resolvedSubject = buildSubject(subject, params);
 		return (await nc.request(resolvedSubject, JSON.stringify(payload), { timeout: opts.timeout ?? 5e3 })).json();
 	}
+	/**
+	* Publishes a JSON payload to any NATS subject defined in the spec,
+	* without waiting for a reply.
+	*
+	* `subject` is the subject template as it appears on the wire, e.g.
+	* `"nova.v2.cells.{cell}.bus-ios.ios.set"`, with `{param}` placeholders
+	* filled in from `params`.
+	*/
+	async publish(subject, params, payload) {
+		const nc = await this.connect();
+		const resolvedSubject = buildSubject(subject, params);
+		nc.publish(resolvedSubject, JSON.stringify(payload));
+	}
 };
 //#endregion
 exports.NovaNatsClient = NovaNatsClient;
+exports.buildNatsServerUrl = buildNatsServerUrl;
 
 //# sourceMappingURL=index.cjs.map

package/dist/experimental/nats/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/lib/experimental/nats/buildSubject.ts","../../../src/lib/experimental/nats/NovaNatsClient.ts"],"sourcesContent":["/**\n * Builds a NATS subject from an AsyncAPI-style channel address template\n * (e.g. `\"{instance}.v2.cells.{cell}\"`) by substituting each `{param}`\n * placeholder with the corresponding value from `params`.\n */\nexport function buildSubject(\n  template: string,\n  params: Record<string, string>,\n): string {\n  return template.replace(/\\{([^}]+)\\}/g, (match, paramName: string) => {\n    const value = params[paramName]\n    if (value === undefined) {\n      throw new Error(\n        `Missing value for subject parameter \"${paramName}\" in template \"${template}\"`,\n      )\n    }\n    if (value === \"\" || /[\\s.>*]/.test(value)) {\n      throw new Error(\n        `Invalid value for subject parameter \"${paramName}\": \"${value}\" (must be non-empty and must not contain whitespace or the NATS special characters \".\", \">\", \"*\")`,\n      )\n    }\n    return value\n  })\n}\n","import {\n  type ConnectionOptions,\n  type Msg,\n  type NatsConnection,\n  wsconnect,\n} from \"@nats-io/nats-core\"\nimport { buildSubject } from \"./buildSubject.ts\"\nimport type {\n  NatsOperationParams,\n  NatsReplyPayloads,\n  NatsRequestPayloads,\n  NatsRequestSubject,\n  NatsSubscribePayloads,\n  NatsSubscribeSubject,\n} from \"./generated/operations.ts\"\n\nexport type NovaNatsClientConfig = ConnectionOptions\n\n/**\n * Typed NATS client for the Wandelbots NOVA messaging API, generated from\n * src/asyncapi.yaml (see scripts/generate-nats-client.ts).\n *\n * Connects over WebSocket via `@nats-io/nats-core`'s `wsconnect`.\n */\nexport class NovaNatsClient {\n  readonly config: NovaNatsClientConfig\n  connection: NatsConnection | null = null\n\n  constructor(config: NovaNatsClientConfig) {\n    this.config = config\n  }\n\n  /** Connects to NATS if not already connected, and returns the connection. */\n  async connect(): Promise<NatsConnection> {\n    if (!this.connection) {\n      this.connection = await wsconnect(this.config)\n    }\n    return this.connection\n  }\n\n  /** Closes the underlying NATS connection, if open. */\n  async close(): Promise<void> {\n    await this.connection?.close()\n    this.connection = null\n  }\n\n  /**\n   * Subscribes to a NATS subject published by the server, invoking `handler`\n   * with the JSON-decoded payload of every message received.\n   *\n   * `subject` is the subject template as it appears on the wire, e.g.\n   * `\"nova.v2.cells.{cell}\"`, with `{param}` placeholders filled in from\n   * `params`.\n   *\n   * Returns a function that unsubscribes when called.\n   */\n  async subscribe<K extends NatsSubscribeSubject>(\n    subject: K,\n    params: NatsOperationParams[K],\n    handler: (payload: NatsSubscribePayloads[K], msg: Msg) => void,\n  ): Promise<() => void> {\n    const nc = await this.connect()\n    const resolvedSubject = buildSubject(subject, params)\n    const sub = nc.subscribe(resolvedSubject)\n\n    ;(async () => {\n      for await (const msg of sub) {\n        handler(msg.json<NatsSubscribePayloads[K]>(), msg)\n      }\n    })().catch((err: unknown) => {\n      console.error(\n        `Error handling NATS subscription for \"${resolvedSubject}\"`,\n        err,\n      )\n    })\n\n    return () => sub.unsubscribe()\n  }\n\n  /**\n   * Sends a request payload for a NATS subject the server receives, and\n   * waits for the JSON-decoded reply.\n   *\n   * `subject` is the subject template as it appears on the wire, e.g.\n   * `\"nova.v2.cells.{cell}.bus-ios.ios.set\"`, with `{param}` placeholders\n   * filled in from `params`.\n   */\n  async request<K extends NatsRequestSubject>(\n    subject: K,\n    params: NatsOperationParams[K],\n    payload: NatsRequestPayloads[K],\n    opts: { timeout?: number } = {},\n  ): Promise<NatsReplyPayloads[K]> {\n    const nc = await this.connect()\n    const resolvedSubject = buildSubject(subject, params)\n    const msg = await nc.request(resolvedSubject, JSON.stringify(payload), {\n      timeout: opts.timeout ?? 5000,\n    })\n    return msg.json<NatsReplyPayloads[K]>()\n  }\n}\n"],"mappings":";;;;;;;;AAKA,SAAgB,aACd,UACA,QACQ;CACR,OAAO,SAAS,QAAQ,iBAAiB,OAAO,cAAsB;EACpE,MAAM,QAAQ,OAAO;EACrB,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MACR,wCAAwC,UAAU,iBAAiB,SAAS,EAC9E;EAEF,IAAI,UAAU,MAAM,UAAU,KAAK,KAAK,GACtC,MAAM,IAAI,MACR,wCAAwC,UAAU,MAAM,MAAM,mGAChE;EAEF,OAAO;CACT,CAAC;AACH;;;;;;;;;ACCA,IAAa,iBAAb,MAA4B;CAC1B;CACA,aAAoC;CAEpC,YAAY,QAA8B;EACxC,KAAK,SAAS;CAChB;;CAGA,MAAM,UAAmC;EACvC,IAAI,CAAC,KAAK,YACR,KAAK,aAAa,OAAA,GAAA,mBAAA,WAAgB,KAAK,MAAM;EAE/C,OAAO,KAAK;CACd;;CAGA,MAAM,QAAuB;EAC3B,MAAM,KAAK,YAAY,MAAM;EAC7B,KAAK,aAAa;CACpB;;;;;;;;;;;CAYA,MAAM,UACJ,SACA,QACA,SACqB;EACrB,MAAM,KAAK,MAAM,KAAK,QAAQ;EAC9B,MAAM,kBAAkB,aAAa,SAAS,MAAM;EACpD,MAAM,MAAM,GAAG,UAAU,eAAe;EAEvC,CAAC,YAAY;GACZ,WAAW,MAAM,OAAO,KACtB,QAAQ,IAAI,KAA+B,GAAG,GAAG;EAErD,GAAG,EAAE,OAAO,QAAiB;GAC3B,QAAQ,MACN,yCAAyC,gBAAgB,IACzD,GACF;EACF,CAAC;EAED,aAAa,IAAI,YAAY;CAC/B;;;;;;;;;CAUA,MAAM,QACJ,SACA,QACA,SACA,OAA6B,CAAC,GACC;EAC/B,MAAM,KAAK,MAAM,KAAK,QAAQ;EAC9B,MAAM,kBAAkB,aAAa,SAAS,MAAM;EAIpD,QAAO,MAHW,GAAG,QAAQ,iBAAiB,KAAK,UAAU,OAAO,GAAG,EACrE,SAAS,KAAK,WAAW,IAC3B,CAAC,GACU,KAA2B;CACxC;AACF"}
+{"version":3,"file":"index.cjs","names":["parseNovaInstanceUrl"],"sources":["../../../src/lib/experimental/nats/buildNatsServerUrl.ts","../../../src/lib/experimental/nats/buildSubject.ts","../../../src/lib/experimental/nats/NovaNatsClient.ts"],"sourcesContent":["import { parseNovaInstanceUrl } from \"../../converters.ts\"\n\n/**\n * Builds the WebSocket URL for a NOVA instance's NATS gateway from its\n * instance URL, e.g. `https://foo.instance.wandelbots.io` becomes\n * `wss://foo.instance.wandelbots.io/api/nats`.\n *\n * Pass the result as `servers` in the `NovaNatsClientConfig` passed to\n * `NovaNatsClient`.\n */\nexport function buildNatsServerUrl(instanceUrl: string): string {\n  const url = parseNovaInstanceUrl(instanceUrl)\n  const protocol = url.protocol === \"https:\" ? \"wss:\" : \"ws:\"\n  return `${protocol}//${url.host}/api/nats`\n}\n","/**\n * Builds a NATS subject from an AsyncAPI-style channel address template\n * (e.g. `\"{instance}.v2.cells.{cell}\"`) by substituting each `{param}`\n * placeholder with the corresponding value from `params`.\n */\n\nfunction isValidSubjectChar(char: string): boolean {\n  const code = char.charCodeAt(0)\n  return (\n    (code >= 48 && code <= 57) || // 0-9\n    (code >= 65 && code <= 90) || // A-Z\n    (code >= 97 && code <= 122) || // a-z\n    char === \"-\" ||\n    char === \"_\"\n  )\n}\n\nfunction isValidSubjectValue(value: string): boolean {\n  // A bare \"*\" is the NATS single-token wildcard, allowed on its own (e.g.\n  // subscribing to all cells with `{ cell: \"*\" }\") but not as part of a\n  // larger value, since it wouldn't act as a wildcard there anyway.\n  if (value === \"*\") return true\n  if (value.length === 0) return false\n  for (const char of value) {\n    if (!isValidSubjectChar(char)) return false\n  }\n  return true\n}\n\nexport function buildSubject(\n  template: string,\n  params: Record<string, string>,\n): string {\n  // Scanned manually (rather than with a regex like /\\{([^}]+)\\}/g) to avoid\n  // a polynomial-time backtracking blowup on pathological input, e.g. a\n  // template consisting of many \"{\" characters with no closing \"}\".\n  let result = \"\"\n  let cursor = 0\n\n  while (cursor < template.length) {\n    const openIndex = template.indexOf(\"{\", cursor)\n    if (openIndex === -1) {\n      result += template.slice(cursor)\n      break\n    }\n\n    const closeIndex = template.indexOf(\"}\", openIndex + 1)\n    if (closeIndex === -1) {\n      result += template.slice(cursor)\n      break\n    }\n\n    result += template.slice(cursor, openIndex)\n    const paramName = template.slice(openIndex + 1, closeIndex)\n    const value = params[paramName]\n    if (value === undefined) {\n      throw new Error(\n        `Missing value for subject parameter \"${paramName}\" in template \"${template}\"`,\n      )\n    }\n    if (!isValidSubjectValue(value)) {\n      throw new Error(\n        `Invalid value for subject parameter \"${paramName}\": \"${value}\" (must be non-empty and contain only letters, digits, \"-\", and \"_\")`,\n      )\n    }\n    result += value\n\n    cursor = closeIndex + 1\n  }\n\n  return result\n}\n","import {\n  type ConnectionOptions,\n  type Msg,\n  type NatsConnection,\n  wsconnect,\n} from \"@nats-io/nats-core\"\nimport type { Nova } from \"../../Nova.ts\"\nimport { buildNatsServerUrl } from \"./buildNatsServerUrl.ts\"\nimport { buildSubject } from \"./buildSubject.ts\"\nimport type {\n  NatsOperationParams,\n  NatsPublishPayloads,\n  NatsPublishSubject,\n  NatsReplyPayloads,\n  NatsRequestPayloads,\n  NatsRequestSubject,\n  NatsSubscribePayloads,\n  NatsSubscribeSubject,\n} from \"./generated/operations.ts\"\n\nexport type NovaNatsClientConfig = ConnectionOptions\n\ntype NatsMessageHandler<K extends NatsSubscribeSubject> = (\n  payload: NatsSubscribePayloads[K],\n  msg: Msg,\n) => void | Promise<void>\n\ntype SubscribeArgs<K extends NatsSubscribeSubject> =\n  keyof NatsOperationParams[K] extends never\n    ? [handler: NatsMessageHandler<K>]\n    : [params: NatsOperationParams[K], handler: NatsMessageHandler<K>]\n\n/**\n * Typed NATS client for the Wandelbots NOVA messaging API, generated from\n * src/asyncapi.yaml (see scripts/generate-nats-client.ts).\n *\n * Connects over WebSocket via `@nats-io/nats-core`'s `wsconnect`.\n */\nexport class NovaNatsClient {\n  readonly config: NovaNatsClientConfig\n  private connectionPromise: Promise<NatsConnection> | null = null\n\n  constructor(nova: Nova, config: NovaNatsClientConfig = {}) {\n    this.config = {\n      servers: buildNatsServerUrl(nova.instanceUrl.href),\n      // Reuse the Nova instance's access token for NATS auth, if it has one\n      // (e.g. from login or a passed-in config.accessToken). Explicit auth\n      // options in `config` (token/user/pass/authenticator) still win.\n      ...(nova.accessToken ? { token: nova.accessToken } : {}),\n      ...config,\n    }\n  }\n\n  /**\n   * Connects to NATS if not already connected or connecting, and returns the\n   * connection. Safe to call concurrently: all callers share the same\n   * in-flight connection attempt instead of each starting their own.\n   */\n  connect(): Promise<NatsConnection> {\n    if (!this.connectionPromise) {\n      this.connectionPromise = wsconnect(this.config).catch((err: unknown) => {\n        // Allow a subsequent connect() call to retry after a failed attempt.\n        this.connectionPromise = null\n        throw err\n      })\n    }\n    return this.connectionPromise\n  }\n\n  /** Closes the underlying NATS connection, if open or connecting. */\n  async close(): Promise<void> {\n    const connectionPromise = this.connectionPromise\n    this.connectionPromise = null\n    if (!connectionPromise) return\n    try {\n      const nc = await connectionPromise\n      await nc.close()\n    } catch {\n      // Connection never succeeded; nothing to close.\n    }\n  }\n\n  /**\n   * Subscribes to a NATS subject published by the server, invoking `handler`\n   * with the JSON-decoded payload of every message received.\n   *\n   * `subject` is the subject template as it appears on the wire, e.g.\n   * `\"nova.v2.cells.{cell}\"`, with `{param}` placeholders filled in from\n   * `params`.\n   *\n   * Errors decoding a message or thrown/rejected by `handler` are caught and\n   * logged per-message, so one bad message doesn't stop later messages on\n   * the same subscription from being handled.\n   *\n   * Returns a function that unsubscribes when called.\n   */\n  async subscribe<K extends NatsSubscribeSubject>(\n    subject: K,\n    ...args: SubscribeArgs<K>\n  ): Promise<() => void> {\n    const [params, handler] =\n      args.length === 1\n        ? ([{}, args[0]] as const)\n        : ([args[0], args[1]] as const)\n\n    const nc = await this.connect()\n    const resolvedSubject = buildSubject(subject, params)\n    const sub = nc.subscribe(resolvedSubject)\n\n    ;(async () => {\n      for await (const msg of sub) {\n        // Handled per-message: a bad payload or a throwing/rejecting handler\n        // should not stop the subscription from processing later messages.\n        try {\n          await handler(msg.json<NatsSubscribePayloads[K]>(), msg)\n        } catch (err) {\n          console.error(\n            `Error handling NATS message on subject \"${resolvedSubject}\"`,\n            err,\n          )\n        }\n      }\n    })().catch((err: unknown) => {\n      console.error(\n        `NATS subscription iterator failed for \"${resolvedSubject}\"`,\n        err,\n      )\n    })\n\n    return () => sub.unsubscribe()\n  }\n\n  /**\n   * Sends a request payload for a NATS subject the server receives, and\n   * waits for the JSON-decoded reply.\n   *\n   * `subject` is the subject template as it appears on the wire, e.g.\n   * `\"nova.v2.cells.{cell}.bus-ios.ios.set\"`, with `{param}` placeholders\n   * filled in from `params`.\n   */\n  async request<K extends NatsRequestSubject>(\n    subject: K,\n    params: NatsOperationParams[K],\n    payload: NatsRequestPayloads[K],\n    opts: { timeout?: number } = {},\n  ): Promise<NatsReplyPayloads[K]> {\n    const nc = await this.connect()\n    const resolvedSubject = buildSubject(subject, params)\n    const msg = await nc.request(resolvedSubject, JSON.stringify(payload), {\n      timeout: opts.timeout ?? 5000,\n    })\n    return msg.json<NatsReplyPayloads[K]>()\n  }\n\n  /**\n   * Publishes a JSON payload to any NATS subject defined in the spec,\n   * without waiting for a reply.\n   *\n   * `subject` is the subject template as it appears on the wire, e.g.\n   * `\"nova.v2.cells.{cell}.bus-ios.ios.set\"`, with `{param}` placeholders\n   * filled in from `params`.\n   */\n  async publish<K extends NatsPublishSubject>(\n    subject: K,\n    params: NatsOperationParams[K],\n    payload: NatsPublishPayloads[K],\n  ): Promise<void> {\n    const nc = await this.connect()\n    const resolvedSubject = buildSubject(subject, params)\n    nc.publish(resolvedSubject, JSON.stringify(payload))\n  }\n}\n"],"mappings":"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"}