@naturali/cli 0.124.0 → 0.125.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.124.0";
+var version = "0.125.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -756,6 +756,9 @@ var Actors = class {
 var Channels = class {
 	/**
 	* List addresses
+	*
+	* Every identifier this project has seen. An address appears the first time a message arrives from it, so this is what naturali has observed rather than a roster you maintain — most rows carry no `action` of their own and defer to the route table.
+	*
 	*/
 	static listAddresses(options) {
 		return (options.client ?? client).get({
@@ -777,6 +780,9 @@ var Channels = class {
 	}
 	/**
 	* Get an address
+	*
+	* Reads one identifier's own action, if it has one. An identifier naturali has never seen is a `404`; to set an action without knowing whether it exists, use [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address-action), which upserts.
+	*
 	*/
 	static getAddress(options) {
 		return (options.client ?? client).get({
@@ -826,6 +832,9 @@ var Channels = class {
 	}
 	/**
 	* List a channel's routes
+	*
+	* One channel's routes, newest first, `disabled` ones included — only `active` routes take part in resolution. For every route in the project in one read, use [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).
+	*
 	*/
 	static listChannelRoutes(options) {
 		return (options.client ?? client).get({
@@ -851,6 +860,9 @@ var Channels = class {
 	}
 	/**
 	* Delete a route
+	*
+	* Conversations opened under this route keep its id and stay where they are; the next inbound resolves to the next most specific route, or the channel default, and opens a new conversation there. To stop a route from matching while keeping it readable, `PATCH` it to `status: disabled` instead.
+	*
 	*/
 	static deleteChannelRoute(options) {
 		return (options.client ?? client).delete({
@@ -860,6 +872,9 @@ var Channels = class {
 	}
 	/**
 	* Get a route
+	*
+	* A route id is only meaningful inside its own channel: the same id under another `channel_id` is a `404`. A conversation's `route_id` may instead be one of the two sentinels for the address's own action and the channel default — those name no route and are not readable here.
+	*
 	*/
 	static getChannelRoute(options) {
 		return (options.client ?? client).get({
@@ -948,6 +963,9 @@ var Channels = class {
 	}
 	/**
 	* Get a channel
+	*
+	* The channel's state, its transport modes and its default action. The access token is never returned — `has_credential` is all a read says about it.
+	*
 	*/
 	static getChannel(options) {
 		return (options.client ?? client).get({
@@ -1002,6 +1020,9 @@ var Channels = class {
 	}
 	/**
 	* Get a conversation
+	*
+	* Where the conversation points: the address it belongs to, the route (or sentinel) whose action opened it, and the runtime session it maps 1:1 to. The messages are not here — read them with [`GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages`](/docs/api/channels/list-channel-conversation-messages).
+	*
 	*/
 	static getChannelConversation(options) {
 		return (options.client ?? client).get({
@@ -3234,6 +3255,9 @@ var Models = class {
 	}
 	/**
 	* Get a model
+	*
+	* `{model}` is naturali's own name for the model, the same value [`GET /v1/models`](/docs/api/models/list-models) returns — a vendor's invocation string is a `404`. A `deprecated` model still reads here, so a project already generating on one can see what happened to it.
+	*
 	*/
 	static getModel(options) {
 		return (options.client ?? client).get({
@@ -4375,9 +4399,11 @@ var Users = class {
 	/**
 	* Get the current account's billing standing
 	*
-	* The plan the account is on, how long its projects may keep content, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+	* The plan the account is on, how long its projects may keep content, how much indexed storage it is holding, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against.
+	*
+	* A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days` or an ingest past `storage_limit_gb`. Every refusal names what is missing; this is where the numbers behind them are read.
 	*
-	* A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days`. Every refusal names what is missing; this is where the numbers behind them are read.
+	* Every figure here is a local read, which is what keeps this route cheap enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter once per project.
 	*
 	* Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.
 	*
@@ -4455,6 +4481,9 @@ var Webhooks = class {
 	}
 	/**
 	* Get a webhook
+	*
+	* The endpoint, the events it is subscribed to and whether deliveries are attempted. The signing secret is not returned: it is shown once by [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook) and again by [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).
+	*
 	*/
 	static getWebhook(options) {
 		return (options.client ?? client).get({
@@ -5588,7 +5617,7 @@ const routes = {
 	"list-addresses": {
 		serviceClass: "Channels",
 		operationId: "listAddresses",
-		description: "List addresses",
+		description: "Every identifier this project has seen. An address appears the first time a message arrives from it, so this is what naturali has observed rather than a roster you maintain — most rows carry no `action` of their own and defer to the route table.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/addresses",
 		httpMethod: "get",
 		pathParams: ["project_id"],
@@ -5620,7 +5649,7 @@ const routes = {
 	"get-address": {
 		serviceClass: "Channels",
 		operationId: "getAddress",
-		description: "Get an address",
+		description: "Reads one identifier's own action, if it has one. An identifier naturali has never seen is a `404`; to set an action without knowing whether it exists, use [`PUT /v1/projects/{project_id}/addresses/{identifier}`](/docs/api/addresses/set-address-action), which upserts.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/addresses",
 		httpMethod: "get",
 		pathParams: ["project_id", "identifier"],
@@ -7966,7 +7995,7 @@ const routes = {
 	"list-channel-routes": {
 		serviceClass: "Channels",
 		operationId: "listChannelRoutes",
-		description: "List a channel's routes",
+		description: "One channel's routes, newest first, `disabled` ones included — only `active` routes take part in resolution. For every route in the project in one read, use [`GET /v1/projects/{project_id}/channel-routes`](/docs/api/channel-routes/list-project-channel-routes).",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/channel-routes",
 		httpMethod: "get",
 		pathParams: ["project_id", "channel_id"],
@@ -8100,7 +8129,7 @@ const routes = {
 	"get-channel-route": {
 		serviceClass: "Channels",
 		operationId: "getChannelRoute",
-		description: "Get a route",
+		description: "A route id is only meaningful inside its own channel: the same id under another `channel_id` is a `404`. A conversation's `route_id` may instead be one of the two sentinels for the address's own action and the channel default — those name no route and are not readable here.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/channel-routes",
 		httpMethod: "get",
 		pathParams: [
@@ -8242,7 +8271,7 @@ const routes = {
 	"delete-channel-route": {
 		serviceClass: "Channels",
 		operationId: "deleteChannelRoute",
-		description: "Delete a route",
+		description: "Conversations opened under this route keep its id and stay where they are; the next inbound resolves to the next most specific route, or the channel default, and opens a new conversation there. To stop a route from matching while keeping it readable, `PATCH` it to `status: disabled` instead.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/channel-routes",
 		httpMethod: "delete",
 		pathParams: [
@@ -8421,7 +8450,7 @@ const routes = {
 	"get-channel": {
 		serviceClass: "Channels",
 		operationId: "getChannel",
-		description: "Get a channel",
+		description: "The channel's state, its transport modes and its default action. The access token is never returned — `has_credential` is all a read says about it.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/channels",
 		httpMethod: "get",
 		pathParams: ["project_id", "channel_id"],
@@ -8621,7 +8650,7 @@ const routes = {
 	"get-channel-conversation": {
 		serviceClass: "Channels",
 		operationId: "getChannelConversation",
-		description: "Get a conversation",
+		description: "Where the conversation points: the address it belongs to, the route (or sentinel) whose action opened it, and the runtime session it maps 1:1 to. The messages are not here — read them with [`GET /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}/messages`](/docs/api/channels/list-channel-conversation-messages).",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/channels",
 		httpMethod: "get",
 		pathParams: [
@@ -12695,7 +12724,7 @@ const routes = {
 	"get-model": {
 		serviceClass: "Models",
 		operationId: "getModel",
-		description: "Get a model",
+		description: "`{model}` is naturali's own name for the model, the same value [`GET /v1/models`](/docs/api/models/list-models) returns — a vendor's invocation string is a `404`. A `deprecated` model still reads here, so a project already generating on one can see what happened to it.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/models",
 		httpMethod: "get",
 		pathParams: ["model"],
@@ -15899,7 +15928,7 @@ const routes = {
 	"get-current-user-billing": {
 		serviceClass: "Users",
 		operationId: "getCurrentUserBilling",
-		description: "The plan the account is on, how long its projects may keep content, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against. A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days`. Every refusal names what is missing; this is where the numbers behind them are read. Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.",
+		description: "The plan the account is on, how long its projects may keep content, how much indexed storage it is holding, and the credit it has left — the figures the platform already enforces against, readable by the account they are enforced against. A managed-model generation is refused with `402 insufficient_credit` while `credit_balance_usd` is negative, and a feature or a resource count outside the plan is refused with `403`, as is a retention window wider than `retention_days` or an ingest past `storage_limit_gb`. Every refusal names what is missing; this is where the numbers behind them are read. Every figure here is a local read, which is what keeps this route cheap enough to poll — unlike `GET /v1/users/me/usage`, which asks the meter once per project. Answers for the caller's own account only, and always the account the credential resolves to — an API key answers for the user that minted it. The plan gating a *project* is that project's billing owner's, so a member of someone else's project reads their own rung here, not that project's.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/users",
 		httpMethod: "get",
 		pathParams: [],
@@ -15997,7 +16026,7 @@ const routes = {
 	"get-webhook": {
 		serviceClass: "Webhooks",
 		operationId: "getWebhook",
-		description: "Get a webhook",
+		description: "The endpoint, the events it is subscribed to and whether deliveries are attempted. The signing secret is not returned: it is shown once by [`POST /v1/projects/{project_id}/webhooks`](/docs/api/webhooks/create-webhook) and again by [`POST /v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret`](/docs/api/webhooks/rotate-webhook-secret).",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/webhooks",
 		httpMethod: "get",
 		pathParams: ["project_id", "webhook_id"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturali/cli",
-  "version": "0.124.0",
+  "version": "0.125.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.124.0"
+    "@naturali/sdk": "0.125.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",