# API Contract for Share Music System
# Version: v004
# Generated: 2025-12-18

endpoints:
  - id: api_create_song_share
    method: POST
    path: /api/share/song/[id]
    request:
      params:
        - name: id
          type: string
          required: true
      body:
        type: CreateShareRequest
        fields:
          - name: platform
            type: string
            required: false
    response:
      type: CreateShareResponse
      fields:
        - name: shareUrl
          type: string
        - name: token
          type: string
        - name: type
          type: ShareType

  - id: api_create_playlist_share
    method: POST
    path: /api/share/playlist/[id]
    request:
      params:
        - name: id
          type: string
          required: true
      body:
        type: CreateShareRequest
    response:
      type: CreateShareResponse

  - id: api_create_album_share
    method: POST
    path: /api/share/album/[id]
    request:
      params:
        - name: id
          type: string
          required: true
      body:
        type: CreateShareRequest
    response:
      type: CreateShareResponse

  - id: api_resolve_share
    method: GET
    path: /api/share/[token]
    request:
      params:
        - name: token
          type: string
          required: true
    response:
      type: ResolveShareResponse
      fields:
        - name: type
          type: ShareType
        - name: targetId
          type: string
        - name: content
          type: object
        - name: shareUrl
          type: string

  - id: api_track_share_click
    method: POST
    path: /api/share/[token]/click
    request:
      params:
        - name: token
          type: string
          required: true
    response:
      type: TrackShareClickResponse
      fields:
        - name: success
          type: boolean
        - name: clickCount
          type: number

types:
  ShareType:
    enum: [SONG, PLAYLIST, ALBUM]

  CreateShareRequest:
    fields:
      platform:
        type: string
        optional: true

  CreateShareResponse:
    fields:
      shareUrl:
        type: string
      token:
        type: string
      type:
        type: ShareType

  ResolveShareResponse:
    fields:
      type:
        type: ShareType
      targetId:
        type: string
      content:
        type: object
      shareUrl:
        type: string

  TrackShareClickResponse:
    fields:
      success:
        type: boolean
      clickCount:
        type: number

shared_types_file: types/api-types.ts