fancy-telegram 0.1.0__py3-none-any.whl

fancy_telegram/__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 -- telegram
+
+"""Telegram 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 .faker import respond
+from .service import BASE_URLS, CONNECTOR_API_VERSION, REQUIRES, SANDBOX, SERVICE, TITLE, descriptor
+from .triggers import get_updates
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BASE_URLS",
+    "CONNECTOR_API_VERSION",
+    "REQUIRES",
+    "SANDBOX",
+    "SERVICE",
+    "TITLE",
+    "FakeValues",
+    "descriptor",
+    "get_updates",
+    "respond",
+]

fancy_telegram/_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 -- telegram
+
+"""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_telegram/_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 -- telegram
+
+"""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_telegram/faker.py

@@ -0,0 +1,77 @@
+# 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 -- telegram
+
+"""The Telegram 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 _get_updates(config: dict[str, Any], fake: FakeValues) -> Any:
+    bound_chat_id = fake.int(100000000, 999999999)
+
+    return {
+        "ok": True,
+        "result": [
+            {
+                "update_id": fake.int(100000, 999999),
+                "message": {
+                    "message_id": fake.int(1, 9999),
+                    "date": 1767225600,
+                    "text": (
+                        str(_v)
+                        if (_v := config.get("sampleText")) is not None and _v != ""
+                        else "hello from the faker"
+                    ),
+                    "chat": {
+                        "id": bound_chat_id,
+                        "type": "private",
+                        "first_name": "Ada",
+                        "username": "ada_example",
+                    },
+                    "from": {
+                        "id": bound_chat_id,
+                        "is_bot": False,
+                        "first_name": "Ada",
+                        "username": "ada_example",
+                        "language_code": "en",
+                    },
+                },
+            },
+        ],
+    }
+
+
+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 == "get_updates":
+        return _get_updates(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'telegram: 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_telegram/service.py

@@ -0,0 +1,94 @@
+# 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 -- telegram
+
+"""Telegram, as one service descriptor shared by every Telegram operation.
+
+The Python twin of the js and php packages' service modules.
+
+## The sandbox trap, written down where it is used
+
+Telegram's test environment is a genuinely SEPARATE ACCOUNT: you create a
+new account inside it and register a new bot there, so the sandbox
+credential is a different token rather than the same one pointed elsewhere.
+The `/test` path segment is how you reach it; the account is what makes it
+separate. Flood limits are NOT relaxed there, so it is a place to test, not
+a place to hammer.
+"""
+
+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 = "telegram"
+TITLE = "Telegram"
+SANDBOX = "separate-account"
+BASE_URLS = {
+    "live": "https://api.telegram.org",
+    "sandbox": "https://api.telegram.org",
+}
+
+"""Credential keys a remote call cannot proceed without."""
+REQUIRES = [
+    "botToken",
+]
+
+
+def authorize(
+    credentials: dict[str, str | None],
+    request: PreparedRequest,
+    mode: str,
+) -> None:
+    """Apply Telegram's auth scheme to an outgoing request.
+    
+    The bot token is a PATH SEGMENT, not a header --
+    https://api.telegram.org/bot<token>/getUpdates -- and the test environment
+    is a further `/test` AFTER the token. So this is the first provider whose
+    auth and whose estate are the same decision expressed in the URL, which is
+    why `authorize` has always been handed the resolved mode. The token
+    therefore ends up in the request URL, where access logs and error reporters
+    will record it. That is Telegram's design, not ours; a host should keep its
+    own logging away from it.
+    
+    The mode is USED here: for this provider auth and estate are the same
+    decision expressed in the URL.
+    """
+    import urllib.parse
+
+    segment = "/bot" + str(credentials.get("botToken") or "")
+
+    # The estate is the SAME decision as the credential here, and it lives in
+    # a further segment AFTER the token. A token pointed at a node marked
+    # "sandbox" would otherwise reach the live bot, and succeed.
+    if mode == "sandbox":
+        segment += "/test"
+
+    parts = urllib.parse.urlsplit(request.url)
+    request.url = urllib.parse.urlunsplit(
+        (parts.scheme, parts.netloc, f"{segment}{parts.path}", parts.query, parts.fragment)
+    )
+
+
+def descriptor() -> ServiceDescriptor:
+    """The Telegram 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_telegram/triggers/__init__.py

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

fancy_telegram/triggers/get_updates.py

@@ -0,0 +1,142 @@
+# GENERATED FILE — do not edit.
+#
+# Emitted from provider/triggers/get-updates.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/triggers/get-updates.json (or weaver's template/) and regenerate:
+#
+# npm run provider -- telegram
+
+"""Telegram's poll trigger — the delivery contract.
+
+Kept beside the service descriptor rather than inside a node, because a
+signature scheme is a fact about TELEGRAM.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .._runtime import ConnectorConfigError
+from ..faker import respond
+from ..service import SERVICE
+
+OPERATION = "get_updates"
+DELIVERY = "poll"
+SETUP = (
+    "The host polls getUpdates on a schedule and persists the `offset` cursor between calls, "
+    "passing the last `cursor` back in — Telegram queues nothing once an offset has "
+    "acknowledged it, so a lost cursor is lost updates. getUpdates and setWebhook are "
+    "MUTUALLY EXCLUSIVE for one bot: a host running both gets neither."
+)
+MIN_POLL_SECONDS = 1
+
+METHOD = "GET"
+PATH = "/getUpdates"
+
+
+def query(config: dict[str, Any]) -> dict[str, Any]:
+    """Build the query string for one poll, failing loudly and specifically."""
+    offset = config.get("offset")
+    if offset is not None and offset != "":
+        try:
+            _n = float(offset)
+        except (TypeError, ValueError):
+            _n = None
+        if _n is None or _n != int(_n):
+            raise ConnectorConfigError(
+                "get_updates: \"offset\" must be a integer, got "
+                f"{offset!r}."
+            )
+
+    limit = config.get("limit")
+    if limit is not None and limit != "":
+        try:
+            _n = float(limit)
+        except (TypeError, ValueError):
+            _n = None
+        if _n is None or _n != int(_n) or _n < 1 or _n > 100:
+            raise ConnectorConfigError(
+                "get_updates: \"limit\" must be a integer, got "
+                f"{limit!r}."
+            )
+
+    out: dict[str, Any] = {}
+    _value = config.get("offset")
+    if _value is not None and _value != "":
+        out["offset"] = int(float(_value))
+    _value = config.get("limit")
+    out["limit"] = int(float(_value)) if _value is not None and _value != "" else 100
+    _value = config.get("allowedUpdates")
+    if _value is not None and _value != "":
+        out["allowed_updates"] = json.dumps(
+            _allowed_updates_list(config.get("allowedUpdates")), separators=(",", ":")
+        )
+
+    return out
+
+
+def check(data: dict[str, Any]) -> None:
+    """Refuse a response that says no while answering 200.
+
+    Telegram answers HTTP 200 with `{ok: false}` for an application-level
+    failure. A status check alone reads that as success and publishes an empty
+    batch — a poll that silently finds nothing, forever, which is
+    indistinguishable from a quiet channel.
+    """
+    if data.get("ok") is False:
+        raise ConnectorConfigError(
+            "get_updates: getUpdates was rejected — "
+            + str(data.get("description") or "no reason given")
+        )
+
+
+def cursor(items: list[Any], previous: int | None = None) -> int | None:
+    """The next cursor, given the batch just received.
+
+    `offset` means "the first one I have NOT handled", so it is the highest id
+    seen plus one. Off by one in either direction is a real bug with no error
+    attached: too low replays every item forever, too high drops one silently.
+    The HOST persists this and passes it back in — nothing else will.
+    """
+    seen = [
+        item["update_id"]
+        for item in items
+        if isinstance(item, dict) and isinstance(item.get("update_id"), int)
+    ]
+
+    return previous if not seen else max(seen) + 1
+
+
+def items(data: Any) -> list[Any]:
+    """The batch, or an empty list when the response carried none."""
+    found = data.get("result") if isinstance(data, dict) else None
+
+    return list(found) if isinstance(found, list) else []
+
+def _allowed_updates_list(value: Any) -> list[str]:
+    """One value, a ","-separated string, or a list — all end up a list."""
+    if isinstance(value, list):
+        items = [str(item) for item in value]
+    elif isinstance(value, str):
+        items = value.split(",")
+    else:
+        return []
+
+    return [item.strip() for item in items if item.strip()]
+
+
+def sample_event(config: dict[str, Any] | None = None) -> Any:
+    """A faked sample event, so the trigger is runnable before any of the setup
+    above.
+    
+    An author can see the real field names and wire the downstream nodes against
+    them before the provider has ever been contacted.
+    """
+    from .._fake import FakeValues, seed_for_call
+
+    resolved = config or {}
+    fake = FakeValues(seed_for_call(SERVICE, OPERATION, resolved))
+
+    return respond(OPERATION, {"config": resolved, "fake": fake})

fancy_telegram-0.1.0.dist-info/METADATA

@@ -0,0 +1,73 @@
+Metadata-Version: 2.5
+Name: fancy-telegram
+Version: 0.1.0
+Summary: Telegram 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/telegram
+Project-URL: Issues, https://github.com/Fancy-Friends/telegram/issues
+Project-URL: Source, https://github.com/Fancy-Friends/telegram
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,connector,fancy-flow,messaging,particle-academy,telegram
+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
+
+# Telegram
+
+Telegram 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/telegram-ui` | `npm install @particle-academy/telegram-ui` |
+| Node | `@particle-academy/telegram-js` | `npm install @particle-academy/telegram-js` |
+| PHP 8.4+ | `particle-academy/telegram-php` | `composer require particle-academy/telegram-php` |
+| Python 3.11+ | `fancy-telegram` | `pip install fancy-telegram` |
+
+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 Telegram 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.
+
+## Run it before you have credentials
+
+Every operation ships a **faker**, whether or not Telegram has a sandbox. Set a
+node's mode to `fake` and it returns the shape Telegram 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/telegram`; 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_telegram-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+fancy_telegram/__init__.py,sha256=1yt1LHmKEonuQTXiSv8M_SfunLrysSh1ZgAoCmYGSlg,973
+fancy_telegram/_fake.py,sha256=jX82WXBFf4ZDvXHfje1KvlNm9kLxiTNcaQ0pSv6axhs,6650
+fancy_telegram/_runtime.py,sha256=RlBl4HW7NQoakJ7utC22u1BHJXkrJYQ5aPL5TD_1s60,13113
+fancy_telegram/faker.py,sha256=1FAHb9gjw5d2R74226PTkW88ATABYhzOLz76uqeqtRY,2751
+fancy_telegram/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fancy_telegram/service.py,sha256=0wxkYV6nQzLPBuUUEN9StwNVqpKz27jt10bKmu7kyKw,3300
+fancy_telegram/triggers/__init__.py,sha256=QlyCueXbmcWAICy2ddi84sNt1mxuN2NYtlAMtdpgoUc,394
+fancy_telegram/triggers/get_updates.py,sha256=efooWg_NKfrdxfnb0CqPgfA9R6Y_j-GOCw3WxuaDkPk,4923
+fancy_telegram-0.1.0.dist-info/METADATA,sha256=TM-9wjNSMJp5x1FYnwrn5pHGUDPj9lj1pjY_B_Wlz1g,3107
+fancy_telegram-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fancy_telegram-0.1.0.dist-info/licenses/LICENSE,sha256=nBlLZPUsduZ364Sj4w82nIJyfqWKvlBnDV3j-czSMnA,1073
+fancy_telegram-0.1.0.dist-info/RECORD,,

fancy_telegram-0.1.0.dist-info/WHEEL

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

fancy_telegram-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.