fancy-twilio 0.1.0__tar.gz

fancy_twilio-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_twilio-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to `@particle-academy/twilio-ui`, `@particle-academy/twilio-js`,
+`particle-academy/twilio-php` and `fancy-twilio`.
+
+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.1.0] — 2026-11-08
+
+### Added
+
+- **First release.** `message_send` (an SMS from a Twilio number or a
+  Messaging Service) and `message_get` (status, segments, price and Twilio's
+  error code, e.g. 21610 when the recipient replied STOP).
+- **Authentication:** HTTP basic with an API key SID and secret (recommended)
+  or the Account SID and Auth Token. The Account SID is its own credential
+  because it is also part of every URL.
+- **Fake mode** answers from the faker, so tests send nothing.
+- **A Laravel Notification channel**: `via(): ['twilio']` sends with
+  `message_send`. The recipient is the notifiable's `routeNotificationForTwilio()`;
+  `toTwilio($notifiable)` returns the body as a string, or `message_send`'s
+  config as an array. `config('connectors.twilio.notifications')` (from
+  `TWILIO_FROM`, `TWILIO_MESSAGINGSERVICESID`, `TWILIO_STATUSCALLBACK`) fills
+  what the message leaves out, typically the sender; the message wins. No route
+  means nothing is sent. `Twilio::fake()` covers notifications:
+  `Twilio::assertSent('message_send', ...)`.
+- Plus the Laravel layer every connector has: the service provider, the
+  `Twilio` facade, `Twilio::fake()` with `assertSent`, and its own Pest suite.

fancy_twilio-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_twilio-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.5
+Name: fancy-twilio
+Version: 0.1.0
+Summary: Twilio 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/twilio
+Project-URL: Issues, https://github.com/Fancy-Friends/twilio/issues
+Project-URL: Source, https://github.com/Fancy-Friends/twilio
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,connector,fancy-flow,messaging,particle-academy,twilio
+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
+
+# Twilio
+
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
+Twilio 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/twilio-ui` | `npm install @particle-academy/twilio-ui` |
+| Node | `@particle-academy/twilio-js` | `npm install @particle-academy/twilio-js` |
+| PHP 8.4+ | `particle-academy/twilio-php` | `composer require particle-academy/twilio-php` |
+| Python 3.11+ | `fancy-twilio` | `pip install fancy-twilio` |
+
+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 Twilio 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 Twilio connection holds 3 values.
+
+Every value here is `account` scope: one per connected account, not one per installation.
+
+| Field | Scope | Secret | Where it comes from |
+|---|---|---|---|
+| **Account SID** | per connected account | not secret | AC followed by 32 hex characters, from the Twilio Console. It is part of every request URL. |
+| **API key SID (or Account SID)** | per connected account | not secret | An API key SID from the Twilio Console (API keys & tokens), recommended. Or the Account SID again, to authenticate with the Auth Token. |
+| **API key secret (or Auth Token)** | per connected account | **secret** | The secret shown once when the API key was created, or the account's Auth Token. The Auth Token can do everything on the account; an API key can be revoked on its own. |
+
+### The estate
+
+**Twilio decides live-or-test by the KEY, not by the endpoint.** The same host serves both, and a live key pointed at a node marked “sandbox” reaches the real estate and SUCCEEDS. Nothing in the request distinguishes them, which is why credentials sit on the connection rather than on each node.
+
+> Twilio's test estate is selected by the CREDENTIALS, not the URL: a separate test Account SID and test Auth Token (Console -> API keys & tokens), against the same api.twilio.com. A live key on a node marked sandbox texts a real phone and is billed. With test credentials only message_send works -- every other resource, including message_get, answers 403 -- nothing is sent or charged, no status callback fires, and From must be Twilio's magic +15005550006 (+15005550004 as To returns 21610, the STOP case). Test credentials are the test Account SID and Auth Token, not an API key.
+
+## What it can do
+
+### Actions
+
+#### `message_get` — Twilio message
+
+Read a message's current status, segments, price and error code.
+
+`GET /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `sid` | yes | From message_send's data.sid. |
+
+#### `message_send` — Send an SMS with Twilio
+
+Send a text message.
+
+`POST /2010-04-01/Accounts/{AccountSid}/Messages.json` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `to` | yes | The recipient in E.164, e.g. +14155550100. |
+| `from` | no | A Twilio number you own, in E.164, or an alphanumeric sender ID where the destination allows one. Give this or a Messaging Service. |
+| `messagingServiceSid` | no | MG... A Messaging Service picks the sender from its pool. Give this or From. |
+| `body` | yes | The text. Up to 1,600 characters. A character outside GSM-7 makes the whole message UCS-2, which halves how much fits in each billed segment. |
+| `statusCallback` | no | Optional. Twilio POSTs delivery status changes here. Verifying those requests arrives in 0.2.0. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Twilio has a sandbox. Set a
+node's mode to `fake` and it returns the shape Twilio 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/twilio`; 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_twilio-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Twilio
+
+[![Fancified](art/fancified.svg)](https://particle.academy)
+
+Twilio 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/twilio-ui` | `npm install @particle-academy/twilio-ui` |
+| Node | `@particle-academy/twilio-js` | `npm install @particle-academy/twilio-js` |
+| PHP 8.4+ | `particle-academy/twilio-php` | `composer require particle-academy/twilio-php` |
+| Python 3.11+ | `fancy-twilio` | `pip install fancy-twilio` |
+
+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 Twilio 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 Twilio connection holds 3 values.
+
+Every value here is `account` scope: one per connected account, not one per installation.
+
+| Field | Scope | Secret | Where it comes from |
+|---|---|---|---|
+| **Account SID** | per connected account | not secret | AC followed by 32 hex characters, from the Twilio Console. It is part of every request URL. |
+| **API key SID (or Account SID)** | per connected account | not secret | An API key SID from the Twilio Console (API keys & tokens), recommended. Or the Account SID again, to authenticate with the Auth Token. |
+| **API key secret (or Auth Token)** | per connected account | **secret** | The secret shown once when the API key was created, or the account's Auth Token. The Auth Token can do everything on the account; an API key can be revoked on its own. |
+
+### The estate
+
+**Twilio decides live-or-test by the KEY, not by the endpoint.** The same host serves both, and a live key pointed at a node marked “sandbox” reaches the real estate and SUCCEEDS. Nothing in the request distinguishes them, which is why credentials sit on the connection rather than on each node.
+
+> Twilio's test estate is selected by the CREDENTIALS, not the URL: a separate test Account SID and test Auth Token (Console -> API keys & tokens), against the same api.twilio.com. A live key on a node marked sandbox texts a real phone and is billed. With test credentials only message_send works -- every other resource, including message_get, answers 403 -- nothing is sent or charged, no status callback fires, and From must be Twilio's magic +15005550006 (+15005550004 as To returns 21610, the STOP case). Test credentials are the test Account SID and Auth Token, not an API key.
+
+## What it can do
+
+### Actions
+
+#### `message_get` — Twilio message
+
+Read a message's current status, segments, price and error code.
+
+`GET /2010-04-01/Accounts/{AccountSid}/Messages/{Sid}.json` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `sid` | yes | From message_send's data.sid. |
+
+#### `message_send` — Send an SMS with Twilio
+
+Send a text message.
+
+`POST /2010-04-01/Accounts/{AccountSid}/Messages.json` · **unsafe to replay** — a retried durable run does it TWICE
+
+| Input | Required | What it is |
+|---|---|---|
+| `to` | yes | The recipient in E.164, e.g. +14155550100. |
+| `from` | no | A Twilio number you own, in E.164, or an alphanumeric sender ID where the destination allows one. Give this or a Messaging Service. |
+| `messagingServiceSid` | no | MG... A Messaging Service picks the sender from its pool. Give this or From. |
+| `body` | yes | The text. Up to 1,600 characters. A character outside GSM-7 makes the whole message UCS-2, which halves how much fits in each billed segment. |
+| `statusCallback` | no | Optional. Twilio POSTs delivery status changes here. Verifying those requests arrives in 0.2.0. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Twilio has a sandbox. Set a
+node's mode to `fake` and it returns the shape Twilio 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/twilio`; 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_twilio-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_twilio-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fancy-twilio"
+version = "0.1.0"
+description = "Twilio 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 = ["twilio", "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/twilio"
+Issues = "https://github.com/Fancy-Friends/twilio/issues"
+Source = "https://github.com/Fancy-Friends/twilio"
+
+[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_twilio"]
+
+[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_twilio"]
+mypy_path = "src"
+strict = true
+disallow_any_expr = false
+disallow_any_explicit = false

fancy_twilio-0.1.0/src/fancy_twilio/__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 -- twilio
+
+"""Twilio 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.message_get import message_get
+from .actions.message_send import message_send
+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",
+    "message_get",
+    "message_send",
+    "respond",
+]

fancy_twilio-0.1.0/src/fancy_twilio/_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 -- twilio
+
+"""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"