openapi.yaml

openapi: 3.0.3
info:
  title: Chat Widget Auth & History API
  description: >
    채팅 위젯의 **인증(Auth)** 및 **대화 내역 저장(History Storage)**을 담당하는 백엔드 API입니다.
    
    **도메인 정책 (v1.3):**
    - 위젯 키 생성 시 `https://` 프로토콜을 제외한 도메인만 입력받습니다.
    - 루트 도메인, 서브 도메인 와일드카드 정책이 적용됩니다.
  version: 1.4.0

servers:
  - url: http://localhost:3000

tags:
  - name: Authentication
    description: Admin 인증 (IDP 연동)
  - name: Widget Auth
    description: (Public) 위젯 초기화 및 세션 발급
  - name: Widget Messages
    description: (Public) 대화 내역 저장 및 조회
  - name: Admin Management
    description: (Private) 위젯 키 관리

paths:
  # ----------------------------
  # 0. Admin Authentication
  # ----------------------------
  /api/v1/auth/admin/login:
    post:
      tags:
        - Authentication
      summary: Admin 로그인
      description: >
        Infoteam IDP access token을 사용하여 로그인하고 자체 JWT 토큰을 발급받습니다.
        
        **인증 요구사항:**
        - Infoteam IDP에서 발급받은 valid access token
        - @gistory.me 이메일 도메인
        
        **응답:**
        - 자체 JWT access token (이후 Admin API 호출 시 사용)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminLoginRequest'
      responses:
        '200':
          description: 로그인 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminLoginResponse'
        '401':
          description: IDP 토큰 검증 실패 또는 권한 없음 (@gistory.me 도메인 아님)

  # ----------------------------
  # 1. Widget Authentication
  # ----------------------------
  /api/v1/widget/auth/session:
    post:
      tags:
        - Widget Auth
      summary: 위젯 세션 토큰 발급
      description: >
        위젯 키와 현재 페이지의 도메인을 검증하여 **세션 토큰**을 발급합니다.
        
        **검증 로직 상세:**
        1. 요청 헤더의 `Origin`이 존재하면 이를 우선 검증값으로 사용합니다.
        2. `Origin`이 없는 경우(일부 환경) body의 `pageUrl`에서 도메인을 추출합니다.
        3. 두 값이 모두 존재하는데 서로 다르다면 요청은 거부(Spoofing 의심)됩니다.
        4. 추출된 도메인(프로토콜 제거)이 DB의 `allowedDomains` 규칙과 매칭되는지 확인합니다.
        5. 해당 `widgetKey`가 `REVOKED` 상태라면 발급을 거부합니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WidgetSessionRequest'
      responses:
        '200':
          description: 세션 발급 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetSessionResponse'
        '400':
          description: 잘못된 요청 (Origin/PageUrl 불일치 등)
        '403':
          description: 도메인 검증 실패 또는 REVOKED 된 키
        '404':
          description: 존재하지 않는 widgetKey

  # ----------------------------
  # 2. Chat History Storage
  # ----------------------------
  /api/v1/widget/messages:
    get:
      tags:
        - Widget Messages
      summary: 대화 내역 조회 (페이징)
      security:
        - widgetSessionAuth: []
      parameters:
        - in: query
          name: cursor
          schema:
            type: string
          description: "이전 페이지의 마지막 메시지 ID (없으면 최신순 조회)"
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
          description: "한 번에 가져올 메시지 개수"
      responses:
        '200':
          description: 조회 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/ChatMessage'
                  nextCursor:  # <--- [중요] 추가됨: 다음 페이지 조회를 위한 커서
                    type: string
                    nullable: true
                    description: "다음 메시지를 불러오기 위한 커서 ID (null이면 더 이상 없음)"

    post:
      tags:
        - Widget Messages
      summary: 대화 메시지 저장
      security:
        - widgetSessionAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatMessageInput'
      responses:
        '201':
          description: 저장 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatMessage'
        '401':
          description: 인증 실패
        '429':
          description: 세션당 질문 횟수 초과 (user 메시지 최대 5회)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyQuestionsError'

  # ----------------------------
  # 3. Admin Management
  # ----------------------------
  /api/v1/admin/widget-keys:
    get:
      tags:
        - Admin Management
      summary: 위젯 키 목록 조회
      description: >
        모든 위젯 키 목록을 조회합니다.
        
        **인증:** @gistory.me 이메일로 Infoteam IDP 인증이 필요합니다.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WidgetKey'
        '401':
          description: 인증 실패 (유효하지 않은 토큰 또는 @gistory.me 이메일이 아님)

    post:
      tags:
        - Admin Management
      summary: 위젯 키 생성
      description: >
        새로운 위젯 키를 생성합니다. 생성된 직후 `secretKey`가 반환됩니다.
        
        키 생성 후 별도로 도메인 등록 API(`POST /api/v1/admin/widget-keys/{widgetKeyId}/domains`)를 호출하여 도메인을 등록해야 합니다.
        
        **인증:** @gistory.me 이메일로 Infoteam IDP 인증이 필요합니다.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  example: "메인 쇼핑몰용"
      responses:
        '201':
          description: 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetKey'
        '401':
          description: 인증 실패 (유효하지 않은 토큰 또는 @gistory.me 이메일이 아님)

  /api/v1/admin/widget-keys/{widgetKeyId}/domains:
    post:
      tags:
        - Admin Management
      summary: 도메인 등록
      description: >
        기존 위젯 키에 도메인을 하나씩 등록합니다. 기존 도메인 목록에 추가됩니다.
        
        **도메인 등록 규칙:**
        - 프로토콜(`https://`)은 제외하고 입력하세요.
        - `*.example.com` 와일드카드 지원.
        - 이미 등록된 도메인은 중복 등록할 수 없습니다.
        
        **인증:** @gistory.me 이메일로 Infoteam IDP 인증이 필요합니다.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: widgetKeyId
          required: true
          schema:
            type: string
            format: uuid
          description: "도메인을 등록할 위젯 키의 UUID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [domain]
              properties:
                domain:
                  type: string
                  example: "*.myshop.com"
                  description: "허용된 도메인 (프로토콜 제외)"
      responses:
        '200':
          description: 도메인 등록 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetKey'
        '400':
          description: 잘못된 요청 (도메인에 프로토콜 포함, 이미 등록된 도메인 등)
        '401':
          description: 인증 실패 (유효하지 않은 토큰 또는 @gistory.me 이메일이 아님)
        '403':
          description: 권한 없음 (본인이 만든 키가 아님)
        '404':
          description: 존재하지 않는 Key ID

  /api/v1/admin/widget-keys/{widgetKeyId}/domains/{domain}:
    delete:
      tags:
        - Admin Management
      summary: 도메인 삭제
      description: >
        기존 위젯 키에서 도메인을 삭제합니다.
        
        **인증:** @gistory.me 이메일로 Infoteam IDP 인증이 필요합니다.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: widgetKeyId
          required: true
          schema:
            type: string
            format: uuid
          description: "도메인을 삭제할 위젯 키의 UUID"
        - in: path
          name: domain
          required: true
          schema:
            type: string
          description: "삭제할 도메인 (프로토콜 제외)"
          example: "*.myshop.com"
      responses:
        '200':
          description: 도메인 삭제 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetKey'
        '401':
          description: 인증 실패 (유효하지 않은 토큰 또는 @gistory.me 이메일이 아님)
        '403':
          description: 권한 없음 (본인이 만든 키가 아님)
        '404':
          description: 존재하지 않는 Key ID 또는 도메인

  /api/v1/admin/widget-keys/{widgetKeyId}/revoke:
    patch:
      tags:
        - Admin Management
      summary: 위젯 키 폐기 (Revoke)
      description: >
        특정 키를 `REVOKED` 상태로 변경하여 더 이상 세션 발급이 불가능하게 만듭니다.
        
        **인증:** @gistory.me 이메일로 Infoteam IDP 인증이 필요합니다.
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: widgetKeyId
          required: true
          schema:
            type: string
            format: uuid
          description: "폐기할 위젯 키의 UUID"
      responses:
        '200':
          description: 폐기 성공 (상태 변경됨)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WidgetKey'
        '404':
          description: 존재하지 않는 Key ID

# ----------------------------
# Components
# ----------------------------
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "Infoteam IDP Access Token (@gistory.me 이메일 필수)"
    widgetSessionAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: "위젯 세션 토큰 (Widget Client)"

  schemas:
    # --- Admin Auth ---
    AdminLoginRequest:
      type: object
      required: [idp_token]
      properties:
        idp_token:
          type: string
          description: "Infoteam IDP에서 발급받은 access token"
          example: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

    AdminLoginResponse:
      type: object
      properties:
        access_token:
          type: string
          description: "자체 발급 JWT access token (Admin API 호출 시 Bearer 토큰으로 사용)"
          example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

    # --- Widget Auth ---
    WidgetSessionRequest:
      type: object
      required: [widgetKey, pageUrl]
      properties:
        widgetKey:
          type: string
          example: "wk_live_abc123"
        pageUrl:
          type: string
          description: "위젯이 실행된 현재 페이지 URL (Origin 검증 보조용)"
          example: "https://www.myshop.com/products/1"

    WidgetSessionResponse:
      type: object
      properties:
        sessionToken:
          type: string
          description: "JWT Access Token"
        expiresIn:
          type: integer
          description: "토큰 만료 시간(초)"

    # --- Chat ---
    ChatMessageInput:
      type: object
      required: [role, content]
      properties:
        role:
          type: string
          enum: [user, assistant]
        content:
          type: string
        metadata:
          type: object
          description: "토큰 사용량 등 부가 정보"

    ChatMessage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        role:
          type: string
          enum: [user, assistant]
        content:
          type: string
        metadata:
          type: object
          description: "토큰 사용량 등 부가 정보"
        createdAt:
          type: string
          format: date-time

    TooManyQuestionsError:
      type: object
      description: "세션당 질문 횟수 초과 시 429 응답"
      properties:
        statusCode:
          type: integer
          example: 429
        message:
          type: string
          example: "이 세션에서는 최대 5개의 질문만 가능합니다."
        limit:
          type: integer
          description: "세션당 최대 질문 횟수"
          example: 5

    # --- Admin ---
    WidgetKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: "위젯 키 이름 (식별용)"
          example: "메인 쇼핑몰용"
        secretKey:
          type: string
          example: "wk_live_xyz789"
        status:
          type: string
          enum: [ACTIVE, REVOKED]
        allowedDomains:
          type: array
          items:
            type: string
          example: ["myshop.com", "*.myshop.com"]
        createdAt:
          type: string
          format: date-time