Metadata-Version: 2.4
Name: wede-sdk
Version: 2.0.0
Summary: Official Python client for the wede API
License-Expression: MIT
Project-URL: Documentation, https://docs.wede.pt
Project-URL: Source, https://github.com/Wedeadmin/wedetech-sdk-python
Keywords: wede,operational-continuity,offline-first,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# wede-sdk

Official Python client for the wede API.

wede keeps critical operations running whatever the state of the network. Operations captured without connectivity are synchronised when it returns, and each one is stored exactly once.

Full documentation: [docs.wede.pt](https://docs.wede.pt)

## Requirements

Python 3.8 or later. No dependencies.

## Installation

```bash
pip install wede-sdk
```

## Credentials

**On a server**, use the tenant API key (`wede_live_...` or `wede_test_...`) and keep it as a secret.

```python
import os
from wede import WedeClient

wede = WedeClient(api_key=os.environ["WEDE_API_KEY"])
```

**On a device**, sign the user in and use the session token. What the token can do depends on the user's role in your tenant.

```python
session = WedeClient.login(email, password)
wede = WedeClient(access_token=session["token"])
```

The token expires after 8 hours. Sign in again and call `wede.set_access_token(new_token)`. Five failed sign-in attempts lock the account for 15 minutes.

| Argument | Default | Description |
| --- | --- | --- |
| `api_key` | | Tenant API key, server side only |
| `access_token` | | User session token |
| `base_url` | `https://api.wede.pt` | API base URL |
| `timeout` | `10.0` | Request timeout in seconds |
| `retries` | `3` | Attempts on network failure |

## Send an event

```python
res = wede.send_event(
    type="cardiac_arrest",
    vertical="healthcare",
    priority="high",
    payload={"patient_ref": "P-1042"},
    metadata={"zone_id": "LIS-01"},
)
res["event_id"]
```

`type` is an event type of your catalog for this vertical, or an event category (see below). `priority` is `low`, `normal`, `high` or `critical`. The same `idempotency_key` twice returns `409 duplicate_event`, so retries are always safe.

## Event types and categories

Event types are yours. You create them in your catalog, per vertical, and link each one to a category:

```python
wede.create_catalog_action("healthcare", "cardiac_arrest", "Cardiac arrest", category="EMERGENCY")
```

Categories are a shared list kept by wede (`list_event_categories()`), for example `EMERGENCY`, `PAYMENT`, `BOOKING`, `STATUS_UPDATE`, `IDENTITY_CONFIRM`, `DISPATCH` and `OTHER`. The list stays open and grows over time. Using them is optional: an event can use a category code directly as its `type`.

An event's `type` is accepted when it is an active type of your catalog for the event's vertical, or an active category. Anything else returns `422 unknown_event_type`.

## Operations captured without connectivity

```python
from wede import capture_event

captured = capture_event("delivery_confirmed", "logistics", "normal", {"parcel": "PX-2231"})
# store `captured` locally, unchanged

result = wede.sync_batch(queued_events)
result["summary"]   # {"total", "accepted", "duplicates", "rejected"}
result["results"]   # one entry per event
```

- Up to 500 events per call.
- `capture_event` adds the capture time and an integrity checksum. An event whose content changes after capture is rejected.
- `duplicates` is your proof against double counting: an operation that already reached wede is stored only once.
- Payloads can contain `dict`, `list`, `str`, `int`, `float`, `bool` and `None`. The SDK serialises them exactly as wede checks them.

## Errors

| Class | When |
| --- | --- |
| `WedeAuthError` | Missing or invalid credentials (`401`) |
| `WedeError` | The API answered with an error. `status`, `code` and `details` carry the reason |
| `WedeNetworkError` | No response after all retries |

Common codes: `duplicate_event` (409), `unknown_event_type` (422), `unknown_vertical` (422), `invalid_payload` (422), `forbidden` (403).

## Method reference

| Area | Methods |
| --- | --- |
| Sign in | `WedeClient.login`, `set_access_token` |
| Events | `send_event`, `list_events`, `get_event` |
| Event types | `list_event_categories`, `list_catalog_actions`, `create_catalog_action`, `update_catalog_action`, `delete_catalog_action` |
| Offline sync | `capture_event`, `sync_batch`, `get_sync_status`, `register_device`, `sync_device_queue` |
| Connectivity | `get_connectivity_status`, `report_connectivity`, `list_zones`, `get_zone` |
| Tenant | `get_tenant_info`, `get_usage`, `get_billing`, `update_dispatch_settings` |
| Teams and dispatch | `list_teams`, `get_team`, `update_member_location`, `score_teams`, `dispatch`, `dispatch_action` |
| Missions | `list_missions`, `list_my_missions`, `get_mission`, `update_mission_status` |
| Parsers | `list_parsers`, `get_parser`, `get_active_parser` |
| Webhooks | `list_webhooks`, `create_webhook`, `delete_webhook` |

What each credential can call depends on its role in your tenant. A call outside it returns `403`.

## License

MIT
