Python SDK — Začínáme

sencai-sdk je Python klient pro Sencai Platform API (/api/v1/*), generovaný z veřejného OpenAPI specu (openapi-generator-cli, šablona python — F4.DEVPORTAL.02). Žije v monorepu na sdk-python/ (samostatný pyproject.toml/setup.cfg balíček, ne npm workspace).

Instalace

sencai-sdk zatím není publikovaný na PyPI — veřejná distribuce balíčku je samostatné obchodní/release rozhodnutí, mimo scope samotné práce na generování SDK. Struktura balíčku je už PyPI-ready; do doby publikace instalovat z monorepo cesty nebo přímo z gitu:

# Z checkoutu monorepa
python3 -m venv .venv
.venv/bin/pip install -e ./sdk-python

# Přímo z gitu
pip install "git+https://github.com/sencai-space/sdk-python.git"

Inicializace klienta

from sencai_sdk import ApiClient, Configuration, OrganisationApi

config = Configuration(
    # Lokální vývoj: http://api.sencai.localhost/api/v1 nebo http://localhost:1337/api/v1
    # Produkce: https://api.sencai.space/api/v1
    host=os.environ["SENCAI_API_BASE_URL"],
    # Bearer JWT (dnes Keycloak access token) — nebo budoucí API-key hlavička.
    # Klient jen umožňuje injection, sám token nezískává ani neobnovuje.
    access_token=os.environ["SENCAI_ACCESS_TOKEN"],
)

with ApiClient(config) as client:
    organisations = OrganisationApi(client)

Configuration.host i autentizace jsou vždy konstruktorové parametry — balíček nikdy neobsahuje hardcoded produkční URL.

Kompletní příklad: seznam organizací, pozvání člena

Ověřeno proti lokálnímu stacku run-local-dev.sh (profily backend, backend-db, auth).

import os
import sencai_sdk

config = sencai_sdk.Configuration(
    host=os.environ["SENCAI_API_BASE_URL"],
    access_token=os.environ["SENCAI_ACCESS_TOKEN"],
)

with sencai_sdk.ApiClient(config) as client:
    organisations = sencai_sdk.OrganisationApi(client)

    # Seznam organizací, jejichž je volající členem.
    result = organisations.find_organisation(pagination_page_size=10)
    print([org.name for org in result.data])
    # -> ['QA Admin Workspace', 'e2e-org-d18a54e2', 'e2e-org-d9e67836']

    target_org = result.data[0]

    # Pozvání existujícího Strapi uživatele do dané organizace. `POST
    # /organisations/{id}/invite` vyžaduje, aby zvaný email už měl
    # registrovaný účet (viz sekce Zpracování chyb níže, co se stane jinak)
    # a aby volající měl v organizaci roli admin+.
    body = sencai_sdk.OrganisationInviteMemberRequest(email="new-member@example.com", role="viewer")
    invite = organisations.organisation_invite_member(target_org.document_id, body)
    print(invite.data)
    # -> OrganisationInviteMember200ResponseData(id=1264, attributes=OrganisationInviteMember200ResponseDataAttributes(
    #      email='new-member@example.com', role='viewer', invited_by='you@example.com',
    #      invited_at=datetime.datetime(2026, 7, 5, 11, 56, 34, tzinfo=TzInfo(0)), status='pending'))

Zpracování chyb

Každá non-2xx odpověď vyhodí sencai_sdk.exceptions.ApiException (nebo specifický subtyp podle stavu, např. UnauthorizedException/ForbiddenException) s atributy .status a syrovým .body řetězcem — typovaná metoda nikdy při chybě nevrátí částečně platný výsledek. Tělo chyby má standardní Strapi obálku: { "error": { "status", "name", "message", "details" } }.

import json
from sencai_sdk.exceptions import ApiException

try:
    organisations.organisation_invite_member(target_org.document_id, body)
except ApiException as err:
    payload = json.loads(err.body)["error"]
    print(err.status, payload["name"], payload["message"])
    # Reálný, běžně narazitelný příklad — limit počtu členů z tarifu organizace:
    # 402 PaymentRequired "Member limit reached (3/3). Upgrade your plan."
    # payload["details"] -> {"limit": 3, "current": 3, "limit_source": "organisation_plan", ...}

Další stavové kódy, které lze u tohoto konkrétního endpointu očekávat: 400 (chybějící/neplatný email/role, nebo žádný Strapi uživatel s daným emailem — tento endpoint nezve ještě neregistrované emaily), 401 (chybějící/expirovaný token), 403 (volající nemá v organizaci roli admin+), 409 (daný uživatel je již členem).

Verzování SDK a breaking changes

Verze balíčku (pyproject.toml/setup.py → version) je při každé regeneraci odvozená z info.version OpenAPI specu — nikdy se nebumpuje ručně. Breaking change API se vydá jako nová major verze specu, což přeregeneruje toto SDK také jako novou major verzi. Co se počítá jako breaking, migrační cestu /api/v1/ → /api/v2/ a konvenci deprecation hlavičky SUNSET_DATE viz Verzování API — tato stránka danou politiku neopakuje, jen popisuje, jak se projevuje v generovaném klientovi.

Kompletní generovanou referenci každé operace, kterou tento klient pokrývá, najdeš v API Reference.