@particle-academy/telegram-js 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to `@particle-academy/telegram-ui`,
+`@particle-academy/telegram-js`, `particle-academy/telegram-php` and
+`fancy-telegram`.
+
+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-08-20
+
+First release. Ported from the vendored connector at
+`px-ui-sandbox/resources/flow-nodes/_telegram`.
+
+### Added
+
+- `get_updates` — start a run when a bot receives an update. A **poll**
+  trigger, not a webhook: `GET /getUpdates` with a persisted `offset` cursor.
+- A faker for it, so the node runs on a canvas before any bot exists.
+
+### The reason this provider exists in the set
+
+**It breaks three assumptions Stripe never tested.**
+
+1. **The trigger is not a webhook.** Telegram offers `getUpdates` long polling
+   OR `setWebhook`, never both for one bot. So the host's obligation here is a
+   schedule and a persisted cursor rather than a route and a signature — and a
+   poll trigger *calls* the provider, where a webhook trigger only republishes
+   what the host already verified. `delivery` was a declaration rather than an
+   assumption for exactly this case.
+
+2. **The credential is a path segment.** `https://api.telegram.org/bot<token>/getUpdates`
+   — and the test environment is a further `/test` after the token. Auth and
+   estate are the same decision expressed in the URL, which is why `authorize`
+   has always been handed the resolved mode even though Stripe never used it.
+
+3. **A rejection arrives as HTTP 200.** Telegram answers `200` with
+   `{"ok": false, "description": "..."}`. A status check alone reads that as
+   success and publishes an empty batch — a poll that silently finds nothing,
+   forever.
+
+### The cursor is the part that bites
+
+`offset` means "the first update id I have NOT handled", so the next cursor is
+the highest `update_id` seen plus one. Off by one in either direction is a real
+bug with no error attached: **too low replays updates forever, too high drops
+one silently**. The trigger computes it and publishes it as `cursor`; the host
+must persist it, because nothing else will.
+
+An empty poll is the NORMAL case and gets its own `empty` port, so the main
+path keeps meaning "something happened" while the host still has somewhere to
+hang cursor bookkeeping.
+
+### On not taking a dependency
+
+There is no official Telegram SDK in any language. Calling the REST API
+directly is therefore the correct choice here rather than a shortcut — the
+alternative is a community wrapper, which is exactly the dependency the kit's
+rules say not to take on a consumer's behalf.
+
+[0.1.0]: https://github.com/Fancy-Friends/telegram/releases/tag/v0.1.0

package/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.

package/README.md

@@ -0,0 +1,51 @@
+# 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.

package/dist/chunk-LFMQKSUM.js

@@ -0,0 +1,124 @@
+import { callConnector } from '@particle-academy/fancy-connector-core';
+
+// src/faker.ts
+function fakeGetUpdates({ config, fake }) {
+  const boundChatId = fake.int(1e8, 999999999);
+  return {
+    "ok": true,
+    "result": [
+      {
+        "update_id": fake.int(1e5, 999999),
+        "message": {
+          "message_id": fake.int(1, 9999),
+          "date": 1767225600,
+          "text": config.sampleText !== void 0 && config.sampleText !== null && config.sampleText !== "" ? String(config.sampleText) : "hello from the faker",
+          "chat": {
+            "id": boundChatId,
+            "type": "private",
+            "first_name": "Ada",
+            "username": "ada_example"
+          },
+          "from": {
+            "id": boundChatId,
+            "is_bot": false,
+            "first_name": "Ada",
+            "username": "ada_example",
+            "language_code": "en"
+          }
+        }
+      }
+    ]
+  };
+}
+var telegramFaker = (operation, request) => {
+  switch (operation) {
+    case "get_updates":
+      return fakeGetUpdates(request);
+    default:
+      throw new Error(
+        `telegram: no fake response is defined for "${operation}". Add a fixture under provider/fixtures/ and regenerate \u2014 a connector without a faker cannot be developed against, tested, or demonstrated.`
+      );
+  }
+};
+
+// src/service.ts
+var CONNECTOR_API_VERSION = 1;
+var TELEGRAM_BASE_URLS = {
+  "live": "https://api.telegram.org",
+  "sandbox": "https://api.telegram.org"
+};
+var TELEGRAM_REQUIRES = [
+  "botToken"
+];
+function telegramAuthorize(credentials, request, mode) {
+  const url = new URL(request.url);
+  const segment = mode === "sandbox" ? `/bot${credentials.botToken ?? ""}/test` : `/bot${credentials.botToken ?? ""}`;
+  url.pathname = `${segment}${url.pathname}`;
+  request.url = url.toString();
+}
+var TELEGRAM = {
+  service: "telegram",
+  title: "Telegram",
+  sandbox: "separate-account",
+  baseUrls: { ...TELEGRAM_BASE_URLS },
+  requires: [...TELEGRAM_REQUIRES],
+  authorize: telegramAuthorize,
+  faker: telegramFaker
+};
+var TELEGRAM_GET_UPDATES = {
+  service: "telegram",
+  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 \u2014 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.",
+  minPollSeconds: 1,
+  faker: telegramFaker
+};
+var GET_UPDATES_OPERATION = "get_updates";
+async function telegramGetUpdates(options) {
+  const config = options.config ?? {};
+  {
+    const n = Number(config.offset);
+    const given = config.offset !== void 0 && config.offset !== null && config.offset !== "";
+    if (given && !Number.isInteger(n)) {
+      throw new Error(
+        `get_updates: "offset" must be a integer, got ${JSON.stringify(config.offset)}.`
+      );
+    }
+  }
+  {
+    const n = Number(config.limit);
+    const given = config.limit !== void 0 && config.limit !== null && config.limit !== "";
+    if (given && !(Number.isInteger(n) && n >= 1 && n <= 100)) {
+      throw new Error(
+        `get_updates: "limit" must be a integer, got ${JSON.stringify(config.limit)}.`
+      );
+    }
+  }
+  return callConnector(TELEGRAM, {
+    operation: GET_UPDATES_OPERATION,
+    config,
+    input: options.input,
+    ...options.credentials === void 0 ? {} : { credentials: options.credentials },
+    ...options.mode === void 0 ? {} : { mode: options.mode },
+    ...options.connectionId === void 0 ? {} : { connectionId: options.connectionId },
+    ...options.attempts === void 0 ? {} : { attempts: options.attempts },
+    ...options.transport === void 0 ? {} : { transport: options.transport },
+    request: {
+      method: "GET",
+      path: "/getUpdates",
+      query: {
+        ...config.offset !== void 0 && config.offset !== null && config.offset !== "" ? { "offset": Math.trunc(Number(config.offset)) } : {},
+        "limit": config.limit !== void 0 && config.limit !== null && config.limit !== "" ? Math.trunc(Number(config.limit)) : 100,
+        ...config.allowedUpdates !== void 0 && config.allowedUpdates !== null && config.allowedUpdates !== "" ? { "allowed_updates": JSON.stringify(allowedUpdatesList(config.allowedUpdates)) } : {}
+      }
+    }
+  });
+}
+function allowedUpdatesList(value) {
+  const items = Array.isArray(value) ? value.map(String) : typeof value === "string" ? value.split(",") : [];
+  return items.map((item) => item.trim()).filter(Boolean);
+}
+
+export { CONNECTOR_API_VERSION, GET_UPDATES_OPERATION, TELEGRAM, TELEGRAM_BASE_URLS, TELEGRAM_GET_UPDATES, TELEGRAM_REQUIRES, telegramAuthorize, telegramFaker, telegramGetUpdates };
+//# sourceMappingURL=chunk-LFMQKSUM.js.map
+//# sourceMappingURL=chunk-LFMQKSUM.js.map

package/dist/chunk-LFMQKSUM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/faker.ts","../src/service.ts","../src/triggers/get-updates.ts"],"names":[],"mappings":"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","file":"chunk-LFMQKSUM.js","sourcesContent":["/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/fixtures/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/fixtures/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * The Telegram faker.\n *\n * Shapes, not behaviour: the goal is that a downstream node sees the field\n * NAMES Telegram actually publishes, so an author can wire {{ $json.data.id }}\n * against a fake and have it keep working against the real thing.\n *\n * Deterministic — same inputs, same output. A faker returning a fresh uuid\n * every call cannot be asserted on, so its fixtures degrade to \"it did not\n * throw\", which is the assertion that catches nothing.\n */\n\nimport type { ConnectorFaker, FakeRequest } from \"@particle-academy/fancy-connector-core\";\n\nfunction fakeGetUpdates({ config, fake }: FakeRequest): unknown {\n  const boundChatId = fake.int(100000000, 999999999);\n\n  return {\n    \"ok\": true,\n    \"result\": [\n      {\n        \"update_id\": fake.int(100000, 999999),\n        \"message\": {\n          \"message_id\": fake.int(1, 9999),\n          \"date\": 1767225600,\n          \"text\": (config.sampleText !== undefined && config.sampleText !== null && config.sampleText !== \"\" ? String(config.sampleText) : \"hello from the faker\"),\n          \"chat\": {\n            \"id\": boundChatId,\n            \"type\": \"private\",\n            \"first_name\": \"Ada\",\n            \"username\": \"ada_example\",\n          },\n          \"from\": {\n            \"id\": boundChatId,\n            \"is_bot\": false,\n            \"first_name\": \"Ada\",\n            \"username\": \"ada_example\",\n            \"language_code\": \"en\",\n          },\n        },\n      },\n    ],\n  };\n}\n\nexport const telegramFaker: ConnectorFaker = (operation, request) => {\n  switch (operation) {\n    case \"get_updates\":\n      return fakeGetUpdates(request);\n\n    default:\n      // A faker asked for an operation it has no shape for must SAY so. Making\n      // something up would produce a green run whose output silently has none\n      // of the fields the author is about to reference.\n      throw new Error(\n        `telegram: no fake response is defined for \"${operation}\". ` +\n          \"Add a fixture under provider/fixtures/ and regenerate — a connector without a faker \" +\n          \"cannot be developed against, tested, or demonstrated.\",\n      );\n  }\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/manifest.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/manifest.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram, as one service descriptor shared by every Telegram operation.\n *\n * @particle-academy/fancy-connector-core carries what is true of ALL\n * connectors. This carries what is true of Telegram: its base URL, its auth\n * scheme, its idempotency header, and its faker.\n *\n * ## The sandbox trap, written down where it is used\n *\n * Telegram's test environment is a genuinely SEPARATE ACCOUNT: you create a\n * new account inside it and register a new bot there, so the sandbox\n * credential is a different token rather than the same one pointed elsewhere.\n * The `/test` path segment is how you reach it; the account is what makes it\n * separate. Flood limits are NOT relaxed there, so it is a place to test, not\n * a place to hammer.\n */\n\nimport type { ConnectorMode, PreparedRequest, ServiceDescriptor } from \"@particle-academy/fancy-connector-core\";\n\nimport { telegramFaker } from \"./faker.js\";\n\n/**\n * The connector API version this package was GENERATED against.\n *\n * A literal, never imported. An imported constant lets an upgrade rewrite the\n * very claim it exists to detect, after which the copy agrees with itself\n * forever.\n */\nexport const CONNECTOR_API_VERSION = 1;\n\nexport const TELEGRAM_BASE_URLS = {\n  \"live\": \"https://api.telegram.org\",\n  \"sandbox\": \"https://api.telegram.org\"\n} as const;\n\n/** Credential keys a remote call cannot proceed without. */\nexport const TELEGRAM_REQUIRES = [\n  \"botToken\"\n] as const;\n\n/**\n * Apply Telegram's auth scheme to an outgoing request.\n *\n * The bot token is a PATH SEGMENT, not a header --\n * https://api.telegram.org/bot<token>/getUpdates -- and the test environment\n * is a further `/test` AFTER the token. So this is the first provider whose\n * auth and whose estate are the same decision expressed in the URL, which is\n * why `authorize` has always been handed the resolved mode. The token\n * therefore ends up in the request URL, where access logs and error reporters\n * will record it. That is Telegram's design, not ours; a host should keep its\n * own logging away from it.\n *\n * The mode is USED here: for this provider auth and estate are the same\n * decision expressed in the URL, which is what this parameter has always been\n * for.\n */\nexport function telegramAuthorize(\n  credentials: Record<string, string | undefined>,\n  request: PreparedRequest,\n  mode: ConnectorMode,\n): void {\n  const url = new URL(request.url);\n\n  // The estate is the SAME decision as the credential here, and it lives in\n  // a further segment AFTER the token. A token pointed at a node marked\n  // \"sandbox\" would otherwise reach the live bot, and succeed.\n  const segment = mode === \"sandbox\"\n    ? `/bot${credentials.botToken ?? \"\"}/test`\n    : `/bot${credentials.botToken ?? \"\"}`;\n\n  url.pathname = `${segment}${url.pathname}`;\n  request.url = url.toString();\n}\n\n/** The Telegram service, for the TypeScript runtime. */\nexport const TELEGRAM: ServiceDescriptor = {\n  service: \"telegram\",\n  title: \"Telegram\",\n  sandbox: \"separate-account\",\n  baseUrls: { ...TELEGRAM_BASE_URLS },\n  requires: [...TELEGRAM_REQUIRES],\n  authorize: telegramAuthorize,\n  faker: telegramFaker,\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/triggers/get-updates.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/triggers/get-updates.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram's poll trigger — the delivery contract.\n *\n * A POLL trigger, so there is no signature and no route: Telegram does not\n * push, the host asks on a schedule and persists a cursor between calls.\n * Nothing queues what a stopped poller did not collect, which is why that\n * obligation is written down rather than assumed.\n */\n\nimport {\n  callConnector,\n  type ConnectorResult,\n  type RequestedMode,\n  type Transport,\n  type TriggerDescriptor,\n} from \"@particle-academy/fancy-connector-core\";\nimport { telegramFaker } from \"../faker.js\";\nimport { TELEGRAM } from \"../service.js\";\n\nexport const TELEGRAM_GET_UPDATES: TriggerDescriptor = {\n  service: \"telegram\",\n  operation: \"get_updates\",\n  delivery: \"poll\",\n  setup:\n    \"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.\",\n  minPollSeconds: 1,\n  faker: telegramFaker,\n};\n\n/**\n * Poll Telegram once.\n *\n * GET /getUpdates — https://core.telegram.org/bots/api#getupdates\n *\n * In `fake` mode this resolves to the faker, so the node is runnable on a\n * canvas before any credential exists — with the same envelope a real poll\n * returns.\n */\n\nexport const GET_UPDATES_OPERATION = \"get_updates\";\n\nexport type GetUpdatesOptions = {\n  /** The node's resolved config. Keys: offset, limit, allowedUpdates, sampleText. */\n  config: Record<string, unknown>;\n  credentials?: Record<string, string | undefined>;\n  mode?: RequestedMode;\n  connectionId?: string | null;\n  input?: unknown;\n  attempts?: number;\n  /** Override the transport. The only way to exercise this without a network. */\n  transport?: Transport;\n};\n\nexport async function telegramGetUpdates(options: GetUpdatesOptions): Promise<ConnectorResult> {\n  const config = options.config ?? {};\n\n  {\n    const n = Number(config.offset);\n    const given = config.offset !== undefined && config.offset !== null && config.offset !== \"\";\n    if (given && !(Number.isInteger(n))) {\n      throw new Error(\n        `get_updates: \"offset\" must be a integer, got ${JSON.stringify(config.offset)}.`,\n      );\n    }\n  }\n\n  {\n    const n = Number(config.limit);\n    const given = config.limit !== undefined && config.limit !== null && config.limit !== \"\";\n    if (given && !(Number.isInteger(n) && n >= 1 && n <= 100)) {\n      throw new Error(\n        `get_updates: \"limit\" must be a integer, got ${JSON.stringify(config.limit)}.`,\n      );\n    }\n  }\n\n  return callConnector(TELEGRAM, {\n    operation: GET_UPDATES_OPERATION,\n    config,\n    input: options.input,\n    ...(options.credentials === undefined ? {} : { credentials: options.credentials }),\n    ...(options.mode === undefined ? {} : { mode: options.mode }),\n    ...(options.connectionId === undefined ? {} : { connectionId: options.connectionId }),\n    ...(options.attempts === undefined ? {} : { attempts: options.attempts }),\n    ...(options.transport === undefined ? {} : { transport: options.transport }),\n    request: {\n      method: \"GET\",\n      path: \"/getUpdates\",\n      query: {\n        ...(config.offset !== undefined && config.offset !== null && config.offset !== \"\" ? { \"offset\": Math.trunc(Number(config.offset)) } : {}),\n        \"limit\": config.limit !== undefined && config.limit !== null && config.limit !== \"\" ? Math.trunc(Number(config.limit)) : 100,\n        ...(config.allowedUpdates !== undefined && config.allowedUpdates !== null && config.allowedUpdates !== \"\" ? { \"allowed_updates\": JSON.stringify(allowedUpdatesList(config.allowedUpdates)) } : {}),\n      },\n    },\n  });\n}\n\n/** One value, a \",\"-separated string, or an array — all end up a list. */\nfunction allowedUpdatesList(value: unknown): string[] {\n  const items = Array.isArray(value)\n    ? value.map(String)\n    : typeof value === \"string\"\n      ? value.split(\",\")\n      : [];\n\n  return items.map((item) => item.trim()).filter(Boolean);\n}\n"]}

package/dist/flow.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+var fancyConnectorCore = require('@particle-academy/fancy-connector-core');
+var telegramUi = require('@particle-academy/telegram-ui');
+
+// src/flow.ts
+
+// src/faker.ts
+function fakeGetUpdates({ config, fake }) {
+  const boundChatId = fake.int(1e8, 999999999);
+  return {
+    "ok": true,
+    "result": [
+      {
+        "update_id": fake.int(1e5, 999999),
+        "message": {
+          "message_id": fake.int(1, 9999),
+          "date": 1767225600,
+          "text": config.sampleText !== void 0 && config.sampleText !== null && config.sampleText !== "" ? String(config.sampleText) : "hello from the faker",
+          "chat": {
+            "id": boundChatId,
+            "type": "private",
+            "first_name": "Ada",
+            "username": "ada_example"
+          },
+          "from": {
+            "id": boundChatId,
+            "is_bot": false,
+            "first_name": "Ada",
+            "username": "ada_example",
+            "language_code": "en"
+          }
+        }
+      }
+    ]
+  };
+}
+var telegramFaker = (operation, request) => {
+  switch (operation) {
+    case "get_updates":
+      return fakeGetUpdates(request);
+    default:
+      throw new Error(
+        `telegram: no fake response is defined for "${operation}". Add a fixture under provider/fixtures/ and regenerate \u2014 a connector without a faker cannot be developed against, tested, or demonstrated.`
+      );
+  }
+};
+
+// src/service.ts
+var TELEGRAM_BASE_URLS = {
+  "live": "https://api.telegram.org",
+  "sandbox": "https://api.telegram.org"
+};
+var TELEGRAM_REQUIRES = [
+  "botToken"
+];
+function telegramAuthorize(credentials, request, mode) {
+  const url = new URL(request.url);
+  const segment = mode === "sandbox" ? `/bot${credentials.botToken ?? ""}/test` : `/bot${credentials.botToken ?? ""}`;
+  url.pathname = `${segment}${url.pathname}`;
+  request.url = url.toString();
+}
+var TELEGRAM = {
+  service: "telegram",
+  title: "Telegram",
+  sandbox: "separate-account",
+  baseUrls: { ...TELEGRAM_BASE_URLS },
+  requires: [...TELEGRAM_REQUIRES],
+  authorize: telegramAuthorize,
+  faker: telegramFaker
+};
+var GET_UPDATES_OPERATION = "get_updates";
+async function telegramGetUpdates(options) {
+  const config = options.config ?? {};
+  {
+    const n = Number(config.offset);
+    const given = config.offset !== void 0 && config.offset !== null && config.offset !== "";
+    if (given && !Number.isInteger(n)) {
+      throw new Error(
+        `get_updates: "offset" must be a integer, got ${JSON.stringify(config.offset)}.`
+      );
+    }
+  }
+  {
+    const n = Number(config.limit);
+    const given = config.limit !== void 0 && config.limit !== null && config.limit !== "";
+    if (given && !(Number.isInteger(n) && n >= 1 && n <= 100)) {
+      throw new Error(
+        `get_updates: "limit" must be a integer, got ${JSON.stringify(config.limit)}.`
+      );
+    }
+  }
+  return fancyConnectorCore.callConnector(TELEGRAM, {
+    operation: GET_UPDATES_OPERATION,
+    config,
+    input: options.input,
+    ...options.credentials === void 0 ? {} : { credentials: options.credentials },
+    ...options.mode === void 0 ? {} : { mode: options.mode },
+    ...options.connectionId === void 0 ? {} : { connectionId: options.connectionId },
+    ...options.attempts === void 0 ? {} : { attempts: options.attempts },
+    ...options.transport === void 0 ? {} : { transport: options.transport },
+    request: {
+      method: "GET",
+      path: "/getUpdates",
+      query: {
+        ...config.offset !== void 0 && config.offset !== null && config.offset !== "" ? { "offset": Math.trunc(Number(config.offset)) } : {},
+        "limit": config.limit !== void 0 && config.limit !== null && config.limit !== "" ? Math.trunc(Number(config.limit)) : 100,
+        ...config.allowedUpdates !== void 0 && config.allowedUpdates !== null && config.allowedUpdates !== "" ? { "allowed_updates": JSON.stringify(allowedUpdatesList(config.allowedUpdates)) } : {}
+      }
+    }
+  });
+}
+function allowedUpdatesList(value) {
+  const items = Array.isArray(value) ? value.map(String) : typeof value === "string" ? value.split(",") : [];
+  return items.map((item) => item.trim()).filter(Boolean);
+}
+
+// src/flow.ts
+var telegramUpdatesTriggerExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const result = await telegramGetUpdates({ config });
+  const data = result.data;
+  if (data?.ok === false) {
+    throw new Error(
+      `get_updates: getUpdates was rejected \u2014 ` + String(data.description ?? "no reason given")
+    );
+  }
+  const items = Array.isArray(data?.result) ? data.result : [];
+  const seen = items.map((item) => item?.update_id).filter((id) => typeof id === "number");
+  const previous = config.offset === void 0 || config.offset === null || config.offset === "" ? void 0 : Number(config.offset);
+  const cursor = seen.length === 0 ? previous : Math.max(...seen) + 1;
+  const value = {
+    mode: result.mode,
+    connection: result.connection,
+    cursor,
+    count: items.length,
+    updates: items,
+    update: items[0] ?? null
+  };
+  if (items.length === 0) {
+    return { __port: "empty", value };
+  }
+  ctx.emit({
+    type: "log",
+    level: "info",
+    nodeId: ctx.node.id,
+    message: `telegram: ${items.length} item(s), next cursor ${cursor} (${result.mode})`
+  });
+  return { __port: "out", value };
+};
+var TELEGRAM_RUNNABLE_KINDS = [
+  { ...telegramUi.telegramUpdatesTriggerKind, executor: telegramUpdatesTriggerExecutor }
+];
+
+exports.TELEGRAM_RUNNABLE_KINDS = TELEGRAM_RUNNABLE_KINDS;
+exports.telegramUpdatesTriggerExecutor = telegramUpdatesTriggerExecutor;
+//# sourceMappingURL=flow.cjs.map
+//# sourceMappingURL=flow.cjs.map

package/dist/flow.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/faker.ts","../src/service.ts","../src/triggers/get-updates.ts","../src/flow.ts"],"names":["callConnector","telegramUpdatesTriggerKind"],"mappings":"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","file":"flow.cjs","sourcesContent":["/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/fixtures/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/fixtures/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * The Telegram faker.\n *\n * Shapes, not behaviour: the goal is that a downstream node sees the field\n * NAMES Telegram actually publishes, so an author can wire {{ $json.data.id }}\n * against a fake and have it keep working against the real thing.\n *\n * Deterministic — same inputs, same output. A faker returning a fresh uuid\n * every call cannot be asserted on, so its fixtures degrade to \"it did not\n * throw\", which is the assertion that catches nothing.\n */\n\nimport type { ConnectorFaker, FakeRequest } from \"@particle-academy/fancy-connector-core\";\n\nfunction fakeGetUpdates({ config, fake }: FakeRequest): unknown {\n  const boundChatId = fake.int(100000000, 999999999);\n\n  return {\n    \"ok\": true,\n    \"result\": [\n      {\n        \"update_id\": fake.int(100000, 999999),\n        \"message\": {\n          \"message_id\": fake.int(1, 9999),\n          \"date\": 1767225600,\n          \"text\": (config.sampleText !== undefined && config.sampleText !== null && config.sampleText !== \"\" ? String(config.sampleText) : \"hello from the faker\"),\n          \"chat\": {\n            \"id\": boundChatId,\n            \"type\": \"private\",\n            \"first_name\": \"Ada\",\n            \"username\": \"ada_example\",\n          },\n          \"from\": {\n            \"id\": boundChatId,\n            \"is_bot\": false,\n            \"first_name\": \"Ada\",\n            \"username\": \"ada_example\",\n            \"language_code\": \"en\",\n          },\n        },\n      },\n    ],\n  };\n}\n\nexport const telegramFaker: ConnectorFaker = (operation, request) => {\n  switch (operation) {\n    case \"get_updates\":\n      return fakeGetUpdates(request);\n\n    default:\n      // A faker asked for an operation it has no shape for must SAY so. Making\n      // something up would produce a green run whose output silently has none\n      // of the fields the author is about to reference.\n      throw new Error(\n        `telegram: no fake response is defined for \"${operation}\". ` +\n          \"Add a fixture under provider/fixtures/ and regenerate — a connector without a faker \" +\n          \"cannot be developed against, tested, or demonstrated.\",\n      );\n  }\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/manifest.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/manifest.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram, as one service descriptor shared by every Telegram operation.\n *\n * @particle-academy/fancy-connector-core carries what is true of ALL\n * connectors. This carries what is true of Telegram: its base URL, its auth\n * scheme, its idempotency header, and its faker.\n *\n * ## The sandbox trap, written down where it is used\n *\n * Telegram's test environment is a genuinely SEPARATE ACCOUNT: you create a\n * new account inside it and register a new bot there, so the sandbox\n * credential is a different token rather than the same one pointed elsewhere.\n * The `/test` path segment is how you reach it; the account is what makes it\n * separate. Flood limits are NOT relaxed there, so it is a place to test, not\n * a place to hammer.\n */\n\nimport type { ConnectorMode, PreparedRequest, ServiceDescriptor } from \"@particle-academy/fancy-connector-core\";\n\nimport { telegramFaker } from \"./faker.js\";\n\n/**\n * The connector API version this package was GENERATED against.\n *\n * A literal, never imported. An imported constant lets an upgrade rewrite the\n * very claim it exists to detect, after which the copy agrees with itself\n * forever.\n */\nexport const CONNECTOR_API_VERSION = 1;\n\nexport const TELEGRAM_BASE_URLS = {\n  \"live\": \"https://api.telegram.org\",\n  \"sandbox\": \"https://api.telegram.org\"\n} as const;\n\n/** Credential keys a remote call cannot proceed without. */\nexport const TELEGRAM_REQUIRES = [\n  \"botToken\"\n] as const;\n\n/**\n * Apply Telegram's auth scheme to an outgoing request.\n *\n * The bot token is a PATH SEGMENT, not a header --\n * https://api.telegram.org/bot<token>/getUpdates -- and the test environment\n * is a further `/test` AFTER the token. So this is the first provider whose\n * auth and whose estate are the same decision expressed in the URL, which is\n * why `authorize` has always been handed the resolved mode. The token\n * therefore ends up in the request URL, where access logs and error reporters\n * will record it. That is Telegram's design, not ours; a host should keep its\n * own logging away from it.\n *\n * The mode is USED here: for this provider auth and estate are the same\n * decision expressed in the URL, which is what this parameter has always been\n * for.\n */\nexport function telegramAuthorize(\n  credentials: Record<string, string | undefined>,\n  request: PreparedRequest,\n  mode: ConnectorMode,\n): void {\n  const url = new URL(request.url);\n\n  // The estate is the SAME decision as the credential here, and it lives in\n  // a further segment AFTER the token. A token pointed at a node marked\n  // \"sandbox\" would otherwise reach the live bot, and succeed.\n  const segment = mode === \"sandbox\"\n    ? `/bot${credentials.botToken ?? \"\"}/test`\n    : `/bot${credentials.botToken ?? \"\"}`;\n\n  url.pathname = `${segment}${url.pathname}`;\n  request.url = url.toString();\n}\n\n/** The Telegram service, for the TypeScript runtime. */\nexport const TELEGRAM: ServiceDescriptor = {\n  service: \"telegram\",\n  title: \"Telegram\",\n  sandbox: \"separate-account\",\n  baseUrls: { ...TELEGRAM_BASE_URLS },\n  requires: [...TELEGRAM_REQUIRES],\n  authorize: telegramAuthorize,\n  faker: telegramFaker,\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/triggers/get-updates.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/triggers/get-updates.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram's poll trigger — the delivery contract.\n *\n * A POLL trigger, so there is no signature and no route: Telegram does not\n * push, the host asks on a schedule and persists a cursor between calls.\n * Nothing queues what a stopped poller did not collect, which is why that\n * obligation is written down rather than assumed.\n */\n\nimport {\n  callConnector,\n  type ConnectorResult,\n  type RequestedMode,\n  type Transport,\n  type TriggerDescriptor,\n} from \"@particle-academy/fancy-connector-core\";\nimport { telegramFaker } from \"../faker.js\";\nimport { TELEGRAM } from \"../service.js\";\n\nexport const TELEGRAM_GET_UPDATES: TriggerDescriptor = {\n  service: \"telegram\",\n  operation: \"get_updates\",\n  delivery: \"poll\",\n  setup:\n    \"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.\",\n  minPollSeconds: 1,\n  faker: telegramFaker,\n};\n\n/**\n * Poll Telegram once.\n *\n * GET /getUpdates — https://core.telegram.org/bots/api#getupdates\n *\n * In `fake` mode this resolves to the faker, so the node is runnable on a\n * canvas before any credential exists — with the same envelope a real poll\n * returns.\n */\n\nexport const GET_UPDATES_OPERATION = \"get_updates\";\n\nexport type GetUpdatesOptions = {\n  /** The node's resolved config. Keys: offset, limit, allowedUpdates, sampleText. */\n  config: Record<string, unknown>;\n  credentials?: Record<string, string | undefined>;\n  mode?: RequestedMode;\n  connectionId?: string | null;\n  input?: unknown;\n  attempts?: number;\n  /** Override the transport. The only way to exercise this without a network. */\n  transport?: Transport;\n};\n\nexport async function telegramGetUpdates(options: GetUpdatesOptions): Promise<ConnectorResult> {\n  const config = options.config ?? {};\n\n  {\n    const n = Number(config.offset);\n    const given = config.offset !== undefined && config.offset !== null && config.offset !== \"\";\n    if (given && !(Number.isInteger(n))) {\n      throw new Error(\n        `get_updates: \"offset\" must be a integer, got ${JSON.stringify(config.offset)}.`,\n      );\n    }\n  }\n\n  {\n    const n = Number(config.limit);\n    const given = config.limit !== undefined && config.limit !== null && config.limit !== \"\";\n    if (given && !(Number.isInteger(n) && n >= 1 && n <= 100)) {\n      throw new Error(\n        `get_updates: \"limit\" must be a integer, got ${JSON.stringify(config.limit)}.`,\n      );\n    }\n  }\n\n  return callConnector(TELEGRAM, {\n    operation: GET_UPDATES_OPERATION,\n    config,\n    input: options.input,\n    ...(options.credentials === undefined ? {} : { credentials: options.credentials }),\n    ...(options.mode === undefined ? {} : { mode: options.mode }),\n    ...(options.connectionId === undefined ? {} : { connectionId: options.connectionId }),\n    ...(options.attempts === undefined ? {} : { attempts: options.attempts }),\n    ...(options.transport === undefined ? {} : { transport: options.transport }),\n    request: {\n      method: \"GET\",\n      path: \"/getUpdates\",\n      query: {\n        ...(config.offset !== undefined && config.offset !== null && config.offset !== \"\" ? { \"offset\": Math.trunc(Number(config.offset)) } : {}),\n        \"limit\": config.limit !== undefined && config.limit !== null && config.limit !== \"\" ? Math.trunc(Number(config.limit)) : 100,\n        ...(config.allowedUpdates !== undefined && config.allowedUpdates !== null && config.allowedUpdates !== \"\" ? { \"allowed_updates\": JSON.stringify(allowedUpdatesList(config.allowedUpdates)) } : {}),\n      },\n    },\n  });\n}\n\n/** One value, a \",\"-separated string, or an array — all end up a list. */\nfunction allowedUpdatesList(value: unknown): string[] {\n  const items = Array.isArray(value)\n    ? value.map(String)\n    : typeof value === \"string\"\n      ? value.split(\",\")\n      : [];\n\n  return items.map((item) => item.trim()).filter(Boolean);\n}\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/actions/ + triggers/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/actions/ + triggers/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram's node kinds with their TypeScript executors attached — for hosts\n * that EXECUTE on TS.\n *\n * The authoring surface in @particle-academy/telegram-ui carries no executor:\n * the editor is React on every host, so a PHP or Python project installs the\n * ui package and never this one.\n */\n\nimport type { NodeExecutor, NodeKindDefinition } from \"@particle-academy/fancy-flow/engine\";\nimport {\n  idempotencyKeyFor,\n  NO_IDEMPOTENCY_KEY_WARNING,\n  resolveConnection,\n  triggerEvent,\n  type RequestedMode,\n} from \"@particle-academy/fancy-connector-core\";\nimport { TELEGRAM } from \"./service.js\";\n\nimport {\n  telegramUpdatesTriggerKind,\n} from \"@particle-academy/telegram-ui\";\n\nimport { TELEGRAM_GET_UPDATES, telegramGetUpdates } from \"./triggers/get-updates.js\";\n\nexport const telegramUpdatesTriggerExecutor: NodeExecutor = async (ctx) => {\n  const config = ((ctx.node.data as { config?: Record<string, unknown> })?.config ?? {});\n\n  const result = await telegramGetUpdates({ config });\n  const data = result.data as Record<string, unknown> | undefined;\n\n  // Telegram answers HTTP 200 with `{ok: false}` for an application-level\n  // failure. A status check alone reads that as success and publishes an\n  // empty batch — a poll that silently finds nothing, forever, which is\n  // indistinguishable from a quiet channel. The connector core cannot know\n  // this; it is exactly the per-provider knowledge a definition exists to\n  // hold.\n  if (data?.ok === false) {\n    throw new Error(\n      `get_updates: getUpdates was rejected — ` +\n        String(data.description ?? \"no reason given\"),\n    );\n  }\n\n  const items = Array.isArray(data?.result) ? (data.result as unknown[]) : [];\n\n  // `offset` means \"the first one I have NOT handled\", so the next cursor\n  // is the highest id seen plus one. Off by one in either direction is a\n  // real bug with no error attached: too low replays every item forever,\n  // too high drops one silently. The HOST persists this and passes it back\n  // in — nothing else will.\n  const seen = items\n    .map((item) => (item as { update_id?: unknown })?.update_id)\n    .filter((id): id is number => typeof id === \"number\");\n  const previous = config.offset === undefined || config.offset === null || config.offset === \"\"\n    ? undefined\n    : Number(config.offset);\n  const cursor = seen.length === 0 ? previous : Math.max(...seen) + 1;\n\n  const value = {\n    mode: result.mode,\n    connection: result.connection,\n    cursor,\n    count: items.length,\n    updates: items,\n    update: items[0] ?? null,\n  };\n\n  // A poll that found nothing is the NORMAL case, not a failure. Routing\n  // it to its own port keeps the main path meaning \"something happened\",\n  // and still gives the host somewhere to hang its cursor bookkeeping.\n  if (items.length === 0) {\n    return { __port: \"empty\", value };\n  }\n\n  ctx.emit({\n    type: \"log\",\n    level: \"info\",\n    nodeId: ctx.node.id,\n    message: `telegram: ${items.length} item(s), next cursor ${cursor} (${result.mode})`,\n  });\n\n  return { __port: \"out\", value };\n};\n\n/** The kinds a TypeScript host registers. */\nexport const TELEGRAM_RUNNABLE_KINDS: NodeKindDefinition[] = [\n  { ...telegramUpdatesTriggerKind, executor: telegramUpdatesTriggerExecutor },\n];\n"]}

package/dist/flow.d.cts

@@ -0,0 +1,26 @@
+import { NodeKindDefinition, NodeExecutor } from '@particle-academy/fancy-flow/engine';
+
+/**
+ * GENERATED FILE — do not edit.
+ *
+ * Emitted from provider/actions/ + 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/actions/ + triggers/ (or weaver's template/) and regenerate:
+ *
+ *     npm run provider -- telegram
+ */
+/**
+ * Telegram's node kinds with their TypeScript executors attached — for hosts
+ * that EXECUTE on TS.
+ *
+ * The authoring surface in @particle-academy/telegram-ui carries no executor:
+ * the editor is React on every host, so a PHP or Python project installs the
+ * ui package and never this one.
+ */
+
+declare const telegramUpdatesTriggerExecutor: NodeExecutor;
+/** The kinds a TypeScript host registers. */
+declare const TELEGRAM_RUNNABLE_KINDS: NodeKindDefinition[];
+
+export { TELEGRAM_RUNNABLE_KINDS, telegramUpdatesTriggerExecutor };

package/dist/flow.d.ts

@@ -0,0 +1,26 @@
+import { NodeKindDefinition, NodeExecutor } from '@particle-academy/fancy-flow/engine';
+
+/**
+ * GENERATED FILE — do not edit.
+ *
+ * Emitted from provider/actions/ + 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/actions/ + triggers/ (or weaver's template/) and regenerate:
+ *
+ *     npm run provider -- telegram
+ */
+/**
+ * Telegram's node kinds with their TypeScript executors attached — for hosts
+ * that EXECUTE on TS.
+ *
+ * The authoring surface in @particle-academy/telegram-ui carries no executor:
+ * the editor is React on every host, so a PHP or Python project installs the
+ * ui package and never this one.
+ */
+
+declare const telegramUpdatesTriggerExecutor: NodeExecutor;
+/** The kinds a TypeScript host registers. */
+declare const TELEGRAM_RUNNABLE_KINDS: NodeKindDefinition[];
+
+export { TELEGRAM_RUNNABLE_KINDS, telegramUpdatesTriggerExecutor };

package/dist/flow.js

@@ -0,0 +1,43 @@
+import { telegramGetUpdates } from './chunk-LFMQKSUM.js';
+import '@particle-academy/fancy-connector-core';
+import { telegramUpdatesTriggerKind } from '@particle-academy/telegram-ui';
+
+var telegramUpdatesTriggerExecutor = async (ctx) => {
+  const config = ctx.node.data?.config ?? {};
+  const result = await telegramGetUpdates({ config });
+  const data = result.data;
+  if (data?.ok === false) {
+    throw new Error(
+      `get_updates: getUpdates was rejected \u2014 ` + String(data.description ?? "no reason given")
+    );
+  }
+  const items = Array.isArray(data?.result) ? data.result : [];
+  const seen = items.map((item) => item?.update_id).filter((id) => typeof id === "number");
+  const previous = config.offset === void 0 || config.offset === null || config.offset === "" ? void 0 : Number(config.offset);
+  const cursor = seen.length === 0 ? previous : Math.max(...seen) + 1;
+  const value = {
+    mode: result.mode,
+    connection: result.connection,
+    cursor,
+    count: items.length,
+    updates: items,
+    update: items[0] ?? null
+  };
+  if (items.length === 0) {
+    return { __port: "empty", value };
+  }
+  ctx.emit({
+    type: "log",
+    level: "info",
+    nodeId: ctx.node.id,
+    message: `telegram: ${items.length} item(s), next cursor ${cursor} (${result.mode})`
+  });
+  return { __port: "out", value };
+};
+var TELEGRAM_RUNNABLE_KINDS = [
+  { ...telegramUpdatesTriggerKind, executor: telegramUpdatesTriggerExecutor }
+];
+
+export { TELEGRAM_RUNNABLE_KINDS, telegramUpdatesTriggerExecutor };
+//# sourceMappingURL=flow.js.map
+//# sourceMappingURL=flow.js.map

package/dist/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/flow.ts"],"names":[],"mappings":";;;;AAoCO,IAAM,8BAAA,GAA+C,OAAO,GAAA,KAAQ;AACzE,EAAA,MAAM,MAAA,GAAW,GAAA,CAAI,IAAA,CAAK,IAAA,EAA+C,UAAU,EAAC;AAEpF,EAAA,MAAM,MAAA,GAAS,MAAM,kBAAA,CAAmB,EAAE,QAAQ,CAAA;AAClD,EAAA,MAAM,OAAO,MAAA,CAAO,IAAA;AAQpB,EAAA,IAAI,IAAA,EAAM,OAAO,KAAA,EAAO;AACtB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,4CAAA,CAAA,GACE,MAAA,CAAO,IAAA,CAAK,WAAA,IAAe,iBAAiB;AAAA,KAChD;AAAA,EACF;AAEA,EAAA,MAAM,KAAA,GAAQ,MAAM,OAAA,CAAQ,IAAA,EAAM,MAAM,CAAA,GAAK,IAAA,CAAK,SAAuB,EAAC;AAO1E,EAAA,MAAM,IAAA,GAAO,KAAA,CACV,GAAA,CAAI,CAAC,IAAA,KAAU,IAAA,EAAkC,SAAS,CAAA,CAC1D,MAAA,CAAO,CAAC,EAAA,KAAqB,OAAO,OAAO,QAAQ,CAAA;AACtD,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,MAAA,KAAW,MAAA,IAAa,MAAA,CAAO,MAAA,KAAW,IAAA,IAAQ,MAAA,CAAO,MAAA,KAAW,EAAA,GACxF,MAAA,GACA,MAAA,CAAO,OAAO,MAAM,CAAA;AACxB,EAAA,MAAM,MAAA,GAAS,KAAK,MAAA,KAAW,CAAA,GAAI,WAAW,IAAA,CAAK,GAAA,CAAI,GAAG,IAAI,CAAA,GAAI,CAAA;AAElE,EAAA,MAAM,KAAA,GAAQ;AAAA,IACZ,MAAM,MAAA,CAAO,IAAA;AAAA,IACb,YAAY,MAAA,CAAO,UAAA;AAAA,IACnB,MAAA;AAAA,IACA,OAAO,KAAA,CAAM,MAAA;AAAA,IACb,OAAA,EAAS,KAAA;AAAA,IACT,MAAA,EAAQ,KAAA,CAAM,CAAC,CAAA,IAAK;AAAA,GACtB;AAKA,EAAA,IAAI,KAAA,CAAM,WAAW,CAAA,EAAG;AACtB,IAAA,OAAO,EAAE,MAAA,EAAQ,OAAA,EAAS,KAAA,EAAM;AAAA,EAClC;AAEA,EAAA,GAAA,CAAI,IAAA,CAAK;AAAA,IACP,IAAA,EAAM,KAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,MAAA,EAAQ,IAAI,IAAA,CAAK,EAAA;AAAA,IACjB,OAAA,EAAS,aAAa,KAAA,CAAM,MAAM,yBAAyB,MAAM,CAAA,EAAA,EAAK,OAAO,IAAI,CAAA,CAAA;AAAA,GAClF,CAAA;AAED,EAAA,OAAO,EAAE,MAAA,EAAQ,KAAA,EAAO,KAAA,EAAM;AAChC;AAGO,IAAM,uBAAA,GAAgD;AAAA,EAC3D,EAAE,GAAG,0BAAA,EAA4B,QAAA,EAAU,8BAAA;AAC7C","file":"flow.js","sourcesContent":["/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/actions/ + triggers/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/actions/ + triggers/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram's node kinds with their TypeScript executors attached — for hosts\n * that EXECUTE on TS.\n *\n * The authoring surface in @particle-academy/telegram-ui carries no executor:\n * the editor is React on every host, so a PHP or Python project installs the\n * ui package and never this one.\n */\n\nimport type { NodeExecutor, NodeKindDefinition } from \"@particle-academy/fancy-flow/engine\";\nimport {\n  idempotencyKeyFor,\n  NO_IDEMPOTENCY_KEY_WARNING,\n  resolveConnection,\n  triggerEvent,\n  type RequestedMode,\n} from \"@particle-academy/fancy-connector-core\";\nimport { TELEGRAM } from \"./service.js\";\n\nimport {\n  telegramUpdatesTriggerKind,\n} from \"@particle-academy/telegram-ui\";\n\nimport { TELEGRAM_GET_UPDATES, telegramGetUpdates } from \"./triggers/get-updates.js\";\n\nexport const telegramUpdatesTriggerExecutor: NodeExecutor = async (ctx) => {\n  const config = ((ctx.node.data as { config?: Record<string, unknown> })?.config ?? {});\n\n  const result = await telegramGetUpdates({ config });\n  const data = result.data as Record<string, unknown> | undefined;\n\n  // Telegram answers HTTP 200 with `{ok: false}` for an application-level\n  // failure. A status check alone reads that as success and publishes an\n  // empty batch — a poll that silently finds nothing, forever, which is\n  // indistinguishable from a quiet channel. The connector core cannot know\n  // this; it is exactly the per-provider knowledge a definition exists to\n  // hold.\n  if (data?.ok === false) {\n    throw new Error(\n      `get_updates: getUpdates was rejected — ` +\n        String(data.description ?? \"no reason given\"),\n    );\n  }\n\n  const items = Array.isArray(data?.result) ? (data.result as unknown[]) : [];\n\n  // `offset` means \"the first one I have NOT handled\", so the next cursor\n  // is the highest id seen plus one. Off by one in either direction is a\n  // real bug with no error attached: too low replays every item forever,\n  // too high drops one silently. The HOST persists this and passes it back\n  // in — nothing else will.\n  const seen = items\n    .map((item) => (item as { update_id?: unknown })?.update_id)\n    .filter((id): id is number => typeof id === \"number\");\n  const previous = config.offset === undefined || config.offset === null || config.offset === \"\"\n    ? undefined\n    : Number(config.offset);\n  const cursor = seen.length === 0 ? previous : Math.max(...seen) + 1;\n\n  const value = {\n    mode: result.mode,\n    connection: result.connection,\n    cursor,\n    count: items.length,\n    updates: items,\n    update: items[0] ?? null,\n  };\n\n  // A poll that found nothing is the NORMAL case, not a failure. Routing\n  // it to its own port keeps the main path meaning \"something happened\",\n  // and still gives the host somewhere to hang its cursor bookkeeping.\n  if (items.length === 0) {\n    return { __port: \"empty\", value };\n  }\n\n  ctx.emit({\n    type: \"log\",\n    level: \"info\",\n    nodeId: ctx.node.id,\n    message: `telegram: ${items.length} item(s), next cursor ${cursor} (${result.mode})`,\n  });\n\n  return { __port: \"out\", value };\n};\n\n/** The kinds a TypeScript host registers. */\nexport const TELEGRAM_RUNNABLE_KINDS: NodeKindDefinition[] = [\n  { ...telegramUpdatesTriggerKind, executor: telegramUpdatesTriggerExecutor },\n];\n"]}

package/dist/index.cjs

@@ -0,0 +1,134 @@
+'use strict';
+
+var fancyConnectorCore = require('@particle-academy/fancy-connector-core');
+
+// src/faker.ts
+function fakeGetUpdates({ config, fake }) {
+  const boundChatId = fake.int(1e8, 999999999);
+  return {
+    "ok": true,
+    "result": [
+      {
+        "update_id": fake.int(1e5, 999999),
+        "message": {
+          "message_id": fake.int(1, 9999),
+          "date": 1767225600,
+          "text": config.sampleText !== void 0 && config.sampleText !== null && config.sampleText !== "" ? String(config.sampleText) : "hello from the faker",
+          "chat": {
+            "id": boundChatId,
+            "type": "private",
+            "first_name": "Ada",
+            "username": "ada_example"
+          },
+          "from": {
+            "id": boundChatId,
+            "is_bot": false,
+            "first_name": "Ada",
+            "username": "ada_example",
+            "language_code": "en"
+          }
+        }
+      }
+    ]
+  };
+}
+var telegramFaker = (operation, request) => {
+  switch (operation) {
+    case "get_updates":
+      return fakeGetUpdates(request);
+    default:
+      throw new Error(
+        `telegram: no fake response is defined for "${operation}". Add a fixture under provider/fixtures/ and regenerate \u2014 a connector without a faker cannot be developed against, tested, or demonstrated.`
+      );
+  }
+};
+
+// src/service.ts
+var CONNECTOR_API_VERSION = 1;
+var TELEGRAM_BASE_URLS = {
+  "live": "https://api.telegram.org",
+  "sandbox": "https://api.telegram.org"
+};
+var TELEGRAM_REQUIRES = [
+  "botToken"
+];
+function telegramAuthorize(credentials, request, mode) {
+  const url = new URL(request.url);
+  const segment = mode === "sandbox" ? `/bot${credentials.botToken ?? ""}/test` : `/bot${credentials.botToken ?? ""}`;
+  url.pathname = `${segment}${url.pathname}`;
+  request.url = url.toString();
+}
+var TELEGRAM = {
+  service: "telegram",
+  title: "Telegram",
+  sandbox: "separate-account",
+  baseUrls: { ...TELEGRAM_BASE_URLS },
+  requires: [...TELEGRAM_REQUIRES],
+  authorize: telegramAuthorize,
+  faker: telegramFaker
+};
+var TELEGRAM_GET_UPDATES = {
+  service: "telegram",
+  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 \u2014 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.",
+  minPollSeconds: 1,
+  faker: telegramFaker
+};
+var GET_UPDATES_OPERATION = "get_updates";
+async function telegramGetUpdates(options) {
+  const config = options.config ?? {};
+  {
+    const n = Number(config.offset);
+    const given = config.offset !== void 0 && config.offset !== null && config.offset !== "";
+    if (given && !Number.isInteger(n)) {
+      throw new Error(
+        `get_updates: "offset" must be a integer, got ${JSON.stringify(config.offset)}.`
+      );
+    }
+  }
+  {
+    const n = Number(config.limit);
+    const given = config.limit !== void 0 && config.limit !== null && config.limit !== "";
+    if (given && !(Number.isInteger(n) && n >= 1 && n <= 100)) {
+      throw new Error(
+        `get_updates: "limit" must be a integer, got ${JSON.stringify(config.limit)}.`
+      );
+    }
+  }
+  return fancyConnectorCore.callConnector(TELEGRAM, {
+    operation: GET_UPDATES_OPERATION,
+    config,
+    input: options.input,
+    ...options.credentials === void 0 ? {} : { credentials: options.credentials },
+    ...options.mode === void 0 ? {} : { mode: options.mode },
+    ...options.connectionId === void 0 ? {} : { connectionId: options.connectionId },
+    ...options.attempts === void 0 ? {} : { attempts: options.attempts },
+    ...options.transport === void 0 ? {} : { transport: options.transport },
+    request: {
+      method: "GET",
+      path: "/getUpdates",
+      query: {
+        ...config.offset !== void 0 && config.offset !== null && config.offset !== "" ? { "offset": Math.trunc(Number(config.offset)) } : {},
+        "limit": config.limit !== void 0 && config.limit !== null && config.limit !== "" ? Math.trunc(Number(config.limit)) : 100,
+        ...config.allowedUpdates !== void 0 && config.allowedUpdates !== null && config.allowedUpdates !== "" ? { "allowed_updates": JSON.stringify(allowedUpdatesList(config.allowedUpdates)) } : {}
+      }
+    }
+  });
+}
+function allowedUpdatesList(value) {
+  const items = Array.isArray(value) ? value.map(String) : typeof value === "string" ? value.split(",") : [];
+  return items.map((item) => item.trim()).filter(Boolean);
+}
+
+exports.CONNECTOR_API_VERSION = CONNECTOR_API_VERSION;
+exports.GET_UPDATES_OPERATION = GET_UPDATES_OPERATION;
+exports.TELEGRAM = TELEGRAM;
+exports.TELEGRAM_BASE_URLS = TELEGRAM_BASE_URLS;
+exports.TELEGRAM_GET_UPDATES = TELEGRAM_GET_UPDATES;
+exports.TELEGRAM_REQUIRES = TELEGRAM_REQUIRES;
+exports.telegramAuthorize = telegramAuthorize;
+exports.telegramFaker = telegramFaker;
+exports.telegramGetUpdates = telegramGetUpdates;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/faker.ts","../src/service.ts","../src/triggers/get-updates.ts"],"names":["callConnector"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/fixtures/ by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/fixtures/ (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * The Telegram faker.\n *\n * Shapes, not behaviour: the goal is that a downstream node sees the field\n * NAMES Telegram actually publishes, so an author can wire {{ $json.data.id }}\n * against a fake and have it keep working against the real thing.\n *\n * Deterministic — same inputs, same output. A faker returning a fresh uuid\n * every call cannot be asserted on, so its fixtures degrade to \"it did not\n * throw\", which is the assertion that catches nothing.\n */\n\nimport type { ConnectorFaker, FakeRequest } from \"@particle-academy/fancy-connector-core\";\n\nfunction fakeGetUpdates({ config, fake }: FakeRequest): unknown {\n  const boundChatId = fake.int(100000000, 999999999);\n\n  return {\n    \"ok\": true,\n    \"result\": [\n      {\n        \"update_id\": fake.int(100000, 999999),\n        \"message\": {\n          \"message_id\": fake.int(1, 9999),\n          \"date\": 1767225600,\n          \"text\": (config.sampleText !== undefined && config.sampleText !== null && config.sampleText !== \"\" ? String(config.sampleText) : \"hello from the faker\"),\n          \"chat\": {\n            \"id\": boundChatId,\n            \"type\": \"private\",\n            \"first_name\": \"Ada\",\n            \"username\": \"ada_example\",\n          },\n          \"from\": {\n            \"id\": boundChatId,\n            \"is_bot\": false,\n            \"first_name\": \"Ada\",\n            \"username\": \"ada_example\",\n            \"language_code\": \"en\",\n          },\n        },\n      },\n    ],\n  };\n}\n\nexport const telegramFaker: ConnectorFaker = (operation, request) => {\n  switch (operation) {\n    case \"get_updates\":\n      return fakeGetUpdates(request);\n\n    default:\n      // A faker asked for an operation it has no shape for must SAY so. Making\n      // something up would produce a green run whose output silently has none\n      // of the fields the author is about to reference.\n      throw new Error(\n        `telegram: no fake response is defined for \"${operation}\". ` +\n          \"Add a fixture under provider/fixtures/ and regenerate — a connector without a faker \" +\n          \"cannot be developed against, tested, or demonstrated.\",\n      );\n  }\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/manifest.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/manifest.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram, as one service descriptor shared by every Telegram operation.\n *\n * @particle-academy/fancy-connector-core carries what is true of ALL\n * connectors. This carries what is true of Telegram: its base URL, its auth\n * scheme, its idempotency header, and its faker.\n *\n * ## The sandbox trap, written down where it is used\n *\n * Telegram's test environment is a genuinely SEPARATE ACCOUNT: you create a\n * new account inside it and register a new bot there, so the sandbox\n * credential is a different token rather than the same one pointed elsewhere.\n * The `/test` path segment is how you reach it; the account is what makes it\n * separate. Flood limits are NOT relaxed there, so it is a place to test, not\n * a place to hammer.\n */\n\nimport type { ConnectorMode, PreparedRequest, ServiceDescriptor } from \"@particle-academy/fancy-connector-core\";\n\nimport { telegramFaker } from \"./faker.js\";\n\n/**\n * The connector API version this package was GENERATED against.\n *\n * A literal, never imported. An imported constant lets an upgrade rewrite the\n * very claim it exists to detect, after which the copy agrees with itself\n * forever.\n */\nexport const CONNECTOR_API_VERSION = 1;\n\nexport const TELEGRAM_BASE_URLS = {\n  \"live\": \"https://api.telegram.org\",\n  \"sandbox\": \"https://api.telegram.org\"\n} as const;\n\n/** Credential keys a remote call cannot proceed without. */\nexport const TELEGRAM_REQUIRES = [\n  \"botToken\"\n] as const;\n\n/**\n * Apply Telegram's auth scheme to an outgoing request.\n *\n * The bot token is a PATH SEGMENT, not a header --\n * https://api.telegram.org/bot<token>/getUpdates -- and the test environment\n * is a further `/test` AFTER the token. So this is the first provider whose\n * auth and whose estate are the same decision expressed in the URL, which is\n * why `authorize` has always been handed the resolved mode. The token\n * therefore ends up in the request URL, where access logs and error reporters\n * will record it. That is Telegram's design, not ours; a host should keep its\n * own logging away from it.\n *\n * The mode is USED here: for this provider auth and estate are the same\n * decision expressed in the URL, which is what this parameter has always been\n * for.\n */\nexport function telegramAuthorize(\n  credentials: Record<string, string | undefined>,\n  request: PreparedRequest,\n  mode: ConnectorMode,\n): void {\n  const url = new URL(request.url);\n\n  // The estate is the SAME decision as the credential here, and it lives in\n  // a further segment AFTER the token. A token pointed at a node marked\n  // \"sandbox\" would otherwise reach the live bot, and succeed.\n  const segment = mode === \"sandbox\"\n    ? `/bot${credentials.botToken ?? \"\"}/test`\n    : `/bot${credentials.botToken ?? \"\"}`;\n\n  url.pathname = `${segment}${url.pathname}`;\n  request.url = url.toString();\n}\n\n/** The Telegram service, for the TypeScript runtime. */\nexport const TELEGRAM: ServiceDescriptor = {\n  service: \"telegram\",\n  title: \"Telegram\",\n  sandbox: \"separate-account\",\n  baseUrls: { ...TELEGRAM_BASE_URLS },\n  requires: [...TELEGRAM_REQUIRES],\n  authorize: telegramAuthorize,\n  faker: telegramFaker,\n};\n","/**\n * GENERATED FILE — do not edit.\n *\n * Emitted from provider/triggers/get-updates.json by weaver's generator.\n * A hand-edit here is destroyed by the next protocol sync, which is worse than\n * being rejected, because it works until it silently does not. Fix\n * provider/triggers/get-updates.json (or weaver's template/) and regenerate:\n *\n *     npm run provider -- telegram\n */\n\n/**\n * Telegram's poll trigger — the delivery contract.\n *\n * A POLL trigger, so there is no signature and no route: Telegram does not\n * push, the host asks on a schedule and persists a cursor between calls.\n * Nothing queues what a stopped poller did not collect, which is why that\n * obligation is written down rather than assumed.\n */\n\nimport {\n  callConnector,\n  type ConnectorResult,\n  type RequestedMode,\n  type Transport,\n  type TriggerDescriptor,\n} from \"@particle-academy/fancy-connector-core\";\nimport { telegramFaker } from \"../faker.js\";\nimport { TELEGRAM } from \"../service.js\";\n\nexport const TELEGRAM_GET_UPDATES: TriggerDescriptor = {\n  service: \"telegram\",\n  operation: \"get_updates\",\n  delivery: \"poll\",\n  setup:\n    \"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.\",\n  minPollSeconds: 1,\n  faker: telegramFaker,\n};\n\n/**\n * Poll Telegram once.\n *\n * GET /getUpdates — https://core.telegram.org/bots/api#getupdates\n *\n * In `fake` mode this resolves to the faker, so the node is runnable on a\n * canvas before any credential exists — with the same envelope a real poll\n * returns.\n */\n\nexport const GET_UPDATES_OPERATION = \"get_updates\";\n\nexport type GetUpdatesOptions = {\n  /** The node's resolved config. Keys: offset, limit, allowedUpdates, sampleText. */\n  config: Record<string, unknown>;\n  credentials?: Record<string, string | undefined>;\n  mode?: RequestedMode;\n  connectionId?: string | null;\n  input?: unknown;\n  attempts?: number;\n  /** Override the transport. The only way to exercise this without a network. */\n  transport?: Transport;\n};\n\nexport async function telegramGetUpdates(options: GetUpdatesOptions): Promise<ConnectorResult> {\n  const config = options.config ?? {};\n\n  {\n    const n = Number(config.offset);\n    const given = config.offset !== undefined && config.offset !== null && config.offset !== \"\";\n    if (given && !(Number.isInteger(n))) {\n      throw new Error(\n        `get_updates: \"offset\" must be a integer, got ${JSON.stringify(config.offset)}.`,\n      );\n    }\n  }\n\n  {\n    const n = Number(config.limit);\n    const given = config.limit !== undefined && config.limit !== null && config.limit !== \"\";\n    if (given && !(Number.isInteger(n) && n >= 1 && n <= 100)) {\n      throw new Error(\n        `get_updates: \"limit\" must be a integer, got ${JSON.stringify(config.limit)}.`,\n      );\n    }\n  }\n\n  return callConnector(TELEGRAM, {\n    operation: GET_UPDATES_OPERATION,\n    config,\n    input: options.input,\n    ...(options.credentials === undefined ? {} : { credentials: options.credentials }),\n    ...(options.mode === undefined ? {} : { mode: options.mode }),\n    ...(options.connectionId === undefined ? {} : { connectionId: options.connectionId }),\n    ...(options.attempts === undefined ? {} : { attempts: options.attempts }),\n    ...(options.transport === undefined ? {} : { transport: options.transport }),\n    request: {\n      method: \"GET\",\n      path: \"/getUpdates\",\n      query: {\n        ...(config.offset !== undefined && config.offset !== null && config.offset !== \"\" ? { \"offset\": Math.trunc(Number(config.offset)) } : {}),\n        \"limit\": config.limit !== undefined && config.limit !== null && config.limit !== \"\" ? Math.trunc(Number(config.limit)) : 100,\n        ...(config.allowedUpdates !== undefined && config.allowedUpdates !== null && config.allowedUpdates !== \"\" ? { \"allowed_updates\": JSON.stringify(allowedUpdatesList(config.allowedUpdates)) } : {}),\n      },\n    },\n  });\n}\n\n/** One value, a \",\"-separated string, or an array — all end up a list. */\nfunction allowedUpdatesList(value: unknown): string[] {\n  const items = Array.isArray(value)\n    ? value.map(String)\n    : typeof value === \"string\"\n      ? value.split(\",\")\n      : [];\n\n  return items.map((item) => item.trim()).filter(Boolean);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,131 @@
+import { ServiceDescriptor, PreparedRequest, ConnectorMode, ConnectorFaker, RequestedMode, Transport, TriggerDescriptor, ConnectorResult } from '@particle-academy/fancy-connector-core';
+
+/**
+ * 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.
+ *
+ * @particle-academy/fancy-connector-core carries what is true of ALL
+ * connectors. This carries what is true of Telegram: its base URL, its auth
+ * scheme, its idempotency header, and its faker.
+ *
+ * ## 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.
+ */
+
+/**
+ * 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.
+ */
+declare const CONNECTOR_API_VERSION = 1;
+declare const TELEGRAM_BASE_URLS: {
+    readonly live: "https://api.telegram.org";
+    readonly sandbox: "https://api.telegram.org";
+};
+/** Credential keys a remote call cannot proceed without. */
+declare const TELEGRAM_REQUIRES: readonly ["botToken"];
+/**
+ * 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, which is what this parameter has always been
+ * for.
+ */
+declare function telegramAuthorize(credentials: Record<string, string | undefined>, request: PreparedRequest, mode: ConnectorMode): void;
+/** The Telegram service, for the TypeScript runtime. */
+declare const TELEGRAM: ServiceDescriptor;
+
+/**
+ * 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.
+ *
+ * Shapes, not behaviour: the goal is that a downstream node sees the field
+ * NAMES Telegram actually publishes, so an author can wire {{ $json.data.id }}
+ * against a fake and have it keep working against the real thing.
+ *
+ * Deterministic — same inputs, same output. 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.
+ */
+
+declare const telegramFaker: ConnectorFaker;
+
+/**
+ * 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.
+ *
+ * A POLL trigger, so there is no signature and no route: Telegram does not
+ * push, the host asks on a schedule and persists a cursor between calls.
+ * Nothing queues what a stopped poller did not collect, which is why that
+ * obligation is written down rather than assumed.
+ */
+
+declare const TELEGRAM_GET_UPDATES: TriggerDescriptor;
+/**
+ * Poll Telegram once.
+ *
+ * GET /getUpdates — https://core.telegram.org/bots/api#getupdates
+ *
+ * In `fake` mode this resolves to the faker, so the node is runnable on a
+ * canvas before any credential exists — with the same envelope a real poll
+ * returns.
+ */
+declare const GET_UPDATES_OPERATION = "get_updates";
+type GetUpdatesOptions = {
+    /** The node's resolved config. Keys: offset, limit, allowedUpdates, sampleText. */
+    config: Record<string, unknown>;
+    credentials?: Record<string, string | undefined>;
+    mode?: RequestedMode;
+    connectionId?: string | null;
+    input?: unknown;
+    attempts?: number;
+    /** Override the transport. The only way to exercise this without a network. */
+    transport?: Transport;
+};
+declare function telegramGetUpdates(options: GetUpdatesOptions): Promise<ConnectorResult>;
+
+export { CONNECTOR_API_VERSION, GET_UPDATES_OPERATION, type GetUpdatesOptions, TELEGRAM, TELEGRAM_BASE_URLS, TELEGRAM_GET_UPDATES, TELEGRAM_REQUIRES, telegramAuthorize, telegramFaker, telegramGetUpdates };

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+import { ServiceDescriptor, PreparedRequest, ConnectorMode, ConnectorFaker, RequestedMode, Transport, TriggerDescriptor, ConnectorResult } from '@particle-academy/fancy-connector-core';
+
+/**
+ * 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.
+ *
+ * @particle-academy/fancy-connector-core carries what is true of ALL
+ * connectors. This carries what is true of Telegram: its base URL, its auth
+ * scheme, its idempotency header, and its faker.
+ *
+ * ## 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.
+ */
+
+/**
+ * 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.
+ */
+declare const CONNECTOR_API_VERSION = 1;
+declare const TELEGRAM_BASE_URLS: {
+    readonly live: "https://api.telegram.org";
+    readonly sandbox: "https://api.telegram.org";
+};
+/** Credential keys a remote call cannot proceed without. */
+declare const TELEGRAM_REQUIRES: readonly ["botToken"];
+/**
+ * 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, which is what this parameter has always been
+ * for.
+ */
+declare function telegramAuthorize(credentials: Record<string, string | undefined>, request: PreparedRequest, mode: ConnectorMode): void;
+/** The Telegram service, for the TypeScript runtime. */
+declare const TELEGRAM: ServiceDescriptor;
+
+/**
+ * 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.
+ *
+ * Shapes, not behaviour: the goal is that a downstream node sees the field
+ * NAMES Telegram actually publishes, so an author can wire {{ $json.data.id }}
+ * against a fake and have it keep working against the real thing.
+ *
+ * Deterministic — same inputs, same output. 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.
+ */
+
+declare const telegramFaker: ConnectorFaker;
+
+/**
+ * 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.
+ *
+ * A POLL trigger, so there is no signature and no route: Telegram does not
+ * push, the host asks on a schedule and persists a cursor between calls.
+ * Nothing queues what a stopped poller did not collect, which is why that
+ * obligation is written down rather than assumed.
+ */
+
+declare const TELEGRAM_GET_UPDATES: TriggerDescriptor;
+/**
+ * Poll Telegram once.
+ *
+ * GET /getUpdates — https://core.telegram.org/bots/api#getupdates
+ *
+ * In `fake` mode this resolves to the faker, so the node is runnable on a
+ * canvas before any credential exists — with the same envelope a real poll
+ * returns.
+ */
+declare const GET_UPDATES_OPERATION = "get_updates";
+type GetUpdatesOptions = {
+    /** The node's resolved config. Keys: offset, limit, allowedUpdates, sampleText. */
+    config: Record<string, unknown>;
+    credentials?: Record<string, string | undefined>;
+    mode?: RequestedMode;
+    connectionId?: string | null;
+    input?: unknown;
+    attempts?: number;
+    /** Override the transport. The only way to exercise this without a network. */
+    transport?: Transport;
+};
+declare function telegramGetUpdates(options: GetUpdatesOptions): Promise<ConnectorResult>;
+
+export { CONNECTOR_API_VERSION, GET_UPDATES_OPERATION, type GetUpdatesOptions, TELEGRAM, TELEGRAM_BASE_URLS, TELEGRAM_GET_UPDATES, TELEGRAM_REQUIRES, telegramAuthorize, telegramFaker, telegramGetUpdates };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { CONNECTOR_API_VERSION, GET_UPDATES_OPERATION, TELEGRAM, TELEGRAM_BASE_URLS, TELEGRAM_GET_UPDATES, TELEGRAM_REQUIRES, telegramAuthorize, telegramFaker, telegramGetUpdates } from './chunk-LFMQKSUM.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@particle-academy/telegram-js",
+  "version": "0.1.0",
+  "description": "Telegram for Node — the service descriptor, its faker, its webhook verification, and one function per operation. Plain HTTP on @particle-academy/fancy-connector-core; no vendor SDK.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fancy-Friends/telegram.git"
+  },
+  "homepage": "https://github.com/Fancy-Friends/telegram#readme",
+  "bugs": "https://github.com/Fancy-Friends/telegram/issues",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./flow": {
+      "import": {
+        "types": "./dist/flow.d.ts",
+        "default": "./dist/flow.js"
+      },
+      "require": {
+        "types": "./dist/flow.d.cts",
+        "default": "./dist/flow.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepublishOnly": "tsup"
+  },
+  "dependencies": {
+    "@particle-academy/fancy-connector-core": ">=0.3.1 <2.0",
+    "@particle-academy/telegram-ui": "0.1.0"
+  },
+  "peerDependencies": {
+    "@particle-academy/fancy-flow": ">=0.47.1 <2.0"
+  },
+  "peerDependenciesMeta": {
+    "@particle-academy/fancy-flow": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@particle-academy/fancy-flow": ">=0.47.1 <2.0",
+    "@types/node": "^26.2.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "telegram",
+    "messaging",
+    "connector",
+    "api",
+    "fancy-ui",
+    "particle-academy"
+  ],
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  }
+}