@epilot/cli 0.1.101 → 0.1.103

package/README.md

@@ -29,7 +29,7 @@ npm install -g @epilot/cli
 
 <!-- usage-help -->
 ```
-epilot v0.1.101 — CLI for epilot APIs
+epilot v0.1.103 — CLI for epilot APIs
 
 USAGE
   epilot <api> <operationId> [params...] [flags]

package/definitions/email-settings.json

@@ -1348,10 +1348,22 @@
       "post": {
         "operationId": "createSmtpConnection",
         "summary": "createSmtpConnection",
-        "description": "Creates a new custom SMTP connection. Runs a live verify against the SMTP server\nbefore persisting; on failure the request is rejected and nothing is saved.\nThe password is encrypted via KMS before being written to DynamoDB.\n",
+        "description": "Creates a new custom SMTP connection. Runs a live verify against the SMTP server\nbefore persisting; on failure the request is rejected and nothing is saved. Pass\n`skip_test=true` to store the configuration untested instead.\n",
         "tags": [
           "Custom SMTP"
         ],
+        "parameters": [
+          {
+            "name": "skip_test",
+            "in": "query",
+            "required": false,
+            "description": "Save without running the live verify. Use when the server is not reachable from\nepilot yet, or when a referenced `{{ env.* }}` secret has not been set. The\nconnection is stored untested — `last_test_status` is left unset rather than\nclaimed as `ok` — and env references are not resolved either, since an\nunresolvable one is expected in this case.\n",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -1428,10 +1440,22 @@
       "put": {
         "operationId": "updateSmtpConnection",
         "summary": "updateSmtpConnection",
-        "description": "Partial update; omitted fields keep their existing values. The merged\nconfiguration is verified against the SMTP server before persisting.\n",
+        "description": "Partial update; omitted fields keep their existing values. The merged\nconfiguration is verified against the SMTP server before persisting. Pass\n`skip_test=true` to store it untested instead, which also clears any previous\ntest result — it described a configuration that no longer applies.\n",
         "tags": [
           "Custom SMTP"
         ],
+        "parameters": [
+          {
+            "name": "skip_test",
+            "in": "query",
+            "required": false,
+            "description": "Save without running the live verify. Use when the server is not reachable from\nepilot yet, or when a referenced `{{ env.* }}` secret has not been set. The\nconnection is stored untested — `last_test_status` is left unset rather than\nclaimed as `ok` — and env references are not resolved either, since an\nunresolvable one is expected in this case.\n",
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
@@ -3335,8 +3359,8 @@
             "description": "Hostname of the SMTP server (e.g. smtp.mailgun.org)"
           },
           "smtp_port": {
-            "type": "integer",
-            "description": "SMTP port (typically 587 for STARTTLS or 465 for TLS)"
+            "type": "string",
+            "description": "SMTP port (typically 587 for STARTTLS or 465 for TLS). A string, because it\nmay hold a `{{ env.your_key }}` reference rather than a literal port.\n"
           },
           "smtp_secure": {
             "type": "string",
@@ -3408,9 +3432,17 @@
             "type": "string"
           },
           "smtp_port": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 65535
+            "description": "A port between 1 and 65535, or a `{{ env.your_key }}` template resolving to\none. An integer is still accepted, so callers predating the template support\nkeep working.\n",
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            ]
           },
           "smtp_secure": {
             "type": "string",
@@ -3437,9 +3469,17 @@
             "type": "string"
           },
           "smtp_port": {
-            "type": "integer",
-            "minimum": 1,
-            "maximum": 65535
+            "description": "A port between 1 and 65535, or a `{{ env.your_key }}` template resolving to\none. An integer is still accepted, so callers predating the template support\nkeep working.\n",
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 65535
+              }
+            ]
           },
           "smtp_secure": {
             "type": "string",

package/definitions/integration-toolkit.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Integration Toolkit API",
-    "version": "1.10.0",
+    "version": "1.12.0",
     "description": "API for integrating with external systems in a standardised way."
   },
   "tags": [
@@ -3744,7 +3744,7 @@
       "post": {
         "operationId": "createErpImport",
         "summary": "createErpImport",
-        "description": "Create a pricing-file import job from an already-uploaded file (S3 ref). Returns a job id and starts the validate phase asynchronously — poll GET /v2/erp/imports/{importId}.",
+        "description": "Register an already-uploaded file (S3 ref) as a pricing-file import job and return its id. Nothing runs yet: no use case is chosen and no validation starts here. Rank the candidates with POST /v2/erp/imports/{importId}:suggest-use-cases, then start the validate phase with POST /v2/erp/imports/{importId}:validate.",
         "tags": [
           "erp-imports"
         ],
@@ -3873,6 +3873,114 @@
         }
       }
     },
+    "/v2/erp/imports/{importId}:validate": {
+      "post": {
+        "operationId": "validateErpImport",
+        "summary": "validateErpImport",
+        "description": "Choose the use case to read this file with, and start the validate phase.\nCallable from PENDING, READY and FAILED — so a wrong choice is corrected by calling this again with a different use case, rather than re-uploading. Each call replaces any previous verdict. Any other status returns 409.",
+        "tags": [
+          "erp-imports"
+        ],
+        "parameters": [
+          {
+            "name": "importId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ValidateErpImportRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Validation started",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErpImportJob"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "422": {
+            "description": "The use case cannot drive an import",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
+    "/v2/erp/imports/{importId}:suggest-use-cases": {
+      "post": {
+        "operationId": "suggestErpImportUseCases",
+        "summary": "suggestErpImportUseCases",
+        "description": "Rank the org's inbound use cases against this file's columns — the input to the ranked picker (\"matches 6 of your 7 columns\"). Reads only the file's first row, not its data.\nEvery eligible use case is returned, including ones matching nothing: the \"nothing fits, pick anyway\" view needs the full list. Highest match first.\nCSV only — an xlsx import fails with 400 rather than silently returning zero matches, which would look identical to \"we checked and nothing matches\".",
+        "tags": [
+          "erp-imports"
+        ],
+        "parameters": [
+          {
+            "name": "importId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Ranked use-case suggestions",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SuggestErpImportUseCasesResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/InternalServerError"
+          }
+        }
+      }
+    },
     "/v2/erp/imports/{importId}:execute": {
       "post": {
         "operationId": "executeErpImport",
@@ -4009,25 +4117,85 @@
       },
       "CreateErpImportRequest": {
         "type": "object",
+        "description": "Register an already-uploaded file as an import. The use case is chosen later, via `:validate` — upload and interpretation are separate decisions.",
         "required": [
-          "s3_reference",
-          "integration_id"
+          "s3_reference"
         ],
+        "additionalProperties": false,
         "properties": {
           "s3_reference": {
             "$ref": "#/components/schemas/S3Reference"
+          }
+        }
+      },
+      "ValidateErpImportRequest": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "use_case_slug"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "integration_id": {
+            "type": "string"
           },
+          "use_case_slug": {
+            "type": "string",
+            "description": "An inbound use case's slug, unique within its integration."
+          }
+        }
+      },
+      "ErpImportUseCaseSuggestion": {
+        "type": "object",
+        "required": [
+          "integration_id",
+          "integration_name",
+          "use_case_slug",
+          "use_case_name",
+          "matched_columns",
+          "file_columns"
+        ],
+        "properties": {
           "integration_id": {
             "type": "string"
           },
+          "integration_name": {
+            "type": "string"
+          },
           "use_case_slug": {
             "type": "string"
+          },
+          "use_case_name": {
+            "type": "string"
+          },
+          "matched_columns": {
+            "type": "integer",
+            "description": "How many of the FILE's columns this use case reads, by exact trimmed name."
+          },
+          "file_columns": {
+            "type": "integer",
+            "description": "Columns in the file. Identical across entries; repeated per entry so each row renders standalone as \"matches N of your M columns\"."
+          }
+        }
+      },
+      "SuggestErpImportUseCasesResponse": {
+        "type": "object",
+        "required": [
+          "suggestions"
+        ],
+        "properties": {
+          "suggestions": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ErpImportUseCaseSuggestion"
+            }
           }
         }
       },
       "ExecuteErpImportRequest": {
         "type": "object",
         "description": "Confirmation options. Required only when the verdict carries warnings — a clean import needs no body at all.",
+        "additionalProperties": false,
         "properties": {
           "ack_warnings": {
             "type": "boolean",
@@ -4174,7 +4342,6 @@
         "required": [
           "import_id",
           "org_id",
-          "integration_id",
           "format",
           "status",
           "s3_input_ref",
@@ -4193,11 +4360,12 @@
             "type": "string"
           },
           "integration_id": {
-            "type": "string"
+            "type": "string",
+            "description": "The integration owning the chosen use case. Absent until the first `:validate`."
           },
           "use_case_slug": {
             "type": "string",
-            "description": "The inbound use case whose mapping drives both phases."
+            "description": "The inbound use case whose mapping drives both phases. Absent until the first `:validate`, and MUTABLE — re-validating with a different use case replaces it."
           },
           "format": {
             "type": "string",
@@ -4208,7 +4376,7 @@
           },
           "status": {
             "type": "string",
-            "description": "PENDING → VALIDATING → READY → PROCESSING → IMPORTED, with FAILED reachable from any working status, and CANCELLING → CANCELLED reachable from VALIDATING or PROCESSING via :abort. IMPORTED, FAILED and CANCELLED are terminal and final.\nIMPORTED means every row was handed to the platform, not that the platform finished — per-row outcomes live in monitoring, filtered by correlation_id. A file that fails validation is FAILED with error.code = VALIDATION_BLOCKED.\nREADY is legitimately idle for as long as the user takes to confirm, so it carries no running work and never goes stale.\nCANCELLING is transient and cooperative: the abort has been recorded but the worker only notices at its next batch boundary. Rows already published stay published — a stop is not a rollback.",
+            "description": "PENDING → VALIDATING → READY → PROCESSING → IMPORTED, with FAILED reachable from any working status, and CANCELLING → CANCELLED reachable from VALIDATING or PROCESSING via :abort. Only IMPORTED and CANCELLED are terminal. READY and FAILED both accept a further `:validate`, which is how a wrong use case is corrected without re-uploading the file.\nIMPORTED means every row was handed to the platform, not that the platform finished — per-row outcomes live in monitoring, filtered by correlation_id. A file that fails validation is FAILED with error.code = VALIDATION_BLOCKED.\nREADY is legitimately idle for as long as the user takes to confirm, so it carries no running work and never goes stale.\nCANCELLING is transient and cooperative: the abort has been recorded but the worker only notices at its next batch boundary. Rows already published stay published — a stop is not a rollback.",
             "enum": [
               "PENDING",
               "VALIDATING",

package/dist/bin/epilot.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "../chunk-CR6NZAXB.js";
+} from "../chunk-EDJKUCRC.js";
 
 // bin/epilot.ts
 import { runMain } from "citty";
@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.101",
+    version: "0.1.103",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -30,8 +30,8 @@ var main = defineCommand({
     auth: () => import("../auth-WMXFMPWE.js").then((m) => m.default),
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
-    completion: () => import("../completion-JKVTLZX7.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-SWIOU3HC.js").then((m) => m.default),
+    completion: () => import("../completion-RUUFYBPO.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-DYMWBKUC.js").then((m) => m.default),
     "access-token": () => import("../access-token-WWE6BDJH.js").then((m) => m.default),
     address: () => import("../address-EH3C4CVB.js").then((m) => m.default),
     "address-suggestions": () => import("../address-suggestions-RRSLOBFW.js").then((m) => m.default),
@@ -134,13 +134,13 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.101" : (await null).default.version;
+var VERSION = true ? "0.1.103" : (await null).default.version;
 var reorderedArgv = hoistFlagsAfterSubcommand(process.argv.slice(2));
 process.argv = [process.argv[0], process.argv[1], ...reorderedArgv];
 var args = process.argv.slice(2);
 var completionsIdx = args.indexOf("--_completions");
 if (completionsIdx >= 0) {
-  const { handleCompletions } = await import("../completion-JKVTLZX7.js");
+  const { handleCompletions } = await import("../completion-RUUFYBPO.js");
   handleCompletions(args[completionsIdx + 1], args[completionsIdx + 2]);
   process.exit(0);
 }

package/dist/{chunk-CR6NZAXB.js → chunk-EDJKUCRC.js}

@@ -860,7 +860,7 @@ var API_LIST = [
     kebabName: "integration-toolkit",
     title: "Integration Toolkit API",
     serverUrl: "https://integration-toolkit.sls.epilot.io",
-    operationCount: 61,
+    operationCount: 63,
     operationIds: [
       "acknowledgeTracking",
       "triggerErp",
@@ -921,6 +921,8 @@ var API_LIST = [
       "listErpImports",
       "createErpImport",
       "getErpImport",
+      "validateErpImport",
+      "suggestErpImportUseCases",
       "executeErpImport",
       "abortErpImport"
     ]

package/dist/{completion-JKVTLZX7.js → completion-RUUFYBPO.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   API_LIST
-} from "./chunk-CR6NZAXB.js";
+} from "./chunk-EDJKUCRC.js";
 import {
   DIM,
   GREEN,

package/dist/{upgrade-SWIOU3HC.js → upgrade-DYMWBKUC.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.101";
+  if (true) return "0.1.103";
   try {
     const output = execSync("npm ls -g @epilot/cli --depth=0 --json 2>/dev/null", {
       encoding: "utf-8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epilot/cli",
-  "version": "0.1.101",
+  "version": "0.1.103",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {