dex-connector-google-docs 0.1.0__tar.gz

dex_connector_google_docs-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_google_docs-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_google_docs-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.5
+Name: dex-connector-google-docs
+Version: 0.1.0
+Summary: Dex-native Google Docs connector
+Project-URL: Source, https://github.com/superdurable/dex-connectors-library/tree/main/connectors/google/docs/python
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: dex-connectors-sdk==0.7.0
+Requires-Dist: dex-python-sdk>=1.28.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# Google Docs Python connector
+
+Dex-native Google Docs operations, with operation-specific Step factories for
+`getDocumentText`, `createDocument`, `replaceDocumentText`, and `appendText`.
+The package requires Connector SDK 0.7.0. Use `new_project_connection` for the
+generated Google OAuth or Workspace domain delegation credential refresh wiring.
+Provider creation timestamps must be valid Go JSON timestamps; invalid values
+fail before a document Result is stored.
+
+The [policy read example](examples/policy_read/README.md) shows the static
+connection name, FDG generation, Worker, and Flow starter. See the
+[parent connector README](../README.md) for authorization and operation guidance.

dex_connector_google_docs-0.1.0/README.md

@@ -0,0 +1,12 @@
+# Google Docs Python connector
+
+Dex-native Google Docs operations, with operation-specific Step factories for
+`getDocumentText`, `createDocument`, `replaceDocumentText`, and `appendText`.
+The package requires Connector SDK 0.7.0. Use `new_project_connection` for the
+generated Google OAuth or Workspace domain delegation credential refresh wiring.
+Provider creation timestamps must be valid Go JSON timestamps; invalid values
+fail before a document Result is stored.
+
+The [policy read example](examples/policy_read/README.md) shows the static
+connection name, FDG generation, Worker, and Flow starter. See the
+[parent connector README](../README.md) for authorization and operation guidance.

dex_connector_google_docs-0.1.0/examples/policy_read/README.md

@@ -0,0 +1,30 @@
+# Google Docs policy read
+
+This Flow reads the first tab of a Google Doc as plain text. It uses the static
+`google-docs-policy` connection and fails if an optional provider branch is selected.
+
+From `connectors/google/docs/python`, install with `uv sync --locked` and generate
+strict FDG 2.0 with:
+
+```sh
+mkdir -p build
+dexcli visualize ./examples/policy_read/flow.py --language python \
+  --python .venv/bin/python --schema-version 2.0 --json \
+  --out ./build/google-docs-policy-read
+```
+
+Start `dexcli dev -flow-rendering-dir ./build`, configure the Google OAuth
+`google-docs-policy` connection in Dex Web following the parent README, then
+export the owner-only `DEX_CONNECTOR_CONFIG_FILE` path and
+`DEX_FLOW_SERVICE_ADDRESS` from that project. Run the Worker and start a
+Flow with a unique ID and a document ID from the
+`/document/d/{documentId}/edit` portion of its Google Docs URL:
+
+```sh
+uv run python -m examples.policy_read.worker
+uv run python -m examples.policy_read.start policy-read-001 YOUR_DOCUMENT_ID
+```
+
+The Dex integration test uses a local provider fake and needs no Google
+authorization: `uv run pytest examples/policy_read/integration_test.py`
+while `dexcli dev` is running.

dex_connector_google_docs-0.1.0/examples/policy_read/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Google Docs policy read example."""

dex_connector_google_docs-0.1.0/examples/policy_read/flow.py

@@ -0,0 +1,68 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Read one Google Doc through a Dex Flow."""
+
+from dataclasses import dataclass, field
+
+import dex
+from dex_connectors.sdk import QueryResult
+
+from dex_connectors.google_docs import (
+    Connection,
+    GetDocumentTextInput,
+    GetDocumentTextOutput,
+    new_get_document_text_step,
+)
+
+CONNECTION_NAME = "google-docs-policy"
+
+
+@dataclass(frozen=True, slots=True)
+class PolicyReadRequest:
+    """Identify the Google Doc whose first tab should be read."""
+
+    document_id: str = field(default="", metadata={"dex_json_name": "documentId"})
+
+
+# dex:group group-id:google-docs group-label:"Google Docs"
+# dex:explanation text:"Complete with the bounded text returned by Google Docs."
+class _CompletePolicyRead(dex.Step[QueryResult[GetDocumentTextOutput]]):
+    def get_step_type(self) -> str:
+        return "CompleteGoogleDocsPolicyRead"
+
+    def execute(
+        self, context: dex.Context, input: QueryResult[GetDocumentTextOutput]
+    ) -> dex.StepDecision:
+        return dex.graceful_complete(input.value)
+
+
+class PolicyReadFlow(dex.Flow[PolicyReadRequest]):
+    """Read one policy document through the static Google Docs connection."""
+
+    def __init__(self, connection: Connection) -> None:
+        if connection.reference.name != CONNECTION_NAME:
+            raise ValueError("policy read requires the static Google Docs connection")
+        self._complete = _CompletePolicyRead()
+        self._read = new_get_document_text_step(
+            step_type="ReadGoogleDocsPolicy",
+            step_input_type=PolicyReadRequest,
+            annotations={
+                "groupId": "google-docs",
+                "groupLabel": "Google Docs",
+                "explanation": "Read the first tab as plain text with pending suggestions rejected.",
+            },
+            connection=connection,
+            connection_name=CONNECTION_NAME,
+            map_to_operation_input=lambda request: GetDocumentTextInput(
+                document_id=request.document_id, format="plainText"
+            ),
+            read=self._complete,
+        )
+
+    def get_flow_type(self) -> str:
+        """Return the stable Flow identity."""
+        return "GoogleDocsPolicyRead"
+
+    def get_steps(self) -> dex.StepList[PolicyReadRequest]:
+        """Register the read and completion Steps."""
+        return dex.StepList.start_step(self._read).other_steps(self._complete)

dex_connector_google_docs-0.1.0/examples/policy_read/integration_test.py

@@ -0,0 +1,93 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Exercise the checked-in Flow with a real Dex Worker and Client."""
+
+import asyncio
+import os
+from datetime import timedelta
+from pathlib import Path
+from uuid import uuid4
+
+import dex
+import httpx
+import pytest
+from dex_connectors.sdk import ConnectionRef, SecretString, StaticCredentialProvider
+
+from dex_connectors.google_docs import Client, Config, Credentials, GetDocumentTextOutput, new_connection
+
+from .flow import CONNECTION_NAME, PolicyReadFlow, PolicyReadRequest
+
+
+@pytest.mark.asyncio
+async def test_read_retries_and_unwired_not_found_fails(tmp_path: Path) -> None:
+    """Verify the read's retry and optional branch through real Dex state."""
+    requests: list[httpx.Request] = []
+
+    def answer(request: httpx.Request) -> httpx.Response:
+        requests.append(request)
+        if request.url.path.endswith("/missing"):
+            return httpx.Response(404, json={"error": {"code": 404}})
+        if len(requests) == 1:
+            return httpx.Response(503, json={"error": {"code": 503}})
+        return httpx.Response(200, json={
+            "documentId": "policy123",
+            "title": "Policy",
+            "revisionId": "rev-1",
+            "tabs": [{
+                "tabProperties": {"tabId": "t.0"},
+                "documentTab": {"body": {"content": [
+                    {"endIndex": 1, "sectionBreak": {}},
+                    {"startIndex": 1, "endIndex": 8, "paragraph": {
+                        "elements": [{"textRun": {"content": "Policy\n"}}]
+                    }},
+                ]}},
+            }],
+        })
+
+    reference = ConnectionRef("google", CONNECTION_NAME)
+    credentials = StaticCredentialProvider({
+        reference: Credentials(access_token=SecretString("inert-docs-token"))
+    })
+    async with httpx.AsyncClient(transport=httpx.MockTransport(answer)) as provider_http_client:
+        provider = Client(
+            Config(docs_endpoint="http://127.0.0.1:44350", drive_endpoint="http://127.0.0.1:44350"),
+            credentials,
+            provider_http_client,
+        )
+        connection = new_connection(provider, reference)
+        flow = PolicyReadFlow(connection)
+        registry = dex.Registry([flow], allow_async_handlers=True)
+        cache = dex.open_blob_cache(dex.BlobCacheConfig(str(tmp_path / "blobs"), 1 << 24))
+        address = os.environ["DEX_FLOW_SERVICE_ADDRESS"]
+        worker = dex.AsyncWorker(registry, cache, dex.WorkerOptions(server_address=address))
+        worker_task = asyncio.create_task(worker.start())
+        try:
+            await worker.wait_pull_registered(timeout=20)
+            async with dex.AsyncClient(
+                registry, cache, dex.ClientOptions(server_address=address)
+            ) as client:
+                successful_id = f"google-docs-python-{uuid4().hex}"
+                await client.start_flow(flow, successful_id, PolicyReadRequest("policy123"))
+                successful = await asyncio.wait_for(
+                    client.wait_for_flow(successful_id, timedelta(seconds=20)), 30
+                )
+                assert successful.status == dex.FlowStatus.COMPLETED, successful.error_message
+                output = successful.single_output(GetDocumentTextOutput)
+                assert output.document_id == "policy123"
+                assert output.text == "Policy"
+                assert len(requests) == 2
+
+                missing_id = f"google-docs-python-{uuid4().hex}"
+                await client.start_flow(flow, missing_id, PolicyReadRequest("missing"))
+                missing = await asyncio.wait_for(
+                    client.wait_for_flow(missing_id, timedelta(seconds=20)), 30
+                )
+                assert missing.status == dex.FlowStatus.FAILED
+                assert missing.error_message is not None
+                assert "notFound" in missing.error_message
+                assert len(requests) == 3
+        finally:
+            await worker.stop()
+            await worker_task
+            cache.close()
+            await connection.aclose()

dex_connector_google_docs-0.1.0/examples/policy_read/start.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Start a policy read through the static Google Docs connection."""
+
+import argparse
+import asyncio
+import os
+import tempfile
+
+import dex
+from dex_connectors.sdk.projectconfig import load_from_environment
+
+from dex_connectors.google_docs import new_project_connection
+
+from .flow import CONNECTION_NAME, PolicyReadFlow, PolicyReadRequest
+
+
+async def start_policy_read(flow_id: str, document_id: str) -> str:
+    """Start one Flow for a Google Docs document ID."""
+    project = await load_from_environment()
+    connection = new_project_connection(project, CONNECTION_NAME)
+    try:
+        flow = PolicyReadFlow(connection)
+        registry = dex.Registry([flow], allow_async_handlers=True)
+        with tempfile.TemporaryDirectory(prefix="google-docs-python-start-blobs-") as directory:
+            cache = dex.open_blob_cache(dex.BlobCacheConfig(directory, 1 << 24))
+            try:
+                async with dex.AsyncClient(
+                    registry, cache,
+                    dex.ClientOptions(
+                        server_address=os.environ.get("DEX_FLOW_SERVICE_ADDRESS", "localhost:8801")
+                    ),
+                ) as client:
+                    return await client.start_flow(flow, flow_id, PolicyReadRequest(document_id))
+            finally:
+                cache.close()
+    finally:
+        await connection.aclose()
+        await project.close()
+
+
+def main() -> None:
+    """Parse a unique Flow ID and document ID."""
+    parser = argparse.ArgumentParser(description="Read a Google Doc through Dex")
+    parser.add_argument("flow_id")
+    parser.add_argument("document_id")
+    arguments = parser.parse_args()
+    print(asyncio.run(start_policy_read(arguments.flow_id, arguments.document_id)))
+
+
+if __name__ == "__main__":
+    main()

dex_connector_google_docs-0.1.0/examples/policy_read/worker.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Worker entrypoint for the Google Docs policy read 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.google_docs import new_project_connection
+
+from .flow import CONNECTION_NAME, PolicyReadFlow
+
+
+async def run_worker() -> None:
+    """Load the connection and serve policy read executions."""
+    project = await load_from_environment()
+    connection = None
+    cache = None
+    try:
+        connection = new_project_connection(project, CONNECTION_NAME)
+        registry = dex.Registry([PolicyReadFlow(connection)], allow_async_handlers=True)
+        cache_directory = os.environ.get(
+            "DEX_BLOB_CACHE_DIR", str(Path(tempfile.gettempdir()) / "dex-google-docs-policy-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 the Worker until stopped."""
+    asyncio.run(run_worker())
+
+
+if __name__ == "__main__":
+    main()

dex_connector_google_docs-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dex-connector-google-docs"
+version = "0.1.0"
+description = "Dex-native Google Docs connector"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["dex-connectors-sdk==0.7.0", "dex-python-sdk>=1.28.0", "httpx>=0.27"]
+
+[project.urls]
+Source = "https://github.com/superdurable/dex-connectors-library/tree/main/connectors/google/docs/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_google_docs-0.1.0/src/dex_connectors/google_docs/__init__.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Super Durable
+# SPDX-License-Identifier: MIT
+"""Dex-native Google Docs provider operations and Step factories."""
+
+from .client import Client, Config, Credentials
+from .connection import Connection, new_connection, new_connection_with_operations, new_project_connection
+from .models import (
+    AppendTextInput,
+    AppendTextOutput,
+    CreatedDocument,
+    CreateDocumentInput,
+    CreateDocumentOutput,
+    GetDocumentTextInput,
+    GetDocumentTextOutput,
+    PlaceholderReplacement,
+    PlaceholderReplacementResult,
+    ReplaceDocumentTextInput,
+    ReplaceDocumentTextOutput,
+)
+from .steps import (
+    new_append_text_step,
+    new_create_document_step,
+    new_get_document_text_step,
+    new_replace_document_text_step,
+)
+
+__all__ = [
+    "Client",
+    "Config",
+    "Credentials",
+    "Connection",
+    "new_connection",
+    "new_connection_with_operations",
+    "new_project_connection",
+    "AppendTextInput",
+    "AppendTextOutput",
+    "CreatedDocument",
+    "CreateDocumentInput",
+    "CreateDocumentOutput",
+    "GetDocumentTextInput",
+    "GetDocumentTextOutput",
+    "PlaceholderReplacement",
+    "PlaceholderReplacementResult",
+    "ReplaceDocumentTextInput",
+    "ReplaceDocumentTextOutput",
+    "new_append_text_step",
+    "new_create_document_step",
+    "new_get_document_text_step",
+    "new_replace_document_text_step",
+]

dex_connector_google_docs-0.1.0/src/dex_connectors/google_docs/_generated/__init__.py

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

dex_connector_google_docs-0.1.0/src/dex_connectors/google_docs/_generated/config.py

@@ -0,0 +1,32 @@
+# 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:
+
+    docs_endpoint: str = "https://docs.googleapis.com"
+    drive_endpoint: str = "https://www.googleapis.com"
+    max_response_bytes: int = 8388608
+    max_text_bytes: int = 1048576
+
+setattr(Config, '__module__', 'dex_connectors.google_docs.client')
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+
+    auth_method_id: str = "google-oauth"
+    oauth_client_id: str | None = None
+    oauth_client_secret: SecretString | None = None
+    access_token: SecretString | None = None
+    refresh_token: SecretString | None = None
+    service_account_key: SecretString | None = None
+    delegated_user: str | None = None
+
+setattr(Credentials, '__module__', 'dex_connectors.google_docs.client')