@epilot/cli 0.1.147 → 0.1.148

package/README.md

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

package/definitions/integration-toolkit.json

@@ -2,7 +2,7 @@
   "openapi": "3.0.3",
   "info": {
     "title": "Integration Toolkit API",
-    "version": "1.22.0",
+    "version": "1.29.1",
     "description": "API for integrating with external systems in a standardised way."
   },
   "tags": [
@@ -3005,11 +3005,11 @@
         }
       }
     },
-    "/v1/entities/{entityId}/sync-status": {
+    "/v1/integrations/entities/{entityId}/sync-status": {
       "get": {
         "operationId": "getEntitySyncStatus",
         "summary": "getEntitySyncStatus",
-        "description": "Get the inbound ERP sync status of an entity: when each integration last\nsynchronized (checked) the entity against the ERP, and when it last\nactually changed it. `last_synced_at` also advances on no-op checks —\nevents that were received and evaluated but changed nothing — which by\ndesign leave no trace on the entity itself (no activity feed entry, no\n`_updated_at` bump). Use it to tell whether an entity is up to date with\nthe ERP. Returns an empty list for entities no inbound use case has\nprocessed. Org-scoped via the caller's token.\n",
+        "description": "Get the inbound ERP sync status of an entity: when each integration last\nsynchronized (checked) the entity against the ERP, and when it last\nactually changed it. `last_synced_at` also advances on no-op checks —\nevents that were received and evaluated but changed nothing — which by\ndesign leave no trace on the entity itself (no activity feed entry, no\n`_updated_at` bump). Use it to tell whether an entity is up to date with\nthe ERP. Returns an empty list for entities no inbound use case has\nprocessed. Org-scoped via the caller's token.\n\nDeprecated alias: `GET /v1/entities/{entityId}/sync-status` is still\nserved (rewritten to this path in the API handler) but will be removed —\nmigrate callers to this path.\n",
         "tags": [
           "integrations"
         ],
@@ -4191,7 +4191,7 @@
       "post": {
         "operationId": "createErpImport",
         "summary": "createErpImport",
-        "description": "Register an already-uploaded file (S3 ref) as a pricing-file import job. Returns the job and a file preview. Nothing runs yet: no use case is chosen and no validation starts here. Optionally rank candidates with POST /v2/erp/imports/{importId}:suggest-use-cases, then start validation with POST /v2/erp/imports/{importId}:validate.\nPass `import_id` to repoint an existing PENDING import at a different file instead, keeping its id and its place in the history.",
+        "description": "Register an already-uploaded file (S3 ref) as a pricing-file import job. Returns the job and a file preview. Nothing runs yet: no use case is chosen and no validation starts here. Optionally rank candidates with POST /v2/erp/imports/{importId}:suggest-use-cases, then start validation with POST /v2/erp/imports/{importId}:validate.\nPass `import_id` to repoint an existing import at a different file instead, keeping its id and its place in the history — allowed while the import has written nothing.",
         "tags": [
           "erp-imports"
         ],
@@ -4425,7 +4425,7 @@
             "$ref": "#/components/responses/Conflict"
           },
           "422": {
-            "description": "The use case cannot drive an import",
+            "description": "The check could not be run. `code` is the translation key.\n\n- `USE_CASE_NOT_USABLE` — missing, not inbound, disabled, or no mapping\n  configuration.\n- `SCHEMA_NOT_AUTHORITATIVE` — an entity schema could not be read. Retryable.\n\nA mapping that CAN be judged and is found wanting is not a 422: the job is\nrecorded FAILED with `error.code = VALIDATION_BLOCKED` and the detail in\n`validation.issues`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4488,7 +4488,7 @@
       "post": {
         "operationId": "executeErpImport",
         "summary": "executeErpImport",
-        "description": "Confirm and run the write phase of a validated import. Only a READY job may be executed; any other status returns 409.",
+        "description": "Confirm and run the write phase of a validated import. Only a READY job may be executed; any other status returns 409.\nThe verdict is re-checked against live inputs first: if the mapping or an entity schema changed since the check, this returns 409 `VALIDATION_STALE` and leaves the verdict untouched for `:validate` to re-form.",
         "tags": [
           "erp-imports"
         ],
@@ -4530,10 +4530,17 @@
             "$ref": "#/components/responses/NotFound"
           },
           "409": {
-            "$ref": "#/components/responses/Conflict"
+            "description": "The job cannot be executed as it stands. `code` is the translation key.\n\n- `IMPORT_NOT_READY` — the job is not READY, or a concurrent confirm won.\n- `VALIDATION_STALE` — the inputs the verdict was formed against have changed;\n  re-run `:validate`.\n\nNeither changes the job's status or its verdict.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponseBase"
+                }
+              }
+            }
           },
           "422": {
-            "description": "The verdict carries warnings and `ack_warnings` was not true",
+            "description": "The write could not be started. `code` is the translation key.\n\n- `WARNINGS_NOT_ACKNOWLEDGED` — the verdict carries warnings and `ack_warnings`\n  was not true.\n- `USE_CASE_NOT_USABLE` — the use case went missing, disabled, or lost its\n  mapping configuration after the check.\n- `SCHEMA_NOT_AUTHORITATIVE` — an entity schema could not be read. Retryable.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4636,7 +4643,7 @@
           },
           "import_id": {
             "type": "string",
-            "description": "Repoint an EXISTING import at this file instead of registering a new one — same row, same id, so iterating on which file to import leaves one entry in the history rather than one per attempt.\nOnly a PENDING import may be repointed; any other status returns 409 with code `IMPORT_NOT_REPLACEABLE`. Past the first check the previous verdict is what tells the user what to fix, and a job that reached the execute phase may already have published rows under `correlation_id`.\nAn id that names nothing returns 404. It never falls back to registering a new import: a stale id must fail loudly rather than quietly produce a second one."
+            "description": "Repoint an EXISTING import at this file instead of registering a new one — same row, same id, so iterating on which file to import leaves one entry in the history rather than one per attempt.\nRepointing is allowed exactly while the import has written nothing: from PENDING and READY, and from FAILED when `error.code` is one of `VALIDATION_BLOCKED`, `VALIDATE_TIMEOUT` or `FILE_FORMAT_UNSUPPORTED`. Anything else returns 409 with code `IMPORT_NOT_REPLACEABLE`. The repoint clears any verdict the import had.\nAn id that names nothing returns 404. It never falls back to registering a new import: a stale id must fail loudly rather than quietly produce a second one."
           }
         }
       },
@@ -4722,7 +4729,7 @@
       },
       "ErpImportIssue": {
         "type": "object",
-        "description": "A problem found during validation, scoped to the file as a whole rather than to individual rows.\n`code` is the translation key and the other fields are its parameters — there is deliberately no message to display. Each code appears at most once, with everything it has to say aggregated into that one entry.",
+        "description": "A problem found during validation, scoped to the file as a whole rather than to\nindividual rows.\n\n`code` is the translation key and the other fields are its parameters — there is\ndeliberately no message to display. Each code appears at most once, with\neverything it has to say aggregated into that one entry.\n\nThe conditional codes describe a file that cannot be written as variants:\n\n- `TIER_ROWS_NOT_GROUPED` — rows of one variant are spread through the file;\n  `columns` names what to group by.\n- `TIER_BANDS_CONFLICT` — two rows of one variant claim the same band.\n- `CONDITION_VALUE_MISSING` — a condition column is blank in every row.\n- `VARIANT_VALUE_CONFLICT` — rows of one variant disagree on a value that is not\n  the one being folded; the first row's value is what would be written.\n- `ATTRIBUTE_NOT_OVERRIDABLE` — the schema does not let a variant override this\n  attribute, so the mapped value would be discarded.\n- `ATTRIBUTE_NOT_IN_SCHEMA` — the schema does not have the attribute at all.\n\nThe rest reject the mapping against the entity schemas, before the file is read, and\nname the thing at fault in `subject`: `IS_CONDITIONAL_NOT_CONSTANT`,\n`SCHEMA_NOT_CONDITIONABLE`, `SCHEMA_NOT_FOUND`, `SCHEMA_DECLARES_NO_CONDITIONS`,\n`GROUPING_KEY_NOT_A_COLUMN`, `GROUPING_KEY_IS_FOLD_COLUMN`.",
         "required": [
           "code",
           "severity"
@@ -4738,7 +4745,19 @@
               "INVALID_ENCODING",
               "EMPTY_FILE",
               "TOO_MANY_ROWS",
-              "BLANK_ROWS_SKIPPED"
+              "BLANK_ROWS_SKIPPED",
+              "TIER_ROWS_NOT_GROUPED",
+              "TIER_BANDS_CONFLICT",
+              "CONDITION_VALUE_MISSING",
+              "VARIANT_VALUE_CONFLICT",
+              "ATTRIBUTE_NOT_OVERRIDABLE",
+              "ATTRIBUTE_NOT_IN_SCHEMA",
+              "IS_CONDITIONAL_NOT_CONSTANT",
+              "SCHEMA_NOT_CONDITIONABLE",
+              "SCHEMA_NOT_FOUND",
+              "SCHEMA_DECLARES_NO_CONDITIONS",
+              "GROUPING_KEY_NOT_A_COLUMN",
+              "GROUPING_KEY_IS_FOLD_COLUMN"
             ]
           },
           "severity": {
@@ -4768,6 +4787,10 @@
               }
             }
           },
+          "subject": {
+            "type": "string",
+            "description": "What the issue is about — an attribute, an entity type slug, or an \"attribute reads column\" pair — to substitute into the client's copy for the code. Independent of `columns`; a code can carry both."
+          },
           "row": {
             "type": "integer",
             "description": "The offending data row, 1-based as the user counts rows. MALFORMED_ROW only."
@@ -4778,7 +4801,6 @@
         "type": "object",
         "description": "Validate-phase summary: what the file will create, and whether it may be confirmed. Absent until the validate phase completes. No per-row detail is kept — a rejected file is corrected and imported again.",
         "required": [
-          "total_rows",
           "blocking",
           "warnings",
           "entities"
@@ -4786,7 +4808,7 @@
         "properties": {
           "total_rows": {
             "type": "integer",
-            "description": "Data rows the import will act on. Rows with no value in any column are dropped before they are counted, and reported as BLANK_ROWS_SKIPPED — so this can be lower than the line count of the file."
+            "description": "Data rows the import will act on. Rows with no value in any column are dropped before they are counted, and reported as BLANK_ROWS_SKIPPED — so this can be lower than the line count of the file.\nABSENT when the verdict was reached without reading the file, as a mapping refused against the entity schemas alone is. Do not default it to zero."
           },
           "blocking": {
             "type": "integer",
@@ -4802,6 +4824,17 @@
             },
             "description": "Distinct entities the file expresses, keyed by entity slug."
           },
+          "entity_details": {
+            "type": "array",
+            "description": "What this import will write, one entry per entity instance, capped at 20 in first-appearance order. `entities` stays exact regardless.",
+            "items": {
+              "$ref": "#/components/schemas/ErpImportEntityDetail"
+            }
+          },
+          "entity_details_truncated": {
+            "type": "boolean",
+            "description": "More entities exist than `entity_details` lists."
+          },
           "issues": {
             "type": "array",
             "description": "Whole-file issues, at most one per `code`. Do not expect the length to match blocking + warnings: those also count per-row problems, which are recorded for support but never listed here. Warnings here are what `ack_warnings` on `:execute` acknowledges.",
@@ -4811,6 +4844,39 @@
           }
         }
       },
+      "ErpImportEntityDetail": {
+        "type": "object",
+        "description": "One entity instance the import will write, attributed to the mapping target that produces it.",
+        "required": [
+          "mapping_index",
+          "entity_schema",
+          "business_key"
+        ],
+        "properties": {
+          "mapping_index": {
+            "type": "integer",
+            "description": "Which `config.entities[]` target produced this entity — the join key back to the mapping."
+          },
+          "entity_schema": {
+            "type": "string"
+          },
+          "business_key": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "The entity's identity: its `unique_ids` as the mapping resolved them, keyed by attribute name in the order the target declares them. Values are strings, as they arrive from CSV."
+          },
+          "variants": {
+            "type": "integer",
+            "description": "Distinct condition tuples. Absent when the entity is not conditional."
+          },
+          "versions": {
+            "type": "integer",
+            "description": "Version writes — one per variant per effective date. Absent when the entity is not conditional."
+          }
+        }
+      },
       "ErpImportProgress": {
         "type": "object",
         "description": "How far the currently running phase has got. Written at every batch boundary, so it advances during long runs rather than only at the end.\n`total_rows` is ABSENT during the validate phase until the file has been read to the end — there is deliberately no counting pass, since that would be a second unbounded read of the whole file. Render an indeterminate indicator while it is missing: dividing by a missing total yields a determinate bar pinned at 0%, which reads as a hung import.",
@@ -4847,6 +4913,7 @@
               "IMPORT_TIMEOUT",
               "USE_CASE_NOT_USABLE",
               "IMPORT_NO_PROGRESS",
+              "TIER_ROWS_NOT_GROUPED",
               "INTERNAL_ERROR"
             ]
           },
@@ -5667,6 +5734,13 @@
             },
             "description": "Configuration defining environment variables needed by this integration. Values are stored in the Environments API."
           },
+          "maps": {
+            "type": "array",
+            "description": "Re-usable key/value maps (e.g. salutation codes) declared by this integration (max 50). Each map is synced to the Environments API as a non-secret variable of type `JSON` and is available in JSONata mappings as `$env.<key>`, together with the `$mapValue(map, key, default)` and `$mapKey(map, value, default)` helpers.\n",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationMap"
+            }
+          },
           "settings": {
             "$ref": "#/components/schemas/IntegrationSettings"
           },
@@ -5882,6 +5956,38 @@
       "UpdateIntegrationRequest": {
         "$ref": "#/components/schemas/IntegrationEditableFields"
       },
+      "IntegrationMap": {
+        "type": "object",
+        "description": "A flat key/value map stored as an Environments API variable of type `JSON`. Values must be strings, numbers, booleans or null; the serialised map must not exceed 32 KB.\n",
+        "required": [
+          "key",
+          "label",
+          "value"
+        ],
+        "properties": {
+          "key": {
+            "type": "string",
+            "description": "Environment variable key the map is synced to (`$env.<key>` in JSONata).",
+            "pattern": "^[a-z0-9][a-z0-9_.\\-]{0,127}$"
+          },
+          "label": {
+            "type": "string",
+            "description": "Display label for the map in the UI",
+            "minLength": 1,
+            "maxLength": 255
+          },
+          "description": {
+            "type": "string",
+            "description": "Help text shown for the map",
+            "maxLength": 1000
+          },
+          "value": {
+            "type": "object",
+            "description": "The map itself, e.g. `{\"Mr.\": 1, \"Ms. / Mrs.\": 2}`",
+            "additionalProperties": true
+          }
+        }
+      },
       "EnvironmentFieldConfig": {
         "type": "object",
         "required": [
@@ -6396,9 +6502,100 @@
             "items": {
               "$ref": "#/components/schemas/IntegrationEntityField"
             }
+          },
+          "conditional": {
+            "$ref": "#/components/schemas/IntegrationEntityConditional"
           }
         }
       },
+      "IntegrationEntityConditional": {
+        "type": "object",
+        "description": "Conditional Pricing extras for this target, used when it writes a conditional entity (a Product, Price or Coupon carrying context-dependent variants). The conditions themselves are declared on the entity schema, not here.",
+        "required": [
+          "folds"
+        ],
+        "properties": {
+          "folds": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 1,
+            "description": "Row folds for this target. Exactly one is supported; the array is the shape for later, not a capability claim.",
+            "items": {
+              "$ref": "#/components/schemas/IntegrationEntityFold"
+            }
+          }
+        }
+      },
+      "IntegrationEntityFold": {
+        "type": "object",
+        "description": "Collapse the rows of one variant-version into a single array attribute, ordered by a column. A commodity file carries one row per consumption band, while a variant-version holds exactly one `tiers` array.",
+        "required": [
+          "attribute",
+          "sort_by",
+          "item"
+        ],
+        "properties": {
+          "attribute": {
+            "type": "string",
+            "description": "The array attribute this fold builds, e.g. `tiers`."
+          },
+          "sort_by": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/MappedFieldValue"
+              }
+            ],
+            "description": "Orders the group's rows. Coerced to a number, so `10000` sorts after `5000` rather than before it as strings."
+          },
+          "item": {
+            "type": "object",
+            "additionalProperties": {
+              "$ref": "#/components/schemas/MappedFieldValue"
+            },
+            "description": "Attribute name to field value, shaping one array item from one row. `jsonataExpression` is often needed here: German ERP exports carry decimal commas (`31,25`) that `Number()` cannot parse."
+          }
+        }
+      },
+      "MappedFieldValue": {
+        "description": "One mapped value. Exactly one of field, constant or jsonataExpression must be set — the same three forms `IntegrationEntityField` accepts.",
+        "oneOf": [
+          {
+            "type": "object",
+            "required": [
+              "field"
+            ],
+            "properties": {
+              "field": {
+                "type": "string",
+                "description": "Source column name, or a JSONPath expression when it starts with $"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "constant"
+            ],
+            "properties": {
+              "constant": {
+                "description": "Constant value, of any type"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "required": [
+              "jsonataExpression"
+            ],
+            "properties": {
+              "jsonataExpression": {
+                "type": "string",
+                "description": "JSONata expression evaluated against the row"
+              }
+            }
+          }
+        ]
+      },
       "IntegrationMeterReading": {
         "type": "object",
         "required": [
@@ -8887,7 +9084,7 @@
       },
       "DirectPayload": {
         "type": "object",
-        "description": "The payload of an ERP event routed to a `direct: true` use case: a versioned envelope of\npre-mapped operations that skip the mapping engine. Sent as the `payload` of an\n`ErpEventV3` - either as a JSON object or as a JSON string (`format` must be `json`;\nXML is rejected for direct use cases).\n\nThe schema is strict: unknown keys on the envelope or on any operation are rejected with\nan error naming the offending path. Attribute values, by contrast, pass through to the\nentity verbatim (except `$relation` / `$relation_ref` envelopes, which are validated and\nresolved).\n\nOne event lands as one queue message, so the whole event (including this payload) must\nstay within the 256 KiB message budget. Identical consecutive payloads within 5 minutes\ncan be deduplicated by the queue - use the event's `deduplication_id` deliberately when\nre-sending identical data.\n",
+        "description": "The payload of an ERP event routed to a `direct: true` use case: a versioned envelope of\npre-mapped operations that skip the mapping engine. Sent as the `payload` of an\n`ErpEventV3` - either as a JSON object or as a JSON string (`format` must be `json`;\nXML is rejected for direct use cases).\n\nThe schema is strict: unknown keys on the envelope or on any operation are rejected with\nan error naming the offending path. Attribute values, by contrast, pass through to the\nentity verbatim (except `$relation` / `$relation_ref` envelopes, which are validated and\nresolved).\n\nOne event lands as one queue message, so the whole serialized event (including this\npayload and its internal envelope) must stay within the 1 MiB message budget. Identical\nconsecutive payloads within 5 minutes can be deduplicated by the queue - use the event's\n`deduplication_id` deliberately when re-sending identical data.\n",
         "required": [
           "version",
           "operations"

package/dist/bin/epilot.js

@@ -11,7 +11,7 @@ import { defineCommand } from "citty";
 var main = defineCommand({
   meta: {
     name: "epilot",
-    version: "0.1.147",
+    version: "0.1.148",
     description: "CLI for epilot APIs"
   },
   args: {
@@ -31,7 +31,7 @@ var main = defineCommand({
     profile: () => import("../profile-OZJL5ZPT.js").then((m) => m.default),
     config: () => import("../config-DGZIMLZK.js").then((m) => m.default),
     completion: () => import("../completion-O46M2V67.js").then((m) => m.default),
-    upgrade: () => import("../upgrade-2CGBWWDQ.js").then((m) => m.default),
+    upgrade: () => import("../upgrade-4KQQCBX6.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,7 +134,7 @@ process.stderr.on("error", (err) => {
   if (err.code === "EPIPE") process.exit(0);
   throw err;
 });
-var VERSION = true ? "0.1.147" : (await null).default.version;
+var VERSION = true ? "0.1.148" : (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);

package/dist/{upgrade-2CGBWWDQ.js → upgrade-4KQQCBX6.js}

@@ -72,7 +72,7 @@ ${GREEN}${BOLD}Upgraded to @epilot/cli@${latest}${RESET}
   }
 });
 var getCurrentVersion = () => {
-  if (true) return "0.1.147";
+  if (true) return "0.1.148";
   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.147",
+  "version": "0.1.148",
   "description": "CLI for epilot APIs",
   "type": "module",
   "bin": {