AniList GraphQL API v2 — OAuth2

naftiko: "1.0.0-alpha2"

info:
  label: "AniList GraphQL API v2 — OAuth2"
  description: >-
    OAuth2 — AniList. 3 operations. Lead operation: Begin the OAuth2
    authorization flow. Self-contained Naftiko capability covering one AniList
    business surface — the OAuth2 endpoints under https://anilist.co/api/v2/oauth
    that authorize a user, exchange an authorization code for a one-year JWT
    access token, and (optionally) display the access token on a copy-and-paste
    pin page for clients that cannot register an HTTP or custom URI scheme
    redirect.
  tags:
    - AniList
    - OAuth2
    - Authentication
  created: "2026-05-30"
  modified: "2026-05-30"

binds:
  - namespace: env
    keys:
      ANILIST_CLIENT_ID: ANILIST_CLIENT_ID
      ANILIST_CLIENT_SECRET: ANILIST_CLIENT_SECRET

capability:

  # ── 1. Consumes — the upstream HTTP API this capability speaks to ─────
  consumes:
    - type: http
      namespace: "anilist-oauth2"
      baseUri: "https://anilist.co"
      description: "AniList GraphQL API v2 — OAuth2 business capability. Self-contained, no shared references."
      resources:
        - name: "oauth-authorize"
          path: "/api/v2/oauth/authorize"
          operations:
            - name: "oauthAuthorize"
              method: GET
              description: "Begin the OAuth2 Authorization Code or Implicit flow by redirecting the user to AniList."
              inputParameters:
                - name: "client_id"
                  in: query
                  type: string
                  required: true
                  description: "The client ID of the developer application."
                - name: "redirect_uri"
                  in: query
                  type: string
                  required: true
                  description: "Registered redirect URI for the application."
                - name: "response_type"
                  in: query
                  type: string
                  required: true
                  description: "`code` for Authorization Code Grant, `token` for Implicit Grant."
                - name: "state"
                  in: query
                  type: string
                  required: false
                  description: "Opaque value for CSRF protection / round-tripping state."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "oauth-token"
          path: "/api/v2/oauth/token"
          operations:
            - name: "oauthExchangeToken"
              method: POST
              description: "Exchange an authorization code for a one-year JWT access token."
              inputParameters:
                - name: "body"
                  in: body
                  type: object
                  required: true
                  description: "JSON payload with grant_type, client_id, client_secret, redirect_uri, and code."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."
        - name: "oauth-pin"
          path: "/api/v2/oauth/pin"
          operations:
            - name: "oauthAuthPin"
              method: GET
              description: "Display the OAuth2 auth pin (access token) on an HTML page for manual copy/paste."
              inputParameters: []
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  # ── 2. REST exposer — required default ────────────────────────────────
  exposes:
    - type: rest
      namespace: "anilist-oauth2-rest"
      port: 8080
      description: "REST adapter for AniList GraphQL API v2 — OAuth2. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/oauth/authorize"
          name: "oauth-authorize"
          description: "REST surface for the AniList OAuth2 authorize endpoint."
          operations:
            - method: GET
              name: "oauthAuthorize"
              description: "Begin the OAuth2 Authorization Code or Implicit flow."
              call: "anilist-oauth2.oauthAuthorize"
              with:
                client_id: "rest.client_id"
                redirect_uri: "rest.redirect_uri"
                response_type: "rest.response_type"
                state: "rest.state"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/oauth/token"
          name: "oauth-token"
          description: "REST surface for the AniList OAuth2 token-exchange endpoint."
          operations:
            - method: POST
              name: "oauthExchangeToken"
              description: "Exchange an authorization code for a one-year JWT access token."
              call: "anilist-oauth2.oauthExchangeToken"
              with:
                body: "rest.body"
              outputParameters:
                - type: object
                  mapping: "$."
        - path: "/v1/oauth/pin"
          name: "oauth-pin"
          description: "REST surface for the AniList OAuth2 auth-pin display page."
          operations:
            - method: GET
              name: "oauthAuthPin"
              description: "Display the OAuth2 auth pin (access token) on an HTML page for manual copy/paste."
              call: "anilist-oauth2.oauthAuthPin"
              with: {}
              outputParameters:
                - type: object
                  mapping: "$."

    # ── 3. MCP exposer — required default ───────────────────────────────
    - type: mcp
      namespace: "anilist-oauth2-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for AniList GraphQL API v2 — OAuth2. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "begin-oauth-authorize"
          description: "Begin the OAuth2 Authorization Code or Implicit flow."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "anilist-oauth2.oauthAuthorize"
          with:
            client_id: "tools.client_id"
            redirect_uri: "tools.redirect_uri"
            response_type: "tools.response_type"
            state: "tools.state"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "exchange-oauth-token"
          description: "Exchange an authorization code for a one-year JWT access token."
          hints:
            readOnly: false
            destructive: false
            idempotent: false
          call: "anilist-oauth2.oauthExchangeToken"
          with:
            body: "tools.body"
          outputParameters:
            - type: object
              mapping: "$."
        - name: "display-oauth-pin"
          description: "Display the OAuth2 auth pin (access token) on an HTML page for manual copy/paste."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "anilist-oauth2.oauthAuthPin"
          with: {}
          outputParameters:
            - type: object
              mapping: "$."