planvortex 0.1.0__tar.gz → 0.2.0__tar.gz

{planvortex-0.1.0 → planvortex-0.2.0}/CHANGELOG.md

@@ -4,6 +4,69 @@ All notable changes to this package are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-08-30
+
+Telegram, the eleventh network, reaches the package. No endpoint was added and no signature moved:
+what changes is what the types know — and unlike in the Node library, where an open enumeration
+absorbs an unknown network in silence, here the closed `Literal`s go red until somebody looks. Which
+is the point of them.
+
+Upgrading from `0.1.0` needs no changes, and `MIGRATION.md` gains no entry.
+
+### Added
+
+- **A third authorization shape: `TelegramBotAuthorization`, with its predicate
+  `is_telegram_bot_authorization`.** This is the part that is genuinely new contract rather than one
+  more name in a list. Telegram is the one entry that carries a `link` and still is not somewhere to
+  redirect: it opens a private chat with the PlanVortex bot, with no OAuth behind it — no consent
+  screen, no `code`, no `redirect_uri` — and the account is born minutes later, when the person
+  drops that bot into their channel. It is announced over the WebSocket and the `new_account`
+  webhook, never as the answer to a call of yours, and `accounts.connect` cannot finish it: for
+  `telegram` that endpoint always answers 700. The block carries `bot_username` (the bot's `@name`,
+  without the at sign) and `add_to_group_link`, the second step, which turns comments on by adding
+  the bot to the channel's linked discussion group. **Branch on `authorization["type"]`, never on
+  whether `link` is empty** — that test was already wrong for WhatsApp and it is worse here, because
+  a filled-in `link` makes it look like it worked.
+- **`"telegram"` in `PublishableNetwork`** — the one hand-written union in `_shapes.py` — and
+  therefore in `PUBLISHABLE_NETWORKS`, `COMMENT_NETWORKS` and `SOCIAL_NETWORKS`, which derive from
+  their `Literal` and needed no edit. It is deliberately **not** in `CONTACT_CHANNELS`: Telegram has
+  no direct messages, and putting it there would promise a chat inbox that does not exist. That the
+  contact channels are now a proper subset of the networks, rather than all of them plus `email`, is
+  written down in the test that used to assert the equality.
+- **`PublicationStats.reactions` and `reactions_by_emoji`**, which are Telegram's only publication
+  metric — and neither of them is asked for. `reactions` is the COMPLETE STATE and not an increment,
+  so it goes down when somebody takes theirs back.
+- **`Publication.extra_data`**, for what one network has to remember about one publication and that
+  has no common field. Today only `telegram_message_ids` writes there: on Telegram an album is one
+  publication that is several messages, `external_identifier` holds the first and the rest live
+  here, because deleting the album means deleting all of them.
+
+### Changed
+
+- The network-counting prose, which had quietly stopped being true and that no test watches:
+  `accounts.connect_links`, `SocialAuthorizationMethod`, `ConnectLink`, `PublishableNetwork` and
+  `is_publishable_network` all said "nine of the ten" or "one of ten and one of nine".
+- Two warnings about this network are now on the methods that would otherwise surprise you, because
+  neither has an error code to announce it. **The comment inbox starts the day the channel was
+  connected** — the Bot API cannot read the past, so `comments.list` has nothing earlier and never
+  will, and `comments.thread`, which is a live read on every other network, is not live here at all.
+  And **there are no impressions and no reach**: engagement is computed over followers, the only
+  audience figure the Bot API publishes being the channel's member count.
+- `catalog.social_limits` explains Telegram's **two numbers for the same field** — 4.096 characters
+  while the publication is text only and 1.024 the moment it carries an image or a video, because
+  then the text is a media caption. The counter switches when the file is attached, not when publish
+  is pressed.
+- `publications.remove` documents Telegram's **48-hour window** (error 966, with `published_date`
+  and `max_hours` in `data`), which is a button to grey out rather than to offer and fail.
+- `examples/connect.py` grows the third branch, and its `else` — the one that skips an authorization
+  method this version does not know — is no longer hypothetical: `telegram_bot` was exactly that.
+
+### Fixed
+
+- The synchronous twin of `products.get` had been left behind by the previous release: its docstring
+  still said the Node library documented that endpoint as broken. Regenerating `resources_sync`
+  brings it back in line.
+
 ## [0.1.0] - 2026-08-28
 
 The first release with code in it. Every documented endpoint of the PlanVortex API has a method -

{planvortex-0.1.0 → planvortex-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official Python client for the PlanVortex API
 Project-URL: Homepage, https://planvortex.com/developers
 Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/

{planvortex-0.1.0 → planvortex-0.2.0}/openapi/planvortex.openapi.json

@@ -107,7 +107,7 @@
           "accounts"
         ],
         "summary": "Get the connection links of every connectable network",
-        "description": "The authorization URL of each network, so the user can connect an account to this organization.\n\n**A network that cannot produce a link simply does not appear.** That is a legitimate answer, not a failure: it is what happens with `discord` in an organization that has not saved its own bot credentials yet (see `PUT /organizations/{id_organization}/social_credentials/{social_network}`).\n\n**An app cannot call this.** Connecting a social account is an OAuth flow with a person in front of it, so this endpoint only accepts a user token or a temporal connect token; with app credentials it answers error 519. The way an integration does it is to issue a temporal connect token with `GET /organizations/{id_organization}/temporal_connect_token` and hand it to its end user.\n\n**Read `authorization`, not `link`.** Nine of the ten networks are `redirect` and you send the person to `link`. **WhatsApp is not a URL at all**: its sign-up is Meta's Embedded Signup, a popup you raise with the Facebook JavaScript SDK, so its `link` is an empty string and everything you need to open that popup travels in `authorization`. A client that loops over the list and redirects to `link` sends its user to its own page.",
+        "description": "The authorization URL of each network, so the user can connect an account to this organization.\n\n**A network that cannot produce a link simply does not appear.** That is a legitimate answer, not a failure: it is what happens with `discord` in an organization that has not saved its own bot credentials yet (see `PUT /organizations/{id_organization}/social_credentials/{social_network}`).\n\n**An app cannot call this.** Connecting a social account is an OAuth flow with a person in front of it, so this endpoint only accepts a user token or a temporal connect token; with app credentials it answers error 519. The way an integration does it is to issue a temporal connect token with `GET /organizations/{id_organization}/temporal_connect_token` and hand it to its end user.\n\n**Read `authorization`, not `link`.** Nine of the eleven networks are `redirect` and you send the person to `link`. Two are not, and neither of them fails visibly if you treat it as one:\n\n• **WhatsApp is not a URL at all.** Its sign-up is Meta's Embedded Signup, a popup you raise with the Facebook JavaScript SDK, so its `link` is an empty string and everything you need to open that popup travels in `authorization`. A client that loops over the list and redirects to `link` sends its user to its own page.\n• **Telegram has a link and still is not a redirect.** It opens a chat with the PlanVortex bot, and nobody comes back from it: the account is born minutes later, from the bot being added to a channel, and it is announced over the WebSocket. Open it in another tab and keep listening; redirect to it and there is nobody left to tell.",
         "operationId": "getConnectLinks",
         "x-planvortex-identity": [
           "current_user",
@@ -656,7 +656,7 @@
           "accounts"
         ],
         "summary": "Complete the connection of a social account",
-        "description": "The endpoint the social network sends the user back to after they authorize. It turns the network's callback into one or more PlanVortex accounts.\n\n**You do not build this URL, the network does.** It is the `redirect_uri` inside the link that `GET /organizations/{id_organization}/connect_links` handed out, so the query parameters are whatever the network appends — typically `code` and `state`. Pass them through untouched.\n\n**One authorization can produce several accounts.** A Facebook user with four pages ends up with four; a Discord authorization produces the channel that was picked.\n\n**It answers 200 even when it fails.** The result carries `errorCode` and `errorMsg` instead of an error body, because the browser lands here from a redirect and a raw 400 would be a broken page. Check `errorCode`: empty means everything went well.\n\n**An app cannot call this** — it needs a user token or a temporal connect token (error 519 otherwise). See `GET /organizations/{id_organization}/temporal_connect_token`.\n\n**A temporal connect token is spent here.** Once this call succeeds, that token cannot connect anything else and answers error 543; the `enable` calls that finish the same connection still work until it expires. And if the token was issued for one network, calling this for another answers error 544.",
+        "description": "The endpoint the social network sends the user back to after they authorize. It turns the network's callback into one or more PlanVortex accounts.\n\n**You do not build this URL, the network does.** It is the `redirect_uri` inside the link that `GET /organizations/{id_organization}/connect_links` handed out, so the query parameters are whatever the network appends — typically `code` and `state`. Pass them through untouched.\n\n**One authorization can produce several accounts.** A Facebook user with four pages ends up with four; a Discord authorization produces the channel that was picked.\n\n**It answers 200 even when it fails.** The result carries `errorCode` and `errorMsg` instead of an error body, because the browser lands here from a redirect and a raw 400 would be a broken page. Check `errorCode`: empty means everything went well.\n\n**An app cannot call this** — it needs a user token or a temporal connect token (error 519 otherwise). See `GET /organizations/{id_organization}/temporal_connect_token`.\n\n**A temporal connect token is spent here.** Once this call succeeds, that token cannot connect anything else and answers error 543; the `enable` calls that finish the same connection still work until it expires. And if the token was issued for one network, calling this for another answers error 544.\n\n**Telegram does not come through here, and cannot be made to.** That network has no callback: the account is created by PlanVortex when the bot is added to a channel, and what authorizes it is a single-use voucher minted at that moment and spent in the same breath — it never leaves the server, so calling this endpoint for `telegram` answers error 700. It is deliberate: the bot is shared, so without it anyone could hang any channel where that bot is an admin off their own organization by passing a chat id by hand. What an integration listens for instead is the `new_account` webhook notification.",
         "operationId": "connectAccount",
         "x-planvortex-identity": [
           "current_user",
@@ -715,7 +715,7 @@
             }
           },
           "400": {
-            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `519` | This endpoint does not accept app credentials |\n| `543` | This temporal connect token has already connected an account. Issue a new one |\n| `544` | This temporal connect token was issued for a different social network |\n| `1101` | Invalid organization, or a temporal token for a different one |",
+            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `519` | This endpoint does not accept app credentials |\n| `543` | This temporal connect token has already connected an account. Issue a new one |\n| `544` | This temporal connect token was issued for a different social network |\n| `700` | The connection cannot be completed through this endpoint. It is what `telegram` always answers here: that network's accounts are created from the bot being added to a channel, never from a call of yours |\n| `1101` | Invalid organization, or a temporal token for a different one |",
             "content": {
               "application/json": {
                 "schema": {
@@ -1761,7 +1761,8 @@
                   "youtube",
                   "google_business",
                   "bluesky",
-                  "discord"
+                  "discord",
+                  "telegram"
                 ]
               }
             }
@@ -1865,7 +1866,7 @@
           "catalog"
         ],
         "summary": "Per-network publication limits",
-        "description": "Every limit a publication is validated against, indexed by limit and then by network.\n\nRead it before building a composer. A few traps worth knowing:\n\n• **`characters` is not always the only text limit.** Bluesky counts 300 *graphemes* **and** 3.000 *bytes*; the second one travels in `max_post_bytes`, where `0` means \"this network does not measure text in bytes\". A family emoji is one grapheme and eleven UTF-16 units, so counting with `String.length` is wrong in both directions.\n• **`0` in `title_characters` means the network has no title field**, not a title of zero length.\n• **`comment_characters` is a different limit from `characters`.** Facebook takes 63.206 in a post and 8.000 in a comment.\n• Every network in `/social_networks` appears in every map. A missing key is a bug, and the backend's conformance suite fails on it.",
+        "description": "Every limit a publication is validated against, indexed by limit and then by network.\n\nRead it before building a composer. A few traps worth knowing:\n\n• **`characters` is not always the only text limit.** Bluesky counts 300 *graphemes* **and** 3.000 *bytes*; the second one travels in `max_post_bytes`, where `0` means \"this network does not measure text in bytes\". A family emoji is one grapheme and eleven UTF-16 units, so counting with `String.length` is wrong in both directions.\n• **`0` in `title_characters` means the network has no title field**, not a title of zero length.\n• **`comment_characters` is a different limit from `characters`.** Facebook takes 63.206 in a post and 8.000 in a comment.\n• **`characters` is not one number per network either.** Telegram takes 4.096 in a text post and **1.024** in the caption of a photo or a video, and it is the same composer field: the second number is the key `telegram_media`. Over the limit the publication is created in state `withErrors` with `publication_errors[].code = 967`, which carries `characters`, `max_characters` and `has_media`.\n• Every network in `/social_networks` appears in every map. A missing key is a bug, and the backend's conformance suite fails on it.",
         "operationId": "getSocialLimits",
         "x-planvortex-identity": [
           "current_user",
@@ -3441,7 +3442,7 @@
           "comments"
         ],
         "summary": "The inbox: first-level comments across the whole organization",
-        "description": "Served from PlanVortex's database, so it costs nothing and calls no social network. It is a **snapshot**: `collected_date` says when each row was last read. Open a thread to see what the network says right now.\n\nOrdered by `creation_date` descending — the date on the network, not the date we collected it — so rows from six networks interleave correctly.\n\n**Your own replies are not in here.** Anything with `author.is_own: true` is filtered out: what you wrote is not incoming mail. They are still stored, and they do show up in the thread.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
+        "description": "Served from PlanVortex's database, so it costs nothing and calls no social network. It is a **snapshot**: `collected_date` says when each row was last read. Open a thread to see what the network says right now.\n\nOrdered by `creation_date` descending — the date on the network, not the date we collected it — so rows from nine networks interleave correctly.\n\n**On `telegram` the inbox starts the day the channel was connected.** The Bot API has no way to read the past: a bot only learns what happens while it is inside, so nothing written before the connection exists here and never will. Say so in your UI — an inbox that opens empty on a busy channel reads like a failure.\n\n**Your own replies are not in here.** Anything with `author.is_own: true` is filtered out: what you wrote is not incoming mail. They are still stored, and they do show up in the thread.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
         "operationId": "getComments",
         "x-planvortex-identity": [
           "current_user",
@@ -3615,7 +3616,7 @@
           "comments"
         ],
         "summary": "The thread of a publication, read live",
-        "description": "Asks the social network and reconciles with what is stored: the network wins on text, counters and existence; the stored copy only contributes `_id`, `read` and `replied`. Comments the network no longer returns are marked deleted and stop appearing in the inbox.\n\n**On X this call costs money.** X bills per unit read, so the response carries `credits_consumed` with what this particular read spent from the client's monthly pool. It is `0` on every other network. Charging happens after the read and by real units: a failed call charges nothing, and a page with three replies is not charged for fifty.\n\nUse this one when the comment has an `id_publication`. When it does not — a review hangs off a listing — use the per-account endpoint instead.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
+        "description": "Asks the social network and reconciles with what is stored: the network wins on text, counters and existence; the stored copy only contributes `_id`, `read` and `replied`. Comments the network no longer returns are marked deleted and stop appearing in the inbox.\n\n**On X this call costs money.** X bills per unit read, so the response carries `credits_consumed` with what this particular read spent from the client's monthly pool. It is `0` on every other network. Charging happens after the read and by real units: a failed call charges nothing, and a page with three replies is not charged for fifty.\n\nUse this one when the comment has an `id_publication`. When it does not — a review hangs off a listing — use the per-account endpoint instead.\n\n**On `telegram` it is not live**, and that is the one exception to everything above: there is no endpoint in the Bot API that lists the replies to a post, so this returns PlanVortex's own inbox — what the bot has seen since the channel was connected. Nothing is reconciled and nothing is swept as deleted, because there is nothing to compare against.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
         "operationId": "getPublicationComments",
         "x-planvortex-identity": [
           "current_user",
@@ -3744,7 +3745,7 @@
           "comments"
         ],
         "summary": "Reply in public",
-        "description": "Posts a **public** reply on the social network. This is not the same as replying privately to whoever commented — that is a Messenger feature and lives in the messaging endpoints.\n\nThe reply is stored immediately, with `author.is_own: true`, without waiting for the network to index it, and the comment it answers is left `replied: true` and `read: true` with `our_reply_external_id` pointing at it.\n\n**On Google Business this is an upsert.** A review has at most one reply, so replying again does not add a second one: it replaces the text of the one that is there, and the stored row is updated in place. Label your button accordingly — \"reply\" the first time, \"edit reply\" afterwards.\n\nThe text is validated against that network's limit before anything is sent (`comment_characters` in `GET /social_limits`); an empty or over-long text returns error `948` with the limit in `data.max`.\n\n**On X this costs credits**: 15, or 200 if the text contains a link, charged only on success.\n\nRequires the `comments:create` permission (`client_organization_comments:create` for apps) and a paid plan.",
+        "description": "Posts a **public** reply on the social network. This is not the same as replying privately to whoever commented — that is a Messenger feature and lives in the messaging endpoints.\n\nThe reply is stored immediately, with `author.is_own: true`, without waiting for the network to index it, and the comment it answers is left `replied: true` and `read: true` with `our_reply_external_id` pointing at it.\n\n**On Google Business this is an upsert.** A review has at most one reply, so replying again does not add a second one: it replaces the text of the one that is there, and the stored row is updated in place. Label your button accordingly — \"reply\" the first time, \"edit reply\" afterwards.\n\nThe text is validated against that network's limit before anything is sent (`comment_characters` in `GET /social_limits`); an empty or over-long text returns error `948` with the limit in `data.max`.\n\n**On X this costs credits**: 15, or 200 if the text contains a link, charged only on success.\n\n**On `telegram` the reply is signed by the PlanVortex bot**, not by the channel. It is written in the channel's linked discussion group, which is where Telegram keeps the comments on a channel post — and a channel with no discussion group has no comments at all, which is error 965. Publishing is not affected: a channel post is signed by the channel.\n\nRequires the `comments:create` permission (`client_organization_comments:create` for apps) and a paid plan.",
         "operationId": "replyComment",
         "x-planvortex-identity": [
           "current_user",
@@ -3885,7 +3886,7 @@
           "comments"
         ],
         "summary": "Delete the comment on the social network",
-        "description": "Deletes it **on the network** and marks the row `deleted: true` here. The row is kept on purpose rather than removed: if it were removed, the next read of the thread — or the webhook, which repeats — would create it again.\n\nWhich comments you may delete depends on the network and on whose comment it is, and the two cases use different permissions of the network's own: `delete_own` for yours, `delete_others` for somebody else's. Instagram and X refuse the second; **on Google Business the only thing that can be deleted is your own reply**, never a review. Reading `GET /social_comment_actions` first is the difference between a button that works and one that always errors.\n\nOn X this costs credits.\n\nRequires the `comments:delete` permission (`client_organization_comments:delete` for apps) and a paid plan.",
+        "description": "Deletes it **on the network** and marks the row `deleted: true` here. The row is kept on purpose rather than removed: if it were removed, the next read of the thread — or the webhook, which repeats — would create it again.\n\nWhich comments you may delete depends on the network and on whose comment it is, and the two cases use different permissions of the network's own: `delete_own` for yours, `delete_others` for somebody else's. Instagram and X refuse the second; **on Google Business the only thing that can be deleted is your own reply**, never a review. Reading `GET /social_comment_actions` first is the difference between a button that works and one that always errors.\n\nOn X this costs credits.\n\nOn `telegram` both are allowed by the network and both depend on a permission the customer controls: the bot has to be an administrator of the discussion group with the right to delete. When it is not, the answer is error 969 — which is the difference between \"this network cannot\" and \"this particular channel cannot\".\n\nRequires the `comments:delete` permission (`client_organization_comments:delete` for apps) and a paid plan.",
         "operationId": "deleteComment",
         "x-planvortex-identity": [
           "current_user",
@@ -3930,7 +3931,7 @@
           "catalog"
         ],
         "summary": "What every network supports",
-        "description": "The full matrix network → capabilities. It is the **single source of truth** about what a network can do: the catalogue publishes it, the backend checks it before acting, and your integration should filter its account pickers with it rather than keeping a list of its own.\n\n`comments` is the coarse gate — whether the network has comments at all. Which *actions* it allows on one is a finer question and lives in `GET /social_comment_actions`, because the shape here is `{[capability]: boolean}` and nesting an object inside would break it.\n\nToday six networks answer `comments: true`: Facebook, Instagram, LinkedIn, X, YouTube and Google Business. TikTok and WhatsApp answer `false`, for reasons of theirs and not ours.\n\nOnly needs authentication.",
+        "description": "The full matrix network → capabilities. It is the **single source of truth** about what a network can do: the catalogue publishes it, the backend checks it before acting, and your integration should filter its account pickers with it rather than keeping a list of its own.\n\n`comments` is the coarse gate — whether the network has comments at all. Which *actions* it allows on one is a finer question and lives in `GET /social_comment_actions`, because the shape here is `{[capability]: boolean}` and nesting an object inside would break it.\n\nToday nine networks answer `comments: true`: Facebook, Instagram, LinkedIn, X, YouTube, Google Business, Bluesky, Discord and Telegram. TikTok and WhatsApp answer `false`, for reasons of theirs and not ours.\n\nA `true` here is about the **network**, not about one account of it: a Telegram channel with no linked discussion group answers 965 on its comments even though the network has them.\n\nOnly needs authentication.",
         "operationId": "getSocialCapabilities",
         "x-planvortex-identity": [
           "current_user",
@@ -3988,7 +3989,7 @@
           "catalog"
         ],
         "summary": "What each network lets you do to a comment",
-        "description": "The fine-grained matrix: reply, hide, delete your own, delete somebody else's — network by network. Read it before painting controls. Networks without comments answer `false` to all four.\n\nThe differences are real and each has a reason in the network's own API:\n\n| Network | reply | hide | delete_own | delete_others |\n| --- | --- | --- | --- | --- |\n| `facebook` | yes | yes | yes | yes |\n| `instagram` | yes | yes | yes | **no** — Instagram only lets you hide someone else's |\n| `youtube` | yes | yes | yes | yes — the channel owner really does moderate |\n| `linkedin` | yes | **no** — there is no hide endpoint | yes | yes |\n| `twitter` | yes | yes | yes | **no** — you cannot delete another account's post |\n| `google_business` | yes | **no** | yes — **your reply**, never the review | **no** |\n| `bluesky` | yes | yes — through the post's `threadgate` | yes | **no** — the reply lives in somebody else's repository |\n| `discord` | yes | **no** — Discord has no hide, only delete | yes | yes |\n| `tiktok`, `whatsapp` | no | no | no | no |\n\nOnly needs authentication.",
+        "description": "The fine-grained matrix: reply, hide, delete your own, delete somebody else's — network by network. Read it before painting controls. Networks without comments answer `false` to all four.\n\nThe differences are real and each has a reason in the network's own API:\n\n| Network | reply | hide | delete_own | delete_others |\n| --- | --- | --- | --- | --- |\n| `facebook` | yes | yes | yes | yes |\n| `instagram` | yes | yes | yes | **no** — Instagram only lets you hide someone else's |\n| `youtube` | yes | yes | yes | yes — the channel owner really does moderate |\n| `linkedin` | yes | **no** — there is no hide endpoint | yes | yes |\n| `twitter` | yes | yes | yes | **no** — you cannot delete another account's post |\n| `google_business` | yes | **no** | yes — **your reply**, never the review | **no** |\n| `bluesky` | yes | yes — through the post's `threadgate` | yes | **no** — the reply lives in somebody else's repository |\n| `discord` | yes | **no** — Discord has no hide, only delete | yes | yes |\n| `telegram` | yes | **no** — Telegram has no hide either | yes | yes — with the bot as an admin of the discussion group, otherwise error 969 |\n| `tiktok`, `whatsapp` | no | no | no | no |\n\nOnly needs authentication.",
         "operationId": "getSocialCommentActions",
         "x-planvortex-identity": [
           "current_user",
@@ -7994,7 +7995,7 @@
           "publications"
         ],
         "summary": "Delete publication by identifier",
-        "description": "Delete publication by identifier. It stops being readable by identifier afterwards, so deleting twice answers error 917. For an already-sent X (Twitter) publication, removing the tweet on X is a paid action that consumes 15 X credits; it is only removed on X when there are enough credits. Returns error 940 when the X credit pool is exhausted.",
+        "description": "Delete publication by identifier. It stops being readable by identifier afterwards, so deleting twice answers error 917. For an already-sent X (Twitter) publication, removing the tweet on X is a paid action that consumes 15 X credits; it is only removed on X when there are enough credits. Returns error 940 when the X credit pool is exhausted.\n\n**On Telegram there is a 48-hour window.** Past it the Bot API refuses to delete a message whatever the bot's role is, and the answer is error 966 with `published_date` and `max_hours` in `data` — so the sensible thing is to grey the button out rather than offer it and fail. Error 969 is the other case: the bot is no longer allowed to delete there. And an album is several messages: all of them go, or the post would be left half-published in the channel.",
         "operationId": "deletePublication",
         "x-planvortex-identity": [
           "current_user",
@@ -8012,7 +8013,7 @@
             }
           },
           "400": {
-            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `917` | Publication doesn't exists |\n| `935` | Invalid publication |\n| `940` | X (Twitter) credits exhausted. Deleting the tweet on X could not be charged. Response data: { used, limit }. |\n| `523` | Invalid application |",
+            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `917` | Publication doesn't exists |\n| `935` | Invalid publication |\n| `940` | X (Twitter) credits exhausted. Deleting the tweet on X could not be charged. Response data: { used, limit }. |\n| `966` | The Telegram message is older than 48 hours and the Bot API will not delete it any more. Response data: { published_date, max_hours }. |\n| `969` | The PlanVortex bot is not allowed to delete messages in that Telegram chat. Response data: { chat_id }. |\n| `523` | Invalid application |",
             "content": {
               "application/json": {
                 "schema": {
@@ -9102,7 +9103,7 @@
     "schemas": {
       "Account": {
         "type": "object",
-        "description": "A social account connected to an organization.\n\nOn `discord` an account is a **channel**, not a profile: publishing to two channels of the same server costs two accounts of the plan.\n\n`error_code` other than `0` means the connection is broken — an expired token, a permission taken away — and the account has to be connected again.",
+        "description": "A social account connected to an organization.\n\nOn `discord` and on `telegram` an account is a **channel**, not a profile: publishing to two Discord channels of the same server — or to two Telegram channels of the same brand — costs two accounts of the plan.\n\n`error_code` other than `0` means the connection is broken — an expired token, a permission taken away — and the account has to be connected again. On `telegram` nothing expires, because there is no account token: what breaks the connection is the bot being removed from the channel or losing its permission to post there (error 968).",
         "required": [
           "_id",
           "id_organization",
@@ -9129,7 +9130,7 @@
           },
           "username": {
             "type": "string",
-            "description": "The handle, when the network has one. Absent on the networks that do not (a Discord channel, a WhatsApp number, a Google Business listing)."
+            "description": "The handle, when the network has one. Absent on the networks that do not (a Discord channel, a WhatsApp number, a Google Business listing) and on a **private** Telegram channel, which has no `@name` at all — only public ones do. That is also why a private channel's publications come back with no `url`."
           },
           "social_network": {
             "allOf": [
@@ -9153,7 +9154,7 @@
           },
           "followers_count": {
             "type": "integer",
-            "description": "Followers the network reports. Absent on an account that has never been measured."
+            "description": "Followers the network reports. Absent on an account that has never been measured. On `telegram` it is the channel's member count, and it is the **only** audience figure that network publishes: there are no views, no impressions and no reach anywhere in the Bot API."
           },
           "next_stats_update": {
             "type": "string",
@@ -9354,15 +9355,16 @@
         "required": [
           "type"
         ],
-        "description": "**How** an account of this network is authorized, which is not always \"send the user to this URL\".\n\nNine of the ten networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. **WhatsApp is not.** Its sign-up is Meta's *Embedded Signup*: a popup raised by the Facebook JavaScript SDK from your own page, which returns — over `postMessage` — session data (`waba_id`, `phone_number_id`) that no query string carries. Its `link` is therefore an empty string.\n\nBranch on `authorization.type`, never on whether `link` is empty.",
+        "description": "**How** an account of this network is authorized, which is not always \"send the user to this URL\".\n\nNine of the eleven networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:\n\n• **WhatsApp.** Its sign-up is Meta's *Embedded Signup*: a popup raised by the Facebook JavaScript SDK from your own page, which returns — over `postMessage` — session data (`waba_id`, `phone_number_id`) that no query string carries. Its `link` is therefore an empty string.\n• **Telegram.** There is no OAuth here: no consent screen, no `code`, no account token. `link` opens a private chat with the PlanVortex bot, the person then adds that bot to their channel, and **the account is created from that event**, not from any request of yours. Which means the connection cannot be finished by calling `GET /organizations/{id_organization}/account-connect/telegram` — see that endpoint.\n\nBranch on `authorization.type`, never on whether `link` is empty.",
         "properties": {
           "type": {
             "type": "string",
             "enum": [
               "redirect",
-              "meta_embedded_signup"
+              "meta_embedded_signup",
+              "telegram_bot"
             ],
-            "description": "`redirect`: send the user to `link`. `meta_embedded_signup`: open the Meta popup with the fields below."
+            "description": "`redirect`: send the user to `link`. `meta_embedded_signup`: open the Meta popup with the fields below. `telegram_bot`: open `link` in another tab and wait for the account to show up."
           },
           "app_id": {
             "type": "string",
@@ -9383,6 +9385,14 @@
           "session_info_version": {
             "type": "string",
             "description": "`meta_embedded_signup` only. Goes to `extras.sessionInfoVersion`."
+          },
+          "bot_username": {
+            "type": "string",
+            "description": "`telegram_bot` only. The bot's `@name`, **without the at sign**. Published here so you never have to write it by hand: it is the name the person will see in Telegram, and it changes with the deployment."
+          },
+          "add_to_group_link": {
+            "type": "string",
+            "description": "`telegram_bot` only. The **second** step, and it does not follow from the first: `link` opens the list of channels and this one opens the list of groups. It adds the bot to the channel's linked discussion group, which is what turns comments on — a Telegram channel with no discussion group has no comment inbox at all (error 965). Optional for the user: publishing and statistics work without it."
           }
         }
       },
@@ -9400,7 +9410,7 @@
                 },
                 "link": {
                   "type": "string",
-                  "description": "The network's authorization URL. Send the user there. **Empty when `authorization.type` is not `redirect`** — WhatsApp has no URL to give."
+                  "description": "The network's authorization URL. Send the user there. **Empty when `authorization.type` is `meta_embedded_signup`** — WhatsApp has no URL to give at all.\n\nOn `telegram_bot` it is filled in, and it still is not somewhere to redirect: it opens a Telegram chat, not an authorization screen. Open it in another tab."
                 },
                 "authorization": {
                   "$ref": "#/components/schemas/AccountsSocialAuthorizationMethod"
@@ -10039,7 +10049,7 @@
                 "$ref": "#/components/schemas/CatalogSocialLimitsMap"
               }
             ],
-            "description": "Maximum length of a publication's text. Bluesky counts graphemes, everyone else counts characters."
+            "description": "Maximum length of a publication's text. Bluesky counts graphemes, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit.\n\nOn Telegram there are **two numbers for the same field**: `telegram` (4.096) while the publication is text only, and `telegram_media` (1.024) the moment it carries an image or a video, because then the text is a media caption and not a message. Switch the counter when the file is attached, not when publish is pressed."
           },
           "max_post_bytes": {
             "allOf": [
@@ -10102,7 +10112,7 @@
       },
       "CatalogSocialLimitsMap": {
         "type": "object",
-        "description": "One number per network. Every network in `/social_networks` is present.",
+        "description": "One number per network. Every network in `/social_networks` is present.\n\n**And a few keys are not a network.** Some limits depend on the *kind* of publication rather than on the network alone, and those get a compound key next to the plain one: `instagram_story`, `facebook_reel`, `telegram_media`. Read the plain key by default and the compound one when it applies.",
         "additionalProperties": {
           "type": "integer"
         }
@@ -10637,11 +10647,11 @@
           },
           "publication_external_id": {
             "type": "string",
-            "description": "What the comment hangs off, on the network: the post/video id in five networks, and the **listing** (`locations/{id}`) for a Google Business review."
+            "description": "What the comment hangs off, on the network: the post/video id in most networks, the **listing** (`locations/{id}`) for a Google Business review, and the published message's id on Telegram — where the thread that holds the comments *is* the forwarded post."
           },
           "external_id": {
             "type": "string",
-            "description": "The comment's id on the network. Unique per account, and what makes repeated webhook deliveries idempotent.\n\nOne exception worth knowing: a Google Business reply has no id of its own — it is a *field* of the review — so PlanVortex fabricates a stable one, `{reviewId}/reply`."
+            "description": "The comment's id on the network. Unique per account, and what makes repeated webhook deliveries idempotent.\n\nTwo exceptions worth knowing, and both are composite ids you should treat as opaque:\n\n• A Google Business reply has no id of its own — it is a *field* of the review — so PlanVortex fabricates a stable one, `{reviewId}/reply`.\n• A Telegram comment lives in a **different chat** from the post it answers (the channel's linked discussion group), so it needs two ids at once and travels as `{thread}/{message}`: replying wants the first, deleting wants the second."
           },
           "parent_external_id": {
             "type": "string",
@@ -10781,7 +10791,8 @@
           "youtube",
           "google_business",
           "bluesky",
-          "discord"
+          "discord",
+          "telegram"
         ]
       },
       "CommentsCommentThread": {
@@ -10884,7 +10895,7 @@
         "properties": {
           "field": {
             "type": "string",
-            "description": "What kind of change this is. **Treat it as an open list** and ignore what you do not handle: it grows with the product.\n\n- `new_account` / `change_state_account`: an account was connected, or its state changed — it stopped working, its token was refreshed, it was disconnected.\n- `messages`: a message came in. It travels in `messageObj`.\n- `messaging_postbacks`: the contact pressed a button or a quick reply. Also in `messageObj`.\n- `messaging_seen`: the contact read the conversation. `messageObj` carries the message they read, when we still have it.\n- `messaging_error`: the network refused a message we sent. The reason is in `messageObj.message_errors`.\n- `comments`: a comment came in. It travels in `commentObj`, never in `messageObj`.",
+            "description": "What kind of change this is. **Treat it as an open list** and ignore what you do not handle: it grows with the product.\n\n- `new_account` / `change_state_account`: an account was connected, or its state changed — it stopped working, its token was refreshed, it was disconnected. On `telegram` this is the **only** way to hear about a connection: there is no callback there, so no request of yours ever returns that account.\n- `messages`: a message came in. It travels in `messageObj`.\n- `messaging_postbacks`: the contact pressed a button or a quick reply. Also in `messageObj`.\n- `messaging_seen`: the contact read the conversation. `messageObj` carries the message they read, when we still have it.\n- `messaging_error`: the network refused a message we sent. The reason is in `messageObj.message_errors`.\n- `comments`: a comment came in. It travels in `commentObj`, never in `messageObj`.",
             "enum": [
               "new_account",
               "change_state_account",
@@ -13200,13 +13211,18 @@
             "type": "integer",
             "description": "Manual retries already spent on a failed publication, against the `max_retries` published by `GET /publication_limits`. Only `POST .../retry` increases it; updating the publication resets it to 0."
           },
+          "extra_data": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "What one network needs to remember about **this** publication and that has no common field. Absent on a publication whose network needs nothing, which is almost all of them.\n\nToday only `telegram` writes here, and only `telegram_message_ids`: the ids of every message an album turned into, because deleting the album means deleting all of them."
+          },
           "external_identifier": {
             "type": "string",
-            "description": "The network's own identifier, once published."
+            "description": "The network's own identifier, once published. On `telegram` an album is one publication that is **several messages**, and this holds the first one; the rest travel in `extra_data.telegram_message_ids`."
           },
           "url": {
             "type": "string",
-            "description": "Link to the publication on the network, when there is one."
+            "description": "Link to the publication on the network, when there is one. A **private** Telegram channel has no public URL, so it comes back empty even though the post went out."
           },
           "statistics": {
             "$ref": "#/components/schemas/PublicationStats"
@@ -13244,7 +13260,7 @@
       },
       "PublicationStats": {
         "type": "object",
-        "description": "Raw, per-network metrics for a publication. Only the fields that belong to the publication's own social network are returned.\n\n**An absent field is not a zero.** A field is present only when the network actually reported it; `0` means the network measured zero. This matters most on X (Twitter), where metrics are split into groups with different access levels: `public_metrics` (likes, replys, retwets, quotes, bookmarks, impressions) is always available, while clicks, the pre-computed `engagement` and the video playback quartiles come from X's non-public metrics — only for your own posts, within 30 days of publishing, and only if the app is entitled to them. When they are unavailable they are omitted rather than returned as `0`. Do not default missing fields to zero when displaying them.\n\nOn `discord` there are only two: `likes` (the reactions on the message) and `comments` (the messages in its thread). There is no impressions figure anywhere in Discord's API, so engagement is computed over the server's member count.\n\nOn `bluesky` there are no impressions and no reach either — only the public counters — so engagement is computed over followers.",
+        "description": "Raw, per-network metrics for a publication. Only the fields that belong to the publication's own social network are returned.\n\n**An absent field is not a zero.** A field is present only when the network actually reported it; `0` means the network measured zero. This matters most on X (Twitter), where metrics are split into groups with different access levels: `public_metrics` (likes, replys, retwets, quotes, bookmarks, impressions) is always available, while clicks, the pre-computed `engagement` and the video playback quartiles come from X's non-public metrics — only for your own posts, within 30 days of publishing, and only if the app is entitled to them. When they are unavailable they are omitted rather than returned as `0`. Do not default missing fields to zero when displaying them.\n\nOn `discord` there are only two: `likes` (the reactions on the message) and `comments` (the messages in its thread). There is no impressions figure anywhere in Discord's API, so engagement is computed over the server's member count.\n\nOn `bluesky` there are no impressions and no reach either — only the public counters — so engagement is computed over followers.\n\nOn `telegram` there are two as well, and **neither of them is asked for**: the Bot API has no method that returns a message's metrics, so `reactions` arrives on its own through the bot and `comments` is counted in PlanVortex's own inbox. There are no impressions, no reach, no views and no forwards to be had anywhere in it, so engagement is computed over followers.",
         "properties": {
           "likes": {
             "type": "integer"
@@ -13353,6 +13369,17 @@
           },
           "views": {
             "type": "integer"
+          },
+          "reactions": {
+            "type": "integer",
+            "description": "Telegram. Every reaction on the post, all emoji together. It is the **complete state and not an increment**: it goes down when somebody takes theirs back. Normalised as `likes`."
+          },
+          "reactions_by_emoji": {
+            "type": "object",
+            "additionalProperties": {
+              "type": "integer"
+            },
+            "description": "Telegram. The same total broken down by emoji. Reactions with a custom emoji are grouped under a single key: their identifier means nothing outside the server that created it."
           }
         }
       },
@@ -13371,13 +13398,14 @@
               "whatsapp",
               "youtube",
               "bluesky",
-              "discord"
+              "discord",
+              "telegram"
             ],
             "description": "Network the publication targets. **Required when creating**: the request fails with error 702 if it is missing or not one of these values. It must match the network of the account in the path.\n\nNot every connectable network publishes — a local business listing receives reviews, not posts — so this list is shorter than the one in `GET /social_networks`. Ask `GET /allowed_social_publications` rather than hardcoding it, because it grows."
           },
           "text": {
             "type": "string",
-            "description": "Body text of the publication. Either `text` or at least one entry in `files` is required: if both are empty the publication is still created, but in state `withErrors` with `publication_errors[].code = 915`. Maximum length depends on the network. On YouTube this is the video **description** (5,000 characters), and the publication must carry exactly one video file and no images — otherwise it is created in state `withErrors` with `publication_errors[].code = 943`. For X (Twitter), a text containing a link costs 200 credits instead of 15."
+            "description": "Body text of the publication. Either `text` or at least one entry in `files` is required: if both are empty the publication is still created, but in state `withErrors` with `publication_errors[].code = 915`. Maximum length depends on the network. On YouTube this is the video **description** (5,000 characters), and the publication must carry exactly one video file and no images — otherwise it is created in state `withErrors` with `publication_errors[].code = 943`. For X (Twitter), a text containing a link costs 200 credits instead of 15.\n\n**On Telegram the limit depends on what else the publication carries**: 4.096 characters while it is text only, and **1.024** the moment it has an image or a video, because then the text is the caption of a photo, a video or an album and no longer a message. Over the limit it is created in state `withErrors` with `publication_errors[].code = 967`, whose `data` carries `characters`, `max_characters` and `has_media`. Both numbers are published, as `characters.telegram` and `characters.telegram_media` in `GET /social_limits`."
           },
           "title": {
             "type": "string",
@@ -13713,7 +13741,8 @@
           "youtube",
           "google_business",
           "bluesky",
-          "discord"
+          "discord",
+          "telegram"
         ],
         "type": "string",
         "description": "A social network supported by PlanVortex.\n\n**This list grows.** Treat it as an open enumeration: a client that rejects an unknown value breaks the day a network is added, which happens several times a year. Not every network does everything — ask `GET /social_capabilities`."
@@ -14270,7 +14299,7 @@
         }
       },
       "CommentsCommentError": {
-        "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `516` | Comments require a paid plan. Every endpoint here returns this on the free plan. |\n| `700` | The account is not connected — no valid token, or nothing to ask the network about. |\n| `936` | The publication was never sent, so it has no thread to read. |\n| `940` | The client's monthly X credits are exhausted. Only X. |\n| `945` | This network has no comments (TikTok, WhatsApp). Carries `social_network` in `data`. |\n| `946` | The network has comments but does not allow **this action**: hiding on LinkedIn or Google Business, deleting someone else's on Instagram or X, deleting a review. Carries `social_network` and `action` in `data`. See `GET /social_comment_actions`. |\n| `947` | The comment no longer exists on the network. What is stored is a photograph; the network always wins. Carries `external_id` in `data`. |\n| `948` | The reply is empty or longer than the network allows. Carries the limit in `data.max`; the same number is published in `comment_characters` of `GET /social_limits`. |\n| `951` | The Google Business listing is not verified, so it cannot reply to its reviews. It is the state of the customer's profile, not of your token. |\n| `952` | PlanVortex's Google Cloud project has no approved access to the Google Business API yet. Until it does, reviews cannot be read or replied to. |\n| `1101` | Invalid organization. |\n| `1501` | The comment's account could not be resolved. |",
+        "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `516` | Comments require a paid plan. Every endpoint here returns this on the free plan. |\n| `700` | The account is not connected — no valid token, or nothing to ask the network about. |\n| `936` | The publication was never sent, so it has no thread to read. |\n| `940` | The client's monthly X credits are exhausted. Only X. |\n| `945` | This network has no comments (TikTok, WhatsApp). Carries `social_network` in `data`. |\n| `946` | The network has comments but does not allow **this action**: hiding on LinkedIn or Google Business, deleting someone else's on Instagram or X, deleting a review. Carries `social_network` and `action` in `data`. See `GET /social_comment_actions`. |\n| `947` | The comment no longer exists on the network. What is stored is a photograph; the network always wins. Carries `external_id` in `data`. |\n| `948` | The reply is empty or longer than the network allows. Carries the limit in `data.max`; the same number is published in `comment_characters` of `GET /social_limits`. |\n| `951` | The Google Business listing is not verified, so it cannot reply to its reviews. It is the state of the customer's profile, not of your token. |\n| `952` | PlanVortex's Google Cloud project has no approved access to the Google Business API yet. Until it does, reviews cannot be read or replied to. |\n| `965` | This Telegram channel has no linked discussion group, so it has no comments. The network gate says `true`; what is missing is a setting of **that channel**, which its owner fixes in two taps. Carries `chat_id` in `data`. |\n| `969` | The PlanVortex bot is not allowed to delete messages in this Telegram discussion group. The network allows it; this installation does not. Carries `chat_id` in `data`. |\n| `970` | Telegram is rate limiting the bot and the wait was longer than PlanVortex is willing to hold the request for. Carries `retry_after_seconds` in `data`: retry after it. |\n| `1101` | Invalid organization. |\n| `1501` | The comment's account could not be resolved. |",
         "content": {
           "application/json": {
             "schema": {

{planvortex-0.1.0 → planvortex-0.2.0}/pyproject.toml

@@ -9,7 +9,7 @@ name = "planvortex"
 # entonces `project.version` desapareceria del pyproject y el paso del workflow de release que
 # compara el tag con la version —que lo lee con `tomllib`— dejaria de encontrarla. Se quedan las dos
 # y las ata `tests/test_packaging.py`, que falla si se separan.
-version = "0.1.0"
+version = "0.2.0"
 description = "Official Python client for the PlanVortex API"
 readme = "README.md"
 requires-python = ">=3.10"