fancy-zoom 0.1.0__py3-none-any.whl

fancy_zoom/__init__.py

@@ -0,0 +1,39 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/manifest.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/manifest.json (or weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+"""Zoom for Python.
+
+The service descriptor, its faker, its delivery contract, and one function
+per operation — plain HTTP on the stdlib, no vendor SDK and no runtime
+dependency.
+"""
+
+from __future__ import annotations
+
+from ._fake import FakeValues
+from .actions.meeting_get import meeting_get
+from .actions.obf_token_create import obf_token_create
+from .faker import respond
+from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BASE_URLS",
+    "CONNECTOR_API_VERSION",
+    "REQUIRES",
+    "SANDBOX",
+    "SERVICE",
+    "TITLE",
+    "FakeValues",
+    "descriptor",
+    "meeting_get",
+    "obf_token_create",
+    "respond",
+]

fancy_zoom/_fake.py

@@ -0,0 +1,170 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/manifest.json (via weaver's
+# template/embed/py/_fake.py) 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/manifest.json (via weaver's template/embed/py/_fake.py) (or
+# weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+"""Deterministic faker values — bit-for-bit with TypeScript and PHP.
+
+PROVENANCE — read before editing.
+
+This is the SINGLE SOURCE for the Python faker helpers. It exists because
+``fancy-connector-core`` has a TypeScript implementation and a PHP twin and
+**no Python twin at all**, so a generated ``fancy-<provider>`` package has no
+shared runtime to import. Every generated package carries a copy emitted from
+this file, and ``new-provider.mjs --check`` fails CI when a copy differs.
+
+The permanent fix is a Python ``fancy-connector-core``. When it exists, this
+file becomes a re-export and every provider picks it up on the next protocol
+sync.
+
+## Bit-for-bit identical is the whole point
+
+Not "similar": the same FNV-1a seed and the same xorshift32 sequence, so a
+golden fixture asserts the exact faked payload and ALL THREE runtimes have to
+produce it. That turns the faker into a parity test rather than a convenience —
+which matters, because cross-runtime drift does not fail loudly. It completes,
+down one path, with no error.
+
+Python integers are unbounded, so every 32-bit operation is masked back into
+range. Dropping one of those masks does not break anything visibly; it just
+makes the runtimes diverge after a few hundred calls, which is the worst
+possible way for this to fail.
+
+## Deterministic, and obviously fake
+
+Same inputs, same output — always. A faker returning a fresh uuid every call
+cannot be asserted on, so its fixtures degrade to "it did not throw", which is
+the assertion that catches nothing. And the values are obviously synthetic ON
+PURPOSE — ``fake_``-prefixed ids, ``example.test`` hosts, round numbers. Nobody
+should ever look at a faked result and wonder whether it moved real money.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+MASK = 0xFFFFFFFF
+
+# `FakeValues.int` is part of the cross-runtime faker API — `fake.int(min, max)`
+# in TypeScript, PHP and here — so the method keeps that name. Inside the class
+# body it then shadows the builtin, and every LATER annotation reading `int`
+# resolves to the method instead of the type. This alias is what the annotations
+# after it use.
+_Int = int
+
+#: The instant every faker counts from. A constant rather than the clock,
+#: because a fixture asserting on ``created`` must not start failing tomorrow.
+FAKE_EPOCH = "2026-01-01T00:00:00.000Z"
+
+_FNV_OFFSET = 0x811C9DC5
+_FNV_PRIME = 0x01000193
+
+
+def _stable_json(value: Any) -> str:
+    """Render a value the way ``JSON.stringify`` would, with sorted object keys.
+
+    Key order must not change a seed. ``json.dumps`` preserves insertion order,
+    so ``{a, b}`` and ``{b, a}`` would hash differently and "same inputs, same
+    output" would hold only for dicts that happened to be built in the same
+    order — the kind of almost-true that survives review and fails in a fixture
+    months later.
+    """
+    if isinstance(value, dict):
+        parts = [
+            f"{json.dumps(str(key))}:{_stable_json(item)}"
+            for key, item in sorted(value.items(), key=lambda pair: str(pair[0]))
+            if item is not ...
+        ]
+        return "{" + ",".join(parts) + "}"
+
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_stable_json(item) for item in value) + "]"
+
+    # `separators` matters: JavaScript emits no spaces, and a space here would
+    # change every seed.
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def seed_from(*parts: Any) -> int:
+    """FNV-1a over the stable rendering of the parts. Twin of ``seedFrom``."""
+    text = "|".join(part if isinstance(part, str) else _stable_json(part) for part in parts)
+
+    hash_ = _FNV_OFFSET
+    # JavaScript hashes UTF-16 code units, so a character outside the BMP
+    # contributes two of them. Encoding to UTF-16-LE and reading pairs is what
+    # keeps a provider name with an emoji in it seeding identically.
+    for unit in _utf16_units(text):
+        hash_ ^= unit
+        hash_ = (hash_ * _FNV_PRIME) & MASK
+
+    return hash_
+
+
+def _utf16_units(text: str) -> list[int]:
+    raw = text.encode("utf-16-le")
+
+    return [raw[i] | (raw[i + 1] << 8) for i in range(0, len(raw), 2)]
+
+
+def seed_for_call(service: str, operation: str, config: dict[str, Any] | None) -> int:
+    """The seed for one faked call: service, operation, and the caller's config."""
+    return seed_from(service, operation, config or {})
+
+
+class FakeValues:
+    """Deterministic value helpers handed to a faker.
+
+    Small on purpose. A faker's job is to return the SHAPE the provider returns
+    — the field names a downstream node will reference — not to simulate the
+    provider's business logic.
+    """
+
+    def __init__(self, seed: int) -> None:
+        masked = seed & MASK
+        self._state = masked if masked != 0 else 0x9E3779B9
+
+    def _next(self) -> int:
+        """xorshift32, matching the JS generator step for step."""
+        state = self._state
+        state ^= (state << 13) & MASK
+        state &= MASK
+        state ^= state >> 17
+        state ^= (state << 5) & MASK
+        state &= MASK
+        self._state = state
+
+        return state
+
+    def hex(self, length: _Int) -> str:
+        """A stable lowercase hex string of ``length`` characters."""
+        out = ""
+        while len(out) < length:
+            out += format(self._next(), "08x")
+
+        return out[:length]
+
+    def id(self, prefix: str) -> str:
+        """A stable id with the provider's usual prefix: ``id("ch")`` -> ``ch_fake_1a2b3c``."""
+        return f"{prefix}_fake_{self.hex(12)}"
+
+    def int(self, minimum: int, maximum: int) -> int:
+        """A stable integer in ``[minimum, maximum]``."""
+        return minimum + (self._next() % max(1, maximum - minimum + 1))
+
+    def pick(self, options: list[Any]) -> Any:
+        """Pick a stable element of a list."""
+        return options[self._next() % len(options)]
+
+    def timestamp(self, offset_seconds: _Int = 0) -> str:
+        """A fixed ISO-8601 instant, offset by whole seconds. Never ``now()``."""
+        base = datetime(2026, 1, 1, tzinfo=UTC) + timedelta(seconds=offset_seconds)
+
+        return base.strftime("%Y-%m-%dT%H:%M:%S") + ".000Z"

fancy_zoom/_runtime.py

@@ -0,0 +1,524 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/manifest.json (via weaver's
+# template/embed/py/_runtime.py) 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/manifest.json (via weaver's template/embed/py/_runtime.py) (or
+# weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+"""The minimum connector runtime, in the standard library only.
+
+PROVENANCE — read before editing.
+
+This is the SINGLE SOURCE for the Python connector runtime, and it is
+deliberately much smaller than ``@particle-academy/fancy-connector-core``. It
+exists because that package has a TypeScript implementation and a PHP twin and
+**no Python twin at all**. Every generated ``fancy-<provider>`` package carries
+a copy emitted from this file, and ``new-provider.mjs --check`` fails CI when a
+copy differs.
+
+The permanent fix is a Python ``fancy-connector-core``. When it exists, this
+file becomes a re-export and every provider picks it up on the next protocol
+sync.
+
+## What it does, and what it deliberately does not
+
+It owns the WIRE: the estate, the auth placement, one call path, the faker
+branch, an idempotency header, and HMAC delivery verification.
+
+It owns NO GATE. Approval, liveness, consent, second review and every journal
+belong to the host, because each is enforced in ONE place and every connector
+inherits it from the dispatch path rather than implementing it.
+
+Three properties that are asserted rather than promised:
+
+- **Nothing here reads the environment.** Credentials are arguments. A package
+  that reached for ``os.environ`` would bypass the host's discipline entirely.
+- **Nothing here retries an ambiguous failure.** A request that may or may not
+  have arrived is repeated only when the caller has said repeating it is
+  harmless.
+- **Nothing here phones home.** No telemetry, no central service, and no URL
+  this module contacts that the connector did not name.
+
+## Zero dependencies is a constraint, not an accident
+
+``urllib`` for HTTP, ``hmac``/``hashlib`` for signatures. A vendor SDK is
+third-party code subject to the kit's full approval bar, and one SDK per
+provider is hundreds of dependencies nobody is tracking.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+Mode = Literal["fake", "sandbox", "live", "auto"]
+
+
+class ConnectorError(Exception):
+    """Something went wrong talking to the provider."""
+
+    def __init__(self, message: str, *, status: int | None = None, retryable: bool = False) -> None:
+        super().__init__(message)
+        self.status = status
+        #: Whether repeating this exact request is known to be harmless. Defaults
+        #: to False: an ambiguous failure is only retryable when the caller said
+        #: so, not when a retry would be convenient.
+        self.retryable = retryable
+
+
+class ConnectorConfigError(ConnectorError):
+    """The call was refused before anything was sent. Nothing was attempted."""
+
+
+class ConnectorAuthError(ConnectorError):
+    """The provider rejected the credential."""
+
+
+class ConnectorModeError(ConnectorError):
+    """The requested estate does not exist for this provider."""
+
+
+@dataclass
+class PreparedRequest:
+    """An outgoing request, after the service descriptor has authorised it."""
+
+    method: str
+    url: str
+    headers: dict[str, str] = field(default_factory=dict)
+    query: dict[str, str] = field(default_factory=dict)
+    body: bytes | None = None
+
+
+@dataclass
+class ServiceDescriptor:
+    """A provider, as one value shared by every one of its operations."""
+
+    service: str
+    title: str
+    sandbox: str
+    base_urls: dict[str, str]
+    requires: list[str]
+    authorize: Callable[[dict[str, str | None], PreparedRequest, str], None]
+    faker: Callable[[str, dict[str, Any]], Any]
+    idempotency_header: str | None = None
+
+
+@dataclass
+class CallResult:
+    """What one call produced, and which estate produced it."""
+
+    mode: str
+    connection: str | None
+    data: Any
+    status: int | None = None
+
+
+@dataclass
+class Verification:
+    """Whether an inbound delivery can be trusted, and why not when it cannot."""
+
+    ok: bool
+    reason: str | None = None
+
+
+#: The estate kinds a ``sandbox`` mode can actually point at. Mirrors the
+#: TypeScript ``sandboxIsSelectable``.
+SELECTABLE_SANDBOX = ("credential", "base-url", "separate-account")
+
+
+def resolve_mode(descriptor: ServiceDescriptor, requested: Mode) -> str:
+    """Turn ``auto`` into a real estate, and refuse one the provider does not have.
+
+    A provider with no sandbox resolving ``sandbox`` to ``live`` would be the
+    worst possible reading: it moves real money while the caller believes it did
+    not.
+    """
+    if requested == "auto":
+        return "fake"
+
+    if requested == "sandbox" and descriptor.sandbox not in SELECTABLE_SANDBOX:
+        raise ConnectorModeError(
+            f'{descriptor.service}: sandbox was requested but this provider\'s estate is '
+            f'"{descriptor.sandbox}", which cannot be selected. Use "fake" to design against '
+            f'a shaped response, or "live" deliberately.'
+        )
+
+    return requested
+
+
+def call(
+    descriptor: ServiceDescriptor,
+    *,
+    operation: str,
+    method: str,
+    path: str,
+    form: dict[str, Any] | None = None,
+    json_body: Any | None = None,
+    query: dict[str, Any] | None = None,
+    config: dict[str, Any] | None = None,
+    credentials: dict[str, str | None] | None = None,
+    mode: Mode = "auto",
+    connection_id: str | None = None,
+    idempotency_key: str | None = None,
+    idempotent: bool = False,
+    attempts: int = 3,
+    timeout: float = 30.0,
+    transport: Callable[[PreparedRequest], tuple[int, str]] | None = None,
+) -> CallResult:
+    """Make one call, or fake one.
+
+    ``fake`` mode never touches the network, so a connector is runnable before an
+    account, a key or a provider that is up.
+    """
+    resolved = resolve_mode(descriptor, mode)
+    config = config or {}
+
+    if resolved == "fake":
+        from ._fake import FakeValues, seed_for_call
+
+        fake = FakeValues(seed_for_call(descriptor.service, operation, config))
+
+        return CallResult(
+            mode="fake",
+            connection=connection_id,
+            data=descriptor.faker(operation, {"config": config, "fake": fake}),
+        )
+
+    base = descriptor.base_urls.get(resolved)
+    if not base:
+        raise ConnectorModeError(f"{descriptor.service}: no base URL for mode \"{resolved}\".")
+
+    credentials = credentials or {}
+    missing = [key for key in descriptor.requires if not credentials.get(key)]
+    if missing:
+        raise ConnectorConfigError(
+            f"{descriptor.service}: the connection is missing {', '.join(missing)}."
+        )
+
+    request = PreparedRequest(method=method, url=base.rstrip("/") + path)
+    request.query = {k: str(v) for k, v in (query or {}).items() if v is not None}
+
+    if form is not None:
+        request.body = urllib.parse.urlencode(
+            {k: v for k, v in form.items() if v is not None}, doseq=False
+        ).encode()
+        request.headers["Content-Type"] = "application/x-www-form-urlencoded"
+    elif json_body is not None:
+        request.body = json.dumps(json_body, separators=(",", ":")).encode()
+        request.headers["Content-Type"] = "application/json"
+
+    if idempotency_key and descriptor.idempotency_header:
+        request.headers[descriptor.idempotency_header] = idempotency_key
+
+    descriptor.authorize(credentials, request, resolved)
+
+    send = transport or _urllib_transport
+    last: ConnectorError | None = None
+
+    for attempt in range(1, max(1, attempts) + 1):
+        try:
+            status, text = send(_with_query(request, timeout))
+        except OSError as error:  # DNS, connection reset, timeout
+            # Nobody can tell whether this arrived. Repeating is safe only when
+            # the caller has said so or the request carries an idempotency key.
+            last = ConnectorError(
+                f"{descriptor.service}: {operation} did not complete ({error}).",
+                retryable=idempotent or bool(idempotency_key),
+            )
+        else:
+            if 200 <= status < 300:
+                return CallResult(
+                    mode=resolved,
+                    connection=connection_id,
+                    data=json.loads(text) if text else None,
+                    status=status,
+                )
+
+            last = _classify(descriptor.service, operation, status, text)
+
+        if not last.retryable or attempt == attempts:
+            raise last
+
+        time.sleep(min(2 ** (attempt - 1), 8))
+
+    raise last if last else ConnectorError(f"{descriptor.service}: {operation} failed.")
+
+
+def _with_query(request: PreparedRequest, timeout: float) -> PreparedRequest:
+    if not request.query:
+        return request
+
+    separator = "&" if "?" in request.url else "?"
+    joined = PreparedRequest(
+        method=request.method,
+        url=f"{request.url}{separator}{urllib.parse.urlencode(request.query)}",
+        headers=dict(request.headers),
+        body=request.body,
+    )
+    joined.headers.setdefault("_timeout", str(timeout))
+
+    return joined
+
+
+def _urllib_transport(request: PreparedRequest) -> tuple[int, str]:
+    timeout = float(request.headers.pop("_timeout", "30"))
+    raw = urllib.request.Request(  # noqa: S310 — the URL comes from the descriptor
+        request.url,
+        data=request.body,
+        headers=request.headers,
+        method=request.method,
+    )
+
+    try:
+        with urllib.request.urlopen(raw, timeout=timeout) as response:  # noqa: S310
+            return response.status, response.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as error:
+        return error.code, error.read().decode("utf-8", "replace")
+
+
+def _classify(service: str, operation: str, status: int, body: str) -> ConnectorError:
+    """Separate "it was refused" from "nobody can tell"."""
+    message = f"{service}: {operation} failed with {status}. {body[:400]}"
+
+    if status in (401, 403):
+        return ConnectorAuthError(message, status=status)
+    if status == 429 or status >= 500:
+        # A 5xx or a rate limit is the provider saying "try again", which is a
+        # different fact from a 4xx saying "this request is wrong".
+        return ConnectorError(message, status=status, retryable=True)
+
+    return ConnectorError(message, status=status)
+
+
+_ALGORITHMS = {"sha256": hashlib.sha256, "sha1": hashlib.sha1, "sha512": hashlib.sha512}
+
+
+def verify_hmac(
+    *,
+    raw: str,
+    signature: str | list[str] | None,
+    secret: str | None,
+    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.
+
+    Refuses rather than accepts on every missing input. That asymmetry is the
+    whole safety property: an unverifiable endpoint is a stranger's button for
+    starting workflows in your account, and defaulting to "allow" would make
+    every misconfiguration into an open door that looks shut.
+
+    ``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")
+
+    # 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(
+                False, "the delivery carried no timestamp, and this scheme signs one"
+            )
+        try:
+            sent = int(float(timestamp))
+        except (TypeError, ValueError):
+            return Verification(False, f'the delivery timestamp "{timestamp}" is not a number')
+
+        current = int(time.time()) if now is None else now
+        if abs(current - sent) > tolerance:
+            return Verification(
+                False,
+                f"the delivery is outside the {tolerance}s replay window "
+                f"({abs(current - sent)}s old)",
+            )
+
+    # 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 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
+
+    return base64.b64encode(raw).decode()

fancy_zoom/actions/__init__.py

@@ -0,0 +1,16 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/actions/ 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/ (or weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+from .meeting_get import meeting_get
+from .obf_token_create import obf_token_create
+
+__all__ = [
+    "meeting_get",
+    "obf_token_create",
+]

fancy_zoom/actions/meeting_get.py

@@ -0,0 +1,78 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/actions/meeting-get.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/meeting-get.json (or weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+"""Read a Zoom meeting's join details and settings.
+
+GET /meetings/{meetingId} — https://developers.zoom.us/docs/api/meetings/
+
+This describes the request. `call` resolves the connection, picks the
+estate, and either calls Zoom 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 = "meeting_get"
+METHOD = "GET"
+PATH = "/meetings/{meetingId}"
+SIDE_EFFECTS = "none"
+
+
+def body(config: dict[str, Any]) -> dict[str, Any]:
+    """Build the JSON body for one call, failing loudly and specifically."""
+    if config.get("meetingId") is None or config.get("meetingId") == "":
+        raise ConnectorConfigError(
+            "meeting_get: \"meetingId\" is required (Meeting ID)."
+        )
+
+    out: dict[str, Any] = {}
+
+    return 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 (
+        "/meetings/"
+        + quote(str(config.get("meetingId") or ""), safe="")
+    )
+
+def meeting_get(
+    config: dict[str, Any],
+    *,
+    credentials: dict[str, str | None] | None = None,
+    mode: Mode = "auto",
+    connection_id: str | None = None,
+    attempts: int = 3,
+) -> CallResult:
+    """Read a Zoom meeting's join details and settings."""
+    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,
+    )

fancy_zoom/actions/obf_token_create.py

@@ -0,0 +1,73 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/actions/obf-token-create.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/obf-token-create.json (or weaver's template/) and
+# regenerate:
+#
+# npm run provider -- zoom
+
+"""Mint a short-lived token so a bot can join a Zoom meeting on the authorising
+user's behalf.
+
+GET /users/me/token —
+https://developers.zoom.us/blog/transition-to-obf-token-meetingsdk-apps/
+
+This describes the request. `call` resolves the connection, picks the
+estate, and either calls Zoom or calls the faker.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._runtime import CallResult, ConnectorConfigError, Mode, call
+from ..service import descriptor
+
+OPERATION = "obf_token_create"
+METHOD = "GET"
+PATH = "/users/me/token"
+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("meetingId") is None or config.get("meetingId") == "":
+        raise ConnectorConfigError(
+            "obf_token_create: \"meetingId\" is required (Meeting ID)."
+        )
+
+    out: dict[str, Any] = {}
+    _value = config.get("meetingId")
+    if _value is None or _value == "":
+        raise ConnectorConfigError("obf_token_create: \"meetingId\" is required.")
+
+    out["meeting_id"] = str(_value)
+
+    out["type"] = "onbehalf"
+    return out
+
+
+def obf_token_create(
+    config: dict[str, Any],
+    *,
+    credentials: dict[str, str | None] | None = None,
+    mode: Mode = "auto",
+    connection_id: str | None = None,
+    attempts: int = 3,
+) -> CallResult:
+    """Mint a short-lived token so a bot can join a Zoom meeting on the authorising user's behalf.
+    """
+    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,
+    )

fancy_zoom/faker.py

@@ -0,0 +1,89 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/fixtures/ 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/fixtures/ (or weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+"""The Zoom faker.
+
+Bit-for-bit identical to the TypeScript and PHP fakers: the same FNV-1a seed
+and the same xorshift32 sequence, so a golden fixture asserts the exact
+faked payload and ALL THREE runtimes have to produce it. That turns the
+faker into a parity test rather than a convenience — which matters, because
+cross-runtime drift does not fail loudly. It completes, down one path, with
+no error.
+"""
+
+from __future__ import annotations
+
+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 _meeting_get(config: dict[str, Any], fake: FakeValues) -> Any:
+    return {
+        "id": (
+            (int(_n) if (_n := _as_number(_v)) is not None else None)
+            if (_v := config.get("meetingId")) is not None and _v != ""
+            else "".join(str(fake.int(0, 9)) for _ in range(10))
+        ),
+        "uuid": "-".join([fake.hex(8), fake.hex(4), fake.hex(4), fake.hex(4), fake.hex(12)]),
+        "host_id": fake.id("u"),
+        "topic": "Weekly sync",
+        "type": 2,
+        "status": "waiting",
+        "start_time": "2026-09-22T14:00:00Z",
+        "duration": 30,
+        "timezone": "America/New_York",
+        "agenda": "",
+        "join_url": "https://zoom.us/j/1234567890?pwd=fake",
+        "password": "".join(str(fake.int(0, 9)) for _ in range(6)),
+        "settings": {
+            "waiting_room": True,
+            "join_before_host": False,
+            "approval_type": 2,
+        },
+    }
+
+
+def _obf_token_create(config: dict[str, Any], fake: FakeValues) -> Any:
+    return {
+        "token": fake.id("obf"),
+    }
+
+
+def respond(operation: str, request: dict[str, Any]) -> Any:
+    """Dispatch to the fixture for one operation."""
+    config: dict[str, Any] = request.get("config") or {}
+    fake: FakeValues = request["fake"]
+
+    if operation == "meeting_get":
+        return _meeting_get(config, fake)
+
+    if operation == "obf_token_create":
+        return _obf_token_create(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.
+    raise ValueError(
+        f'zoom: no fake response is defined for "{operation}". '
+        "Add a fixture under provider/fixtures/ and regenerate — a connector without a faker "
+        "cannot be developed against, tested, or demonstrated."
+    )

fancy_zoom/service.py

@@ -0,0 +1,71 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/manifest.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/manifest.json (or weaver's template/) and regenerate:
+#
+# npm run provider -- zoom
+
+"""Zoom, as one service descriptor shared by every Zoom operation.
+
+The Python twin of the js and php packages' service modules.
+
+## The sandbox trap, written down where it is used
+
+Zoom has no test estate distinct from a real account, as far as this review
+found (2026-09-15) -- but it is UNVERIFIED, not confirmed. Every call
+authorizes against the caller's own Zoom account and can read real meeting
+data. Use fake mode while building.
+"""
+
+from __future__ import annotations
+
+from ._runtime import PreparedRequest, ServiceDescriptor
+from .faker import respond
+
+# The connector API version this package was GENERATED against. A literal,
+# never imported: an imported constant lets an upgrade rewrite the very claim
+# it exists to detect, after which the copy agrees with itself forever.
+CONNECTOR_API_VERSION = 1
+
+SERVICE = "zoom"
+TITLE = "Zoom"
+SANDBOX = "unverified"
+BASE_URLS = {
+    "live": "https://api.zoom.us/v2",
+}
+
+"""Credential keys a remote call cannot proceed without."""
+REQUIRES = [
+    "accessToken",
+]
+
+
+def authorize(
+    credentials: dict[str, str | None],
+    request: PreparedRequest,
+    mode: str,
+) -> None:
+    """Apply Zoom's auth scheme to an outgoing request.
+    
+    Every Zoom REST call is a Bearer token on the Authorization header, OAuth or
+    Server-to-Server alike; this provider declares the user OAuth shape so a
+    host can connect a rep's own Zoom account rather than one shared app-wide
+    identity.
+    """
+    request.headers["Authorization"] = f"Bearer {credentials.get('accessToken') or ''}"
+
+
+def descriptor() -> ServiceDescriptor:
+    """The Zoom service, for the Python runtime."""
+    return ServiceDescriptor(
+        service=SERVICE,
+        title=TITLE,
+        sandbox=SANDBOX,
+        base_urls=BASE_URLS,
+        requires=REQUIRES,
+        authorize=authorize,
+        faker=respond,
+        idempotency_header=None,
+    )

fancy_zoom-0.1.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: fancy-zoom
+Version: 0.1.0
+Summary: Zoom 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/zoom
+Project-URL: Issues, https://github.com/Fancy-Friends/zoom/issues
+Project-URL: Source, https://github.com/Fancy-Friends/zoom
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,connector,fancy-flow,messaging,particle-academy,zoom
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Zoom
+
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
+Zoom 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.
+
+[flow]: https://github.com/Particle-Academy/fancy-flow
+
+| Runtime | Package | Install |
+|---|---|---|
+| Authoring surface (every host) | `@particle-academy/zoom-ui` | `npm install @particle-academy/zoom-ui` |
+| Node | `@particle-academy/zoom-js` | `npm install @particle-academy/zoom-js` |
+| PHP 8.4+ | `particle-academy/zoom-php` | `composer require particle-academy/zoom-php` |
+| Python 3.11+ | `fancy-zoom` | `pip install fancy-zoom` |
+
+The `ui` package is the editor surface and is React on every host — a PHP or
+Python project installs it *and* its own runtime package, and never the `js` one.
+
+## What it costs you
+
+One dependency: `@particle-academy/fancy-connector-core` (or
+`particle-academy/fancy-connector-core` on Composer), which the `js` and `php`
+packages pull in themselves. The Python package has **zero** runtime
+dependencies.
+
+**No Zoom SDK.** Plain HTTP, deliberately: a vendor SDK is third-party code
+subject to the kit's full approval bar, and one per provider is hundreds of
+dependencies nobody is tracking.
+
+## Setting it up
+
+Everything below is generated from `provider/manifest.json`, so it cannot disagree with what the packages do.
+
+### Credentials
+
+A Zoom connection holds 4 values.
+
+**Two kinds of value, and mixing them up matters.** A `provider` credential is ONE value for the whole installation — an OAuth app's client secret serves every connected account. An `account` credential is one per connected account. A host that stores the second where it stores the first lets one account's credentials reach another's.
+
+| Field | Scope | Secret | Where it comes from |
+|---|---|---|---|
+| **OAuth client ID** | per installation | not secret | From the Zoom app you registered at marketplace.zoom.us. One value for the whole installation -- the same app serves every connected Zoom account. |
+| **OAuth client secret** | per installation | **secret** | From the same app. Used to exchange the code and to refresh; never sent with an API request. |
+| **Access token** | per connected account | **secret** | Obtained by the host's OAuth exchange, PER CONNECTED ZOOM ACCOUNT. Expires after one hour -- a host that does not refresh will work for a while and then fail with no warning. |
+| **Refresh token** | per connected account | **secret** | Also per account. A NEW one is issued on every refresh -- persist the replacement atomically, and never retry a refresh that may have already succeeded: replaying an old refresh token is Zoom's own reported failure mode for a rotating grant. |
+
+### Authorising
+
+Zoom uses OAuth2 (authorization_code). The package DECLARES the exchange; the HOST performs it — a consent screen needs a browser, a redirect URI and somewhere to persist the result, and all three belong to the host.
+
+- **Authorize URL** — https://zoom.us/oauth/authorize
+- **Token URL** — https://zoom.us/oauth/token
+- **Scopes** — `meeting:read:meeting`, `user:read:token`
+- **Access token lifetime** — 3600 seconds (1 hours). A host that never refreshes works all afternoon and is broken by morning.
+
+**The refresh tokens ROTATE, and they are single use.** Every refresh returns a new one and spends the one submitted, so replaying a spent token revokes the ENTIRE grant — the user is signed out, with nothing in the failure that says why.
+
+Two consequences, both of which a host gets wrong by default:
+
+1. **Do not RETRY a failed refresh with the same token.** A response that arrived but was not persisted — a crash between the reply and the write — turns the reflexive retry into a replay.
+2. **Do not refresh CONCURRENTLY.** Two workers refreshing at once means one of them replays.
+
+Persist the returned token before using the access token it came with.
+
+### The estate
+
+**Nobody has checked whether Zoom has a test estate.** Treat every call as real.
+
+> Zoom has no test estate distinct from a real account, as far as this review found (2026-09-15) -- but it is UNVERIFIED, not confirmed. Every call authorizes against the caller's own Zoom account and can read real meeting data. Use fake mode while building.
+
+## What it can do
+
+### Actions
+
+#### `meeting_get` — Get meeting
+
+Read a Zoom meeting's join details and settings.
+
+`GET /meetings/{meetingId}` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `meetingId` | yes | The meeting's numeric id, from its join URL or from Zoom's own meeting list. |
+
+#### `obf_token_create` — Mint on-behalf-of token
+
+Mint a short-lived token so a bot can join a Zoom meeting on the authorising user's behalf.
+
+`GET /users/me/token` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `meetingId` | yes | The meeting the bot is about to join. The minted token works for this meeting only. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Zoom has a sandbox. Set a
+node's mode to `fake` and it returns the shape Zoom actually publishes — the
+same field names, deterministically — so you can wire the downstream nodes before
+touching an account, a key, or a network.
+
+## This repository is generated
+
+`provider/` is the source. Everything under `packages/` is emitted from it and
+**must not be hand-edited** — CI regenerates and diffs on every push, and the
+next protocol sync destroys anything it finds. See [`AGENTS.md`](AGENTS.md).
+
+## Two namespaces, which do not match on purpose
+
+The repo is `github.com/Fancy-Friends/zoom`; the packages publish under
+`particle-academy`. Nothing derives one from the other — the names come from
+weaver's `friends.json` and nowhere else.
+
+## Licence
+
+MIT.

fancy_zoom-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+fancy_zoom/__init__.py,sha256=z1mJmFZea9tGast6c4s4_T5LGL4x9zQPuwM2aROMOjw,1055
+fancy_zoom/_fake.py,sha256=9X-skqBd9b0-P4SdKm6Ap8YjjTrSLYArIUYBwFcGf_o,6646
+fancy_zoom/_runtime.py,sha256=s00I8sZrW9JrK8rPqf70wIVCuSTZ3Lat5U-xnm2csYE,19430
+fancy_zoom/faker.py,sha256=TIf7PzLGDZFqttqjvDNQXeNwqgngkR7KCRKRZ8r_6pw,3141
+fancy_zoom/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fancy_zoom/service.py,sha256=DGjHJYlb6B_1zsqt5K5YzePMAiZL3yz1JG22T7Vw_6Q,2220
+fancy_zoom/actions/__init__.py,sha256=wR8Lsw0HQ86yTA-Ne8SJ8y_24eVRvPM9g0UQvhpbjDA,470
+fancy_zoom/actions/meeting_get.py,sha256=tIpmjDT4mjTIsTwjKGK6D2CDZn97e6aQm1hM3YEHMug,2353
+fancy_zoom/actions/obf_token_create.py,sha256=bf5ZWFryG-d1Ke3tBIB72MTxsLJCSZan1uJNhWUGta0,2161
+fancy_zoom-0.1.0.dist-info/METADATA,sha256=Mh4HtYPZrwTx-3BTgf-Qkf4PinxNUhc8ZWj6VJx4_B4,6849
+fancy_zoom-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fancy_zoom-0.1.0.dist-info/licenses/LICENSE,sha256=nBlLZPUsduZ364Sj4w82nIJyfqWKvlBnDV3j-czSMnA,1073
+fancy_zoom-0.1.0.dist-info/RECORD,,

fancy_zoom-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fancy_zoom-0.1.0.dist-info/licenses/LICENSE

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