updo-sdk 0.2.0__tar.gz → 0.4.0__tar.gz

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

@@ -4,6 +4,147 @@ Format: [Keep a Changelog](https://keepachangelog.com/1.1.0/).
 Versioning: [SemVer](https://semver.org/) — on the SDK's own surface, not on the
 platform's. A backwards-compatible server change never forces a major bump here.
 
+## [0.4.0] — 2026-10-02
+
+### Field type `jurisdiction`
+
+- `updo codegen` maps the new `jurisdiction` field type to `str`. It arrived
+  server-side on 2026-10-01 and no contract check could see it: field types
+  live in tenant data, not in the OpenAPI document. Until mapped, such a field
+  generated `Any` -- silently, since the coverage test kept its own copy of the
+  server's type list and stayed green.
+- Documented: exact filters are case-sensitive, and a jurisdiction is stored as
+  an UPPERCASE ISO code (`CA`, `CA-QC`). `where={"work_jurisdiction": "ca-qc"}`
+  returns zero rows and no error.
+
+
+### Record PDFs
+
+- `client.entity(slug).pdf(record_id, template=..., language=..., dest=...)`
+  and `.documents()`, sync and async -- the two routes the platform added so an
+  external system can fetch an invoice (or any record) as the PDF the tenant
+  designed. Each call is a fresh render; nothing is archived server-side.
+- `dest` may be an existing DIRECTORY: the file takes the name the server
+  suggests (the record's reference, e.g. an invoice number). The name is
+  re-sanitised to `[A-Za-z0-9._-]`, last path component only -- a
+  `Content-Disposition` header never chooses where on the caller's disk the
+  SDK writes. With no usable suggestion the call is refused rather than
+  inventing a name the next call would overwrite. This applies to `export()`
+  too, whose CSV and XLSX responses carry a name as well.
+- `language` is validated against the renderer's own pattern before sending.
+  The server IGNORES a malformed value instead of refusing it, so
+  `language="fr_CA"` would have produced a PDF in the default language with a
+  200 -- the kind of mistake a customer finds before the integrator does.
+- The record id is validated as a UUID: the route is `<uuid:pk>`, and anything
+  else is Django's HTML 404, which carries none of the route's error codes.
+- `TemplateRequired` (a `ValidationError`) for `400 TEMPLATE_REQUIRED`, with
+  `.templates` listing the slugs to choose from.
+- `PermissionDenied.resources` -- the `data:<slug>` entities a template READS
+  and the token may not (an invoice prints its lines and its customer; one
+  missing right refuses the whole document) -- and `PermissionDenied.feature`
+  for `FEATURE_NOT_LICENSED`.
+
+### Export
+
+- `export(..., export_fields=["sku", "name"])` picks the columns and their
+  order. Refused locally: an EMPTY list, which the server reads as "not given"
+  and answers with every column, and a slug containing a comma, which it would
+  split in two. A plain string is refused too, since `"sku,name"` would iterate
+  character by character.
+
+### Contract
+
+- The OpenAPI fixture is refreshed: 25 -> 27 operations. `NOT_YET_EXPOSED`
+  stays empty -- the SDK reaches every documented operation.
+
+---
+
+## [0.3.0] — 2026-08-25
+
+### Record images
+
+- `client.entity(slug).images(record_id)` with `.list()`, `.upload()` and
+  `.delete()`, sync and async. Upload and publish are one call: a `201` means
+  the image is attached AND its `public_url` is live, and a refusal stores
+  nothing, so there is no half-done state to clean up.
+- `upload()` accepts a path, `bytes`, or a binary handle, and always reads the
+  file into memory. The transport replays a 429 even for POST -- a throttle
+  refuses before any side effect -- and a live handle would be at EOF on the
+  replay, uploading nothing and drawing "no file provided" for a file that was
+  plainly there.
+- `category` is a REQUIRED keyword although the server's schema marks it
+  optional. Publication checks it against the entity's `public_media` whitelist,
+  and the normaliser that builds that whitelist strips blank entries, so `""`
+  can never be a member: omitting the category is a guaranteed 409, not a
+  default. A parameter whose only optional value always fails is not optional.
+- Checked before sending, because each of these otherwise costs a full upload
+  and comes back as a code that names the lock rather than the fix: the file
+  signature (only PNG, JPEG, GIF and WebP publish -- SVG is excluded because it
+  executes script when served inline), the 10 MiB ceiling, `position` against
+  the `smallint` it lands in, and the alt-text bounds (125 characters per
+  language, 24 languages).
+- `PublicationRefused`, a `ConflictError` subclass carrying the server's stable
+  refusal `.code` plus a sentence saying what to do about it. `.is_configuration`
+  separates the four refusals only a Workshop or operator change can lift from
+  the one the caller fixes by sending different bytes -- the distinction that
+  stops a queue worker replaying a job forever against a lock nothing in its
+  reach can open.
+- `RecordImage.public_url` is deliberately NOT masked, unlike `PaymentLink.url`.
+  It carries no authority beyond "show these bytes" and exists to be pasted into
+  an `<img src>`; masking every URL because one URL is a secret is cargo cult.
+
+### Transport
+
+- `request()` accepts `files=` and `data=` for multipart bodies, sync and async.
+  No `Content-Type` is set in that case: httpx generates the boundary and puts
+  it in that header, and a boundary-less `multipart/form-data` is refused by
+  every parser. Passing both `json=` and `files=` raises `TypeError`.
+
+### Contract
+
+- `NOT_YET_EXPOSED` in the contract test is now EMPTY: the SDK reaches every
+  documented operation of the public surface. The set stays in place as the
+  declared home for the next gap, so "not covered yet" remains a written
+  decision rather than a silence.
+
+### CI
+
+The release jobs could not actually control which credential they used, and the
+guard that was supposed to catch that reported success. Three repairs, in the
+order they matter:
+
+- **The token is resolved in the shell, not in the job's `variables:`.** A
+  project-level CI/CD variable OUTRANKS a `variables:` entry of the same name,
+  so a project variable called `TWINE_PASSWORD` silently replaced whatever
+  `TWINE_PASSWORD: "$TESTPYPI_TOKEN"` resolved to. The rehearsal then presented
+  a pypi.org token to test.pypi.org and got a bare `403 Forbidden`. The
+  `TWINE_PASSWORD:` keys are gone from both jobs -- writing them there did not
+  decide what twine received, it only made the file look as though it did.
+- **The guard checks the value, not the name.** It used to assert that
+  `$TWINE_PASSWORD` was non-empty, which the overriding project variable
+  satisfied; it reported "credentials present" for a credential the job had not
+  chosen. It now derives which service ISSUED the token and refuses a mismatch
+  with the target index. A Warehouse token is `pypi-` plus base64url of a v2
+  macaroon whose first field is the issuing host, so every token from a given
+  service opens with the same literal -- `pypi-AgEIcHlwaS5v` for pypi.org,
+  `pypi-AgENdGVzdC5weXBpLm9y` for test.pypi.org. Twelve and twenty characters,
+  no more: base64 quantises three bytes at a time and only those are fixed by
+  the location alone. Nothing is decoded, no subprocess runs, and `unknown`
+  never blocks a release -- a check that cannot tell must not be why a publish
+  fails.
+- **`TWINE_USERNAME` is printed and asserted.** Its value is the literal
+  `__token__` and is not a secret. A CI/CD variable of that name outranks the
+  job's, and twine then authenticates as a real account with a token for a
+  password -- which PyPI also answers with a bare `403 Forbidden`, making the
+  two causes indistinguishable from the log. Printing it separates them at a
+  glance.
+
+`set +x` is now the first statement of the block rather than sitting below the
+resolution: measured, `sh -x` printed the token twice before reaching it. GitLab
+masks the exact value of a masked variable, never a fragment of one.
+
+---
+
 ## [0.2.0] — 2026-08-25
 
 ### Payment links

{updo_sdk-0.2.0/src/updo_sdk.egg-info → updo_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: updo-sdk
-Version: 0.2.0
+Version: 0.4.0
 Summary: Python SDK for the Updo360 (Qlaris) public ERP API
 Author: UPDO Technologies Inc.
 License-Expression: MIT
@@ -270,6 +270,13 @@ products.list(where=F(status="active") & F(sale_price__gte=10))
 > list-valued field: `tags__contains="promo"` finds records whose
 > `multi_select` includes that choice.
 
+**Exact matches are case-sensitive.** The server compares the stored JSON value
+as-is, without normalising it. That matters most for codes the platform
+normalises *on write*: a `jurisdiction` field stores ISO codes in uppercase
+(`CA` for a country, `CA-QC` for a subdivision — never a bare `QC`, which would
+be ambiguous with California's `US-CA`), so `where={"work_jurisdiction":
+"ca-qc"}` returns zero rows and no error. Pass `"CA-QC"`.
+
 An `__in` list cannot carry a value containing a comma: the server splits on
 commas and strips each part, so `["Dupont, Jean", "Tremblay"]` would arrive as
 three wrong terms. The SDK refuses such a value rather than sending it wrong.
@@ -372,6 +379,18 @@ data = products.export("csv")  # without dest: the bytes
 
 The export honours filters, search and ordering, and ignores pagination.
 
+```python
+products.export("csv", dest="short.csv", export_fields=["sku", "name", "sale_price"])
+```
+
+`export_fields` picks the columns **and their order**. Omitted, every readable
+column comes out in the entity's own order — relation ids included, which is
+what keeps the file re-importable. An unknown slug and one this token may not
+read get the *same* 400, on purpose. Two values are refused locally because the
+server would turn them into a silent surprise: an **empty list**, which reaches
+it as "not given" and exports every column, and a slug containing a comma,
+which it would split into two.
+
 > **The server truncates an export at 10 000 rows** — no header, no marker, no
 > error: a 40 000-record entity yields a perfectly well-formed CSV holding the
 > first 10 000. The SDK therefore counts first and **raises** rather than hand
@@ -381,6 +400,63 @@ The export honours filters, search and ordering, and ignores pagination.
 
 ---
 
+## Record PDFs (invoices, quotes, labels…)
+
+Render any record with one of the PDF templates designed for its entity — an
+invoice first of all.
+
+```python
+invoices = client.entity("invoice")
+
+for template in invoices.documents():
+    print(template.slug, template.display("fr"))
+
+pdf = invoices.pdf(invoice_id)  # the bytes
+invoices.pdf(invoice_id, template="invoice", dest="out/")  # -> out/INV-00042.pdf
+invoices.pdf(invoice_id, language="en", dest="invoice-en.pdf")
+```
+
+`dest` takes a file path, a binary handle, or an **existing directory** — the
+file is then named after the record's reference as the server suggests it (the
+invoice number). That name is re-sanitised before it touches your disk: a
+header never chooses the directory.
+
+**A fresh render on every call.** Nothing is archived server-side — no issued
+document, no stored file — so polling this is a read, and two calls can differ
+if the record changed in between.
+
+**`template`** may be omitted when the entity has exactly one usable PDF
+template. With several, the server refuses to guess, and the exception tells
+you which exist:
+
+```python
+from updo import TemplateRequired
+
+try:
+    pdf = invoices.pdf(invoice_id)
+except TemplateRequired as exc:
+    pdf = invoices.pdf(invoice_id, template=exc.templates[0])
+```
+
+**`language`** (`"en"`, `"fr-CA"`) overrides the render language; omitted, the
+template's own language field (the customer's, typically) decides, then the
+workspace default. The SDK checks it before sending, because the server
+**ignores** a malformed value instead of refusing it — `language="fr_CA"`
+would quietly produce a PDF in the default language.
+
+> ⚠️ **The template reads more than the record.** An invoice prints its lines
+> and its customer, and each of those entities needs the same right as
+> `GET data/<slug>/`. When one is missing, the *whole* document is refused —
+> `PermissionDenied` with `exc.resources` naming what to grant
+> (`["data:invoice_line"]`). Rows a row-level policy hides are left out of the
+> document without an error.
+
+A record that does not exist and one this token may not read both answer
+`404 RECORD_NOT_FOUND`, by design. A `503 PDF_RENDER_FAILED` is retried like any
+503 on a GET — safe here, since the route writes nothing.
+
+---
+
 ## Payment links
 
 Turn an invoice into a payer-facing URL, server to server. The payer needs no
@@ -426,6 +502,116 @@ invoice, or one with a zero balance, raises `ValidationError`.
 
 ---
 
+## Record images
+
+The one surface here that publishes to the open internet. Upload and publish are
+a single call: a `201` means the image is attached *and* its URL is live.
+
+```python
+images = client.entity("product").images(product_id)
+
+image = images.upload(
+    "photos/moulin.png",
+    category="photo",
+    alt_text={"fr": "Le moulin en hiver", "en": "The mill in winter"},
+)
+print(image.public_url)  # paste straight into <img src="...">
+```
+
+```python
+for image in images.list():
+    print(image.position, image.category, image.public_url)
+
+images.delete(image.id)
+```
+
+`upload()` takes a path, raw `bytes`, or a handle opened in **binary** mode. The
+file is read into memory — the server caps uploads at 10 MiB — so that a
+throttled request can be replayed without uploading an empty body.
+
+### `category` is required, whatever the schema says
+
+The server's OpenAPI marks it optional. It is not: publication checks the
+category against the entity's `public_media` whitelist, and that whitelist is
+built by a normaliser that strips blank entries — so `""` can never be a member,
+and omitting the category is a guaranteed `409`, not a default. The SDK requires
+it so the refusal happens at the call site instead of a round trip later.
+
+> **The whitelist is not readable through the public API.** The schema endpoint
+> returns *fields*, and this declaration is a property of the entity. Today the
+> only ways to learn which categories publish are to open the entity in the
+> Workshop, or to try and catch `PublicationRefused`.
+
+### What the SDK refuses before sending
+
+Each of these also comes back from the server — but only after the whole file
+has gone up, and only as a bare code that names the lock rather than the fix:
+
+| Refused locally | Because |
+|---|---|
+| an SVG, PDF, BMP, TIFF, ICO, HEIC or ZIP | the server publishes only PNG, JPEG, GIF and WebP, and it *decodes* the bytes rather than trusting the file name |
+| over 10 MiB | the server's ceiling |
+| `position` outside 0–32767 | it lands in a `smallint` |
+| alt text over 125 characters, or over 24 languages | the domain's bounds |
+| a non-UUID record id | the server's 404 would not say which id was wrong |
+
+SVG is excluded deliberately, not by oversight: it is a document format that
+executes script when served inline, and a published blob is served with no
+origin of its own. Rasterise it first.
+
+### Publication refusals
+
+```python
+from updo import PublicationRefused
+
+try:
+    images.upload(photo, category="contract")
+except PublicationRefused as exc:
+    if exc.is_configuration:
+        alert_ops(exc.code)  # nothing the caller can resend will fix it
+    else:
+        convert_and_retry()
+```
+
+`PublicationRefused` subclasses `ConflictError`, so an existing `except
+ConflictError` keeps working. Its `.code` is one of five stable, machine-readable
+values the server documents for branching:
+
+| `exc.code` | What to do |
+|---|---|
+| `public_media_not_declared` | the entity publishes nothing at all; add a `public_media` declaration in the Workshop |
+| `public_media_category_not_publishable` | name the category in that whitelist |
+| `public_media_not_an_image` | send different bytes — the only refusal the caller can fix |
+| `public_media_unavailable` | the deployment has no public container; an operator matter |
+| `public_media_sandbox_refused` | a sandbox twin may not publish — its URLs would go dead on a real site |
+
+Every refusal is decided **before anything is stored**, so a `409` has written no
+blob and attached no row. Retrying after fixing the cause needs no cleanup.
+
+### Three warnings
+
+**Uploading is not idempotent.** Unlike a payment link, nothing de-duplicates
+here: two calls with the same file attach two images. Only the transport's 429
+replay is safe, because a throttle refuses before the server has done anything.
+
+**Publishing stores the bytes twice, and you are billed for both.** A published
+image is a *copy* into the public container; the private original stays where it
+was. The workspace's metered storage counts the total, so a bulk import of
+product photos costs twice what the files weigh. That is the platform's real
+cost, not a rounding artefact — worth knowing before looping `upload()` over a
+catalogue.
+
+**Un-publishing is not retroactive.** `delete()` stops new public reads, but a
+CDN or a browser that already fetched the blob may keep serving it. Treat a
+published image as published for good — which is exactly why the server refuses
+to publish anything but decoded raster images.
+
+`image.public_url` is **not** masked in `repr()`, unlike `PaymentLink.url`. It
+carries no authority beyond "show these bytes" and exists to be embedded
+publicly; hiding it would obstruct the only thing anyone does with it.
+
+---
+
 ## Webhooks
 
 ### Subscribing
@@ -498,7 +684,9 @@ from updo import (
     PermissionDenied,
     NotFoundError,
     ValidationError,
+    TemplateRequired,
     ConflictError,
+    PublicationRefused,
     PlanLimitExceeded,
     RateLimitError,
     ServerError,
@@ -522,10 +710,12 @@ The server speaks **two error dialects** (the platform envelope
 |---|---|---|
 | 401 | `AuthenticationError` | unknown or expired token, IP refused, call outside `/api/public/` |
 | 402 | `PlanLimitExceeded` | subscription quota reached |
-| 403 | `PermissionDenied` | ABAC refusal, token scope ceiling, module disabled |
+| 403 | `PermissionDenied` | ABAC refusal, token scope ceiling, module disabled; `exc.resources` / `exc.feature` on a PDF |
 | 404 | `NotFoundError` | entity or record does not exist |
 | 400 / 422 | `ValidationError` | business rule, invalid value, unknown parameter |
+| 400 | `TemplateRequired` | several PDF templates fit — `exc.templates` lists them |
 | 409 | `ConflictError` | protected deletion, separation-of-duties conflict |
+| 409 | `PublicationRefused` | a `public_media` declaration forbids publishing an image — a `ConflictError` subclass carrying a stable `.code` |
 | 429 | `RateLimitError` | throttling — `exc.retry_after` |
 | 5xx | `ServerError` | platform-side outage |
 
@@ -678,8 +868,9 @@ The token is never displayed again: every output passes it through a mask
 
 ## Covered surface
 
-All 18 public routes, in full — a contract test checks this against the OpenAPI
-document served by the platform.
+Every documented public route — a contract test checks this against the OpenAPI
+document served by the platform, and fails the build on any operation the SDK
+does not reach.
 
 | Route | SDK method |
 |---|---|
@@ -694,6 +885,11 @@ document served by the platform.
 | `GET · POST /webhooks/` | `client.webhooks.list()` `.create()` |
 | `GET · PUT · PATCH · DELETE /webhooks/{id}/` | `.get()` `.replace()` `.update()` `.delete()` |
 | `GET /webhooks/deliveries/[{id}/]` | `.deliveries()` `.delivery()` |
+| `POST · DELETE /payment-links/` | `client.payments.create_link()` `.revoke_links()` |
+| `GET · POST /data/{slug}/{id}/images/` | `.images(id).list()` `.upload()` |
+| `DELETE /data/{slug}/{id}/images/{image_id}/` | `.images(id).delete()` |
+| `GET /data/{slug}/{id}/pdf/` | `.pdf(id)` |
+| `GET /data/{slug}/documents/` | `.documents()` |
 | `GET /schema/` | `client.openapi()` |
 
 For any route that is not modelled, the escape hatch keeps authentication and

{updo_sdk-0.2.0 → updo_sdk-0.4.0}/README.md

@@ -234,6 +234,13 @@ products.list(where=F(status="active") & F(sale_price__gte=10))
 > list-valued field: `tags__contains="promo"` finds records whose
 > `multi_select` includes that choice.
 
+**Exact matches are case-sensitive.** The server compares the stored JSON value
+as-is, without normalising it. That matters most for codes the platform
+normalises *on write*: a `jurisdiction` field stores ISO codes in uppercase
+(`CA` for a country, `CA-QC` for a subdivision — never a bare `QC`, which would
+be ambiguous with California's `US-CA`), so `where={"work_jurisdiction":
+"ca-qc"}` returns zero rows and no error. Pass `"CA-QC"`.
+
 An `__in` list cannot carry a value containing a comma: the server splits on
 commas and strips each part, so `["Dupont, Jean", "Tremblay"]` would arrive as
 three wrong terms. The SDK refuses such a value rather than sending it wrong.
@@ -336,6 +343,18 @@ data = products.export("csv")  # without dest: the bytes
 
 The export honours filters, search and ordering, and ignores pagination.
 
+```python
+products.export("csv", dest="short.csv", export_fields=["sku", "name", "sale_price"])
+```
+
+`export_fields` picks the columns **and their order**. Omitted, every readable
+column comes out in the entity's own order — relation ids included, which is
+what keeps the file re-importable. An unknown slug and one this token may not
+read get the *same* 400, on purpose. Two values are refused locally because the
+server would turn them into a silent surprise: an **empty list**, which reaches
+it as "not given" and exports every column, and a slug containing a comma,
+which it would split into two.
+
 > **The server truncates an export at 10 000 rows** — no header, no marker, no
 > error: a 40 000-record entity yields a perfectly well-formed CSV holding the
 > first 10 000. The SDK therefore counts first and **raises** rather than hand
@@ -345,6 +364,63 @@ The export honours filters, search and ordering, and ignores pagination.
 
 ---
 
+## Record PDFs (invoices, quotes, labels…)
+
+Render any record with one of the PDF templates designed for its entity — an
+invoice first of all.
+
+```python
+invoices = client.entity("invoice")
+
+for template in invoices.documents():
+    print(template.slug, template.display("fr"))
+
+pdf = invoices.pdf(invoice_id)  # the bytes
+invoices.pdf(invoice_id, template="invoice", dest="out/")  # -> out/INV-00042.pdf
+invoices.pdf(invoice_id, language="en", dest="invoice-en.pdf")
+```
+
+`dest` takes a file path, a binary handle, or an **existing directory** — the
+file is then named after the record's reference as the server suggests it (the
+invoice number). That name is re-sanitised before it touches your disk: a
+header never chooses the directory.
+
+**A fresh render on every call.** Nothing is archived server-side — no issued
+document, no stored file — so polling this is a read, and two calls can differ
+if the record changed in between.
+
+**`template`** may be omitted when the entity has exactly one usable PDF
+template. With several, the server refuses to guess, and the exception tells
+you which exist:
+
+```python
+from updo import TemplateRequired
+
+try:
+    pdf = invoices.pdf(invoice_id)
+except TemplateRequired as exc:
+    pdf = invoices.pdf(invoice_id, template=exc.templates[0])
+```
+
+**`language`** (`"en"`, `"fr-CA"`) overrides the render language; omitted, the
+template's own language field (the customer's, typically) decides, then the
+workspace default. The SDK checks it before sending, because the server
+**ignores** a malformed value instead of refusing it — `language="fr_CA"`
+would quietly produce a PDF in the default language.
+
+> ⚠️ **The template reads more than the record.** An invoice prints its lines
+> and its customer, and each of those entities needs the same right as
+> `GET data/<slug>/`. When one is missing, the *whole* document is refused —
+> `PermissionDenied` with `exc.resources` naming what to grant
+> (`["data:invoice_line"]`). Rows a row-level policy hides are left out of the
+> document without an error.
+
+A record that does not exist and one this token may not read both answer
+`404 RECORD_NOT_FOUND`, by design. A `503 PDF_RENDER_FAILED` is retried like any
+503 on a GET — safe here, since the route writes nothing.
+
+---
+
 ## Payment links
 
 Turn an invoice into a payer-facing URL, server to server. The payer needs no
@@ -390,6 +466,116 @@ invoice, or one with a zero balance, raises `ValidationError`.
 
 ---
 
+## Record images
+
+The one surface here that publishes to the open internet. Upload and publish are
+a single call: a `201` means the image is attached *and* its URL is live.
+
+```python
+images = client.entity("product").images(product_id)
+
+image = images.upload(
+    "photos/moulin.png",
+    category="photo",
+    alt_text={"fr": "Le moulin en hiver", "en": "The mill in winter"},
+)
+print(image.public_url)  # paste straight into <img src="...">
+```
+
+```python
+for image in images.list():
+    print(image.position, image.category, image.public_url)
+
+images.delete(image.id)
+```
+
+`upload()` takes a path, raw `bytes`, or a handle opened in **binary** mode. The
+file is read into memory — the server caps uploads at 10 MiB — so that a
+throttled request can be replayed without uploading an empty body.
+
+### `category` is required, whatever the schema says
+
+The server's OpenAPI marks it optional. It is not: publication checks the
+category against the entity's `public_media` whitelist, and that whitelist is
+built by a normaliser that strips blank entries — so `""` can never be a member,
+and omitting the category is a guaranteed `409`, not a default. The SDK requires
+it so the refusal happens at the call site instead of a round trip later.
+
+> **The whitelist is not readable through the public API.** The schema endpoint
+> returns *fields*, and this declaration is a property of the entity. Today the
+> only ways to learn which categories publish are to open the entity in the
+> Workshop, or to try and catch `PublicationRefused`.
+
+### What the SDK refuses before sending
+
+Each of these also comes back from the server — but only after the whole file
+has gone up, and only as a bare code that names the lock rather than the fix:
+
+| Refused locally | Because |
+|---|---|
+| an SVG, PDF, BMP, TIFF, ICO, HEIC or ZIP | the server publishes only PNG, JPEG, GIF and WebP, and it *decodes* the bytes rather than trusting the file name |
+| over 10 MiB | the server's ceiling |
+| `position` outside 0–32767 | it lands in a `smallint` |
+| alt text over 125 characters, or over 24 languages | the domain's bounds |
+| a non-UUID record id | the server's 404 would not say which id was wrong |
+
+SVG is excluded deliberately, not by oversight: it is a document format that
+executes script when served inline, and a published blob is served with no
+origin of its own. Rasterise it first.
+
+### Publication refusals
+
+```python
+from updo import PublicationRefused
+
+try:
+    images.upload(photo, category="contract")
+except PublicationRefused as exc:
+    if exc.is_configuration:
+        alert_ops(exc.code)  # nothing the caller can resend will fix it
+    else:
+        convert_and_retry()
+```
+
+`PublicationRefused` subclasses `ConflictError`, so an existing `except
+ConflictError` keeps working. Its `.code` is one of five stable, machine-readable
+values the server documents for branching:
+
+| `exc.code` | What to do |
+|---|---|
+| `public_media_not_declared` | the entity publishes nothing at all; add a `public_media` declaration in the Workshop |
+| `public_media_category_not_publishable` | name the category in that whitelist |
+| `public_media_not_an_image` | send different bytes — the only refusal the caller can fix |
+| `public_media_unavailable` | the deployment has no public container; an operator matter |
+| `public_media_sandbox_refused` | a sandbox twin may not publish — its URLs would go dead on a real site |
+
+Every refusal is decided **before anything is stored**, so a `409` has written no
+blob and attached no row. Retrying after fixing the cause needs no cleanup.
+
+### Three warnings
+
+**Uploading is not idempotent.** Unlike a payment link, nothing de-duplicates
+here: two calls with the same file attach two images. Only the transport's 429
+replay is safe, because a throttle refuses before the server has done anything.
+
+**Publishing stores the bytes twice, and you are billed for both.** A published
+image is a *copy* into the public container; the private original stays where it
+was. The workspace's metered storage counts the total, so a bulk import of
+product photos costs twice what the files weigh. That is the platform's real
+cost, not a rounding artefact — worth knowing before looping `upload()` over a
+catalogue.
+
+**Un-publishing is not retroactive.** `delete()` stops new public reads, but a
+CDN or a browser that already fetched the blob may keep serving it. Treat a
+published image as published for good — which is exactly why the server refuses
+to publish anything but decoded raster images.
+
+`image.public_url` is **not** masked in `repr()`, unlike `PaymentLink.url`. It
+carries no authority beyond "show these bytes" and exists to be embedded
+publicly; hiding it would obstruct the only thing anyone does with it.
+
+---
+
 ## Webhooks
 
 ### Subscribing
@@ -462,7 +648,9 @@ from updo import (
     PermissionDenied,
     NotFoundError,
     ValidationError,
+    TemplateRequired,
     ConflictError,
+    PublicationRefused,
     PlanLimitExceeded,
     RateLimitError,
     ServerError,
@@ -486,10 +674,12 @@ The server speaks **two error dialects** (the platform envelope
 |---|---|---|
 | 401 | `AuthenticationError` | unknown or expired token, IP refused, call outside `/api/public/` |
 | 402 | `PlanLimitExceeded` | subscription quota reached |
-| 403 | `PermissionDenied` | ABAC refusal, token scope ceiling, module disabled |
+| 403 | `PermissionDenied` | ABAC refusal, token scope ceiling, module disabled; `exc.resources` / `exc.feature` on a PDF |
 | 404 | `NotFoundError` | entity or record does not exist |
 | 400 / 422 | `ValidationError` | business rule, invalid value, unknown parameter |
+| 400 | `TemplateRequired` | several PDF templates fit — `exc.templates` lists them |
 | 409 | `ConflictError` | protected deletion, separation-of-duties conflict |
+| 409 | `PublicationRefused` | a `public_media` declaration forbids publishing an image — a `ConflictError` subclass carrying a stable `.code` |
 | 429 | `RateLimitError` | throttling — `exc.retry_after` |
 | 5xx | `ServerError` | platform-side outage |
 
@@ -642,8 +832,9 @@ The token is never displayed again: every output passes it through a mask
 
 ## Covered surface
 
-All 18 public routes, in full — a contract test checks this against the OpenAPI
-document served by the platform.
+Every documented public route — a contract test checks this against the OpenAPI
+document served by the platform, and fails the build on any operation the SDK
+does not reach.
 
 | Route | SDK method |
 |---|---|
@@ -658,6 +849,11 @@ document served by the platform.
 | `GET · POST /webhooks/` | `client.webhooks.list()` `.create()` |
 | `GET · PUT · PATCH · DELETE /webhooks/{id}/` | `.get()` `.replace()` `.update()` `.delete()` |
 | `GET /webhooks/deliveries/[{id}/]` | `.deliveries()` `.delivery()` |
+| `POST · DELETE /payment-links/` | `client.payments.create_link()` `.revoke_links()` |
+| `GET · POST /data/{slug}/{id}/images/` | `.images(id).list()` `.upload()` |
+| `DELETE /data/{slug}/{id}/images/{image_id}/` | `.images(id).delete()` |
+| `GET /data/{slug}/{id}/pdf/` | `.pdf(id)` |
+| `GET /data/{slug}/documents/` | `.documents()` |
 | `GET /schema/` | `client.openapi()` |
 
 For any route that is not modelled, the escape hatch keeps authentication and