@mpgd/platform 0.22.0 → 0.23.0

package/dist/notifications-policy.d.ts

@@ -0,0 +1,885 @@
+import type { tags } from 'typia';
+import type { PlatformEvidenceEnvelope } from './index.js';
+import type { NotificationCapabilities, NotificationChannel, NotificationPermissionAllowance, NotificationPermissionScope, NotificationPermissionSnapshot, NotificationPermissionState, NotificationProviderId, NotificationPurpose, NotificationRemoteContent, NotificationTopicId } from './notifications-contract.js';
+/**
+* Notifications v2 pure policy (RFC "Topic catalog", "Reminders", "Server",
+* and "Advertising rules"): topic declarations and their rules, consent
+* records, deployment settings, provider registry entries, the delivery gate
+* `evaluateNotificationDelivery` with the advertising rendering, input bounds
+* and idempotency fingerprints, reminder routing and the client-evaluable
+* reminder checks, the Asia/Seoul night window and quiet hours, and the
+* consent notices. No Phaser, DOM, network, or SDK imports, and no state
+* beyond a bounded cache of `Intl` formatters: every function decides from its
+* arguments. `./notifications` re-exports it.
+*/
+type NonEmptyString = string & tags.MinLength<1>;
+type PositiveInteger = number & tags.Type<'uint32'> & tags.Minimum<1>;
+type IsoDateTime = string & tags.Format<'date-time'>;
+export interface NotificationTopicCopy {
+  readonly title: NonEmptyString;
+  readonly body: NonEmptyString;
+}
+export interface NotificationTopicFrequency {
+  /** Deliveries of the topic to one player within any 24 hours. */
+  readonly maxPerDay: PositiveInteger;
+}
+/** A wall-clock time `HH:MM`, 00:00 to 23:59. */
+export type NotificationClockTime = string & tags.Pattern<'^(?:[01][0-9]|2[0-3]):[0-5][0-9]$'>;
+/** Holds sends from `start` (inclusive) to `end` (exclusive); `start` after `end` spans midnight. */
+export interface NotificationQuietHours {
+  readonly start: NotificationClockTime;
+  readonly end: NotificationClockTime;
+}
+/** One target's mapping fields, for example `templateSetCode` or approved `title` and `body`. */
+export type NotificationTopicMapping = Readonly<Record<string, string | number | boolean>>;
+/** A topic as the catalog declares it, independent of any target. */
+export interface NotificationTopicDefinition {
+  readonly id: NonEmptyString;
+  readonly purpose: NotificationPurpose;
+  readonly channels: readonly NotificationChannel[] & tags.MinItems<1>;
+  /** The route the open leads to; it must pass `isRootRelativeNotificationRoute`. */
+  readonly route: NonEmptyString;
+  /** Required for `advertising`: the screen where the player withdraws advertising consent. */
+  readonly optOutRoute?: NonEmptyString;
+  /** Copy per locale; placeholders use `{{name}}`. */
+  readonly copy?: Readonly<Record<string, NotificationTopicCopy>>;
+  readonly frequency?: NotificationTopicFrequency;
+  readonly quietHours?: NotificationQuietHours;
+  /**
+  * `false`: a send held by the night window or the topic's quiet hours is
+  * suppressed instead of deferred. Default `true`.
+  */
+  readonly deferrable?: boolean;
+}
+/** A topic resolved for one provider: the definition plus that target's mapping. */
+export interface NotificationTopicDeclaration extends NotificationTopicDefinition {
+  readonly mapping?: NotificationTopicMapping;
+}
+/** Template data and routing context of a send or reminder (RFC input bounds). */
+export type NotificationTemplateData = Readonly<Record<string, string | number | boolean>>;
+/** A broken topic rule, for example `{ path: 'topics[2].optOutRoute', message: '…' }`. */
+export interface NotificationTopicIssue {
+  readonly path: string;
+  readonly message: string;
+}
+/**
+* Whether a topic's mapping declares that the host needs no agreement for it
+* (an Apps in Toss `service` template without an agreement statement): it
+* reads `granted`, never prompts, is never recorded, and passes gate step 3.
+* A provider's answer that the recipient has not agreed is still recorded,
+* but it does not stop sends, because nothing could ask the player again:
+* the host decides each send.
+*/
+export declare function notificationTopicNeedsNoAgreement(topic: Pick<NotificationTopicDeclaration, 'mapping'>): boolean;
+/**
+* Whether `route` is a root-relative route on the game's origin, at most 2048
+* characters, and already in the form `normalizeRootRelativeRoute` from
+* `@mpgd/platform/routes` returns. That is the rule share links and v1
+* notification deep links follow, so neither a URL parser nor a client that
+* percent-decodes the path once reads the route as another host
+* (`//evil.example/x`, `/%2e//evil.example/x`, `/%2F%2Fevil.example/x`).
+* A route with another normalized form is refused rather than rewritten, so
+* the route a topic declares is the route a player opens: dot segments
+* (`/a/../b`), a backslash in the path, an empty `?` or `#`, and characters a
+* URL serializes percent-encoded (`/é`, `/a b`) all change the form.
+*/
+export declare function isRootRelativeNotificationRoute(route: string): boolean;
+/**
+* The error for a route `isRootRelativeNotificationRoute` refuses, about
+* `subject` (`The local reminder route`), or `undefined` when it passes. A
+* route with another normalized form names that form, so the caller can
+* write it instead.
+*/
+export declare function notificationRouteError(subject: string, route: string): string | undefined;
+/**
+* The rules a topic definition must meet on its own (RFC "Topic catalog"):
+* a trimmed id that is not `__proto__`, channels that do not repeat, no
+* `local` channel for advertising, root-relative `route` and `optOutRoute`, an
+* `optOutRoute` for advertising, and quiet hours that do not start and end at
+* the same time. `path` prefixes each issue's path.
+*/
+export declare function notificationTopicDefinitionIssues(topic: NotificationTopicDefinition, path?: string): NotificationTopicIssue[];
+export type NotificationConsentKind = 'delivery-permission' | 'host-agreement' | 'topic-preference' | 'advertising' | 'night';
+/** Permission states the runtime records: decided ones, never `prompt`, `unknown`, `action-required`, or `unsupported`. */
+export type NotificationRecordablePermissionState = Exclude<NotificationPermissionState, 'prompt' | 'unknown' | 'action-required' | 'unsupported'>;
+export type NotificationConsentState = NotificationRecordablePermissionState | 'withdrawn';
+/** `provider`: a delivery provider's answer that the recipient has not agreed. */
+export type NotificationConsentSource = 'client-report' | 'player' | 'provider';
+/**
+* One consent record. The per-kind shapes encode the RFC rules: permission
+* kinds carry a permission state, a `delivery-permission` record comes from a
+* client report or a player revocation, a `host-agreement` record from a
+* client report or a provider answer, `host-agreement` and `topic-preference`
+* name their topic, the player-authored kinds carry `granted` or `withdrawn`,
+* and advertising and night consent carry the consent text version. The
+* backend stamps `at` with its own clock.
+*/
+export type NotificationConsentRecord = {
+  readonly kind: 'delivery-permission';
+  readonly topic?: never;
+  readonly state: NotificationRecordablePermissionState;
+  readonly source: 'client-report' | 'player';
+  readonly at: IsoDateTime;
+  readonly evidence?: PlatformEvidenceEnvelope;
+  readonly textVersion?: never;
+} | {
+  readonly kind: 'host-agreement';
+  readonly topic: NonEmptyString;
+  readonly state: NotificationRecordablePermissionState;
+  readonly source: 'client-report' | 'provider';
+  readonly at: IsoDateTime;
+  readonly evidence?: PlatformEvidenceEnvelope;
+  readonly textVersion?: never;
+} | {
+  readonly kind: 'topic-preference';
+  readonly topic: NonEmptyString;
+  readonly state: 'granted' | 'withdrawn';
+  readonly source: 'player';
+  readonly at: IsoDateTime;
+  readonly evidence?: never;
+  readonly textVersion?: never;
+} | {
+  readonly kind: 'advertising' | 'night';
+  readonly topic?: never;
+  readonly state: 'granted' | 'withdrawn';
+  readonly source: 'player';
+  readonly at: IsoDateTime;
+  readonly evidence?: never;
+  /** Consent text version the player agreed to or withdrew from. */
+  readonly textVersion: NonEmptyString;
+};
+export declare const recordableNotificationPermissionStates: readonly ["granted", "prompt-with-rationale", "denied", "blocked"];
+/** Whether the runtime records this state: a decided state, never prompt, unknown, action-required, or unsupported. */
+export declare function isRecordableNotificationPermissionState(state: NotificationPermissionState): state is NotificationRecordablePermissionState;
+/** The consent kind that holds delivery permission for a permission scope. */
+export declare function notificationPermissionConsentKind(scope: NotificationPermissionScope): 'delivery-permission' | 'host-agreement';
+/** A topic's state in a snapshot: its own entry, else the app state, else `unknown`. */
+export declare function notificationPermissionStateOf(snapshot: NotificationPermissionSnapshot, topic: NotificationTopicId): NotificationPermissionState;
+/**
+* The latest record of `kind` for exactly `topic` in `records` (oldest first):
+* with `topic`, only records naming that topic match; without it, only
+* records without a topic (app-scope permission, advertising, night) match.
+*/
+export declare function latestNotificationConsent(records: readonly NotificationConsentRecord[], kind: NotificationConsentKind, topic?: NotificationTopicId): NotificationConsentRecord | undefined;
+/** `kr` applies the Korean advertising rules to every recipient; `none` keeps consent and the opt-out route only. */
+export type NotificationAdvertisingRules = 'kr' | 'none';
+/** The deployment's advertising sender, which every advertising send carries under `kr`. */
+export interface NotificationAdvertisingSender {
+  /** The sender's name; leave it out only when it equals the app's name. */
+  readonly name?: NonEmptyString;
+  /** The phone number or address the law requires. */
+  readonly contact: NonEmptyString;
+}
+export interface NotificationDeployment {
+  /**
+  * Required when the catalog has an `advertising` topic: the gate refuses to
+  * evaluate an advertising send without it.
+  */
+  readonly advertisingRules?: NotificationAdvertisingRules;
+  readonly advertisingSender?: NotificationAdvertisingSender;
+  /** The free-of-charge opt-out line; `무료 수신거부: 수신거부 버튼` when absent or blank. */
+  readonly advertisingOptOutLine?: NonEmptyString;
+  /** IANA zone for recipients that registered none; Asia/Seoul when absent. */
+  readonly timeZone?: NonEmptyString;
+}
+export declare const notificationDefaultOptOutLine = "\uBB34\uB8CC \uC218\uC2E0\uAC70\uBD80: \uC218\uC2E0\uAC70\uBD80 \uBC84\uD2BC";
+export declare const notificationDefaultDeploymentTimeZone = "Asia/Seoul";
+/** The deployment's advertising settings as gate step 8 reads them under `kr`. */
+export interface NotificationAdvertisingSettings {
+  /** The sender, trimmed, without a blank name; absent when there is no contact to send. */
+  readonly sender?: NotificationAdvertisingSender;
+  /** The opt-out line, trimmed; the default when it is absent or blank. */
+  readonly optOutLine: string;
+  /** Each field the gate cannot use as written. */
+  readonly issues: readonly NotificationTopicIssue[];
+}
+/**
+* How gate step 8 reads the deployment under `kr`; the catalog validator
+* reports its `issues`, so both read the settings the same way. The sender's
+* contact and name and the opt-out line are trimmed. A missing sender or a
+* blank contact leaves `sender` absent, which suppresses every advertisement
+* as `advertising-sender-missing`; a blank name is left out of the sender
+* line, and a blank opt-out line gives way to the default. `path` prefixes
+* each issue's path.
+*/
+export declare function resolveNotificationAdvertisingSettings(deployment: NotificationDeployment | undefined, path?: string): NotificationAdvertisingSettings;
+/** A per-recipient or app-wide count within a rolling window. */
+export interface NotificationProviderLimit {
+  readonly count: PositiveInteger;
+  readonly windowSeconds: PositiveInteger;
+}
+/**
+* A delivery provider's server-side registry entry, the gate's only
+* capability input. The runtime compares its provider's capabilities with it
+* at start.
+*/
+export interface NotificationDeliveryProviderEntry {
+  readonly provider: NotificationProviderId;
+  readonly purposes: readonly NotificationPurpose[];
+  readonly addressing: 'device' | 'platform-user';
+  readonly content: NotificationRemoteContent;
+  readonly permission: {
+    readonly scope: NotificationPermissionScope;
+    readonly serverReadable: boolean;
+    readonly allowance: NotificationPermissionAllowance;
+  };
+  /** Per-recipient limits; a window of a day or longer suppresses, a shorter one defers. */
+  readonly limits?: readonly NotificationProviderLimit[];
+  /** App-wide dispatch rate the scheduler keeps to. */
+  readonly rate?: NotificationProviderLimit;
+  /** Whether a send can carry an expiry, which advertising needs under the Korean rules. */
+  readonly expiry: boolean;
+  /** Whether a send can carry the advertising opt-out action. */
+  readonly actions: boolean;
+  /** Whether each send needs a post or comment link (Devvit). */
+  readonly link: boolean;
+  /** The mapping fields this provider needs in each catalog topic. */
+  readonly mappingFields: readonly string[];
+}
+/** How the catalog validator checks one mapping field of a provider. */
+export interface NotificationMappingField {
+  readonly required: boolean;
+  /** Longest accepted string in Unicode code points. */
+  readonly maxLength?: PositiveInteger;
+  /** The accepted string values, when the field is an enumeration. */
+  readonly values?: readonly string[];
+  /** A pattern every string value must match, such as Devvit's `t3_`/`t1_` ids. */
+  readonly pattern?: string;
+}
+/** A registry entry with the mapping-field rules the catalog validator applies. */
+export interface NotificationProviderRegistryEntry extends NotificationDeliveryProviderEntry {
+  readonly mapping: Readonly<Record<string, NotificationMappingField>>;
+}
+/**
+* Reference registry entries for the RFC provider profiles. They are reference
+* values: a project registers its own entries under its own provider ids, and
+* the P-phase providers own the final values.
+*/
+export declare const referenceNotificationProviders: Readonly<Record<'fcm' | 'apps-in-toss' | 'devvit', NotificationProviderRegistryEntry>>;
+/** Reference target names and the provider each one enables. */
+export declare const referenceNotificationTargetProviders: Readonly<Record<string, keyof typeof referenceNotificationProviders>>;
+/**
+* Where a client provider's capabilities disagree with the provider's registry
+* entry, or `undefined` when they agree. The runtime compares them at start,
+* and a mismatch makes the provider `configuration-required`.
+*/
+export declare function notificationRegistryMismatch(capabilities: NotificationCapabilities, entry: NotificationDeliveryProviderEntry): string | undefined;
+export type NotificationDeliveryStatus = 'delivered' | 'suppressed' | 'deferred' | 'unavailable' | 'in-flight';
+export type NotificationSuppressionReason = 'topic-unknown' | 'channel-unsupported' | 'purpose-unsupported' | 'permission-denied' | 'agreement-missing' | 'allowance-exhausted' | 'request-missing' | 'preference-off' | 'advertising-consent-missing' | 'night-consent-missing' | 'quiet-hours' | 'frequency-capped' | 'provider-limit' | 'advertising-sender-missing';
+/** Why a send waits: a time window, a short provider limit, or a provider's rate-limit answer. */
+export type NotificationDeferralReason = 'night-window' | 'quiet-hours' | 'provider-limit' | 'provider-rate-limited';
+export type NotificationUnavailableReason = 'no-endpoint' | 'link-missing' | 'endpoint-invalid' | 'provider-rejected' | 'provider-rate-limited';
+export declare const notificationSuppressionReasons: readonly ["topic-unknown", "channel-unsupported", "purpose-unsupported", "permission-denied", "agreement-missing", "allowance-exhausted", "request-missing", "preference-off", "advertising-consent-missing", "night-consent-missing", "quiet-hours", "frequency-capped", "provider-limit", "advertising-sender-missing"];
+export type NotificationDeliveryRefusal = {
+  readonly status: 'suppressed';
+  readonly reason: NotificationSuppressionReason;
+} | {
+  readonly status: 'deferred';
+  readonly reason: NotificationDeferralReason;
+  readonly until: IsoDateTime;
+} | {
+  readonly status: 'unavailable';
+  readonly reason: NotificationUnavailableReason;
+};
+/**
+* The recorded result of one send. `alreadyProcessed` marks a key that had
+* already delivered; `in-flight` answers a key whose delivery a claim holds.
+*/
+export type NotificationDeliveryOutcome = {
+  readonly status: 'delivered';
+  readonly alreadyProcessed: boolean;
+} | {
+  readonly status: 'in-flight';
+} | NotificationDeliveryRefusal;
+/** An action a notification carries; under `kr`, advertising carries the opt-out action. */
+export interface NotificationAction {
+  readonly id: NonEmptyString;
+  readonly title: NonEmptyString;
+  /** A root-relative route the action opens. */
+  readonly route: NonEmptyString;
+}
+/** The advertising opt-out action under the Korean rules. */
+export declare const notificationAdvertisingOptOutActionId = "advertising-opt-out";
+/** What a provider sends; `title` and `body` are absent when the host template carries the copy. */
+export interface NotificationDeliveryContent {
+  readonly title?: string;
+  readonly body?: string;
+  readonly route: string;
+  /** Under `kr`, advertising carries the opt-out action. */
+  readonly actions?: readonly NotificationAction[];
+  readonly source: 'mapping' | 'host-template' | 'catalog';
+}
+/**
+* The gate's answer: `allowed` with the content to send and, for advertising
+* without night consent under `kr`, the expiry at the next 21:00 KST; or the
+* refusal to record.
+*/
+export type NotificationDeliveryDecision = {
+  readonly status: 'allowed';
+  readonly content: NotificationDeliveryContent;
+  readonly expiresAt?: IsoDateTime;
+} | NotificationDeliveryRefusal;
+/** A send already delivered to the recipient. */
+export interface NotificationDeliveryHistoryEntry {
+  readonly provider: NotificationProviderId;
+  readonly topic: NotificationTopicId;
+  readonly at: string;
+}
+export interface EvaluateNotificationDeliveryInput {
+  /** The provider's registry entry; the gate never reads the client's declaration. */
+  readonly entry: NotificationDeliveryProviderEntry;
+  readonly deployment?: NotificationDeployment;
+  /** The send's topic as declared for this provider; absent when the catalog does not declare it. */
+  readonly topic: NotificationTopicDeclaration | undefined;
+  /**
+  * Gate step 2: this recipient resolved, a valid endpoint for
+  * `addressing: 'device'` or an authenticated platform identity for
+  * `'platform-user'`.
+  */
+  readonly recipientResolved: boolean;
+  /** The send's post or comment link, for providers whose entry sets `link`. */
+  readonly link?: string;
+  /** The recipient's consent records, oldest first. */
+  readonly consent: readonly NotificationConsentRecord[];
+  /** The host's answer at send time; required when the entry is server-readable. */
+  readonly serverPermission?: NotificationPermissionState;
+  /**
+  * For `addressing: 'device'`: the permission this endpoint's latest
+  * registration reported. Anything but `granted`, or none, does not deliver.
+  */
+  readonly endpointPermission?: NotificationPermissionState;
+  /**
+  * Sends delivered to the recipient, oldest first (the gate sorts a copy of
+  * a history out of order, so the order never changes the answer): at least
+  * those within the longest limit window and, for a per-send provider, every
+  * send of the topic since the first recorded acceptance. A backend that
+  * reserves acceptances atomically with the delivery claim also passes its
+  * in-flight sends.
+  */
+  readonly history: readonly NotificationDeliveryHistoryEntry[];
+  /** The time of the provider call, RFC 3339 with an offset. */
+  readonly at: string;
+  /** The recipient's registered zone; the deployment's zone when absent. */
+  readonly timeZone?: string;
+  /** The delivery's locale, else the recipient's registered locale. */
+  readonly locale?: string;
+  readonly defaultLocale: string;
+  readonly templateData?: NotificationTemplateData;
+}
+/**
+* The policy gate, evaluated per recipient immediately before the provider
+* call: after any queue, and for a scheduled reminder or a deferred send when
+* it comes due (the caller looks up the idempotency key first). The steps run
+* in order and the first failure decides:
+*
+* 1. the topic is declared (`topic-unknown`), has the `remote` channel
+*    (`channel-unsupported`), and the entry delivers its purpose, advertising
+*    only as free-form content and, under `kr`, with an expiry and the opt-out
+*    action (`purpose-unsupported`);
+* 2. the recipient resolves (`unavailable: no-endpoint`), with a link where
+*    the entry needs one (`unavailable: link-missing`);
+* 3. delivery permission is positively `granted`: the send-time host answer on
+*    a server-readable provider, the endpoint's registered permission for
+*    device addressing, or a latest `delivery-permission` record of `granted`
+*    for an app-scope platform-user provider; a topic-scope provider also
+*    needs a latest `host-agreement` of `granted` unless the topic needs no
+*    agreement (then the host decides each send, after a provider's denial
+*    too), and a per-send provider an unreserved acceptance
+*    (`permission-denied`, `agreement-missing`, `allowance-exhausted`);
+* 4. the topic preference, only `topic-preference` records, the latest winning
+*    (`request-missing`, `preference-off`);
+* 5. advertising consent (`advertising-consent-missing`);
+* 6. the night window under `kr` and the topic's quiet hours in the
+*    recipient's zone (`deferred` until the holding window ends, `suppressed`
+*    for a topic that is not deferrable, or `night-consent-missing` when the
+*    windows leave no time to send);
+* 7. the topic frequency cap and the entry's limits over rolling windows
+*    (`frequency-capped`, `provider-limit`; a limit window shorter than a day
+*    defers instead);
+* 8. under `kr`, advertising needs the deployment's sender with a contact
+*    that is not blank (`advertising-sender-missing`) and is rendered with the
+*    label, the sender line, the opt-out line, and the opt-out action, the
+*    settings read by `resolveNotificationAdvertisingSettings`.
+*
+* Caller errors throw a `TypeError` instead of deciding: a missing
+* `serverPermission`, an advertising topic without the deployment's
+* `advertisingRules` (the gate fails closed rather than guess them), an
+* unknown time zone, missing copy or template data, an advertising topic
+* without `optOutRoute`, and a route or opt-out route that is not
+* root-relative.
+*/
+export declare function evaluateNotificationDelivery(input: EvaluateNotificationDeliveryInput): NotificationDeliveryDecision;
+/**
+* A text's `{{name}}` placeholders, as `fillNotificationTemplate` reads them,
+* and whether a brace is left once they are taken out. `{name}`, `{{name}`,
+* `{{a.b}}`, and full-width braces fill nothing and would reach the player as
+* written.
+*/
+export declare function readNotificationTemplate(text: string): {
+  readonly placeholders: readonly string[];
+  readonly strayBrace: boolean;
+};
+/** Fills `{{name}}` placeholders from `data`; a placeholder without a value is a caller error. */
+export declare function fillNotificationTemplate(text: string, data?: NotificationTemplateData): string;
+/**
+* The topic's copy for `locale`: that locale, then its language (`en` for
+* `en-US` or `en_US`), then `defaultLocale`, each matched without regard to
+* case as locale tags are; `undefined` when the topic has none of them.
+*/
+export declare function findNotificationCopy(topic: Pick<NotificationTopicDefinition, 'copy'>, locale: string | undefined, defaultLocale: string): NotificationTopicCopy | undefined;
+export interface ResolveNotificationContentInput {
+  readonly topic: NotificationTopicDeclaration;
+  readonly content: NotificationRemoteContent;
+  /** The delivery's locale, else the recipient's registered locale. */
+  readonly locale?: string;
+  readonly defaultLocale: string;
+  readonly templateData?: NotificationTemplateData;
+}
+/**
+* Content precedence (RFC "Topic catalog"): the target mapping when it
+* carries its own `title` and `body`, the host template when
+* `remote.content` is `host-template`, and otherwise the catalog copy for the
+* locale (`findNotificationCopy`). No copy, a missing template value, and a
+* route that `isRootRelativeNotificationRoute` refuses are caller errors, so
+* a catalog that skipped validation still never sends another host's link.
+*/
+export declare function resolveNotificationContent(input: ResolveNotificationContentInput): NotificationDeliveryContent;
+/** The advertising label every advertising title and body starts with under `kr`. */
+export declare const notificationAdvertisingPrefix = "(\uAD11\uACE0)";
+/**
+* `(광고)`, one space, and the text without leading whitespace. Text that
+* already starts with the label keeps it once, followed by one space.
+*/
+export declare function applyNotificationAdvertisingLabel(text: string): string;
+/**
+* Gate step 8 under `kr`: the title starts with `(광고) `; the body starts with
+* `(광고) ` and the sender line (`name contact`, or `contact` alone), then the
+* copy on the next line, then the opt-out line on the last line; and the
+* message carries the opt-out action that opens the topic's `optOutRoute`.
+* The sender and the opt-out line are read as
+* `resolveNotificationAdvertisingSettings` reads them; a blank contact is a
+* caller error.
+*/
+export declare function renderNotificationAdvertisement(topic: NotificationTopicDefinition, content: NotificationDeliveryContent, sender: NotificationAdvertisingSender, optOutLine?: string): NotificationDeliveryContent;
+/** v1's input bounds, which v2 keeps. */
+export declare const notificationInputBounds: Readonly<{
+  readonly keyLength: 2048;
+  readonly entries: 128;
+  readonly stringLength: 16384;
+}>;
+/** Key prefixes the scheduler reserves; a caller's send key may not start with one. */
+export declare const notificationReservedKeyPrefixes: readonly ["reminder:", "notice:"];
+/** Why `key` is not a valid send or reminder key, or `undefined`. */
+export declare function notificationKeyIssue(key: string): string | undefined;
+/** The reserved prefix `key` starts with, if any. */
+export declare function notificationReservedKeyPrefix(key: string): string | undefined;
+/**
+* Why `data` is not valid template data or routing data, or `undefined`: at
+* most 128 entries of strings, finite numbers, or booleans, each string at most
+* 16,384 characters. With `stringsOnly`, every value must be a string (routing
+* `data`).
+*/
+export declare function notificationTemplateDataIssue(data: unknown, options?: {
+  readonly stringsOnly?: boolean;
+}): string | undefined;
+/** The request a send key is bound to (RFC "Policy gate", binding). */
+export interface NotificationSendRequest {
+  readonly player: string;
+  readonly provider?: string;
+  readonly topic: string;
+  readonly templateData?: NotificationTemplateData;
+  readonly data?: Readonly<Record<string, string>>;
+  readonly locale?: string;
+  readonly link?: string;
+}
+/**
+* The fingerprint a stored key is bound to: the player, provider, topic,
+* template data, routing data, locale, and link, in a canonical JSON form. The
+* resolved address is left out, so a replay after a token rotation still
+* matches.
+*/
+export declare function notificationSendFingerprint(request: NotificationSendRequest): string;
+export type NotificationReminderRoute = 'local' | 'remote' | 'none';
+/**
+* A reminder's answer (RFC `ReminderResult`). The local route reports the
+* gate's `permission-denied` as `permission-required`.
+*/
+export type NotificationReminderStatus = 'scheduled' | 'replaced' | 'cancelled' | 'permission-required' | 'request-missing' | 'preference-off' | 'advertising-consent-missing' | 'frequency-capped' | 'quiet-hours' | 'capacity-exceeded' | 'action-required' | 'unavailable';
+export interface ReminderResult {
+  readonly route: NotificationReminderRoute;
+  readonly status: NotificationReminderStatus;
+}
+/**
+* Reminder routing: local when the topic has the `local` channel, is not
+* `advertising`, and the provider supports local notifications; else remote
+* when the topic has the `remote` channel and the provider supports remote
+* delivery; else none. A reminder never takes both routes, and an advertising
+* topic never takes the local route even when a catalog that skipped
+* validation declares it.
+*/
+export declare function routeNotificationReminder(topic: Pick<NotificationTopicDefinition, 'channels' | 'purpose'>, capabilities: Pick<NotificationCapabilities, 'local' | 'remote'>): NotificationReminderRoute;
+export interface EvaluateLocalNotificationReminderInput {
+  readonly topic: NotificationTopicDefinition;
+  /** The topic's effective permission: the host read, or the latest record when the host answers `unknown`. */
+  readonly permission: NotificationPermissionState;
+  /** The player's consent records, oldest first. */
+  readonly consent: readonly NotificationConsentRecord[];
+  readonly fireAt: string;
+  /** Quiet-hours zone: the registered zone, else the deployment's zone. */
+  readonly timeZone: string;
+  /** The topic's other pending local reminders, for `frequency.maxPerDay`. */
+  readonly pending?: readonly {
+    readonly fireAt: string;
+  }[];
+}
+export type LocalNotificationReminderDecision = {
+  readonly status: 'schedule';
+  readonly fireAt: string;
+} | {
+  readonly status: 'permission-required' | 'request-missing' | 'preference-off' | 'quiet-hours' | 'frequency-capped';
+};
+/**
+* The gate steps a client can evaluate before scheduling a local reminder, in
+* order: delivery permission (`permission-required`), the topic preference,
+* the topic's quiet hours, and `frequency.maxPerDay` over the topic's pending
+* local reminders within any 24 hours (`frequency-capped`). As at gate step
+* 6, a `fireAt` inside the quiet hours moves to the first time outside them,
+* hopping over a window that a clock change makes end inside another, and a
+* topic with `deferrable: false` is not scheduled there (`quiet-hours`).
+* Without quiet hours `fireAt` is kept. The night window does not apply,
+* because advertising never takes the local route.
+*/
+export declare function evaluateLocalNotificationReminder(input: EvaluateLocalNotificationReminderInput): LocalNotificationReminderDecision;
+export interface EvaluateNotificationReminderConsentInput {
+  readonly entry: NotificationDeliveryProviderEntry;
+  readonly topic: NotificationTopicDeclaration;
+  readonly consent: readonly NotificationConsentRecord[];
+  /** The host's answer for a server-readable provider. */
+  readonly serverPermission?: NotificationPermissionState;
+  /** For device addressing: `granted` when any of the player's endpoints reported it. */
+  readonly endpointPermission?: NotificationPermissionState;
+  readonly history: readonly NotificationDeliveryHistoryEntry[];
+}
+/**
+* Gate steps 3 to 5 at the time a server reminder is set, against the
+* backend's records or the host read: `undefined` when they pass, else the
+* reminder status to answer (`permission-required` for a permission, agreement,
+* or allowance refusal). The scheduler runs the whole gate again at send time.
+*/
+export declare function evaluateNotificationReminderConsent(input: EvaluateNotificationReminderConsentInput): 'permission-required' | 'request-missing' | 'preference-off' | 'advertising-consent-missing' | undefined;
+/**
+* Idempotency key of a server reminder's send:
+* `reminder:<player>:<key>:<fireAt>`, with the player and key percent-encoded
+* (`encodeURIComponent`) so ids containing `:` cannot collide, and `fireAt` in
+* the canonical timestamp form.
+*/
+export declare function createNotificationReminderIdempotencyKey(input: {
+  readonly player: string;
+  readonly key: string;
+  readonly fireAt: string;
+}): string;
+/** The Korean advertising night window: 21:00 inclusive to 08:00 exclusive, Asia/Seoul. */
+export declare const notificationNightWindow: Readonly<{
+  readonly timeZone: 'Asia/Seoul';
+  readonly start: '21:00';
+  readonly end: '08:00';
+}>;
+export type NotificationWindowCheck = {
+  readonly inside: false;
+} | {
+  readonly inside: true;
+  readonly until: string;
+};
+/** Whether `at` falls in the night window, and the next 08:00 Asia/Seoul when it does. */
+export declare function checkNotificationNightWindow(at: string): NotificationWindowCheck;
+/**
+* Whether `at` falls in the quiet hours in `timeZone`, and the window's next
+* end when it does. An unknown zone throws a `TypeError`.
+*/
+export declare function checkNotificationQuietHours(at: string, quietHours: NotificationQuietHours, timeZone: string): NotificationWindowCheck;
+/** Whether `Intl` knows `timeZone`, so quiet hours can be read in it. */
+export declare function isValidNotificationTimeZone(timeZone: string): boolean;
+/** The Asia/Seoul calendar date of an instant, `YYYY-MM-DD`. */
+export declare function toSeoulCalendarDate(at: string): string;
+/**
+* ISO 8601 UTC without a `.000` millisecond part, as the vectors write
+* timestamps. The input needs a date, a time with seconds, and an offset (`Z`
+* or `±HH:MM`): a zone-less time would depend on the process's time zone.
+*/
+export declare function normalizeNotificationTimestamp(at: string): string;
+/**
+* Whether `at` is an RFC 3339 instant as every notifications timestamp must
+* be: a date that exists, `T` (not a space), a time, and an offset. Fractions
+* past milliseconds are dropped when it is read.
+*/
+export declare function isNotificationTimestamp(at: string): boolean;
+/** How a validated string field is read: an instant (`date-time`) or a calendar date (`date`). */
+export type NotificationTimeFormat = 'date-time' | 'date';
+/**
+* The `date-time` and `date` fields of a validated type, by key. A nested
+* spec applies to an object, and to each item of an array.
+*/
+export interface NotificationTimeFields {
+  readonly [key: string]: NotificationTimeFormat | NotificationTimeFields;
+}
+/**
+* The check every notifications validator runs after typia's, whose formats
+* accept a day the month does not have (31 April) and a space for `T`: each
+* `date-time` field `fields` names must pass `isNotificationTimestamp`, and
+* each `date` field `isNotificationCalendarDate`. Answers the first field
+* that does not, or `undefined`.
+*/
+export declare function notificationTimeFieldIssue(value: unknown, fields: NotificationTimeFields, path?: string): string | undefined;
+/**
+* The time fields of each validated type with any, for
+* `notificationTimeFieldIssue`. A test keeps them equal to the formats in the
+* published JSON Schemas.
+*/
+export declare const notificationTimeFields: {
+  readonly LocalNotificationRequest: {
+    readonly fireAt: 'date-time';
+  };
+  readonly LocalNotificationEntry: {
+    readonly fireAt: 'date-time';
+  };
+  readonly NotificationBridgeListLocalResult: {
+    readonly pending: {
+      readonly fireAt: 'date-time';
+    };
+  };
+  readonly NotificationConsentRecord: {
+    readonly at: 'date-time';
+  };
+  readonly NotificationNotice: {
+    readonly record: {
+      readonly at: 'date-time';
+    };
+    readonly dueBy: 'date';
+  };
+  readonly RecordNotificationNoticeInput: {
+    readonly record: {
+      readonly at: 'date-time';
+    };
+    readonly dueBy: 'date';
+  };
+  readonly NotificationConformanceVector: {
+    readonly context: {
+      readonly now: 'date-time';
+    };
+    readonly steps: {
+      readonly at: 'date-time';
+      readonly input: {
+        readonly record: {
+          readonly at: 'date-time';
+        };
+        readonly dueBy: 'date';
+        readonly fireAt: 'date-time';
+      };
+      readonly returns: {
+        readonly record: {
+          readonly at: 'date-time';
+        };
+        readonly dueBy: 'date';
+        readonly until: 'date-time';
+      };
+    };
+    readonly expect: {
+      readonly deliveries: {
+        readonly until: 'date-time';
+      };
+      readonly providerCalls: {
+        readonly expiresAt: 'date-time';
+      };
+      readonly local: {
+        readonly operations: {
+          readonly fireAt: 'date-time';
+        };
+        readonly pending: {
+          readonly fireAt: 'date-time';
+        };
+      };
+      readonly reminders: {
+        readonly fireAt: 'date-time';
+      };
+      readonly notices: {
+        readonly record: {
+          readonly at: 'date-time';
+        };
+        readonly dueBy: 'date';
+      };
+    };
+  };
+};
+export type NotificationNoticeKind = 'consent-result' | 'reconfirmation';
+export interface NotificationNotice {
+  readonly kind: NotificationNoticeKind;
+  /** The advertising or night record the notice reports on, with its date. */
+  readonly record: {
+    readonly kind: 'advertising' | 'night';
+    readonly state: 'granted' | 'withdrawn';
+    readonly at: IsoDateTime;
+    readonly textVersion?: NonEmptyString;
+  };
+  /** The last Asia/Seoul calendar date the notice may be given, `YYYY-MM-DD`. */
+  readonly dueBy: string & tags.Format<'date'>;
+  /**
+  * The variant of `notices.copy` the notice is given in, set when it is
+  * listed, so the game shows the text the scheduler would send.
+  */
+  readonly variant: NotificationNoticeVariant;
+}
+/**
+* What names one notice: its kind, the record it reports on (that record's
+* kind and time), and its `dueBy`. A listed notice carries these fields, and
+* `notices.recordShown` takes the listed notice as is or exactly them.
+*/
+export interface NotificationNoticeIdentity {
+  readonly kind: NotificationNoticeKind;
+  readonly record: {
+    readonly kind: 'advertising' | 'night';
+    /** RFC 3339 with an explicit offset; compared as an instant. */
+    readonly at: IsoDateTime;
+  };
+  /** The notice's last Asia/Seoul calendar date, `YYYY-MM-DD`. */
+  readonly dueBy: string & tags.Format<'date'>;
+}
+/** Whether two notices are one: the same kind, record kind, record instant, and `dueBy`. */
+export declare function isSameNotificationNotice(left: NotificationNoticeIdentity, right: NotificationNoticeIdentity): boolean;
+/**
+* The copy a notice is given in: its kind, its record's kind, and for a
+* result notice what the record was, so the text can say what the player did
+* (decree art. 62-2): a consent (`granted`), the withdrawal of a consent
+* (`withdrawn`), or a refusal (`refused`), a `withdrawn` record whose latest
+* earlier record of its kind is not a consent. A re-confirmation always
+* reports on a consent (decree art. 62-3). A named union keeps the JSON
+* Schema names readable.
+*/
+export type NotificationNoticeVariant = 'consent-result.advertising.granted' | 'consent-result.advertising.refused' | 'consent-result.advertising.withdrawn' | 'consent-result.night.granted' | 'consent-result.night.refused' | 'consent-result.night.withdrawn' | 'reconfirmation.advertising' | 'reconfirmation.night';
+/** Every `NotificationNoticeVariant`, in this order; a test keeps the two equal. */
+export declare const notificationNoticeVariants: readonly ["consent-result.advertising.granted", "consent-result.advertising.refused", "consent-result.advertising.withdrawn", "consent-result.night.granted", "consent-result.night.refused", "consent-result.night.withdrawn", "reconfirmation.advertising", "reconfirmation.night"];
+/**
+* The variants `notices.copy` may leave out, each with the variant whose text
+* stands in for it: a refusal is given in the withdrawal's text.
+*/
+export declare const notificationNoticeVariantFallbacks: Readonly<Partial<Record<NotificationNoticeVariant, NotificationNoticeVariant>>>;
+/**
+* One locale of `notices.copy`: a title and a body for each notice variant.
+* A refusal's text is optional; without it a refusal is given in the
+* withdrawal's text (`notificationNoticeVariantFallbacks`).
+*/
+export interface NotificationNoticeLocaleCopy {
+  readonly 'consent-result.advertising.granted': NotificationTopicCopy;
+  readonly 'consent-result.advertising.refused'?: NotificationTopicCopy;
+  readonly 'consent-result.advertising.withdrawn': NotificationTopicCopy;
+  readonly 'consent-result.night.granted': NotificationTopicCopy;
+  readonly 'consent-result.night.refused'?: NotificationTopicCopy;
+  readonly 'consent-result.night.withdrawn': NotificationTopicCopy;
+  readonly 'reconfirmation.advertising': NotificationTopicCopy;
+  readonly 'reconfirmation.night': NotificationTopicCopy;
+}
+/**
+* The catalog's `notices.copy`: per locale, a title and a body for every
+* notice variant, a refusal's optional. `{{consentDate}}`, the record's
+* Asia/Seoul date, is the only placeholder the server fills, and each
+* variant uses it. The text carries the rest of what the decree requires:
+* the sender's name and, for a result notice (art. 62-2), the processing
+* result, or, for a re-confirmation (art. 62-3(2)), how to keep or withdraw
+* the consent.
+*/
+export type NotificationNoticeCopy = Readonly<Record<string, NotificationNoticeLocaleCopy>>;
+/**
+* The catalog's `notices` block, which a backend and a vector take as one:
+* the topic consent notices go out through, and their copy per variant.
+*/
+export interface NotificationNoticeSettings {
+  /** A remote `service` topic that keeps only the delivery settings. */
+  readonly topic: NonEmptyString;
+  readonly copy: NotificationNoticeCopy;
+}
+/**
+* The rules `notices.copy` follows wherever it is read (the catalog
+* validator, a backend, and the vector loader), each issue under `path`,
+* with locale and variant keys in brackets (`["ko-KR"]["reconfirmation.night"]`):
+*
+* - an object of locales that includes `defaultLocale`, matched without
+*   regard to case;
+* - per locale, a title and a body for each notice variant, a refusal's
+*   optional (`notificationNoticeVariantFallbacks`), and no other key;
+* - each title and body a string that is not blank, with no placeholder but
+*   `{{consentDate}}` and no brace outside one; and `{{consentDate}}` in the
+*   title or the body, because a notice states the date of the act it
+*   reports on.
+*/
+export declare function notificationNoticeCopyIssues(copy: unknown, defaultLocale: string, path?: string): NotificationTopicIssue[];
+/**
+* One variant's copy per locale, shaped as a topic's `copy`, so the notice
+* topic sends it with the lookup and default-locale fallback of any topic
+* (`findNotificationCopy`). A locale without a refusal's text gives the
+* withdrawal's (`notificationNoticeVariantFallbacks`); a locale without the
+* variant, which a validated catalog never has, is left out rather than
+* found empty.
+*/
+export declare function notificationNoticeVariantCopy(copy: NotificationNoticeCopy, variant: NotificationNoticeVariant): Readonly<Record<string, NotificationTopicCopy>>;
+/**
+* Whether a provider can carry a consent notice: it sends free-form content
+* and needs no `title` or `body` in a topic's mapping, which it would send in
+* place of the notice's copy. The catalog validator keeps the notice topic
+* off any other provider, and a scheduler pushes no notice through one.
+*/
+export declare function notificationProviderCarriesNotices(entry: Pick<NotificationDeliveryProviderEntry, 'content' | 'mappingFields'>): boolean;
+/**
+* The notice topic as the gate renders one notice from it: its delivery
+* settings, any `title` or `body` dropped from its mapping so nothing stands
+* in for the copy, and the variant's `notices.copy` in place of a copy of its
+* own (`notificationNoticeVariantCopy`).
+*/
+export declare function notificationNoticeTopic(topic: NotificationTopicDeclaration, copy: NotificationNoticeCopy, variant: NotificationNoticeVariant): NotificationTopicDeclaration;
+/** Result notice: 14 days after the record's Asia/Seoul date, counted from the next day. */
+export declare function notificationConsentResultDueBy(at: string): string;
+/**
+* The `ordinal`-th re-confirmation notice of a consent: the day before the
+* Asia/Seoul date `2 × ordinal` years after the consent date. A 29 February
+* consent date counts as 28 February.
+*/
+export declare function notificationReconfirmationDueBy(at: string, ordinal?: number): string;
+/** Days before its `dueBy` from which a re-confirmation is listed. */
+export declare const notificationReconfirmationListDays = 60;
+/**
+* The notices a player's advertising and night records owe at `at`, ordered
+* by `dueBy` and then `kind`, each with the variant of `notices.copy` it is
+* given in. `records` are in the order they were written. A notice that
+* `given` names is not listed:
+*
+* - a `consent-result` notice for every record, which reports a refusal for
+*   a `withdrawn` record whose latest earlier record of its kind is not a
+*   consent;
+* - per kind whose latest record is a consent, the first re-confirmation of
+*   that consent not given yet, from `notificationReconfirmationListDays`
+*   days before its `dueBy`. Each one follows the one before it, so silence
+*   keeps the series going, a new consent restarts it, and a withdrawal ends
+*   it.
+*
+* A listed notice stays listed after its `dueBy` until it is given.
+*/
+export declare function listNotificationNotices(records: readonly NotificationConsentRecord[], given: readonly NotificationNoticeIdentity[], at: string): readonly NotificationNotice[];
+/** Days before `dueBy` from which the scheduler sends a notice nobody recorded. */
+export declare const notificationNoticeLeadDays = 7;
+/**
+* The first Asia/Seoul calendar date the scheduler sends an unrecorded notice:
+* `notificationNoticeLeadDays` days before `dueBy`.
+*/
+export declare function notificationNoticeSendFrom(dueBy: string): string;
+/** Whether `date` is a calendar date `YYYY-MM-DD` that exists, such as a notice's `dueBy`. */
+export declare function isNotificationCalendarDate(date: string): boolean;
+/**
+* Idempotency key of a scheduled notice:
+* `notice:<player>:<kind>:<record kind>:<record at>:<dueBy>`, with the player
+* percent-encoded, the record's time in the canonical form, and `dueBy` as
+* `YYYY-MM-DD`. Each notice has its own key: every re-confirmation of one
+* consent, and the notices of an advertising and a night record written at
+* one instant.
+*/
+export declare function createNotificationNoticeIdempotencyKey(input: NotificationNoticeIdentity & {
+  readonly player: string;
+}): string;
+export {};