@celigo/api-specs 0.2.129 → 0.2.131

package/README.md

@@ -85,7 +85,7 @@ OpenAPI consumers can ignore them; validators and AI agents may find them useful
 | `x-celigo-refModel`            | ID fields             | The resource type the ID points at (`flows`, `scripts`, and so on).                                                                                               |
 | `x-celigo-ai-guidance`         | Schemas and fields    | Operational hints for AI agents: which default to choose, what to set when scaffolding, and the concrete failure that results from getting it wrong.              |
 | `x-celigo-ui-override`         | Schemas and fields    | Marks a requirement or default that mirrors the integrator.io form, which is stricter than the raw API, so generated configurations are complete and connectable. |
-| `x-celigo-agent`               | Expression fields     | How the field is authored — capability tags such as `handlebars`, `sql`, `graphql`, `filter`, `mapping`, `script`.                                                |
+| `x-celigo-agent`               | Expression fields     | The field's value is authored in an expression language or editor; its capability tags (`handlebars`, `sql`, `mapping`, …) tell an agent or tool which one.       |
 | `x-celigo-handlebars-context`  | Handlebars fields     | The data context the expression is evaluated against, such as `pre-mapped` or `post-mapped`.                                                                      |
 | `x-celigo-excludeAdaptorTypes` | Shared adaptor fields | Adaptor types the field does not apply to.                                                                                                                        |
 | `x-lowercase`, `x-uppercase`   | String fields         | The API normalizes the value's case on save.                                                                                                                      |

package/dist/flow.yml

@@ -2965,8 +2965,8 @@ paths:
         time-bounded `logging.debugUntil` debug window). Jobs older than the flow's log retention window will
         return an empty `logs` array.
 
-        For detailed per-stage data (HTTP request/response, script `options.logs` output), pick an
-        entry and call `POST .../logs/data/query` with the corresponding `stage`. To stitch an
+        For per-stage data (an HTTP request and response, or a mapping's or script hook's input and
+        output), pick an entry and call `POST .../logs/data/query` with the corresponding `stage`. To stitch an
         export entry to its downstream imports, use the `traceKey` with
         `POST .../logs/metadata/query`.
       parameters:
@@ -3184,22 +3184,14 @@ paths:
         - Flows
       summary: Get per-stage execution log data for a record
       description: |-
-        Returns the decoded log data (typically request/response bodies, transform input/output, or script
-        `options.logs` entries) for a single `(step, stage)` tuple within a flow run.
-
-        Stages are bubble-kind specific. The most useful values:
-        - **Export / Lookup:** `apiCall` (HTTP request+response for HTTP exports), `transformation`,
-          `outputFilter`, `responseMapping`.
-        - **Import:** `apiCall`, `mapping`, `inputFilter`, `responseTransformation`.
-        - **Router:** `routing` (branching decision).
-        - **Any:** the `function` name from a configured script hook (e.g. `preMap`, `postMap`, `postSubmit`,
-          `postResponseMap`, `preSavePage`) — populated only when the hook explicitly calls
-          `options.logs.push(...)`.
+        Returns the decoded log data for a single `(step, stage)` tuple within a flow run, such as the
+        HTTP request and response a step sent or the input and output of its mapping or a script hook.
 
         This is typically the terminal call in the drill-down sequence: `execution-logs` then
-        `metadata/query` then `data/query`. For HTTP traces, set `stage: apiCall`. A 200 with
-        `logs: []` means the stage ran but produced no log entry — usually because a script did not
-        call `options.logs.push()`, or the stage is not instrumented for that adaptor.
+        `metadata/query` then `data/query`. An empty `logs` array does not show that the stage ran or
+        that its name is valid: the server answers an unknown stage name the same way as a stage that
+        captured nothing, so check the stage name and the job's `logMode` (`GET /v1/jobs/{_id}`)
+        before concluding the step recorded nothing.
       parameters:
         - name: _id
           in: path
@@ -3231,13 +3223,13 @@ paths:
                   groupId: 69e981ee18808f3e5ed1b2fd
                   recordId: '0'
                   stage: apiCall
-              post_map_script:
-                summary: Fetch `options.logs` output from a postMap script hook
+              pre_map_hook:
+                summary: Fetch a preMap hook's input and output for an import step
                 value:
-                  _expOrImpId: 69a9aa5d3b213b3ac975e8d2
-                  groupId: 69e981ee18808f3e5ed1b2fd
-                  recordId: '0'
-                  stage: postMap
+                  _expOrImpId: 69a9aa5c54e3d9bd11b86d82
+                  groupId: 4tQqtS
+                  recordId: f0xVak
+                  stage: preMapHook
       responses:
         '200':
           description: Log entries for the requested `(step, stage)`.
@@ -3261,8 +3253,31 @@ paths:
                           response:
                             statusCode: 200
                     errors: []
-                empty_no_hook_output:
-                  summary: Script-hook stage that never called `options.logs.push(...)`
+                pre_map_hook:
+                  summary: preMap hook stage — the hook's options and its return value
+                  value:
+                    logs:
+                      - log:
+                          timeStamp: '2026-04-23T02:51:51.402Z'
+                          groupId: 4tQqtS
+                          stage: preMapHook
+                          input:
+                            - data:
+                                - id: 1
+                                  name: Acme Corp
+                                  phone: 555-0100 x12
+                              _importId: 69a9aa5c54e3d9bd11b86d82
+                              testMode: false
+                          output:
+                            - data:
+                                id: 1
+                                name: Acme Corp
+                                phone: 555-0100 x12
+                                phoneExtension: '12'
+                          errors: []
+                    errors: []
+                empty_result:
+                  summary: Nothing captured for the stage, or an unknown stage name
                   value:
                     logs: []
                     errors: []
@@ -7306,7 +7321,7 @@ components:
               description: |-
                 Effective logging mode for this job, resolved from the flow's `logging.mode`
                 and the account-level logging preference. Common values: `basic` (default),
-                `off`, `on`, `debug`.
+                `detailed`, `off`, `on`, `debug`.
               examples:
                 - basic
             __lastPageGeneratorJob:
@@ -7926,7 +7941,8 @@ components:
       type: object
       description: |-
         Request body for `POST /v1/flows/{_id}/jobs/{_jobId}/logs/data/query`.
-        Fetches the actual data captured at a specific execution stage for a single record-at-step.
+        Fetches the data one step captured at one execution stage for a record, or for the record's
+        whole group at a group-level stage.
       properties:
         _expOrImpId:
           type: string
@@ -7936,23 +7952,26 @@ components:
             - 60a2c4e6f321d800129a1a3c
         stage:
           type: string
-          description: Execution stage whose data to return.
-          enum:
+          description: |-
+            Execution stage whose data to return. `apiCall` holds the request and response an HTTP
+            export or import sent. On a job whose `logMode` is `debug`, an export's transform and
+            output filter record under `transformation` and `outputFilter`, an import's mapping and
+            response mapping under `mapping` and `responseMapping`, and a script hook's `options` and
+            return value under its hook type plus `Hook` (`preSavePageHook`, `preMapHook`,
+            `postMapHook`, `postSubmitHook`, `postResponseMapHook`), whatever the function is called;
+            neither the bare hook name (`preMap`) nor `<functionName>Hook` returns them (live-verified
+            2026-10-20).
+          examples:
             - apiCall
-            - preMap
-            - postMap
-            - postSubmit
-            - postResponseMap
-            - transform
-            - responseTransform
-          x-enumDescriptions:
-            apiCall: Raw HTTP request and response from the adaptor invocation.
-            preMap: Data captured by the preMap script hook via options.logs.push().
-            postMap: Data captured by the postMap script hook via options.logs.push().
-            postSubmit: Data captured by the postSubmit script hook via options.logs.push().
-            postResponseMap: Data captured by the postResponseMap script hook via options.logs.push().
-            transform: Data captured during the transformation stage.
-            responseTransform: Data captured during the response transformation stage.
+            - transformation
+            - outputFilter
+            - mapping
+            - responseMapping
+            - preSavePageHook
+            - preMapHook
+            - postMapHook
+            - postSubmitHook
+            - postResponseMapHook
         groupId:
           type: string
           description: Batch id from the `execution-log` entry.
@@ -7971,12 +7990,19 @@ components:
     ExecutionLogDataResponse:
       type: object
       description: |-
-        Stage data for a single record-at-step. Returned by
-        `POST /v1/flows/{_id}/jobs/{_jobId}/logs/data/query`.
-
-        The payload inside `logs[].log` is stage-specific. For `apiCall`, it contains decoded request + response
-        bodies, headers, status, and duration. For script-hook stages (`preMap`, `postMap`, …), it contains
-        whatever the hook pushed via `options.logs.push(...)`, and is empty (`logs: []`) when the hook did not log.
+        Stage data one step of a flow run recorded for a record, or for the record's whole group at a
+        group-level stage. Returned by `POST /v1/flows/{_id}/jobs/{_jobId}/logs/data/query`.
+
+        The payload inside `logs[].log` is stage-specific (live-verified 2026-10-20):
+
+        - `apiCall`: the request's method and URI and the response's status code. A job whose `logMode` is
+          `detailed` or `debug` also records each side's headers and body; a `basic` job does not.
+        - `mapping`, `transformation`, `outputFilter`, `responseMapping`: a per-record entry carrying the
+          record's `recordId`, the stage's `input`, and its `output` (`outputFilter` has `success` instead).
+        - `preSavePageHook`, `preMapHook`, `postMapHook`, `postSubmitHook`: one entry for the record's whole
+          group, with no `recordId`. `input` is a one-element array holding the `options` the hook received,
+          and `output` holds what the hook returned.
+        - `postResponseMapHook`: `recordId` is null, and `input` is the `options` object itself.
       properties:
         logs:
           type: array

package/dist/job.yml

@@ -1620,7 +1620,7 @@ components:
               description: |-
                 Effective logging mode for this job, resolved from the flow's `logging.mode`
                 and the account-level logging preference. Common values: `basic` (default),
-                `off`, `on`, `debug`.
+                `detailed`, `off`, `on`, `debug`.
               examples:
                 - basic
             __lastPageGeneratorJob:

package/package.json

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

package/schemas.json

@@ -1,8 +1,8 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "0c268add",
-		"generatedAt": "2026-10-20"
+		"iasCommit": "a1fc60f9",
+		"generatedAt": "2026-10-21"
 	},
 	"roots": {
 		"aiagent": 133,