SDKs (TypeScript, Python)

Official clients from the same OpenAPI file as this reference — version = spec version. Everything shown here also works with raw HTTP.

Installation

TypeScript: npm package @claritos/api (ESM, Node ≥ 18, also edge/browser with your own fetch). Python: PyPI package claritos (Python ≥ 3.9, httpx). Both ship types for all endpoints and webhook verification.

shell

npm install @claritos/api
# oder
pip install claritos

TypeScript

createClaritos({ apiKey }) returns a configured client; every operation is a function named after the endpoint (contactsList, invoicesIssue, …) taking { client, path, query, body, headers }. Responses are { data, error, response }; with throwOnError: true the call throws instead. Pass the Idempotency-Key header on write calls.

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) returns an AuthenticatedClient; operations live as modules under claritos_api.api.<domain>.<operation> with sync/asyncio variants (sync, sync_detailed, asyncio). Models under claritos_api.models — field names 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"),
)

Verifying webhooks

verifyWebhook / verify_webhook check webhook-id, webhook-timestamp (±5 minutes) and webhook-signature (HMAC-SHA256, Standard Webhooks) — always over the raw body. During secret rotation pass both secrets as a list.

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)

Versions

The SDK version is the version of the OpenAPI file (see the changelog). New endpoints and fields are additive; updating the SDK is never required to keep calling. Published to npm/PyPI by tags sdk-ts-v… and sdk-py-v… in the repository.