@celigo/api-specs 0.2.133 → 0.2.134

package/dist/export.yml

@@ -360,8 +360,9 @@ paths:
       x-internal: false
       summary: Clone an export
       description: |
-        Creates a copy of an existing export.
-        Supports optionally remapping referenced connections (via connectionMap).
+        Creates a copy of an existing export, remapping its connection through `connectionMap`.
+        For an export that uses a connection, omitting the map or sending an empty one fails with
+        400 `invalid_connectionMap`; map the connection to itself to keep it.
       operationId: cloneExport
       tags:
         - Exports
@@ -500,7 +501,11 @@ paths:
               description: |-
                 Full export document (mirror of `POST /v1/exports` body shape),
                 optionally with `test.limit` to cap preview record count. Omit
-                `_id` when previewing a not-yet-saved export.
+                `_id` when previewing a not-yet-saved export. For an export this
+                endpoint previews (an HTTP export, for example), a `mockOutput` in
+                the body is returned as a lone `parse` stage instead of a live read,
+                so remove it from a document read back with GET to sample the
+                source.
               additionalProperties: true
             examples:
               http_preview:
@@ -528,9 +533,9 @@ paths:
         '400':
           description: |-
             The export type does not support preview. Virtual (unsaved) previews
-            are rejected for `simple` and other virtual export types — only
-            builder-style exports (e.g. HTTP, RDBMS) can be previewed via this
-            endpoint.
+            are rejected for `simple`, `webhook` and other virtual export types —
+            only builder-style exports (e.g. HTTP, RDBMS) can be previewed via
+            this endpoint.
           content:
             application/json:
               schema:
@@ -633,8 +638,9 @@ paths:
         validation (bad ID, missing auth).
 
         This endpoint executes the export against the live source system.
-        `POST /v1/exports/preview` also queries the live source (reads only,
-        no job) — prefer it when you only need to inspect fetched records.
+        `POST /v1/exports/preview` also queries the live source when its body
+        carries no `mockOutput` (reads only, no job) — prefer it when you only
+        need to inspect fetched records.
       parameters:
         - in: path
           name: _id
@@ -5485,7 +5491,7 @@ components:
             Selects which files are processed: files matching the filter criteria are exported,
             and non-matching files are skipped entirely before processing begins. Filterable
             fields come from each file's metadata — most providers expose filename, filesize,
-            and lastmodified (e.g. ["endswith", ["extract", "filename"], ".csv"]).
+            and lastmodified (e.g. ["endswith", ["string", ["extract", "filename"]], ".csv"]).
           allOf:
             - $ref: '#/components/schemas/Filter'
           x-celigo-ai-guidance:
@@ -5500,7 +5506,7 @@ components:
 
               1. **filename**: The name of the file (with extension)
                 - Example filter: Match files with specific extensions or naming patterns
-                - Usage: `["endswith", ["extract", "filename"], ".csv"]`
+                - Usage: `["endswith", ["string", ["extract", "filename"]], ".csv"]`
 
               2. **filesize**: The size of the file in bytes
                 - Example filter: Skip files that are too large or too small
@@ -5508,7 +5514,7 @@ components:
 
               3. **lastmodified**: The last modification timestamp of the file
                 - Example filter: Process only files created/modified within a specific date range
-                - Usage: `["greaterthan", ["extract", "lastmodified"], "2023-01-01T00:00:00Z"]`
+                - Usage: `["greaterthan", ["epochtime", ["extract", "lastmodified"]], 1672531200000]` (2023-01-01T00:00:00Z in epoch milliseconds)
         backupPath:
           type: string
           description: Path where backup copies of source files are stored before processing.
@@ -5769,38 +5775,10 @@ components:
         bearerToken:
           type: string
           description: |-
-            Bearer token used to authenticate inbound distributed export requests. Optional — most
-            distributed listeners (NetSuite, Salesforce real-time) use no token. Write-only and stored
-            encrypted; treat it as a sensitive credential.
-          x-celigo-ai-guidance:
-            - |-
-              ## FIELD BEHAVIOR
-
-              This token provides authentication for the distributed export:
-
-              - Required for secure access to distributed endpoints
-              - Must be a valid bearer token format
-              - Used in Authorization header as "Bearer {token}"
-              - Should be kept secure and rotated regularly
-            - |-
-              ## IMPLEMENTATION GUIDANCE
-
-              ### Token management
-
-              - Store tokens securely (encrypted at rest)
-              - Implement token rotation policies
-              - Monitor token expiration dates
-              - Use environment variables for token storage
-
-              ### Security considerations
-
-              - Never log bearer tokens in plain text
-              - Implement proper access controls
-              - Use HTTPS for all token transmissions
-              - Validate tokens on each request
-
-              IMPORTANT: Bearer tokens provide full access to the distributed export.
-              Treat them as sensitive credentials.
+            Bearer token that a system pushing data into this export sends as
+            `Authorization: Bearer <token>`. Optional — most distributed listeners (NetSuite,
+            Salesforce real-time) use no token. Write-only and stored encrypted; treat it as a
+            sensitive credential.
           format: password
           examples:
             - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
@@ -15640,9 +15618,10 @@ components:
 
         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:
+        response instead of calling the source. A saved mock is not read anywhere else: a target
+        lookup in that preview runs its live query, invoking the export
+        (`POST /v1/exports/{_id}/invoke`) reads 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
@@ -15651,6 +15630,11 @@ components:
         `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.
 
+        `POST /v1/exports/preview` reads the `mockOutput` in its request body, not the saved one. For
+        an export the preview supports (an HTTP export, for example), a body that carries it (as an
+        export read back with GET does) returns that snapshot as a lone `parse` stage without calling
+        the source; remove `mockOutput` from the body to preview live records.
+
         **Limitations**
 
         - Maximum of 10 records
@@ -15668,8 +15652,8 @@ components:
           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.
+          during a page-processor preview. A target lookup's preview, `POST /v1/exports/{_id}/invoke`
+          and every real run call the source and never read it.
       properties:
         page_of_records:
           type: array
@@ -16181,9 +16165,9 @@ components:
           x-celigo-agent:
             - filter
           description: |-
-            Filter applied to records immediately after they are retrieved from the source.
-            Records that match continue through the flow; records that don't are silently dropped.
-            Filter expressions reference the exported record's own fields.
+            Filter applied to each record after the export's transform and before its preSavePage
+            hook. Records that match continue through the flow; records that don't are silently
+            dropped. Filter expressions reference the transformed record's fields.
           allOf:
             - $ref: '#/components/schemas/Filter'
           x-celigo-ai-guidance:
@@ -16193,13 +16177,13 @@ components:
 
               ## FILTER BEHAVIOR
 
-              When configured, the filter is applied immediately after records are retrieved from the source system:
+              When configured, the filter is applied to each record after the export's transform and before the preSavePage hook:
               - Records that match the filter criteria continue through the flow
               - Records that don't match are silently dropped
               - No partial record processing is performed
 
               ## AVAILABLE FILTER FIELDS
-              The fields available for filtering are the data fields from each record retrieved by the export.
+              The fields available for filtering are those of each record as the export's transform leaves it (the retrieved record when no transform is set).
         inputFilter:
           x-celigo-agent:
             - filter
@@ -16312,9 +16296,12 @@ components:
               x-celigo-agent:
                 - script
               description: |-
-                Hook that runs after each page of records is retrieved from the source but before it
-                is sent to downstream steps. Commonly used to flatten structures, drop unwanted
-                records, or add computed fields.
+                Hook that runs on each page of records after the export's transform and output
+                filter, before the page is sent to downstream steps; commonly used to flatten
+                structures, drop unwanted records, or add computed fields. It receives the page as
+                `options.data` (with `errors`, `pageIndex`, `configuration` and `settings`) and returns
+                `{data, errors, abort, newErrorsAndRetryData}`. An exception thrown here fails every
+                record on that page, each with its own retry data, and later pages still run.
               properties:
                 function:
                   type: string
@@ -17114,8 +17101,10 @@ components:
         connectionMap:
           type: object
           description: |
-            Optional mapping of original connection ids to replacement connection ids.
+            Mapping of original connection ids to replacement connection ids.
             Keys are source connection ids on the original resource; values are target connection ids.
+            For an export that uses a connection, omitting the map or sending an empty one fails
+            with 400 `invalid_connectionMap`; map the connection to itself to reuse it in the clone.
           additionalProperties:
             type: string
           example:
@@ -17155,6 +17144,7 @@ components:
             Final sampled records produced by the preview — the output of the last
             stage. Identical in practice to the last `stages[].data` entry, exposed
             here as a convenience for callers that only care about the end result.
+            Absent from the zero-record answers described under `stages`.
           items: {}
         dataURIs:
           type: array
@@ -17177,10 +17167,15 @@ components:
             runs through parsing only — the export's transform, output filter,
             and preSavePage hook are NOT applied here (they run in flow
             previews, test runs, and real runs). Observed stage names: `parse`
-            always; `request` and `raw` for HTTP exports; `group` when the
-            export groups records (grouped records are bare arrays of the
-            grouped rows). Each stage carries its `data[]` output and any
-            `errors[]` raised at that stage.
+            for a live read that returned records, and as the only stage when a
+            `mockOutput` in the request body answers; `request` and `raw` for HTTP
+            exports; `group` when the export groups records (grouped records are
+            bare arrays of the grouped rows). Each stage carries its `data[]`
+            output and any `errors[]` raised at that stage. A live read that
+            selects no records has been observed without a `parse` stage or
+            top-level `data` on two adaptors: an HTTP export returns only `request`
+            and `raw`, and a NetSuite RESTlet search returns an empty object. Treat
+            those as zero records, not as a failed preview.
           items:
             type: object
             description: One pipeline stage's diagnostic and output envelope.

package/dist/flow.yml

@@ -8249,6 +8249,7 @@ components:
             Final sampled records produced by the preview — the output of the last
             stage. Identical in practice to the last `stages[].data` entry, exposed
             here as a convenience for callers that only care about the end result.
+            Absent from the zero-record answers described under `stages`.
           items: {}
         dataURIs:
           type: array
@@ -8271,10 +8272,15 @@ components:
             runs through parsing only — the export's transform, output filter,
             and preSavePage hook are NOT applied here (they run in flow
             previews, test runs, and real runs). Observed stage names: `parse`
-            always; `request` and `raw` for HTTP exports; `group` when the
-            export groups records (grouped records are bare arrays of the
-            grouped rows). Each stage carries its `data[]` output and any
-            `errors[]` raised at that stage.
+            for a live read that returned records, and as the only stage when a
+            `mockOutput` in the request body answers; `request` and `raw` for HTTP
+            exports; `group` when the export groups records (grouped records are
+            bare arrays of the grouped rows). Each stage carries its `data[]`
+            output and any `errors[]` raised at that stage. A live read that
+            selects no records has been observed without a `parse` stage or
+            top-level `data` on two adaptors: an HTTP export returns only `request`
+            and `raw`, and a NetSuite RESTlet search returns an empty object. Treat
+            those as zero records, not as a failed preview.
           items:
             type: object
             description: One pipeline stage's diagnostic and output envelope.

package/dist/import.yml

@@ -372,8 +372,9 @@ paths:
       x-internal: false
       summary: Clone an import
       description: |
-        Creates a copy of an existing import.
-        Supports optionally remapping referenced connections (via connectionMap).
+        Creates a copy of an existing import, remapping its connection through `connectionMap`.
+        For an import that uses a connection, an empty map fails with 400 `invalid_connectionMap`;
+        map the connection to itself to keep it.
       operationId: cloneImport
       tags:
         - Imports
@@ -17136,8 +17137,11 @@ components:
         connectionMap:
           type: object
           description: |
-            Optional mapping of original connection ids to replacement connection ids.
+            Mapping of original connection ids to replacement connection ids.
             Keys are source connection ids on the original resource; values are target connection ids.
+            For an import that uses a connection, an empty map fails with 400
+            `invalid_connectionMap`, as it does for an export; map the connection to itself to reuse
+            it in the clone.
           additionalProperties:
             type: string
           example:

package/dist/tool.yml

@@ -29813,7 +29813,7 @@ components:
             Selects which files are processed: files matching the filter criteria are exported,
             and non-matching files are skipped entirely before processing begins. Filterable
             fields come from each file's metadata — most providers expose filename, filesize,
-            and lastmodified (e.g. ["endswith", ["extract", "filename"], ".csv"]).
+            and lastmodified (e.g. ["endswith", ["string", ["extract", "filename"]], ".csv"]).
           allOf:
             - $ref: '#/components/schemas/Filter'
           x-celigo-ai-guidance:
@@ -29828,7 +29828,7 @@ components:
 
               1. **filename**: The name of the file (with extension)
                 - Example filter: Match files with specific extensions or naming patterns
-                - Usage: `["endswith", ["extract", "filename"], ".csv"]`
+                - Usage: `["endswith", ["string", ["extract", "filename"]], ".csv"]`
 
               2. **filesize**: The size of the file in bytes
                 - Example filter: Skip files that are too large or too small
@@ -29836,7 +29836,7 @@ components:
 
               3. **lastmodified**: The last modification timestamp of the file
                 - Example filter: Process only files created/modified within a specific date range
-                - Usage: `["greaterthan", ["extract", "lastmodified"], "2023-01-01T00:00:00Z"]`
+                - Usage: `["greaterthan", ["epochtime", ["extract", "lastmodified"]], 1672531200000]` (2023-01-01T00:00:00Z in epoch milliseconds)
         backupPath:
           type: string
           description: Path where backup copies of source files are stored before processing.
@@ -30097,38 +30097,10 @@ components:
         bearerToken:
           type: string
           description: |-
-            Bearer token used to authenticate inbound distributed export requests. Optional — most
-            distributed listeners (NetSuite, Salesforce real-time) use no token. Write-only and stored
-            encrypted; treat it as a sensitive credential.
-          x-celigo-ai-guidance:
-            - |-
-              ## FIELD BEHAVIOR
-
-              This token provides authentication for the distributed export:
-
-              - Required for secure access to distributed endpoints
-              - Must be a valid bearer token format
-              - Used in Authorization header as "Bearer {token}"
-              - Should be kept secure and rotated regularly
-            - |-
-              ## IMPLEMENTATION GUIDANCE
-
-              ### Token management
-
-              - Store tokens securely (encrypted at rest)
-              - Implement token rotation policies
-              - Monitor token expiration dates
-              - Use environment variables for token storage
-
-              ### Security considerations
-
-              - Never log bearer tokens in plain text
-              - Implement proper access controls
-              - Use HTTPS for all token transmissions
-              - Validate tokens on each request
-
-              IMPORTANT: Bearer tokens provide full access to the distributed export.
-              Treat them as sensitive credentials.
+            Bearer token that a system pushing data into this export sends as
+            `Authorization: Bearer <token>`. Optional — most distributed listeners (NetSuite,
+            Salesforce real-time) use no token. Write-only and stored encrypted; treat it as a
+            sensitive credential.
           format: password
           examples:
             - eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
@@ -36701,9 +36673,10 @@ components:
 
         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:
+        response instead of calling the source. A saved mock is not read anywhere else: a target
+        lookup in that preview runs its live query, invoking the export
+        (`POST /v1/exports/{_id}/invoke`) reads 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
@@ -36712,6 +36685,11 @@ components:
         `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.
 
+        `POST /v1/exports/preview` reads the `mockOutput` in its request body, not the saved one. For
+        an export the preview supports (an HTTP export, for example), a body that carries it (as an
+        export read back with GET does) returns that snapshot as a lone `parse` stage without calling
+        the source; remove `mockOutput` from the body to preview live records.
+
         **Limitations**
 
         - Maximum of 10 records
@@ -36729,8 +36707,8 @@ components:
           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.
+          during a page-processor preview. A target lookup's preview, `POST /v1/exports/{_id}/invoke`
+          and every real run call the source and never read it.
       properties:
         page_of_records:
           type: array
@@ -37172,9 +37150,9 @@ components:
           x-celigo-agent:
             - filter
           description: |-
-            Filter applied to records immediately after they are retrieved from the source.
-            Records that match continue through the flow; records that don't are silently dropped.
-            Filter expressions reference the exported record's own fields.
+            Filter applied to each record after the export's transform and before its preSavePage
+            hook. Records that match continue through the flow; records that don't are silently
+            dropped. Filter expressions reference the transformed record's fields.
           allOf:
             - $ref: '#/components/schemas/Filter'
           x-celigo-ai-guidance:
@@ -37184,13 +37162,13 @@ components:
 
               ## FILTER BEHAVIOR
 
-              When configured, the filter is applied immediately after records are retrieved from the source system:
+              When configured, the filter is applied to each record after the export's transform and before the preSavePage hook:
               - Records that match the filter criteria continue through the flow
               - Records that don't match are silently dropped
               - No partial record processing is performed
 
               ## AVAILABLE FILTER FIELDS
-              The fields available for filtering are the data fields from each record retrieved by the export.
+              The fields available for filtering are those of each record as the export's transform leaves it (the retrieved record when no transform is set).
         inputFilter:
           x-celigo-agent:
             - filter
@@ -37303,9 +37281,12 @@ components:
               x-celigo-agent:
                 - script
               description: |-
-                Hook that runs after each page of records is retrieved from the source but before it
-                is sent to downstream steps. Commonly used to flatten structures, drop unwanted
-                records, or add computed fields.
+                Hook that runs on each page of records after the export's transform and output
+                filter, before the page is sent to downstream steps; commonly used to flatten
+                structures, drop unwanted records, or add computed fields. It receives the page as
+                `options.data` (with `errors`, `pageIndex`, `configuration` and `settings`) and returns
+                `{data, errors, abort, newErrorsAndRetryData}`. An exception thrown here fails every
+                record on that page, each with its own retry data, and later pages still run.
               properties:
                 function:
                   type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.133",
+  "version": "0.2.134",
   "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": "60c8d128",
+		"iasCommit": "86f54b3d",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {