Metadata-Version: 2.4
Name: drc-vantage
Version: 1.6.8
Summary: Thin HTTP client for the DRC Vantage platform API
Project-URL: Homepage, https://github.com/nathan294/vantage
Project-URL: Repository, https://github.com/nathan294/vantage
Project-URL: Issues, https://github.com/nathan294/vantage/issues
Author: DRC
License-Expression: LicenseRef-Proprietary
Keywords: api,data,http,sdk,vantage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary 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

# drc-vantage

Thin HTTP client for the Vantage platform. Talks only to the **Next.js API** (`VANTAGE_API_URL`) with a **developer account API key**.

## Install

```bash
pip install drc-vantage
# or
uv add drc-vantage
```

## Configuration

| Variable          | Description                        | Example                     |
| ----------------- | ---------------------------------- | --------------------------- |
| `VANTAGE_API_URL` | Next.js API base (includes `/api`) | `http://localhost:3000/api` |
| `VANTAGE_API_KEY` | Developer account API key          | `vantage_…`                 |

## Quick start (100 % `Client`)

```python
from vantage import Client

client = Client()

# Teams: read + create on the same namespace
team = client.teams.create(name="Sales", description="Revenue ops")
record = client.teams.find_by_name("Sales")

# Users: resolve profile or get a handle for actions
guest = client.users.resolve("guest@example.com")  # .id, .email, .name
guest_handle = client.users.for_ref("guest@example.com")
user = client.users.create(
    first_name="Ada",
    last_name="Lovelace",
    email="ada@example.com",
    password="secure-password",
)

# KPI → chain governance on the returned handle
my_kpi = client.kpis.create(
    name="Monthly revenue",
    dataset_id="…",
    definition_type="MANUAL",
    manual_config={"valueField": "amount", "aggregation": "SUM"},
)
my_kpi.assign_to_team("analytics")

# Ingestion (flat — no client.ingestion.*)
client.storage_systems.register(
    slug="wh-pg",
    env_key="DRC_PG",
    name="Warehouse PostgreSQL",
    kind="POSTGRESQL",
)
category = client.data_source_categories.register(
    slug="saas", name="SaaS", color="#3366FF"
)
client.data_sources.register(slug="hubspot", name="HubSpot", category=category)

dataset = client.datasets.register(
    location={"schema": "marts", "table": "nps"},
    name="NPS",
    type="TABLE",
)
dataset.analyze_and_check_alerts()

# Dashboard → register then chain governance on the returned handle
dashboard = client.dashboards.register(
    title="Sales metrics",
    icon="layout-dashboard",
    embed_mode="INLINE",
    inline_path="sales/metrics",
)
dashboard.assign_to_team("Sales")
dashboard.assign_owner("nathan.boulogne@gmail.com")
dashboard.link_datasets(["NPS"])
dashboard.assign_editors(["editor@example.com"])
```

## Public exports

`Client`, catalogue exceptions (`NotFoundError`, `AmbiguousLookupError`), `Page`, orchestration helpers.

Advanced typing: `from vantage.handles import User, Kpi, Dataset` (not exported from top-level `vantage`).

This package ships [`py.typed`](src/vantage/py.typed) — use Pylance **basic** or stricter for parameter hints on `client.*.create` / `register`.

## Client namespaces

| Property | Read | Write |
| -------- | ---- | ----- |
| `client.datasets` | list, get, find_by_name | `register`, `for_id` |
| `client.kpis` | list, get, find_by_name | `create`, `for_id` |
| `client.figures` | catalogue | `create`, `for_id` |
| `client.dashboards` | browse, get, find_by_title | `register`, `for_id`, `create_folder`, assign & link on handle |
| `client.dashboard_folders` | browse, list, get, find_by_id, find_by_name | `create`, `for_id` |
| `client.data_sources` | list, get | `register` |
| `client.data_source_categories` | — | `register` |
| `client.storage_systems` | — | `register` |
| `client.teams` | list, find_by_name, find_by_slug | `create` |
| `client.users` | — | `create`, `resolve`, `for_ref`, `for_id` |
| `client.organisations` | — | `create` |
| `client.search` | global search | — |

## Orchestration

```python
from vantage import Client, vantage_flow

client = Client()

@vantage_flow(client)
def my_flow():
    client.data_sources.register(...)
```
