formbridge-sdk 0.1.0__tar.gz

formbridge_sdk-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Auto Claude data directory
+.auto-claude/
+
+# Auto Claude machine-specific config
+.auto-claude-security.json
+.auto-claude-status
+.claude_settings.json
+
+# Development verification artifacts
+*VERIFICATION*.md
+
+# Dependencies
+node_modules/
+
+# Python virtual environment
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+
+# Coverage reports
+.coverage
+coverage/
+coverage-report.json
+
+# Environment files
+.env
+.env.*
+!.env.example
+.env.local
+.env.*.local
+
+# Build outputs
+dist/
+*.tsbuildinfo
+
+# Compiled output accidentally emitted into src/
+src/*.js
+src/*.js.map
+src/*.d.ts
+src/*.d.ts.map
+src/**/*.js
+src/**/*.js.map
+src/**/*.d.ts
+src/**/*.d.ts.map
+
+# SQLite runtime files
+*.db
+*.db-shm
+*.db-wal
+
+# BMAD planning artifacts
+_bmad/
+_bmad-output/

formbridge_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "formbridge-sdk"
+version = "0.1.0"
+description = "Python SDK for FormBridge — async and sync HTTP client"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "FormBridge Team" }]
+keywords = ["formbridge", "sdk", "forms", "submissions"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24.0"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-asyncio>=0.21", "respx>=0.21", "ruff>=0.1"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/formbridge"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"

formbridge_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,266 @@
+"""Unit tests for FormBridge SDK client."""
+
+from __future__ import annotations
+
+import pytest
+import httpx
+import respx
+
+from formbridge import (
+    FormBridgeClient,
+    FormBridgeClientSync,
+    FormBridgeError,
+    Actor,
+)
+
+BASE_URL = "http://test-formbridge:3000"
+
+
+@pytest.fixture
+def client():
+    return FormBridgeClient(url=BASE_URL, api_key="test-key")
+
+
+@pytest.fixture
+def sync_client():
+    return FormBridgeClientSync(url=BASE_URL, api_key="test-key")
+
+
+# ── Auth Header ──────────────────────────────────────────────────────
+
+
+@respx.mock
+async def test_auth_header(client: FormBridgeClient):
+    """Bearer token sent on all requests."""
+    route = respx.get(f"{BASE_URL}/intake/test/submissions/sub1").mock(
+        return_value=httpx.Response(200, json={
+            "ok": True, "submissionId": "sub1", "intakeId": "test",
+            "state": "draft", "fields": {},
+        })
+    )
+    await client.get_submission("test", "sub1")
+    assert route.called
+    assert route.calls[0].request.headers["authorization"] == "Bearer test-key"
+    await client.close()
+
+
+# ── create_submission ─────────────────────────────────────────────────
+
+
+@respx.mock
+async def test_create_submission_success(client: FormBridgeClient):
+    respx.post(f"{BASE_URL}/intake/vendor/submissions").mock(
+        return_value=httpx.Response(201, json={
+            "ok": True,
+            "submissionId": "sub_123",
+            "state": "in_progress",
+            "resumeToken": "tok_abc",
+            "schema": {"type": "object"},
+            "missingFields": ["email"],
+        })
+    )
+
+    sub = await client.create_submission(
+        "vendor",
+        fields={"company": "Acme"},
+        actor=Actor(kind="agent", id="agent-1", name="Bot"),
+        idempotency_key="idem-1",
+    )
+    assert sub.submission_id == "sub_123"
+    assert sub.state == "in_progress"
+    assert sub.resume_token == "tok_abc"
+    assert sub.missing_fields == ["email"]
+    assert sub.intake_id == "vendor"
+    await client.close()
+
+
+# ── set_fields ────────────────────────────────────────────────────────
+
+
+@respx.mock
+async def test_set_fields_success(client: FormBridgeClient):
+    respx.patch(f"{BASE_URL}/intake/vendor/submissions/sub_123").mock(
+        return_value=httpx.Response(200, json={
+            "ok": True,
+            "submissionId": "sub_123",
+            "state": "in_progress",
+            "resumeToken": "tok_new",
+            "missingFields": [],
+        })
+    )
+
+    result = await client.set_fields(
+        "vendor", "sub_123", "tok_abc", {"email": "a@b.com"},
+        actor=Actor(kind="agent", id="agent-1"),
+    )
+    assert result.submission_id == "sub_123"
+    assert result.resume_token == "tok_new"
+    await client.close()
+
+
+# ── submit ────────────────────────────────────────────────────────────
+
+
+@respx.mock
+async def test_submit_success(client: FormBridgeClient):
+    respx.post(f"{BASE_URL}/intake/vendor/submissions/sub_123/submit").mock(
+        return_value=httpx.Response(200, json={
+            "ok": True,
+            "submissionId": "sub_123",
+            "intakeId": "vendor",
+            "state": "submitted",
+        })
+    )
+
+    sub = await client.submit("vendor", "sub_123", "tok_abc")
+    assert sub.state == "submitted"
+    await client.close()
+
+
+# ── get_submission ────────────────────────────────────────────────────
+
+
+@respx.mock
+async def test_get_submission_success(client: FormBridgeClient):
+    respx.get(f"{BASE_URL}/intake/vendor/submissions/sub_123").mock(
+        return_value=httpx.Response(200, json={
+            "ok": True,
+            "submissionId": "sub_123",
+            "intakeId": "vendor",
+            "state": "draft",
+            "fields": {"company": "Acme"},
+            "metadata": {"createdAt": "2026-01-01T00:00:00Z"},
+        })
+    )
+
+    sub = await client.get_submission("vendor", "sub_123")
+    assert sub.submission_id == "sub_123"
+    assert sub.fields == {"company": "Acme"}
+    assert sub.created_at == "2026-01-01T00:00:00Z"
+    await client.close()
+
+
+# ── Retry on 429 ──────────────────────────────────────────────────────
+
+
+@respx.mock
+async def test_retry_on_429(client: FormBridgeClient):
+    """Should retry on 429 and succeed on subsequent attempt."""
+    route = respx.get(f"{BASE_URL}/intake/v/submissions/s1")
+    route.side_effect = [
+        httpx.Response(429, json={"ok": False, "error": {"type": "rate_limited"}}),
+        httpx.Response(200, json={
+            "ok": True, "submissionId": "s1", "intakeId": "v", "state": "draft", "fields": {},
+        }),
+    ]
+
+    # Override backoffs for fast test
+    import formbridge.client as mod
+    original = mod._RETRY_BACKOFFS
+    mod._RETRY_BACKOFFS = [0.01, 0.01, 0.01]
+    try:
+        sub = await client.get_submission("v", "s1")
+        assert sub.submission_id == "s1"
+        assert route.call_count == 2
+    finally:
+        mod._RETRY_BACKOFFS = original
+    await client.close()
+
+
+# ── Retry on 5xx then fail ────────────────────────────────────────────
+
+
+@respx.mock
+async def test_retry_5xx_then_fail(client: FormBridgeClient):
+    """After max retries on 5xx, should raise FormBridgeError."""
+    route = respx.get(f"{BASE_URL}/intake/v/submissions/s1")
+    route.side_effect = [
+        httpx.Response(502, json={"ok": False, "error": {"type": "bad_gateway", "message": "down"}}),
+        httpx.Response(502, json={"ok": False, "error": {"type": "bad_gateway", "message": "down"}}),
+        httpx.Response(502, json={"ok": False, "error": {"type": "bad_gateway", "message": "down"}}),
+        httpx.Response(502, json={"ok": False, "error": {"type": "bad_gateway", "message": "down"}}),
+    ]
+
+    import formbridge.client as mod
+    original = mod._RETRY_BACKOFFS
+    mod._RETRY_BACKOFFS = [0.01, 0.01, 0.01]
+    try:
+        with pytest.raises(FormBridgeError) as exc_info:
+            await client.get_submission("v", "s1")
+        assert exc_info.value.status_code == 502
+        assert route.call_count == 4  # 1 initial + 3 retries
+    finally:
+        mod._RETRY_BACKOFFS = original
+    await client.close()
+
+
+# ── No retry on 400/401/403 ──────────────────────────────────────────
+
+
+@respx.mock
+async def test_no_retry_on_client_errors(client: FormBridgeClient):
+    """Should NOT retry on 400, 401, 403."""
+    route = respx.get(f"{BASE_URL}/intake/v/submissions/s1")
+    route.mock(return_value=httpx.Response(401, json={
+        "ok": False, "error": {"type": "unauthorized", "message": "bad key"},
+    }))
+
+    with pytest.raises(FormBridgeError) as exc_info:
+        await client.get_submission("v", "s1")
+    assert exc_info.value.status_code == 401
+    assert route.call_count == 1
+    await client.close()
+
+
+# ── Connection refused → graceful error ───────────────────────────────
+
+
+@respx.mock
+async def test_connection_refused():
+    """Connection error should produce FormBridgeError with is_connectivity_error=True."""
+    route = respx.get(f"{BASE_URL}/intake/v/submissions/s1")
+    route.side_effect = httpx.ConnectError("Connection refused")
+
+    import formbridge.client as mod
+    original = mod._RETRY_BACKOFFS
+    mod._RETRY_BACKOFFS = [0.01, 0.01, 0.01]
+
+    client = FormBridgeClient(url=BASE_URL, api_key="test-key")
+    try:
+        with pytest.raises(FormBridgeError) as exc_info:
+            await client.get_submission("v", "s1")
+        assert exc_info.value.is_connectivity_error is True
+        assert "Connection" in str(exc_info.value)
+    finally:
+        mod._RETRY_BACKOFFS = original
+        await client.close()
+
+
+# ── Sync client ───────────────────────────────────────────────────────
+
+
+@respx.mock
+def test_sync_client_create(sync_client: FormBridgeClientSync):
+    """Sync wrapper should work without event loop."""
+    respx.post(f"{BASE_URL}/intake/vendor/submissions").mock(
+        return_value=httpx.Response(201, json={
+            "ok": True,
+            "submissionId": "sub_sync",
+            "state": "draft",
+            "resumeToken": "tok_s",
+        })
+    )
+
+    sub = sync_client.create_submission("vendor", fields={"name": "Test"})
+    assert sub.submission_id == "sub_sync"
+    sync_client.close()
+
+
+# ── API key not leaked in logs ────────────────────────────────────────
+
+
+def test_api_key_not_in_repr():
+    """API key should not appear in string representations."""
+    client = FormBridgeClient(api_key="super-secret-key-123")
+    assert "super-secret-key-123" not in repr(client)
+    assert "super-secret-key-123" not in str(client)