WakaTime API — Stats

naftiko: 1.0.0-alpha2
info:
  label: WakaTime API — Stats
  description: 'WakaTime API — Stats. 5 operations. Lead operation: Get All Time Since Today. Self-contained Naftiko capability covering one WakaTime business surface.'
  tags:
  - WakaTime
  - Developer Productivity
  - Stats
  created: '2026-05-30'
  modified: '2026-05-30'
binds:
- namespace: env
  keys:
    WAKATIME_API_KEY: WAKATIME_API_KEY
capability:
  consumes:
  - type: http
    namespace: wakatime-api-v1-stats
    baseUri: https://wakatime.com/api/v1
    description: WakaTime API — Stats business capability. Self-contained, no shared references.
    authentication:
      type: basic
      username: '{{env.WAKATIME_API_KEY}}'
      password: ''
    resources:
    - name: users-current-all-time-since-today
      path: /users/current/all_time_since_today
      operations:
      - name: getAllTimeSinceTodayCurrent
        method: GET
        description: Get All Time Since Today
        inputParameters:
        - name: project
          in: query
          type: string
          required: false
          description: Filter by project name.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-user-all-time-since-today
      path: /users/{user}/all_time_since_today
      operations:
      - name: getAllTimeSinceToday
        method: GET
        description: Get User All Time Since Today
        inputParameters:
        - name: user
          in: path
          type: string
          required: true
          description: User id, username, or "current".
        - name: project
          in: query
          type: string
          required: false
          description: Filter by project name.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-current-stats
      path: /users/current/stats
      operations:
      - name: getStatsForRange
        method: GET
        description: Get Stats For Range
        inputParameters:
        - name: range
          in: query
          type: string
          required: false
          description: Range filter (last_7_days, last_30_days, last_6_months, last_year, all_time).
        - name: timeout
          in: query
          type: integer
          required: false
          description: Keystroke timeout in minutes (defaults to user's account setting).
        - name: writes_only
          in: query
          type: boolean
          required: false
          description: Whether to only include time editing (writing) files.
        - name: timezone
          in: query
          type: string
          required: false
          description: Timezone to use (defaults to the user's profile timezone).
        - name: project
          in: query
          type: string
          required: false
          description: Filter by project name.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-current-stats-range
      path: /users/current/stats/{range}
      operations:
      - name: getStatsByRange
        method: GET
        description: Get Stats By Named Range
        inputParameters:
        - name: range
          in: path
          type: string
          required: true
          description: Preset range.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: users-current-stats-aggregated
      path: /users/current/stats_aggregated
      operations:
      - name: getStatsAggregated
        method: GET
        description: Get Stats Aggregated
        inputParameters:
        - name: range
          in: query
          type: string
          required: false
          description: Range filter (last_7_days, last_30_days, last_6_months, last_year, all_time).
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    namespace: wakatime-api-v1-stats-rest
    port: 8080
    description: REST adapter for WakaTime API — Stats. One Spectral-compliant resource per consumed operation, prefixed with /v1.
    resources:
    - path: /v1/users/current/all-time-since-today
      name: users-current-all-time-since-today
      description: REST surface for /users/current/all_time_since_today.
      operations:
      - method: GET
        name: getAllTimeSinceTodayCurrent
        description: Get All Time Since Today
        call: wakatime-api-v1-stats.getAllTimeSinceTodayCurrent
        with:
          project: rest.project
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/{user}/all-time-since-today
      name: users-user-all-time-since-today
      description: REST surface for /users/{user}/all_time_since_today.
      operations:
      - method: GET
        name: getAllTimeSinceToday
        description: Get User All Time Since Today
        call: wakatime-api-v1-stats.getAllTimeSinceToday
        with:
          user: rest.user
          project: rest.project
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/current/stats
      name: users-current-stats
      description: REST surface for /users/current/stats.
      operations:
      - method: GET
        name: getStatsForRange
        description: Get Stats For Range
        call: wakatime-api-v1-stats.getStatsForRange
        with:
          range: rest.range
          timeout: rest.timeout
          writes_only: rest.writes_only
          timezone: rest.timezone
          project: rest.project
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/current/stats/{range}
      name: users-current-stats-range
      description: REST surface for /users/current/stats/{range}.
      operations:
      - method: GET
        name: getStatsByRange
        description: Get Stats By Named Range
        call: wakatime-api-v1-stats.getStatsByRange
        with:
          range: rest.range
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/users/current/stats-aggregated
      name: users-current-stats-aggregated
      description: REST surface for /users/current/stats_aggregated.
      operations:
      - method: GET
        name: getStatsAggregated
        description: Get Stats Aggregated
        call: wakatime-api-v1-stats.getStatsAggregated
        with:
          range: rest.range
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: wakatime-api-v1-stats-mcp
    port: 9090
    transport: http
    description: MCP adapter for WakaTime API — Stats. One tool per consumed operation, routed inline through this capability's consumes block.
    tools:
    - name: get-all-time-since-today
      description: Get All Time Since Today
      hints:
        destructive: false
        idempotent: true
        readOnly: true
      call: wakatime-api-v1-stats.getAllTimeSinceTodayCurrent
      with:
        project: tools.project
      outputParameters:
      - type: object
        mapping: $.
    - name: get-user-all-time-since-today
      description: Get User All Time Since Today
      hints:
        destructive: false
        idempotent: true
        readOnly: true
      call: wakatime-api-v1-stats.getAllTimeSinceToday
      with:
        user: tools.user
        project: tools.project
      outputParameters:
      - type: object
        mapping: $.
    - name: get-stats-range
      description: Get Stats For Range
      hints:
        destructive: false
        idempotent: true
        readOnly: true
      call: wakatime-api-v1-stats.getStatsForRange
      with:
        range: tools.range
        timeout: tools.timeout
        writes_only: tools.writes_only
        timezone: tools.timezone
        project: tools.project
      outputParameters:
      - type: object
        mapping: $.
    - name: get-stats-named-range
      description: Get Stats By Named Range
      hints:
        destructive: false
        idempotent: true
        readOnly: true
      call: wakatime-api-v1-stats.getStatsByRange
      with:
        range: tools.range
      outputParameters:
      - type: object
        mapping: $.
    - name: get-stats-aggregated
      description: Get Stats Aggregated
      hints:
        destructive: false
        idempotent: true
        readOnly: true
      call: wakatime-api-v1-stats.getStatsAggregated
      with:
        range: tools.range
      outputParameters:
      - type: object
        mapping: $.