@celigo/api-specs 0.2.133 → 0.2.135

package/dist/api.yml

@@ -5015,6 +5015,12 @@ components:
               type: boolean
               description: When true, the connection has been taken offline and is skipped during flow execution.
               readOnly: true
+            needsAuthorization:
+              type: boolean
+              readOnly: true
+              description: |-
+                OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
             _sourceId:
               type: string
               format: objectId
@@ -6071,7 +6077,7 @@ components:
             OAuth 2.0 redirect URI (callback URL) registered with the API provider.
             Must exactly match the redirect URI configured in the OAuth application registration.
           examples:
-            - https://api.integrator.io/connection/oauth2callback
+            - https://integrator.io/connection/oauth2callback
         useIClientFields:
           type: boolean
           description: |
@@ -9927,7 +9933,7 @@ components:
 
           ## REQUIRED FIELDS
           - pingFunction (name of the function that tests connection health)
-          - _stackId (set on the parent connection object — references the Celigo Stack)
+          - _stackId (inside this object, as `wrapper._stackId` — references the Celigo Stack)
 
           ## CUSTOM FIELDS
           Use encrypted/unencrypted fields to store connection-specific configuration.

package/dist/connection.yml

@@ -2438,7 +2438,8 @@ paths:
         Returns the buffered debug log stream for the connection — request/response pairs from
         recent exports, imports, and lookups that used it. Capture is gated by the connection's
         `debugDate`: logs are recorded only while `debugDate` is in the future, so enable it first
-        via `PUT /v1/connections/{_id}` or the buffer stays empty.
+        with `PATCH /v1/connections/{_id}` on `/debugDate` (credential-safe, unlike a full `PUT`)
+        or the buffer stays empty.
 
         The response is a plain-text stream (not JSON): each entry is a header line
         (`timestamp traceKey resourceType resourceId`) followed by a single-line JSON payload,
@@ -2494,11 +2495,11 @@ paths:
 
         Idempotent — works whether the buffer held entries, was already empty, or the given
         connection id does not exist. Does **not** clear the connection's `debugDate` — debug
-        capture remains enabled until `debugDate` expires or is removed via a PUT.
+        capture remains enabled until `debugDate` expires or is removed.
 
         Useful between test runs to isolate logs for a single scenario. To fully
-        disable debug capture, also `PUT /v1/connections/{_id}` with `debugDate`
-        removed from the body.
+        disable debug capture, also send `PATCH /v1/connections/{_id}` with a `remove`
+        operation on `/debugDate`.
       parameters:
         - name: _id
           in: path
@@ -4126,6 +4127,12 @@ components:
               type: boolean
               description: When true, the connection has been taken offline and is skipped during flow execution.
               readOnly: true
+            needsAuthorization:
+              type: boolean
+              readOnly: true
+              description: |-
+                OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
             _sourceId:
               type: string
               format: objectId
@@ -5182,7 +5189,7 @@ components:
             OAuth 2.0 redirect URI (callback URL) registered with the API provider.
             Must exactly match the redirect URI configured in the OAuth application registration.
           examples:
-            - https://api.integrator.io/connection/oauth2callback
+            - https://integrator.io/connection/oauth2callback
         useIClientFields:
           type: boolean
           description: |
@@ -9038,7 +9045,7 @@ components:
 
           ## REQUIRED FIELDS
           - pingFunction (name of the function that tests connection health)
-          - _stackId (set on the parent connection object — references the Celigo Stack)
+          - _stackId (inside this object, as `wrapper._stackId` — references the Celigo Stack)
 
           ## CUSTOM FIELDS
           Use encrypted/unencrypted fields to store connection-specific configuration.
@@ -10441,7 +10448,7 @@ components:
             Embeds a one-time token in the `state` query parameter that expires quickly and is
             invalidated after a single use.
           examples:
-            - https://login.example.com/oauth2/authorize?response_type=code&client_id=0oa1b2c3d4EXAMPLE5&redirect_uri=https%3A%2F%2Fapi.integrator.io%2Fconnection%2Foauth2callback&scope=read+write&state=eyJfY29ubmVjdGlvbklkIjoiNjE1ZGZhMDc0Mjc2MzY3MTI3NWI3MGFiIn0
+            - https://login.example.com/oauth2/authorize?response_type=code&client_id=0oa1b2c3d4EXAMPLE5&redirect_uri=https%3A%2F%2Fintegrator.io%2Fconnection%2Foauth2callback&scope=read+write&state=eyJfY29ubmVjdGlvbklkIjoiNjE1ZGZhMDc0Mjc2MzY3MTI3NWI3MGFiIn0
     DependencyEntry:
       type: object
       description: A single resource that depends on the queried resource.

package/dist/enduser.yml

@@ -2227,6 +2227,12 @@ components:
               type: boolean
               description: When true, the connection has been taken offline and is skipped during flow execution.
               readOnly: true
+            needsAuthorization:
+              type: boolean
+              readOnly: true
+              description: |-
+                OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
             _sourceId:
               type: string
               format: objectId
@@ -3283,7 +3289,7 @@ components:
             OAuth 2.0 redirect URI (callback URL) registered with the API provider.
             Must exactly match the redirect URI configured in the OAuth application registration.
           examples:
-            - https://api.integrator.io/connection/oauth2callback
+            - https://integrator.io/connection/oauth2callback
         useIClientFields:
           type: boolean
           description: |
@@ -7139,7 +7145,7 @@ components:
 
           ## REQUIRED FIELDS
           - pingFunction (name of the function that tests connection health)
-          - _stackId (set on the parent connection object — references the Celigo Stack)
+          - _stackId (inside this object, as `wrapper._stackId` — references the Celigo Stack)
 
           ## CUSTOM FIELDS
           Use encrypted/unencrypted fields to store connection-specific configuration.

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/iclient.yml

@@ -324,7 +324,9 @@ paths:
         account: every update must include the full JSON key. An Azure
         service principal keeps its stored `clientSecret` or `certificate`
         when the field is omitted — only a new value replaces it, and
-        `certificate` is never returned.
+        `certificate` is never returned. Connections work the other way:
+        re-sending the mask on `PUT /v1/connections/{_id}` clears the stored
+        credential.
       operationId: updateIClient
       tags:
         - iClients
@@ -487,8 +489,9 @@ paths:
       x-internal: false
       summary: Delete an iClient
       description: |-
-        Permanently deletes an iClient. Blocked if the iClient is still
-        referenced by a connection.
+        Permanently deletes an iClient. Blocked while any connection references
+        it, including a deleted connection still in the recycle bin: purge that
+        connection with `DELETE /v1/recycleBinTTL/connections/{_id}` first.
       operationId: deleteIClient
       tags:
         - iClients
@@ -508,7 +511,20 @@ paths:
         '404':
           $ref: '#/components/responses/404-not-found'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            A connection still references the iClient. A deleted connection in the
+            recycle bin counts until it is purged.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                referencedByBinnedConnection:
+                  summary: A deleted connection still in the recycle bin references the iClient
+                  value:
+                    errors:
+                      - code: delete_not_allowed
+                        message: 'this document is referenced by Connection : 6a1b2c3d4e5f60718293a4b5'
   /v1/iclients/{_id}/dependencies:
     get:
       x-internal: false
@@ -1366,7 +1382,7 @@ components:
                   It is used in OAuth 2.0 authorization flows to receive authorization codes or
                   access tokens securely.
               examples:
-                - https://api.integrator.io/connection/oauth2callback
+                - https://integrator.io/connection/oauth2callback
                 - https://client.example.com/callback
                 - https://app.example.com/oauth2/callback
                 - https://localhost:8080/auth/callback
@@ -2165,7 +2181,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plain password value here to set/update it.
-                  - To keep the existing password unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored password on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   Use `password` for the OAuth2 password value used with the password grant;
                   this is the value provided to configure or update the iClient,
@@ -3166,7 +3182,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plaintext consumer key here to set/update it.
-                  - To keep the existing value unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored value on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   Set the NetSuite consumer key value used for authentication;
                   provide this value to configure or update the iClient.
@@ -3192,7 +3208,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plaintext consumer secret here to set/update it.
-                  - To keep the existing value unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored value on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   The NetSuite consumer secret value used for authentication;
                   provide this value to configure or update the iClient.
@@ -3336,7 +3352,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plain client secret value here to set/update it.
-                  - To keep the existing secret unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored secret on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   Use the Salesforce OAuth **client secret** value to configure or update the Salesforce iClient;
                   integrator.io stores this secret encrypted at rest internally (for example as
@@ -3425,7 +3441,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plaintext private key value here to set/update it (often PEM formatted).
-                  - To keep the existing private key unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored private key on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   Set the Salesforce private key value used for authentication flows such as JWT
                   bearer token OAuth;
@@ -3693,7 +3709,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plaintext certificate ID value here to set/update it.
-                  - To keep the existing value unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored value on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   Use the eBay certificate ID value for authentication;
                   this is the value you provide to configure or update the iClient. integrator.io
@@ -3906,7 +3922,7 @@ components:
                 - |-
                   ## IMPLEMENTATION GUIDANCE:
                   - Provide the plaintext secret key value here to set/update it.
-                  - To keep the existing value unchanged during an update, omit this field (or keep `"******"` as-is if returned).
+                  - To keep the stored value on a PUT, re-send `"******"` (the masked value GET returns) unchanged; never omit this field to keep it.
                 - |-
                   Use the Amazon MWS secret key value for authentication;
                   provide this value to configure or update the iClient.
@@ -4555,18 +4571,5 @@ components:
                 errors:
                   - code: not_found
                     message: The requested resource was not found.
-    422-unprocessable-entity:
-      description: |
-        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
-      content:
-        application/json:
-          schema:
-            $ref: '#/components/schemas/Error'
-          examples:
-            default:
-              value:
-                errors:
-                  - code: unprocessable_entity
-                    message: The request could not be processed due to a semantic error.
 x-enable-proxy: true
 x-internal: false

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/mcp-server.yml

@@ -4052,6 +4052,12 @@ components:
               type: boolean
               description: When true, the connection has been taken offline and is skipped during flow execution.
               readOnly: true
+            needsAuthorization:
+              type: boolean
+              readOnly: true
+              description: |-
+                OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
             _sourceId:
               type: string
               format: objectId
@@ -5108,7 +5114,7 @@ components:
             OAuth 2.0 redirect URI (callback URL) registered with the API provider.
             Must exactly match the redirect URI configured in the OAuth application registration.
           examples:
-            - https://api.integrator.io/connection/oauth2callback
+            - https://integrator.io/connection/oauth2callback
         useIClientFields:
           type: boolean
           description: |
@@ -8964,7 +8970,7 @@ components:
 
           ## REQUIRED FIELDS
           - pingFunction (name of the function that tests connection health)
-          - _stackId (set on the parent connection object — references the Celigo Stack)
+          - _stackId (inside this object, as `wrapper._stackId` — references the Celigo Stack)
 
           ## CUSTOM FIELDS
           Use encrypted/unencrypted fields to store connection-specific configuration.

package/dist/tool.yml

@@ -7380,6 +7380,12 @@ components:
               type: boolean
               description: When true, the connection has been taken offline and is skipped during flow execution.
               readOnly: true
+            needsAuthorization:
+              type: boolean
+              readOnly: true
+              description: |-
+                OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
             _sourceId:
               type: string
               format: objectId
@@ -8436,7 +8442,7 @@ components:
             OAuth 2.0 redirect URI (callback URL) registered with the API provider.
             Must exactly match the redirect URI configured in the OAuth application registration.
           examples:
-            - https://api.integrator.io/connection/oauth2callback
+            - https://integrator.io/connection/oauth2callback
         useIClientFields:
           type: boolean
           description: |
@@ -12292,7 +12298,7 @@ components:
 
           ## REQUIRED FIELDS
           - pingFunction (name of the function that tests connection health)
-          - _stackId (set on the parent connection object — references the Celigo Stack)
+          - _stackId (inside this object, as `wrapper._stackId` — references the Celigo Stack)
 
           ## CUSTOM FIELDS
           Use encrypted/unencrypted fields to store connection-specific configuration.
@@ -29813,7 +29819,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 +29834,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 +29842,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 +30103,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 +36679,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 +36691,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 +36713,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 +37156,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 +37168,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 +37287,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.135",
   "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": "db3dbe3d",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {
@@ -2275,6 +2275,7 @@
 				"lastModified": 1,
 				"microServices": 224,
 				"name": 1,
+				"needsAuthorization": 9,
 				"offline": 9,
 				"pgp": 220,
 				"queues": 226,
@@ -3626,6 +3627,7 @@
 				"microServices": 224,
 				"mongodb": 291,
 				"name": 1,
+				"needsAuthorization": 9,
 				"netsuite": 232,
 				"offline": 9,
 				"pgp": 220,