pyhubblenetwork 0.0.2__tar.gz → 0.0.3__tar.gz

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyhubblenetwork
-Version: 0.0.2
+Version: 0.0.3
 Summary: Hubble SDK host-side tools
 Author-email: Paul Buckley <paul@hubble.com>
 License-Expression: Apache-2.0

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyhubblenetwork"
-version = "0.0.2"
+version = "0.0.3"
 requires-python = ">=3.9"
 authors = [
   { name="Paul Buckley", email="paul@hubble.com" },

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/src/hubblenetwork/__init__.py

@@ -11,6 +11,8 @@ from .packets import Location, EncryptedPacket, DecryptedPacket
 from .device import Device
 from .org import Organization
 from .crypto import decrypt
+from .errors import InvalidCredentialsError
+from .cloud import Credentials, Environment
 
 __all__ = [
     "ble",
@@ -21,4 +23,7 @@ __all__ = [
     "DecryptedPacket",
     "Device",
     "Organization",
+    "Credentials",
+    "Environment",
+    "InvalidCredentialsError",
 ]

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/src/hubblenetwork/cli.py

@@ -13,6 +13,8 @@ from hubblenetwork import Organization
 from hubblenetwork import Device, DecryptedPacket, EncryptedPacket
 from hubblenetwork import ble as ble_mod
 from hubblenetwork import decrypt
+from hubblenetwork import cloud
+from hubblenetwork import InvalidCredentialsError
 
 
 def _get_env_or_fail(name: str) -> str:
@@ -122,6 +124,36 @@ def cli() -> None:
     # top-level group; subcommands are added below
 
 
+@cli.command("validate-credentials")
+@click.option(
+    "--org-id",
+    "-o",
+    type=str,
+    envvar="HUBBLE_ORG_ID",
+    default=None,
+    show_default=False,
+    help="Organization ID (if not using HUBBLE_ORG_ID env var)",
+)
+@click.option(
+    "--token",
+    "-t",
+    type=str,
+    envvar="HUBBLE_API_TOKEN",
+    default=None,
+    show_default=False,
+    help="Token (if not using HUBBLE_API_TOKEN env var)",
+)
+def validate_credentials(org_id, token) -> None:
+    """Validate the given credentials"""
+    # subgroup for organization-related commands
+    credentials = cloud.Credentials(org_id, token)
+    env = cloud.get_env_from_credentials(credentials)
+    if env:
+        click.echo(f'Valid credentials (env="{env.name}")')
+    else:
+        click.secho(f"Invalid credentials!", fg="red", err=True)
+
+
 @cli.group()
 def ble() -> None:
     """BLE utilities."""
@@ -182,8 +214,10 @@ def ble_scan(timeout, ingest: bool = False, key: str = None) -> None:
     if ingest:
         click.echo("[INFO] Ingesting packet(s) into the backend... ", nl=False)
         org = Organization(
-            org_id=_get_env_or_fail("HUBBLE_ORG_ID"),
-            api_token=_get_env_or_fail("HUBBLE_API_TOKEN"),
+            cloud.Credentials(
+                org_id=_get_env_or_fail("HUBBLE_ORG_ID"),
+                api_token=_get_env_or_fail("HUBBLE_API_TOKEN"),
+            )
         )
         for pkt in pkts:
             org.ingest_packet(pkt)
@@ -212,21 +246,14 @@ pass_orgcfg = click.make_pass_decorator(Organization, ensure=True)
     show_default=False,
     help="Token (if not using HUBBLE_API_TOKEN env var)",
 )
-@click.option(
-    "--url",
-    "-u",
-    type=str,
-    envvar="HUBBLE_BASE_URL",
-    default=None,
-    show_default=False,
-    help="Base URL to override production (if not using HUBBLE_BASE_URL env var)",
-)
 @click.pass_context
-def org(ctx, org_id, token, url) -> None:
+def org(ctx, org_id, token) -> None:
     """Organization utilities."""
     # subgroup for organization-related commands
-    ctx.obj = Organization(org_id=org_id, api_token=token)
-    ctx.obj.base_url = url
+    try:
+        ctx.obj = Organization(cloud.Credentials(org_id=org_id, api_token=token))
+    except InvalidCredentialsError as e:
+        raise click.BadParameter(str(e))
 
 
 @org.command("info")

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/src/hubblenetwork/cloud.py

@@ -1,5 +1,6 @@
 # hubble/cloud_api.py
 from __future__ import annotations
+from dataclasses import dataclass
 import httpx
 import time
 import base64
@@ -13,11 +14,23 @@ from .errors import (
     raise_for_response,
 )
 
-ENVIRONMENTS = {
-    "PROD": "https://api.hubble.com",
-    "TESTING": "https://api-testing.hubblenetwork.io",
-}
-default_env_url = None
+
+@dataclass(frozen=True)
+class Environment:
+    name: str
+    url: str
+
+
+@dataclass(frozen=True)
+class Credentials:
+    org_id: str
+    api_token: str
+
+
+_ENVIRONMENTS = [
+    Environment("PROD", "https://api.hubble.com"),
+    Environment("TESTING", "https://api-testing.hubblenetwork.io"),
+]
 
 
 def _auth_headers(api_token: str) -> dict[str, str]:
@@ -28,69 +41,64 @@ def _auth_headers(api_token: str) -> dict[str, str]:
     }
 
 
-def _list_devices_endpoint(org_id: str) -> str:
-    return f"/org/{org_id}/devices"
+def _list_devices_endpoint(credentials: Credentials) -> str:
+    return f"/org/{credentials.org_id}/devices"
 
 
-def _register_device_endpoint(org_id: str) -> str:
-    return f"/v2/org/{org_id}/devices"
+def _register_device_endpoint(credentials: Credentials) -> str:
+    return f"/v2/org/{credentials.org_id}/devices"
 
 
-def _retrieve_org_packets_endpoint(org_id: str) -> str:
-    return f"/org/{org_id}/packets"
+def _retrieve_org_packets_endpoint(credentials: Credentials) -> str:
+    return f"/org/{credentials.org_id}/packets"
 
 
-def _ingest_packets_endpoint(org_id: str) -> str:
-    return f"/org/{org_id}/packets"
+def _ingest_packets_endpoint(credentials: Credentials) -> str:
+    return f"/org/{credentials.org_id}/packets"
 
 
-def _update_device_endpoint(org_id: str, device_id: str) -> str:
-    return f"/org/{org_id}/devices/{device_id}"
+def _update_device_endpoint(credentials: Credentials, device_id: str) -> str:
+    return f"/org/{credentials.org_id}/devices/{device_id}"
 
 
-def _retrive_org_metadata_endpoint(org_id: str) -> str:
-    return f"/org/{org_id}"
+def _retrieve_org_metadata_endpoint(credentials: Credentials) -> str:
+    return f"/org/{credentials.org_id}"
 
 
-def set_env(env: str) -> None:
-    default_env_url = env
+def _validate_key_endpoint(credentials: Credentials) -> str:
+    return f"/org/{credentials.org_id}/check"
 
 
 def cloud_request(
+    *,
     method: str,
     path: str,
-    *,
-    api_token: Optional[str] = None,
+    env: Environment,
+    credentials: Optional[credentials] = None,
     json: Any = None,
     timeout_s: float = 10.0,
     params: Optional[MutableMapping[str, Any]] = None,
-    base_url: Optional[str] = None,
 ) -> Any:
     """
     Make a single HTTP request to the Hubble Cloud API and return parsed JSON.
 
     - `method`: "GET", "POST", etc.
     - `path`: endpoint path (e.g., "/devices" or "orgs/{id}/devices")
-    - `api_token`: API token for auth (optional, but recommended)
-    - `org_id`: if provided, will be added as query param `orgId=<org_id>`
-               (skip or embed in `path` if your endpoint uses a path param instead)
+    - `credentials`: Credentials to use for this call
+    - `env`: Environment to call into (typically prod or testing)
     - `json`: request JSON body (for POST/PUT/PATCH)
     - `timeout_s`: request timeout in seconds
     - `params`: optional HTTP request parameters
-    - `base_url`: URL to use in place of default production URL
     """
-    path = path.lstrip("/")
-    base_url = base_url if base_url is not None else default_env_url
-    base_url = base_url.rstrip("/")
-    url = f"{base_url}/api/{path}"
+    url = f"{env.url.rstrip('/')}/api/{path.lstrip('/')}"
 
     # headers
     headers: MutableMapping[str, str] = {
         "Accept": "application/json",
         "Content-Type": "application/json",
     }
-    if api_token:
-        headers["Authorization"] = f"Bearer {api_token}"
+    if credentials:
+        headers["Authorization"] = f"Bearer {credentials.api_token}"
 
     try:
         with httpx.Client(timeout=timeout_s) as client:
@@ -118,11 +126,25 @@ def cloud_request(
         raise BackendError(f"Non-JSON response from {url}") from e
 
 
+def get_env_from_credentials(credentials: Credentials) -> Optional[Environment]:
+    for env in _ENVIRONMENTS:
+        try:
+            resp = cloud_request(
+                method="GET",
+                path=_validate_key_endpoint(credentials),
+                credentials=credentials,
+                env=env,
+            )
+            return env
+        except:
+            pass
+    return None
+
+
 def register_device(
     *,
-    org_id: str,
-    api_token: str,
-    base_url: Optional[str] = None,
+    credentials: Credentials,
+    env: Environment,
 ) -> Any:
     """Create a new device and return it."""
     data = {
@@ -131,18 +153,17 @@ def register_device(
     }
     return cloud_request(
         method="POST",
-        path=_register_device_endpoint(org_id),
-        api_token=api_token,
+        env=env,
+        path=_register_device_endpoint(credentials),
+        credentials=credentials,
         json=data,
-        base_url=base_url,
     )
 
 
 def update_device(
     *,
-    org_id: str,
-    api_token: str,
-    base_url: Optional[str] = None,
+    credentials: Credentials,
+    env: Environment,
     name: str,
     device_id: str,
 ) -> Any:
@@ -153,15 +174,17 @@ def update_device(
     }
     return cloud_request(
         method="PATCH",
-        path=_update_device_endpoint(org_id, device_id),
-        api_token=api_token,
+        env=env,
+        path=_update_device_endpoint(credentials, device_id),
+        credentials=credentials,
         json=data,
-        base_url=base_url,
     )
 
 
 def list_devices(
-    *, org_id: str, api_token: str, base_url: Optional[str] = None
+    *,
+    credentials: Credentials,
+    env: Environment,
 ) -> list[Any]:
     """
     List devices for the org (keys typically omitted).
@@ -172,19 +195,18 @@ def list_devices(
     """
     return cloud_request(
         method="GET",
-        path=_list_devices_endpoint(org_id),
-        api_token=api_token,
-        base_url=base_url,
+        env=env,
+        path=_list_devices_endpoint(credentials),
+        credentials=credentials,
     )
 
 
 def retrieve_packets(
     *,
-    org_id: str,
-    api_token: str,
-    device_id: Optional[str] = None,
+    credentials: Credentials,
+    env: Environment,
+    device_id: str,
     days: int = 7,
-    base_url: Optional[str] = None,
 ) -> Any:
     """Fetch decrypted packets for a device."""
     params = {"start": (int(time.time()) - (days * 24 * 60 * 60))}
@@ -192,19 +214,18 @@ def retrieve_packets(
         params["device_id"] = device_id
     return cloud_request(
         method="GET",
-        path=_retrieve_org_packets_endpoint(org_id),
-        api_token=api_token,
+        env=env,
+        path=_retrieve_org_packets_endpoint(credentials),
+        credentials=credentials,
         params=params,
-        base_url=base_url,
     )
 
 
 def ingest_packet(
     *,
-    org_id: str,
-    api_token: str,
+    credentials: Credentials,
+    env: Environment,
     packet: EncryptedPacket,
-    base_url: Optional[str] = None,
 ) -> Any:
     body = {
         "ble_locations": [
@@ -229,18 +250,17 @@ def ingest_packet(
     }
     return cloud_request(
         method="POST",
-        path=_ingest_packets_endpoint(org_id),
-        api_token=api_token,
+        env=env,
+        path=_ingest_packets_endpoint(credentials),
+        credentials=credentials,
         json=body,
-        base_url=base_url,
     )
 
 
 def retrieve_org_metadata(
     *,
-    org_id: str,
-    api_token: str,
-    base_url: Optional[str] = None,
+    credentials: Credentials,
+    env: Environment,
 ) -> Any:
     """
     Get organizational metadata
@@ -251,7 +271,7 @@ def retrieve_org_metadata(
     """
     return cloud_request(
         method="GET",
-        path=_retrive_org_metadata_endpoint(org_id),
-        api_token=api_token,
-        base_url=base_url,
+        env=env,
+        path=_retrieve_org_metadata_endpoint(credentials),
+        credentials=credentials,
     )

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/src/hubblenetwork/errors.py

@@ -40,6 +40,10 @@ class APITimeout(BackendError):
     """The API call exceeded its allowed timeout."""
 
 
+class InvalidCredentialsError(BackendError):
+    """Invalid credentials passed in"""
+
+
 # Request/response semantics
 class ValidationError(BackendError):
     """The request was invalid (schema/semantics)."""

{pyhubblenetwork-0.0.2 → pyhubblenetwork-0.0.3}/src/hubblenetwork/org.py

@@ -6,7 +6,7 @@ from typing import Optional, List
 from . import cloud
 from .packets import DecryptedPacket, Location
 from .device import Device
-from .errors import BackendError
+from .errors import BackendError, InvalidCredentialsError
 
 
 class Organization:
@@ -15,43 +15,26 @@ class Organization:
     Used to manage devices and fetch decrypted packets from the backend.
     """
 
-    org_id: str
-    api_token: str
-
-    api_base_url: str
-    env: str
     name: str
 
-    def __init__(self, org_id: str, api_token: str) -> str:
-        self.org_id = org_id
-        self.api_token = api_token
+    credentials: cloud.Credentials
+    env: cloud.Environment
 
-        # Attempt to resolve environment (testing or prod)
-        resp = None
-        for env, url in cloud.ENVIRONMENTS.items():
-            try:
-                resp = cloud.retrieve_org_metadata(
-                    org_id=self.org_id, api_token=self.api_token, base_url=url
-                )
-                self.api_base_url = url
-                self.env = env
-                break
-            except:
-                pass
-        if not resp:
-            raise BackendError(f"Unable to determine environment")
-        self.name = resp["name"]
+    def __init__(self, credentials: cloud.Credentials) -> str:
+        self.credentials = credentials
+        self.env = cloud.get_env_from_credentials(self.credentials)
+        if not self.env:
+            raise InvalidCredentialsError("Invalid credentials passed in.")
+        self.name = cloud.retrieve_org_metadata(
+            credentials=self.credentials, env=self.env
+        )["name"]
 
     def register_device(self) -> Device:
         """
         Register a new device in this organization and return it.
         Returned Device will have an ID and provisioned key.
         """
-        resp = cloud.register_device(
-            org_id=self.org_id,
-            api_token=self.api_token,
-            base_url=self.api_base_url,
-        )
+        resp = cloud.register_device(credentials=self.credentials, env=self.env)
         # Currently, only registering a single device and taking the
         # first in the returned list
         device = resp["devices"][0]
@@ -63,11 +46,10 @@ class Organization:
         Returned Device will have an ID and provisioned key.
         """
         resp = cloud.update_device(
-            org_id=self.org_id,
-            api_token=self.api_token,
+            credentials=self.credentials,
+            env=self.env,
             name=name,
             device_id=device_id,
-            base_url=self.api_base_url,
         )
         return Device(id=resp["id"], name=resp["name"])
 
@@ -79,9 +61,7 @@ class Organization:
             list[Device]
         """
 
-        payload = cloud.list_devices(
-            org_id=self.org_id, api_token=self.api_token, base_url=self.api_base_url
-        )
+        payload = cloud.list_devices(credentials=self.credentials, env=self.env)
         raw_list = payload["devices"]
 
         # Turn each JSON object into a Device
@@ -96,11 +76,10 @@ class Organization:
         or None if none exists.
         """
         resp = cloud.retrieve_packets(
-            org_id=self.org_id,
-            api_token=self.api_token,
+            credentials=self.credentials,
+            env=self.env,
             device_id=device.id,
             days=days,
-            base_url=self.api_base_url,
         )
         packets = []
         for packet in resp["packets"]:
@@ -126,8 +105,7 @@ class Organization:
 
     def ingest_packet(self, packet: EncryptedPacket) -> None:
         cloud.ingest_packet(
-            org_id=self.org_id,
-            api_token=self.api_token,
+            credentials=self.credentials,
+            env=self.env,
             packet=packet,
-            base_url=self.api_base_url,
         )