workbench-sdk 1.3.0
Official Python SDK for the Workbench CRM API
License: MIT
Requires Python: >=3.9
Keywords: workbench, crm, api, sdk, invoices, quotes, jobs, clients

# workbench-sdk

Official Python SDK for the [Workbench CRM](https://tryworkbench.app) API.

## Installation

```bash
pip install workbench-sdk
```

## Quick Start

```python
from workbench import WorkbenchClient

# Initialize with your API key
client = WorkbenchClient(api_key="wbk_live_xxxxxxxxxxxxxxxxxxxxx")

# List clients
response = client.clients.list(status="active", per_page=10)
for c in response["data"]:
    print(f"{c['first_name']} {c['last_name']}")

# Create an invoice
invoice = client.invoices.create(
    client_id=response["data"][0]["id"],
    items=[
        {"description": "Consulting Services", "quantity": 2, "unit_price": 150}
    ],
    tax_rate=8.5
)

# Send the invoice
client.invoices.send(invoice["data"]["id"])
```

## Authentication

### API Key Authentication

Get your API key from [Workbench Settings > API Keys](https://app.tryworkbench.app/settings/api-keys).

```python
client = WorkbenchClient(api_key="wbk_live_xxxxxxxxxxxxxxxxxxxxx")
```

### OAuth Authentication

For third-party applications using OAuth 2.0:

```python
client = WorkbenchClient(access_token="wbk_at_xxxxxxxxxxxxxxxxxxxxx")
```

## Configuration

```python
client = WorkbenchClient(
    api_key="wbk_live_xxx",

    # Optional: Custom base URL (default: https://api.tryworkbench.app)
    base_url="https://api.tryworkbench.app",

    # Optional: Request timeout in seconds (default: 30)
    timeout=30.0,

    # Optional: Maximum retries for failed requests (default: 3)
    max_retries=3
)
```

## Context Manager

The client can be used as a context manager to ensure proper cleanup:

```python
with WorkbenchClient(api_key="wbk_live_xxx") as client:
    response = client.clients.list()
```

## Resources

### Clients

```python
# List clients
response = client.clients.list(
    status="active",
    search="john",
    page=1,
    per_page=20
)

# Get a client
result = client.clients.get("client-uuid")

# Create a client
new_client = client.clients.create(
    first_name="John",
    last_name="Doe",
    email="john@example.com",
    phone="+1-555-123-4567",
    company="Acme Corp",
    status="active",
    tags=["vip", "commercial"]
)

# Update a client
updated = client.clients.update("client-uuid", status="inactive")

# Delete a client
client.clients.delete("client-uuid")
```

### Invoices

```python
# List invoices
response = client.invoices.list(status="sent", client_id="client-uuid")

# Get an invoice
result = client.invoices.get("invoice-uuid")

# Create an invoice
invoice = client.invoices.create(
    client_id="client-uuid",
    due_date="2024-02-15",
    items=[
        {"description": "Web Development", "quantity": 10, "unit_price": 100},
        {"description": "Hosting Setup", "quantity": 1, "unit_price": 50}
    ],
    tax_rate=8.5,
    notes="Payment due within 30 days"
)

# Update an invoice
client.invoices.update("invoice-uuid", status="paid")

# Send an invoice
client.invoices.send("invoice-uuid")

# Delete an invoice
client.invoices.delete("invoice-uuid")
```

### Quotes

```python
# List quotes
response = client.quotes.list(status="sent")

# Create a quote
quote = client.quotes.create(
    client_id="client-uuid",
    valid_until="2024-03-01",
    items=[
        {"description": "Kitchen Renovation", "quantity": 1, "unit_price": 5000}
    ]
)

# Send a quote
client.quotes.send(quote["data"]["id"])
```

### Jobs

```python
# List jobs
response = client.jobs.list(status="scheduled", priority="high")

# Create a job
job = client.jobs.create(
    client_id="client-uuid",
    title="Kitchen Faucet Installation",
    priority="high",
    scheduled_start="2024-01-20T09:00:00Z",
    scheduled_end="2024-01-20T12:00:00Z"
)

# Update job status
client.jobs.update(job["data"]["id"], status="completed")
```

### Service Requests

```python
# List service requests
response = client.service_requests.list(status="new")

# Create a service request
request = client.service_requests.create(
    title="AC Repair",
    contact_name="Jane Smith",
    contact_email="jane@example.com",
    contact_phone="+1-555-987-6543",
    address="123 Main St",
    priority="urgent"
)
```

### Webhooks

```python
# List webhooks
response = client.webhooks.list()

# Create a webhook
webhook = client.webhooks.create(
    name="Invoice Notifications",
    url="https://example.com/webhooks/workbench",
    events=["invoice.created", "invoice.paid"]
)

# IMPORTANT: Store the webhook secret securely!
print(f"Webhook secret: {webhook['data']['secret']}")

# Update a webhook
client.webhooks.update(
    webhook["data"]["id"],
    events=["invoice.created", "invoice.paid", "invoice.overdue"]
)

# Delete a webhook
client.webhooks.delete(webhook["data"]["id"])
```

## Webhook Signature Verification

Verify that webhooks are actually from Workbench:

```python
from workbench import verify_webhook_signature, construct_webhook_event, WebhookVerificationError
import os

# In your webhook handler (e.g., Flask)
@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get("X-Workbench-Signature")
    secret = os.environ["WEBHOOK_SECRET"]

    try:
        # Option 1: Just verify
        verify_webhook_signature(payload, signature, secret)
        event = json.loads(payload)

        # Option 2: Verify and parse in one step
        event = construct_webhook_event(payload, signature, secret)

        # Handle the event
        if event["event"] == "invoice.paid":
            print(f"Invoice paid: {event['data']['id']}")
        elif event["event"] == "client.created":
            print(f"New client: {event['data']['first_name']}")

        return "", 200

    except WebhookVerificationError as e:
        print(f"Webhook verification failed: {e}")
        return "", 400
```

## Error Handling

```python
from workbench import WorkbenchClient, WorkbenchError

try:
    result = client.clients.get("invalid-uuid")
except WorkbenchError as e:
    print(f"API Error: {e.message}")
    print(f"Status: {e.status}")
    print(f"Code: {e.code}")
    print(f"Request ID: {e.request_id}")

    if e.details:
        for detail in e.details:
            print(f"  {detail['field']}: {detail['message']}")
```

## Type Hints

This SDK includes full type hints for better IDE support:

```python
from workbench import WorkbenchClient
from workbench.types import Client, Invoice, CreateClientParams

client = WorkbenchClient(api_key="wbk_live_xxx")

# Types are inferred
response = client.clients.list()  # ListResponse[Client]
data = response["data"]  # List[Client]

result = client.invoices.get("uuid")  # ApiResponse[Invoice]
invoice = result["data"]  # Invoice
```

## API Documentation

For complete API documentation, visit [docs.tryworkbench.app](https://docs.tryworkbench.app).

## Support

- **Documentation**: [docs.tryworkbench.app](https://docs.tryworkbench.app)
- **Issues**: [GitHub Issues](https://github.com/KoalityCRM/workbench-sdk-python/issues)
- **Email**: support@tryworkbench.app

## License

MIT License - see [LICENSE](LICENSE) for details.