@iveri/contracts 0.17.0 → 0.18.0

package/README.md

@@ -3,6 +3,13 @@
 The wire contract every Iveri service and frontend compiles against: shared types and plain
 enums, and nothing else.
 
+Release `0.18.0` adds the localization contract under `@iveri/contracts/localization` —
+`Locale`, `Namespace`, `Message` with its declared `MessageVariable` list, `Translation`,
+`Release`, the build-time `TranslationBundle` and the runtime render shapes — plus five
+`localization:*` permissions. Two consumers exist from day one and they read it differently: a
+frontend pulls a bundle at build time and compiles it in, a backend renders a message at runtime
+for a locale that belongs to the recipient rather than the caller.
+
 Release `0.17.0` adds `realtime.unsubscribe`. Subscribing is additive and capped per socket, so
 without it a long-lived inbox that pages through conversations reaches the cap and then silently
 stops receiving anything.
@@ -25,9 +32,10 @@ import { CursorPage, ErrorCode, Maybe, Paginated, UUID, UserPermission } from '@
 import type { CaptureSummary, Endpoint } from '@iveri/contracts/conduit';
 import type { AuthSession, Principal } from '@iveri/contracts/identity';
 import type { Conversation, Message } from '@iveri/contracts/unibox';
+import type { Namespace, TranslationBundle } from '@iveri/contracts/localization';
 ```
 
-Five entry points, and no others — never `@iveri/contracts/dist/...`.
+Six entry points, and no others — never `@iveri/contracts/dist/...`.
 
 The per-service surfaces are **not** re-exported from the root, deliberately. Conduit owns a
 `Provider`, a `Connection` and an `Endpoint`; Unibox owns a `Channel` and a `Contact` and would
@@ -129,6 +137,19 @@ is a first-class member for the same reason Conduit's `local-echo` connector is:
 is provable without a Meta app, and a test double would put a branch in the normalizer registry
 that only exists under Jest.
 
+### `api/localization/` → `@iveri/contracts/localization`
+
+`iveri-localization-api`'s surface, and the clearest case yet for a shared entry point: the two
+halves are consumed by different kinds of client and must not drift. `TranslationBundle` is what a
+frontend build pulls and commits; `RenderBody`/`RenderedMessage` is what a backend posts when it
+needs a string in the _recipient's_ language. `Locale`, `Namespace`, `Message` with its
+`MessageVariable` declarations, `Translation`, `Release` and `ReleaseDiff` carry the authoring
+surface the translator panel is written against, with `TranslationStatus` and `VariableType`.
+
+`Locale` is a row rather than an enum on purpose — see the type's own note. Nothing in the
+platform branches on _which_ language a string is in, so encoding the set in a type would make
+adding one a release of this package and a redeploy of every consumer, for a value no code reads.
+
 ### Why the wire shapes moved here
 
 `conduit-admin-web` hand-transcribed all of it, carefully and with comments. It still drifted:
@@ -160,6 +181,9 @@ Conduit's outbox.
 - Version `0.13.0` adds the billing invoice read and manage permissions.
 - Version `0.14.0` adds messaging message, OTP and credit permissions.
 - Version `0.15.0` adds optional per-key FIFO ordering to outbound dispatches.
+- Version `0.18.0` adds the localization entry point and the `localization:read`,
+  `localization:message:manage`, `localization:translate`, `localization:publish` and
+  `localization:render` permissions.
 - Widening a type is minor; narrowing it is major.
 - Under `api/`, the contract follows the service: add the field to the service's DTO and to the
   interface in the same release, and let `implements` prove they agree.

package/dist/cjs/api/localization/bundle.type.d.ts

@@ -0,0 +1,41 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+/**
+ * One namespace at one locale, flattened — what a build pulls and commits into a repo.
+ *
+ * **UI strings are fetched at build time, never at runtime, and that is the load-bearing decision
+ * in this service.** A React app that fetched its labels on mount would put a network call in
+ * front of every first paint, make this service a hard dependency of two admin panels that are
+ * otherwise happy while it is down, and render a screen of empty strings when it is not. The
+ * strings were known when the app compiled; that is when they should be baked in.
+ *
+ * So a consumer runs `pnpm i18n:pull`, gets one of these per locale, writes it to
+ * `src/locale/<code>.json`, and commits it. The diff is reviewable, the app has no runtime
+ * dependency, and rolling back a bad translation is `git revert`.
+ *
+ * {@link RenderedMessage} is the other half — for text produced on a server, where there is no
+ * bundle to bake into.
+ */
+export interface TranslationBundle {
+    namespaceKey: string;
+    localeCode: string;
+    /** The release this was cut from. Pinned by the consumer; `latest` resolves to a number. */
+    version: number;
+    generatedAt: IsoDateTime;
+    /**
+     * Message key to ICU value.
+     *
+     * **Flat, not nested.** `{"inbox.title": "..."}` rather than `{"inbox": {"title": "..."}}`,
+     * even though the dotted keys invite nesting. Nesting means a key containing a dot becomes
+     * ambiguous, and it makes `messages[key]` — the only lookup anyone performs — a path walk
+     * instead of a property read.
+     */
+    messages: Record<string, string>;
+    /**
+     * Keys served from a fallback locale rather than this one, and where they came from.
+     *
+     * Emitted so a build can fail, or warn, on an incomplete bundle. Without it a half-translated
+     * locale looks identical to a complete one: every key resolves, and half of them are English.
+     */
+    fallbacks: Record<string, string>;
+}
+//# sourceMappingURL=bundle.type.d.ts.map

package/dist/cjs/api/localization/bundle.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.type.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/bundle.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAEpE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IAEnB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;IAEhB,WAAW,EAAE,WAAW,CAAC;IAEzB;;;;;;;OAOG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC"}

package/dist/cjs/api/localization/bundle.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=bundle.type.js.map

package/dist/cjs/api/localization/bundle.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.type.js","sourceRoot":"","sources":["../../../../src/api/localization/bundle.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/localization/index.d.ts

@@ -0,0 +1,10 @@
+export * from './bundle.type.js';
+export * from './locale.type.js';
+export * from './message.type.js';
+export * from './namespace.type.js';
+export * from './release.type.js';
+export * from './render.type.js';
+export * from './translation-status.enum.js';
+export * from './translation.type.js';
+export * from './variable-type.enum.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/api/localization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC"}

package/dist/cjs/api/localization/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./bundle.type.js"), exports);
+__exportStar(require("./locale.type.js"), exports);
+__exportStar(require("./message.type.js"), exports);
+__exportStar(require("./namespace.type.js"), exports);
+__exportStar(require("./release.type.js"), exports);
+__exportStar(require("./render.type.js"), exports);
+__exportStar(require("./translation-status.enum.js"), exports);
+__exportStar(require("./translation.type.js"), exports);
+__exportStar(require("./variable-type.enum.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/api/localization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/localization/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC;AACjC,mDAAiC;AACjC,oDAAkC;AAClC,sDAAoC;AACpC,oDAAkC;AAClC,mDAAiC;AACjC,+DAA6C;AAC7C,wDAAsC;AACtC,0DAAwC"}

package/dist/cjs/api/localization/locale.type.d.ts

@@ -0,0 +1,67 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/**
+ * A language a tenant publishes in.
+ *
+ * **A row, not an enum member.** The obvious alternative — `enum LocaleCode { EN, RU, KA }` — makes
+ * adding Ukrainian a contracts release, an SDK release and a redeploy of every consumer, to add a
+ * value that no code branches on. Nothing in the platform switches on *which* locale a string is
+ * in; it only ever looks one up. So the set belongs in data.
+ *
+ * `code` is a BCP-47 tag and is what every other surface uses: the `Accept-Language` header the
+ * SDK already resolves into `RequestContext.locale`, the export filename, the render request.
+ */
+export interface Locale {
+    id: UUID;
+    /** BCP-47, lowercased — `en`, `ru`, `ka`, `en-GB`. Unique within the tenant. */
+    code: string;
+    /** For the language picker in an English-language admin screen. */
+    englishName: string;
+    /** For the language picker a native speaker sees — `ქართული`, `Русский`. */
+    nativeName: string;
+    /**
+     * The locale translators translate *from*. Exactly one per tenant.
+     *
+     * It is also the locale a message's source text lives in, so editing a source value is what
+     * flips every other locale's translation of that message to `needs-review`. Changing which
+     * locale is the source is therefore not a display preference — it moves that trigger.
+     */
+    isSource: boolean;
+    /**
+     * Whether this locale is offered at all. Inactive keeps the translations and stops them
+     * being exported or rendered, which is what a locale that is half-translated needs — the
+     * alternative is deleting the work to hide it.
+     */
+    isActive: boolean;
+    /**
+     * Where a lookup goes when this locale has no approved translation. Null ends the chain.
+     *
+     * Chains are followed transitively (`en-GB → en → null`) and are **rejected at write time if
+     * they cycle**, because the resolver would otherwise loop on a row a customer can create.
+     */
+    fallbackCode: Nullable<string>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** `GET /api/v1/locales`. Small and unpaged — a tenant has a handful of these, not a page of them. */
+export type LocaleList = Locale[];
+/** `POST /api/v1/locales`. */
+export interface CreateLocaleBody {
+    code: string;
+    englishName: string;
+    nativeName: string;
+    isSource?: boolean;
+    isActive?: boolean;
+    fallbackCode?: Nullable<string>;
+}
+/** `PATCH /api/v1/locales/:code`. */
+export interface UpdateLocaleBody {
+    englishName?: string;
+    nativeName?: string;
+    /** Promoting a locale to source demotes the previous one in the same transaction. */
+    isSource?: boolean;
+    isActive?: boolean;
+    fallbackCode?: Nullable<string>;
+}
+//# sourceMappingURL=locale.type.d.ts.map

package/dist/cjs/api/localization/locale.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.type.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/locale.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,MAAM;IACnB,EAAE,EAAE,IAAI,CAAC;IAET,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IAEb,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IAEpB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAC;IAElB;;;;;OAKG;IACH,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE/B,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,sGAAsG;AACtG,MAAM,MAAM,UAAU,GAAG,MAAM,EAAE,CAAC;AAElC,8BAA8B;AAC9B,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACnC;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACnC"}

package/dist/cjs/api/localization/locale.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=locale.type.js.map

package/dist/cjs/api/localization/locale.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale.type.js","sourceRoot":"","sources":["../../../../src/api/localization/locale.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/localization/message.type.d.ts

@@ -0,0 +1,90 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { Paginated } from '../../type/paginated.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { TranslationStatus } from './translation-status.enum.js';
+import type { VariableType } from './variable-type.enum.js';
+/** One placeholder a message declares. See {@link VariableType} for why these are declared. */
+export interface MessageVariable {
+    /** The name inside the braces — `orderNumber` in `{orderNumber}`. `[a-zA-Z][a-zA-Z0-9]*`. */
+    name: string;
+    type: VariableType;
+    /**
+     * What it holds, in a sentence, for the translator.
+     *
+     * Worth more than it looks: a translator seeing `{count}` cannot tell whether it counts
+     * unread messages or days remaining, and the two need different words in Georgian.
+     */
+    description: Nullable<string>;
+    /** A representative value, used to preview the rendered string in the editor. */
+    example: Nullable<string>;
+    /**
+     * For {@link VariableType.SELECT} only — the closed set of branches a translation may use.
+     * A translation branching on anything outside it is rejected at write time.
+     */
+    options: Nullable<string[]>;
+}
+/**
+ * A translatable string, identified by a key that never changes.
+ *
+ * The key is the contract with the consuming code: `t('inbox.conversation.assign')` is compiled
+ * into an app, so renaming one is a breaking change to every release that already shipped. Keys
+ * are therefore **immutable after creation** and retired by archiving, not by deletion.
+ */
+export interface Message {
+    id: UUID;
+    namespaceId: UUID;
+    namespaceKey: string;
+    /** Dotted, lowercase, `[a-z0-9.-]` — `inbox.conversation.assign`. Unique in the namespace. */
+    key: string;
+    /**
+     * Where this string appears and what it is doing there.
+     *
+     * The highest-leverage field in the schema. A translator handed `Open` with no context cannot
+     * know whether it is a button, an adjective describing a conversation, or a status label —
+     * and those are three different Georgian words. Missing context is the main cause of
+     * translations that are individually correct and collectively wrong.
+     */
+    description: Nullable<string>;
+    variables: MessageVariable[];
+    /**
+     * Retired. Excluded from new releases, kept so an older pinned release still resolves and so
+     * the translation work is not destroyed by a key that turns out to be still in use.
+     */
+    isArchived: boolean;
+    /** Present on the detail response; omitted from the listing, which is already wide. */
+    translations?: MessageTranslationSummary[];
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** One locale's standing on a message, as shown in a listing row. */
+export interface MessageTranslationSummary {
+    localeCode: string;
+    /** `MISSING` here is synthesised — see {@link TranslationStatus}. */
+    status: TranslationStatus;
+    value: Nullable<string>;
+    updatedAt: Nullable<IsoDateTime>;
+}
+/** `GET /api/v1/namespaces/:key/messages`. */
+export type MessagesPage = Paginated<Message>;
+/** `POST /api/v1/namespaces/:key/messages`. */
+export interface CreateMessageBody {
+    key: string;
+    description?: Nullable<string>;
+    variables?: MessageVariable[];
+    /** The source-locale text. Written as an `APPROVED` translation in the same transaction. */
+    sourceValue: string;
+}
+/**
+ * `PATCH /api/v1/namespaces/:key/messages/:messageKey`.
+ *
+ * Editing `variables` is the sharp one: removing a declared variable invalidates every
+ * translation still using it, so the service refuses the edit and names them rather than
+ * silently leaving broken strings behind.
+ */
+export interface UpdateMessageBody {
+    description?: Nullable<string>;
+    variables?: MessageVariable[];
+    isArchived?: boolean;
+}
+//# sourceMappingURL=message.type.d.ts.map

package/dist/cjs/api/localization/message.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.type.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/message.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D,+FAA+F;AAC/F,MAAM,WAAW,eAAe;IAC5B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IAEb,IAAI,EAAE,YAAY,CAAC;IAEnB;;;;;OAKG;IACH,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,iFAAiF;IACjF,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE1B;;;OAGG;IACH,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,IAAI,CAAC;IAET,WAAW,EAAE,IAAI,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IAErB,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;;;;OAOG;IACH,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B,SAAS,EAAE,eAAe,EAAE,CAAC;IAE7B;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB,uFAAuF;IACvF,YAAY,CAAC,EAAE,yBAAyB,EAAE,CAAC;IAE3C,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,qEAAqE;AACrE,MAAM,WAAW,yBAAyB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACpC;AAED,8CAA8C;AAC9C,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AAE9C,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAC9B,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB"}

package/dist/cjs/api/localization/message.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=message.type.js.map

package/dist/cjs/api/localization/message.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.type.js","sourceRoot":"","sources":["../../../../src/api/localization/message.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/localization/namespace.type.d.ts

@@ -0,0 +1,67 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { Paginated } from '../../type/paginated.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/**
+ * A bounded set of keys owned by one consumer — `unibox-web`, `billing.invoice`, `messaging.otp`.
+ *
+ * **The unit of publish and the unit of fetch, and it has to be both.** Without namespaces every
+ * consumer downloads every string the tenant has ever written, and a translator fixing one word in
+ * an invoice template republishes the entire admin panel's UI at the same time. Those are the two
+ * failures a flat key space produces, and neither is visible until the key count is in the
+ * thousands and it is expensive to fix.
+ *
+ * A namespace maps roughly to a deployable: one app, or one family of server-rendered messages.
+ */
+export interface Namespace {
+    id: UUID;
+    /** Lowercase `[a-z0-9.-]`, e.g. `unibox-web`. Unique within the tenant. */
+    key: string;
+    /** What lives in here, for whoever has to decide where a new key belongs. */
+    description: Nullable<string>;
+    /**
+     * Whether a release may include translations still in `draft`.
+     *
+     * Off by default. On for a namespace nobody reads in production yet, where requiring approval
+     * on every key means a translator cannot see their own work in the app.
+     */
+    allowsDraftRelease: boolean;
+    messageCount: number;
+    /** Null until the namespace has been published once. */
+    latestReleaseVersion: Nullable<number>;
+    latestReleaseAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/** `GET /api/v1/namespaces`. */
+export type NamespacesPage = Paginated<Namespace>;
+/** `POST /api/v1/namespaces`. */
+export interface CreateNamespaceBody {
+    key: string;
+    description?: Nullable<string>;
+    allowsDraftRelease?: boolean;
+}
+/** `PATCH /api/v1/namespaces/:key`. The key itself is immutable — consumers pin it. */
+export interface UpdateNamespaceBody {
+    description?: Nullable<string>;
+    allowsDraftRelease?: boolean;
+}
+/**
+ * `GET /api/v1/namespaces/:key/progress` — how much is left to do, per locale.
+ *
+ * The one screen a translation project actually runs on. Answering it from the message listing
+ * would mean paging through every key to count what is missing.
+ */
+export interface NamespaceProgress {
+    namespaceKey: string;
+    messageCount: number;
+    locales: LocaleProgress[];
+}
+export interface LocaleProgress {
+    localeCode: string;
+    approved: number;
+    needsReview: number;
+    draft: number;
+    missing: number;
+}
+//# sourceMappingURL=namespace.type.d.ts.map

package/dist/cjs/api/localization/namespace.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.type.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/namespace.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACtB,EAAE,EAAE,IAAI,CAAC;IAET,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IAEZ,6EAA6E;IAC7E,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAE9B;;;;;OAKG;IACH,kBAAkB,EAAE,OAAO,CAAC;IAE5B,YAAY,EAAE,MAAM,CAAC;IAErB,wDAAwD;IACxD,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvC,eAAe,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAEvC,SAAS,EAAE,WAAW,CAAC;IACvB,SAAS,EAAE,WAAW,CAAC;CAC1B;AAED,gCAAgC;AAChC,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;AAElD,iCAAiC;AACjC,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,uFAAuF;AACvF,MAAM,WAAW,mBAAmB;IAChC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACnB"}

package/dist/cjs/api/localization/namespace.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=namespace.type.js.map

package/dist/cjs/api/localization/namespace.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.type.js","sourceRoot":"","sources":["../../../../src/api/localization/namespace.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/localization/release.type.d.ts

@@ -0,0 +1,74 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { Nullable } from '../../type/nil.type.js';
+import type { Paginated } from '../../type/paginated.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+/**
+ * An immutable snapshot of one namespace, at every active locale, at one moment.
+ *
+ * **This is what makes the service safe to depend on.** Without it, editing a translation changes
+ * production text the instant it is saved — so a translator experimenting at 2am is a deploy, an
+ * unfinished sentence is an outage, and there is no way to answer "what did this say last
+ * Tuesday". With it, editing is free and publishing is the decision, gated by its own permission.
+ *
+ * The snapshot is stored in full rather than reconstructed from the translation rows by
+ * timestamp. Reconstruction sounds cheaper and is wrong: a message archived after the release, or
+ * a variable renamed, changes what the reconstruction produces, so a consumer pinned to version 3
+ * would silently get different bytes next month.
+ */
+export interface Release {
+    id: UUID;
+    namespaceId: UUID;
+    namespaceKey: string;
+    /** Monotonic per namespace, starting at 1. What a consumer pins. */
+    version: number;
+    /** What changed and why, for whoever reads the history. */
+    notes: Nullable<string>;
+    /** Locales the snapshot contains — the active ones at publish time, not necessarily now. */
+    localeCodes: string[];
+    messageCount: number;
+    /** Null when published by a service principal. */
+    publishedByUserId: Nullable<UUID>;
+    publishedAt: IsoDateTime;
+}
+/** `GET /api/v1/namespaces/:key/releases`. Newest first. */
+export type ReleasesPage = Paginated<Release>;
+/** `POST /api/v1/namespaces/:key/releases`. */
+export interface PublishReleaseBody {
+    notes?: Nullable<string>;
+}
+/**
+ * `GET /api/v1/namespaces/:key/releases/preview` — what publishing right now would change.
+ *
+ * Shown before the button is pressed. A publish is irreversible in the sense that matters — the
+ * consumers pull it — so the operator gets to see the diff first rather than discovering it in
+ * production.
+ */
+export interface ReleaseDiff {
+    namespaceKey: string;
+    /** The version this would become. */
+    nextVersion: number;
+    /** Null when nothing has been published yet, in which case everything reads as added. */
+    previousVersion: Nullable<number>;
+    entries: ReleaseDiffEntry[];
+    /**
+     * Messages with no publishable translation in a locale that is active.
+     *
+     * Not an error — a release ships with gaps and the consumer falls back. It is surfaced
+     * because shipping a gap should be a choice someone made, not one they made by not looking.
+     */
+    untranslated: UntranslatedEntry[];
+}
+export interface ReleaseDiffEntry {
+    messageKey: string;
+    localeCode: string;
+    change: 'added' | 'changed' | 'removed';
+    previousValue: Nullable<string>;
+    nextValue: Nullable<string>;
+}
+export interface UntranslatedEntry {
+    messageKey: string;
+    localeCode: string;
+    /** Where the fallback chain lands, or null if it falls off the end and the key renders raw. */
+    fallsBackTo: Nullable<string>;
+}
+//# sourceMappingURL=release.type.d.ts.map

package/dist/cjs/api/localization/release.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.type.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/release.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,OAAO;IACpB,EAAE,EAAE,IAAI,CAAC;IAET,WAAW,EAAE,IAAI,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IAErB,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAEhB,2DAA2D;IAC3D,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAExB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,EAAE,CAAC;IAEtB,YAAY,EAAE,MAAM,CAAC;IAErB,kDAAkD;IAClD,iBAAiB,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAClC,WAAW,EAAE,WAAW,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;AAE9C,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IAC/B,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB,YAAY,EAAE,MAAM,CAAC;IAErB,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IAEpB,yFAAyF;IACzF,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAElC,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,YAAY,EAAE,iBAAiB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACxC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,+FAA+F;IAC/F,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACjC"}

package/dist/cjs/api/localization/release.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=release.type.js.map

package/dist/cjs/api/localization/release.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.type.js","sourceRoot":"","sources":["../../../../src/api/localization/release.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/localization/render.type.d.ts

@@ -0,0 +1,50 @@
+import type { Nullable } from '../../type/nil.type.js';
+/**
+ * `POST /api/v1/render` — resolve and format messages server-side.
+ *
+ * The counterpart to {@link TranslationBundle}, for the case a bundle cannot serve: text produced
+ * on a server, where there is no compiled app to bake strings into and the target locale belongs
+ * to whoever will read the message rather than whoever is making the request. An OTP body, an
+ * invoice line, an order confirmation.
+ *
+ * **Batched, because the caller almost always needs several.** An invoice email is a subject, a
+ * greeting, six line labels and a footer, and one HTTP round trip per string would put this
+ * service on the latency path of every email the platform sends.
+ */
+export interface RenderBody {
+    /** BCP-47. Falls back through the locale chain when this one has no translation. */
+    localeCode: string;
+    items: RenderItem[];
+}
+export interface RenderItem {
+    namespaceKey: string;
+    messageKey: string;
+    /**
+     * Values for the message's declared placeholders.
+     *
+     * A missing one is an error rather than an empty substitution: an OTP that renders as
+     * "Your code is " is worse than an error, because it is sent.
+     */
+    variables?: Record<string, string | number>;
+}
+export interface RenderResult {
+    items: RenderedMessage[];
+}
+export interface RenderedMessage {
+    namespaceKey: string;
+    messageKey: string;
+    /** The locale actually used, which is not necessarily the one asked for. */
+    localeCode: string;
+    /** Formatted for {@link localeCode} — plural branches taken, numbers and dates localised. */
+    value: string;
+    /**
+     * True when the requested locale had nothing and the chain supplied this.
+     *
+     * Returned rather than hidden so a caller that must not send a half-localised message — an
+     * OTP, a legal notice — can decide for itself rather than discovering it from a customer.
+     */
+    isFallback: boolean;
+    /** The release the value came from. Null for a message that has never been published. */
+    version: Nullable<number>;
+}
+//# sourceMappingURL=render.type.d.ts.map

package/dist/cjs/api/localization/render.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.type.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/render.type.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACvB,oFAAoF;IACpF,UAAU,EAAE,MAAM,CAAC;IAEnB,KAAK,EAAE,UAAU,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,UAAU;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,YAAY;IACzB,KAAK,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,eAAe;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IAEnB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IAEnB,6FAA6F;IAC7F,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB,yFAAyF;IACzF,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CAC7B"}

package/dist/cjs/api/localization/render.type.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=render.type.js.map

package/dist/cjs/api/localization/render.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.type.js","sourceRoot":"","sources":["../../../../src/api/localization/render.type.ts"],"names":[],"mappings":""}

package/dist/cjs/api/localization/translation-status.enum.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a single translation stands, for one message in one locale.
+ *
+ * The states exist to answer one question a translator asks constantly — *what is left to do* —
+ * and they are ordered by how much trust a reader may put in the value.
+ *
+ * `MISSING` is **not stored**. A translation row exists only once someone has written something,
+ * so "missing" is the absence of a row projected into this enum by the read side. Storing it
+ * would mean writing a row per message per locale the moment a key is created, which turns
+ * adding one key into N writes and makes "has anyone touched this?" unanswerable.
+ */
+export declare enum TranslationStatus {
+    /** No row exists. Synthesised by the read side so a listing can be filtered on it. */
+    MISSING = "missing",
+    /** Someone is working on it. Excluded from a release unless the namespace allows drafts. */
+    DRAFT = "draft",
+    /**
+     * Written, but the source text changed underneath it.
+     *
+     * Set automatically when the source-locale value of the same message is edited — an English
+     * label reworded from `Archive` to `Delete` leaves a Georgian translation that is
+     * grammatically fine and now says the wrong thing. Nothing else in the system can catch that,
+     * because the translation is still valid text.
+     */
+    NEEDS_REVIEW = "needs-review",
+    /** Reviewed and publishable. */
+    APPROVED = "approved"
+}
+//# sourceMappingURL=translation-status.enum.d.ts.map

package/dist/cjs/api/localization/translation-status.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translation-status.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/localization/translation-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oBAAY,iBAAiB;IACzB,sFAAsF;IACtF,OAAO,YAAY;IAEnB,4FAA4F;IAC5F,KAAK,UAAU;IAEf;;;;;;;OAOG;IACH,YAAY,iBAAiB;IAE7B,gCAAgC;IAChC,QAAQ,aAAa;CACxB"}