fancy-zoom 0.1.0__tar.gz

fancy_zoom-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+node_modules/
+dist/
+vendor/
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Lockfiles are NOT source of a generated repo.
+#
+# The generator cannot emit one -- a lockfile is the result of a network
+# resolve -- and "a provider repo must be generated and re-generatable" is the
+# constraint the whole estate rests on. At a few hundred repos, a committed
+# lockfile each is a few hundred files nothing can regenerate and a few hundred
+# Dependabot surfaces.
+#
+# The trade is real and worth stating: CI resolves fresh on every run, so an
+# upstream release inside the declared range can break a build with no change
+# here. That is early warning rather than a surprise at publish time, and the
+# ranges are deliberately narrow (>=X <2.0, never a caret on a 0.x).
+composer.lock
+package-lock.json

fancy_zoom-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog — Zoom
+
+All four packages — `@particle-academy/zoom-ui`, `@particle-academy/zoom-js`,
+`particle-academy/zoom-php` and `fancy-zoom` — are released together under one
+version. They are generated from one `provider/` definition, so a change to it
+changes all four, and separate version lines would only record which of the
+four somebody remembered to bump.
+
+**Write entries HERE**, in the weaver envelope at `providers/zoom/CHANGELOG.md`,
+then regenerate. This file is the one thing in a release that cannot be derived
+— somebody has to write what changed — but writing it in the provider repo
+would be a hand-edit that `.weaver.json` flags and the next sync destroys.
+
+## [0.1.0] — 2026-09-16
+
+### Added
+
+- **`meeting_get`** — read a meeting's join link and settings (`GET /meetings/{meetingId}`, scope `meeting:read:meeting`).
+- **`obf_token_create`** — mint the on-behalf-of token a Meeting SDK bot needs to join a meeting it did not create (`GET /users/me/token?type=onbehalf`, scope `user:read:token`), required since Zoom's own 2026-02-23 enforcement date. Meeting-scoped and single-use, so it is minted fresh before every join rather than cached.
+- OAuth2 authorization-code, with `refreshTokenRotates: true` — Zoom issues a new refresh token on every refresh and treats reuse of an old one as an error, the same shape this vocabulary already refuses to retry or run concurrently.
+- Sandbox is `unverified`: Zoom documents no test estate distinct from a real account, but nobody has confirmed there is truly nothing rather than simply not having found it.
+
+Tynn #10 (MOIC U15) — the OAuth flow, both endpoints and the sandbox note were checked against Zoom's own docs, its developer forum and its migration blog on 2026-09-15; `meeting_get`'s field list is the long-stable v2 shape rather than a page transcription (Zoom's detail page did not render for review) and is flagged for a live spot-check before an account depends on it.

fancy_zoom-0.1.0/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.

fancy_zoom-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,118 @@
+# 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/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_zoom-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fancy-zoom"
+version = "0.1.0"
+description = "Zoom 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,
+# and a floor that dies before the package's second release is not a floor.
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Particle Academy" }]
+keywords = ["zoom", "messaging", "connector", "api", "fancy-flow", "particle-academy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+# ZERO runtime dependencies, and that is a design constraint rather than an
+# accident. There is no Python twin of fancy-connector-core to depend on, and a
+# vendor SDK is third-party code subject to the kit's full approval bar — one
+# SDK per provider is hundreds of dependencies nobody is tracking. The HTTP is
+# stdlib `urllib`; the HMAC is stdlib `hmac`.
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/Fancy-Friends/zoom"
+Issues = "https://github.com/Fancy-Friends/zoom/issues"
+Source = "https://github.com/Fancy-Friends/zoom"
+
+[dependency-groups]
+# Not optional. A package with no way to run its tests reports green by doing
+# nothing, which is the one defect that hides itself.
+test = ["pytest>=8.0"]
+lint = ["ruff>=0.16"]
+typecheck = ["mypy>=1.11"]
+dev = [{ include-group = "test" }, { include-group = "lint" }, { include-group = "typecheck" }]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fancy_zoom"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/art", "/README.md", "/CHANGELOG.md", "/LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# importlib mode pairs with src-layout: the working tree is never on sys.path,
+# so the tests exercise the INSTALLED package. Under the default mode a missing
+# py.typed or an unshipped file passes locally and breaks for every user.
+addopts = "--import-mode=importlib -ra"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+target-version = "py311"
+
+[tool.ruff.lint]
+# `S` — flake8-bandit — is ON, and it is the one addition worth arguing for: this
+# package handles a credential, builds an HMAC, and opens a URL. Security lint
+# belongs on exactly this code.
+#
+# It also makes the two `# noqa: S310` in _runtime.py MEANINGFUL. Without `S`
+# selected, ruff reports them as unused directives (RUF100) and the obvious fix
+# is to delete them — which quietly removes a security annotation because a
+# linter was not looking for it.
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "N", "C4", "PT", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+# pytest's whole idiom is bare `assert`. S101 would fail every test file.
+"tests/*" = ["S101"]
+
+[tool.mypy]
+python_version = "3.11"
+packages = ["fancy_zoom"]
+mypy_path = "src"
+strict = true
+disallow_any_expr = false
+disallow_any_explicit = false

fancy_zoom-0.1.0/src/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-0.1.0/src/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"