openapi: "3.0.3"

info:
  title: SentryAgent.ai — SDK Scaffold Generator
  version: 1.0.0
  description: |
    SDK scaffold generator endpoint for the SentryAgent.ai AgentIdP platform.

    The scaffold endpoint generates a ready-to-run agent project ZIP archive
    pre-configured with the agent's credentials, API URL, and chosen SDK.

    The generated scaffold includes:
    - Language-specific project structure (TypeScript / Python / Go / Java / Rust)
    - Pre-filled `.env.example` with `CLIENT_ID` and `API_URL`
    - Agent authentication boilerplate using the SentryAgent.ai SDK
    - README with quickstart instructions
    - Docker / CI configuration (where applicable)

    **Authentication:** Requires a valid Bearer JWT.
    **Rate limit:** 10 requests per minute per tenant (separate from the global limit).
    The scaffold endpoint responds with `Retry-After` on rate limit.

    **Supported languages:** `typescript`, `python`, `go`, `java`, `rust`

servers:
  - url: http://localhost:3000/api/v1
    description: Local development server
  - url: https://api.sentryagent.ai/v1
    description: Production server

tags:
  - name: SDK Scaffold
    description: Generate a ready-to-run agent SDK project scaffold

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT access token obtained via `POST /token`.
        Include as `Authorization: Bearer <token>`.

  schemas:
    ScaffoldLanguage:
      type: string
      enum:
        - typescript
        - python
        - go
        - java
        - rust
      description: Target programming language for the scaffold project.
      example: typescript

    ErrorResponse:
      type: object
      description: Standard error response envelope.
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: "AGENT_NOT_FOUND"
        message:
          type: string
          example: "Agent with the specified ID was not found."
        details:
          type: object
          additionalProperties: true

  responses:
    Unauthorized:
      description: Missing or invalid Bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "UNAUTHORIZED"
            message: "A valid Bearer token is required to access this resource."

    Forbidden:
      description: Valid token but insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "FORBIDDEN"
            message: "You do not have permission to access this agent's scaffold."

    NotFound:
      description: Agent not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "AGENT_NOT_FOUND"
            message: "Agent with the specified ID was not found."

    TooManyRequests:
      description: |
        Scaffold-specific rate limit exceeded (10 requests per minute per tenant).
        Retry after the duration specified in the `Retry-After` header.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Number of seconds to wait before retrying.
          example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "RATE_LIMIT_EXCEEDED"
            message: "Scaffold rate limit exceeded. Please retry after 60 seconds."

    InternalServerError:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: "INTERNAL_SERVER_ERROR"
            message: "An unexpected error occurred. Please try again later."

security:
  - BearerAuth: []

paths:
  /sdk/scaffold/{agentId}:
    get:
      operationId: getAgentScaffold
      tags:
        - SDK Scaffold
      summary: Generate and download an agent SDK scaffold ZIP
      description: |
        Generates a ready-to-run agent project scaffold for the specified agent
        and streams it as a ZIP file download.

        The scaffold is customized with:
        - The agent's `CLIENT_ID` pre-filled in `.env.example`
        - The platform API URL (`API_URL`) configured for the environment
        - The agent's name, type, and capabilities reflected in project metadata
        - Language-specific SDK integration boilerplate

        **Rate limit:** 10 requests per minute per tenant.
        Exceeding this limit returns `429 Too Many Requests` with a `Retry-After` header.

        **Language selection:** Pass the desired `language` query parameter.
        Defaults to `typescript` when omitted.

        **Authorization:** The authenticated agent (from Bearer token) must belong to
        the same organization as the target agent (`agentId`). Cross-tenant scaffold
        generation is not permitted.
      parameters:
        - name: agentId
          in: path
          required: true
          description: UUID of the agent to generate a scaffold for.
          schema:
            type: string
            format: uuid
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        - name: language
          in: query
          required: false
          description: |
            Target programming language for the scaffold.
            Defaults to `typescript` when omitted.
          schema:
            $ref: '#/components/schemas/ScaffoldLanguage'
          example: typescript
      responses:
        '200':
          description: |
            Scaffold ZIP archive generated and streamed successfully.

            The response body is a ZIP archive containing the generated project files.
            Save it locally and unzip to get started:
            ```
            curl -O -J -H "Authorization: Bearer <token>" \
              "https://api.sentryagent.ai/v1/sdk/scaffold/a1b2c3d4-e5f6-7890-abcd-ef1234567890?language=typescript"
            unzip screener-001-scaffold.zip
            cd screener-001-scaffold && npm install
            ```
          headers:
            Content-Disposition:
              schema:
                type: string
              description: |
                Filename for the ZIP download.
                Format: `attachment; filename="<agent-name>-scaffold.zip"`
              example: 'attachment; filename="screener-001-scaffold.zip"'
            Content-Type:
              schema:
                type: string
              example: "application/zip"
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Scaffold rate limit (requests per minute per tenant).
              example: 10
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Remaining scaffold requests in the current window.
              example: 9
          content:
            application/zip:
              schema:
                type: string
                format: binary
                description: ZIP archive of the generated scaffold project.
        '400':
          description: Invalid `language` query parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "VALIDATION_ERROR"
                message: "Invalid language. Supported languages are: typescript, python, go, java, rust."
                details:
                  field: "language"
                  provided: "ruby"
                  supported:
                    - typescript
                    - python
                    - go
                    - java
                    - rust
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          description: Agent is decommissioned — cannot generate scaffold for inactive agents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: "AGENT_DECOMMISSIONED"
                message: "Cannot generate scaffold for a decommissioned agent."
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'