@celigo/api-specs 0.2.196 → 0.2.198

package/dist/tool.yml

@@ -3919,7 +3919,9 @@ components:
             - statusMapping
             - departmentCodes
         hardCodedValue:
-          type: string
+          type:
+            - string
+            - 'null'
           description: |
             Constant written to the destination instead of an extracted value. On a primitive
             array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
@@ -3927,6 +3929,8 @@ components:
             On an `object` it must be a JSON object string and on an `objectarray` a JSON array
             string (an object string becomes one element); the save parses it and refuses non-JSON
             or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+            JSON `null` writes the destination field as null; it is what the mapper saves for its
+            hard-coded "Use null as default value" choice.
           examples:
             - USD
             - A,B
@@ -5013,7 +5017,9 @@ components:
               - statusMapping
               - departmentCodes
           hardCodedValue:
-            type: string
+            type:
+              - string
+              - 'null'
             description: |
               Constant written to the destination instead of an extracted value. On a primitive
               array (`stringarray`, `numberarray`, `booleanarray`) the string is split on commas,
@@ -5021,6 +5027,8 @@ components:
               On an `object` it must be a JSON object string and on an `objectarray` a JSON array
               string (an object string becomes one element); the save parses it and refuses non-JSON
               or the wrong shape with 422, and an array row with a constant needs no `buildArrayHelper`.
+              JSON `null` writes the destination field as null; it is what the mapper saves for its
+              hard-coded "Use null as default value" choice.
             examples:
               - USD
               - A,B
@@ -31239,12 +31247,22 @@ components:
       description: |-
         Change-data-capture configuration for real-time listener exports (the "Listen for real-time
         data" source step). Present only when `type` is `stream`. Set on `MongodbExport` (MongoDB change
-        streams) and `RDBMSExport` (SQL Server CDC and PostgreSQL logical replication); the listener
-        streams change events continuously instead of fetching records on a schedule.
+        streams) and `RDBMSExport` (SQL Server CDC, PostgreSQL logical replication, and MySQL binary-log
+        CDC); the listener streams change events continuously instead of fetching records on a schedule.
 
         On save the API normalizes the `properties` grid into the typed fields: a `snapshot.mode`
         entry populates `snapshotMode` and a `capture.mode` entry populates `captureMode`. Every
         stream export must resolve a snapshot mode from one of those two places.
+
+        The prerequisites live on the database, not on the export: a listener saves (201) on a
+        connection whose database host is unreachable, so a successful save does not confirm them.
+        The platform's listener documentation requires: for PostgreSQL, logical replication
+        (`wal_level=logical`) and a replication-capable user; for SQL Server, CDC enabled on the
+        database and tables; for MongoDB change streams, a replica set; for MySQL, binary logging in
+        row format (`log_bin=ON`, `binlog_format=ROW`, `binlog_row_image=FULL`) and a connection user
+        holding `REPLICATION SLAVE`, `REPLICATION CLIENT` and `SELECT` on the captured tables
+        (`RELOAD` is not needed on Amazon RDS or Aurora, where the listener takes no global read
+        lock).
       x-celigo-ai-guidance:
         - |-
           A stream export that resolves no snapshot mode — neither `snapshotMode` nor a
@@ -31263,7 +31281,13 @@ components:
           description: |-
             How MongoDB change-stream events are materialized into records. Use
             `change_streams_update_full_with_pre_image` when downstream steps need the document's prior
-            state. MongoDB listeners only — `RDBMSExport` (SQL Server CDC, PostgreSQL) does not set this.
+            state. MongoDB listeners only — `RDBMSExport` (SQL Server CDC, PostgreSQL, MySQL) does not
+            set this.
+          x-celigo-ai-guidance:
+            - |-
+              Never author this on an `RDBMSExport`: the API stores it on a MySQL stream export without
+              rejecting it (unlike `slotName`, it is not gated per adaptor), so nothing at save time
+              catches the mistake and the dead setting rides on the document.
           examples:
             - change_streams_update_full
             - change_streams_update_full_with_pre_image
@@ -31281,13 +31305,17 @@ components:
             initial_only: Takes the initial snapshot and then stops, without streaming ongoing changes.
           default: no_data
           description: |-
-            Whether the listener seeds existing rows before streaming changes. Use `initial` to backfill
-            existing data on the first run; `no_data` to stream only new changes.
+            Whether the listener seeds existing rows before streaming changes. `no_data` streams only
+            new changes; `initial` backfills existing data on the first run where the listener form
+            offers it (MongoDB, SQL Server). The PostgreSQL and MySQL forms offer `no_data` and
+            `when_needed` only; the MySQL listener documentation describes `when_needed` as a one-time
+            read of the captured tables when no stream position is stored or the stored position is no
+            longer on the server.
           x-celigo-ai-guidance:
             - |-
-              The PostgreSQL listener form offers only `no_data` and `when_needed`. The API stores other
-              values on a PostgreSQL export without rejecting them, but they are outside the supported
-              PostgreSQL matrix — stay within the form's subset.
+              The PostgreSQL and MySQL listener forms offer only `no_data` and `when_needed`. The API
+              stores other values on those exports without rejecting them, but they are outside the
+              supported matrix — stay within the form's subset.
           examples:
             - initial
             - no_data
@@ -31302,8 +31330,9 @@ components:
             underscore).
           x-celigo-ai-guidance:
             - |-
-              PostgreSQL connections only: on any other connection the save is rejected 422
-              `not_allowed` ("CDC slotName can only be used with postgresql adaptor type").
+              PostgreSQL connections only: on any other connection — SQL Server, MySQL — the save is
+              rejected 422 `not_allowed` ("CDC slotName can only be used with postgresql adaptor type").
+              MySQL CDC reads the binary log directly; it has no replication slot.
             - |-
               The identifier pattern is enforced server-side — an invalid name (uppercase, dashes) is
               rejected 422 `invalid_field_value` at save time.
@@ -31323,17 +31352,27 @@ components:
               sent, so nothing catches the ambiguity at save time — the exclusivity is the listener
               form's rule (publication wins as the sole table filter).
             - |-
-              PostgreSQL connections only: rejected 422 `not_allowed` on other connections, and the
-              identifier pattern is enforced server-side like `slotName`.
+              PostgreSQL connections only: rejected 422 `not_allowed` on other connections (SQL Server,
+              MySQL — "CDC publicationName can only be used with postgresql adaptor type"), and the
+              identifier pattern is enforced server-side like `slotName`. A MySQL listener scopes
+              tables only through `rdbms.tables` and the include / exclude `properties`.
+            - |-
+              On a PostgreSQL connection one of this field or `rdbms.tables` must be present: a stream
+              export carrying neither is rejected 422 `missing_required_field` on both paths
+              ("publicationName is required when tables is not provided." / "tables is required when
+              publicationName is not provided."). SQL Server and MySQL listeners save without either.
           examples:
             - celigo_pub
             - orders_publication
         cursor:
           type: string
           description: |-
-            Server-managed stream position marker (where the listener resumes reading change events).
+            Server-managed stream position marker (where the listener resumes reading change events;
+            the MySQL listener documentation describes it as the binlog file and position last saved).
             Maintained by the platform as events are consumed; the UI exposes a reset workflow for it
-            under Cursor Management.
+            under Cursor Management, which appears once a cursor exists. The form's reset is a full save that omits `cursor` and carries the
+            top-level request flag `pendingCursorReset: true`; the API accepts the flag and does not
+            store it on the document.
           x-celigo-ai-guidance:
             - Never author or modify this field — the platform owns the stream position.
         paths:
@@ -31342,17 +31381,33 @@ components:
             type: string
           description: |-
             Dot-notation paths within each raw change event to retain in the emitted record. MongoDB
-            listeners default to `["payload"]` (the whole change document); SQL Server and PostgreSQL
-            listeners commonly select `payload.after`, `payload.op`, and related fields to expose the
-            changed row and operation type.
+            listeners default to `["payload"]` (the whole change document); SQL Server, PostgreSQL and
+            MySQL listeners commonly select `payload.after`, `payload.op`, and related fields to expose
+            the changed row and operation type. The MySQL listener form offers `payload.after`,
+            `payload.before`, `schema`, `payload.source`, `payload.op`, `payload.transaction`,
+            `payload.ts_ms`, `payload.ts_us` and `payload.ts_ns`, preselecting `payload.after`; it has
+            no `updateDescription`-derived options and no `payload.id`. The MySQL listener
+            documentation describes `after` as the row after the change (empty on a delete), `before`
+            as the row before an update or delete (needs `binlog_row_image=FULL`), `op` as `c` / `u` /
+            `d` / `r` (insert / update / delete / snapshot read) and `source` as the database, table,
+            binlog file and position.
           examples:
             - - payload
             - - payload.after
               - payload.op
+            - - payload.after
+              - payload.before
+              - payload.op
         intervalTime:
           type: integer
           default: 300
-          description: Polling interval, in seconds, at which the listener checks the source for new change events.
+          minimum: 30
+          x-celigo-ui-override: The minimum mirrors the listener forms, which label this field Max wait time and reject a value under 30 ("Max wait time must be at least 30 seconds."); the API itself stores a lower value.
+          description: |-
+            Interval, in seconds, that bounds how long the listener holds change events before sending
+            a page downstream. The listener forms label it Max wait time, and the platform's listener
+            documentation describes it as the longest a page waits when fewer than `pageSize` events
+            have arrived — a full page is sent as soon as it fills.
           examples:
             - 300
             - 30
@@ -31361,11 +31416,25 @@ components:
           description: |-
             Connector-engine settings passed through to the underlying CDC connector as name/value
             pairs. Mirrors the form's additional-properties grid: the required keys (`capture.mode`
-            and `snapshot.mode` for MongoDB, `snapshot.mode` for SQL Server and PostgreSQL) are
+            and `snapshot.mode` for MongoDB, `snapshot.mode` for SQL Server, PostgreSQL and MySQL) are
             serialized first, followed by optional keys such as `field.exclude.list`,
             `column.include.list`, or `snapshot.collection.filter.overrides.<db>.<collection>`.
             On save the API also lifts `snapshot.mode` / `capture.mode` entries into the typed
             `snapshotMode` / `captureMode` fields.
+
+            The MySQL listener form offers six keys: `snapshot.mode` (preselected `no_data`) and five
+            optional comma-separated regular-expression lists — `table.exclude.list` (matched on
+            `database.table`), `database.include.list`, `database.exclude.list`,
+            `column.include.list` and `column.exclude.list` (matched on `database.table.column`).
+            MySQL has no schema layer, so there are no `schema.include.list` / `schema.exclude.list`
+            keys, and the MongoDB keys (`capture.mode`, `collection.exclude.list`,
+            `field.exclude.list`) do not apply. The MySQL listener documentation describes a blank
+            watch list as every table the connection's user can read, trimmed by `table.exclude.list`.
+          x-celigo-ai-guidance:
+            - |-
+              The API persists any key sent here without validating it against the connector, so a
+              MongoDB or PostgreSQL key on a MySQL listener saves cleanly and does nothing — author only
+              the keys the listener's form offers.
           items:
             type: object
             required:
@@ -37290,8 +37359,8 @@ components:
         for other connection types. For query-type exports (standard, delta, once) it is REQUIRED
         when the _connectionId field references an RDBMS database connection and holds the SQL
         query. For real-time stream listeners (`type: "stream"`) it holds the CDC watch list
-        (`tables`) instead — and a PostgreSQL listener scoped by a publication
-        (`cdc.publicationName`) may omit this object entirely.
+        (`tables`) instead — and a SQL Server or MySQL listener with no watch list, or a PostgreSQL
+        listener scoped by a publication (`cdc.publicationName`), may omit this object entirely.
 
         **Rdbms export capabilities**
         - Execute custom SQL SELECT statements
@@ -37345,8 +37414,8 @@ components:
         ```
 
         **Real-time CDC listener exports (type: "stream")**
-        SQL Server and PostgreSQL connections support change-data-capture listeners that stream row
-        changes continuously (the `cdc` object holds the listener settings). A stream export has NO
+        SQL Server, PostgreSQL and MySQL connections support change-data-capture listeners that stream
+        row changes continuously (the `cdc` object holds the listener settings). A stream export has NO
         `query` — it watches `tables`:
         ```json
         {
@@ -37355,9 +37424,26 @@ components:
           "cdc": { "properties": [{ "name": "snapshot.mode", "value": "no_data" }] }
         }
         ```
+        A MySQL listener names its tables as `database.table` (MySQL has no schema layer):
+        ```json
+        {
+          "type": "stream",
+          "rdbms": { "tables": "sales.orders,sales.order_lines" },
+          "cdc": {
+            "properties": [{ "name": "snapshot.mode", "value": "no_data" }],
+            "paths": ["payload.after", "payload.op"]
+          }
+        }
+        ```
         A PostgreSQL listener can instead scope tables through a publication
         (`cdc.publicationName`), in which case `tables` stays unset and the `rdbms` object may be
-        omitted entirely.
+        omitted entirely; on PostgreSQL one of the two must be present. SQL Server and MySQL
+        listeners save with no `tables` and no `rdbms` object at all (a blank `tables` string is
+        dropped on save); the MySQL listener documentation describes that as every table the
+        connection's user can read, trimmed by the `table.exclude.list` property.
+        `POST /v1/exports/preview` rejects a stream export both with `rdbms.tables` sent and with
+        no `rdbms` object at all, with the same 422 `missing_required_field` ("rdbms subschema not
+        defined") — listeners have no preview.
       properties:
         tables:
           type: string
@@ -37365,16 +37451,26 @@ components:
             Comma-separated list of tables the CDC listener watches for changes. Used only by real-time
             listener exports (`type` is `stream`); standard SQL exports use `query` instead. SQL Server
             listeners use fully-qualified three-part names (`database.schema.table`); PostgreSQL
-            listeners use two-part names (`schema.table`).
+            listeners use two-part names (`schema.table`); MySQL listeners use two-part
+            `database.table` names, since MySQL has no schema layer between the database and the
+            table. A PostgreSQL listener must carry this field or `cdc.publicationName`; SQL Server
+            and MySQL listeners may leave it out (for MySQL the listener documentation describes that
+            as every table the connection's user can read, trimmed by `table.exclude.list`).
           x-celigo-ai-guidance:
             - |-
               For a PostgreSQL listener, author EITHER this field OR `cdc.publicationName`, never both —
               when a publication is set it is the sole table filter and the listener form clears this
               field (the API stores both if sent, so nothing catches the conflict at save time).
+            - |-
+              The API does not validate the names against the engine — a three-part name on a MySQL
+              listener saves cleanly — so nothing at save time catches the wrong form. Use the engine's
+              own: `database.table` on MySQL, `schema.table` on PostgreSQL, `database.schema.table` on
+              SQL Server.
           examples:
             - UKGODS.dbo.UKG_MetadataStaging
             - dbo.WorkOrderT,dbo.OrderLineT
             - public.orders,public.customers
+            - sales.orders,sales.order_lines
         query:
           type: string
           x-celigo-agent:
@@ -38206,8 +38302,8 @@ components:
               - **Listen for inbound events from NetSuite or Salesforce**
                 -> `distributed`
               - **Stream database changes in real time as they happen**
-                (change data capture from MongoDB, SQL Server, or
-                PostgreSQL — "when a row changes", "listen to my table")
+                (change data capture from MongoDB, SQL Server, PostgreSQL
+                or MySQL — "when a row changes", "listen to my table")
                 -> `stream`, configured via the `cdc` object
               - **Subscribe to an Event Streams topic** ("listen to topic X",
                 "consume messages published to …") -> `stream` with
@@ -38231,8 +38327,8 @@ components:
               delta config is a separate concern that scopes how you fill in
               the chosen config, not whether to use it.
             - |-
-              `stream` is accepted only on MongoDB and RDBMS exports (SQL Server
-              or PostgreSQL connections) and on Event Streams listeners
+              `stream` is accepted only on MongoDB and RDBMS exports (SQL Server,
+              PostgreSQL or MySQL connections) and on Event Streams listeners
               (`adaptorType: TopicExport`); every other adaptor rejects the save
               with `unsupported_export_type`. A MongoDB or RDBMS stream export
               must carry `cdc.snapshotMode` (and `cdc.captureMode` on MongoDB) —
@@ -38257,7 +38353,7 @@ components:
             simple: Allows manual file uploads through the data loader UI.
             blob: Retrieves raw files without parsing them into structured data records.
             distributed: Listens for real-time events from NetSuite or Salesforce.
-            stream: Streams events in real time — database change data capture (MongoDB change streams, SQL Server CDC, PostgreSQL logical replication) configured through the `cdc` object, or an Event Streams topic subscription (`TopicExport`) configured through `topic`.
+            stream: Streams events in real time — database change data capture (MongoDB change streams, SQL Server CDC, PostgreSQL logical replication, MySQL binary log) configured through the `cdc` object, or an Event Streams topic subscription (`TopicExport`) configured through `topic`.
             all: Explicitly retrieves all available records — equivalent to omitting `type`.
           examples:
             - webhook
@@ -38384,6 +38480,21 @@ components:
           $ref: '#/components/schemas/Distributed'
         cdc:
           $ref: '#/components/schemas/Cdc'
+        pendingCursorReset:
+          type: boolean
+          writeOnly: true
+          description: |-
+            When true on a save of a stream listener, requests a reset of the listener's stored stream
+            position — the Cursor Management reset the listener form sends, with `cdc.cursor` omitted
+            from the same document; the listener documentation describes the save as clearing the
+            stored cursor and restarting the listener. Accepted on the request and not stored on the
+            export.
+          x-celigo-ai-guidance:
+            - |-
+              Never author this flag — like `cdc.cursor`, the stream position is the platform's, and
+              the reset is the listener form's Cursor Management action. The API accepts it silently
+              (200) and the readback carries no trace that it was sent, so a save that carried it by
+              mistake cannot be seen afterwards on the export.
         topic:
           $ref: '#/components/schemas/Topic-2'
         filesystem:

package/package.json

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