@iveri/contracts 0.19.0 → 0.21.0

package/README.md

@@ -3,6 +3,22 @@
 The wire contract every Iveri service and frontend compiles against: shared types and plain
 enums, and nothing else.
 
+Release `0.21.0` adds the shared realtime contract under `@iveri/contracts/realtime`: closed
+resource and event vocabularies, identifier-only publish messages, and short-lived subscription
+grants bound to one tenant, person and resource. It also separates permission to issue a grant
+from permission to publish an event, because authorizing a read and announcing a write are
+different powers.
+
+Release `0.20.0` adds the notification contract under `@iveri/contracts/notification` —
+`NotificationChannel`, `NotificationDeliveryStatus`, `NotificationTemplate`, `Notification` with
+its per-channel `NotificationDelivery` list, `InAppNotification` and the submit body — plus six
+`notification:*` permissions. Two absences are decisions and each carries a spec: there is no
+`push` channel, because a channel a caller can name and nothing can deliver reads as a successful
+submit and reaches nobody; and no `delivered` status, because a relay accepting a message is not
+evidence a person received it and nothing subscribes to a bounce. Status lives on the delivery
+rather than the notification — one that emailed successfully and dead-lettered in the inbox has
+two true answers and no single one.
+
 Release `0.19.0` adds `MessageVariableInput` — a declaration as a client sends it, where the
 optional halves may be absent. A separate type rather than `MessageVariable` with everything
 optional, because omitting a field on the way in and receiving `null` on the way out are
@@ -38,9 +54,11 @@ 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';
+import type { Notification, NotificationChannel } from '@iveri/contracts/notification';
+import type { RealtimeSubscription, RealtimeResourceUpdatedMessage } from '@iveri/contracts/realtime';
 ```
 
-Six entry points, and no others — never `@iveri/contracts/dist/...`.
+Eight 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
@@ -155,6 +173,26 @@ surface the translator panel is written against, with `TranslationStatus` and `V
 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.
 
+### `api/notification/` → `@iveri/contracts/notification`
+
+`iveri-notification-api`'s surface: `NotificationTemplate` and its upsert body, `Notification`
+with its per-channel `NotificationDelivery` list, `SubmitNotificationBody`, `InAppNotification`,
+and the `NotificationChannel` and `NotificationDeliveryStatus` enums.
+
+Three shapes here are decisions rather than descriptions, and each is pinned by a spec:
+
+- **Status lives on the delivery, not the notification.** One that emailed successfully and
+  dead-lettered in the inbox has two true answers, and a rolled-up field would have to pick one —
+  hiding a dead letter behind a success, or failing a notification that mostly worked.
+- **No `push` channel**, because there is no device registry, no per-platform credentials and no
+  token rotation behind one. A channel a caller can name and nothing can deliver looks like a
+  successful submit and reaches nobody.
+- **No `delivered` status**, because a relay accepting a message is not evidence a person received
+  it and nothing subscribes to a bounce yet. `SENT` is the strongest honest statement.
+
+A template holds message **keys**, never text — the wording lives in `iveri-localization-api`, so
+there is one place with ICU validation, a review gate and Georgian, rather than two.
+
 ### Why the wire shapes moved here
 
 `conduit-admin-web` hand-transcribed all of it, carefully and with comments. It still drifted:

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

@@ -0,0 +1,5 @@
+export * from './notification-channel.enum.js';
+export * from './notification-delivery-status.enum.js';
+export * from './notification-template.type.js';
+export * from './notification.type.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/notification/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wCAAwC,CAAC;AACvD,cAAc,iCAAiC,CAAC;AAChD,cAAc,wBAAwB,CAAC"}

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

@@ -0,0 +1,21 @@
+"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("./notification-channel.enum.js"), exports);
+__exportStar(require("./notification-delivery-status.enum.js"), exports);
+__exportStar(require("./notification-template.type.js"), exports);
+__exportStar(require("./notification.type.js"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/notification/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iEAA+C;AAC/C,yEAAuD;AACvD,kEAAgD;AAChD,yDAAuC"}

package/dist/cjs/api/notification/notification-channel.enum.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A way a notification reaches a person.
+ *
+ * A channel is not a provider. `EMAIL` says a message is addressed to a mailbox; whether it
+ * leaves through a local SMTP sink, SES or a transactional-email vendor is an adapter detail
+ * `iveri-notification-api` keeps behind its own boundary, and nothing on the wire names one.
+ *
+ * **There is deliberately no `PUSH` member yet**, and adding one is not a formality. Push needs a
+ * device registry, per-platform credentials (APNs keys, FCM service accounts) and a token-rotation
+ * story, none of which exist and none of which any product currently asks for. A member declared
+ * before the machinery behind it is a value a caller can send that quietly goes nowhere — worse
+ * than a 422 saying the channel is unknown, because it looks like it worked.
+ */
+export declare enum NotificationChannel {
+    /** A message to a mailbox. Needs `recipient.emailAddress`. */
+    EMAIL = "email",
+    /**
+     * A row in the recipient's own in-app inbox. Needs `recipient.userId`.
+     *
+     * The only channel whose delivery is a local write, which is why it is the one channel that
+     * cannot fail for a reason outside our control. It still goes through the same queue as
+     * email: a notification that fans out to both must not have one half committed inline and the
+     * other half queued, or a rollback leaves the two halves disagreeing about what happened.
+     */
+    IN_APP = "in-app"
+}
+//# sourceMappingURL=notification-channel.enum.d.ts.map

package/dist/cjs/api/notification/notification-channel.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-channel.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/notification/notification-channel.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,mBAAmB;IAC3B,8DAA8D;IAC9D,KAAK,UAAU;IAEf;;;;;;;OAOG;IACH,MAAM,WAAW;CACpB"}

package/dist/cjs/api/notification/notification-channel.enum.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationChannel = void 0;
+/**
+ * A way a notification reaches a person.
+ *
+ * A channel is not a provider. `EMAIL` says a message is addressed to a mailbox; whether it
+ * leaves through a local SMTP sink, SES or a transactional-email vendor is an adapter detail
+ * `iveri-notification-api` keeps behind its own boundary, and nothing on the wire names one.
+ *
+ * **There is deliberately no `PUSH` member yet**, and adding one is not a formality. Push needs a
+ * device registry, per-platform credentials (APNs keys, FCM service accounts) and a token-rotation
+ * story, none of which exist and none of which any product currently asks for. A member declared
+ * before the machinery behind it is a value a caller can send that quietly goes nowhere — worse
+ * than a 422 saying the channel is unknown, because it looks like it worked.
+ */
+var NotificationChannel;
+(function (NotificationChannel) {
+    /** A message to a mailbox. Needs `recipient.emailAddress`. */
+    NotificationChannel["EMAIL"] = "email";
+    /**
+     * A row in the recipient's own in-app inbox. Needs `recipient.userId`.
+     *
+     * The only channel whose delivery is a local write, which is why it is the one channel that
+     * cannot fail for a reason outside our control. It still goes through the same queue as
+     * email: a notification that fans out to both must not have one half committed inline and the
+     * other half queued, or a rollback leaves the two halves disagreeing about what happened.
+     */
+    NotificationChannel["IN_APP"] = "in-app";
+})(NotificationChannel || (exports.NotificationChannel = NotificationChannel = {}));
+//# sourceMappingURL=notification-channel.enum.js.map

package/dist/cjs/api/notification/notification-channel.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-channel.enum.js","sourceRoot":"","sources":["../../../../src/api/notification/notification-channel.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,IAAY,mBAaX;AAbD,WAAY,mBAAmB;IAC3B,8DAA8D;IAC9D,sCAAe,CAAA;IAEf;;;;;;;OAOG;IACH,wCAAiB,CAAA;AACrB,CAAC,EAbW,mBAAmB,mCAAnB,mBAAmB,QAa9B"}

package/dist/cjs/api/notification/notification-delivery-status.enum.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How far one channel's attempt at a notification got.
+ *
+ * The state lives on the **delivery**, never on the notification. A notification that fans out to
+ * email and the in-app inbox has two independent fates, and a single rolled-up status would have
+ * to pick one of them to report — which means either hiding a dead letter behind a success or
+ * marking a wholly delivered notification as failed because one channel bounced.
+ *
+ * These mirror `conduit-api`'s outbound states deliberately but are a **separate enum**, for the
+ * same reason Conduit keeps its inbound and outbound statuses apart: the words coincide and the
+ * stories do not. A dead-lettered dispatch means a customer's message never reached a provider; a
+ * dead-lettered notification means a person was never told something we decided to tell them.
+ */
+export declare enum NotificationDeliveryStatus {
+    /** Waiting for its next attempt, due at `nextAttemptAt`. */
+    PENDING = "pending",
+    /**
+     * Claimed by a worker and in progress.
+     *
+     * A row stranded here past the claim timeout is reclaimed by the same query that claims fresh
+     * work, which is where at-least-once becomes visible and why every channel adapter has to
+     * tolerate being asked twice.
+     */
+    IN_FLIGHT = "in-flight",
+    /**
+     * The channel accepted it. Terminal, and the strongest thing we can honestly say.
+     *
+     * **There is no `DELIVERED`**, and its absence is a decision rather than an omission. An SMTP
+     * relay accepting a message is not evidence a person received it — the bounce arrives minutes
+     * later, out of band, and nothing here is listening for one yet. A `DELIVERED` state we cannot
+     * observe would be a field every UI renders as a green tick and no code ever sets.
+     */
+    SENT = "sent",
+    /**
+     * The attempt budget is spent, or the channel refused in a way no retry can fix. Terminal.
+     *
+     * Reached from a permanent refusal on the very first attempt — an address the relay rejects
+     * outright, a template that names a message key nobody has published — because four more
+     * identical failures buy nothing and delay the moment somebody can act.
+     */
+    DEAD_LETTERED = "dead-lettered",
+    /** An operator stopped it before it went out. Terminal, and not a failure. */
+    CANCELLED = "cancelled"
+}
+//# sourceMappingURL=notification-delivery-status.enum.d.ts.map

package/dist/cjs/api/notification/notification-delivery-status.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-delivery-status.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/notification/notification-delivery-status.enum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,oBAAY,0BAA0B;IAClC,4DAA4D;IAC5D,OAAO,YAAY;IAEnB;;;;;;OAMG;IACH,SAAS,cAAc;IAEvB;;;;;;;OAOG;IACH,IAAI,SAAS;IAEb;;;;;;OAMG;IACH,aAAa,kBAAkB;IAE/B,8EAA8E;IAC9E,SAAS,cAAc;CAC1B"}

package/dist/cjs/api/notification/notification-delivery-status.enum.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NotificationDeliveryStatus = void 0;
+/**
+ * How far one channel's attempt at a notification got.
+ *
+ * The state lives on the **delivery**, never on the notification. A notification that fans out to
+ * email and the in-app inbox has two independent fates, and a single rolled-up status would have
+ * to pick one of them to report — which means either hiding a dead letter behind a success or
+ * marking a wholly delivered notification as failed because one channel bounced.
+ *
+ * These mirror `conduit-api`'s outbound states deliberately but are a **separate enum**, for the
+ * same reason Conduit keeps its inbound and outbound statuses apart: the words coincide and the
+ * stories do not. A dead-lettered dispatch means a customer's message never reached a provider; a
+ * dead-lettered notification means a person was never told something we decided to tell them.
+ */
+var NotificationDeliveryStatus;
+(function (NotificationDeliveryStatus) {
+    /** Waiting for its next attempt, due at `nextAttemptAt`. */
+    NotificationDeliveryStatus["PENDING"] = "pending";
+    /**
+     * Claimed by a worker and in progress.
+     *
+     * A row stranded here past the claim timeout is reclaimed by the same query that claims fresh
+     * work, which is where at-least-once becomes visible and why every channel adapter has to
+     * tolerate being asked twice.
+     */
+    NotificationDeliveryStatus["IN_FLIGHT"] = "in-flight";
+    /**
+     * The channel accepted it. Terminal, and the strongest thing we can honestly say.
+     *
+     * **There is no `DELIVERED`**, and its absence is a decision rather than an omission. An SMTP
+     * relay accepting a message is not evidence a person received it — the bounce arrives minutes
+     * later, out of band, and nothing here is listening for one yet. A `DELIVERED` state we cannot
+     * observe would be a field every UI renders as a green tick and no code ever sets.
+     */
+    NotificationDeliveryStatus["SENT"] = "sent";
+    /**
+     * The attempt budget is spent, or the channel refused in a way no retry can fix. Terminal.
+     *
+     * Reached from a permanent refusal on the very first attempt — an address the relay rejects
+     * outright, a template that names a message key nobody has published — because four more
+     * identical failures buy nothing and delay the moment somebody can act.
+     */
+    NotificationDeliveryStatus["DEAD_LETTERED"] = "dead-lettered";
+    /** An operator stopped it before it went out. Terminal, and not a failure. */
+    NotificationDeliveryStatus["CANCELLED"] = "cancelled";
+})(NotificationDeliveryStatus || (exports.NotificationDeliveryStatus = NotificationDeliveryStatus = {}));
+//# sourceMappingURL=notification-delivery-status.enum.js.map

package/dist/cjs/api/notification/notification-delivery-status.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-delivery-status.enum.js","sourceRoot":"","sources":["../../../../src/api/notification/notification-delivery-status.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,IAAY,0BAkCX;AAlCD,WAAY,0BAA0B;IAClC,4DAA4D;IAC5D,iDAAmB,CAAA;IAEnB;;;;;;OAMG;IACH,qDAAuB,CAAA;IAEvB;;;;;;;OAOG;IACH,2CAAa,CAAA;IAEb;;;;;;OAMG;IACH,6DAA+B,CAAA;IAE/B,8EAA8E;IAC9E,qDAAuB,CAAA;AAC3B,CAAC,EAlCW,0BAA0B,0CAA1B,0BAA0B,QAkCrC"}

package/dist/cjs/api/notification/notification-template.type.d.ts

@@ -0,0 +1,68 @@
+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';
+import type { NotificationChannel } from './notification-channel.enum.js';
+/**
+ * What a notification *type* means: which channels it reaches and which strings it renders.
+ *
+ * A template holds **no text**. It names message keys in `iveri-localization-api`, which resolves
+ * them into the recipient's own language at send time. Storing the wording here instead would
+ * give the platform two places to author user-facing copy, and the second one would be the one
+ * without ICU validation, without a review gate and without Russian — see §13.1 of the workspace
+ * guide, which draws that line for exactly this case.
+ *
+ * **Built-in templates ship in code and a tenant row overrides one by key**, the same arrangement
+ * `conduit-api` uses for provider and connector manifests. `user.invitation` has to exist before
+ * any tenant has configured anything, and a platform whose password-reset email depends on a seed
+ * row is a platform where one missing row means nobody can get back into their account.
+ */
+export interface NotificationTemplate {
+    /**
+     * The stable type key a caller submits — `user.invitation`, `user.password-reset`.
+     *
+     * Dotted `<aggregate>.<event>`, lowercase. It is what a caller writes down, so it never
+     * changes once shipped; a rename is a new key and a deprecation of the old one.
+     */
+    key: string;
+    /** Null for a built-in. A tenant override is a real row and carries an id. */
+    id: Nullable<UUID>;
+    /**
+     * Which channels this type fans out to. One delivery row is written per channel.
+     *
+     * An empty list is refused on write rather than stored: a template that reaches nobody is a
+     * notification that silently disappears, and the submit would still answer 202.
+     */
+    channels: NotificationChannel[];
+    /** The localization namespace holding this template's strings. */
+    namespaceKey: string;
+    /** Message key for the subject line. Null for channels that have no subject. */
+    subjectMessageKey: Nullable<string>;
+    /** Message key for the body. Always present — a notification with no body says nothing. */
+    bodyMessageKey: string;
+    /**
+     * Placeholder names the body and subject need supplied at submit time.
+     *
+     * Checked when a notification is submitted, not when it is sent. A missing variable fails
+     * identically on every attempt, so discovering it five backoffs later tells the caller nothing
+     * they can still act on — the same rule Conduit applies to an unfillable path template.
+     */
+    requiredVariables: string[];
+    /**
+     * False for a tenant's own row, true for one of the platform's.
+     *
+     * Surfaced so a panel can say "you are overriding a built-in" rather than presenting a
+     * customised password-reset email as if the platform had no opinion about it.
+     */
+    isBuiltIn: boolean;
+    createdAt: Nullable<IsoDateTime>;
+    updatedAt: Nullable<IsoDateTime>;
+}
+/** `PUT /api/v1/templates/{key}` — create or replace a tenant's override of a template. */
+export interface UpsertNotificationTemplateBody {
+    channels: NotificationChannel[];
+    namespaceKey: string;
+    subjectMessageKey?: Nullable<string>;
+    bodyMessageKey: string;
+    requiredVariables?: Nullable<string[]>;
+}
+//# sourceMappingURL=notification-template.type.d.ts.map

package/dist/cjs/api/notification/notification-template.type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notification-template.type.d.ts","sourceRoot":"","sources":["../../../../src/api/notification/notification-template.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,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAE1E;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ,8EAA8E;IAC9E,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAEhC,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IAErB,gFAAgF;IAChF,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEpC,2FAA2F;IAC3F,cAAc,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAE5B;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IACjC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;CACpC;AAED,2FAA2F;AAC3F,MAAM,WAAW,8BAA8B;IAC3C,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CAC1C"}

package/dist/cjs/api/notification/notification-template.type.js

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

package/dist/cjs/api/notification/notification-template.type.js.map

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

package/dist/cjs/api/notification/notification.type.d.ts

@@ -0,0 +1,136 @@
+import type { CursorPage } from '../../type/cursor-page.type.js';
+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';
+import type { NotificationChannel } from './notification-channel.enum.js';
+import type { NotificationDeliveryStatus } from './notification-delivery-status.enum.js';
+/** Who a notification is for, and in what language. */
+export interface NotificationRecipient {
+    /**
+     * The person, when there is one. Required by {@link NotificationChannel.IN_APP}.
+     *
+     * Null for a notification to somebody who has no account yet — which is precisely the
+     * invitation case, and the reason this is nullable rather than the obvious required field.
+     */
+    userId: Nullable<UUID>;
+    /** Required by {@link NotificationChannel.EMAIL}. */
+    emailAddress: Nullable<string>;
+    /**
+     * BCP-47. The language of the **recipient**, not of whoever submitted the notification.
+     *
+     * Null falls back to the tenant's source locale. This is the field that makes rendering a
+     * runtime concern rather than a build-time one: an agent working in English invites a
+     * colleague who reads Georgian, and the email is the colleague's.
+     */
+    localeCode: Nullable<string>;
+}
+/**
+ * One attempt-tracked send of a notification down one channel.
+ *
+ * This row **is** the outbox. It is written in the same transaction as the notification it belongs
+ * to, claimed by a worker afterwards, and retried on its own schedule — so a channel that is down
+ * delays one delivery rather than failing the submit.
+ */
+export interface NotificationDelivery {
+    id: UUID;
+    notificationId: UUID;
+    channel: NotificationChannel;
+    status: NotificationDeliveryStatus;
+    /** Attempts actually made. A refusal that costs no attempt does not increment it. */
+    attemptCount: number;
+    /** When the next attempt is due. Null once the delivery reaches a terminal state. */
+    nextAttemptAt: Nullable<IsoDateTime>;
+    sentAt: Nullable<IsoDateTime>;
+    /**
+     * Why the last attempt failed, in words an operator can act on.
+     *
+     * Never carries the rendered body or the recipient's address — a delivery log is read by more
+     * people than the mailbox it describes.
+     */
+    lastError: Nullable<string>;
+    /**
+     * The channel's own handle for what it accepted — an SMTP message id.
+     *
+     * Opaque and provider-shaped by nature, kept so a support question about one email can be
+     * traced into a relay's logs. Nothing branches on it.
+     */
+    providerReference: Nullable<string>;
+    /** When the recipient opened it. In-app only; email opens are not tracked. */
+    readAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+    updatedAt: IsoDateTime;
+}
+/**
+ * Something the platform decided to tell somebody.
+ *
+ * **It carries no status of its own**, and that is the load-bearing shape here. Status lives on
+ * {@link NotificationDelivery}, one per channel, because a notification that emailed successfully
+ * and dead-lettered in the inbox has two true answers and no single one. A caller asking "did it
+ * go" reads `deliveries`, which answers precisely rather than approximately.
+ */
+export interface Notification {
+    id: UUID;
+    /** The {@link NotificationTemplate} key this was rendered from. */
+    type: string;
+    recipient: NotificationRecipient;
+    /**
+     * Values for the template's declared placeholders.
+     *
+     * Stored as submitted and re-used on every retry, so a message that is retried an hour later
+     * says what it said the first time. Rendering happens per attempt; the *inputs* do not move.
+     */
+    variables: Record<string, string | number>;
+    /**
+     * The caller's deduplication key, unique per tenant.
+     *
+     * Enforced by a unique index rather than by a read before the insert. Two replicas processing
+     * the same event submit at the same instant, and the read-then-insert both of them do
+     * succeeds — the index is the only thing that turns that into one email.
+     */
+    idempotencyKey: Nullable<string>;
+    deliveries: NotificationDelivery[];
+    createdAt: IsoDateTime;
+}
+/** `POST /api/v1/notifications` */
+export interface SubmitNotificationBody {
+    /** A {@link NotificationTemplate} key. Unknown keys are refused at submit, not at send. */
+    type: string;
+    recipient: {
+        userId?: Nullable<UUID>;
+        emailAddress?: Nullable<string>;
+        localeCode?: Nullable<string>;
+    };
+    variables?: Nullable<Record<string, string | number>>;
+    /** Strongly recommended. Without one, a retried submit tells somebody the same thing twice. */
+    idempotencyKey?: Nullable<string>;
+}
+export interface SubmitNotificationResponse {
+    id: UUID;
+    /**
+     * True when the idempotency key matched an existing notification and nothing was created.
+     *
+     * Reported rather than flattened into success: it means the recipient was already being told,
+     * so a caller treating it as a fresh send would write a second record of one event.
+     */
+    isDuplicate: boolean;
+    deliveries: NotificationDelivery[];
+}
+/**
+ * A row in the caller's own in-app inbox, already rendered.
+ *
+ * Rendered text is returned rather than a key and variables, because it was rendered once at send
+ * time in the recipient's language and re-rendering it on read would let a published translation
+ * change what a notification from last week says.
+ */
+export interface InAppNotification {
+    id: UUID;
+    notificationId: UUID;
+    type: string;
+    subject: Nullable<string>;
+    body: string;
+    readAt: Nullable<IsoDateTime>;
+    createdAt: IsoDateTime;
+}
+export type InAppNotificationPage = CursorPage<InAppNotification>;
+export type NotificationDeliveryPage = CursorPage<NotificationDelivery>;
+//# sourceMappingURL=notification.type.d.ts.map

package/dist/cjs/api/notification/notification.type.d.ts.map

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

package/dist/cjs/api/notification/notification.type.js

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

package/dist/cjs/api/notification/notification.type.js.map

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

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

@@ -0,0 +1,4 @@
+export * from './realtime-event-type.enum.js';
+export * from './realtime-resource-type.enum.js';
+export * from './realtime.type.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/realtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAC;AAC9C,cAAc,kCAAkC,CAAC;AACjD,cAAc,oBAAoB,CAAC"}

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

@@ -0,0 +1,20 @@
+"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("./realtime-event-type.enum.js"), exports);
+__exportStar(require("./realtime-resource-type.enum.js"), exports);
+__exportStar(require("./realtime.type.js"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/api/realtime/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gEAA8C;AAC9C,mEAAiD;AACjD,qDAAmC"}

package/dist/cjs/api/realtime/realtime-event-type.enum.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Identifier-only change notifications delivered over the shared gateway.
+ *
+ * These are prompts to refetch from an owning API, never domain state. Keeping the set closed
+ * prevents a typo from becoming a silently ignored update or forcing clients to refetch every
+ * resource for an event they do not understand.
+ */
+export declare enum RealtimeEventType {
+    TAXI_RIDE_UPDATED = "taxi.ride.updated",
+    DELIVERY_JOB_UPDATED = "delivery.job.updated",
+    MOBILITY_WORKER_LOCATION_UPDATED = "mobility.worker-location.updated",
+    MOBILITY_ASSIGNMENT_UPDATED = "mobility.assignment.updated"
+}
+//# sourceMappingURL=realtime-event-type.enum.d.ts.map

package/dist/cjs/api/realtime/realtime-event-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-event-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/realtime/realtime-event-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,oBAAY,iBAAiB;IACzB,iBAAiB,sBAAsB;IACvC,oBAAoB,yBAAyB;IAC7C,gCAAgC,qCAAqC;IACrE,2BAA2B,gCAAgC;CAC9D"}

package/dist/cjs/api/realtime/realtime-event-type.enum.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeEventType = void 0;
+/**
+ * Identifier-only change notifications delivered over the shared gateway.
+ *
+ * These are prompts to refetch from an owning API, never domain state. Keeping the set closed
+ * prevents a typo from becoming a silently ignored update or forcing clients to refetch every
+ * resource for an event they do not understand.
+ */
+var RealtimeEventType;
+(function (RealtimeEventType) {
+    RealtimeEventType["TAXI_RIDE_UPDATED"] = "taxi.ride.updated";
+    RealtimeEventType["DELIVERY_JOB_UPDATED"] = "delivery.job.updated";
+    RealtimeEventType["MOBILITY_WORKER_LOCATION_UPDATED"] = "mobility.worker-location.updated";
+    RealtimeEventType["MOBILITY_ASSIGNMENT_UPDATED"] = "mobility.assignment.updated";
+})(RealtimeEventType || (exports.RealtimeEventType = RealtimeEventType = {}));
+//# sourceMappingURL=realtime-event-type.enum.js.map

package/dist/cjs/api/realtime/realtime-event-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-event-type.enum.js","sourceRoot":"","sources":["../../../../src/api/realtime/realtime-event-type.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,IAAY,iBAKX;AALD,WAAY,iBAAiB;IACzB,4DAAuC,CAAA;IACvC,kEAA6C,CAAA;IAC7C,0FAAqE,CAAA;IACrE,gFAA2D,CAAA;AAC/D,CAAC,EALW,iBAAiB,iCAAjB,iBAAiB,QAK5B"}

package/dist/cjs/api/realtime/realtime-resource-type.enum.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resource classes the shared realtime gateway can address.
+ *
+ * Closed by design. A publisher cannot invent a room namespace, and the gateway can map every
+ * resource type to the one owning service allowed to issue subscription grants for it.
+ */
+export declare enum RealtimeResourceType {
+    TAXI_RIDE = "taxi.ride",
+    DELIVERY_JOB = "delivery.job",
+    MOBILITY_WORKER = "mobility.worker",
+    MOBILITY_DISPATCH = "mobility.dispatch"
+}
+//# sourceMappingURL=realtime-resource-type.enum.d.ts.map

package/dist/cjs/api/realtime/realtime-resource-type.enum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-resource-type.enum.d.ts","sourceRoot":"","sources":["../../../../src/api/realtime/realtime-resource-type.enum.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,oBAAoB;IAC5B,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,eAAe,oBAAoB;IACnC,iBAAiB,sBAAsB;CAC1C"}

package/dist/cjs/api/realtime/realtime-resource-type.enum.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeResourceType = void 0;
+/**
+ * Resource classes the shared realtime gateway can address.
+ *
+ * Closed by design. A publisher cannot invent a room namespace, and the gateway can map every
+ * resource type to the one owning service allowed to issue subscription grants for it.
+ */
+var RealtimeResourceType;
+(function (RealtimeResourceType) {
+    RealtimeResourceType["TAXI_RIDE"] = "taxi.ride";
+    RealtimeResourceType["DELIVERY_JOB"] = "delivery.job";
+    RealtimeResourceType["MOBILITY_WORKER"] = "mobility.worker";
+    RealtimeResourceType["MOBILITY_DISPATCH"] = "mobility.dispatch";
+})(RealtimeResourceType || (exports.RealtimeResourceType = RealtimeResourceType = {}));
+//# sourceMappingURL=realtime-resource-type.enum.js.map

package/dist/cjs/api/realtime/realtime-resource-type.enum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-resource-type.enum.js","sourceRoot":"","sources":["../../../../src/api/realtime/realtime-resource-type.enum.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC5B,+CAAuB,CAAA;IACvB,qDAA6B,CAAA;IAC7B,2DAAmC,CAAA;IACnC,+DAAuC,CAAA;AAC3C,CAAC,EALW,oBAAoB,oCAApB,oBAAoB,QAK/B"}