@naturali/cli 0.123.0 → 0.124.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.123.0";
+var version = "0.124.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -3632,6 +3632,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 +3817,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({
@@ -4393,9 +4395,13 @@ var Users = class {
 	*
 	* Counted across the projects this account is the billing owner of, over the current UTC calendar month, from the meter itself. Archived projects are included: the runs they already made were made.
 	*
-	* **Nothing is refused against this.** The allowance is published, not enforced — an account past it keeps running. What does stop a managed-model generation is a negative credit balance, which is `GET /v1/users/me/billing`.
+	* **On the `free` plan the allowance is enforced.** An account that has used it is refused `403 plan_limit_reached` with `resource: "runs"` on everything that starts a generation — on its own provider credential as much as on a managed model, because a run is a run — until the billing month turns or it upgrades. On `pro` and `business` nothing is refused: runs past the allowance are billed at the overage rate those plans are sold with. A contract plan is not counted.
+	*
+	* The other thing that stops a managed-model generation is a negative credit balance, which is `GET /v1/users/me/billing`, and it never applies to your own credential.
+	*
+	* **This route counts live; the refusal reads a figure counted every few minutes.** So the two can differ by a burst: this is the more current number, and a refusal quotes the one it actually enforced.
 	*
-	* This read is more expensive than the balance one: it asks the meter once per project. Poll it on the order of minutes, not seconds.
+	* It is also more expensive than the balance read: it asks the meter once per project. Poll it on the order of minutes, not seconds.
 	*
 	*/
 	static getCurrentUserUsage(options) {
@@ -13576,13 +13582,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",
@@ -13598,7 +13616,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"
@@ -13610,6 +13628,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.",
@@ -14122,7 +14224,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"],
@@ -15807,7 +15909,7 @@ const routes = {
 	"get-current-user-usage": {
 		serviceClass: "Users",
 		operationId: "getCurrentUserUsage",
-		description: "How many runs the account has made this billing cycle, and how many its plan includes. A **run is one agent generation** — the unit every rung is priced in. Counted across the projects this account is the billing owner of, over the current UTC calendar month, from the meter itself. Archived projects are included: the runs they already made were made. **Nothing is refused against this.** The allowance is published, not enforced — an account past it keeps running. What does stop a managed-model generation is a negative credit balance, which is `GET /v1/users/me/billing`. This read is more expensive than the balance one: it asks the meter once per project. Poll it on the order of minutes, not seconds.",
+		description: "How many runs the account has made this billing cycle, and how many its plan includes. A **run is one agent generation** — the unit every rung is priced in. Counted across the projects this account is the billing owner of, over the current UTC calendar month, from the meter itself. Archived projects are included: the runs they already made were made. **On the `free` plan the allowance is enforced.** An account that has used it is refused `403 plan_limit_reached` with `resource: \"runs\"` on everything that starts a generation — on its own provider credential as much as on a managed model, because a run is a run — until the billing month turns or it upgrades. On `pro` and `business` nothing is refused: runs past the allowance are billed at the overage rate those plans are sold with. A contract plan is not counted. The other thing that stops a managed-model generation is a negative credit balance, which is `GET /v1/users/me/billing`, and it never applies to your own credential. **This route counts live; the refusal reads a figure counted every few minutes.** So the two can differ by a burst: this is the more current number, and a refusal quotes the one it actually enforced. It is also more expensive than the balance read: it asks the meter once per project. Poll it on the order of minutes, not seconds.",
 		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/users",
 		httpMethod: "get",
 		pathParams: [],

package/package.json

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