planvortex 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -4,6 +4,62 @@ 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.5.0] - 2026-09-02
+
+**Threads is the twelfth network**, and the types now know it.
+
+Nothing here removes anything: `SocialNetwork` gains a value, `PublishableNetwork` gains another,
+and everything that type-checked before type-checks now. What was wrong until today was quieter than
+an error — the committed copy of the spec predated Threads, so an account coming back from a real
+API arrived with a `social_network` no `Literal` had ever heard of, and the prose still counted
+eleven networks where the API had twelve.
+
+### Changed
+
+- The OpenAPI copy and the generated models are rebuilt from the published document, so `threads`
+  is a `SocialNetwork`, a `CommentNetwork` and a publishable network.
+- `PublishableNetwork` — hand-maintained, because generating it is not possible — includes
+  `threads`: **eleven of the twelve** networks have a feed, and `google_business` is still the one
+  that does not.
+- The prose that counts networks: a connection link is a `redirect` on **ten of the twelve**, not
+  nine of eleven. WhatsApp and Telegram are still the two that are not.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.3.0
+Version: 0.5.0
 Summary: Official Python client for the PlanVortex API
 Project-URL: Homepage, https://planvortex.com/developers
 Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/

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

@@ -107,7 +107,7 @@
           "accounts"
         ],
         "summary": "Get the connection links of every connectable network",
-        "description": "The authorization URL of each network, so the user can connect an account to this organization.\n\n**A network that cannot produce a link simply does not appear.** That is a legitimate answer, not a failure: it is what happens with `discord` in an organization that has not saved its own bot credentials yet (see `PUT /organizations/{id_organization}/social_credentials/{social_network}`).\n\n**An app cannot call this.** Connecting a social account is an OAuth flow with a person in front of it, so this endpoint only accepts a user token or a temporal connect token; with app credentials it answers error 519. The way an integration does it is to issue a temporal connect token with `GET /organizations/{id_organization}/temporal_connect_token` and hand it to its end user.\n\n**Read `authorization`, not `link`.** Nine of the eleven networks are `redirect` and you send the person to `link`. Two are not, and neither of them fails visibly if you treat it as one:\n\n• **WhatsApp is not a URL at all.** Its sign-up is Meta's Embedded Signup, a popup you raise with the Facebook JavaScript SDK, so its `link` is an empty string and everything you need to open that popup travels in `authorization`. A client that loops over the list and redirects to `link` sends its user to its own page.\n• **Telegram has a link and still is not a redirect.** It opens a chat with the PlanVortex bot, and nobody comes back from it: the account is born minutes later, from the bot being added to a channel, and it is announced over the WebSocket. Open it in another tab and keep listening; redirect to it and there is nobody left to tell.",
+        "description": "The authorization URL of each network, so the user can connect an account to this organization.\n\n**A network that cannot produce a link simply does not appear.** That is a legitimate answer, not a failure: it is what happens with `discord` in an organization that has not saved its own bot credentials yet (see `PUT /organizations/{id_organization}/social_credentials/{social_network}`).\n\n**An app cannot call this.** Connecting a social account is an OAuth flow with a person in front of it, so this endpoint only accepts a user token or a temporal connect token; with app credentials it answers error 519. The way an integration does it is to issue a temporal connect token with `GET /organizations/{id_organization}/temporal_connect_token` and hand it to its end user.\n\n**Read `authorization`, not `link`.** Ten of the twelve networks are `redirect` and you send the person to `link`. Two are not, and neither of them fails visibly if you treat it as one:\n\n• **WhatsApp is not a URL at all.** Its sign-up is Meta's Embedded Signup, a popup you raise with the Facebook JavaScript SDK, so its `link` is an empty string and everything you need to open that popup travels in `authorization`. A client that loops over the list and redirects to `link` sends its user to its own page.\n• **Telegram has a link and still is not a redirect.** It opens a chat with the PlanVortex bot, and nobody comes back from it: the account is born minutes later, from the bot being added to a channel, and it is announced over the WebSocket. Open it in another tab and keep listening; redirect to it and there is nobody left to tell.",
         "operationId": "getConnectLinks",
         "x-planvortex-identity": [
           "current_user",
@@ -1000,7 +1000,7 @@
           "ai_plans"
         ],
         "summary": "List AI publication plans",
-        "description": "Return the organization's AI plans ordered by creation date (desc), paginated. Requires the ai_plans:read permission.\n\n**Cancelled plans are not listed.** Deleting a plan sets it to `cancelled` rather than removing it, and this listing filters those out — so a plan you deleted simply stops appearing, while `GET` by id still returns it.\n\nWithout `limit` the whole list comes back.",
+        "description": "Return the organization's AI plans ordered by creation date (desc), paginated. Requires the ai_plans:read permission.\n\n**Active plans by default, archived ones with `archived=true`** — never both at once. Archiving is visibility only (see `POST .../archive`): the plan leaves this listing and keeps every publication it had.\n\n**Cancelled plans are not listed either.** Deleting a plan sets it to `cancelled` rather than removing it, and this listing filters those out — so a plan you deleted simply stops appearing, while `GET` by id still returns it.\n\nWithout `limit` the whole list comes back.",
         "operationId": "getAiPlans",
         "x-planvortex-identity": [
           "current_user",
@@ -1031,6 +1031,16 @@
             "schema": {
               "type": "integer"
             }
+          },
+          {
+            "name": "archived",
+            "in": "query",
+            "description": "`true` returns the archived plans instead of the active ones. Anything other than the literal string `true` is read as false.",
+            "required": false,
+            "schema": {
+              "type": "boolean",
+              "default": false
+            }
           }
         ],
         "responses": {
@@ -1113,8 +1123,8 @@
         "tags": [
           "ai_plans"
         ],
-        "summary": "Cancel / discard an AI publication plan",
-        "description": "Discard the plan and delete its generated draft publications. AI credits already spent on generation are NOT refunded (same criterion as X: if the provider charged, we charge). Requires the ai_plans:delete permission.",
+        "summary": "Delete an AI publication plan and its pending publications",
+        "description": "Delete the plan **and every publication of it that has not gone out yet**: the generated drafts and, if the plan was already validated, whatever was still scheduled. Two states are deliberately left alone: `sended`, because it is already live on the network and deleting it here would only lose its history while the post stays up, and `publishing`, which the publishing job holds at that very moment.\n\nAI credits already spent on generation are NOT refunded (same criterion as X: if the provider charged, we charge). A plan being generated cannot be deleted (state `generating`, error 2102): wait for the job to finish.\n\nTo keep the plan and its publications and only take it out of the listing, archive it instead (`POST .../archive`). Requires the ai_plans:delete permission.",
         "operationId": "deleteAiPlan",
         "x-planvortex-identity": [
           "current_user",
@@ -1258,6 +1268,106 @@
         }
       }
     },
+    "/clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}/archive": {
+      "post": {
+        "tags": [
+          "ai_plans"
+        ],
+        "summary": "Archive an AI publication plan",
+        "description": "Take the plan out of the default listing and move it to the archived one (`GET .../ai_plans?archived=true`). It is **visibility only**: no publication is touched — anything scheduled keeps publishing — no credits are refunded, and nothing is cancelled. It is reversible with `POST .../unarchive` and valid in **any state**, `generating` included, because it does not interrupt the generation job.\n\nArchiving an already archived plan just refreshes `archived_date`. Requires the ai_plans:update permission.",
+        "operationId": "archiveAiPlan",
+        "x-planvortex-identity": [
+          "current_user",
+          "current_app"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AiPlansidClient"
+          },
+          {
+            "$ref": "#/components/parameters/AiPlansidOrganization"
+          },
+          {
+            "$ref": "#/components/parameters/AiPlansidAiPlan"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation. Returns the plan with `archived_date` set.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AiPlansAiPlanOne"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `2100` | AI plan doesn't exist. The identifier is invalid or doesn't exist. |\n| `521` | Invalid client. The identifier is invalid or doesn't exist |",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unhandled error by the server"
+          }
+        }
+      }
+    },
+    "/clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}/unarchive": {
+      "post": {
+        "tags": [
+          "ai_plans"
+        ],
+        "summary": "Unarchive an AI publication plan",
+        "description": "Return the plan to the default listing: `archived_date` is cleared. Unarchiving a plan that was not archived does nothing and answers 200. Requires the ai_plans:update permission.",
+        "operationId": "unarchiveAiPlan",
+        "x-planvortex-identity": [
+          "current_user",
+          "current_app"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AiPlansidClient"
+          },
+          {
+            "$ref": "#/components/parameters/AiPlansidOrganization"
+          },
+          {
+            "$ref": "#/components/parameters/AiPlansidAiPlan"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation. Returns the plan without `archived_date`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AiPlansAiPlanOne"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `2100` | AI plan doesn't exist. The identifier is invalid or doesn't exist. |\n| `521` | Invalid client. The identifier is invalid or doesn't exist |",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Unhandled error by the server"
+          }
+        }
+      }
+    },
     "/clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}/publications/{id_publication}/regenerate": {
       "post": {
         "tags": [
@@ -1762,7 +1872,8 @@
                   "google_business",
                   "bluesky",
                   "discord",
-                  "telegram"
+                  "telegram",
+                  "threads"
                 ]
               }
             }
@@ -3487,7 +3598,7 @@
           "comments"
         ],
         "summary": "The inbox: first-level comments across the whole organization",
-        "description": "Served from PlanVortex's database, so it costs nothing and calls no social network. It is a **snapshot**: `collected_date` says when each row was last read. Open a thread to see what the network says right now.\n\nOrdered by `creation_date` descending — the date on the network, not the date we collected it — so rows from nine networks interleave correctly.\n\n**On `telegram` the inbox starts the day the channel was connected.** The Bot API has no way to read the past: a bot only learns what happens while it is inside, so nothing written before the connection exists here and never will. Say so in your UI — an inbox that opens empty on a busy channel reads like a failure.\n\n**Your own replies are not in here.** Anything with `author.is_own: true` is filtered out: what you wrote is not incoming mail. They are still stored, and they do show up in the thread.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
+        "description": "Served from PlanVortex's database, so it costs nothing and calls no social network. It is a **snapshot**: `collected_date` says when each row was last read. Open a thread to see what the network says right now.\n\nOrdered by `creation_date` descending — the date on the network, not the date we collected it — so rows from ten networks interleave correctly.\n\n**On `telegram` the inbox starts the day the channel was connected.** The Bot API has no way to read the past: a bot only learns what happens while it is inside, so nothing written before the connection exists here and never will. Say so in your UI — an inbox that opens empty on a busy channel reads like a failure.\n\n**Your own replies are not in here.** Anything with `author.is_own: true` is filtered out: what you wrote is not incoming mail. They are still stored, and they do show up in the thread.\n\nRequires the `comments:read` permission (`client_organization_comments:read` for apps) and a paid plan.",
         "operationId": "getComments",
         "x-planvortex-identity": [
           "current_user",
@@ -3976,7 +4087,7 @@
           "catalog"
         ],
         "summary": "What every network supports",
-        "description": "The full matrix network → capabilities. It is the **single source of truth** about what a network can do: the catalogue publishes it, the backend checks it before acting, and your integration should filter its account pickers with it rather than keeping a list of its own.\n\n`comments` is the coarse gate — whether the network has comments at all. Which *actions* it allows on one is a finer question and lives in `GET /social_comment_actions`, because the shape here is `{[capability]: boolean}` and nesting an object inside would break it.\n\nToday nine networks answer `comments: true`: Facebook, Instagram, LinkedIn, X, YouTube, Google Business, Bluesky, Discord and Telegram. TikTok and WhatsApp answer `false`, for reasons of theirs and not ours.\n\nA `true` here is about the **network**, not about one account of it: a Telegram channel with no linked discussion group answers 965 on its comments even though the network has them.\n\nOnly needs authentication.",
+        "description": "The full matrix network → capabilities. It is the **single source of truth** about what a network can do: the catalogue publishes it, the backend checks it before acting, and your integration should filter its account pickers with it rather than keeping a list of its own.\n\n`comments` is the coarse gate — whether the network has comments at all. Which *actions* it allows on one is a finer question and lives in `GET /social_comment_actions`, because the shape here is `{[capability]: boolean}` and nesting an object inside would break it.\n\nToday ten networks answer `comments: true`: Facebook, Instagram, Threads, LinkedIn, X, YouTube, Google Business, Bluesky, Discord and Telegram. TikTok and WhatsApp answer `false`, for reasons of theirs and not ours.\n\nA `true` here is about the **network**, not about one account of it: a Telegram channel with no linked discussion group answers 965 on its comments even though the network has them.\n\nOnly needs authentication.",
         "operationId": "getSocialCapabilities",
         "x-planvortex-identity": [
           "current_user",
@@ -4034,7 +4145,7 @@
           "catalog"
         ],
         "summary": "What each network lets you do to a comment",
-        "description": "The fine-grained matrix: reply, hide, delete your own, delete somebody else's — network by network. Read it before painting controls. Networks without comments answer `false` to all four.\n\nThe differences are real and each has a reason in the network's own API:\n\n| Network | reply | hide | delete_own | delete_others |\n| --- | --- | --- | --- | --- |\n| `facebook` | yes | yes | yes | yes |\n| `instagram` | yes | yes | yes | **no** — Instagram only lets you hide someone else's |\n| `youtube` | yes | yes | yes | yes — the channel owner really does moderate |\n| `linkedin` | yes | **no** — there is no hide endpoint | yes | yes |\n| `twitter` | yes | yes | yes | **no** — you cannot delete another account's post |\n| `google_business` | yes | **no** | yes — **your reply**, never the review | **no** |\n| `bluesky` | yes | yes — through the post's `threadgate` | yes | **no** — the reply lives in somebody else's repository |\n| `discord` | yes | **no** — Discord has no hide, only delete | yes | yes |\n| `telegram` | yes | **no** — Telegram has no hide either | yes | yes — with the bot as an admin of the discussion group, otherwise error 969 |\n| `tiktok`, `whatsapp` | no | no | no | no |\n\nOnly needs authentication.",
+        "description": "The fine-grained matrix: reply, hide, delete your own, delete somebody else's — network by network. Read it before painting controls. Networks without comments answer `false` to all four.\n\nThe differences are real and each has a reason in the network's own API:\n\n| Network | reply | hide | delete_own | delete_others |\n| --- | --- | --- | --- | --- |\n| `facebook` | yes | yes | yes | yes |\n| `instagram` | yes | yes | yes | **no** — Instagram only lets you hide someone else's |\n| `youtube` | yes | yes | yes | yes — the channel owner really does moderate |\n| `linkedin` | yes | **no** — there is no hide endpoint | yes | yes |\n| `twitter` | yes | yes | yes | **no** — you cannot delete another account's post |\n| `google_business` | yes | **no** | yes — **your reply**, never the review | **no** |\n| `bluesky` | yes | yes — through the post's `threadgate` | yes | **no** — the reply lives in somebody else's repository |\n| `discord` | yes | **no** — Discord has no hide, only delete | yes | yes |\n| `telegram` | yes | **no** — Telegram has no hide either | yes | yes — with the bot as an admin of the discussion group, otherwise error 969 |\n| `threads` | yes | yes | yes | **no** — deleting somebody else's reply is not a permission you lack, it is a call that does not exist in the API |\n| `tiktok`, `whatsapp` | no | no | no | no |\n\nOnly needs authentication.",
         "operationId": "getSocialCommentActions",
         "x-planvortex-identity": [
           "current_user",
@@ -9400,7 +9511,7 @@
         "required": [
           "type"
         ],
-        "description": "**How** an account of this network is authorized, which is not always \"send the user to this URL\".\n\nNine of the eleven networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:\n\n• **WhatsApp.** Its sign-up is Meta's *Embedded Signup*: a popup raised by the Facebook JavaScript SDK from your own page, which returns — over `postMessage` — session data (`waba_id`, `phone_number_id`) that no query string carries. Its `link` is therefore an empty string.\n• **Telegram.** There is no OAuth here: no consent screen, no `code`, no account token. `link` opens a private chat with the PlanVortex bot, the person then adds that bot to their channel, and **the account is created from that event**, not from any request of yours. Which means the connection cannot be finished by calling `GET /organizations/{id_organization}/account-connect/telegram` — see that endpoint.\n\nBranch on `authorization.type`, never on whether `link` is empty.",
+        "description": "**How** an account of this network is authorized, which is not always \"send the user to this URL\".\n\nTen of the twelve networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:\n\n• **WhatsApp.** Its sign-up is Meta's *Embedded Signup*: a popup raised by the Facebook JavaScript SDK from your own page, which returns — over `postMessage` — session data (`waba_id`, `phone_number_id`) that no query string carries. Its `link` is therefore an empty string.\n• **Telegram.** There is no OAuth here: no consent screen, no `code`, no account token. `link` opens a private chat with the PlanVortex bot, the person then adds that bot to their channel, and **the account is created from that event**, not from any request of yours. Which means the connection cannot be finished by calling `GET /organizations/{id_organization}/account-connect/telegram` — see that endpoint.\n\nBranch on `authorization.type`, never on whether `link` is empty.",
         "properties": {
           "type": {
             "type": "string",
@@ -9597,6 +9708,11 @@
             ],
             "description": "State machine: pending -> generating -> generated -> validated | failed | cancelled. Poll the plan while state is pending or generating."
           },
+          "archived_date": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When the plan was archived. Absent means it is active, which is how every plan created before archiving existed comes back.\n\nIt is a field of its own and NOT a value of `state` on purpose: `state` is the generation lifecycle and archiving is orthogonal to it — a `validated` plan that already published gets archived just like a `failed` one. Inside the enum you would have to decide which state it returns to when unarchived, and that question has no answer.\n\nArchiving is visibility only: it takes the plan out of the default listing and touches no publication. Anything it had scheduled keeps publishing."
+          },
           "orchestrator_result": {
             "type": "object",
             "description": "Raw plan returned by the orchestrator, kept for audit (before validation/trimming)."
@@ -10399,7 +10515,7 @@
                 "$ref": "#/components/schemas/CatalogSocialLimitsMap"
               }
             ],
-            "description": "Maximum length of a publication's text. Bluesky counts graphemes, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit.\n\nOn Telegram there are **two numbers for the same field**: `telegram` (4.096) while the publication is text only, and `telegram_media` (1.024) the moment it carries an image or a video, because then the text is a media caption and not a message. Switch the counter when the file is attached, not when publish is pressed."
+            "description": "Maximum length of a publication's text. **Bluesky and Threads count GRAPHEMES**, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit. The difference is not academic: an emoji is one grapheme and two `String.length` units, so counting a Threads post with `.length` rejects at 250 emojis what the network publishes happily at 500.\n\nOn Telegram there are **two numbers for the same field**: `telegram` (4.096) while the publication is text only, and `telegram_media` (1.024) the moment it carries an image or a video, because then the text is a media caption and not a message. Switch the counter when the file is attached, not when publish is pressed."
           },
           "max_post_bytes": {
             "allOf": [
@@ -11142,7 +11258,8 @@
           "google_business",
           "bluesky",
           "discord",
-          "telegram"
+          "telegram",
+          "threads"
         ]
       },
       "CommentsCommentThread": {
@@ -13610,7 +13727,7 @@
       },
       "PublicationStats": {
         "type": "object",
-        "description": "Raw, per-network metrics for a publication. Only the fields that belong to the publication's own social network are returned.\n\n**An absent field is not a zero.** A field is present only when the network actually reported it; `0` means the network measured zero. This matters most on X (Twitter), where metrics are split into groups with different access levels: `public_metrics` (likes, replys, retwets, quotes, bookmarks, impressions) is always available, while clicks, the pre-computed `engagement` and the video playback quartiles come from X's non-public metrics — only for your own posts, within 30 days of publishing, and only if the app is entitled to them. When they are unavailable they are omitted rather than returned as `0`. Do not default missing fields to zero when displaying them.\n\nOn `discord` there are only two: `likes` (the reactions on the message) and `comments` (the messages in its thread). There is no impressions figure anywhere in Discord's API, so engagement is computed over the server's member count.\n\nOn `bluesky` there are no impressions and no reach either — only the public counters — so engagement is computed over followers.\n\nOn `telegram` there are two as well, and **neither of them is asked for**: the Bot API has no method that returns a message's metrics, so `reactions` arrives on its own through the bot and `comments` is counted in PlanVortex's own inbox. There are no impressions, no reach, no views and no forwards to be had anywhere in it, so engagement is computed over followers.",
+        "description": "Raw, per-network metrics for a publication. Only the fields that belong to the publication's own social network are returned.\n\n**An absent field is not a zero.** A field is present only when the network actually reported it; `0` means the network measured zero. This matters most on X (Twitter), where metrics are split into groups with different access levels: `public_metrics` (likes, replys, retwets, quotes, bookmarks, impressions) is always available, while clicks, the pre-computed `engagement` and the video playback quartiles come from X's non-public metrics — only for your own posts, within 30 days of publishing, and only if the app is entitled to them. When they are unavailable they are omitted rather than returned as `0`. Do not default missing fields to zero when displaying them.\n\nOn `discord` there are only two: `likes` (the reactions on the message) and `comments` (the messages in its thread). There is no impressions figure anywhere in Discord's API, so engagement is computed over the server's member count.\n\nOn `bluesky` there are no impressions and no reach either — only the public counters — so engagement is computed over followers.\n\nOn `threads` there are six, and the one that matters is `views`: it is the only one of the four newest networks with something like impressions, so its engagement rate is computed over a real base and not over followers. Sharing arrives split in three — `reposts`, `quotes` and `shares` (outside Threads) — and the three are added into one figure, the same criterion as on X; the breakdown stays in `raw`. A reply is what every other network calls a comment.\n\nOn `telegram` there are two as well, and **neither of them is asked for**: the Bot API has no method that returns a message's metrics, so `reactions` arrives on its own through the bot and `comments` is counted in PlanVortex's own inbox. There are no impressions, no reach, no views and no forwards to be had anywhere in it, so engagement is computed over followers.",
         "properties": {
           "likes": {
             "type": "integer"
@@ -13749,7 +13866,8 @@
               "youtube",
               "bluesky",
               "discord",
-              "telegram"
+              "telegram",
+              "threads"
             ],
             "description": "Network the publication targets. **Required when creating**: the request fails with error 702 if it is missing or not one of these values. It must match the network of the account in the path.\n\nNot every connectable network publishes — a local business listing receives reviews, not posts — so this list is shorter than the one in `GET /social_networks`. Ask `GET /allowed_social_publications` rather than hardcoding it, because it grows."
           },
@@ -14092,7 +14210,8 @@
           "google_business",
           "bluesky",
           "discord",
-          "telegram"
+          "telegram",
+          "threads"
         ],
         "type": "string",
         "description": "A social network supported by PlanVortex.\n\n**This list grows.** Treat it as an open enumeration: a client that rejects an unknown value breaks the day a network is added, which happens several times a year. Not every network does everything — ask `GET /social_capabilities`."

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

{planvortex-0.3.0 → planvortex-0.5.0}/src/planvortex/_generated/models.py

@@ -137,7 +137,7 @@ class AccountsSocialAuthorizationMethod(TypedDict):
     """
     **How** an account of this network is authorized, which is not always "send the user to this URL".
 
-    Nine of the eleven networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:
+    Ten of the twelve networks are `redirect`: open `link` and the network sends the person back to PlanVortex with a code. Two are not:
 
     • **WhatsApp.** Its sign-up is Meta's *Embedded Signup*: a popup raised by the Facebook JavaScript SDK from your own page, which returns — over `postMessage` — session data (`waba_id`, `phone_number_id`) that no query string carries. Its `link` is therefore an empty string.
     • **Telegram.** There is no OAuth here: no consent screen, no `code`, no account token. `link` opens a private chat with the PlanVortex bot, the person then adds that bot to their channel, and **the account is created from that event**, not from any request of yours. Which means the connection cannot be finished by calling `GET /organizations/{id_organization}/account-connect/telegram` — see that endpoint.
@@ -855,6 +855,7 @@ CommentsCommentNetworkName: TypeAlias = Literal[
     "bluesky",
     "discord",
     "telegram",
+    "threads",
 ]
 """
 A network that has comments. Treat it as an open list: a new one is added before your integration hears about it.
@@ -1668,6 +1669,8 @@ class PublicationStats(TypedDict):
 
     On `bluesky` there are no impressions and no reach either — only the public counters — so engagement is computed over followers.
 
+    On `threads` there are six, and the one that matters is `views`: it is the only one of the four newest networks with something like impressions, so its engagement rate is computed over a real base and not over followers. Sharing arrives split in three — `reposts`, `quotes` and `shares` (outside Threads) — and the three are added into one figure, the same criterion as on X; the breakdown stays in `raw`. A reply is what every other network calls a comment.
+
     On `telegram` there are two as well, and **neither of them is asked for**: the Bot API has no method that returns a message's metrics, so `reactions` arrives on its own through the bot and `comments` is counted in PlanVortex's own inbox. There are no impressions, no reach, no views and no forwards to be had anywhere in it, so engagement is computed over followers.
     """
 
@@ -1758,6 +1761,7 @@ class PublicationsPublicationInput(TypedDict):
             "bluesky",
             "discord",
             "telegram",
+            "threads",
         ]
     ]
     """
@@ -1907,6 +1911,7 @@ SocialNetwork: TypeAlias = Literal[
     "bluesky",
     "discord",
     "telegram",
+    "threads",
 ]
 """
 A social network supported by PlanVortex.
@@ -2175,7 +2180,7 @@ class CatalogPlannerTemplate(TypedDict):
 class CatalogSocialLimits(TypedDict):
     characters: CatalogSocialLimitsMap
     """
-    Maximum length of a publication's text. Bluesky counts graphemes, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit.
+    Maximum length of a publication's text. **Bluesky and Threads count GRAPHEMES**, everyone else counts characters — Telegram included, where `String.length` is exactly the right unit. The difference is not academic: an emoji is one grapheme and two `String.length` units, so counting a Threads post with `.length` rejects at 250 emojis what the network publishes happily at 500.
 
     On Telegram there are **two numbers for the same field**: `telegram` (4.096) while the publication is text only, and `telegram_media` (1.024) the moment it carries an image or a video, because then the text is a media caption and not a message. Switch the counter when the file is attached, not when publish is pressed.
     """
@@ -2872,6 +2877,14 @@ class AiPlansAiPlan(TypedDict):
     """
     State machine: pending -> generating -> generated -> validated | failed | cancelled. Poll the plan while state is pending or generating.
     """
+    archived_date: NotRequired[str]
+    """
+    When the plan was archived. Absent means it is active, which is how every plan created before archiving existed comes back.
+
+    It is a field of its own and NOT a value of `state` on purpose: `state` is the generation lifecycle and archiving is orthogonal to it — a `validated` plan that already published gets archived just like a `failed` one. Inside the enum you would have to decide which state it returns to when unarchived, and that question has no answer.
+
+    Archiving is visibility only: it takes the plan out of the default listing and touches no publication. Anything it had scheduled keeps publishing.
+    """
     orchestrator_result: NotRequired[dict[str, Any]]
     """
     Raw plan returned by the orchestrator, kept for audit (before validation/trimming).

{planvortex-0.3.0 → planvortex-0.5.0}/src/planvortex/_shapes.py

@@ -137,7 +137,7 @@ class AccountUpdate(TypedDict):
 
 
 class RedirectAuthorization(TypedDict):
-    """Send the person to the entry's ``link``. Nine of the eleven networks.
+    """Send the person to the entry's ``link``. Ten of the twelve networks.
 
     One of the THREE halves of the ``authorization`` block of a connection link. The generated type
     is a single flat ``TypedDict`` with every field ``NotRequired``, because that is the only way
@@ -255,6 +255,7 @@ class EnableResult(TypedDict):
 PublishableNetwork: TypeAlias = Literal[
     "facebook",
     "instagram",
+    "threads",
     "twitter",
     "linkedin",
     "tiktok",
@@ -264,12 +265,12 @@ PublishableNetwork: TypeAlias = Literal[
     "discord",
     "telegram",
 ]
-"""A network that accepts publications: the ten of the eleven that have a feed.
+"""A network that accepts publications: the eleven of the twelve that have a feed.
 
 ``google_business`` is the one missing, and it is not an oversight: a local listing receives
 reviews, not posts. Sending it raises error 702. It is a **narrower** type than
 ``types.SocialNetwork`` and that is the whole point — an account's ``social_network`` is one of
-eleven and this is one of ten, so handing one straight to the other is a type error even when a
+twelve and this is one of eleven, so handing one straight to the other is a type error even when a
 ``capability="publications"`` filter has already made it impossible at runtime.
 ``types.is_publishable_network`` is what bridges it.
 

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

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import platform
 
-VERSION = "0.3.0"
+VERSION = "0.5.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.3.0 → planvortex-0.5.0}/src/planvortex/resources/accounts.py

@@ -56,7 +56,7 @@ class AsyncAccountsResource(AsyncResource):
         rather than a failure: it is what happens to Discord in an organization that has not saved
         its own bot credentials yet.
 
-        **LOOK AT ``authorization``, NOT AT WHETHER ``link`` IS EMPTY.** Nine of the eleven networks
+        **LOOK AT ``authorization``, NOT AT WHETHER ``link`` IS EMPTY.** Ten of the twelve networks
         are ``redirect`` and the person is sent to ``link``. The other two are not, and neither of them
         fails visibly if you walk the list redirecting to ``link``:
 

{planvortex-0.3.0 → planvortex-0.5.0}/src/planvortex/resources/ai_plans.py

@@ -22,7 +22,13 @@ AND WHAT SURPRISES PEOPLE:
   so Monday/Wednesday/Friday with 3 accounts is 9 publications, not 21.
 - **These routes hang off the CLIENT**, not only off the organization: they carry both identifiers.
 - **Deleting is cancelling.** The plan moves to ``cancelled`` and stops appearing in the listing, but
-  :meth:`AsyncAiPlansResource.get` still returns it.
+  :meth:`AsyncAiPlansResource.get` still returns it. What does go for good are its publications that
+  had not gone out yet: the drafts and, if the plan was already validated, whatever was still
+  scheduled.
+- **Archiving is NOT deleting, and it is the action people are usually after.**
+  :meth:`AsyncAiPlansResource.archive` takes the plan out of the listing and touches no publication
+  — anything scheduled keeps publishing — works in any state and can be undone. The archived ones
+  are read with ``list(..., archived=True)``, never next to the active ones.
 
 THE TEMPLATES: WHAT THE PLAN IS GENERATED FROM
 
@@ -67,7 +73,7 @@ from collections.abc import AsyncIterator
 
 from planvortex._core.pagination import Page, PageParams
 from planvortex._shapes import AiPlanRegenerateResult
-from planvortex.resources.base import AsyncResource, require_id
+from planvortex.resources.base import AsyncResource, Query, require_id
 from planvortex.types import AiPlan, AiPlanCreateRequest, AiPlanCreateResult
 
 
@@ -166,17 +172,27 @@ class AsyncAiPlansResource(AsyncResource):
         *,
         limit: int | None = None,
         offset: int | None = None,
+        archived: bool | None = None,
         timeout: float | None = None,
     ) -> Page[AiPlan]:
-        """The organization's plans, from the newest to the oldest.
+        """The organization's ACTIVE plans, from the newest to the oldest.
 
-        **The cancelled ones do not show up**, and here ``publications`` are identifiers, not the
-        whole publications: for that there is :meth:`get`. With no ``limit`` they all come back.
+        **The cancelled ones do not show up** — nor the archived ones, which are asked for with
+        ``archived=True`` — and here ``publications`` are identifiers, not the whole publications:
+        for that there is :meth:`get`. With no ``limit`` they all come back.
+
+        ``archived`` opens the other cupboard, never both at once: archiving moves a plan somewhere
+        else, it does not put a label on it and leave it where it was.
+
+        .. code-block:: python
+
+            activos = await pv.ai_plans.list(client_id, org_id)
+            guardados = await pv.ai_plans.list(client_id, org_id, archived=True)
         """
         pagina: Page[AiPlan] = await self._list(
             self._path(id_client, id_organization),
             "ai_plans",
-            {"limit": limit, "offset": offset},
+            self._list_query(limit, offset, archived),
             timeout=timeout,
         )
         return pagina
@@ -188,6 +204,7 @@ class AsyncAiPlansResource(AsyncResource):
         *,
         limit: int | None = None,
         offset: int | None = None,
+        archived: bool | None = None,
         timeout: float | None = None,
     ) -> AsyncIterator[AiPlan]:
         """The organization's plans, chaining pages."""
@@ -198,6 +215,7 @@ class AsyncAiPlansResource(AsyncResource):
                 id_organization,
                 limit=params.limit,
                 offset=params.offset,
+                archived=archived,
                 timeout=timeout,
             )
 
@@ -274,6 +292,47 @@ class AsyncAiPlansResource(AsyncResource):
         resultado: AiPlanRegenerateResult = await self._post(ruta, {"target": target}, timeout=timeout)
         return resultado
 
+    async def archive(
+        self,
+        id_client: str,
+        id_organization: str,
+        id_ai_plan: str,
+        *,
+        timeout: float | None = None,
+    ) -> AiPlan:
+        """Archive the plan: it leaves the listing and moves to the archived one
+        (``list(..., archived=True)``).
+
+        It is **visibility only**. No publication is touched — anything scheduled keeps publishing —
+        no credits are refunded and nothing is cancelled, so it works in ANY state, ``generating``
+        included: it does not interrupt the job. Undone with :meth:`unarchive`.
+
+        It is what people are after almost every time they think of "removing" a plan: :meth:`remove`
+        takes the publications that have not gone out with it, and this does not.
+        """
+        plan: AiPlan = await self._post_one(
+            f"{self._one_path(id_client, id_organization, id_ai_plan)}/archive",
+            "ai_plan",
+            timeout=timeout,
+        )
+        return plan
+
+    async def unarchive(
+        self,
+        id_client: str,
+        id_organization: str,
+        id_ai_plan: str,
+        *,
+        timeout: float | None = None,
+    ) -> AiPlan:
+        """Put the plan back in the active listing. On a plan that was not archived it does nothing."""
+        plan: AiPlan = await self._post_one(
+            f"{self._one_path(id_client, id_organization, id_ai_plan)}/unarchive",
+            "ai_plan",
+            timeout=timeout,
+        )
+        return plan
+
     async def remove(
         self,
         id_client: str,
@@ -282,11 +341,28 @@ class AsyncAiPlansResource(AsyncResource):
         *,
         timeout: float | None = None,
     ) -> None:
-        """Cancel the plan. **It does not delete it**: it moves to ``cancelled``, disappears from
-        :meth:`list` and :meth:`get` still returns it.
+        """Delete the plan **and its publications that have not gone out yet**: the generated drafts
+        and, if it had already been validated, whatever was still scheduled. The already published
+        ones stay — deleting them here would not take them off the network, it would only lose their
+        history — and neither is the one being published at that very moment touched.
+
+        The plan itself is not wiped: it moves to ``cancelled``, disappears from :meth:`list` and
+        :meth:`get` still returns it. Spent credits are not refunded and a ``generating`` plan cannot
+        be deleted (2102): wait for the job to finish.
+
+        To stop seeing it without losing anything, :meth:`archive`.
         """
         await self._delete(self._one_path(id_client, id_organization, id_ai_plan), timeout=timeout)
 
+    def _list_query(self, limit: int | None, offset: int | None, archived: bool | None) -> Query:
+        return {
+            "limit": limit,
+            "offset": offset,
+            # El servidor enciende el filtro con el literal "true": mandar `archived=false` pediria
+            # lo mismo que no mandar nada, asi que un `False` se omite en vez de viajar como ruido.
+            "archived": True if archived else None,
+        }
+
     def _path(self, id_client: str, id_organization: str) -> str:
         cliente = require_id(id_client, "id_client")
         organizacion = require_id(id_organization, "id_organization")