@saasicat/ui-vue 0.25.0 → 0.26.1

package/README.md

@@ -15,12 +15,35 @@ The package is layered so that each entry only loads what it names.
 Lower layers never import upward; ESLint (`no-restricted-imports`, repo
 root config) enforces the boundaries in CI.
 
-| Entry                                                                   | Source                           | May import                               | Contents                                                                                                                                                                                                   |
-| ----------------------------------------------------------------------- | -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@saasicat/ui-vue/client`                                               | `src/client/`                    | `@saasicat/types` only                   | Framework-free core: `BootLoader`, `ManifestLoader` (ETag cache), nav builder, action registry, batch column fetcher, `HttpClient`/`KvStore` contract. Usable from any framework or plain Node/TypeScript. |
-| `@saasicat/ui-vue` (main)                                               | `src/vue/` (+ client re-exports) | Vue, `vue-router`, Pinia — **no Quasar** | Composables (`useTenants`, `usePlanEditor`, …), router guards, injection keys + shell contract, notify-port type, optional Pinia store factory.                                                            |
-| `@saasicat/ui-vue/quasar`                                               | `src/quasar/`                    | everything above + Quasar                | `createSuperAdminApp()` bootstrap and the Quasar notify-port implementation.                                                                                                                               |
-| `@saasicat/ui-vue/pages-standard/*`, `/pages-tenant/*`, `/components/*` | SFC directories                  | everything                               | The Quasar reference UI, shipped as raw `.vue` from `src/` (compiled by the consumer's Vite).                                                                                                              |
+| Entry                                                                   | Source                           | May import                               | Contents                                                                                                                                                                                                                                                         |
+| ----------------------------------------------------------------------- | -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@saasicat/ui-vue/client`                                               | `src/client/`                    | `@saasicat/types` only                   | Framework-free core: `BootLoader`, `ManifestLoader` (ETag cache), nav builder, action registry, batch column fetcher, the `HttpClient`/`KvStore` contract with its `fetch` and axios adapters, `AdminError`. Usable from any framework or plain Node/TypeScript. |
+| `@saasicat/ui-vue` (main)                                               | `src/vue/` (+ client re-exports) | Vue, `vue-router`, Pinia — **no Quasar** | Composables (`useTenants`, `usePlanEditor`, …), router guards, injection keys + shell contract, notify-port type, optional Pinia store factory.                                                                                                                  |
+| `@saasicat/ui-vue/quasar`                                               | `src/quasar/`                    | everything above + Quasar                | `createSuperAdminApp()` bootstrap and the Quasar notify-port implementation.                                                                                                                                                                                     |
+| `@saasicat/ui-vue/pages-standard/*`, `/pages-tenant/*`, `/components/*` | SFC directories                  | everything                               | The Quasar reference UI, shipped as raw `.vue` from `src/` (compiled by the consumer's Vite).                                                                                                                                                                    |
+
+### The shipped source has a language floor
+
+The last row is not a build output: those subpaths hand out `.vue` and `.ts`
+straight from `src/`, so **your** `tsconfig` compiles them, not ours. Anything
+they reach — which includes `src/client/` and `src/vue/` — therefore has to
+compile under the oldest language level a consumer uses.
+
+That floor is **ES2021** (`lib: ES2021, DOM`), with **TypeScript 5.0** as the
+minimum compiler. The language level is checked rather than promised:
+`pnpm --filter @saasicat/ui-vue test:shipped-source` compiles the closure
+reachable from every source-shipping subpath at that level, with
+`isolatedModules`, `useDefineForClassFields` and `strictPropertyInitialization`
+set the way a Vite app sets them, and CI runs it. The directories come from the export map, so a new source subpath
+is covered the day it is added. The compiler version is not checked — `satisfies`
+in the shipped source needs 4.9 or newer whatever `lib` says, and testing that
+would mean installing old compilers.
+
+Practically this rules out a handful of ES2022 conveniences in shipped code —
+`new Error(msg, { cause })` and `Object.hasOwn` are the two that have come up.
+Use `attachCause()` from `src/client/attach-cause.ts` and
+`Object.prototype.hasOwnProperty.call()` instead. Code that only ever runs from
+`dist/` is unaffected.
 
 Rules of thumb when contributing:
 
@@ -48,8 +71,32 @@ createSuperAdminApp({
 });
 ```
 
-Confirm dialogs inside the reference pages intentionally keep using Quasar's
-`Dialog` — the pages _are_ the Quasar layer.
+### Confirm port
+
+A second seam, `UiConfirm` (`SUPER_ADMIN_CONFIRM_KEY`), works the same way:
+`createSuperAdminApp()` provides a Quasar `Dialog` default, and an app with its
+own modal system replaces it.
+
+It is available to your own pages today. The standard pages do **not** use it
+yet — `UsersPage`, `PilotsPage`, `PromoCodesPage` and `PlatformEmailPage` still
+call `q.dialog()` directly, so replacing the port does not change what they show.
+Moving them onto it belongs to the page migration.
+
+```ts
+createSuperAdminApp({
+    // ...
+    confirm: (request) => myModals.ask(request),
+});
+```
+
+A request may ask for a value as well as a yes — an audit reason before a
+password reset, the date a pilot is extended to — so the port resolves
+`{ ok, value? }` rather than a bare boolean. An implementation must actually
+ask: one that resolves `{ ok: true }` outright turns every guarded action into
+an unguarded one.
+
+Dialogs that collect a form, and the one that displays a generated one-time
+password, are not confirmations and stay as they are.
 
 ## Usage
 

package/dist/{catalog-DJcfm5N2.d.cts → catalog-Dch1Ryw0.d.cts}

@@ -1,4 +1,5 @@
-import { StandardPageKey, AdminManifest, TenantActionDef } from '@saasicat/types';
+import * as _saasicat_types from '@saasicat/types';
+import { AuditQuery, AuditEntry, TenantListFilter, TenantDto, PlanVersionRow, CreatePlanVersionDraftData, PlanVersionMutationResult, UpdatePlanVersionDraftData, PlanRow, CreatePlanData, UpdatePlanData, StandardPageKey, AdminManifest, TenantActionDef } from '@saasicat/types';
 
 /**
  * Minimal abstraction over `fetch`. Consumers may pass their own
@@ -33,11 +34,280 @@ interface KvStore {
  */
 declare function defaultKvStore(): KvStore;
 /**
- * Default `HttpClient` over `fetch`. Consumers pass their own variant
- * through when they need auth headers / tenant headers / retry logic.
+ * Default `HttpClient` over `fetch`, with no base URL and no headers of its
+ * own. Consumers pass their own variant when they need auth headers, tenant
+ * headers or retry logic — `createFetchHttpClient({ headers })` and
+ * `createAxiosHttpClient(instance)` are the two the package ships.
+ *
+ * It delegates rather than calling `fetch` itself so that there is one
+ * implementation to reason about instead of two that drift.
  */
 declare function defaultHttpClient(): HttpClient;
 
+/**
+ * What an operation needs to know about the app it runs in, beyond its own
+ * arguments.
+ *
+ * Today each composable takes these as its own options and each consumer
+ * passes them again per page. They are app-wide constants — which is why they
+ * belong in one context rather than in every signature.
+ */
+interface ResourceContext {
+    /** Admin API root, e.g. `/api/v1/admin`. No trailing slash. */
+    readonly apiBase: string;
+    /** The project whose catalogue is being administered. */
+    readonly projectKey: string;
+    /** Active UI locale, for the operations whose payload is per-language. */
+    readonly locale: string;
+}
+/** One operation: everything it needs, in the order it needs it. */
+type ResourceOp<A extends unknown[], R> = (http: HttpClient, ctx: ResourceContext, ...args: A) => Promise<R>;
+/** The operations of one resource, keyed by name. */
+type ResourceOps = Record<string, ResourceOp<never[], unknown>>;
+interface ResourceDef<TOps extends ResourceOps> {
+    /** Name this resource is registered and overridden under. */
+    readonly key: string;
+    readonly ops: TOps;
+    /**
+     * Whether these operations read `ctx.projectKey`.
+     *
+     * Declared per descriptor rather than known centrally, because it is not a
+     * property of the registry: one of the four platform resources is
+     * project-scoped and three are not, and the tenant list would be refused
+     * for a project it never asks about. `bindResource` refuses to bind a
+     * descriptor that declares this against a context that names no project.
+     *
+     * `resources-declare-their-project-scope.test.js` drives every operation
+     * and fails when a declaration and what the operations actually read
+     * disagree — in either direction.
+     */
+    readonly projectScoped: boolean;
+}
+/** What a descriptor declares beyond its name and its operations. */
+interface DefineResourceOptions {
+    /** See `ResourceDef.projectScoped`. Default `false`. */
+    projectScoped?: boolean;
+}
+/**
+ * The same operations with `(http, ctx)` already supplied — the form a page or
+ * a composable calls.
+ */
+type Bound<TOps extends ResourceOps> = {
+    [K in keyof TOps]: TOps[K] extends ResourceOp<infer A, infer R> ? (...args: A) => Promise<R> : never;
+};
+/**
+ * Declares a resource.
+ *
+ * Deliberately thin — it exists to name the set and to fix the type, not to
+ * add behaviour. Anything it did at definition time would be a thing an
+ * override could not replace.
+ */
+declare function defineResource<const TOps extends ResourceOps>(key: string, ops: TOps, options?: DefineResourceOptions): ResourceDef<TOps>;
+/**
+ * Supplies `(http, ctx)` once and hands back the callable operations.
+ *
+ * The context is read at call time rather than captured per operation, so a
+ * context that changes — a locale the operator switches, a project the shell
+ * re-scopes — is picked up by calls made afterwards without rebinding.
+ */
+declare function bindResource<TOps extends ResourceOps>(def: ResourceDef<TOps>, http: HttpClient, ctx: ResourceContext | (() => ResourceContext)): Bound<TOps>;
+
+/** 1-based: the page a list starts on, and the one a changed filter returns to. */
+declare const LIST_FIRST_PAGE = 1;
+/**
+ * What the admin API falls back to when `pageSize` is absent. Sent explicitly
+ * rather than relied on, so the URL states what it asked for.
+ */
+declare const LIST_PAGE_SIZE_DEFAULT = 50;
+/**
+ * The largest page the admin API serves. There is no "all" to pass on, which is
+ * why `SERVER_PAGE_SIZE_OPTIONS` leaves Quasar's `ALL_ROWS` out as well.
+ */
+declare const LIST_PAGE_SIZE_MAX = 200;
+/** The two parameters the pagination owns; a filter may not carry them. */
+declare const LIST_PAGINATION_PARAMS: readonly ["page", "pageSize"];
+/**
+ * A filter without the two keys the pagination owns.
+ *
+ * The platform's filter types (`TenantListFilter`, `AuditQuery`) declare
+ * `page` and `pageSize` because they were once passed as one object. Serialised
+ * after the pagination they silently overwrite it — `goToPage(3)` moves the ref
+ * while the request asks for page 7 — so a descriptor takes the filter without
+ * them and the page number travels in its own field.
+ */
+type ListFilterOf<TFilter> = Omit<TFilter, 'page' | 'pageSize'>;
+/** Everything one list request varies: which page, how big, filtered by what. */
+interface ListQuery<TFilter extends object = Record<string, unknown>> {
+    /** 1-based. Defaults to `LIST_FIRST_PAGE`. */
+    page?: number;
+    /** Defaults to `LIST_PAGE_SIZE_DEFAULT`. */
+    pageSize?: number;
+    /** Serialised as `?key=value`; see `isSentInQuery` for what is left out. */
+    filter?: TFilter;
+}
+/**
+ * One page of a list, as the admin API answers it.
+ *
+ * `total` is optional because it is genuinely absent from some answers: a
+ * controller returning a bare array has reported the rows it sent and nothing
+ * about the rest, and an envelope may omit the field altogether. A number
+ * invented here would read as "rows matching the filter" under a paginator that
+ * then offers pages nobody can reach.
+ */
+interface ResourceListPage<T> {
+    items: T[];
+    /** Rows matching the filter — only when the server said so. */
+    total?: number;
+    /** What the server echoed back about the page it served, when it echoed anything. */
+    page?: number;
+    pageSize?: number;
+}
+/** A list operation: the query in, one page out. */
+type ListOp<TRow, TFilter extends object = Record<string, unknown>> = ResourceOp<[
+    query?: ListQuery<TFilter>
+], ResourceListPage<TRow>>;
+/**
+ * Whether a filter value reaches the query string at all.
+ *
+ * `undefined`, `null` and `''` are the three spellings of "not filtered" that
+ * a form produces, and sending them would filter on the literal text `null`.
+ * Everything else goes as `String(value)` — including `0` and `false`, which
+ * are answers, not absences.
+ */
+declare function isSentInQuery(value: unknown): boolean;
+/**
+ * `?a=b` for a filter on its own, or `''` when nothing survives — the form the
+ * admin endpoints that do not page take their filter in.
+ */
+declare function filterQueryString(filter: object): string;
+/**
+ * The URL one page of a list is requested from.
+ *
+ * `page` and `pageSize` are always present and always first — an endpoint that
+ * ignores them is free to, but the request says which page it meant. The filter
+ * follows in its own insertion order, and the endpoint may already carry a
+ * query of its own.
+ */
+declare function listUrl<TFilter extends object>(endpoint: string, query?: ListQuery<TFilter>): string;
+/**
+ * Reads whatever a list endpoint answered into one page.
+ *
+ * Both shapes are real: some controllers return a bare array, others the
+ * `{ items, page, pageSize, total }` envelope. Accepting only the envelope is
+ * what once rendered three tenants as an empty table (see
+ * `use-api-list-shape.test.js`). What the answer did not state stays absent
+ * rather than being filled in — the caller decides what "no total" means for
+ * its paginator.
+ */
+declare function readListPage<T>(raw: unknown): ResourceListPage<T>;
+/** Keeps a requested page on the 1-based scale the API counts on. */
+declare function clampListPage(page: number): number;
+/** Keeps a requested page size inside the 1..`LIST_PAGE_SIZE_MAX` the API serves. */
+declare function clampListPageSize(size: number): number;
+/**
+ * A list operation over one endpoint: the second of a pair, and the reason it
+ * is a function rather than two hand-written descriptors.
+ *
+ * The endpoint is a function of the context so a `context` override on the
+ * registry — an app pointing one resource at a legacy base — reaches it without
+ * the descriptor knowing.
+ */
+declare function defineListOp<TRow, TFilter extends object = Record<string, unknown>>(endpoint: (ctx: ResourceContext) => string): ListOp<TRow, TFilter>;
+
+/** What the audit list can be narrowed by. The page number is not a filter. */
+type AuditListFilter = ListFilterOf<AuditQuery>;
+declare const auditResource: ResourceDef<{
+    readonly list: ListOp<AuditEntry, AuditListFilter>;
+}>;
+
+/** What the tenants list can be narrowed by. The page number is not a filter. */
+type TenantsListFilter = ListFilterOf<TenantListFilter>;
+declare const tenantsResource: ResourceDef<{
+    readonly list: ListOp<TenantDto, TenantsListFilter>;
+}>;
+
+/** What `publish` may override at the moment a version goes live. */
+interface PublishPlanVersionOptions {
+    forceRegressive?: boolean;
+    allowZeroPrice?: boolean;
+    validFrom?: string | null;
+    validUntil?: string | null;
+}
+/**
+ * The plan catalogue — the one platform resource that is read per project.
+ *
+ * `list`, `tenantCounts` and `create` all carry `ctx.projectKey`, so binding
+ * this against a context that names no project is refused rather than sent (see
+ * `bindResource`). Its three siblings address a plan or a version by id and are
+ * not declared here.
+ */
+declare const plansResource: ResourceDef<{
+    readonly list: (http: HttpClient, ctx: ResourceContext) => Promise<PlanRow[]>;
+    readonly tenantCounts: (http: HttpClient, ctx: ResourceContext) => Promise<Record<string, number>>;
+    /**
+     * The project comes from the context, not from the caller.
+     *
+     * The endpoint takes it in the body, and the composable this replaces
+     * made that the caller's job — so a page had to keep hold of the
+     * project it was administering just to create in it, and `list()` and
+     * `create()` read two different sources for one value. A stale one
+     * creates a plan outside the project the list is showing.
+     */
+    readonly create: (http: HttpClient, ctx: ResourceContext, data: Omit<CreatePlanData, "projectKey">) => Promise<PlanRow>;
+    readonly update: (http: HttpClient, ctx: ResourceContext, planId: string, data: UpdatePlanData) => Promise<PlanRow>;
+    /** Marks the plan deleted. Fails while it still has versions. */
+    readonly softDelete: (http: HttpClient, ctx: ResourceContext, planId: string) => Promise<void>;
+    /** Removes the plan for good. 422 `PLAN_HAS_VERSIONS` when it cannot. */
+    readonly hardDelete: (http: HttpClient, ctx: ResourceContext, planId: string) => Promise<void>;
+}>;
+declare const planVersionsResource: ResourceDef<{
+    readonly listForPlan: (http: HttpClient, ctx: ResourceContext, planId: string) => Promise<PlanVersionRow[]>;
+    readonly createDraft: (http: HttpClient, ctx: ResourceContext, planId: string, data: Omit<CreatePlanVersionDraftData, "planId">) => Promise<PlanVersionMutationResult>;
+    readonly updateDraft: (http: HttpClient, ctx: ResourceContext, versionId: string, data: UpdatePlanVersionDraftData) => Promise<PlanVersionMutationResult>;
+    readonly publish: (http: HttpClient, ctx: ResourceContext, versionId: string, options?: PublishPlanVersionOptions) => Promise<PlanVersionMutationResult>;
+    readonly discardDraft: (http: HttpClient, ctx: ResourceContext, versionId: string) => Promise<void>;
+    /**
+     * Ends a live version on `endsAt`, with no successor. Idempotent — a
+     * second call with another date overwrites the first.
+     *
+     * `endsAt` is the date itself, not a payload: the endpoint's body is
+     * `{ endsAt }` and wrapping it is this operation's job, not the caller's.
+     */
+    readonly terminate: (http: HttpClient, ctx: ResourceContext, versionId: string, endsAt: string) => Promise<PlanVersionRow>;
+}>;
+
+/**
+ * Every resource the shell offers by default.
+ *
+ * The registry binds these; an app overrides by key. Partial while the roster
+ * grows — a page whose resource is not here yet keeps its props.
+ */
+declare const platformResources: {
+    plans: ResourceDef<{
+        readonly list: (http: HttpClient, ctx: ResourceContext) => Promise<_saasicat_types.PlanRow[]>;
+        readonly tenantCounts: (http: HttpClient, ctx: ResourceContext) => Promise<Record<string, number>>;
+        readonly create: (http: HttpClient, ctx: ResourceContext, data: Omit<_saasicat_types.CreatePlanData, "projectKey">) => Promise<_saasicat_types.PlanRow>;
+        readonly update: (http: HttpClient, ctx: ResourceContext, planId: string, data: _saasicat_types.UpdatePlanData) => Promise<_saasicat_types.PlanRow>;
+        readonly softDelete: (http: HttpClient, ctx: ResourceContext, planId: string) => Promise<void>;
+        readonly hardDelete: (http: HttpClient, ctx: ResourceContext, planId: string) => Promise<void>;
+    }>;
+    planVersions: ResourceDef<{
+        readonly listForPlan: (http: HttpClient, ctx: ResourceContext, planId: string) => Promise<_saasicat_types.PlanVersionRow[]>;
+        readonly createDraft: (http: HttpClient, ctx: ResourceContext, planId: string, data: Omit<_saasicat_types.CreatePlanVersionDraftData, "planId">) => Promise<_saasicat_types.PlanVersionMutationResult>;
+        readonly updateDraft: (http: HttpClient, ctx: ResourceContext, versionId: string, data: _saasicat_types.UpdatePlanVersionDraftData) => Promise<_saasicat_types.PlanVersionMutationResult>;
+        readonly publish: (http: HttpClient, ctx: ResourceContext, versionId: string, options?: PublishPlanVersionOptions) => Promise<_saasicat_types.PlanVersionMutationResult>;
+        readonly discardDraft: (http: HttpClient, ctx: ResourceContext, versionId: string) => Promise<void>;
+        readonly terminate: (http: HttpClient, ctx: ResourceContext, versionId: string, endsAt: string) => Promise<_saasicat_types.PlanVersionRow>;
+    }>;
+    tenants: ResourceDef<{
+        readonly list: ListOp<_saasicat_types.TenantDto, TenantsListFilter>;
+    }>;
+    audit: ResourceDef<{
+        readonly list: ListOp<_saasicat_types.AuditEntry, AuditListFilter>;
+    }>;
+};
+type PlatformResources = typeof platformResources;
+
 /** Locales the platform itself ships a catalog for. */
 type SaBuiltinLocale = 'de' | 'en';
 /**
@@ -60,64 +330,6 @@ declare const SA_LOCALE_LABELS: Record<SaBuiltinLocale, string>;
 /** Narrows untrusted input to a locale the platform ships a catalog for. */
 declare function isSaBuiltinLocale(value: unknown): value is SaBuiltinLocale;
 
-type SaNavMessages = {
-    readonly pages: Record<StandardPageKey, string>;
-    readonly sections: {
-        readonly overview: string;
-        readonly catalog: string;
-        readonly customers: string;
-        readonly system: string;
-    };
-};
-declare const navMessages: Record<SaBuiltinLocale, SaNavMessages>;
-
-/** Consumer implementation; receives the action inputs as a generic object. */
-type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
-interface ResolvedAction<TInput = unknown, TResult = unknown> {
-    def: TenantActionDef;
-    handler: ActionHandler<TInput, TResult>;
-}
-declare class MissingHandlerError extends Error {
-    constructor(actionKey: string);
-}
-declare class ActionDefNotInManifestError extends Error {
-    constructor(actionKey: string);
-}
-declare class ActionRegistry {
-    private readonly defs;
-    private readonly handlers;
-    constructor(manifest: AdminManifest, handlers?: Record<string, ActionHandler>);
-    /**
-     * Registers a handler after the fact (e.g. when consumer code loads
-     * lazily). Throws `ActionDefNotInManifestError` if the `actionKey` is not
-     * declared in the manifest — prevents dead registrations.
-     */
-    register<TInput, TResult>(actionKey: string, handler: ActionHandler<TInput, TResult>): void;
-    /**
-     * Returns the `{def, handler}` pair. Throws if the key is missing from
-     * the manifest or no handler is registered. The shell's UI layer calls
-     * the method, checks `def.requiresMfa` / `def.confirmType` for the
-     * pre-flow, and then calls `handler(input)`.
-     */
-    get<TInput = unknown, TResult = unknown>(actionKey: string): ResolvedAction<TInput, TResult>;
-    /**
-     * Convenience: `get(key).handler(input)`. UI convenience for actions
-     * that need neither MFA nor confirm.
-     */
-    dispatch<TInput, TResult>(actionKey: string, input: TInput): Promise<TResult>;
-    /**
-     * List of actionKeys that are declared in the manifest but have no
-     * handler. Consumers use this in a doctor check to detect drift between
-     * the manifest and the shell build.
-     */
-    listOrphanedDefs(): string[];
-    /**
-     * List of registered handlers that are missing from the manifest. Drift
-     * in the other direction.
-     */
-    listOrphanedHandlers(): string[];
-}
-
 /** Nested string map — the shape of every message namespace. */
 interface MessageTree {
     readonly [key: string]: string | MessageTree;
@@ -478,9 +690,6 @@ declare const discoveryMessages: Record<SaBuiltinLocale, {
     replacedBy: string;
     replaces: string;
     reapproveEmphasis: string;
-    errorDiscoveryHttp: string;
-    errorRescanHttp: string;
-    errorCatalogHttp: string;
     capList: {
         orphanFeature: string;
         removedFromCode: string;
@@ -622,6 +831,20 @@ declare const emailMessages: Record<SaBuiltinLocale, {
     };
 }>;
 
+declare const errorsMessages: Record<SaBuiltinLocale, {
+    network: string;
+    emptyResponse: string;
+    unauthorized: string;
+    forbidden: string;
+    notFound: string;
+    conflict: string;
+    validation: string;
+    rateLimited: string;
+    server: string;
+    httpStatus: string;
+    unexpected: string;
+}>;
+
 declare const marketingMessages: Record<SaBuiltinLocale, {
     topFeatures: string;
     tabs: {
@@ -745,11 +968,19 @@ declare const marketingMessages: Record<SaBuiltinLocale, {
         delete: string;
         deleteConfirm: string;
     };
-    errors: {
-        projectionsApi: string;
-    };
 }>;
 
+type SaNavMessages = {
+    readonly pages: Record<StandardPageKey, string>;
+    readonly sections: {
+        readonly overview: string;
+        readonly catalog: string;
+        readonly customers: string;
+        readonly system: string;
+    };
+};
+declare const navMessages: Record<SaBuiltinLocale, SaNavMessages>;
+
 declare const pilotsMessages: Record<SaBuiltinLocale, {
     title: string;
     subtitleCount: string;
@@ -1334,7 +1565,6 @@ declare const plansMessages: Record<SaBuiltinLocale, {
 declare const promosMessages: Record<SaBuiltinLocale, {
     title: string;
     createAction: string;
-    apiErrorHttpStatus: string;
     list: {
         searchLabel: string;
         tileScheduled: string;
@@ -1440,6 +1670,12 @@ declare const shellMessages: Record<SaBuiltinLocale, {
         roleBadge: string;
         logout: string;
         language: string;
+        theme: {
+            label: string;
+            light: string;
+            dark: string;
+            system: string;
+        };
     };
     drawer: {
         docs: string;
@@ -1589,6 +1825,7 @@ declare const usersMessages: Record<SaBuiltinLocale, {
 /** Complete platform catalog for one locale, keyed by namespace. */
 type SaMessages = {
     readonly common: (typeof commonMessages)['de'];
+    readonly errors: (typeof errorsMessages)['de'];
     readonly nav: (typeof navMessages)['de'];
     readonly shell: (typeof shellMessages)['de'];
     readonly dashboard: (typeof dashboardMessages)['de'];
@@ -1616,6 +1853,53 @@ declare const SA_MESSAGES: Record<SaBuiltinLocale, SaMessages>;
  */
 declare function resolveMessages(locale: SaBuiltinLocale, overrides?: SaMessagesOverrides): SaMessages;
 
+/** Consumer implementation; receives the action inputs as a generic object. */
+type ActionHandler<TInput = unknown, TResult = unknown> = (input: TInput) => Promise<TResult>;
+interface ResolvedAction<TInput = unknown, TResult = unknown> {
+    def: TenantActionDef;
+    handler: ActionHandler<TInput, TResult>;
+}
+declare class MissingHandlerError extends Error {
+    constructor(actionKey: string);
+}
+declare class ActionDefNotInManifestError extends Error {
+    constructor(actionKey: string);
+}
+declare class ActionRegistry {
+    private readonly defs;
+    private readonly handlers;
+    constructor(manifest: AdminManifest, handlers?: Record<string, ActionHandler>);
+    /**
+     * Registers a handler after the fact (e.g. when consumer code loads
+     * lazily). Throws `ActionDefNotInManifestError` if the `actionKey` is not
+     * declared in the manifest — prevents dead registrations.
+     */
+    register<TInput, TResult>(actionKey: string, handler: ActionHandler<TInput, TResult>): void;
+    /**
+     * Returns the `{def, handler}` pair. Throws if the key is missing from
+     * the manifest or no handler is registered. The shell's UI layer calls
+     * the method, checks `def.requiresMfa` / `def.confirmType` for the
+     * pre-flow, and then calls `handler(input)`.
+     */
+    get<TInput = unknown, TResult = unknown>(actionKey: string): ResolvedAction<TInput, TResult>;
+    /**
+     * Convenience: `get(key).handler(input)`. UI convenience for actions
+     * that need neither MFA nor confirm.
+     */
+    dispatch<TInput, TResult>(actionKey: string, input: TInput): Promise<TResult>;
+    /**
+     * List of actionKeys that are declared in the manifest but have no
+     * handler. Consumers use this in a doctor check to detect drift between
+     * the manifest and the shell build.
+     */
+    listOrphanedDefs(): string[];
+    /**
+     * List of registered handlers that are missing from the manifest. Drift
+     * in the other direction.
+     */
+    listOrphanedHandlers(): string[];
+}
+
 /** A language an app brings along, on top of the two the platform ships. */
 interface SaLocaleDefinition {
     /**
@@ -1672,4 +1956,4 @@ interface SaCatalog {
  */
 declare function createSaCatalog(options?: SaCatalogOptions): SaCatalog;
 
-export { type ActionHandler as A, DEFAULT_SA_LOCALE as D, type HttpClient as H, type KvStore as K, type MessageTree as M, type PartialMessages as P, type ResolvedAction as R, type SaLocale as S, type TranslationOf as T, type SaMessages as a, type SaLocaleOption as b, type SaLocaleDefinition as c, type SaMessagesOverrides as d, ActionRegistry as e, ActionDefNotInManifestError as f, type HttpResponse as g, MissingHandlerError as h, SA_INTL_LOCALES as i, SA_LOCALES as j, SA_LOCALE_LABELS as k, SA_MESSAGES as l, type SaBuiltinLocale as m, type SaCatalog as n, type SaCatalogOptions as o, createSaCatalog as p, defaultHttpClient as q, defaultKvStore as r, defineMessages as s, isSaBuiltinLocale as t, mergeMessages as u, resolveMessages as v, type SaNavMessages as w };
+export { filterQueryString as $, type ActionHandler as A, type Bound as B, SA_LOCALE_LABELS as C, DEFAULT_SA_LOCALE as D, SA_MESSAGES as E, type SaBuiltinLocale as F, type SaCatalog as G, type HttpClient as H, type SaCatalogOptions as I, type TranslationOf as J, type KvStore as K, LIST_FIRST_PAGE as L, type MessageTree as M, auditResource as N, bindResource as O, type PlatformResources as P, clampListPage as Q, type ResourceDef as R, type SaLocale as S, type TenantsListFilter as T, clampListPageSize as U, createSaCatalog as V, defaultHttpClient as W, defaultKvStore as X, defineListOp as Y, defineMessages as Z, defineResource as _, type SaMessages as a, isSaBuiltinLocale as a0, isSentInQuery as a1, listUrl as a2, mergeMessages as a3, planVersionsResource as a4, plansResource as a5, readListPage as a6, resolveMessages as a7, tenantsResource as a8, type SaNavMessages as a9, type SaLocaleOption as b, type SaLocaleDefinition as c, type SaMessagesOverrides as d, type ResourceOps as e, type ResourceContext as f, type ResourceListPage as g, ActionRegistry as h, ActionDefNotInManifestError as i, type AuditListFilter as j, type DefineResourceOptions as k, type HttpResponse as l, LIST_PAGE_SIZE_DEFAULT as m, LIST_PAGE_SIZE_MAX as n, LIST_PAGINATION_PARAMS as o, platformResources as p, type ListFilterOf as q, type ListOp as r, type ListQuery as s, MissingHandlerError as t, type PartialMessages as u, type PublishPlanVersionOptions as v, type ResolvedAction as w, type ResourceOp as x, SA_INTL_LOCALES as y, SA_LOCALES as z };