@naturali/cli 0.40.1 → 0.42.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.40.1";
+var version = "0.42.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
@@ -1361,7 +1361,11 @@ var Knowledge = class {
 	/**
 	* Create a document
 	*
-	* Add an inline-text document to the collection. The platform ingests the content (chunk + embed) and records the document's ingestion status. File upload (PDF/binary) is a deliberate follow-up.
+	* Add a document to the collection, from **inline text** (`content`) or from an **uploaded file** (`file`, base64, plus `content_type` and `filename`) — exactly one of the two.
+	*
+	* `application/pdf`, `text/plain` and `text/markdown` are extracted natively. Any other media type needs a converter (`POST /v1/projects/{project_id}/knowledge/converters`) registered for it in the project; without one the request is rejected with `unsupported_content_type` and no document is created.
+	*
+	* Ingestion (extract → chunk → embed) runs in the background: the document comes back `pending` and becomes `indexed` or `failed`, which is announced by the `knowledge.document_ingested` / `knowledge.ingest_failed` webhook events.
 	*
 	*/
 	static createKnowledgeDocument(options) {
@@ -1406,6 +1410,86 @@ var Knowledge = class {
 			...options
 		});
 	}
+	/**
+	* List converters
+	*
+	* Lists the media converters registered in the project.
+	*/
+	static listKnowledgeConverters(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/knowledge/converters",
+			...options
+		});
+	}
+	/**
+	* Create a converter
+	*
+	* Register a converter for a media type the platform cannot extract natively, so files of that type become ingestable documents like any other. A converter maps a `content_type` glob (`image*`, `audio/mpeg`, …) onto one of two workers:
+	*
+	* - an **agent** (`agent_id`) — the file is handed to a
+	* multimodal model with a fixed "extract all the text" instruction and
+	* its answer becomes the document text. The shortest path for images
+	* and scanned PDFs; nothing to map.
+	*
+	* - a **tool** (`tool_id`) — the file is passed to an
+	* `http` tool as `{ content_type, filename, data_base64 }`, and
+	* whatever string the tool returns becomes the document text. The path
+	* for dedicated non-chat APIs (speech-to-text, a specialist OCR
+	* engine); use the tool's `execute.body_mode: multipart` for
+	* form-data endpoints and its `output_mapping` to reduce a JSON
+	* response to the bare string.
+	*
+	*
+	* Exactly one of `agent_id` / `tool_id`, and one converter per `content_type` in a project.
+	*
+	*/
+	static createKnowledgeConverter(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/knowledge/converters",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a converter
+	*
+	* Removes the converter. Documents already ingested through it are untouched; new files of that media type stop being ingestable until another converter covers them.
+	*
+	*/
+	static deleteKnowledgeConverter(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/knowledge/converters/{converter_id}",
+			...options
+		});
+	}
+	/**
+	* Get a converter
+	*/
+	static getKnowledgeConverter(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/knowledge/converters/{converter_id}",
+			...options
+		});
+	}
+	/**
+	* Update a converter
+	*
+	* Change the worker or the chunking defaults. At least one field is required; `agent_id` and `tool_id` stay mutually exclusive, so setting one clears the other.
+	*
+	*/
+	static updateKnowledgeConverter(options) {
+		return (options.client ?? client).patch({
+			url: "/v1/projects/{project_id}/knowledge/converters/{converter_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
 };
 var Models = class {
 	/**
@@ -1850,6 +1934,126 @@ var Traces = class {
 		});
 	}
 };
+var Webhooks = class {
+	/**
+	* List webhooks
+	*
+	* The endpoints registered in the project, newest first.
+	*/
+	static listWebhooks(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/webhooks",
+			...options
+		});
+	}
+	/**
+	* Create a webhook
+	*
+	* Register an endpoint and subscribe it to one or more event types.
+	* The response carries `secret` — the signing key, in plaintext. **This is the only time it is returned.** Store it where your receiver can read it; if you lose it, rotate rather than re-create, so the endpoint keeps its delivery history.
+	* Returns `501` on a deployment with no credential-sealing key configured, since the secret could not then be stored safely.
+	*
+	*/
+	static createWebhook(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/webhooks",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a webhook
+	*
+	* Removes the endpoint and its delivery records. To stop deliveries while keeping the audit trail, `PATCH` it to `active: false` instead.
+	*
+	*/
+	static deleteWebhook(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/webhooks/{webhook_id}",
+			...options
+		});
+	}
+	/**
+	* Get a webhook
+	*/
+	static getWebhook(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/webhooks/{webhook_id}",
+			...options
+		});
+	}
+	/**
+	* Update a webhook
+	*
+	* Change the destination, the subscription, the label, or whether deliveries are attempted at all. At least one field is required.
+	* Setting `active: false` is the reversible half of `DELETE`: deliveries stop, the endpoint and its history stay. It is what to reach for while a receiver is being repaired.
+	*
+	*/
+	static updateWebhook(options) {
+		return (options.client ?? client).patch({
+			url: "/v1/projects/{project_id}/webhooks/{webhook_id}",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Rotate the signing secret
+	*
+	* Issues a new signing secret for the same endpoint and returns it — the second and last time a secret is ever returned. This is the `…:rotate-secret` action; the path segment is `{webhook_id}:rotate-secret`.
+	* The change takes effect on the next delivery, including retries of deliveries already queued, so roll the new secret out to your receiver promptly. There is no overlap window in which both secrets verify.
+	*
+	*/
+	static rotateWebhookSecret(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret",
+			...options
+		});
+	}
+	/**
+	* List webhook deliveries
+	*
+	* Every delivery attempted in the project, newest first — what was sent, where, how many times, and what came back. Filter by endpoint, by lifecycle status, or by event type.
+	* Deliveries are per (event, endpoint): an event matching two subscribed endpoints produces two rows, retried and observed independently.
+	*
+	*/
+	static listWebhookDeliveries(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/webhook-deliveries",
+			...options
+		});
+	}
+	/**
+	* Get a webhook delivery
+	*
+	* One delivery, including the exact payload that was signed and sent.
+	*
+	*/
+	static getWebhookDelivery(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/webhook-deliveries/{delivery_id}",
+			...options
+		});
+	}
+	/**
+	* Redeliver an event
+	*
+	* Queue the same event at the same endpoint again — the recovery path for a delivery that failed, or one your receiver dropped. This is the `…:redeliver` action; the path segment is `{delivery_id}:redeliver`.
+	* A **new** delivery is created and returned; the original record is left untouched, because its attempt history is the evidence you redelivered on. The event's `id` is carried over unchanged, so a receiver deduping on the event sees the same event twice while one deduping on `X-Naturali-Delivery` sees a distinct delivery.
+	*
+	*/
+	static redeliverWebhookDelivery(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/webhook-deliveries/{delivery_id}:redeliver",
+			...options
+		});
+	}
+};
 //#endregion
 //#region ../sdk/src/naturaliClient.ts
 /**
@@ -1912,6 +2116,7 @@ var NaturaliClient = class {
 	tasks;
 	tools;
 	traces;
+	webhooks;
 	/** The underlying HTTP client, for interceptors or one-off requests. */
 	http;
 	constructor({ token, headers } = {}) {
@@ -1937,6 +2142,7 @@ var NaturaliClient = class {
 		this.tasks = bindResource(Tasks, this.http);
 		this.tools = bindResource(Tools, this.http);
 		this.traces = bindResource(Traces, this.http);
+		this.webhooks = bindResource(Webhooks, this.http);
 	}
 };
 //#endregion
@@ -1958,6 +2164,7 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	Tasks: () => Tasks,
 	Tools: () => Tools,
 	Traces: () => Traces,
+	Webhooks: () => Webhooks,
 	createClient: () => createClient,
 	createConfig: () => createConfig
 });
@@ -4266,7 +4473,7 @@ const routes = {
 	"create-knowledge-document": {
 		serviceClass: "Knowledge",
 		operationId: "createKnowledgeDocument",
-		description: "Add an inline-text document to the collection. The platform ingests the content (chunk + embed) and records the document's ingestion status. File upload (PDF/binary) is a deliberate follow-up.",
+		description: "Add a document to the collection, from **inline text** (`content`) or from an **uploaded file** (`file`, base64, plus `content_type` and `filename`) — exactly one of the two. `application/pdf`, `text/plain` and `text/markdown` are extracted natively. Any other media type needs a converter (`POST /v1/projects/{project_id}/knowledge/converters`) registered for it in the project; without one the request is rejected with `unsupported_content_type` and no document is created. Ingestion (extract → chunk → embed) runs in the background: the document comes back `pending` and becomes `indexed` or `failed`, which is announced by the `knowledge.document_ingested` / `knowledge.ingest_failed` webhook events.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
 		httpMethod: "post",
 		pathParams: ["project_id", "collection_id"],
@@ -4288,14 +4495,28 @@ const routes = {
 			},
 			{
 				"name": "content",
-				"description": "The document's text content.",
-				"required": true,
+				"description": "The document's text content. Mutually exclusive with `file`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "file",
+				"description": "The file's bytes, base64-encoded. Mutually exclusive with `content`.\n",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "content_type",
+				"description": "Media type of `file`. `application/pdf`, `text/plain` and `text/markdown` are extracted natively; anything else needs a matching converter in the project. Required with `file`.\n",
+				"required": false,
 				"type": "string",
 				"in": "body"
 			},
 			{
 				"name": "filename",
-				"description": "A label for the document; also its logical filename.",
+				"description": "A label for the document; also its logical filename. Required with `file`.\n",
 				"required": false,
 				"type": "string",
 				"in": "body"
@@ -4306,6 +4527,27 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "body"
+			},
+			{
+				"name": "chunk_strategy",
+				"description": "How the extracted text is split for embedding. `page` (the default) makes one chunk per page, which is what lets a retrieved chunk cite a page number; `size` makes fixed-width character windows, which retrieves more sharply on dense pages at the cost of that citation; `whole` keeps the document as a single chunk. Ignored for inline text.\n",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_size",
+				"description": "Window width in characters, when `chunk_strategy` is `size`.",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			},
+			{
+				"name": "chunk_overlap",
+				"description": "Characters of overlap between consecutive windows, when `chunk_strategy` is `size`. Must be smaller than `chunk_size`.\n",
+				"required": false,
+				"type": "integer",
+				"in": "body"
 			}
 		]
 	},
@@ -4417,23 +4659,22 @@ const routes = {
 			}
 		]
 	},
-	"list-models": {
-		serviceClass: "Models",
-		operationId: "listModels",
-		description: "Lists catalog models, newest sources merged and sorted by id. Filter by vendor, provider, output/input modality or status.",
-		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/models",
+	"list-knowledge-converters": {
+		serviceClass: "Knowledge",
+		operationId: "listKnowledgeConverters",
+		description: "Lists the media converters registered in the project.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
 		httpMethod: "get",
-		pathParams: [],
-		queryParams: [
-			"limit",
-			"cursor",
-			"vendor",
-			"provider",
-			"modality",
-			"status",
-			"managed"
-		],
+		pathParams: ["project_id"],
+		queryParams: ["limit", "cursor"],
 		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
 			{
 				"name": "limit",
 				"description": "Maximum items per page.",
@@ -4447,61 +4688,293 @@ const routes = {
 				"required": false,
 				"type": "string",
 				"in": "query"
+			}
+		]
+	},
+	"create-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "createKnowledgeConverter",
+		description: "Register a converter for a media type the platform cannot extract natively, so files of that type become ingestable documents like any other. A converter maps a `content_type` glob (`image/*`, `audio/mpeg`, …) onto one of two workers: - an **agent** (`agent_id`) — the file is handed to a multimodal model with a fixed \"extract all the text\" instruction and its answer becomes the document text. The shortest path for images and scanned PDFs; nothing to map. - a **tool** (`tool_id`) — the file is passed to an `http` tool as `{ content_type, filename, data_base64 }`, and whatever string the tool returns becomes the document text. The path for dedicated non-chat APIs (speech-to-text, a specialist OCR engine); use the tool's `execute.body_mode: multipart` for form-data endpoints and its `output_mapping` to reduce a JSON response to the bare string. Exactly one of `agent_id` / `tool_id`, and one converter per `content_type` in a project.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
 			},
 			{
-				"name": "vendor",
-				"description": "Filter by model maker (e.g. anthropic, amazon, meta).",
+				"name": "content_type",
+				"description": "The media-type glob to claim — an exact type (`audio/mpeg`) or a `*` wildcard on the subtype (`image/*`).\n",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "agent_id",
+				"description": "An agent in this project, used as the converter.",
 				"required": false,
 				"type": "string",
-				"in": "query"
+				"in": "body"
 			},
 			{
-				"name": "provider",
-				"description": "Filter by the provider slug that serves the model.",
+				"name": "tool_id",
+				"description": "An `http` tool in this project, used as the converter.",
 				"required": false,
 				"type": "string",
-				"in": "query"
+				"in": "body"
 			},
 			{
-				"name": "modality",
-				"description": "Filter to models whose input or output modalities include this value (e.g. text, image, embedding, speech).\n",
+				"name": "preset_parameters",
+				"description": "Fixed arguments merged into every tool-converter call.",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "native_extraction",
+				"description": "",
 				"required": false,
 				"type": "string",
-				"in": "query"
+				"in": "body"
 			},
 			{
-				"name": "status",
-				"description": "Filter by lifecycle status.",
+				"name": "chunk_strategy",
+				"description": "",
 				"required": false,
 				"type": "string",
-				"in": "query"
+				"in": "body"
 			},
 			{
-				"name": "managed",
-				"description": "Filter by whether the model can back a managed provider — `managed=true` is the set you can pass to `POST /v1/projects/{project_id}/providers` with `kind: managed`. Omit to leave the catalog unfiltered on this axis; `false` returns only the BYOK-only models. Any other value is a 400.\n",
+				"name": "chunk_size",
+				"description": "",
 				"required": false,
-				"type": "boolean",
-				"in": "query"
+				"type": "integer",
+				"in": "body"
+			},
+			{
+				"name": "chunk_overlap",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
 			}
 		]
 	},
-	"get-model": {
-		serviceClass: "Models",
-		operationId: "getModel",
-		description: "Get a model",
-		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/models",
+	"get-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "getKnowledgeConverter",
+		description: "Get a converter",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
 		httpMethod: "get",
-		pathParams: ["model_id"],
+		pathParams: ["project_id", "converter_id"],
 		queryParams: [],
 		flags: [{
-			"name": "model_id",
-			"description": "Public model id.",
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
 			"required": true,
 			"type": "string",
 			"in": "path"
-		}]
-	},
-	"list-projects": {
+		}, {
+			"name": "converter_id",
+			"description": "Knowledge converter public ID (igr_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"update-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "updateKnowledgeConverter",
+		description: "Change the worker or the chunking defaults. At least one field is required; `agent_id` and `tool_id` stay mutually exclusive, so setting one clears the other.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "patch",
+		pathParams: ["project_id", "converter_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "converter_id",
+				"description": "Knowledge converter public ID (igr_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "content_type",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "agent_id",
+				"description": "Switches the converter to this agent, clearing `tool_id`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "tool_id",
+				"description": "Switches the converter to this tool, clearing `agent_id`.",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "preset_parameters",
+				"description": "",
+				"required": false,
+				"type": "object",
+				"in": "body"
+			},
+			{
+				"name": "native_extraction",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_strategy",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "chunk_size",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			},
+			{
+				"name": "chunk_overlap",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "body"
+			}
+		]
+	},
+	"delete-knowledge-converter": {
+		serviceClass: "Knowledge",
+		operationId: "deleteKnowledgeConverter",
+		description: "Removes the converter. Documents already ingested through it are untouched; new files of that media type stop being ingestable until another converter covers them.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/knowledge",
+		httpMethod: "delete",
+		pathParams: ["project_id", "converter_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "converter_id",
+			"description": "Knowledge converter public ID (igr_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"list-models": {
+		serviceClass: "Models",
+		operationId: "listModels",
+		description: "Lists catalog models, newest sources merged and sorted by id. Filter by vendor, provider, output/input modality or status.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/models",
+		httpMethod: "get",
+		pathParams: [],
+		queryParams: [
+			"limit",
+			"cursor",
+			"vendor",
+			"provider",
+			"modality",
+			"status",
+			"managed"
+		],
+		flags: [
+			{
+				"name": "limit",
+				"description": "Maximum items per page.",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "cursor",
+				"description": "Opaque pagination cursor from a previous response's next_cursor.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "vendor",
+				"description": "Filter by model maker (e.g. anthropic, amazon, meta).",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "provider",
+				"description": "Filter by the provider slug that serves the model.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "modality",
+				"description": "Filter to models whose input or output modalities include this value (e.g. text, image, embedding, speech).\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "status",
+				"description": "Filter by lifecycle status.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "managed",
+				"description": "Filter by whether the model can back a managed provider — `managed=true` is the set you can pass to `POST /v1/projects/{project_id}/providers` with `kind: managed`. Omit to leave the catalog unfiltered on this axis; `false` returns only the BYOK-only models. Any other value is a 400.\n",
+				"required": false,
+				"type": "boolean",
+				"in": "query"
+			}
+		]
+	},
+	"get-model": {
+		serviceClass: "Models",
+		operationId: "getModel",
+		description: "Get a model",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/models",
+		httpMethod: "get",
+		pathParams: ["model_id"],
+		queryParams: [],
+		flags: [{
+			"name": "model_id",
+			"description": "Public model id.",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"list-projects": {
 		serviceClass: "Projects",
 		operationId: "listProjects",
 		description: "Lists projects accessible to the caller.",
@@ -5747,6 +6220,306 @@ const routes = {
 				"in": "query"
 			}
 		]
+	},
+	"list-webhooks": {
+		serviceClass: "Webhooks",
+		operationId: "listWebhooks",
+		description: "The endpoints registered in the project, newest first.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: ["limit", "cursor"],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum items per page.",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "cursor",
+				"description": "Opaque pagination cursor from a previous response's next_cursor.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			}
+		]
+	},
+	"create-webhook": {
+		serviceClass: "Webhooks",
+		operationId: "createWebhook",
+		description: "Register an endpoint and subscribe it to one or more event types. The response carries `secret` — the signing key, in plaintext. **This is the only time it is returned.** Store it where your receiver can read it; if you lose it, rotate rather than re-create, so the endpoint keeps its delivery history. Returns `501` on a deployment with no credential-sealing key configured, since the secret could not then be stored safely.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "url",
+				"description": "An `https://` endpoint (`http://` is accepted for localhost, so a tunnel works in development).\n",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "events",
+				"description": "Which events this endpoint receives. Each entry is an exact type (`task.created`), a resource wildcard (`task.*`), or `*` for everything. A bare resource name (`task`) matches nothing and is rejected.\n",
+				"required": true,
+				"type": "array",
+				"in": "body"
+			},
+			{
+				"name": "description",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "active",
+				"description": "",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
+			}
+		]
+	},
+	"get-webhook": {
+		serviceClass: "Webhooks",
+		operationId: "getWebhook",
+		description: "Get a webhook",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "get",
+		pathParams: ["project_id", "webhook_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "webhook_id",
+			"description": "Webhook public ID (whk_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"update-webhook": {
+		serviceClass: "Webhooks",
+		operationId: "updateWebhook",
+		description: "Change the destination, the subscription, the label, or whether deliveries are attempted at all. At least one field is required. Setting `active: false` is the reversible half of `DELETE`: deliveries stop, the endpoint and its history stay. It is what to reach for while a receiver is being repaired.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "patch",
+		pathParams: ["project_id", "webhook_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "webhook_id",
+				"description": "Webhook public ID (whk_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "url",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "events",
+				"description": "Which events this endpoint receives. Each entry is an exact type (`task.created`), a resource wildcard (`task.*`), or `*` for everything. A bare resource name (`task`) matches nothing and is rejected.\n",
+				"required": false,
+				"type": "array",
+				"in": "body"
+			},
+			{
+				"name": "description",
+				"description": "",
+				"required": false,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "active",
+				"description": "",
+				"required": false,
+				"type": "boolean",
+				"in": "body"
+			}
+		]
+	},
+	"delete-webhook": {
+		serviceClass: "Webhooks",
+		operationId: "deleteWebhook",
+		description: "Removes the endpoint and its delivery records. To stop deliveries while keeping the audit trail, `PATCH` it to `active: false` instead.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "delete",
+		pathParams: ["project_id", "webhook_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "webhook_id",
+			"description": "Webhook public ID (whk_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"rotate-webhook-secret": {
+		serviceClass: "Webhooks",
+		operationId: "rotateWebhookSecret",
+		description: "Issues a new signing secret for the same endpoint and returns it — the second and last time a secret is ever returned. This is the `…:rotate-secret` action; the path segment is `{webhook_id}:rotate-secret`. The change takes effect on the next delivery, including retries of deliveries already queued, so roll the new secret out to your receiver promptly. There is no overlap window in which both secrets verify.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "post",
+		pathParams: ["project_id", "webhook_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "webhook_id",
+			"description": "Webhook public ID (whk_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"list-webhook-deliveries": {
+		serviceClass: "Webhooks",
+		operationId: "listWebhookDeliveries",
+		description: "Every delivery attempted in the project, newest first — what was sent, where, how many times, and what came back. Filter by endpoint, by lifecycle status, or by event type. Deliveries are per (event, endpoint): an event matching two subscribed endpoints produces two rows, retried and observed independently.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: [
+			"limit",
+			"cursor",
+			"webhook_id",
+			"status",
+			"event_type"
+		],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "Maximum items per page.",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "cursor",
+				"description": "Opaque pagination cursor from a previous response's next_cursor.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "webhook_id",
+				"description": "Only deliveries addressed to this endpoint.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "status",
+				"description": "Only deliveries in this state.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "event_type",
+				"description": "Only deliveries of this event type.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			}
+		]
+	},
+	"get-webhook-delivery": {
+		serviceClass: "Webhooks",
+		operationId: "getWebhookDelivery",
+		description: "One delivery, including the exact payload that was signed and sent.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "get",
+		pathParams: ["project_id", "delivery_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "delivery_id",
+			"description": "Delivery public ID (whd_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
+	"redeliver-webhook-delivery": {
+		serviceClass: "Webhooks",
+		operationId: "redeliverWebhookDelivery",
+		description: "Queue the same event at the same endpoint again — the recovery path for a delivery that failed, or one your receiver dropped. This is the `…:redeliver` action; the path segment is `{delivery_id}:redeliver`. A **new** delivery is created and returned; the original record is left untouched, because its attempt history is the evidence you redelivered on. The event's `id` is carried over unchanged, so a receiver deduping on the event sees the same event twice while one deduping on `X-Naturali-Delivery` sees a distinct delivery.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
+		httpMethod: "post",
+		pathParams: ["project_id", "delivery_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "delivery_id",
+			"description": "Delivery public ID (whd_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
 	}
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.40.1",
+  "version": "0.42.0",
   "description": "Command-line interface for the naturali.ai API, generated from its OpenAPI specs",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "tsx": "^4.23.1",
     "typescript": "~6.0.3",
     "vitest": "^4.1.10",
-    "@naturali/sdk": "0.40.1"
+    "@naturali/sdk": "0.42.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",