# SDKs & collections

Two thin clients and two collections for API tools. All four are generated from the [OpenAPI contract](https://docs.creator-guard.com/openapi.yaml), so every operation in the [API reference](https://docs.creator-guard.com/reference/) is in each of them, under its `operationId`. Neither client has runtime dependencies.

The clients are not on npm or PyPI yet. Download them here and keep the copy in your project; the download always matches the contract version shown in the header.

| Download | What |
|---|---|
| [creatorguard-python.zip](https://docs.creator-guard.com/downloads/creatorguard-python.zip) | Python client, Python 3.10 or newer, standard library only |
| [creatorguard-typescript.zip](https://docs.creator-guard.com/downloads/creatorguard-typescript.zip) | TypeScript client (ES modules), Node 20 or newer |
| [creatorguard.postman_collection.json](https://docs.creator-guard.com/downloads/creatorguard.postman_collection.json) | Postman collection (v2.1), one request per operation |
| [creatorguard-bruno.zip](https://docs.creator-guard.com/downloads/creatorguard-bruno.zip) | Bruno collection with a `production` environment (`https://api.creator-guard.com`) |

## Python

Unzip, then either copy `creatorguard.py` and `creatorguard_operations.py` next to your code or install the folder with `pip install ./creatorguard-python`.

```python
import os
from creatorguard import Client, CreatorGuardError

cg = Client(os.environ["CG_API_KEY"])

lead = cg.create_lead(body={
    "external_id": "crm-1047",
    "creator_name": "Mia",
    "instagram_handle": "@miacreates",
    "platforms": ["OnlyFans", "Instagram"],
    "consent_confirmed": True,
})

for lead in cg.paginate("listLeads", query={"stage": "draft"}):
    print(lead["id"], lead["stage"])
```

A creator integration (OAuth) passes the access token instead of a key: `Client(access_token=os.environ["CG_ACCESS_TOKEN"])`. Pass exactly one of the two; both are sent as `Authorization: Bearer …`.

Every operation is also a method named after its `operationId` in snake case (`createLead` → `create_lead`). Path parameters are positional, everything else is a keyword: `query=`, `body=`, `idempotency_key=` (POST) and `if_match=` (PATCH and PUT). `cg.request("createLead", body=...)` does the same by name.

## TypeScript

Unzip, build it once inside the folder with `npm ci && npm run build` (output in `dist/`), then install the folder in your project with `npm install ./creatorguard-typescript`. For a creator integration (OAuth) pass `accessToken` instead of `apiKey` — exactly one of the two.

```ts
import { CreatorGuard, CreatorGuardError } from '@creatorguard/api';

const cg = new CreatorGuard({ apiKey: process.env.CG_API_KEY! });

const lead = await cg.request('createLead', {
  body: { external_id: 'crm-1047', creator_name: 'Mia', instagram_handle: '@miacreates',
    platforms: ['OnlyFans', 'Instagram'], consent_confirmed: true },
});

for await (const item of cg.paginate('listLeads', { query: { stage: 'draft' } })) {
  console.log(item);
}
```

## Retries and idempotency

Both clients retry the same way, so a script behaves alike in either language:

| Answer | Retried? |
|---|---|
| No answer (network error, timeout) | Yes |
| `408`, `429`, `500`, `502`, `504` | Yes |
| `503` | Yes, except `not_configured` |
| `409 idempotency_in_progress` | Yes |
| Any other `4xx` | No |

Up to 2 retries by default (`max_retries` / `maxRetries`). The wait is the `Retry-After` header when the API sends one (at most 60 seconds), otherwise an exponential backoff from 0.5 to 8 seconds with jitter.

A `Retry-After` longer than 60 seconds is never waited for: the call ends at once, without a retry, so a script cannot hang for an hour. For a `429` the client then raises `RateLimitError` with the wait in seconds (`retry_after` in Python, `retryAfter` in TypeScript) — schedule the next attempt yourself. A `429` that is still there after the last retry is a `RateLimitError` as well.

Every `POST` carries an `Idempotency-Key`. The client makes one (a random UUID) unless you pass your own, and it reuses the same key for every retry of that call — so a lead that was created before a timeout is not created a second time. Pass your own key when your job can restart, for example the row id of your import. See [Idempotency & retries](https://docs.creator-guard.com/idempotency/).

## Pagination

`paginate()` follows `next_cursor` as `starting_after` until `has_more` is `false` and yields the items one by one. Pass the filters of the list operation in `query`; `limit` sets the page size (1–100).

## Errors

A non-`2xx` answer raises `CreatorGuardError` with `status`, `type`, `code`, `message`, `request_id`, `field` and `details` — the fields of the [error body](https://docs.creator-guard.com/errors/). Branch on `code`. A `429` is a `RateLimitError`, a subclass of `CreatorGuardError`. A proxy page instead of an API error (a `502` while a release switches over) has `code` `proxy_error`. When no HTTP answer arrives after the last retry, the Python client raises `ConnectionError_` and the TypeScript client `ConnectionError`.

## Webhook signatures

Check `CG-Signature` against the raw request body (bytes, before any JSON parsing) and the endpoint secret. Both helpers accept every `v1` signature in the header (two during a secret rotation) and reject timestamps more than 300 seconds away from now.

```python
from creatorguard import verify_webhook_signature

def handle_webhook(raw_body: bytes, headers) -> int:
    if not verify_webhook_signature(raw_body, headers["CG-Signature"], os.environ["CG_WEBHOOK_SECRET"]):
        return 400
    return 200
```

```ts
import { verifyWebhookSignature } from '@creatorguard/api';

const header = String(req.headers['cg-signature'] ?? '');
if (!verifyWebhookSignature(rawBody, header, process.env.CG_WEBHOOK_SECRET!)) {
  res.status(400).end();
}
```

## Postman and Bruno

- **Postman:** Import → the JSON file. Put `api_key` into a Postman environment as a secret variable, not into the collection, which you might share. `base_url` is `https://api.creator-guard.com`.
- **Bruno:** unzip, then Open Collection → the `creatorguard-bruno` folder. Pick the `production` environment and enter `api_key` there; it is a secret variable, so Bruno keeps it out of the files.

There is one host for everything. To try requests without touching live data, use a `cg_test_` key: it works on the same `https://api.creator-guard.com` against your account's sandbox, see [Test mode](https://docs.creator-guard.com/test-mode/). A `cg_live_` key works on live data.

Every `POST` request sends a fresh `Idempotency-Key` (`{{$guid}}`); a resend from the tool therefore counts as a new request. Request bodies are the examples from the reference.
