aiogotoconnect 0.2.0__tar.gz

aiogotoconnect-0.2.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Oneofthegeeks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

aiogotoconnect-0.2.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: aiogotoconnect
+Version: 0.2.0
+Summary: Async Python client for GoTo Connect: SMS via Messaging v2, outbound TTS voice calls via SIP
+License: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: audioop-lts>=0.2; python_version >= "3.13"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-aiohttp; extra == "dev"
+Dynamic: license-file
+
+# aiogotoconnect
+
+Async Python client for GoTo Connect: send SMS via the Messaging v2 API and place outbound text-to-speech voice calls over SIP. Pure Python, asyncio only.
+
+Used by [ha-goto](https://github.com/oneofthegeeks/ha-goto), the Home Assistant integration.
+
+Formerly published as `gotoconnect` (v0.1.0); renamed so the unofficial client does not carry the bare product name. The old PyPI name stays claimed but dormant.
+
+## Install
+
+```bash
+pip install aiogotoconnect
+```
+
+Python 3.12+.
+
+## SMS
+
+```python
+import asyncio
+from aiogotoconnect import GoToOAuth, GoToMessaging
+
+async def main():
+    auth = GoToOAuth(client_id="...", client_secret="...", refresh_token="...")
+    sms = GoToMessaging(auth.async_get_access_token)
+    await sms.async_send_sms("+15551230000", ["+15551234567"], "Hello from aiogotoconnect")
+    # GoTo may rotate the refresh token: persist auth.refresh_token after calls.
+
+asyncio.run(main())
+```
+
+`GoToMessaging` takes any async callable returning a bearer token, so a host app (e.g. Home Assistant) can supply its own.
+
+## Voice calls
+
+```python
+import asyncio
+from aiogotoconnect import GoToVoice
+
+async def main():
+    voice = GoToVoice("sip-username", "sip-password")  # server="reg.jiveip.net"
+    with open("message.wav", "rb") as f:  # 16-bit PCM WAV
+        result = await voice.call_and_play("+15551234567", f.read(), ring_timeout=25, repeat=1)
+    print(result)  # CallResult(answered=True, duration=4.2, reason='completed')
+
+asyncio.run(main())
+```
+
+`reason` is one of `completed`, `remote-hangup`, `no-answer`, `busy`, `rejected`. `bye_confirmed` is `False` only when we hung up but the server never answered (or refused) our BYE, so the far side may still think the call is up; it is `True` when no BYE was needed or it was confirmed. Bad SIP credentials raise `GoToAuthError`.
+
+UDP requests are retransmitted (0.5 s, 1 s, 2 s, ...) until the server responds, and the Record-Route set from the answer is honoured on the ACK and BYE. Cancelling the `call_and_play` task hangs up (or CANCELs a ringing call) before the cancellation propagates.
+
+### Logging
+
+Everything logs to `logging.getLogger("aiogotoconnect.sip.call")` at DEBUG: SIP start-lines and status codes plus state changes, never headers or credentials. `examples/make_call.py --verbose` turns it on.
+
+## Exceptions
+
+All library errors derive from `GoToError`:
+
+- `GoToAuthError`: credentials rejected (OAuth refresh failed, SIP digest refused, SMS 401).
+- `GoToApiError`: a REST call returned a non-success status (`.status`).
+- `GoToSipError`: SIP registration/signalling failed, including network failures (timeouts, DNS, TLS errors are wrapped, never raised raw).
+  - `GoToCallError`: the call itself failed (e.g. 4xx/5xx to the INVITE, no usable SDP).
+
+Bad arguments raise plain `ValueError` before any network traffic: an invalid destination number, a WAV that is unreadable, empty or has more than two channels, or an unknown `codec`.
+
+### Create the SIP device in GoTo
+
+1. In GoTo Connect Admin, go to **Devices** -> **Add Device** -> **SIP Device**.
+2. Copy the **SIP Username**, **Password**, and the device's **SIP Server** and
+   **Outbound Proxy**. The registrar is typically `reg.jiveip.net` (the library's
+   default); the outbound proxy is account-specific (e.g.
+   `<account>.jive.rtcfront.net`) — pass it as `proxy=`. Calls proven live against
+   GoTo used both.
+
+### Transport
+
+UDP (port 5060) is the default. TLS (port 5061) is supported: `GoToVoice(..., transport="tls")`. TLS verifies the server certificate with the system CAs; pass `ssl_context=` to override. An outbound `proxy=` host, if set, is the connection target while `server` stays in the SIP URIs.
+
+### Live smoke test
+
+```bash
+GOTO_SIP_USERNAME=... GOTO_SIP_PASSWORD=... python examples/make_call.py --to +15551234567 --wav message.wav --transport tls
+```
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```

aiogotoconnect-0.2.0/README.md

@@ -0,0 +1,93 @@
+# aiogotoconnect
+
+Async Python client for GoTo Connect: send SMS via the Messaging v2 API and place outbound text-to-speech voice calls over SIP. Pure Python, asyncio only.
+
+Used by [ha-goto](https://github.com/oneofthegeeks/ha-goto), the Home Assistant integration.
+
+Formerly published as `gotoconnect` (v0.1.0); renamed so the unofficial client does not carry the bare product name. The old PyPI name stays claimed but dormant.
+
+## Install
+
+```bash
+pip install aiogotoconnect
+```
+
+Python 3.12+.
+
+## SMS
+
+```python
+import asyncio
+from aiogotoconnect import GoToOAuth, GoToMessaging
+
+async def main():
+    auth = GoToOAuth(client_id="...", client_secret="...", refresh_token="...")
+    sms = GoToMessaging(auth.async_get_access_token)
+    await sms.async_send_sms("+15551230000", ["+15551234567"], "Hello from aiogotoconnect")
+    # GoTo may rotate the refresh token: persist auth.refresh_token after calls.
+
+asyncio.run(main())
+```
+
+`GoToMessaging` takes any async callable returning a bearer token, so a host app (e.g. Home Assistant) can supply its own.
+
+## Voice calls
+
+```python
+import asyncio
+from aiogotoconnect import GoToVoice
+
+async def main():
+    voice = GoToVoice("sip-username", "sip-password")  # server="reg.jiveip.net"
+    with open("message.wav", "rb") as f:  # 16-bit PCM WAV
+        result = await voice.call_and_play("+15551234567", f.read(), ring_timeout=25, repeat=1)
+    print(result)  # CallResult(answered=True, duration=4.2, reason='completed')
+
+asyncio.run(main())
+```
+
+`reason` is one of `completed`, `remote-hangup`, `no-answer`, `busy`, `rejected`. `bye_confirmed` is `False` only when we hung up but the server never answered (or refused) our BYE, so the far side may still think the call is up; it is `True` when no BYE was needed or it was confirmed. Bad SIP credentials raise `GoToAuthError`.
+
+UDP requests are retransmitted (0.5 s, 1 s, 2 s, ...) until the server responds, and the Record-Route set from the answer is honoured on the ACK and BYE. Cancelling the `call_and_play` task hangs up (or CANCELs a ringing call) before the cancellation propagates.
+
+### Logging
+
+Everything logs to `logging.getLogger("aiogotoconnect.sip.call")` at DEBUG: SIP start-lines and status codes plus state changes, never headers or credentials. `examples/make_call.py --verbose` turns it on.
+
+## Exceptions
+
+All library errors derive from `GoToError`:
+
+- `GoToAuthError`: credentials rejected (OAuth refresh failed, SIP digest refused, SMS 401).
+- `GoToApiError`: a REST call returned a non-success status (`.status`).
+- `GoToSipError`: SIP registration/signalling failed, including network failures (timeouts, DNS, TLS errors are wrapped, never raised raw).
+  - `GoToCallError`: the call itself failed (e.g. 4xx/5xx to the INVITE, no usable SDP).
+
+Bad arguments raise plain `ValueError` before any network traffic: an invalid destination number, a WAV that is unreadable, empty or has more than two channels, or an unknown `codec`.
+
+### Create the SIP device in GoTo
+
+1. In GoTo Connect Admin, go to **Devices** -> **Add Device** -> **SIP Device**.
+2. Copy the **SIP Username**, **Password**, and the device's **SIP Server** and
+   **Outbound Proxy**. The registrar is typically `reg.jiveip.net` (the library's
+   default); the outbound proxy is account-specific (e.g.
+   `<account>.jive.rtcfront.net`) — pass it as `proxy=`. Calls proven live against
+   GoTo used both.
+
+### Transport
+
+UDP (port 5060) is the default. TLS (port 5061) is supported: `GoToVoice(..., transport="tls")`. TLS verifies the server certificate with the system CAs; pass `ssl_context=` to override. An outbound `proxy=` host, if set, is the connection target while `server` stays in the SIP URIs.
+
+### Live smoke test
+
+```bash
+GOTO_SIP_USERNAME=... GOTO_SIP_PASSWORD=... python examples/make_call.py --to +15551234567 --wav message.wav --transport tls
+```
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest
+```

aiogotoconnect-0.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aiogotoconnect"
+version = "0.2.0"
+description = "Async Python client for GoTo Connect: SMS via Messaging v2, outbound TTS voice calls via SIP"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.9",
+    "audioop-lts>=0.2; python_version >= '3.13'",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+    "pytest-asyncio",
+    "pytest-aiohttp",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aiogotoconnect = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

aiogotoconnect-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aiogotoconnect-0.2.0/src/aiogotoconnect/__init__.py

@@ -0,0 +1,23 @@
+from aiogotoconnect.auth import GoToOAuth, TokenProvider
+from aiogotoconnect.exceptions import (
+    GoToApiError,
+    GoToAuthError,
+    GoToCallError,
+    GoToError,
+    GoToSipError,
+)
+from aiogotoconnect.messaging import GoToMessaging
+from aiogotoconnect.sip.call import CallResult, GoToVoice
+
+__all__ = [
+    "CallResult",
+    "GoToApiError",
+    "GoToAuthError",
+    "GoToCallError",
+    "GoToError",
+    "GoToMessaging",
+    "GoToOAuth",
+    "GoToSipError",
+    "GoToVoice",
+    "TokenProvider",
+]

aiogotoconnect-0.2.0/src/aiogotoconnect/auth.py

@@ -0,0 +1,83 @@
+import asyncio
+import base64
+import time
+from collections.abc import Awaitable, Callable
+
+import aiohttp
+
+from aiogotoconnect.exceptions import GoToAuthError
+
+# Any async callable returning a bearer token. Home Assistant passes its own.
+TokenProvider = Callable[[], Awaitable[str]]
+
+DEFAULT_TOKEN_URL = "https://authentication.logmeininc.com/oauth/token"
+
+# Refresh this many seconds before expiry so a token never expires mid-request.
+REFRESH_MARGIN_SECONDS = 60
+
+
+class GoToOAuth:
+    """Standalone OAuth provider: refresh-token grant with cached access token."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        refresh_token: str,
+        token_url: str = DEFAULT_TOKEN_URL,
+        session: aiohttp.ClientSession | None = None,
+    ):
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self.refresh_token = refresh_token  # GoTo may rotate this on every refresh
+        self._token_url = token_url
+        self._session = session
+        self._access_token: str | None = None
+        self._expires_at = 0.0
+        self._refresh_lock = asyncio.Lock()
+
+    def _needs_refresh(self) -> bool:
+        expiring = time.monotonic() >= self._expires_at - REFRESH_MARGIN_SECONDS
+        return self._access_token is None or expiring
+
+    async def async_get_access_token(self) -> str:
+        if not self._needs_refresh():
+            return self._access_token
+        # Lock + re-check: concurrent callers wait, then reuse the token the first one fetched.
+        # Needed because a rotating refresh_token is single-use.
+        async with self._refresh_lock:
+            if self._needs_refresh():
+                await self._async_refresh()
+        return self._access_token
+
+    async def _async_refresh(self) -> None:
+        credentials = base64.b64encode(f"{self._client_id}:{self._client_secret}".encode()).decode()
+        headers = {"Authorization": f"Basic {credentials}"}
+        form = {"grant_type": "refresh_token", "refresh_token": self.refresh_token}
+
+        if self._session is None:
+            async with aiohttp.ClientSession() as session:
+                payload = await self._async_post_token(session, headers, form)
+        else:
+            payload = await self._async_post_token(self._session, headers, form)
+
+        # Error text is deliberately not included: it could echo a secret.
+        try:
+            access_token = payload["access_token"]
+            expires_in = float(payload["expires_in"])
+        except (KeyError, TypeError, ValueError) as error:
+            raise GoToAuthError("Token response missing access_token or expires_in") from error
+        self._access_token = access_token
+        self.refresh_token = payload.get("refresh_token", self.refresh_token)
+        self._expires_at = time.monotonic() + expires_in
+
+    async def _async_post_token(self, session, headers, form) -> dict:
+        try:
+            async with session.post(self._token_url, headers=headers, data=form) as response:
+                if response.status != 200:
+                    raise GoToAuthError(f"Token refresh failed with HTTP {response.status}")
+                return await response.json()
+        except (aiohttp.ClientError, asyncio.TimeoutError) as error:
+            raise GoToAuthError("Token refresh request failed") from error
+        except ValueError as error:  # JSONDecodeError (non-JSON body)
+            raise GoToAuthError("Token response was not valid JSON") from error

aiogotoconnect-0.2.0/src/aiogotoconnect/exceptions.py

@@ -0,0 +1,22 @@
+class GoToError(Exception):
+    """Base class for all aiogotoconnect errors."""
+
+
+class GoToAuthError(GoToError):
+    """Credentials were rejected: OAuth token refresh failed, SIP digest credentials refused, or SMS got a 401."""
+
+
+class GoToApiError(GoToError):
+    """A GoTo REST API call returned a non-success HTTP status."""
+
+    def __init__(self, message: str, status: int):
+        super().__init__(message)
+        self.status = status
+
+
+class GoToSipError(GoToError):
+    """SIP registration or signalling failed."""
+
+
+class GoToCallError(GoToSipError):
+    """An outbound call could not be completed."""

aiogotoconnect-0.2.0/src/aiogotoconnect/messaging.py

@@ -0,0 +1,51 @@
+import asyncio
+
+import aiohttp
+
+from aiogotoconnect.auth import TokenProvider
+from aiogotoconnect.exceptions import GoToApiError, GoToAuthError, GoToError
+
+
+class GoToMessaging:
+    """GoTo Messaging v2 client: send SMS from an owner number to contact numbers."""
+
+    def __init__(
+        self,
+        token_provider: TokenProvider,
+        session: aiohttp.ClientSession | None = None,
+        base_url: str = "https://api.goto.com",
+    ):
+        self._token_provider = token_provider
+        self._session = session
+        self._base_url = base_url
+
+    async def async_send_sms(self, owner_phone: str, contacts: list[str], body: str) -> dict:
+        # GoTo rejects owner == contact with a confusing error, so fail fast here.
+        if owner_phone in contacts:
+            raise ValueError("owner_phone must not also be a contact")
+
+        headers = {"Authorization": f"Bearer {await self._token_provider()}"}
+        payload = {"ownerPhoneNumber": owner_phone, "contactPhoneNumbers": contacts, "body": body}
+        url = f"{self._base_url}/messaging/v1/messages"
+
+        if self._session is None:
+            async with aiohttp.ClientSession() as session:
+                return await self._async_post(session, url, headers, payload)
+        return await self._async_post(self._session, url, headers, payload)
+
+    async def _async_post(self, session, url, headers, payload) -> dict:
+        try:
+            async with session.post(url, headers=headers, json=payload) as response:
+                if response.status == 401:
+                    raise GoToAuthError("SMS send rejected: access token not accepted")
+                # Error text is deliberately not included: it could echo phone numbers or tokens.
+                if response.status >= 400:
+                    raise GoToApiError(f"SMS send failed with HTTP {response.status}", response.status)
+                # Success with no usable body is still success: GoTo returns JSON, but don't rely on it.
+                try:
+                    parsed = await response.json(content_type=None)
+                except ValueError:  # JSONDecodeError: body was not JSON
+                    return {}
+                return {} if parsed is None else parsed  # aiohttp yields None for an empty body
+        except (aiohttp.ClientError, asyncio.TimeoutError) as error:
+            raise GoToError("SMS send request failed") from error

aiogotoconnect-0.2.0/src/aiogotoconnect/sip/audio.py

@@ -0,0 +1,50 @@
+"""WAV to raw G.711 conversion for the RTP sender.
+
+Input is any PCM WAV (Home Assistant TTS output). Output is headerless a-law
+(PCMA, payload type 8) or mu-law (PCMU) bytes at 8 kHz mono, one byte per sample.
+"""
+
+import io
+import warnings
+import wave
+
+# ponytail: audioop is deprecated on 3.12 (PEP 594) and removed on 3.13, where
+# the audioop-lts dependency provides the same module name. Silence only this
+# import-time DeprecationWarning, so the rest of the suite still fails on warnings.
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", DeprecationWarning)
+    import audioop
+
+TARGET_RATE = 8000
+CODECS = {"pcma": audioop.lin2alaw, "pcmu": audioop.lin2ulaw}
+
+
+def wav_to_g711(wav_bytes: bytes, codec: str = "pcma") -> bytes:
+    """Convert WAV bytes to 8 kHz mono G.711 (`pcma` or `pcmu`) payload bytes."""
+    encode = CODECS.get(codec)
+    if encode is None:
+        raise ValueError(f"unknown codec {codec!r}; expected 'pcma' or 'pcmu'")
+    try:
+        with wave.open(io.BytesIO(wav_bytes), "rb") as wf:
+            channels = wf.getnchannels()
+            width = wf.getsampwidth()
+            rate = wf.getframerate()
+            frames = wf.readframes(wf.getnframes())
+    except (wave.Error, EOFError) as exc:
+        raise ValueError(f"input is not a readable PCM WAV: {exc}") from exc
+
+    if not frames:
+        raise ValueError("WAV contains no audio frames")  # would otherwise 'play' a silent call
+    if channels > 2:
+        # ponytail: stereo downmix only, multichannel needs a per-channel mixer.
+        raise ValueError(f"unsupported channel count: {channels}")
+    if width == 1:
+        # WAV 8-bit PCM is unsigned; audioop expects signed samples.
+        frames = audioop.bias(frames, 1, 128)
+    if width != 2:
+        frames = audioop.lin2lin(frames, width, 2)
+    if channels == 2:
+        frames = audioop.tomono(frames, 2, 0.5, 0.5)
+    if rate != TARGET_RATE:
+        frames, _ = audioop.ratecv(frames, 2, 1, rate, TARGET_RATE, None)
+    return encode(frames, 2)