planvortex 0.7.0__tar.gz → 0.9.0__tar.gz

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

@@ -4,6 +4,87 @@ 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.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
+tests went red the moment the models were regenerated**, because `PublishableNetwork` is a closed
+`Literal` written by hand. The Node package did not break at all, and that is worse: its
+`SocialNetwork` is an open enumeration, so a missing network there costs autocompletion and
+documentation with nothing to signal it.
+
+Nothing was removed and no signature moved: upgrading from `0.7.0` needs no changes, and
+`MIGRATION.md` gains no entry.
+
+### Fixed
+
+- **Slack's errors (980-986) were not `PublicationError`.** The publication family stopped at 979,
+  so every one of them fell outside the table and arrived as a plain `PlanVortexError` — including
+  **980, the commonest error on the whole network**: the PlanVortex app is not in the channel.
+  Code that catches `PublicationError` to tell a fixable publication failure from anything else was
+  told nothing. The range now reaches 986, both ends are pinned by a test, and the README's range
+  table — which a test compares against the package — says so too.
+
+### Added
+
+- **`slack` in `PublishableNetwork`**, so it is in `PUBLISHABLE_NETWORKS` at runtime and
+  `is_publishable_network("slack")` answers `True`. It is deliberately **not** in `CommentNetwork`
+  nor in `ContactChannel`: Slack has neither a comment inbox nor direct messages, and putting it in
+  either would promise a screen that does not exist. `SocialNetwork` picked it up on its own — it
+  comes from the generated models.
+- **A warning on `accounts.enable()`, because nothing else announces it.** On Slack that call is
+  also what puts the app inside the channel. On a **public** channel it joins by itself; on a
+  **private** one it cannot — Slack has no API for that — and somebody has to type
+  `/invite @PlanVortex` in the channel. The call succeeds either way and the account stays
+  connected: what fails is the first publication, with error 980. Say it before your user picks the
+  channel.
+
+### Changed
+
+- The prose that counts networks, in the five places it had gone stale: the two union sizes
+  (`PublishableNetwork` is now **twelve of the thirteen**), the bridge in `is_publishable_network`,
+  `SOCIAL_NETWORKS` ("six to thirteen in two years"), `ContactChannel` — where `slack` joins
+  `telegram` as a network that is **not** a channel, for the same reason: a bot cannot start a
+  conversation with anybody — and the two examples, `connect.py` and `publish.py`.
 ## [0.7.0] - 2026-09-04
 
 **Users are unlimited on every plan**, so the quota that said otherwise is gone from the types —

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.7.0
+Version: 0.9.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/
@@ -246,7 +246,7 @@ memorising numbers:
 | 601-612 | `user` | `UserError` |
 | 700-715 | `account` | `AccountError` |
 | 800-810 | `file` | `FileError` |
-| 900-979 | `publication` | `PublicationError` |
+| 900-986 | `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.7.0 → planvortex-0.9.0}/README.md

@@ -216,7 +216,7 @@ memorising numbers:
 | 601-612 | `user` | `UserError` |
 | 700-715 | `account` | `AccountError` |
 | 800-810 | `file` | `FileError` |
-| 900-979 | `publication` | `PublicationError` |
+| 900-986 | `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.