codecraftai-restclient-twingate 1.2.0__py3-none-any.whl

ccai/restclient/twingate/__init__.py

@@ -0,0 +1,34 @@
+"""
+    .. module:: twingate
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: The ``codecraftai-restclient-twingate`` package — a typed,
+                   aspect-driven GraphQL client for the Twingate Admin API.
+
+    The package re-exports :class:`TwingateClient` (which implements the
+    :class:`IVPNControlPlane` protocol), the :class:`AspectsTwingate`
+    behaviour bundle and the :class:`GraphQLRequestBody` request dataclass.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from ccai.restclient.twingate.twingateclient import (
+    TwingateClient, GRAPHQL_LEAF
+)
+from ccai.restclient.twingate.aspectstwingate import (
+    AspectsTwingate, DEFAULT_TWINGATE_ASPECTS
+)
+from ccai.restclient.twingate.graphqlrequestbody import GraphQLRequestBody
+
+
+__all__ = [
+    "TwingateClient",
+    "GRAPHQL_LEAF",
+    "AspectsTwingate",
+    "DEFAULT_TWINGATE_ASPECTS",
+    "GraphQLRequestBody",
+]

ccai/restclient/twingate/_codegen/__init__.py

@@ -0,0 +1,12 @@
+"""
+    .. module:: _codegen
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Maintainer-facing GraphQL schema introspection and emitter
+                   package. See ``import_schema.py`` for the regeneration flow.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []

ccai/restclient/twingate/_codegen/emitter.py

@@ -0,0 +1,189 @@
+"""
+    .. module:: emitter
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that contains the schema emitter — walks a GraphQL
+                   introspection ``__schema`` payload and produces Python
+                   source text for ``SchemaObject`` and ``enum.Enum`` types.
+
+    See the "Codegen Decision" section of ``AGENTS.md``. The emitter is
+    retained so a maintainer with a live network can regenerate; the
+    checked-in ``model/`` / ``inputs/`` modules were hand-authored from the
+    documented Twingate surface because no live network was available at
+    build time.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+from typing import Any, Dict, List
+
+from ccai.restclient.twingate._codegen.typemap import (
+    python_typename_for_scalar
+)
+
+
+GENERATED_HEADER = (
+    '"""\n'
+    "    DO NOT EDIT — generated by\n"
+    "    python -m ccai.restclient.twingate._codegen.import_schema\n"
+    '"""\n'
+)
+
+
+def resolve_type_expression(*, type_ref: Dict[str, Any]) -> str:
+    """
+        Resolve a GraphQL type reference into an emitted Python type
+        expression, applying the ``NON_NULL`` and ``LIST`` wrapping rules.
+
+        :param type_ref: The GraphQL type reference node.
+
+        :returns: The Python type expression string.
+    """
+    kind = type_ref.get("kind")
+    name = type_ref.get("name")
+    of_type = type_ref.get("ofType")
+
+    if kind == "NON_NULL":
+        # NON_NULL drops the Optional wrapper — emit the inner type bare.
+        rtnval = resolve_type_expression(type_ref=of_type)
+        return rtnval
+
+    if kind == "LIST":
+        inner = resolve_type_expression(type_ref=of_type)
+        rtnval = f"List[{inner}]"
+        return rtnval
+
+    if kind == "SCALAR":
+        rtnval = python_typename_for_scalar(scalar_name=name)
+        return rtnval
+
+    if kind == "ENUM":
+        rtnval = name
+        return rtnval
+
+    if kind == "OBJECT" or kind == "INPUT_OBJECT":
+        rtnval = name
+        return rtnval
+
+    rtnval = "Any"
+    return rtnval
+
+
+def emit_enum(*, type_node: Dict[str, Any]) -> str:
+    """
+        Emit Python source for a GraphQL ``ENUM`` type.
+
+        :param type_node: The ``__schema`` type node with ``kind=ENUM``.
+
+        :returns: Python source text for an :class:`enum.Enum` subclass.
+    """
+    name = type_node.get("name")
+    lines: List[str] = [GENERATED_HEADER, "import enum", "", "",
+                        f"class {name}(enum.Enum):",
+                        f'    """Mirror of the Twingate {name} GraphQL '
+                        f'enum."""']
+
+    enum_values = type_node.get("enumValues", [])
+    if enum_values is None:
+        enum_values = []
+
+    for value_node in enum_values:
+        value_name = value_node.get("name")
+        lines.append(f'    {value_name} = "{value_name}"')
+
+    lines.append("")
+    lines.append(f'__all__ = ["{name}"]')
+    lines.append("")
+
+    rtnval = "\n".join(lines)
+    return rtnval
+
+
+def emit_object(*, type_node: Dict[str, Any]) -> str:
+    """
+        Emit Python source for a GraphQL ``OBJECT`` or ``INPUT_OBJECT``
+        type as a :class:`SchemaObject` subclass.
+
+        :param type_node: The ``__schema`` type node.
+
+        :returns: Python source text for a :class:`SchemaObject` subclass.
+    """
+    name = type_node.get("name")
+    lines: List[str] = [
+        GENERATED_HEADER,
+        "from typing import Any, Dict, List",
+        "",
+        "from ccai.restclient.base.schemaobject import SchemaObject",
+        "from ccai.restclient.base.schemafield import Field",
+        "",
+        "",
+        f"class {name}(SchemaObject):",
+        f'    """Mirror of the Twingate {name} GraphQL type."""',
+        "",
+    ]
+
+    fields = type_node.get("fields")
+    if fields is None:
+        fields = type_node.get("inputFields", [])
+    if fields is None:
+        fields = []
+
+    for field_node in fields:
+        field_name = field_node.get("name")
+        type_ref = field_node.get("type", {})
+        type_expr = resolve_type_expression(type_ref=type_ref)
+        required = type_ref.get("kind") == "NON_NULL"
+        lines.append(
+            f"    {field_name}: {type_expr} = Field("
+            f"{type_expr!r}, required={required})")
+
+    lines.append("")
+    lines.append(f'__all__ = ["{name}"]')
+    lines.append("")
+
+    rtnval = "\n".join(lines)
+    return rtnval
+
+
+def emit_schema_modules(*, schema: Dict[str, Any]) -> Dict[str, str]:
+    """
+        Walk a GraphQL ``__schema`` payload and emit a mapping of module
+        file name to Python source text for every non-internal OBJECT,
+        INPUT_OBJECT and ENUM type.
+
+        :param schema: The ``__schema`` block of an introspection payload.
+
+        :returns: A mapping of ``<typename-lowercase>.py`` to source text.
+    """
+    emitted: Dict[str, str] = {}
+
+    types = schema.get("types", [])
+    if types is None:
+        types = []
+
+    for type_node in types:
+        name = type_node.get("name", "")
+        kind = type_node.get("kind", "")
+        if name.startswith("__"):
+            continue
+
+        if kind == "ENUM":
+            emitted[f"{name.lower()}.py"] = emit_enum(type_node=type_node)
+        elif kind == "OBJECT" or kind == "INPUT_OBJECT":
+            emitted[f"{name.lower()}.py"] = emit_object(type_node=type_node)
+
+    rtnval = emitted
+    return rtnval
+
+
+__all__ = [
+    "GENERATED_HEADER",
+    "resolve_type_expression",
+    "emit_enum",
+    "emit_object",
+    "emit_schema_modules",
+]

ccai/restclient/twingate/_codegen/import_schema.py

@@ -0,0 +1,182 @@
+"""
+    .. module:: import_schema
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Maintainer-facing GraphQL introspection import script for
+                   the Twingate Admin API schema.
+
+    Run by hand against a real Twingate network when the upstream schema
+    changes::
+
+        python -m ccai.restclient.twingate._codegen.import_schema \\
+            --network <slug> --token <api-token>
+
+    See the "Codegen Decision" section of ``AGENTS.md`` — at the time of
+    package authoring no live Twingate network was available, so the
+    generated output under ``model/``, ``inputs/``, ``queries/`` and
+    ``mutations/`` is hand-authored from the documented Twingate GraphQL
+    surface. This script remains the mechanical re-sync path for a
+    maintainer who does have a live network.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import argparse
+import hashlib
+import json
+import os
+
+from http import HTTPStatus
+from typing import Any, Dict
+
+import requests
+
+from ccai.errors.exceptions import ConfigurationError
+
+
+# The canonical GraphQL introspection query. Trimmed to the fields the
+# emitter consumes.
+INTROSPECTION_QUERY = (
+    "query IntrospectionQuery {"
+    " __schema {"
+    " queryType { name } mutationType { name }"
+    " types {"
+    " kind name"
+    " fields { name type { kind name ofType { kind name"
+    " ofType { kind name } } } }"
+    " enumValues { name }"
+    " inputFields { name type { kind name ofType { kind name } } }"
+    " } } }"
+)
+
+
+def _spec_directory() -> str:
+    """
+        Resolve the absolute path of the ``_spec`` directory.
+
+        :returns: The ``_spec`` directory path.
+    """
+    here = os.path.dirname(os.path.abspath(__file__))
+    package_dir = os.path.dirname(here)
+    rtnval = os.path.join(package_dir, "_spec")
+    return rtnval
+
+
+def introspect(*, network_slug: str, api_token: str,
+               timeout_seconds: float = 30.0) -> Dict[str, Any]:
+    """
+        POST the canonical GraphQL introspection query to a live Twingate
+        network and return the decoded ``__schema`` payload.
+
+        :param network_slug: The Twingate network slug.
+        :param api_token: The Twingate service-account API token.
+        :param timeout_seconds: HTTP request timeout.
+
+        :returns: The decoded GraphQL introspection response.
+
+        :raises: :class:`ConfigurationError` when the upstream response is
+            non-200 or carries GraphQL ``errors``.
+    """
+    endpoint = f"https://{network_slug}.twingate.com/api/graphql/v1"
+
+    headers = {
+        "Authorization": f"Bearer {api_token}",
+        "X-Network-Slug": network_slug,
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+    }
+    body = {"query": INTROSPECTION_QUERY, "operationName": "IntrospectionQuery"}
+
+    response = requests.post(
+        endpoint, headers=headers, json=body, timeout=timeout_seconds)
+
+    if response.status_code != HTTPStatus.OK:
+        err_msg_lines = [
+            "Twingate GraphQL introspection returned a non-200 status.",
+            f"NETWORK SLUG: {network_slug}",
+            f"STATUS: {response.status_code}",
+            f"BODY: {response.text[:512]}",
+        ]
+        err_msg = os.linesep.join(err_msg_lines)
+        raise ConfigurationError(err_msg)
+
+    payload = response.json()
+
+    errors = payload.get("errors")
+    if errors is not None and len(errors) > 0:
+        err_msg_lines = [
+            "Twingate GraphQL introspection returned GraphQL errors.",
+            f"NETWORK SLUG: {network_slug}",
+            f"ERRORS: {errors}",
+        ]
+        err_msg = os.linesep.join(err_msg_lines)
+        raise ConfigurationError(err_msg)
+
+    rtnval = payload
+    return rtnval
+
+
+def save_schema(*, payload: Dict[str, Any]) -> str:
+    """
+        Save an introspection payload to ``_spec/schema.json`` and record
+        its SHA-256 in ``_spec/schema.sha256``.
+
+        :param payload: The introspection payload to persist.
+
+        :returns: The computed SHA-256 hex digest.
+    """
+    spec_dir = _spec_directory()
+    if not os.path.isdir(spec_dir):
+        os.makedirs(spec_dir)
+
+    schema_text = json.dumps(payload, indent=2, sort_keys=True)
+    schema_bytes = schema_text.encode("utf-8")
+
+    digest = hashlib.sha256(schema_bytes).hexdigest()
+
+    schema_path = os.path.join(spec_dir, "schema.json")
+    with open(schema_path, "w", encoding="utf-8") as schema_file:
+        schema_file.write(schema_text)
+
+    hash_path = os.path.join(spec_dir, "schema.sha256")
+    with open(hash_path, "w", encoding="utf-8") as hash_file:
+        hash_file.write(digest)
+
+    rtnval = digest
+    return rtnval
+
+
+def main() -> int:
+    """
+        Command-line entry point for the introspection import script.
+
+        :returns: Process exit code — ``0`` on success.
+    """
+    parser = argparse.ArgumentParser(
+        description="Introspect a live Twingate network and dump the "
+                    "GraphQL schema.")
+    parser.add_argument(
+        "--network", required=True, help="Twingate network slug.")
+    parser.add_argument(
+        "--token", required=True,
+        help="Twingate service-account API token.")
+    args = parser.parse_args()
+
+    payload = introspect(network_slug=args.network, api_token=args.token)
+    digest = save_schema(payload=payload)
+
+    print(f"Twingate schema saved. SHA-256: {digest}")
+
+    rtnval = 0
+    return rtnval
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = ["INTROSPECTION_QUERY", "introspect", "save_schema", "main"]

ccai/restclient/twingate/_codegen/typemap.py

@@ -0,0 +1,76 @@
+"""
+    .. module:: typemap
+        :platform: Darwin, Linux, Unix, Windows
+        :synopsis: Module that maps GraphQL scalar type names to Python types
+                   for the schema-import emitter.
+
+    .. moduleauthor:: Myron Walker <myron.walker@gmail.com>
+"""
+
+__author__ = "Myron Walker"
+__copyright__ = "Copyright 2025, Code Craft AI LLC"
+__credits__ = []
+
+
+import datetime
+
+from typing import Any, Dict
+
+
+# GraphQL scalar type name -> (python type object, python type source name).
+GRAPHQL_SCALAR_TYPEMAP: Dict[str, Any] = {
+    "String": str,
+    "Int": int,
+    "Boolean": bool,
+    "ID": str,
+    "Float": float,
+    "DateTime": datetime.datetime,
+    "JSON": dict,
+}
+
+
+# GraphQL scalar type name -> python type expression as used in emitted code.
+GRAPHQL_SCALAR_TYPENAMES: Dict[str, str] = {
+    "String": "str",
+    "Int": "int",
+    "Boolean": "bool",
+    "ID": "str",
+    "Float": "float",
+    "DateTime": "datetime.datetime",
+    "JSON": "Dict[str, Any]",
+}
+
+
+def python_type_for_scalar(*, scalar_name: str) -> Any:
+    """
+        Resolve the Python type object for a GraphQL scalar type name.
+
+        :param scalar_name: The GraphQL scalar type name.
+
+        :returns: The Python type object, defaulting to :class:`str` for
+            unrecognised scalar names so the emitter never fails closed.
+    """
+    rtnval = GRAPHQL_SCALAR_TYPEMAP.get(scalar_name, str)
+    return rtnval
+
+
+def python_typename_for_scalar(*, scalar_name: str) -> str:
+    """
+        Resolve the emitted Python type expression for a GraphQL scalar
+        type name.
+
+        :param scalar_name: The GraphQL scalar type name.
+
+        :returns: The Python type expression string, defaulting to ``str``
+            for unrecognised scalar names.
+    """
+    rtnval = GRAPHQL_SCALAR_TYPENAMES.get(scalar_name, "str")
+    return rtnval
+
+
+__all__ = [
+    "GRAPHQL_SCALAR_TYPEMAP",
+    "GRAPHQL_SCALAR_TYPENAMES",
+    "python_type_for_scalar",
+    "python_typename_for_scalar",
+]

ccai/restclient/twingate/_spec/README.md

@@ -0,0 +1,32 @@
+# `_spec/` — Twingate GraphQL Schema Snapshot
+
+This directory is the home of the checked-in Twingate GraphQL introspection
+result (`schema.json`) and its integrity hash (`schema.sha256`).
+
+## Codegen status
+
+Per the §9.2a decision rule in `PLAN-VPN-AND-CLOUD-PROVISIONING.md` and the
+"Codegen Decision" section of the repository `AGENTS.md`: at package-authoring
+time no live Twingate network + API token was available, so GraphQL
+introspection could **not** be run. The typed DTOs, inputs, query builders and
+mutation builders under `model/`, `inputs/`, `queries/` and `mutations/` were
+**hand-authored** from the documented Twingate GraphQL surface (and validated
+against the working M3 `TwingateControlPlane`).
+
+`schema.json` here is a **representative hand-authored snapshot** covering the
+type surface the client consumes (`Resource`, `Group`, `Connector`,
+`RemoteNetwork`, `Device`, `ConnectorState`, `ProtocolsInput`). It is *not* a
+full live introspection dump.
+
+## Regenerating from a live network
+
+A maintainer with a live Twingate network can produce the authoritative dump:
+
+```
+python -m ccai.restclient.twingate._codegen.import_schema \
+    --network <slug> --token <api-token>
+```
+
+That rewrites `schema.json` + `schema.sha256` and the emitter
+(`_codegen/emitter.py`) can then be used to validate or extend the hand-authored
+modules.