Metadata-Version: 2.4
Name: kaabist
Version: 1.40.0
Summary: Official Python client for the Kaabist web automation API
Project-URL: Homepage, https://kaab.ist
Project-URL: Documentation, https://docs.kaab.ist/guides/sdks
Project-URL: Changelog, https://docs.kaab.ist/changelog
Author-email: Kaabist <support@kaab.ist>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,browser-automation,kaab,kaabist,sdk,web-automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<1,>=0.23.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: typing-extensions>=4.7.0
Description-Content-Type: text/markdown

# kaabist

The official Python client for the [Kaabist](https://kaab.ist) API.

Kaabist runs web automation as programs: log in, fill a form, download a document, read typed
values. Programs are versioned, resume from checkpoints, never submit twice after a crash, and
pause for a person when a site asks for a one-time code. This package gives you every API
operation as a typed method, blocking or `asyncio`, with safe retries and a `wait` helper that
answers paused jobs for you.

```bash
pip install kaabist
```

Python 3.11 or newer. Fully typed (`py.typed`), built on `httpx`.

## Quick start

Create an API key in the panel (**Settings → API keys**, [app.kaab.ist](https://app.kaab.ist/settings/api-keys)).
Use an `sk_test_…` key while you build: test jobs run on the same engine but spend no credits,
within a daily job quota.

```bash
export KAAB_API_KEY=sk_test_...
```

```python
from kaabist import Kaab

with Kaab() as kaab:  # reads KAAB_API_KEY
    job = kaab.jobs.create(
        url="https://example.com",
        extract={"title": "h1"},
        wait=30,  # wait up to 30 s for the result in the same request
    )
    print(job.status, job.data)  # succeeded {'title': 'Example Domain'}
```

## Run a saved program

A program is a flow you defined once (in the panel, with the recorder, or as JSON). Run a version
by name and pass its inputs:

```python
job = kaab.jobs.create(program="supplier-invoices@production", inputs={"month": "2026-10"})
```

## Wait for a job, and answer it on the way

`jobs.wait` follows a job to the end. If the site asks for a one-time code, or the job needs a
decision, your callbacks answer it and the job continues from where it stopped:

```python
done = kaab.jobs.wait(
    job.id,
    timeout=600,
    # awaiting_input: e.g. a 2FA code the account owner types in
    on_input=lambda request, job: input(f"{request.prompt}: "),
    # needs_attention: skip the step, retry, or return "wait" to leave it to a person
    on_attention=lambda attention, job: {"skip_step": True},
)

if done.status == "succeeded":
    print(done.data)
```

Without callbacks, `wait` returns as soon as the job pauses, so you can hand it to the hosted
resolve page instead.

## asyncio

`AsyncKaab` has the same methods, awaited:

```python
from kaabist import AsyncKaab

async with AsyncKaab() as kaab:
    job = await kaab.jobs.create(program="supplier-invoices@production", inputs={"month": "2026-10"})
    done = await kaab.jobs.wait(job.id)

    async for proposal in kaab.proposals.list(status="pending"):
        print(proposal.id)
```

## Lists

List methods fetch pages as you iterate:

```python
for program in kaab.programs.list():
    print(program.name)
```

## Webhooks

Verify a delivery on its **raw** body before you trust it:

```python
import os
from flask import Flask, request
from kaabist import webhooks

app = Flask(__name__)

@app.post("/hooks/kaabist")
def kaabist_hook():
    event = webhooks.construct_event(
        request.get_data(),
        request.headers.get("Kaab-Signature"),
        os.environ["KAAB_WEBHOOK_SECRET"],
    )  # raises KaabSignatureError when the signature does not match

    if event["type"] == "job.succeeded":
        ...
    return "", 204
```

## Errors, retries and idempotency

- Every failure raises a `KaabError` with `code`, `status`, `request_id` and `details`.
- Reads, deletes and keyed creates are retried on `408`, `429` and `5xx` with backoff (2 retries
  by default).
- `jobs.create` and `jobs.batch` always send an `Idempotency-Key`, so a retry never starts a
  second job. To retry yourself, make the key once and reuse it:

```python
import kaabist
from kaabist import KaabError

key = kaabist.new_idempotency_key()
try:
    kaab.jobs.create(program="supplier-invoices@production", idempotency_key=key)
except KaabError as error:
    if error.code == "insufficient_credits":
        ...
    raise
```

A `connection_error` or `timeout` on a keyed call carries the key it sent in
`error.idempotency_key`: the job may already exist, and the same key returns it instead of creating
another.

## Configuration

| Argument | Default | |
|---|---|---|
| `api_key` | `KAAB_API_KEY` | `sk_live_…` or `sk_test_…` |
| `base_url` | `KAAB_BASE_URL`, then `https://api.kaab.ist/v1` | |
| `timeout` | 60 s | per attempt; a long-poll gets its wait on top |
| `max_retries` | `2` | retries after the first attempt |
| `headers` | none | sent with every request |
| `http_client` | a new `httpx.Client` | bring your own for proxies or tests |

Bodies can be given as keyword arguments, a mapping or a model; answers are typed models from
`kaabist.models`.

## Links

- [SDK guide](https://docs.kaab.ist/guides/sdks) and [API reference](https://docs.kaab.ist/reference/api)
- [Webhooks](https://docs.kaab.ist/guides/webhooks), [keys and test mode](https://docs.kaab.ist/getting-started/keys-and-modes)
- [API changelog](https://docs.kaab.ist/changelog) · support@kaab.ist

Versions follow the API: `1.40.x` speaks API 1.40. MIT licensed.
