[bug]: Google Contacts Caller ID lookup fails for US numbers in E.164 format

[sbenlevy]

FreePBX Version

FreePBX 17

Issue Description

Google Contacts Caller ID lookup via Superfecta fails when the incoming caller number is provided in E.164 format (e.g. +15161234567).

The Google People API endpoint people:searchContacts does not consistently return results when queried with E.164 numbers, even when the contact exists and the canonicalForm matches. However, the same contact is returned when the query is formatted using NANP notation (e.g. (516) 123-4567).

This results in Google Contacts Caller ID not working for US numbers in real-world FreePBX deployments, where inbound numbers are typically normalized to E.164 by the PBX.

Testing confirms:

• Querying Google Contacts with +1XXXXXXXXXX returns no results
• Querying the same number in NANP format (XXX) XXX-XXXX returns correct matches

This issue affects Superfecta Google Contacts lookups and prevents caller ID resolution for US numbers.

A minimal, backward-compatible fix is to attempt a NANP-formatted lookup first for US numbers (10-digit or 11-digit starting with 1), before falling back to the existing E.164 / prefix logic.

Operating Environment

FreePBX Framework: 17.x
Asterisk: 21.4.1
Superfecta module: current git version
Google Contacts integration using People API (people.googleapis.com)

Inbound numbers normalized to E.164 (+1XXXXXXXXXX)
Google Contacts contain phone numbers in canonicalForm and formatted NANP values

Relevant log output

Normalized query number (E.164): +15161234567
URL: https://people.googleapis.com/v1/people:searchContacts?readMask=names,nicknames,organizations,phoneNumbers&access_token=ya29.a0Aa7pCA8ffP0swcqDz5hscmItklyOTiqMuWLf5St6rIZHz-9HKPa5eRmlWMBOlUGcP5tAzF61avQh356STYdXKLm5YdlLQZ4u8ZMF5gqq8K_-OTfAmnxx1xTqQ0rEFJBZje5pAuLEyJhB-zrZREhxtnDOZyyV-wjUSe_WrQV016aVWm0by1LnT7Gw0dcEY84FbiuRV_trlAaCgYKAagSARQSFQHGX2MiYMbdCB__JRGb0FpOHGWHrw0209&query=%2B15161234567
cURL HTTP Code: 200
Raw API result:
[]

No results with E.164, retrying with NANP format
URL: https://people.googleapis.com/v1/people:searchContacts?readMask=names,nicknames,organizations,phoneNumbers&access_token=ya29.a0Aa7pCA8ffP0swcqDz5hscmItklyOTiqMuWLf5St6rIZHz-9HKPa5eRmlWMBOlUGcP5tAzF61avQh356STYdXKLm5YdlLQZ4u8ZMF5gqq8K_-OTfAmnxx1xTqQ0rEFJBZje5pAuLEyJhB-zrZREhxtnDOZyyV-wjUSe_WrQV016aVWm0by1LnT7Gw0dcEY84FbiuRV_trlAaCgYKAagSARQSFQHGX2MiYMbdCB__JRGb0FpOHGWHrw0209&query=%28516%29+123-4567
cURL HTTP Code: 200
Raw API result:
{
  "results": [
    {
      "person": {
        "resourceName": "people/c3058638428797574698",
        "etag": "%EgkBAgoLDC43PT8aAQIiDHY3QnFEOHVubEM0PQ==",
        "names": [
          {
            "metadata": {
              "primary": true,
              "source": {
                "type": "CONTACT",
                "id": "2a72777214d69e2a"
              },
              "sourcePrimary": true
            },
            "displayName": "Test Contact",
            "familyName": "Contact",
            "givenName": "Test",
            "displayNameLastFirst": "Contact, Test",
            "unstructuredName": "Test Contact"
          }
        ],
        "phoneNumbers": [
          {
            "metadata": {
              "primary": true,
              "source": {
                "type": "CONTACT",
                "id": "2a72777214d69e2a"
              }
            },
            "value": "(516) 123-4567",
            "type": "work",
            "formattedType": "Work"
          }
        ]
      }
    }
  ]
}