@soat/cli 0.15.2 → 0.15.4

package/dist/index.mjs

@@ -11,7 +11,7 @@ import { load } from "js-yaml";
 import * as os from "node:os";
 
 //#region package.json
-var version = "0.15.2";
+var version = "0.15.4";
 
 //#endregion
 //#region src/cli-wrappers/wrappers/formations.ts
@@ -2166,13 +2166,25 @@ var routes = {
     description: "Returns all documents the caller has access to. If projectId is provided, returns only documents in that project. project keys are scoped to a single project automatically. JWT users without projectId receive documents across all their accessible projects.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/documents",
     pathParams: [],
-    queryParams: ["project_id"],
+    queryParams: ["project_id", "limit", "offset"],
     flags: [{
       "name": "project_id",
       "description": "Project ID (optional)",
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "limit",
+      "description": "Maximum number of results to return",
+      "required": false,
+      "type": "integer",
+      "in": "query"
+    }, {
+      "name": "offset",
+      "description": "Number of results to skip",
+      "required": false,
+      "type": "integer",
+      "in": "query"
     }]
   },
   "create-document": {
@@ -5154,7 +5166,7 @@ var routes = {
     description: "Returns the raw usage-meter rows the caller can access, most recent first, optionally filtered by agent and generation. Each row is the per-generation token usage as reported by the provider, for audit and reconciliation.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
     pathParams: [],
-    queryParams: ["agent_id", "generation_id", "trace_id", "trigger_id", "action_id", "limit", "offset"],
+    queryParams: ["agent_id", "generation_id", "trace_id", "trigger_id", "action_id", "meter_type", "limit", "offset"],
     flags: [{
       "name": "agent_id",
       "description": "Filter by agent public ID",
@@ -5185,6 +5197,12 @@ var routes = {
       "required": false,
       "type": "string",
       "in": "query"
+    }, {
+      "name": "meter_type",
+      "description": "Filter by meter type (e.g. `llm_tokens`, `compute_execution`, `api_request`, `storage`)\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
     }, {
       "name": "limit",
       "description": "",
@@ -5199,17 +5217,119 @@ var routes = {
       "in": "query"
     }]
   },
+  "get-usage": {
+    serviceClass: "Usage",
+    operationId: "getUsage",
+    description: "Returns a project's usage rolled up over an optional `[from, to]` time window, bucketed by a single dimension. Each group and the grand total carry summed token counts and `cost_usd` (null when no event in the bucket was priced). This is the per-project cost-by-range/by-category query — a monthly figure without scanning raw meter rows client-side.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
+    pathParams: [],
+    queryParams: ["project_id", "group_by", "from", "to"],
+    flags: [{
+      "name": "project_id",
+      "description": "Project public ID to aggregate usage for",
+      "required": true,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "group_by",
+      "description": "Dimension to bucket by. `day` buckets on the event's UTC calendar day; the others bucket on the matching column.\n",
+      "required": true,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "from",
+      "description": "Inclusive lower bound (ISO-8601 timestamp) on the event created_at. Omit for no lower bound.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "to",
+      "description": "Inclusive upper bound (ISO-8601 timestamp) on the event created_at. Omit for no upper bound.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
+  },
+  "list-usage-thresholds": {
+    serviceClass: "Usage",
+    operationId: "listUsageThresholds",
+    description: "Lists the usage alert thresholds the caller can access, optionally filtered by project_id. Each threshold fires the `usage.threshold_crossed` webhook when a project's cost or token usage over a calendar-month or rolling-24h window crosses the configured value.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
+    pathParams: [],
+    queryParams: ["project_id"],
+    flags: [{
+      "name": "project_id",
+      "description": "Filter by project public ID",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }]
+  },
+  "create-usage-threshold": {
+    serviceClass: "Usage",
+    operationId: "createUsageThreshold",
+    description: "Creates a usage alert threshold on a project. Thresholds are immutable apart from deletion — to change one, delete and recreate it (which resets its fire state).",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
+    pathParams: [],
+    queryParams: [],
+    flags: [{
+      "name": "project_id",
+      "description": "",
+      "required": true,
+      "type": "string",
+      "in": "body"
+    }, {
+      "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 0",
+      "required": true,
+      "type": "number",
+      "in": "body"
+    }]
+  },
+  "delete-usage-threshold": {
+    serviceClass: "Usage",
+    operationId: "deleteUsageThreshold",
+    description: "Deletes a usage threshold, resetting its fire state. Recreating a threshold starts its once-per-window / hysteresis state fresh.",
+    moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
+    pathParams: ["threshold_id"],
+    queryParams: [],
+    flags: [{
+      "name": "threshold_id",
+      "description": "Threshold public ID",
+      "required": true,
+      "type": "string",
+      "in": "path"
+    }]
+  },
   "get-usage-receipt": {
     serviceClass: "Usage",
     operationId: "getUsageReceipt",
-    description: "Returns a billing receipt for a completed generation: per-model line items (tokens, the price-book version that priced them, and cost) plus totals.",
+    description: "Returns a billing receipt. Pass generation_id for a per-generation receipt, or run_id for a per-run receipt summed across the orchestration run's meters — both share the same shape (per-model line items with tokens, the price-book version that priced them, and cost, plus totals). Exactly one of generation_id or run_id must be supplied.",
     moduleDocsUrl: "https://soat.ttoss.dev/docs/modules/usage",
     pathParams: [],
-    queryParams: ["generation_id"],
+    queryParams: ["generation_id", "run_id"],
     flags: [{
       "name": "generation_id",
-      "description": "Generation public ID",
-      "required": true,
+      "description": "Generation public ID. Mutually exclusive with run_id.\n",
+      "required": false,
+      "type": "string",
+      "in": "query"
+    }, {
+      "name": "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"
     }]
@@ -5615,6 +5735,21 @@ var parseFlagValue = value => {
   }
   return value;
 };
+/**
+* Build the value for an array-typed flag. Collects repeated occurrences
+* (`--document_paths /a/ --document_paths /b/`) into a list, coercing each
+* element with `parseFlagValue`. A single JSON-array literal
+* (`--document_ids '["doc_1","doc_2"]'`) is passed through as-is rather than
+* being wrapped again, and a single scalar (`--document_paths /playbooks/`)
+* becomes a one-element array.
+*/
+var buildArrayFlagValue = rawValues => {
+  const parsed = rawValues.map(v => {
+    return parseFlagValue(v);
+  });
+  if (parsed.length === 1 && Array.isArray(parsed[0])) return parsed[0];
+  return parsed;
+};
 /** Normalize symbol names to compare exports across acronym casing differences. */
 var normalizeSymbol = name => {
   return name.toLowerCase().replace(/[^a-z0-9]/g, "");
@@ -5799,13 +5934,17 @@ program.argument("[command]", "API command in kebab-case (e.g. list-actors)").ar
     })
   });
   const flags = wrapped.flags.single;
+  const repeatedFlags = wrapped.flags.repeated;
+  const flagTypeByCanonical = new Map(route.flags.map(f => {
+    return [toCanonical(f.name), f.type];
+  }));
   const pathArgs = {};
   const queryArgs = {};
   const bodyArgs = {};
   for (const [flagKey, val] of Object.entries(flags)) {
     if (flagKey === "profile" || flagKey === "id") continue;
     const canonical = toCanonical(flagKey);
-    const parsedValue = parseFlagValue(val);
+    const parsedValue = flagTypeByCanonical.get(canonical) === "array" ? buildArrayFlagValue(repeatedFlags[flagKey] ?? [val]) : parseFlagValue(val);
     const pathParam = route.pathParams.find(p => {
       return toCanonical(p) === canonical;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soat/cli",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "type": "module",
   "dependencies": {
     "@inquirer/input": "^5.1.2",
@@ -8,7 +8,7 @@
     "@ttoss/logger": "^0.8.19",
     "commander": "^15.0.0",
     "js-yaml": "^5.2.1",
-    "@soat/sdk": "0.15.2"
+    "@soat/sdk": "0.15.4"
   },
   "devDependencies": {
     "@ttoss/config": "^1.37.17",