@naturali/cli 0.123.1 → 0.125.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.123.1";
+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({
@@ -3632,6 +3656,8 @@ var Projects = class {
 	*
 	* Every bucket also carries components — the amounts actually measured. The token counts describe LLM usage alone, so that is where a storage, api_request or compute_execution bucket reports its real quantity instead of zeroed token fields.
 	*
+	* The rollup can also be narrowed to one session or one end user before it is bucketed. That is the question no dimension answers: group_by splits the project's whole spend, so "what did this conversation cost, per day" and "what has this end user spent across every session" are reachable only by narrowing. The narrowings intersect, apply to the totals as well as the buckets, and are echoed back complete — null for each one not applied — because a rollup of zeros is otherwise indistinguishable from a project that spent nothing.
+	*
 	*/
 	static getProjectUsage(options) {
 		return (options.client ?? client).get({
@@ -3815,7 +3841,7 @@ var Sessions = class {
 	/**
 	* Get a session
 	*
-	* Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, or a split by day, model, agent, provider or run, read `GET /v1/projects/{project_id}/usage` instead.
+	* Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, a split by day or model, or one end user across every session, narrow `GET /v1/projects/{project_id}/usage` with `session_id` / `actor_id` instead.
 	*/
 	static getSession(options) {
 		return (options.client ?? client).get({
@@ -4373,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.
 	*
@@ -4453,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({
@@ -5586,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"],
@@ -5618,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"],
@@ -7964,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"],
@@ -8098,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: [
@@ -8240,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: [
@@ -8419,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"],
@@ -8619,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: [
@@ -12693,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"],
@@ -13580,13 +13611,25 @@ const routes = {
 	"get-project-usage": {
 		serviceClass: "Projects",
 		operationId: "getProjectUsage",
-		description: "The per-project meter — the re-billing view (A11/C12/P3). Aggregates the project's usage over an optional [from, to] window, bucketed by a single dimension. Costs are the billing-grade cost_usd the runtime freezes at write time; null means nothing in the bucket was priced (never that it was free). Only managed providers are priced (on the runtime), so cost reflects managed usage; BYOK usage carries no LLM cost. Every bucket also carries components — the amounts actually measured. The token counts describe LLM usage alone, so that is where a storage, api_request or compute_execution bucket reports its real quantity instead of zeroed token fields.",
+		description: "The per-project meter — the re-billing view (A11/C12/P3). Aggregates the project's usage over an optional [from, to] window, bucketed by a single dimension. Costs are the billing-grade cost_usd the runtime freezes at write time; null means nothing in the bucket was priced (never that it was free). Only managed providers are priced (on the runtime), so cost reflects managed usage; BYOK usage carries no LLM cost. Every bucket also carries components — the amounts actually measured. The token counts describe LLM usage alone, so that is where a storage, api_request or compute_execution bucket reports its real quantity instead of zeroed token fields. The rollup can also be narrowed to one session or one end user before it is bucketed. That is the question no dimension answers: group_by splits the project's whole spend, so \"what did this conversation cost, per day\" and \"what has this end user spent across every session\" are reachable only by narrowing. The narrowings intersect, apply to the totals as well as the buckets, and are echoed back complete — null for each one not applied — because a rollup of zeros is otherwise indistinguishable from a project that spent nothing.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/projects",
 		httpMethod: "get",
 		pathParams: ["project_id"],
 		queryParams: [
 			"group_by",
 			"meter_type",
+			"session_id",
+			"actor_id",
+			"agent_id",
+			"ai_provider_id",
+			"orchestration_run_id",
+			"orchestration_id",
+			"generation_id",
+			"trace_id",
+			"source",
+			"trigger_id",
+			"action_id",
+			"include",
 			"from",
 			"to",
 			"limit",
@@ -13602,7 +13645,7 @@ const routes = {
 			},
 			{
 				"name": "group_by",
-				"description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others on the matching id. `model` buckets on the model *and* the provider that served it, so one model name served by two providers is two groups (see `ai_provider_id`). `ai_provider` buckets on the provider the spend was billed against — a routed generation's serving target, or the agent's pinned provider — which is the total a per-provider reconciliation wants, without summing the model dimension by hand. `run` buckets on the orchestration run an event belongs to; work that runs no orchestration collapses into the single null bucket, so the bucket count there is not a count of runs.\n",
+				"description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others on the matching id. `model` buckets on the model *and* the provider that served it, so one model name served by two providers is two groups (see `ai_provider_id`). `ai_provider` buckets on the provider the spend was billed against — a routed generation's serving target, or the agent's pinned provider — which is the total a per-provider reconciliation wants, without summing the model dimension by hand. `run` buckets on the orchestration run an event belongs to; work that runs no orchestration collapses into the single null bucket, so the bucket count there is not a count of runs. `session` and `actor` bucket on the conversation and the end user behind the spend — what a customer re-billing their own users charges each of them for; traffic with no end user behind it collapses into the single null bucket on both. `source` buckets on what the spend was incurred for (`eval`, `eval_judge`), which is how verification spend is told apart from the traffic serving real users; ordinary traffic carries no source and is the null bucket.\n",
 				"required": false,
 				"type": "string",
 				"in": "query"
@@ -13614,6 +13657,90 @@ const routes = {
 				"type": "string",
 				"in": "query"
 			},
+			{
+				"name": "session_id",
+				"description": "Narrow the whole rollup — every bucket and the top-level totals alike — to one session's traffic. Combines with group_by: group_by=day&session_id=... is one conversation's spend per day, group_by=model the same spend split by model. This is the figure behind the usage roll-up a single session read carries, broken down. An id naming no session in this project yields an empty rollup, never the project total.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "actor_id",
+				"description": "The same narrowing, for one end user across every session they appear in — what a customer re-billing their own users charges each of them for. An id naming no actor in this project yields an empty rollup, never the project total.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "agent_id",
+				"description": "Narrow to one agent's traffic, across every session, run and trigger that dispatched it.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "ai_provider_id",
+				"description": "Narrow to the spend billed against one provider record — a routed generation's serving target, or the agent's pinned provider.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "orchestration_run_id",
+				"description": "Narrow to the events one orchestration run metered.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "orchestration_id",
+				"description": "Narrow to the runs of one orchestration — the ones it started itself, never the subtree a loop or sub-orchestration node started under it, which is metered against the child orchestration where it was incurred. Additive: summed across a project's orchestrations the figures reach the project total exactly once.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "generation_id",
+				"description": "Narrow to one generation's events. A generation writes more than one when it meters several dimensions, such as tokens and compute.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "trace_id",
+				"description": "Narrow to the events recorded under one trace.",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "source",
+				"description": "Narrow by what the spend was incurred for — eval and eval_judge are verification spend. Ordinary traffic carries no source, so it cannot be selected by this filter; omit the filter for everything.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "trigger_id",
+				"description": "Narrow to the spend one trigger initiated. Matched as recorded rather than resolved, so it still selects the spend of a trigger that has since been deleted.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "action_id",
+				"description": "Narrow to one caller-supplied action label, for per-action spend. Matched as recorded, like trigger_id.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "include",
+				"description": "Optional extras to compute. The only value is distinct, which adds the distinct object — one count per kind of entity the window touched. Opt-in because each counter costs the window another sort, so a caller who does not ask keeps the cheap response whatever the event table grows to. Any other value is a 400.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
 			{
 				"name": "from",
 				"description": "Inclusive lower bound (ISO-8601) on event time. Omit for no lower bound.",
@@ -14126,7 +14253,7 @@ const routes = {
 	"get-session": {
 		serviceClass: "Sessions",
 		operationId: "getSession",
-		description: "Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, or a split by day, model, agent, provider or run, read `GET /v1/projects/{project_id}/usage` instead.",
+		description: "Returns details of a single session, including a `usage` roll-up of what its generations cost. The listing omits `usage`; for a window, a split by day or model, or one end user across every session, narrow `GET /v1/projects/{project_id}/usage` with `session_id` / `actor_id` instead.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/sessions",
 		httpMethod: "get",
 		pathParams: ["project_id", "session_id"],
@@ -15801,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: [],
@@ -15899,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.123.1",
+  "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.123.1"
+    "@naturali/sdk": "0.125.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",