Telefono Phone Intelligence

naftiko: "1.0.0-alpha1"

info:
  label: "Telefono Phone Intelligence"
  description: >-
    Unified phone number intelligence capability combining validation, carrier lookup,
    and number formatting APIs. Designed for developers building fraud prevention,
    user verification, data enrichment, and SMS campaign optimization workflows.
  tags:
    - Carrier Lookup
    - Data Enrichment
    - Fraud Prevention
    - Number Intelligence
    - Phone Validation
    - Telecommunications
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TELEFONO_API_KEY: TELEFONO_API_KEY

capability:
  consumes:
    - import: telefono
      location: ./shared/telefono-validation.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: phone-intelligence-api
      description: "Unified REST API for phone number intelligence — validation, carrier lookup, and formatting."
      resources:
        - path: /v1/validate
          name: validate
          description: "Real-time phone number validation"
          operations:
            - method: GET
              name: validate-number
              description: "Validate a phone number and get type, carrier, country, and format"
              call: "telefono.validate-phone-number"
              with:
                number: "rest.number"
                country_code: "rest.country_code"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/validate/batch
          name: validate-batch
          description: "Batch phone number validation"
          operations:
            - method: POST
              name: validate-batch
              description: "Validate up to 100 phone numbers in one request"
              call: "telefono.validate-phone-number-batch"
              with:
                numbers: "rest.numbers"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/carrier
          name: carrier
          description: "Carrier and network information lookup"
          operations:
            - method: GET
              name: lookup-carrier
              description: "Look up carrier information for a phone number"
              call: "telefono.lookup-carrier"
              with:
                number: "rest.number"
                hlr: "rest.hlr"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/format
          name: format
          description: "Phone number format conversion"
          operations:
            - method: GET
              name: format-number
              description: "Format a phone number into multiple standard formats"
              call: "telefono.format-phone-number"
              with:
                number: "rest.number"
                country_code: "rest.country_code"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: phone-intelligence-mcp
      transport: http
      description: "MCP server for AI-assisted phone number intelligence, validation, and data enrichment."
      tools:
        - name: validate-phone-number
          description: "Validate a phone number and check if it is valid, reachable, mobile/landline/VoIP, and get the carrier and country"
          hints:
            readOnly: true
            openWorld: true
          call: "telefono.validate-phone-number"
          with:
            number: "tools.number"
            country_code: "tools.country_code"
          outputParameters:
            - type: object
              mapping: "$."

        - name: batch-validate-numbers
          description: "Validate a list of up to 100 phone numbers in a single batch request"
          hints:
            readOnly: true
            openWorld: true
          call: "telefono.validate-phone-number-batch"
          with:
            numbers: "tools.numbers"
          outputParameters:
            - type: object
              mapping: "$."

        - name: lookup-carrier
          description: "Look up the mobile carrier, network type (GSM/LTE/5G), MCC, MNC, and portability status for a phone number"
          hints:
            readOnly: true
            openWorld: true
          call: "telefono.lookup-carrier"
          with:
            number: "tools.number"
            hlr: "tools.hlr"
          outputParameters:
            - type: object
              mapping: "$."

        - name: format-number
          description: "Parse and reformat a phone number into E.164, national, international, and RFC3966 formats"
          hints:
            readOnly: true
            openWorld: false
          call: "telefono.format-phone-number"
          with:
            number: "tools.number"
            country_code: "tools.country_code"
          outputParameters:
            - type: object
              mapping: "$."