@enerlence/suntropy-cli 0.12.0 → 0.14.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)();
@@ -4645,6 +4645,21 @@ async function call(client, method, path, options = {}) {
   });
   return res.data?.data;
 }
+async function callMultipart(client, path, filePath, payload, params) {
+  const FormData = (await import("form-data")).default;
+  const form = new FormData();
+  form.append("file", readFileSync6(filePath), { filename: filePath.split("/").pop() });
+  if (payload) form.append("payload", JSON.stringify(payload));
+  const res = await client.request({
+    method: "post",
+    url: path,
+    params: dropEmpty(params),
+    data: form,
+    headers: form.getHeaders(),
+    maxBodyLength: Infinity
+  });
+  return res.data?.data;
+}
 function dropEmpty(params) {
   if (!params) return void 0;
   return Object.fromEntries(
@@ -4753,7 +4768,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 +4846,94 @@ 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));
+    }
+  });
+  const columnFlag = (value) => value ? { column: value } : void 0;
+  const columnsList = (value) => value ? value.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  campaigns.command("excel-preview <file>").summary("Headers and first rows of an Excel, to decide the column mapping.").description(
+    'Reads the first sheet of an .xlsx (headers in row 1) and returns `headers`,\n`sampleRows` and `totalRows`, without creating anything. Run it before\n`create-from-excel` to see which column holds the name, the address parts,\nthe coordinates ("lat,lng"), the phone, the website or the email.\n\nExample:\n  suntropy satvolt campaigns excel-preview empresas.xlsx --sample 10 --format human'
+  ).option("--sample <n>", "Rows to return (1-50, default 5)").action(async (file, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await callMultipart(satvoltClient(global), "/campaigns/excel/preview", file, void 0, {
+        sampleSize: opts.sample !== void 0 ? parseIntOption(opts.sample, "--sample") : void 0
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("excel-geocode-test <file>").summary("Geocode the first rows with the chosen address columns, before creating.").description(
+    'When the Excel has no coordinates, the campaign geocodes each row from the\ncolumns you choose (concatenated with commas). This runs that geocoding on the\nfirst rows only and shows the query, the coordinates and the formatted address\nfound, so you can check the columns are right before paying for every lead.\nCosts one Google geocoding request per sampled row.\n\nExample:\n  suntropy satvolt campaigns excel-geocode-test empresas.xlsx \\\n    --columns "Direcci\xF3n,CP,Municipio" --region Cantabria --sample 5 --format human'
+  ).requiredOption("--columns <headers>", "Comma-separated Excel headers that form the address, in order").option("--sample <n>", "Rows to test (1-25, default 5)").option("--region <text>", "Region appended to every query to disambiguate (province, country)").action(async (file, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const data = await callMultipart(satvoltClient(global, 12e4), "/campaigns/excel/geocode-test", file, {
+        columns: columnsList(opts.columns),
+        sampleSize: opts.sample !== void 0 ? parseIntOption(opts.sample, "--sample") : void 0,
+        region: opts.region
+      });
+      output(data, global);
+    } catch (err) {
+      outputError(satvoltError(err));
+    }
+  });
+  campaigns.command("create-from-excel <file>").summary("Create a campaign whose leads come from an Excel (no Maps search).").description(
+    'Imports the rows of the first sheet as leads (one row = one lead) and builds the\npipeline on them. The campaign stays queued unless --start is passed, and it\ncannot be extended later: the leads are fixed at creation.\n\nMapping (see `excel-preview` for the headers):\n  --name-column <h>            required: commercial name of the business\n  --coordinates-column <h>     column with "lat,lng"  \u2014 OR \u2014\n  --geocode-columns <h1,h2>    address columns to geocode per lead (GEOCODE_ADDRESS,\n                               10 credits per lead; test them with excel-geocode-test)\n  --address-columns <h1,h2>    address shown on the lead (joined with ", ")\n  --phone-column, --url-column, --email-column, --type-column <h>\n  --country <text>             literal applied to every row\n  --mapping <json|@file>       full columnMapping object instead of the flags above\n\nPipeline: --template, --from-campaign or --steps, as in `campaigns create`.\n\nExamples:\n  suntropy satvolt campaigns create-from-excel empresas.xlsx --name "Clientes CRM" \\\n    --name-column Empresa --geocode-columns "Direcci\xF3n,CP,Municipio" --region Cantabria \\\n    --template "Industria" --max-leads 100\n  suntropy satvolt campaigns create-from-excel leads.xlsx --name "Con coordenadas" \\\n    --name-column Nombre --coordinates-column Coordenadas --phone-column Tel\xE9fono \\\n    --steps @steps.json'
+  ).requiredOption("--name <name>", "Campaign name").option("--name-column <header>", "Column with the commercial name (required unless --mapping)").option("--coordinates-column <header>", 'Column with "lat,lng" coordinates').option("--geocode-columns <headers>", "Comma-separated address columns to geocode when there are no coordinates").option("--address-columns <headers>", "Comma-separated columns joined as the lead address").option("--phone-column <header>", "Column with the phone").option("--url-column <header>", "Column with the website").option("--email-column <header>", "Column with the email (stored in fullData.importMetadata.email)").option("--type-column <header>", "Column with the business type (googlePlacesType)").option("--country <text>", "Country applied to every lead").option("--mapping <json>", "columnMapping as JSON, @file or - (overrides the *-column flags)").option("--template <idOrName>", "Base the pipeline on a campaign template").option("--from-campaign <id>", "Copy the pipeline of another campaign").option("--steps <json>", "LEAD steps as JSON array, @file or -").option("--max-leads <n>", "Import only the first n rows").option("--region <text>", "Region of the leads (also biases the geocoding)").option("--description <text>", "Natural language description of the configuration").option("--start", "Start the pipeline right after creating it (spends credits)").action(async (file, opts) => {
+    const global = getGlobalOpts17(campaigns);
+    try {
+      const columnMapping = opts.mapping ? readJsonArg(opts.mapping, "--mapping") : {
+        commercialName: columnFlag(opts.nameColumn),
+        coordinates: columnFlag(opts.coordinatesColumn),
+        address: columnsList(opts.addressColumns)?.map((column) => ({ column })),
+        phone: columnFlag(opts.phoneColumn),
+        url: columnFlag(opts.urlColumn),
+        email: columnFlag(opts.emailColumn),
+        googlePlacesType: columnFlag(opts.typeColumn),
+        country: opts.country ? { literal: opts.country } : void 0
+      };
+      if (!columnMapping.commercialName) throw new Error("--name-column is required (or a --mapping with commercialName)");
+      const geocodeColumns = columnsList(opts.geocodeColumns);
+      if (!columnMapping.coordinates && !geocodeColumns) {
+        throw new Error("Pass --coordinates-column <header> or --geocode-columns <h1,h2,...>");
+      }
+      if (opts.template && opts.fromCampaign) throw new Error("Use either --template or --from-campaign, not both");
+      const payload = {
+        name: opts.name,
+        columnMapping,
+        geocoding: geocodeColumns ? { enabled: true, columns: geocodeColumns } : void 0,
+        templateId: opts.template,
+        fromCampaignId: opts.fromCampaign ? parseId(opts.fromCampaign, "--from-campaign") : void 0,
+        steps: opts.steps ? readJsonArg(opts.steps, "--steps") : void 0,
+        maxLeads: opts.maxLeads !== void 0 ? parseIntOption(opts.maxLeads, "--max-leads") : void 0,
+        region: opts.region,
+        description: opts.description,
+        start: opts.start ? true : void 0
+      };
+      const data = await callMultipart(satvoltClient(global, 3e5), "/campaigns/from-excel", file, payload);
+      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 +4955,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 +5856,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 +5982,10 @@ var WRITE_VERBS = /* @__PURE__ */ new Set([
   "duplicate",
   "extend",
   "move",
-  "reorder"
+  "reorder",
+  "pause",
+  "unpause",
+  "cancel"
 ]);
 var PATH_OVERRIDES = {
   "studies calculate production": "write"
@@ -5928,7 +6095,7 @@ function registerCommandProfileCommand(program2) {
 }
 
 // src/index.ts
-var CLI_VERSION = true ? "0.12.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.14.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)");