syncteams-sdk 0.2.0__tar.gz

syncteams_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-10-28
+
+### Added
+- Initial Python SDK release
+- `WorkflowClient` with full API support
+- `execute_workflow`, `get_task_status`, `continue_task` methods
+- `wait_for_completion` with polling and callbacks
+- `execute_and_wait` convenience method with approval handling
+- Automatic retry with exponential backoff
+- Type hints and comprehensive error handling
+- Unit tests with pytest
+
+### Features
+- Full parity with JavaScript SDK
+- Python 3.9+ support
+- Async-friendly polling with stop events
+- Webhook event type definitions
+- Detailed error responses with `WorkflowAPIError`

syncteams_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SyncTeams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

syncteams_sdk-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+recursive-include src *.py
+recursive-include src py.typed
+prune tests
+prune .github
+global-exclude __pycache__
+global-exclude *.py[co]

syncteams_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.2
+Name: syncteams-sdk
+Version: 0.2.0
+Summary: Python client for the SyncTeams Workflow API
+Author-email: SyncTeams <support@syncteams.studio>
+Project-URL: Homepage, https://develop.syncteams.studio
+Project-URL: Repository, https://github.com/syncteamsstudio/python-sdk.git
+Project-URL: Documentation, https://develop.syncteams.studio
+Keywords: workflow,automation,syncteams,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: typing-extensions>=4.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: responses>=0.25.0; extra == "dev"
+Requires-Dist: coverage>=7.3; extra == "dev"
+
+# SyncTeams Workflow SDK (Python)
+
+A Python client for the SyncTeams Workflow API. Mirrors the capabilities of the JavaScript SDK, offering convenient helpers to execute workflows, monitor task status, and manage approval flows.
+
+---
+
+## Installation
+
+```bash
+pip install syncteams-sdk
+```
+
+**Requirements:** Python 3.9 or newer
+
+---
+
+## Quick Start
+
+```python
+from syncteams_sdk import WorkflowClient
+
+client = WorkflowClient(api_key="YOUR_API_KEY")
+
+# Execute a workflow
+result = client.execute_workflow(
+    workflow_id="your_workflow_id",
+    input={"email": "user@example.com"},
+    unique_id="customer-123",
+)
+
+task_id = result["taskId"]
+
+# Wait for completion
+final_status = client.wait_for_completion(
+    task_id,
+    poll_interval_ms=2_000,
+    on_update=lambda status: print(f"Status: {status['status']}")
+)
+
+if final_status["status"] == "COMPLETED":
+    print("Workflow completed successfully!")
+```
+
+---
+
+## Configuration
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `api_key` | ✅ | – | Your SyncTeams API key |
+| `base_url` | ❌ | `https://develop.api.syncteams.studio` | API base URL |
+| `timeout_ms` | ❌ | `30000` | Request timeout in milliseconds |
+| `retry` | ❌ | See below | Retry configuration for failed requests |
+| `default_headers` | ❌ | `{}` | Extra headers merged into every request |
+| `user_agent_suffix` | ❌ | – | Extra token appended to the default User-Agent |
+
+### Retry Configuration
+
+By default, the SDK retries transient failures with exponential backoff:
+- Maximum attempts: 3
+- Initial delay: 1 second
+- Backoff factor: 2x
+- Maximum delay: 30 seconds
+- Retries on: 408, 425, 429, and all 5xx responses
+
+You can override any subset of these values when constructing the client.
+
+---
+
+## API overview
+
+### `execute_workflow(workflow_id, input, unique_id=None)`
+
+Starts a workflow execution.
+
+```python
+response = client.execute_workflow(
+    workflow_id="your_workflow_id",
+    input={"customer_id": "cust-123"},
+)
+
+print(response["taskId"], response["status"])
+```
+
+Returns the `taskId` and initial status.
+
+### `get_task_status(task_id)`
+
+Fetches the latest status and the filtered event log for a task.
+
+```python
+status = client.get_task_status(task_id)
+print(status["status"], len(status.get("eventLogs", [])))
+```
+
+### `continue_task(task_id, decision, message=None)`
+
+Resumes a waiting workflow after an approval decision.
+
+```python
+client.continue_task(task_id=task_id, decision="APPROVE")
+
+client.continue_task(
+    task_id=task_id,
+    decision="REJECT",
+    message="Missing documentation",
+)
+```
+
+When `decision` is `"REJECT"`, `message` is required.
+
+### `wait_for_completion(task_id, *, poll_interval_ms=2000, max_wait_time_ms=600000, on_update=None, exit_on_waiting=False, terminal_statuses=None, stop_event=None)`
+
+Polls a task until it reaches a terminal status (`COMPLETED`, `FAILED`, or `CANCELED`).
+
+```python
+final_status = client.wait_for_completion(
+    task_id,
+    poll_interval_ms=1000,
+    on_update=lambda payload: print("Status:", payload["status"]),
+)
+```
+
+### `execute_and_wait(workflow_id, input, **options)`
+
+Convenience method that starts a workflow and optionally handles approvals via `on_waiting`.
+
+```python
+def handle_waiting(status):
+    # Perform approval logic
+    client.continue_task(task_id=status["taskId"], decision="APPROVE")
+    return True
+
+result = client.execute_and_wait(
+    workflow_id="wf-123",
+    input={"amount": 500},
+    on_waiting=handle_waiting,
+)
+```
+
+If `on_waiting` returns `False`, polling stops and the SDK returns the current status (even if still waiting).
+
+---
+
+## Error Handling
+
+The SDK raises `WorkflowAPIError` for API failures. It exposes the HTTP status, headers, response payload, and request metadata to simplify debugging.
+
+```python
+from syncteams_sdk import WorkflowAPIError
+
+try:
+    client.execute_workflow(workflow_id="invalid", input={})
+except WorkflowAPIError as error:
+    print("API error:", error.status, error.data)
+```
+
+Transient errors (timeouts, rate limits, server errors) are automatically retried according to the configured policy.
+
+---
+
+## Webhooks
+
+You can receive workflow updates via webhooks instead of polling:
+
+```python
+from flask import Flask, request
+from syncteams_sdk import WebhookEventPayload
+
+app = Flask(__name__)
+
+@app.post("/webhooks/syncteams")
+def handle_webhook():
+    payload: WebhookEventPayload = request.get_json(force=True)
+    print("Task", payload["taskId"], "status:", payload["status"])
+    return ("", 200)
+```
+
+---
+
+## Development
+
+Install dependencies and run tests:
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+---
+
+## License
+
+MIT

syncteams_sdk-0.2.0/README.md

@@ -0,0 +1,194 @@
+# SyncTeams Workflow SDK (Python)
+
+A Python client for the SyncTeams Workflow API. Mirrors the capabilities of the JavaScript SDK, offering convenient helpers to execute workflows, monitor task status, and manage approval flows.
+
+---
+
+## Installation
+
+```bash
+pip install syncteams-sdk
+```
+
+**Requirements:** Python 3.9 or newer
+
+---
+
+## Quick Start
+
+```python
+from syncteams_sdk import WorkflowClient
+
+client = WorkflowClient(api_key="YOUR_API_KEY")
+
+# Execute a workflow
+result = client.execute_workflow(
+    workflow_id="your_workflow_id",
+    input={"email": "user@example.com"},
+    unique_id="customer-123",
+)
+
+task_id = result["taskId"]
+
+# Wait for completion
+final_status = client.wait_for_completion(
+    task_id,
+    poll_interval_ms=2_000,
+    on_update=lambda status: print(f"Status: {status['status']}")
+)
+
+if final_status["status"] == "COMPLETED":
+    print("Workflow completed successfully!")
+```
+
+---
+
+## Configuration
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `api_key` | ✅ | – | Your SyncTeams API key |
+| `base_url` | ❌ | `https://develop.api.syncteams.studio` | API base URL |
+| `timeout_ms` | ❌ | `30000` | Request timeout in milliseconds |
+| `retry` | ❌ | See below | Retry configuration for failed requests |
+| `default_headers` | ❌ | `{}` | Extra headers merged into every request |
+| `user_agent_suffix` | ❌ | – | Extra token appended to the default User-Agent |
+
+### Retry Configuration
+
+By default, the SDK retries transient failures with exponential backoff:
+- Maximum attempts: 3
+- Initial delay: 1 second
+- Backoff factor: 2x
+- Maximum delay: 30 seconds
+- Retries on: 408, 425, 429, and all 5xx responses
+
+You can override any subset of these values when constructing the client.
+
+---
+
+## API overview
+
+### `execute_workflow(workflow_id, input, unique_id=None)`
+
+Starts a workflow execution.
+
+```python
+response = client.execute_workflow(
+    workflow_id="your_workflow_id",
+    input={"customer_id": "cust-123"},
+)
+
+print(response["taskId"], response["status"])
+```
+
+Returns the `taskId` and initial status.
+
+### `get_task_status(task_id)`
+
+Fetches the latest status and the filtered event log for a task.
+
+```python
+status = client.get_task_status(task_id)
+print(status["status"], len(status.get("eventLogs", [])))
+```
+
+### `continue_task(task_id, decision, message=None)`
+
+Resumes a waiting workflow after an approval decision.
+
+```python
+client.continue_task(task_id=task_id, decision="APPROVE")
+
+client.continue_task(
+    task_id=task_id,
+    decision="REJECT",
+    message="Missing documentation",
+)
+```
+
+When `decision` is `"REJECT"`, `message` is required.
+
+### `wait_for_completion(task_id, *, poll_interval_ms=2000, max_wait_time_ms=600000, on_update=None, exit_on_waiting=False, terminal_statuses=None, stop_event=None)`
+
+Polls a task until it reaches a terminal status (`COMPLETED`, `FAILED`, or `CANCELED`).
+
+```python
+final_status = client.wait_for_completion(
+    task_id,
+    poll_interval_ms=1000,
+    on_update=lambda payload: print("Status:", payload["status"]),
+)
+```
+
+### `execute_and_wait(workflow_id, input, **options)`
+
+Convenience method that starts a workflow and optionally handles approvals via `on_waiting`.
+
+```python
+def handle_waiting(status):
+    # Perform approval logic
+    client.continue_task(task_id=status["taskId"], decision="APPROVE")
+    return True
+
+result = client.execute_and_wait(
+    workflow_id="wf-123",
+    input={"amount": 500},
+    on_waiting=handle_waiting,
+)
+```
+
+If `on_waiting` returns `False`, polling stops and the SDK returns the current status (even if still waiting).
+
+---
+
+## Error Handling
+
+The SDK raises `WorkflowAPIError` for API failures. It exposes the HTTP status, headers, response payload, and request metadata to simplify debugging.
+
+```python
+from syncteams_sdk import WorkflowAPIError
+
+try:
+    client.execute_workflow(workflow_id="invalid", input={})
+except WorkflowAPIError as error:
+    print("API error:", error.status, error.data)
+```
+
+Transient errors (timeouts, rate limits, server errors) are automatically retried according to the configured policy.
+
+---
+
+## Webhooks
+
+You can receive workflow updates via webhooks instead of polling:
+
+```python
+from flask import Flask, request
+from syncteams_sdk import WebhookEventPayload
+
+app = Flask(__name__)
+
+@app.post("/webhooks/syncteams")
+def handle_webhook():
+    payload: WebhookEventPayload = request.get_json(force=True)
+    print("Task", payload["taskId"], "status:", payload["status"])
+    return ("", 200)
+```
+
+---
+
+## Development
+
+Install dependencies and run tests:
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+---
+
+## License
+
+MIT

syncteams_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0.0,<77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "syncteams-sdk"
+version = "0.2.0"
+description = "Python client for the SyncTeams Workflow API"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [
+  {name = "SyncTeams", email = "support@syncteams.studio"}
+]
+dependencies = [
+  "requests>=2.31.0",
+  "typing-extensions>=4.8.0"
+]
+keywords = ["workflow", "automation", "syncteams", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4",
+  "responses>=0.25.0",
+  "coverage>=7.3"
+]
+
+[project.urls]
+Homepage = "https://develop.syncteams.studio"
+Repository = "https://github.com/syncteamsstudio/python-sdk.git"
+Documentation = "https://develop.syncteams.studio"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

syncteams_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

syncteams_sdk-0.2.0/src/__init__.py

@@ -0,0 +1,47 @@
+"""Public package API for the SyncTeams Workflow Python SDK."""
+from __future__ import annotations
+
+from ._version import __version__
+from .errors import WorkflowAPIError, is_workflow_api_error
+from .types import (
+    ApprovalDecision,
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_WAIT_TIME_MS,
+    DEFAULT_POLL_INTERVAL_MS,
+    DEFAULT_REQUEST_TIMEOUT_MS,
+    ExecuteAndWaitOptions,
+    ExecuteWorkflowInput,
+    ExecuteWorkflowResponse,
+    TaskEventLog,
+    TaskStatusResponse,
+    WaitForCompletionOptions,
+    WebhookEventPayload,
+    WorkflowClientOptions,
+    WorkflowClientRetryConfig,
+    WorkflowEventType,
+    WorkflowStatus,
+)
+from .workflow_client import WorkflowClient
+
+__all__ = [
+    "WorkflowClient",
+    "WorkflowAPIError",
+    "is_workflow_api_error",
+    "WorkflowStatus",
+    "WorkflowEventType",
+    "ApprovalDecision",
+    "TaskEventLog",
+    "ExecuteWorkflowInput",
+    "ExecuteWorkflowResponse",
+    "TaskStatusResponse",
+    "WebhookEventPayload",
+    "WorkflowClientOptions",
+    "WorkflowClientRetryConfig",
+    "WaitForCompletionOptions",
+    "ExecuteAndWaitOptions",
+    "DEFAULT_REQUEST_TIMEOUT_MS",
+    "DEFAULT_POLL_INTERVAL_MS",
+    "DEFAULT_MAX_WAIT_TIME_MS",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]

syncteams_sdk-0.2.0/src/_version.py

@@ -0,0 +1,4 @@
+"""Package version, shared between packaging metadata and runtime."""
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

syncteams_sdk-0.2.0/src/errors.py

@@ -0,0 +1,61 @@
+"""Custom exceptions raised by the SyncTeams Python SDK."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Mapping, MutableMapping, Optional, Union
+
+from .types import Headers, RequestDescriptor
+
+ErrorResponseData = Union[Mapping[str, Any], str, None]
+
+
+@dataclass
+class WorkflowAPIErrorRequest:
+    method: str
+    url: str
+    body: Optional[Any] = None
+
+
+class WorkflowAPIError(Exception):
+    """Raised when the SyncTeams API returns an error response."""
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        status: int,
+        status_text: str,
+        headers: Mapping[str, str] | Headers,
+        data: ErrorResponseData,
+        request: RequestDescriptor,
+        cause: Exception | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.status_text = status_text
+        self.headers = dict(headers)
+        self.data = data
+        self.request = request
+        self.cause = cause
+
+    def __repr__(self) -> str:  # pragma: no cover - repr convenience
+        return (
+            f"WorkflowAPIError(status={self.status!r}, message={self.args[0]!r}, "
+            f"url={self.request.url!r})"
+        )
+
+
+def is_workflow_api_error(error: Exception) -> bool:
+    """Return ``True`` if *error* is a :class:`WorkflowAPIError`."""
+
+    return isinstance(error, WorkflowAPIError)
+
+
+def normalize_headers(headers: Mapping[str, str] | Headers | None) -> Dict[str, str]:
+    if headers is None:
+        return {}
+
+    if isinstance(headers, MutableMapping):
+        return dict(headers)
+
+    return {key: value for key, value in headers.items()}