# poke

The official [Poke](https://poke.com) Python SDK for sending messages to your Poke agent, creating webhook triggers, and firing webhooks.

Built by [Interaction Company](https://poke.com) in California.

## Installation

```bash
pip install poke
```

Zero dependencies. Works with Python 3.8+.

## Quick start

```python
from poke import Poke

client = Poke(api_key="pk_...")

# Send a message to your agent
client.send_message("Summarize my unread emails")

# Create a webhook trigger
webhook = client.create_webhook(
    condition="When a deploy fails",
    action="Send me a summary of the error",
)

# Fire the webhook with data
client.send_webhook(
    webhook_url=webhook["webhookUrl"],
    webhook_token=webhook["webhookToken"],
    data={"event": "deploy_failed", "repo": "my-app", "error": "OOM killed"},
)
```

### Authentication

The SDK resolves credentials in this order:

1. `api_key` passed to the constructor
2. `POKE_API_KEY` environment variable
3. Credentials from `poke login` (`~/.config/poke/credentials.json`)

```python
# Option 1: Pass directly
client = Poke(api_key="pk_...")

# Option 2: Set POKE_API_KEY in your environment
client = Poke()

# Option 3: Run `poke login` first, then
client = Poke()
```

Get your API key at [poke.com/kitchen/api-keys](https://poke.com/kitchen/api-keys).

### Methods

#### `client.send_message(message)`

Send a text message to your Poke agent.

```python
result = client.send_message("What meetings do I have today?")
# {"success": True, "message": "..."}
```

#### `client.create_webhook(condition, action)`

Create a webhook trigger. Returns a `webhookUrl` and `webhookToken` that you use with `send_webhook`.

```python
webhook = client.create_webhook(
    condition="When a new user signs up",
    action="Send me a welcome summary in Slack",
)
# {
#     "triggerId": "...",
#     "webhookUrl": "https://poke.com/api/v1/inbound/webhook",
#     "webhookToken": "eyJhbG..."
# }
```

#### `client.send_webhook(webhook_url, webhook_token, data)`

Fire a webhook trigger with data. Use the `webhook_url` and `webhook_token` returned by `create_webhook`.

```python
client.send_webhook(
    webhook_url=webhook["webhookUrl"],
    webhook_token=webhook["webhookToken"],
    data={"event": "new_signup", "email": "user@example.com", "plan": "pro"},
)
# {"success": True}
```

### Configuration

| Option | Environment Variable | Default |
|--------|---------------------|---------|
| `api_key` | `POKE_API_KEY` | — |
| `base_url` | `POKE_API` | `https://poke.com/api/v1` |

### Error handling

```python
from poke import Poke, AuthenticationError, ForbiddenError, RateLimitError, PokeError

client = Poke()

try:
    client.send_message("hello")
except AuthenticationError:
    print("Bad API key")
except ForbiddenError:
    print("Key lacks required scopes")
except RateLimitError:
    print("Slow down")
except PokeError as e:
    print(f"API error ({e.status}): {e}")
```

## Configuration

Credentials are stored in `~/.config/poke/credentials.json` (respects `$XDG_CONFIG_HOME`).

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `POKE_API_KEY` | API key for SDK usage | — |
| `POKE_API` | API base URL | `https://poke.com/api/v1` |
