@iveri/contracts 0.19.0 → 0.21.0

package/dist/esm/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/esm/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/esm/api/notification/notification.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=notification.type.js.map

package/dist/esm/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/esm/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/esm/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/esm/api/realtime/index.js

@@ -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.js.map

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

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

package/dist/esm/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/esm/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/esm/api/realtime/realtime-event-type.enum.js

@@ -0,0 +1,15 @@
+/**
+ * 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 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 || (RealtimeEventType = {}));
+//# sourceMappingURL=realtime-event-type.enum.js.map

package/dist/esm/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,MAAM,CAAN,IAAY,iBAKX;AALD,WAAY,iBAAiB;IACzB,4DAAuC,CAAA;IACvC,kEAA6C,CAAA;IAC7C,0FAAqE,CAAA;IACrE,gFAA2D,CAAA;AAC/D,CAAC,EALW,iBAAiB,KAAjB,iBAAiB,QAK5B"}

package/dist/esm/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/esm/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/esm/api/realtime/realtime-resource-type.enum.js

@@ -0,0 +1,14 @@
+/**
+ * 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 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 || (RealtimeResourceType = {}));
+//# sourceMappingURL=realtime-resource-type.enum.js.map

package/dist/esm/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,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC5B,+CAAuB,CAAA;IACvB,qDAA6B,CAAA;IAC7B,2DAAmC,CAAA;IACnC,+DAAuC,CAAA;AAC3C,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B"}

package/dist/esm/api/realtime/realtime.type.d.ts

@@ -0,0 +1,106 @@
+import type { IsoDateTime } from '../../type/iso-date-time.type.js';
+import type { UUID } from '../../type/uuid.type.js';
+import type { RealtimeEventType } from './realtime-event-type.enum.js';
+import type { RealtimeResourceType } from './realtime-resource-type.enum.js';
+export declare const REALTIME_CLIENT_EVENT: {
+    readonly SUBSCRIBE: "realtime.subscribe";
+    readonly UNSUBSCRIBE: "realtime.unsubscribe";
+};
+export declare const REALTIME_SERVER_EVENT: {
+    readonly READY: "realtime.ready";
+    readonly SUBSCRIBED: "realtime.subscribed";
+    readonly RESOURCE_UPDATED: "realtime.resource-updated";
+    readonly ERROR: "realtime.error";
+};
+export declare const REALTIME_PROTOCOL_VERSION = 1;
+export declare const MAX_REALTIME_SUBSCRIPTIONS_PER_SOCKET = 100;
+export declare const MAX_REALTIME_EVENT_BYTES: number;
+export declare const DEFAULT_REALTIME_GRANT_TTL_SECONDS = 120;
+export declare const MAX_REALTIME_GRANT_TTL_SECONDS = 300;
+export declare const REALTIME_GRANT_AUDIENCE = "iveri-realtime-subscription";
+export declare const REALTIME_GRANT_ISSUER = "iveri-realtime";
+/**
+ * Requested by an owning API only after it has authorized a person to read the resource.
+ *
+ * `tenantId` is absent: it comes from the API's service token. The grant is bound to
+ * `subjectId`, so copying one to another authenticated socket does not authorize that socket.
+ */
+export interface IssueRealtimeSubscriptionGrantBody {
+    subjectId: UUID;
+    resourceType: RealtimeResourceType;
+    resourceId: UUID;
+    ttlSeconds?: number;
+}
+export interface RealtimeSubscriptionGrantResponse {
+    grant: string;
+    expiresAt: IsoDateTime;
+}
+/** Claims inside a subscription grant signed and verified only by `iveri-realtime`. */
+export interface RealtimeSubscriptionGrantClaims {
+    jti: UUID;
+    sub: UUID;
+    tid: UUID;
+    azp: UUID;
+    resourceType: RealtimeResourceType;
+    resourceId: UUID;
+    purpose: 'subscription';
+    iat: number;
+    exp: number;
+    iss: typeof REALTIME_GRANT_ISSUER;
+    aud: typeof REALTIME_GRANT_AUDIENCE;
+}
+/**
+ * A product service's best-effort change notification.
+ *
+ * The tenant comes from the authenticated service principal and is intentionally absent here.
+ * `idempotencyKey` makes an HTTP retry harmless; no domain data or location coordinates travel
+ * over this channel.
+ */
+export interface PublishRealtimeEventBody {
+    idempotencyKey: UUID;
+    resourceType: RealtimeResourceType;
+    resourceId: UUID;
+    event: RealtimeEventType;
+    version: number;
+    occurredAt: IsoDateTime;
+}
+export interface PublishRealtimeEventResponse {
+    accepted: boolean;
+    duplicate: boolean;
+}
+/** A socket subscribes with grants, never with client-chosen room names or bare resource ids. */
+export interface RealtimeSubscribeRequest {
+    grants: string[];
+}
+export interface RealtimeUnsubscribeRequest {
+    subscriptions: RealtimeSubscription[];
+}
+export interface RealtimeSubscription {
+    resourceType: RealtimeResourceType;
+    resourceId: UUID;
+}
+export interface RealtimeReadyMessage {
+    protocolVersion: typeof REALTIME_PROTOCOL_VERSION;
+}
+export interface RealtimeSubscribedMessage {
+    subscriptions: RealtimeSubscription[];
+}
+export interface RealtimeResourceUpdatedMessage {
+    resourceType: RealtimeResourceType;
+    resourceId: UUID;
+    event: RealtimeEventType;
+    version: number;
+    occurredAt: IsoDateTime;
+}
+export interface RealtimeErrorMessage {
+    code: 'UNAUTHENTICATED' | 'FORBIDDEN' | 'INVALID_GRANT' | 'INVALID_SUBSCRIPTION' | 'SUBSCRIPTION_LIMIT_REACHED';
+    message: string;
+}
+export type RealtimeSubscriptionAck = {
+    ok: true;
+    message: RealtimeSubscribedMessage;
+} | {
+    ok: false;
+    message: RealtimeErrorMessage;
+};
+//# sourceMappingURL=realtime.type.d.ts.map

package/dist/esm/api/realtime/realtime.type.d.ts.map

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

package/dist/esm/api/realtime/realtime.type.js

@@ -0,0 +1,18 @@
+export const REALTIME_CLIENT_EVENT = {
+    SUBSCRIBE: 'realtime.subscribe',
+    UNSUBSCRIBE: 'realtime.unsubscribe',
+};
+export const REALTIME_SERVER_EVENT = {
+    READY: 'realtime.ready',
+    SUBSCRIBED: 'realtime.subscribed',
+    RESOURCE_UPDATED: 'realtime.resource-updated',
+    ERROR: 'realtime.error',
+};
+export const REALTIME_PROTOCOL_VERSION = 1;
+export const MAX_REALTIME_SUBSCRIPTIONS_PER_SOCKET = 100;
+export const MAX_REALTIME_EVENT_BYTES = 4 * 1024;
+export const DEFAULT_REALTIME_GRANT_TTL_SECONDS = 120;
+export const MAX_REALTIME_GRANT_TTL_SECONDS = 300;
+export const REALTIME_GRANT_AUDIENCE = 'iveri-realtime-subscription';
+export const REALTIME_GRANT_ISSUER = 'iveri-realtime';
+//# sourceMappingURL=realtime.type.js.map

package/dist/esm/api/realtime/realtime.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.type.js","sourceRoot":"","sources":["../../../../src/api/realtime/realtime.type.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACjC,SAAS,EAAE,oBAAoB;IAC/B,WAAW,EAAE,sBAAsB;CAC7B,CAAC;AAEX,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACjC,KAAK,EAAE,gBAAgB;IACvB,UAAU,EAAE,qBAAqB;IACjC,gBAAgB,EAAE,2BAA2B;IAC7C,KAAK,EAAE,gBAAgB;CACjB,CAAC;AAEX,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,qCAAqC,GAAG,GAAG,CAAC;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAG,IAAI,CAAC;AACjD,MAAM,CAAC,MAAM,kCAAkC,GAAG,GAAG,CAAC;AACtD,MAAM,CAAC,MAAM,8BAA8B,GAAG,GAAG,CAAC;AAClD,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAC;AACrE,MAAM,CAAC,MAAM,qBAAqB,GAAG,gBAAgB,CAAC"}

package/dist/esm/enum/user-permission.enum.d.ts

@@ -271,7 +271,72 @@ export declare enum UserPermission {
      * rendering an invoice line hold this and nothing else here — they have no reason to read the
      * key catalogue, and separating it keeps a compromised worker from enumerating it.
      */
-    LOCALIZATION_RENDER = "localization:render"
+    LOCALIZATION_RENDER = "localization:render",
+    /**
+     * Submit a notification for delivery.
+     *
+     * **A service permission, and the sharpest one here.** It reaches a real person's mailbox with
+     * text the platform composed, and it is not deliberately absent from the seeded `ADMIN` role
+     * the way `UNIBOX_REALTIME_PUBLISH` is — an admin has no reason to hold it, because there is
+     * nothing for a human to prove by sending a notification to somebody else by hand.
+     *
+     * Note what it does *not* let a holder do: a submission names a **template key**, never a
+     * subject and body. The wording of every notification the platform sends was written by
+     * somebody holding {@link UserPermission.NOTIFICATION_TEMPLATE_MANAGE} and translated by
+     * somebody holding {@link UserPermission.LOCALIZATION_TRANSLATE}. This is the same shape as
+     * `CONDUIT_DISPATCH_SEND` naming an operation rather than a URL, and it is load-bearing for
+     * the same reason: without it, a compromised service principal is an authenticated way to
+     * send arbitrary text from our own domain to any address it likes.
+     */
+    NOTIFICATION_SEND = "notification:send",
+    /**
+     * Read **your own** in-app inbox, and mark your own rows read.
+     *
+     * Scoped to the calling principal by the endpoint, not by this permission — there is no
+     * variant that reads somebody else's inbox, because a notification is addressed to one person
+     * and reading another's is reading their mail. It belongs in every human role, including the
+     * narrowest, for the same reason: without it a member cannot see what the product is telling
+     * them.
+     */
+    NOTIFICATION_READ = "notification:read",
+    /** Read the tenant's notification templates and the platform's built-in ones. */
+    NOTIFICATION_TEMPLATE_READ = "notification:template:read",
+    /**
+     * Override a built-in template, or define a new one — which channels a notification type
+     * reaches and which message keys it renders.
+     *
+     * Configuration that decides what every future notification of a type says, including the
+     * password-reset email. Overriding one badly is a way to stop people getting back into their
+     * accounts, so it is separated from reading for the same reason `CONDUIT_CONNECTOR_MANAGE` is.
+     */
+    NOTIFICATION_TEMPLATE_MANAGE = "notification:template:manage",
+    /**
+     * Read the delivery log and the dead-letter queue, including each delivery's last error.
+     *
+     * Grouped with reading rather than with operating the queue, and it is closer to a data-read
+     * permission than a config one: the log names who was written to and about what.
+     */
+    NOTIFICATION_DELIVERY_READ = "notification:delivery:read",
+    /**
+     * Redrive a dead-lettered delivery, or cancel one still pending.
+     *
+     * Separate from reading because it causes a message to be sent to a person rather than
+     * returning a row — and because redriving a backlog is a way to mail somebody the same thing
+     * fifty times an hour after an outage.
+     */
+    NOTIFICATION_DELIVERY_OPERATE = "notification:delivery:operate",
+    /**
+     * Ask the shared gateway to issue a short-lived subscription grant after the owning API has
+     * authorized a person to read one resource. Service-only: a human may consume a grant but
+     * must never mint one.
+     */
+    REALTIME_SUBSCRIPTION_GRANT_ISSUE = "realtime:subscription-grant:issue",
+    /**
+     * Publish an identifier-only resource change. Separate from grant issue because announcing a
+     * write and authorizing a read are distinct powers and a service may legitimately need one
+     * without the other.
+     */
+    REALTIME_EVENT_PUBLISH = "realtime:event:publish"
 }
 /**
  * Every member, for seeding the owner role and validating custom-role input.

package/dist/esm/enum/user-permission.enum.d.ts.map

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

package/dist/esm/enum/user-permission.enum.js

@@ -316,6 +316,73 @@ export var UserPermission;
      * key catalogue, and separating it keeps a compromised worker from enumerating it.
      */
     UserPermission["LOCALIZATION_RENDER"] = "localization:render";
+    // ══ iveri-notification-api ══════════════════════════════════════════════
+    /**
+     * Submit a notification for delivery.
+     *
+     * **A service permission, and the sharpest one here.** It reaches a real person's mailbox with
+     * text the platform composed, and it is not deliberately absent from the seeded `ADMIN` role
+     * the way `UNIBOX_REALTIME_PUBLISH` is — an admin has no reason to hold it, because there is
+     * nothing for a human to prove by sending a notification to somebody else by hand.
+     *
+     * Note what it does *not* let a holder do: a submission names a **template key**, never a
+     * subject and body. The wording of every notification the platform sends was written by
+     * somebody holding {@link UserPermission.NOTIFICATION_TEMPLATE_MANAGE} and translated by
+     * somebody holding {@link UserPermission.LOCALIZATION_TRANSLATE}. This is the same shape as
+     * `CONDUIT_DISPATCH_SEND` naming an operation rather than a URL, and it is load-bearing for
+     * the same reason: without it, a compromised service principal is an authenticated way to
+     * send arbitrary text from our own domain to any address it likes.
+     */
+    UserPermission["NOTIFICATION_SEND"] = "notification:send";
+    /**
+     * Read **your own** in-app inbox, and mark your own rows read.
+     *
+     * Scoped to the calling principal by the endpoint, not by this permission — there is no
+     * variant that reads somebody else's inbox, because a notification is addressed to one person
+     * and reading another's is reading their mail. It belongs in every human role, including the
+     * narrowest, for the same reason: without it a member cannot see what the product is telling
+     * them.
+     */
+    UserPermission["NOTIFICATION_READ"] = "notification:read";
+    /** Read the tenant's notification templates and the platform's built-in ones. */
+    UserPermission["NOTIFICATION_TEMPLATE_READ"] = "notification:template:read";
+    /**
+     * Override a built-in template, or define a new one — which channels a notification type
+     * reaches and which message keys it renders.
+     *
+     * Configuration that decides what every future notification of a type says, including the
+     * password-reset email. Overriding one badly is a way to stop people getting back into their
+     * accounts, so it is separated from reading for the same reason `CONDUIT_CONNECTOR_MANAGE` is.
+     */
+    UserPermission["NOTIFICATION_TEMPLATE_MANAGE"] = "notification:template:manage";
+    /**
+     * Read the delivery log and the dead-letter queue, including each delivery's last error.
+     *
+     * Grouped with reading rather than with operating the queue, and it is closer to a data-read
+     * permission than a config one: the log names who was written to and about what.
+     */
+    UserPermission["NOTIFICATION_DELIVERY_READ"] = "notification:delivery:read";
+    /**
+     * Redrive a dead-lettered delivery, or cancel one still pending.
+     *
+     * Separate from reading because it causes a message to be sent to a person rather than
+     * returning a row — and because redriving a backlog is a way to mail somebody the same thing
+     * fifty times an hour after an outage.
+     */
+    UserPermission["NOTIFICATION_DELIVERY_OPERATE"] = "notification:delivery:operate";
+    // ══ iveri-realtime ══════════════════════════════════════════════════════
+    /**
+     * Ask the shared gateway to issue a short-lived subscription grant after the owning API has
+     * authorized a person to read one resource. Service-only: a human may consume a grant but
+     * must never mint one.
+     */
+    UserPermission["REALTIME_SUBSCRIPTION_GRANT_ISSUE"] = "realtime:subscription-grant:issue";
+    /**
+     * Publish an identifier-only resource change. Separate from grant issue because announcing a
+     * write and authorizing a read are distinct powers and a service may legitimately need one
+     * without the other.
+     */
+    UserPermission["REALTIME_EVENT_PUBLISH"] = "realtime:event:publish";
 })(UserPermission || (UserPermission = {}));
 /**
  * Every member, for seeding the owner role and validating custom-role input.

package/dist/esm/enum/user-permission.enum.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iveri/contracts",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Wire contracts shared by every Iveri backend and frontend. Zero runtime dependencies.",
   "license": "MIT",
   "repository": {
@@ -49,6 +49,16 @@
       "import": "./dist/esm/api/localization/index.js",
       "require": "./dist/cjs/api/localization/index.js"
     },
+    "./notification": {
+      "types": "./dist/cjs/api/notification/index.d.ts",
+      "import": "./dist/esm/api/notification/index.js",
+      "require": "./dist/cjs/api/notification/index.js"
+    },
+    "./realtime": {
+      "types": "./dist/cjs/api/realtime/index.d.ts",
+      "import": "./dist/esm/api/realtime/index.js",
+      "require": "./dist/cjs/api/realtime/index.js"
+    },
     "./package.json": "./package.json"
   },
   "typesVersions": {
@@ -62,6 +72,12 @@
       "localization": [
         "./dist/cjs/api/localization/index.d.ts"
       ],
+      "notification": [
+        "./dist/cjs/api/notification/index.d.ts"
+      ],
+      "realtime": [
+        "./dist/cjs/api/realtime/index.d.ts"
+      ],
       "unibox": [
         "./dist/cjs/api/unibox/index.d.ts"
       ],