planvortex 0.12.0__tar.gz → 0.13.0__tar.gz

{planvortex-0.12.0 → planvortex-0.13.0}/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.13.0] - 2026-10-03
+
+### Added
+
+- **Two webhook events for AI plans: `ai_plan_generated` and `ai_plan_failed`**, typed as
+  `AiPlanChange` (with `AiPlanFailure` for its `error`) and narrowed with `is_ai_plan_change` in
+  `planvortex.webhooks`. When a plan finishes, your app's `webhook_url` now hears about it, so you
+  no longer have to poll `pv.ai_plans.get` every few seconds. The change carries ids and numbers
+  only (`id_ai_plan`, `state`, `template`, `total_publications`, `credits_spent`, how many
+  `warnings`, and `error` with its `code` and `message` on a failure), never the prompt or the
+  generated text: read the plan once when it arrives. Each plan sends one of the two, never a
+  `failed` followed by a `generated`. Deliveries are not retried, so keep polling as the fallback
+  if your endpoint can be down.
+
+- **`pending_publish` on `Publication`**, with the `PublicationPending` type to name it. An
+  Instagram video that Meta takes more than ~30 seconds to process now comes back in state
+  `publishing` with this object, and PlanVortex keeps asking Instagram in the background for up to
+  10 minutes. **Wait and read the publication again after `next_check`; do not retry it or create
+  it again**, or the video goes out twice. While it is present the publication cannot be updated
+  (error 921). It is read-only: nothing new to send.
+
+### Changed
+
+- The reference no longer says that an X publication left without credits (940) fires your app's
+  webhook. It never did: no webhook announces publications, so read the publication to find out.
+- `publication_errors` documents two new Instagram codes: **998** (Meta rejected the file, so
+  retrying it unchanged fails the same way) and **999** (Meta ran out of time, and a retry usually
+  works).
+
 ## [0.12.0] - 2026-10-02
 
 **Your app can show its own account picker.** Until now the person connecting a social account

{planvortex-0.12.0 → planvortex-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: planvortex
-Version: 0.12.0
+Version: 0.13.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/
@@ -369,13 +369,19 @@ would rather do it in two steps, `verify_webhook_signature(payload, signature, s
 plain `True`/`False` and `parse_webhook_body(payload)` gives you the changes.
 
 Narrow with the predicates — `is_account_state_change`, `is_message_change`, `is_comment_change`,
-`is_integration_error_change` — and let anything else fall through: **the event list grows**, and a
+`is_integration_error_change`, `is_ai_plan_change` — and let anything else fall through: **the event list grows**, and a
 `field` this release has never heard of is not an error.
 
 **PlanVortex does not retry a failed delivery.** A 500 of yours loses the event, so if your work is
 slow, queue it and answer — and use `pv.comments.list` / `pv.messages.list` to catch up on anything
 you missed.
 
+**An AI plan tells you when it is done.** `ai_plan_generated` and `ai_plan_failed` arrive when a plan
+finishes, so you do not have to poll `pv.ai_plans.get` every few seconds: read the plan once when
+one of them comes in. They carry ids and numbers only (`id_ai_plan`, `state`, how many `warnings`,
+and `error` on a failure), never the prompt or the generated text. If your endpoint was down,
+`pv.ai_plans.get` still tells you how the plan ended.
+
 ## The whole API, in fourteen resources
 
 `pv.catalog` · `pv.clients` · `pv.organizations` · `pv.accounts` · `pv.uploads` · `pv.publications`

{planvortex-0.12.0 → planvortex-0.13.0}/README.md

@@ -339,13 +339,19 @@ would rather do it in two steps, `verify_webhook_signature(payload, signature, s
 plain `True`/`False` and `parse_webhook_body(payload)` gives you the changes.
 
 Narrow with the predicates — `is_account_state_change`, `is_message_change`, `is_comment_change`,
-`is_integration_error_change` — and let anything else fall through: **the event list grows**, and a
+`is_integration_error_change`, `is_ai_plan_change` — and let anything else fall through: **the event list grows**, and a
 `field` this release has never heard of is not an error.
 
 **PlanVortex does not retry a failed delivery.** A 500 of yours loses the event, so if your work is
 slow, queue it and answer — and use `pv.comments.list` / `pv.messages.list` to catch up on anything
 you missed.
 
+**An AI plan tells you when it is done.** `ai_plan_generated` and `ai_plan_failed` arrive when a plan
+finishes, so you do not have to poll `pv.ai_plans.get` every few seconds: read the plan once when
+one of them comes in. They carry ids and numbers only (`id_ai_plan`, `state`, how many `warnings`,
+and `error` on a failure), never the prompt or the generated text. If your endpoint was down,
+`pv.ai_plans.get` still tells you how the plan ended.
+
 ## The whole API, in fourteen resources
 
 `pv.catalog` · `pv.clients` · `pv.organizations` · `pv.accounts` · `pv.uploads` · `pv.publications`

{planvortex-0.12.0 → planvortex-0.13.0}/openapi/planvortex.openapi.json

@@ -1359,7 +1359,7 @@
           "ai_plans"
         ],
         "summary": "Create an AI publication plan",
-        "description": "Create a weekly AI publication plan. The plan is queued in state 'pending' and generated asynchronously by the generate-ai-plans job; poll GET by id while state is pending or generating. Validations at creation: the client plan allows AI (it contracts AI credits; Free does not), the accounts belong to the organization, there are enough AI credits for the deterministic base cost (orchestration + target texts), and there is room in the organization's monthly publication limit. Returns the created plan together with the deterministic cost estimate. Requires the ai_plans:create permission. Since the plan can be generated from a SOURCE (`template` + `source`), part of that validation is the source itself: the article is downloaded, the catalogue is read live and the product pictures are copied — all of it inside this request, so what does not work fails with the user in front of it. A plan whose source did not fit in the week is still created, and says so in ai_plan.warnings (2117). With a Pinterest account in the plan, two more checks run at creation: every Pinterest account needs its board in `destinations` (2118), and a configuration that would leave pins without an image is refused (2119).",
+        "description": "Create a weekly AI publication plan. The plan is queued in state 'pending' and generated asynchronously by the generate-ai-plans job. When it finishes, your app's `webhook_url` receives `ai_plan_generated` or `ai_plan_failed` (the payload is in the comments specification, `AiPlanWebhookChange`); without a webhook, poll GET by id while state is pending or generating. The webhook is best effort and not retried, so the GET is still the source of truth. Validations at creation: the client plan allows AI (it contracts AI credits; Free does not), the accounts belong to the organization, there are enough AI credits for the deterministic base cost (orchestration + target texts), and there is room in the organization's monthly publication limit. Returns the created plan together with the deterministic cost estimate. Requires the ai_plans:create permission. Since the plan can be generated from a SOURCE (`template` + `source`), part of that validation is the source itself: the article is downloaded, the catalogue is read live and the product pictures are copied — all of it inside this request, so what does not work fails with the user in front of it. A plan whose source did not fit in the week is still created, and says so in ai_plan.warnings (2117). With a Pinterest account in the plan, two more checks run at creation: every Pinterest account needs its board in `destinations` (2118), and a configuration that would leave pins without an image is refused (2119).",
         "operationId": "addAiPlan",
         "x-planvortex-identity": [
           "current_user",
@@ -1674,7 +1674,7 @@
           "ai_plans"
         ],
         "summary": "Get an AI publication plan by id",
-        "description": "Return a single AI plan with its generated publications populated. This is the endpoint clients poll while state is pending or generating to detect when generation finishes. Requires the ai_plans:read permission.",
+        "description": "Return a single AI plan with its generated publications populated. Read it when your app receives `ai_plan_generated` or `ai_plan_failed`. Without a webhook, this is the endpoint to poll while state is pending or generating. The webhook is not retried, so if your endpoint was down when the plan finished, this GET still tells you how it ended. Requires the ai_plans:read permission.",
         "operationId": "getAiPlan",
         "x-planvortex-identity": [
           "current_user",
@@ -1873,7 +1873,7 @@
           "ai_plans"
         ],
         "summary": "Retry a failed AI publication plan",
-        "description": "Re-queue a failed plan: it goes back to state 'pending' (attempts and error reset) and the background job regenerates it with the SAME data (prompt, accounts, options). Poll the plan while state is pending or generating, as after creation. Only valid from state 'failed'. Already-spent credits are NOT refunded and a new generation spends again; drafts left over from the failed attempt are discarded by the generation itself. If the failure was a business error (no AI credits, no monthly publication slots), retrying will fail the same way. Requires the ai_plans:update permission.",
+        "description": "Re-queue a failed plan: it goes back to state 'pending' (attempts and error reset) and the background job regenerates it with the SAME data (prompt, accounts, options). As after creation, the end arrives on your webhook as `ai_plan_generated` or `ai_plan_failed`; without one, poll the plan while state is pending or generating. Only valid from state 'failed'. Already-spent credits are NOT refunded and a new generation spends again; drafts left over from the failed attempt are discarded by the generation itself. If the failure was a business error (no AI credits, no monthly publication slots), retrying will fail the same way. Requires the ai_plans:update permission.",
         "operationId": "retryAiPlan",
         "x-planvortex-identity": [
           "current_user",
@@ -10503,7 +10503,7 @@
           "publications"
         ],
         "summary": "Create new publications",
-        "description": "Create new publications. For X (Twitter) accounts, paid actions consume the client's monthly X credit pool (shared across organizations). When a publication is sent immediately, the required credits are checked before publishing and only charged on success. A tweet costs 15 credits, or 200 credits if its text contains a link. Link detection uses the same rule the backend applies: an http(s):// URL, a www. host, or a bare domain with a recognized TLD (regex TWITTER_LINK_REGEX). A scheduled publication does not consume credits when created; it is charged when the background job publishes it. If there are not enough credits at publish time the scheduled publication is left in state 'withErrors' with publication_errors.code = 940 and the client-app webhook is fired (it is never thrown). Publishing immediately without enough credits returns error 940.",
+        "description": "Create new publications. For X (Twitter) accounts, paid actions consume the client's monthly X credit pool (shared across organizations). When a publication is sent immediately, the required credits are checked before publishing and only charged on success. A tweet costs 15 credits, or 200 credits if its text contains a link. Link detection uses the same rule the backend applies: an http(s):// URL, a www. host, or a bare domain with a recognized TLD (regex TWITTER_LINK_REGEX). A scheduled publication does not consume credits when created; it is charged when the background job publishes it. If there are not enough credits at publish time the scheduled publication is left in state 'withErrors' with publication_errors.code = 940 (it is never thrown, and no webhook announces it: read the publication to find out). Publishing immediately without enough credits returns error 940.\n\n**An Instagram video can come back in state `publishing`, and that is not an error.** Instagram processes a video before it can be published, and the request waits about 30 seconds for it. If Meta has not finished by then, the response carries `state: \"publishing\"` and a `pending_publish` object, and PlanVortex keeps asking Instagram about once a minute in the background, for up to 10 minutes. Read the publication again (`GET /organizations/{id_organization}/publish/{id_publication}`) after `pending_publish.next_check` until it is `sended` or `withErrors`. **Do not retry it or create it again**: the first one is still on its way, and a second one would publish the video twice.",
         "operationId": "addPublication",
         "x-planvortex-identity": [
           "current_user",
@@ -10942,7 +10942,7 @@
             }
           },
           "400": {
-            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `917` | Publication doesn't exists |\n| `935` | Invalid publication |\n| `921` | Can't update a publication already sended |\n| `940` | X (Twitter) credits exhausted. Not enough monthly credits to publish this tweet (same link detection and 15/200 tariff as on create). Response data: { used, limit }. |\n| `523` | Invalid application |",
+            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `917` | Publication doesn't exists |\n| `935` | Invalid publication |\n| `921` | Can't update a publication already sended, **or one the network is still processing** (state `publishing` with `pending_publish`; then `data.state` is `publishing`). Editing it would publish it twice. It can be edited again if it fails. |\n| `940` | X (Twitter) credits exhausted. Not enough monthly credits to publish this tweet (same link detection and 15/200 tariff as on create). Response data: { used, limit }. |\n| `523` | Invalid application |",
             "content": {
               "application/json": {
                 "schema": {
@@ -10978,7 +10978,7 @@
           "publications"
         ],
         "summary": "Delete publication by identifier",
-        "description": "Delete publication by identifier. It stops being readable by identifier afterwards, so deleting twice answers error 917. For an already-sent X (Twitter) publication, removing the tweet on X is a paid action that consumes 15 X credits; it is only removed on X when there are enough credits. Returns error 940 when the X credit pool is exhausted.\n\n**On Telegram there is a 48-hour window.** Past it the Bot API refuses to delete a message whatever the bot's role is, and the answer is error 966 with `published_date` and `max_hours` in `data` — so the sensible thing is to grey the button out rather than offer it and fail. Error 969 is the other case: the bot is no longer allowed to delete there. And an album is several messages: all of them go, or the post would be left half-published in the channel.",
+        "description": "Delete publication by identifier. It stops being readable by identifier afterwards, so deleting twice answers error 917. For an already-sent X (Twitter) publication, removing the tweet on X is a paid action that consumes 15 X credits; it is only removed on X when there are enough credits. Returns error 940 when the X credit pool is exhausted.\n\n**On Telegram there is a 48-hour window.** Past it the Bot API refuses to delete a message whatever the bot's role is, and the answer is error 966 with `published_date` and `max_hours` in `data` — so the sensible thing is to grey the button out rather than offer it and fail. Error 969 is the other case: the bot is no longer allowed to delete there. And an album is several messages: all of them go, or the post would be left half-published in the channel.\n\n**Deleting a publication that is still `publishing` with `pending_publish` stops it**: PlanVortex stops asking Instagram and never publishes it, unless the check running at that very moment has already done so.",
         "operationId": "deletePublication",
         "x-planvortex-identity": [
           "current_user",
@@ -11054,7 +11054,7 @@
           "publications"
         ],
         "summary": "Retry a failed publication",
-        "description": "Sends a publication that ended in state `withErrors` to its social network again, WITHOUT changing its content.\n\nThe publication is sent during the request, so the response already carries the outcome: `state: \"sended\"` if it went out, or `state: \"withErrors\"` with the errors of THIS attempt if it failed again. A scheduled publication whose date has not arrived yet goes back to `ready` and the scheduler picks it up at its time.\n\nEvery accepted call spends one retry, even when the publication fails again — what the endpoint promises is an attempt, not a success. The limit is `max_retries`, also served by `GET /publication_limits`. Once it is spent the way to try again is to update the publication (`PUT`), which resets the counter to 0, or to create a new one.",
+        "description": "Sends a publication that ended in state `withErrors` to its social network again, WITHOUT changing its content.\n\nThe publication is sent during the request, so the response already carries the outcome: `state: \"sended\"` if it went out, or `state: \"withErrors\"` with the errors of THIS attempt if it failed again. An Instagram video can also come back in `publishing` with `pending_publish`: the attempt goes on in the background, and the retry is already spent (see `pending_publish` in `Publication`).\n\nOn Instagram, a retry is worth it after a **999** (Meta ran out of time) and pointless after a **998** (Meta rejected the file): change the file with a `PUT` first. A scheduled publication whose date has not arrived yet goes back to `ready` and the scheduler picks it up at its time.\n\nEvery accepted call spends one retry, even when the publication fails again — what the endpoint promises is an attempt, not a success. The limit is `max_retries`, also served by `GET /publication_limits`. Once it is spent the way to try again is to update the publication (`PUT`), which resets the counter to 0, or to create a new one.",
         "operationId": "retryPublication",
         "x-planvortex-identity": [
           "current_user",
@@ -11893,7 +11893,7 @@
             }
           },
           "400": {
-            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `917` | Publication doesn't exists |\n| `935` | Invalid publication |\n| `921` | Can't update a publication already sended |\n| `940` | X (Twitter) credits exhausted. Not enough monthly credits to publish this tweet (same link detection and 15/200 tariff as on create). Response data: { used, limit }. |\n| `523` | Invalid application |",
+            "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `1101` | Invalid organization |\n| `917` | Publication doesn't exists |\n| `935` | Invalid publication |\n| `921` | Can't update a publication already sended, **or one the network is still processing** (state `publishing` with `pending_publish`; then `data.state` is `publishing`). Editing it would publish it twice. It can be edited again if it fails. |\n| `940` | X (Twitter) credits exhausted. Not enough monthly credits to publish this tweet (same link detection and 15/200 tariff as on create). Response data: { used, limit }. |\n| `523` | Invalid application |",
             "content": {
               "application/json": {
                 "schema": {
@@ -12537,7 +12537,7 @@
           "webhooks"
         ],
         "summary": "A change happened (notification to your app)",
-        "description": "PlanVortex `POST`s to the `webhook_url` of your client app when something happens. **The body is an array of changes**, and each one carries `field` telling you what it is — switch on it and ignore what you do not handle, because the list grows with the product.\n\nTwo shapes travel in that array. A change on an **account** (`WebhookChange`) always carries `id_account`, `id_organization` and `social_network`. A change on an **integration** (`IntegrationWebhookChange`) carries none of those, because an integration hangs off the organization and not off any account.\n\nThe events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments` and `integration_error`.\n\n### Comments\n\n`field: \"comments\"` is the one for this section, and the comment itself travels in **`commentObj`** — a property of its own, never in `messageObj`. That is deliberate: a comment is not a message, it has no contact and it hangs off a publication. A consumer that only understands messages sees `commentObj` as absent and ignores the change, which is exactly what should happen.\n\n**Which networks arrive this way:** Facebook and Instagram, because Meta pushes them. YouTube, LinkedIn and Google Business have no comment webhook, so those are polled by a background job and appear in the inbox within a few hours rather than instantly. X is polled too, and only when the organization turns it on, because reading replies there is billed per unit.\n\n**Meta repeats deliveries.** The same comment can arrive more than once; the backend is idempotent about it and so should you be — deduplicate on `commentObj.external_id`.\n\n### Verifying the signature\n\nEvery delivery carries the body signed with your app's secret, twice:\n\n- `x-hub-signature`: `sha1=<hmac>`\n- `x-hub-signature-256`: `sha256=<hmac>`\n\nCompute the HMAC over the **raw** request body — not over a re-serialized copy of the parsed JSON — and compare in constant time. Prefer the sha256 header.\n\nDelivery is best effort: PlanVortex does not retry a webhook that fails.",
+        "description": "PlanVortex `POST`s to the `webhook_url` of your client app when something happens. **The body is an array of changes**, and each one carries `field` telling you what it is — switch on it and ignore what you do not handle, because the list grows with the product.\n\nThree shapes travel in that array. A change on an **account** (`WebhookChange`) always carries `id_account`, `id_organization` and `social_network`. A change on an **integration** (`IntegrationWebhookChange`) and the end of an **AI plan** (`AiPlanWebhookChange`) carry none of those, because they hang off the organization and not off any account.\n\nThe events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments`, `integration_error`, `ai_plan_generated` and `ai_plan_failed`.\n\n### Comments\n\n`field: \"comments\"` is the one for this section, and the comment itself travels in **`commentObj`** — a property of its own, never in `messageObj`. That is deliberate: a comment is not a message, it has no contact and it hangs off a publication. A consumer that only understands messages sees `commentObj` as absent and ignores the change, which is exactly what should happen.\n\n**Which networks arrive this way:** Facebook and Instagram, because Meta pushes them. YouTube, LinkedIn and Google Business have no comment webhook, so those are polled by a background job and appear in the inbox within a few hours rather than instantly. X is polled too, and only when the organization turns it on, because reading replies there is billed per unit.\n\n**Meta repeats deliveries.** The same comment can arrive more than once; the backend is idempotent about it and so should you be — deduplicate on `commentObj.external_id`.\n\n### AI plans\n\n`ai_plan_generated` and `ai_plan_failed` say that a plan has **finished**: it was generated, or it gave up. Instead of polling the plan every few seconds, wait for one of these and then read it once with `GET /clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}`. The change carries ids and numbers only, never the prompt or the generated text, so the publications are in that `GET`.\n\nA plan that hits a transient error goes back to the queue and is retried. That is not an end and sends nothing, so each plan sends **one** of these two events, never a `failed` followed by a `generated`. A plan generated with notices (`warnings` above zero) is still `ai_plan_generated`: it is usable, and the notices are in the plan.\n\nThe event goes to **every** app of the client that has a `webhook_url`, not only to the one that created the plan. And it is not retried: if your endpoint was down when the plan finished, the `GET` still tells you how it ended, so on startup read the plans you were waiting for.\n\n### Verifying the signature\n\nEvery delivery carries the body signed with your app's secret, twice:\n\n- `x-hub-signature`: `sha1=<hmac>`\n- `x-hub-signature-256`: `sha256=<hmac>`\n\nCompute the HMAC over the **raw** request body — not over a re-serialized copy of the parsed JSON — and compare in constant time. Prefer the sha256 header.\n\nDelivery is best effort: PlanVortex does not retry a webhook that fails.",
         "operationId": "onCommentsWebhook",
         "requestBody": {
           "required": true,
@@ -12552,6 +12552,9 @@
                     },
                     {
                       "$ref": "#/components/schemas/CommentsIntegrationWebhookChange"
+                    },
+                    {
+                      "$ref": "#/components/schemas/CommentsAiPlanWebhookChange"
                     }
                   ]
                 }
@@ -13372,7 +13375,7 @@
               "failed",
               "cancelled"
             ],
-            "description": "State machine: pending -> generating -> generated -> validated | failed | cancelled. Poll the plan while state is pending or generating."
+            "description": "State machine: pending -> generating -> generated -> validated | failed | cancelled. Reaching `generated` or `failed` is announced to your app's webhook (`ai_plan_generated`, `ai_plan_failed`); without one, poll the plan while state is pending or generating."
           },
           "archived_date": {
             "type": "string",
@@ -14040,7 +14043,7 @@
           },
           "webhook_url": {
             "type": "string",
-            "description": "Where PlanVortex posts events, when one is configured.\n\n**The body is an array of changes, not a single object**, and it carries two signature headers computed with this app's secret over the **raw** body: `x-hub-signature` (`sha1=<hex>`) and `x-hub-signature-256` (`sha256=<hex>`). Verify against the bytes you received — parsing the JSON and re-serialising it changes them and the signature will not match.\n\nThe events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments` and `integration_error`. The payload is documented in the `comments` specification. Delivery is best effort: PlanVortex does not retry a webhook that fails."
+            "description": "Where PlanVortex posts events, when one is configured.\n\n**The body is an array of changes, not a single object**, and it carries two signature headers computed with this app's secret over the **raw** body: `x-hub-signature` (`sha1=<hex>`) and `x-hub-signature-256` (`sha256=<hex>`). Verify against the bytes you received — parsing the JSON and re-serialising it changes them and the signature will not match.\n\nThe events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments`, `integration_error`, `ai_plan_generated` and `ai_plan_failed`. The payload is documented in the `comments` specification. **Every** app of the client that has a `webhook_url` receives every event, not only the app whose call caused it: with two apps, each event arrives twice. Delivery is best effort: PlanVortex does not retry a webhook that fails."
           },
           "creation_date": {
             "type": "string",
@@ -14894,6 +14897,90 @@
           }
         }
       },
+      "CommentsAiPlanWebhookChange": {
+        "type": "object",
+        "description": "One change in the array PlanVortex posts to your app's `webhook_url`, when an **AI plan finished**: `ai_plan_generated` when it came out, `ai_plan_failed` when it gave up.\n\nLike `IntegrationWebhookChange`, it carries no `id_account` and no `social_network`: a plan can span several networks, and it hangs off the organization. It carries ids and numbers only. Read the plan itself with `GET /clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}`.",
+        "properties": {
+          "field": {
+            "type": "string",
+            "enum": [
+              "ai_plan_generated",
+              "ai_plan_failed"
+            ]
+          },
+          "id_ai_plan": {
+            "type": "string"
+          },
+          "id_organization": {
+            "type": "string"
+          },
+          "state": {
+            "type": "string",
+            "enum": [
+              "generated",
+              "failed"
+            ],
+            "description": "The state the plan finished in. It always matches `field`: `generated` with `ai_plan_generated`, `failed` with `ai_plan_failed`."
+          },
+          "template": {
+            "type": "string",
+            "enum": [
+              "standard",
+              "from_images",
+              "from_text",
+              "from_catalog",
+              "campaign"
+            ],
+            "description": "What the plan was generated from, the same value as `AiPlan.template`."
+          },
+          "total_publications": {
+            "type": "integer",
+            "description": "How many draft publications the plan holds. A failed plan can still hold the drafts of its failed attempt; retrying it discards them."
+          },
+          "credits_spent": {
+            "type": "integer",
+            "description": "AI credits the generation consumed, the same figure as `AiPlan.credits_spent`. A failed plan can have spent credits too, and they are not refunded."
+          },
+          "warnings": {
+            "type": "integer",
+            "description": "**How many** non-blocking notices the plan has, not the notices themselves: those are in `AiPlan.warnings`. Above zero the plan is still generated and usable."
+          },
+          "error": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CommentsAiPlanWebhookError"
+              }
+            ],
+            "description": "Only on `ai_plan_failed`: why the plan failed, the same `code` and `message` as `AiPlan.error`. Its `data` does not travel here; read the plan for it."
+          }
+        },
+        "required": [
+          "field",
+          "id_ai_plan",
+          "id_organization",
+          "state",
+          "template",
+          "total_publications",
+          "credits_spent",
+          "warnings"
+        ]
+      },
+      "CommentsAiPlanWebhookError": {
+        "type": "object",
+        "description": "Why an AI plan failed, inside `AiPlanWebhookChange.error`: the same `code` and `message` as `AiPlan.error`. Its `data` is left out, because it can carry what the AI provider answered; read the plan for it.",
+        "properties": {
+          "code": {
+            "type": "integer"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "code",
+          "message"
+        ]
+      },
       "CommentsComment": {
         "type": "object",
         "description": "A comment — or a review — as PlanVortex stores it. Remember it is a **snapshot** of what the network said at `collected_date`; the live thread endpoints return the same shape reconciled against the network.",
@@ -15188,7 +15275,7 @@
       },
       "CommentsWebhookChange": {
         "type": "object",
-        "description": "One change in the array PlanVortex posts to your app's `webhook_url`, when the change concerns a social **account**.\n\nAn integration that stopped working has a shape of its own — `IntegrationWebhookChange` — and one delivery can mix both. Switch on `field`, and ignore what you do not handle.",
+        "description": "One change in the array PlanVortex posts to your app's `webhook_url`, when the change concerns a social **account**.\n\nAn integration that stopped working has a shape of its own (`IntegrationWebhookChange`), and so does an AI plan that finished (`AiPlanWebhookChange`). One delivery can mix them. Switch on `field`, and ignore what you do not handle.",
         "properties": {
           "field": {
             "type": "string",
@@ -17725,7 +17812,10 @@
               "draft",
               "publishing"
             ],
-            "description": "`draft` is never sent; `ready` is scheduled; `publishing` is in the network's hands right now; `sended` went out; `withErrors` failed and carries the reason in `publication_errors`."
+            "description": "`draft` is never sent; `ready` is scheduled; `publishing` is in the network's hands right now; `sended` went out; `withErrors` failed and carries the reason in `publication_errors`.\n\n`publishing` usually lasts a few seconds, but it can last **up to 10 minutes** when the network is still processing a video (today, Instagram). Then `pending_publish` is present: wait and read the publication again, do not retry it."
+          },
+          "pending_publish": {
+            "$ref": "#/components/schemas/PublicationPending"
           },
           "files": {
             "type": "array",
@@ -17744,7 +17834,7 @@
           },
           "publication_errors": {
             "type": "array",
-            "description": "Why the publication failed, one entry per problem. **It is an array**, and it is empty on a publication that has not failed.\n\nFor a scheduled X (Twitter) publication that runs out of credits at publish time, `code` is 940 and `data` is `{ used, limit }`; the publication stays in state `withErrors` and the client-app webhook is fired.",
+            "description": "Why the publication failed, one entry per problem. **It is an array**, and it is empty on a publication that has not failed.\n\nFor a scheduled X (Twitter) publication that runs out of credits at publish time, `code` is 940 and `data` is `{ used, limit }`; the publication stays in state `withErrors`. No webhook announces it: read the publication to find out.\n\nOn Instagram, two codes tell you whether a retry makes sense. **998**: Meta rejected the media while processing it (a codec, a duration, a URL it could not download). `data` carries `container_id`, `status_code` and, when Meta gives one, its reason in `status`. Retrying the same file fails the same way: change it first. **999**: Meta had not finished processing the media 10 minutes after it was sent. `data` carries `container_ids` and `minutes`. The file is not the problem, and a retry usually works.",
             "items": {
               "type": "object",
               "required": [
@@ -17859,6 +17949,34 @@
           }
         }
       },
+      "PublicationPending": {
+        "type": "object",
+        "description": "Present only while the network is still **processing** what was sent, and PlanVortex is waiting to publish it. Today that happens on Instagram alone, when Meta takes longer than the ~30 seconds the request waits to process the media. In practice, that means videos.\n\nThe publication stays in state `publishing`, and the background job asks Instagram again about once a minute until it goes out (`sended`) or fails (`withErrors`). It gives up 10 minutes after the media was sent to Instagram, and then the publication ends in `withErrors` with code 999. The object disappears as soon as the publication is resolved.\n\n**Wait for it. Do not retry it and do not create it again**: it has not failed, and a second publication would put the same video out twice. There is no webhook for the outcome: read the publication again after `next_check`. While this object is present the publication **cannot be updated** (error 921), for the same reason.",
+        "properties": {
+          "next_check": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When PlanVortex will ask the network again. A good moment to read the publication again: asking before it changes nothing."
+          },
+          "deadline": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When PlanVortex stops waiting. If the network has not finished by then, the publication ends in `withErrors` (999 on Instagram)."
+          },
+          "temp_keys": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "PlanVortex's own bookkeeping: the temporary cropped files the network may still be downloading. Do not rely on it."
+          },
+          "data": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "PlanVortex's own bookkeeping to resume the publication (on Instagram, the ids of Meta's containers). Its content may change without notice."
+          }
+        }
+      },
       "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 `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.\n\nOn `slack` there is exactly **one**, `reactions`, and the other absences are the informative part: the Web API publishes no impressions, no reach, no views and no clicks for a message, so those keys are missing rather than zero. There is no `comments` either — Slack threads are not read at all (`comments` is `false` in `GET /social_capabilities`). Engagement is computed over the channel's members.\n\nOn `pinterest` there are seven, and three of them exist nowhere else: `saves` — the gesture the whole network is built on —, `outbound_clicks` (clicks that left the pin towards its `link`, which is the one normalised as the common `clicks`) and `pin_clicks` (clicks that opened the pin inside Pinterest, with no common equivalent). `impressions` is real here, so the engagement rate is computed over it and not over followers. `video_views` only exists on a video pin. And `comments` is the odd one: Pinterest **counts** them and offers no way to read them, so the number is reported while `comments` is `false` in `GET /social_capabilities` — this network has no comment inbox, and it is not a gap waiting to be filled.",

{planvortex-0.12.0 → planvortex-0.13.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.12.0"
+version = "0.13.0"
 description = "Official Python client for the PlanVortex API"
 readme = "README.md"
 requires-python = ">=3.10"

{planvortex-0.12.0 → planvortex-0.13.0}/src/planvortex/_generated/models.py

@@ -562,7 +562,7 @@ class AppsClientApp(TypedDict):
 
     **The body is an array of changes, not a single object**, and it carries two signature headers computed with this app's secret over the **raw** body: `x-hub-signature` (`sha1=<hex>`) and `x-hub-signature-256` (`sha256=<hex>`). Verify against the bytes you received — parsing the JSON and re-serialising it changes them and the signature will not match.
 
-    The events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments` and `integration_error`. The payload is documented in the `comments` specification. Delivery is best effort: PlanVortex does not retry a webhook that fails.
+    The events delivered today are `new_account`, `change_state_account`, `messages`, `messaging_postbacks`, `messaging_seen`, `messaging_error`, `comments`, `integration_error`, `ai_plan_generated` and `ai_plan_failed`. The payload is documented in the `comments` specification. **Every** app of the client that has a `webhook_url` receives every event, not only the app whose call caused it: with two apps, each event arrives twice. Delivery is best effort: PlanVortex does not retry a webhook that fails.
     """
     creation_date: str
     deleted: bool
@@ -897,6 +897,15 @@ class ClientsRolesUserList(TypedDict):
     total: NotRequired[int]
 
 
+class CommentsAiPlanWebhookError(TypedDict):
+    """
+    Why an AI plan failed, inside `AiPlanWebhookChange.error`: the same `code` and `message` as `AiPlan.error`. Its `data` is left out, because it can carry what the AI provider answered; read the plan for it.
+    """
+
+    code: int
+    message: str
+
+
 class CommentsCommentActions(TypedDict):
     """
     What one network lets you do to a comment. Four booleans and never fewer: an absent key would be indistinguishable from an oversight.
@@ -1927,6 +1936,33 @@ class PublicationDestination(TypedDict):
     """
 
 
+class PublicationPending(TypedDict):
+    """
+    Present only while the network is still **processing** what was sent, and PlanVortex is waiting to publish it. Today that happens on Instagram alone, when Meta takes longer than the ~30 seconds the request waits to process the media. In practice, that means videos.
+
+    The publication stays in state `publishing`, and the background job asks Instagram again about once a minute until it goes out (`sended`) or fails (`withErrors`). It gives up 10 minutes after the media was sent to Instagram, and then the publication ends in `withErrors` with code 999. The object disappears as soon as the publication is resolved.
+
+    **Wait for it. Do not retry it and do not create it again**: it has not failed, and a second publication would put the same video out twice. There is no webhook for the outcome: read the publication again after `next_check`. While this object is present the publication **cannot be updated** (error 921), for the same reason.
+    """
+
+    next_check: NotRequired[str]
+    """
+    When PlanVortex will ask the network again. A good moment to read the publication again: asking before it changes nothing.
+    """
+    deadline: NotRequired[str]
+    """
+    When PlanVortex stops waiting. If the network has not finished by then, the publication ends in `withErrors` (999 on Instagram).
+    """
+    temp_keys: NotRequired[list[str]]
+    """
+    PlanVortex's own bookkeeping: the temporary cropped files the network may still be downloading. Do not rely on it.
+    """
+    data: NotRequired[dict[str, Any]]
+    """
+    PlanVortex's own bookkeeping to resume the publication (on Instagram, the ids of Meta's containers). Its content may change without notice.
+    """
+
+
 class PublicationStats(TypedDict):
     """
     Raw, per-network metrics for a publication. Only the fields that belong to the publication's own social network are returned.
@@ -2773,6 +2809,42 @@ class ClientsPlan(TypedDict):
     stripe_customer_id: NotRequired[str]
 
 
+class CommentsAiPlanWebhookChange(TypedDict):
+    """
+    One change in the array PlanVortex posts to your app's `webhook_url`, when an **AI plan finished**: `ai_plan_generated` when it came out, `ai_plan_failed` when it gave up.
+
+    Like `IntegrationWebhookChange`, it carries no `id_account` and no `social_network`: a plan can span several networks, and it hangs off the organization. It carries ids and numbers only. Read the plan itself with `GET /clients/{id_client}/organizations/{id_organization}/ai_plans/{id_ai_plan}`.
+    """
+
+    field: Literal["ai_plan_generated", "ai_plan_failed"]
+    id_ai_plan: str
+    id_organization: str
+    state: Literal["generated", "failed"]
+    """
+    The state the plan finished in. It always matches `field`: `generated` with `ai_plan_generated`, `failed` with `ai_plan_failed`.
+    """
+    template: Literal["standard", "from_images", "from_text", "from_catalog", "campaign"]
+    """
+    What the plan was generated from, the same value as `AiPlan.template`.
+    """
+    total_publications: int
+    """
+    How many draft publications the plan holds. A failed plan can still hold the drafts of its failed attempt; retrying it discards them.
+    """
+    credits_spent: int
+    """
+    AI credits the generation consumed, the same figure as `AiPlan.credits_spent`. A failed plan can have spent credits too, and they are not refunded.
+    """
+    warnings: int
+    """
+    **How many** non-blocking notices the plan has, not the notices themselves: those are in `AiPlan.warnings`. Above zero the plan is still generated and usable.
+    """
+    error: NotRequired[CommentsAiPlanWebhookError]
+    """
+    Only on `ai_plan_failed`: why the plan failed, the same `code` and `message` as `AiPlan.error`. Its `data` does not travel here; read the plan for it.
+    """
+
+
 class Contact(TypedDict):
     """
     A person the organization exchanges messages with. The same contact can be reachable on several channels — that is what `social_identifiers` is.
@@ -3307,7 +3379,10 @@ class Publication(TypedDict):
     state: Literal["ready", "withErrors", "sended", "draft", "publishing"]
     """
     `draft` is never sent; `ready` is scheduled; `publishing` is in the network's hands right now; `sended` went out; `withErrors` failed and carries the reason in `publication_errors`.
+
+    `publishing` usually lasts a few seconds, but it can last **up to 10 minutes** when the network is still processing a video (today, Instagram). Then `pending_publish` is present: wait and read the publication again, do not retry it.
     """
+    pending_publish: NotRequired[PublicationPending]
     files: list[Upload]
     """
     The attached files, **already resolved**: every read and write path returns full uploads, not identifiers. Identifiers are what you SEND (see `PublicationInput.files`).
@@ -3318,7 +3393,9 @@ class Publication(TypedDict):
     """
     Why the publication failed, one entry per problem. **It is an array**, and it is empty on a publication that has not failed.
 
-    For a scheduled X (Twitter) publication that runs out of credits at publish time, `code` is 940 and `data` is `{ used, limit }`; the publication stays in state `withErrors` and the client-app webhook is fired.
+    For a scheduled X (Twitter) publication that runs out of credits at publish time, `code` is 940 and `data` is `{ used, limit }`; the publication stays in state `withErrors`. No webhook announces it: read the publication to find out.
+
+    On Instagram, two codes tell you whether a retry makes sense. **998**: Meta rejected the media while processing it (a codec, a duration, a URL it could not download). `data` carries `container_id`, `status_code` and, when Meta gives one, its reason in `status`. Retrying the same file fails the same way: change it first. **999**: Meta had not finished processing the media 10 minutes after it was sent. `data` carries `container_ids` and `minutes`. The file is not the problem, and a retry usually works.
     """
     retries: int
     """
@@ -3493,7 +3570,7 @@ class AiPlansAiPlan(TypedDict):
     options: AiPlansAiPlanOptions
     state: Literal["pending", "generating", "generated", "validated", "failed", "cancelled"]
     """
-    State machine: pending -> generating -> generated -> validated | failed | cancelled. Poll the plan while state is pending or generating.
+    State machine: pending -> generating -> generated -> validated | failed | cancelled. Reaching `generated` or `failed` is announced to your app's webhook (`ai_plan_generated`, `ai_plan_failed`); without one, poll the plan while state is pending or generating.
     """
     archived_date: NotRequired[str]
     """
@@ -3877,7 +3954,7 @@ class CommentsWebhookChange(TypedDict):
     """
     One change in the array PlanVortex posts to your app's `webhook_url`, when the change concerns a social **account**.
 
-    An integration that stopped working has a shape of its own — `IntegrationWebhookChange` — and one delivery can mix both. Switch on `field`, and ignore what you do not handle.
+    An integration that stopped working has a shape of its own (`IntegrationWebhookChange`), and so does an AI plan that finished (`AiPlanWebhookChange`). One delivery can mix them. Switch on `field`, and ignore what you do not handle.
     """
 
     field: Literal[

{planvortex-0.12.0 → planvortex-0.13.0}/src/planvortex/_version.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import platform
 
-VERSION = "0.12.0"
+VERSION = "0.13.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.12.0 → planvortex-0.13.0}/src/planvortex/resources/ai_plans.py

@@ -11,8 +11,10 @@ THE CYCLE, which is what to have clear before anything else::
 AND WHAT SURPRISES PEOPLE:
 
 - **``create()`` generates nothing**: it queues the plan and returns the budget. The generating is
-  done by a separate job, so you poll :meth:`AsyncAiPlansResource.get` while the state is ``pending``
-  or ``generating``. It can take minutes.
+  done by a separate job and can take minutes. When it ends, your app's ``webhook_url`` receives
+  ``ai_plan_generated`` or ``ai_plan_failed`` (``is_ai_plan_change`` in :mod:`planvortex.webhooks`);
+  without a webhook, poll :meth:`AsyncAiPlansResource.get` while the state is ``pending`` or
+  ``generating``.
 - **What is generated are NORMAL publications in state ``draft``.** They are edited and deleted with
   ``pv.publications``, not with anything here. Validating is what moves them to ``ready``.
 - **It is paid for in AI credits and the price is known BEFOREHAND.** The budget is computed by the
@@ -175,8 +177,10 @@ class AsyncAiPlansResource(AsyncResource):
     ) -> AiPlan:
         """One plan, with its publications **already resolved** and with each one's files.
 
-        It is the endpoint you poll while ``state`` is ``pending`` or ``generating``. There is no
-        webhook for this yet.
+        Read it when your app receives ``ai_plan_generated`` or ``ai_plan_failed``. Without a
+        webhook, it is the endpoint you poll while ``state`` is ``pending`` or ``generating``. The
+        webhook is not retried, so if your endpoint was down when the plan finished, this still tells
+        you how it ended.
 
         Read ``warnings`` on a plan that came out ``generated``, which is the place nobody
         looks: it is not an error of the response, it is a notice about a plan that generated fine.
@@ -333,8 +337,8 @@ class AsyncAiPlansResource(AsyncResource):
         *,
         timeout: float | None = None,
     ) -> AiPlan:
-        """Queue a ``failed`` plan again with the same data. The state goes back to ``pending`` and you
-        have to poll again.
+        """Queue a ``failed`` plan again with the same data. The state goes back to ``pending`` and the
+        end arrives again as after ``create()``: on your webhook, or by polling.
 
         It uses the brand context copied when the plan was created, not today's: a plan is
         reproducible even if somebody edited the configuration in the meantime.

{planvortex-0.12.0 → planvortex-0.13.0}/src/planvortex/resources_sync/ai_plans.py

@@ -114,8 +114,10 @@ class AiPlansResource(Resource):
     ) -> AiPlan:
         """One plan, with its publications **already resolved** and with each one's files.
 
-        It is the endpoint you poll while ``state`` is ``pending`` or ``generating``. There is no
-        webhook for this yet.
+        Read it when your app receives ``ai_plan_generated`` or ``ai_plan_failed``. Without a
+        webhook, it is the endpoint you poll while ``state`` is ``pending`` or ``generating``. The
+        webhook is not retried, so if your endpoint was down when the plan finished, this still tells
+        you how it ended.
 
         Read ``warnings`` on a plan that came out ``generated``, which is the place nobody
         looks: it is not an error of the response, it is a notice about a plan that generated fine.
@@ -272,8 +274,8 @@ class AiPlansResource(Resource):
         *,
         timeout: float | None = None,
     ) -> AiPlan:
-        """Queue a ``failed`` plan again with the same data. The state goes back to ``pending`` and you
-        have to poll again.
+        """Queue a ``failed`` plan again with the same data. The state goes back to ``pending`` and the
+        end arrives again as after ``create()``: on your webhook, or by polling.
 
         It uses the brand context copied when the plan was created, not today's: a plan is
         reproducible even if somebody edited the configuration in the meantime.