planvortex 0.4.0__tar.gz → 0.6.0__tar.gz

{planvortex-0.4.0 → planvortex-0.6.0}/CHANGELOG.md

@@ -4,6 +4,66 @@ 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.6.0] - 2026-09-03
+
+**Publications are unlimited on every plan**, so the quota that said otherwise is gone from the
+types.
+
+It was never a number this package invented: `PlanData["publications"]` came from the spec, and the
+server stopped charging for it on 02-09-2026. What stayed behind was worse than a wrong number — it
+was a key mypy kept promising, so `limits["publications"]` type-checked and raised `KeyError` at
+runtime.
+
+### Changed
+
+- **BREAKING (types only): `PlanData` no longer has a `publications` key.** The count moved to the
+  new `PlanUseData`, which is what `actual_use` has always been in practice: the same shape as a
+  plan plus `publications`, and `NotRequired` because a brand-new organization has spent nothing.
+  Nothing changes on the wire.
+- `OrganizationUse["actual_use"]` is a `PlanUseData`; `actual_asigned` stays a `PlanData`, which is
+  the real asymmetry: what a child organization was handed cannot include a metric.
+- The `publish` example prints publications as what they are — a monthly count with no ceiling —
+  instead of `12 de 100`. What throttles publishing is rate (per hour and account, and the
+  per-network daily caps in `GET /social_limits`), not the plan.
+- **The `publication` error family now reaches 979, not 960.** Everything above the old ceiling was
+  falling outside every range and arriving as a bare `PlanVortexError`: the Bluesky, Discord,
+  Telegram and Threads codes (961-977) and, more to the point, the two rate brakes that replaced the
+  monthly quota — **978** (publishing too fast on this account) and **979** (that network's daily
+  cap). `except PublicationError` now catches them.
+
+### Added
+
+**The public API is on every plan now, the free one included** — it used to be a Custom-plan
+feature — and the types follow the three things that came with opening it.
+
+- `PlanData["apps"]`: how many apps the plan allows (1 on Free, 2 on Basic, 5 on Pro, 10 on Custom).
+  Each app is a `client_id` with a secret, so each one is a key to the whole API. Unlike accounts,
+  users or storage it is **not** split between organizations — an app belongs to the client.
+- Three error codes, and the two ranges that were hiding them: **545** (the plan's API rate limit,
+  which arrives as a `429` with `Retry-After`) and **546** (the account's email must be verified to
+  create an app) are `AuthError`, so that range now runs to 546; **1308** (no more apps fit in this
+  plan) is a `PlanLimitError`, so that one runs to 1308.
+
+## [0.5.0] - 2026-09-02
+
+**Threads is the twelfth network**, and the types now know it.
+
+Nothing here removes anything: `SocialNetwork` gains a value, `PublishableNetwork` gains another,
+and everything that type-checked before type-checks now. What was wrong until today was quieter than
+an error — the committed copy of the spec predated Threads, so an account coming back from a real
+API arrived with a `social_network` no `Literal` had ever heard of, and the prose still counted
+eleven networks where the API had twelve.
+
+### Changed
+
+- The OpenAPI copy and the generated models are rebuilt from the published document, so `threads`
+  is a `SocialNetwork`, a `CommentNetwork` and a publishable network.
+- `PublishableNetwork` — hand-maintained, because generating it is not possible — includes
+  `threads`: **eleven of the twelve** networks have a feed, and `google_business` is still the one
+  that does not.
+- The prose that counts networks: a connection link is a `redirect` on **ten of the twelve**, not
+  nine of eleven. WhatsApp and Telegram are still the two that are not.
+
 ## [0.4.0] - 2026-08-31
 
 An AI plan can now be **archived**, and deleting one finally means what people thought it meant.

{planvortex-0.4.0 → planvortex-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.4.0
+Version: 0.6.0
 Summary: Official Python client for the PlanVortex API
 Project-URL: Homepage, https://planvortex.com/developers
 Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
@@ -242,15 +242,15 @@ memorising numbers:
 
 | Codes | Family | Exception |
 |---|---|---|
-| 500-544 | `auth` | `AuthError` |
+| 500-546 | `auth` | `AuthError` |
 | 601-612 | `user` | `UserError` |
 | 700-715 | `account` | `AccountError` |
 | 800-810 | `file` | `FileError` |
-| 900-960 | `publication` | `PublicationError` |
+| 900-979 | `publication` | `PublicationError` |
 | 1000-1003 | `general` | `PlanVortexError` |
 | 1100-1111 | `organization` | `OrganizationError` |
 | 1200-1207 | `role` | `PlanVortexError` |
-| 1300-1307, 1400-1408 | `plan_limit` | `PlanLimitError` |
+| 1300-1308, 1400-1408 | `plan_limit` | `PlanLimitError` |
 | 1500-1512 | `messaging` | `MessagingError` |
 | 1600-1601 | `contact` | `ContactError` |
 | 1900-1906 | `payment` | `PlanVortexError` |

{planvortex-0.4.0 → planvortex-0.6.0}/README.md

@@ -212,15 +212,15 @@ memorising numbers:
 
 | Codes | Family | Exception |
 |---|---|---|
-| 500-544 | `auth` | `AuthError` |
+| 500-546 | `auth` | `AuthError` |
 | 601-612 | `user` | `UserError` |
 | 700-715 | `account` | `AccountError` |
 | 800-810 | `file` | `FileError` |
-| 900-960 | `publication` | `PublicationError` |
+| 900-979 | `publication` | `PublicationError` |
 | 1000-1003 | `general` | `PlanVortexError` |
 | 1100-1111 | `organization` | `OrganizationError` |
 | 1200-1207 | `role` | `PlanVortexError` |
-| 1300-1307, 1400-1408 | `plan_limit` | `PlanLimitError` |
+| 1300-1308, 1400-1408 | `plan_limit` | `PlanLimitError` |
 | 1500-1512 | `messaging` | `MessagingError` |
 | 1600-1601 | `contact` | `ContactError` |
 | 1900-1906 | `payment` | `PlanVortexError` |

{planvortex-0.4.0 → planvortex-0.6.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 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.",
+        "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`.** Ten of the twelve 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",
@@ -1872,7 +1872,8 @@
                   "google_business",
                   "bluesky",
                   "discord",
-                  "telegram"
+                  "telegram",
+                  "threads"
                 ]
               }
             }
@@ -2448,7 +2449,6 @@
                     "name": "Client X",
                     "actual_plan": {
                       "accounts": 4,
-                      "publications": 150,
                       "users": 1,
                       "space": 0.25,
                       "integrations": 1,
@@ -2624,7 +2624,6 @@
                   "value": {
                     "actual_plan": {
                       "accounts": 8,
-                      "publications": 300,
                       "users": 3,
                       "space": 1,
                       "integrations": 3,
@@ -3597,7 +3596,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 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.",
+        "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 ten 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",
@@ -4086,7 +4085,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 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.",
+        "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 ten networks answer `comments: true`: Facebook, Instagram, Threads, 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",
@@ -4144,7 +4143,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| `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.",
+        "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| `threads` | yes | yes | yes | **no** — deleting somebody else's reply is not a permission you lack, it is a call that does not exist in the API |\n| `tiktok`, `whatsapp` | no | no | no | no |\n\nOnly needs authentication.",
         "operationId": "getSocialCommentActions",
         "x-planvortex-identity": [
           "current_user",
@@ -6023,7 +6022,6 @@
                   "value": {
                     "actual_plan": {
                       "accounts": 8,
-                      "publications": 300,
                       "users": 3,
                       "space": 1,
                       "integrations": 3,
@@ -6342,7 +6340,6 @@
                     "name": "Client X - Spain",
                     "actual_plan": {
                       "accounts": 3,
-                      "publications": 100,
                       "users": 1,
                       "space": 0.25,
                       "integrations": 0,
@@ -9510,7 +9507,7 @@
         "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 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.",
+        "description": "**How** an account of this network is authorized, which is not always \"send the user to this URL\".\n\nTen of the twelve 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",
@@ -10514,7 +10511,7 @@
                 "$ref": "#/components/schemas/CatalogSocialLimitsMap"
               }
             ],
-            "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."
+            "description": "Maximum length of a publication's text. **Bluesky and Threads count GRAPHEMES**, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit. The difference is not academic: an emoji is one grapheme and two `String.length` units, so counting a Threads post with `.length` rejects at 250 emojis what the network publishes happily at 500.\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": [
@@ -10701,7 +10698,7 @@
           "actual_use": {
             "allOf": [
               {
-                "$ref": "#/components/schemas/PlanData"
+                "$ref": "#/components/schemas/PlanUseData"
               }
             ],
             "description": "Current consumption across every organization of the client. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent this calendar month."
@@ -11257,7 +11254,8 @@
           "google_business",
           "bluesky",
           "discord",
-          "telegram"
+          "telegram",
+          "threads"
         ]
       },
       "CommentsCommentThread": {
@@ -12077,7 +12075,7 @@
           "actual_use": {
             "allOf": [
               {
-                "$ref": "#/components/schemas/PlanData"
+                "$ref": "#/components/schemas/PlanUseData"
               }
             ],
             "description": "What the organization and its children are consuming right now."
@@ -12263,7 +12261,7 @@
           },
           "code": {
             "type": "integer",
-            "description": "PlanVortex error code. Ranges: 500-544 auth, tokens and client apps · 601-612 user · 700-715 social accounts · 800-810 files · 900-960 publications · 1000-1003 general · 1100-1111 organizations · 1200-1207 roles · 1300-1307 client plan · 1400-1408 organization plan · 1500-1512 messaging · 1600-1601 contacts · 1900-1906 payments · 2000-2099 products · 2100-2199 AI plans · 2200-2299 integrations."
+            "description": "PlanVortex error code. Ranges: 500-546 auth, tokens and client apps · 601-612 user · 700-715 social accounts · 800-810 files · 900-979 publications · 1000-1003 general · 1100-1111 organizations · 1200-1207 roles · 1300-1308 client plan · 1400-1408 organization plan · 1500-1512 messaging · 1600-1601 contacts · 1900-1906 payments · 2000-2099 products · 2100-2199 AI plans · 2200-2299 integrations."
           },
           "data": {
             "additionalProperties": true,
@@ -12941,7 +12939,7 @@
           "actual_use": {
             "allOf": [
               {
-                "$ref": "#/components/schemas/PlanData"
+                "$ref": "#/components/schemas/PlanUseData"
               }
             ],
             "description": "Current consumption. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent in the current calendar month; the rest is what exists right now."
@@ -13383,7 +13381,6 @@
         "description": "The resources a plan grants. On a client it is what was contracted; on an organization, the slice of it that was assigned. The sum across all the organizations of a client can never exceed what the client has contracted.",
         "required": [
           "accounts",
-          "publications",
           "users",
           "space",
           "integrations"
@@ -13393,10 +13390,6 @@
             "type": "integer",
             "description": "Social accounts that may be connected."
           },
-          "publications": {
-            "type": "integer",
-            "description": "Publications that may be sent per month."
-          },
           "users": {
             "type": "integer",
             "description": "Users with access."
@@ -13407,7 +13400,11 @@
           },
           "integrations": {
             "type": "integer",
-            "description": "Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it is a Custom-plan feature of its own."
+            "description": "Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`."
+          },
+          "apps": {
+            "type": "integer",
+            "description": "Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts, users or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now."
           },
           "twitter_credits": {
             "type": "integer",
@@ -13431,6 +13428,21 @@
           }
         }
       },
+      "PlanUseData": {
+        "type": "object",
+        "description": "What is being consumed right now. Same shape as PlanData plus `publications`, which is counted but neither charged nor split between organizations.",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/PlanData"
+          }
+        ],
+        "properties": {
+          "publications": {
+            "type": "integer",
+            "description": "Publications created in the current calendar month. A METRIC, not a quota: publications are unlimited on every plan, so there is no limit to compare it against. What throttles publishing is rate, not plan — see the per-hour and per-network daily caps."
+          }
+        }
+      },
       "ProductsProduct": {
         "allOf": [
           {
@@ -13725,7 +13737,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.\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.",
+        "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 `threads` there are six, and the one that matters is `views`: it is the only one of the four newest networks with something like impressions, so its engagement rate is computed over a real base and not over followers. Sharing arrives split in three — `reposts`, `quotes` and `shares` (outside Threads) — and the three are added into one figure, the same criterion as on X; the breakdown stays in `raw`. A reply is what every other network calls a comment.\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"
@@ -13864,7 +13876,8 @@
               "youtube",
               "bluesky",
               "discord",
-              "telegram"
+              "telegram",
+              "threads"
             ],
             "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."
           },
@@ -14207,7 +14220,8 @@
           "google_business",
           "bluesky",
           "discord",
-          "telegram"
+          "telegram",
+          "threads"
         ],
         "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`."

{planvortex-0.4.0 → planvortex-0.6.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.4.0"
+version = "0.6.0"
 description = "Official Python client for the PlanVortex API"
 readme = "README.md"
 requires-python = ">=3.10"

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/_core/errors.py

@@ -27,15 +27,22 @@ class ErrorRange(NamedTuple):
 # Los mismos 16 rangos que publica `swagger/common.json`, `PLANVORTEX_ERROR_RANGES` del paquete de
 # Node y el apendice A del roadmap. SI SE TOCA UN RANGO, SE TOCAN LOS CINCO SITIOS.
 PLANVORTEX_ERROR_RANGES: tuple[ErrorRange, ...] = (
-    ErrorRange(500, 544, "auth"),
+    # Hasta 546, no 544: la API publica se abrio a todos los planes y trajo dos codigos nuevos
+    # —545 (ritmo por plan, que sale 429) y 546 (correo sin verificar al crear una app)—.
+    ErrorRange(500, 546, "auth"),
     ErrorRange(601, 612, "user"),
     ErrorRange(700, 715, "account"),
     ErrorRange(800, 810, "file"),
-    ErrorRange(900, 960, "publication"),
+    # El techo sube con el catalogo del servidor, y subir tarde no da un error: da un consejo
+    # equivocado. Los codigos de Bluesky, Discord, Telegram y Threads (961-977) y los dos frenos
+    # de ritmo de la fase de publicaciones ilimitadas (978, 979) nacieron por encima de 960 y
+    # caian fuera de toda familia.
+    ErrorRange(900, 979, "publication"),
     ErrorRange(1000, 1003, "general"),
     ErrorRange(1100, 1111, "organization"),
     ErrorRange(1200, 1207, "role"),
-    ErrorRange(1300, 1307, "plan_limit"),
+    # 1308 es el tope de APPS del plan, que nacio al quitar el candado de precio de la API.
+    ErrorRange(1300, 1308, "plan_limit"),
     ErrorRange(1400, 1408, "plan_limit"),
     ErrorRange(1500, 1512, "messaging"),
     ErrorRange(1600, 1601, "contact"),
@@ -101,7 +108,7 @@ class PlanVortexError(Exception):
 
 
 class AuthError(PlanVortexError):
-    """500-544 — tokens, client apps, permissions. Includes 501 and 522, the expired-token ones."""
+    """500-546 — tokens, client apps, permissions. Includes 501 and 522, the expired-token ones."""
 
 
 class UserError(PlanVortexError):
@@ -117,7 +124,9 @@ class FileError(PlanVortexError):
 
 
 class PublicationError(PlanVortexError):
-    """900-960 — publications, including per-network limits (characters, images, duration)."""
+    """900-979 — publications, including per-network limits (characters, images, duration) and the
+    two rate brakes: 978 (publishing too fast on this account) and 979 (that network's daily cap).
+    """
 
 
 class OrganizationError(PlanVortexError):
@@ -125,7 +134,7 @@ class OrganizationError(PlanVortexError):
 
 
 class PlanLimitError(PlanVortexError):
-    """1300-1307 and 1400-1408 — the plan's quota, on the client or on the organization.
+    """1300-1308 and 1400-1408 — the plan's quota, on the client or on the organization.
 
     This is the error an integrator actually wants to tell apart: it is not fixed by retrying, it is
     fixed by changing plan. That is why both ranges share a class.

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/_generated/models.py

@@ -137,7 +137,7 @@ class AccountsSocialAuthorizationMethod(TypedDict):
     """
     **How** an account of this network is authorized, which is not always "send the user to this URL".
 
-    Nine of the eleven networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:
+    Ten of the twelve networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:
 
     • **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.
     • **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.
@@ -855,6 +855,7 @@ CommentsCommentNetworkName: TypeAlias = Literal[
     "bluesky",
     "discord",
     "telegram",
+    "threads",
 ]
 """
 A network that has comments. Treat it as an open list: a new one is added before your integration hears about it.
@@ -1071,7 +1072,7 @@ class Error1(TypedDict):
     """
     code: int
     """
-    PlanVortex error code. Ranges: 500-544 auth, tokens and client apps · 601-612 user · 700-715 social accounts · 800-810 files · 900-960 publications · 1000-1003 general · 1100-1111 organizations · 1200-1207 roles · 1300-1307 client plan · 1400-1408 organization plan · 1500-1512 messaging · 1600-1601 contacts · 1900-1906 payments · 2000-2099 products · 2100-2199 AI plans · 2200-2299 integrations.
+    PlanVortex error code. Ranges: 500-546 auth, tokens and client apps · 601-612 user · 700-715 social accounts · 800-810 files · 900-979 publications · 1000-1003 general · 1100-1111 organizations · 1200-1207 roles · 1300-1308 client plan · 1400-1408 organization plan · 1500-1512 messaging · 1600-1601 contacts · 1900-1906 payments · 2000-2099 products · 2100-2199 AI plans · 2200-2299 integrations.
     """
     data: NotRequired[dict[str, Any]]
     """
@@ -1552,10 +1553,6 @@ class PlanData(TypedDict):
     """
     Social accounts that may be connected.
     """
-    publications: int
-    """
-    Publications that may be sent per month.
-    """
     users: int
     """
     Users with access.
@@ -1566,7 +1563,11 @@ class PlanData(TypedDict):
     """
     integrations: int
     """
-    Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it is a Custom-plan feature of its own.
+    Connections to a third-party tool material is pulled from (Google Drive, an RSS feed). Not the same thing as an app: an app is API access, and it has its own allowance in `apps`.
+    """
+    apps: NotRequired[int]
+    """
+    Apps this plan allows: 1 on Free, 2 on Basic, 5 on Pro, 10 on Custom. Each one is a `client_id` with a secret, so each one is a key to the whole public API — which every plan has, Free included. Unlike accounts, users or storage this is NOT split between organizations: an app belongs to the client. On a use payload it is how many exist right now.
     """
     twitter_credits: NotRequired[int]
     """
@@ -1590,6 +1591,17 @@ class PlanData(TypedDict):
     """
 
 
+class PlanUseData(PlanData):
+    """
+    What is being consumed right now. Same shape as PlanData plus `publications`, which is counted but neither charged nor split between organizations.
+    """
+
+    publications: NotRequired[int]
+    """
+    Publications created in the current calendar month. A METRIC, not a quota: publications are unlimited on every plan, so there is no limit to compare it against. What throttles publishing is rate, not plan — see the per-hour and per-network daily caps.
+    """
+
+
 class ProductsProductCatalog(TypedDict):
     """
     A Meta commerce catalogue, as the network returns it.
@@ -1668,6 +1680,8 @@ class PublicationStats(TypedDict):
 
     On `bluesky` there are no impressions and no reach either — only the public counters — so engagement is computed over followers.
 
+    On `threads` there are six, and the one that matters is `views`: it is the only one of the four newest networks with something like impressions, so its engagement rate is computed over a real base and not over followers. Sharing arrives split in three — `reposts`, `quotes` and `shares` (outside Threads) — and the three are added into one figure, the same criterion as on X; the breakdown stays in `raw`. A reply is what every other network calls a comment.
+
     On `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.
     """
 
@@ -1758,6 +1772,7 @@ class PublicationsPublicationInput(TypedDict):
             "bluesky",
             "discord",
             "telegram",
+            "threads",
         ]
     ]
     """
@@ -1907,6 +1922,7 @@ SocialNetwork: TypeAlias = Literal[
     "bluesky",
     "discord",
     "telegram",
+    "threads",
 ]
 """
 A social network supported by PlanVortex.
@@ -2175,7 +2191,7 @@ class CatalogPlannerTemplate(TypedDict):
 class CatalogSocialLimits(TypedDict):
     characters: CatalogSocialLimitsMap
     """
-    Maximum length of a publication's text. Bluesky counts graphemes, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit.
+    Maximum length of a publication's text. **Bluesky and Threads count GRAPHEMES**, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit. The difference is not academic: an emoji is one grapheme and two `String.length` units, so counting a Threads post with `.length` rejects at 250 emojis what the network publishes happily at 500.
 
     On 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.
     """
@@ -2394,7 +2410,7 @@ class DashboardDashboardPublicationRef(TypedDict):
 
 
 class DashboardPlanUse(TypedDict):
-    actual_use: PlanData
+    actual_use: PlanUseData
     """
     What the organization and its children are consuming right now.
     """
@@ -2636,7 +2652,7 @@ class Organization(TypedDict):
     """
     The slice of the client's plan assigned to this organization. **Absent when nothing was assigned**, and then the organization shares whatever its nearest parent with a plan has — or, failing that, the client's unassigned remainder. Ask `GET /organizations/{id_organization}/limits` for the effective numbers instead of reading this.
     """
-    actual_use: NotRequired[PlanData]
+    actual_use: NotRequired[PlanUseData]
     """
     Current consumption. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent in the current calendar month; the rest is what exists right now.
     """
@@ -2952,7 +2968,7 @@ class ClientsClient(TypedDict):
     """
     Read-only view of the client's own AI provider configuration (BYOK). Written via `PUT /clients/{id_client}/ai-settings`. API keys are stored encrypted and are NEVER returned: each scope only exposes provider, model and has_api_key.
     """
-    actual_use: NotRequired[PlanData]
+    actual_use: NotRequired[PlanUseData]
     """
     Current consumption across every organization of the client. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent this calendar month.
     """

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/_shapes.py

@@ -31,6 +31,7 @@ from planvortex._generated.models import (
     DashboardPublicationsSummary,
     Organization,
     PlanData,
+    PlanUseData,
     Publication,
     Upload,
 )
@@ -118,7 +119,7 @@ class OrganizationUse(TypedDict):
     with ``get_use=True``.
     """
 
-    actual_use: NotRequired[PlanData]
+    actual_use: NotRequired[PlanUseData]
     actual_asigned: NotRequired[PlanData]
 
 
@@ -137,7 +138,7 @@ class AccountUpdate(TypedDict):
 
 
 class RedirectAuthorization(TypedDict):
-    """Send the person to the entry's ``link``. Nine of the eleven networks.
+    """Send the person to the entry's ``link``. Ten of the twelve networks.
 
     One of the THREE halves of the ``authorization`` block of a connection link. The generated type
     is a single flat ``TypedDict`` with every field ``NotRequired``, because that is the only way
@@ -255,6 +256,7 @@ class EnableResult(TypedDict):
 PublishableNetwork: TypeAlias = Literal[
     "facebook",
     "instagram",
+    "threads",
     "twitter",
     "linkedin",
     "tiktok",
@@ -264,12 +266,12 @@ PublishableNetwork: TypeAlias = Literal[
     "discord",
     "telegram",
 ]
-"""A network that accepts publications: the ten of the eleven that have a feed.
+"""A network that accepts publications: the eleven of the twelve that have a feed.
 
 ``google_business`` is the one missing, and it is not an oversight: a local listing receives
 reviews, not posts. Sending it raises error 702. It is a **narrower** type than
 ``types.SocialNetwork`` and that is the whole point — an account's ``social_network`` is one of
-eleven and this is one of ten, so handing one straight to the other is a type error even when a
+twelve and this is one of eleven, so handing one straight to the other is a type error even when a
 ``capability="publications"`` filter has already made it impossible at runtime.
 ``types.is_publishable_network`` is what bridges it.
 

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/_version.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import platform
 
-VERSION = "0.4.0"
+VERSION = "0.6.0"
 
 # Sin barra final, y con el `/v1.0.0` dentro: la version de la API es parte de la ruta, no una
 # cabecera, asi que una `base_url` sin ella da 404 en todo.

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/resources/accounts.py

@@ -56,7 +56,7 @@ class AsyncAccountsResource(AsyncResource):
         rather than a failure: it is what happens to Discord in an organization that has not saved
         its own bot credentials yet.
 
-        **LOOK AT ``authorization``, NOT AT WHETHER ``link`` IS EMPTY.** Nine of the eleven networks
+        **LOOK AT ``authorization``, NOT AT WHETHER ``link`` IS EMPTY.** Ten of the twelve networks
         are ``redirect`` and the person is sent to ``link``. The other two are not, and neither of them
         fails visibly if you walk the list redirecting to ``link``:
 

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/resources_sync/accounts.py

@@ -49,7 +49,7 @@ class AccountsResource(Resource):
         rather than a failure: it is what happens to Discord in an organization that has not saved
         its own bot credentials yet.
 
-        **LOOK AT ``authorization``, NOT AT WHETHER ``link`` IS EMPTY.** Nine of the eleven networks
+        **LOOK AT ``authorization``, NOT AT WHETHER ``link`` IS EMPTY.** Ten of the twelve networks
         are ``redirect`` and the person is sent to ``link``. The other two are not, and neither of them
         fails visibly if you walk the list redirecting to ``link``:
 

{planvortex-0.4.0 → planvortex-0.6.0}/src/planvortex/types.py

@@ -289,6 +289,18 @@ CAREFUL WITH THE SUM: what is assigned to a client's organizations can never exc
 has contracted — asking for more comes back as a 1400-1408.
 """
 
+PlanUseData: TypeAlias = _models.PlanUseData
+"""What is being CONSUMED right now: a :data:`PlanData` plus ``publications``.
+
+``publications`` is a METRIC, not a quota — publications are unlimited on every plan — so there is
+no ceiling to compare it against: do not draw it as a bar. What throttles whoever publishes too
+much is RATE (a per-hour cap per account, and the per-network daily caps in ``GET /social_limits``),
+not the plan.
+
+Not to be confused with :data:`PlanUse`, which is the dashboard's whole block: consumption, what
+was handed down, and the limits together.
+"""
+
 Organization: TypeAlias = _models.Organization
 """An organization: the container of accounts, publications and files. They nest.
 
@@ -502,7 +514,7 @@ for whoever is in Docker.
 
 That ``datetime`` is why this is the one shape written by hand on top of the generated type: OpenAPI
 has a ``string`` with ``format: date-time`` and no way to say "or the language's own date". Its
-``social_network`` is :data:`PublishableNetwork`, which is **nine** networks and not ten.
+``social_network`` is :data:`PublishableNetwork`, which is **eleven** networks and not twelve.
 """
 
 PublicationErrorDetail: TypeAlias = _models.PublicationError
@@ -1115,6 +1127,7 @@ __all__ = [
     "PersistentMenu",
     "PlanData",
     "PlanUse",
+    "PlanUseData",
     "PlannerTemplate",
     "PlannerTemplateField",
     "PlannerTemplateFieldType",

{planvortex-0.4.0 → planvortex-0.6.0}/tests/test_core.py

@@ -305,7 +305,19 @@ def test_cada_rango_del_catalogo_cae_en_su_clase() -> None:
     """
     assert error_class_for_code(500) is error_class_for_code(544)
     assert error_class_for_code(900).__name__ == "PublicationError"
+    # El rango llega hasta 979, no hasta 960: por encima del 960 estan las cuatro ultimas redes
+    # (Bluesky, Discord, Telegram y Threads) y los DOS FRENOS DE RITMO que sustituyeron al cupo
+    # mensual de publicaciones. Fuera de familia, el 978 llegaba como un error generico y quien lo
+    # recibia no tenia forma de saber que la respuesta es esperar.
+    assert error_class_for_code(975).__name__ == "PublicationError"
+    assert error_class_for_code(978).__name__ == "PublicationError"
+    assert error_class_for_code(979).__name__ == "PublicationError"
     assert error_class_for_code(1300).__name__ == "PlanLimitError"
+    # 1308 es el tope de APPS del plan, y 545/546 los dos codigos que trajo abrir la API publica
+    # a todos los planes. Los tres nacieron por encima del techo que tenian sus rangos.
+    assert error_class_for_code(1308).__name__ == "PlanLimitError"
+    assert error_class_for_code(545).__name__ == "AuthError"
+    assert error_class_for_code(546).__name__ == "AuthError"
     assert error_class_for_code(1408).__name__ == "PlanLimitError"
     assert error_class_for_code(2299).__name__ == "IntegrationError"
     # Los siete de las plantillas del planificador. No hay nada que registrar para que caigan aqui:

{planvortex-0.4.0 → planvortex-0.6.0}/tests/test_example_connect.py

@@ -92,7 +92,7 @@ def _camino(
         url=f"{BASE_URL}/clients/cli1/organizations?limit=1",
         json={"organizations": [ORGANIZACION], "total": 1},
     )
-    httpx_mock.add_response(url=f"{ORG}/limits", json={"accounts": 5, "publications": 100})
+    httpx_mock.add_response(url=f"{ORG}/limits", json={"accounts": 5, "users": 3})
     httpx_mock.add_response(
         url=f"{ORG}?getUse=true",
         json={

{planvortex-0.4.0 → planvortex-0.6.0}/tests/test_example_publish.py

@@ -77,7 +77,7 @@ def _camino(httpx_mock: HTTPXMock, *, publicacion: dict[str, Any] | None = None)
         url=f"{BASE_URL}/clients/cli1/organizations?limit=1",
         json={"organizations": [ORGANIZACION], "total": 1},
     )
-    httpx_mock.add_response(url=f"{ORG}/limits", json={"accounts": 5, "publications": 100})
+    httpx_mock.add_response(url=f"{ORG}/limits", json={"accounts": 5, "users": 3})
     httpx_mock.add_response(
         url=f"{ORG}?getUse=true",
         json={"organization": {**ORGANIZACION, "actual_use": {"accounts": 1, "publications": 12}}},

{planvortex-0.4.0 → planvortex-0.6.0}/tests/test_organizations.py

@@ -73,9 +73,9 @@ def test_las_hijas_se_listan_se_iteran_y_se_crean(cliente: ClienteDePrueba, http
 
 def test_limits_llega_sin_sobre(cliente: ClienteDePrueba, httpx_mock: HTTPXMock) -> None:
     """La cascada ya resuelta, y en crudo. Es lo que hay que mirar, no `actual_plan`."""
-    httpx_mock.add_response(url=f"{ORG}/limits", json={"accounts": 5, "publications": 100})
+    httpx_mock.add_response(url=f"{ORG}/limits", json={"accounts": 5, "users": 3})
 
-    assert cliente.esperar(cliente.pv.organizations.limits("org1")) == {"accounts": 5, "publications": 100}
+    assert cliente.esperar(cliente.pv.organizations.limits("org1")) == {"accounts": 5, "users": 3}
     assert ruta(unica(httpx_mock)) == "/organizations/org1/limits"