Wordnik — Account

naftiko: "1.0.0-alpha2"

info:
  label: "Wordnik — Account"
  description: >-
    Account — API-key telemetry and user authentication surface. 5 operations covering
    API-token quota status, authentication via GET or POST, current-user profile lookup,
    and the authenticated user's word-list inventory. Lead operation: return current API
    token status. Self-contained Naftiko capability covering one Wordnik business surface.
  tags:
    - Wordnik
    - Dictionary
    - Account
  created: "2026-05-29"
  modified: "2026-05-29"

binds:
  - namespace: env
    keys:
      WORDNIK_API_KEY: WORDNIK_API_KEY
      WORDNIK_AUTH_TOKEN: WORDNIK_AUTH_TOKEN

capability:

  consumes:
    - type: http
      namespace: "wordnik-account"
      baseUri: "https://api.wordnik.com/v4"
      description: "Wordnik — Account business capability. Self-contained, no shared references."
      authentication:
        type: apikey
        key: api_key
        value: "{{env.WORDNIK_API_KEY}}"
        placement: query
      resources:
        - name: "account"
          path: "/account.json"
          operations:
            - name: "getApiTokenStatus"
              method: GET
              description: "Return API token status."
              inputParameters:
                - { name: api_key, in: header, type: string, required: false, description: "Wordnik API key." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "authenticate"
              method: GET
              description: "Authenticate a user."
              inputParameters:
                - { name: username, in: path, type: string, required: true, description: "A confirmed Wordnik username." }
                - { name: password, in: query, type: string, required: true, description: "The user's password." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "authenticatePost"
              method: POST
              description: "Authenticate a user via POST body."
              inputParameters:
                - { name: username, in: path, type: string, required: true, description: "A confirmed Wordnik username." }
                - { name: body, in: body, type: object, required: true, description: "Password payload." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "getLoggedInUser"
              method: GET
              description: "Return the currently authenticated user."
              inputParameters:
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }
            - name: "getWordListsForLoggedInUser"
              method: GET
              description: "Return the authenticated user's word lists."
              inputParameters:
                - { name: auth_token, in: header, type: string, required: true, description: "Valid user auth token." }
                - { name: skip, in: query, type: integer, required: false, description: "Results to skip." }
                - { name: limit, in: query, type: integer, required: false, description: "Maximum number of lists to return." }
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: "$." }

  exposes:
    - type: rest
      namespace: "wordnik-account-rest"
      port: 8080
      description: "REST adapter for Wordnik — Account. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/account/api-token-status"
          name: "api-token-status"
          description: "REST surface for API token status."
          operations:
            - method: GET
              name: "getApiTokenStatus"
              description: "Return API token status."
              call: "wordnik-account.getApiTokenStatus"
              with:
                api_key: "rest.api_key"
              outputParameters:
                - { type: object, mapping: "$." }
        - path: "/v1/account/authenticate/{username}"
          name: "authenticate"
          description: "REST surface for user authentication."
          operations:
            - method: GET
              name: "authenticate"
              description: "Authenticate a user."
              call: "wordnik-account.authenticate"
              with:
                username: "rest.username"
                password: "rest.password"
              outputParameters:
                - { type: object, mapping: "$." }
            - method: POST
              name: "authenticatePost"
              description: "Authenticate a user via POST body."
              call: "wordnik-account.authenticatePost"
              with:
                username: "rest.username"
                body: "rest.body"
              outputParameters:
                - { type: object, mapping: "$." }
        - path: "/v1/account/user"
          name: "logged-in-user"
          description: "REST surface for the current authenticated user."
          operations:
            - method: GET
              name: "getLoggedInUser"
              description: "Return the currently authenticated user."
              call: "wordnik-account.getLoggedInUser"
              with:
                auth_token: "rest.auth_token"
              outputParameters:
                - { type: object, mapping: "$." }
        - path: "/v1/account/word-lists"
          name: "user-word-lists"
          description: "REST surface for the user's word lists."
          operations:
            - method: GET
              name: "getWordListsForLoggedInUser"
              description: "Return the authenticated user's word lists."
              call: "wordnik-account.getWordListsForLoggedInUser"
              with:
                auth_token: "rest.auth_token"
                skip: "rest.skip"
                limit: "rest.limit"
              outputParameters:
                - { type: object, mapping: "$." }

    - type: mcp
      namespace: "wordnik-account-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Wordnik — Account. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "check-api-token-status"
          description: "Return API token status."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "wordnik-account.getApiTokenStatus"
          with:
            api_key: "tools.api_key"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "authenticate-user"
          description: "Authenticate a user."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "wordnik-account.authenticate"
          with:
            username: "tools.username"
            password: "tools.password"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "authenticate-user-post"
          description: "Authenticate a user via POST body."
          hints: { readOnly: true, destructive: false, idempotent: false }
          call: "wordnik-account.authenticatePost"
          with:
            username: "tools.username"
            body: "tools.body"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "get-logged-in-user"
          description: "Return the currently authenticated user."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "wordnik-account.getLoggedInUser"
          with:
            auth_token: "tools.auth_token"
          outputParameters:
            - { type: object, mapping: "$." }
        - name: "list-user-word-lists"
          description: "Return the authenticated user's word lists."
          hints: { readOnly: true, destructive: false, idempotent: true }
          call: "wordnik-account.getWordListsForLoggedInUser"
          with:
            auth_token: "tools.auth_token"
            skip: "tools.skip"
            limit: "tools.limit"
          outputParameters:
            - { type: object, mapping: "$." }