Metadata-Version: 2.5
Name: noxhere
Version: 0.2.6
Summary: Unified Python SDK for every NoxHere resource
Project-URL: Homepage, https://app.noxhere.com
Project-URL: Repository, https://github.com/No-Box-Dev/NoxHere
Author: No Box Dev
License: PolyForm-Noncommercial-1.0.0
Keywords: activity,feedback,incidents,noxhere,planning,stats
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: typing-extensions>=4.12
Description-Content-Type: text/markdown

# `noxhere`

The unified Python client for every NoxHere resource. Its complete operation
catalog is generated from the same OpenAPI contract as `@noxhere/sdk`.

Install the official distribution from [PyPI](https://pypi.org/project/noxhere/):

```bash
python -m pip install --upgrade noxhere
```

```python
from noxhere import NoxHereClient

nox = NoxHereClient(token="nox_sk_...")
services = nox.workspace.list_nox_services()
```

The SDK is optional. The equivalent operation can always be called directly:

```python
import os
import requests

response = requests.get(
    "https://app.noxhere.com/api/v1/services",
    headers={"Authorization": f"Bearer {os.environ['NOXHERE_API_TOKEN']}"},
    timeout=10,
)
response.raise_for_status()
services = response.json()
```

See the repository's [direct HTTP guide](../../public/docs/direct-api.md) and the
OpenAPI-generated operation examples in the developer reference.

Every path, query, body, and response model is generated from NoxHere's
OpenAPI contract and is available through `noxhere.models`. Async applications
use the same generated resources:

```python
from noxhere import AsyncNoxHereClient

nox = AsyncNoxHereClient(token="nox_sk_...")
page = await nox.activity.get_activity(query={"limit": 25})
```

Namespaces are `workspace`, `activity`, `planning`, `feedback`, `stats`, and
`incidents`. These unified namespaces are the only supported resource names.
Use `noxhere.stats.create_stats_client`, `noxhere.incidents.create_incident_client`, or
`noxhere.feedback.create_feedback_client` for focused clients.

Server telemetry is available from the same distribution:

```python
import os

from noxhere.telemetry import create_telemetry

with create_telemetry() as telemetry:
    telemetry.user.registered("user-42")
    telemetry.events.record_parsed("user-42", "record-7")
```

`create_telemetry()` reads `NOXHERE_API_TOKEN` (preferred) or the legacy
`NOXHERE_INGEST_KEY`, plus `NOXHERE_SOURCE_ID`, `NOXHERE_IDENTITY_HASH_KEY`,
`NOXHERE_IDENTITY_KEY_ID`, `NOXHERE_ENVIRONMENT`, and `NOXHERE_RELEASE`.
`track()` queues delivery and returns immediately; process shutdown or leaving
the context flushes the queue. Delivery failures are returned or retained for
`flush()` and never raised into the host application. Set
`NOXHERE_TELEMETRY_MODE=memory` in tests, then inspect
`telemetry.captured_events` without making network calls. Identifiers are
HMAC-SHA256 protected before JSON serialization and
the original value is never transmitted. Keep the identity key stable—changing
it resets user continuity. Compatibility helpers such as `user.registered()`
and `activity()` delegate to the same contract. The typed `events` helpers keep
built-in event names out of application strings while event timing remains an
explicit decision at the call site.

`telemetry` remains available as a deprecated forwarding package for existing
applications; new code should import `noxhere.telemetry`.

`noxhere.events.create_platform_event` builds the same common event envelope
as the TypeScript SDK. Versions, size limits, privacy keys, and the registered
event-type catalog are generated from the canonical platform event contract,
so contract changes make the SDK drift check fail until both languages are
regenerated.
