dex-connector-front 0.1.0__tar.gz

dex_connector_front-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.DS_Store
+__pycache__/
+*.py[cod]
+node_modules/
+dist/
+sdkpython/dist/dex_connectors_sdk-0.1.0-py3-none-any.whl
+/.bin/dexcli
+/.bin/dex-server-zd
+/sdkpython/.dexcli-data/
+site/.catalog.yaml
+coverage/
+*.out
+*.test
+go.work
+go.work.sum
+.idea/

dex_connector_front-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Super Durable
+
+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.

dex_connector_front-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: dex-connector-front
+Version: 0.1.0
+Summary: Dex-native Front conversation and contact connector
+Project-URL: Source, https://github.com/superdurable/dex-connectors-library/tree/main/connectors/front/python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: dex-connectors-sdk==0.1.0
+Requires-Dist: dex-python-sdk>=1.28.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Front connector for Python
+
+`dex-connector-front==0.1.0` implements all five Front operations as Dex Python
+Queries and Mutations: `searchConversations`, `getConversation`,
+`replyToConversation`, `updateConversation`, and `findContactByEmail`. It has
+no Python Trigger. Import from `dex_connectors.front`; the generated models,
+Step factories, connection binding, mock outcomes, and `dex-connector.json`
+come from [`connector.yaml`](../connector.yaml).
+
+The connector requires Python 3.11 or newer, Dex Python SDK 1.28.0 or newer,
+and the pinned `dex-connectors-sdk` release in `pyproject.toml`.
+
+## Connection
+
+The runnable example uses the static name `front-support`. Create an API token
+at <https://app.frontapp.com/> under **Settings > Developers > API Tokens**.
+A company admin chooses **Create API token**, grants contact read access for
+this example, then copies the token into the secret `api_token` field in Dex Web
+**Connections**. The token has three dot-separated JWT segments and is sent
+only as an Authorization bearer token. The `maxResponseBytes` setting limits
+one complete response in bytes; leave it blank to retain the displayed safety
+limit, and raise it only when a valid large response selects `invalidResponse`.
+The [Front connector guide](../README.md#authorization) details permissions
+for every operation and the inbox, teammate, and tag pickers.
+
+The runnable [`main.py`](examples/contact_lookup/main.py) loads project
+configuration and resolves private credentials at call time through
+`new_project_connection(project, "front-support")`. Secrets stay out of Flow
+input, Results, Attributes, receipts, logs, and generated manifests.
+
+## Operation outcomes
+
+The generated operation-specific factories accept one required happy-path
+branch. Optional branches fail the Flow when left unwired. Searches select
+`searched`; conversation reads and contact lookups select `found`; replies
+select `replied`; updates select `updated`. Reads and updates retry safe
+transient failures. A reply or internal comment uses the SDK single-dispatch
+fence because Front has no provider idempotency key. Ambiguous delivery
+selects `uncertain`; reconcile it in Front before making a new request. An
+update reads back its requested values and can repeat absolute writes.
+
+`frontmock.Mock` and its generated named scenarios can exercise branch routing
+without credentials. The 50 Go-recorded provider scenarios in
+[`conformance/connectors/front`](../../../conformance/connectors/front/scenarios.json)
+exercise exact HTTP requests, response decoding, branches, retry decisions,
+and the production SDK output codec. They supplement the real Dex Worker and
+Client [example integration test](examples/contact_lookup/integration_test.py).
+
+## Run the example
+
+See the [contact lookup Flow](examples/contact_lookup/README.md). From this
+package directory, install and run its Worker after configuring Dex Web:
+
+```sh
+uv sync --locked
+DEX_FLOW_SERVICE_ADDRESS=127.0.0.1:8801 \
+  DEX_CONNECTOR_CONFIG_FILE=/path/to/connections.json \
+  uv run python -m examples.contact_lookup.main
+```
+
+For local verification with `dexcli dev`, use `uv run pytest` for the package
+suite and set `DEX_FLOW_SERVICE_ADDRESS` to the active local Dex gRPC address
+when running `uv run pytest examples/contact_lookup/integration_test.py`.
+The local integration test uses a free-port Front stand-in; Front account
+setup, API permissions, and live provider behavior remain unverified.

dex_connector_front-0.1.0/README.md

@@ -0,0 +1,65 @@
+# Front connector for Python
+
+`dex-connector-front==0.1.0` implements all five Front operations as Dex Python
+Queries and Mutations: `searchConversations`, `getConversation`,
+`replyToConversation`, `updateConversation`, and `findContactByEmail`. It has
+no Python Trigger. Import from `dex_connectors.front`; the generated models,
+Step factories, connection binding, mock outcomes, and `dex-connector.json`
+come from [`connector.yaml`](../connector.yaml).
+
+The connector requires Python 3.11 or newer, Dex Python SDK 1.28.0 or newer,
+and the pinned `dex-connectors-sdk` release in `pyproject.toml`.
+
+## Connection
+
+The runnable example uses the static name `front-support`. Create an API token
+at <https://app.frontapp.com/> under **Settings > Developers > API Tokens**.
+A company admin chooses **Create API token**, grants contact read access for
+this example, then copies the token into the secret `api_token` field in Dex Web
+**Connections**. The token has three dot-separated JWT segments and is sent
+only as an Authorization bearer token. The `maxResponseBytes` setting limits
+one complete response in bytes; leave it blank to retain the displayed safety
+limit, and raise it only when a valid large response selects `invalidResponse`.
+The [Front connector guide](../README.md#authorization) details permissions
+for every operation and the inbox, teammate, and tag pickers.
+
+The runnable [`main.py`](examples/contact_lookup/main.py) loads project
+configuration and resolves private credentials at call time through
+`new_project_connection(project, "front-support")`. Secrets stay out of Flow
+input, Results, Attributes, receipts, logs, and generated manifests.
+
+## Operation outcomes
+
+The generated operation-specific factories accept one required happy-path
+branch. Optional branches fail the Flow when left unwired. Searches select
+`searched`; conversation reads and contact lookups select `found`; replies
+select `replied`; updates select `updated`. Reads and updates retry safe
+transient failures. A reply or internal comment uses the SDK single-dispatch
+fence because Front has no provider idempotency key. Ambiguous delivery
+selects `uncertain`; reconcile it in Front before making a new request. An
+update reads back its requested values and can repeat absolute writes.
+
+`frontmock.Mock` and its generated named scenarios can exercise branch routing
+without credentials. The 50 Go-recorded provider scenarios in
+[`conformance/connectors/front`](../../../conformance/connectors/front/scenarios.json)
+exercise exact HTTP requests, response decoding, branches, retry decisions,
+and the production SDK output codec. They supplement the real Dex Worker and
+Client [example integration test](examples/contact_lookup/integration_test.py).
+
+## Run the example
+
+See the [contact lookup Flow](examples/contact_lookup/README.md). From this
+package directory, install and run its Worker after configuring Dex Web:
+
+```sh
+uv sync --locked
+DEX_FLOW_SERVICE_ADDRESS=127.0.0.1:8801 \
+  DEX_CONNECTOR_CONFIG_FILE=/path/to/connections.json \
+  uv run python -m examples.contact_lookup.main
+```
+
+For local verification with `dexcli dev`, use `uv run pytest` for the package
+suite and set `DEX_FLOW_SERVICE_ADDRESS` to the active local Dex gRPC address
+when running `uv run pytest examples/contact_lookup/integration_test.py`.
+The local integration test uses a free-port Front stand-in; Front account
+setup, API permissions, and live provider behavior remain unverified.

dex_connector_front-0.1.0/examples/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Runnable Front connector applications."""

dex_connector_front-0.1.0/examples/contact_lookup/README.md

@@ -0,0 +1,29 @@
+# Front contact lookup Flow
+
+This Flow uses the static `front-support` connection to find the Front contact
+that owns one email handle. Run its Worker with `python -m
+examples.contact_lookup.main` after configuring the connection through Dex Web.
+The connection holds an API token; the Flow input is only an email address.
+
+Start `dexcli dev` and configure `front / front-support` in Dex Web **Connections**.
+Create the Front API token using the authorization guide in
+[`connector.yaml`](../../../connector.yaml). In Front, an admin opens
+<https://app.frontapp.com/> > **Settings > Developers > API Tokens**,
+creates a token with contact read access, and copies its secret into Dex Web.
+Leave the response byte limit blank for the displayed default. Set
+`DEX_CONNECTOR_CONFIG_FILE` to the private `connections.json` exported by that
+project, then run:
+
+```sh
+uv sync --locked
+DEX_FLOW_SERVICE_ADDRESS=127.0.0.1:8801 \
+  DEX_CONNECTOR_CONFIG_FILE=/path/to/connections.json \
+  uv run python -m examples.contact_lookup.main
+```
+
+The Worker registration uses the real application source in [`main.py`](main.py).
+Start `FrontContactLookupPython` with `sample-input.json` using a Dex Client.
+Only the `found` branch is wired; a missing contact, provider rejection,
+invalid response, or local defect fails the Flow. `integration_test.py` runs
+this Flow through a real Dex Worker and Client against a local Front stand-in.
+Live Front authorization and provider behavior remain unverified.

dex_connector_front-0.1.0/examples/contact_lookup/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Front contact lookup Flow."""

dex_connector_front-0.1.0/examples/contact_lookup/flow.py

@@ -0,0 +1,78 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Find a Front contact through one durable Dex Query Step."""
+
+from dataclasses import dataclass
+
+import dex
+from dex_connectors.sdk import QueryResult
+
+from dex_connectors.front import (
+    Connection,
+    FindContactByEmailInput,
+    FindContactByEmailOutput,
+    new_find_contact_by_email_step,
+)
+
+CONNECTION_NAME = "front-support"
+FLOW_TYPE = "FrontContactLookupPython"
+
+
+@dataclass(frozen=True, slots=True)
+class ContactLookupRequest:
+    """Customer email entered when starting the Flow."""
+
+    email: str
+
+
+def map_to_contact_lookup_input(request: ContactLookupRequest) -> FindContactByEmailInput:
+    """Map the safe Flow input to Front's email alias lookup."""
+    return FindContactByEmailInput(email=request.email)
+
+
+# dex:group group-id:front-contact group-label:"Front contact"
+# dex:explanation text:"Return the Front contact found for the requested email."
+class CompleteContactLookup(dex.Step[QueryResult[FindContactByEmailOutput]]):
+    """Complete the Flow with the contact lookup output."""
+
+    def get_step_type(self) -> str:
+        """Return the stable completion Step identity."""
+        return "CompleteFrontContactLookup"
+
+    def execute(self, context: dex.Context, input: QueryResult[FindContactByEmailOutput]) -> dex.StepDecision:
+        """Keep the result free of connection credentials."""
+        return dex.graceful_complete(input.value)
+
+
+class ContactLookupFlow(dex.Flow[ContactLookupRequest]):
+    """Find a contact through the static Front connection."""
+
+    def __init__(self, connection: Connection) -> None:
+        if connection.reference.name != CONNECTION_NAME:
+            raise ValueError("Front contact lookup requires its static connection name")
+        self.complete = CompleteContactLookup()
+        self.lookup = new_find_contact_by_email_step(
+            step_type="FindFrontContactByEmail",
+            step_input_type=ContactLookupRequest,
+            annotations={
+                "groupId": "front-contact",
+                "groupLabel": "Front contact",
+                "explanation": "Find the Front contact with this email handle.",
+            },
+            connection=connection,
+            connection_name="front-support",
+            map_to_operation_input=map_to_contact_lookup_input,
+            found=self.complete,
+        )
+
+    def get_flow_type(self) -> str:
+        """Return the stable application Flow type."""
+        return FLOW_TYPE
+
+    def get_steps(self) -> dex.StepList[ContactLookupRequest]:
+        """Register the provider Query and completion Step."""
+        return dex.StepList.start_step(self.lookup).other_steps(self.complete)
+
+    def get_persistence_schema(self) -> dex.PersistenceSchema:
+        """Persist no Attributes; completion carries the safe contact."""
+        return dex.PersistenceSchema.of()

dex_connector_front-0.1.0/examples/contact_lookup/integration_test.py

@@ -0,0 +1,89 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Exercise the Front example through a real Dex Worker and Client."""
+
+import asyncio
+import os
+from datetime import timedelta
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from threading import Thread
+from uuid import uuid4
+
+import dex
+import pytest
+from dex_connectors.sdk import ConnectionRef, SecretString, StaticCredentialProvider
+
+from dex_connectors.front import Client, Config, Credentials, FindContactByEmailOutput, new_connection
+
+from .flow import CONNECTION_NAME, ContactLookupFlow, ContactLookupRequest
+
+
+@pytest.mark.asyncio
+async def test_contact_lookup_retries_and_fails_unwired_not_found(tmp_path: Path) -> None:
+    """Verify durable retry and optional branch routing against a local provider."""
+    server_address = os.environ["DEX_FLOW_SERVICE_ADDRESS"]
+    requests: list[str] = []
+
+    class FrontHandler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:
+            requests.append(self.path)
+            if "missing" in self.path:
+                self.send_response(404)
+                self.end_headers()
+                return
+            if len(requests) == 1:
+                self.send_response(429)
+                self.end_headers()
+                return
+            body = (
+                b'{"id":"crd_100","name":"Jane","handles":'
+                b'[{"handle":"jane@acme.example.com","source":"email"}]}'
+            )
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def log_message(self, format: str, *args: object) -> None:
+            pass  # The stand-in logs no request details or credentials.
+
+    provider = ThreadingHTTPServer(("127.0.0.1", 0), FrontHandler)
+    provider_thread = Thread(target=provider.serve_forever, daemon=True)
+    provider_thread.start()
+    reference = ConnectionRef("front", CONNECTION_NAME)
+    credentials = StaticCredentialProvider({reference: Credentials(SecretString("front-inert-test-token"))})
+    client = Client(Config(), credentials, api_base_url=f"http://127.0.0.1:{provider.server_port}")
+    connection = new_connection(client, reference)
+    flow = ContactLookupFlow(connection)
+    registry = dex.Registry([flow], allow_async_handlers=True)
+    cache = dex.open_blob_cache(dex.BlobCacheConfig(str(tmp_path / "blobs"), 1 << 24))
+    worker = dex.AsyncWorker(registry, cache, dex.WorkerOptions(server_address=server_address))
+    worker_task = asyncio.create_task(worker.start())
+    try:
+        await worker.wait_pull_registered(timeout=30)
+        async with dex.AsyncClient(
+            registry, cache, dex.ClientOptions(server_address=server_address)
+        ) as dex_client:
+            success_id = f"front-python-found-{uuid4().hex}"
+            await dex_client.start_flow(flow, success_id, ContactLookupRequest("jane@acme.example.com"))
+            success = await asyncio.wait_for(dex_client.wait_for_flow(success_id, timedelta(seconds=30)), 40)
+            assert success.status == dex.FlowStatus.COMPLETED, success.error_message
+            output = success.single_output(FindContactByEmailOutput)
+            assert output.contacts[0].id == "crd_100"
+            assert requests.count("/contacts/alt:email:jane@acme.example.com") == 2
+
+            missing_id = f"front-python-missing-{uuid4().hex}"
+            await dex_client.start_flow(flow, missing_id, ContactLookupRequest("missing@acme.example.com"))
+            missing = await asyncio.wait_for(dex_client.wait_for_flow(missing_id, timedelta(seconds=30)), 40)
+            assert missing.status == dex.FlowStatus.FAILED
+            assert missing.error_message is not None and "notFound" in missing.error_message
+    finally:
+        await worker.stop()
+        await worker_task
+        cache.close()
+        await connection.aclose()
+        provider.shutdown()
+        provider.server_close()
+        provider_thread.join(timeout=5)

dex_connector_front-0.1.0/examples/contact_lookup/main.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Load the Front connection and run the contact lookup Worker."""
+
+import asyncio
+
+from dex_connectors.sdk.projectconfig import load_from_environment
+
+from dex_connectors.front import new_project_connection
+
+from .flow import CONNECTION_NAME, ContactLookupFlow
+from .worker import run_worker
+
+
+async def main() -> None:
+    """Bind current project credentials to the static Front connection."""
+    project = await load_from_environment()
+    connection = new_project_connection(project, CONNECTION_NAME)
+    try:
+        await run_worker(ContactLookupFlow(connection))
+    finally:
+        await connection.aclose()
+        await project.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

dex_connector_front-0.1.0/examples/contact_lookup/sample-input.json

@@ -0,0 +1 @@
+{"email":"jane@acme.example.com"}

dex_connector_front-0.1.0/examples/contact_lookup/worker.py

@@ -0,0 +1,26 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Serve the Front contact lookup Flow with a Dex Worker."""
+
+import os
+import tempfile
+from pathlib import Path
+
+import dex
+
+from .flow import ContactLookupFlow
+
+
+async def run_worker(flow: ContactLookupFlow) -> None:
+    """Run the Flow until the Worker is stopped."""
+    registry = dex.Registry([flow], allow_async_handlers=True)
+    directory = Path(
+        os.environ.get("DEX_BLOB_CACHE_DIR", str(Path(tempfile.gettempdir()) / "dex-front-python-blobs"))
+    )
+    cache = dex.open_blob_cache(dex.BlobCacheConfig(str(directory), 1 << 30))
+    try:
+        address = os.environ.get("DEX_FLOW_SERVICE_ADDRESS", "localhost:8801")
+        async with dex.AsyncWorker(registry, cache, dex.WorkerOptions(server_address=address)) as worker:
+            await worker.start()
+    finally:
+        cache.close()

dex_connector_front-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dex-connector-front"
+version = "0.1.0"
+description = "Dex-native Front conversation and contact connector"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["dex-connectors-sdk==0.1.0", "dex-python-sdk>=1.28.0", "httpx>=0.27"]
+
+[project.urls]
+Source = "https://github.com/superdurable/dex-connectors-library/tree/main/connectors/front/python"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.13", "ruff>=0.7", "PyYAML>=6", "types-PyYAML>=6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dex_connectors"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+explicit_package_bases = true
+
+[tool.ruff]
+target-version = "py311"
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

dex_connector_front-0.1.0/src/dex_connectors/front/__init__.py

@@ -0,0 +1,62 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Front conversation and contact operations for Dex Python Flows."""
+
+from .client import Client, Config, Credentials
+from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
+from .models import (
+    Comment,
+    Contact,
+    ContactHandle,
+    Conversation,
+    ConversationDetails,
+    ConversationReply,
+    FindContactByEmailInput,
+    FindContactByEmailOutput,
+    GetConversationInput,
+    Message,
+    ReplyToConversationInput,
+    SearchConversationsInput,
+    SearchConversationsOutput,
+    UpdateConversationInput,
+    UpdateConversationOutput,
+)
+from .operations import build_reply_html
+from .steps import (
+    new_find_contact_by_email_step,
+    new_get_conversation_step,
+    new_reply_to_conversation_step,
+    new_search_conversations_step,
+    new_update_conversation_step,
+)
+
+__all__ = [
+    "Client",
+    "Config",
+    "Credentials",
+    "Connection",
+    "new_connection",
+    "new_connection_with_operations",
+    "new_project_connection",
+    "Comment",
+    "Contact",
+    "ContactHandle",
+    "Conversation",
+    "ConversationDetails",
+    "ConversationReply",
+    "FindContactByEmailInput",
+    "FindContactByEmailOutput",
+    "GetConversationInput",
+    "Message",
+    "ReplyToConversationInput",
+    "SearchConversationsInput",
+    "SearchConversationsOutput",
+    "UpdateConversationInput",
+    "UpdateConversationOutput",
+    "build_reply_html",
+    "new_find_contact_by_email_step",
+    "new_get_conversation_step",
+    "new_reply_to_conversation_step",
+    "new_search_conversations_step",
+    "new_update_conversation_step",
+]

dex_connector_front-0.1.0/src/dex_connectors/front/_generated/__init__.py

@@ -0,0 +1,2 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT

dex_connector_front-0.1.0/src/dex_connectors/front/_generated/config.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from dataclasses import dataclass
+
+from dex_connectors.sdk import SecretString
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+
+    max_response_bytes: int = 4194304
+
+setattr(Config, '__module__', 'dex_connectors.front.client')
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+
+    api_token: SecretString
+
+setattr(Credentials, '__module__', 'dex_connectors.front.client')