@enerlence/suntropy-cli 0.12.0 → 0.13.0

package/dist/bin/suntropy.js

@@ -1872,7 +1872,7 @@ function registerInventoryCommands(program2) {
 import { Option } from "commander";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync4, existsSync as existsSync2 } from "fs";
 
-// node_modules/uuid/dist/esm-node/rng.js
+// ../suntropy-cli/node_modules/uuid/dist/esm-node/rng.js
 import crypto from "crypto";
 var rnds8Pool = new Uint8Array(256);
 var poolPtr = rnds8Pool.length;
@@ -1884,16 +1884,16 @@ function rng() {
   return rnds8Pool.slice(poolPtr, poolPtr += 16);
 }
 
-// node_modules/uuid/dist/esm-node/regex.js
+// ../suntropy-cli/node_modules/uuid/dist/esm-node/regex.js
 var regex_default = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i;
 
-// node_modules/uuid/dist/esm-node/validate.js
+// ../suntropy-cli/node_modules/uuid/dist/esm-node/validate.js
 function validate(uuid) {
   return typeof uuid === "string" && regex_default.test(uuid);
 }
 var validate_default = validate;
 
-// node_modules/uuid/dist/esm-node/stringify.js
+// ../suntropy-cli/node_modules/uuid/dist/esm-node/stringify.js
 var byteToHex = [];
 for (let i = 0; i < 256; ++i) {
   byteToHex.push((i + 256).toString(16).substr(1));
@@ -1907,7 +1907,7 @@ function stringify(arr, offset = 0) {
 }
 var stringify_default = stringify;
 
-// node_modules/uuid/dist/esm-node/v4.js
+// ../suntropy-cli/node_modules/uuid/dist/esm-node/v4.js
 function v4(options, buf, offset) {
   options = options || {};
   const rnds = options.random || (options.rng || rng)();
@@ -4753,7 +4753,7 @@ function buildArea(opts) {
   return { type: "polygon", coordinates: parsed };
 }
 function registerSatvoltCampaignCommands(satvolt) {
-  const campaigns = satvolt.command("campaigns").description("Satvolt campaigns: list, create from an area, start, reset, resume, usage, logs and funnel.");
+  const campaigns = satvolt.command("campaigns").description("Satvolt campaigns: list, create from an area, start, pause, cancel, reset, resume, usage, logs and funnel.");
   campaigns.command("list").description(
     'List campaigns, newest first.\nExamples:\n  suntropy satvolt campaigns list --state completed,inProgress\n  suntropy satvolt campaigns list --search "Alcobendas" --format human'
   ).option("--limit <n>", "Max results (max 200)", "50").option("--offset <n>", "Skip results", "0").option("--search <text>", "Match name, region or input address").option("--state <states>", "Comma-separated campaign states (see: satvolt catalog states)").option("--source <source>", "maps | excel | campaign").action(async (opts) => {
@@ -4831,6 +4831,25 @@ search query and lead limit come from it; any flag you pass wins.
       outputError(satvoltError(err));
     }
   });
+  campaigns.command("estimate").summary("Count the businesses a campaign would find over an area, without creating it.").description(
+    'Preview of FIND_LEADS: how many businesses Google Maps returns inside the area with\nthe given business groups (nearby search) or text query, plus a sample to inspect.\nNothing is created and no credits are spent. Use it to iterate the filters before\n`campaigns create`: check `places.atLeast`, `byType` and the `sample` names, then\ntighten or widen --business-groups until the sample looks like the target.\n\nThe count is a minimum: the preview has a request budget and is cached (7 days) per\narea, groups and query; `places.exhaustive:false` means dense zones were left out.\nA text query matches place NAMES, not categories ("manufactura" only finds businesses\ncalled "Manufacturas \u2026"): for a category, use business groups without --search-query.\n\nArea (exactly one): --circle <lat,lng> --radius <m> | --bounds <nwLat,nwLng,seLat,seLng>\n| --polygon <json|@file|->. Base (optional): --template or --from-campaign give the\ngroups and query when not passed explicitly.\n\nExamples:\n  suntropy satvolt campaigns estimate --circle 43.3934,-3.8445 --radius 1500 \\\n    --business-groups businesses --format human\n  suntropy satvolt campaigns estimate --circle 43.3934,-3.8445 --radius 1500 \\\n    --business-groups industrial_logistics,automotive --sample 50\n  suntropy satvolt campaigns estimate --bounds 40.45,-3.70,40.44,-3.68 --template "Industria"'
+  ).option("--circle <lat,lng>", "Circle center").option("--radius <meters>", "Circle radius in meters").option("--bounds <nwLat,nwLng,seLat,seLng>", "Rectangle corners").option("--polygon <json>", "Polygon points, GeoJSON, @file or - for stdin").option("--template <idOrName>", "Take business groups and query from a campaign template").option("--from-campaign <id>", "Take business groups and query from another Maps campaign").option("--business-groups <ids>", "Comma-separated group ids or raw Google Places types. See: satvolt catalog business-groups").option("--search-query <text>", "Places text search with this query instead of nearby search (matches names, not categories)").option("--sample <n>", "Sample places to return (1-100, default 20)").option("--offset <n>", "Skip this many sample places (to page through them)").action(async (opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const body = { area: buildArea(opts) };
+      if (opts.template && opts.fromCampaign) throw new Error("Use either --template or --from-campaign, not both");
+      if (opts.template) body.templateId = opts.template;
+      if (opts.fromCampaign) body.fromCampaignId = parseId(opts.fromCampaign, "--from-campaign");
+      if (opts.businessGroups) body.businessGroups = opts.businessGroups.split(",").map((s) => s.trim()).filter(Boolean);
+      if (opts.searchQuery) body.searchQuery = opts.searchQuery;
+      if (opts.sample !== void 0) body.sample = parseIntOption(opts.sample, "--sample");
+      if (opts.offset !== void 0) body.offset = parseIntOption(opts.offset, "--offset");
+      const data = await call(satvoltClient(global, 12e4), "post", "/campaigns/estimate", { data: body });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
   campaigns.command("delete <campaignId>").summary("Delete a campaign and everything it generated (irreversible, --yes).").description(
     "Delete a campaign with its sectors, leads, step executions, pipeline configuration\nand queued jobs. Irreversible. Export tables of the campaign stop working.\nExample:\n  suntropy satvolt campaigns delete 63 --yes"
   ).option("--yes", "Confirm the deletion (required)").action(async (campaignId, opts) => {
@@ -4852,6 +4871,40 @@ search query and lead limit come from it; any flag you pass wins.
       outputError(satvoltError(err));
     }
   });
+  campaigns.command("pause <campaignId>").summary("Pause a running campaign: nothing else runs or is charged until unpause.").description(
+    "Pause a running campaign. Queued work is withdrawn and steps already in flight\nfinish without queuing their successors, so no more credits are spent. Results\nof async steps whose webhook arrives meanwhile are kept. Only a running\ncampaign (inProgress, sectorized, leadsFound, analyzed) can be paused;\notherwise 409 INVALID_CAMPAIGN_STATE.\nExample:\n  suntropy satvolt campaigns pause 72"
+  ).action(async (campaignId) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await call(satvoltClient(global, 12e4), "post", `/campaigns/${parseId(campaignId, "campaignId")}/pause`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("unpause <campaignId>").summary("Resume a paused campaign where it stopped (no step is run twice).").description(
+    "Resume a paused campaign where it stopped: every lead that is not finished gets\nits next pending step queued, and steps already executed are neither re-run\nnor charged again. Only a paused campaign can be unpaused. This is not\n`resume`, which appends a NEW step to a finished campaign.\nExample:\n  suntropy satvolt campaigns unpause 72"
+  ).action(async (campaignId) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await call(satvoltClient(global, 12e4), "post", `/campaigns/${parseId(campaignId, "campaignId")}/unpause`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("cancel <campaignId>").summary("Cancel a running or paused campaign for good, keeping its leads and data (--yes).").description(
+    "Cancel a running, paused or queued campaign. Irreversible: it cannot be unpaused\nor started again (reset relaunches it from scratch, deleting the leads). Leads\nand the data already enriched are kept, can be exported and are still charged.\nExample:\n  suntropy satvolt campaigns cancel 72 --yes"
+  ).option("--yes", "Confirm the cancellation (required)").action(async (campaignId, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      if (!opts.yes) throw new Error("Cancelling a campaign is irreversible. Re-run with --yes to confirm.");
+      const data = await call(satvoltClient(global, 12e4), "post", `/campaigns/${parseId(campaignId, "campaignId")}/cancel`);
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
   campaigns.command("reset <campaignId>").summary("Relaunch a campaign from scratch: deletes its leads and results (--yes).").description(
     "Relaunch a campaign from scratch: deletes its sectors, leads and processing data\nand returns it to queued, keeping the configuration. Excel/campaign-sourced\ncampaigns keep their imported leads. Irreversible.\nExample:\n  suntropy satvolt campaigns reset 59 --yes --start"
   ).option("--start", "Start the pipeline again after resetting").option("--yes", "Confirm the reset (required)").action(async (campaignId, opts) => {
@@ -5719,13 +5772,40 @@ Typical flow:
   satvolt export-tables create <id> ... \xB7 satvolt export-tables export <tableId>
   satvolt campaigns resume <id> --action AI_AGENT --config @step.json
   satvolt templates create --name <n> --from-campaign <id> \xB7 campaigns create --template <n>
-  satvolt campaigns extend <id> --max-leads N \xB7 leads run-step <id> <leadId> <step>`
+  satvolt campaigns extend <id> --max-leads N \xB7 leads run-step <id> <leadId> <step>
+  satvolt campaigns pause <id> \xB7 unpause <id> \xB7 cancel <id> --yes
+  satvolt usage [--month YYYY-MM]              credits spent by the account this month`
   );
   registerSatvoltCampaignCommands(satvolt);
   registerSatvoltPipelineCommands(satvolt);
   registerSatvoltLeadCommands(satvolt);
   registerSatvoltExportTableCommands(satvolt);
   registerSatvoltTemplateCommands(satvolt);
+  satvolt.command("usage").summary("Credits spent by the whole account in a calendar month, by campaign and by step.").description(
+    "Credits spent by the whole account in a calendar month (UTC): total, previous\nmonth for comparison, and the breakdown by campaign and by step. It sums every\ncharge in the period, including the Google Maps search (FIND_LEADS), so it\ndoes not have to match `campaigns usage`, which reconstructs the cost of one\ncampaign and leaves the search out.\nExamples:\n  suntropy satvolt usage\n  suntropy satvolt usage --month 2026-08 --format human"
+  ).option("--month <YYYY-MM>", "Month to report (default: current month)").action(async (opts) => {
+    const global = getGlobalOpts17(satvolt);
+    try {
+      if (opts.month !== void 0 && !/^\d{4}-\d{2}$/.test(String(opts.month))) {
+        throw new Error("--month must be YYYY-MM, e.g. 2026-08");
+      }
+      const data = await call(satvoltClient(global, 12e4), "get", "/usage", { params: { month: opts.month } });
+      if (global.format === "human" || global.format === "csv") {
+        if (global.format === "human") {
+          process.stderr.write(
+            `${data.month}: ${data.credits} credits \xB7 ${data.executions} executions \xB7 previous month (${data.previous.month}): ${data.previous.credits} credits
+
+`
+          );
+        }
+        output(data.byCampaign, global);
+        return;
+      }
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
   const catalog = satvolt.command("catalog").description("Reference data for building campaigns and pipelines.");
   const catalogEntries = [
     ["actions", "/catalog/actions", "Pipeline actions: credits per lead (fixed per action; failed or skipped runs are free), dependencies, multiple, and the JSON Schema of their config (the input). The data each step writes: satvolt export-tables fields <campaignId>."],
@@ -5818,7 +5898,10 @@ var WRITE_VERBS = /* @__PURE__ */ new Set([
   "duplicate",
   "extend",
   "move",
-  "reorder"
+  "reorder",
+  "pause",
+  "unpause",
+  "cancel"
 ]);
 var PATH_OVERRIDES = {
   "studies calculate production": "write"
@@ -5928,7 +6011,7 @@ function registerCommandProfileCommand(program2) {
 }
 
 // src/index.ts
-var CLI_VERSION = true ? "0.12.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.13.0" : "0.0.0-dev";
 function createProgram() {
   const program2 = new Command4();
   program2.name("suntropy").description("Agent-first CLI for Suntropy solar platform. Optimized for programmatic data manipulation and progressive exploration.").version(CLI_VERSION).option("--format <format>", "Output format: json (default), human, csv", "json").option("--fields <fields>", "Comma-separated fields to include in output").option("--server <url>", "Override API server URL").option("--token <jwt>", "Override authentication token").option("--profile <name>", "Use a specific config profile").option("--verbose", "Show HTTP request/response details on stderr").option("--quiet", "Suppress non-data output").option("--save <file>", "Save output to file (also writes to stdout)");