fancy-notion 0.1.0__tar.gz

fancy_notion-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_notion-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@particle-academy/notion-ui`,
+`@particle-academy/notion-js`, `particle-academy/notion-php` and `fancy-notion`.
+
+## [0.1.0] - 2026-08-28
+
+### Added
+
+- Retrieve page content through Notion's enhanced Markdown endpoint.
+- Capability-based OAuth without invented scope strings.
+- Rotating refresh-token guidance and an explicitly undocumented access-token lifetime.
+- Dedicated development-workspace sandbox guidance.
+- A deterministic fixture matching Notion's top-level `page_markdown` response.
+
+[0.1.0]: https://github.com/Fancy-Friends/notion/releases/tag/v0.1.0

fancy_notion-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_notion-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.5
+Name: fancy-notion
+Version: 0.1.0
+Summary: Notion 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/notion
+Project-URL: Issues, https://github.com/Fancy-Friends/notion/issues
+Project-URL: Source, https://github.com/Fancy-Friends/notion
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,connector,fancy-flow,notion,particle-academy,productivity
+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
+
+# Notion
+
+Notion 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/notion-ui` | `npm install @particle-academy/notion-ui` |
+| Node | `@particle-academy/notion-js` | `npm install @particle-academy/notion-js` |
+| PHP 8.4+ | `particle-academy/notion-php` | `composer require particle-academy/notion-php` |
+| Python 3.11+ | `fancy-notion` | `pip install fancy-notion` |
+
+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 Notion 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 Notion 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 | The public connection's OAuth client ID from its Configuration tab. |
+| **OAuth client secret** | per installation | **secret** | The matching secret used by the host for code exchange and token refresh. |
+| **Access token** | per connected account | **secret** | The bearer token for one user's installation in one Notion workspace. |
+| **Refresh token** | per connected account | **secret** | The rotating refresh token. Replace it atomically with the new value returned by every refresh. |
+
+### Authorising
+
+Notion 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://api.notion.com/v1/oauth/authorize
+- **Token URL** — https://api.notion.com/v1/oauth/token
+- **Configured capabilities** — `Read content`. This provider does not accept OAuth scope strings; configure these permissions on the integration itself.
+- **Access token lifetime** — not documented by the provider. The host must retain the refresh token and refresh in response to expiry rather than scheduling from an invented TTL.
+
+**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
+
+Notion has a test estate on the same host, reached with credentials from a SEPARATE test account you register. Selecting sandbox mode uses those credentials.
+
+> Install the public connection into a dedicated Notion development workspace and grant it only test pages. Calls use the live API and create or read real content inside that workspace.
+
+## What it can do
+
+### Actions
+
+#### `page_markdown_get` — Notion page Markdown
+
+Retrieve a Notion page's content as enhanced Markdown.
+
+`GET /v1/pages/{pageId}/markdown` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `pageId` | yes | The Notion page UUID, with or without hyphens. The connection must have Read content capability and access to this page. |
+| `includeTranscript` | no | Include meeting-note transcripts when the connection and caller are permitted to read them. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Notion has a sandbox. Set a
+node's mode to `fake` and it returns the shape Notion 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/notion`; 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_notion-0.1.0/README.md

@@ -0,0 +1,107 @@
+# Notion
+
+Notion 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/notion-ui` | `npm install @particle-academy/notion-ui` |
+| Node | `@particle-academy/notion-js` | `npm install @particle-academy/notion-js` |
+| PHP 8.4+ | `particle-academy/notion-php` | `composer require particle-academy/notion-php` |
+| Python 3.11+ | `fancy-notion` | `pip install fancy-notion` |
+
+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 Notion 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 Notion 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 | The public connection's OAuth client ID from its Configuration tab. |
+| **OAuth client secret** | per installation | **secret** | The matching secret used by the host for code exchange and token refresh. |
+| **Access token** | per connected account | **secret** | The bearer token for one user's installation in one Notion workspace. |
+| **Refresh token** | per connected account | **secret** | The rotating refresh token. Replace it atomically with the new value returned by every refresh. |
+
+### Authorising
+
+Notion 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://api.notion.com/v1/oauth/authorize
+- **Token URL** — https://api.notion.com/v1/oauth/token
+- **Configured capabilities** — `Read content`. This provider does not accept OAuth scope strings; configure these permissions on the integration itself.
+- **Access token lifetime** — not documented by the provider. The host must retain the refresh token and refresh in response to expiry rather than scheduling from an invented TTL.
+
+**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
+
+Notion has a test estate on the same host, reached with credentials from a SEPARATE test account you register. Selecting sandbox mode uses those credentials.
+
+> Install the public connection into a dedicated Notion development workspace and grant it only test pages. Calls use the live API and create or read real content inside that workspace.
+
+## What it can do
+
+### Actions
+
+#### `page_markdown_get` — Notion page Markdown
+
+Retrieve a Notion page's content as enhanced Markdown.
+
+`GET /v1/pages/{pageId}/markdown` · reads only — safe to replay
+
+| Input | Required | What it is |
+|---|---|---|
+| `pageId` | yes | The Notion page UUID, with or without hyphens. The connection must have Read content capability and access to this page. |
+| `includeTranscript` | no | Include meeting-note transcripts when the connection and caller are permitted to read them. |
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Notion has a sandbox. Set a
+node's mode to `fake` and it returns the shape Notion 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/notion`; 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_notion-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fancy-notion"
+version = "0.1.0"
+description = "Notion 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 = ["notion", "productivity", "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/notion"
+Issues = "https://github.com/Fancy-Friends/notion/issues"
+Source = "https://github.com/Fancy-Friends/notion"
+
+[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_notion"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/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_notion"]
+mypy_path = "src"
+strict = true
+disallow_any_expr = false
+disallow_any_explicit = false

fancy_notion-0.1.0/src/fancy_notion/__init__.py

@@ -0,0 +1,37 @@
+# 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 -- notion
+
+"""Notion 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.page_markdown_get import page_markdown_get
+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",
+    "page_markdown_get",
+    "respond",
+]

fancy_notion-0.1.0/src/fancy_notion/_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 -- notion
+
+"""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_notion-0.1.0/src/fancy_notion/_runtime.py

@@ -0,0 +1,371 @@
+# 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 -- notion
+
+"""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 | None,
+    secret: str | None,
+    payload: Callable[[str, str | None], str],
+    algorithm: str,
+    encoding: str = "hex",
+    tolerance: int | None = None,
+    timestamp: str | None = None,
+    now: int | 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.
+    """
+    if not secret:
+        return Verification(False, "no signing secret is configured for this connection")
+    if not signature:
+        return Verification(False, "the delivery carried no signature")
+
+    digest = _ALGORITHMS.get(algorithm)
+    if digest is None:
+        return Verification(False, f'unsupported signature algorithm "{algorithm}"')
+
+    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)",
+            )
+
+    computed = hmac.new(secret.encode(), payload(raw, timestamp).encode(), digest)
+    expected = computed.hexdigest() if encoding == "hex" else _b64(computed.digest())
+
+    # Constant time, so a signature cannot be discovered one character at a time.
+    if not hmac.compare_digest(expected, signature):
+        return Verification(False, "the signature does not match")
+
+    return Verification(True)
+
+
+def _b64(raw: bytes) -> str:
+    import base64
+
+    return base64.b64encode(raw).decode()

fancy_notion-0.1.0/src/fancy_notion/actions/__init__.py

@@ -0,0 +1,14 @@
+# 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 -- notion
+
+from .page_markdown_get import page_markdown_get
+
+__all__ = [
+    "page_markdown_get",
+]

fancy_notion-0.1.0/src/fancy_notion/actions/page_markdown_get.py

@@ -0,0 +1,83 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/actions/page-markdown-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/page-markdown-get.json (or weaver's template/) and
+# regenerate:
+#
+# npm run provider -- notion
+
+"""Retrieve a Notion page's content as enhanced Markdown.
+
+GET /v1/pages/{pageId}/markdown —
+https://developers.notion.com/reference/retrieve-page-markdown
+
+This describes the request. `call` resolves the connection, picks the
+estate, and either calls Notion 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 = "page_markdown_get"
+METHOD = "GET"
+PATH = "/v1/pages/{pageId}/markdown"
+SIDE_EFFECTS = "none"
+
+
+def body(config: dict[str, Any]) -> dict[str, Any]:
+    """Build the form body for one call, failing loudly and specifically."""
+    if config.get("pageId") is None or config.get("pageId") == "":
+        raise ConnectorConfigError(
+            "page_markdown_get: \"pageId\" is required (Page ID)."
+        )
+
+    out: dict[str, Any] = {}
+    _value = config.get("includeTranscript")
+    out["include_transcript"] = bool(_value) if _value is not None and _value != "" else False
+
+    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 (
+        "/v1/pages/"
+        + quote(str(config.get("pageId") or ""), safe="")
+        + "/markdown"
+    )
+
+def page_markdown_get(
+    config: dict[str, Any],
+    *,
+    credentials: dict[str, str | None] | None = None,
+    mode: Mode = "auto",
+    connection_id: str | None = None,
+    attempts: int = 3,
+) -> CallResult:
+    """Retrieve a Notion page's content as enhanced Markdown."""
+    return call(
+        descriptor(),
+        operation=OPERATION,
+        method=METHOD,
+        path=PATH,
+        form=body(config),
+        config=config,
+        credentials=credentials,
+        mode=mode,
+        connection_id=connection_id,
+        attempts=attempts,
+    )

fancy_notion-0.1.0/src/fancy_notion/faker.py

@@ -0,0 +1,55 @@
+# 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 -- notion
+
+"""The Notion 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 _page_markdown_get(config: dict[str, Any], fake: FakeValues) -> Any:
+    return {
+        "object": "page_markdown",
+        "id": "-".join([fake.hex(8), fake.hex(4), fake.hex(4), fake.hex(4), fake.hex(12)]),
+        "markdown": (
+                        "# Meeting Notes\n\nDiscussed roadmap priorities.\n\n## Action items\n\n- "
+                        "[ ] Draft proposal\n- [ ] Schedule follow-up"
+                    ),
+        "truncated": False,
+        "unknown_block_ids": [],
+    }
+
+
+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 == "page_markdown_get":
+        return _page_markdown_get(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'notion: 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_notion-0.1.0/src/fancy_notion/service.py

@@ -0,0 +1,70 @@
+# 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 -- notion
+
+"""Notion, as one service descriptor shared by every Notion operation.
+
+The Python twin of the js and php packages' service modules.
+
+## The sandbox trap, written down where it is used
+
+Install the public connection into a dedicated Notion development workspace
+and grant it only test pages. Calls use the live API and create or read real
+content inside that workspace.
+"""
+
+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 = "notion"
+TITLE = "Notion"
+SANDBOX = "separate-account"
+BASE_URLS = {
+    "live": "https://api.notion.com",
+    "sandbox": "https://api.notion.com",
+}
+
+"""Credential keys a remote call cannot proceed without."""
+REQUIRES = [
+    "accessToken",
+]
+
+
+def authorize(
+    credentials: dict[str, str | None],
+    request: PreparedRequest,
+    mode: str,
+) -> None:
+    """Apply Notion's auth scheme to an outgoing request.
+    
+    
+    """
+    request.headers["Notion-Version"] = "2026-03-11"
+
+    request.headers["Authorization"] = f"Bearer {credentials.get('accessToken') or ''}"
+
+
+def descriptor() -> ServiceDescriptor:
+    """The Notion 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_notion-0.1.0/tests/test_faker.py

@@ -0,0 +1,46 @@
+# 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 -- notion
+
+"""The golden fixtures — the SAME values the TypeScript and PHP packages
+assert.
+
+Bit-for-bit identical is the claim, and this is what checks it for Python.
+Cross-runtime drift does not fail loudly on its own: it completes, down one
+path, with no error.
+"""
+
+import pytest
+
+from fancy_notion._fake import FakeValues, seed_for_call
+from fancy_notion.faker import respond
+
+
+def test_page_markdown_get_fakes_the_published_shape() -> None:
+    config = {}
+    fake = FakeValues(seed_for_call("notion", "page_markdown_get", config))
+
+    faked = respond("page_markdown_get", {"config": config, "fake": fake})
+
+    assert faked == {
+        "object": "page_markdown",
+        "id": "3d7f940f-303c-0dc4-6ba0-886fba9c98bc",
+        "markdown": (
+                        "# Meeting Notes\n\nDiscussed roadmap priorities.\n\n## Action items\n\n- "
+                        "[ ] Draft proposal\n- [ ] Schedule follow-up"
+                    ),
+        "truncated": False,
+        "unknown_block_ids": [],
+    }
+
+
+def test_an_operation_with_no_fixture_raises_rather_than_inventing_a_shape() -> None:
+    fake = FakeValues(seed_for_call("notion", "no_such_operation", {}))
+
+    with pytest.raises(ValueError, match="no fake response"):
+        respond("no_such_operation", {"config": {}, "fake": fake})