naftiko: "1.0.0-alpha2"

info:
  label: "Genius API — Albums"
  description: >-
    Albums — album metadata, tracks, cover arts, comments, and leaderboards. 5 operations.
    Lead operation: Get Album.
    Self-contained Naftiko capability covering one Genius business surface.
  tags:
    - Genius
    - Music
    - Albums
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      GENIUS_ACCESS_TOKEN: GENIUS_ACCESS_TOKEN

capability:

  consumes:
    - type: http
      namespace: "genius-albums"
      baseUri: "https://api.genius.com"
      description: "Genius API — Albums business capability."
      authentication:
        type: bearer
        token: "{{env.GENIUS_ACCESS_TOKEN}}"
      resources:
        - name: "album"
          path: "/albums/{id}"
          operations:
            - name: "getAlbum"
              method: GET
              description: "Returns album metadata."
              inputParameters:
                - { name: "id",         in: path,  type: integer, required: true,  description: "Genius album ID." }
                - { name: "text_format",in: query, type: string,  required: false, description: "Format for textual fields." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "album-tracks"
          path: "/albums/{id}/tracks"
          operations:
            - name: "getAlbumTracks"
              method: GET
              description: "Returns the album tracklist."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius album ID." }
                - { name: "per_page", in: query, type: integer, required: false, description: "Results per page." }
                - { name: "page",     in: query, type: integer, required: false, description: "Page index." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "album-comments"
          path: "/albums/{id}/comments"
          operations:
            - name: "getAlbumComments"
              method: GET
              description: "Returns comments left on the album page."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius album ID." }
                - { name: "per_page", in: query, type: integer, required: false, description: "Results per page." }
                - { name: "page",     in: query, type: integer, required: false, description: "Page index." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "album-cover-arts"
          path: "/albums/{id}/cover_arts"
          operations:
            - name: "getAlbumCoverArts"
              method: GET
              description: "Returns all cover-art images attached to the album."
              inputParameters:
                - { name: "id", in: path, type: integer, required: true, description: "Genius album ID." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "album-leaderboard"
          path: "/albums/{id}/leaderboard"
          operations:
            - name: "getAlbumLeaderboard"
              method: GET
              description: "Returns top contributors to the album."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Genius album ID." }
                - { name: "per_page", in: query, type: integer, required: false, description: "Results per page." }
                - { name: "page",     in: query, type: integer, required: false, description: "Page index." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]

  exposes:
    - type: rest
      namespace: "genius-albums-rest"
      port: 8080
      description: "REST adapter for Genius — Albums."
      resources:
        - path: "/v1/albums/{id}"
          name: "album"
          description: "Album detail."
          operations:
            - method: GET
              name: "getAlbum"
              description: "Get an album by ID."
              call: "genius-albums.getAlbum"
              with: { "id": "rest.id", "text_format": "rest.text_format" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/albums/{id}/tracks"
          name: "album-tracks"
          description: "Album tracklist."
          operations:
            - method: GET
              name: "getAlbumTracks"
              description: "List tracks on an album."
              call: "genius-albums.getAlbumTracks"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/albums/{id}/comments"
          name: "album-comments"
          description: "Album comments."
          operations:
            - method: GET
              name: "getAlbumComments"
              description: "List album comments."
              call: "genius-albums.getAlbumComments"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/albums/{id}/cover-arts"
          name: "album-cover-arts"
          description: "Album cover arts."
          operations:
            - method: GET
              name: "getAlbumCoverArts"
              description: "Get album cover arts."
              call: "genius-albums.getAlbumCoverArts"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/albums/{id}/leaderboard"
          name: "album-leaderboard"
          description: "Album leaderboard."
          operations:
            - method: GET
              name: "getAlbumLeaderboard"
              description: "Get top contributors to the album."
              call: "genius-albums.getAlbumLeaderboard"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "genius-albums-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Genius — Albums."
      tools:
        - name: "get-album"
          description: "Get a Genius album by ID."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-albums.getAlbum"
          with: { "id": "tools.id", "text_format": "tools.text_format" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-album-tracks"
          description: "List tracks on a Genius album."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-albums.getAlbumTracks"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-album-comments"
          description: "List comments on a Genius album."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-albums.getAlbumComments"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-album-cover-arts"
          description: "Get cover-art images for a Genius album."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-albums.getAlbumCoverArts"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "get-album-leaderboard"
          description: "Get the leaderboard for a Genius album."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-albums.getAlbumLeaderboard"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]