fancy-google-docs 0.3.4__tar.gz → 0.4.0__tar.gz

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/CHANGELOG.md

@@ -8,6 +8,21 @@ The four packages share one version, because they are generated from one
 `provider/` definition and a version that meant something different in each
 would be a version nobody could reason about.
 
+## [0.4.0] — 2026-10-01
+
+### Added
+
+- **`text_insert`** — insert plain text into an existing document's body
+  (`documents.batchUpdate`, a single `insertText` request). No scope
+  change. Until now `document_create` could only make a BLANK document
+  with no way to ever put content in it.
+- Deliberately NOT included: the general `batchUpdate` escape hatch (an
+  author-supplied array of Google's dozens of typed request kinds —
+  `deleteContentRange`, `replaceAllText`, `insertTable`, text styling,
+  ...). That needs an array-of-polymorphic-objects config shape nothing
+  in this estate has used before — a real second need, not a first
+  guess, same bar as everything in `vocabulary-deferred.md`.
+
 ## [0.3.4] — 2026-09-12
 
 ### Changed

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fancy-google-docs
-Version: 0.3.4
+Version: 0.4.0
 Summary: Google Docs for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK.
 Project-URL: Homepage, https://github.com/Fancy-Friends/google-docs
 Project-URL: Issues, https://github.com/Fancy-Friends/google-docs/issues
@@ -22,6 +22,8 @@ Description-Content-Type: text/markdown
 
 # Google Docs
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 Google Docs for [fancy-flow][flow] — as **four imported, versioned packages**, one
 per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
 change.
@@ -97,6 +99,18 @@ Create a blank Google Docs document.
 |---|---|---|
 | `title` | yes | The title of the new blank document. |
 
+#### `text_insert` — Insert text into a Google Doc
+
+Insert plain text at a position in an existing document's body.
+
+`POST /v1/documents/{documentId}:batchUpdate` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `documentId` | yes | From document_create's data.documentId, or the id in the document's own URL. |
+| `text` | yes | Inserted verbatim. A newline in it starts a new paragraph, carrying the style of whatever paragraph the insertion point sits in. |
+| `index` | yes | A zero-based position in UTF-16 code units, but 0 itself is never valid -- Google's body content starts at index 1. 1 is the very beginning of a freshly created blank document. To append after existing content, read the document's own length first (not yet offered by this connector) and insert there instead. |
+
 ## Run it before you have credentials
 
 Every operation ships a **faker**, whether or not Google Docs has a sandbox. Set a

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/README.md

@@ -1,5 +1,7 @@
 # Google Docs
 
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
 Google Docs for [fancy-flow][flow] — as **four imported, versioned packages**, one
 per runtime. Not vendored source: a copy cannot be upgraded, and third-party APIs
 change.
@@ -75,6 +77,18 @@ Create a blank Google Docs document.
 |---|---|---|
 | `title` | yes | The title of the new blank document. |
 
+#### `text_insert` — Insert text into a Google Doc
+
+Insert plain text at a position in an existing document's body.
+
+`POST /v1/documents/{documentId}:batchUpdate` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `documentId` | yes | From document_create's data.documentId, or the id in the document's own URL. |
+| `text` | yes | Inserted verbatim. A newline in it starts a new paragraph, carrying the style of whatever paragraph the insertion point sits in. |
+| `index` | yes | A zero-based position in UTF-16 code units, but 0 itself is never valid -- Google's body content starts at index 1. 1 is the very beginning of a freshly created blank document. To append after existing content, read the document's own length first (not yet offered by this connector) and insert there instead. |
+
 ## Run it before you have credentials
 
 Every operation ships a **faker**, whether or not Google Docs has a sandbox. Set a

fancy_google_docs-0.4.0/art/fancified.svg

@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="28" role="img" aria-label="Fancified — built with Fancy UI">
+  <title>Fancified · built with Fancy UI</title>
+  <defs>
+    <linearGradient id="fcdBg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#6d28d9"/>
+      <stop offset=".5" stop-color="#9333ea"/>
+      <stop offset="1" stop-color="#d946ef"/>
+    </linearGradient>
+    <linearGradient id="fcdGloss" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#ffffff" stop-opacity=".30"/>
+      <stop offset=".55" stop-color="#ffffff" stop-opacity="0"/>
+    </linearGradient>
+    <clipPath id="fcdClip"><rect width="128" height="28" rx="7"/></clipPath>
+  </defs>
+  <g clip-path="url(#fcdClip)">
+    <rect width="128" height="28" fill="url(#fcdBg)"/>
+    <rect width="34" height="28" fill="#3b0764" fill-opacity=".5"/>
+    <rect width="128" height="13" fill="url(#fcdGloss)"/>
+    <g fill="#fff">
+      <path transform="translate(17 14)" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+      <path transform="translate(25.5 7.5) scale(.34)" fill-opacity=".85" d="M0 -7 C.6 -2.2 2.2 -.6 7 0 C2.2 .6 .6 2.2 0 7 C-.6 2.2 -2.2 .6 -7 0 C-2.2 -.6 -.6 -2.2 0 -7 Z"/>
+    </g>
+    <text x="81" y="18.5" fill="#ffffff" text-anchor="middle" font-family="'Segoe UI',Verdana,'DejaVu Sans',sans-serif" font-size="12" font-weight="700" letter-spacing=".3">Fancified</text>
+  </g>
+  <rect x=".5" y=".5" width="127" height="27" rx="6.5" fill="none" stroke="#ffffff" stroke-opacity=".22"/>
+</svg>

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fancy-google-docs"
-version = "0.3.4"
+version = "0.4.0"
 description = "Google Docs for Python — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP; no vendor SDK."
 readme = "README.md"
 # 3.11 matches fancy-flow-py's floor: 3.10 reaches end of life on 2026-10-31,
@@ -49,7 +49,7 @@ dev = [{ include-group = "test" }, { include-group = "lint" }, { include-group =
 packages = ["src/fancy_google_docs"]
 
 [tool.hatch.build.targets.sdist]
-include = ["/src", "/tests", "/README.md", "/CHANGELOG.md", "/LICENSE"]
+include = ["/src", "/tests", "/art", "/README.md", "/CHANGELOG.md", "/LICENSE"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/src/fancy_google_docs/__init__.py

@@ -18,10 +18,11 @@ from __future__ import annotations
 
 from ._fake import FakeValues
 from .actions.document_create import document_create
+from .actions.text_insert import text_insert
 from .faker import respond
 from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
 
-__version__ = "0.3.4"
+__version__ = "0.4.0"
 
 __all__ = [
     "BASE_URLS",
@@ -34,4 +35,5 @@ __all__ = [
     "descriptor",
     "document_create",
     "respond",
+    "text_insert",
 ]

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/src/fancy_google_docs/_runtime.py

@@ -308,14 +308,17 @@ _ALGORITHMS = {"sha256": hashlib.sha256, "sha1": hashlib.sha1, "sha512": hashlib
 def verify_hmac(
     *,
     raw: str,
-    signature: str | None,
+    signature: str | list[str] | None,
     secret: str | None,
-    payload: Callable[[str, str | None], str],
+    payload: Callable[..., str],
     algorithm: str,
     encoding: str = "hex",
     tolerance: int | None = None,
     timestamp: str | None = None,
     now: int | None = None,
+    secret_encoding: str = "utf8",  # noqa: S107 — how the secret is SPELLED, not one
+    secret_prefix: str | None = None,
+    id: str | None = None,
 ) -> Verification:
     """Verify one inbound delivery.
 
@@ -327,16 +330,36 @@ def verify_hmac(
     ``raw`` must be the body EXACTLY as received. Re-serialised JSON changes key
     order and whitespace and produces a mismatch that looks precisely like a
     wrong secret.
+
+    ``secret_encoding`` says how the SECRET is spelled: ``utf8`` (the default,
+    every provider before Svix — the key is the text's bytes) or ``base64``
+    (the key is the DECODED bytes; Svix's ``whsec_<base64>``, half of whose
+    bytes are not UTF-8). ``secret_prefix`` is stripped first, and its absence
+    is a refusal, never a guess.
     """
     if not secret:
         return Verification(False, "no signing secret is configured for this connection")
-    if not signature:
+
+    # A LIST when the provider sends several — Stripe signs once per active
+    # secret while a secret is rolled, Svix's header "could be any number of
+    # signatures" — and the delivery is accepted when ANY matches. A first-only
+    # rule fails every delivery whose first signature came from the new secret.
+    offered = signature if isinstance(signature, list) else [signature]
+    candidates = [s for s in offered if isinstance(s, str) and s]
+    if not candidates:
         return Verification(False, "the delivery carried no signature")
 
     digest = _ALGORITHMS.get(algorithm)
     if digest is None:
         return Verification(False, f'unsupported signature algorithm "{algorithm}"')
 
+    # The key is checked BEFORE anything is signed, so a secret that cannot be
+    # a key is named as such rather than producing a mismatch that reads like a
+    # wrong secret.
+    key = _secret_key_bytes(secret, secret_encoding, secret_prefix)
+    if isinstance(key, Verification):
+        return key
+
     if tolerance is not None:
         if not timestamp:
             return Verification(
@@ -355,16 +378,146 @@ def verify_hmac(
                 f"({abs(current - sent)}s old)",
             )
 
-    computed = hmac.new(secret.encode(), payload(raw, timestamp).encode(), digest)
+    # A payload that signs the delivery's ID (Svix) takes it as a third argument;
+    # the two-argument payloads every earlier scheme wrote are called as before.
+    signed = payload(raw, timestamp) if id is None else payload(raw, timestamp, id)
+    computed = hmac.new(key, signed.encode(), digest)
     expected = computed.hexdigest() if encoding == "hex" else _b64(computed.digest())
 
-    # Constant time, so a signature cannot be discovered one character at a time.
-    if not hmac.compare_digest(expected, signature):
+    # Constant time per candidate, so a signature cannot be discovered one
+    # character at a time; which candidate matched is not a secret.
+    if not any(hmac.compare_digest(expected, candidate) for candidate in candidates):
         return Verification(False, "the signature does not match")
 
     return Verification(True)
 
 
+def _secret_key_bytes(
+    secret: str,
+    secret_encoding: str = "utf8",  # noqa: S107 — how the secret is SPELLED, not one
+    secret_prefix: str | None = None,
+) -> bytes | Verification:
+    """The HMAC key a scheme's secret spells, or the refusal it earns."""
+    import base64
+    import binascii
+    import json
+    import re
+
+    material = secret
+    if secret_prefix is not None:
+        if not material.startswith(secret_prefix):
+            return Verification(
+                False, f"signing secret does not start with {json.dumps(secret_prefix)}"
+            )
+        material = material[len(secret_prefix) :]
+
+    if secret_encoding == "base64":  # noqa: S105 — a spelling, not a password
+        # Strict: a lenient decode of a KEY is a key nobody can reason about.
+        well_formed = re.fullmatch(r"[A-Za-z0-9+/]*={0,2}", material) is not None
+        if not material or len(material) % 4 != 0 or not well_formed:
+            return Verification(False, "signing secret is not valid base64")
+        try:
+            return base64.b64decode(material, validate=True)
+        except (binascii.Error, ValueError):
+            return Verification(False, "signing secret is not valid base64")
+
+    return material.encode()
+
+
+def verify_shared_token(
+    *,
+    raw: str,
+    headers: dict[str, str],
+    secret: str | None,
+    placement: str,
+    name: str,
+) -> Verification:
+    """Verify a delivery by a token the provider ECHOES rather than a signature it computes.
+
+    Google Calendar sends the channel's ``token`` back in ``X-Goog-Channel-Token``
+    on every notification — with an EMPTY body, so there is nothing to sign.
+    Microsoft Graph sends ``clientState`` inside every item of the
+    notification's ``value`` array. Same refusal-by-default as ``verify_hmac``,
+    same result shape, and a constant-time comparison: a token is a secret.
+
+    ``placement`` is ``header`` (then ``name`` is the header) or ``body`` (then
+    ``name`` is a dotted path into the JSON body; a segment ending in ``[]``
+    means EVERY element of that array, all of which must match — one wrong item
+    refuses the whole delivery). The reasons are the connector core's exact
+    strings, so a host logs the same words whichever runtime answered.
+    """
+    if not secret:
+        return Verification(False, "no shared token configured for this trigger")
+
+    tokens: list[Any]
+    if placement == "header":
+        tokens = [next((v for k, v in headers.items() if k.lower() == name.lower()), None)]
+    else:
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            return Verification(False, "delivery body is not JSON")
+        tokens = _read_tokens(parsed, name.split("."))
+
+    present = [t for t in tokens if t is not None and t != ""]
+    if not present:
+        return Verification(False, "delivery carried no token")
+
+    # Every element is compared, none is skipped: a batch is accepted as a whole
+    # or refused as a whole.
+    matched = len(present) == len(tokens)
+    for token in present:
+        matched = (isinstance(token, str) and hmac.compare_digest(secret, token)) and matched
+
+    return Verification(True) if matched else Verification(False, "token did not match")
+
+
+def _read_tokens(value: Any, segments: list[str]) -> list[Any]:
+    """Every value at a dotted path; a ``[]`` segment fans out over a list. Absent is None."""
+    if not segments:
+        return [value]
+
+    head, rest = segments[0], segments[1:]
+    each_element = head.endswith("[]")
+    key = head[:-2] if each_element else head
+
+    if not isinstance(value, dict) or key not in value:
+        return [None]
+    nxt = value[key]
+
+    if not each_element:
+        return _read_tokens(nxt, rest)
+    if not isinstance(nxt, list):
+        return [None]
+
+    found: list[Any] = []
+    for element in nxt:
+        found.extend(_read_tokens(element, rest))
+
+    return found
+
+
+def handshake_response(
+    param: str | None, query: dict[str, str | list[str]], content_type: str = "text/plain"
+) -> dict[str, Any] | None:
+    """Answer a provider's challenge — Graph POSTs ``?validationToken=…`` when a
+    subscription is created and refuses to create it unless the token comes
+    back, decoded, as ``text/plain``. The pure half: what to send, or None when
+    the request is not a challenge at all (no parameter, an empty one, or a
+    trigger that declares no handshake). ``query`` is already URL-decoded by
+    the framework.
+    """
+    if param is None:
+        return None
+
+    raw = query.get(param)
+    token = raw[0] if isinstance(raw, list) and raw else raw
+    if not token or isinstance(token, list):
+        return None
+
+    return {"status": 200, "contentType": content_type, "body": token}
+
+
 def _b64(raw: bytes) -> str:
     import base64
 

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/src/fancy_google_docs/actions/__init__.py

@@ -8,7 +8,9 @@
 # npm run provider -- google_docs
 
 from .document_create import document_create
+from .text_insert import text_insert
 
 __all__ = [
     "document_create",
+    "text_insert",
 ]

fancy_google_docs-0.4.0/src/fancy_google_docs/actions/text_insert.py

@@ -0,0 +1,161 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/actions/text-insert.json by weaver's generator.
+# A hand-edit here is destroyed by the next protocol sync, which is worse than
+# being rejected, because it works until it silently does not. Fix
+# provider/actions/text-insert.json (or weaver's template/) and regenerate:
+#
+# npm run provider -- google_docs
+
+"""Insert plain text at a position in an existing document's body.
+
+POST /v1/documents/{documentId}:batchUpdate —
+https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/batchUpdate
+
+This describes the request. `call` resolves the connection, picks the
+estate, and either calls Google Docs or calls the faker.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._runtime import CallResult, ConnectorConfigError, Mode, call
+from ..service import descriptor
+
+OPERATION = "text_insert"
+METHOD = "POST"
+PATH = "/v1/documents/{documentId}:batchUpdate"
+SIDE_EFFECTS = "unsafe-to-replay"
+
+
+def body(config: dict[str, Any]) -> dict[str, Any]:
+    """Build the JSON body for one call, failing loudly and specifically."""
+    if config.get("documentId") is None or config.get("documentId") == "":
+        raise ConnectorConfigError(
+            "text_insert: \"documentId\" is required (Document ID)."
+        )
+
+    if config.get("text") is None or config.get("text") == "":
+        raise ConnectorConfigError(
+            "text_insert: \"text\" is required (Text)."
+        )
+
+    index = config.get("index")
+    if index is not None and index != "":
+        try:
+            _n = float(index)
+        except (TypeError, ValueError):
+            _n = None
+        if _n is None or _n != int(_n) or _n < 1:
+            raise ConnectorConfigError(
+                "text_insert: \"index\" must be a integer, got "
+                f"{index!r}."
+            )
+    else:
+        raise ConnectorConfigError(
+            "text_insert: \"index\" is required (Insert at index)."
+        )
+
+    out: dict[str, Any] = {}
+    _value = config.get("text")
+    if _value is None or _value == "":
+        raise ConnectorConfigError("text_insert: \"text\" is required.")
+
+    out["requests.0.insertText.text"] = str(_value)
+    _value = config.get("index")
+    if _value is None or _value == "":
+        raise ConnectorConfigError("text_insert: \"index\" is required.")
+
+    out["requests.0.insertText.location.index"] = int(float(_value))
+
+    return _nest_fields(out)
+
+
+
+def path(config: dict[str, Any]) -> str:
+    """The request path, with each config value URL-ENCODED into it.
+
+    `PATH` above is the TEMPLATE, which is what the descriptor advertises;
+    this is what a caller sends. A value interpolated raw changes WHICH URL is
+    called — a range like `Sheet1!A:B`, or a sheet named `Q1/Q2` — and the
+    provider answers 404 about the document rather than about the encoding.
+    """
+    return (
+        "/v1/documents/"
+        + quote(str(config.get("documentId") or ""), safe="")
+        + ":batchUpdate"
+    )
+
+def text_insert(
+    config: dict[str, Any],
+    *,
+    credentials: dict[str, str | None] | None = None,
+    mode: Mode = "auto",
+    connection_id: str | None = None,
+    attempts: int = 3,
+) -> CallResult:
+    """Insert plain text at a position in an existing document's body."""
+    return call(
+        descriptor(),
+        operation=OPERATION,
+        method=METHOD,
+        path=PATH,
+        json_body=body(config),
+        config=config,
+        credentials=credentials,
+        mode=mode,
+        connection_id=connection_id,
+        attempts=attempts,
+    )
+
+
+
+def _nest_fields(flat: dict[str, Any]) -> dict[str, Any]:
+    """`{"properties.email": x}` -> `{"properties": {"email": x}}`.
+
+    A dotted `as` means NESTING, and only a JSON body can nest -- in a form body
+    that spelling already means a literal dotted key.
+    """
+    out: dict[str, Any] = {}
+
+    for path, value in flat.items():
+        parts = path.split(".")
+        node = out
+
+        for key in parts[:-1]:
+            found = node.get(key)
+            if not isinstance(found, dict):
+                found = {}
+                node[key] = found
+            node = found
+
+        node[parts[-1]] = value
+
+    # The ROOT is always an object -- a JSON body's top level is never a list
+    # -- so only its VALUES are converted. That also keeps the return type
+    # honest: `_listify` returns Any, and returning it directly is a
+    # no-any-return error under mypy --strict.
+    return {key: _listify(value) for key, value in out.items()}
+
+
+def _listify(node: Any) -> Any:
+    """A mapping whose keys are 0, 1, 2 ... is an ARRAY, not an object.
+
+    `dateRanges.0.startDate` has to become `[{...}]`. PHP produced the list by
+    accident -- its integer-keyed arrays serialise as JSON arrays -- while
+    TypeScript and Python produced `{"0": {...}}`, which the provider refuses
+    as the wrong type. The parity suite is what caught the disagreement, and
+    converting at the END keeps the walk above simple.
+    """
+    if not isinstance(node, dict):
+        return node
+
+    walked = {key: _listify(value) for key, value in node.items()}
+    wanted = [str(index) for index in range(len(walked))]
+
+    if walked and list(walked.keys()) == wanted:
+        return [walked[key] for key in wanted]
+
+    return walked

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/src/fancy_google_docs/faker.py

@@ -24,6 +24,18 @@ from typing import Any
 from ._fake import FakeValues
 
 
+def _as_number(value: Any) -> float | None:
+    """The coercion an `"as": "integer" | "number"` config binding uses: a value
+    that IS a number, never int(float(...))'s uncaught ValueError on one that
+    merely looks like text (a text field's auto-generated example, before an
+    author has typed a real one).
+    """
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
 def _document_create(config: dict[str, Any], fake: FakeValues) -> Any:
     return {
         "documentId": fake.id("1Doc"),
@@ -35,6 +47,19 @@ def _document_create(config: dict[str, Any], fake: FakeValues) -> Any:
     }
 
 
+def _text_insert(config: dict[str, Any], fake: FakeValues) -> Any:
+    return {
+        "documentId": (
+            str(_v)
+            if (_v := config.get("documentId")) is not None and _v != ""
+            else fake.id("1Doc")
+        ),
+        "replies": [
+            {},
+        ],
+    }
+
+
 def respond(operation: str, request: dict[str, Any]) -> Any:
     """Dispatch to the fixture for one operation."""
     config: dict[str, Any] = request.get("config") or {}
@@ -43,6 +68,9 @@ def respond(operation: str, request: dict[str, Any]) -> Any:
     if operation == "document_create":
         return _document_create(config, fake)
 
+    if operation == "text_insert":
+        return _text_insert(config, fake)
+
     # A faker asked for an operation it has no shape for must SAY so. Making
     # something up would produce a green run whose output silently has none of
     # the fields the author is about to reference.

{fancy_google_docs-0.3.4 → fancy_google_docs-0.4.0}/tests/test_faker.py

@@ -33,6 +33,20 @@ def test_document_create_fakes_the_published_shape() -> None:
     }
 
 
+def test_text_insert_fakes_the_published_shape() -> None:
+    config = {}
+    fake = FakeValues(seed_for_call("google_docs", "text_insert", config))
+
+    faked = respond("text_insert", {"config": config, "fake": fake})
+
+    assert faked == {
+        "documentId": "1Doc_fake_2a078907bfc7",
+        "replies": [
+            {},
+        ],
+    }
+
+
 def test_an_operation_with_no_fixture_raises_rather_than_inventing_a_shape() -> None:
     fake = FakeValues(seed_for_call("google_docs", "no_such_operation", {}))