@naturali/cli 0.125.0 → 0.127.0

package/dist/index.mjs

@@ -14,7 +14,7 @@ var __exportAll = (all, no_symbols) => {
 };
 //#endregion
 //#region package.json
-var version = "0.125.0";
+var version = "0.127.0";
 //#endregion
 //#region ../sdk/src/generated/core/bodySerializer.gen.ts
 const serializeFormDataPair = (data, key, value) => {
@@ -1138,6 +1138,20 @@ var Admin = class {
 			}
 		});
 	}
+	/**
+	* Read the global price book
+	*
+	* The upstream runtime's global default prices — the rows carrying neither a provider nor a project, which is all the upstream listing returns, so no tenant's own rates appear here.
+	*
+	* These are a cost basis, not a tariff: what a customer pays is the plan they bought plus the multiplier in PRICING.md section 3, applied when spend is reconciled. This is the read behind the storage-rate assertion at boot and the pinned embedding rate.
+	*
+	*/
+	static getAdminPriceBook(options) {
+		return (options?.client ?? client).get({
+			url: "/v1/admin/usage/prices",
+			...options
+		});
+	}
 };
 var Agents = class {
 	/**
@@ -3665,6 +3679,75 @@ 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
+		});
+	}
+	/**
+	* List usage thresholds
+	*
+	* The spend alerts this project has set. A threshold fires the usage.threshold_crossed event when the project's windowed usage crosses it, so one is only useful alongside a webhook subscribed to that event.
+	*
+	*/
+	static listProjectUsageThresholds(options) {
+		return (options.client ?? client).get({
+			url: "/v1/projects/{project_id}/usage/thresholds",
+			...options
+		});
+	}
+	/**
+	* Set a usage threshold
+	*
+	* Creates an alert on this project's windowed usage. Crossing it fires usage.threshold_crossed once per window — a calendar_month threshold fires at most once in a month, and a rolling_24h one re-arms when the windowed total falls back below 90% of the threshold, so a total hovering at the line does not alert repeatedly.
+	*
+	* Requires the admin role: an alerting rule belongs to the account that pays, not to one member.
+	*
+	*/
+	static createProjectUsageThreshold(options) {
+		return (options.client ?? client).post({
+			url: "/v1/projects/{project_id}/usage/thresholds",
+			...options,
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers
+			}
+		});
+	}
+	/**
+	* Delete a usage threshold
+	*
+	* Stops the alert. Requires the admin role.
+	*/
+	static deleteProjectUsageThreshold(options) {
+		return (options.client ?? client).delete({
+			url: "/v1/projects/{project_id}/usage/thresholds/{threshold_id}",
+			...options
+		});
+	}
 };
 var Quotas = class {
 	/**
@@ -6003,6 +6086,16 @@ const routes = {
 			}
 		]
 	},
+	"get-admin-price-book": {
+		serviceClass: "Admin",
+		operationId: "getAdminPriceBook",
+		description: "The upstream runtime's global default prices — the rows carrying neither a provider nor a project, which is all the upstream listing returns, so no tenant's own rates appear here. These are a cost basis, not a tariff: what a customer pays is the plan they bought plus the multiplier in PRICING.md section 3, applied when spend is reconciled. This is the read behind the storage-rate assertion at boot and the pinned embedding rate.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/admin",
+		httpMethod: "get",
+		pathParams: [],
+		queryParams: [],
+		flags: []
+	},
 	"list-agents": {
 		serviceClass: "Agents",
 		operationId: "listAgents",
@@ -13771,6 +13864,262 @@ 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-project-usage-thresholds": {
+		serviceClass: "Projects",
+		operationId: "listProjectUsageThresholds",
+		description: "The spend alerts this project has set. A threshold fires the usage.threshold_crossed event when the project's windowed usage crosses it, so one is only useful alongside a webhook subscribed to that event.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/projects",
+		httpMethod: "get",
+		pathParams: ["project_id"],
+		queryParams: ["limit", "offset"],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "limit",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			},
+			{
+				"name": "offset",
+				"description": "",
+				"required": false,
+				"type": "integer",
+				"in": "query"
+			}
+		]
+	},
+	"create-project-usage-threshold": {
+		serviceClass: "Projects",
+		operationId: "createProjectUsageThreshold",
+		description: "Creates an alert on this project's windowed usage. Crossing it fires usage.threshold_crossed once per window — a calendar_month threshold fires at most once in a month, and a rolling_24h one re-arms when the windowed total falls back below 90% of the threshold, so a total hovering at the line does not alert repeatedly. Requires the admin role: an alerting rule belongs to the account that pays, not to one member.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/projects",
+		httpMethod: "post",
+		pathParams: ["project_id"],
+		queryParams: [],
+		flags: [
+			{
+				"name": "project_id",
+				"description": "Project public ID (proj_ prefix).",
+				"required": true,
+				"type": "string",
+				"in": "path"
+			},
+			{
+				"name": "metric",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "window",
+				"description": "",
+				"required": true,
+				"type": "string",
+				"in": "body"
+			},
+			{
+				"name": "threshold",
+				"description": "Must be greater than zero.",
+				"required": true,
+				"type": "number",
+				"in": "body"
+			}
+		]
+	},
+	"delete-project-usage-threshold": {
+		serviceClass: "Projects",
+		operationId: "deleteProjectUsageThreshold",
+		description: "Stops the alert. Requires the admin role.",
+		moduleDocsUrl: "https://docs.naturali.ai/docs/modules/projects",
+		httpMethod: "delete",
+		pathParams: ["project_id", "threshold_id"],
+		queryParams: [],
+		flags: [{
+			"name": "project_id",
+			"description": "Project public ID (proj_ prefix).",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}, {
+			"name": "threshold_id",
+			"description": "",
+			"required": true,
+			"type": "string",
+			"in": "path"
+		}]
+	},
 	"list-quotas": {
 		serviceClass: "Quotas",
 		operationId: "listQuotas",

package/package.json

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