@enerlence/suntropy-cli 0.11.3 → 0.11.5

package/README.md

@@ -35,6 +35,27 @@ suntropy auth status
 > root command (e.g. `suntropy --profile dev auth status`). They apply to every
 > subcommand, including `auth`.
 
+### Token resolution order
+
+The auth token is resolved in this order (first non-empty wins):
+
+1. `--token <jwt>` global flag
+2. `SUNTROPY_API_KEY` environment variable
+3. `token` stored in the active profile (`~/.suntropy/config.json`, written by
+   `auth set-key` / `auth login`)
+
+The `SUNTROPY_API_KEY` fallback (available since `0.11.3`) lets a host runtime
+inject a just-in-time credential without a prior `auth login` / `auth set-key`:
+
+```bash
+SUNTROPY_API_KEY=<jwt> suntropy studies list
+```
+
+> ⚠️ The value must be a **JWT** (the one you'd pass to `auth set-key --key`),
+> since the CLI sends it as `Authorization: Bearer <token>`. Despite the name, it
+> is not a `shp_`/`devic-`-style API key — an invalid format yields a 401 from
+> the backend.
+
 ## Global Options
 
 | Option | Default | Description |
@@ -42,7 +63,7 @@ suntropy auth status
 | `--format json\|human\|csv` | `json` | Output format |
 | `--fields f1,f2,...` | all | Select specific fields |
 | `--server <url>` | config | Override API server URL |
-| `--token <jwt>` | config | Override auth token |
+| `--token <jwt>` | `SUNTROPY_API_KEY` env / config | Override auth token (see "Token resolution order") |
 | `--profile <name>` | default | Config profile |
 | `--verbose` | false | Show HTTP details on stderr |
 | `--quiet` | false | Suppress non-data output |

package/dist/bin/suntropy.js

@@ -139,6 +139,15 @@ function createUnauthClient(baseURL) {
     headers: { "Content-Type": "application/json" }
   });
 }
+var OBJECT_ID_RE = /^[a-f0-9]{24}$/i;
+function assertStudyObjectId(id) {
+  if (OBJECT_ID_RE.test(id)) return id;
+  const looksLikeUuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(id);
+  const hint = looksLikeUuid ? `It looks like a UUID (e.g. a chat or shareable uid), not a study _id.` : `A study _id is a 24-character hex MongoDB ObjectId.`;
+  throw new Error(
+    `Invalid study id: "${id}". ${hint} Get the correct id from \`suntropy studies list\` (the \`solarStudyId\` field).`
+  );
+}
 function assertFound(data, entity, id) {
   const isEmptyObject = data != null && typeof data === "object" && !Array.isArray(data) && Object.keys(data).length === 0;
   if (data == null || typeof data !== "object" || Array.isArray(data) || isEmptyObject) {
@@ -2275,6 +2284,7 @@ function registerStudyBuilderCommands(studies) {
     "Download an existing study from the backend into a local file.\nExample: suntropy studies pull abc123 --file /tmp/study.json"
   ).option("--file <path>", "Output file path").action(async (studyId, opts) => {
     try {
+      assertStudyObjectId(studyId);
       const filePath = resolveFile(opts);
       const global = getGlobalOpts7(studies);
       const client = createServiceClient("solar", global);
@@ -2635,7 +2645,7 @@ Examples:
   });
   set.command("economics").description(
     "Set economic parameters for the study.\nExample: suntropy studies set economics --file study.json --margin 15 --total-cost 6500 --lifetime 25"
-  ).option("--file <path>", "Study file path").option("--margin <n>", "Margin percentage").option("--total-cost <n>", "Total installation cost (\u20AC)").option("--lifetime <n>", "Installation lifetime in years").option("--inflation <n>", "Inflation rate percentage").option("--taxes-pct <n>", "Tax percentage").option("--include-taxes", "Include taxes in pricing").option("--commercial-fee <n>", "Commercial fee percentage").option("--excesses-mode <mode>", "Excesses compensation: gridSelling, PPA, noInjection, virtualBattery").option("--excesses-buy-price <n>", "Excesses buy price (\u20AC/MWh)").option("--excesses-selling-price <n>", "Excesses selling price (\u20AC/MWh)").option("--peak-power-cost <n>", "Cost per kWp (\u20AC/kWp)").option("--guarantee-production <n>", "Guarantee production percentage").action(async (opts) => {
+  ).option("--file <path>", "Study file path").option("--margin <n>", "Margin percentage").option("--total-cost <n>", "Total installation cost (\u20AC)").option("--lifetime <n>", "Installation lifetime in years").option("--inflation <n>", "Inflation rate percentage").option("--taxes-pct <n>", "Tax percentage").option("--include-taxes", "Include taxes in pricing").option("--commercial-fee <n>", "Commercial fee percentage").option("--excesses-mode <mode>", "Excesses compensation: gridSelling, PPA, noInjection, virtualBattery").option("--excesses-buy-price <n>", "Excesses buy price (\u20AC/MWh)").option("--excesses-selling-price <n>", "Excesses selling price (\u20AC/MWh)").option("--peak-power-cost <n>", "Cost per Wp (\u20AC/Wp). If --total-cost is omitted, totalCost is derived as cost \xD7 installed peak power (W)").option("--guarantee-production <n>", "Guarantee production percentage").action(async (opts) => {
     try {
       const result = updateStudy(resolveFile(opts), (study) => {
         const er = study.economicResults || {};
@@ -2651,6 +2661,30 @@ Examples:
         if (opts.excessesSellingPrice !== void 0) er.excessesSellingPrice = parseFloat(opts.excessesSellingPrice);
         if (opts.peakPowerCost !== void 0) er.peakPowerCost = parseFloat(opts.peakPowerCost);
         if (opts.guaranteeProduction !== void 0) er.guaranteeProductionPercentage = parseFloat(opts.guaranteeProduction);
+        if (opts.peakPowerCost !== void 0 && opts.totalCost === void 0) {
+          const surfaces = study.surfaces || [];
+          let totalWatts = 0;
+          let resolvedCount = 0;
+          let anyDefault = false;
+          for (const surface of surfaces) {
+            const { installedPower, isDefault } = resolveSurfaceInstalledPower(surface, study);
+            if (isDefault) {
+              anyDefault = true;
+              continue;
+            }
+            totalWatts += installedPower;
+            resolvedCount += 1;
+          }
+          if (resolvedCount > 0 && !anyDefault) {
+            er.totalCost = Math.round(parseFloat(opts.peakPowerCost) * totalWatts * 100) / 100;
+          } else {
+            process.stderr.write(
+              JSON.stringify({
+                warning: "Set --peak-power-cost but could not derive totalCost: " + (surfaces.length === 0 ? "the study has no surfaces." : "some surfaces have no resolvable installed power (set panels + kit/panel first).") + " Pass --total-cost explicitly to set it."
+              }) + "\n"
+            );
+          }
+        }
         study.economicResults = er;
         return void 0;
       });
@@ -3246,6 +3280,7 @@ Example: suntropy studies set data --file study.json --data '{"referenceId":"REF
     'Add a comment to an existing study via API.\nExample: suntropy studies comment abc123 --content "Revisado por agente"'
   ).requiredOption("--content <text>", "Comment text").addOption(new Option("--as-alexandria").hideHelp()).addOption(new Option("--reply-to-user <userUID>").hideHelp()).addOption(new Option("--reply-to-name <name>").hideHelp()).action(async (studyId, opts) => {
     try {
+      assertStudyObjectId(studyId);
       const global = getGlobalOpts7(studies);
       const client = createServiceClient("solar", global);
       const comment = createComment("commented", opts.content, {
@@ -3569,6 +3604,7 @@ function registerStudiesCommands(program2) {
   });
   studies.command("metadata <id>").description("Get solar study metadata by metadata ID (relational). Full MySQL record with state, costs, versions.").option("--by-study-id", "Interpret <id> as MongoDB solarStudyId instead of metadata ID").action(async (id, opts) => {
     try {
+      if (opts.byStudyId) assertStudyObjectId(id);
       const global = getGlobalOpts8(studies);
       const client = createServiceClient("solar", global);
       const path = opts.byStudyId ? `/solar-study/metadata/solar-study-id/${id}` : `/solar-study/findSolarStudyMetadataById/${id}`;
@@ -3582,6 +3618,7 @@ function registerStudiesCommands(program2) {
     "Get solar study by MongoDB ID. By default returns summary (no heavy curves).\nExpand sections: surfaces, results, economics, batteries, consumption, equipment, client, location\nExamples:\n  suntropy studies get abc123\n  suntropy studies get abc123 --expand surfaces,results\n  suntropy studies get abc123 --expand all\n  suntropy studies get abc123 --fields name,market  (bypasses expand filter)"
   ).option("--expand <sections>", 'Comma-separated sections to expand (or "all")').action(async (studyId, opts) => {
     try {
+      assertStudyObjectId(studyId);
       const global = getGlobalOpts8(studies);
       const client = createServiceClient("solar", global);
       const res = await client.get(`/solar-study/findById/${studyId}`);
@@ -3604,6 +3641,7 @@ function registerStudiesCommands(program2) {
     "Extract and analyze a PowerCurve from a study.\nCurve names: consumption, production, net-consumption, excesses\nDefault: --stats. Use --raw for full hourly data (8760 values).\nUse --monthly for monthly aggregates, --daily for daily totals."
   ).option("--stats", "Show statistics (default if no other flag)").option("--monthly", "Monthly accumulated values").option("--daily", "Daily accumulated values").option("--raw", "Full hourly DayCurve[] data").option("--total", "Just the total accumulated value").option("--surface-index <n>", "Surface index for production curve", "0").option("--save <file>", "Save curve data to file").action(async (studyId, curveName, opts) => {
     try {
+      assertStudyObjectId(studyId);
       const global = getGlobalOpts8(studies);
       const client = createServiceClient("solar", global);
       const res = await client.get(`/solar-study/findById/${studyId}`);
@@ -4598,7 +4636,7 @@ function registerCommandProfileCommand(program2) {
 }
 
 // src/index.ts
-var CLI_VERSION = true ? "0.11.3" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.11.5" : "0.0.0-dev";
 function createProgram() {
   const program2 = new Command3();
   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)");