@fleetless/contracts 1.0.0

package/dist/app-users.d.ts

@@ -0,0 +1,606 @@
+import { z } from 'zod';
+/**
+ * **App users: the per-app identity space** (spec `2026-09-05-app-user-auth`,
+ * D1–D7).
+ *
+ * The 2026-08-29 model put developers and end users into one pool per org,
+ * tied apps to groups, and let an org admin enter an app only by
+ * impersonation. It modelled the wrong thing: the people who configure robots
+ * in the console and the people who use a developer's app are different
+ * populations with different lifecycles, and every mechanism that connected
+ * them — groups, assignments, impersonation, the app-branded portal pages —
+ * was cost without a product reason.
+ *
+ * So there are now **two identity spaces and nothing joins them**:
+ *
+ * - *Fleetless users* (`identity.ts`) — the org's team. Email globally unique,
+ *   tier `owner | developer`, Fleetless password, console access.
+ * - *app users* (this file) — one app each. Email unique **per app**,
+ *   case-insensitively. The same address may exist in several apps of one org
+ *   as unrelated accounts, and a Fleetless user who wants to use an app
+ *   registers or is invited like anybody else.
+ *
+ * **Fleetless shows an app user no page** (D2). The developer's own UI owns
+ * every screen and calls the JSON client-auth API (`client-auth.ts`). The one
+ * Fleetless-rendered surface an app user can reach is the problem page for an
+ * OIDC callback whose state no longer resolves to a redirect URI — every other
+ * error is redirected to the app to render. That is why the four URLs on
+ * `appAuthConfig` exist: Fleetless mails a link, and the link points into the
+ * app.
+ */
+/** App-user display names share the Fleetless-user bound, so a rename cannot be legal in one space and refused in the other. */
+export declare const APP_USER_DISPLAY_NAME_MAX = 120;
+/**
+ * **A provider slug — hyphenated, and deliberately not the ROS slug grammar.**
+ *
+ * `appIdentifier` is `slug`: lowercase and *underscore*-separated, because it
+ * names something that also appears in ROS. A provider slug appears in a URL
+ * path (`/api/client/oidc/:slug/start`) and on the developer's own sign-in
+ * buttons, where a hyphen is the conventional spelling — `azure-ad`, not
+ * `azure_ad`.
+ *
+ * The two grammars are one character apart, which is exactly why this is its
+ * own export with its own tests rather than a reuse: reusing the wrong one
+ * would be invisible until a customer typed a hyphen.
+ */
+export declare const providerSlug: z.ZodString;
+/**
+ * **The three states an app user can be in, and the order is the lifecycle.**
+ *
+ * - `pending_verification` — self-registered, mail sent, cannot log in yet
+ *   (D6). Without this state the domain whitelist would prove nothing: anybody
+ *   could claim any address at an allowed domain.
+ * - `active` — may log in.
+ * - `blocked` — may not, and every refusal is the same `invalid_credentials`
+ *   a wrong password gets (§4). A block that announced itself would be an
+ *   account-enumeration oracle with an extra step.
+ *
+ * `pending_verification` is reached exactly once and left only by spending the
+ * mailed token, which is why `patchAppUserRequest` cannot set it: see there.
+ */
+export declare const appUserStatus: z.ZodEnum<{
+    pending_verification: "pending_verification";
+    active: "active";
+    blocked: "blocked";
+}>;
+export type AppUserStatus = z.infer<typeof appUserStatus>;
+/**
+ * **A user of one app.** Not a user of the org: `app_id` is the whole scope,
+ * and the uniqueness constraint the cloud enforces is `(app_id, lower(email))`
+ * rather than a global one. The same person at two apps of one org is two
+ * unrelated rows, by design (D1).
+ */
+export declare const appUser: z.ZodObject<{
+    id: z.ZodUUID;
+    app_id: z.ZodUUID;
+    email: z.ZodEmail;
+    display_name: z.ZodNullable<z.ZodString>;
+    role_id: z.ZodUUID;
+    status: z.ZodEnum<{
+        pending_verification: "pending_verification";
+        active: "active";
+        blocked: "blocked";
+    }>;
+    has_password: z.ZodBoolean;
+    providers: z.ZodArray<z.ZodString>;
+    last_login_at: z.ZodNullable<z.ZodISODateTime>;
+    created_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type AppUser = z.infer<typeof appUser>;
+/** `GET /api/apps/:id/users` — every app user of one app, never null: an app with no users answers an empty array. */
+export declare const appUserListResponse: z.ZodObject<{
+    users: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        app_id: z.ZodUUID;
+        email: z.ZodEmail;
+        display_name: z.ZodNullable<z.ZodString>;
+        role_id: z.ZodUUID;
+        status: z.ZodEnum<{
+            pending_verification: "pending_verification";
+            active: "active";
+            blocked: "blocked";
+        }>;
+        has_password: z.ZodBoolean;
+        providers: z.ZodArray<z.ZodString>;
+        last_login_at: z.ZodNullable<z.ZodISODateTime>;
+        created_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AppUserListResponse = z.infer<typeof appUserListResponse>;
+/**
+ * **A developer creating an app user directly, password and all** — the door
+ * that exists so a developer can seed an account without waiting for a mail.
+ *
+ * `.strict()`: `status` is absent and cannot arrive. A user created here is
+ * `active`, because a developer who typed the password has already vouched for
+ * the address; letting the body choose would give one route two lifecycles.
+ */
+export declare const createAppUserRequest: z.ZodObject<{
+    email: z.ZodEmail;
+    password: z.ZodString;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    role_id: z.ZodOptional<z.ZodUUID>;
+}, z.core.$strict>;
+export type CreateAppUserRequest = z.infer<typeof createAppUserRequest>;
+/**
+ * `PATCH /api/apps/:id/users/:userId` — **what a developer may change, and
+ * what is absent rather than merely un-required.**
+ *
+ * `email` is not here: it is the identifier of the account, the value every
+ * invitation, reset link and audit line names, and a PATCH that could change
+ * it is both an account-takeover surface and a uniqueness race. Strict, so
+ * offering it is a refusal rather than a silently dropped field.
+ *
+ * **`status` admits only `active` and `blocked`.** `pending_verification` is
+ * reached once, by self-registration, and left by spending the mailed token
+ * (D6). A developer able to set it back could void a verified address without
+ * the user ever seeing a mail, and there is no route out of that state that
+ * does not require a token nobody re-sent. So the narrower enum is the rule,
+ * stated in the schema rather than left to a handler to remember.
+ */
+export declare const patchAppUserRequest: z.ZodObject<{
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    role_id: z.ZodOptional<z.ZodUUID>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        blocked: "blocked";
+    }>>;
+}, z.core.$strict>;
+export type PatchAppUserRequest = z.infer<typeof patchAppUserRequest>;
+/**
+ * **Inviting an address into an app.** The invitation carries the role, so the
+ * person who accepts it lands with the access the developer chose rather than
+ * with a default somebody has to remember to change afterwards.
+ */
+export declare const createAppInvitationRequest: z.ZodObject<{
+    email: z.ZodEmail;
+    role_id: z.ZodOptional<z.ZodUUID>;
+    display_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    send_mail: z.ZodBoolean;
+}, z.core.$strict>;
+export type CreateAppInvitationRequest = z.infer<typeof createAppInvitationRequest>;
+/**
+ * The invitation as issued.
+ *
+ * **`accept_url` is nullable, and that is a policy rather than a convenience.**
+ * The link points into the developer's app, at their configured `invite_url`.
+ * An app that has configured none has nowhere for it to point, so there is no
+ * link to hand back — `null` says that outright, where an absent key would be
+ * indistinguishable from a mapper that dropped the field and a fabricated
+ * Fleetless-hosted URL would name a page this product does not serve (D2).
+ */
+export declare const appInvitation: z.ZodObject<{
+    id: z.ZodUUID;
+    app_id: z.ZodUUID;
+    email: z.ZodEmail;
+    role_id: z.ZodUUID;
+    expires_at: z.ZodISODateTime;
+    accept_url: z.ZodNullable<z.ZodURL>;
+    mail: z.ZodEnum<{
+        sent: "sent";
+        not_requested: "not_requested";
+        not_configured: "not_configured";
+        failed: "failed";
+    }>;
+}, z.core.$strip>;
+export type AppInvitation = z.infer<typeof appInvitation>;
+/**
+ * A pending invitation as the developer sees it in the list — **without its
+ * `accept_url`**, and that omission is the point.
+ *
+ * The list exists so a developer can see what is outstanding and revoke it.
+ * Neither needs the token, and a list that carries it turns every screenshot,
+ * log line and browser-history entry of that page into live credentials for
+ * somebody else's account. The same rule `pendingUserInvite` already keeps.
+ *
+ * `mail` is omitted for a duller reason: it described what happened at
+ * creation time, and re-serving it invites a reader to take it as current.
+ */
+export declare const pendingAppInvitation: z.ZodObject<{
+    id: z.ZodUUID;
+    email: z.ZodEmail;
+    expires_at: z.ZodISODateTime;
+    app_id: z.ZodUUID;
+    role_id: z.ZodUUID;
+}, z.core.$strip>;
+export type PendingAppInvitation = z.infer<typeof pendingAppInvitation>;
+/** `GET /api/apps/:id/invitations` — pending only. An accepted invitation is history, not something to revoke. */
+export declare const appInvitationListResponse: z.ZodObject<{
+    invitations: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        email: z.ZodEmail;
+        expires_at: z.ZodISODateTime;
+        app_id: z.ZodUUID;
+        role_id: z.ZodUUID;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AppInvitationListResponse = z.infer<typeof appInvitationListResponse>;
+/**
+ * **An app's OIDC provider, as read back** (D4). Any number per app, unlike
+ * the group provider this replaces — a developer serving two customers needs
+ * two, and the old at-most-one rule was a property of groups rather than of
+ * identity.
+ *
+ * **No secret, by construction.** The client secret goes in through the create
+ * and patch requests and never comes back out: a secret a response can carry
+ * is a secret in every log that ever captured a response, the same rule the
+ * server key and the group provider already kept.
+ *
+ * `issuer` is `idpIssuer` — http(s) only, no credentials, query or fragment.
+ * **This is not the SSRF defence.** It cannot tell the dev IdP
+ * (`http://localhost:8081/realms/…`) from `http://127.0.0.1:5432`, both being
+ * loopback http; the real defence refuses loopback, link-local and private
+ * ranges at the discovery fetch, in the cloud, and names DNS rebinding as its
+ * own residual.
+ */
+export declare const appOidcProvider: z.ZodObject<{
+    id: z.ZodUUID;
+    app_id: z.ZodUUID;
+    slug: z.ZodString;
+    name: z.ZodString;
+    issuer: z.ZodURL;
+    client_id: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    link_verified_emails: z.ZodBoolean;
+    enabled: z.ZodBoolean;
+    created_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type AppOidcProvider = z.infer<typeof appOidcProvider>;
+/** `GET /api/apps/:id/oidc-providers` — every provider of the app, enabled or not; the public client route lists only the enabled ones. */
+export declare const appOidcProviderListResponse: z.ZodObject<{
+    providers: z.ZodArray<z.ZodObject<{
+        id: z.ZodUUID;
+        app_id: z.ZodUUID;
+        slug: z.ZodString;
+        name: z.ZodString;
+        issuer: z.ZodURL;
+        client_id: z.ZodString;
+        scopes: z.ZodArray<z.ZodString>;
+        link_verified_emails: z.ZodBoolean;
+        enabled: z.ZodBoolean;
+        created_at: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strip>;
+export type AppOidcProviderListResponse = z.infer<typeof appOidcProviderListResponse>;
+/**
+ * **Creating a provider** — `.strict()`, and the only place besides the patch
+ * that carries the client secret.
+ *
+ * The secret is **required here and optional on the patch**: a provider with
+ * no secret cannot exchange a code, so a create without one would store a row
+ * that can never work; a patch without one keeps the stored value, so a
+ * routine edit of the scopes does not force the secret back onto the wire.
+ * The minimum length refuses a trivial value — a one-character client secret
+ * is a misconfiguration, not a rotation.
+ */
+export declare const createAppOidcProviderRequest: z.ZodObject<{
+    slug: z.ZodString;
+    name: z.ZodString;
+    issuer: z.ZodURL;
+    client_id: z.ZodString;
+    client_secret: z.ZodString;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    link_verified_emails: z.ZodDefault<z.ZodBoolean>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type CreateAppOidcProviderRequest = z.infer<typeof createAppOidcProviderRequest>;
+/**
+ * **Patching a provider** — every field optional, and `slug` absent.
+ *
+ * The slug is in the path and is what `app_user_identities` rows are keyed by,
+ * so renaming it would orphan every linked account. Strict, so offering it is
+ * a `400` naming the field rather than a `200` that changed nothing — the
+ * silence `updateAppRequest` was made strict to avoid.
+ */
+export declare const patchAppOidcProviderRequest: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    issuer: z.ZodOptional<z.ZodURL>;
+    client_id: z.ZodOptional<z.ZodString>;
+    client_secret: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    link_verified_emails: z.ZodOptional<z.ZodBoolean>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type PatchAppOidcProviderRequest = z.infer<typeof patchAppOidcProviderRequest>;
+/**
+ * **The placeholder each configurable app URL must carry, declared once.**
+ *
+ * Three of the four take a `{token}` and the fourth an `{interaction}`, and
+ * the difference is not cosmetic: the MCP login URL is handed an interaction
+ * id, not a credential. Exported so the console's help text, the cloud's
+ * substitution and this file's validators cannot spell them differently —
+ * `OAUTH_PATHS`' lesson, applied before there are five hand-written copies.
+ */
+export declare const APP_URL_PLACEHOLDERS: {
+    readonly invite_url: "{token}";
+    readonly verify_url: "{token}";
+    readonly reset_url: "{token}";
+    readonly mcp_login_url: "{interaction}";
+};
+/**
+ * **An app-hosted URL template: https (or loopback http) carrying its
+ * placeholder exactly once.**
+ *
+ * Two rules, each with a failure it exists to prevent.
+ *
+ * *The scheme.* These links are mailed and carry a single-use credential in
+ * their path; over plain http on a public host that credential is readable by
+ * every hop. `localhost` and `127.0.0.1` are the exception because a developer
+ * building their app has no certificate, and a rule that made local
+ * development impossible would be worked around with a proxy nobody reviewed.
+ *
+ * *Exactly once.* The cloud substitutes the token with a plain string replace,
+ * which takes the **first** occurrence. A template naming the placeholder
+ * twice would therefore get one occurrence substituted and one left literal,
+ * and the link would 404 for the person who received the mail rather than fail
+ * for the developer who wrote it. Refusing at configuration time is the only
+ * place that mistake is cheap. A template with no placeholder is refused for
+ * the mirror reason: it would mail every recipient the same link.
+ *
+ * **What it cannot check**: that the URL resolves, that the app serves that
+ * path, or that the developer's page knows what to do with the token. Nothing
+ * a schema can see says any of that, and a validator that looked sufficient
+ * here would be read as an assurance.
+ */
+export declare function appUrlTemplate(placeholder: string): z.ZodString;
+/**
+ * **An origin, and nothing longer than an origin.**
+ *
+ * This list is both the CORS allow-list and the redirect-URI check, and a
+ * browser's `Origin` header is a bare origin: scheme, host, port. An entry
+ * carrying a path would compare unequal forever — a rule that silently never
+ * matches, which is worse than one that refuses, because the developer sees
+ * their own app rejected with nothing naming the typo.
+ *
+ * `u.origin === v` is the whole check for that: it rejects a trailing slash, a
+ * path, a query and a fragment in one comparison, and it does so against the
+ * browser's own normalisation rather than against a regex somebody has to keep
+ * in step with it.
+ */
+export declare const allowedOrigin: z.ZodString;
+/**
+ * **A domain for the self-registration whitelist, in one canonical spelling.**
+ *
+ * The list is compared against the domain part of an address the cloud has
+ * already lowercased, so an entry carrying a capital could never match — and
+ * the developer who typed it would see self-registration refuse everybody with
+ * nothing saying why. Lowercase is therefore the rule rather than a
+ * normalisation applied later in one of the two places that compare.
+ *
+ * The pattern is the ordinary LDH rule: labels of letters, digits and internal
+ * hyphens, at least two labels, a TLD of letters. 253 characters is the DNS
+ * name limit.
+ */
+export declare const emailDomain: z.ZodString;
+/**
+ * **The app's auth settings: one row per app, configured by a Fleetless user**
+ * (D3).
+ *
+ * `self_registration` and `allowed_domains` are **one policy for one
+ * decision** — they govern registration by password and registration through
+ * an identity provider alike (D4). An invitation always bypasses both, because
+ * a developer inviting somebody by hand has already made the decision the
+ * whitelist automates.
+ *
+ * The four URLs are what makes D2 work: Fleetless mails a link, and the link
+ * points into the developer's app. An app that has configured none of them
+ * still works for password login — it simply cannot send a mail that leads
+ * anywhere, and `send_mail` is refused rather than silently sending a dead
+ * link.
+ */
+export declare const appAuthConfig: z.ZodObject<{
+    self_registration: z.ZodBoolean;
+    allowed_domains: z.ZodArray<z.ZodString>;
+    allowed_origins: z.ZodArray<z.ZodString>;
+    mcp_enabled: z.ZodBoolean;
+    invite_url: z.ZodNullable<z.ZodString>;
+    verify_url: z.ZodNullable<z.ZodString>;
+    reset_url: z.ZodNullable<z.ZodString>;
+    mcp_login_url: z.ZodNullable<z.ZodString>;
+    oidc_callback_url: z.ZodURL;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type AppAuthConfig = z.infer<typeof appAuthConfig>;
+/**
+ * `PUT /api/apps/:id/auth-config` — a replace, not a merge, and `.strict()`.
+ *
+ * `oidc_callback_url` and `updated_at` are omitted because both are the
+ * server's: see the callback URL's own note for why a writable one would be a
+ * redirect-target hole rather than a convenience.
+ */
+export declare const putAppAuthConfigRequest: z.ZodObject<{
+    self_registration: z.ZodBoolean;
+    allowed_domains: z.ZodArray<z.ZodString>;
+    allowed_origins: z.ZodArray<z.ZodString>;
+    mcp_enabled: z.ZodBoolean;
+    invite_url: z.ZodNullable<z.ZodString>;
+    verify_url: z.ZodNullable<z.ZodString>;
+    reset_url: z.ZodNullable<z.ZodString>;
+    mcp_login_url: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PutAppAuthConfigRequest = z.infer<typeof putAppAuthConfigRequest>;
+/**
+ * The three mails a developer may replace with their own template (D5).
+ * Mails to *Fleetless* users — a team invitation, a console password reset —
+ * stay Fleetless default and are deliberately not customisable: they are
+ * about this platform, not about the developer's product.
+ */
+export declare const mailTemplateKind: z.ZodEnum<{
+    invite: "invite";
+    verify: "verify";
+    reset: "reset";
+}>;
+export type MailTemplateKind = z.infer<typeof mailTemplateKind>;
+/**
+ * **Every variable a template may name, and the list is closed.**
+ *
+ * Liquid runs in strict mode: an unknown variable is an error at save time and
+ * in the preview, rather than an empty string in a mail somebody already
+ * received. That is only worth anything if the permitted set is written down
+ * where the renderer, the console's completion and the docs all read the same
+ * one.
+ */
+export declare const MAIL_TEMPLATE_VARIABLES: readonly ["app.name", "org.name", "user.email", "user.display_name", "role.name", "link", "expires_in_hours"];
+/**
+ * **The Fleetless default text for the three app mails** (spec D5, §6).
+ *
+ * It lives here rather than in the cloud because two products send the same
+ * words: the cloud renders these when an app has no template of its own, and
+ * the console seeds its editor with them when a developer presses *Customise*.
+ * They were written twice, in different words, and a developer comparing the
+ * editor against a mail they had received would have found two Fleetless
+ * defaults that disagreed. One text, one place, and neither consumer may hold
+ * a copy.
+ *
+ * These are Liquid templates like any custom one — the same variables, the
+ * same renderer, the same bounds — so the cloud's fallback path cannot become
+ * a second, weaker mechanism that merely looks like the real one.
+ *
+ * **Text-only (`html: null`).** A text part is a complete mail, and a default
+ * that shipped markup would make every app that never opens the Mails tab send
+ * Fleetless-styled HTML on behalf of a product that is not Fleetless.
+ *
+ * The voice is plain and short, names the app rather than this platform, and
+ * says what the link does, how long it lasts, and what to do if it was not
+ * you.
+ *
+ * **`verify` and `reset` greet by the address, not by the display name**, and
+ * that is a security decision rather than a style one. `display_name` on those
+ * two mails comes from `POST /api/client/register`, which is unauthenticated:
+ * whoever typed the address also chose 120 characters of text that Fleetless
+ * then renders into a mail sent from the *developer's* own sender to an
+ * address the same caller chose. "Hello Account suspended — verify at
+ * https://evil.example now," is a phishing line with a real product's return
+ * address on it. The recipient's own address is the one value in that mail
+ * they can check, and it is the greeting. `invite` keeps the display name:
+ * that one is written by an authenticated developer about somebody they
+ * invited.
+ *
+ * **`expires_in_hours` is the only lifetime variable the spec offers**, and
+ * the three values are 1, 24 and 168. "The next 168 hours" is not how a person
+ * says a week, so each default converts: 48 and up reads in days, exactly one
+ * reads "1 hour", everything else reads in hours. The conversion is in the
+ * template rather than in a new variable because a custom template has the
+ * same problem and this is the spelling it can copy.
+ *
+ * **What contracts does NOT assert about these.** That they compile as Liquid
+ * is the cloud's business — contracts has no renderer and adding one to check
+ * its own constant would be a second, weaker copy of the thing that actually
+ * sends mail. Here they are pinned as a complete, non-empty set; the cloud
+ * asserts that the mail it sends for each kind is this exact text.
+ */
+export declare const DEFAULT_MAIL_TEMPLATES: Record<MailTemplateKind, {
+    subject: string;
+    text: string;
+    html: null;
+}>;
+/**
+ * One stored template. `html` is nullable because the mailer's HTML part is
+ * optional — a text-only mail is a complete mail, and an app that wants one
+ * should not have to write the same words twice.
+ */
+export declare const appMailTemplate: z.ZodObject<{
+    kind: z.ZodEnum<{
+        invite: "invite";
+        verify: "verify";
+        reset: "reset";
+    }>;
+    subject: z.ZodString;
+    text: z.ZodString;
+    html: z.ZodNullable<z.ZodString>;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strip>;
+export type AppMailTemplate = z.infer<typeof appMailTemplate>;
+/** `GET /api/apps/:id/mail-templates` — **only the kinds that have a custom template.** An absent kind is one using the Fleetless default, which is a state and not a gap. */
+export declare const appMailTemplateListResponse: z.ZodObject<{
+    templates: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            invite: "invite";
+            verify: "verify";
+            reset: "reset";
+        }>;
+        subject: z.ZodString;
+        text: z.ZodString;
+        html: z.ZodNullable<z.ZodString>;
+        updated_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AppMailTemplateListResponse = z.infer<typeof appMailTemplateListResponse>;
+export declare const putAppMailTemplateRequest: z.ZodObject<{
+    subject: z.ZodString;
+    text: z.ZodString;
+    html: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type PutAppMailTemplateRequest = z.infer<typeof putAppMailTemplateRequest>;
+/**
+ * **The preview takes the same document the PUT does — as a second object,
+ * not as an alias.**
+ *
+ * The fields are defined once (`mailTemplateBody` above) and `.strict()` twice,
+ * so there is one definition and two values. An alias would be one value under
+ * two contract names, and the export registry resolves an artifact by object
+ * identity: it refuses a schema registered twice, because the artifact a route
+ * points at would otherwise be a coin toss.
+ */
+export declare const mailTemplatePreviewRequest: z.ZodObject<{
+    subject: z.ZodString;
+    text: z.ZodString;
+    html: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type MailTemplatePreviewRequest = z.infer<typeof mailTemplatePreviewRequest>;
+/** What the preview renders, with the sample data filled in. The developer reads this before anybody receives it. */
+export declare const mailTemplatePreviewResponse: z.ZodObject<{
+    subject: z.ZodString;
+    text: z.ZodString;
+    html: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type MailTemplatePreviewResponse = z.infer<typeof mailTemplatePreviewResponse>;
+/**
+ * The `details` of a `422 template_invalid`: **which part failed**, not merely
+ * that something did.
+ *
+ * A template has three independently-rendered parts, and an error that did not
+ * say which one leaves the developer re-reading all three. `message` is the
+ * renderer's own — it names the unknown variable or the syntax error — and
+ * carries nothing else: it is written into an audit event as well, where the
+ * rule is that no credential, token or password may appear.
+ */
+export declare const mailTemplateProblemDetails: z.ZodObject<{
+    part: z.ZodEnum<{
+        subject: "subject";
+        text: "text";
+        html: "html";
+    }>;
+    message: z.ZodString;
+}, z.core.$strip>;
+export type MailTemplateProblemDetails = z.infer<typeof mailTemplateProblemDetails>;
+/**
+ * **What a `202` says when the only thing that happened was a mail.**
+ *
+ * Three routes do one act and answer nothing about it — re-sending a user's
+ * reset link, mailing an invitation, sending a test template. A bare `202`
+ * with an empty body would be honest about the *acceptance* and silent about
+ * the one fact the developer needs next, which is whether a mail actually left:
+ * an app with no SMTP configured looks exactly like one that mailed, and the
+ * developer waits for a message nobody sent.
+ *
+ * So the body is `{ "mail": mailStatus }` and nothing else. `sent` means the
+ * SMTP server accepted it, not that it was delivered; `not_configured` is an
+ * expected state on a deployment without a mailer and is not a failure;
+ * `failed` is the one worth somebody's attention.
+ *
+ * It is its own object rather than a reuse of `appInvitation`'s field because
+ * the export registry resolves an artifact by object identity — one schema
+ * under two contract names would make the artifact a route points at a coin
+ * toss, the same reason `mailTemplatePreviewRequest` is a second `.strict()`
+ * rather than an alias.
+ */
+export declare const mailOutcome: z.ZodObject<{
+    mail: z.ZodEnum<{
+        sent: "sent";
+        not_requested: "not_requested";
+        not_configured: "not_configured";
+        failed: "failed";
+    }>;
+}, z.core.$strip>;
+export type MailOutcome = z.infer<typeof mailOutcome>;