@celigo/api-specs 0.2.1

package/dist/profile.yml

@@ -0,0 +1,455 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Profile
+  description: Read and update the currently-authenticated user's profile, including display name, email, timezone, and notification preferences.
+  x-celigo-ai-guidance:
+    - API for reading and updating the currently-authenticated user's profile (`/api/profile`).
+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: Profile
+    description: |-
+      Read and update the currently-authenticated user's profile, including
+      display name, email, timezone, and notification preferences.
+
+      ## Preferences schema
+
+      {% openapi-schemas spec="profile" schemas="Preferences" grouped="true" %}
+paths:
+  /v1/preferences:
+    get:
+      x-internal: false
+      summary: Get current user preferences
+      operationId: getPreferences
+      tags:
+        - Profile
+      description: |-
+        Returns UI and account/environment preferences for the currently-authenticated user.
+
+        Examples include:
+        - date/time display formatting (`dateFormat`, `timeFormat`)
+        - current environment selection (`environment`)
+        - UI layout preferences (dashboard/pagination/drawer settings)
+      responses:
+        '200':
+          description: Preferences object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Preferences'
+              examples:
+                default:
+                  value:
+                    environment: production
+                    defaultAShareId: own
+                    defaultEnvId: 60a2c4e6f321d800129a1a3c
+                    dateFormat: MM/DD/YYYY
+                    timeFormat: h:mm:ss A
+                    colorTheme: system
+                    showRelativeDateTime: false
+                    drawerOpened: true
+                    enableAIChatbot: true
+                    sampleIntegrationRequired: false
+                    scheduleShiftForFlowsCreatedAfter: '2024-06-13T11:39:15.778Z'
+                    lastLoginAt: '2026-05-14T18:22:10.000Z'
+                    featureFlags:
+                      enableLookupCache: true
+                      enableSizeBasedAggregation: false
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+    put:
+      x-internal: false
+      summary: Update current user preferences
+      operationId: updatePreferences
+      tags:
+        - Profile
+      description: |-
+        Updates user preferences for the currently-authenticated user.
+        Only include fields you intend to change.
+      x-celigo-ai-guidance:
+        - |-
+          AI guidance:
+          - Only include fields you intend to change.
+          - Prefer updating `dateFormat` / `timeFormat` here (not in `/api/profile`).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/Request'
+            examples:
+              change-theme:
+                summary: Switch to dark mode
+                value:
+                  colorTheme: dark
+              change-date-format:
+                summary: Change date and time display
+                value:
+                  dateFormat: YYYY-MM-DD
+                  timeFormat: HH:mm:ss
+                  showRelativeDateTime: false
+      responses:
+        '200':
+          description: Updated preferences object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Preferences'
+              examples:
+                updated:
+                  summary: Preferences after switching to dark mode
+                  value:
+                    environment: production
+                    defaultAShareId: own
+                    defaultEnvId: 60a2c4e6f321d800129a1a3c
+                    dateFormat: MM/DD/YYYY
+                    timeFormat: h:mm:ss A
+                    colorTheme: dark
+                    showRelativeDateTime: false
+                    drawerOpened: true
+                    enableAIChatbot: true
+                    sampleIntegrationRequired: false
+                    scheduleShiftForFlowsCreatedAfter: '2024-06-13T11:39:15.778Z'
+                    lastLoginAt: '2026-05-14T18:22:10.000Z'
+                    featureFlags:
+                      enableLookupCache: true
+                      enableSizeBasedAggregation: false
+        '204':
+          description: Preferences updated (no body returned).
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    PreferencesBase:
+      type: object
+      description: Writable preference fields shared by the request and response schemas.
+      properties:
+        environment:
+          type: string
+          enum:
+            - production
+            - sandbox
+          x-enumDescriptions:
+            production: The production environment context.
+            sandbox: The sandbox (non-production) environment context.
+          description: The selected environment context for the user.
+        defaultAShareId:
+          type: string
+          examples:
+            - own
+          description: The selected account context for the user.
+          x-celigo-ai-guidance:
+            - |-
+              Common values:
+              - `own` for the user's own account
+              - an AShare/account-share id when working in a shared account
+        defaultEnvId:
+          type: string
+          format: objectId
+          examples:
+            - 60a2c4e6f321d800129a1a3c
+          description: Default environment id to use when applicable.
+        dateFormat:
+          type: string
+          description: |-
+            The user's preferred date display format used across the UI.
+
+            Choose one of the supported formats.
+          enum:
+            - MM/DD/YYYY
+            - DD/MM/YYYY
+            - DD-MMM-YYYY
+            - DD.MM.YYYY
+            - DD-MMMM-YYYY
+            - DD MMMM, YYYY
+            - YYYY/MM/DD
+            - YYYY-MM-DD
+          x-enumDescriptions:
+            MM/DD/YYYY: US format with slashes (e.g. 01/31/2026).
+            DD/MM/YYYY: European format with slashes (e.g. 31/01/2026).
+            DD-MMM-YYYY: Day with abbreviated month name (e.g. 31-Jan-2026).
+            DD.MM.YYYY: European format with dots (e.g. 31.01.2026).
+            DD-MMMM-YYYY: Day with full month name and dashes (e.g. 31-January-2026).
+            DD MMMM, YYYY: Day with full month name and comma (e.g. 31 January, 2026).
+            YYYY/MM/DD: ISO-style format with slashes (e.g. 2026/01/31).
+            YYYY-MM-DD: ISO 8601 format with dashes (e.g. 2026-01-31).
+        timeFormat:
+          type: string
+          description: The user's preferred time display format used across the UI.
+          enum:
+            - h:mm:ss A
+            - HH:mm:ss
+          x-enumDescriptions:
+            h:mm:ss A: 12-hour time with AM/PM suffix (e.g. 2:30:00 PM).
+            HH:mm:ss: 24-hour time (e.g. 14:30:00).
+        showRelativeDateTime:
+          type: boolean
+          description: Whether timestamps should be displayed as relative time (e.g., "5 minutes ago") instead of absolute date/time.
+        colorTheme:
+          type: string
+          description: UI theme preference.
+          enum:
+            - system
+            - light
+            - dark
+          x-enumDescriptions:
+            system: Follow the operating system's theme preference.
+            light: Force the light UI theme.
+            dark: Force the dark UI theme.
+        scheduleShiftForFlowsCreatedAfter:
+          type: string
+          format: date-time
+          examples:
+            - '2024-06-13T11:39:15.778Z'
+          description: Threshold timestamp used by scheduling logic for certain flows (UI/system preference).
+        recentActivity:
+          type: object
+          description: Recently accessed resources, typically keyed by environment.
+        dashboard:
+          type: object
+          description: Dashboard UI preferences (filters, tile order, view mode).
+          properties:
+            view:
+              type: string
+              description: Dashboard view mode.
+              enum:
+                - tile
+                - list
+              x-enumDescriptions:
+                tile: Display dashboard integrations as visual tiles.
+                list: Display dashboard integrations as a compact list.
+            filters:
+              type: object
+              description: Dashboard filter settings.
+            tilesOrder:
+              type: array
+              description: Ordered list of dashboard tile ids.
+              items:
+                type: string
+        pagination:
+          type: object
+          description: Per-resource pagination settings (e.g., pageSize).
+        drawerOpened:
+          type: boolean
+          description: When true, the main UI drawer/left nav is open.
+        expand:
+          type:
+            - string
+            - 'null'
+          examples:
+            - resources
+          description: UI section name last expanded/opened (UI state).
+        fbBottomDrawerHeight:
+          type: integer
+          examples:
+            - 240
+          description: Flow Builder bottom drawer height in pixels (UI state).
+        enableAIChatbot:
+          type: boolean
+          description: When true, AI chat features are enabled in the UI for this user.
+        enableBeginnerGuide:
+          type: boolean
+          description: When true, the beginner guide UI is enabled for this user.
+        showIconView:
+          type: boolean
+          description: When true, Flow Builder icon view is enabled for this user.
+        allowPostmanCollectionUpload:
+          type: boolean
+          description: When true, Postman collection upload UI is enabled for this user.
+        helpContent:
+          type: object
+          description: UI help content preferences/state.
+        sampleIntegrationRequired:
+          type: boolean
+          description: When true, the sample-integration walkthrough is still required for the user.
+        hideGettingStarted:
+          type: boolean
+          description: When true, the Getting Started banner is hidden.
+        isLeftNavExpanded:
+          type: boolean
+          description: When true, the left navigation sidebar is expanded.
+        isNewGenFlowEnabled:
+          type: boolean
+          description: When true, the next-generation Flow Builder UI is enabled for the user.
+        useClickHouseForJobs:
+          type: boolean
+          description: When true, the account uses ClickHouse-backed job queries.
+        featureFlags:
+          type: object
+          description: UI/feature flag overrides for the user (if present).
+    Preferences:
+      type: object
+      description: Complete preferences object as returned by `GET /v1/preferences`.
+      allOf:
+        - $ref: '#/components/schemas/PreferencesBase'
+        - type: object
+          properties:
+            lastLoginAt:
+              type: string
+              format: date-time
+              readOnly: true
+              examples:
+                - '2026-05-14T18:22:10.000Z'
+              description: Last login timestamp recorded for the user (if present).
+            showReactSneakPeekFromDate:
+              type: string
+              format: date
+              readOnly: true
+              examples:
+                - '2025-09-01'
+              description: Legacy feature-rollout date marker (UI state).
+              x-celigo-ai-guidance:
+                - Feature rollout date marker used by the UI (if present).
+            showReactBetaFromDate:
+              type: string
+              format: date
+              readOnly: true
+              examples:
+                - '2025-11-15'
+              description: Legacy feature-rollout date marker (UI state).
+              x-celigo-ai-guidance:
+                - Feature rollout date marker used by the UI (if present).
+            oldDefaultAShareId:
+              type: string
+              readOnly: true
+              examples:
+                - own
+              description: Previous default account-share ID, retained after switching accounts.
+            resourceDrawerPanelSizes:
+              type: object
+              readOnly: true
+              description: Persisted panel-size state for the resource drawer (UI layout).
+              properties:
+                left:
+                  type: number
+                  examples:
+                    - 320
+                  description: Persisted size of the resource drawer's left panel.
+                right:
+                  type: number
+                  examples:
+                    - 480
+                  description: Persisted size of the resource drawer's right panel.
+            accounts:
+              type: object
+              readOnly: true
+              description: Per-account UI state keyed by account ID.
+    Request:
+      type: object
+      description: |-
+        Fields that can be sent when updating the current user's preferences
+        via `PUT /v1/preferences`. Send a partial object with only the
+        fields you want to change.
+      x-celigo-ai-guidance:
+        - |-
+          AI guidance:
+          - Send a partial object with only the fields you want to change.
+          - Use this endpoint (not `/api/profile`) to change `dateFormat` and `timeFormat`.
+      allOf:
+        - $ref: '#/components/schemas/PreferencesBase'
+    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
+  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.
+x-enable-proxy: true
+x-internal: false