planvortex 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -4,6 +4,114 @@ 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.4.0] - 2026-08-31
+
+An AI plan can now be **archived**, and deleting one finally means what people thought it meant.
+
+The two look alike on a screen and have nothing in common underneath: archiving takes the plan out
+of the listing and touches nothing else, while deleting takes the publications that had not gone out
+with it. Almost every time someone reaches for "remove" they wanted the first one.
+
+Upgrading from `0.3.0` needs no changes and `MIGRATION.md` gains no entry — everything added here is
+additive. **Read the note on `remove()` anyway**: what it deletes changed in the server, so it has
+been happening to your `0.3.0` calls for a while and the docs that shipped with them say otherwise.
+
+### Added
+
+- **`ai_plans.archive()` and `ai_plans.unarchive()`**, in both clients. Archiving is **visibility
+  only**: the plan leaves the listing and moves to the archived one, no publication is touched —
+  anything scheduled keeps publishing — no credits come back, nothing is cancelled. It therefore
+  works in **any state**, `generating` included, and it is undone. On the object it is
+  `archived_date`: a field, **not** a value of `state`, so reading the state to find out whether a
+  plan is archived will never work. Absent means active, which is how every plan created before the
+  field existed comes back.
+- **`archived` on `ai_plans.list()` and `ai_plans.aiterate()`/`iterate()`.** `True` returns the
+  archived plans instead of the active ones, never both at once. A `False` is not sent: the server
+  switches the filter on with the literal `"true"`, so it would be noise — and it would suggest a
+  third mode with both cupboards open that does not exist.
+
+### Changed
+
+- **`ai_plans.remove()` deletes the plan's publications that have not gone out yet**, not only the
+  drafts: if the plan had already been validated, whatever was still scheduled goes too. This is a
+  change **in the server**, so it reached your existing calls the day it shipped — before it, a
+  validated plan you deleted kept publishing by itself the following week. Two states are
+  deliberately left alone: the already published one, because deleting it here would not take it off
+  the network and would only lose its history, and the one being published at that very moment.
+  If you wanted the plan out of the way without losing anything, that is `archive()`.
+
+## [0.3.0] - 2026-08-31
+
+The AI planner stops being one thing. A plan can now be generated from **your own photos**, from an
+**article**, from the **products of a connected catalogue** or as a **countdown towards a date**, and
+the package publishes the catalogue that says what each of those accepts and what each of them
+costs.
+
+Everything here is additive: `template` and `source` are optional, and a plan created without them
+is a `standard` one — exactly what every plan was before templates existed. Upgrading from `0.2.0`
+needs no changes and `MIGRATION.md` gains no entry.
+
+**The headline is a price, and it is worth saying out loud before your user creates the plan.**
+Images are 94 % of what a plan costs. A template whose pictures come from the source generates none,
+so the same week — 7 publications with a picture on each, one account — goes from **519 credits to
+48**. That is not a rounding: it is the difference between a feature a customer uses once a month
+and one they use every week.
+
+### Added
+
+- **`catalog.planner_templates()`**, in both clients and cached like the rest of the catalogue. It
+  answers what a plan can be generated FROM and what each source allows: `allows_shared`,
+  `allows_gallery`, `generates_images`, the `regenerate` matrix, `orchestration_cost` and
+  `orchestration_cost_per_source_item`, `max_source_items`, and the `source_fields` the source step
+  is made of. **Read it, do not copy it** — it is the one catalogue entry that carries prices, and a
+  table written by hand in your interface would show a cost the server no longer charges. It is also
+  the only route of the catalogue that **wraps its answer** (`{"templates": [...]}`), which is the
+  kind of thing that fails without an error: iterating the envelope gives you the string
+  `"templates"` and nothing complains.
+- **`template` and `source` on `ai_plans.create()`**, with the five templates: `standard`,
+  `from_images`, `from_text`, `from_catalog` and `campaign`. A template is the **source** of the
+  content and not a different flow — publish days, language, tone, `shared` and the images stay
+  cross-cutting options, and each template declares which of them it accepts. Sending one it does
+  not accept is a 2106, not a silent ignore.
+- **`PlannerTemplateName` and `PLANNER_TEMPLATES`**, plus `PlannerTemplate`,
+  `PlannerTemplateField`, `PlannerTemplateFieldType`, `AiPlanSourceInput`,
+  `AiPlanSourceImageInput`, `AiPlanSource`, `AiPlanSourceProduct` and `AiPlanNotice`. The
+  `Literal` is **closed**, unlike the Node library's open enumeration and for the same reason the
+  networks are closed here: a template you have not heard of should go red where you branch on it
+  rather than slip through. `AiPlan` now carries `template` — always, a plan created before
+  templates existed reads `standard` — and `source`.
+- **Errors 2111 to 2117 arrive as `AiPlanError`**, with nothing registered to make them: they fall
+  in the 2100-2199 range on their own, and there is now a test that says so rather than assuming it.
+  They come back from `create()`, which is the part that surprises: **the source is validated when
+  the plan is created, not when it is generated.** The article is downloaded, the catalogue is read
+  live and the product pictures are copied inside that call, so a source that does not work fails
+  while your user is still in front of it. What gets stored is a snapshot — a `retry` three days
+  later does not depend on the article still being online or the product still being in the
+  catalogue.
+
+### Changed
+
+- `ai_plans.regenerate` documents that **`"image"` depends on the plan's template**, not only on
+  whether the plan allowed images. The template that did not generate the picture cannot regenerate
+  it: read `regenerate["image"]` from the catalogue before you draw that button, because on
+  `from_images` it charges 70 credits to replace the user's own photo with an invented one.
+- `ai_plans.get` documents **`warnings`**, which is a notice on a plan that generated **fine** and
+  not an error of the response — the place nobody looks. Today it carries one: **2117**, part of the
+  source did not fit in the plan week. A plan is weekly and the source does not extend it, so twelve
+  photos with six slots left publish six; `data` brings `{"source_items": ..., "capacity": ...}`,
+  and the slots are your publish days times your accounts, so it can be said before creating the
+  plan rather than after charging for it.
+- Two traps are now written on the types that carry them, because neither has an error code and both
+  fail silently. **`source["text"]` wins over `source["url"]`** when both arrive — pasting the
+  article is what a user does when the download did not work, so re-downloading to ignore what they
+  wrote would take away their only way out. And **`event_date` is a calendar day, `YYYY-MM-DD`**,
+  never an ISO instant: it is read in the plan's timezone, and `2026-09-15T00:00:00Z` is the 14th in
+  the afternoon in New York — a whole day off in a countdown, for half of America.
+- `AiPlanSourceProduct["price"]` says why the price is **never converted**: it comes exactly as the
+  network returned it, the same field is a number elsewhere in Meta's API, and dividing by 100 "just
+  in case" is precisely how a 10 EUR product gets advertised at 0,10 EUR.
+- The route census is **113 of 113**. The new one is `GET /planner_templates`.
+
 ## [0.2.0] - 2026-08-30
 
 Telegram, the eleventh network, reaches the package. No endpoint was added and no signature moved:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.2.0
+Version: 0.4.0
 Summary: Official Python client for the PlanVortex API
 Project-URL: Homepage, https://planvortex.com/developers
 Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
@@ -180,6 +180,60 @@ if (pv.comments.actions_for("linkedin") or {}).get("hide"):
     ...
 ```
 
+## AI plans, and what they are generated from
+
+A plan is a **week** of drafts written by a model: you queue it, a job generates it, and what comes
+out are ordinary publications in `draft` that you edit and validate. `template` says what the
+content is generated FROM, and it is the only thing that changes between one plan and another —
+publish days, language, tone and images stay cross-cutting options, and each template declares which
+of them it accepts.
+
+```python
+# The list, the prices and the fields of the source step. Cached, like the rest of the catalogue.
+templates = pv.catalog.planner_templates()
+
+# A week written from the customer's own photos, in the order that tells the story.
+queued = pv.ai_plans.create(
+    client_id,
+    org_id,
+    {
+        "prompt": "Our autumn menu",
+        "accounts": [account_id],
+        "template": "from_images",
+        "source": {
+            "images": [
+                {"id_upload": first, "description": "Dough resting on the bench"},
+                {"id_upload": second, "description": "The loaf coming out of the oven"},
+            ]
+        },
+    },
+)
+queued["estimate"]["images_target"]  # 0 — the pictures come from the source
+```
+
+Four things worth knowing before you build the screen:
+
+- **The template that does not generate images does not spend image credits, and images are 94 % of
+  a plan.** The same week — 7 publications with a picture on each, one account — costs 519 credits
+  as `standard` and **48** as `from_images`. Say it before the plan is created, not after it is
+  charged.
+- **`regenerate(..., "image")` is per template**, not just per plan: the one that did not generate
+  the picture cannot regenerate it. Read `regenerate["image"]` from the catalogue before you draw
+  the button — on `from_images` it would charge 70 credits to replace the user's own photo with an
+  invented one.
+- **The source is validated when the plan is CREATED**, not when it is generated: the article is
+  downloaded, the catalogue is read live and the product pictures are copied inside that call. So a
+  broken source fails while your user is still there — errors 2111 to 2116, all of them
+  `AiPlanError` — and what gets stored is a snapshot: a `retry` three days later does not depend on
+  the article still being online.
+- **A plan is weekly and the source does not extend it.** Twelve photos with six slots left publish
+  six, and the plan carries warning **2117** in `ai_plan["warnings"]` — a notice on a plan that
+  generated fine, not an error. The slots are your publish days times your accounts, so you can say
+  it in advance.
+
+Do not hardcode the list, the costs or the field limits: `GET /planner_templates` publishes them
+because the server is what charges them.
+
 ## Errors
 
 Errors are classified by `code`, **never by the HTTP status** — every domain error in this API
@@ -294,7 +348,7 @@ you missed.
 · `pv.comments` · `pv.messages` · `pv.contacts` · `pv.products` · `pv.integrations` · `pv.ai_plans`
 · `pv.dashboard` · `pv.apps`
 
-That is **112 of the 112 operations** the specification documents — everything except the 19 routes
+That is **113 of the 113 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.2.0 → planvortex-0.4.0}/README.md

@@ -150,6 +150,60 @@ if (pv.comments.actions_for("linkedin") or {}).get("hide"):
     ...
 ```
 
+## AI plans, and what they are generated from
+
+A plan is a **week** of drafts written by a model: you queue it, a job generates it, and what comes
+out are ordinary publications in `draft` that you edit and validate. `template` says what the
+content is generated FROM, and it is the only thing that changes between one plan and another —
+publish days, language, tone and images stay cross-cutting options, and each template declares which
+of them it accepts.
+
+```python
+# The list, the prices and the fields of the source step. Cached, like the rest of the catalogue.
+templates = pv.catalog.planner_templates()
+
+# A week written from the customer's own photos, in the order that tells the story.
+queued = pv.ai_plans.create(
+    client_id,
+    org_id,
+    {
+        "prompt": "Our autumn menu",
+        "accounts": [account_id],
+        "template": "from_images",
+        "source": {
+            "images": [
+                {"id_upload": first, "description": "Dough resting on the bench"},
+                {"id_upload": second, "description": "The loaf coming out of the oven"},
+            ]
+        },
+    },
+)
+queued["estimate"]["images_target"]  # 0 — the pictures come from the source
+```
+
+Four things worth knowing before you build the screen:
+
+- **The template that does not generate images does not spend image credits, and images are 94 % of
+  a plan.** The same week — 7 publications with a picture on each, one account — costs 519 credits
+  as `standard` and **48** as `from_images`. Say it before the plan is created, not after it is
+  charged.
+- **`regenerate(..., "image")` is per template**, not just per plan: the one that did not generate
+  the picture cannot regenerate it. Read `regenerate["image"]` from the catalogue before you draw
+  the button — on `from_images` it would charge 70 credits to replace the user's own photo with an
+  invented one.
+- **The source is validated when the plan is CREATED**, not when it is generated: the article is
+  downloaded, the catalogue is read live and the product pictures are copied inside that call. So a
+  broken source fails while your user is still there — errors 2111 to 2116, all of them
+  `AiPlanError` — and what gets stored is a snapshot: a `retry` three days later does not depend on
+  the article still being online.
+- **A plan is weekly and the source does not extend it.** Twelve photos with six slots left publish
+  six, and the plan carries warning **2117** in `ai_plan["warnings"]` — a notice on a plan that
+  generated fine, not an error. The slots are your publish days times your accounts, so you can say
+  it in advance.
+
+Do not hardcode the list, the costs or the field limits: `GET /planner_templates` publishes them
+because the server is what charges them.
+
 ## Errors
 
 Errors are classified by `code`, **never by the HTTP status** — every domain error in this API
@@ -264,7 +318,7 @@ you missed.
 · `pv.comments` · `pv.messages` · `pv.contacts` · `pv.products` · `pv.integrations` · `pv.ai_plans`
 · `pv.dashboard` · `pv.apps`
 
-That is **112 of the 112 operations** the specification documents — everything except the 19 routes
+That is **113 of the 113 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.