@celigo/api-specs 0.2.138 → 0.2.139

package/dist/import.yml

@@ -12130,7 +12130,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
@@ -12180,9 +12180,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
@@ -12202,7 +12205,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
@@ -12220,7 +12227,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
                 [
@@ -12311,8 +12331,11 @@ components:
                 [
                   "notequals",
                   [
-                    "extract",
-                    "status"
+                    "string",
+                    [
+                      "extract",
+                      "status"
+                    ]
                   ],
                   "cancelled"
                 ]
@@ -12323,8 +12346,11 @@ components:
                 [
                   "startswith",
                   [
-                    "extract",
-                    "filename"
+                    "string",
+                    [
+                      "extract",
+                      "filename"
+                    ]
                   ],
                   "HC"
                 ]
@@ -12345,29 +12371,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
@@ -12558,14 +12581,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.
@@ -12628,9 +12652,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
@@ -12829,6 +12856,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: |
@@ -12964,15 +13004,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
 
@@ -13597,14 +13647,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.
@@ -13667,9 +13718,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
@@ -13868,6 +13922,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: |
@@ -14003,15 +14070,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
 
@@ -14773,7 +14850,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
@@ -14793,10 +14870,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.
@@ -14805,6 +14884,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
@@ -14825,13 +14909,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

package/dist/processor.yml

@@ -23,7 +23,8 @@ tags:
 
       These are one-shot transformation calls — they do not create or modify
       any resources. Use them to test parsing rules, preview file definitions,
-      or transform data outside of a flow.
+      or transform data outside of a flow. The filter and Handlebars processors
+      test a step's filter rules or templates the same way.
 
       ## Processor descriptor schema
 
@@ -1047,6 +1048,212 @@ paths:
                           type: string
                   path:
                     type: string
+  /v1/processors/filter:
+    post:
+      x-internal: false
+      operationId: evaluateFilterRules
+      tags:
+        - Parsers & Generators
+      summary: Test filter rules against records
+      description: |-
+        Evaluates export and import filter rules (`Filter.expression`) against the records in `data` and
+        returns the records that pass. Nothing is saved and no flow runs, so it checks a rule before the
+        rule is saved on a step. Rules are validated as they are when a filter is saved: an unknown
+        operator or a bare `extract` is refused with 422.
+
+        Send each record bare, the way it reaches a step's filter. A record wrapped as
+        `{"record": {...}}` is evaluated as that wrapper, so field rules don't match it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - rules
+                - data
+              properties:
+                rules:
+                  type: object
+                  description: The filter expression to evaluate, in the shape of a step's `filter.expression`.
+                  required:
+                    - version
+                    - rules
+                  properties:
+                    version:
+                      type: string
+                      enum:
+                        - '1'
+                      x-enumDescriptions:
+                        '1': Version 1 of the Celigo expression-based filter format.
+                      description: Version of the filter format used by `rules`.
+                    rules:
+                      type: array
+                      description: Prefix-notation rule in the grammar of `Filter.expression.rules`.
+                      x-celigo-agent:
+                        - filter
+                      items: {}
+                data:
+                  type: array
+                  description: Records to evaluate, each a bare record object.
+                  items:
+                    type: object
+                    additionalProperties: true
+            examples:
+              default:
+                summary: Keep the records whose email has a value
+                value:
+                  rules:
+                    version: '1'
+                    rules:
+                      - notempty
+                      - - string
+                        - - extract
+                          - email
+                  data:
+                    - email: a@example.com
+                    - email: ''
+                    - {}
+      responses:
+        '200':
+          description: The records that pass the rules.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mediaType:
+                    type: string
+                    description: Always `json` for the filter processor.
+                    enum:
+                      - json
+                    x-enumDescriptions:
+                      json: Response data is formatted as JSON.
+                  data:
+                    type: array
+                    description: The input records that pass the rules, unchanged and in input order.
+                    items:
+                      type: object
+                      additionalProperties: true
+                  duration:
+                    type: integer
+                    description: Processing time in milliseconds.
+              examples:
+                default:
+                  value:
+                    mediaType: json
+                    data:
+                      - email: a@example.com
+                    duration: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The rules are invalid, for example an unknown operator ("Invalid operation: isnotempty.") or
+            an `extract` that is not wrapped in a type conversion ("Field operation extract must be called
+            by a Type Conversion Operation but was called by notempty.").
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/processors/handlebars:
+    post:
+      x-internal: false
+      operationId: renderHandlebarsTemplate
+      tags:
+        - Parsers & Generators
+      summary: Render a Handlebars template
+      description: |-
+        Renders a Handlebars template against the object in `data` and returns the result. Nothing is
+        saved and no flow runs, so it tests a template or a helper before the template is saved on a
+        step.
+
+        `data` is the template's root context: `{{name}}` reads `data.name`. A template written for a
+        step reads the record as `{{record.<field>}}`, so send the record under `record`
+        (`"data": {"record": {...}}`). Double braces HTML-escape the value (`&` renders as `&amp;`);
+        triple braces insert it unchanged. A `timestamp` with no time zone renders in UTC.
+
+        An unknown helper is refused with 422. `GET /v1/processors` lists helpers under the handlebars
+        entry's `helperFunctions`, but that list is not complete: `eq` and `truncateWords`, for
+        example, render although it omits them, so render a doubtful helper once here before relying
+        on it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - rules
+                - data
+              properties:
+                rules:
+                  type: object
+                  required:
+                    - template
+                  properties:
+                    template:
+                      type: string
+                      description: The Handlebars template to render.
+                      x-celigo-agent:
+                        - handlebars
+                    resultMode:
+                      type: string
+                      description: Form of the result; `text` returns the rendered string.
+                      examples:
+                        - text
+                data:
+                  type: object
+                  additionalProperties: true
+                  description: Root context the template renders against.
+            examples:
+              step_template:
+                summary: Render a step template against a record
+                value:
+                  rules:
+                    template: '{{record.name}} | {{{record.name}}}'
+                    resultMode: text
+                  data:
+                    record:
+                      name: Smith & Sons
+      responses:
+        '200':
+          description: The rendered template.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  mediaType:
+                    type: string
+                    description: Always `text` for the handlebars processor.
+                    enum:
+                      - text
+                    x-enumDescriptions:
+                      text: Response data is the rendered text.
+                  data:
+                    description: |-
+                      The rendered result, normally a string. A template that renders only a helper's
+                      numeric result can come back as a JSON number.
+                  duration:
+                    type: integer
+                    description: Processing time in milliseconds.
+              examples:
+                default:
+                  value:
+                    mediaType: text
+                    data: Smith &amp; Sons | Smith & Sons
+                    duration: 0
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          description: |-
+            The template could not be rendered, for example because it calls a helper that does not
+            exist ('Missing helper: "first"').
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
 components:
   securitySchemes:
     bearerAuth:
@@ -1219,6 +1426,46 @@ components:
         traceKeysDuplicate:
           type: boolean
           description: When true, duplicate trace keys were detected in the output records.
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
   responses:
     401-unauthorized:
       description: |-