dex-connector-figma 0.1.0__tar.gz

dex_connector_figma-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+/.dex-local/dexcli
+/.dex-local/dex-server-zd
+/.dex-local/data/
+/.dex-local/cli.log
+/.dex-local/visualize.json
+/.dex-local/visualize.err

dex_connector_figma-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: dex-connector-figma
+Version: 0.1.0
+Summary: Figma connector for Dex Flows
+License-Expression: MIT
+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
+
+# Figma connector for Python
+
+Install with `pip install dex-connector-figma==0.1.0`. The package requires
+`dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`, and implements the
+manifest Queries `getFile` and `getFileComments` with the same branches,
+defaults, and failure classification as the Go module.
+
+## Operations
+
+| Operation | Factory | Happy branch | Optional branches |
+| --- | --- | --- | --- |
+| `getFile` | `new_get_file_step` | `found` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+| `getFileComments` | `new_get_file_comments_step` | `listed` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+
+Both take a file key of 1 to 128 letters, digits, `_`, or `-`. `getFile`
+returns the file name, last-modified text, and the document node tree as
+JSON. Integral number values retain their exact integer value; a number that
+Dex JSON encoding would round selects `invalidResponse` and names its document
+field. A response without a name or document also selects `invalidResponse`.
+404 selects `notFound`; 408, 409, 429, 5xx, and transport failures retry; 401,
+403, and other non-200 responses select `providerRejected`.
+
+## Authorization
+
+Create a Dex Web connection named `figma` as described in the
+[connector README](../README.md#connection). The personal access token travels
+only in `X-Figma-Token` and is resolved for every attempt.
+
+## Example
+
+[`examples/figma_lookup`](examples/figma_lookup/flow.py) reads a file and then
+its comments. Run the Worker with
+`uv run python -m examples.figma_lookup.worker` after `dexcli dev` has loaded a
+project containing the `figma` connection.
+
+## Tests
+
+`figmamock.Mock` scripts both Queries and defaults to the manifest answers.
+Run `uv run pytest tests` for provider parity and manifest contract checks.

dex_connector_figma-0.1.0/README.md

@@ -0,0 +1,39 @@
+# Figma connector for Python
+
+Install with `pip install dex-connector-figma==0.1.0`. The package requires
+`dex-connectors-sdk==0.1.0` and `dex-python-sdk>=1.28.0`, and implements the
+manifest Queries `getFile` and `getFileComments` with the same branches,
+defaults, and failure classification as the Go module.
+
+## Operations
+
+| Operation | Factory | Happy branch | Optional branches |
+| --- | --- | --- | --- |
+| `getFile` | `new_get_file_step` | `found` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+| `getFileComments` | `new_get_file_comments_step` | `listed` | `notFound`, `providerRejected`, `invalidResponse`, `defect` |
+
+Both take a file key of 1 to 128 letters, digits, `_`, or `-`. `getFile`
+returns the file name, last-modified text, and the document node tree as
+JSON. Integral number values retain their exact integer value; a number that
+Dex JSON encoding would round selects `invalidResponse` and names its document
+field. A response without a name or document also selects `invalidResponse`.
+404 selects `notFound`; 408, 409, 429, 5xx, and transport failures retry; 401,
+403, and other non-200 responses select `providerRejected`.
+
+## Authorization
+
+Create a Dex Web connection named `figma` as described in the
+[connector README](../README.md#connection). The personal access token travels
+only in `X-Figma-Token` and is resolved for every attempt.
+
+## Example
+
+[`examples/figma_lookup`](examples/figma_lookup/flow.py) reads a file and then
+its comments. Run the Worker with
+`uv run python -m examples.figma_lookup.worker` after `dexcli dev` has loaded a
+project containing the `figma` connection.
+
+## Tests
+
+`figmamock.Mock` scripts both Queries and defaults to the manifest answers.
+Run `uv run pytest tests` for provider parity and manifest contract checks.

dex_connector_figma-0.1.0/examples/figma_lookup/__init__.py

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

dex_connector_figma-0.1.0/examples/figma_lookup/flow.py

@@ -0,0 +1,126 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Runnable Figma lookup Flow: read a file, then its comments."""
+
+from dataclasses import dataclass, field
+
+import dex
+from dex_connectors.sdk import QueryResult
+
+from dex_connectors.figma import (
+    Connection,
+    File,
+    FileComment,
+    FileComments,
+    GetFileCommentsInput,
+    GetFileInput,
+    new_get_file_comments_step,
+    new_get_file_step,
+)
+
+FLOW_TYPE = "FigmaLookup"
+CONNECTION_NAME = "figma"
+_FIRST_STEP_TYPE = "ReadFigmaFirst"
+_SECOND_STEP_TYPE = "ReadFigmaSecond"
+_ANNOTATION_GROUP = {"groupId": "figma-lookup", "groupLabel": "Figma lookup"}
+_FILE_KEY = dex.Attribute("figma-file-key", str)
+
+
+@dataclass(frozen=True, slots=True)
+class FigmaLookupRequest:
+    """Figma file key to read."""
+
+    file_key: str = field(metadata={"dex_json_name": "fileKey"})
+
+
+@dataclass(frozen=True, slots=True)
+class FigmaLookupOutcome:
+    """Comments on the file."""
+
+    comments: tuple[FileComment, ...] = ()
+
+
+def map_to_get_file_input(request: FigmaLookupRequest) -> GetFileInput:
+    """Read the requested file."""
+    return GetFileInput(request.file_key)
+
+
+def map_to_get_file_comments_input(input: GetFileCommentsInput) -> GetFileCommentsInput:
+    """Read the comments of the file chosen after the file read."""
+    return input
+
+
+# dex:group group-id:figma-lookup group-label:"Figma lookup"
+# dex:explanation text:"Record the file key and start the lookup."
+class _StartRequest(dex.Step[FigmaLookupRequest]):
+    def get_step_type(self) -> str:
+        return "StartFigmaLookup"
+
+    def execute(self, context: dex.Context, input: FigmaLookupRequest) -> dex.StepDecision:
+        if not input.file_key:
+            return dex.force_fail("fileKey is required")
+        _FILE_KEY.set(context, input.file_key)
+        return dex.go_to(dex.StepRef(_FIRST_STEP_TYPE), input)
+
+
+# dex:group group-id:figma-lookup group-label:"Figma lookup"
+# dex:explanation text:"Continue from the file to its comments."
+class _AfterFirst(dex.Step[QueryResult[File]]):
+    def get_step_type(self) -> str:
+        return "AfterFigmaFirst"
+
+    def execute(self, context: dex.Context, input: QueryResult[File]) -> dex.StepDecision:
+        return dex.go_to(dex.StepRef(_SECOND_STEP_TYPE), GetFileCommentsInput(_FILE_KEY.get(context)))
+
+
+# dex:group group-id:figma-lookup group-label:"Figma lookup"
+# dex:explanation text:"Complete with the comments Figma returned."
+class _CompleteLookup(dex.Step[QueryResult[FileComments]]):
+    def get_step_type(self) -> str:
+        return "CompleteFigmaLookup"
+
+    def execute(self, context: dex.Context, input: QueryResult[FileComments]) -> dex.StepDecision:
+        return dex.graceful_complete(FigmaLookupOutcome(input.value.comments))
+
+
+class FigmaLookupFlow(dex.Flow[FigmaLookupRequest]):
+    """Read a Figma file and its comments through the static figma connection."""
+
+    def __init__(self, connection: Connection) -> None:
+        if connection.reference.name != CONNECTION_NAME:
+            raise ValueError("Figma lookup requires the static figma connection")
+        self._start = _StartRequest()
+        self._after_first = _AfterFirst()
+        self._complete = _CompleteLookup()
+        self._file = new_get_file_step(
+            step_type=_FIRST_STEP_TYPE,
+            step_input_type=FigmaLookupRequest,
+            annotations={**_ANNOTATION_GROUP, "explanation": "Read Figma records."},
+            connection=connection,
+            connection_name=CONNECTION_NAME,
+            map_to_operation_input=map_to_get_file_input,
+            found=self._after_first,
+        )
+        self._comments = new_get_file_comments_step(
+            step_type=_SECOND_STEP_TYPE,
+            step_input_type=GetFileCommentsInput,
+            annotations={**_ANNOTATION_GROUP, "explanation": "Read the related Figma resource."},
+            connection=connection,
+            connection_name=CONNECTION_NAME,
+            map_to_operation_input=map_to_get_file_comments_input,
+            listed=self._complete,
+        )
+
+    def get_flow_type(self) -> str:
+        """Return the stable Flow identity used in Dex Web."""
+        return FLOW_TYPE
+
+    def get_steps(self) -> dex.StepList[FigmaLookupRequest]:
+        """Register the start, both Figma reads, and their result Steps."""
+        return dex.StepList.start_step(self._start).other_steps(
+            self._file, self._after_first, self._comments, self._complete
+        )
+
+    def get_persistence_schema(self) -> dex.PersistenceSchema:
+        """Persist the requested file key between the two reads."""
+        return dex.PersistenceSchema.of(_FILE_KEY)

dex_connector_figma-0.1.0/examples/figma_lookup/worker.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Worker entrypoint for the Figma lookup Flow."""
+
+import asyncio
+import os
+import tempfile
+from pathlib import Path
+
+import dex
+from dex_connectors.sdk.projectconfig import load_from_environment
+
+from dex_connectors.figma import new_project_connection
+
+from .flow import CONNECTION_NAME, FigmaLookupFlow
+
+
+async def run_worker() -> None:
+    """Load the named Dex Web connection and serve Figma lookups."""
+    project = await load_from_environment()
+    connection = None
+    cache = None
+    try:
+        connection = new_project_connection(project, CONNECTION_NAME)
+        registry = dex.Registry([FigmaLookupFlow(connection)], allow_async_handlers=True)
+        cache_directory = os.environ.get(
+            "DEX_BLOB_CACHE_DIR", str(Path(tempfile.gettempdir()) / "dex-figma-lookup-blobs")
+        )
+        cache = dex.open_blob_cache(dex.BlobCacheConfig(cache_directory, 1 << 30))
+        worker = dex.AsyncWorker(
+            registry,
+            cache,
+            dex.WorkerOptions(server_address=os.environ.get("DEX_FLOW_SERVICE_ADDRESS", "localhost:8801")),
+        )
+        async with worker:
+            await worker.start()
+    finally:
+        if connection is not None:
+            await connection.aclose()
+        if cache is not None:
+            cache.close()
+        await project.close()
+
+
+def main() -> None:
+    """Run until the Worker stops or the process receives an interrupt."""
+    asyncio.run(run_worker())
+
+
+if __name__ == "__main__":
+    main()

dex_connector_figma-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dex-connector-figma"
+version = "0.1.0"
+description = "Figma connector for Dex Flows"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["dex-connectors-sdk==0.1.0", "dex-python-sdk>=1.28.0", "httpx>=0.27"]
+
+[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_figma-0.1.0/src/dex_connectors/figma/__init__.py

@@ -0,0 +1,51 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Figma file and comment Queries for Dex connector Steps."""
+
+from .client import (
+    CONNECTOR_ID,
+    DEFECT,
+    FOUND,
+    GET_FILE_COMMENTS_DEFINITION,
+    GET_FILE_DEFINITION,
+    INVALID_RESPONSE,
+    LISTED,
+    NOT_FOUND,
+    PROVIDER_REJECTED,
+    Client,
+    Config,
+    Credentials,
+    GetFileCommentsOperation,
+    GetFileOperation,
+)
+from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
+from .models import File, FileComment, FileComments, GetFileCommentsInput, GetFileInput
+from .steps import new_get_file_comments_step, new_get_file_step
+
+__all__ = [
+    "Client",
+    "Config",
+    "Connection",
+    "Credentials",
+    "File",
+    "FileComment",
+    "FileComments",
+    "GetFileCommentsInput",
+    "GetFileCommentsOperation",
+    "GetFileInput",
+    "GetFileOperation",
+    "new_connection",
+    "new_connection_with_operations",
+    "new_get_file_comments_step",
+    "new_get_file_step",
+    "new_project_connection",
+    "CONNECTOR_ID",
+    "DEFECT",
+    "FOUND",
+    "GET_FILE_COMMENTS_DEFINITION",
+    "GET_FILE_DEFINITION",
+    "INVALID_RESPONSE",
+    "LISTED",
+    "NOT_FOUND",
+    "PROVIDER_REJECTED",
+]

dex_connector_figma-0.1.0/src/dex_connectors/figma/_generated/__init__.py

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

dex_connector_figma-0.1.0/src/dex_connectors/figma/_generated/config.py

@@ -0,0 +1,25 @@
+# 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:
+
+    base_url: str = "https://api.figma.com/v1"
+    timeout_seconds: float = 30
+    max_response_bytes: int = 8388608
+
+setattr(Config, '__module__', 'dex_connectors.figma.client')
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+
+    api_key: SecretString
+
+setattr(Credentials, '__module__', 'dex_connectors.figma.client')

dex_connector_figma-0.1.0/src/dex_connectors/figma/_generated/connection.py

@@ -0,0 +1,137 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from typing import Any
+
+import httpx
+from dex_connectors.sdk import ConnectionRef, Query, Call, SecretString
+from dex_connectors.sdk.projectconfig import ConnectionKey, LoadedProject
+
+from ..client import Client, Config, Credentials
+from .definitions import CONNECTOR_ID, GET_FILE_COMMENTS_DEFINITION, GET_FILE_DEFINITION
+from ..models import File, FileComments, GetFileCommentsInput, GetFileInput
+
+class Connection:
+
+    __slots__ = ('_get_file', '_get_file_comments', '_client', 'reference')
+
+    def __init__(self,
+        reference: ConnectionRef,
+        get_file: Query[GetFileInput, File],
+        get_file_comments: Query[GetFileCommentsInput, FileComments],
+        client: Client | None = None,
+    ) -> None:
+        reference.validate()
+        if reference.provider != CONNECTOR_ID or get_file is None or get_file_comments is None:
+            raise ValueError("Figma connection provider and operations are required")
+        if get_file.definition().operation != GET_FILE_DEFINITION.operation:
+            raise ValueError("Figma connection operation identity differs")
+        if get_file_comments.definition().operation != GET_FILE_COMMENTS_DEFINITION.operation:
+            raise ValueError("Figma connection operation identity differs")
+        self.reference = reference
+        self._get_file = get_file
+        self._get_file_comments = get_file_comments
+        self._client = client
+
+    def get_file(self) -> Query[GetFileInput, File]:
+        return self._get_file
+
+    def get_file_comments(self) -> Query[GetFileCommentsInput, FileComments]:
+        return self._get_file_comments
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+
+    def __repr__(self) -> str:
+        return "figma.Connection([REDACTED])"
+
+    def __reduce__(self) -> tuple[object, ...]:
+        raise TypeError("Figma connections cannot be serialized")
+
+setattr(Connection, '__module__', 'dex_connectors.figma.connection')
+
+
+def new_connection(client: Client, reference: ConnectionRef) -> Connection:
+    if client is None:
+        raise ValueError("Figma client is required")
+    return Connection(reference, client.get_file(), client.get_file_comments(), client)
+
+setattr(new_connection, '__module__', 'dex_connectors.figma.connection')
+
+
+def new_connection_with_operations(
+    get_file: Query[GetFileInput, File],
+    get_file_comments: Query[GetFileCommentsInput, FileComments],
+    reference: ConnectionRef,
+) -> Connection:
+    return Connection(reference, get_file, get_file_comments)
+
+setattr(new_connection_with_operations, '__module__', 'dex_connectors.figma.connection')
+
+
+class _ProjectCredentialSource:
+
+    def __init__(self, project: LoadedProject, key: ConnectionKey) -> None:
+        self.project = project
+        self.key = key
+
+    async def resolve(self, call: Call) -> Credentials:
+        material = await self.project.resolve_credential(self.key, str(call.id))
+        if not isinstance(material, dict):
+            raise ValueError("Figma stored credential does not match the connector credential fields")
+        if set(material) - set(('api_key',)):
+            raise ValueError("Figma stored credential does not match the connector credential fields")
+        api_key = material.get("api_key")
+        if api_key is not None and not (isinstance(api_key, str)):
+            raise ValueError("Figma credential api_key has an invalid type")
+        if not api_key:
+            raise ValueError("Figma credential api_key is required")
+        return Credentials(SecretString(api_key))
+
+
+def new_project_connection(
+    project: LoadedProject, connection_name: str, http_client: httpx.AsyncClient | None = None
+) -> Connection:
+    if project is None:
+        raise ValueError("Figma connection requires loaded project configuration")
+    reference = ConnectionRef(CONNECTOR_ID, connection_name)
+    reference.validate()
+    key = ConnectionKey(CONNECTOR_ID, connection_name)
+    matching = [
+        entry
+        for entry in project.configuration.connections
+        if entry.connector_id == CONNECTOR_ID and entry.connection_name == connection_name
+    ]
+    if len(matching) != 1:
+        raise ValueError("Figma project connection is missing or duplicated")
+    if matching[0].provider != CONNECTOR_ID:
+        raise ValueError("Figma project connection provider differs")
+    config = _decode_config(matching[0].configuration)
+    client = Client(config, _ProjectCredentialSource(project, key), http_client)
+    return new_connection(client, reference)
+
+setattr(new_project_connection, '__module__', 'dex_connectors.figma.connection')
+
+
+def _decode_config(value: dict[str, Any]) -> Config:
+    if set(value) - {"baseUrl", "timeout", "maxResponseBytes"}:
+        raise ValueError("Figma configuration has unknown fields")
+    config_arguments: dict[str, Any] = {}
+    if "baseUrl" in value:
+        base_url = value["baseUrl"]
+        if not (isinstance(base_url, str)):
+            raise ValueError("Figma configuration baseUrl has an invalid type")
+        config_arguments['base_url'] = base_url
+    if "timeout" in value:
+        timeout = value["timeout"]
+        if not (type(timeout) is int):
+            raise ValueError("Figma configuration timeout has an invalid type")
+        config_arguments['timeout_seconds'] = timeout / 1_000_000_000
+    if "maxResponseBytes" in value:
+        max_response_bytes = value["maxResponseBytes"]
+        if not (type(max_response_bytes) is int):
+            raise ValueError("Figma configuration maxResponseBytes has an invalid type")
+        config_arguments['max_response_bytes'] = max_response_bytes
+    return Config(**config_arguments)

dex_connector_figma-0.1.0/src/dex_connectors/figma/_generated/definitions.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+# ruff: noqa
+
+from datetime import timedelta
+
+from dex_connectors.sdk import (
+    BranchDefinition,
+    MutationDefinition,
+    OperationRef,
+    QueryDefinition,
+    RetryPolicy,
+    StepDefaults,
+    default_connector_step_execute_retry_policy,
+)
+
+CONNECTOR_ID = "figma"
+PROVIDER = "figma"
+GET_FILE_OPERATION_ID = "getFile"
+GET_FILE_COMMENTS_OPERATION_ID = "getFileComments"
+DEFECT = "defect"
+FOUND = "found"
+INVALID_RESPONSE = "invalidResponse"
+LISTED = "listed"
+NOT_FOUND = "notFound"
+PROVIDER_REJECTED = "providerRejected"
+
+GET_FILE_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, GET_FILE_OPERATION_ID),
+    (
+        BranchDefinition(FOUND, "Figma returned the requested data.", False),
+        BranchDefinition(NOT_FOUND, "Figma does not have the requested resource.", True),
+        BranchDefinition(PROVIDER_REJECTED, "Figma conclusively rejected the read.", True),
+        BranchDefinition(INVALID_RESPONSE, "Figma returned malformed or oversized JSON.", True),
+        BranchDefinition(DEFECT, "Local input or connection credentials are invalid.", True),
+    ),
+    StepDefaults(
+        timedelta(seconds=45),
+        2,
+        execute_retry=default_connector_step_execute_retry_policy(),
+    ),
+)
+
+GET_FILE_COMMENTS_DEFINITION = QueryDefinition(
+    OperationRef(CONNECTOR_ID, GET_FILE_COMMENTS_OPERATION_ID),
+    (
+        BranchDefinition(LISTED, "Figma returned the requested data.", False),
+        BranchDefinition(NOT_FOUND, "Figma does not have the requested resource.", True),
+        BranchDefinition(PROVIDER_REJECTED, "Figma conclusively rejected the read.", True),
+        BranchDefinition(INVALID_RESPONSE, "Figma returned malformed or oversized JSON.", True),
+        BranchDefinition(DEFECT, "Local input or connection credentials are invalid.", True),
+    ),
+    StepDefaults(
+        timedelta(seconds=45),
+        2,
+        execute_retry=default_connector_step_execute_retry_policy(),
+    ),
+)