@celigo/api-specs 0.2.80 → 0.2.81

package/dist/ai-agent.yml

@@ -3869,20 +3869,48 @@ components:
         extracts evaluate against that envelope:
 
         - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
-          "errors": []}` — `data` holds the records the lookup returned, so
-          extracts must start from it: `data[0].name` copies a field of the
-          first result, `data` copies the whole result array. A bare
-          result-record field name (e.g. `name`) resolves to nothing and merges
-          nothing.
+          "errors": []}` — `data` holds the records the lookup step returns,
+          AFTER the export's own `transform` and output `filter` have run, so
+          extracts must start from it and name transformed fields by their
+          transformed name: `data[0].name` copies a field of the first result,
+          `data` copies the whole result array. A bare result-record field name
+          (e.g. `name`) resolves to nothing and merges nothing, and so does the
+          raw response path a transform consumed.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
-          "ignored": false, "errors": [], "_json": <raw destination response>}` —
-          use `id` for the destination-assigned id and `_json.<path>` for fields
-          inside the destination's response body. The full envelope (including
-          `id`) is present on real runs and in flow-builder previews; flow TEST
-          runs never execute imports, and their mock-built envelope carries no
-          `id` — an `extract: "id"` merges nothing in a test run even though it
-          works on real runs.
+          "ignored": false, "errors": [], "_json": <raw destination response>,
+          ...<response body fields flattened at the root>}` — use `id` for the
+          destination-assigned id and `_json.<path>` (or the flattened
+          `<path>`) for fields inside the destination's response body. The full
+          envelope (including `id`) is present on real runs and in flow-builder
+          previews; flow TEST runs never execute imports, and their mock-built
+          envelope carries no `id` — an `extract: "id"` merges nothing in a test
+          run even though it works on real runs.
+
+        An `extract` may also be a Handlebars expression. It evaluates against
+        the same envelope as a plain path, so every path inside `{{ }}` starts
+        where the plain paths start — `{{data.0.name}}`,
+        `{{#compare data.0.count "==" 1}}yes{{else}}no{{/compare}}`,
+        `{{#if data.length}}found{{/if}}` on a lookup; `{{_json.order.id}}` or
+        `{{id}}` on an import. Index arrays with dots inside Handlebars
+        (`data.0.name` or `data.[0].name`; `data[0].name` renders nothing), and
+        expect a string result (`"1"`, `"false"`). There is no `record` object in
+        this context: `{{record.<anything>}}` renders nothing. Prefer a plain
+        path when the value is simply copied.
       x-celigo-ai-guidance:
+        - |-
+          Handlebars is allowed in `extract` but only rooted at the envelope —
+          `{{data.0.x}}` on a lookup, `{{_json.x}}` / `{{id}}` on an import. The
+          `record.` root belongs to import-mapping templates; here every
+          `{{record.…}}` form renders nothing, silently, and `{{data[0].x}}`
+          (bracket index inside Handlebars) renders nothing too. Use Handlebars
+          only for a derived value (a flag, a concatenation); copy values with a
+          plain path.
+        - |-
+          A lookup's `data[]` is the step's output after its `transform` and
+          `filter`, so author extracts against the transformed records — never
+          against the raw response the transform consumed, and never against a
+          saved `mockOutput` as stored (it is the raw response; the transform
+          runs on top of it in a test run).
         - |-
           Send `fields` and `lists` as bare arrays, exactly as GET returns them.
           Never wrap either in an object (e.g. `"fields": {"type": [...]}`): the
@@ -3924,22 +3952,29 @@ components:
             properties:
               extract:
                 type: string
+                x-celigo-agent:
+                  - handlebars
                 description: |
                   Path within the canonical response envelope to copy the value
-                  from. For lookup steps, paths start from the envelope's `data`
-                  array (`data[0].x` and `data.0.x` are equivalent; `data` alone
-                  copies every result); for import steps, use the envelope fields
-                  `id`, `statusCode`, `ignored`, or `_json.<path>` for the raw
-                  response body. Paths that skip the envelope (bare response
-                  field names) resolve to nothing, and a `[*]` wildcard is not
-                  honored here — `data[*].x` merges nothing; iterate arrays with
-                  `lists` instead.
+                  from, or a Handlebars expression over that same envelope. For
+                  lookup steps, paths start from the envelope's `data` array
+                  (`data[0].x` and `data.0.x` are equivalent; `data` alone
+                  copies every result) — a lookup result field written without
+                  the `data` prefix resolves to nothing. For import steps, use
+                  the envelope fields `id`, `statusCode`, `ignored`, `_json.<path>`
+                  for the raw response body, or the body field itself at the
+                  envelope root (`orderNumber` and `_json.orderNumber` read the
+                  same value). A `[*]` wildcard is not honored here — `data[*].x`
+                  merges nothing; iterate arrays with `lists` instead. Inside
+                  Handlebars, index with dots (`{{data.0.x}}`, never
+                  `{{data[0].x}}`) and never use a `record.` root.
                 examples:
                   - data[0].customer.name
                   - data.0.fields.Product Name
                   - data
                   - id
                   - _json.orderNumber
+                  - '{{#if data.length}}found{{else}}missing{{/if}}'
               generate:
                 type: string
                 description: |

package/dist/export.yml

@@ -15929,19 +15929,38 @@ components:
 
         **Usage**
 
-        When executing a test run or configuring a flow, integrator.io will use this mock output
-        instead of executing the export to retrieve live data. This allows you to:
+        In a flow test run, and for an upstream lookup during a page-processor preview
+        (`previewPageProcessor`), integrator.io substitutes this mock output for the export's live
+        response instead of calling the source. It is not substituted anywhere else: a target lookup
+        in that preview runs its live query, `POST /v1/exports/preview` calls the source, and real
+        runs ignore it. This allows you to:
         - Test mappings with representative data
         - Configure downstream flow steps without waiting for real data
         - Simulate various data scenarios
 
+        Where it is substituted, the records stand in for the RAW parsed response: the export's own
+        `transform` and output `filter` still run on top of them, so downstream steps — and a
+        lookup's results mapping — see the transformed, filtered records, not the shape stored here.
+
         **Limitations**
 
         - Maximum of 10 records
         - Maximum size of 1 MB
         - Must follow the canonical format shown above
 
-        Mock output can be populated automatically from preview data or entered manually.
+        Mock output can be populated automatically from preview data (which is the parsed response,
+        before `transform` / `filter`) or entered manually.
+      x-celigo-ai-guidance:
+        - |-
+          Store the RAW parsed response records here, never transformed ones — the platform runs
+          the export's `transform` and `filter` on the mock exactly as on live data, and a
+          pre-transformed mock would be transformed twice. When you read `mockOutput` to learn
+          what a lookup returns, apply the transform first; a results mapping authored against
+          the stored shape walks paths that do not exist at runtime.
+        - |-
+          A saved mockOutput is read in exactly two places — a flow test run, and an upstream lookup
+          during a page-processor preview. A target lookup's preview, `POST /v1/exports/preview` and
+          every real run call the source and never read it.
       properties:
         page_of_records:
           type: array

package/dist/flow.yml

@@ -4135,20 +4135,48 @@ components:
         extracts evaluate against that envelope:
 
         - **Lookup steps**: `{"statusCode": 200, "data": [<result records>],
-          "errors": []}` — `data` holds the records the lookup returned, so
-          extracts must start from it: `data[0].name` copies a field of the
-          first result, `data` copies the whole result array. A bare
-          result-record field name (e.g. `name`) resolves to nothing and merges
-          nothing.
+          "errors": []}` — `data` holds the records the lookup step returns,
+          AFTER the export's own `transform` and output `filter` have run, so
+          extracts must start from it and name transformed fields by their
+          transformed name: `data[0].name` copies a field of the first result,
+          `data` copies the whole result array. A bare result-record field name
+          (e.g. `name`) resolves to nothing and merges nothing, and so does the
+          raw response path a transform consumed.
         - **Import steps**: `{"id": "<destination record id>", "statusCode": 200,
-          "ignored": false, "errors": [], "_json": <raw destination response>}` —
-          use `id` for the destination-assigned id and `_json.<path>` for fields
-          inside the destination's response body. The full envelope (including
-          `id`) is present on real runs and in flow-builder previews; flow TEST
-          runs never execute imports, and their mock-built envelope carries no
-          `id` — an `extract: "id"` merges nothing in a test run even though it
-          works on real runs.
+          "ignored": false, "errors": [], "_json": <raw destination response>,
+          ...<response body fields flattened at the root>}` — use `id` for the
+          destination-assigned id and `_json.<path>` (or the flattened
+          `<path>`) for fields inside the destination's response body. The full
+          envelope (including `id`) is present on real runs and in flow-builder
+          previews; flow TEST runs never execute imports, and their mock-built
+          envelope carries no `id` — an `extract: "id"` merges nothing in a test
+          run even though it works on real runs.
+
+        An `extract` may also be a Handlebars expression. It evaluates against
+        the same envelope as a plain path, so every path inside `{{ }}` starts
+        where the plain paths start — `{{data.0.name}}`,
+        `{{#compare data.0.count "==" 1}}yes{{else}}no{{/compare}}`,
+        `{{#if data.length}}found{{/if}}` on a lookup; `{{_json.order.id}}` or
+        `{{id}}` on an import. Index arrays with dots inside Handlebars
+        (`data.0.name` or `data.[0].name`; `data[0].name` renders nothing), and
+        expect a string result (`"1"`, `"false"`). There is no `record` object in
+        this context: `{{record.<anything>}}` renders nothing. Prefer a plain
+        path when the value is simply copied.
       x-celigo-ai-guidance:
+        - |-
+          Handlebars is allowed in `extract` but only rooted at the envelope —
+          `{{data.0.x}}` on a lookup, `{{_json.x}}` / `{{id}}` on an import. The
+          `record.` root belongs to import-mapping templates; here every
+          `{{record.…}}` form renders nothing, silently, and `{{data[0].x}}`
+          (bracket index inside Handlebars) renders nothing too. Use Handlebars
+          only for a derived value (a flag, a concatenation); copy values with a
+          plain path.
+        - |-
+          A lookup's `data[]` is the step's output after its `transform` and
+          `filter`, so author extracts against the transformed records — never
+          against the raw response the transform consumed, and never against a
+          saved `mockOutput` as stored (it is the raw response; the transform
+          runs on top of it in a test run).
         - |-
           Send `fields` and `lists` as bare arrays, exactly as GET returns them.
           Never wrap either in an object (e.g. `"fields": {"type": [...]}`): the
@@ -4190,22 +4218,29 @@ components:
             properties:
               extract:
                 type: string
+                x-celigo-agent:
+                  - handlebars
                 description: |
                   Path within the canonical response envelope to copy the value
-                  from. For lookup steps, paths start from the envelope's `data`
-                  array (`data[0].x` and `data.0.x` are equivalent; `data` alone
-                  copies every result); for import steps, use the envelope fields
-                  `id`, `statusCode`, `ignored`, or `_json.<path>` for the raw
-                  response body. Paths that skip the envelope (bare response
-                  field names) resolve to nothing, and a `[*]` wildcard is not
-                  honored here — `data[*].x` merges nothing; iterate arrays with
-                  `lists` instead.
+                  from, or a Handlebars expression over that same envelope. For
+                  lookup steps, paths start from the envelope's `data` array
+                  (`data[0].x` and `data.0.x` are equivalent; `data` alone
+                  copies every result) — a lookup result field written without
+                  the `data` prefix resolves to nothing. For import steps, use
+                  the envelope fields `id`, `statusCode`, `ignored`, `_json.<path>`
+                  for the raw response body, or the body field itself at the
+                  envelope root (`orderNumber` and `_json.orderNumber` read the
+                  same value). A `[*]` wildcard is not honored here — `data[*].x`
+                  merges nothing; iterate arrays with `lists` instead. Inside
+                  Handlebars, index with dots (`{{data.0.x}}`, never
+                  `{{data[0].x}}`) and never use a `record.` root.
                 examples:
                   - data[0].customer.name
                   - data.0.fields.Product Name
                   - data
                   - id
                   - _json.orderNumber
+                  - '{{#if data.length}}found{{else}}missing{{/if}}'
               generate:
                 type: string
                 description: |

package/dist/tool.yml

@@ -6033,11 +6033,21 @@ components:
                         can read them. Extracts do NOT read the raw application
                         response — they evaluate against the platform's canonical
                         per-record envelope: for lookups (`type: "export"`) that is
-                        `{"statusCode", "data": [<result records>], "errors"}`, so
-                        paths must start from `data` (e.g. `data[0].name`); for
-                        imports it is `{"id", "statusCode", "ignored", "_json"}`,
-                        so use `id` or `_json.<path>`. Bare result-record field
-                        names resolve to nothing and merge nothing.
+                        `{"statusCode", "data": [<result records>], "errors"}`
+                        where `data` holds the records AFTER the export's own
+                        `transform` and output `filter`, so paths must start from
+                        `data` and name transformed fields by their transformed
+                        name (e.g. `data[0].name`) — a lookup result field
+                        written without the `data` prefix resolves to nothing;
+                        for imports it is `{"id", "statusCode", "ignored",
+                        "_json", ...<body fields flattened>}`, so use `id`,
+                        `_json.<path>`, or the body field itself at the root
+                        (`orderNumber` and `_json.orderNumber` read the same
+                        value). An extract may be a Handlebars expression over
+                        the same envelope (`{{data.0.name}}`,
+                        `{{#if data.length}}found{{/if}}`; dot indexes only; a
+                        string result); there is no `record` object in this
+                        context, so `{{record.…}}` renders nothing.
                       properties:
                         fields:
                           type: array
@@ -6047,15 +6057,20 @@ components:
                             properties:
                               extract:
                                 type: string
+                                x-celigo-agent:
+                                  - handlebars
                                 description: |
                                   Path within the canonical response envelope to
                                   copy the value from (`data[0].x` / `data.0.x`
-                                  for lookups; `id` or `_json.<path>` for
-                                  imports).
+                                  for lookups; `id`, `_json.<path>` or the
+                                  flattened body field `<path>` for imports), or
+                                  a Handlebars expression over that envelope (dot
+                                  indexes inside `{{ }}`, never a `record.` root).
                                 examples:
                                   - data[0].customer.name
                                   - data.0.fields.Product Name
                                   - id
+                                  - '{{#if data.length}}found{{else}}missing{{/if}}'
                               generate:
                                 type: string
                                 description: |
@@ -36177,19 +36192,38 @@ components:
 
         **Usage**
 
-        When executing a test run or configuring a flow, integrator.io will use this mock output
-        instead of executing the export to retrieve live data. This allows you to:
+        In a flow test run, and for an upstream lookup during a page-processor preview
+        (`previewPageProcessor`), integrator.io substitutes this mock output for the export's live
+        response instead of calling the source. It is not substituted anywhere else: a target lookup
+        in that preview runs its live query, `POST /v1/exports/preview` calls the source, and real
+        runs ignore it. This allows you to:
         - Test mappings with representative data
         - Configure downstream flow steps without waiting for real data
         - Simulate various data scenarios
 
+        Where it is substituted, the records stand in for the RAW parsed response: the export's own
+        `transform` and output `filter` still run on top of them, so downstream steps — and a
+        lookup's results mapping — see the transformed, filtered records, not the shape stored here.
+
         **Limitations**
 
         - Maximum of 10 records
         - Maximum size of 1 MB
         - Must follow the canonical format shown above
 
-        Mock output can be populated automatically from preview data or entered manually.
+        Mock output can be populated automatically from preview data (which is the parsed response,
+        before `transform` / `filter`) or entered manually.
+      x-celigo-ai-guidance:
+        - |-
+          Store the RAW parsed response records here, never transformed ones — the platform runs
+          the export's `transform` and `filter` on the mock exactly as on live data, and a
+          pre-transformed mock would be transformed twice. When you read `mockOutput` to learn
+          what a lookup returns, apply the transform first; a results mapping authored against
+          the stored shape walks paths that do not exist at runtime.
+        - |-
+          A saved mockOutput is read in exactly two places — a flow test run, and an upstream lookup
+          during a page-processor preview. A target lookup's preview, `POST /v1/exports/preview` and
+          every real run call the source and never read it.
       properties:
         page_of_records:
           type: array

package/package.json

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

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "09c1f65",
+		"iasCommit": "83152dc",
 		"generatedAt": "2026-10-08"
 	},
 	"roots": {