SDKs (TypeScript, Python)

Offizielle Clients aus derselben OpenAPI-Datei wie diese Referenz — Version = Spec-Version. Alles, was hier steht, geht auch mit rohem HTTP.

Installation

TypeScript: npm-Paket @claritos/api (ESM, Node ≥ 18, auch Edge/Browser mit eigenem fetch). Python: PyPI-Paket claritos (Python ≥ 3.9, httpx). Beide bringen Typen für alle Endpunkte und die Webhook-Verifikation mit.

shell

npm install @claritos/api
# oder
pip install claritos

TypeScript

createClaritos({ apiKey }) liefert einen konfigurierten Client; jede Operation ist eine Funktion mit dem Endpunkt-Namen (contactsList, invoicesIssue, …) und nimmt { client, path, query, body, headers }. Antworten kommen als { data, error, response }; mit throwOnError: true wirft der Aufruf stattdessen. Für Schreibaufrufe den Idempotency-Key als Header mitgeben.

typescript

import { createClaritos, contactsList, contactsCreate, STAGING_BASE_URL } from "@claritos/api";

const claritos = createClaritos({
  apiKey: process.env.CLARITOS_API_KEY!,
  // baseUrl: STAGING_BASE_URL, // Sandbox
});

const { data, error } = await contactsList({ client: claritos, query: { limit: 50, q: "muster" } });
if (error) throw new Error(error.title);
for (const c of data.data) console.log(c.displayName);

const created = await contactsCreate({
  client: claritos,
  body: { type: "PERSON", firstName: "Anna", lastName: "Muster", email: "anna@example.com" },
  headers: { "Idempotency-Key": crypto.randomUUID() },
  throwOnError: true,
});

Python

create_client(api_key) liefert einen AuthenticatedClient; die Operationen liegen als Module unter claritos_api.api.<domäne>.<operation> mit sync/asyncio-Varianten (sync, sync_detailed, asyncio). Modelle unter claritos_api.models — Feldnamen in snake_case.

python

from claritos import create_client, STAGING_BASE_URL
from claritos_api.api.contacts import contacts_list, contacts_create
from claritos_api.models import ContactsCreateBody

client = create_client(api_key="capi_…")  # base_url=STAGING_BASE_URL für die Sandbox

page = contacts_list.sync(client=client, limit=50, q="muster")
for c in page.data:
    print(c.display_name)

created = contacts_create.sync(
    client=client,
    body=ContactsCreateBody(type="PERSON", first_name="Anna", last_name="Muster", email="anna@example.com"),
)

Webhooks verifizieren

verifyWebhook / verify_webhook prüfen webhook-id, webhook-timestamp (±5 Minuten) und webhook-signature (HMAC-SHA256, Standard Webhooks) — immer über den Roh-Body. Bei Secret-Rotation beide Secrets als Liste übergeben.

typescript

import { verifyWebhook, WebhookVerificationError } from "@claritos/api";

export async function POST(req: Request) {
  const payload = await req.text(); // Roh-Body, nicht geparst
  try {
    const event = await verifyWebhook({ payload, headers: req.headers, secret: process.env.CLARITOS_WEBHOOK_SECRET! });
    // event.type z. B. "invoices.invoice.paid"; event.data = Nutzlast
    return new Response(null, { status: 204 });
  } catch (e) {
    if (e instanceof WebhookVerificationError) return new Response("invalid signature", { status: 400 });
    throw e;
  }
}

python

from claritos import verify_webhook, WebhookVerificationError

@app.post("/webhooks/claritos")
def claritos_webhook(request):
    try:
        event = verify_webhook(request.get_data(), request.headers, secret=os.environ["CLARITOS_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return ("invalid signature", 400)
    handle(event["type"], event["data"])
    return ("", 204)

Versionen

Die SDK-Version ist die Version der OpenAPI-Datei (Changelog beachten). Neue Endpunkte und Felder kommen additiv; ein Update des SDK ist nie Pflicht, um weiter aufzurufen. Veröffentlichung auf npm/PyPI per Tag sdk-ts-v… bzw. sdk-py-v… im Repository.