Windsurf Analytics and Billing

naftiko: "1.0.0-alpha1"

info:
  label: "Windsurf Analytics and Billing"
  description: >-
    Analytics and billing management capability for Windsurf Enterprise. Enables
    platform administrators to query AI code completion usage, monitor Cascade agent
    activity, review per-user analytics, manage billing configurations, and track
    team credit consumption. Designed for engineering leaders, DevOps teams, and
    finance teams managing AI coding tool usage.
  tags:
    - Windsurf
    - Analytics
    - Billing
    - Enterprise
    - AI Coding
    - Teams
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      WINDSURF_SERVICE_KEY: WINDSURF_SERVICE_KEY

capability:
  consumes:
    - import: windsurf
      location: ./shared/windsurf-enterprise.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: windsurf-analytics-api
      description: "Unified REST API for Windsurf Analytics and Billing management."
      resources:
        - path: /v1/analytics/completions
          name: completion-analytics
          description: "Code completion analytics"
          operations:
            - method: POST
              name: query-completion-analytics
              description: "Query code completion usage analytics"
              call: "windsurf.get-custom-analytics"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/analytics/users
          name: user-analytics
          description: "Per-user analytics"
          operations:
            - method: POST
              name: query-user-analytics
              description: "Get user-level analytics and acceptance rates"
              call: "windsurf.get-user-analytics"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/analytics/cascade
          name: cascade-analytics
          description: "Cascade AI agent analytics"
          operations:
            - method: POST
              name: query-cascade-analytics
              description: "Get Cascade AI usage analytics"
              call: "windsurf.get-cascade-analytics"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/billing/credits
          name: credit-balance
          description: "Credit balance management"
          operations:
            - method: POST
              name: get-credit-balance
              description: "Get team credit balance"
              call: "windsurf.get-credit-balance"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/billing/config
          name: usage-config
          description: "Usage configuration"
          operations:
            - method: POST
              name: get-usage-config
              description: "Get usage configuration settings"
              call: "windsurf.get-usage-config"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: PUT
              name: update-usage-config
              description: "Update usage configuration settings"
              call: "windsurf.set-usage-config"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: windsurf-analytics-mcp
      transport: http
      description: "MCP server for AI-assisted Windsurf Analytics and Billing management."
      tools:
        - name: query-completion-analytics
          description: "Query Windsurf code completion usage analytics for the team"
          hints:
            readOnly: true
            openWorld: true
          call: "windsurf.get-custom-analytics"
          with:
            start_timestamp: "tools.start_timestamp"
            end_timestamp: "tools.end_timestamp"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-user-analytics
          description: "Get per-user code completion analytics and acceptance rates"
          hints:
            readOnly: true
            openWorld: true
          call: "windsurf.get-user-analytics"
          with:
            emails: "tools.emails"
            start_timestamp: "tools.start_timestamp"
            end_timestamp: "tools.end_timestamp"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-cascade-analytics
          description: "Get Cascade AI agent usage metrics including lines generated"
          hints:
            readOnly: true
            openWorld: true
          call: "windsurf.get-cascade-analytics"
          with:
            emails: "tools.emails"
            start_timestamp: "tools.start_timestamp"
            end_timestamp: "tools.end_timestamp"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-credit-balance
          description: "Check current team credit balance and usage for Windsurf Enterprise"
          hints:
            readOnly: true
            openWorld: false
          call: "windsurf.get-credit-balance"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-usage-config
          description: "Get current usage configuration and feature flags for the team"
          hints:
            readOnly: true
            openWorld: false
          call: "windsurf.get-usage-config"
          outputParameters:
            - type: object
              mapping: "$."

        - name: update-usage-config
          description: "Update usage configuration, model access controls, and feature flags"
          hints:
            readOnly: false
            destructive: false
            idempotent: true
          call: "windsurf.set-usage-config"
          with:
            model_access: "tools.model_access"
            feature_flags: "tools.feature_flags"
          outputParameters:
            - type: object
              mapping: "$."