Metadata-Version: 2.4
Name: pulsegrid
Version: 0.2.0
Summary: Official Python SDK for AltraNC Connect / PulseGrid realtime messaging, presence, push and webhooks
Author: ALTRANC HOLDINGS (Pty) Ltd
License-Expression: MIT
Project-URL: Homepage, https://www.altrancconnect.com/
Project-URL: Documentation, https://www.altrancconnect.com/docs/
Keywords: pulsegrid,altranc-connect,realtime,websocket,webhooks,push-notifications,presence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: websocket-client<2,>=1.7
Dynamic: license-file

# PulseGrid Python SDK 0.2.0

Official Python SDK for **AltraNC Connect / PulseGrid**.

## Install

```bash
pip install pulsegrid
```

## Fastest setup

```bash
export PULSEGRID_PUBLIC_KEY=pk_...
export PULSEGRID_SECRET_KEY=sk_...
```

```python
from pulsegrid import PulseGrid

pg = PulseGrid()
pg.channel("orders").publish("Order ready")
```

The SDK defaults to `https://www.altrancconnect.com` and can infer the project ID from the API key.

## Client token

```python
token = pg.tokens.create(
    identifier_id="user_123",
    allowed_channels=["orders"],
)
```

## Realtime

```python
connection = pg.channel("orders").connect(
    client_token=token,
    on_message=lambda payload: print(payload),
)
connection.send("Hello")
```

Realtime supports reconnect, exponential backoff, heartbeat and an outgoing queue.

## History / presence

```python
events = pg.channel("orders").events(limit=50)
online = pg.channel("orders").online_count()
```

## Push

```python
pg.push.send_to_topic(
    "news",
    title="New update",
    body="Something changed",
)
```

Push sends use an idempotency key automatically.

> Current production API targeting by user uses the internal PulseGrid `AppUser` UUID. `send_to_user()` is preserved and is equivalent to `send_to_app_user_id()`.

## Webhooks

```python
from pulsegrid import construct_webhook_event

event = construct_webhook_event(
    secret=WEBHOOK_SECRET,
    headers=request.headers,
    body=request.body,
)
```

Always pass the raw body.

## Doctor

```bash
pulsegrid doctor
```
