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

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

@@ -4,6 +4,61 @@ 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

{updo_sdk-0.3.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.3.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
@@ -512,12 +588,19 @@ values the server documents for branching:
 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.
 
-### Two warnings
+### 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
@@ -601,6 +684,7 @@ from updo import (
     PermissionDenied,
     NotFoundError,
     ValidationError,
+    TemplateRequired,
     ConflictError,
     PublicationRefused,
     PlanLimitExceeded,
@@ -626,9 +710,10 @@ 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` |
@@ -803,6 +888,8 @@ does not reach.
 | `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.3.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
@@ -476,12 +552,19 @@ values the server documents for branching:
 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.
 
-### Two warnings
+### 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
@@ -565,6 +648,7 @@ from updo import (
     PermissionDenied,
     NotFoundError,
     ValidationError,
+    TemplateRequired,
     ConflictError,
     PublicationRefused,
     PlanLimitExceeded,
@@ -590,9 +674,10 @@ 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` |
@@ -767,6 +852,8 @@ does not reach.
 | `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.3.0 → updo_sdk-0.4.0}/src/updo/__init__.py

@@ -26,6 +26,7 @@ from .errors import (
     PublicationRefused,
     RateLimitError,
     ServerError,
+    TemplateRequired,
     UpdoAPIError,
     UpdoConfigError,
     UpdoConnectionError,
@@ -37,6 +38,7 @@ from .errors import (
 from .models import (
     AggregateResult,
     ApprovalPending,
+    DocumentTemplate,
     EntitySchema,
     EntitySummary,
     FieldSpec,
@@ -64,6 +66,7 @@ __all__ = [
     "AuthenticationError",
     "ClientConfig",
     "ConflictError",
+    "DocumentTemplate",
     "EntitySchema",
     "EntitySummary",
     "F",
@@ -80,6 +83,7 @@ __all__ = [
     "Record",
     "RecordImage",
     "ServerError",
+    "TemplateRequired",
     "TokenIdentity",
     "UpdoAPIError",
     "UpdoClient",

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/_transport.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import json
 import random
+import re
 from collections.abc import Iterable, Mapping
 from typing import Any
 
@@ -30,6 +31,7 @@ __all__ = [
     "IDEMPOTENT_METHODS",
     "RETRY_STATUSES",
     "UpdoJSONEncoder",
+    "attachment_filename",
     "build_headers",
     "encode_json_body",
     "join_path",
@@ -186,6 +188,29 @@ def retry_delay(attempt: int, response: httpx.Response | None = None) -> float:
     return random.uniform(0.0, window)  # noqa: S311 - jitter, not cryptography
 
 
+_FILENAME_PARAM = re.compile(r'filename\s*=\s*"?([^";]+)"?', re.IGNORECASE)
+_UNSAFE_NAME_CHARS = re.compile(r"[^A-Za-z0-9._-]+")
+
+
+def attachment_filename(response: httpx.Response) -> str | None:
+    """The file name a ``Content-Disposition: attachment`` response suggests.
+
+    Re-sanitised here even though the server already sanitises it: this name
+    becomes a path on the CALLER's disk, and a client that trusts a header to
+    choose where it writes is one bad proxy away from ``../../.bashrc``. Only
+    the last path component survives, reduced to ``[A-Za-z0-9._-]``; a name
+    that sanitises to nothing, or to a dot-name, yields ``None``.
+    """
+    match = _FILENAME_PARAM.search(response.headers.get("Content-Disposition", ""))
+    if not match:
+        return None
+    base = match.group(1).strip().replace("\\", "/").rsplit("/", 1)[-1]
+    name = _UNSAFE_NAME_CHARS.sub("-", base).strip("-")
+    if not name or name.strip(".") == "":
+        return None
+    return name.lstrip(".") or None
+
+
 def wrap_transport_error(exc: Exception) -> UpdoTransportError:
     """Translate an httpx transport failure into this SDK's vocabulary."""
     if isinstance(exc, httpx.TimeoutException):

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version (read by ``pyproject.toml``)."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/aio.py

@@ -18,6 +18,7 @@ from typing import Any
 import httpx
 
 from ._transport import (
+    attachment_filename,
     build_headers,
     encode_json_body,
     join_path,
@@ -273,7 +274,9 @@ class AsyncUpdoClient:
                     if response.status_code >= 400:
                         await response.aread()
                         raise error_from_response(response)
-                    return await _consume(response.aiter_bytes(), dest)
+                    return await _consume(
+                        response.aiter_bytes(), dest, attachment_filename(response)
+                    )
             except httpx.HTTPError as exc:
                 if should_retry_exception("GET", exc, attempt, self.config.max_retries):
                     await asyncio.sleep(retry_delay(attempt))
@@ -303,7 +306,15 @@ class AsyncUpdoClient:
         return True
 
 
-async def _consume(chunks: Any, dest: Any) -> Any:
+async def _consume(chunks: Any, dest: Any, suggested: str | None = None) -> Any:
+    """Write a streamed body to ``dest``, or collect it into bytes.
+
+    ``dest`` may also be an EXISTING DIRECTORY: the file then takes the name the
+    server suggested (an invoice number, say), already re-sanitised by
+    :func:`attachment_filename`. Without a usable suggestion it is refused
+    rather than invented -- a made-up name would overwrite the previous one on
+    the next call.
+    """
     if dest is None:
         buffer = bytearray()
         async for chunk in chunks:
@@ -314,6 +325,13 @@ async def _consume(chunks: Any, dest: Any) -> Any:
             dest.write(chunk)
         return dest
     target = Path(dest)
+    if target.is_dir():
+        if not suggested:
+            raise ValueError(
+                f"{target} is a directory and the server suggested no file name; "
+                "pass a full file path instead."
+            )
+        target = target / suggested
     target.parent.mkdir(parents=True, exist_ok=True)
     with target.open("wb") as handle:
         async for chunk in chunks:

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/client.py

@@ -13,6 +13,7 @@ from typing import Any
 import httpx
 
 from ._transport import (
+    attachment_filename,
     build_headers,
     encode_json_body,
     join_path,
@@ -278,7 +279,7 @@ class UpdoClient:
                     if response.status_code >= 400:
                         response.read()
                         raise error_from_response(response)
-                    return _consume(response.iter_bytes(), dest)
+                    return _consume(response.iter_bytes(), dest, attachment_filename(response))
             except httpx.HTTPError as exc:
                 if should_retry_exception("GET", exc, attempt, self.config.max_retries):
                     time.sleep(retry_delay(attempt))
@@ -311,8 +312,15 @@ class UpdoClient:
         return True
 
 
-def _consume(chunks: Any, dest: Any) -> Any:
-    """Write a streamed body to ``dest``, or collect it into bytes."""
+def _consume(chunks: Any, dest: Any, suggested: str | None = None) -> Any:
+    """Write a streamed body to ``dest``, or collect it into bytes.
+
+    ``dest`` may also be an EXISTING DIRECTORY: the file then takes the name the
+    server suggested (an invoice number, say), already re-sanitised by
+    :func:`attachment_filename`. Without a usable suggestion it is refused
+    rather than invented -- a made-up name would overwrite the previous one on
+    the next call.
+    """
     if dest is None:
         return b"".join(chunks)
     if hasattr(dest, "write"):
@@ -320,6 +328,13 @@ def _consume(chunks: Any, dest: Any) -> Any:
             dest.write(chunk)
         return dest
     target = Path(dest)
+    if target.is_dir():
+        if not suggested:
+            raise ValueError(
+                f"{target} is a directory and the server suggested no file name; "
+                "pass a full file path instead."
+            )
+        target = target / suggested
     target.parent.mkdir(parents=True, exist_ok=True)
     with target.open("wb") as handle:
         for chunk in chunks:

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/codegen.py

@@ -48,6 +48,9 @@ TYPE_MAP: dict[str, str] = {
     "email": "str",
     "url": "str",
     "country": "str",
+    # An ISO code, stored UPPERCASE: "CA" (a country) or "CA-QC" (one of its
+    # subdivisions). Filters compare it exactly, so "ca-qc" matches nothing.
+    "jurisdiction": "str",
     "file": "str",
     "password": "str",
     "autonumber": "str",

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/errors.py

@@ -32,6 +32,7 @@ __all__ = [
     "PublicationRefused",
     "RateLimitError",
     "ServerError",
+    "TemplateRequired",
     "UpdoAPIError",
     "UpdoConfigError",
     "UpdoConnectionError",
@@ -141,6 +142,24 @@ class PermissionDenied(UpdoAPIError):
         value = self.extra.get("module_code")
         return None if value is None else str(value)
 
+    @property
+    def resources(self) -> list[str]:
+        """The ``data:<slug>`` resources a document READS and this token may not.
+
+        Set by the PDF route when the refusal comes from the document's CONTENT
+        rather than its own entity: an invoice template also prints the
+        invoice lines and the customer, and each of those needs the same right
+        as ``GET data/<slug>/``. This list is what to grant.
+        """
+        value = self.extra.get("resources")
+        return [str(item) for item in value] if isinstance(value, list) else []
+
+    @property
+    def feature(self) -> str | None:
+        """``FEATURE_NOT_LICENSED`` only: the capability the workspace lacks."""
+        value = self.extra.get("feature")
+        return None if value is None else str(value)
+
 
 class NotFoundError(UpdoAPIError):
     """404 -- unknown entity/record, or a cross-tenant reference shown as not-found."""
@@ -160,6 +179,23 @@ class ValidationError(UpdoAPIError):
     """400 / 422 -- business rule, invalid value object, tenant script, bad parameter."""
 
 
+class TemplateRequired(ValidationError):
+    """400 ``TEMPLATE_REQUIRED`` -- the entity has several PDF templates.
+
+    The server refuses to guess which document you meant, and says which ones
+    exist: :attr:`templates` lists the slugs ``pdf(template=...)`` accepts. A
+    caller can therefore recover without a second request::
+
+        except TemplateRequired as exc:
+            pdf = invoices.pdf(record_id, template=exc.templates[0])
+    """
+
+    @property
+    def templates(self) -> list[str]:
+        value = self.extra.get("templates")
+        return [str(item) for item in value] if isinstance(value, list) else []
+
+
 class ConflictError(UpdoAPIError):
     """409 -- protected relation on delete, or a separation-of-duties refusal."""
 
@@ -356,6 +392,17 @@ def error_from_response(response: httpx.Response) -> UpdoAPIError:
     # send. Promoting it here rather than in the images resource keeps one
     # translation of the wire format, and PublicationRefused subclasses
     # ConflictError, so an existing `except ConflictError` still catches it.
+    if code == "TEMPLATE_REQUIRED":
+        return TemplateRequired(
+            detail,
+            status_code=status,
+            code=code,
+            field_errors=field_errors,
+            extra=extra,
+            body=body,
+            response=response,
+        )
+
     if status == 409 and detail in PublicationRefused.REASONS:
         return PublicationRefused(
             f"cannot publish: {PublicationRefused.REASONS[detail]}.",

{updo_sdk-0.3.0 → updo_sdk-0.4.0}/src/updo/models.py

@@ -20,6 +20,7 @@ from typing import Any, Generic, TypeVar
 
 __all__ = [
     "AggregateResult",
+    "DocumentTemplate",
     "PaymentLink",
     "ApprovalPending",
     "EntitySchema",
@@ -712,6 +713,39 @@ class RecordImage:
         )
 
 
+@dataclass(frozen=True)
+class DocumentTemplate:
+    """A PDF template an entity's records can be rendered with.
+
+    ``slug`` is what :meth:`~updo.resources.records.RecordsResource.pdf` takes
+    as ``template``. The list is already narrowed server-side to what this
+    token may render here: templates of this entity, visible on the current
+    site, and not behind a capability the workspace has not bought -- those are
+    ABSENT, not padlocked.
+    """
+
+    slug: str
+    label: dict[str, str] = field(default_factory=dict)
+    kind: str = "pdf"
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def display(self, lang: str = "fr") -> str:
+        return localize(self.label, lang, self.slug)
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> DocumentTemplate:
+        raw_label = payload.get("label")
+        label = (
+            {str(k): str(v) for k, v in raw_label.items()} if isinstance(raw_label, Mapping) else {}
+        )
+        return cls(
+            slug=str(payload.get("slug") or ""),
+            label=label,
+            kind=str(payload.get("kind") or "pdf"),
+            raw=dict(payload),
+        )
+
+
 @dataclass(frozen=True)
 class Webhook:
     """A webhook subscription (``action_type`` is always ``webhook`` here)."""