nerova-sdk

Server-side Python client for Nerova's dedicated stable tenant-v1 contract. The client code is machine-generated with Microsoft Kiota from ../contract/tenant-v1.openapi.json; there is no hand-written client layer. Kiota's Python generation is upstream-stable.

This package is server-side only: no browser credential flow, no UI, no persistent credential storage. Never ship an API key to a browser or a mobile app.

pip install nerova-sdk==0.3.0b1

The distribution name is nerova-sdk; the import name is nerova_sdk. It needs Python 3.9 or later and installs the Kiota runtime (microsoft-kiota-abstractions, microsoft-kiota-http, and the JSON, text, form, and multipart serialization packages) as regular dependencies.

Versioning

The SDK shares one version line with @nerova/sdk and Nerova.Sdk (currently 0.3.0-preview.1). PyPI requires PEP 440 versions, so a -preview.N suffix is written as bN: 0.3.0-preview.1 is 0.3.0b1, and 0.3.0-preview.2 will be 0.3.0b2. A stable release keeps the bare X.Y.Z. Pip skips pre-releases unless you pin one (as above) or pass --pre. The API surface may change before 1.0, so pin the exact version.

Quickstart

The API has one public host, https://api.nerovasystems.com, baked into the generated client as the default base URL. Every API key is a Live key (nrv_live_) that reaches Production; approved platforms start on a free testing allowance. Read the key from the environment and send it as Authorization: Bearer <key>:

import asyncio
import os

from kiota_abstractions.authentication import ApiKeyAuthenticationProvider, KeyLocation
from kiota_http.httpx_request_adapter import HttpxRequestAdapter
from nerova_sdk import NerovaPartnerClient


async def main() -> None:
    value = os.environ["NEROVA_API_KEY"]
    tenant_id = os.environ["TENANT_ID"]

    authentication_provider = ApiKeyAuthenticationProvider(
        KeyLocation.Header, f"Bearer {value}", "Authorization"
    )
    client = NerovaPartnerClient(HttpxRequestAdapter(authentication_provider))

    manifest = await client.api.v1.tenants.by_tenant_id(tenant_id).activation.manifest.get()
    print(manifest.state, manifest.next_allowed_actions)


asyncio.run(main())

The client mirrors the URL structure of the API: client.api.v1.status, client.api.v1.context, client.api.v1.tenants, and client.api.v1.tenants.by_tenant_id(id) for everything under one tenant. Models live in nerova_sdk.models, and request builders in nerova_sdk.api.

Conventions

• Idempotency: send a caller-owned Idempotency-Key header on every mutation via the request configuration, and reuse the same value when repeating the same command. The client performs no automatic retries of mutations:

  from kiota_abstractions.base_request_configuration import RequestConfiguration
  from nerova_sdk.models.create_tenant_v1_request import CreateTenantV1Request
  
  configuration = RequestConfiguration()
  configuration.headers.add("Idempotency-Key", "provision-tenant-your-crm-id-123")
  created = await client.api.v1.tenants.post(
      CreateTenantV1Request(display_name="Demo Salon", external_reference="your-crm-id-123"),
      configuration,
  )
  

• Errors follow RFC 9457 problem details: the request adapter raises the deserialized nerova_sdk.models.problem_details.ProblemDetails (an APIError) with response_status_code and response_headers attached; the stable code and correlationId arrive in additional_data. Branch on those fields, never on message text.

• Enums are open string sets; treat unknown values as forward compatibility.

• List endpoints paginate with unixms|id cursors: pass cursor back through the query parameters until next_cursor is None.

Regeneration

The whole nerova_sdk folder is Kiota-owned: it is regenerated with --clean-output, and the developer CLI then writes the package __init__.py and the py.typed marker. nerova_sdk/kiota-lock.json pins the contract hash and tool version. Packaging metadata (pyproject.toml, this README, LICENSE) is the only hand-written part.

dotnet run --project developer-cli -- partner-sdk --kiota --quiet

Publishing is manual and runs from the Publish SDKs workflow (publish-sdks.yml, target pypi) through PyPI trusted publishing. A CI smoke test builds the sdist and wheel and imports the client from a clean virtual environment on every change to the SDK folder.

See the repository SDK guide for Postman, webhook status, and the full conventions reference.