@friggframework/core 2.0.0--canary.522.cbd3d5a.0 → 2.0.0--canary.517.35ee143.0

package/openapi/openapi-v2.yaml

@@ -1,1535 +0,0 @@
-openapi: 3.0.3
-info:
-    title: Frigg Framework API (v2)
-    version: 2.0.0
-    description: |
-        Enterprise-grade serverless integration framework API for managing integrations,
-        entities, credentials, and proxying requests to external systems.
-
-        ## API Version: v2 (Current)
-
-        This is the **v2 API** with clean, well-separated endpoints and response structures.
-        All v2 endpoints are prefixed with `/api/v2/`.
-
-        ### Key v2 Improvements
-
-        - **Clean responses**: Each endpoint returns only the relevant data
-        - **Separation of concerns**: Integrations, entities, and options are separate endpoints
-        - **Consistent structure**: All list endpoints return `{ <resource>: [...] }`
-        - **Better REST semantics**: Resources are properly organized
-
-        ### Migration from v1
-
-        | v1 Endpoint | v2 Equivalent | Change |
-        |-------------|---------------|--------|
-        | `GET /api/integrations` (combined) | `GET /api/v2/integrations` | Returns only `{ integrations }` |
-        | (from v1 combined response) | `GET /api/v2/integrations/options` | Separate endpoint for options |
-        | (from v1 combined response) | `GET /api/v2/entities` | Separate endpoint for entities |
-
-        ## Overview
-        The Frigg Framework enables direct/native integrations between products and external
-        software partners through a standardized API that handles authentication, authorization,
-        and data synchronization.
-
-        ## Key Concepts
-        - **Entities**: Connected accounts representing external integrations (e.g., a HubSpot account)
-        - **Credentials**: Authentication data for external systems (OAuth tokens, API keys)
-        - **Integrations**: Configured bidirectional sync relationships between entities
-        - **Proxy**: Secure API forwarding to external systems using stored credentials
-
-        ## Authentication
-        All API endpoints require Bearer token authentication unless otherwise noted.
-    contact:
-        name: Frigg Framework
-        url: https://friggframework.org
-    license:
-        name: MIT
-
-servers:
-    - url: http://localhost:3000
-      description: Local development server
-    - url: https://api.{stage}.friggframework.org
-      description: Production environments
-      variables:
-          stage:
-              default: prod
-              enum:
-                  - dev
-                  - staging
-                  - prod
-
-security:
-    - bearerAuth: []
-
-tags:
-    - name: Integrations
-      description: Integration configuration and management
-    - name: Authorization
-      description: OAuth and authentication flows for connecting external systems
-    - name: Entities
-      description: Connected accounts and entity management
-    - name: Credentials
-      description: Credential management and reauthorization
-    - name: Health
-      description: Service health and readiness checks
-
-paths:
-    # Integration Endpoints (v2 clean response)
-    /api/v2/integrations:
-        get:
-            tags:
-                - Integrations
-            summary: List user's integrations
-            description: |
-                Retrieve all integrations owned by the authenticated user.
-
-                **v2 Response Format**: Returns only the integrations array.
-                For integration options, use `GET /api/v2/integrations/options`.
-                For authorized entities, use `GET /api/v2/entities`.
-            operationId: listIntegrationsV2
-            responses:
-                '200':
-                    description: List of integrations
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ListIntegrationsResponse'
-                            example:
-                                integrations:
-                                    - id: int-456
-                                      userId: user-789
-                                      config:
-                                          type: hubspot-salesforce
-                                      status: ENABLED
-                                      entities:
-                                          - entity-123
-                                          - entity-456
-                                      dateCreated: '2024-01-15T10:30:00Z'
-                                      dateUpdated: '2024-01-15T10:30:00Z'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-
-        post:
-            tags:
-                - Integrations
-            summary: Create integration
-            description: Create a new integration between two or more entities
-            operationId: createIntegrationV2
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/CreateIntegrationRequest'
-                        example:
-                            entities:
-                                - entity-123
-                                - entity-456
-                            config:
-                                syncDirection: bidirectional
-                                syncInterval: 3600
-            responses:
-                '201':
-                    description: Integration created successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Integration'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-
-    /api/v2/integrations/options:
-        get:
-            tags:
-                - Integrations
-            summary: List available integration types
-            description: |
-                Get available integration types that can be configured.
-                This replaces the `entities.options` field from the v1 combined response.
-            operationId: listIntegrationOptionsV2
-            responses:
-                '200':
-                    description: List of available integration types
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ListIntegrationOptionsResponse'
-                            example:
-                                integrations:
-                                    - type: hubspot
-                                      name: HubSpot
-                                      description: HubSpot CRM integration
-                                      hasAuth: true
-                                      modules:
-                                          - name: hubspot
-                                            authType: oauth2
-                                            stepCount: 1
-                                    - type: salesforce
-                                      name: Salesforce
-                                      description: Salesforce CRM integration
-                                      hasAuth: true
-                                      modules:
-                                          - name: salesforce
-                                            authType: oauth2
-                                            stepCount: 1
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-
-    /api/v2/integrations/{integrationId}:
-        get:
-            tags:
-                - Integrations
-            summary: Get integration
-            description: Retrieve detailed information about a specific integration
-            operationId: getIntegrationV2
-            parameters:
-                - $ref: '#/components/parameters/IntegrationId'
-            responses:
-                '200':
-                    description: Integration retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Integration'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        patch:
-            tags:
-                - Integrations
-            summary: Update integration
-            description: Update integration configuration
-            operationId: updateIntegrationV2
-            parameters:
-                - $ref: '#/components/parameters/IntegrationId'
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/UpdateIntegrationRequest'
-            responses:
-                '200':
-                    description: Integration updated successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Integration'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        delete:
-            tags:
-                - Integrations
-            summary: Delete integration
-            description: Delete an integration (entities and credentials remain)
-            operationId: deleteIntegrationV2
-            parameters:
-                - $ref: '#/components/parameters/IntegrationId'
-            responses:
-                '200':
-                    description: Integration deleted successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/DeleteResponse'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-    # Authorization Endpoints
-    /api/v2/authorize:
-        get:
-            tags:
-                - Authorization
-            summary: Get authorization requirements
-            description: |
-                Retrieve the authentication requirements for a given module type and step.
-                Used to start or continue a multi-step authorization flow.
-            operationId: getAuthorizationRequirementsV2
-            parameters:
-                - name: moduleType
-                  in: query
-                  required: true
-                  schema:
-                      type: string
-                  description: Module type to authorize (e.g., 'hubspot', 'salesforce')
-                - name: step
-                  in: query
-                  schema:
-                      type: integer
-                      minimum: 1
-                      default: 1
-                  description: Current step number (for multi-step flows)
-                - name: sessionId
-                  in: query
-                  schema:
-                      type: string
-                  description: Session ID from previous step (required for step > 1)
-            responses:
-                '200':
-                    description: Authorization requirements retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/AuthorizationRequirements'
-                            example:
-                                type: oauth2
-                                step: 1
-                                totalSteps: 1
-                                isMultiStep: false
-                                data:
-                                    url: https://app.hubspot.com/oauth/authorize?client_id=xxx&redirect_uri=xxx&scope=contacts
-                                    scopes:
-                                        - contacts
-                                        - crm.objects.contacts.read
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        post:
-            tags:
-                - Authorization
-            summary: Submit authorization data
-            description: |
-                Submit authentication data to authorize an entity. This may complete the
-                authorization or return next step requirements for multi-step flows.
-            operationId: submitAuthorizationV2
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/AuthorizationRequest'
-                        example:
-                            moduleType: hubspot
-                            data:
-                                code: oauth_authorization_code_here
-                                redirect_uri: https://app.example.com/oauth/callback
-            responses:
-                '200':
-                    description: Authorization completed or next step returned
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/AuthorizationResponse'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '422':
-                    $ref: '#/components/responses/ValidationError'
-
-    # Entity Endpoints
-    /api/v2/entities:
-        get:
-            tags:
-                - Entities
-            summary: List user's entities
-            description: |
-                Retrieve all entities owned by the authenticated user.
-                This replaces the `entities.authorized` field from the v1 combined response.
-            operationId: listEntitiesV2
-            responses:
-                '200':
-                    description: List of entities retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ListEntitiesResponse'
-                            example:
-                                entities:
-                                    - id: entity-123
-                                      type: hubspot
-                                      name: My HubSpot Account
-                                      externalId: hub-12345
-                                      credentialId: cred-abc
-                                      userId: user-789
-                                      dateCreated: '2024-01-15T10:30:00Z'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-
-        post:
-            tags:
-                - Entities
-            summary: Create entity from credential
-            description: Create a new entity linked to an existing credential
-            operationId: createEntityV2
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/CreateEntityRequest'
-            responses:
-                '201':
-                    description: Entity created successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/CreateEntityResponse'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '422':
-                    $ref: '#/components/responses/ValidationError'
-
-    /api/v2/entities/types:
-        get:
-            tags:
-                - Entities
-            summary: List available entity types
-            description: Get a list of all available entity types (API modules) that can be integrated
-            operationId: listEntityTypesV2
-            responses:
-                '200':
-                    description: List of available entity types
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ListEntityTypesResponse'
-                            example:
-                                types:
-                                    - type: hubspot
-                                      name: HubSpot
-                                      description: HubSpot CRM and Marketing
-                                      authType: oauth2
-                                      isMultiStep: false
-                                      stepCount: 1
-                                      capabilities:
-                                          - contacts
-                                          - companies
-                                          - deals
-                                    - type: salesforce
-                                      name: Salesforce
-                                      description: Salesforce CRM
-                                      authType: oauth2
-                                      isMultiStep: false
-                                      stepCount: 1
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-
-    /api/v2/entities/types/{typeName}:
-        get:
-            tags:
-                - Entities
-            summary: Get entity type metadata
-            description: Retrieve detailed information about a specific entity type
-            operationId: getEntityTypeV2
-            parameters:
-                - $ref: '#/components/parameters/TypeName'
-            responses:
-                '200':
-                    description: Entity type metadata retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/EntityType'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-    /api/v2/entities/types/{typeName}/requirements:
-        get:
-            tags:
-                - Entities
-            summary: Get authentication requirements for entity type
-            description: |
-                Get the authentication requirements (OAuth URLs, form schemas, etc.)
-                needed to authorize this entity type
-            operationId: getEntityTypeRequirementsV2
-            parameters:
-                - $ref: '#/components/parameters/TypeName'
-                - name: step
-                  in: query
-                  schema:
-                      type: integer
-                      minimum: 1
-                      default: 1
-                  description: Step number for multi-step auth flows
-            responses:
-                '200':
-                    description: Authentication requirements retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/AuthorizationRequirements'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-    /api/v2/entities/{entityId}:
-        get:
-            tags:
-                - Entities
-            summary: Get specific entity
-            description: Retrieve detailed information about a specific entity
-            operationId: getEntityV2
-            parameters:
-                - $ref: '#/components/parameters/EntityId'
-            responses:
-                '200':
-                    description: Entity retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Entity'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        delete:
-            tags:
-                - Entities
-            summary: Delete entity
-            description: Delete an entity (credential remains unless orphaned)
-            operationId: deleteEntityV2
-            parameters:
-                - $ref: '#/components/parameters/EntityId'
-            responses:
-                '200':
-                    description: Entity deleted successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/DeleteResponse'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-    /api/v2/entities/{entityId}/test-auth:
-        get:
-            tags:
-                - Entities
-            summary: Test entity authentication
-            description: Verify that the entity's credentials are valid and working
-            operationId: testEntityAuthV2
-            parameters:
-                - $ref: '#/components/parameters/EntityId'
-            responses:
-                '200':
-                    description: Authentication test result
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/TestAuthResponse'
-                            example:
-                                valid: true
-                                message: Authentication successful
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-    /api/v2/entities/{entityId}/reauthorize:
-        get:
-            tags:
-                - Entities
-            summary: Get entity reauthorization requirements
-            description: Get authentication requirements to reauthorize an existing entity
-            operationId: getEntityReauthorizationRequirementsV2
-            parameters:
-                - $ref: '#/components/parameters/EntityId'
-                - name: step
-                  in: query
-                  schema:
-                      type: integer
-                      minimum: 1
-                      default: 1
-            responses:
-                '200':
-                    description: Reauthorization requirements retrieved
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/AuthorizationRequirements'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        post:
-            tags:
-                - Entities
-            summary: Submit entity reauthorization
-            description: Reauthorize an existing entity with new credentials
-            operationId: reauthorizeEntityV2
-            parameters:
-                - $ref: '#/components/parameters/EntityId'
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/ReauthorizeRequest'
-            responses:
-                '200':
-                    description: Reauthorization completed or next step returned
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ReauthorizeResponse'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-                '422':
-                    $ref: '#/components/responses/ValidationError'
-
-    /api/v2/entities/{entityId}/proxy:
-        post:
-            tags:
-                - Entities
-            summary: Proxy API request through entity
-            description: |
-                Forward an API request to the external system using the entity's credentials.
-                Automatically handles authentication headers and token refresh.
-
-                **Example**: To call HubSpot's contacts API:
-                ```json
-                {
-                  "method": "GET",
-                  "path": "/crm/v3/objects/contacts",
-                  "query": { "limit": 10 }
-                }
-                ```
-            operationId: proxyEntityRequestV2
-            parameters:
-                - $ref: '#/components/parameters/EntityId'
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/ProxyRequest'
-                        example:
-                            method: GET
-                            path: /crm/v3/objects/contacts
-                            query:
-                                limit: 10
-                                properties: firstname,lastname,email
-            responses:
-                '200':
-                    description: Request proxied successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ProxyResponse'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-                '502':
-                    description: Upstream API error
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ProxyErrorResponse'
-
-    # Credential Endpoints
-    /api/v2/credentials:
-        get:
-            tags:
-                - Credentials
-            summary: List user's credentials
-            description: Retrieve all credentials owned by the authenticated user (tokens masked)
-            operationId: listCredentialsV2
-            responses:
-                '200':
-                    description: List of credentials retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ListCredentialsResponse'
-                            example:
-                                credentials:
-                                    - id: cred-abc
-                                      type: hubspot
-                                      externalId: hub-12345
-                                      userId: user-789
-                                      entityCount: 1
-                                      dateCreated: '2024-01-15T10:30:00Z'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-
-    /api/v2/credentials/{credentialId}:
-        get:
-            tags:
-                - Credentials
-            summary: Get specific credential
-            description: Retrieve detailed information about a specific credential (tokens masked)
-            operationId: getCredentialV2
-            parameters:
-                - $ref: '#/components/parameters/CredentialId'
-            responses:
-                '200':
-                    description: Credential retrieved successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/Credential'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        delete:
-            tags:
-                - Credentials
-            summary: Delete credential
-            description: Delete a credential and all associated entities
-            operationId: deleteCredentialV2
-            parameters:
-                - $ref: '#/components/parameters/CredentialId'
-            responses:
-                '200':
-                    description: Credential deleted successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/DeleteResponse'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-    /api/v2/credentials/{credentialId}/reauthorize:
-        get:
-            tags:
-                - Credentials
-            summary: Get credential reauthorization requirements
-            description: Get authentication requirements to reauthorize an existing credential
-            operationId: getCredentialReauthorizationRequirementsV2
-            parameters:
-                - $ref: '#/components/parameters/CredentialId'
-                - name: step
-                  in: query
-                  schema:
-                      type: integer
-                      minimum: 1
-                      default: 1
-            responses:
-                '200':
-                    description: Reauthorization requirements retrieved
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/AuthorizationRequirements'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-
-        post:
-            tags:
-                - Credentials
-            summary: Submit credential reauthorization
-            description: Reauthorize an existing credential with new authentication data
-            operationId: reauthorizeCredentialV2
-            parameters:
-                - $ref: '#/components/parameters/CredentialId'
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/ReauthorizeRequest'
-            responses:
-                '200':
-                    description: Reauthorization completed or next step returned
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ReauthorizeResponse'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-                '422':
-                    $ref: '#/components/responses/ValidationError'
-
-    /api/v2/credentials/{credentialId}/proxy:
-        post:
-            tags:
-                - Credentials
-            summary: Proxy API request through credential
-            description: |
-                Forward an API request to the external system using this credential.
-                Similar to entity proxy but doesn't require an entity to be created.
-            operationId: proxyCredentialRequestV2
-            parameters:
-                - $ref: '#/components/parameters/CredentialId'
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            $ref: '#/components/schemas/ProxyRequest'
-            responses:
-                '200':
-                    description: Request proxied successfully
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ProxyResponse'
-                '400':
-                    $ref: '#/components/responses/BadRequest'
-                '401':
-                    $ref: '#/components/responses/Unauthorized'
-                '404':
-                    $ref: '#/components/responses/NotFound'
-                '502':
-                    description: Upstream API error
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ProxyErrorResponse'
-
-    # Health Endpoints (same as v1 - not versioned)
-    /health:
-        get:
-            tags:
-                - Health
-            summary: Basic health check
-            description: Simple health check endpoint that returns service status
-            operationId: healthCheck
-            security: []
-            responses:
-                '200':
-                    description: Service is healthy
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/HealthResponse'
-
-    /health/ready:
-        get:
-            tags:
-                - Health
-            summary: Readiness check
-            description: |
-                Detailed readiness check that validates database connectivity,
-                module loading, and encryption system status
-            operationId: readinessCheck
-            security: []
-            responses:
-                '200':
-                    description: Service is ready
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ReadinessResponse'
-                '503':
-                    description: Service not ready
-                    content:
-                        application/json:
-                            schema:
-                                $ref: '#/components/schemas/ReadinessResponse'
-
-components:
-    securitySchemes:
-        bearerAuth:
-            type: http
-            scheme: bearer
-            bearerFormat: JWT
-            description: JWT token obtained from authentication
-
-    parameters:
-        EntityId:
-            name: entityId
-            in: path
-            required: true
-            schema:
-                type: string
-            description: Unique entity identifier
-
-        CredentialId:
-            name: credentialId
-            in: path
-            required: true
-            schema:
-                type: string
-            description: Unique credential identifier
-
-        IntegrationId:
-            name: integrationId
-            in: path
-            required: true
-            schema:
-                type: string
-            description: Unique integration identifier
-
-        TypeName:
-            name: typeName
-            in: path
-            required: true
-            schema:
-                type: string
-            description: Entity type name (e.g., 'hubspot', 'salesforce')
-
-    schemas:
-        # v2 clean responses
-        ListIntegrationsResponse:
-            type: object
-            description: |
-                **v2 Clean Response Format**
-
-                Returns only the integrations array. For integration options and entities,
-                use the dedicated endpoints.
-            required:
-                - integrations
-            properties:
-                integrations:
-                    type: array
-                    description: User's active integrations
-                    items:
-                        $ref: '#/components/schemas/Integration'
-
-        ListIntegrationOptionsResponse:
-            type: object
-            required:
-                - integrations
-            properties:
-                integrations:
-                    type: array
-                    items:
-                        $ref: '#/components/schemas/IntegrationOption'
-
-        IntegrationOption:
-            type: object
-            description: An available integration type
-            required:
-                - type
-                - name
-            properties:
-                type:
-                    type: string
-                    description: Integration type identifier
-                name:
-                    type: string
-                    description: Display name
-                description:
-                    type: string
-                    description: Integration description
-                hasAuth:
-                    type: boolean
-                    description: Whether this integration requires authentication
-                modules:
-                    type: array
-                    description: List of modules included in this integration
-                    items:
-                        type: object
-                        properties:
-                            name:
-                                type: string
-                            authType:
-                                type: string
-                                enum: [oauth2, form, api-key, basic]
-                            stepCount:
-                                type: integer
-
-        Integration:
-            type: object
-            required:
-                - id
-                - userId
-            properties:
-                id:
-                    type: string
-                userId:
-                    type: string
-                config:
-                    type: object
-                    description: Integration configuration
-                status:
-                    type: string
-                    enum: [ENABLED, DISABLED, PAUSED, ERROR]
-                entities:
-                    type: array
-                    items:
-                        type: string
-                    description: Array of entity IDs
-                dateCreated:
-                    type: string
-                    format: date-time
-                dateUpdated:
-                    type: string
-                    format: date-time
-
-        CreateIntegrationRequest:
-            type: object
-            required:
-                - entities
-            properties:
-                entities:
-                    type: array
-                    items:
-                        type: string
-                    description: Array of entity IDs to integrate
-                    minItems: 1
-                config:
-                    type: object
-                    description: Integration configuration
-
-        UpdateIntegrationRequest:
-            type: object
-            properties:
-                config:
-                    type: object
-                enabled:
-                    type: boolean
-                status:
-                    type: string
-                    enum: [ENABLED, DISABLED, PAUSED]
-
-        Entity:
-            type: object
-            description: A connected account/entity representing an external integration
-            required:
-                - id
-                - type
-            properties:
-                id:
-                    type: string
-                    description: Unique entity identifier
-                type:
-                    type: string
-                    description: Module/entity type name (e.g., 'hubspot', 'salesforce')
-                name:
-                    type: string
-                    description: Display name for the entity
-                externalId:
-                    type: string
-                    description: ID from the external system (e.g., HubSpot portal ID)
-                credentialId:
-                    type: string
-                    description: ID of the linked credential
-                userId:
-                    type: string
-                    description: ID of the user who owns this entity
-                dateCreated:
-                    type: string
-                    format: date-time
-                dateUpdated:
-                    type: string
-                    format: date-time
-
-        ListEntitiesResponse:
-            type: object
-            required:
-                - entities
-            properties:
-                entities:
-                    type: array
-                    items:
-                        $ref: '#/components/schemas/Entity'
-
-        CreateEntityRequest:
-            type: object
-            required:
-                - moduleType
-                - credentialId
-            properties:
-                moduleType:
-                    type: string
-                    description: Type of entity to create (module name)
-                credentialId:
-                    type: string
-                    description: ID of the credential to link to this entity
-                options:
-                    type: object
-                    description: Additional entity options
-                    additionalProperties: true
-
-        CreateEntityResponse:
-            type: object
-            required:
-                - entityId
-                - credentialId
-                - type
-            properties:
-                entityId:
-                    type: string
-                credentialId:
-                    type: string
-                type:
-                    type: string
-
-        EntityType:
-            type: object
-            required:
-                - type
-                - name
-            properties:
-                type:
-                    type: string
-                    description: Module name (e.g., 'hubspot', 'salesforce')
-                name:
-                    type: string
-                    description: Display name
-                description:
-                    type: string
-                authType:
-                    type: string
-                    enum: [oauth2, form, api-key, basic]
-                isMultiStep:
-                    type: boolean
-                stepCount:
-                    type: integer
-                    minimum: 1
-                capabilities:
-                    type: array
-                    items:
-                        type: string
-
-        ListEntityTypesResponse:
-            type: object
-            required:
-                - types
-            properties:
-                types:
-                    type: array
-                    items:
-                        $ref: '#/components/schemas/EntityType'
-
-        TestAuthResponse:
-            type: object
-            properties:
-                valid:
-                    type: boolean
-                message:
-                    type: string
-
-        Credential:
-            type: object
-            description: A credential object (tokens are masked in responses)
-            required:
-                - id
-                - type
-            properties:
-                id:
-                    type: string
-                type:
-                    type: string
-                    description: Module type (e.g., 'hubspot', 'salesforce')
-                externalId:
-                    type: string
-                userId:
-                    type: string
-                entityCount:
-                    type: integer
-                    description: Number of entities using this credential
-                dateCreated:
-                    type: string
-                    format: date-time
-                dateUpdated:
-                    type: string
-                    format: date-time
-
-        ListCredentialsResponse:
-            type: object
-            required:
-                - credentials
-            properties:
-                credentials:
-                    type: array
-                    items:
-                        $ref: '#/components/schemas/Credential'
-
-        AuthorizationRequirements:
-            type: object
-            required:
-                - type
-                - step
-                - totalSteps
-            properties:
-                type:
-                    type: string
-                    enum: [oauth2, form, api-key, basic]
-                step:
-                    type: integer
-                    minimum: 1
-                totalSteps:
-                    type: integer
-                    minimum: 1
-                isMultiStep:
-                    type: boolean
-                sessionId:
-                    type: string
-                data:
-                    oneOf:
-                        - $ref: '#/components/schemas/OAuth2Requirements'
-                        - $ref: '#/components/schemas/FormRequirements'
-                        - $ref: '#/components/schemas/ApiKeyRequirements'
-
-        OAuth2Requirements:
-            type: object
-            required:
-                - url
-            properties:
-                url:
-                    type: string
-                    format: uri
-                    description: OAuth2 authorization URL
-                scopes:
-                    type: array
-                    items:
-                        type: string
-
-        FormRequirements:
-            type: object
-            required:
-                - jsonSchema
-            properties:
-                jsonSchema:
-                    type: object
-                    description: JSON Schema for form fields
-                uiSchema:
-                    type: object
-                    description: UI hints for form rendering
-
-        ApiKeyRequirements:
-            type: object
-            required:
-                - fields
-            properties:
-                fields:
-                    type: array
-                    items:
-                        type: object
-                        properties:
-                            name:
-                                type: string
-                            type:
-                                type: string
-                                enum: [api_key, secret, token]
-                            label:
-                                type: string
-                            required:
-                                type: boolean
-
-        AuthorizationRequest:
-            type: object
-            required:
-                - moduleType
-            properties:
-                moduleType:
-                    type: string
-                    description: Module type to authorize
-                data:
-                    type: object
-                    description: Authentication data (OAuth code, form fields, API keys)
-                    additionalProperties: true
-                step:
-                    type: integer
-                    minimum: 1
-                    default: 1
-                sessionId:
-                    type: string
-
-        AuthorizationResponse:
-            oneOf:
-                - $ref: '#/components/schemas/AuthorizationSuccess'
-                - $ref: '#/components/schemas/AuthorizationNextStep'
-
-        AuthorizationSuccess:
-            type: object
-            required:
-                - entityId
-                - credentialId
-                - type
-            properties:
-                entityId:
-                    type: string
-                credentialId:
-                    type: string
-                type:
-                    type: string
-                name:
-                    type: string
-                    description: Display name of the connected account
-
-        AuthorizationNextStep:
-            type: object
-            required:
-                - nextStep
-                - sessionId
-                - requirements
-            properties:
-                nextStep:
-                    type: integer
-                    minimum: 2
-                sessionId:
-                    type: string
-                requirements:
-                    $ref: '#/components/schemas/AuthorizationRequirements'
-                message:
-                    type: string
-
-        ReauthorizeRequest:
-            type: object
-            required:
-                - data
-            properties:
-                data:
-                    type: object
-                    additionalProperties: true
-                step:
-                    type: integer
-                    minimum: 1
-                    default: 1
-                sessionId:
-                    type: string
-
-        ReauthorizeResponse:
-            oneOf:
-                - $ref: '#/components/schemas/ReauthorizeSuccess'
-                - $ref: '#/components/schemas/ReauthorizeNextStep'
-
-        ReauthorizeSuccess:
-            type: object
-            required:
-                - success
-                - credentialId
-            properties:
-                success:
-                    type: boolean
-                credentialId:
-                    type: string
-                entityId:
-                    type: string
-                message:
-                    type: string
-
-        ReauthorizeNextStep:
-            type: object
-            required:
-                - step
-                - totalSteps
-                - sessionId
-                - requirements
-            properties:
-                step:
-                    type: integer
-                totalSteps:
-                    type: integer
-                sessionId:
-                    type: string
-                requirements:
-                    type: object
-
-        ProxyRequest:
-            type: object
-            required:
-                - method
-                - path
-            properties:
-                method:
-                    type: string
-                    enum: [GET, POST, PUT, PATCH, DELETE]
-                    description: HTTP method for the upstream request
-                path:
-                    type: string
-                    pattern: ^/
-                    description: API path on the upstream service
-                query:
-                    type: object
-                    description: Query parameters
-                    additionalProperties: true
-                headers:
-                    type: object
-                    description: Additional headers (auth added automatically)
-                    additionalProperties:
-                        type: string
-                body:
-                    description: Request body for POST/PUT/PATCH
-                    oneOf:
-                        - type: object
-                        - type: array
-                        - type: string
-                        - type: 'null'
-
-        ProxyResponse:
-            type: object
-            required:
-                - success
-                - status
-                - data
-            properties:
-                success:
-                    type: boolean
-                status:
-                    type: integer
-                    description: HTTP status from upstream
-                headers:
-                    type: object
-                    additionalProperties:
-                        type: string
-                data:
-                    description: Response body from upstream API
-
-        ProxyErrorResponse:
-            type: object
-            required:
-                - success
-                - status
-                - error
-            properties:
-                success:
-                    type: boolean
-                    enum: [false]
-                status:
-                    type: integer
-                error:
-                    type: object
-                    required:
-                        - code
-                        - message
-                    properties:
-                        code:
-                            type: string
-                            enum:
-                                - INVALID_AUTH
-                                - EXPIRED_TOKEN
-                                - UPSTREAM_ERROR
-                                - TIMEOUT
-                                - NETWORK_ERROR
-                                - RATE_LIMITED
-                                - INVALID_REQUEST
-                                - NOT_FOUND
-                                - PERMISSION_DENIED
-                        message:
-                            type: string
-                        details:
-                            type: object
-                        upstreamStatus:
-                            type: integer
-
-        DeleteResponse:
-            type: object
-            required:
-                - success
-            properties:
-                success:
-                    type: boolean
-                message:
-                    type: string
-
-        HealthResponse:
-            type: object
-            properties:
-                status:
-                    type: string
-                    example: ok
-                timestamp:
-                    type: string
-                    format: date-time
-
-        ReadinessResponse:
-            type: object
-            properties:
-                ready:
-                    type: boolean
-                timestamp:
-                    type: string
-                    format: date-time
-                checks:
-                    type: object
-                    properties:
-                        database:
-                            type: boolean
-                        modules:
-                            type: boolean
-                        encryption:
-                            type: object
-                            properties:
-                                status:
-                                    type: string
-                                testResult:
-                                    type: string
-
-        Error:
-            type: object
-            required:
-                - error
-            properties:
-                error:
-                    type: object
-                    required:
-                        - code
-                        - message
-                    properties:
-                        code:
-                            type: string
-                        message:
-                            type: string
-                        details:
-                            type: object
-
-    responses:
-        BadRequest:
-            description: Bad request - invalid input
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-                    example:
-                        error:
-                            code: BAD_REQUEST
-                            message: Invalid request parameters
-
-        Unauthorized:
-            description: Unauthorized - missing or invalid authentication
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-                    example:
-                        error:
-                            code: UNAUTHORIZED
-                            message: Authentication required
-
-        NotFound:
-            description: Resource not found
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-                    example:
-                        error:
-                            code: NOT_FOUND
-                            message: Resource not found
-
-        ValidationError:
-            description: Validation error - invalid data
-            content:
-                application/json:
-                    schema:
-                        $ref: '#/components/schemas/Error'
-                    example:
-                        error:
-                            code: VALIDATION_ERROR
-                            message: Data validation failed