@naturali/cli 0.124.0 → 0.126.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.126.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({
@@ -3641,6 +3665,34 @@ var Projects = class {
 			...options
 		});
 	}
+	/**
+	* List project usage events
+	*
+	* The rows a rollup summed — one per metered occurrence, most recent first. Takes the same narrowings [the meter](/docs/api/projects/get-project-usage) does, so a query that produced a bucket answers here unchanged and reads back what went into it. This is the audit and reconciliation view: what was measured, when, against which agent, session, actor and provider, and what each component was priced at.
+	*
+	* An id naming nothing in this project yields an empty page rather than dropping the filter, so a mistyped narrowing can never widen the list past what was asked for.
+	*
+	*/
+	static listProjectUsageEvents(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/usage/events",
+			...options
+		});
+	}
+	/**
+	* Get a generation or orchestration-run billing receipt
+	*
+	* What one occurrence was billed, line by line: per-event line items with their measured components and unit prices, a per-meter-type split, and the totals. Pass generation_id for one generation, or orchestration_run_id for a receipt summed across every event the run metered. Exactly one of the two is required.
+	*
+	* This is the itemisation behind a single number — where [the meter](/docs/api/projects/get-project-usage) says a window cost $12.40, a receipt says which components of which call made up one occurrence of it. On an orchestration-run receipt every line carries node_id, so grouping by it gives the per-node cost the total hides; a retried node contributes one line per attempt, which is the intended reading for spend.
+	*
+	*/
+	static getProjectUsageReceipt(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/usage/receipt",
+			...options
+		});
+	}
 };
 var Quotas = class {
 	/**
@@ -4375,9 +4427,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 +4509,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 +5645,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 +5677,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 +8023,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 +8157,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 +8299,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 +8478,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 +8678,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 +12752,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"],
@@ -13742,6 +13799,169 @@ const routes = {
 			}
 		]
 	},
+	"list-project-usage-events": {
+		serviceClass: "Projects",
+		operationId: "listProjectUsageEvents",
+		description: "The rows a rollup summed — one per metered occurrence, most recent first. Takes the same narrowings [the meter](/docs/api/projects/get-project-usage) does, so a query that produced a bucket answers here unchanged and reads back what went into it. This is the audit and reconciliation view: what was measured, when, against which agent, session, actor and provider, and what each component was priced at. An id naming nothing in this project yields an empty page rather than dropping the filter, so a mistyped narrowing can never widen the list past what was asked for.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/projects",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: [
+			"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",
+			"limit",
+			"offset"
+		],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "meter_type",
+				"description": "Narrow the rollup to one meter type (llm_tokens, compute_execution, api_request, storage). Omit to include every meter. Useful with group_by=model, whose dimension otherwise mixes model ids with platform SKUs. An unrecognized value yields an empty rollup, not an error.\n",
+				"required": false,
+				"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": "limit",
+				"description": "Maximum number of events to return. A value above 100 is refused rather than clamped, so a caller paging by their own stride never silently skips a row.\n",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "Number of events to skip.",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
+	"get-project-usage-receipt": {
+		serviceClass: "Projects",
+		operationId: "getProjectUsageReceipt",
+		description: "What one occurrence was billed, line by line: per-event line items with their measured components and unit prices, a per-meter-type split, and the totals. Pass generation_id for one generation, or orchestration_run_id for a receipt summed across every event the run metered. Exactly one of the two is required. This is the itemisation behind a single number — where [the meter](/docs/api/projects/get-project-usage) says a window cost $12.40, a receipt says which components of which call made up one occurrence of it. On an orchestration-run receipt every line carries node_id, so grouping by it gives the per-node cost the total hides; a retried node contributes one line per attempt, which is the intended reading for spend.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/projects",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: ["generation_id", "orchestration_run_id"],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "generation_id",
+				"description": "Generation public ID. Mutually exclusive with orchestration_run_id.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			},
+			{
+				"name": "orchestration_run_id",
+				"description": "Orchestration run public ID. Returns the receipt summed across every generation the run metered. Mutually exclusive with generation_id.\n",
+				"required": false,
+				"type": "string",
+				"in": "query"
+			}
+		]
+	},
 	"list-quotas": {
 		serviceClass: "Quotas",
 		operationId: "listQuotas",
@@ -15899,7 +16119,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 +16217,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.126.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.126.0"
   },
   "scripts": {
     "generate": "tsx scripts/generate.ts",