vintasend-templates-management-api 3.5.0__tar.gz

vintasend_templates_management_api-3.5.0/PKG-INFO

@@ -0,0 +1,778 @@
+Metadata-Version: 2.4
+Name: vintasend-templates-management-api
+Version: 3.5.0
+Summary: REST API that exposes a VintaSend ManagedTemplateService over HTTP for template-management UIs
+License-Expression: MIT
+Keywords: vintasend,notifications,templates,django,django-ninja,rest-api
+Author: Vinta Software
+Author-email: contact@vinta.com.br
+Requires-Python: >=3.10,<3.15
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Topic :: Communications :: Email
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Dist: django (>=4.2,<6.0)
+Requires-Dist: django-ninja (>=1.4.3,<2.0.0)
+Requires-Dist: python-dotenv (>=1.1.1,<2.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
+Requires-Dist: vintasend (==3.5.0)
+Requires-Dist: vintasend-managed-templates (==3.5.0)
+Project-URL: Changelog, https://github.com/vintasoftware/vintasend/blob/main/RELEASE_NOTES.md
+Project-URL: Homepage, https://github.com/vintasoftware/vintasend-templates-management-api
+Project-URL: Issues, https://github.com/vintasoftware/vintasend-templates-management-api/issues
+Project-URL: Repository, https://github.com/vintasoftware/vintasend-templates-management-api
+Description-Content-Type: text/markdown
+
+# VintaSend Templates API
+
+REST API that exposes a
+[`ManagedTemplateService`](https://github.com/vintasoftware/vintasend-managed-templates)
+over HTTP, built with Django and [django-ninja](https://django-ninja.dev/).
+
+It exists so a template-management UI does not have to embed a template store: the UI
+becomes a pure API client, and any implementation of this contract can serve it. It is
+the templates-side sibling of
+[`vintasend-api`](https://github.com/vintasoftware/vintasend-api), which does the same
+for notifications, and follows the same conventions — bearer-token auth, a `{ data }` /
+`{ error }` envelope, 1-indexed pages, camelCase on the wire.
+
+**[`openapi.yaml`](./openapi.yaml) is generated, not maintained.** It is produced from
+the route declarations in
+[`api.py`](./vintasend_templates_management_api/templates_manager/api.py) and the schemas in
+[`contract.py`](./vintasend_templates_management_api/templates_manager/contract.py) and
+[`query.py`](./vintasend_templates_management_api/templates_manager/query.py) by
+`manage.py export_openapi`. A test asserts the committed copy matches the live routes, so
+a change that was not regenerated fails the suite rather than shipping a stale contract.
+
+```
+┌─────────────────────┐   HTTPS + API key    ┌───────────────────────┐
+│  Template mgmt UI   │ ───────────────────▶ │ vintasend-templates-  │
+│  server-side only   │ ◀─────────────────── │ api (this project)    │
+└─────────────────────┘     JSON contract    └───────────┬───────────┘
+                                                         │
+                                          ┌──────────────┴──────────────┐
+                                          │  Your ManagedTemplateService│
+                                          │  template manager backend + │
+                                          │  managed template renderer  │
+                                          └─────────────────────────────┘
+```
+
+The API owns everything that needs backend credentials — database access, template
+rendering. The UI owns presentation and user authentication.
+
+## Why Django, for a library with no web framework
+
+The same reason as `vintasend-api`: the template store decides. The reference backend,
+`vintasend-django-templates-manager`, persists templates through the Django ORM, and
+reading them needs a Django app registry and connection handling — another framework's
+process would have to boot a half-configured Django anyway.
+
+Nothing is lost for non-Django deployments. `BaseTemplateManagerBackend` is a pluggable
+seam, so a FastAPI application storing templates through SQLAlchemy is served by this
+same API: point `MANAGED_TEMPLATE_SERVICE_FACTORY` at a factory that builds a
+SQLAlchemy-backed service and the HTTP layer neither knows nor cares.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/health` | Liveness probe (unauthenticated) |
+| GET | `/api/v1/capabilities` | Filter capabilities of the configured backend |
+| GET | `/api/v1/templates` | List template versions with filters and pagination |
+| POST | `/api/v1/templates` | Create a template's first version |
+| GET | `/api/v1/templates/{key}` | One version — the latest unless `?version=` is given |
+| DELETE | `/api/v1/templates/{key}` | Delete one never-published version (the latest unless `?version=`); a published one is a 409 `CONFLICT` |
+| GET | `/api/v1/templates/{key}/versions` | Every version, newest first |
+| POST | `/api/v1/templates/{key}/versions` | Create a new version from the latest |
+| GET | `/api/v1/templates/{key}/versions/{version}` | One pinned version |
+| DELETE | `/api/v1/templates/{key}/versions/{version}` | Delete one pinned, never-published version; a published one is a 409 `CONFLICT` |
+| GET | `/api/v1/templates/{key}/composition` | One version assembled — what the engine actually receives |
+| GET | `/api/v1/templates/{key}/status-history` | Status audit trail, most recent first |
+| POST | `/api/v1/templates/{key}/status` | Move a version to an explicitly named status |
+| POST | `/api/v1/templates/{key}/activate` | Publish a version |
+| POST | `/api/v1/templates/{key}/deactivate` | Retire a version without archiving it |
+| POST | `/api/v1/templates/{key}/archive` | Archive a version (terminal by default) |
+| POST | `/api/v1/templates/{key}/preview` | Render a version against a supplied context |
+| PUT | `/api/v1/templates/{key}/tags` | Replace one version's tags, in place |
+| GET | `/api/v1/tags` | List tags with filters and pagination |
+| POST | `/api/v1/tags` | Create a tag ahead of any template using it |
+| GET | `/api/v1/tags/{slug}` | One tag |
+| PATCH | `/api/v1/tags/{slug}` | Rename a tag (its slug is regenerated) |
+| DELETE | `/api/v1/tags/{slug}` | Delete a tag, stripping it from every template |
+| POST | `/api/v1/tags/{slug}/archive` | Retire a tag from the pickers |
+| POST | `/api/v1/tags/{slug}/restore` | Put an archived tag back on offer |
+
+A browsable version of the generated schema is served at `/api/v1/docs`.
+
+Conventions a client can rely on:
+
+- `page` is **1-indexed**.
+- `hasMore` is `true` when the next page has at least one row, so a list that exactly fills
+  its last page never offers an empty one. The template-manager seam has no count method,
+  so no total is available: after a full page the API reads the one row that would follow
+  it.
+- **Request bodies are JSON.** A request that declares `application/json` (or any
+  `application/*+json`) must carry valid JSON, so an empty body there is a 400. A request
+  that declares no media type, or another one, counts as an omitted body when its body is
+  empty, which is how an all-optional body (`activate`, `deactivate`, `archive`, `preview`,
+  `POST /templates/{key}/versions`) is left out. Anything else is a 400 rather than a guess.
+  `curl -d` sends form encoding unless told otherwise, so pass
+  `-H 'Content-Type: application/json'`.
+- **`GET /templates` lists one row per key by default.** A row in the store is a *version*,
+  so the raw read returns a key once per version it has ever had. `mostRecentActiveVersion`
+  defaults to `true` and narrows that to each key's current version — the highest-numbered
+  `active` or `draft` one. Send `mostRecentActiveVersion=false` to list every version.
+- **`version` omitted means "the latest"** everywhere except `status-history`, where it
+  means "every version" — that endpoint forwards it to the backend, which returns the
+  whole key's trail.
+- **`GET /templates` orders only when asked, and only by what the backend can sort.**
+  `orderByField` takes `key`, `name`, `version`, `status`, `createdAt` or `updatedAt`;
+  `orderByDirection` takes `asc` or `desc` and defaults to `asc`. Neither has a default
+  field, so omitting them asks for the backend's own order. See
+  [Ordering](#ordering-the-listing).
+- Every template payload carries `isAbstract`: whether that version is a base to build on rather than one to send. See [Composition](#composition-templates-built-on-templates).
+- Every template payload carries `allowedTransitions`: the statuses that version can move
+  to right now, as the *configured service* answers it. A UI enables buttons from that
+  rather than reimplementing the lifecycle or discovering it by catching a 409.
+- **A send renders the newest `active` version, never a draft.** Reads here are the editing
+  view: `version` omitted returns the newest version whatever its status, and a preview with no
+  `version` renders that. When several versions are active, an unpinned send renders the
+  highest-numbered one, so activating an older version does not change what is sent.
+- **Only a never-published version can be deleted.** A version that was ever activated is
+  refused with a 409 `CONFLICT`: a notification may be pinned to it, and its status history
+  records who published it. Archive it instead. That applies to `DELETE /templates/{key}` with no
+  `version` too, which resolves to the latest version, so prefer naming the version you mean.
+  Status history is never deleted.
+- **`changedBy` in a status body is only a fallback.** A host that knows who is calling sets
+  `MANAGED_TEMPLATE_ACTOR_RESOLVER` (see [Attribution](#attribution)), and its answer replaces
+  whatever the body says.
+- **`templateManagedBackend` in a create body can be overridden by the host.** A host serving one
+  backend sets `MANAGED_TEMPLATE_BACKEND_NAME` (see [Backend name](#backend-name)), and every new
+  template is stored under it, whatever the body says.
+- Timestamps are ISO-8601 UTC strings, `null` when unset — never absent.
+- Errors always use the envelope `{ "error": { "code", "message", "details"? } }`.
+
+### Tags
+
+Tags label template versions so they can be found. A template carries any number of tags
+and a tag is carried by any number of templates.
+
+- **The slug is the identity.** It is normalized from the text — lowercased, accents
+  folded, everything else collapsed to `-` — and is unique store-wide, so `Black Friday`,
+  `black friday` and `BLACK-FRIDAY` are one tag. Store the `slug`, not the `text`.
+- **Anywhere a tag is named, its text works too.** `GET /tags/Black%20Friday` and
+  `GET /tags/black-friday` are the same lookup, and the same holds for the filters.
+- **Tags are created on the fly.** Send `tags` on `POST /templates` or
+  `POST /templates/{key}/versions` and any tag that does not exist yet is created. Use
+  `POST /tags` only when a collision should be reported rather than resolved — it is a
+  409 there and silent everywhere else.
+- **Renaming changes the slug.** `PATCH /tags/{slug}` regenerates it, so a stored filter
+  naming the old slug stops matching. Read the new `slug` off the response. Renaming onto
+  another tag's text is allowed and yields `-2`: two tags may read the same, and the slug
+  is what tells them apart.
+- **Archive hides the tag; delete removes the label.** An archived tag drops out of
+  `GET /tags?status=active` but stays on the templates carrying it, and filtering by it
+  still finds them. Deleting is what strips the label, and it is not reversible.
+- **Searching by tag** uses `includesAllTags` (carries *every* tag listed) or
+  `includesAnyOfTags` (carries *at least one*). Repeat the parameter per tag. Sending both
+  combines them with AND, like every other filter pair. A template matching several of the
+  tags listed is returned once, not once per match.
+
+  ```
+  GET /api/v1/templates?includesAllTags=billing&includesAllTags=urgent
+  GET /api/v1/templates?includesAnyOfTags=billing&includesAnyOfTags=marketing
+  ```
+- **Tags belong to a version, not a key**, so two versions of one template can be labelled
+  differently — a draft can be tagged for review without relabelling what is live.
+
+### Versions in the listing
+
+The store holds a row per version, and a template-management UI almost always wants a list of
+*templates*. `GET /api/v1/templates` therefore defaults to `mostRecentActiveVersion=true`:
+
+```
+GET /api/v1/templates                                # one row per key — the current version
+GET /api/v1/templates?mostRecentActiveVersion=false  # every version of every key
+GET /api/v1/templates/{key}/versions                 # every version of one key, newest first
+```
+
+Current means the **highest-numbered `active` or `draft` version**: what is published, plus the
+draft on its way to replacing it. A key whose versions are all `inactive` or `archived` has no
+current version and does not appear in the default listing — ask for
+`mostRecentActiveVersion=false` to see it.
+
+A `status` filter applies on top of the default, so `?status=archived` on its own finds
+nothing: the one row kept per key is never `inactive` or `archived`. Send both:
+
+```
+GET /api/v1/templates?status=archived&mostRecentActiveVersion=false
+```
+
+`false` lifts the restriction rather than inverting it: it lists everything, not only the rows
+the default hides. The complement is a legitimate query in the library's filter vocabulary
+(`{"most_recent_active_version": False}`) but there is no wire parameter for it, because no UI
+has asked to list *only* superseded versions.
+
+The narrowing happens in the store, so pagination still counts what the backend counted. A
+backend declining `fields.mostRecentActiveVersion` has the filter dropped like any other
+unsupported one, and its listing shows every version.
+
+### Ordering the listing
+
+```
+GET /api/v1/templates?orderByField=name&orderByDirection=asc
+```
+
+`orderByField` accepts `key`, `name`, `version`, `status`, `createdAt` and `updatedAt` —
+each a scalar the backend already stores per row, so a store can answer it from an index.
+Tags are absent because ordering by a many-to-many has no single value to compare, and
+`mostRecentActiveVersion` because it is a filter rather than a field.
+
+`orderByDirection` is `asc` or `desc`, and defaults to `asc` when a field is given without
+one. Sent on its own it is a `400`: there is nothing to order by, and ignoring it would
+look exactly like a backend that cannot sort.
+
+**Ask `/capabilities` first.** Every `orderBy.*` key defaults to `false`, so a backend that
+has not declared a field cannot sort by it and the request is a `400` naming the key:
+
+```jsonc
+// GET /api/v1/capabilities
+{
+  "data": {
+    "orderBy.key": true,
+    "orderBy.name": true,
+    "orderBy.version": true,
+    "orderBy.status": false,   // this backend cannot sort by status
+    "orderBy.createdAt": true,
+    "orderBy.updatedAt": true
+    // ... plus the fields.*, logical.* and stringLookups.* keys
+  }
+}
+```
+
+Build the sortable columns of a UI from that report and the `400` never happens. Unlike an
+unsupported *filter*, which is dropped so the request still succeeds, an unsupported
+*order* is refused — see [Design notes](#design-notes) for why the two differ.
+
+The order is applied by the backend to the whole result set before a page is chosen, so
+page 2 of an ordered listing is the second page of that order rather than the backend's
+own second page re-sorted.
+
+### Composition: templates built on templates
+
+A managed template can build on another one, and all of it is resolved **before** any
+template engine runs — so the stored `bodyTemplate` is only half of what renders:
+
+```
+base-email    <html><body>
+                {% managed_block header %}<h1>Acme</h1>{% managed_endblock %}
+                {% managed_children %}
+                {% managed_include "footer" %}
+              </body></html>
+
+welcome       {% managed_extends "base-email" %}
+              {% managed_block header %}<h1>Welcome!</h1>{% managed_endblock %}
+              <p>Hi {{ name }}, welcome aboard.</p>
+```
+
+The tag language belongs to
+[`vintasend-managed-templates`](https://github.com/vintasoftware/vintasend-managed-templates#composition-bases-blocks-and-includes)
+— `managed_extends`, `managed_children`, `managed_block` / `managed_endblock`,
+`managed_super`, `managed_include`, with `version=2` to pin a reference. This API stores those templates as written and exposes what they assemble to.
+
+**`GET /api/v1/templates/{key}/composition`** returns the assembled sources, plus what the
+version directly references and whether it is abstract:
+
+```
+GET /api/v1/templates/welcome/composition          # the latest version
+GET /api/v1/templates/welcome/composition?version=3
+
+{ "data": {
+    "key": "welcome",
+    "version": 3,
+    "isAbstract": false,
+    "references": [
+      { "kind": "extends", "key": "base-email", "version": null, "field": "bodyTemplate" }
+    ],
+    "composedBodyTemplate": "<html><body><h1>Welcome!</h1>...",
+    "composedSubjectTemplate": null,
+    "composedPreheaderTemplate": null
+} }
+```
+
+Nothing there is rendered against a context: `{{ name }}` and every other engine tag
+survives untouched. `POST /templates/{key}/preview` is what renders — and it composes
+first, so a preview shows the base's chrome around the child's content, exactly as a real
+send would.
+
+A template that cannot be assembled — a base that does not exist, a chain that loops, a
+malformed tag — is a **409 `TEMPLATE_COMPOSITION_ERROR`** carrying the library's message,
+which names the reference chain that broke. It is a 409 and not a 404 because the template
+asked for is there; what it names is not.
+
+Previewing tells the two ways a template can be broken apart by code, so a UI knows whether
+to send the editor to the chain or to the template:
+
+- A template that cannot be assembled is the same **409 `TEMPLATE_COMPOSITION_ERROR`** the
+  composition endpoint gives.
+- A template that assembles but fails to render is a **409 `PREVIEW_UNAVAILABLE`** carrying
+  the renderer's message.
+- A store that fails while assembling is a plain **500 `INTERNAL_ERROR`**: its message stays
+  on the server, and the error goes to the unhandled-error hook.
+
+Two more things worth knowing:
+
+- **Each of the three sources composes against the same field of what it references.** A
+  child's body extends the base's body, its subject extends the base's subject. `field` on
+  every reference says which one it was written in.
+- **References are direct only.** What the referenced templates themselves reference is not
+  followed, and nothing is resolved — a reference to a template that does not exist is
+  reported here rather than raising.
+
+#### `isAbstract`
+
+Every template payload carries `isAbstract`: `true` when the version is a base to build on
+rather than a template to send — it declares a `{% managed_children %}` hole, or blocks
+without extending anything.
+
+```
+GET /api/v1/templates?isAbstract=false   # what a "pick a template to send" screen lists
+GET /api/v1/templates?isAbstract=true    # the bases, for a "pick a base to extend" screen
+GET /api/v1/templates                    # both
+```
+
+On a listing it is read from the backend's stored flag, so filtering is a column lookup
+rather than a parse of every row, and serializing a page costs nothing. The composition
+endpoint recomputes it from the source instead, which makes that copy the authority — worth
+asking for when the flag cannot be trusted, such as a backend that predates it.
+
+A backend declining `fields.isAbstract` has the filter dropped like any other unsupported
+one, and its listing shows both.
+
+### Error codes
+
+| Code | Status | Means |
+| --- | --- | --- |
+| `BAD_REQUEST` | 400 | Invalid input. See below. |
+| `UNAUTHORIZED` | 401 | Missing or wrong API key. |
+| `FORBIDDEN` | 403 | The caller was authenticated and is not allowed to do this. Declared on every route for hosts that check permissions in front of this API; the API key alone never produces it. |
+| `NOT_FOUND` | 404 | No such template key, or no such version of it. |
+| `CONFLICT` | 409 | The request cannot be applied in the current state: a tag whose text already slugs onto an existing one, or deleting a published version. |
+| `INVALID_STATUS_TRANSITION` | 409 | The lifecycle does not allow that status change. |
+| `PREVIEW_UNAVAILABLE` | 409 | The template could not be rendered; the message says why. |
+| `TEMPLATE_COMPOSITION_ERROR` | 409 | The template could not be assembled — a missing base, a loop, a malformed tag. The message names the chain. |
+| `INTERNAL_ERROR` | 500 | Unexpected failure. Reported generically, with an `X-Request-Id` header; logged as one redacted line. |
+
+Every 400 carries `details.issues`, a list of `{ "path", "message" }`, whatever the mistake
+was, so a client reads one shape:
+
+| Mistake | `path` |
+| --- | --- |
+| An invalid query parameter or body field | the field, dotted when nested |
+| A version in the path that is not a positive integer (`/versions/1abc`) | `version` |
+| A body that is not valid JSON, not a JSON object, or not sent as JSON | empty |
+| An order the backend cannot apply | `orderByField` / `orderByDirection` |
+| A value the backend refused, such as tag text with nothing sluggable in it | empty, repeating the message |
+
+An unexpected error is logged as one line: its class name, the request id, the method and the
+route pattern (`api/v1/templates/<key>/preview`, not the path). Its message, its traceback, the
+request body and a preview's context are never logged: errors from the template store or the
+template engine can carry template content and context values, which in the applications this
+API serves can be health data. Django's own `django.request` record for the 500 is suppressed
+too, since it would repeat the concrete path and attach the request object. The request id is
+the client's `X-Request-Id` when it matches `[A-Za-z0-9._-]{1,128}`, and a fresh UUID otherwise,
+so a client cannot forge a log line through it. Set `MANAGED_TEMPLATE_UNHANDLED_ERROR_HANDLER` to send errors somewhere with its own
+scrubbing instead (see [Unexpected errors](#unexpected-errors)).
+
+## Authentication
+
+By default, every `/api/v1` request must carry the shared secret:
+
+```
+Authorization: Bearer $VINTASEND_API_KEY
+```
+
+Call this API from your UI's own server side so the key never reaches a browser. If you
+do need to call it from a browser, set `VINTASEND_API_CORS_ORIGINS` to the allowed
+origins — and put a per-user auth layer in front of it first.
+
+A host that knows its callers sets `VINTASEND_API_AUTHENTICATOR` instead, and the shared key
+is then neither checked nor required. See [Authenticating callers yourself](#authenticating-callers-yourself).
+
+## Installing and embedding
+
+The package is a Django app, so the API can run inside a Django project you already deploy
+rather than as a service of its own:
+
+```bash
+pip install vintasend-templates-management-api
+```
+
+Add the app and include its URLconf under a prefix of your choosing:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    # ...
+    "vintasend_templates_management_api.templates_manager.apps.TemplatesManagerConfig",
+]
+```
+
+```python
+# urls.py
+from django.urls import include, path
+
+urlpatterns = [
+    # ...
+    path("templates-api/", include("vintasend_templates_management_api.templates_manager.urls")),
+]
+```
+
+That serves `/templates-api/health` and `/templates-api/api/v1/...`. The routes are the same as
+in the standalone project, under your prefix. Include the URLconf once per project. The main
+API's URL namespace is `vintasend_templates_management_api`, so its routes reverse as
+`vintasend_templates_management_api:<name>` and do not collide with
+[`vintasend-api`](https://github.com/vintasoftware/vintasend-api)'s when one project mounts both.
+
+The app reads these settings from your settings module. Each has a default, so leave out what
+you do not use:
+
+| Setting | Required | Default | Description |
+| --- | --- | --- | --- |
+| `MANAGED_TEMPLATE_SERVICE_FACTORY` | yes | `""` | Dotted path to the callable building your service. See [Configuring your service](#configuring-your-service). |
+| `VINTASEND_API_KEY` | unless an authenticator is set | `""` | Shared secret clients send as a bearer token. |
+| `VINTASEND_API_AUTHENTICATOR` | no | unset | `(request) -> None`, replacing the shared-key check. See below. |
+| `MANAGED_TEMPLATE_BACKEND_NAME` | no | `""` | Backend name every new template is stored under. See [Backend name](#backend-name). |
+| `MANAGED_TEMPLATE_ACTOR_RESOLVER` | no | unset | `(request) -> str \| None`, who made a status change. See [Attribution](#attribution). |
+| `MANAGED_TEMPLATE_UNHANDLED_ERROR_HANDLER` | no | unset | `(exc, request, request_id) -> None`. See [Unexpected errors](#unexpected-errors). |
+| `VINTASEND_API_CORS_ORIGINS` | no | `[]` | Browser origins allowed to call the API, as a list. Only read by the optional CORS middleware. |
+
+The three callables take a dotted path or the callable itself. The required settings, and a
+callable that cannot be imported, fail `manage.py check`, the same as in the standalone project.
+
+Nothing else from the standalone project is needed: not its settings module, its middleware or
+its `handler404`. Two of those are optional extras:
+
+- **CORS.** Add `"vintasend_templates_management_api.templates_manager.cors.CorsMiddleware"` to
+  `MIDDLEWARE` only if a browser calls the API directly. It applies to the API's routes under
+  whatever prefix you mount them, and to nothing else your project serves.
+- **A JSON 404.** Errors from the API's routes always use the `{ error }` envelope. A path that
+  matches no route at all gets your project's 404 page. To answer those in the envelope too, set
+  `handler404 = "vintasend_templates_management_api.templates_manager.views.envelope_404"` in
+  your root URLconf. It applies to every unmatched path in your project, not only the API's.
+
+### Authenticating callers yourself
+
+`VINTASEND_API_AUTHENTICATOR` names a callable `(request) -> None` that runs before every
+`/api/v1` route. Return to let the request through. Raise `ApiError("UNAUTHORIZED", ...)` for a
+caller with no valid credential and `ApiError("FORBIDDEN", ...)` for one you know and refuse: a
+401 would tell a signed-in user to sign in again. Both reach the client in the contract's error
+envelope. The callable may be `async`. `/health` is never authenticated.
+
+To check a token yourself, such as one your identity provider issued, read it with
+`bearer_token`. It takes the request or the header's value, matches the `Bearer` scheme in any
+case, and returns `None` when there is no token:
+
+```python
+# myproject/templates_api.py
+from vintasend_templates_management_api.templates_manager.auth import ApiError, bearer_token
+
+
+def authenticate(request):
+    token = bearer_token(request)
+    user = verify_token(token) if token is not None else None   # your own verification
+    if user is None:
+        raise ApiError.unauthorized("Sign in to manage templates.")
+    if not user.can_edit_templates:
+        raise ApiError.forbidden("You cannot manage templates.")
+    request.templates_user = user   # for the actor resolver below
+
+
+def resolve_actor(request):
+    return request.templates_user.email
+```
+
+```python
+# settings.py
+VINTASEND_API_AUTHENTICATOR = "myproject.templates_api.authenticate"
+MANAGED_TEMPLATE_ACTOR_RESOLVER = "myproject.templates_api.resolve_actor"
+```
+
+The authenticator only decides who may call. Who made a status change is still
+`MANAGED_TEMPLATE_ACTOR_RESOLVER`'s answer, as in [Attribution](#attribution).
+
+The setting has the same name and shape in `vintasend-api`, so a project mounting both can
+point them at one function, and that function may raise either package's `ApiError`: a refusal
+is recognised by its class name and its code, as the TypeScript packages do, not by its class.
+Only `UNAUTHORIZED` and `FORBIDDEN` count as a refusal; an `ApiError` with any other code, like
+any other exception, is an unexpected error and answers 500.
+
+## Running it on its own
+
+The package also carries a complete Django project, for a deployment that runs the API as a
+service of its own. Configure it through environment variables (see
+[Environment variables](#environment-variables)), or through a `.env` file in the directory you
+start it from. The project does not depend on a WSGI server, so install one alongside it:
+
+```bash
+pip install vintasend-templates-management-api gunicorn
+export DJANGO_SETTINGS_MODULE=vintasend_templates_management_api.settings
+django-admin check                          # fails on missing or unusable settings
+gunicorn vintasend_templates_management_api.wsgi:application --bind 0.0.0.0:3334
+```
+
+Your service factory must be importable by the process, so install it as a package or put its
+directory on `PYTHONPATH`. `vintasend_templates_management_api.asgi:application` is there for an
+ASGI server, though the API is synchronous throughout.
+
+## Getting started
+
+To work on the API itself, from a checkout:
+
+```bash
+poetry install
+cp .env.example .env
+```
+
+Then configure the service the API should read from (below), and run:
+
+```bash
+poetry run python manage.py runserver 0.0.0.0:3334
+```
+
+## Configuring your service
+
+The API ships no template store of its own. Point `MANAGED_TEMPLATE_SERVICE_FACTORY` at a
+callable that returns a configured service:
+
+```python
+# vintasend_templates_management_api/vintasend_config.py
+from vintasend_managed_templates.managed_template_renderer import ManagedTemplateEmailRenderer
+from vintasend_managed_templates.managed_template_service import ManagedTemplateService
+
+
+def create_template_service():
+    backend = ...   # your BaseTemplateManagerBackend
+    renderer = ManagedTemplateEmailRenderer(backend, ...)  # wraps an ordinary renderer
+
+    return ManagedTemplateService(
+        template_manager_backend=backend,
+        template_renderer=renderer,
+    )
+```
+
+Start from
+[`vintasend_config.example.py`](./vintasend_templates_management_api/vintasend_config.example.py),
+copying it to `vintasend_templates_management_api/vintasend_config.py` (gitignored) in a checkout.
+With the package installed, the factory lives in any module of yours the process can import,
+such as `myproject.templates_api.create_template_service`. The factory is called once per process and its result reused, so it must be safe to call once and the
+service it returns must be safe to share across requests.
+
+Only the preview endpoint uses the renderer, so a deployment that never previews can pass
+one that raises. A preview never uses a fallback registered on the renderer: it renders a stored
+version or reports a 404.
+
+### Attribution
+
+Status routes record a `changedBy` in the audit trail. By default it comes from the request
+body, which is only safe when everyone holding the API key is trusted to attribute honestly.
+When the host knows who is calling (a gateway header, a session it validated), point
+`MANAGED_TEMPLATE_ACTOR_RESOLVER` at a callable that answers it:
+
+```python
+# vintasend_templates_management_api/vintasend_config.py
+def resolve_actor(request) -> str | None:
+    return request.headers.get("X-Authenticated-User")   # set by your trusted proxy
+```
+
+```bash
+MANAGED_TEMPLATE_ACTOR_RESOLVER=vintasend_templates_management_api.vintasend_config.resolve_actor
+```
+
+When it is set, its answer is what `/status`, `/activate`, `/deactivate` and `/archive` all
+record, and any `changedBy` in the body is ignored. `None` records the change as unattributed.
+The resolver may be `async`. The body field stays optional in the contract, so existing clients
+keep working. In `settings.py` you can also assign the callable itself rather than a dotted path.
+
+### Backend name
+
+`POST /templates` stores the `templateManagedBackend` its body carries. A host that serves one
+template backend sets `MANAGED_TEMPLATE_BACKEND_NAME`, and every new template is stored under that
+name instead, so a caller cannot label a template with another backend:
+
+```bash
+MANAGED_TEMPLATE_BACKEND_NAME=medplum
+```
+
+Unset, the body's value is stored. The body field stays required either way, so clients written
+against the contract keep working.
+
+### Unexpected errors
+
+`MANAGED_TEMPLATE_UNHANDLED_ERROR_HANDLER` names a callable `(exc, request, request_id) -> None`
+that receives every error the API does not map to a contract error, in place of the default
+one-line log. It may be `async`. It gets the exception itself, so keeping health data out of
+wherever it sends it is your responsibility. If it raises, the default line is logged instead
+and what it raised is not; the client gets the same generic 500 with the same `X-Request-Id`
+either way.
+
+```python
+def report_unhandled_error(exc, request, request_id):
+    error_tracker.capture(exc, tags={"request_id": request_id})   # with its own scrubbing
+```
+
+The lifecycle is your service's, not this API's. A `ManagedTemplateService` subclass with
+its own `ALLOWED_STATUS_TRANSITIONS`, or one built with
+`validate_status_transitions=False`, is reported accurately through `allowedTransitions`
+and enforced through the same 409.
+
+## Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `VINTASEND_API_KEY` | unless an authenticator is set | Shared secret clients must send as a bearer token. |
+| `VINTASEND_API_AUTHENTICATOR` | no | Dotted path to `(request) -> None`, replacing the shared-key check. See [Authenticating callers yourself](#authenticating-callers-yourself). |
+| `MANAGED_TEMPLATE_SERVICE_FACTORY` | yes | Dotted path to the callable building your service. |
+| `VINTASEND_API_CORS_ORIGINS` | no | Comma-separated browser origins allowed to call the API. |
+| `MANAGED_TEMPLATE_BACKEND_NAME` | no | Backend name every new template is stored under, replacing the create body's. See [Backend name](#backend-name). |
+| `MANAGED_TEMPLATE_ACTOR_RESOLVER` | no | Dotted path to `(request) -> str \| None`, who made a status change. See [Attribution](#attribution). |
+| `MANAGED_TEMPLATE_UNHANDLED_ERROR_HANDLER` | no | Dotted path to `(exc, request, request_id) -> None`. See [Unexpected errors](#unexpected-errors). |
+| `DJANGO_SECRET_KEY` | no | Django requires one; this API signs nothing. |
+| `DJANGO_DEBUG` / `DJANGO_ALLOWED_HOSTS` / `DJANGO_LOG_LEVEL` | no | Standard Django knobs. |
+| `DJANGO_DB_*` | no | Only needed by backends that resolve their models through Django. |
+
+The required ones are enforced by a Django system check, so a deployment missing one fails
+on `manage.py check` and on `runserver` rather than on the first request. The three hooks are
+checked the same way: a dotted path that does not import, or names something that is not
+callable, fails the check. Run
+`manage.py check` in your release step if you serve with gunicorn.
+
+## Development
+
+```bash
+poetry run python manage.py runserver          # dev server
+poetry run pytest                              # tests
+poetry run ruff check .                        # lint
+poetry run ruff format .                       # format
+poetry run mypy                                # type-check
+poetry run python manage.py export_openapi     # regenerate openapi.yaml
+poetry run python manage.py export_openapi --check   # fail if it is stale
+```
+
+Tests drive the real Django application through the test client over a real
+`ManagedTemplateService` composed of in-memory seams. Faking the *seams* rather than the
+service is deliberate: version resolution, the transition table and filter validation are
+the service's behaviour, and this API's job is to expose it faithfully — a fake service
+would let a route drift from the thing it is meant to be exposing without the suite
+noticing.
+
+## Design notes
+
+Worth knowing if you are implementing this contract elsewhere, or wondering why something
+is missing.
+
+**Filters are dropped; orders are refused.** Both are negotiated against the same
+capability report, and they resolve in opposite directions. That is deliberate:
+
+| | Unsupported filter | Unsupported order |
+|---|---|---|
+| What happens | dropped, request succeeds | `400 BAD_REQUEST` |
+| If it were ignored | more rows than asked for | the same rows, arbitrary sequence |
+| Can the client tell? | yes, from the rows | **no** |
+
+A client rendering an unordered page under a highlighted "sorted by name" column header is
+displaying a sort that never happened, and nothing in the response says so. Sending
+`orderByDirection` without `orderByField` is a 400 for the same reason — ignoring it looks
+exactly like a backend that cannot sort, which hides the client bug.
+
+**Neither ordering parameter has a default.** Every `orderBy.*` capability defaults to
+`false`, so a default field would make the ordinary listing a 400 against most backends.
+Omitted asks for the backend's own order — which is what an unordered listing has always
+returned. Note this differs from `vintasend-api`, which *does* default its order; there,
+every notification backend can sort.
+
+Read `GET /api/v1/capabilities` and offer only the columns it reports as sortable.
+
+**Pagination needs no negotiation.** `vintasend-api` reads `pagination.oneIndexed` off
+each backend because notification backends genuinely differ. Here `ManagedTemplateService`
+validates `page >= 1` itself and no call reaches a backend without passing through that
+validation, so the wire's 1-indexing *is* the service's convention.
+
+**Capabilities are declared, not required.** `BaseTemplateManagerBackend.get_filter_capabilities`
+is concrete and returns `{}`, so a backend that says nothing keeps working. As with
+notifications, a backend declares only what it *cannot* do, and `ManagedTemplateService`
+merges its report over the library's default.
+
+The `orderBy.*` keys are the one exception to "a missing key means supported": they
+default to `false`. Ordering is newer vocabulary than the filters, so a `true` default
+would have every backend written before it existed claim an order it silently ignores. A
+backend that can sort declares it — and should verify each claim by *running* the sort, not
+by reading its store's documentation.
+
+**Composition is reported, not enforced on write.** A template that extends a base which
+does not exist yet is stored without complaint: a UI drafting a set of templates would
+otherwise have to create them in dependency order, and a base can legitimately be written
+after the child that names it. The cost is that a broken reference is found on read rather
+than on save — which is why `GET /templates/{key}/composition` exists and returns the
+library's message verbatim, and why a save-then-check round trip is the pattern for an
+editor that wants to warn before publishing. Publishing is where it matters: a template
+that cannot be assembled cannot be sent, so check before `POST /templates/{key}/activate`.
+
+**Preview contexts are plain dicts.** The renderer seam types a context as
+`NotificationContextDict`, but that class cannot represent an ordinary nested object: its
+validation requires every value inside a nested `dict` to itself be a
+`NotificationContextDict`, with no base case for a scalar, so `{"user": {"name": "Ana"}}`
+is inexpressible. `None` values and lists of strings are refused for related reasons, and
+both appear in real stored contexts. Since a notification's stored `context_used` is a
+plain dict and renderers only read from a context, the caller's object is passed through —
+the same thing `vintasend-api` does. A preview that refused what a real send carries would
+be a worse guide to production than no preview.
+
+**Updates create versions.** `POST /templates/{key}/versions` rather than a `PATCH`,
+because the backend copies the latest version forward and applies the non-`None` fields to
+the copy. An already-published version is never modified, and the route shape says so.
+
+**Deletion is per version.** The seam has no operation removing every version of a key, so
+neither does this API; doing it as a loop here would be a multi-step deletion with no
+transaction around it.
+
+**Retagging is the one write that does not create a version.** `PUT /templates/{key}/tags`
+edits a version in place, unlike every other write on a template. Tags describe how a
+template is *found*, not what it renders, so relabelling one for search should not fork a
+version and drop it back to draft. To change tags and content together, send `tags` on
+`POST /templates/{key}/versions` instead — where an omitted `tags` carries the previous
+version's forward and `[]` clears them.
+
+**Tag listing is paged in this API, not in the store.** The template-manager seam has no
+paginated tag read, so `GET /tags` slices the page in process. That is sound in a way
+in-process *ordering* would not be: `get_tags` returns the whole set in one stable order,
+so a page is a slice of a complete list rather than a re-sort of an arbitrary window.
+
+**`fields.mostRecentActiveVersion` is a capability of its own.** It is not a column test like
+every other field: a backend answers it by comparing a row against the other versions of its
+key, which a store keeping no version history cannot do. Declining it means the list endpoint
+drops it and returns a row per version — the honest answer for a store that has only one.
+
+**The two tag filters are separate capabilities.** `fields.includesAllTags` and
+`fields.includesAnyOfTags` are different queries — the first needs a per-template count
+over the tags asked for, the second only needs membership — so a backend can support one
+without the other. As with every filter, a declined one is dropped rather than failing the
+request.
+
+## License
+
+MIT
+