naftiko: "1.0.0-alpha2"

info:
  label: "Genius API — Annotations"
  description: >-
    Annotations — community annotations attached to lyric fragments. 8 operations covering read,
    create, delete, edits, comments, and voting. Lead operation: Get Annotation.
    Self-contained Naftiko capability covering one Genius business surface.
  tags:
    - Genius
    - Music
    - Annotations
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      GENIUS_ACCESS_TOKEN: GENIUS_ACCESS_TOKEN

capability:

  consumes:
    - type: http
      namespace: "genius-annotations"
      baseUri: "https://api.genius.com"
      description: "Genius API — Annotations business capability."
      authentication:
        type: bearer
        token: "{{env.GENIUS_ACCESS_TOKEN}}"
      resources:
        - name: "annotation"
          path: "/annotations/{id}"
          operations:
            - name: "getAnnotation"
              method: GET
              description: "Returns the full content of an annotation."
              inputParameters:
                - { name: "id",         in: path,  type: integer, required: true,  description: "Annotation ID." }
                - { name: "text_format",in: query, type: string,  required: false, description: "Format for textual fields." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
            - name: "deleteAnnotation"
              method: DELETE
              description: "Deletes an annotation owned by the authenticated user."
              inputParameters:
                - { name: "id", in: path, type: integer, required: true, description: "Annotation ID." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "annotations"
          path: "/annotations"
          operations:
            - name: "createAnnotation"
              method: POST
              description: "Creates a new annotation."
              inputParameters:
                - { name: "body", in: body, type: object, required: true, description: "CreateAnnotationRequest payload." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "annotation-edits"
          path: "/annotations/{id}/edits"
          operations:
            - name: "getAnnotationEdits"
              method: GET
              description: "Returns the version history of an annotation."
              inputParameters:
                - { name: "id", in: path, type: integer, required: true, description: "Annotation ID." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "annotation-comments"
          path: "/annotations/{id}/comments"
          operations:
            - name: "getAnnotationComments"
              method: GET
              description: "Returns comments left on an annotation."
              inputParameters:
                - { name: "id",       in: path,  type: integer, required: true,  description: "Annotation 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: "annotation-vote"
          path: "/annotations/{id}/vote"
          operations:
            - name: "upvoteAnnotation"
              method: PUT
              description: "Upvotes an annotation as the authenticated user."
              inputParameters:
                - { name: "id", in: path, type: integer, required: true, description: "Annotation ID." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
            - name: "removeAnnotationVote"
              method: DELETE
              description: "Removes the authenticated user's vote from the annotation."
              inputParameters:
                - { name: "id", in: path, type: integer, required: true, description: "Annotation ID." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]
        - name: "annotation-downvote"
          path: "/annotations/{id}/downvote"
          operations:
            - name: "downvoteAnnotation"
              method: PUT
              description: "Downvotes an annotation as the authenticated user."
              inputParameters:
                - { name: "id", in: path, type: integer, required: true, description: "Annotation ID." }
              outputRawFormat: json
              outputParameters: [{ name: result, type: object, value: "$." }]

  exposes:
    - type: rest
      namespace: "genius-annotations-rest"
      port: 8080
      description: "REST adapter for Genius — Annotations."
      resources:
        - path: "/v1/annotations/{id}"
          name: "annotation"
          description: "Annotation detail."
          operations:
            - method: GET
              name: "getAnnotation"
              description: "Get an annotation by ID."
              call: "genius-annotations.getAnnotation"
              with: { "id": "rest.id", "text_format": "rest.text_format" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: DELETE
              name: "deleteAnnotation"
              description: "Delete an annotation."
              call: "genius-annotations.deleteAnnotation"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/annotations"
          name: "annotations"
          description: "Annotation collection."
          operations:
            - method: POST
              name: "createAnnotation"
              description: "Create a new annotation."
              call: "genius-annotations.createAnnotation"
              with: { "body": "rest.body" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/annotations/{id}/edits"
          name: "annotation-edits"
          description: "Annotation version history."
          operations:
            - method: GET
              name: "getAnnotationEdits"
              description: "Get annotation version history."
              call: "genius-annotations.getAnnotationEdits"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/annotations/{id}/comments"
          name: "annotation-comments"
          description: "Annotation comments."
          operations:
            - method: GET
              name: "getAnnotationComments"
              description: "List comments on an annotation."
              call: "genius-annotations.getAnnotationComments"
              with: { "id": "rest.id", "per_page": "rest.per_page", "page": "rest.page" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/annotations/{id}/vote"
          name: "annotation-vote"
          description: "Annotation vote."
          operations:
            - method: PUT
              name: "upvoteAnnotation"
              description: "Upvote an annotation."
              call: "genius-annotations.upvoteAnnotation"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
            - method: DELETE
              name: "removeAnnotationVote"
              description: "Remove a vote from an annotation."
              call: "genius-annotations.removeAnnotationVote"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]
        - path: "/v1/annotations/{id}/downvote"
          name: "annotation-downvote"
          description: "Annotation downvote."
          operations:
            - method: PUT
              name: "downvoteAnnotation"
              description: "Downvote an annotation."
              call: "genius-annotations.downvoteAnnotation"
              with: { "id": "rest.id" }
              outputParameters: [{ type: object, mapping: "$." }]

    - type: mcp
      namespace: "genius-annotations-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Genius — Annotations."
      tools:
        - name: "get-annotation"
          description: "Get a Genius annotation by ID."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-annotations.getAnnotation"
          with: { "id": "tools.id", "text_format": "tools.text_format" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "delete-annotation"
          description: "Delete a Genius annotation."
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: "genius-annotations.deleteAnnotation"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "create-annotation"
          description: "Create a new Genius annotation."
          hints: { readOnly: false, destructive: false, idempotent: false }
          call: "genius-annotations.createAnnotation"
          with: { "body": "tools.body" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-annotation-edits"
          description: "List the version history for a Genius annotation."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-annotations.getAnnotationEdits"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "list-annotation-comments"
          description: "List comments on a Genius annotation."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "genius-annotations.getAnnotationComments"
          with: { "id": "tools.id", "per_page": "tools.per_page", "page": "tools.page" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "upvote-annotation"
          description: "Upvote a Genius annotation."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "genius-annotations.upvoteAnnotation"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "remove-annotation-vote"
          description: "Remove the user's vote from a Genius annotation."
          hints: { readOnly: false, destructive: true, idempotent: true }
          call: "genius-annotations.removeAnnotationVote"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]
        - name: "downvote-annotation"
          description: "Downvote a Genius annotation."
          hints: { readOnly: false, destructive: false, idempotent: true }
          call: "genius-annotations.downvoteAnnotation"
          with: { "id": "tools.id" }
          outputParameters: [{ type: object, mapping: "$." }]