planvortex 0.0.1__tar.gz → 0.2.0__tar.gz

{planvortex-0.0.1 → planvortex-0.2.0}/.gitignore

@@ -5,6 +5,9 @@ dist/
 build/
 *.egg-info/
 site/
+# La referencia se GENERA (`scripts/build_docs.py`) y la publica la CI en cada push a main. Si se
+# commiteara, la pagina publicada seria la de la ultima vez que alguien se acordo de regenerarla.
+docs/
 
 # Cachés de herramientas
 __pycache__/

planvortex-0.2.0/CHANGELOG.md

@@ -0,0 +1,177 @@
+# Changelog
+
+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.2.0] - 2026-08-30
+
+Telegram, the eleventh network, reaches the package. No endpoint was added and no signature moved:
+what changes is what the types know — and unlike in the Node library, where an open enumeration
+absorbs an unknown network in silence, here the closed `Literal`s go red until somebody looks. Which
+is the point of them.
+
+Upgrading from `0.1.0` needs no changes, and `MIGRATION.md` gains no entry.
+
+### Added
+
+- **A third authorization shape: `TelegramBotAuthorization`, with its predicate
+  `is_telegram_bot_authorization`.** This is the part that is genuinely new contract rather than one
+  more name in a list. Telegram is the one entry that carries a `link` and still is not somewhere to
+  redirect: it opens a private chat with the PlanVortex bot, with no OAuth behind it — no consent
+  screen, no `code`, no `redirect_uri` — and the account is born minutes later, when the person
+  drops that bot into their channel. It is announced over the WebSocket and the `new_account`
+  webhook, never as the answer to a call of yours, and `accounts.connect` cannot finish it: for
+  `telegram` that endpoint always answers 700. The block carries `bot_username` (the bot's `@name`,
+  without the at sign) and `add_to_group_link`, the second step, which turns comments on by adding
+  the bot to the channel's linked discussion group. **Branch on `authorization["type"]`, never on
+  whether `link` is empty** — that test was already wrong for WhatsApp and it is worse here, because
+  a filled-in `link` makes it look like it worked.
+- **`"telegram"` in `PublishableNetwork`** — the one hand-written union in `_shapes.py` — and
+  therefore in `PUBLISHABLE_NETWORKS`, `COMMENT_NETWORKS` and `SOCIAL_NETWORKS`, which derive from
+  their `Literal` and needed no edit. It is deliberately **not** in `CONTACT_CHANNELS`: Telegram has
+  no direct messages, and putting it there would promise a chat inbox that does not exist. That the
+  contact channels are now a proper subset of the networks, rather than all of them plus `email`, is
+  written down in the test that used to assert the equality.
+- **`PublicationStats.reactions` and `reactions_by_emoji`**, which are Telegram's only publication
+  metric — and neither of them is asked for. `reactions` is the COMPLETE STATE and not an increment,
+  so it goes down when somebody takes theirs back.
+- **`Publication.extra_data`**, for what one network has to remember about one publication and that
+  has no common field. Today only `telegram_message_ids` writes there: on Telegram an album is one
+  publication that is several messages, `external_identifier` holds the first and the rest live
+  here, because deleting the album means deleting all of them.
+
+### Changed
+
+- The network-counting prose, which had quietly stopped being true and that no test watches:
+  `accounts.connect_links`, `SocialAuthorizationMethod`, `ConnectLink`, `PublishableNetwork` and
+  `is_publishable_network` all said "nine of the ten" or "one of ten and one of nine".
+- Two warnings about this network are now on the methods that would otherwise surprise you, because
+  neither has an error code to announce it. **The comment inbox starts the day the channel was
+  connected** — the Bot API cannot read the past, so `comments.list` has nothing earlier and never
+  will, and `comments.thread`, which is a live read on every other network, is not live here at all.
+  And **there are no impressions and no reach**: engagement is computed over followers, the only
+  audience figure the Bot API publishes being the channel's member count.
+- `catalog.social_limits` explains Telegram's **two numbers for the same field** — 4.096 characters
+  while the publication is text only and 1.024 the moment it carries an image or a video, because
+  then the text is a media caption. The counter switches when the file is attached, not when publish
+  is pressed.
+- `publications.remove` documents Telegram's **48-hour window** (error 966, with `published_date`
+  and `max_hours` in `data`), which is a button to grey out rather than to offer and fail.
+- `examples/connect.py` grows the third branch, and its `else` — the one that skips an authorization
+  method this version does not know — is no longer hypothetical: `telegram_bot` was exactly that.
+
+### Fixed
+
+- The synchronous twin of `products.get` had been left behind by the previous release: its docstring
+  still said the Node library documented that endpoint as broken. Regenerating `resources_sync`
+  brings it back in line.
+
+## [0.1.0] - 2026-08-28
+
+The first release with code in it. Every documented endpoint of the PlanVortex API has a method -
+**112 of the 112 operations** - in two clients that cannot drift apart, the types come from the same
+OpenAPI document the API publishes, the three test layers are in place (the third against a real
+PlanVortex) and the reference is published. It is a `0.x` on purpose: the shape of the client is
+settled and pinned by tests, but nobody outside has used it yet, so a break before `1.0.0` is
+possible and would arrive written down in `MIGRATION.md`.
+
+The `0.0.1` already on PyPI carries no code. It was published on 2026-08-26 to reserve the name and
+to prove the release pipeline before there was anything to lose.
+
+### Added
+
+- The **types**, generated from the OpenAPI document PlanVortex publishes and exposed with readable
+  names in `planvortex.types`: `Publication`, `Account`, `Upload`, `Comment`, `Message`, `Contact`
+  and the rest of the API's shapes, as `TypedDict`. The API's field names survive untranslated, so
+  it is `publication["_id"]` and not `publication.id`.
+- The value lists, at the package root and at runtime: `SOCIAL_NETWORKS`, `PUBLICATION_STATES`,
+  `PUBLICATION_TYPES`, `COMMENT_NETWORKS`, `CONTACT_CHANNELS`, `MESSAGE_TYPES`,
+  `INTEGRATION_PROVIDERS` and `AI_PLAN_STATES`. Each one is derived from the same `Literal` the type
+  checker reads, so the two cannot disagree. **The lists grow**: a value you do not recognise is one
+  this release had not heard of, not an error.
+- Helpers for the fields the API returns in two shapes: `account_id()`, `account()`,
+  `publication_id()`, `publication()`, `message_direction()`, `message_contact_id()`,
+  `message_contact()`, `message_files()` and `message_file_ids()`. `id_account` arrives resolved in
+  some operations and as a string in others, and these cover it without an `isinstance` in every
+  call site.
+- The asynchronous and synchronous cores: HTTP with timeouts, backoff and retry rules, the
+  `client_credentials` token with its cache and its lock, the error hierarchy, and the query encoder
+  with the camelCase map.
+- **The two clients**, `PlanVortex` and `AsyncPlanVortex`, with **fourteen resources covering the
+  whole public API**: `catalog`, `clients`, `organizations`, `accounts`, `uploads`, `publications`,
+  `comments`, `messages`, `contacts`, `products`, `integrations`, `ai_plans`, `dashboard` and
+  `apps` — **112 of the 112 operations** the specification documents, everything except the 19
+  routes of roles and invitations, which are out of scope. The synchronous client is generated from
+  the asynchronous one, so they cannot drift apart, and `scripts/route_coverage.py` walks the
+  OpenAPI bundle on every test run so that "no route is missing" keeps being true.
+- Three things that **used to be documented as broken and work now**, fixed in the server on
+  2026-08-24 and exposed here for the first time: filtering contacts by `social_network`, asking for
+  one product by `product_id` (`products.get()`, which also tolerates the single-object shape the
+  network answers with), and `in_response_external_id` in `messages.send()`, which is what makes
+  `comment_message` and `publication_message` reachable from the public API.
+- `contacts.merge()`, which reads the contact before updating it so that its `extra_data` is not
+  wiped: it is the one field the server overwrites with whatever the body carries.
+- `organizations.users()`, the one read of the roles section the library covers, because a custom
+  panel needs to paint the team.
+- `Page(data, total)` for every listing, with the API's envelope already opened, plus `iterate()` /
+  `aiterate()` to chain pages — with a page cap so that a server ignoring the `offset` fails instead
+  of hanging the process.
+- Uploading from a path, `bytes`, an open binary file or an iterable of `bytes`. A path is the one
+  that neither goes through memory nor asks you to close anything. A body that cannot be rewound
+  forbids the retry outright, because a second attempt over a spent stream uploads zero bytes.
+- `publish_date` accepts a `datetime` and is serialized with its offset. A naive one raises instead
+  of guessing: assuming UTC publishes at the wrong time for whoever is in Madrid, and assuming the
+  process's zone does it for whoever is in Docker.
+- `as_temporal_token()`, for the account-connection flow: an app cannot connect an account, so it
+  issues a temporal token and hands it to the person who can.
+- `is_publishable_network()`, a `TypeGuard` narrowing a network down to the **nine** that accept
+  publications, and `PUBLISHABLE_NETWORKS` beside it. An account's `social_network` is one of ten
+  and a publication's is one of nine — `google_business` receives reviews, not posts — so handing
+  one to the other was a type error with no way out that did not throw away a real guarantee.
+- **Five runnable examples**, each with a test of its own: `publish.py` (credentials to a scheduled
+  publication), `schedule.py` (the calendar, moving a post, rescuing a failed one), `comments.py`
+  (inbox, actions matrix, live thread and replying — read-only unless `PLANVORTEX_ALLOW_REPLY=1`),
+  `webhooks.py` (a receiver with no dependencies, and a `--self-test` that signs a delivery to
+  itself) and `connect.py` (the connection flow, and what the browser has to do).
+- **The published reference**, generated with `pdoc` from the docstrings and deployed to GitHub
+  Pages on every push to `main`: <https://taliasoftworks.github.io/PlanVortexPython/>.
+- **`planvortex.webhooks`**, in a module of its own because whoever receives deliveries is rarely
+  the process that publishes: `verify_webhook_signature()` over the **raw** body with a constant-time
+  comparison, `parse_webhook_body()` (the body is an **array** of changes), and
+  `handle_webhook_request()`, which does both and finds the signature header whatever your framework
+  calls it. No framework middleware is shipped: the README carries the Flask, FastAPI and Django
+  recipes, each with the one line that gives you the raw body.
+- The webhook event types, split by `field` so they can be narrowed — `AccountStateChange`,
+  `MessageChange`, `CommentChange` and `IntegrationErrorChange` — with the predicates
+  `is_comment_change()` and friends, and `UnknownWebhookChange` for the events a future server sends
+  and this release has never heard of. `WebhookSignatureError` and `WebhookBodyError` are
+  `PlanVortexError` of family `webhook`.
+
+- **The live test suite** (`tests/live/`), which talks to a real PlanVortex and is the only layer
+  that can notice the *server* changing under the library: a renamed list envelope, an error code
+  that moved, a tenth social network. It ships in the sdist like the rest of the tests. It is not in
+  `uv run pytest` — it carries the `live` marker and is asked for with `uv run pytest -m live` — it
+  skips itself whole without `.env.live`, and everything that writes is behind `LIVE_ALLOW_PUBLISH`,
+  `LIVE_ALLOW_SOCIAL_PUBLISH` and `LIVE_ALLOW_PRODUCTION`. See `.env.live.example`.
+
+### Changed
+
+- `PublicationInput["publish_date"]` now **accepts a `datetime` in the type**, not only at runtime.
+  The generated type said `str`, so the usage the library documents did not type-check. It is the
+  one shape written by hand on top of the generated one, and it has a parity test against the
+  specification that allows exactly that one difference.
+- `examples/` is inside mypy's scope. It was the only code in the repository nobody checked, and
+  the two failures it turned up were holes in the library, not in the examples.
+- `typing-extensions` is now a dependency on **Python 3.10 only** (`python_version < "3.11"`), where
+  `NotRequired` is not yet in `typing`. Nothing is installed from 3.11 upwards.
+- The coverage floor is now enforced (`fail_under = 97`), measured over layers 1 and 2 — the ones
+  CI runs.
+
+## [0.0.1] - 2026-08-26
+
+Placeholder release. It reserves the `planvortex` name on PyPI and proves the trusted-publishing
+pipeline end to end before there is anything to lose. It contains no client.
+
+[0.1.0]: https://github.com/taliasoftworks/PlanVortexPython/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/taliasoftworks/PlanVortexPython/releases/tag/v0.0.1

planvortex-0.2.0/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.5
+Name: planvortex
+Version: 0.2.0
+Summary: Official Python client for the PlanVortex API
+Project-URL: Homepage, https://planvortex.com/developers
+Project-URL: Documentation, https://taliasoftworks.github.io/PlanVortexPython/
+Project-URL: API, https://planvortex.com/documentation
+Project-URL: Repository, https://github.com/taliasoftworks/PlanVortexPython
+Project-URL: Changelog, https://github.com/taliasoftworks/PlanVortexPython/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/taliasoftworks/PlanVortexPython/issues
+Author-email: Talia Softworks <contact@planvortex.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bluesky,facebook,instagram,linkedin,planvortex,publishing,scheduling,social media,tiktok
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx2<3,>=2.12
+Requires-Dist: typing-extensions>=4.5; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# planvortex
+
+[![PyPI](https://img.shields.io/pypi/v/planvortex.svg?color=2036d8&label=pypi)](https://pypi.org/project/planvortex/)
+[![python](https://img.shields.io/pypi/pyversions/planvortex.svg?color=2036d8)](https://pypi.org/project/planvortex/)
+[![CI](https://github.com/taliasoftworks/PlanVortexPython/actions/workflows/ci.yml/badge.svg)](https://github.com/taliasoftworks/PlanVortexPython/actions/workflows/ci.yml)
+[![license](https://img.shields.io/pypi/l/planvortex.svg?color=2036d8)](./LICENSE)
+
+The official Python client for the [PlanVortex](https://planvortex.com) API — connect social
+accounts, schedule and publish posts, read comments and messages, and pull stats, from Python.
+
+```bash
+pip install planvortex
+```
+
+- **Synchronous and asynchronous**, same surface: `PlanVortex` and `AsyncPlanVortex`.
+- **Typed**, from the same OpenAPI specification the API publishes at
+  <https://planvortex.com/openapi.json>. Returned shapes are `TypedDict`, so `_id` stays `_id`.
+- **One runtime dependency**, `httpx2` — a different package from `httpx` classic, so it will not
+  collide with whatever your project already uses.
+- **Server-side.** The `client_credentials` flow needs your `client_secret`, which must never reach
+  a browser. Connecting an account from one is what the [temporal connect token](#connecting-an-account)
+  is for.
+- Python 3.10 and newer.
+
+**Reference:** <https://taliasoftworks.github.io/PlanVortexPython/> · **Guides:**
+[planvortex.com/developers](https://planvortex.com/developers)
+
+## Authentication
+
+Your credentials are a **client app**'s: you create one in the PlanVortex panel and it gives you a
+`client_id` and a `client_secret`. They are read from the environment, so nothing is hardcoded:
+
+```bash
+export PLANVORTEX_CLIENT_ID=...
+export PLANVORTEX_CLIENT_SECRET=...
+# Only if you are not talking to production:
+export PLANVORTEX_BASE_URL=http://localhost:3000/v1.0.0
+```
+
+```python
+from planvortex import PlanVortex
+
+pv = PlanVortex()  # from the environment
+pv = PlanVortex(client_id="...", client_secret="...")  # or explicitly
+```
+
+The token is fetched on the first call, cached, and renewed before it expires — you never touch
+`/oauth/token`. Use the client as a context manager (`with PlanVortex() as pv:`) so the connection
+pool closes, and **keep one instance**: a new one per request throws away the cache and the pool.
+
+An app sees **its own client** and that client's organizations, and nothing else.
+
+## Publishing
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from planvortex import PlanVortex
+
+pv = PlanVortex()
+
+upload = pv.uploads.create(org_id, "./sourdough.jpg")
+publication = pv.publications.create(
+    org_id,
+    account_id,
+    {
+        "social_network": "instagram",
+        "text": "New oven, new loaves",
+        "files": [upload["_id"]],
+        "publish_date": datetime.now(timezone.utc) + timedelta(hours=1),
+    },
+)
+
+# A publication that could not be built is NOT an exception: it comes back saved, in `withErrors`,
+# with the reason inside. The content is validated against the network, and that is not a failure
+# of your request.
+if publication["state"] == "withErrors":
+    for failure in publication["publication_errors"]:
+        print(failure["code"], failure["message"])
+```
+
+`publish_date` takes a `datetime` as well as an ISO-8601 string, and **it has to carry a timezone**:
+a naive one raises rather than being guessed at, because assuming UTC publishes at the wrong time
+for whoever is in Madrid and assuming the process's zone does it for whoever is in Docker. With no
+`publish_date` at all it goes out in that same request, and the answer already says whether it did.
+
+A file can be a path, an open file, `bytes`, or a `(name, bytes)` pair. Per-network limits —
+characters, images, video length, file size — come from `pv.catalog.social_limits()`, which is the
+server's own copy: whoever enforces a limit is who gets to announce it.
+
+Listing gives you a page, and there is a chaining iterator for when you want them all:
+
+```python
+page = pv.accounts.list(org_id, limit=50)
+page.data, page.total
+
+for publication in pv.publications.iterate(org_id, state=["ready"]):
+    ...
+```
+
+The same code in async changes three things and no more — the class, an `await`, and `aiterate`:
+
+```python
+from planvortex import AsyncPlanVortex
+
+async with AsyncPlanVortex() as pv:
+    page = await pv.accounts.list(org_id, limit=50)
+    async for publication in pv.publications.aiterate(org_id, state=["ready"]):
+        ...
+```
+
+## Connecting an account
+
+Connecting is the one flow the library **cannot finish on its own**: it ends with a person pressing
+"allow" on Instagram's page. What the library does is hand you a URL to send them to.
+
+```python
+connection = pv.organizations.create_connect_token(org_id)
+# connection["url"] is where the person goes. Never send them your client_secret.
+
+person = pv.as_temporal_token(connection["token"])  # a client that can only do this
+for link in person.accounts.connect_links(org_id):
+    ...
+```
+
+Four things about that token, and each one bites separately: it lasts **fifteen minutes**, it is
+**single-use**, it is tied to **one** organization, and it **cannot issue another one**. Saving it
+for "next time" fails four different ways — issue a fresh one per connection, they are free.
+
+And one that trips people without giving an error: branch on `link["authorization"]["type"]`, never
+on the `link`. WhatsApp's is the empty string, because its sign-up is Meta's *Embedded Signup* popup
+and not an OAuth redirect; walking the list redirecting to `link` sends your user to your own page.
+
+Accounts come back **disabled** and take no plan slot until `pv.accounts.enable(...)`, and one
+authorization can leave several — a Facebook user with four pages is four of them.
+
+## Comments and messages
+
+```python
+# The comments inbox comes out of PlanVortex's database: free, fast, and a photograph of the last
+# time the network was read. The thread asks the network right then, and on X that costs credits.
+for comment in pv.comments.iterate(org_id, unread=True, rating=[1, 2]):
+    print(comment["rating"], comment["text"])
+
+thread = pv.comments.thread(org_id, publication_id)
+thread["credits_consumed"]  # real money on X, 0 everywhere else
+
+# Before painting a button, ask what the network allows: they are not all the same.
+if (pv.comments.actions_for("linkedin") or {}).get("hide"):
+    ...
+```
+
+## Errors
+
+Errors are classified by `code`, **never by the HTTP status** — every domain error in this API
+travels with a 400. Each range has its own exception class, so you can catch a family without
+memorising numbers:
+
+| Codes | Family | Exception |
+|---|---|---|
+| 500-544 | `auth` | `AuthError` |
+| 601-612 | `user` | `UserError` |
+| 700-715 | `account` | `AccountError` |
+| 800-810 | `file` | `FileError` |
+| 900-960 | `publication` | `PublicationError` |
+| 1000-1003 | `general` | `PlanVortexError` |
+| 1100-1111 | `organization` | `OrganizationError` |
+| 1200-1207 | `role` | `PlanVortexError` |
+| 1300-1307, 1400-1408 | `plan_limit` | `PlanLimitError` |
+| 1500-1512 | `messaging` | `MessagingError` |
+| 1600-1601 | `contact` | `ContactError` |
+| 1900-1906 | `payment` | `PlanVortexError` |
+| 2000-2099 | `product` | `ProductError` |
+| 2100-2199 | `ai_plan` | `AiPlanError` |
+| 2200-2299 | `integration` | `IntegrationError` |
+
+```python
+from planvortex import PlanLimitError, PlanVortexError
+
+try:
+    ...
+except PlanLimitError as error:
+    ...  # not fixed by retrying: fixed by changing plan
+except PlanVortexError as error:
+    error.code, error.family, error.message, error.data, error.status
+```
+
+The runtime list is `PLANVORTEX_ERROR_RANGES`. Two more that are not the API's answer:
+`PlanVortexConnectionError` (it never got there — retried already, on the methods where retrying is
+safe) and `PlanVortexConfigError` (something is wrong on this side, like a missing `client_secret`).
+
+## Webhooks
+
+PlanVortex `POST`s to your app when something happens: an account changed state, a message or a
+comment came in, an integration stopped working. Two things trip up everybody, so they go first.
+
+**The body is an array of changes**, not an object. And **the signature is computed over the raw
+body** — if your framework already parsed the JSON and you serialise it again, the bytes are not the
+same ones and the signature never matches. The line that gives you the raw body is the only line of
+the recipe that changes:
+
+```python
+# Flask
+import os
+
+from flask import request
+
+from planvortex.webhooks import handle_webhook_request, is_comment_change
+
+
+@app.post("/webhooks/planvortex")
+def planvortex_webhook():
+    changes = handle_webhook_request(
+        body=request.get_data(),  # raw! never request.json
+        headers=request.headers,
+        secret=os.environ["PLANVORTEX_CLIENT_SECRET"],
+    )
+    for change in changes:
+        if is_comment_change(change):
+            moderate(change.get("commentObj"))
+    return "", 200
+```
+
+```python
+# FastAPI
+@app.post("/webhooks/planvortex")
+async def planvortex_webhook(request: Request):
+    changes = handle_webhook_request(
+        body=await request.body(),  # raw! never the parsed model
+        headers=request.headers,
+        secret=os.environ["PLANVORTEX_CLIENT_SECRET"],
+    )
+    ...
+```
+
+```python
+# Django
+@csrf_exempt
+def planvortex_webhook(request):
+    changes = handle_webhook_request(
+        body=request.body,  # raw! never request.POST
+        headers=request.headers,
+        secret=os.environ["PLANVORTEX_CLIENT_SECRET"],
+    )
+    ...
+```
+
+`handle_webhook_request` raises `WebhookSignatureError` if the signature is missing or does not
+match (answer 401) and `WebhookBodyError` if the body is not what it has to be (answer 400). If you
+would rather do it in two steps, `verify_webhook_signature(payload, signature, secret)` returns a
+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
+`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.
+
+## The whole API, in fourteen resources
+
+`pv.catalog` · `pv.clients` · `pv.organizations` · `pv.accounts` · `pv.uploads` · `pv.publications`
+· `pv.comments` · `pv.messages` · `pv.contacts` · `pv.products` · `pv.integrations` · `pv.ai_plans`
+· `pv.dashboard` · `pv.apps`
+
+That is **112 of the 112 operations** the specification documents — everything except the 19 routes
+of roles and invitations, which are out of scope. A script walks the OpenAPI bundle on every test
+run and fails if a route is left without a method, so the sentence above stays true.
+
+## Examples
+
+Five runnable scripts, each one the whole of its path and with a test of its own:
+
+| | |
+|---|---|
+| [`examples/publish.py`](https://github.com/taliasoftworks/PlanVortexPython/blob/main/examples/publish.py) | Credentials, quota, account, network limits, upload, scheduled publication. |
+| [`examples/schedule.py`](https://github.com/taliasoftworks/PlanVortexPython/blob/main/examples/schedule.py) | The calendar: what is queued, moving it, and rescuing what failed. |
+| [`examples/comments.py`](https://github.com/taliasoftworks/PlanVortexPython/blob/main/examples/comments.py) | The inbox, the actions matrix, the live thread, and replying. |
+| [`examples/webhooks.py`](https://github.com/taliasoftworks/PlanVortexPython/blob/main/examples/webhooks.py) | A receiver with no dependencies. `--self-test` signs a delivery to itself. |
+| [`examples/connect.py`](https://github.com/taliasoftworks/PlanVortexPython/blob/main/examples/connect.py) | The connection flow, and what the browser has to do. |
+
+`comments.py` only reads unless you set `PLANVORTEX_ALLOW_REPLY=1`: replying is public, immediate,
+and reaches a person.
+
+## Links
+
+- [Reference](https://taliasoftworks.github.io/PlanVortexPython/)
+- [API documentation](https://planvortex.com/documentation)
+- [Developers](https://planvortex.com/developers)
+- [Node client](https://github.com/taliasoftworks/PlanVortexNode)
+- [Contributing](https://github.com/taliasoftworks/PlanVortexPython/blob/main/CONTRIBUTING.md) · [Security](https://github.com/taliasoftworks/PlanVortexPython/blob/main/SECURITY.md) · [Changelog](https://github.com/taliasoftworks/PlanVortexPython/blob/main/CHANGELOG.md)
+
+MIT © Talia Softworks