planvortex 0.5.0__tar.gz → 0.6.0__tar.gz

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

@@ -4,6 +4,46 @@ 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.5.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.5.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.5.0 → planvortex-0.6.0}/openapi/planvortex.openapi.json

@@ -2449,7 +2449,6 @@
                     "name": "Client X",
                     "actual_plan": {
                       "accounts": 4,
-                      "publications": 150,
                       "users": 1,
                       "space": 0.25,
                       "integrations": 1,
@@ -2625,7 +2624,6 @@
                   "value": {
                     "actual_plan": {
                       "accounts": 8,
-                      "publications": 300,
                       "users": 3,
                       "space": 1,
                       "integrations": 3,
@@ -6024,7 +6022,6 @@
                   "value": {
                     "actual_plan": {
                       "accounts": 8,
-                      "publications": 300,
                       "users": 3,
                       "space": 1,
                       "integrations": 3,
@@ -6343,7 +6340,6 @@
                     "name": "Client X - Spain",
                     "actual_plan": {
                       "accounts": 3,
-                      "publications": 100,
                       "users": 1,
                       "space": 0.25,
                       "integrations": 0,
@@ -10702,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."
@@ -12079,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."
@@ -12265,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,
@@ -12943,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."
@@ -13385,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"
@@ -13395,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."
@@ -13409,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",
@@ -13433,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": [
           {

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

{planvortex-0.5.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.5.0 → planvortex-0.6.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]]
     """
@@ -1553,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.
@@ -1567,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]
     """
@@ -1591,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.
@@ -2399,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.
     """
@@ -2641,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.
     """
@@ -2957,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.5.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]
 
 

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

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

{planvortex-0.5.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.5.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.5.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.5.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"