Metadata-Version: 2.4
Name: flowmation
Version: 0.1.1
Summary: Official Python SDK for the FlowMation workflow automation API
License: MIT
Project-URL: Homepage, https://flowmation.mastechinnovations.xyz/
Project-URL: Documentation, https://flowmation.mastechinnovations.xyz/developers.html
Keywords: flowmation,workflow,automation,api-client,sdk,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# FlowMation Python SDK

Official zero-dependency client for the FlowMation workflow automation API. Uses only the Python standard library (urllib), supports Python 3.9+, and mirrors every endpoint in the [public developer guide](https://flowmation.mastechinnovations.xyz/developers.html).

## Install

```bash
pip install flowmation
```

To install a local checkout instead (for development):

```bash
pip install /path/to/this/sdk
```

## Quickstart

```python
import os

from flowmation import FlowMationClient

client = FlowMationClient(
    "https://flowmation-gateway.example.com",
    api_key=os.environ["FLOWMATION_API_KEY"],  # flm_live_* workspace key or flm_sess_* session token
)

overview = client.overview()
print("Active workflows:", overview.get("activeWorkflows"))

run = client.workflows.trigger("workflow-uuid", {"order": 42})
print("Run queued:", run["id"])
```

## Authentication

Two credential types work, both passed as `api_key` or `session_token`:

- **Workspace API key** (`flm_live_*`): tenant-scoped, ideal for servers. Sent as both `Authorization: Bearer` and `X-API-Key`.
- **User session token** (`flm_sess_*`): from `client.auth.login()`, `client.auth.register()`, or `client.auth.setup()`. Add `workspace_id` to target one of several workspaces the user belongs to (sent as `X-Workspace-ID`). Successful `login`, `register`, and `setup` calls store the returned token on the client automatically.

```python
client = FlowMationClient("https://gw.example.com")
client.auth.login("ops@yourdomain.com", "your-password")
workspaces = client.workspaces.list()
client.workspace_id = workspaces["workspaces"][0]["id"]
```

## API surface

| Group | Methods |
| --- | --- |
| `client.health()` | Gateway health snapshot |
| `client.auth` | `status`, `setup`, `register`, `login`, `logout`, `update_password` |
| `client.workspaces` | `list`, `create`, `switch`, `get`, `update`, `test_alert` |
| `client.overview()` | Active workflows, monthly tasks, managed message counters |
| `client.workflows` | `list`, `get`, `create`, `update`, `patch`, `set_status`, `remove`, `export`, `import_workflow`, `runs`, `run`, `trigger` |
| `client.runs` | `list`, `get`, `retry` |
| `client.connections` | `list`, `get`, `create`, `remove`, `set_credentials` |
| `client.api_keys` | `list`, `create`, `revoke` |
| `client.email_templates` | `list`, `create`, `remove` |
| `client.billing` | `get`, `checkout`, `cancel` |
| `client.request(method, path, ...)` | Escape hatch for any endpoint in the [developer guide](https://flowmation.mastechinnovations.xyz/developers.html) |

## Inbound webhook helper

Each workspace exposes tenant-isolated hook URLs (`/hooks/{workspaceSlug}/{path}`). Build them safely with:

```python
url = client.build_webhook_url("lagos-ops", "paystack")
# https://gw.example.com/hooks/lagos-ops/paystack
```

## Errors and retries

Non-2xx responses raise `FlowMationError` with `status`, `code` (when the API returns one, such as `plan_limit` or `workspace_suspended`), and `details` (the parsed body). HTTP 429 and 5xx responses are retried with backoff (default 2 retries) and honor `Retry-After`; tune with `max_retries` and `timeout`.

## Testing your integration

Pass a custom `transport` callable to stub the network in unit tests. It receives `(method, url, headers, body)` and returns `(status, headers, body_bytes)`:

```python
def fake_transport(method, url, headers, body):
    return 200, {"Content-Type": "application/json"}, b'{"ok": true}'

client = FlowMationClient("https://gw.example.com", api_key="flm_live_test", transport=fake_transport)
```

Run this package's own tests with `python3 -m unittest discover -s tests -t .` from `sdks/python`.

## Publishing (maintainers)

The package is MIT licensed; publishing the client does not publish any server code. Releases are cut by maintainers over CI when a GitHub release is published.
