@fractal_cloud/sdk 1.1.0 → 1.2.0

package/dist/index.mjs

@@ -1143,28 +1143,61 @@ let BlueprintComponent;
 const CLIENT_ID_HEADER$1 = "X-ClientID";
 const CLIENT_SECRET_HEADER$1 = "X-ClientSecret";
 const FRACTAL_API_URL$1 = "https://api.fractal.cloud";
+/**
+* Converts a raw superagent error into a descriptive Error with context.
+* Includes the operation name, target ID, HTTP status (if any), and response
+* body (if any) so the caller always knows what went wrong and where.
+*/
+const toApiError$1 = (operation, target, err) => {
+	const e = err;
+	const status = e.status ? `HTTP ${e.status}` : "network error";
+	const body = e.response?.text?.trim();
+	const detail = body ? ` — ${body}` : "";
+	return /* @__PURE__ */ new Error(`${operation} failed (${status}) for ${target}${detail}`);
+};
+const authHeaders$1 = (credentials) => ({
+	[CLIENT_ID_HEADER$1]: credentials.id.serviceAccountIdValue,
+	[CLIENT_SECRET_HEADER$1]: credentials.secret
+});
 const deployFractal = async (credentials, fractal) => {
-	const fractalUrl = `${FRACTAL_API_URL$1}/blueprints/${fractal.id.toString().replace(":", "/")}`;
-	((await superagent.get(fractalUrl).ok((res) => res.status === 200 || res.status === 404).set(CLIENT_ID_HEADER$1, credentials.id.serviceAccountIdValue).set(CLIENT_SECRET_HEADER$1, credentials.secret).send()).status === 200 ? superagent.put(fractalUrl) : superagent.post(fractalUrl)).set(CLIENT_ID_HEADER$1, credentials.id.serviceAccountIdValue).set(CLIENT_SECRET_HEADER$1, credentials.secret).send({
-		description: fractal.description,
-		isPrivate: fractal.isPrivate,
-		components: fractal.components.map((c) => ({
-			...c,
-			type: c.type.toString(),
-			id: c.id.value.toString(),
-			version: c.version.toString(),
-			parameters: c.parameters.toMap(),
-			dependencies: c.dependencies.map((d) => d.id.value.toString()),
-			links: c.links.map((l) => ({
-				componentId: l.id.value.toString(),
-				settings: l.parameters.toMap()
-			})),
-			outputFields: Object.keys(c.outputFields.value)
-		}))
-	}).catch((e) => console.error(e.message, e.response.text));
+	const target = fractal.id.toString();
+	const fractalUrl = `${FRACTAL_API_URL$1}/blueprints/${target.replace(":", "/")}`;
+	let getFractalResponse;
+	try {
+		getFractalResponse = await superagent.get(fractalUrl).ok((res) => res.status === 200 || res.status === 404).set(authHeaders$1(credentials)).send();
+	} catch (err) {
+		throw toApiError$1("check fractal existence", target, err);
+	}
+	const request = getFractalResponse.status === 200 ? superagent.put(fractalUrl) : superagent.post(fractalUrl);
+	try {
+		await request.set(authHeaders$1(credentials)).send({
+			description: fractal.description,
+			isPrivate: fractal.isPrivate,
+			components: fractal.components.map((c) => ({
+				...c,
+				type: c.type.toString(),
+				id: c.id.value.toString(),
+				version: c.version.toString(),
+				parameters: c.parameters.toMap(),
+				dependencies: c.dependencies.map((d) => d.id.value.toString()),
+				links: c.links.map((l) => ({
+					componentId: l.id.value.toString(),
+					settings: l.parameters.toMap()
+				})),
+				outputFields: Object.keys(c.outputFields.value)
+			}))
+		});
+	} catch (err) {
+		throw toApiError$1(getFractalResponse.status === 200 ? "update fractal" : "create fractal", target, err);
+	}
 };
 const destroyFractal = async (credentials, id) => {
-	await superagent.delete(`${FRACTAL_API_URL$1}/blueprints/${id.toString().replace(":", "/")}`).set(CLIENT_ID_HEADER$1, credentials.id.serviceAccountIdValue).set(CLIENT_SECRET_HEADER$1, credentials.secret);
+	const target = id.toString();
+	try {
+		await superagent.delete(`${FRACTAL_API_URL$1}/blueprints/${target.replace(":", "/")}`).set(authHeaders$1(credentials));
+	} catch (err) {
+		throw toApiError$1("destroy fractal", target, err);
+	}
 };
 let FractalService;
 (function(_FractalService) {
@@ -1806,43 +1839,178 @@ const getLiveSystemComponentBuilder = () => {
 const CLIENT_ID_HEADER = "X-ClientID";
 const CLIENT_SECRET_HEADER = "X-ClientSecret";
 const FRACTAL_API_URL = "https://api.fractal.cloud";
-const deployLiveSystem = async (credentials, liveSystem) => {
-	const body = {
-		liveSystemId: liveSystem.id.toString(),
-		fractalId: liveSystem.fractalId.toString(),
-		description: liveSystem.description,
-		provider: liveSystem.genericProvider,
-		blueprintMap: liveSystem.components.reduce((acc, c) => {
-			acc[c.id.value.toString()] = {
-				...c,
-				type: c.type.toString(),
-				id: c.id.value.toString(),
-				version: c.version.toString(),
-				parameters: c.parameters.toMap(),
-				dependencies: c.dependencies.map((d) => d.id.value.toString()),
-				links: c.links.map((l) => ({
-					componentId: l.id.value.toString(),
-					settings: l.parameters.toMap()
-				})),
-				outputFields: c.outputFields.value
-			};
-			return acc;
-		}, {}),
-		parameters: liveSystem.parameters.toMap(),
-		environment: {
-			id: {
-				type: liveSystem.environment.id.ownerType,
-				ownerId: liveSystem.environment.id.ownerId.toString(),
-				shortName: liveSystem.environment.id.name.toString()
-			},
-			parameters: liveSystem.environment.parameters.toMap()
+const DEFAULT_POLL_INTERVAL_MS = 5e3;
+const DEFAULT_TIMEOUT_MS = 6e5;
+const TERMINAL_FAILURE_STATUSES = ["FailedMutation", "Error"];
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const log = (quiet, level, message, fields) => {
+	if (quiet) return;
+	const ts = (/* @__PURE__ */ new Date()).toISOString();
+	const fieldStr = fields ? "  " + Object.entries(fields).map(([k, v]) => `${k}=${v}`).join(" ") : "";
+	console.log(`[${ts}] ${level.padEnd(5)} ${message}${fieldStr}`);
+};
+const elapsedSec = (startMs) => `${Math.round((Date.now() - startMs) / 1e3)}s`;
+/**
+* Converts a raw superagent error into a descriptive Error with context.
+* Includes the operation name, target ID, HTTP status (if any), and response
+* body (if any) so the caller always knows what went wrong and where.
+*/
+const toApiError = (operation, target, err) => {
+	const e = err;
+	const status = e.status ? `HTTP ${e.status}` : "network error";
+	const body = e.response?.text?.trim();
+	const detail = body ? ` — ${body}` : "";
+	return /* @__PURE__ */ new Error(`${operation} failed (${status}) for ${target}${detail}`);
+};
+/**
+* Returns true for 4xx client errors that will not self-heal on retry
+* (e.g. 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable).
+*/
+const isClientError = (err) => {
+	const status = err.status;
+	return status !== void 0 && status >= 400 && status < 500;
+};
+const authHeaders = (credentials) => ({
+	[CLIENT_ID_HEADER]: credentials.id.serviceAccountIdValue,
+	[CLIENT_SECRET_HEADER]: credentials.secret
+});
+const buildBody = (liveSystem) => ({
+	liveSystemId: liveSystem.id.toString(),
+	fractalId: liveSystem.fractalId.toString(),
+	description: liveSystem.description,
+	provider: liveSystem.genericProvider,
+	blueprintMap: liveSystem.components.reduce((acc, c) => {
+		acc[c.id.value.toString()] = {
+			...c,
+			type: c.type.toString(),
+			id: c.id.value.toString(),
+			version: c.version.toString(),
+			parameters: c.parameters.toMap(),
+			dependencies: c.dependencies.map((d) => d.id.value.toString()),
+			links: c.links.map((l) => ({
+				componentId: l.id.value.toString(),
+				settings: l.parameters.toMap()
+			})),
+			outputFields: c.outputFields.value
+		};
+		return acc;
+	}, {}),
+	parameters: liveSystem.parameters.toMap(),
+	environment: {
+		id: {
+			type: liveSystem.environment.id.ownerType,
+			ownerId: liveSystem.environment.id.ownerId.toString(),
+			shortName: liveSystem.environment.id.name.toString()
+		},
+		parameters: liveSystem.environment.parameters.toMap()
+	}
+});
+const submitDeploy = async (credentials, liveSystem) => {
+	const target = liveSystem.id.toString();
+	const liveSystemUrl = `${FRACTAL_API_URL}/livesystems/${target}`;
+	let getResponse;
+	try {
+		getResponse = await superagent.get(liveSystemUrl).ok((res) => res.status === 200 || res.status === 404).set(authHeaders(credentials)).send();
+	} catch (err) {
+		throw toApiError("check live system existence", target, err);
+	}
+	const request = getResponse.status === 200 ? superagent.put(liveSystemUrl) : superagent.post(`${FRACTAL_API_URL}/livesystems`);
+	try {
+		await request.set(authHeaders(credentials)).send(buildBody(liveSystem));
+	} catch (err) {
+		throw toApiError(getResponse.status === 200 ? "update live system" : "create live system", target, err);
+	}
+};
+const getLiveSystemStatus = async (credentials, id) => {
+	try {
+		return (await superagent.get(`${FRACTAL_API_URL}/livesystems/${id.toString()}`).set(authHeaders(credentials)).send()).body.status;
+	} catch (err) {
+		throw toApiError("get live system status", id.toString(), err);
+	}
+};
+const pollUntilActive = async (credentials, id, options, startMs) => {
+	const quiet = options.quiet ?? false;
+	const interval = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+	const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const deadline = Date.now() + timeout;
+	let round = 0;
+	while (Date.now() < deadline) {
+		await sleep(interval);
+		round++;
+		let status;
+		try {
+			status = await getLiveSystemStatus(credentials, id);
+		} catch (err) {
+			if (isClientError(err)) {
+				const message = err instanceof Error ? err.message : String(err);
+				log(quiet, "ERROR", "Fatal error polling Live System status", {
+					system: id.toString(),
+					round,
+					elapsed: elapsedSec(startMs),
+					error: message
+				});
+				throw err;
+			}
+			const message = err instanceof Error ? err.message : String(err);
+			log(quiet, "WARN", "Transient error polling status, will retry", {
+				system: id.toString(),
+				round,
+				elapsed: elapsedSec(startMs),
+				error: message
+			});
+			continue;
 		}
-	};
-	const liveSystemUrl = `${FRACTAL_API_URL}/livesystems/${liveSystem.id.toString()}`;
-	((await superagent.get(liveSystemUrl).ok((res) => res.status === 200 || res.status === 404).set(CLIENT_ID_HEADER, credentials.id.serviceAccountIdValue).set(CLIENT_SECRET_HEADER, credentials.secret).send()).status === 200 ? superagent.put(liveSystemUrl) : superagent.post(`${FRACTAL_API_URL}/livesystems`)).set(CLIENT_ID_HEADER, credentials.id.serviceAccountIdValue).set(CLIENT_SECRET_HEADER, credentials.secret).send(body).catch((e) => console.error(e.message, e.response.text));
+		if (status === "Active") return;
+		if (TERMINAL_FAILURE_STATUSES.includes(status)) {
+			log(quiet, "ERROR", "Live System deployment failed", {
+				system: id.toString(),
+				status,
+				elapsed: elapsedSec(startMs)
+			});
+			throw new Error(`Live system deployment failed with status: ${status} — check the Fractal Cloud console for component-level errors`);
+		}
+		log(quiet, "CHECK", "Polling Live System status", {
+			system: id.toString(),
+			round,
+			status,
+			elapsed: elapsedSec(startMs)
+		});
+	}
+	log(quiet, "ERROR", "Live System deployment timed out", {
+		system: id.toString(),
+		elapsed: elapsedSec(startMs),
+		timeoutMs: timeout
+	});
+	throw new Error(`Live system deployment timed out after ${timeout}ms. Increase timeoutMs in DeployOptions if provisioning takes longer.`);
+};
+const deployLiveSystem = async (credentials, liveSystem, options = { mode: "fire-and-forget" }) => {
+	if (options.mode === "fire-and-forget") {
+		submitDeploy(credentials, liveSystem).catch((err) => {
+			const message = err instanceof Error ? err.message : String(err);
+			console.error(`[Fractal] live system deploy error: ${message}`);
+		});
+		return;
+	}
+	const quiet = options.quiet ?? false;
+	const startMs = Date.now();
+	log(quiet, "INFO", "Deploying Live System", {
+		system: liveSystem.id.toString(),
+		fractal: liveSystem.fractalId.toString(),
+		provider: liveSystem.genericProvider
+	});
+	await submitDeploy(credentials, liveSystem);
+	await pollUntilActive(credentials, liveSystem.id, options, startMs);
+	log(quiet, "INFO", "Live System Active", {
+		system: liveSystem.id.toString(),
+		elapsed: elapsedSec(startMs)
+	});
 };
 const destroyLiveSystem = async (credentials, id) => {
-	await superagent.delete(`${FRACTAL_API_URL}/livesystems/${id.toString()}`).set(CLIENT_ID_HEADER, credentials.id.serviceAccountIdValue).set(CLIENT_SECRET_HEADER, credentials.secret);
+	try {
+		await superagent.delete(`${FRACTAL_API_URL}/livesystems/${id.toString()}`).set(authHeaders(credentials));
+	} catch (err) {
+		throw toApiError("destroy live system", id.toString(), err);
+	}
 };
 let LiveSystemService;
 (function(_LiveSystemService) {
@@ -1987,7 +2155,7 @@ const getLiveSystemBuilder = () => {
 			if (validationErrors.length > 0) throw new SyntaxError(validationErrors.join("\n"));
 			return {
 				...internalState,
-				deploy: (credentials) => LiveSystemService.deploy(credentials, internalState),
+				deploy: (credentials, options) => LiveSystemService.deploy(credentials, internalState, options),
 				destroy: (credentials) => LiveSystemService.destroy(credentials, internalState.id)
 			};
 		}
@@ -2026,7 +2194,7 @@ function buildVirtualNetworkType() {
 function pushParam$25(params, key, value) {
 	params.push(key, value);
 }
-function makeVirtualNetworkNode(vpc, subnetNodes, sgs) {
+function makeVirtualNetworkComponent(vpc, subnetNodes, sgs) {
 	const vpcDep = { id: vpc.id };
 	const wiredSubnets = subnetNodes.map((n) => ({
 		...n.subnet,
@@ -2051,8 +2219,8 @@ function makeVirtualNetworkNode(vpc, subnetNodes, sgs) {
 			...allVMs,
 			...allEcsSvcs
 		],
-		withSubnets: (newSubnets) => makeVirtualNetworkNode(vpc, newSubnets, sgs),
-		withSecurityGroups: (newSgs) => makeVirtualNetworkNode(vpc, subnetNodes, newSgs)
+		withSubnets: (newSubnets) => makeVirtualNetworkComponent(vpc, newSubnets, sgs),
+		withSecurityGroups: (newSgs) => makeVirtualNetworkComponent(vpc, subnetNodes, newSgs)
 	};
 }
 let VirtualNetwork;
@@ -2128,7 +2296,7 @@ let VirtualNetwork;
 		const b = getBuilder().withId(config.id).withVersion(config.version.major, config.version.minor, config.version.patch).withDisplayName(config.displayName);
 		if (config.cidrBlock) b.withCidrBlock(config.cidrBlock);
 		if (config.description) b.withDescription(config.description);
-		return makeVirtualNetworkNode(b.build().vpc, [], []);
+		return makeVirtualNetworkComponent(b.build().vpc, [], []);
 	};
 })(VirtualNetwork || (VirtualNetwork = {}));
 
@@ -2148,7 +2316,7 @@ function buildSubnetType() {
 function pushParam$24(params, key, value) {
 	params.push(key, value);
 }
-function makeSubnetNode(subnet, vms, workloadNodes) {
+function makeSubnetComponent(subnet, vms, workloadNodes) {
 	const subnetDep = { id: subnet.id };
 	const wiredVMs = vms.map((n) => ({
 		...n.component,
@@ -2167,8 +2335,8 @@ function makeSubnetNode(subnet, vms, workloadNodes) {
 			...wiredVMs,
 			...wiredWorkloads
 		],
-		withVirtualMachines: (newVMs) => makeSubnetNode(subnet, newVMs, workloadNodes),
-		withWorkloads: (newWorkloads) => makeSubnetNode(subnet, vms, newWorkloads)
+		withVirtualMachines: (newVMs) => makeSubnetComponent(subnet, newVMs, workloadNodes),
+		withWorkloads: (newWorkloads) => makeSubnetComponent(subnet, vms, newWorkloads)
 	};
 }
 let Subnet;
@@ -2226,7 +2394,7 @@ let Subnet;
 		const b = getBuilder().withId(config.id).withVersion(config.version.major, config.version.minor, config.version.patch).withDisplayName(config.displayName);
 		if (config.cidrBlock) b.withCidrBlock(config.cidrBlock);
 		if (config.description) b.withDescription(config.description);
-		return makeSubnetNode(b.build().subnet, [], []);
+		return makeSubnetComponent(b.build().subnet, [], []);
 	};
 })(Subnet || (Subnet = {}));
 
@@ -2308,16 +2476,23 @@ function buildLinkParams$1(link) {
 	if (link.protocol) params.push("protocol", link.protocol);
 	return params;
 }
-function makeVirtualMachineNode(component) {
+function makeVirtualMachineComponent(component) {
 	return {
 		component,
 		components: [component],
-		withLinks: (links) => {
+		linkToVirtualMachine: (links) => {
 			const componentLinks = links.map((l) => getLinkBuilder().withId(l.target.component.id).withType(buildVirtualMachineType()).withParameters(buildLinkParams$1(l)).build());
-			return makeVirtualMachineNode({
+			return makeVirtualMachineComponent({
 				...component,
 				links: [...component.links, ...componentLinks]
 			});
+		},
+		linkToSecurityGroup: (sgs) => {
+			const sgLinks = sgs.map((sg) => getLinkBuilder().withId(sg.id).withType(sg.type).withParameters(getParametersInstance()).build());
+			return makeVirtualMachineComponent({
+				...component,
+				links: [...component.links, ...sgLinks]
+			});
 		}
 	};
 }
@@ -2353,7 +2528,7 @@ let VirtualMachine;
 	_VirtualMachine.create = (config) => {
 		const b = getBuilder().withId(config.id).withVersion(config.version.major, config.version.minor, config.version.patch).withDisplayName(config.displayName);
 		if (config.description) b.withDescription(config.description);
-		return makeVirtualMachineNode(b.build());
+		return makeVirtualMachineComponent(b.build());
 	};
 })(VirtualMachine || (VirtualMachine = {}));
 
@@ -2524,7 +2699,7 @@ let AwsSubnet;
 
 //#endregion
 //#region src/live_system/component/network_and_compute/iaas/security_group.ts
-const AWS_SG_TYPE_NAME = "AwsSecurityGroup";
+const AWS_SG_TYPE_NAME = "SecurityGroup";
 function buildId$22(id) {
 	return getComponentIdBuilder().withValue(KebabCaseString$1.getBuilder().withValue(id).build()).build();
 }
@@ -4106,7 +4281,7 @@ function buildVersion$4(major, minor, patch) {
 function buildContainerPlatformType() {
 	return getBlueprintComponentTypeBuilder().withInfrastructureDomain(InfrastructureDomain$1.NetworkAndCompute).withServiceDeliveryModel(ServiceDeliveryModel$1.PaaS).withName(PascalCaseString$1.getBuilder().withValue(CONTAINER_PLATFORM_TYPE_NAME).build()).build();
 }
-function makeContainerPlatformNode(platform, workloadNodes) {
+function makeContainerPlatformComponent(platform, workloadNodes) {
 	const platformDep = { id: platform.id };
 	return {
 		platform,
@@ -4117,7 +4292,7 @@ function makeContainerPlatformNode(platform, workloadNodes) {
 				dependencies: [...w.component.dependencies, platformDep]
 			}
 		})),
-		withWorkloads: (newWorkloads) => makeContainerPlatformNode(platform, newWorkloads)
+		withWorkloads: (newWorkloads) => makeContainerPlatformComponent(platform, newWorkloads)
 	};
 }
 let ContainerPlatform;
@@ -4149,7 +4324,7 @@ let ContainerPlatform;
 	_ContainerPlatform.create = (config) => {
 		const b = getBuilder().withId(config.id).withVersion(config.version.major, config.version.minor, config.version.patch).withDisplayName(config.displayName);
 		if (config.description) b.withDescription(config.description);
-		return makeContainerPlatformNode(b.build(), []);
+		return makeContainerPlatformComponent(b.build(), []);
 	};
 })(ContainerPlatform || (ContainerPlatform = {}));
 
@@ -4181,20 +4356,20 @@ function buildLinkParams(fromPort, toPort, protocol) {
 	if (protocol) p.push("protocol", protocol);
 	return p;
 }
-function makeWorkloadNode(component) {
+function makeWorkloadComponent(component) {
 	return {
 		component,
 		components: [component],
-		withLinks: (links) => {
+		linkToWorkload: (links) => {
 			const portLinks = links.map((l) => getLinkBuilder().withId(l.target.component.id).withType(buildWorkloadType()).withParameters(buildLinkParams(l.fromPort, l.toPort, l.protocol)).build());
-			return makeWorkloadNode({
+			return makeWorkloadComponent({
 				...component,
 				links: [...component.links, ...portLinks]
 			});
 		},
-		withSecurityGroups: (sgs) => {
+		linkToSecurityGroup: (sgs) => {
 			const sgLinks = sgs.map((sg) => getLinkBuilder().withId(sg.id).withType(sg.type).withParameters(getParametersInstance()).build());
-			return makeWorkloadNode({
+			return makeWorkloadComponent({
 				...component,
 				links: [...component.links, ...sgLinks]
 			});
@@ -4259,7 +4434,7 @@ let Workload;
 		if (config.cpu) b.withCpu(config.cpu);
 		if (config.memory) b.withMemory(config.memory);
 		if (config.desiredCount !== void 0) b.withDesiredCount(config.desiredCount);
-		return makeWorkloadNode(b.build());
+		return makeWorkloadComponent(b.build());
 	};
 })(Workload || (Workload = {}));
 
@@ -4492,7 +4667,8 @@ let AwsEcsService;
 	};
 	_AwsEcsService.satisfy = (workload) => {
 		const params = getParametersInstance();
-		const inner = getLiveSystemComponentBuilder().withType(buildAwsEcsServiceType()).withParameters(params).withProvider("AWS").withId(buildId(workload.id.toString())).withVersion(buildVersion(workload.version.major, workload.version.minor, workload.version.patch)).withDisplayName(workload.displayName).withDependencies(workload.dependencies).withLinks(workload.links);
+		const deps = [...workload.dependencies];
+		const inner = getLiveSystemComponentBuilder().withType(buildAwsEcsServiceType()).withParameters(params).withProvider("AWS").withId(buildId(workload.id.toString())).withVersion(buildVersion(workload.version.major, workload.version.minor, workload.version.patch)).withDisplayName(workload.displayName).withDependencies(deps).withLinks(workload.links);
 		if (workload.description) inner.withDescription(workload.description);
 		const desiredCount = workload.parameters.getOptionalFieldByName(DESIRED_COUNT_PARAM);
 		if (desiredCount !== null) pushParam(params, DESIRED_COUNT_PARAM, desiredCount);
@@ -4505,6 +4681,11 @@ let AwsEcsService;
 				pushParam(params, ASSIGN_PUBLIC_IP_PARAM, assign);
 				return satisfiedBuilder;
 			},
+			withTaskDefinition: (taskDef) => {
+				deps.push({ id: taskDef.id });
+				inner.withDependencies(deps);
+				return satisfiedBuilder;
+			},
 			build: () => inner.build()
 		};
 		return satisfiedBuilder;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fractal_cloud/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Typescript Fractal Cloud SDK",
   "license": "GPL-3.0-or-later",
   "author": "Fractal Cloud",