planvortex 0.19.0__tar.gz → 0.20.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. {planvortex-0.19.0 → planvortex-0.20.0}/CHANGELOG.md +34 -0
  2. {planvortex-0.19.0 → planvortex-0.20.0}/PKG-INFO +1 -1
  3. {planvortex-0.19.0 → planvortex-0.20.0}/openapi/planvortex.openapi.json +41 -13
  4. {planvortex-0.19.0 → planvortex-0.20.0}/pyproject.toml +1 -1
  5. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_generated/models.py +27 -3
  6. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_shapes.py +9 -3
  7. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_version.py +1 -1
  8. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/clients.py +8 -5
  9. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/organizations.py +8 -3
  10. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/clients.py +2 -2
  11. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/organizations.py +8 -3
  12. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_organizations.py +20 -0
  13. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_types.py +11 -1
  14. {planvortex-0.19.0 → planvortex-0.20.0}/.gitignore +0 -0
  15. {planvortex-0.19.0 → planvortex-0.20.0}/LICENSE +0 -0
  16. {planvortex-0.19.0 → planvortex-0.20.0}/README.md +0 -0
  17. {planvortex-0.19.0 → planvortex-0.20.0}/scripts/build_docs.py +0 -0
  18. {planvortex-0.19.0 → planvortex-0.20.0}/scripts/check_packaging.py +0 -0
  19. {planvortex-0.19.0 → planvortex-0.20.0}/scripts/generate_models.py +0 -0
  20. {planvortex-0.19.0 → planvortex-0.20.0}/scripts/generate_sync.py +0 -0
  21. {planvortex-0.19.0 → planvortex-0.20.0}/scripts/route_coverage.py +0 -0
  22. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/__init__.py +0 -0
  23. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_client.py +0 -0
  24. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_client_sync.py +0 -0
  25. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/__init__.py +0 -0
  26. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/auth.py +0 -0
  27. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/auth_sync.py +0 -0
  28. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/errors.py +0 -0
  29. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/files.py +0 -0
  30. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/http.py +0 -0
  31. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/http_sync.py +0 -0
  32. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/pagination.py +0 -0
  33. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/query.py +0 -0
  34. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_core/transport.py +0 -0
  35. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/_generated/__init__.py +0 -0
  36. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/py.typed +0 -0
  37. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/__init__.py +0 -0
  38. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/accounts.py +0 -0
  39. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/ai_plans.py +0 -0
  40. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/apps.py +0 -0
  41. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/base.py +0 -0
  42. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/catalog.py +0 -0
  43. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/comments.py +0 -0
  44. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/contacts.py +0 -0
  45. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/dashboard.py +0 -0
  46. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/integrations.py +0 -0
  47. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/messages.py +0 -0
  48. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/products.py +0 -0
  49. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/publications.py +0 -0
  50. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources/uploads.py +0 -0
  51. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/__init__.py +0 -0
  52. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/accounts.py +0 -0
  53. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/ai_plans.py +0 -0
  54. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/apps.py +0 -0
  55. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/base.py +0 -0
  56. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/catalog.py +0 -0
  57. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/comments.py +0 -0
  58. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/contacts.py +0 -0
  59. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/dashboard.py +0 -0
  60. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/integrations.py +0 -0
  61. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/messages.py +0 -0
  62. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/products.py +0 -0
  63. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/publications.py +0 -0
  64. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/resources_sync/uploads.py +0 -0
  65. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/types.py +0 -0
  66. {planvortex-0.19.0 → planvortex-0.20.0}/src/planvortex/webhooks.py +0 -0
  67. {planvortex-0.19.0 → planvortex-0.20.0}/tests/__init__.py +0 -0
  68. {planvortex-0.19.0 → planvortex-0.20.0}/tests/conftest.py +0 -0
  69. {planvortex-0.19.0 → planvortex-0.20.0}/tests/contrato.py +0 -0
  70. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/__init__.py +0 -0
  71. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/conftest.py +0 -0
  72. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/test_auth.py +0 -0
  73. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/test_catalog.py +0 -0
  74. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/test_connect_flow.py +0 -0
  75. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/test_errors.py +0 -0
  76. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/test_publish.py +0 -0
  77. {planvortex-0.19.0 → planvortex-0.20.0}/tests/live/test_read.py +0 -0
  78. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_accounts.py +0 -0
  79. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_ai_plans.py +0 -0
  80. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_apps.py +0 -0
  81. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_catalog.py +0 -0
  82. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_client.py +0 -0
  83. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_clients.py +0 -0
  84. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_comments.py +0 -0
  85. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_contacts.py +0 -0
  86. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_core.py +0 -0
  87. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_dashboard.py +0 -0
  88. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_example_comments.py +0 -0
  89. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_example_connect.py +0 -0
  90. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_example_publish.py +0 -0
  91. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_example_schedule.py +0 -0
  92. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_example_webhooks.py +0 -0
  93. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_files.py +0 -0
  94. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_generate_models.py +0 -0
  95. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_generate_sync.py +0 -0
  96. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_integrations.py +0 -0
  97. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_messages.py +0 -0
  98. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_models.py +0 -0
  99. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_openapi_freshness.py +0 -0
  100. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_packaging.py +0 -0
  101. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_pagination.py +0 -0
  102. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_products.py +0 -0
  103. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_publications.py +0 -0
  104. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_query_parity.py +0 -0
  105. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_readme.py +0 -0
  106. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_route_coverage.py +0 -0
  107. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_shapes_parity.py +0 -0
  108. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_uploads.py +0 -0
  109. {planvortex-0.19.0 → planvortex-0.20.0}/tests/test_webhooks.py +0 -0
@@ -6,6 +6,40 @@ All notable changes to this package are documented here. The format follows
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.20.0] - 2026-11-17
10
+
11
+ ### Added
12
+
13
+ - **`own_use` on an organization** (with `get_use=True`, in `organizations.get()`, `children()` and
14
+ `clients.organizations()`): what that organization uses on its own, without the folders it shares
15
+ a plan with. `actual_use` is still the figure of the whole pool it draws from, the one the server
16
+ checks before letting one more account in, so every organization in a pool shows the same
17
+ `actual_use`. Adding up the `own_use` of the organizations in a pool gives its `actual_use`.
18
+ `organizations.use()` now returns it too (`OrganizationUse.own_use`). Absent from a server older
19
+ than November 2026.
20
+ - **`pool_use` on a client** (with `get_use=True`): what the client's shared pool is using, that
21
+ is, the organizations without a plan of their own that draw straight from the client. With
22
+ `actual_asigned` and `actual_plan["plan_data"]` it splits the plan in three: used by the shared
23
+ pool, free in the shared pool (`plan_data` minus `actual_asigned` minus `pool_use`) and handed out
24
+ to organizations with a plan of their own.
25
+ - The regenerated models also carry `Message.delivery_status` (`"sent"`, `"delivered"`, `"read"`
26
+ or `"failed"`), how far a message we sent got, like the ticks in WhatsApp (typing only: the field
27
+ already came back from the API).
28
+
29
+ ### Changed
30
+
31
+ - **A client's `actual_use` now counts every organization of the client**, which is the figure
32
+ billing charges for. It used to count only the shared pool, so it did not match the accounts on
33
+ the invoice as soon as an organization had a plan of its own. What it counted before is now
34
+ `pool_use`. This is a server change: an organization's `actual_use` keeps its meaning.
35
+ - Users in a client's or an organization's consumption are now counted as people: someone with a
36
+ role in three organizations used to count three times.
37
+ - On the free plan `google_business` joins `whatsapp` as a network that needs a paid plan: it is
38
+ left out of the connect links, a temporal connect token asked for it answers error 516 and so
39
+ does enabling a new account, because reviews are behind a paid plan. An organization that
40
+ already has an active one can still reconnect it. This is a server change; only the
41
+ descriptions of the regenerated types say so.
42
+
9
43
  ## [0.19.0] - 2026-11-13
10
44
 
11
45
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: planvortex
3
- Version: 0.19.0
3
+ Version: 0.20.0
4
4
  Summary: Official Python client for the PlanVortex API
5
5
  Project-URL: Homepage, https://planvortex.com/en/developers
6
6
  Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
@@ -107,7 +107,7 @@
107
107
  "accounts"
108
108
  ],
109
109
  "summary": "Get the connection links of every connectable network",
110
- "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**On the free plan `whatsapp` does not appear either**, unless the organization already has an active WhatsApp account, which has to stay reconnectable. Its chat and its templates need a paid plan, so enabling a new account answers error 516. Asking for it by name gets you an empty list, not an error.\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`.** Almost every network is `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.\n\n**With a temporal token issued with `account_selection=integrator`** the list has a single entry: the session's network, with the session's `state` inside its link. Any other link would go back through the hosted flow, which that token cannot use (error 554). Once the person has come back from the network the session is no longer waiting for a link, and this answers 551.",
110
+ "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**On the free plan `whatsapp` and `google_business` do not appear either**, unless the organization already has an active account of that network, which has to stay reconnectable. WhatsApp only has chat and templates and Google Business only has reviews, and all of that needs a paid plan, so enabling a new account answers error 516. Asking for it by name gets you an empty list, not an error.\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`.** Almost every network is `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.\n\n**With a temporal token issued with `account_selection=integrator`** the list has a single entry: the session's network, with the session's `state` inside its link. Any other link would go back through the hosted flow, which that token cannot use (error 554). Once the person has come back from the network the session is no longer waiting for a link, and this answers 551.",
111
111
  "operationId": "getConnectLinks",
112
112
  "x-planvortex-identity": [
113
113
  "current_user",
@@ -873,7 +873,7 @@
873
873
  "accounts"
874
874
  ],
875
875
  "summary": "Re-enable a disconnected account",
876
- "description": "Brings back an account that was removed, without going through the authorization again — as long as its stored token still works.\n\nIt takes a **slot of the plan**, so it fails with error 706 when the organization is already at its account limit. It also turns the network's webhooks back on, on any plan but the free one. On the free plan a `whatsapp` account that is not active cannot be enabled (error 516), because its chat and its templates need a paid plan. One that is already active can still be reconnected.\n\n**On `telegram` you normally never call this.** That network's accounts are born active — there is no authorization return in which to choose them, so PlanVortex takes the slot when the bot is added to the channel. The one case left is a channel that arrived while the plan was full: it stays off until a slot frees up, and this is what turns it on.\n\n**On `slack` this is also what puts the PlanVortex app inside the channel**, with `conversations.join`. It works on a **public** channel and it cannot work on a private one: Slack has no API for joining one. The account is enabled all the same and the connection looks healthy, and then the first publication fails with error 980 — so a private channel has to be told to the person **before** they pick it, together with the `/invite @PlanVortex` they have to run in that channel. Whether the app is inside travels in `extra_data.is_member`, and it can turn `false` later, the day somebody removes the app from an already connected channel.",
876
+ "description": "Brings back an account that was removed, without going through the authorization again — as long as its stored token still works.\n\nIt takes a **slot of the plan**, so it fails with error 706 when the organization is already at its account limit. It also turns the network's webhooks back on, on any plan but the free one. On the free plan a `whatsapp` or `google_business` account that is not active cannot be enabled (error 516), because everything those networks do needs a paid plan (chat and templates on WhatsApp, reviews on Google Business). One that is already active can still be reconnected.\n\n**On `telegram` you normally never call this.** That network's accounts are born active — there is no authorization return in which to choose them, so PlanVortex takes the slot when the bot is added to the channel. The one case left is a channel that arrived while the plan was full: it stays off until a slot frees up, and this is what turns it on.\n\n**On `slack` this is also what puts the PlanVortex app inside the channel**, with `conversations.join`. It works on a **public** channel and it cannot work on a private one: Slack has no API for joining one. The account is enabled all the same and the connection looks healthy, and then the first publication fails with error 980 — so a private channel has to be told to the person **before** they pick it, together with the `/invite @PlanVortex` they have to run in that channel. Whether the app is inside travels in `extra_data.is_member`, and it can turn `false` later, the day somebody removes the app from an already connected channel.",
877
877
  "operationId": "enableAccount",
878
878
  "x-planvortex-identity": [
879
879
  "current_user",
@@ -919,7 +919,7 @@
919
919
  }
920
920
  },
921
921
  "400": {
922
- "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `700` | The account has no usable token: it has to be connected again |\n| `706` | The organization has no account slots left in its plan |\n| `516` | The plan is free and this network needs a paid plan (today, `whatsapp`) |\n| `519` | This endpoint does not accept app credentials |\n| `544` | This temporal connect token was issued for a different social network |",
922
+ "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `700` | The account has no usable token: it has to be connected again |\n| `706` | The organization has no account slots left in its plan |\n| `516` | The plan is free and this network needs a paid plan (today, `whatsapp` and `google_business`) |\n| `519` | This endpoint does not accept app credentials |\n| `544` | This temporal connect token was issued for a different social network |",
923
923
  "content": {
924
924
  "application/json": {
925
925
  "schema": {
@@ -1322,7 +1322,7 @@
1322
1322
  }
1323
1323
  },
1324
1324
  "400": {
1325
- "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials |\n| `551` | Connect session not found, expired, or issued by another app |\n| `552` | The session is not waiting for a confirmation: the person has not come back yet, or it was already confirmed. `data.status` says which |\n| `553` | Some account is not part of this session. `data.accounts` lists them |\n| `706` | The new accounts do not fit in the plan. `data` carries `limit`, `used` and `requested`, and none was enabled |\n| `1101` | Invalid organization |\n| `516` | The plan is free and one of the accounts belongs to a network that needs a paid plan (today, `whatsapp`) |",
1325
+ "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials |\n| `551` | Connect session not found, expired, or issued by another app |\n| `552` | The session is not waiting for a confirmation: the person has not come back yet, or it was already confirmed. `data.status` says which |\n| `553` | Some account is not part of this session. `data.accounts` lists them |\n| `706` | The new accounts do not fit in the plan. `data` carries `limit`, `used` and `requested`, and none was enabled |\n| `1101` | Invalid organization |\n| `516` | The plan is free and one of the accounts belongs to a network that needs a paid plan (today, `whatsapp` and `google_business`) |",
1326
1326
  "content": {
1327
1327
  "application/json": {
1328
1328
  "schema": {
@@ -5522,7 +5522,7 @@
5522
5522
  "comments"
5523
5523
  ],
5524
5524
  "summary": "Mark as read, or hide on the network",
5525
- "description": "Two different kinds of change, accepted together because a panel changes them from the same place:\n\n- `read` is **yours**. It touches no social network, costs nothing and can always be set.\n- `hidden` **touches the network**, and not every network allows it — LinkedIn and Google Business have no hide endpoint at all and return error `946`. Check `GET /social_comment_actions` before offering the control.\n\nRequires the `comments:create` permission (`client_organization_comments:create` for apps) and a paid plan.",
5525
+ "description": "Two different kinds of change, accepted together because a panel changes them from the same place:\n\n- `read` is **yours**. It touches no social network, costs nothing and can always be set.\n- `hidden` **touches the network**, and not every network allows it — LinkedIn and Google Business have no hide endpoint at all and return error `946`. Check `GET /social_comment_actions` before offering the control.\n\nSetting `read` requires the `comments:read` permission (`client_organization_comments:read` for apps): marking a comment read is part of reading it, as opening a conversation is in the chat. Setting `hidden` also requires `comments:create` (`client_organization_comments:create`), the same as replying, and without it the whole request is refused with `520` and nothing changes, `read` included. Both need a paid plan.",
5526
5526
  "operationId": "updateComment",
5527
5527
  "x-planvortex-identity": [
5528
5528
  "current_user",
@@ -8482,7 +8482,7 @@
8482
8482
  "orgnaizations"
8483
8483
  ],
8484
8484
  "summary": "Get an organization by identifier",
8485
- "description": "Get one organization by its identifier",
8485
+ "description": "Get one organization by its identifier, with what it is using of its plan (`actual_use`) and what it has been assigned (`actual_asigned`).\n\n**Anyone with a role in the organization can read it**, whatever that role's permissions are, and so can anyone with a client role, an app of the client and a temporal token of this organization. It used to require `organization:read`, and that left a role allowed to connect accounts, create AI plans or publish without knowing how much of the plan was left. `organization:read` now means seeing the plan consumption: `GET /organizations/{id_organization}/use`, `GET /organizations/{id_organization}/limits` and the `plan_use` block of the dashboard.",
8486
8486
  "operationId": "getOrganization",
8487
8487
  "x-planvortex-identity": [
8488
8488
  "current_user",
@@ -9228,7 +9228,7 @@
9228
9228
  "orgnaizations"
9229
9229
  ],
9230
9230
  "summary": "Issue a temporal connect token for an end user",
9231
- "description": "Returns a URL that lets **a person** connect a social account to this organization, without that person having a PlanVortex account and without your `client_secret` ever leaving your server.\n\nIt exists because **an app cannot connect accounts**: `connect_links` and `account-connect` refuse app credentials with error 519, since authorizing Instagram is an OAuth flow with a human in front of it. The shape of the integration is therefore:\n\n1. Your server asks for this token — **this endpoint is the one that requires app credentials**, and a user token is refused. So is a temporal connect token: it cannot renew itself, which is what keeps its life a real limit rather than the first link of a chain.\n2. You send your end user to the `url` that comes back, by redirect or in an iframe. The bare\n `token` comes back too, so a server-side client can authenticate with it directly instead of\n parsing it out of that URL.\n3. With that token the browser completes `connect_links` and `account-connect`.\n\nThe token lasts **fifteen minutes**, is tied to **this** organization — using it against another answers error 1101 — and carries only two permissions: create accounts and read the organization. It is the piece designed for a browser, and the only credential of ours that belongs there.\n\n**It connects once.** As soon as an `account-connect` succeeds, the token stops being able to connect anything else and answers error 543; the `enable` calls that finish that same connection keep working until it expires. Issue a new one per connection — they are free and immediate.\n\n**If you pass `social_network`, the token is bound to that network** and will not connect any other (error 544). Leave it out to let the person pick. On the free plan, asking for `whatsapp` answers error 516 unless the organization already has an active WhatsApp account to reconnect: its chat and its templates need a paid plan.\n\n**Or show the account picker yourself** with `account_selection=integrator`. By default PlanVortex shows the screen where the person picks which accounts to enable, and only then sends them to your `redirect_uri`. In this mode that screen is yours:\n\n1. The `url` that comes back is **the network's own authorization page**, so the person goes there straight from your app. Keep the `connect_session` id next to your user's session.\n2. When they finish, the network sends them through PlanVortex, which renders nothing, to `redirect_uri?connect_session=…&social_network=…`. Check that the id is the one you started.\n3. Read the accounts with `GET /organizations/{id_organization}/connect_sessions/{id_session}`, show your picker, and confirm with `POST /organizations/{id_organization}/connect_sessions/{id_session}/confirm`.\n\nThis mode needs `redirect_uri` and `social_network` (error 549): your app also picks the network. `telegram` cannot use it (error 550), because its link opens a chat that never comes back to the browser. On `whatsapp` the `url` is still a PlanVortex page with one button, because Meta's popup only opens on our domain; the picker after it is yours.\n\nPlanVortex's domain does show in the address bar on the way back: networks only return to the URLs registered in their own portals.\n\nIf you send `redirect_uri` it has to be one of the app's `redirect_urls`, or the call answers error 532.",
9231
+ "description": "Returns a URL that lets **a person** connect a social account to this organization, without that person having a PlanVortex account and without your `client_secret` ever leaving your server.\n\nIt exists because **an app cannot connect accounts**: `connect_links` and `account-connect` refuse app credentials with error 519, since authorizing Instagram is an OAuth flow with a human in front of it. The shape of the integration is therefore:\n\n1. Your server asks for this token — **this endpoint is the one that requires app credentials**, and a user token is refused. So is a temporal connect token: it cannot renew itself, which is what keeps its life a real limit rather than the first link of a chain.\n2. You send your end user to the `url` that comes back, by redirect or in an iframe. The bare\n `token` comes back too, so a server-side client can authenticate with it directly instead of\n parsing it out of that URL.\n3. With that token the browser completes `connect_links` and `account-connect`.\n\nThe token lasts **fifteen minutes**, is tied to **this** organization — using it against another answers error 1101 — and carries only two permissions: create accounts and read the organization. It is the piece designed for a browser, and the only credential of ours that belongs there.\n\n**It connects once.** As soon as an `account-connect` succeeds, the token stops being able to connect anything else and answers error 543; the `enable` calls that finish that same connection keep working until it expires. Issue a new one per connection — they are free and immediate.\n\n**If you pass `social_network`, the token is bound to that network** and will not connect any other (error 544). Leave it out to let the person pick. On the free plan, asking for `whatsapp` or `google_business` answers error 516 unless the organization already has an active account of that network to reconnect: everything those networks do needs a paid plan.\n\n**Or show the account picker yourself** with `account_selection=integrator`. By default PlanVortex shows the screen where the person picks which accounts to enable, and only then sends them to your `redirect_uri`. In this mode that screen is yours:\n\n1. The `url` that comes back is **the network's own authorization page**, so the person goes there straight from your app. Keep the `connect_session` id next to your user's session.\n2. When they finish, the network sends them through PlanVortex, which renders nothing, to `redirect_uri?connect_session=…&social_network=…`. Check that the id is the one you started.\n3. Read the accounts with `GET /organizations/{id_organization}/connect_sessions/{id_session}`, show your picker, and confirm with `POST /organizations/{id_organization}/connect_sessions/{id_session}/confirm`.\n\nThis mode needs `redirect_uri` and `social_network` (error 549): your app also picks the network. `telegram` cannot use it (error 550), because its link opens a chat that never comes back to the browser. On `whatsapp` the `url` is still a PlanVortex page with one button, because Meta's popup only opens on our domain; the picker after it is yours.\n\nPlanVortex's domain does show in the address bar on the way back: networks only return to the URLs registered in their own portals.\n\nIf you send `redirect_uri` it has to be one of the app's `redirect_urls`, or the call answers error 532.",
9232
9232
  "operationId": "createTemporalConnectToken",
9233
9233
  "x-planvortex-identity": [
9234
9234
  "current_app"
@@ -9312,7 +9312,7 @@
9312
9312
  }
9313
9313
  },
9314
9314
  "400": {
9315
- "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials: neither a user token nor a temporal connect token can issue one |\n| `516` | The plan is free, `social_network` needs a paid plan (today, `whatsapp`) and the organization has no active account of it to reconnect |\n| `532` | `redirect_uri` is not one of the app's registered `redirect_urls` |\n| `549` | `account_selection` is not `planvortex` or `integrator`, or it is `integrator` without `redirect_uri` or `social_network`. `data` says which |\n| `550` | `account_selection=integrator` on a network with no return to the browser (`telegram`) |\n| `702` | `social_network` is not one of the networks PlanVortex supports |\n| `1101` | Invalid organization |",
9315
+ "description": "The request failed. The body carries the PlanVortex error code in `code`:\n\n| Code | Meaning |\n| --- | --- |\n| `514` | This endpoint needs app credentials: neither a user token nor a temporal connect token can issue one |\n| `516` | The plan is free, `social_network` needs a paid plan (today, `whatsapp` and `google_business`) and the organization has no active account of it to reconnect |\n| `532` | `redirect_uri` is not one of the app's registered `redirect_urls` |\n| `549` | `account_selection` is not `planvortex` or `integrator`, or it is `integrator` without `redirect_uri` or `social_network`. `data` says which |\n| `550` | `account_selection=integrator` on a network with no return to the browser (`telegram`) |\n| `702` | `social_network` is not one of the networks PlanVortex supports |\n| `1101` | Invalid organization |",
9316
9316
  "content": {
9317
9317
  "application/json": {
9318
9318
  "schema": {
@@ -14952,13 +14952,21 @@
14952
14952
  ],
14953
14953
  "description": "Current consumption across every organization of the client. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent this calendar month."
14954
14954
  },
14955
+ "pool_use": {
14956
+ "allOf": [
14957
+ {
14958
+ "$ref": "#/components/schemas/PlanUseData"
14959
+ }
14960
+ ],
14961
+ "description": "What the client's shared pool is using: the root organizations without a plan of their own and the folders below them, which is the `actual_use` each of them shows. **Only present with `getUse=true`.** Together with `actual_asigned` and the plan it splits the plan in three: used by the shared pool, free in the shared pool, and handed out to organizations with a plan of their own. `apps` is not here: apps belong to the client, not to an organization."
14962
+ },
14955
14963
  "actual_asigned": {
14956
14964
  "allOf": [
14957
14965
  {
14958
14966
  "$ref": "#/components/schemas/PlanData"
14959
14967
  }
14960
14968
  ],
14961
- "description": "What is already handed out to the client's root organizations, which is what is left to assign. **Only present with `getUse=true`.**"
14969
+ "description": "What is already handed out to organizations with a plan of their own (root organizations, or organizations under a folder), which is not available to the shared pool any more. **Only present with `getUse=true`.**"
14962
14970
  }
14963
14971
  }
14964
14972
  },
@@ -15575,10 +15583,11 @@
15575
15583
  },
15576
15584
  "name": {
15577
15585
  "type": "string",
15578
- "description": "Display name. Always present for a review, including anonymous ones, which get a placeholder rather than an empty string."
15586
+ "description": "Display name. Always present for a review, including anonymous ones, which get a placeholder rather than an empty string. On LinkedIn it is read from LinkedIn on every request and is not stored by PlanVortex: it is absent when LinkedIn does not return the member's profile, and LinkedIn only lets you cache it for 24 hours (see the LinkedIn section above)."
15579
15587
  },
15580
15588
  "profile_pic": {
15581
- "type": "string"
15589
+ "type": "string",
15590
+ "description": "Link to the author's picture, when the network gives one. On LinkedIn it is read on every request like `name`, it is a signed link that expires after a few weeks, and LinkedIn's servers refuse most downloads that do not come from a browser: show it in an `<img>`, do not copy it."
15582
15591
  },
15583
15592
  "is_own": {
15584
15593
  "type": "boolean",
@@ -17265,7 +17274,18 @@
17265
17274
  ]
17266
17275
  },
17267
17276
  "read": {
17268
- "type": "boolean"
17277
+ "type": "boolean",
17278
+ "description": "On a message from the contact, whether someone has read it in PlanVortex. On one of ours it is **not** a read receipt (messages sent from the WhatsApp Business app, or imported from the network, are stored as read): use `delivery_status`."
17279
+ },
17280
+ "delivery_status": {
17281
+ "type": "string",
17282
+ "enum": [
17283
+ "sent",
17284
+ "delivered",
17285
+ "read",
17286
+ "failed"
17287
+ ],
17288
+ "description": "Only on messages **we** sent (`contact_id`): how far the message got, like the ticks in WhatsApp. `sent` means the network accepted it, `delivered` that it reached the contact's device, `read` that the contact saw it, and `failed` that the network rejected it (`message_errors` says why).\n\nIt only moves forward, and each network reports what it can. WhatsApp and Messenger report all three steps, Instagram reports `sent` and `read` (it does not report delivery), and Bluesky only `sent`. A read receipt also covers the earlier messages to that contact, the same as opening the chat.\n\nAbsent when PlanVortex does not know: messages from the contact, messages sent before 15 November 2026 and messages imported from the network's history.\n\nNo webhook event is sent for `delivered`: read the field on the message. A `read` arrives as `messaging_seen`."
17269
17289
  },
17270
17290
  "text": {
17271
17291
  "type": "string",
@@ -17632,7 +17652,15 @@
17632
17652
  "$ref": "#/components/schemas/PlanUseData"
17633
17653
  }
17634
17654
  ],
17635
- "description": "Current consumption. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent in the current calendar month; the rest is what exists right now."
17655
+ "description": "What the plan this organization draws from is using, which is the figure the server checks before letting one more account or integration in: the owner of that plan (this organization if it has a plan of its own, otherwise its nearest parent with one, otherwise the client's shared pool) plus the folders without a plan below it. Organizations sharing a pool therefore show the same `actual_use`; what each one uses on its own is `own_use`. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent in the current calendar month; the rest is what exists right now."
17656
+ },
17657
+ "own_use": {
17658
+ "allOf": [
17659
+ {
17660
+ "$ref": "#/components/schemas/PlanUseData"
17661
+ }
17662
+ ],
17663
+ "description": "What THIS organization uses on its own, without the folders it shares a plan with. **Only present with `getUse=true`.** `actual_use` is the consumption of the whole pool this organization draws from (the same figure the server checks before letting one more account in), so every organization without a plan of its own shows the same `actual_use`; `own_use` is what hangs from this one. Adding up the `own_use` of the organizations that share a pool gives that pool's `actual_use`. On an organization with a plan of its own and no folders below it, both are the same."
17636
17664
  },
17637
17665
  "actual_asigned": {
17638
17666
  "allOf": [
@@ -9,7 +9,7 @@ name = "planvortex"
9
9
  # entonces `project.version` desapareceria del pyproject y el paso del workflow de release que
10
10
  # compara el tag con la version —que lo lee con `tomllib`— dejaria de encontrarla. Se quedan las dos
11
11
  # y las ata `tests/test_packaging.py`, que falla si se separan.
12
- version = "0.19.0"
12
+ version = "0.20.0"
13
13
  description = "Official Python client for the PlanVortex API"
14
14
  readme = "README.md"
15
15
  requires-python = ">=3.10"
@@ -946,9 +946,12 @@ class CommentsCommentAuthor(TypedDict):
946
946
  """
947
947
  name: NotRequired[str]
948
948
  """
949
- Display name. Always present for a review, including anonymous ones, which get a placeholder rather than an empty string.
949
+ Display name. Always present for a review, including anonymous ones, which get a placeholder rather than an empty string. On LinkedIn it is read from LinkedIn on every request and is not stored by PlanVortex: it is absent when LinkedIn does not return the member's profile, and LinkedIn only lets you cache it for 24 hours (see the LinkedIn section above).
950
950
  """
951
951
  profile_pic: NotRequired[str]
952
+ """
953
+ Link to the author's picture, when the network gives one. On LinkedIn it is read on every request like `name`, it is a signed link that expires after a few weeks, and LinkedIn's servers refuse most downloads that do not come from a browser: show it in an `<img>`, do not copy it.
954
+ """
952
955
  is_own: bool
953
956
  """
954
957
  Whether the connected account wrote it. This is what separates "delete mine" from "delete theirs", and what keeps your own replies out of the inbox.
@@ -3476,7 +3479,11 @@ class Organization(TypedDict):
3476
3479
  """
3477
3480
  actual_use: NotRequired[PlanUseData]
3478
3481
  """
3479
- Current consumption. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent in the current calendar month; the rest is what exists right now.
3482
+ What the plan this organization draws from is using, which is the figure the server checks before letting one more account or integration in: the owner of that plan (this organization if it has a plan of its own, otherwise its nearest parent with one, otherwise the client's shared pool) plus the folders without a plan below it. Organizations sharing a pool therefore show the same `actual_use`; what each one uses on its own is `own_use`. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent in the current calendar month; the rest is what exists right now.
3483
+ """
3484
+ own_use: NotRequired[PlanUseData]
3485
+ """
3486
+ What THIS organization uses on its own, without the folders it shares a plan with. **Only present with `getUse=true`.** `actual_use` is the consumption of the whole pool this organization draws from (the same figure the server checks before letting one more account in), so every organization without a plan of its own shows the same `actual_use`; `own_use` is what hangs from this one. Adding up the `own_use` of the organizations that share a pool gives that pool's `actual_use`. On an organization with a plan of its own and no folders below it, both are the same.
3480
3487
  """
3481
3488
  actual_asigned: NotRequired[PlanData]
3482
3489
  """
@@ -3998,9 +4005,13 @@ class ClientsClient(TypedDict):
3998
4005
  """
3999
4006
  Current consumption across every organization of the client. **Only present with `getUse=true`.** `twitter_credits` and `ai_credits` are what has been spent this calendar month.
4000
4007
  """
4008
+ pool_use: NotRequired[PlanUseData]
4009
+ """
4010
+ What the client's shared pool is using: the root organizations without a plan of their own and the folders below them, which is the `actual_use` each of them shows. **Only present with `getUse=true`.** Together with `actual_asigned` and the plan it splits the plan in three: used by the shared pool, free in the shared pool, and handed out to organizations with a plan of their own. `apps` is not here: apps belong to the client, not to an organization.
4011
+ """
4001
4012
  actual_asigned: NotRequired[PlanData]
4002
4013
  """
4003
- What is already handed out to the client's root organizations, which is what is left to assign. **Only present with `getUse=true`.**
4014
+ What is already handed out to organizations with a plan of their own (root organizations, or organizations under a folder), which is not available to the shared pool any more. **Only present with `getUse=true`.**
4004
4015
  """
4005
4016
 
4006
4017
 
@@ -4213,6 +4224,19 @@ class Message(TypedDict):
4213
4224
  Set when the **contact** wrote to us.
4214
4225
  """
4215
4226
  read: bool
4227
+ """
4228
+ On a message from the contact, whether someone has read it in PlanVortex. On one of ours it is **not** a read receipt (messages sent from the WhatsApp Business app, or imported from the network, are stored as read): use `delivery_status`.
4229
+ """
4230
+ delivery_status: NotRequired[Literal["sent", "delivered", "read", "failed"]]
4231
+ """
4232
+ Only on messages **we** sent (`contact_id`): how far the message got, like the ticks in WhatsApp. `sent` means the network accepted it, `delivered` that it reached the contact's device, `read` that the contact saw it, and `failed` that the network rejected it (`message_errors` says why).
4233
+
4234
+ It only moves forward, and each network reports what it can. WhatsApp and Messenger report all three steps, Instagram reports `sent` and `read` (it does not report delivery), and Bluesky only `sent`. A read receipt also covers the earlier messages to that contact, the same as opening the chat.
4235
+
4236
+ Absent when PlanVortex does not know: messages from the contact, messages sent before 15 November 2026 and messages imported from the network's history.
4237
+
4238
+ No webhook event is sent for `delivered`: read the field on the message. A `read` arrives as `messaging_seen`.
4239
+ """
4216
4240
  text: NotRequired[str]
4217
4241
  """
4218
4242
  Absent on the messages that carry no text of their own, such as a `messaging_seen` acknowledgement.
@@ -121,13 +121,19 @@ class ConnectToken(TypedDict):
121
121
  class OrganizationUse(TypedDict):
122
122
  """What an organization spends and what it has already handed down to its children.
123
123
 
124
- Both are missing when the server was not asked for them, which is why they are optional here:
125
- the two figures come from an aggregation over every organization underneath, so they only travel
126
- with ``get_use=True``.
124
+ All of them are missing when the server was not asked for them, which is why they are optional
125
+ here: the figures come from an aggregation over every organization underneath, so they only
126
+ travel with ``get_use=True``.
127
+
128
+ Mind which one you paint. ``actual_use`` is what the whole POOL this organization draws from is
129
+ using (itself plus the folders without a plan that spend from it), the figure the server checks
130
+ before letting one more account in, so every organization in a pool shows the same one.
131
+ ``own_use`` is this organization on its own; a server older than November 2026 does not send it.
127
132
  """
128
133
 
129
134
  actual_use: NotRequired[PlanUseData]
130
135
  actual_asigned: NotRequired[PlanData]
136
+ own_use: NotRequired[PlanUseData]
131
137
 
132
138
 
133
139
  # =================================================================================================
@@ -12,7 +12,7 @@ from __future__ import annotations
12
12
 
13
13
  import platform
14
14
 
15
- VERSION = "0.19.0"
15
+ VERSION = "0.20.0"
16
16
 
17
17
  # Sin barra final, y con el `/v1.0.0` dentro: la version de la API es parte de la ruta, no una
18
18
  # cabecera, asi que una `base_url` sin ella da 404 en todo.
@@ -6,9 +6,12 @@ audited it and it was easy to read the wrong field: ``client["actual_plan"]`` is
6
6
  inside it, in ``actual_plan["plan_data"]``. Looking at ``plan_identifier`` to work out the limits is
7
7
  the classic mistake: a ``custom`` plan carries its own.
8
8
 
9
- And THE CONSUMPTION DOES NOT TRAVEL UNLESS ASKED FOR: ``actual_use`` and ``actual_asigned`` only
10
- appear with ``get_use=True``, because counting them is an aggregation over every organization of the
11
- client.
9
+ And THE CONSUMPTION DOES NOT TRAVEL UNLESS ASKED FOR: ``actual_use``, ``pool_use`` and
10
+ ``actual_asigned`` only appear with ``get_use=True``, because counting them is an aggregation over
11
+ every organization of the client. Between them they split the plan: ``actual_use`` is what EVERY
12
+ organization uses (what is billed), ``pool_use`` what the shared pool uses (the organizations without
13
+ a plan of their own that draw straight from the client) and ``actual_asigned`` what is handed out to
14
+ the ones with a plan of their own. What is free in the pool is the plan minus the last two.
12
15
 
13
16
  THIS FILE IS THE SOURCE OF ``resources_sync/clients.py``.
14
17
  """
@@ -36,8 +39,8 @@ class AsyncClientsResource(AsyncResource):
36
39
  ) -> Page[Client]:
37
40
  """The clients the caller can see. With app credentials, its own.
38
41
 
39
- ``get_use`` also brings ``actual_use`` and ``actual_asigned``. It costs an aggregation: do
40
- not ask for it out of habit.
42
+ ``get_use`` also brings ``actual_use``, ``pool_use`` and ``actual_asigned``. It costs an
43
+ aggregation: do not ask for it out of habit.
41
44
  """
42
45
  pagina: Page[Client] = await self._list(
43
46
  "/clients", "clients", _list_query(limit, offset, get_use), timeout=timeout
@@ -37,8 +37,8 @@ class AsyncOrganizationsResource(AsyncResource):
37
37
  ) -> Organization:
38
38
  """One organization's record.
39
39
 
40
- ``get_use`` also brings ``actual_use`` and ``actual_asigned``, which cost an aggregation over
41
- everything underneath: do not ask for them out of habit.
40
+ ``get_use`` also brings ``actual_use``, ``own_use`` and ``actual_asigned``, which cost an
41
+ aggregation over everything underneath: do not ask for them out of habit.
42
42
  """
43
43
  organizacion: Organization = await self._one(
44
44
  self._path(id_organization),
@@ -139,9 +139,12 @@ class AsyncOrganizationsResource(AsyncResource):
139
139
  async def use(self, id_organization: str, *, timeout: float | None = None) -> OrganizationUse:
140
140
  """This organization's consumption and what it has already handed down to its children.
141
141
 
142
- It is a shortcut for ``get(id, get_use=True)`` that returns only the two figures, which is
142
+ It is a shortcut for ``get(id, get_use=True)`` that returns only those figures, which is
143
143
  what you want when painting a "3 of 5 accounts" bar. For the client-wide numbers and the
144
144
  rest of the dashboard there is ``pv.dashboard``.
145
+
146
+ ``actual_use`` is the pool this organization draws from, the same figure for every
147
+ organization in it; what this one uses on its own is ``own_use``.
145
148
  """
146
149
  organizacion = await self.get(id_organization, get_use=True, timeout=timeout)
147
150
  uso: OrganizationUse = {}
@@ -149,6 +152,8 @@ class AsyncOrganizationsResource(AsyncResource):
149
152
  uso["actual_use"] = organizacion["actual_use"]
150
153
  if "actual_asigned" in organizacion:
151
154
  uso["actual_asigned"] = organizacion["actual_asigned"]
155
+ if "own_use" in organizacion:
156
+ uso["own_use"] = organizacion["own_use"]
152
157
  return uso
153
158
 
154
159
  async def create_connect_token(
@@ -29,8 +29,8 @@ class ClientsResource(Resource):
29
29
  ) -> Page[Client]:
30
30
  """The clients the caller can see. With app credentials, its own.
31
31
 
32
- ``get_use`` also brings ``actual_use`` and ``actual_asigned``. It costs an aggregation: do
33
- not ask for it out of habit.
32
+ ``get_use`` also brings ``actual_use``, ``pool_use`` and ``actual_asigned``. It costs an
33
+ aggregation: do not ask for it out of habit.
34
34
  """
35
35
  pagina: Page[Client] = self._list(
36
36
  "/clients", "clients", _list_query(limit, offset, get_use), timeout=timeout
@@ -34,8 +34,8 @@ class OrganizationsResource(Resource):
34
34
  ) -> Organization:
35
35
  """One organization's record.
36
36
 
37
- ``get_use`` also brings ``actual_use`` and ``actual_asigned``, which cost an aggregation over
38
- everything underneath: do not ask for them out of habit.
37
+ ``get_use`` also brings ``actual_use``, ``own_use`` and ``actual_asigned``, which cost an
38
+ aggregation over everything underneath: do not ask for them out of habit.
39
39
  """
40
40
  organizacion: Organization = self._one(
41
41
  self._path(id_organization),
@@ -136,9 +136,12 @@ class OrganizationsResource(Resource):
136
136
  def use(self, id_organization: str, *, timeout: float | None = None) -> OrganizationUse:
137
137
  """This organization's consumption and what it has already handed down to its children.
138
138
 
139
- It is a shortcut for ``get(id, get_use=True)`` that returns only the two figures, which is
139
+ It is a shortcut for ``get(id, get_use=True)`` that returns only those figures, which is
140
140
  what you want when painting a "3 of 5 accounts" bar. For the client-wide numbers and the
141
141
  rest of the dashboard there is ``pv.dashboard``.
142
+
143
+ ``actual_use`` is the pool this organization draws from, the same figure for every
144
+ organization in it; what this one uses on its own is ``own_use``.
142
145
  """
143
146
  organizacion = self.get(id_organization, get_use=True, timeout=timeout)
144
147
  uso: OrganizationUse = {}
@@ -146,6 +149,8 @@ class OrganizationsResource(Resource):
146
149
  uso["actual_use"] = organizacion["actual_use"]
147
150
  if "actual_asigned" in organizacion:
148
151
  uso["actual_asigned"] = organizacion["actual_asigned"]
152
+ if "own_use" in organizacion:
153
+ uso["own_use"] = organizacion["own_use"]
149
154
  return uso
150
155
 
151
156
  def create_connect_token(
@@ -92,6 +92,26 @@ def test_use_es_un_atajo_de_get_con_get_use(cliente: ClienteDePrueba, httpx_mock
92
92
  assert ruta(unica(httpx_mock)) == "/organizations/org1"
93
93
 
94
94
 
95
+ def test_use_trae_own_use_lo_de_esta_organizacion_sola(
96
+ cliente: ClienteDePrueba, httpx_mock: HTTPXMock
97
+ ) -> None:
98
+ """`actual_use` es la bolsa que comparte; `own_use`, lo suyo. Los dos viajan si vienen."""
99
+ httpx_mock.add_response(
100
+ url=f"{ORG}?getUse=true",
101
+ json={
102
+ "organization": {
103
+ **ORGANIZACION,
104
+ "actual_use": {"accounts": 3},
105
+ "own_use": {"accounts": 1},
106
+ }
107
+ },
108
+ )
109
+
110
+ uso = cliente.esperar(cliente.pv.organizations.use("org1"))
111
+
112
+ assert uso == {"actual_use": {"accounts": 3}, "own_use": {"accounts": 1}}
113
+
114
+
95
115
  def test_use_no_inventa_las_dos_cifras_cuando_no_vienen(
96
116
  cliente: ClienteDePrueba, httpx_mock: HTTPXMock
97
117
  ) -> None:
@@ -11,7 +11,17 @@ solo se probara con la poblada pasaria igual escribiendo `resource["id_account"]
11
11
 
12
12
  from __future__ import annotations
13
13
 
14
- from typing import Any, TypeGuard, cast, get_type_hints
14
+ import sys
15
+ from typing import Any, TypeGuard, cast
16
+
17
+ # El mismo corte que `_generated/models.py`: en 3.10 los modelos usan el `NotRequired` de
18
+ # `typing_extensions`, y el `get_type_hints` de `typing` de 3.10 no lo reconoce, asi que lo deja
19
+ # envolviendo el tipo (`NotRequired[X] is X` da falso). El de `typing_extensions` lo quita en todas
20
+ # las versiones. Desde el 02-10-2026 la CI de 3.10 estuvo en rojo por esto.
21
+ if sys.version_info >= (3, 11):
22
+ from typing import get_type_hints
23
+ else:
24
+ from typing_extensions import get_type_hints
15
25
 
16
26
  from planvortex.types import (
17
27
  COMMENT_NETWORKS,
File without changes
File without changes
File without changes