Metadata-Version: 2.4
Name: curnext
Version: 1.0.0
Summary: Official CurNext Python SDK for the construction readiness API
Project-URL: Homepage, https://curnext.app
Project-URL: Documentation, https://api.curnext.app/docs
Project-URL: Repository, https://github.com/awunjia/curnext-python
Project-URL: Issues, https://github.com/awunjia/CurNext/issues
Project-URL: API Docs, https://api.curnext.app/docs
Author-email: Awunjia Serge Atabong <info@curnext.app>, CurNext Oy <info@curnext.app>
Maintainer-email: CurNext Oy <info@curnext.app>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,bim,construction,curnext,iot,python,readiness,sdk,webhooks
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# curnext

[![PyPI version](https://img.shields.io/pypi/v/curnext.svg)](https://pypi.org/project/curnext/)
[![Python versions](https://img.shields.io/pypi/pyversions/curnext.svg)](https://pypi.org/project/curnext/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

**Official Python client** for the [CurNext](https://curnext.app) construction readiness API.

Use it from Django, FastAPI, or plain scripts to pull surface readiness, BIM context, devices, alerts, measurements, and webhook configuration into your own dashboards, ERP, CMMS, or automation pipelines - with API-key auth over HTTPS.

| | |
| --- | --- |
| **Package** | `curnext` |
| **Version** | `1.0.0` |
| **Runtime** | Python 3.9+ (stdlib only) |
| **API base** | `https://api.curnext.app` (`/api/v1`) |
| **OpenAPI** | [https://api.curnext.app/docs](https://api.curnext.app/docs) |
| **Platform** | [https://curnext.app](https://curnext.app) |

---

## Table of contents

- [Install](#install)
- [Quick start](#quick-start)
- [Authentication](#authentication)
- [Configuration](#configuration)
- [API surface](#api-surface)
- [Error handling](#error-handling)
- [Webhooks](#webhooks)
- [Local development & smoke test](#local-development--smoke-test)
- [Author & support](#author--support)
- [License](#license)

---

## Install

```bash
pip install curnext
```

```python
from curnext import CurNext, CurNextApiError
```

---

## Quick start

```python
import os
from curnext import CurNext

client = CurNext(
    api_key=os.environ["CURNEXT_API_KEY"],
    # base_url defaults to https://api.curnext.app
)

health = client.health.get()
# {"status": "ok", "service": "curnext-api", "version": "…", "api": "/api/v1"}

projects = client.projects.list()
readiness = client.projects.get_readiness("SURFACE_EXTERNAL_ID")

print(readiness["status"], readiness.get("readiness_score"))
```

---

## Authentication

1. Open the CurNext platform → your project → **API keys**.
2. Create a project key (`cn_live_…`).
3. Pass it to the client. The SDK sends:

```http
Authorization: Bearer cn_live_…
```

API access is included with **Professional** (and Enterprise programs). Keys and webhook endpoints are managed in the product UI - this SDK is a consumer of the public REST API.

Never commit live keys. Prefer environment variables:

```bash
export CURNEXT_API_KEY=cn_live_…
```

---

## Configuration

```python
client = CurNext(
    api_key="cn_live_…",                 # required
    base_url="https://api.curnext.app",  # optional (default)
    timeout=60.0,                        # optional seconds
)
```

| Option | Default | Notes |
| --- | --- | --- |
| `api_key` | - | Required. Project API key. |
| `base_url` | `https://api.curnext.app` | Host only - **do not** append `/api/v1` (the SDK adds it). |
| `timeout` | `60.0` | Request timeout in seconds. |

**Local API:**

```python
client = CurNext(
    api_key=os.environ["CURNEXT_API_KEY"],
    base_url="http://localhost:4000",
)
```

---

## API surface

All methods return decoded JSON (dicts / lists). Failures raise [`CurNextApiError`](#error-handling).

### Health

```python
client.health.get()
# {"status", "service": "curnext-api", "version", "api": "/api/v1"}
```

### Projects

| Method | Description |
| --- | --- |
| `projects.list()` | Projects visible to the API key |
| `projects.get(project_id)` | Project summary |
| `projects.list_members(project_id)` | Members & invitations |
| `projects.list_audit_events(project_id, page=…, limit=…, event_type=…)` | GDPR / compliance audit trail |
| `projects.get_subscription(project_id)` | Subscription + recent invoices |
| `projects.get_readiness(surface_id)` | Latest surface readiness prediction |

### Surfaces & predictions

```python
client.surfaces.get_readiness(surface_id)  # alias of projects.get_readiness
client.predictions.list(surface_id, limit=None)
```

### BIM

```python
client.bim.get(project_id)  # buildings → floors → rooms → surfaces tree
```

### Devices

```python
client.devices.list(project_id=None)
client.devices.get(device_id)
```

### Alerts

```python
client.alerts.list(project_id=None, resolved=None, limit=None)
client.alerts.get(alert_id)
client.alerts.resolve(alert_id)
```

### Measurements

```python
client.measurements.list_cycles(building_id, limit=None)
client.measurements.latest_device(device_id)
```

### Webhooks (read)

```python
client.webhooks.list(project_id=None)
```

Create / edit / delete webhook receivers in the CurNext dashboard. The API lists active endpoints (events include readiness, alerts, devices including `DEVICE_DISPLACED`, compliance, and handover).

### Low-level

```python
client.request("/custom/path", method="GET", query={"foo": "bar"}, body=None)
```

Paths without `/api/` are prefixed with `/api/v1/`.

---

## Error handling

```python
from curnext import CurNext, CurNextApiError

try:
    readiness = client.projects.get_readiness("SURFACE_ID")
    print(readiness["status"])
except CurNextApiError as exc:
    # 401 invalid key · 403 forbidden · 404 not found · 429 rate limited · 5xx server
    print(exc.status_code, exc.message, exc.code, exc.body)
    raise
```

| Attribute | Type | Description |
| --- | --- | --- |
| `status_code` | `int` | HTTP status |
| `message` | `str` | Human-readable error |
| `code` | `str \| None` | Optional API error code |
| `body` | `Any` | Raw response payload |

---

## Webhooks

Outbound event delivery is configured in the product (HTTPS URL, scope, event types, signing secret).

- List configs: `client.webhooks.list()`
- Event catalog includes `SURFACE_READY`, `ALERT_CREATED`, `DEVICE_DISPLACED`, `PROJECT_HANDOVER_READY`, and more
- Verify signatures with the secret shown once at creation (`X-CurNext-Signature`)

Full event list and REST reference: [OpenAPI UI](https://api.curnext.app/docs).

---

## Local development & smoke test

Maintainers working in the CurNext monorepo (`packages/sdk-python`):

```bash
# terminal 1 - API
pnpm --filter api dev

# terminal 2 - Python SDK smoke (health, projects, webhooks)
cd packages/sdk-python
CURNEXT_API_KEY=cn_live_… \
CURNEXT_API_BASE=http://localhost:4000 \
python3 scripts/smoke.py
```

---

## Author & support

| | |
| --- | --- |
| **Author** | Awunjia Serge Atabong |
| **Company** | CurNext Oy (CurNext) |
| **Copyright** | © 2026 CurNext Oy |
| **Website** | [https://curnext.app](https://curnext.app) |
| **Contact** | [info@curnext.app](mailto:info@curnext.app) |
| **API docs** | [https://api.curnext.app/docs](https://api.curnext.app/docs) |
| **Product** | Manage keys & webhooks in the CurNext dashboard |
| **Sales / API access** | [https://curnext.app/contact](https://curnext.app/contact) |
| **Issues** | [github.com/awunjia/CurNext/issues](https://github.com/awunjia/CurNext/issues) |
| **Source (monorepo)** | [`packages/sdk-python`](https://github.com/awunjia/CurNext/tree/main/packages/sdk-python) |
| **Publish repo** | [github.com/awunjia/curnext-python](https://github.com/awunjia/curnext-python) |

CurNext provides construction readiness intelligence - surface curing status, site alerts, BIM context, and device fleet APIs - so decisions leave the dashboard and enter your stack.

---

## License

MIT © 2026 CurNext Oy · Awunjia Serge Atabong
