@celigo/api-specs 0.2.1

package/dist/eventreport.yml

@@ -0,0 +1,692 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Event Reports
+  description: API for generating and downloading Celigo event reports — CSV exports of flow execution event data over a time window.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Event Reports
+    description: |-
+      Event reports capture flow execution event data over a time window and
+      produce a downloadable CSV once generation completes. Use them for
+      compliance auditing, SLA reporting, and bulk error analysis.
+
+      The typical lifecycle is: create a report with target flow IDs and a
+      time range, poll until status reaches `completed`, then download the
+      CSV via a time-limited signed URL.
+
+      ## Event report schema
+
+      {% openapi-schemas spec="eventreport" schemas="EventReport" grouped="true" %}
+paths:
+  /v1/eventreports:
+    post:
+      x-internal: false
+      operationId: createEventReport
+      tags:
+        - Event Reports
+      summary: Create an event report
+      description: |-
+        Queues generation of a new event report for the specified flows and time window. The report
+        is created in `queued` status and transitions through `running` to `completed` (or `canceled`).
+
+        `startTime` must be within the last 30 days and the span to `endTime` must not exceed 3 days.
+        If `endTime` is omitted, the server defaults it to the current time. Poll
+        `GET /v1/eventreports/{_id}` until `status` is `completed`, then download the CSV via
+        `GET /v1/eventreports/{_id}/signedURL`. The create response includes `_requestedByUserId`;
+        subsequent GET responses replace this with the `requestedByUser` object (name + email).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/EventReportCreateRequest'
+            examples:
+              single_flow:
+                summary: Report for a single flow over two days
+                value:
+                  type: flow_events
+                  _flowIds:
+                    - 63a1b2c3d4e5f60011223344
+                  startTime: '2026-04-27T00:00:00.000Z'
+                  endTime: '2026-04-29T00:00:00.000Z'
+              multiple_flows:
+                summary: Report for multiple flows (endTime defaults to now)
+                value:
+                  type: flow_events
+                  _flowIds:
+                    - 63a1b2c3d4e5f60011223344
+                    - 63a1b2c3d4e5f60011223355
+                  startTime: '2026-04-28T00:00:00.000Z'
+      responses:
+        '201':
+          description: Event report created and queued for generation.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventReport'
+              examples:
+                created:
+                  summary: Newly created event report
+                  value:
+                    _id: 682278b3e4b0a10012abcdef
+                    _requestedByUserId: 60f1a2b3c4d5e6f7a8b9c0d1
+                    type: flow_events
+                    _flowIds:
+                      - 63a1b2c3d4e5f60011223344
+                    startTime: '2026-04-27T00:00:00.000Z'
+                    endTime: '2026-04-29T00:00:00.000Z'
+                    status: queued
+                    reportGenerationErrors: []
+                    createdAt: '2026-04-29T14:30:00.000Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    get:
+      x-internal: false
+      operationId: listEventReports
+      tags:
+        - Event Reports
+      summary: List event reports
+      description: |-
+        Returns all event report objects for the account. No pagination or
+        filtering is supported — query parameters like `eventReportId`,
+        `_limit`, and `status` are accepted but silently ignored.
+      responses:
+        '200':
+          description: Array of event report objects.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/EventReport'
+              examples:
+                list:
+                  summary: List with one completed and one queued report
+                  value:
+                    - _id: 682278b3e4b0a10012abcdef
+                      type: flow_events
+                      _flowIds:
+                        - 63a1b2c3d4e5f60011223344
+                      startTime: '2026-04-27T00:00:00.000Z'
+                      endTime: '2026-04-29T00:00:00.000Z'
+                      status: completed
+                      reportGenerationErrors: []
+                      createdAt: '2026-04-28T14:30:00.000Z'
+                      startedAt: '2026-04-28T14:30:05.000Z'
+                      endedAt: '2026-04-28T14:32:00.000Z'
+                      requestedByUser:
+                        name: Jane Doe
+                        email: jane.doe@example.com
+                    - _id: 682278b3e4b0a10012aaaaaa
+                      type: flow_events
+                      _flowIds:
+                        - 63a1b2c3d4e5f60011223355
+                      startTime: '2026-04-28T00:00:00.000Z'
+                      endTime: '2026-04-29T12:00:00.000Z'
+                      status: queued
+                      reportGenerationErrors: []
+                      createdAt: '2026-04-29T15:00:00.000Z'
+                      requestedByUser:
+                        name: Jane Doe
+                        email: jane.doe@example.com
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/eventreports/{_id}:
+    get:
+      x-internal: false
+      operationId: getEventReportById
+      tags:
+        - Event Reports
+      summary: Get an event report
+      description: |-
+        Returns a single event report by ID. Check `status` for `completed` before attempting to
+        download via the signed URL. The `reportGenerationErrors` array may contain per-flow errors
+        even when the overall status is `completed`.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Event report ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: eventreports
+            examples:
+              - 682278b3e4b0a10012abcdef
+      responses:
+        '200':
+          description: The event report record.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventReport'
+              examples:
+                completed:
+                  summary: A completed event report
+                  value:
+                    _id: 682278b3e4b0a10012abcdef
+                    type: flow_events
+                    _flowIds:
+                      - 63a1b2c3d4e5f60011223344
+                    startTime: '2026-04-27T00:00:00.000Z'
+                    endTime: '2026-04-29T00:00:00.000Z'
+                    status: completed
+                    reportGenerationErrors: []
+                    createdAt: '2026-04-28T14:30:00.000Z'
+                    startedAt: '2026-04-28T14:30:05.000Z'
+                    endedAt: '2026-04-28T14:32:00.000Z'
+                    requestedByUser:
+                      name: Jane Doe
+                      email: jane.doe@example.com
+                running:
+                  summary: A report still in progress
+                  value:
+                    _id: 682278b3e4b0a10012aaaaaa
+                    type: flow_events
+                    _flowIds:
+                      - 63a1b2c3d4e5f60011223355
+                    startTime: '2026-04-28T00:00:00.000Z'
+                    endTime: '2026-04-29T12:00:00.000Z'
+                    status: running
+                    reportGenerationErrors: []
+                    createdAt: '2026-04-29T15:00:00.000Z'
+                    startedAt: '2026-04-29T15:00:02.000Z'
+                    requestedByUser:
+                      name: Jane Doe
+                      email: jane.doe@example.com
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/eventreports/{_id}/signedURL:
+    get:
+      x-internal: false
+      operationId: getEventReportSignedUrl
+      tags:
+        - Event Reports
+      summary: Get signed URL for an event report
+      description: |-
+        Returns a pre-signed S3 URL for downloading the completed event report as a CSV file.
+        The URL is valid for approximately 15 minutes. Only works when the report `status` is
+        `completed` -- requesting it in any other status returns 400. If the URL has expired,
+        call this endpoint again to get a fresh one.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Event report ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: eventreports
+            examples:
+              - 682278b3e4b0a10012abcdef
+      responses:
+        '200':
+          description: Signed URL for CSV download.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EventReportSignedUrlResponse'
+              examples:
+                signed_url:
+                  summary: Signed URL response
+                  value:
+                    signedURL: https://integrator-event-reports.s3.us-east-1.amazonaws.com/_682278b3e4b0a10012abcdef.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123
+        '400':
+          description: The report is not in `completed` status.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_status:
+                  summary: Report not completed
+                  value:
+                    errors:
+                      - code: invalid_status
+                        message: Event report can be downloaded only if it's in completed status.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/eventreports/{_id}/cancel:
+    put:
+      x-internal: false
+      operationId: cancelEventReport
+      tags:
+        - Event Reports
+      summary: Cancel an event report
+      description: |-
+        Cancels a queued or running event report. The report's `status` transitions to `canceled`.
+        No request body is needed. Idempotent for reports already in `canceled` status. A `completed`
+        report cannot be canceled, and canceled reports cannot be resumed -- create a new one instead.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Event report ID to cancel.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: eventreports
+            examples:
+              - 682278b3e4b0a10012abcdef
+      responses:
+        '204':
+          description: Event report canceled successfully.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '422':
+          description: The report is in `completed` status and cannot be canceled.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                invalid_status:
+                  summary: Cannot cancel a completed report
+                  value:
+                    errors:
+                      - field: status
+                        code: invalid_status
+                        message: An event report status cannot be modified once its in completed status.
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    ResourceResponse:
+      type: object
+      description: Response
+      x-celigo-ai-guidance:
+        - Core response fields shared by all Celigo resources
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          description: Unique identifier for the resource. Format is a 24-character hexadecimal string.
+          x-celigo-ai-guidance:
+            - |-
+              The _id is used in:
+              - API endpoints that operate on a specific resource (e.g., GET, PUT, DELETE)
+              - References from other resources (e.g., flows that use this resource)
+              - Job history and error tracking
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was created. Set automatically and cannot be modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix).
+          examples:
+            - '2023-04-01T09:15:32Z'
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was last updated. Changes whenever any property is modified.
+          x-celigo-ai-guidance:
+            - Recorded in ISO 8601 with a UTC timezone (Z suffix); always equal to or later than `createdAt`.
+          examples:
+            - '2023-04-15T14:30:15Z'
+        deletedAt:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          description: Timestamp when the resource was soft-deleted. When null or absent, the resource is active.
+          x-celigo-ai-guidance:
+            - Non-null means the resource is soft-deleted (in the recycle bin) — recoverable within the retention period before permanent removal.
+          examples:
+            - '2023-05-20T11:45:32Z'
+      required:
+        - _id
+    EventReport:
+      type: object
+      required:
+        - _id
+        - type
+        - _flowIds
+        - startTime
+        - status
+        - createdAt
+      description: |
+        An event report captures flow execution event data for a set of flows over
+        a specified time window. Once generation completes, the report can be
+        downloaded as a CSV via a time-limited signed URL.
+
+        **Status lifecycle:** `queued` -> `running` -> `completed` | `canceled`
+
+        The `reportGenerationErrors` array may contain per-flow errors even when the overall status
+        is `completed`. The `_requestedByUserId` field only appears on the POST create response;
+        GET endpoints return `requestedByUser` (with `name` and `email`) instead.
+      allOf:
+        - $ref: '#/components/schemas/ResourceResponse'
+        - type: object
+          properties:
+            _requestedByUserId:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              readOnly: true
+              description: The user ID of the person who requested the report.
+              examples:
+                - 60f1a2b3c4d5e6f7a8b9c0d1
+            type:
+              type: string
+              description: |
+                The type of event report. Currently only `flow_events` is supported.
+              enum:
+                - flow_events
+              x-enumDescriptions:
+                flow_events: Report capturing flow execution event data.
+              examples:
+                - flow_events
+            _flowIds:
+              type: array
+              description: |
+                Array of flow IDs whose events are included in the report. At least
+                one flow ID is required.
+              minItems: 1
+              items:
+                type: string
+                format: objectId
+                x-celigo-refModel: flows
+              examples:
+                - - 63a1b2c3d4e5f60011223344
+                  - 63a1b2c3d4e5f60011223355
+            startTime:
+              type: string
+              format: date-time
+              description: |
+                Start of the time window for the report. Must be within the last
+                30 days. ISO 8601 format.
+              examples:
+                - '2026-04-01T00:00:00.000Z'
+            endTime:
+              type: string
+              format: date-time
+              description: |
+                End of the time window for the report. Defaults to the current time
+                if omitted. The span between `startTime` and `endTime` must not
+                exceed 3 days.
+              examples:
+                - '2026-04-03T00:00:00.000Z'
+            status:
+              type: string
+              readOnly: true
+              description: Current status of the report generation.
+              enum:
+                - queued
+                - running
+                - completed
+                - canceled
+              x-enumDescriptions:
+                queued: Report request accepted and waiting to be processed.
+                running: Report generation is in progress.
+                completed: Report CSV is ready for download.
+                canceled: Report was canceled before completion.
+              examples:
+                - queued
+            reportGenerationErrors:
+              type: array
+              readOnly: true
+              description: |
+                Errors encountered during report generation. May contain entries even
+                when the overall status is `completed` (e.g. a single flow failed
+                while others succeeded).
+              items:
+                type: object
+                properties:
+                  code:
+                    type: string
+                    description: Machine-readable error code.
+                    examples:
+                      - flow_not_found
+                  message:
+                    type: string
+                    description: Human-readable error description.
+                    examples:
+                      - Flow 63a1b2c3d4e5f60011223344 could not be found.
+              examples:
+                - []
+            startedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When report generation began. Present once the report enters `running` status.
+              examples:
+                - '2026-04-28T14:30:05.000Z'
+            endedAt:
+              type: string
+              format: date-time
+              readOnly: true
+              description: When report generation finished. Only present on `completed` reports.
+              examples:
+                - '2026-04-28T14:32:00.000Z'
+            requestedByUser:
+              type: object
+              readOnly: true
+              description: |
+                The user who requested the report. Present on GET responses
+                but not on the POST create response (which returns
+                `_requestedByUserId` instead).
+              properties:
+                name:
+                  type: string
+                  description: Display name of the requesting user.
+                  examples:
+                    - Tyler Lamparter
+                email:
+                  type: string
+                  format: email
+                  description: Email address of the requesting user.
+                  examples:
+                    - tyler.lamparter@celigo.com
+    EventReportCreateRequest:
+      type: object
+      description: |
+        Request body for creating a new event report. `startTime` must be within the last 30 days
+        and the span to `endTime` must not exceed 3 days. If `endTime` is omitted, the server
+        defaults it to the current time.
+      properties:
+        type:
+          type: string
+          description: |
+            The type of event report to generate. Currently only `flow_events`
+            is supported.
+          enum:
+            - flow_events
+          x-enumDescriptions:
+            flow_events: Report capturing flow execution event data.
+          examples:
+            - flow_events
+        _flowIds:
+          type: array
+          description: |
+            Array of flow IDs whose events should be included in the report.
+            At least one flow ID is required.
+          minItems: 1
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: flows
+          examples:
+            - - 63a1b2c3d4e5f60011223344
+        startTime:
+          type: string
+          format: date-time
+          description: |
+            Start of the time window. Must be within the last 30 days.
+            ISO 8601 format.
+          examples:
+            - '2026-04-01T00:00:00.000Z'
+        endTime:
+          type: string
+          format: date-time
+          description: |
+            End of the time window. Defaults to the current time if omitted.
+            The total span (`endTime - startTime`) must not exceed 3 days.
+          examples:
+            - '2026-04-03T00:00:00.000Z'
+      required:
+        - type
+        - startTime
+        - _flowIds
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    EventReportSignedUrlResponse:
+      type: object
+      description: |
+        Response containing a pre-signed S3 URL for downloading the completed
+        event report CSV. The URL is valid for approximately 15 minutes and
+        should be consumed immediately. Only returned when the report `status`
+        is `completed`.
+      properties:
+        signedURL:
+          type: string
+          format: uri
+          description: |
+            Pre-signed S3 URL for downloading the report CSV. Valid for
+            approximately 15 minutes from generation.
+          examples:
+            - https://integrator-event-reports.s3.us-east-1.amazonaws.com/_682278b3e4b0a10012abcdef.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&...
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    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.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false