@celigo/api-specs 0.2.38 → 0.2.40

package/dist/export.yml

@@ -111,6 +111,16 @@ paths:
                   http:
                     relativeURI: /api/v1/contacts
                     method: GET
+              topic_listener:
+                summary: Event Streams listener on a topic (no connection)
+                value:
+                  name: Order Events Listener
+                  adaptorType: TopicExport
+                  type: stream
+                  topic:
+                    _topicId: 6ab1f48d38d7733b4599875c
+                    startPosition: latest
+                    maxWaitTimeMs: 30000
       responses:
         '201':
           description: Export created successfully
@@ -133,6 +143,21 @@ paths:
                     apiIdentifier: e53af6b210
                     createdAt: '2026-06-09T17:30:12.482Z'
                     lastModified: '2026-06-09T17:30:12.554Z'
+                topic_listener:
+                  summary: Created Event Streams listener — topic defaults filled in
+                  value:
+                    _id: 6ab1f553de9162306b4d7bac
+                    name: Order Events Listener
+                    adaptorType: TopicExport
+                    type: stream
+                    topic:
+                      _topicId: 6ab1f48d38d7733b4599875c
+                      startPosition: latest
+                      maxWaitTimeMs: 30000
+                    asynchronous: true
+                    apiIdentifier: ea8179ebf0
+                    createdAt: '2026-09-22T03:26:11.864Z'
+                    lastModified: '2026-09-22T03:26:11.905Z'
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -5588,18 +5613,33 @@ components:
             - /mnt/nas/backups/clients/acme
             - ./backups
             - ~/integrations/backups
+        includeSubdirectories:
+          type: boolean
+          default: false
+          x-celigo-ui-override: 'Defaulted by the Azure Data Lake Storage Gen2 export form (fieldDefinitions/resources/exports/azuredatalakestoragegen2.js: ''file.includeSubdirectories'' defaultValue r?.file?.includeSubdirectories === true, visible only for that assistant). The API stores the flag on any file export; the form offers it for ADLS Gen2 only.'
+          description: |-
+            When true, an Azure Data Lake Storage Gen2 transfer (`assistant: azuredatalakestoragegen2`,
+            `http.type: file`) also picks up files in the subdirectories below the directory path in
+            `http.relativeURI`; when false or omitted only that directory's own files are transferred.
+          examples:
+            - true
+            - false
         directory:
           type: object
           required:
             - pathMode
           description: |-
             Structured source location for cloud file-provider sources (Google Drive shared drives,
-            Box, Dropbox), replacing the flat path used by classic FTP/S3 sources. Select the location
-            by folder ID or by a path relative to a configured storage root via pathMode. For these
-            cloud providers, directoryId mode addresses the folder by id alone — the flat
-            relative-path field is not consulted at runtime.
+            Box, Dropbox, Google Cloud Storage, Azure Data Lake Storage Gen2), replacing the flat path
+            used by classic FTP/S3 sources. Select the location by folder ID or by a path relative to
+            a configured storage root via pathMode. For the drive-style providers, directoryId mode
+            addresses the folder by id alone — the flat relative-path field is not consulted at
+            runtime. Google Cloud Storage puts the bucket in `storageRootId` and the object prefix in
+            `id` with `pathMode: directoryId`; Azure Data Lake Storage Gen2 puts the container in
+            `name` and the directory path in `http.relativeURI`.
           x-celigo-ai-guidance:
             - Save-time validation accepts any string for id without checking it against the provider — set it only from a folder ID the user supplied or the UI folder browser stored; never fabricate one. To address a folder by path instead, set pathMode to relativePath and put the path in the adaptor's flat path field.
+            - '`id` and `pathMode` are validated as a pair: `pathMode: directoryId` without `id` fails with 422 `missing_required_field` ("File exports require the file.directory.id to have a value."), and `id` with any other pathMode fails with 422 `missing_required_field` ("File exports require the file.directory.pathMode to have a value.").'
           properties:
             pathMode:
               type: string
@@ -5618,22 +5658,29 @@ components:
               description: |-
                 Provider-native folder ID of the source directory (e.g. a Google Drive folder ID); set
                 when pathMode is directoryId. This is the file provider's own ID, not a Celigo resource ID.
+                For Google Cloud Storage it is the object prefix inside the bucket, ending with `/`.
               examples:
                 - 1KppvTTr4jKhJqwPAhGWN6SRwk5m45DL2
+                - inbound/orders/
             name:
               type: string
               description: |-
                 Display name of the folder identified by id, kept for readability in the UI; the
-                folder browser fills it when the location is picked visually.
+                folder browser fills it when the location is picked visually. For Azure Data Lake
+                Storage Gen2 it is the authoritative container name instead — the form saves the
+                container here and no id.
               examples:
                 - Invoices - Inbound
+                - invoices-inbound
             storageRootId:
               type: string
               description: |-
                 Provider-native ID of the storage root (e.g. a Google Drive shared-drive ID) the relative
                 path resolves against; set when pathMode is relativePath. The provider's own ID, not a Celigo ID.
+                For Google Cloud Storage it is the bucket name.
               examples:
                 - 1qU1hvFarBFMb4-twqKm1rR5o_6j9vs9g
+                - erp-exports
             storageRootName:
               type: string
               description: Display name of the storage root identified by storageRootId, retained for reference in the UI.
@@ -5884,6 +5931,73 @@ components:
                 examples:
                   - no_data
                   - schema.table.column1,schema.table.column2
+    Topic:
+      type: object
+      description: |-
+        Subscription settings for an Event Streams listener (`adaptorType: TopicExport`). The
+        listener consumes messages published to the topic and hands them to the flow in batches;
+        the platform delivers them internally, so the export carries no `_connectionId`. Present
+        when `adaptorType` is `TopicExport`; the server fills `startPosition` and `maxWaitTimeMs`
+        with their defaults when they are omitted.
+      x-celigo-ai-guidance:
+        - |-
+          Send `type: "stream"` together with this object, as the listener form always does; the
+          save also succeeds without `type`, so nothing catches the omission at save time. Sending
+          this object without `adaptorType` is enough for the server to infer `TopicExport`.
+        - |-
+          Never add a `_connectionId`: the server then validates the document as that connection's
+          adaptor instead (an http connection fails with 422 missing_required_field "http subschema
+          not defined"). A TopicExport carries no `cdc` object either — sending `cdc.snapshotMode`
+          fails with 422 `not_allowed` ("CDC snapshotMode can only be used with stream export type").
+      properties:
+        _topicId:
+          type: string
+          format: objectId
+          x-celigo-refModel: topics
+          x-celigo-ui-override: 'Required by the Event Streams listener form (fieldDefinitions/resources/exports/export.js: ''topic._topicId'' is required:true, validWhen isNot ''''). The API saves a TopicExport without it, so the requirement is encoded on the request schema to mirror the form and keep listeners bound to a topic.'
+          description: |-
+            Topic this listener subscribes to. Create or look it up with `GET /v1/topics`; the
+            topic must belong to the same account. Pointing an existing listener at a different
+            topic starts a new subscription, read from `startPosition`.
+          x-celigo-ai-guidance:
+            - |-
+              An id that is not a topic in the account fails the save with 422 `invalid_ref`
+              ("<id> is not a valid topic._topicId"); a malformed id fails with 422 `invalid_field`.
+          examples:
+            - 6ab1f48d38d7733b4599875c
+        startPosition:
+          type: string
+          enum:
+            - latest
+            - earliest
+          default: latest
+          x-enumDescriptions:
+            latest: Deliver only messages published after the listener subscribes
+            earliest: Replay every retained message on the topic before delivering new ones
+          description: |-
+            Where the listener starts reading when it first subscribes to `_topicId`. Use `earliest`
+            to backfill retained history, `latest` (the default) to process only new messages. Read
+            on create and whenever `_topicId` changes; on other updates the stored value is kept even
+            if a different value is sent.
+          examples:
+            - latest
+            - earliest
+        maxWaitTimeMs:
+          type: integer
+          minimum: 1000
+          default: 30000
+          description: |-
+            Longest time, in milliseconds, the listener waits to fill a batch before delivering
+            whatever it has collected. Lower values reduce latency for sparse topics; the default
+            of 30 seconds favors fuller batches. The batch record cap is the export's `pageSize`.
+          x-celigo-ai-guidance:
+            - |-
+              Values below 1000 (including 0 and negatives) fail the save with 422 `min`
+              ("Path `topic.maxWaitTimeMs` (0) is less than minimum allowed value (1000)"). The form
+              edits this as whole seconds and saves seconds × 1000.
+          examples:
+            - 30000
+            - 5000
     FileSystem:
       type: object
       description: |-
@@ -6034,23 +6148,33 @@ components:
             - graph_ql
         method:
           type: string
-          description: HTTP method used to request data from the target API. Consult the target API's documentation to determine the appropriate method.
+          description: |-
+            HTTP method used to request data from the target API. Consult the target API's
+            documentation to determine the appropriate method. `HEAD` exists for connector endpoints
+            that return metadata in response headers only (Azure Data Lake Storage Gen2 path
+            properties).
           enum:
             - GET
             - POST
             - PUT
             - PATCH
             - DELETE
+            - HEAD
           x-enumDescriptions:
             GET: Retrieves data from the target API without modifying resources.
             POST: Sends a request body to the target API when body criteria are needed, commonly used for RPC or SOAP/XML-based data retrieval
             PUT: Sends a full replacement payload, available for APIs that support it for data retrieval.
             PATCH: Sends a partial update payload, less common for exports but available for specialized APIs.
             DELETE: Requests resource deletion, rarely used for exports but available for specialized use cases.
+            HEAD: Requests only the response headers, for connector endpoints that expose metadata that way (e.g. ADLS Gen2 path properties); there is no body to parse
+          x-celigo-ai-guidance:
+            - |-
+              Any other verb fails the save with 422 `enum` ("`OPTIONS` is not a valid enum value for
+              path `http.method`"). Import `http.method` does not accept `HEAD`.
           examples:
             - GET
             - POST
-            - PUT
+            - HEAD
         followRedirects:
           type: boolean
           default: true
@@ -7640,21 +7764,6 @@ components:
               `GET /v1/httpconnectors/{_id}/{_httpConnectorResourceId}/{_id}` for an endpoint's `method` and
               `relativeURI`. A top-level `_httpConnectorId` on the export itself is dropped. Verified against
               the live API 2026-09-21.
-      if:
-        properties:
-          type:
-            const: file
-        required:
-          - type
-        not:
-          properties:
-            formType:
-              const: assistant
-          required:
-            - formType
-      then:
-        required:
-          - file
     Salesforce:
       type: object
       description: 'Configuration for Salesforce exports. Required when the export''s `_connectionId` references a Salesforce connection; omit for other connection types. The `type` field selects the extraction mode: `soql` runs batch queries and requires the `soql` object, while `distributed` listens for real-time events and requires the `distributed` object. File retrieval (when the export''s `type` is `blob`) requires `sObjectType` and `id` instead.'
@@ -9571,9 +9680,12 @@ components:
     MongoDB:
       type: object
       description: |-
-        Defines how documents are retrieved from MongoDB collections. Required when the
-        _connectionId field references a MongoDB connection; must not be included for other
-        connection types. Supports find queries with optional filter criteria and field projections.
+        Defines how documents are retrieved from MongoDB collections. Required, with `method` and
+        `collection`, when the _connectionId field references a MongoDB connection and the export
+        fetches documents; must not be included for other connection types. A change-stream
+        listener (`type: stream`) is configured through `cdc` instead and may omit this object, or
+        set only `collection` to scope the listener. Supports find queries with optional filter
+        criteria and field projections.
       x-celigo-ai-guidance:
         - Configuration object for MongoDB data integration exports.
         - |-
@@ -9582,8 +9694,11 @@ components:
           - Filters documents based on query criteria
           - Selects specific fields with projections
           - Provides NoSQL flexibility with JSON query syntax
-      required:
-        - collection
+        - |-
+          On a find export both `method` and `collection` are validator-enforced: omitting either
+          fails the save with 422 `missing_required_field` ("Expected field: collection to be
+          present." / "Expected field: method to be present."). On a `type: stream` listener neither
+          is required and the object is returned only when `collection` is set.
       properties:
         method:
           type: string
@@ -9601,7 +9716,7 @@ components:
 
               This field defines the query approach:
 
-              - REQUIRED for all MongoDB exports
+              - REQUIRED for find exports (not for `type: stream` listeners)
               - Currently only supports "find" operations
               - Determines how other parameters are interpreted
               - Corresponds to MongoDB's db.collection.find() method
@@ -9635,10 +9750,11 @@ components:
             - find
         collection:
           type: string
-          x-celigo-ui-override: Required by the MongoDB export form (mongodb.collection is required:true). Encoded to mirror the form so builders produce connectable configurations.
           description: |-
             Name of the MongoDB collection to query. Case-sensitive and must reference an existing
-            collection in the connected database.
+            collection in the connected database. Required on find exports; on a change-stream
+            listener (`type: stream`) it is optional and may list several collections separated by
+            commas, matching the listener form's "Collections" field.
           x-celigo-ai-guidance:
             - Specifies the MongoDB collection to query for documents.
             - |-
@@ -9646,7 +9762,7 @@ components:
 
               This field identifies the data source:
 
-              - REQUIRED for all MongoDB exports
+              - REQUIRED for find exports; optional (single or comma-separated) on `type: stream` listeners
               - Must reference a valid collection in the MongoDB database
               - Case-sensitive according to MongoDB collection naming
               - The primary container for documents to be retrieved
@@ -9654,7 +9770,7 @@ components:
             - customers
             - orders
             - product_catalog
-            - user_profiles
+            - users, orders, products
         filter:
           type: string
           description: |-
@@ -9900,7 +10016,7 @@ components:
             - distributed
             - file
           x-enumDescriptions:
-            search: Retrieves records using a NetSuite saved search.
+            search: Retrieves records with a NetSuite saved search over SOAP web services; the export form marks this path deprecated in favour of the REST APIs for new exports
             basicSearch: Retrieves records using a basic NetSuite search query.
             metadata: Retrieves metadata about a NetSuite record type.
             selectoption: Retrieves the available select options for a specific field.
@@ -15918,7 +16034,9 @@ components:
             Connection this export uses to reach the source system. The connection's type must be
             compatible with the export's `adaptorType` (e.g. an `HTTPExport` needs an `http` connection;
             `NetSuiteExport` and `NetSuiteHTTPExport` both need a `netsuite` connection).
-            Server-required unless `type` is `webhook` or `simple` (those receive data instead of fetching it).
+            Server-required unless `type` is `webhook` or `simple` (those receive data instead of
+            fetching it) or `adaptorType` is `TopicExport` (Event Streams listeners are delivered
+            by the platform itself and must omit it).
           examples:
             - 60a2c4e6f321d800129a1a3c
         adaptorType:
@@ -15943,6 +16061,7 @@ components:
             - SimpleExport
             - WebhookExport
             - FileSystemExport
+            - TopicExport
             - RESTExport
           x-enumDescriptions:
             HTTPExport: Exports data from generic REST or SOAP APIs over HTTP.
@@ -15960,12 +16079,14 @@ components:
             SimpleExport: Exports data via manual file uploads through the data loader UI.
             WebhookExport: Listens for incoming HTTP requests as a real-time event endpoint.
             FileSystemExport: Exports files from a local or mounted file system.
+            TopicExport: Listens to an Event Streams topic and delivers its messages in batches, configured through `topic`; needs no connection.
             RESTExport: Legacy REST adaptor, superseded by HTTPExport — still accepted and present on older exports.
           examples:
             - HTTPExport
             - NetSuiteExport
             - NetSuiteHTTPExport
             - SalesforceExport
+            - TopicExport
           x-celigo-ai-guidance:
             - |-
               On a netsuite connection, default to `NetSuiteHTTPExport` (with `nsDomainType` and an
@@ -16065,6 +16186,10 @@ components:
                 (change data capture from MongoDB, SQL Server, or
                 PostgreSQL — "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
+                `adaptorType: TopicExport`, configured via the `topic` object
+                (no `cdc`, no `_connectionId`)
               - **Transfer raw files WITHOUT parsing their contents into
                 records** (images, PDFs, binaries) -> `blob`
               - **Manual data uploads via the data loader UI** -> `simple`
@@ -16084,8 +16209,11 @@ components:
               the chosen config, not whether to use it.
             - |-
               `stream` is accepted only on MongoDB and RDBMS exports (SQL Server
-              or PostgreSQL connections); every other adaptor rejects the save
-              with `unsupported_export_type`.
+              or PostgreSQL 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) —
+              omitting them fails with 422 `missing_required_field` on those paths.
           enum:
             - webhook
             - test
@@ -16106,7 +16234,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 database changes in real time via change data capture (MongoDB change streams, SQL Server CDC, PostgreSQL logical replication), configured through the `cdc` object.
+            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`.
             all: Explicitly retrieves all available records — equivalent to omitting `type`.
           examples:
             - webhook
@@ -16209,6 +16337,8 @@ components:
           $ref: '#/components/schemas/Distributed'
         cdc:
           $ref: '#/components/schemas/Cdc'
+        topic:
+          $ref: '#/components/schemas/Topic'
         filesystem:
           $ref: '#/components/schemas/FileSystem'
         http:
@@ -16470,7 +16600,16 @@ components:
           $ref: '#/components/schemas/PreSave'
         assistant:
           type: string
-          description: Identifier for the connector assistant used to configure this export.
+          description: |-
+            Identifier for the connector assistant used to configure this export. For the cloud
+            file providers it also selects the provider-specific location rules —
+            `azuredatalakestoragegen2` (container in `file.directory.name`, path in
+            `http.relativeURI`) and `googlecloudstorage` (bucket in `file.directory.storageRootId`,
+            prefix in `file.directory.id`).
+          examples:
+            - shopify
+            - azuredatalakestoragegen2
+            - googlecloudstorage
         assistantMetadata:
           type:
             - object
@@ -16774,7 +16913,8 @@ components:
       description: |-
         Fields that can be sent when creating or updating an export. Set the adaptor-specific
         configuration object matching `adaptorType`, and the mode-specific object matching `type`.
-        `SimpleExport` (data-loader) is the exception — it needs no adaptor config object.
+        `SimpleExport` (data-loader) is the exception — it needs no adaptor config object. An Event
+        Streams listener (`TopicExport`) carries `topic` and `type: stream` and no `_connectionId`.
       required:
         - name
       allOf:
@@ -16788,6 +16928,64 @@ components:
       then:
         required:
           - http
+        if:
+          properties:
+            assistant:
+              const: azuredatalakestoragegen2
+          required:
+            - assistant
+        then:
+          x-celigo-ui-override: 'Required by the Azure Data Lake Storage Gen2 export form (fieldDefinitions/resources/exports/azuredatalakestoragegen2.js: ''file.directory.storageRootId_adls'' is required:true and preSave persists it as file.directory.name; the directory path in http.relativeURI is required:false). Encoded to mirror the form so builders produce connectable configurations.'
+          required:
+            - file
+          properties:
+            file:
+              required:
+                - directory
+              properties:
+                directory:
+                  required:
+                    - name
+        else:
+          if:
+            properties:
+              assistant:
+                const: googlecloudstorage
+            required:
+              - assistant
+          then:
+            x-celigo-ui-override: 'Required by the Google Cloud Storage export form (fieldDefinitions/resources/exports/googlecloudstorage.js: bucket ''file.directory.storageRootId_gcs'' is required:true and prefix ''file.directory.id'' is required:true; preSave forces file.directory.pathMode to directoryId). Encoded to mirror the form so builders produce connectable configurations.'
+            required:
+              - file
+            properties:
+              file:
+                required:
+                  - directory
+                properties:
+                  directory:
+                    required:
+                      - storageRootId
+                      - id
+          else:
+            if:
+              required:
+                - http
+              properties:
+                http:
+                  required:
+                    - type
+                  properties:
+                    type:
+                      const: file
+                  not:
+                    required:
+                      - formType
+                    properties:
+                      formType:
+                        const: assistant
+            then:
+              required:
+                - file
       else:
         if:
           properties:
@@ -16885,8 +17083,23 @@ components:
                           required:
                             - adaptorType
                         then:
-                          required:
-                            - mongodb
+                          if:
+                            properties:
+                              type:
+                                const: stream
+                            required:
+                              - type
+                          then:
+                            required:
+                              - cdc
+                          else:
+                            required:
+                              - mongodb
+                            properties:
+                              mongodb:
+                                required:
+                                  - method
+                                  - collection
                         else:
                           if:
                             properties:
@@ -16937,6 +17150,21 @@ components:
                                   then:
                                     required:
                                       - http
+                                  else:
+                                    if:
+                                      properties:
+                                        adaptorType:
+                                          const: TopicExport
+                                      required:
+                                        - adaptorType
+                                    then:
+                                      x-celigo-ui-override: 'Required by the Event Streams listener form (fieldDefinitions/resources/exports/export.js: ''topic._topicId'' is required:true). Encoded to mirror the form so builders produce listeners that are bound to a topic.'
+                                      required:
+                                        - topic
+                                      properties:
+                                        topic:
+                                          required:
+                                            - _topicId
     Error:
       type: object
       description: Standard error response envelope returned by integrator.io APIs.
@@ -17206,6 +17434,13 @@ components:
           description: Display name of the dependent resource.
           examples:
             - Import Orders to NetSuite
+        type:
+          type: string
+          description: |-
+            Sub-type of the dependent resource when its collection distinguishes one, such as
+            `stream` for a listener export. Only present for resource types that carry a `type`.
+          examples:
+            - stream
         paths:
           type: array
           description: |-

package/dist/filedefinition.yml

@@ -1286,6 +1286,13 @@ components:
           description: Display name of the dependent resource.
           examples:
             - Import Orders to NetSuite
+        type:
+          type: string
+          description: |-
+            Sub-type of the dependent resource when its collection distinguishes one, such as
+            `stream` for a listener export. Only present for resource types that carry a `type`.
+          examples:
+            - stream
         paths:
           type: array
           description: |-