@naturali/sdk 0.194.2 → 0.195.0

package/dist/index.mjs

@@ -4494,6 +4494,361 @@ var Orchestrations = class {
 		});
 	}
 };
+var Playbooks = class {
+	/**
+	* List playbooks
+	*
+	* Returns the playbooks defined in a project, newest first.
+	*/
+	static listPlaybooks(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbooks",
+			...options
+		});
+	}
+	/**
+	* Create a playbook
+	*
+	* Creates a playbook at version 1. The definition is refused with `400 PLAYBOOK_VALIDATION_FAILED` when it holds a duplicate node or input, an input reading a missing node or field, an `execute` node without an executor or another kind with one, transformations on a non-final node, or a cycle; `meta.problems` lists every one. A duplicate `name` in the project is `409 NAME_CONFLICT`.
+	*
+	* The caller becomes the version's author, whom its executors run as, so it must be allowed to start every executor the definition names (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A definition with executors written with a trigger or OAuth token is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`: those carry their boundary in the token, so no run can act as them.
+	*/
+	static createPlaybook(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbooks",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Validate a playbook definition
+	*
+	* Answers what a create or update would be told about a definition, without writing: `valid`, and every graph problem it holds. A definition whose shape cannot be read is `400 VALIDATION_FAILED`, as on a write.
+	*/
+	static validatePlaybook(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbooks/validate",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a playbook
+	*
+	* Deletes a playbook and its version archive. A playbook with cases is refused with `409 PLAYBOOK_HAS_CASES`.
+	*/
+	static deletePlaybook(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}",
+			...options
+		});
+	}
+	/**
+	* Get a playbook
+	*
+	* Returns a playbook with its current definition and version.
+	*/
+	static getPlaybook(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}",
+			...options
+		});
+	}
+	/**
+	* Update a playbook
+	*
+	* Updates any of `name`, `description` and `definition`. Only a change to `definition` archives a new version; a rename or a rewrite of the definition the playbook already holds leaves `version` where it is. A case keeps the version it was created on.
+	*
+	* A new version is authored by the caller, checked as on create: `403 PLAYBOOK_EXECUTOR_FORBIDDEN` for an executor it may not start, `409 PLAYBOOK_AUTHOR_UNAVAILABLE` for a trigger or OAuth token.
+	*/
+	static updatePlaybook(options) {
+		return (options.client ?? client).patch({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List a playbook's versions
+	*
+	* Returns the playbook's archived definitions, newest first. A version is written on create and on every write that changes `definition`.
+	*/
+	static listPlaybookVersions(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}/versions",
+			...options
+		});
+	}
+	/**
+	* Fetch an archived playbook version
+	*
+	* Returns the definition a version held: what a case pinned to it is evaluated against.
+	*/
+	static getPlaybookVersion(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}/versions/{version}",
+			...options
+		});
+	}
+	/**
+	* Restore an archived playbook version
+	*
+	* Writes an archived definition back as the playbook's live one, which archives it again as a new version rather than rewinding the counter. Restoring the definition the playbook already holds is a no-op. The caller authors the new version, checked as on create.
+	*/
+	static restorePlaybookVersion(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}/versions/{version}/restore",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Create a case
+	*
+	* Creates a case for one subject on the playbook's current version. The case stays on that version however the playbook changes later.
+	*/
+	static createPlaybookCase(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbooks/{playbook_id}/cases",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List playbook cases
+	*
+	* Returns a project's cases, newest first, without node states; read one case for those.
+	*/
+	static listPlaybookCases(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases",
+			...options
+		});
+	}
+	/**
+	* Delete a case
+	*
+	* Deletes a case and every entry written to it.
+	*/
+	static deletePlaybookCase(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}",
+			...options
+		});
+	}
+	/**
+	* Get a case
+	*
+	* Returns a case with every node's state, computed from its entries on each read and never stored.
+	*/
+	static getPlaybookCase(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}",
+			...options
+		});
+	}
+	/**
+	* Write a case's inputs
+	*
+	* Writes a batch of manual inputs, all or none. Each write names the revision it read in `expected_revision`, `null` for a field still unset; when any field has moved on the whole batch is refused with `409 PLAYBOOK_INPUT_CONFLICT` and `meta.conflicts` names each field. An input the case's version does not declare, one that reads another node, or a value its schema refuses is `400 PLAYBOOK_INPUT_INVALID`. A value equal to the field's current one writes no revision. Once written, every node the write makes runnable is queued to run, unless the case is paused. A write made with a credential the case's own work runs as — the case, one of its executions in flight, or the task or run one started — is `403 PLAYBOOK_SELF_WRITE`.
+	*/
+	static writePlaybookCaseInputs(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/inputs",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List what a node still needs
+	*
+	* Returns the manual inputs still unset, or refused by their schema, before `node` can be reached, grouped in waves: nothing in a later wave can run before the earlier ones are filled.
+	*/
+	static getPlaybookCaseMissing(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/missing",
+			...options
+		});
+	}
+	/**
+	* List a case's entries
+	*
+	* Returns every value written to the case, newest first. Entries are never rewritten, so this is the case's full history.
+	*/
+	static listPlaybookCaseEntries(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/entries",
+			...options
+		});
+	}
+	/**
+	* Run a node of a case
+	*
+	* Runs one node now. The cascade already runs every node whose inputs are set once a write, a settle or a resume makes it runnable, and never reruns a `failed` one: this is how a failed node is retried. A `collect` node takes its own input values as its output, any other node starts its executor with the node's input values mapped through the executor's `input`. The executor runs as the author of the case's playbook version, whose permission to start it is checked again here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`); an author that no longer exists is `409 PLAYBOOK_AUTHOR_UNAVAILABLE`. Only a `ready`, `stale` or `failed` node with every required input set runs; anything else is `409 PLAYBOOK_NODE_NOT_RUNNABLE`. A paused case is `409 PLAYBOOK_CASE_PAUSED`.
+	*
+	* The output is written as an entry when the execution settles. A value equal to the node's current output writes no revision. If the node's inputs change while it runs, the execution settles as `superseded` and writes nothing.
+	*
+	* Without `wait` the execution answers `running` and settles in the background. With `wait: true` it answers once the executor settles, or once it parks: a workflow task still open, or an orchestration run waiting on a person or a timer, settles the node when it closes or ends.
+	*/
+	static runPlaybookCaseNode(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/nodes/{node}/run",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List a case's executions
+	*
+	* Returns every run of the case's nodes, newest first.
+	*/
+	static listPlaybookCaseExecutions(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/executions",
+			...options
+		});
+	}
+	/**
+	* Get an execution
+	*
+	* Returns one run of a case's node.
+	*/
+	static getPlaybookCaseExecution(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/executions/{execution_id}",
+			...options
+		});
+	}
+	/**
+	* Export a final node
+	*
+	* Renders one revision of a final node as files, one export per transformation: each transformation's tool is called with the case's `case_id` and `subject`, the `node`, the `revision` and that revision's `output`, and must answer a file (`execute.response_mode: base64`) of its `format`'s content type. The file is kept in the project's files under `/.system/playbooks/`. An export never feeds a node.
+	*
+	* Without `revision` the node's current output is exported, which needs the node `done` (`409 PLAYBOOK_NODE_NOT_EXPORTABLE`); a `revision` names an earlier output or confirmation of the node. Each tool runs as the author of the case's playbook version, whose permission to call it is checked here (`403 PLAYBOOK_EXECUTOR_FORBIDDEN`). A paused case is `409 PLAYBOOK_CASE_PAUSED`.
+	*
+	* Without `wait` every export answers `running` and settles in the background; with `wait: true` it answers once each has its file or its error.
+	*/
+	static exportPlaybookCaseNode(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/nodes/{node}/exports",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List a case's exports
+	*
+	* Returns every file rendered from the case's final nodes, newest first.
+	*/
+	static listPlaybookCaseExports(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/exports",
+			...options
+		});
+	}
+	/**
+	* Get an export
+	*
+	* Returns one file rendered from a case's final node.
+	*/
+	static getPlaybookCaseExport(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/exports/{export_id}",
+			...options
+		});
+	}
+	/**
+	* Upgrade a case
+	*
+	* Moves a case to another version of its playbook: the playbook's current version, or the `version` named, an earlier one included. Values carry over by node key, and every node's state is read against the new version: a node added is open, a node removed leaves the structure while its entries stay, a node whose input reads another field is `stale`, and a value its input's new schema refuses is missing again. The cascade then runs what became runnable. Each upgrade is recorded with what moved; the version the case is already on records nothing.
+	*
+	* An execution running is `409 PLAYBOOK_CASE_BUSY`; one queued but not started settles `superseded`. An upgrade made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.
+	*/
+	static upgradePlaybookCase(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/upgrade",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* List a case's upgrades
+	*
+	* Returns every version change of the case, newest first.
+	*/
+	static listPlaybookCaseUpgrades(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/upgrades",
+			...options
+		});
+	}
+	/**
+	* Pause a case
+	*
+	* Stops the case starting anything: no node is queued and no queued execution starts until it is resumed. Executions already running settle. Input writes are still accepted. Pausing a paused case keeps the first pause.
+	*/
+	static pausePlaybookCase(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/pause",
+			...options
+		});
+	}
+	/**
+	* Resume a case
+	*
+	* Lifts the pause and starts what became runnable while the case was paused. A case that is not paused is `409 PLAYBOOK_CASE_NOT_PAUSED`.
+	*/
+	static resumePlaybookCase(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/resume",
+			...options
+		});
+	}
+	/**
+	* Confirm a node of a case
+	*
+	* Approves or rejects a `confirm` node on the inputs the confirmer read. `expected_revisions` names the revision of each of the node's inputs as read (`nodes[].inputs[].revision` on the case); an input that moved since is `409 PLAYBOOK_INPUT_CONFLICT`, `meta.conflicts` naming each, and nothing is written.
+	*
+	* An approval writes a `confirmation` entry whose value is the node's input values: it is the node's output, and the nodes reading it run next. A rejection writes a `rejection` entry with the `reason`: the node is `rejected`, and every node reading it is blocked, until its inputs change or it is approved. Another node, or a `confirm` node with a required input unset or reading a node that is not `done`, is `409 PLAYBOOK_NODE_NOT_CONFIRMABLE`. A confirmation made with a credential the case's own work runs as is `403 PLAYBOOK_SELF_WRITE`.
+	*/
+	static confirmPlaybookCaseNode(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/playbook-cases/{case_id}/nodes/{node}/confirmation",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+};
 var Projects = class {
 	/**
 	* List projects
@@ -6129,6 +6484,7 @@ var NaturaliClient = class {
 	quotas;
 	models;
 	orchestrations;
+	playbooks;
 	projects;
 	secrets;
 	sessions;
@@ -6184,6 +6540,7 @@ var NaturaliClient = class {
 		this.quotas = bindResource(Quotas, this.http);
 		this.models = bindResource(Models, this.http);
 		this.orchestrations = bindResource(Orchestrations, this.http);
+		this.playbooks = bindResource(Playbooks, this.http);
 		this.projects = bindResource(Projects, this.http);
 		this.secrets = bindResource(Secrets, this.http);
 		this.sessions = bindResource(Sessions, this.http);
@@ -6197,4 +6554,4 @@ var NaturaliClient = class {
 	}
 };
 //#endregion
-export { Activity, Actors, Admin, AgentVersions, Agents, AiProviders, ApiKeys, Approvals, Assistant, AuditLog, Auth, Chains, Channels, Conversations, Deciders, Documents, Embeddings, Evaluations, Exceptions, Files, Formations, Generations, Guardrails, IngestionRules, Installs, Knowledge, Listings, Memories, MemoryRules, MemoryStores, MetadataSchemas, ModelRoutes, Models, NaturaliClient, Orchestrations, Projects, Quotas, Secrets, Sessions, Tasks, Tools, Traces, Triggers, Users, Webhooks, Workflows, createClient, createConfig };
+export { Activity, Actors, Admin, AgentVersions, Agents, AiProviders, ApiKeys, Approvals, Assistant, AuditLog, Auth, Chains, Channels, Conversations, Deciders, Documents, Embeddings, Evaluations, Exceptions, Files, Formations, Generations, Guardrails, IngestionRules, Installs, Knowledge, Listings, Memories, MemoryRules, MemoryStores, MetadataSchemas, ModelRoutes, Models, NaturaliClient, Orchestrations, Playbooks, Projects, Quotas, Secrets, Sessions, Tasks, Tools, Traces, Triggers, Users, Webhooks, Workflows, createClient, createConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/sdk",
-  "version": "0.194.2",
+  "version": "0.195.0",
   "description": "TypeScript SDK for the naturali.ai API, generated from its OpenAPI specs",
   "keywords": [
     "naturali",
@@ -38,7 +38,7 @@
   },
   "devDependencies": {
     "@hey-api/openapi-ts": "^0.99.0",
-    "@naturali/api": "0.194.2",
+    "@naturali/api": "0.195.0",
     "@ttoss/openapi-codegen": "^0.5.0",
     "@types/node": "^26.5.1",
     "tsdown": "^0.23.0",