Metadata-Version: 2.4
Name: callingbox
Version: 0.1.0
Summary: Python SDK for CallingBox – the API for AI phone calls
Project-URL: Homepage, https://callingbox.io
Project-URL: Documentation, https://docs.callingbox.io
Project-URL: Repository, https://github.com/callingbox/callingbox-python
License-Expression: MIT
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27
Provides-Extra: cli
Requires-Dist: rich>=13; extra == 'cli'
Requires-Dist: shellingham>=1.5; extra == 'cli'
Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'cli'
Requires-Dist: typer>=0.12; extra == 'cli'
Description-Content-Type: text/markdown

# CallingBox Python SDK

The official Python SDK for [CallingBox](https://callingbox.io) – the API for AI phone calls.

## Install

```bash
pip install callingbox
```

## Quick Start

```python
import callingbox

# Search and purchase a number (one-time setup)
available = callingbox.numbers.search_available(area_code="415")
number = callingbox.numbers.purchase(available[0].phone_number)

# Make a call – uses your oldest purchased number by default
call = callingbox.calls.create(
    to="+15551234567",
    prompt="Confirm appointment tomorrow 2pm",
    context={"patient": "Maria Lopez"},
    returns={"confirmed": "boolean"},
)

print(call.status)    # "initiated"
print(call.id)        # uuid
```

## Example

There's a runnable quickstart in `[examples/quickstart.py](examples/quickstart.py)` that walks through the full flow — buying a number, making a call, polling for results:

```bash
export CALLINGBOX_API_KEY=sk_live_...
python examples/quickstart.py +15551234567
```

## Authentication

Set your API key as an environment variable:

```bash
export CALLINGBOX_API_KEY=sk_live_...
```

Or pass it directly:

```python
from callingbox import Callingbox

client = Callingbox(api_key="sk_live_...")
call = client.calls.create(to="+15551234567", prompt="Hello")
```

## Choosing a Caller ID

By default, calls use your organization's oldest active purchased number. To use a specific number:

```python
call = callingbox.calls.create(
    to="+15551234567",
    prompt="Confirm appointment tomorrow 2pm",
    from_="+15557654321",
)
```

The `from_` parameter accepts any active E.164 number owned by your organization.

## Managing Numbers

```python
# List your numbers
numbers = callingbox.numbers.list()

# Search available numbers
available = callingbox.numbers.search_available(
    country_code="US",
    area_code="415",
    number_type="local",
    limit=10,
)

# Purchase a number
number = callingbox.numbers.purchase("+14155551234")
```

## Retrieving Calls

```python
# List recent calls
calls = callingbox.calls.list()

# Get a specific call
call = callingbox.calls.retrieve("call-uuid-here")
print(call.result)  # structured data extracted from the call
```

## CLI

The SDK ships with an optional command-line interface. Install the extras:

```bash
pip install 'callingbox[cli]'
```

Log in once (the key is stored in `~/.config/callingbox/config.toml` with mode `0600`):

```bash
callingbox login
# or non-interactively:
callingbox login --api-key sk_live_...
```

Dispatch a call and wait for the structured result:

```bash
callingbox call \
  --to "+15551234567" \
  --prompt "Confirm appointment tomorrow 2pm" \
  --returns '{"confirmed": "boolean"}'
```

Add `--transcript` to also print what each side said once the call completes:

```bash
callingbox call \
  --to "+15551234567" \
  --prompt "Confirm appointment tomorrow 2pm" \
  --transcript
```

Other useful commands:

```bash
callingbox calls list --limit 20          # paginated; add --all to fetch every page
callingbox calls get <call-id>
callingbox numbers list
callingbox numbers search --area-code 415
callingbox numbers buy +14155551234
callingbox whoami                          # shows the active credentials source
```

Add `--json` to any command (or pipe the output) to get machine-readable JSON.
Credential resolution order: `--api-key` flag > `CALLINGBOX_API_KEY` env > config
file. Shell completions install with `callingbox --install-completion`.

## Error Handling

```python
from callingbox import AuthenticationError, BadRequestError, NotFoundError, APIError

try:
    call = callingbox.calls.create(to="+15551234567")
except BadRequestError as e:
    print(f"Invalid request: {e.message}")
except AuthenticationError:
    print("Check your API key")
except NotFoundError:
    print("Resource not found")
except APIError as e:
    print(f"API error [{e.status_code}]: {e.message}")
```

