@celigo/api-specs 0.2.138 → 0.2.140

package/dist/tool.yml

@@ -1224,8 +1224,9 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            The Tool ran but a step failed. Includes `invocationId` when logging is active, so
-            the failed run can be opened in the run history.
+            A step failed, or the Tool was refused before any step ran because its branches
+            don't all merge back (`tool_dangling_branch`). Either way the response includes
+            `invocationId` when logging is active, so the run can be opened in the run history.
           content:
             application/json:
               schema:
@@ -2398,6 +2399,11 @@ paths:
         `GET /v1/tools/{_id}/test/run/{runId}/{_stepId}` to inspect stage-by-stage
         results. The run id for follow-up calls is the `flowJob._id` value.
 
+        A test run is not free of outside calls: lookups call their sources live. Imports never
+        send; each returns its saved `mockResponse`, or a placeholder response when none is saved
+        (see `mockResponse` on imports). A second test run started while one is still running is
+        refused with `test_run_not_allowed`.
+
         Test runs are a separate, short-lived history from normal runs — capture
         any follow-up step or log details soon after the run completes.
       operationId: testRunTool
@@ -2520,7 +2526,14 @@ paths:
                         status: completed
                         numError: 1
         '400':
-          $ref: '#/components/responses/400-bad-request'
+          description: |-
+            The run was refused before any step ran. A Tool with no steps fails with
+            `tool_empty_router`, and one whose branches don't all merge back with
+            `tool_dangling_branch`; re-running the same document fails the same way.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '401':
           $ref: '#/components/responses/401-unauthorized'
         '404':
@@ -3546,14 +3559,15 @@ components:
             - `objectarray`: Array of objects (most common array type)
             - `arrayarray`: Array of arrays (for matrix/table structures)
 
-            Array dataTypes can be populated two ways: pass a source array through
-            unchanged via `extract` alone (when the source is already an array of
-            the right shape), or construct/iterate via `buildArrayHelper`.
+            Array dataTypes can be populated three ways: pass a source array
+            through unchanged via a JSONPath `extract` alone (when the source is
+            already an array of the right shape), construct/iterate via
+            `buildArrayHelper`, or set a constant with `hardCodedValue`.
 
             IMPORTANT: The dataType controls which additional fields are relevant:
             - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
             - For object types: 'mappings' array becomes relevant
-            - For array types: `buildArrayHelper` is one option (see above)
+            - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
 
             When analyzing existing mappings or generating new ones, always check dataType first
             to understand what additional fields should be present.
@@ -3616,9 +3630,12 @@ components:
             - Access input record fields with {{record.fieldName}} notation; a grouped
               (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
             - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
-            - Valid on `object`, `objectarray`, and primitive-array dataTypes as
-              well as scalars — the rendered template output must parse into the
-              declared shape
+            - Valid on scalars and on `object` rows, where the rendered output must
+              parse into an object. On an array row the template goes in a
+              `buildArrayHelper` entry instead: on an `objectarray` row's own
+              `extract` it is refused with 422 ("buildArrayHelper" must be present
+              for object array datatype), and on a primitive-array row's own
+              `extract` it renders null without an error
 
             ```json
             "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
@@ -3817,6 +3834,19 @@ components:
             - countryCodeToName
             - statusMapping
             - departmentCodes
+        hardCodedValue:
+          type: string
+          description: |
+            Constant written to the destination instead of an extracted value. On a primitive
+            array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
+            verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
+            On an `object` it must be a JSON object string and on an `objectarray` a JSON array
+            string (an object string becomes one element); the save parses it and refuses non-JSON
+            or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+          examples:
+            - USD
+            - A,B
+            - '[{"code": "A"}, {"code": "B"}]'
         description:
           type: string
           description: |
@@ -3952,15 +3982,25 @@ components:
               processor renders the entire destination array as null with no
               validation error. To emit a fixed number of static elements, add
               that many sibling constructed entries — never index the extract.
+            - |-
+              An entry's `extract` can be a Handlebars template. On an
+              `objectarray` it must render a JSON object (one element) or a JSON
+              array (one element per item). On a primitive array each entry
+              renders one element, so a serialized array becomes one string
+              element. A bare literal entry extract is refused with 422 ("extract
+              only supports json path or handlebars expression"); set a constant
+              with the row's `hardCodedValue` instead.
           description: |
             **Purpose**
             Configures how to construct arrays in the output record, handling various array types and inputs.
 
             **Guidance**
-            This is the REQUIRED mechanism for ALL array data types:
+            This is the mechanism for building array data types:
 
             **When to Use**
-            - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
+            - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
+              row passes a source array through with a JSONPath `extract` alone or sets
+              `hardCodedValue`
             - Each entry in this array contributes elements to the output array
             - Multiple entries allow combining data from different input arrays
 
@@ -4585,14 +4625,15 @@ components:
               - `objectarray`: Array of objects (most common array type)
               - `arrayarray`: Array of arrays (for matrix/table structures)
 
-              Array dataTypes can be populated two ways: pass a source array through
-              unchanged via `extract` alone (when the source is already an array of
-              the right shape), or construct/iterate via `buildArrayHelper`.
+              Array dataTypes can be populated three ways: pass a source array
+              through unchanged via a JSONPath `extract` alone (when the source is
+              already an array of the right shape), construct/iterate via
+              `buildArrayHelper`, or set a constant with `hardCodedValue`.
 
               IMPORTANT: The dataType controls which additional fields are relevant:
               - For date-like string fields: extractDateFormat, generateDateFormat, etc. become relevant
               - For object types: 'mappings' array becomes relevant
-              - For array types: `buildArrayHelper` is one option (see above)
+              - For array types: a JSONPath `extract` alone, `buildArrayHelper`, or `hardCodedValue` (see above)
 
               When analyzing existing mappings or generating new ones, always check dataType first
               to understand what additional fields should be present.
@@ -4655,9 +4696,12 @@ components:
               - Access input record fields with {{record.fieldName}} notation; a grouped
                 (array) record binds as `rows` instead — {{rows.0.fieldName}} / {{#each rows}}
               - Examples: "{{record.firstName}} {{record.lastName}}", "{{#if record.isActive}}Active{{else}}Inactive{{/if}}"
-              - Valid on `object`, `objectarray`, and primitive-array dataTypes as
-                well as scalars — the rendered template output must parse into the
-                declared shape
+              - Valid on scalars and on `object` rows, where the rendered output must
+                parse into an object. On an array row the template goes in a
+                `buildArrayHelper` entry instead: on an `objectarray` row's own
+                `extract` it is refused with 422 ("buildArrayHelper" must be present
+                for object array datatype), and on a primitive-array row's own
+                `extract` it renders null without an error
 
               ```json
               "extract": "{{record.price}} {{record.currency}}"  // Combines two fields
@@ -4856,6 +4900,19 @@ components:
               - countryCodeToName
               - statusMapping
               - departmentCodes
+          hardCodedValue:
+            type: string
+            description: |
+              Constant written to the destination instead of an extracted value. On a primitive
+              array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
+              verbatim and untrimmed, into elements of the array's type (`"A,B"` gives `["A", "B"]`).
+              On an `object` it must be a JSON object string and on an `objectarray` a JSON array
+              string (an object string becomes one element); the save parses it and refuses non-JSON
+              or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+            examples:
+              - USD
+              - A,B
+              - '[{"code": "A"}, {"code": "B"}]'
           description:
             type: string
             description: |
@@ -4991,15 +5048,25 @@ components:
                 processor renders the entire destination array as null with no
                 validation error. To emit a fixed number of static elements, add
                 that many sibling constructed entries — never index the extract.
+              - |-
+                An entry's `extract` can be a Handlebars template. On an
+                `objectarray` it must render a JSON object (one element) or a JSON
+                array (one element per item). On a primitive array each entry
+                renders one element, so a serialized array becomes one string
+                element. A bare literal entry extract is refused with 422 ("extract
+                only supports json path or handlebars expression"); set a constant
+                with the row's `hardCodedValue` instead.
             description: |
               **Purpose**
               Configures how to construct arrays in the output record, handling various array types and inputs.
 
               **Guidance**
-              This is the REQUIRED mechanism for ALL array data types:
+              This is the mechanism for building array data types:
 
               **When to Use**
-              - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.)
+              - REQUIRED when dataType ends with "array" (stringarray, objectarray, etc.), unless the
+                row passes a source array through with a JSONPath `extract` alone or sets
+                `hardCodedValue`
               - Each entry in this array contributes elements to the output array
               - Multiple entries allow combining data from different input arrays
 
@@ -6030,7 +6097,7 @@ components:
                     - envelope
                   x-enumDescriptions:
                     record: The transform processor evaluates `mappings[].extract` JSONPath against the flat record itself (`$.field`, no `record.` segment) — the default when absent.
-                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, settings, job, …}` (file-provider steps also carry `fileMeta`) — extracts must include the `record.` segment (`$.record.field`).
+                    envelope: The transform processor evaluates JSONPath against the wrapped runtime envelope `{record, job, testMode, settings, headers, queryParams}` (file-provider steps also carry `fileMeta`) — record fields need the `record.` segment (`$.record.field`), while `headers` and `queryParams` sit beside `record` (`$.headers['X-Id']`, `$.queryParams.src`).
                   description: |
                     Controls the JSON shape the transformTwoDotZero processor
                     evaluates `mappings[].extract` JSONPath values against at
@@ -6050,10 +6117,12 @@ components:
                         `"$.PLACEHOLDER_<field>"`.
                         This is the dominant Celigo idiom and the right choice for new transforms.
                       - `envelope`: the processor sees a wrapped object
-                        `{record: {...}, settings: ..., job: ...}` (plus
-                        `fileMeta` on file-provider steps).
+                        `{record: {...}, job, testMode, settings, headers,
+                        queryParams}` (plus `fileMeta` on file-provider steps).
                         `mappings[].extract` JSONPath MUST include the
-                        `record.` segment — e.g. `"$.record.orderId"`;
+                        `record.` segment for record fields — e.g.
+                        `"$.record.orderId"` — and reads `headers` and
+                        `queryParams` beside it (`$.headers['X-Id']`);
                         PLACEHOLDER extracts use `"$.record.PLACEHOLDER_<field>"`.
                         Pick this only when the transform was authored against
                         the envelope shape on purpose.
@@ -6062,6 +6131,11 @@ components:
                       (`{{record.field}}`, `{{dateFormat ... record.field}}`)
                       ALWAYS reference the `record` root regardless of
                       `inputContext` — only JSONPath anchoring flips.
+                    - |-
+                      In `envelope` mode a `modify` transform merges its mapped
+                      fields into `record` and keeps the rest of the envelope
+                      around it; a `create` transform returns only the mapped
+                      fields, as a bare record.
                     - |-
                       Emit `inputContext` explicitly on new v2 transforms:
                       unset is read as `record`, but stating it makes the
@@ -6082,13 +6156,17 @@ components:
 
                       - ``envelope``: the transform processor sees a wrapped
                         object of the shape
-                        ``{record: {...}, settings: ..., job: ...}`` (plus
-                        ``fileMeta`` on file-provider steps) — the
+                        ``{record: {...}, job, testMode, settings, headers,
+                        queryParams}`` (plus ``fileMeta`` on file-provider
+                        steps; ``headers`` and ``queryParams`` sit beside
+                        ``record``) — the
                         same runtime-context envelope Handlebars / SQL /
                         GraphQL templates render against.  ``mappings[].extract``
-                        JSONPath values MUST include the ``record.`` segment
-                        — for example ``"$.record.orderId"`` or
-                        ``"$.record.customer.email"``.  PLACEHOLDER extracts
+                        JSONPath values for record fields MUST include the
+                        ``record.`` segment — for example ``"$.record.orderId"``
+                        or ``"$.record.customer.email"`` — while ``headers`` and
+                        ``queryParams`` are read beside it
+                        (``"$.headers['X-Id']"``).  PLACEHOLDER extracts
                         use ``"$.record.PLACEHOLDER_<field>"``.  Pick this
                         mode only when the export was authored against the
                         envelope shape on purpose (typically because an
@@ -19798,7 +19876,7 @@ components:
           without the array); a mapping reshapes the message instead.
         - |-
           Publishing is not limited to flows. Verified surfaces: a flow step; an API step (the API
-          invoked at `POST /apis/{version}/{relativeURI}`); a Tool reached through a `ToolImport`
+          invoked at `POST /apis/{version}{relativeURI}`); a Tool reached through a `ToolImport`
           step in a flow; and `POST /v1/imports/{_id}/invoke` with `{"data": [record, ...]}`. A flow
           or API test run (`/test/run`) publishes nothing — import steps are mocked there.
       properties:
@@ -23432,7 +23510,7 @@ components:
 
             **Common filter patterns**
 
-            1. **Pattern matching**: Using wildcards like `*` and `?`
+            1. **Pattern matching**: Regular expressions with `matches`
             2. **Value range filtering**: Numbers between min and max values
             3. **Date range filtering**: Items created/modified within specific time ranges
             4. **Status checking**: Items with specific status values or properties
@@ -23482,9 +23560,12 @@ components:
                 - `"endswith"`: String ends with specified suffix (ends with)
                 - `"contains"`: String contains specified substring (contains)
                 - `"doesnotcontain"`: String does not contain specified substring (does not contain)
-                - `"isempty"`: Field is empty or null (is empty)
-                - `"isnotempty"`: Field contains a value (is not empty)
-                - `"matches"`: Matches specified pattern (matches)
+                - `"empty"`: Field is missing or empty (is empty)
+                - `"notempty"`: Field contains a value (is not empty)
+                - `"matches"`: Matches a regular expression (matches)
+
+                `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
+                "Invalid operation: <name>".
 
                 **Logical Operators**
                 - `"and"`: All conditions must be true
@@ -23504,7 +23585,11 @@ components:
                 **Using `extract` to access record fields:**
                 - Retrieves values from the current record being processed
                 - Can access nested properties using dot notation (e.g., `"customer.email"`)
-                - Returns the raw field value which may need type conversion
+                - In a record filter, must be wrapped in a type conversion (`string`, `number`,
+                  `boolean` or `epochtime`): a bare `["extract", ...]` operand is refused with 422
+                  "Field operation extract must be called by a Type Conversion Operation but was called
+                  by <operator>", both when an import's filter is saved and by
+                  `POST /v1/processors/filter`
 
                 **Using `settings` to access configuration values:**
                 - Retrieves values from the integration's configuration settings
@@ -23522,7 +23607,20 @@ components:
                 - `"floor"`: Round number down to the nearest integer
                 - `"abs"`: Get absolute value of a number
 
-                Type conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:
+                **Handlebars operands**
+                - An operand can also be a string holding exactly one Handlebars expression, such as
+                  `"{{record.status}}"` or `"{{lowercase record.code}}"`, on either side of the
+                  operator. It renders against the record (`record.<field>`; an unprefixed
+                  `{{status}}` renders empty) before the comparison.
+                - The rendered value is a string: wrap it in `["number", ...]` to compare it with a
+                  number, or the rule is refused with 422.
+                - `epochtime` does not render Handlebars: `["epochtime", "{{timestamp}}"]` is refused
+                  with 422 "invalid datetime format".
+                - A string with text around the expression, or with more than one expression, is
+                  compared as a literal.
+
+                Choose the type conversion that matches the comparison — `number` for numeric
+                comparisons, `epochtime` for dates, `string` for text. For example:
 
                 ```json
                 [
@@ -23613,8 +23711,11 @@ components:
                 [
                   "notequals",
                   [
-                    "extract",
-                    "status"
+                    "string",
+                    [
+                      "extract",
+                      "status"
+                    ]
                   ],
                   "cancelled"
                 ]
@@ -23625,8 +23726,11 @@ components:
                 [
                   "startswith",
                   [
-                    "extract",
-                    "filename"
+                    "string",
+                    [
+                      "extract",
+                      "filename"
+                    ]
                   ],
                   "HC"
                 ]
@@ -23647,29 +23751,26 @@ components:
                 ]
                 ```
 
-                Example 4: Order date is after January 1, 2023
+                Example 4: Order date is after January 1, 2023 (UTC). Compare dates as `epochtime`
+                against epoch milliseconds: a `string` comparison of ISO timestamps orders values with
+                different UTC offsets wrongly.
                 ```json
                 [
                   "greaterthan",
                   [
-                    "extract",
-                    "orderDate"
-                  ],
-                  "2023-01-01T00:00:00Z"
-                ]
-                ```
-
-                Example 5: Category contains any of ["Urgent", "High Priority"]
-                ```json
-                [
-                  "anyof",
-                  [
-                    "extract",
-                    "category"
+                    "epochtime",
+                    [
+                      "extract",
+                      "orderDate"
+                    ]
                   ],
-                  ["Urgent", "High Priority"]
+                  1672531200000
                 ]
                 ```
+              x-celigo-ai-guidance:
+                - |-
+                  To test whether a field has a value, use `notempty` on the wrapped extract, not a
+                  `matches` pattern: a record without the field matches `.*\S.*`.
               items:
                 oneOf:
                   - title: String

package/dist/tradingpartnerconnector.yml

@@ -563,7 +563,7 @@ components:
 
             **Common filter patterns**
 
-            1. **Pattern matching**: Using wildcards like `*` and `?`
+            1. **Pattern matching**: Regular expressions with `matches`
             2. **Value range filtering**: Numbers between min and max values
             3. **Date range filtering**: Items created/modified within specific time ranges
             4. **Status checking**: Items with specific status values or properties
@@ -613,9 +613,12 @@ components:
                 - `"endswith"`: String ends with specified suffix (ends with)
                 - `"contains"`: String contains specified substring (contains)
                 - `"doesnotcontain"`: String does not contain specified substring (does not contain)
-                - `"isempty"`: Field is empty or null (is empty)
-                - `"isnotempty"`: Field contains a value (is not empty)
-                - `"matches"`: Matches specified pattern (matches)
+                - `"empty"`: Field is missing or empty (is empty)
+                - `"notempty"`: Field contains a value (is not empty)
+                - `"matches"`: Matches a regular expression (matches)
+
+                `isempty`, `isnotempty` and `anyof` are not operators: they are refused with 422
+                "Invalid operation: <name>".
 
                 **Logical Operators**
                 - `"and"`: All conditions must be true
@@ -635,7 +638,11 @@ components:
                 **Using `extract` to access record fields:**
                 - Retrieves values from the current record being processed
                 - Can access nested properties using dot notation (e.g., `"customer.email"`)
-                - Returns the raw field value which may need type conversion
+                - In a record filter, must be wrapped in a type conversion (`string`, `number`,
+                  `boolean` or `epochtime`): a bare `["extract", ...]` operand is refused with 422
+                  "Field operation extract must be called by a Type Conversion Operation but was called
+                  by <operator>", both when an import's filter is saved and by
+                  `POST /v1/processors/filter`
 
                 **Using `settings` to access configuration values:**
                 - Retrieves values from the integration's configuration settings
@@ -653,7 +660,20 @@ components:
                 - `"floor"`: Round number down to the nearest integer
                 - `"abs"`: Get absolute value of a number
 
-                Type conversion operators are often necessary when comparing extracted field values against literals or when the field type doesn't match the comparison operator's expected type. For example:
+                **Handlebars operands**
+                - An operand can also be a string holding exactly one Handlebars expression, such as
+                  `"{{record.status}}"` or `"{{lowercase record.code}}"`, on either side of the
+                  operator. It renders against the record (`record.<field>`; an unprefixed
+                  `{{status}}` renders empty) before the comparison.
+                - The rendered value is a string: wrap it in `["number", ...]` to compare it with a
+                  number, or the rule is refused with 422.
+                - `epochtime` does not render Handlebars: `["epochtime", "{{timestamp}}"]` is refused
+                  with 422 "invalid datetime format".
+                - A string with text around the expression, or with more than one expression, is
+                  compared as a literal.
+
+                Choose the type conversion that matches the comparison — `number` for numeric
+                comparisons, `epochtime` for dates, `string` for text. For example:
 
                 ```json
                 [
@@ -744,8 +764,11 @@ components:
                 [
                   "notequals",
                   [
-                    "extract",
-                    "status"
+                    "string",
+                    [
+                      "extract",
+                      "status"
+                    ]
                   ],
                   "cancelled"
                 ]
@@ -756,8 +779,11 @@ components:
                 [
                   "startswith",
                   [
-                    "extract",
-                    "filename"
+                    "string",
+                    [
+                      "extract",
+                      "filename"
+                    ]
                   ],
                   "HC"
                 ]
@@ -778,29 +804,26 @@ components:
                 ]
                 ```
 
-                Example 4: Order date is after January 1, 2023
+                Example 4: Order date is after January 1, 2023 (UTC). Compare dates as `epochtime`
+                against epoch milliseconds: a `string` comparison of ISO timestamps orders values with
+                different UTC offsets wrongly.
                 ```json
                 [
                   "greaterthan",
                   [
-                    "extract",
-                    "orderDate"
-                  ],
-                  "2023-01-01T00:00:00Z"
-                ]
-                ```
-
-                Example 5: Category contains any of ["Urgent", "High Priority"]
-                ```json
-                [
-                  "anyof",
-                  [
-                    "extract",
-                    "category"
+                    "epochtime",
+                    [
+                      "extract",
+                      "orderDate"
+                    ]
                   ],
-                  ["Urgent", "High Priority"]
+                  1672531200000
                 ]
                 ```
+              x-celigo-ai-guidance:
+                - |-
+                  To test whether a field has a value, use `notempty` on the wrapped extract, not a
+                  `matches` pattern: a record without the field matches `.*\S.*`.
               items:
                 oneOf:
                   - title: String

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.138",
+  "version": "0.2.140",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [