Metadata-Version: 2.5
Name: genorbex-connectors
Version: 0.1.0
Summary: Python clients for Genorbex and its GitHub, Gmail, S3, WhatsApp, Calendly, Datadog, Outlook, and Supabase connectors
Author: Genorbex
License: MIT
License-File: LICENSE
Keywords: connectors,genorbex,integrations,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: boto3>=1.34; extra == 'all'
Requires-Dist: psycopg[binary]>=3.1; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3>=1.34; extra == 'aws'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Description-Content-Type: text/markdown

# Genorbex Connectors for Python

A small, synchronous Python SDK for the connector types displayed in Genorbex:
GitHub, Google Gmail, Amazon S3, WhatsApp Cloud API, Calendly, Datadog,
Microsoft Outlook, and Supabase.

The package has no mandatory runtime dependency. Install extras only for S3 or
direct PostgreSQL access:

```bash
pip install -e packages/genorbex-connectors-python
pip install -e 'packages/genorbex-connectors-python[all]'
```

## Use connector instances already configured in Genorbex

This is the preferred approach for Gmail, GitHub, Outlook, and other OAuth
connectors because Genorbex keeps and refreshes their tokens. Pass either an API
bearer token supported by your deployment or an authenticated session cookie.

```python
from genorbex_connectors import GenorbexClient

orbex = GenorbexClient(
    "https://www.genorbex.com",
    api_token="your-api-token",
    # Or: session_cookie="next-auth.session-token=...",
)

instances = orbex.list_instances(active=True)["instances"]
github = next(item for item in instances if item["connectorId"] == "github")

print(orbex.test_instance(github["id"]))
print(orbex.query_instance(github["id"], table="repositories", limit=20))
orbex.start_sync(github["id"])
```

Do not embed a browser session cookie in deployed code. Use a deployment API
token when available and keep it in a secret manager.

## Connect directly to providers

```python
from genorbex_connectors import GitHubConnector, WhatsAppConnector

github = GitHubConnector(access_token="...")
if github.test_connection():
    print(github.list_repositories())

whatsapp = WhatsAppConnector(access_token="...", phone_number_id="...")
whatsapp.send_text("447700900123", "Hello from Python")
```

Every direct client exposes `request(method, path, ...)` for provider operations
that do not yet have a convenience method.

## Environment factory

```python
from genorbex_connectors import connector_from_env, test_all

connectors = {
    name: connector_from_env(name)
    for name in ("github", "gmail", "s3", "whatsapp", "calendly", "datadog", "microsoft_outlook", "supabase")
}
for name, result in test_all(connectors).items():
    print(name, result.success, result.message)
```

Supported variables:

| Connector | Environment variables |
|---|---|
| GitHub | `GITHUB_ACCESS_TOKEN` |
| Gmail | `GMAIL_ACCESS_TOKEN` |
| S3 | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `AWS_S3_BUCKET`; optional `AWS_SESSION_TOKEN` |
| WhatsApp | `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`; optional `WHATSAPP_BASE_URL` |
| Calendly | `CALENDLY_API_TOKEN`; optional `CALENDLY_USER_URI`, `CALENDLY_ORGANIZATION_URI` |
| Datadog | `DATADOG_API_KEY`, `DATADOG_APP_KEY`; optional `DATADOG_SITE` |
| Outlook | `OUTLOOK_ACCESS_TOKEN` |
| Supabase REST | `SUPABASE_URL`, `SUPABASE_KEY` |
| Supabase Management | `SUPABASE_ACCESS_TOKEN`, `SUPABASE_PROJECT_REF` |
| Supabase PostgreSQL | `SUPABASE_DB_HOST`, `SUPABASE_DB_PASSWORD`; optional `SUPABASE_DB_PORT`, `SUPABASE_DB_NAME`, `SUPABASE_DB_USER` |

`test_connection()` returns a `ConnectionResult` rather than raising for normal
connection failures. Operational methods raise `ConnectorError` with the HTTP
status and parsed response body when an API rejects a request.

