@naturali/sdk 0.78.6 → 0.80.0

package/dist/index.cjs

@@ -2462,6 +2462,126 @@ var Files = class {
 		});
 	}
 };
+var Formations = class {
+	/**
+	* Validate a formation template
+	*
+	* Validates a formation template without creating any resources. Returns a list of errors and warnings. Accepts the template as a JSON object or as a YAML/JSON string.
+	*
+	*/
+	static validateFormation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/formations/validate",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Plan a formation deployment
+	*
+	* Computes a diff between the desired template and the current stack state without making any changes. Returns the list of planned actions.
+	*
+	*/
+	static planFormation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/formations/plan",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List formations
+	*
+	* Returns all formation stacks for a project
+	*/
+	static listFormations(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/formations",
+			...options
+		});
+	}
+	/**
+	* Create a new formation
+	*
+	* Validates the template, creates the formation record, then provisions all declared resources in dependency order.
+	*
+	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `201` and `status: "failed"`, and `error` explains why (the resources created before the failure are rolled back). Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `create-formation && …` does not lie.
+	*
+	*/
+	static createFormation(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/formations",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete an formation
+	*
+	* Deletes the formation stack and all its managed resources in reverse dependency order.
+	*
+	* A resource the platform refuses to delete on its own — most often an agent that has generation or trace history — fails the teardown with `409 FORMATION_DELETE_FAILED`, naming every blocking resource in `error.meta.failures`. Resolve the blockers (for an agent, `DELETE /v1/projects/{project_id}/agents/{agent_id}?force=true` also removes its generations and traces, and `deletion_policy: retain` exempts it from teardown entirely) and delete the formation again.
+	*
+	* A refusal the platform can foresee is found by a pre-flight, before the first delete: nothing is removed, and the formation stays `active` and intact for the retry. An unforeseeable error surfaces mid-teardown instead, where resources deleted before the blocker stay deleted and the formation is left in `delete_failed`. The error message states which happened.
+	*
+	*/
+	static deleteFormation(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/formations/{formation_id}",
+			...options
+		});
+	}
+	/**
+	* Get a specific formation
+	*
+	* Returns the formation stack including its current resources.
+	*/
+	static getFormation(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/formations/{formation_id}",
+			...options
+		});
+	}
+	/**
+	* Update an formation
+	*
+	* Applies a new template to the formation. Resources are created, updated, or deleted to reconcile the current state with the desired state.
+	*
+	* A **template-shape** error is refused with `400`. A **deploy** failure is not: the operation ran, so the formation is returned with `200` and `status: "failed"`, and `error` explains why. Read `status` — a `2xx` here means the deploy was attempted, not that it worked. The `builtin` CLI exits non-zero on that body so `update-formation && …` does not lie.
+	*
+	*/
+	static updateFormation(options) {
+		return (options.client ?? client).put({
+			url: "/v1/projects/{project_id}/formations/{formation_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List formation operation events
+	*
+	* Returns all operations (create, update, delete) with their event logs for the formation, ordered chronologically.
+	*
+	*/
+	static listFormationEvents(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/formations/{formation_id}/events",
+			...options
+		});
+	}
+};
 var Generations = class {
 	/**
 	* List generations
@@ -3122,7 +3242,9 @@ var Orchestrations = class {
 	/**
 	* List orchestration runs
 	*
-	* Returns orchestration runs the caller can access, optionally filtered by orchestration.
+	* Returns orchestration runs the caller can access, optionally filtered by orchestration, by parent run, or by whether the run has a parent at all.
+	*
+	* Note when aggregating: a run's `usage` covers its whole subtree, so summing it over a list that contains both a parent and its children counts the children more than once. Pass `nested=false` to sum over runs a caller started.
 	*/
 	static listOrchestrationRuns(options) {
 		return (options.client ?? client).get({
@@ -3772,7 +3894,7 @@ var Tools = class {
 	*
 	* Directly invokes a tool and returns its output. Supported for `http`, `mcp`, and `pipeline` tools. `client` tools cannot be invoked server-side and will return 422. A `pipeline` tool runs its declared steps in order and returns the mapped `output` (or the last step's output); `action` is ignored and `input` is the pipeline input.
 	* For `mcp` tools the `action` field is required and identifies which tool name to invoke. For `http` tools `action` is ignored. When an `mcp` tool declares an `actions` allowlist, an action outside it is rejected with `400 VALIDATION_FAILED` ("not available on this tool") before any outbound request is made.
-	* `preset_parameters` stored on the tool are merged with the caller-supplied `input` before execution; preset keys take lower precedence.
+	* `preset_parameters` stored on the tool are pinned over the caller-supplied `input` before execution: a key the tool presets keeps its preset value even when `input` sets it. Keys the presets do not name are taken from `input` as sent.
 	*
 	*/
 	static callTool(options) {
@@ -4282,6 +4404,7 @@ var NaturaliClient = class {
 	evaluations;
 	exceptions;
 	files;
+	formations;
 	generations;
 	guardrails;
 	ingestionRules;
@@ -4329,6 +4452,7 @@ var NaturaliClient = class {
 		this.evaluations = bindResource(Evaluations, this.http);
 		this.exceptions = bindResource(Exceptions, this.http);
 		this.files = bindResource(Files, this.http);
+		this.formations = bindResource(Formations, this.http);
 		this.generations = bindResource(Generations, this.http);
 		this.guardrails = bindResource(Guardrails, this.http);
 		this.ingestionRules = bindResource(IngestionRules, this.http);
@@ -4369,6 +4493,7 @@ exports.Embeddings = Embeddings;
 exports.Evaluations = Evaluations;
 exports.Exceptions = Exceptions;
 exports.Files = Files;
+exports.Formations = Formations;
 exports.Generations = Generations;
 exports.Guardrails = Guardrails;
 exports.IngestionRules = IngestionRules;