Metadata-Version: 2.4
Name: licensekit-sdk
Version: 1.0.0
Summary: Typed Python SDK for the LicenseKit licensing API
Project-URL: Homepage, https://licensekit.dev
Project-URL: Documentation, https://licensekit.dev/docs/agent-quickstart
Project-URL: API Contract, https://licensekit.dev/docs/api-contract
Project-URL: OpenAPI Spec, https://licensekit.dev/openapi.yaml
Project-URL: LLM Reference, https://licensekit.dev/llms.txt
Author: David Main
License: MIT
License-File: LICENSE
Keywords: activation,entitlements,license-management,licensekit,licensing,metering,python,software-licensing
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 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pynacl<2,>=1.5
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: twine<7,>=5; extra == 'dev'
Description-Content-Type: text/markdown

# `licensekit-sdk`

First-party Python SDK for `licensekit.dev`.

This package exposes Management, Runtime, and System clients over the LicenseKit licensing API at `https://api.licensekit.dev`, including reporting and frozen export operations, along with least-privilege scope metadata and Ed25519 runtime-signature verification helpers for activation, validation, metering, and offline-aware license flows.

## Why use it

- Typed `ManagementClient`, `RuntimeClient`, and `SystemClient` surfaces.
- Runtime signature verification helpers backed by `PyNaCl`.
- Least-privilege scope discovery derived from the OpenAPI contract.
- Hosted and self-hosted support through a configurable `base_url`.

Links:

- [Agent quickstart](https://licensekit.dev/docs/agent-quickstart)
- [API contract notes](https://licensekit.dev/docs/api-contract)
- [OpenAPI spec](https://licensekit.dev/openapi.yaml)
- [LLM reference](https://licensekit.dev/llms.txt)
- [PyPI package](https://pypi.org/project/licensekit-sdk/)

## Install

```bash
pip install licensekit-sdk
```

## Quick Start

```python
from licensekit import (
    ManagementClient,
    PublicKeyStore,
    RuntimeClient,
    SystemClient,
    verify_runtime_result,
)

base_url = "https://api.licensekit.dev"

system = SystemClient(base_url=base_url)
health = system.health()
print(health["data"]["status"])

management = ManagementClient(
    base_url=base_url,
    token="lkm_..."
)

product = management.create_product(
    body={
        "name": "Example App",
        "code": "example-app",
    }
)

runtime = RuntimeClient(
    base_url=base_url,
    license_key="lsk_..."
)

result = runtime.validate_license(
    body={
        "fingerprint": "host-123",
    }
)

public_keys = system.list_public_keys()
verified = verify_runtime_result(
    result,
    PublicKeyStore(public_keys["data"]),
)

print(product["data"]["id"], verified.ok)
```

## Package Shape

- `ManagementClient`
  Uses `Authorization: Bearer <token>` for `/api/v1/...` management operations, including `/api/v1/activities` and `/api/v1/reports/...`.
- `RuntimeClient`
  Uses `Authorization: License <license-key>` for `/api/v1/license/...` runtime operations.
- `SystemClient`
  Unauthenticated access to `/health`, `/healthz`, `/readyz`, `/metrics`, and `/api/v1/system/public-keys`.

Hosted deployments should prefer `/health` for liveness checks behind `api.licensekit.dev`.
`/healthz` remains available for local and self-hosted compatibility.

## Scope Metadata

```python
from licensekit import get_required_scopes, has_required_scopes

scopes = get_required_scopes("createProduct")
allowed = has_required_scopes("createProduct", ["product:write"])
```

## Raw Response Access

Each client exposes a `.raw` companion for callers that need status codes and headers.

```python
from licensekit import SystemClient

system = SystemClient(base_url="https://api.licensekit.dev")
ready = system.raw.readyz()

print(ready.status, ready.data["data"]["status"])
```

`management.download_report_export()` returns raw bytes so JSON, CSV, and PDF report snapshots can be handled without assuming a single response shape. Use `management.raw.download_report_export()` when you also need the response headers to branch on `Content-Type`.

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
python scripts/generate_from_openapi.py
pytest
python -m build
python -m twine check dist/*
```

Generation uses the checked-in OpenAPI snapshot at [`openapi/openapi.yaml`](./openapi/openapi.yaml).
