Metadata-Version: 2.5
Name: northstar-sdk
Version: 1.5-rc.1
Summary: Thin HTTP client for the Northstar platform API
Project-URL: Homepage, https://github.com/nathan294/northstar
Project-URL: Repository, https://github.com/nathan294/northstar
Project-URL: Issues, https://github.com/nathan294/northstar/issues
Author: Nathan Boulogne
License-Expression: Apache-2.0
Keywords: api,data,http,northstar,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: httpx>=0.28.0
Requires-Dist: loguru>=0.7.0
Description-Content-Type: text/markdown

# northstar-sdk

Python client for the Northstar platform API. It authenticates with the API key of an integration (developer) account and talks only to the platform's Next.js API (`NORTHSTAR_API_URL`), never to a database or a warehouse.

## Install

```bash
pip install northstar-sdk
# or
uv add northstar-sdk
```

## Configure

| Variable | Description | Example |
| --- | --- | --- |
| `NORTHSTAR_API_URL` | Platform API base, including `/api` | `https://data.example.com/api` |
| `NORTHSTAR_API_KEY` | Integration account API key | `northstar_…` |

## Example

```python
from northstar_sdk import Client

client = Client()

orders = client.datasets.upsert(
    location={"schema": "marts", "table": "orders"},
    name="Orders",
    type="TABLE",
    layer="GOLD",
    storage_system_slug="warehouse",
)
orders.assign_to_team("sales")
orders.analyze()
```

## Documentation

The user guide is the **Developers** section of the platform's help center (Help, in the app). Its source is in this repository:

- [Integration accounts](https://github.com/nathan294/northstar/blob/main/front/content/help/en-GB/developer-accounts.md)
- [API keys](https://github.com/nathan294/northstar/blob/main/front/content/help/en-GB/api-keys.md)
- [Python SDK](https://github.com/nathan294/northstar/blob/main/front/content/help/en-GB/python-sdk.md): configuration, namespaces, write methods, governance, errors
- [SDK recipes](https://github.com/nathan294/northstar/blob/main/front/content/help/en-GB/sdk-recipes.md): warehouses, datasets, documents, KPIs, dashboards, pipelines
- [SDK reference](https://github.com/nathan294/northstar/blob/main/front/content/help/en-GB/sdk-reference.md): credentials, locations, errors, raw HTTP

A change to the SDK's public behaviour updates those articles, in English and French, in the same change (see the root `CLAUDE.md`).

## Maintaining the SDK

The SDK is a thin HTTP client: request bodies are validated by the servers, not by the SDK.

```mermaid
flowchart LR
  Sdk["northstar-sdk Client"]
  Bff["Next.js /api/feature/..."]
  FastApi["FastAPI /v1/feature/..."]
  Compute["northstar-compute"]
  Prisma["Prisma / Postgres"]
  Sdk -->|"X-API-KEY"| Bff
  Bff -->|"proxyAuthenticatedJson"| FastApi
  FastApi --> Compute
  Bff --> Prisma
```

| Resource | Next.js route | Canonical body |
| --- | --- | --- |
| Storage system | `/api/feature/data-storage-systems/create\|upsert` → FastAPI | [`DataStorageSystemWriteRequest`](../../api/src/api/v1/feature/data_storage_system/schemas.py) |
| Dataset | `/api/feature/datasets/create\|upsert` → FastAPI | [`DatasetWriteRequest`](../../api/src/api/v1/feature/dataset/schemas.py) |
| Document collection | `/api/feature/document-collections/create\|upsert\|ingest` → FastAPI | [`DocumentCollectionWriteRequest`](../../api/src/api/v1/feature/document_collection/schemas.py) |
| Data source | `/api/feature/data-sources/create\|upsert`, `PATCH …/[id]/write` → FastAPI | [`DataSourceWriteRequest`](../../api/src/api/v1/feature/data_source/schemas.py) |
| Data source category | `/api/feature/data-source-categories/create\|upsert` (Prisma) | Zod in those routes |
| KPI | `POST /api/feature/kpi-catalogue` | camelCase in that route |
| Dashboard | `POST /api/feature/dashboards` | [`registerDashboardSchema`](../../front/src/lib/dashboard/dashboard-register-schema.ts) |
| Figure | `POST /api/feature/builder/figures` | Builder figure route |
| Team / user / organization | `/api/teams`, `/api/users`, `/api/organizations` | Those Next.js routes |

- Storage credentials are checked in [`warehouse/credentials.py`](../northstar_compute/src/northstar_compute/warehouse/credentials.py) (`validate_and_normalize_credentials`).
- Dataset and collection `location` keys: `LOCATION_KEY_PARTS` in [`datasets/location.py`](../northstar_compute/src/northstar_compute/datasets/location.py) and [`document_collections/location.py`](../northstar_compute/src/northstar_compute/document_collections/location.py).
- Resources proxied to FastAPI use snake_case JSON; Next.js catalogue resources (`kpi-catalogue`, `dashboards`, `figures`) use camelCase. The SDK maps snake_case Python arguments for you.

When you change a FastAPI `*WriteRequest` or a Next.js Zod schema:

1. Update the matching handle `_payload()` / `_base_payload()` in [`src/northstar_sdk/handles/`](src/northstar_sdk/handles/).
2. Update the namespace arguments and [`src/northstar_sdk/types/params.py`](src/northstar_sdk/types/params.py).
3. Run `uv run --package northstar-sdk pytest tests/test_typing_params.py`.
4. Update the SDK articles of the help center (`front/content/help/*/python-sdk.md`, `sdk-recipes.md`, `sdk-reference.md`).

Publishing: [PUBLISHING.md](PUBLISHING.md).
