@celigo/api-specs 0.2.147 → 0.2.149

package/dist/export.yml

@@ -984,10 +984,13 @@ components:
       description: |-
         Configures incremental exports that retrieve only records created or modified since the last
         successful run. Required when the export's type is "delta"; omit for other export types.
-        When no cutoff is supplied, the platform-managed last-successful-run timestamp (exposed as
-        {{lastExportDateTime}}) is the lower bound — the first run behaves like a full export, and
-        after a failed run the next run reuses the last successful timestamp so changed records are
-        not missed.
+        The platform-managed last-successful-run timestamp (exposed as {{lastExportDateTime}}) is the
+        lower bound, and after a failed run the next run reuses the last successful timestamp so
+        changed records are not missed. A first run is not a full export: with no `startDate`, its
+        {{lastExportDateTime}} is the run's own timestamp (the value {{currentExportDateTime}} also
+        holds), so it picks up no earlier changes. Set `startDate` to reach back further. On success,
+        when `POST /v1/flows/{_id}/run` sends `export.endDate`, the flow's checkpoint is left at that
+        value, so an end date in the past moves the next run's lower bound back.
       x-celigo-ai-guidance:
         - |-
           This object is REQUIRED when the export's type field is set to "delta" and
@@ -1023,7 +1026,7 @@ components:
 
           2. The system automatically maintains the last successful run timestamp
               - No need to store or manage timestamps in your own code
-              - First run fetches all records (equivalent to a standard export)
+              - A first run without ``startDate`` fetches nothing older than the run itself
               - Subsequent runs use this timestamp as the starting point
 
           3. Error handling and recovery:
@@ -1245,9 +1248,9 @@ components:
             - 'null'
           format: date-time
           description: |-
-            Explicit lower-bound cutoff for the first run, overriding the default of starting from the
-            beginning of time. Subsequent runs use the platform-managed last-successful-run timestamp.
-            Set it to backfill from a specific point rather than exporting all history.
+            Lower-bound cutoff for the first run. Omitting it doesn't export history: the first run
+            then starts at its own timestamp. Set it to the earliest change the first run should pick
+            up. Subsequent runs use the platform-managed last-successful-run timestamp.
           x-celigo-ai-guidance:
             - |-
               Initial cutoff timestamp for the first export run, in ISO-8601 UTC format (e.g.
@@ -16402,8 +16405,11 @@ components:
                 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.
+                `{data, errors, abort, newErrorsAndRetryData}`. Return that object, not the array: a
+                hook that returns `options.data` itself, or a filtered copy, drops the page without an
+                error, and the run completes with 0 records, 0 errors and 0 pages. 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/dist/flow.yml

@@ -824,8 +824,9 @@ paths:
 
         The request body is optional. When omitted, the flow runs with its configured schedule behavior —
         for delta flows this means using the current `lastExportDateTime` as the lower bound. Pass
-        `export.startDate` / `export.endDate` to override the delta window for this run only (the flow's
-        checkpoint still advances on success). Pass `_exportIds` to limit execution to a subset of the flow's
+        `export.startDate` / `export.endDate` to set this run's delta window. On success, when
+        `export.endDate` is sent, the flow's checkpoint is left at that value, so an end date in the past
+        moves the next run's lower bound back. Pass `_exportIds` to limit execution to a subset of the flow's
         generators (useful for flows with many independent sources).
 
         Flow-level preconditions enforced by the platform:
@@ -835,8 +836,9 @@ paths:
 
         To trace a run end-to-end, arm debug logging before calling this, then use the returned
         `_jobId` with the execution-log endpoints. For delta backfills, prefer passing explicit
-        `startDate`/`endDate` over editing the export's `lastExportDateTime` — the override is
-        scoped to one run. A flow runs one instance at a time: a run requested while another
+        `startDate`/`endDate` over editing the export's `lastExportDateTime`, and read the checkpoint
+        first (`GET /v1/flows/{_id}/lastExportDateTime`): the override doesn't stay with one run, since
+        a successful run that sends `endDate` leaves the checkpoint there. A flow runs one instance at a time: a run requested while another
         instance is queued or running is refused with `409 job_already_queued` ("Another instance
         for this flow is already queued or running"), and a run-next-flow trigger that arrives in
         that state is dropped rather than queued.
@@ -1080,11 +1082,14 @@ paths:
         generators (exports) in the flow. This value is what gets substituted into the `{{lastExportDateTime}}`
         Handlebars variable on the next delta run of any export in the flow.
 
-        The checkpoint advances automatically at the end of a successful delta run. It can be overridden per
-        run by passing `export.startDate` / `export.endDate` to `POST /v1/flows/{_id}/run`.
+        The checkpoint advances automatically at the end of a successful delta run. On success, when
+        `POST /v1/flows/{_id}/run` sends `export.endDate`, the checkpoint is left at that value, so an end
+        date in the past moves the next run's lower bound back.
 
-        A missing or very old value means the next delta run will re-scan the full history window from
-        the source. This is the flow-scoped checkpoint; per-export checkpoints (for flows with multiple
+        A missing value (`null`, a flow that has never run) is not a full re-scan: the next delta run's
+        `{{lastExportDateTime}}` is the export's `delta.startDate` when set, and otherwise the run's own
+        timestamp, which picks up no earlier changes. A very old value re-reads everything changed since
+        then. This is the flow-scoped checkpoint; per-export checkpoints (for flows with multiple
         generators that advance independently) are exposed on the export record's `delta` block.
       parameters:
         - name: _id
@@ -4221,7 +4226,10 @@ components:
           type: string
           description: |-
             Cron expression for this specific generator, overriding the flow's main schedule.
-            When omitted, the generator inherits the flow's schedule.
+            When omitted, the generator inherits the flow's schedule. It is read in the flow's
+            `timezone`, and a flow with no flow-level `schedule` still runs on it. PATCH reaches
+            the flow-level `/schedule` and `/timezone` but not this field, so changing it is a full
+            update of the flow.
           examples:
             - '? 5 0,6,12,18 ? * *'
             - '? 30 2 ? * *'
@@ -4231,6 +4239,10 @@ components:
               - Overrides the flow's main schedule for this generator
               - Allows different data sources to refresh at different intervals
               - Useful for sources with varying update frequencies
+            - |-
+              Check for one before rescheduling a flow: a flow-level `schedule` change succeeds
+              but leaves a generator that has its own `schedule` running at its old times. Change
+              the generator's `schedule` instead, with a PUT of the whole flow.
         skipRetries:
           type: boolean
           default: false
@@ -4645,7 +4657,16 @@ components:
             Filter criteria that determines which records match this branch.
 
             Only used when the router's `routeRecordsUsing` is `input_filters`.
-            Records matching these criteria will be routed to this branch.
+            Records matching these criteria will be routed to this branch. A branch
+            without an `inputFilter` matches every record, so under
+            `first_matching_branch` the catch-all branch goes last.
+
+            Send `version` and `rules` directly on `inputFilter` — not inside the
+            `{type: "expression", expression: {...}}` wrapper that export and import
+            filters use. A wrapped filter is saved without an error, but the branch is
+            stored with no `inputFilter` and takes every record.
+          x-celigo-ai-guidance:
+            - Read the flow back after saving a branching router and check that each filtered branch still has its `inputFilter`; a filter sent in the export-filter wrapper is dropped on save without an error.
           properties:
             version:
               type: string
@@ -4674,6 +4695,11 @@ components:
                 logical operators (`and`, `or`, `not`), field access (`extract`, `settings`)
                 and type conversions (`string`, `number`, `boolean`, `epochtime`).
 
+                Every `extract` must be wrapped in a type conversion. A bare
+                `["extract", "<field>"]` is refused when the flow is saved, with 422 "Field
+                operation extract must be called by a Type Conversion Operation but was called
+                by equals." (the message names the operator that held it).
+
                 Example — route records whose `isDeleted` field is the string "false":
                 ```json
                 ["equals", ["string", ["extract", "isDeleted"]], "false"]
@@ -4777,7 +4803,7 @@ components:
           examples:
             - first_matching_branch
           x-celigo-ai-guidance:
-            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config`.
+            - Set this and `routeRecordsUsing` together on every router that decides between branches; setting only one of the two is rejected with 422 `invalid_flow_router_config` ("Either both the routeRecordsTo and routeRecordsUsing fields or none of them should be defined on the router.").
             - Leave both unset on a one-branch pass-through router (the steps before the first branching router, or a merge point). Setting them there still runs, but Flow Builder shows a router node with one branch and no rules. A router with neither field and more than one branch is rejected with 422 `invalid_flow_router_branch`.
         routeRecordsUsing:
           type: string
@@ -5427,7 +5453,9 @@ components:
         Writable flow fields shared by the request and response schemas.
 
         Use `pageProcessors` for simple linear flows or `routers` for conditional branching — never
-        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`.
+        include both: a flow with both arrays non-empty is rejected with 422 `invalid_branched_flow_config`
+        ("Either routers or pageProcessors should be present in the flow configuration and not both.").
+        Turning a linear flow into a branching one moves its top-level steps into the branches.
         The same import can be a step only once per flow: a second `pageProcessors` entry with its
         `_importId`, in the same array or another branch, fails with 422 `invalid_flow` ("… already
         included as a pageProcessor"). The `schedule` field uses Celigo's 6-field cron format (not
@@ -5486,7 +5514,15 @@ components:
               Build `schedule` as a Celigo 6-field cron:
               `? minute hour day-of-month month day-of-week`.
               The seconds field is always `?`; day-of-month is usually `?`, month `*`,
-              and day-of-week `*` (or specific days, 0=Sun..6=Sat).
+              and day-of-week `*` (or specific days, 0=Sun..6=Sat — weekdays are `1-5`,
+              `1,2,3,4,5` or `MON-FRI`; `2-6` is Tuesday to Saturday).
+            - |-
+              The hours are read in the flow's `timezone`. Keep a user's local times as
+              they are and set their IANA zone; never convert them to UTC, which is an hour
+              off for half the year in a zone with daylight saving and shifts them twice
+              when paired with the local `timezone`. Before changing when a flow runs, read
+              `pageGenerators[]`: a generator with its own `schedule` keeps it after a
+              flow-level change.
             - |-
               Disabling a flow does not bypass schedule validation: POST, PUT, and PATCH
               all reject free text or a sub-minute expression (`not a cron`, `* * * * * *`)
@@ -5521,7 +5557,10 @@ components:
           type:
             - string
             - 'null'
-          description: IANA timezone for the schedule (e.g. `America/New_York`). Defaults to UTC.
+          description: |-
+            IANA timezone for the schedule (e.g. `America/New_York`). Defaults to UTC. The flow's
+            `schedule` and each page generator's own `schedule` are read in this timezone; a page
+            generator has no timezone of its own.
           examples:
             - America/New_York
             - Europe/London

package/dist/import.yml

@@ -16408,7 +16408,11 @@ components:
                 - script
               description: |-
                 Hook that runs on each page of records before the import's mappings are applied.
-                Commonly used to reshape or filter records ahead of mapping.
+                Commonly used to reshape or filter records ahead of mapping. Its changes shape only
+                the request this import sends: the next step receives the record as it arrived here,
+                plus whatever this step's response mapping merges back. A value later steps need
+                belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
+                the flow, or in the later import's own `preMap`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -16430,7 +16434,8 @@ components:
               description: |-
                 Hook that runs after the import's mappings are applied but before records are sent
                 to the destination system. Commonly used for adjustments that need the mapped
-                (destination-shaped) record.
+                (destination-shaped) record. Like `preMap`, its changes shape only the request this
+                import sends; the next step never sees them.
               x-celigo-ai-guidance:
                 - |-
                   Post-map JavaScript hook — runs once per page AFTER the
@@ -16453,7 +16458,11 @@ components:
               description: |-
                 Hook that runs after the destination system responds, with access to both the
                 submitted records and the destination's responses. Commonly used to inspect results
-                or adjust the response data passed downstream.
+                or adjust the response data passed downstream. Each `options.responseData` entry is
+                one submitted record's result, in order: `statusCode`, `errors` (`{code, message,
+                source}`, empty on success), `ignored`, `id`, and `_json` — the destination's parsed
+                response body, where its own error detail sits (`_headers` holds the response
+                headers).
               x-celigo-ai-guidance:
                 - |-
                   Post-submit JavaScript hook — runs AFTER each batch of

package/dist/tool.yml

@@ -25289,7 +25289,11 @@ components:
                 - script
               description: |-
                 Hook that runs on each page of records before the import's mappings are applied.
-                Commonly used to reshape or filter records ahead of mapping.
+                Commonly used to reshape or filter records ahead of mapping. Its changes shape only
+                the request this import sends: the next step receives the record as it arrived here,
+                plus whatever this step's response mapping merges back. A value later steps need
+                belongs in the source export's `preSavePage`, in this step's `postResponseMap` hook on
+                the flow, or in the later import's own `preMap`.
               x-celigo-ai-guidance:
                 - |-
                   Pre-map JavaScript hook — runs once per page BEFORE the
@@ -25311,7 +25315,8 @@ components:
               description: |-
                 Hook that runs after the import's mappings are applied but before records are sent
                 to the destination system. Commonly used for adjustments that need the mapped
-                (destination-shaped) record.
+                (destination-shaped) record. Like `preMap`, its changes shape only the request this
+                import sends; the next step never sees them.
               x-celigo-ai-guidance:
                 - |-
                   Post-map JavaScript hook — runs once per page AFTER the
@@ -25334,7 +25339,11 @@ components:
               description: |-
                 Hook that runs after the destination system responds, with access to both the
                 submitted records and the destination's responses. Commonly used to inspect results
-                or adjust the response data passed downstream.
+                or adjust the response data passed downstream. Each `options.responseData` entry is
+                one submitted record's result, in order: `statusCode`, `errors` (`{code, message,
+                source}`, empty on success), `ignored`, `id`, and `_json` — the destination's parsed
+                response body, where its own error detail sits (`_headers` holds the response
+                headers).
               x-celigo-ai-guidance:
                 - |-
                   Post-submit JavaScript hook — runs AFTER each batch of
@@ -25833,10 +25842,13 @@ components:
       description: |-
         Configures incremental exports that retrieve only records created or modified since the last
         successful run. Required when the export's type is "delta"; omit for other export types.
-        When no cutoff is supplied, the platform-managed last-successful-run timestamp (exposed as
-        {{lastExportDateTime}}) is the lower bound — the first run behaves like a full export, and
-        after a failed run the next run reuses the last successful timestamp so changed records are
-        not missed.
+        The platform-managed last-successful-run timestamp (exposed as {{lastExportDateTime}}) is the
+        lower bound, and after a failed run the next run reuses the last successful timestamp so
+        changed records are not missed. A first run is not a full export: with no `startDate`, its
+        {{lastExportDateTime}} is the run's own timestamp (the value {{currentExportDateTime}} also
+        holds), so it picks up no earlier changes. Set `startDate` to reach back further. On success,
+        when `POST /v1/flows/{_id}/run` sends `export.endDate`, the flow's checkpoint is left at that
+        value, so an end date in the past moves the next run's lower bound back.
       x-celigo-ai-guidance:
         - |-
           This object is REQUIRED when the export's type field is set to "delta" and
@@ -25872,7 +25884,7 @@ components:
 
           2. The system automatically maintains the last successful run timestamp
               - No need to store or manage timestamps in your own code
-              - First run fetches all records (equivalent to a standard export)
+              - A first run without ``startDate`` fetches nothing older than the run itself
               - Subsequent runs use this timestamp as the starting point
 
           3. Error handling and recovery:
@@ -26094,9 +26106,9 @@ components:
             - 'null'
           format: date-time
           description: |-
-            Explicit lower-bound cutoff for the first run, overriding the default of starting from the
-            beginning of time. Subsequent runs use the platform-managed last-successful-run timestamp.
-            Set it to backfill from a specific point rather than exporting all history.
+            Lower-bound cutoff for the first run. Omitting it doesn't export history: the first run
+            then starts at its own timestamp. Set it to the earliest change the first run should pick
+            up. Subsequent runs use the platform-managed last-successful-run timestamp.
           x-celigo-ai-guidance:
             - |-
               Initial cutoff timestamp for the first export run, in ISO-8601 UTC format (e.g.
@@ -37409,8 +37421,11 @@ components:
                 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.
+                `{data, errors, abort, newErrorsAndRetryData}`. Return that object, not the array: a
+                hook that returns `options.data` itself, or a filtered copy, drops the page without an
+                error, and the run completes with 0 records, 0 errors and 0 pages. 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.147",
+  "version": "0.2.149",
   "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": "53d752ea",
+		"iasCommit": "4808eca1",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {