planvortex 0.8.0__tar.gz → 0.10.0__tar.gz

{planvortex-0.8.0 → planvortex-0.10.0}/CHANGELOG.md

@@ -4,6 +4,97 @@ 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.10.0] - 2026-09-24
+
+Pinterest, the fourteenth network, reaches the package — and it is the first one where choosing
+the account does not choose where the publication comes out. **A pin goes to a board**, and that is
+a field no other network has. Nothing was removed and no signature moved: upgrading from `0.9.0`
+needs no changes, and `MIGRATION.md` gains no entry. The new fields are optional for the other
+thirteen networks.
+
+**`PublishableNetwork` is a closed `Literal` written by hand, and it went red on regeneration** —
+which is how it is meant to find out. Pinterest is also the first network that enters
+`PUBLISHABLE_NETWORKS` and **not** `COMMENT_NETWORKS`, so it is the first real proof that the two
+lists are independent.
+
+### Added
+
+- **`pv.accounts.destinations(id_organization, id_account)`** and
+  **`pv.accounts.destination(id_organization, id_account, id_destination)`**, over
+  `GET /organizations/{id}/accounts/{id}/destinations[/{id}]`: an account's Pinterest boards, and
+  one board with its sections. Every other network answers 992 — the account itself is where its
+  publications go. Both take `refresh=True` to skip the server's short cache, for a board created
+  a moment ago; not on every call, because all of PlanVortex's Pinterest traffic leaves through one
+  application. Also on the synchronous client.
+- **`"pinterest"` in `PublishableNetwork` and `PUBLISHABLE_NETWORKS`**, and **`destination` and
+  `link` on `PublicationInput`.** On Pinterest the board is **required**, and leaving it out does
+  not raise: the publication is created in `withErrors` with code 987 and is never attempted.
+  `destination["id"]` is **always a string** — Pinterest's ids are long integers. `link` is where
+  the pin takes whoever clicks it: it goes in its own field, not inside `text`. On every other
+  network both fields are deleted on save. Ask `destinations` and `link` in
+  `catalog.social_capabilities()` rather than keeping a list of which network has which.
+- **`destinations` on `AiPlanCreateRequest` and `AiPlan`, and `options["link"]`.** A plan with a
+  Pinterest account needs that account's board, one entry per account; without it
+  `ai_plans.create` raises **2118**, listing every account that fails. A plan that would leave pins
+  without an image is refused with **2119** before a single credit is spent, and an image that
+  fails halfway through the generation shows up as a **922** in `warnings`, with the publication
+  that was left without it.
+- Types `Destination`, `PublicationDestination` and `AiPlanDestination`.
+
+### Fixed
+
+- **Pinterest's error codes (987-996) arrived outside every family**, the third time a network's
+  codes were born above the ceiling of the publications range (after 978 and 980). They are now
+  `PublicationError`. The one that matters most is **991**: Pinterest throttling the application,
+  sent as HTTP 429 with `Retry-After` — the answer is to wait, and `error.retry_after` says how long.
+- **547, 548 and 716 were unclassified too.** 547 (a client app's identifier cannot change) and
+  548 (rotating the secret failed, the method that came with `0.9.0`) are now `AuthError`, and 716
+  (another process is renewing the Bluesky session; retry) is `AccountError`.
+- A test now checks that **every** error code named in the specification's error tables falls into
+  some family, so the next network cannot repeat this without the build going red.
+- The prose that counts networks said "nine of the eleven" and "eleven and not twelve" in places;
+  it now says fourteen, thirteen of which publish.
+
+## [0.9.0] - 2026-09-17
+
+**Which AI plan worked?** The server can now answer it, and so can this package:
+`ai_plans.results()` returns what every plan achieved with what it published, the aggregate per
+template and the total.
+
+Nothing was removed and no signature moved: upgrading from `0.8.0` needs no changes, and
+`MIGRATION.md` gains no entry.
+
+### Added
+
+- **`pv.ai_plans.results(id_client, id_organization, ...)`**, over
+  `GET /clients/{id}/organizations/{id}/ai_plans/results`, in both clients. Four things about it
+  are not obvious, and all four are in its docstring:
+  - **The range filters on the plan's week** (`week_start`), not on when it was created. A plan
+    created today for next week has published nothing yet.
+  - **The ranking is interactions per _measured_ publication**, not the total — the total rewards
+    the plan with seven accounts even when each post does half as well — and only plans with
+    `ranked: True` (at least three measured publications, or all of them) compete in it.
+  - **`social_network` recomputes every plan with only its publications on those networks**,
+    which is what makes plans on different networks comparable. With that filter
+    `credits_per_engagement` is absent: the cost belongs to the whole plan.
+  - **It is not a `Page`.** Besides the page it carries `totals` and `by_template`, which do not
+    depend on the page, so it comes back whole.
+  - **Being first is not being good.** Every plan, group and the dashboard block carry
+    `engagement_vs_average`: the plan's interactions per post over what your usual posts get on the
+    same networks (`expected_engagement_per_publication`), where **1 is your average**. The ranking
+    still orders by interactions per post, so the first plan can be below 1.
+- Types `AiPlanResult`, `AiPlanResults`, `AiPlanResultsGroup`, `AiPlanResultsTemplateGroup` and
+  the closed `AiPlanResultsSort`.
+- **`Dashboard["ai_plan_results"]`** and its `available_blocks["ai_plan_results"]`: the three best
+  plans of the range, for the home screen. It needs both `ai_plans:read` and
+  `publication_stats:read`, and unlike `ai_plans.results()` it covers the organization **and its
+  children**, so each row carries its `id_organization`.
+- **`pv.apps.rotate_secret(id_client, id_app)`**, over `POST /clients/{id}/apps/{id}/secret`. The
+  route reached the specification before this package, and regenerating the models is what turned
+  `tests/test_route_coverage.py` red — which is the test doing its job. **The previous secret stops
+  working the moment it answers, and the webhook signature changes with it.** Like `secret()`, it
+  needs a user token.
+
 ## [0.8.0] - 2026-09-13
 
 Slack, the thirteenth network, reaches the package — and here it arrives the way it should: **three

{planvortex-0.8.0 → planvortex-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.8.0
+Version: 0.10.0
 Summary: Official Python client for the PlanVortex API
 Project-URL: Homepage, https://planvortex.com/en/developers
 Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
@@ -242,11 +242,11 @@ memorising numbers:
 
 | Codes | Family | Exception |
 |---|---|---|
-| 500-546 | `auth` | `AuthError` |
+| 500-548 | `auth` | `AuthError` |
 | 601-612 | `user` | `UserError` |
-| 700-715 | `account` | `AccountError` |
+| 700-716 | `account` | `AccountError` |
 | 800-810 | `file` | `FileError` |
-| 900-986 | `publication` | `PublicationError` |
+| 900-996 | `publication` | `PublicationError` |
 | 1000-1003 | `general` | `PlanVortexError` |
 | 1100-1111 | `organization` | `OrganizationError` |
 | 1200-1207 | `role` | `PlanVortexError` |
@@ -348,7 +348,7 @@ you missed.
 · `pv.comments` · `pv.messages` · `pv.contacts` · `pv.products` · `pv.integrations` · `pv.ai_plans`
 · `pv.dashboard` · `pv.apps`
 
-That is **113 of the 113 operations** the specification documents — everything except the 19 routes
+That is **117 of the 117 operations** the specification documents — everything except the 19 routes
 of roles and invitations, which are out of scope. A script walks the OpenAPI bundle on every test
 run and fails if a route is left without a method, so the sentence above stays true.
 

{planvortex-0.8.0 → planvortex-0.10.0}/README.md

@@ -212,11 +212,11 @@ memorising numbers:
 
 | Codes | Family | Exception |
 |---|---|---|
-| 500-546 | `auth` | `AuthError` |
+| 500-548 | `auth` | `AuthError` |
 | 601-612 | `user` | `UserError` |
-| 700-715 | `account` | `AccountError` |
+| 700-716 | `account` | `AccountError` |
 | 800-810 | `file` | `FileError` |
-| 900-986 | `publication` | `PublicationError` |
+| 900-996 | `publication` | `PublicationError` |
 | 1000-1003 | `general` | `PlanVortexError` |
 | 1100-1111 | `organization` | `OrganizationError` |
 | 1200-1207 | `role` | `PlanVortexError` |
@@ -318,7 +318,7 @@ you missed.
 · `pv.comments` · `pv.messages` · `pv.contacts` · `pv.products` · `pv.integrations` · `pv.ai_plans`
 · `pv.dashboard` · `pv.apps`
 
-That is **113 of the 113 operations** the specification documents — everything except the 19 routes
+That is **117 of the 117 operations** the specification documents — everything except the 19 routes
 of roles and invitations, which are out of scope. A script walks the OpenAPI bundle on every test
 run and fails if a route is left without a method, so the sentence above stays true.