planvortex 0.5.0__tar.gz → 0.7.0__tar.gz

{planvortex-0.5.0 → planvortex-0.7.0}/CHANGELOG.md

@@ -4,6 +4,71 @@ 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.7.0] - 2026-09-04
+
+**Users are unlimited on every plan**, so the quota that said otherwise is gone from the types —
+the same correction 0.6.0 made for publications, one axis later.
+
+It is the second half of a change the server made on 03-09-2026: users stopped being something a
+plan grants and became something you simply count. `PlanData["users"]` was a **required** key, so
+mypy accepted `limits["users"]` and the call raised `KeyError` at runtime, which is the same
+failure mode 0.6.0 describes for publications.
+
+### Changed
+
+- **BREAKING (types only): `PlanData["users"]` no longer exists.** The count moved to
+  `PlanUseData` as an optional key — how many users have access right now, with no limit to
+  compare it against, because there is none. Nothing changes on the wire.
+- **The `/apps` operations no longer claim the Custom plan.** Their docstrings still said the API
+  needed it. That stopped being true on 02-09-2026, and the docstrings come straight from the
+  OpenAPI document, so they were repeating a copy of the spec that had not been rebuilt since.
+
+### Removed
+
+- **`PlanData["artificial_inteligence"]`, `PlanData["stats"]` and `PlanData["whatsapp"]`.**
+  Three optional keys describing a plan model that no longer exists: statistics and WhatsApp are on
+  every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero.
+
+## [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.

{planvortex-0.5.0 → planvortex-0.7.0}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.5.0
+Version: 0.7.0
 Summary: Official Python client for the PlanVortex API
-Project-URL: Homepage, https://planvortex.com/developers
+Project-URL: Homepage, https://planvortex.com/en/developers
 Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
 Project-URL: API, https://planvortex.com/documentation
 Project-URL: Repository, https://github.com/taliasoftworks/PlanVortexPython
@@ -53,7 +53,7 @@ pip install planvortex
 - Python 3.10 and newer.
 
 **Reference:** <https://taliasoftworks.github.io/PlanVortexPython/> · **Guides:**
-[planvortex.com/developers](https://planvortex.com/developers)
+[planvortex.com/en/developers](https://planvortex.com/en/developers)
 
 ## Authentication
 
@@ -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` |
@@ -371,7 +371,7 @@ and reaches a person.
 
 - [Reference](https://taliasoftworks.github.io/PlanVortexPython/)
 - [API documentation](https://planvortex.com/documentation)
-- [Developers](https://planvortex.com/developers)
+- [Developers](https://planvortex.com/en/developers)
 - [Node client](https://github.com/taliasoftworks/PlanVortexNode)
 - [Contributing](https://github.com/taliasoftworks/PlanVortexPython/blob/main/CONTRIBUTING.md) · [Security](https://github.com/taliasoftworks/PlanVortexPython/blob/main/SECURITY.md) · [Changelog](https://github.com/taliasoftworks/PlanVortexPython/blob/main/CHANGELOG.md)
 

{planvortex-0.5.0 → planvortex-0.7.0}/README.md

@@ -23,7 +23,7 @@ pip install planvortex
 - Python 3.10 and newer.
 
 **Reference:** <https://taliasoftworks.github.io/PlanVortexPython/> · **Guides:**
-[planvortex.com/developers](https://planvortex.com/developers)
+[planvortex.com/en/developers](https://planvortex.com/en/developers)
 
 ## Authentication
 
@@ -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` |
@@ -341,7 +341,7 @@ and reaches a person.
 
 - [Reference](https://taliasoftworks.github.io/PlanVortexPython/)
 - [API documentation](https://planvortex.com/documentation)
-- [Developers](https://planvortex.com/developers)
+- [Developers](https://planvortex.com/en/developers)
 - [Node client](https://github.com/taliasoftworks/PlanVortexNode)
 - [Contributing](https://github.com/taliasoftworks/PlanVortexPython/blob/main/CONTRIBUTING.md) · [Security](https://github.com/taliasoftworks/PlanVortexPython/blob/main/SECURITY.md) · [Changelog](https://github.com/taliasoftworks/PlanVortexPython/blob/main/CHANGELOG.md)
 

{planvortex-0.5.0 → planvortex-0.7.0}/openapi/planvortex.openapi.json

@@ -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.\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.",
+        "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.\n\n**And a Telegram account arrives already active.** In the other eleven networks this endpoint hands you accounts that are still off, and you pick which ones spend a plan slot with `POST .../accounts/{id_account}/enable`. Here there is nothing to call: one channel arrives — the one the person picked in Telegram — and PlanVortex takes the slot for it right then. If the plan has no free slot the account is still created, off, and the person is told so in the bot chat; `GET /organizations/{id_organization}/accounts` will not list it, because that listing only returns active accounts, but naming it in the `accounts` filter does return it.",
         "operationId": "connectAccount",
         "x-planvortex-identity": [
           "current_user",
@@ -736,7 +736,7 @@
           "accounts"
         ],
         "summary": "Re-enable a disconnected account",
-        "description": "Brings back an account that was removed, without going through the authorization again — as long as its stored token still works.\n\nIt takes a **slot of the plan**, so it fails with error 706 when the organization is already at its account limit. It also turns the network's webhooks back on, on any plan but the free one.",
+        "description": "Brings back an account that was removed, without going through the authorization again — as long as its stored token still works.\n\nIt takes a **slot of the plan**, so it fails with error 706 when the organization is already at its account limit. It also turns the network's webhooks back on, on any plan but the free one.\n\n**On `telegram` you normally never call this.** That network's accounts are born active — there is no authorization return in which to choose them, so PlanVortex takes the slot when the bot is added to the channel. The one case left is a channel that arrived while the plan was full: it stays off until a slot frees up, and this is what turns it on.",
         "operationId": "enableAccount",
         "x-planvortex-identity": [
           "current_user",
@@ -945,7 +945,7 @@
           "ai_plans"
         ],
         "summary": "Create an AI publication plan",
-        "description": "Create a weekly AI publication plan. The plan is queued in state 'pending' and generated asynchronously by the generate-ai-plans job; poll GET by id while state is pending or generating. Validations at creation: the client plan allows AI (artificial_inteligence), the accounts belong to the organization, there are enough AI credits for the deterministic base cost (orchestration + target texts), and there is room in the organization's monthly publication limit. Returns the created plan together with the deterministic cost estimate. Requires the ai_plans:create permission. Since the plan can be generated from a SOURCE (`template` + `source`), part of that validation is the source itself: the article is downloaded, the catalogue is read live and the product pictures are copied — all of it inside this request, so what does not work fails with the user in front of it. A plan whose source did not fit in the week is still created, and says so in ai_plan.warnings (2117).",
+        "description": "Create a weekly AI publication plan. The plan is queued in state 'pending' and generated asynchronously by the generate-ai-plans job; poll GET by id while state is pending or generating. Validations at creation: the client plan allows AI (it contracts AI credits; Free does not), the accounts belong to the organization, there are enough AI credits for the deterministic base cost (orchestration + target texts), and there is room in the organization's monthly publication limit. Returns the created plan together with the deterministic cost estimate. Requires the ai_plans:create permission. Since the plan can be generated from a SOURCE (`template` + `source`), part of that validation is the source itself: the article is downloaded, the catalogue is read live and the product pictures are copied — all of it inside this request, so what does not work fails with the user in front of it. A plan whose source did not fit in the week is still created, and says so in ai_plan.warnings (2117).",
         "operationId": "addAiPlan",
         "x-planvortex-identity": [
           "current_user",
@@ -1564,7 +1564,7 @@
           "apps"
         ],
         "summary": "List the client's apps",
-        "description": "The apps of a client. Secrets never travel here: to read one, ask for it explicitly with the `secret` endpoint.\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. It also needs the **Custom plan** (`ERROR_CODE_542`): apps are what that plan adds, and they are the door to this whole API.",
+        "description": "The apps of a client. Secrets never travel here: to read one, ask for it explicitly with the `secret` endpoint.\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. **No plan is required**: apps are on all four plans, the free one included — what the plan decides is how many you can hold at once and how fast you can call.",
         "operationId": "getClientApps",
         "x-planvortex-identity": [
           "current_user"
@@ -1616,7 +1616,7 @@
           "apps"
         ],
         "summary": "Create an app",
-        "description": "Creates the app and its credentials.\n\n**A client can have one app.** Creating a second answers error 536. If you need to rotate credentials, update the existing app rather than creating another.\n\nEvery URL is validated: a bad entry in `allowed_domains` answers 531, in `redirect_urls` 532, and a bad `webhook_url` answers 535.\n\n**The secret is not in the response.** Read it with `GET /clients/{id_client}/apps/{id_app}/secret`.\n\n**A client can only have ONE app.** Creating a second one is rejected with `ERROR_CODE_536`: delete or update the one that exists. The listing is paginated because every listing in this API is, not because there can be more than one.\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. It also needs the **Custom plan** (`ERROR_CODE_542`): apps are what that plan adds, and they are the door to this whole API.",
+        "description": "Creates the app and its credentials.\n\n**How many apps fit is decided by the plan**, not by a fixed limit of one: 1 on free, 2 on basic, 5 on pro and 10 on custom. Going over answers `ERROR_CODE_1308`, which carries `limit` and `used` in its `data`. Deleting an app frees its slot immediately, because only live apps count. If you just need to rotate credentials, update the existing app rather than creating another.\n\n**The user's email must be verified** (`ERROR_CODE_546`). This is the only route in `/apps` that asks for it: an app is a key to the whole public API, and this is what stops a throwaway address from minting them in bulk. Reading, updating and deleting an app you already own do not check it.\n\nEvery URL is validated: a bad entry in `allowed_domains` answers 531, in `redirect_urls` 532, and a bad `webhook_url` answers 535.\n\n**The secret is not in the response.** Read it with `GET /clients/{id_client}/apps/{id_app}/secret`.\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. **No plan is required**: apps are on all four plans, the free one included — what the plan decides is how many you can hold at once and how fast you can call.",
         "operationId": "createClientApp",
         "x-planvortex-identity": [
           "current_user"
@@ -1667,7 +1667,7 @@
           "apps"
         ],
         "summary": "Get one app",
-        "description": "The app's record, without its secret. Note the envelope: `{client_app}` here, `{client_apps, total}` in the list.\n\n**An app token works here.** This is the one part of `/apps` that does: an app can read and update its own record, but it cannot list, create, delete, or read the secret. The **Custom plan** is still required (`ERROR_CODE_542`).",
+        "description": "The app's record, without its secret. Note the envelope: `{client_app}` here, `{client_apps, total}` in the list.\n\n**An app token works here.** This is the one part of `/apps` that does: an app can read and update its own record, but it cannot list, create, delete, or read the secret. **No plan is required**: apps are on all four plans, the free one included.",
         "operationId": "getClientApp",
         "x-planvortex-identity": [
           "current_user",
@@ -1710,7 +1710,7 @@
           "apps"
         ],
         "summary": "Update an app",
-        "description": "Replaces the app's configuration. **Every field is overwritten with what you send**, so a `redirect_urls` you leave out becomes an empty list — send the whole object, not a patch.\n\nChanging `webhook_url` takes effect on the next event; there is no verification handshake.\n\n**It replaces every field with what the body carries.** `name`, `keycloak_client_idenfifier`, `allowed_domains`, `redirect_urls` and `webhook_url` are all written as sent, so omitting one erases it — sending an update without `webhook_url` turns the webhook off. Read the app first and send it back whole.\n\n**An app token works here.** This is the one part of `/apps` that does: an app can read and update its own record, but it cannot list, create, delete, or read the secret. The **Custom plan** is still required (`ERROR_CODE_542`).",
+        "description": "Replaces the app's configuration. **Every field is overwritten with what you send**, so a `redirect_urls` you leave out becomes an empty list — send the whole object, not a patch.\n\nChanging `webhook_url` takes effect on the next event; there is no verification handshake.\n\n**It replaces every field with what the body carries.** `name`, `keycloak_client_idenfifier`, `allowed_domains`, `redirect_urls` and `webhook_url` are all written as sent, so omitting one erases it — sending an update without `webhook_url` turns the webhook off. Read the app first and send it back whole.\n\n**An app token works here.** This is the one part of `/apps` that does: an app can read and update its own record, but it cannot list, create, delete, or read the secret. **No plan is required**: apps are on all four plans, the free one included.",
         "operationId": "updateClientApp",
         "x-planvortex-identity": [
           "current_user",
@@ -1763,7 +1763,7 @@
           "apps"
         ],
         "summary": "Delete an app",
-        "description": "Revokes the credentials and marks the app as deleted. **Tokens already issued stop working**: the token endpoint checks that the app still exists before answering, and requests carrying an old token no longer resolve to an app.\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. It also needs the **Custom plan** (`ERROR_CODE_542`): apps are what that plan adds, and they are the door to this whole API.",
+        "description": "Revokes the credentials and marks the app as deleted. **Tokens already issued stop working**: the token endpoint checks that the app still exists before answering, and requests carrying an old token no longer resolve to an app.\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. **No plan is required**: apps are on all four plans, the free one included — what the plan decides is how many you can hold at once and how fast you can call.",
         "operationId": "deleteClientApp",
         "x-planvortex-identity": [
           "current_user"
@@ -1799,7 +1799,7 @@
           "apps"
         ],
         "summary": "Read the app's secret",
-        "description": "Returns the `client_secret` in clear. It is a separate endpoint precisely so that the secret never travels inside a listing that gets logged, cached or drawn on a screen by accident.\n\nThe same secret is what signs the outgoing webhooks (`x-hub-signature`, `x-hub-signature-256`).\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. It also needs the **Custom plan** (`ERROR_CODE_542`): apps are what that plan adds, and they are the door to this whole API.\n\nIt comes straight from Keycloak, so it is the live secret and not a copy: treat the response as a credential and never log it.",
+        "description": "Returns the `client_secret` in clear. It is a separate endpoint precisely so that the secret never travels inside a listing that gets logged, cached or drawn on a screen by accident.\n\nThe same secret is what signs the outgoing webhooks (`x-hub-signature`, `x-hub-signature-256`).\n\n**Needs a USER token, not an app token.** With client credentials it answers `ERROR_CODE_512`. **No plan is required**: apps are on all four plans, the free one included — what the plan decides is how many you can hold at once and how fast you can call.\n\nIt comes straight from Keycloak, so it is the live secret and not a copy: treat the response as a credential and never log it.",
         "operationId": "getClientAppSecret",
         "x-planvortex-identity": [
           "current_user"
@@ -2449,8 +2449,6 @@
                     "name": "Client X",
                     "actual_plan": {
                       "accounts": 4,
-                      "publications": 150,
-                      "users": 1,
                       "space": 0.25,
                       "integrations": 1,
                       "twitter_credits": 2500,
@@ -2625,8 +2623,6 @@
                   "value": {
                     "actual_plan": {
                       "accounts": 8,
-                      "publications": 300,
-                      "users": 3,
                       "space": 1,
                       "integrations": 3,
                       "twitter_credits": 5000,
@@ -2711,7 +2707,7 @@
           "clients"
         ],
         "summary": "Configure the client's own AI models (BYOK)",
-        "description": "Set the client's Bring-Your-Own-Key AI provider configuration per scope. The request body is an object keyed by scope (orchestrator, text, image); a scope set to null clears it. Providers and capabilities are validated against a fixed catalogue. When a scope uses BYOK, its calls are billed to the client's own provider and do NOT consume PlanVortex AI credits, but the artificial_inteligence plan flag is still required to use the feature. API keys are stored encrypted and never returned; the response client only exposes provider, model and has_api_key per scope. Requires the client:update permission.",
+        "description": "Set the client's Bring-Your-Own-Key AI provider configuration per scope. The request body is an object keyed by scope (orchestrator, text, image); a scope set to null clears it. Providers and capabilities are validated against a fixed catalogue. When a scope uses BYOK, its calls are billed to the client's own provider and do NOT consume PlanVortex AI credits, but the plan still has to include AI credits to use the feature. API keys are stored encrypted and never returned; the response client only exposes provider, model and has_api_key per scope. Requires the client:update permission.",
         "operationId": "updateAiSettings",
         "x-planvortex-identity": [
           "current_user",
@@ -6024,8 +6020,6 @@
                   "value": {
                     "actual_plan": {
                       "accounts": 8,
-                      "publications": 300,
-                      "users": 3,
                       "space": 1,
                       "integrations": 3,
                       "twitter_credits": 5000,
@@ -6343,8 +6337,6 @@
                     "name": "Client X - Spain",
                     "actual_plan": {
                       "accounts": 3,
-                      "publications": 100,
-                      "users": 1,
                       "space": 0.25,
                       "integrations": 0,
                       "twitter_credits": 0,
@@ -10702,7 +10694,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."
@@ -12079,7 +12071,7 @@
           "actual_use": {
             "allOf": [
               {
-                "$ref": "#/components/schemas/PlanData"
+                "$ref": "#/components/schemas/PlanUseData"
               }
             ],
             "description": "What the organization and its children are consuming right now."
@@ -12265,7 +12257,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,
@@ -12943,7 +12935,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."
@@ -13382,11 +13374,9 @@
       },
       "PlanData": {
         "type": "object",
-        "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.",
+        "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.\n\nUsers are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero.",
         "required": [
           "accounts",
-          "publications",
-          "users",
           "space",
           "integrations"
         ],
@@ -13395,21 +13385,17 @@
             "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."
-          },
           "space": {
             "type": "number",
             "description": "Storage, in GB."
           },
           "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 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",
@@ -13418,18 +13404,25 @@
           "ai_credits": {
             "type": "integer",
             "description": "Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope."
+          }
+        }
+      },
+      "PlanUseData": {
+        "type": "object",
+        "description": "What is being consumed right now. Same shape as PlanData plus `publications` and `users`, which are 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."
           },
-          "artificial_inteligence": {
-            "type": "boolean",
-            "description": "Whether AI generation is enabled."
-          },
-          "whatsapp": {
-            "type": "boolean",
-            "description": "Whether WhatsApp may be connected."
-          },
-          "stats": {
-            "type": "boolean",
-            "description": "Whether statistics collection is enabled."
+          "users": {
+            "type": "integer",
+            "description": "Users with access right now. A METRIC, not a quota: users are unlimited on every plan, so there is no limit to compare it against."
           }
         }
       },

{planvortex-0.5.0 → planvortex-0.7.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.5.0"
+version = "0.7.0"
 description = "Official Python client for the PlanVortex API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -67,7 +67,7 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://planvortex.com/developers"
+Homepage = "https://planvortex.com/en/developers"
 # `Documentation` es la referencia generada de ESTE paquete, que es lo que busca quien llega a la
 # ficha de PyPI. La especificacion de la API entera vive aparte, en `API`: son dos cosas distintas y
 # apuntar las dos al mismo sitio dejaba una de las dos sin enlace.

{planvortex-0.5.0 → planvortex-0.7.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.5.0 → planvortex-0.7.0}/src/planvortex/_generated/models.py

@@ -1072,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]]
     """
@@ -1547,27 +1547,25 @@ class OrganizationsUserList(TypedDict):
 class PlanData(TypedDict):
     """
     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.
+
+    Users are NOT here: every plan has unlimited users, so they are neither charged nor split between organizations. They are still counted, in `PlanUseData.users`. There are no `artificial_inteligence`, `whatsapp` or `stats` flags either: statistics and WhatsApp are on every plan, and what gates AI is `ai_credits` — a plan with credits has AI, and Free has zero.
     """
 
     accounts: int
     """
     Social accounts that may be connected.
     """
-    publications: int
-    """
-    Publications that may be sent per month.
-    """
-    users: int
-    """
-    Users with access.
-    """
     space: float
     """
     Storage, in GB.
     """
     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 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]
     """
@@ -1577,17 +1575,20 @@ class PlanData(TypedDict):
     """
     Monthly AI credits (1 credit = $0.001 of provider cost): 15 per plan orchestration pass, 2 per generated text, 70 per generated image. Resets monthly and does not roll over. A client using its own provider key (BYOK) does not consume them in that scope.
     """
-    artificial_inteligence: NotRequired[bool]
+
+
+class PlanUseData(PlanData):
     """
-    Whether AI generation is enabled.
+    What is being consumed right now. Same shape as PlanData plus `publications` and `users`, which are counted but neither charged nor split between organizations.
     """
-    whatsapp: NotRequired[bool]
+
+    publications: NotRequired[int]
     """
-    Whether WhatsApp may be connected.
+    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.
     """
-    stats: NotRequired[bool]
+    users: NotRequired[int]
     """
-    Whether statistics collection is enabled.
+    Users with access right now. A METRIC, not a quota: users are unlimited on every plan, so there is no limit to compare it against.
     """
 
 
@@ -2399,7 +2400,7 @@ class DashboardDashboardPublicationRef(TypedDict):
 
 
 class DashboardPlanUse(TypedDict):
-    actual_use: PlanData
+    actual_use: PlanUseData
     """
     What the organization and its children are consuming right now.
     """
@@ -2641,7 +2642,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.
     """
@@ -2957,7 +2958,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.5.0 → planvortex-0.7.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]
 
 

{planvortex-0.5.0 → planvortex-0.7.0}/src/planvortex/_version.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import platform
 
-VERSION = "0.5.0"
+VERSION = "0.7.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.5.0 → planvortex-0.7.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.
 
@@ -1115,6 +1127,7 @@ __all__ = [
     "PersistentMenu",
     "PlanData",
     "PlanUse",
+    "PlanUseData",
     "PlannerTemplate",
     "PlannerTemplateField",
     "PlannerTemplateFieldType",

{planvortex-0.5.0 → planvortex-0.7.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.5.0 → planvortex-0.7.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.5.0 → planvortex-0.7.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.5.0 → planvortex-0.7.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"