formbridge-sdk 0.1.0__py3-none-any.whl

formbridge/__init__.py

@@ -0,0 +1,14 @@
+"""FormBridge Python SDK — async and sync HTTP client."""
+
+from formbridge.client import FormBridgeClient, FormBridgeClientSync
+from formbridge.errors import FormBridgeError
+from formbridge.types import Actor, FieldsResult, Submission
+
+__all__ = [
+    "FormBridgeClient",
+    "FormBridgeClientSync",
+    "FormBridgeError",
+    "Actor",
+    "FieldsResult",
+    "Submission",
+]

formbridge/client.py

@@ -0,0 +1,387 @@
+"""FormBridge async and sync HTTP clients.
+
+Usage::
+
+    async with FormBridgeClient() as client:
+        sub = await client.create_submission("vendor-onboarding", fields={"company": "Acme"})
+        result = await client.set_fields(sub.intake_id, sub.submission_id, sub.resume_token, {"email": "a@b.com"})
+        final = await client.submit(sub.intake_id, sub.submission_id, result.resume_token)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Any, Dict, Optional
+
+try:
+    import httpx
+except ImportError:
+    raise ImportError("httpx is required. Install with: pip install formbridge-sdk")
+
+from formbridge.errors import FormBridgeError
+from formbridge.types import Actor, FieldsResult, Submission
+
+logger = logging.getLogger("formbridge.client")
+
+_DEFAULT_URL = "http://localhost:3000"
+_DEFAULT_TIMEOUT = 10.0
+_RETRY_BACKOFFS = [0.5, 1.0, 2.0]
+_RETRYABLE_STATUS = {429, 500, 502, 503, 504}
+
+
+def _serialize_actor(actor: Optional[Actor]) -> Optional[Dict[str, Any]]:
+    if actor is None:
+        return None
+    d: Dict[str, Any] = {"kind": actor.kind, "id": actor.id}
+    if actor.name is not None:
+        d["name"] = actor.name
+    return d
+
+
+class FormBridgeClient:
+    """Async HTTP client for FormBridge API.
+
+    Parameters:
+        url: Base URL. Defaults to ``FORMBRIDGE_URL`` env var or ``http://localhost:3000``.
+        api_key: API key for Bearer auth. Defaults to ``FORMBRIDGE_API_KEY`` env var.
+        timeout: Request timeout in seconds. Defaults to ``FORMBRIDGE_TIMEOUT`` env var or 10.
+        max_retries: Max retry attempts on 429/5xx (default 3).
+    """
+
+    def __init__(
+        self,
+        url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: int = 3,
+    ) -> None:
+        self._url = (url or os.environ.get("FORMBRIDGE_URL", _DEFAULT_URL)).rstrip("/")
+        self._api_key = api_key or os.environ.get("FORMBRIDGE_API_KEY", "")
+        raw_timeout = timeout if timeout is not None else os.environ.get("FORMBRIDGE_TIMEOUT")
+        self._timeout = float(raw_timeout) if raw_timeout is not None else _DEFAULT_TIMEOUT
+        self._max_retries = max_retries
+
+        headers: Dict[str, str] = {"Content-Type": "application/json"}
+        if self._api_key:
+            headers["Authorization"] = f"Bearer {self._api_key}"
+
+        self._http = httpx.AsyncClient(
+            base_url=self._url,
+            headers=headers,
+            timeout=self._timeout,
+        )
+
+    async def __aenter__(self) -> "FormBridgeClient":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.aclose()
+
+    # ── Public API ────────────────────────────────────────────────────
+
+    async def create_submission(
+        self,
+        intake_id: str,
+        *,
+        fields: Optional[Dict[str, Any]] = None,
+        actor: Optional[Actor] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Submission:
+        """Create a new submission.
+
+        Args:
+            intake_id: The intake definition ID.
+            fields: Optional initial field values.
+            actor: Optional actor performing the action.
+            idempotency_key: Optional idempotency key for deduplication.
+
+        Returns:
+            Submission with id, state, resume_token, etc.
+
+        Raises:
+            FormBridgeError: On API or connectivity error.
+        """
+        body: Dict[str, Any] = {}
+        if fields:
+            body["fields"] = fields
+        if actor:
+            body["actor"] = _serialize_actor(actor)
+        if idempotency_key:
+            body["idempotencyKey"] = idempotency_key
+
+        data = await self._request("POST", f"/intake/{intake_id}/submissions", json_data=body)
+        sub = Submission.from_response(data)
+        # API may not return intakeId on create; fill it in
+        if not sub.intake_id:
+            sub = Submission(
+                submission_id=sub.submission_id,
+                intake_id=intake_id,
+                state=sub.state,
+                resume_token=sub.resume_token,
+                fields=sub.fields,
+                missing_fields=sub.missing_fields,
+                schema=sub.schema,
+                created_at=sub.created_at,
+                updated_at=sub.updated_at,
+                raw=sub.raw,
+            )
+        return sub
+
+    async def set_fields(
+        self,
+        intake_id: str,
+        submission_id: str,
+        resume_token: str,
+        fields: Dict[str, Any],
+        actor: Optional[Actor] = None,
+    ) -> FieldsResult:
+        """Update fields on a submission.
+
+        Args:
+            intake_id: The intake definition ID.
+            submission_id: The submission ID.
+            resume_token: Current resume token.
+            fields: Field values to set.
+            actor: Optional actor performing the action.
+
+        Returns:
+            FieldsResult with new state, resume_token (may rotate), missing_fields.
+
+        Raises:
+            FormBridgeError: On API or connectivity error.
+        """
+        body: Dict[str, Any] = {
+            "resumeToken": resume_token,
+            "fields": fields,
+        }
+        if actor:
+            body["actor"] = _serialize_actor(actor)
+
+        data = await self._request(
+            "PATCH", f"/intake/{intake_id}/submissions/{submission_id}", json_data=body
+        )
+        return FieldsResult.from_response(data)
+
+    async def submit(
+        self,
+        intake_id: str,
+        submission_id: str,
+        resume_token: str,
+        *,
+        actor: Optional[Actor] = None,
+    ) -> Submission:
+        """Submit a submission for processing.
+
+        Args:
+            intake_id: The intake definition ID.
+            submission_id: The submission ID.
+            resume_token: Current resume token.
+            actor: Optional actor performing the action.
+
+        Returns:
+            Final Submission state.
+
+        Raises:
+            FormBridgeError: On API or connectivity error.
+        """
+        body: Dict[str, Any] = {"resumeToken": resume_token}
+        if actor:
+            body["actor"] = _serialize_actor(actor)
+
+        data = await self._request(
+            "POST", f"/intake/{intake_id}/submissions/{submission_id}/submit", json_data=body
+        )
+        return Submission.from_response(data)
+
+    async def get_submission(
+        self,
+        intake_id: str,
+        submission_id: str,
+    ) -> Submission:
+        """Get a submission by ID.
+
+        Args:
+            intake_id: The intake definition ID.
+            submission_id: The submission ID.
+
+        Returns:
+            Submission details.
+
+        Raises:
+            FormBridgeError: On API or connectivity error.
+        """
+        data = await self._request(
+            "GET", f"/intake/{intake_id}/submissions/{submission_id}"
+        )
+        return Submission.from_response(data)
+
+    # ── Internals ─────────────────────────────────────────────────────
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_data: Optional[Any] = None,
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry and graceful error handling."""
+        last_exc: Optional[Exception] = None
+        backoffs = _RETRY_BACKOFFS[: self._max_retries]
+
+        for attempt in range(1 + len(backoffs)):
+            try:
+                resp = await self._http.request(method, path, json=json_data)
+
+                if resp.status_code in _RETRYABLE_STATUS and attempt < len(backoffs):
+                    logger.warning(
+                        "FormBridge returned %d (attempt %d/%d), retrying in %.1fs",
+                        resp.status_code,
+                        attempt + 1,
+                        len(backoffs) + 1,
+                        backoffs[attempt],
+                    )
+                    await asyncio.sleep(backoffs[attempt])
+                    continue
+
+                data = resp.json()
+
+                if resp.status_code >= 400:
+                    error_info = data.get("error", {}) if isinstance(data, dict) else {}
+                    raise FormBridgeError(
+                        error_info.get("message", f"HTTP {resp.status_code}"),
+                        status_code=resp.status_code,
+                        error_type=error_info.get("type"),
+                        response_data=data,
+                    )
+
+                return data
+
+            except FormBridgeError:
+                raise
+            except (httpx.ConnectError, httpx.TimeoutException, httpx.ConnectTimeout) as exc:
+                last_exc = exc
+                if attempt < len(backoffs):
+                    logger.warning(
+                        "FormBridge connection error (attempt %d/%d): %s, retrying in %.1fs",
+                        attempt + 1,
+                        len(backoffs) + 1,
+                        exc,
+                        backoffs[attempt],
+                    )
+                    await asyncio.sleep(backoffs[attempt])
+                    continue
+                raise FormBridgeError(
+                    f"Connection failed: {exc}",
+                    is_connectivity_error=True,
+                ) from exc
+            except Exception as exc:
+                raise FormBridgeError(
+                    f"Unexpected error: {exc}",
+                    is_connectivity_error=True,
+                ) from exc
+
+        # Should not reach here
+        if last_exc:
+            raise FormBridgeError(
+                f"Connection failed after retries: {last_exc}",
+                is_connectivity_error=True,
+            ) from last_exc
+        raise RuntimeError("Retry loop exhausted unexpectedly")
+
+
+class FormBridgeClientSync:
+    """Synchronous wrapper around FormBridgeClient.
+
+    Works without an existing event loop. Creates its own loop internally.
+
+    Usage::
+
+        client = FormBridgeClientSync(api_key="sk-...")
+        sub = client.create_submission("vendor-onboarding", fields={"company": "Acme"})
+        client.close()
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._async_client = FormBridgeClient(**kwargs)
+
+    def __enter__(self) -> "FormBridgeClientSync":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._run(self._async_client.close())
+
+    def create_submission(
+        self,
+        intake_id: str,
+        *,
+        fields: Optional[Dict[str, Any]] = None,
+        actor: Optional[Actor] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Submission:
+        """Create a new submission. See :meth:`FormBridgeClient.create_submission`."""
+        return self._run(
+            self._async_client.create_submission(
+                intake_id, fields=fields, actor=actor, idempotency_key=idempotency_key
+            )
+        )
+
+    def set_fields(
+        self,
+        intake_id: str,
+        submission_id: str,
+        resume_token: str,
+        fields: Dict[str, Any],
+        actor: Optional[Actor] = None,
+    ) -> FieldsResult:
+        """Update fields on a submission. See :meth:`FormBridgeClient.set_fields`."""
+        return self._run(
+            self._async_client.set_fields(intake_id, submission_id, resume_token, fields, actor)
+        )
+
+    def submit(
+        self,
+        intake_id: str,
+        submission_id: str,
+        resume_token: str,
+        *,
+        actor: Optional[Actor] = None,
+    ) -> Submission:
+        """Submit a submission. See :meth:`FormBridgeClient.submit`."""
+        return self._run(
+            self._async_client.submit(intake_id, submission_id, resume_token, actor=actor)
+        )
+
+    def get_submission(
+        self,
+        intake_id: str,
+        submission_id: str,
+    ) -> Submission:
+        """Get a submission by ID. See :meth:`FormBridgeClient.get_submission`."""
+        return self._run(self._async_client.get_submission(intake_id, submission_id))
+
+    @staticmethod
+    def _run(coro: Any) -> Any:
+        """Run a coroutine in a new event loop (safe from any context)."""
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop and loop.is_running():
+            # We're inside an async context — use a thread
+            import concurrent.futures
+
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                return pool.submit(asyncio.run, coro).result()
+        else:
+            return asyncio.run(coro)

formbridge/errors.py

@@ -0,0 +1,31 @@
+"""Error types for FormBridge SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class FormBridgeError(Exception):
+    """Base error for FormBridge SDK.
+
+    Attributes:
+        status_code: HTTP status code (None for connectivity errors).
+        error_type: Error type from API response (e.g. 'not_found').
+        is_connectivity_error: True if the error is due to a connection failure.
+        response_data: Raw response body if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        error_type: Optional[str] = None,
+        is_connectivity_error: bool = False,
+        response_data: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_type = error_type
+        self.is_connectivity_error = is_connectivity_error
+        self.response_data = response_data

formbridge/types.py

@@ -0,0 +1,73 @@
+"""Response types for FormBridge SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class Actor:
+    """Submission actor."""
+
+    kind: str
+    id: str
+    name: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Submission:
+    """Submission returned by the API."""
+
+    submission_id: str
+    intake_id: str
+    state: str
+    resume_token: Optional[str] = None
+    fields: Dict[str, Any] = field(default_factory=dict)
+    missing_fields: Optional[List[str]] = None
+    schema: Optional[Dict[str, Any]] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_response(cls, data: Dict[str, Any]) -> "Submission":
+        """Parse API response into a Submission."""
+        return cls(
+            submission_id=data.get("submissionId", ""),
+            intake_id=data.get("intakeId", ""),
+            state=data.get("state", ""),
+            resume_token=data.get("resumeToken"),
+            fields=data.get("fields", {}),
+            missing_fields=data.get("missingFields"),
+            schema=data.get("schema"),
+            created_at=data.get("metadata", {}).get("createdAt")
+            if isinstance(data.get("metadata"), dict)
+            else data.get("createdAt"),
+            updated_at=data.get("metadata", {}).get("updatedAt")
+            if isinstance(data.get("metadata"), dict)
+            else data.get("updatedAt"),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True)
+class FieldsResult:
+    """Result from set_fields."""
+
+    submission_id: str
+    state: str
+    resume_token: str
+    missing_fields: Optional[List[str]] = None
+    raw: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_response(cls, data: Dict[str, Any]) -> "FieldsResult":
+        """Parse API response into a FieldsResult."""
+        return cls(
+            submission_id=data.get("submissionId", ""),
+            state=data.get("state", ""),
+            resume_token=data.get("resumeToken", ""),
+            missing_fields=data.get("missingFields"),
+            raw=data,
+        )

formbridge_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: formbridge-sdk
+Version: 0.1.0
+Summary: Python SDK for FormBridge — async and sync HTTP client
+Author: FormBridge Team
+License-Expression: MIT
+Keywords: formbridge,forms,sdk,submissions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# formbridge-sdk
+
+Python SDK for [FormBridge](https://github.com/agentkitai/formbridge) — async and sync HTTP client for managing form submissions.
+
+## Installation
+
+This SDK is not yet published to PyPI. Install it from source:
+
+```bash
+git clone https://github.com/agentkitai/formbridge.git
+pip install ./formbridge/sdk/python
+```
+
+## Quick Start (Async)
+
+```python
+import asyncio
+from formbridge import FormBridgeClient, Actor
+
+async def main():
+    async with FormBridgeClient(
+        url="http://localhost:3000",
+        api_key="your-api-key",
+    ) as client:
+        # Create a submission with initial fields
+        sub = await client.create_submission(
+            "vendor-onboarding",
+            fields={"company_name": "Acme Corp"},
+            actor=Actor(kind="agent", id="agent-1", name="Onboarding Bot"),
+        )
+        print(f"Created: {sub.submission_id}, state={sub.state}")
+        print(f"Missing fields: {sub.missing_fields}")
+
+        # Add more fields (resume_token rotates on each call)
+        result = await client.set_fields(
+            sub.intake_id,
+            sub.submission_id,
+            sub.resume_token,
+            {"contact_email": "alice@acme.com", "phone": "+1-555-0100"},
+        )
+        print(f"Updated: state={result.state}, missing={result.missing_fields}")
+
+        # Submit when all fields are filled
+        final = await client.submit(
+            sub.intake_id,
+            sub.submission_id,
+            result.resume_token,
+        )
+        print(f"Submitted: state={final.state}")
+
+        # Retrieve a submission
+        fetched = await client.get_submission(sub.intake_id, sub.submission_id)
+        print(f"Fields: {fetched.fields}")
+
+asyncio.run(main())
+```
+
+## Quick Start (Sync)
+
+```python
+from formbridge import FormBridgeClientSync, Actor
+
+with FormBridgeClientSync(api_key="your-api-key") as client:
+    sub = client.create_submission(
+        "vendor-onboarding",
+        fields={"company_name": "Acme Corp"},
+        actor=Actor(kind="agent", id="agent-1"),
+    )
+    print(f"Created: {sub.submission_id}")
+```
+
+## Configuration
+
+| Parameter | Env Var | Default |
+|-----------|---------|---------|
+| `url` | `FORMBRIDGE_URL` | `http://localhost:3000` |
+| `api_key` | `FORMBRIDGE_API_KEY` | — |
+| `timeout` | `FORMBRIDGE_TIMEOUT` | `10` (seconds) |
+
+## Error Handling
+
+```python
+from formbridge import FormBridgeClient, FormBridgeError
+
+async with FormBridgeClient() as client:
+    try:
+        sub = await client.get_submission("intake-1", "sub-123")
+    except FormBridgeError as e:
+        if e.is_connectivity_error:
+            print("Server unreachable — degrade gracefully")
+        elif e.status_code == 404:
+            print("Not found")
+        else:
+            print(f"API error: {e.error_type} — {e}")
+```
+
+## Retry Behavior
+
+- **Retries on:** 429 (rate limited), 500, 502, 503, 504
+- **Does NOT retry on:** 400, 401, 403, 404 (client errors)
+- **Backoff:** 0.5s → 1.0s → 2.0s (exponential)
+- **Max retries:** 3 (configurable via `max_retries`)
+
+## License
+
+MIT

formbridge_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+formbridge/__init__.py,sha256=k4W7Z4XnpDK3P5mxLINfpf1xLCx4ccRSxi_43ioHDG4,392
+formbridge/client.py,sha256=HwlRJAFiEG4XqYAdeVjofA_mrduC_CWbmT5cFIC6lxQ,13327
+formbridge/errors.py,sha256=sXh5Mt8MlvjJKN40xy8GA6RvwEHaAF07X6vlFdO9YmU,998
+formbridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+formbridge/types.py,sha256=-K3M0HyLAocvAx9piOsVVxbSLve1GvNNS63eJUeO95I,2297
+formbridge_sdk-0.1.0.dist-info/METADATA,sha256=PZKEueirSZgL3uPF61SafZljG5IcxomQA4G0oEV0MnI,3730
+formbridge_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+formbridge_sdk-0.1.0.dist-info/RECORD,,

formbridge_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any