@endora-commerce/contracts 0.100.0

package/dist/admin-contributions.js

@@ -0,0 +1,495 @@
+/**
+ * What a module package's `./admin` layer declares (feature 091, Principle II).
+ *
+ * These are **declarations, not components**, and the distinction is the whole
+ * design. Three consumers need a contribution to be enumerable without being
+ * executed: the registry generator, which writes an artefact naming every
+ * contribution and must not import a React tree to do it; the bundler, which
+ * has to see a `() => import('…')` factory as a split point and cannot follow a
+ * computed specifier; and the gating predicate, which decides visibility from
+ * `{ module, requiredPermission }` before anything renders. So a contribution
+ * is a plain object whose only function-valued field is a dynamic-import
+ * factory — the shape a `manifest.ts`'s `actions` array already has one layer
+ * up, and the reason the ⌘K palette is the one admin extension mechanism that
+ * needs no host edit today.
+ *
+ * They live here rather than in a types-only package because they cross a
+ * package boundary and Principle II puts a shape that does in
+ * `packages/contracts/`, beside `ModuleManifest` and `ModuleActionSchema`.
+ *
+ * **The component factory is a TypeScript type and not a Zod schema, and the
+ * split is deliberate.** Everything a generator, a check or a server can
+ * validate is a schema below; the factory is `unknown` to Zod because a
+ * function value carries nothing to validate beyond its arity, and pretending
+ * otherwise would put a `z.function()` in a package `admin` and `storefront`
+ * both compile while telling a reader it was checked. The data half is
+ * `AdminRouteDeclarationSchema`; the whole declaration, factory included, is
+ * the `AdminRouteDeclaration` interface.
+ */
+import { z } from 'zod';
+import { KnownIconNameSchema } from './admin-actions.js';
+// ---------------------------------------------------------------------------
+// Field-level patterns
+// ---------------------------------------------------------------------------
+/**
+ * An admin route path, as `react-router` reads it.
+ *
+ * The manifest action's `targetRoute` pattern plus `:` — a palette entry points
+ * at a landing screen and may not carry a parameter, while a route table is
+ * mostly parametric (`/orders/:id`). No query string, in both.
+ */
+const adminRoutePathRe = /^\/[A-Za-z0-9/_:-]*$/;
+/**
+ * A module-relative translation key: `nav.crm.label`, never
+ * `crm.nav.crm.label`.
+ *
+ * The same rule a palette action's `labelKey` follows, and the same silent
+ * failure if it is broken: the module's bundle is a flat
+ * `{"a.b.c": "text"}` map, a nested object fails
+ * `TranslationBundleEntriesSchema`, the boot reconciler logs and skips it, and
+ * the entry renders its raw key.
+ */
+const translationKeyRe = /^[a-z][a-zA-Z0-9_]*(\.[a-z][a-zA-Z0-9_]*)*$/;
+// ---------------------------------------------------------------------------
+// Permission requirement
+// ---------------------------------------------------------------------------
+/**
+ * A permission code, or a set of codes any one of which suffices.
+ *
+ * The array form exists because the routes have it: `requireAdminAny([…])` is
+ * satisfied by either member, and naming only the first in the UI hides the
+ * screen from a role that holds the second. It is the shape
+ * `admin/src/lib/surface-visibility.ts` already defines, published here so a
+ * module package declares it without reaching into the admin for the type.
+ */
+export const PermissionRequirementSchema = z.union([
+    z.string().min(1).max(128),
+    z.array(z.string().min(1).max(128)).min(1),
+]);
+// ---------------------------------------------------------------------------
+// Nav sections
+// ---------------------------------------------------------------------------
+/**
+ * The sidebar sections a module may join — closed, and derived from the ones
+ * `admin/src/components/AppShell.tsx` already declares.
+ *
+ * A module may not invent a section, for D-23's reason: an invented section is
+ * a heading nobody else can join, so two modules that belong together end up in
+ * two headings of one each and the operator reads it as two features.
+ */
+export const AdminNavSectionNameSchema = z.enum([
+    'main',
+    'sales',
+    'catalog',
+    'inventory',
+    'pricing',
+    'customers',
+    'channels',
+    'content',
+    'messaging',
+    'newsletter',
+    'analyticsAds',
+    'system',
+]);
+// ---------------------------------------------------------------------------
+// Zones
+// ---------------------------------------------------------------------------
+/**
+ * The places in a screen one module owns where another module's contribution
+ * may appear — closed, hierarchical, dot-separated, and the platform's.
+ *
+ * **A member exists when a host renders it, and not before.** The four members
+ * this enum opened with were derived from the places module additions had
+ * reached into by editing another module's file, which was the right derivation
+ * and produced a set nothing rendered and nothing contributed to — four names
+ * that had been silent since the enum landed. `check:admin-zones` reports every
+ * one of those as `unrendered-zone`, and it carries **no ledger**, deliberately:
+ * the remedy is always available in the same merge request, and it is either to
+ * render the place or to remove the name. So the set grows with the batch that
+ * mounts it, one member per place a host screen actually renders.
+ *
+ * `payment_method.row.actions` is the member that shows why. Measured, nothing
+ * under the payment-methods admin surface names a gateway id at all — the five
+ * gateways were given their own routes and settings screens — so there was
+ * nothing waiting to contribute and inventing a host for it would have been
+ * inventing a host.
+ *
+ * **Closed and unparameterised, and that is load-bearing.** A parameter in the
+ * name (`product.editor.field:<fieldPath>`, or a `z.templateLiteral`) was
+ * rejected: the refusal below compares declared names to rendered ones, and a
+ * name computed from a field path compares to nothing. The parameter is a prop
+ * — see {@link AdminZonePropsMap} — and one member may be mounted many times on
+ * one screen, each mount carrying its own.
+ *
+ * Both directions refuse: a contribution to a zone nobody declares is a build
+ * refusal, and a zone the platform declares that no host screen renders is one
+ * too. A contribution that silently renders nowhere is worse than one that
+ * fails.
+ */
+export const AdminZoneNameSchema = z.enum([
+    /**
+     * Above the product editor's Details tab, before the platform's own fields.
+     *
+     * Mounted **once** per editor. Props: {@link ProductEditorZoneProps}.
+     */
+    'product.editor.details.before',
+    /**
+     * Above the product editor's Pricing tab.
+     *
+     * Mounted **once** per editor. Props: {@link ProductEditorZoneProps}.
+     */
+    'product.editor.pricing.before',
+    /**
+     * Beside one editable field of the product editor.
+     *
+     * Mounted **once per field** — `name`, `description`, `categories`,
+     * `gallery`, `attachments`, and once per attribute row — each mount carrying
+     * that field's own {@link ProductEditorFieldZoneProps}. One member, twelve
+     * mount points, and a contributor that renders on all of them declares one
+     * contribution: the fan-out is the mount's, not the name's.
+     */
+    'product.editor.field.after',
+    /**
+     * The integrations card on the delivery-methods list — one entry per shipping
+     * integration a module supplies, each linking to that module's own
+     * configuration screen.
+     *
+     * Mounted **once** per list screen and carrying no props, so its entry in
+     * {@link AdminZonePropsMap} is the empty object. That is not a placeholder
+     * for a parameter nobody has thought of yet: the host has no identifier to
+     * pass — the contributions *are* the integrations, and a contributor renders
+     * a card describing itself.
+     *
+     * It is the first member whose host is not `catalog`'s product editor, and
+     * the first whose contributors are the modules that used to be **named** by
+     * the host: `delivery_methods` hard-coded a `dhl_parcel` block and an
+     * `inpost` block, each with the other module's title, description, route and
+     * permission code, which
+     * `backend/scripts/ledgers/foreign-module-ids.ts` recorded as two
+     * `visibility-gate` couplings with this conversion as their retiring
+     * condition. Props: {@link DeliveryMethodIntegrationsZoneProps}.
+     */
+    'delivery_method.list.integrations',
+    /**
+     * The integrations card on the payment-methods list — one entry per online
+     * payment adapter a module supplies, each linking to that module's own
+     * configuration screen.
+     *
+     * Mounted once per list screen and carrying no props. The free host owns the
+     * place and its heading; separately shipped gateway modules own the cards.
+     * Props: {@link PaymentMethodIntegrationsZoneProps}.
+     */
+    'payment_method.list.integrations',
+    /**
+     * Below the invoice detail's totals column, at the end of the right-hand
+     * stack.
+     *
+     * Mounted **once** per invoice detail screen. Props:
+     * {@link InvoiceDetailZoneProps}.
+     *
+     * The first member whose host is `invoices` and whose contributor is `ksef`.
+     * `invoices`' invoice detail imported `ksef`'s `InvoiceKsefPanel` by path —
+     * the single key in
+     * `backend/scripts/ledgers/cross-module-imports/invoices.ts`, whose recorded
+     * retiring condition is this member existing. Z1 question 1 is answered from
+     * the panel's own signature: `(invoiceId, kind, ksefReferenceNumber)` — three
+     * values in, nothing out, no `onChange` — so it is question 2's case, an
+     * addition the owner makes because the owner is installed.
+     *
+     * **Per-host and not a shared `invoice.detail.after` twin of some general
+     * member** (§10 Z13): a member shared by two hosts lets one host's mount
+     * cover the other host's absence, which is the failure `unrendered-zone`
+     * exists to refuse.
+     */
+    'invoice.detail.after',
+    /**
+     * The end of the category editor's form, after its save/cancel row.
+     *
+     * Mounted **once** per open category, and named from the host's own word for
+     * the place (Z14): `catalog`'s `CategoriesTree.tsx` is the editor, and the
+     * place is *after* everything the editor itself offers. Props:
+     * {@link CategoryEditorZoneProps}.
+     *
+     * The first member whose contributor is `price_lists`. `catalog` imported
+     * `DisplayModeOverrideRow` by path and handed it its own label and its own
+     * hint — one of the three admin keys in
+     * `backend/scripts/ledgers/cross-module-imports/catalog.ts`. A host cannot
+     * hand copy to a contributor it does not know, so the two `catalog` strings
+     * go with the import and the control renders `price_lists`' own.
+     */
+    'category.editor.after',
+    /**
+     * The end of the product editor's Pricing tab.
+     *
+     * Mounted **once** per editor, and the twin of
+     * `product.editor.pricing.before`: two places in one editor, one before the
+     * platform's own pricing fields and one after them. Props:
+     * {@link ProductEditorZoneProps}, reused rather than aliased — a props type
+     * is the *shape* the mount carries, and both places carry a product id.
+     */
+    'product.editor.pricing.after',
+    /**
+     * The **body** of the product editor's Channels tab.
+     *
+     * Mounted **once** per editor. Props: {@link ProductEditorZoneProps}.
+     *
+     * The host keeps the tab strip and the label — `channels` is `catalog`'s own
+     * tab id — and stops knowing which module fills it: the button is shown by
+     * `useAdminZone(name, props).length > 0` (Z15), which has already applied
+     * both presence axes and the contributor's permission. A strip zone that
+     * contributed the button too was rejected: one contributor, one host, and the
+     * label is the host's own vocabulary.
+     */
+    'product.editor.channels',
+    /**
+     * Below the sales-channel editor's identity form.
+     *
+     * Mounted **once** per channel, and only for a channel that already exists —
+     * the create form has no id to pass. Props:
+     * {@link SalesChannelEditorZoneProps}.
+     *
+     * The first member whose host is `sales_channels` and whose contributor is
+     * `inventory`. The panel behind it is warehouse↔channel routing, which is a
+     * fact about fulfilment rather than about the channel's identity, and its
+     * four routes take `inventory:read` / `inventory:write`.
+     */
+    'sales_channel.editor.after',
+    /**
+     * The stack of panels an organization's detail screen ends with.
+     *
+     * Mounted **once** per organization, and the "once" is a rule rather than a
+     * layout choice (§10.1): two mounts of this member on one screen, with no
+     * prop to tell them apart, render **every** contribution twice and nothing in
+     * the renderer can distinguish them. Props:
+     * {@link OrganizationDetailZoneProps}.
+     *
+     * The first member with four contributors, and the first whose conversion
+     * makes scattered panels contiguous: `sales_channels`' channel membership,
+     * `price_lists`' display-mode override and `quick_order`'s ordering defaults
+     * sat at three different depths of
+     * `admin/src/modules/organizations/OrganizationDetail.tsx`, each imported by
+     * path — the three keys of
+     * `backend/scripts/ledgers/cross-module-imports/organizations.ts`, whose
+     * shard this member deletes. `carts` joins them with the cart-approval
+     * policy, whose panel this host owned and nothing rendered (§10.5).
+     *
+     * **Per-host and not a shared `entity.detail.after`** (§10 Z13): the
+     * `unrendered-zone` refusal is computed per member, so one host's mount would
+     * cover another host's absence. `customer.detail.after` is the twin, and the
+     * cost of keeping them apart is one four-line wrapper in `quick_order`.
+     */
+    'organization.detail.after',
+    /**
+     * The stack of panels a customer's detail screen ends with.
+     *
+     * Mounted **once** per customer, on `organization.detail.after`'s terms and
+     * for its reasons. Props: {@link CustomerDetailZoneProps}.
+     *
+     * One contributor: `quick_order`'s ordering defaults, which
+     * `admin/src/modules/customers/CustomerDetail.tsx` imported by path — the
+     * single key of `backend/scripts/ledgers/cross-module-imports/customers.ts`,
+     * whose shard this member deletes.
+     */
+    'customer.detail.after',
+    /**
+     * The **body** of the order detail's Payment tab.
+     *
+     * Mounted **once** per order, and named from the host's own word for the
+     * place (Z14): `orders`' `OrderDetail.tsx` calls the tab `payment` and its
+     * label `orderDetail.tabs.payment`. Props: {@link OrderDetailZoneProps}.
+     *
+     * The host keeps the tab strip and the label and stops knowing which module
+     * fills it: the button is shown by `useAdminZone(name, props).length > 0`
+     * (Z15), which has already applied both presence axes and the contributor's
+     * permission. `orders` used to render `payments`' tab itself, gated on
+     * `isVisible({ module: 'payments', requiredPermission: 'payments:read' })` —
+     * the `visibility-gate` key of `backend/scripts/ledgers/foreign-module-ids.ts`
+     * whose recorded retiring condition is this member.
+     */
+    'order.detail.payment',
+    /**
+     * The per-row action cell of the order detail's Delivery tab.
+     *
+     * Mounted **once per shipment attempt**, each mount carrying that attempt's
+     * own {@link OrderShipmentRowZoneProps} — the first member in this enum whose
+     * contributions narrow themselves with `match` rather than by returning
+     * `null`, which is the population Z13 reserves for it: one host, one place,
+     * many mounts.
+     *
+     * `providerCode` and `status` are props **because** they are matched on. A
+     * key the mount's props do not carry never agrees (fail-closed), so a
+     * contribution matching a prop this interface omits renders nowhere and
+     * nothing reports it — which is why the two are declared here and not left
+     * for the contributor to read out of a payload.
+     *
+     * `orders` used to write `inpost`'s knowledge into its own JSX —
+     * `providerDetails?.['provider'] === 'inpost' && status === 'success'`, under
+     * an `isVisible({ module: 'inpost', … })` gate and an `inpost` translation
+     * namespace, which is two of the three `foreign-module-ids` keys this member
+     * retires.
+     */
+    'order.shipment.row.actions',
+    /**
+     * The footer action bar of the order detail's Delivery tab.
+     *
+     * Mounted **once** per tab, below the attempts table and beside the host's
+     * own "generate again" button. Props:
+     * {@link OrderShipmentsActionsZoneProps}.
+     *
+     * Its contributor is the carrier the ledgers could not see: `dhl_parcel` was
+     * named by **delivery-method code** (`'dhl_parcel_courier'`,
+     * `'dhl_parcel_pickup'`) rather than by module id, so
+     * `check:admin-zones`' `foreign-module-id` predicate — which reads module ids
+     * out of strings — never had it in its population and never will. The three
+     * buttons behind those codes carried **no permission gate at all** while the
+     * routes behind them enforce `dhl_parcel:read` and `dhl_parcel:write`; a
+     * contribution declares one code, so the conversion closes that
+     * over-exposure by construction.
+     */
+    'order.shipments.tab.actions',
+    /**
+     * The switch between the two ways of entering an order, above the entry form.
+     *
+     * **A tab strip rather than a stack**, and the only member so far whose
+     * renderer is `<RouteTabsZone>`: the contributions are the tabs, the host
+     * supplies the strip, and *"fewer than two tabs is not a choice"* is the
+     * strip counting what `useAdminZone` already filtered rather than a rule any
+     * module states. Props: {@link OrderEntryTabsZoneProps}, which carries
+     * nothing — the mount has no identifier to pass, exactly as
+     * `delivery_method.list.integrations` has none.
+     *
+     * **Two hosts and one place, which is the one exception Z13 leaves open and
+     * is stated here rather than discovered.** Z13 refuses a member shared by
+     * hosts that each have *a place of their own*, because one host's mount then
+     * covers another's absence. This is not that: the place is a single
+     * navigational switch, and it appears on **both** of the pages it switches
+     * between — `orders`' order-create screen and `quick_order`'s on-behalf
+     * screen — because a switch visible from only one side is not a switch. The
+     * cost is real and is the one Z13 names: deleting the mount from one of the
+     * two screens leaves the member rendered, so `unrendered-zone` would not
+     * report it. What does report it is
+     * `admin/test/modules/orders/order-entry-tabs-zone.test.tsx`, which asserts
+     * both mounts by name.
+     *
+     * The contributors are the two modules the strip used to be filtered *by*:
+     * `admin/src/components/OrderEntryTabs.tsx` held a two-element array naming
+     * `orders` and `quick_order`, each with the other module's route and the
+     * other module's label out of the `core` bundle — the last two keys of
+     * `backend/scripts/ledgers/admin-surface.ts`, which this member empties. Each
+     * module now contributes its own tab, with its own label in its own bundle.
+     */
+    'order.entry.tabs',
+    /**
+     * The switch between invoice-ledger deliveries, routing, and vendor adapter
+     * connection screens.
+     *
+     * **A tab strip**, same renderer as `order.entry.tabs`: `<RouteTabsZone>`.
+     * `invoice_ledger` contributes Deliveries and Routing, and asks a vendor
+     * adapter's connection tab to weigh more than its own two so that it sorts
+     * after the screens it is a vendor of. The sidebar keeps one **Invoice
+     * ledger** row. Props: {@link LedgerSectionTabsZoneProps}.
+     *
+     * **No vendor is named here.** One was until 2026-09-22, and the vendors are
+     * what feature 134's wave 4 takes out of this repository — a free package's
+     * source naming a paid module id is the reach that sweep exists to remove
+     * (and a string literal is the spelling no instrument sees).
+     *
+     * The name is `ledger.section.tabs` and not `invoice_ledger.section.tabs`
+     * so an adapter file that mounts the strip does not spell a sibling module
+     * id (`check:admin-zones` `foreign-module-id`).
+     *
+     * **Many hosts and one place**, the same Z13 exception `order.entry.tabs`
+     * records: the switch must appear on every page it switches between or it
+     * is not a switch. `unrendered-zone` is per zone rather than per host, so
+     * that is asserted **per contributing package**, in each one's own
+     * `src/admin/index.test.ts` over a relative read of its own screens — which
+     * is where it keeps working once the vendors are installed from tarballs
+     * rather than resolved in this workspace (feature 134 W2.2, D-262 clause 3).
+     * The strip's own mechanism is driven in
+     * `admin/test/modules/invoice_ledger/ledger-section-tabs-zone.test.tsx`.
+     */
+    'ledger.section.tabs',
+]);
+// ---------------------------------------------------------------------------
+// Declarations
+// ---------------------------------------------------------------------------
+/**
+ * The data half of a route declaration — everything a generator or a check can
+ * read without evaluating the module's UI code.
+ *
+ * **Owner attribution is not a field.** The module id is the registry entry's
+ * key, so a declaration cannot claim to belong to a module other than the one
+ * that shipped it — the same reason a packaged migration is attributed to
+ * `endora.id` and never to a path segment (D-142). An attribution a module can
+ * write is an attribution a module can get wrong.
+ */
+export const AdminRouteDeclarationSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .max(255)
+        .regex(adminRoutePathRe, 'Admin route must be a leading-slash ASCII path with no query string'),
+    requiredPermission: PermissionRequirementSchema.optional(),
+    /** Marks the module's landing route, so a nav entry can default to it. */
+    index: z.boolean().optional(),
+});
+/**
+ * The data half of a sidebar entry.
+ *
+ * Deliberately the same five fields `NAV` already carries in
+ * `admin/src/components/AppShell.tsx`, so the sidebar renders
+ * `[...hostNav, ...registryNav]` through the one existing predicate with no
+ * second gate. Issue #230's finding — three surfaces answering the visibility
+ * question three ways — does not get a fourth chance.
+ */
+export const AdminNavDeclarationSchema = z.object({
+    to: z
+        .string()
+        .min(1)
+        .max(255)
+        .regex(adminRoutePathRe, 'Admin route must be a leading-slash ASCII path with no query string'),
+    labelKey: z
+        .string()
+        .min(1)
+        .max(255)
+        .regex(translationKeyRe, 'Translation key must be dot-separated camelCase namespaces'),
+    icon: KnownIconNameSchema,
+    section: AdminNavSectionNameSchema,
+    /** Order within the section. Ties are broken by module id, so it is stable. */
+    weight: z.number().int(),
+    requiredPermission: PermissionRequirementSchema.optional(),
+});
+/**
+ * The data half of a contribution into another module's screen.
+ *
+ * A contribution declares **one** zone, so a component appearing in two zones
+ * is two contributions — and only the one that needs narrowing carries a
+ * {@link AdminZoneContributionSchema.shape.match}.
+ */
+export const AdminZoneContributionSchema = z.object({
+    zone: AdminZoneNameSchema,
+    weight: z.number().int(),
+    requiredPermission: PermissionRequirementSchema.optional(),
+    /**
+     * Narrow this contribution to the mounts whose props agree with every key.
+     *
+     * The renderer includes the contribution when, for each key, the zone's props
+     * carry that key with that value — or with a member of that array. Data only,
+     * enumerable, and readable by a check.
+     *
+     * **It exists for FR-013 and not for tidiness.** One zone is mounted on many
+     * screens; without `match` a contributor narrows by returning `null` for the
+     * mounts it does not serve, which means its chunk is fetched and evaluated on
+     * every one of them. `match` is decided **before** `React.lazy` is touched,
+     * so the chunk is never requested. The alternative — a near-identical enum
+     * member per case — is the openness the closed enum exists to refuse, wearing
+     * a different hat.
+     *
+     * A key the zone's props do not carry never agrees, so a `match` naming a
+     * prop that does not exist hides the contribution rather than widening it.
+     */
+    match: z
+        .record(z.string(), z.union([z.string(), z.array(z.string()).readonly()]))
+        .optional(),
+});
+//# sourceMappingURL=admin-contributions.js.map

package/dist/admin-contributions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-contributions.js","sourceRoot":"","sources":["../src/admin-contributions.ts"],"names":[],"mappings":"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"}

package/dist/admin-i18n.d.ts

@@ -0,0 +1,135 @@
+import { z } from 'zod';
+import { type SupportedLanguage } from './platform-language.js';
+/**
+ * @deprecated Use `SupportedLanguageSchema` from `platform-language.ts`. The set
+ * is the platform's, not the Admin UI's — a buyer is answered out of the same
+ * enum (feature 083, D-136). Draining task: `specs/083-buyer-language-resolution`
+ * T021.
+ */
+export declare const SupportedAdminLanguageSchema: z.ZodEnum<{
+    en: "en";
+    pl: "pl";
+}>;
+/**
+ * @deprecated Use `SupportedLanguage` from `platform-language.ts`. Draining
+ * task: `specs/083-buyer-language-resolution` T021.
+ */
+export type SupportedAdminLanguage = SupportedLanguage;
+/**
+ * On-disk bundle JSON shape and the row payload persisted to
+ * `translation_bundles.entries`. Flat string→string only at v1; nested
+ * objects, arrays, and non-string values are rejected.
+ */
+export declare const TranslationBundleEntriesSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type TranslationBundleEntries = z.infer<typeof TranslationBundleEntriesSchema>;
+/** Admin SPA boot fetch — `GET /api/v1/admin/i18n/bundles?language=…` response. */
+export declare const GetBundlesResponseSchema: z.ZodObject<{
+    language: z.ZodEnum<{
+        en: "en";
+        pl: "pl";
+    }>;
+    version: z.ZodNumber;
+    bundles: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type GetBundlesResponse = z.infer<typeof GetBundlesResponseSchema>;
+/** `PATCH /api/v1/admin/me/preferred-language` body. `null` reverts to the platform default. */
+export declare const PatchPreferredLanguageBodySchema: z.ZodObject<{
+    preferredLanguage: z.ZodNullable<z.ZodEnum<{
+        en: "en";
+        pl: "pl";
+    }>>;
+}, z.core.$strip>;
+export type PatchPreferredLanguageBody = z.infer<typeof PatchPreferredLanguageBodySchema>;
+/** Standard 400 envelope when an unsupported language is requested. */
+export declare const UnsupportedLanguageErrorSchema: z.ZodObject<{
+    error: z.ZodLiteral<"unsupported-language">;
+    supported: z.ZodArray<z.ZodEnum<{
+        en: "en";
+        pl: "pl";
+    }>>;
+}, z.core.$strip>;
+export type UnsupportedLanguageError = z.infer<typeof UnsupportedLanguageErrorSchema>;
+export declare const I18nCoverageLanguageSchema: z.ZodObject<{
+    languageCode: z.ZodEnum<{
+        en: "en";
+        pl: "pl";
+    }>;
+    totalKeysSeen: z.ZodNumber;
+    missingCount: z.ZodNumber;
+    missingKeys: z.ZodArray<z.ZodString>;
+    fellBackToEnCount: z.ZodNumber;
+    fellBackToEnKeys: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type I18nCoverageLanguage = z.infer<typeof I18nCoverageLanguageSchema>;
+export declare const I18nCoverageModuleSchema: z.ZodObject<{
+    moduleId: z.ZodString;
+    languages: z.ZodArray<z.ZodObject<{
+        languageCode: z.ZodEnum<{
+            en: "en";
+            pl: "pl";
+        }>;
+        totalKeysSeen: z.ZodNumber;
+        missingCount: z.ZodNumber;
+        missingKeys: z.ZodArray<z.ZodString>;
+        fellBackToEnCount: z.ZodNumber;
+        fellBackToEnKeys: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type I18nCoverageModule = z.infer<typeof I18nCoverageModuleSchema>;
+export declare const I18nCoverageResponseSchema: z.ZodObject<{
+    capturedAt: z.ZodISODateTime;
+    modules: z.ZodArray<z.ZodObject<{
+        moduleId: z.ZodString;
+        languages: z.ZodArray<z.ZodObject<{
+            languageCode: z.ZodEnum<{
+                en: "en";
+                pl: "pl";
+            }>;
+            totalKeysSeen: z.ZodNumber;
+            missingCount: z.ZodNumber;
+            missingKeys: z.ZodArray<z.ZodString>;
+            fellBackToEnCount: z.ZodNumber;
+            fellBackToEnKeys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type I18nCoverageResponse = z.infer<typeof I18nCoverageResponseSchema>;
+export declare const I18nCoverageQuerySchema: z.ZodObject<{
+    module: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    language: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        en: "en";
+        pl: "pl";
+    }>, z.ZodArray<z.ZodEnum<{
+        en: "en";
+        pl: "pl";
+    }>>]>>;
+    includeKeys: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+        missing: "missing";
+        all: "all";
+    }>>>;
+}, z.core.$strip>;
+export type I18nCoverageQuery = z.infer<typeof I18nCoverageQuerySchema>;
+/**
+ * Container name: `adminI18nService`. Owner: `_i18n`.
+ *
+ * The backend-side string resolver: a module id, a key inside that module's
+ * bundle and the operator's language in, the rendered sentence out. The
+ * resolver falls back to English and, failing that, returns `moduleId.key`
+ * verbatim — a caller that wants to detect a missing key compares against that
+ * placeholder rather than against `null`.
+ *
+ * This is the one method the resolver's cross-module callers use. The bundle
+ * install, removal and coverage surfaces of `_i18n`'s service stay inside
+ * `_i18n`: they are the reconciler's business, not a consumer's.
+ *
+ * When `_i18n` is off the port fails closed. That is the right answer for a
+ * caller rendering an operator-facing string: a screen labelled with raw keys
+ * is worse than a screen that says the platform will not answer.
+ *
+ * Whether `_i18n` has an off state at all is its manifest's `activation` to
+ * say, not this line's: a module declaring `nonDeactivatable` never enters one.
+ */
+export interface AdminI18nTranslatePort {
+    translate(moduleId: string, key: string, language: SupportedAdminLanguage, params?: Record<string, string | number>): Promise<string>;
+}
+//# sourceMappingURL=admin-i18n.d.ts.map

package/dist/admin-i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-i18n.d.ts","sourceRoot":"","sources":["../src/admin-i18n.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEzF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B;;;EAA0B,CAAC;AACpE;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AAEvD;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,uCAG1C,CAAC;AACF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,mFAAmF;AACnF,eAAO,MAAM,wBAAwB;;;;;;;iBAMnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,gGAAgG;AAChG,eAAO,MAAM,gCAAgC;;;;;iBAE3C,CAAC;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F,uEAAuE;AACvE,eAAO,MAAM,8BAA8B;;;;;;iBAGzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAMtF,eAAO,MAAM,0BAA0B;;;;;;;;;;iBAOrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;iBAGnC,CAAC;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;iBAGrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;iBAMlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAIxE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,sBAAsB;IACrC,SAAS,CACP,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,sBAAsB,EAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACvC,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB"}