@mpgd/platform 0.22.0 → 0.23.0

package/dist/notifications-policy.js

@@ -0,0 +1,1658 @@
+import { normalizeRootRelativeRoute } from './routes.js';
+/**
+ * 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 function notificationTopicNeedsNoAgreement(topic) {
+    return topic.mapping?.['agreement'] === 'none';
+}
+/** The longest route a topic or a local reminder may name. */
+const maxNotificationRouteLength = 2048;
+/**
+ * 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 function isRootRelativeNotificationRoute(route) {
+    return route.length <= maxNotificationRouteLength
+        && normalizeRootRelativeRoute(route) === route;
+}
+/**
+ * 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 function notificationRouteError(subject, route) {
+    if (isRootRelativeNotificationRoute(route)) {
+        return undefined;
+    }
+    const normalized = route.length <= maxNotificationRouteLength
+        ? normalizeRootRelativeRoute(route)
+        : undefined;
+    return normalized === undefined
+        ? `${subject} is not root-relative: ${JSON.stringify(route)}`
+        : `${subject} is not in normalized form: ${JSON.stringify(route)}; write ${JSON.stringify(normalized)}`;
+}
+/**
+ * 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 function notificationTopicDefinitionIssues(topic, path = 'topic') {
+    const issues = [];
+    if (topic.id.trim() !== topic.id || hasControlCharacter(topic.id)) {
+        issues.push({
+            path: `${path}.id`,
+            message: 'topic ids must be trimmed, without control characters',
+        });
+    }
+    if (topic.id === '__proto__') {
+        // Topic ids key plain objects (snapshots, outcomes), where this one cannot be an own key.
+        issues.push({ path: `${path}.id`, message: 'the topic id __proto__ is reserved' });
+    }
+    if (new Set(topic.channels).size !== topic.channels.length) {
+        issues.push({ path: `${path}.channels`, message: 'channels must not repeat' });
+    }
+    if (topic.purpose === 'advertising' && topic.channels.includes('local')) {
+        issues.push({
+            path: `${path}.channels`,
+            message: 'advertising topics may not use the local channel: the server could not withdraw, label, or hold a device-scheduled advertisement',
+        });
+    }
+    if (!isRootRelativeNotificationRoute(topic.route)) {
+        issues.push({ path: `${path}.route`, message: rootRelativeMessage(topic.route) });
+    }
+    if (topic.optOutRoute !== undefined && !isRootRelativeNotificationRoute(topic.optOutRoute)) {
+        issues.push({ path: `${path}.optOutRoute`, message: rootRelativeMessage(topic.optOutRoute) });
+    }
+    if (topic.purpose === 'advertising' && topic.optOutRoute === undefined) {
+        issues.push({
+            path: `${path}.optOutRoute`,
+            message: 'advertising topics need an optOutRoute, the screen where the player withdraws advertising consent',
+        });
+    }
+    if (topic.quietHours !== undefined && topic.quietHours.start === topic.quietHours.end) {
+        issues.push({
+            path: `${path}.quietHours`,
+            message: 'quiet hours must not start and end at the same time',
+        });
+    }
+    return issues;
+}
+function rootRelativeMessage(route) {
+    const normalized = route.length <= maxNotificationRouteLength
+        ? normalizeRootRelativeRoute(route)
+        : undefined;
+    return normalized === undefined
+        ? `${JSON.stringify(route)} must be a root-relative path on the game's origin, such as /?entry=continue`
+        : `${JSON.stringify(route)} must be written in its normalized form, ${JSON.stringify(normalized)}`;
+}
+function hasControlCharacter(value) {
+    return /[\u0000-\u001f\u007f]/u.test(value);
+}
+export const recordableNotificationPermissionStates = Object.freeze([
+    'granted',
+    'prompt-with-rationale',
+    'denied',
+    'blocked',
+]);
+/** Whether the runtime records this state: a decided state, never prompt, unknown, action-required, or unsupported. */
+export function isRecordableNotificationPermissionState(state) {
+    return recordableNotificationPermissionStates.includes(state);
+}
+/** The consent kind that holds delivery permission for a permission scope. */
+export function notificationPermissionConsentKind(scope) {
+    return scope === 'app' ? 'delivery-permission' : 'host-agreement';
+}
+/** A topic's state in a snapshot: its own entry, else the app state, else `unknown`. */
+export function notificationPermissionStateOf(snapshot, topic) {
+    return Object.prototype.hasOwnProperty.call(snapshot.topics, topic)
+        ? (snapshot.topics[topic] ?? snapshot.app ?? 'unknown')
+        : (snapshot.app ?? 'unknown');
+}
+/**
+ * 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 function latestNotificationConsent(records, kind, topic) {
+    for (let index = records.length - 1; index >= 0; index -= 1) {
+        const record = records[index];
+        if (record !== undefined && record.kind === kind && record.topic === topic) {
+            return record;
+        }
+    }
+    return undefined;
+}
+export const notificationDefaultOptOutLine = '무료 수신거부: 수신거부 버튼';
+export const notificationDefaultDeploymentTimeZone = 'Asia/Seoul';
+/**
+ * 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 function resolveNotificationAdvertisingSettings(deployment, path = 'deployment') {
+    const issues = [];
+    const declared = deployment?.advertisingSender;
+    const contact = deploymentText(declared?.contact);
+    const name = deploymentText(declared?.name);
+    const optOutLine = deploymentText(deployment?.advertisingOptOutLine);
+    if (declared === undefined) {
+        issues.push({
+            path: `${path}.advertisingSender`,
+            message: 'the Korean advertising rules need the advertising sender; without it every advertising send is suppressed',
+        });
+    }
+    else if (contact === undefined) {
+        issues.push({
+            path: `${path}.advertisingSender.contact`,
+            message: 'the advertising sender contact is blank, so every advertising send is suppressed',
+        });
+    }
+    if (declared?.name !== undefined && name === undefined) {
+        issues.push({
+            path: `${path}.advertisingSender.name`,
+            message: 'the advertising sender name is blank, so the sender line leaves it out; omit name only when the sender is the app',
+        });
+    }
+    if (deployment?.advertisingOptOutLine !== undefined && optOutLine === undefined) {
+        issues.push({
+            path: `${path}.advertisingOptOutLine`,
+            message: 'the opt-out line is blank, so advertising carries the default line; leave it out to use the default',
+        });
+    }
+    return {
+        ...(contact === undefined ? {} : { sender: name === undefined ? { contact } : { name, contact } }),
+        optOutLine: optOutLine ?? notificationDefaultOptOutLine,
+        issues,
+    };
+}
+/** A deployment text trimmed, or `undefined` when it is absent or blank. */
+function deploymentText(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === '' ? undefined : trimmed;
+}
+/**
+ * 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 const referenceNotificationProviders = deepFreeze({
+    fcm: {
+        provider: 'fcm',
+        purposes: ['service', 'requested', 'advertising'],
+        addressing: 'device',
+        content: 'free-form',
+        permission: { scope: 'app', serverReadable: false, allowance: 'persistent' },
+        expiry: true,
+        actions: true,
+        link: false,
+        mappingFields: [],
+        mapping: { channelId: { required: false } },
+    },
+    'apps-in-toss': {
+        provider: 'apps-in-toss',
+        purposes: ['service', 'requested'],
+        addressing: 'platform-user',
+        content: 'host-template',
+        permission: { scope: 'topic', serverReadable: false, allowance: 'persistent' },
+        limits: [{ count: 10, windowSeconds: 60 }],
+        rate: { count: 15_000, windowSeconds: 60 },
+        expiry: false,
+        actions: false,
+        link: false,
+        mappingFields: ['templateSetCode', 'agreement'],
+        mapping: {
+            templateSetCode: { required: true },
+            agreement: { required: true, values: ['required', 'none'] },
+        },
+    },
+    devvit: {
+        provider: 'devvit',
+        purposes: ['service', 'requested'],
+        addressing: 'platform-user',
+        content: 'free-form',
+        permission: { scope: 'app', serverReadable: true, allowance: 'persistent' },
+        limits: [{ count: 2, windowSeconds: 86_400 }],
+        rate: { count: 25_000, windowSeconds: 86_400 },
+        expiry: false,
+        actions: false,
+        link: true,
+        mappingFields: ['title', 'body'],
+        mapping: {
+            title: { required: true, maxLength: 60 },
+            body: { required: true, maxLength: 100 },
+            link: { required: false, pattern: '^t[13]_[A-Za-z0-9]+$' },
+        },
+    },
+});
+/** Reference target names and the provider each one enables. */
+export const referenceNotificationTargetProviders = Object.freeze({
+    android: 'fcm',
+    ios: 'fcm',
+    ait: 'apps-in-toss',
+    reddit: 'devvit',
+});
+/**
+ * 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 function notificationRegistryMismatch(capabilities, entry) {
+    const remote = capabilities.remote;
+    if (!remote.supported) {
+        return 'the provider declares no remote delivery';
+    }
+    if (remote.addressing !== entry.addressing) {
+        return `addressing ${remote.addressing} differs from the registry's ${entry.addressing}`;
+    }
+    if (remote.content !== entry.content) {
+        return `content ${remote.content} differs from the registry's ${entry.content}`;
+    }
+    const purposes = [...remote.purposes].sort().join(',');
+    if (purposes !== [...entry.purposes].sort().join(',')) {
+        return `purposes ${purposes} differ from the registry's ${[...entry.purposes].sort().join(',')}`;
+    }
+    const { permission } = capabilities;
+    if (permission.scope !== entry.permission.scope
+        || permission.serverReadable !== entry.permission.serverReadable
+        || permission.allowance !== entry.permission.allowance) {
+        return 'permission scope, server readability, or allowance differs from the registry';
+    }
+    return undefined;
+}
+export const notificationSuppressionReasons = Object.freeze([
+    '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',
+]);
+/** The advertising opt-out action under the Korean rules. */
+export const notificationAdvertisingOptOutActionId = 'advertising-opt-out';
+/**
+ * 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 function evaluateNotificationDelivery(input) {
+    const { entry, topic } = input;
+    if (topic === undefined) {
+        return { status: 'suppressed', reason: 'topic-unknown' };
+    }
+    if (!topic.channels.includes('remote')) {
+        return { status: 'suppressed', reason: 'channel-unsupported' };
+    }
+    const rules = input.deployment?.advertisingRules;
+    if (topic.purpose === 'advertising' && rules === undefined) {
+        // The Korean rules must be chosen on purpose: a deployment that forgot them fails closed.
+        throw new TypeError(`Advertising topic ${topic.id} needs the deployment's advertisingRules ('kr' or 'none').`);
+    }
+    if (!entry.purposes.includes(topic.purpose)
+        || (topic.purpose === 'advertising'
+            && (entry.content !== 'free-form' || (rules === 'kr' && (!entry.expiry || !entry.actions))))) {
+        return { status: 'suppressed', reason: 'purpose-unsupported' };
+    }
+    if (!input.recipientResolved) {
+        return { status: 'unavailable', reason: 'no-endpoint' };
+    }
+    if (entry.link && input.link === undefined && typeof topic.mapping?.['link'] !== 'string') {
+        return { status: 'unavailable', reason: 'link-missing' };
+    }
+    const permission = deliveryPermissionRefusal(input, topic);
+    if (permission !== undefined) {
+        return { status: 'suppressed', reason: permission };
+    }
+    const preference = topicPreferenceRefusal(topic, input.consent);
+    if (preference !== undefined) {
+        return { status: 'suppressed', reason: preference };
+    }
+    if (topic.purpose === 'advertising'
+        && latestNotificationConsent(input.consent, 'advertising')?.state !== 'granted') {
+        return { status: 'suppressed', reason: 'advertising-consent-missing' };
+    }
+    const timeZone = input.timeZone
+        ?? input.deployment?.timeZone
+        ?? notificationDefaultDeploymentTimeZone;
+    const windows = resolveTimeWindows(topic, input.consent, input.at, timeZone, rules ?? 'none');
+    if (windows.status === 'suppressed') {
+        return { status: 'suppressed', reason: windows.reason };
+    }
+    if (windows.status === 'held') {
+        return { status: 'deferred', reason: windows.reason, until: windows.until };
+    }
+    const limit = limitDecision(input, topic);
+    if (limit !== undefined) {
+        return limit;
+    }
+    const advertising = topic.purpose === 'advertising' && rules === 'kr'
+        ? resolveNotificationAdvertisingSettings(input.deployment)
+        : undefined;
+    if (advertising !== undefined && advertising.sender === undefined) {
+        return { status: 'suppressed', reason: 'advertising-sender-missing' };
+    }
+    const content = resolveNotificationContent({
+        topic,
+        content: entry.content,
+        defaultLocale: input.defaultLocale,
+        ...(input.locale === undefined ? {} : { locale: input.locale }),
+        ...(input.templateData === undefined ? {} : { templateData: input.templateData }),
+    });
+    if (advertising?.sender === undefined) {
+        return { status: 'allowed', content };
+    }
+    const nightConsent = latestNotificationConsent(input.consent, 'night')?.state === 'granted';
+    return {
+        status: 'allowed',
+        content: renderNotificationAdvertisement(topic, content, advertising.sender, advertising.optOutLine),
+        ...(nightConsent ? {} : { expiresAt: nextNightWindowStart(input.at) }),
+    };
+}
+function deliveryPermissionRefusal(input, topic) {
+    const { entry } = input;
+    if (entry.permission.serverReadable) {
+        if (input.serverPermission === undefined) {
+            throw new TypeError(`Provider ${entry.provider} is server-readable; the gate needs the host answer at send time.`);
+        }
+        if (input.serverPermission !== 'granted') {
+            return 'permission-denied';
+        }
+    }
+    else if (entry.addressing === 'device') {
+        if (input.endpointPermission !== 'granted') {
+            return 'permission-denied';
+        }
+    }
+    else if (entry.permission.scope === 'app'
+        && latestNotificationConsent(input.consent, 'delivery-permission')?.state !== 'granted') {
+        return 'permission-denied';
+    }
+    // A topic that needs no agreement goes on even after a provider's denial:
+    // nothing could ask the player again, and the host decides each send.
+    if (entry.permission.scope === 'topic' && !notificationTopicNeedsNoAgreement(topic)) {
+        if (latestNotificationConsent(input.consent, 'host-agreement', topic.id)?.state !== 'granted') {
+            return 'agreement-missing';
+        }
+    }
+    if (entry.permission.allowance === 'per-send') {
+        const acceptanceKind = notificationPermissionConsentKind(entry.permission.scope);
+        const accepted = input.consent.filter((record) => record.kind === acceptanceKind
+            && record.state === 'granted'
+            && (entry.permission.scope === 'app' ? record.topic === undefined : record.topic === topic.id))
+            .length;
+        const used = input.history.filter((sent) => sent.provider === entry.provider
+            && (entry.permission.scope === 'app' || sent.topic === topic.id)).length;
+        if (accepted <= used) {
+            return 'allowance-exhausted';
+        }
+    }
+    return undefined;
+}
+/** Gate step 4: only `topic-preference` records decide, and the latest one wins. */
+function topicPreferenceRefusal(topic, consent) {
+    const latest = latestNotificationConsent(consent, 'topic-preference', topic.id);
+    if (topic.purpose === 'requested') {
+        if (latest === undefined) {
+            return 'request-missing';
+        }
+        return latest.state === 'granted' ? undefined : 'preference-off';
+    }
+    return latest?.state === 'withdrawn' ? 'preference-off' : undefined;
+}
+/** The window holding a send at `at`: the night window for advertising without night consent under `kr`, then quiet hours. */
+function windowHold(topic, consent, at, timeZone, rules) {
+    if (rules === 'kr'
+        && topic.purpose === 'advertising'
+        && latestNotificationConsent(consent, 'night')?.state !== 'granted') {
+        const night = checkNotificationNightWindow(at);
+        if (night.inside) {
+            return { reason: 'night-window', until: night.until };
+        }
+    }
+    if (topic.quietHours !== undefined) {
+        const quiet = checkNotificationQuietHours(at, topic.quietHours, timeZone);
+        if (quiet.inside) {
+            return { reason: 'quiet-hours', until: quiet.until };
+        }
+    }
+    return undefined;
+}
+/** Window hops before the windows count as covering every hour (two windows settle in far fewer). */
+const maxWindowHops = 6;
+/**
+ * Gate step 6. A topic that is not deferrable is suppressed by the window
+ * holding it, and a send whose windows together leave no time to send (quiet
+ * hours that close exactly where the night window opens and the reverse) is
+ * `night-consent-missing`, so the scheduler can never defer it forever.
+ */
+function resolveTimeWindows(topic, consent, at, timeZone, rules) {
+    const first = windowHold(topic, consent, at, timeZone, rules);
+    if (first === undefined) {
+        return { status: 'clear' };
+    }
+    if (topic.deferrable === false) {
+        return {
+            status: 'suppressed',
+            reason: first.reason === 'night-window' ? 'night-consent-missing' : 'quiet-hours',
+        };
+    }
+    // Follow each window's end until a time no window holds.
+    let current = first.until;
+    for (let hop = 1; hop < maxWindowHops; hop += 1) {
+        const hold = windowHold(topic, consent, current, timeZone, rules);
+        if (hold === undefined) {
+            return { status: 'held', reason: first.reason, until: first.until };
+        }
+        current = hold.until;
+    }
+    return { status: 'suppressed', reason: 'night-consent-missing' };
+}
+/**
+ * Gate step 7. A send at `s` counts for a send at `t` when `t − window < s ≤
+ * t`. The topic's daily cap and limits of a day or longer suppress; a shorter
+ * provider limit defers until the oldest counted send leaves the window.
+ * `at` reads strictly even when nothing is counted. Each counted send is read
+ * once, and the count walks from the newest one to the longest window.
+ */
+function limitDecision(input, topic) {
+    const at = parseInstant(input.at);
+    const limits = input.entry.limits ?? [];
+    const capped = topic.frequency !== undefined;
+    if (!capped && limits.length === 0) {
+        return undefined;
+    }
+    const longest = Math.max(capped ? dayMs : 0, ...limits.map((limit) => limit.windowSeconds * 1000));
+    const sends = countedSends(input.history, {
+        topic: capped ? topic.id : undefined,
+        provider: limits.length > 0 ? input.entry.provider : undefined,
+    });
+    // The topic's and the provider's sends inside the longest window.
+    const topicSends = [];
+    const providerSends = [];
+    for (let index = sends.length - 1; index >= 0; index -= 1) {
+        const sent = sends[index];
+        if (sent === undefined) {
+            continue;
+        }
+        if (sent.at <= at - longest) {
+            break;
+        }
+        if (sent.at > at) {
+            continue;
+        }
+        if (sent.topic) {
+            topicSends.push(sent.at);
+        }
+        if (sent.provider) {
+            providerSends.push(sent.at);
+        }
+    }
+    // Oldest first again, as the deferral below reads them.
+    topicSends.reverse();
+    providerSends.reverse();
+    const counted = (sends, windowMs) => sends.filter((sentAt) => sentAt > at - windowMs);
+    if (topic.frequency !== undefined) {
+        const sends = counted(topicSends, dayMs);
+        if (sends.length >= topic.frequency.maxPerDay) {
+            return { status: 'suppressed', reason: 'frequency-capped' };
+        }
+    }
+    // Every limit that is full: one of a day or longer suppresses, whatever the
+    // order of the entry's limits; shorter ones defer until all have room.
+    let until;
+    for (const limit of limits) {
+        const windowMs = limit.windowSeconds * 1000;
+        const sends = counted(providerSends, windowMs);
+        if (sends.length < limit.count) {
+            continue;
+        }
+        if (windowMs >= dayMs) {
+            return { status: 'suppressed', reason: 'provider-limit' };
+        }
+        // Room opens when enough of the oldest counted sends have left the window.
+        const leaving = (sends[sends.length - limit.count] ?? sends[0] ?? at) + windowMs;
+        until = until === undefined ? leaving : Math.max(until, leaving);
+    }
+    return until === undefined
+        ? undefined
+        : { status: 'deferred', reason: 'provider-limit', until: formatNotificationTimestamp(until) };
+}
+/**
+ * The sends step 7 counts, oldest first: the topic's when it has a daily cap,
+ * and the provider's when it has limits, each read once. The history comes
+ * oldest first; the same pass finds one that does not, and its copy is sorted.
+ */
+function countedSends(history, counted) {
+    const sends = [];
+    let ordered = true;
+    for (const sent of history) {
+        const topic = counted.topic !== undefined && sent.topic === counted.topic;
+        const provider = counted.provider !== undefined && sent.provider === counted.provider;
+        if (!topic && !provider) {
+            continue;
+        }
+        const at = parseInstant(sent.at);
+        const previous = sends[sends.length - 1];
+        if (previous !== undefined && at < previous.at) {
+            ordered = false;
+        }
+        sends.push({ at, topic, provider });
+    }
+    // `sends` is a copy already, so it sorts in place.
+    return ordered ? sends : sends.sort((left, right) => left.at - right.at);
+}
+/** The next start of the night window (21:00 Asia/Seoul) after `at`. */
+function nextNightWindowStart(at) {
+    const millis = parseInstant(at);
+    const wall = seoulZone.wall(millis);
+    const start = parseClockTime(notificationNightWindow.start);
+    const day = wall.minute < start ? wall.day : wall.day + 1;
+    return formatNotificationTimestamp(Date.UTC(wall.year, wall.month - 1, day, 0, start) - seoulOffsetMs);
+}
+// Content (RFC "Topic catalog" and gate step 8).
+const placeholderPattern = /\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}/gu;
+/** A brace, full-width ones included, which a text holds only inside a `{{name}}` placeholder. */
+const bracePattern = /[{}\uFF5B\uFF5D]/u;
+/**
+ * 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 function readNotificationTemplate(text) {
+    return {
+        placeholders: [...text.matchAll(placeholderPattern)].map((match) => match[1] ?? ''),
+        strayBrace: bracePattern.test(text.replace(placeholderPattern, '')),
+    };
+}
+/** Fills `{{name}}` placeholders from `data`; a placeholder without a value is a caller error. */
+export function fillNotificationTemplate(text, data = {}) {
+    return text.replace(placeholderPattern, (_match, name) => {
+        const value = Object.prototype.hasOwnProperty.call(data, name) ? data[name] : undefined;
+        if (value === undefined) {
+            throw new TypeError(`Template data has no value for {{${name}}}.`);
+        }
+        return String(value);
+    });
+}
+/**
+ * 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 function findNotificationCopy(topic, locale, defaultLocale) {
+    const copy = topic.copy;
+    if (copy === undefined) {
+        return undefined;
+    }
+    const keys = Object.keys(copy);
+    const candidates = locale === undefined
+        ? [defaultLocale]
+        : [locale, locale.split(/[-_]/u, 1)[0] ?? locale, defaultLocale];
+    for (const candidate of candidates) {
+        const key = Object.prototype.hasOwnProperty.call(copy, candidate)
+            ? candidate
+            : keys.find((name) => name.toLowerCase() === candidate.toLowerCase());
+        if (key !== undefined) {
+            return copy[key];
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function resolveNotificationContent(input) {
+    const { topic, templateData } = input;
+    assertRootRelativeRoute(topic.id, 'route', topic.route);
+    const mappedTitle = topic.mapping?.['title'];
+    const mappedBody = topic.mapping?.['body'];
+    if (typeof mappedTitle === 'string' && typeof mappedBody === 'string') {
+        return {
+            title: fillNotificationTemplate(mappedTitle, templateData),
+            body: fillNotificationTemplate(mappedBody, templateData),
+            route: topic.route,
+            source: 'mapping',
+        };
+    }
+    if (input.content === 'host-template') {
+        return { route: topic.route, source: 'host-template' };
+    }
+    const copy = findNotificationCopy(topic, input.locale, input.defaultLocale);
+    if (copy === undefined) {
+        throw new TypeError(`Topic ${topic.id} has no copy for ${input.locale ?? input.defaultLocale} `
+            + `or the default locale ${input.defaultLocale}.`);
+    }
+    return {
+        title: fillNotificationTemplate(copy.title, templateData),
+        body: fillNotificationTemplate(copy.body, templateData),
+        route: topic.route,
+        source: 'catalog',
+    };
+}
+/** The advertising label every advertising title and body starts with under `kr`. */
+export const notificationAdvertisingPrefix = '(광고)';
+/**
+ * `(광고)`, one space, and the text without leading whitespace. Text that
+ * already starts with the label keeps it once, followed by one space.
+ */
+export function applyNotificationAdvertisingLabel(text) {
+    const trimmed = text.trimStart();
+    const rest = trimmed.startsWith(notificationAdvertisingPrefix)
+        ? trimmed.slice(notificationAdvertisingPrefix.length).trimStart()
+        : trimmed;
+    return `${notificationAdvertisingPrefix} ${rest}`;
+}
+/**
+ * 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 function renderNotificationAdvertisement(topic, content, sender, optOutLine = notificationDefaultOptOutLine) {
+    if (topic.optOutRoute === undefined) {
+        throw new TypeError(`Advertising topic ${topic.id} declares no optOutRoute.`);
+    }
+    assertRootRelativeRoute(topic.id, 'optOutRoute', topic.optOutRoute);
+    const settings = resolveNotificationAdvertisingSettings({
+        advertisingSender: sender,
+        advertisingOptOutLine: optOutLine,
+    });
+    if (settings.sender === undefined) {
+        throw new TypeError(`Advertising topic ${topic.id} needs a sender contact that is not blank.`);
+    }
+    const { name, contact } = settings.sender;
+    const senderLine = name === undefined ? contact : `${name} ${contact}`;
+    return {
+        ...content,
+        ...(content.title === undefined
+            ? {}
+            : { title: applyNotificationAdvertisingLabel(content.title) }),
+        ...(content.body === undefined
+            ? {}
+            : {
+                body: `${notificationAdvertisingPrefix} ${senderLine}\n${content.body}\n${settings.optOutLine}`,
+            }),
+        actions: [
+            {
+                id: notificationAdvertisingOptOutActionId,
+                title: '수신거부',
+                route: topic.optOutRoute,
+            },
+        ],
+    };
+}
+function assertRootRelativeRoute(topic, field, route) {
+    const error = notificationRouteError(`Topic ${topic} has a ${field} that`, route);
+    if (error !== undefined) {
+        throw new TypeError(error);
+    }
+}
+// Inputs and idempotency (RFC "Reminders" input bounds and "Policy gate").
+/** v1's input bounds, which v2 keeps. */
+export const notificationInputBounds = Object.freeze({
+    keyLength: 2048,
+    entries: 128,
+    stringLength: 16_384,
+});
+/** Key prefixes the scheduler reserves; a caller's send key may not start with one. */
+export const notificationReservedKeyPrefixes = Object.freeze(['reminder:', 'notice:']);
+/** Why `key` is not a valid send or reminder key, or `undefined`. */
+export function notificationKeyIssue(key) {
+    if (key.length === 0 || key.length > notificationInputBounds.keyLength) {
+        return `keys hold 1 to ${notificationInputBounds.keyLength} characters`;
+    }
+    if (hasControlCharacter(key) || /[\uD800-\uDFFF]/u.test(key)) {
+        return 'keys hold no control characters or lone surrogates';
+    }
+    return undefined;
+}
+/** The reserved prefix `key` starts with, if any. */
+export function notificationReservedKeyPrefix(key) {
+    return notificationReservedKeyPrefixes.find((prefix) => key.startsWith(prefix));
+}
+/**
+ * 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 function notificationTemplateDataIssue(data, options = {}) {
+    if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+        return 'expected an object of entries';
+    }
+    const entries = Object.entries(data);
+    if (entries.length > notificationInputBounds.entries) {
+        return `at most ${notificationInputBounds.entries} entries`;
+    }
+    for (const [name, value] of entries) {
+        if (name.length === 0 || name.length > notificationInputBounds.keyLength || hasControlCharacter(name)) {
+            return `entry name ${JSON.stringify(name)} is not valid`;
+        }
+        if (typeof value === 'string') {
+            if (value.length > notificationInputBounds.stringLength) {
+                return `entry ${name} is longer than ${notificationInputBounds.stringLength} characters`;
+            }
+            continue;
+        }
+        if (options.stringsOnly) {
+            return `entry ${name} must be a string`;
+        }
+        if (!(typeof value === 'boolean' || (typeof value === 'number' && Number.isFinite(value)))) {
+            return `entry ${name} must be a string, a finite number, or a boolean`;
+        }
+    }
+    return undefined;
+}
+/**
+ * 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 function notificationSendFingerprint(request) {
+    return canonicalJson({
+        player: request.player,
+        provider: request.provider ?? null,
+        topic: request.topic,
+        templateData: request.templateData ?? null,
+        data: request.data ?? null,
+        locale: request.locale ?? null,
+        link: request.link ?? null,
+    });
+}
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(',')}]`;
+    }
+    if (typeof value === 'object' && value !== null) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * 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 function routeNotificationReminder(topic, capabilities) {
+    if (topic.channels.includes('local')
+        && topic.purpose !== 'advertising'
+        && capabilities.local.supported) {
+        return 'local';
+    }
+    if (topic.channels.includes('remote') && capabilities.remote.supported) {
+        return 'remote';
+    }
+    return 'none';
+}
+/**
+ * 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 function evaluateLocalNotificationReminder(input) {
+    if (input.permission !== 'granted') {
+        return { status: 'permission-required' };
+    }
+    const preference = topicPreferenceRefusal(input.topic, input.consent);
+    if (preference !== undefined) {
+        return { status: preference };
+    }
+    let fireAt = normalizeNotificationTimestamp(input.fireAt);
+    const { quietHours } = input.topic;
+    if (quietHours !== undefined) {
+        let quiet = checkNotificationQuietHours(fireAt, quietHours, input.timeZone);
+        if (quiet.inside && input.topic.deferrable === false) {
+            return { status: 'quiet-hours' };
+        }
+        // As at gate step 6: follow each window's end until a time outside them.
+        for (let hop = 1; quiet.inside; hop += 1) {
+            if (hop >= maxWindowHops) {
+                // No time outside the windows: the gate would never send it either.
+                return { status: 'quiet-hours' };
+            }
+            fireAt = quiet.until;
+            quiet = checkNotificationQuietHours(fireAt, quietHours, input.timeZone);
+        }
+    }
+    const maxPerDay = input.topic.frequency?.maxPerDay;
+    if (maxPerDay !== undefined && exceedsDailyCount(fireAt, input.pending ?? [], maxPerDay)) {
+        return { status: 'frequency-capped' };
+    }
+    return { status: 'schedule', fireAt };
+}
+/** Whether some 24-hour window around `fireAt` would hold more than `max` reminders with it. */
+function exceedsDailyCount(fireAt, pending, max) {
+    const at = parseInstant(fireAt);
+    const times = pending.map((entry) => parseInstant(entry.fireAt));
+    // Windows [start, start + 24h) that contain `at` start at `at` or at an earlier reminder.
+    const starts = [at, ...times.filter((time) => time <= at && time > at - dayMs)];
+    return starts.some((start) => times.filter((time) => time >= start && time < start + dayMs).length + 1 > max);
+}
+/**
+ * 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 function evaluateNotificationReminderConsent(input) {
+    const gateInput = {
+        entry: input.entry,
+        topic: input.topic,
+        recipientResolved: true,
+        consent: input.consent,
+        ...(input.serverPermission === undefined ? {} : { serverPermission: input.serverPermission }),
+        ...(input.endpointPermission === undefined
+            ? {}
+            : { endpointPermission: input.endpointPermission }),
+        history: input.history,
+        at: '1970-01-01T00:00:00Z',
+        defaultLocale: 'und',
+    };
+    if (deliveryPermissionRefusal(gateInput, input.topic) !== undefined) {
+        return 'permission-required';
+    }
+    const preference = topicPreferenceRefusal(input.topic, input.consent);
+    if (preference !== undefined) {
+        return preference;
+    }
+    if (input.topic.purpose === 'advertising'
+        && latestNotificationConsent(input.consent, 'advertising')?.state !== 'granted') {
+        return 'advertising-consent-missing';
+    }
+    return 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 function createNotificationReminderIdempotencyKey(input) {
+    for (const [name, value] of [
+        ['player', input.player],
+        ['key', input.key],
+    ]) {
+        if (value.length === 0 || /[\uD800-\uDFFF]/u.test(value)) {
+            throw new TypeError(`Reminder idempotency keys need a well-formed, non-empty ${name}.`);
+        }
+    }
+    return `reminder:${encodeURIComponent(input.player)}:${encodeURIComponent(input.key)}:`
+        + normalizeNotificationTimestamp(input.fireAt);
+}
+// Time windows.
+const minuteMs = 60_000;
+const hourMs = 60 * minuteMs;
+const dayMs = 24 * hourMs;
+/** Korea has kept UTC+9 without daylight saving time since 1988. */
+const seoulOffsetMs = 9 * hourMs;
+/** The Korean advertising night window: 21:00 inclusive to 08:00 exclusive, Asia/Seoul. */
+export const notificationNightWindow = Object.freeze({
+    timeZone: 'Asia/Seoul',
+    start: '21:00',
+    end: '08:00',
+});
+/** Whether `at` falls in the night window, and the next 08:00 Asia/Seoul when it does. */
+export function checkNotificationNightWindow(at) {
+    return checkWindow(parseInstant(at), parseClockTime(notificationNightWindow.start), parseClockTime(notificationNightWindow.end), seoulZone);
+}
+/**
+ * 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 function checkNotificationQuietHours(at, quietHours, timeZone) {
+    return checkWindow(parseInstant(at), parseClockTime(quietHours.start), parseClockTime(quietHours.end), timeZone === notificationNightWindow.timeZone ? seoulZone : intlZone(timeZone));
+}
+/** Whether `Intl` knows `timeZone`, so quiet hours can be read in it. */
+export function isValidNotificationTimeZone(timeZone) {
+    try {
+        intlZone(timeZone);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The Asia/Seoul calendar date of an instant, `YYYY-MM-DD`. */
+export function toSeoulCalendarDate(at) {
+    const wall = seoulZone.wall(parseInstant(at));
+    return formatCalendarDate(Date.UTC(wall.year, wall.month - 1, wall.day));
+}
+/**
+ * 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 function normalizeNotificationTimestamp(at) {
+    return formatNotificationTimestamp(parseInstant(at));
+}
+function formatNotificationTimestamp(millis) {
+    const iso = new Date(millis).toISOString();
+    return iso.endsWith('.000Z') ? `${iso.slice(0, -5)}Z` : iso;
+}
+const isoInstantPattern = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/u;
+/**
+ * An RFC 3339 instant with an explicit offset (`T` and `Z` in either case).
+ * A calendar field out of range, such as 31 February or a leap second, is
+ * refused rather than rolled over into the next day.
+ */
+function parseInstant(at) {
+    const millis = instantOrNaN(at);
+    if (Number.isNaN(millis)) {
+        throw new TypeError(`Invalid ISO-8601 timestamp (a date, a time, and an offset): ${at}`);
+    }
+    return millis;
+}
+function instantOrNaN(at) {
+    const match = isoInstantPattern.exec(at);
+    return match === null ? Number.NaN : instantOf(match);
+}
+/**
+ * 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 function isNotificationTimestamp(at) {
+    return !Number.isNaN(instantOrNaN(at));
+}
+/**
+ * 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 function notificationTimeFieldIssue(value, fields, path = '') {
+    if (Array.isArray(value)) {
+        for (const [index, item] of value.entries()) {
+            const issue = notificationTimeFieldIssue(item, fields, `${path}[${index}]`);
+            if (issue !== undefined) {
+                return issue;
+            }
+        }
+        return undefined;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return undefined;
+    }
+    for (const [key, format] of Object.entries(fields)) {
+        if (!Object.prototype.hasOwnProperty.call(value, key)) {
+            continue;
+        }
+        const field = value[key];
+        const at = path === '' ? key : `${path}.${key}`;
+        if (typeof format !== 'string') {
+            const issue = notificationTimeFieldIssue(field, format, at);
+            if (issue !== undefined) {
+                return issue;
+            }
+        }
+        else if (typeof field === 'string'
+            && !(format === 'date' ? isNotificationCalendarDate(field) : isNotificationTimestamp(field))) {
+            return format === 'date'
+                ? `${at} must be a date that exists, YYYY-MM-DD; got ${JSON.stringify(field)}`
+                : `${at} must be RFC 3339 with a date that exists, T, and an offset; got ${JSON.stringify(field)}`;
+        }
+    }
+    return undefined;
+}
+const noticeTimeFields = { record: { at: 'date-time' }, dueBy: 'date' };
+/**
+ * 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 const notificationTimeFields = {
+    LocalNotificationRequest: { fireAt: 'date-time' },
+    LocalNotificationEntry: { fireAt: 'date-time' },
+    NotificationBridgeListLocalResult: { pending: { fireAt: 'date-time' } },
+    NotificationConsentRecord: { at: 'date-time' },
+    NotificationNotice: noticeTimeFields,
+    RecordNotificationNoticeInput: noticeTimeFields,
+    NotificationConformanceVector: {
+        context: { now: 'date-time' },
+        steps: {
+            at: 'date-time',
+            input: { fireAt: 'date-time', ...noticeTimeFields },
+            returns: { until: 'date-time', ...noticeTimeFields },
+        },
+        expect: {
+            deliveries: { until: 'date-time' },
+            providerCalls: { expiresAt: 'date-time' },
+            local: { operations: { fireAt: 'date-time' }, pending: { fireAt: 'date-time' } },
+            reminders: { fireAt: 'date-time' },
+            notices: noticeTimeFields,
+        },
+    },
+};
+function instantOf(match) {
+    const [year, month, day, hour, minute, second] = match.slice(1, 7).map(Number);
+    const offsetHours = Number(match[9] ?? 0);
+    const offsetMinutes = Number(match[10] ?? 0);
+    if (year === undefined
+        || month === undefined
+        || day === undefined
+        || hour === undefined
+        || minute === undefined
+        || second === undefined
+        || month < 1
+        || month > 12
+        || day < 1
+        || day > daysInMonth(year, month)
+        || hour > 23
+        || minute > 59
+        || second > 59
+        || offsetHours > 23
+        || offsetMinutes > 59) {
+        return Number.NaN;
+    }
+    const date = new Date(0);
+    date.setUTCFullYear(year, month - 1, day);
+    date.setUTCHours(hour, minute, second, Number((match[7] ?? '0').slice(0, 3).padEnd(3, '0')));
+    const offsetMs = (offsetHours * 60 + offsetMinutes) * minuteMs;
+    return date.getTime() - (match[8] === '-' ? -offsetMs : offsetMs);
+}
+function daysInMonth(year, month) {
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1] ?? 0;
+}
+function parseClockTime(value) {
+    const match = /^([01][0-9]|2[0-3]):([0-5][0-9])$/u.exec(value);
+    if (match === null) {
+        throw new TypeError(`Invalid clock time ${value}; expected HH:MM.`);
+    }
+    return Number(match[1]) * 60 + Number(match[2]);
+}
+function formatCalendarDate(utcMidnight) {
+    return new Date(utcMidnight).toISOString().slice(0, 10);
+}
+function fixedOffsetZone(offsetMs) {
+    return {
+        wall(millis) {
+            const local = new Date(millis + offsetMs);
+            return {
+                year: local.getUTCFullYear(),
+                month: local.getUTCMonth() + 1,
+                day: local.getUTCDate(),
+                minute: local.getUTCHours() * 60 + local.getUTCMinutes(),
+            };
+        },
+        instants(year, month, day, minute) {
+            return [Date.UTC(year, month - 1, day, 0, minute) - offsetMs];
+        },
+        shiftedInstant(year, month, day, minute) {
+            return Date.UTC(year, month - 1, day, 0, minute) - offsetMs;
+        },
+    };
+}
+const seoulZone = fixedOffsetZone(seoulOffsetMs);
+/** Formatters by zone, least recently used first. */
+const intlFormatters = new Map();
+/** Zone names come from clients; past this many the least recently used zone goes. */
+const intlFormatterLimit = 64;
+/** A zone read through `Intl`, which every supported runtime ships with time zone data. */
+function intlZone(timeZone) {
+    let formatter = intlFormatters.get(timeZone);
+    if (formatter !== undefined) {
+        // Most recently used last.
+        intlFormatters.delete(timeZone);
+        intlFormatters.set(timeZone, formatter);
+    }
+    else {
+        try {
+            formatter = new Intl.DateTimeFormat('en-US', {
+                timeZone,
+                hourCycle: 'h23',
+                year: 'numeric',
+                month: '2-digit',
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                second: '2-digit',
+            });
+        }
+        catch {
+            throw new TypeError(`Unknown time zone: ${timeZone}`);
+        }
+        if (intlFormatters.size >= intlFormatterLimit) {
+            const oldest = intlFormatters.keys().next();
+            if (oldest.done !== true) {
+                intlFormatters.delete(oldest.value);
+            }
+        }
+        intlFormatters.set(timeZone, formatter);
+    }
+    const zoneFormatter = formatter;
+    const read = (millis) => {
+        const fields = {};
+        for (const part of zoneFormatter.formatToParts(new Date(millis))) {
+            fields[part.type] = Number(part.value);
+        }
+        const hour = (fields.hour ?? 0) % 24;
+        return {
+            year: fields.year ?? 1970,
+            month: fields.month ?? 1,
+            day: fields.day ?? 1,
+            minute: hour * 60 + (fields.minute ?? 0),
+            second: fields.second ?? 0,
+        };
+    };
+    const offsetAt = (millis) => {
+        const wall = read(millis);
+        const wallAsUtc = Date.UTC(wall.year, wall.month - 1, wall.day, 0, wall.minute, wall.second);
+        return wallAsUtc - Math.floor(millis / 1000) * 1000;
+    };
+    return {
+        wall: read,
+        instants(year, month, day, minute) {
+            const wallAsUtc = Date.UTC(year, month - 1, day, 0, minute);
+            // The offsets a day either side cover any change on this date.
+            const offsets = new Set([
+                offsetAt(wallAsUtc - dayMs),
+                offsetAt(wallAsUtc),
+                offsetAt(wallAsUtc + dayMs),
+            ]);
+            const matching = [...offsets]
+                .map((offset) => wallAsUtc - offset)
+                .filter((instant) => {
+                const wall = read(instant);
+                return wall.year === year && wall.month === month && wall.day === day
+                    && wall.minute === minute;
+            });
+            return [...new Set(matching)].sort((left, right) => left - right);
+        },
+        shiftedInstant(year, month, day, minute) {
+            const wallAsUtc = Date.UTC(year, month - 1, day, 0, minute);
+            return wallAsUtc - offsetAt(wallAsUtc - dayMs);
+        },
+    };
+}
+function checkWindow(millis, start, end, zone) {
+    if (start === end) {
+        return { inside: false };
+    }
+    const wall = zone.wall(millis);
+    const overnight = start > end;
+    const inside = overnight
+        ? wall.minute >= start || wall.minute < end
+        : wall.minute >= start && wall.minute < end;
+    if (!inside) {
+        return { inside: false };
+    }
+    const endDate = new Date(Date.UTC(wall.year, wall.month - 1, wall.day + (overnight && wall.minute >= start ? 1 : 0)));
+    const year = endDate.getUTCFullYear();
+    const month = endDate.getUTCMonth() + 1;
+    const day = endDate.getUTCDate();
+    // The earliest end after `at`: in a repeated hour the end can occur twice,
+    // and the first occurrence may already be behind a send inside the window.
+    const until = zone.instants(year, month, day, end).find((instant) => instant > millis)
+        ?? zone.shiftedInstant(year, month, day, end);
+    // A window always ends after a time inside it; the guard keeps a scheduler
+    // from replaying a send at the same instant should a zone disagree.
+    return {
+        inside: true,
+        until: formatNotificationTimestamp(until > millis ? until : millis + minuteMs),
+    };
+}
+/** Whether two notices are one: the same kind, record kind, record instant, and `dueBy`. */
+export function isSameNotificationNotice(left, right) {
+    return left.kind === right.kind
+        && left.record.kind === right.record.kind
+        && left.dueBy === right.dueBy
+        && parseInstant(left.record.at) === parseInstant(right.record.at);
+}
+/** Every `NotificationNoticeVariant`, in this order; a test keeps the two equal. */
+export const notificationNoticeVariants = Object.freeze([
+    '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 const notificationNoticeVariantFallbacks = Object.freeze({
+    'consent-result.advertising.refused': 'consent-result.advertising.withdrawn',
+    'consent-result.night.refused': 'consent-result.night.withdrawn',
+});
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 function notificationNoticeCopyIssues(copy, defaultLocale, path = 'notices.copy') {
+    if (copy === undefined) {
+        return [{
+                path,
+                message: 'a notice states what the player did; give a title and a body for each notice variant in each locale',
+            }];
+    }
+    if (!isPlainObject(copy)) {
+        return [{
+                path,
+                message: 'expected NotificationNoticeCopy: each locale mapped to a title and a body per notice variant',
+            }];
+    }
+    const issues = [];
+    const variants = notificationNoticeVariants;
+    // The same lookup a send makes: a locale matches a copy key without regard to case.
+    if (!Object.keys(copy).some((locale) => locale.toLowerCase() === defaultLocale.toLowerCase())) {
+        issues.push({ path, message: `must include the default locale ${defaultLocale}` });
+    }
+    for (const [locale, texts] of Object.entries(copy)) {
+        const at = `${path}[${JSON.stringify(locale)}]`;
+        if (!isPlainObject(texts)) {
+            issues.push({
+                path: at,
+                message: 'expected the notice copy of one locale: a title and a body per notice variant',
+            });
+            continue;
+        }
+        for (const variant of notificationNoticeVariants) {
+            if (texts[variant] === undefined && notificationNoticeVariantFallbacks[variant] === undefined) {
+                issues.push({
+                    path: `${at}[${JSON.stringify(variant)}]`,
+                    message: `every locale needs a title and a body for each notice variant; ${locale} lacks ${variant}`,
+                });
+            }
+        }
+        for (const [variant, text] of Object.entries(texts)) {
+            const variantPath = `${at}[${JSON.stringify(variant)}]`;
+            if (!variants.includes(variant)) {
+                issues.push({
+                    path: variantPath,
+                    message: `is not a notice variant; expected one of ${variants.join(', ')}`,
+                });
+            }
+            else if (text !== undefined) {
+                issues.push(...noticeTextIssues(text, variantPath));
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * One variant's title and body: strings, not blank, and filled only with
+ * `{{consentDate}}`, which one of them uses.
+ */
+function noticeTextIssues(text, path) {
+    if (!isPlainObject(text)) {
+        return [{ path, message: 'expected NotificationTopicCopy: a title and a body' }];
+    }
+    const issues = [];
+    for (const key of Object.keys(text)) {
+        if (key !== 'title' && key !== 'body') {
+            issues.push({
+                path: `${path}.${key}`,
+                message: "is not part of a notice's text; a notice has only a title and a body",
+            });
+        }
+    }
+    let dated = false;
+    for (const field of ['title', 'body']) {
+        const value = text[field];
+        if (typeof value !== 'string') {
+            issues.push({ path: `${path}.${field}`, message: `expected a string ${field}` });
+            continue;
+        }
+        if (value.trim().length === 0) {
+            issues.push({ path: `${path}.${field}`, message: `a notice's ${field} must not be blank` });
+        }
+        const { placeholders, strayBrace } = readNotificationTemplate(value);
+        for (const name of placeholders) {
+            if (name === 'consentDate') {
+                dated = true;
+            }
+            else {
+                issues.push({
+                    path: `${path}.${field}`,
+                    message: `notices are filled only with {{consentDate}}; {{${name}}} would have no value`,
+                });
+            }
+        }
+        if (strayBrace) {
+            issues.push({
+                path: `${path}.${field}`,
+                message: 'a brace outside a {{name}} placeholder reaches the player as written; write {{consentDate}}',
+            });
+        }
+    }
+    if (!dated) {
+        issues.push({
+            path,
+            message: 'a notice states the date of the act it reports on; its title or body needs {{consentDate}}',
+        });
+    }
+    return issues;
+}
+/**
+ * The variant a notice is given in. `act` is what its record was: a consent,
+ * the withdrawal of a consent, or a refusal; a re-confirmation reports on a
+ * consent.
+ */
+function noticeVariantOf(kind, recordKind, act) {
+    return kind === 'reconfirmation'
+        ? `reconfirmation.${recordKind}`
+        : `consent-result.${recordKind}.${act}`;
+}
+/**
+ * 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 function notificationNoticeVariantCopy(copy, variant) {
+    const fallback = notificationNoticeVariantFallbacks[variant];
+    return Object.fromEntries(Object.entries(copy).flatMap(([locale, variants]) => {
+        const text = variants[variant]
+            ?? (fallback === undefined ? undefined : variants[fallback]);
+        return text === undefined ? [] : [[locale, text]];
+    }));
+}
+/**
+ * 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 function notificationProviderCarriesNotices(entry) {
+    return entry.content === 'free-form'
+        && !entry.mappingFields.includes('title')
+        && !entry.mappingFields.includes('body');
+}
+/**
+ * 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 function notificationNoticeTopic(topic, copy, variant) {
+    const { mapping, copy: _ownCopy, ...delivery } = topic;
+    const { title: _title, body: _body, ...rest } = mapping ?? {};
+    return {
+        ...delivery,
+        ...(mapping === undefined ? {} : { mapping: rest }),
+        copy: notificationNoticeVariantCopy(copy, variant),
+    };
+}
+/** Result notice: 14 days after the record's Asia/Seoul date, counted from the next day. */
+export function notificationConsentResultDueBy(at) {
+    return consentResultDueByOf(parseInstant(at));
+}
+function consentResultDueByOf(instant) {
+    const wall = seoulZone.wall(instant);
+    return formatCalendarDate(Date.UTC(wall.year, wall.month - 1, wall.day + 14));
+}
+/**
+ * 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 function notificationReconfirmationDueBy(at, ordinal = 1) {
+    if (!Number.isInteger(ordinal) || ordinal < 1) {
+        throw new TypeError('A re-confirmation ordinal is a whole number from 1.');
+    }
+    return reconfirmationDueByOf(parseInstant(at), ordinal);
+}
+function reconfirmationDueByOf(instant, ordinal) {
+    const wall = seoulZone.wall(instant);
+    const day = wall.month === 2 && wall.day === 29 ? 28 : wall.day;
+    return formatCalendarDate(Date.UTC(wall.year + 2 * ordinal, wall.month - 1, day - 1));
+}
+/** Days before its `dueBy` from which a re-confirmation is listed. */
+export const notificationReconfirmationListDays = 60;
+/** A notice's name as one string, with the record time as an instant in milliseconds. */
+function noticeNameOf(kind, recordKind, instant, dueBy) {
+    return JSON.stringify([kind, recordKind, instant, dueBy]);
+}
+/**
+ * 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 function listNotificationNotices(records, given, at) {
+    const today = toSeoulCalendarDate(at);
+    // Given notices by name, each record time parsed once.
+    const givenNames = new Set(given.map(({ kind, record, dueBy }) => noticeNameOf(kind, record.kind, parseInstant(record.at), dueBy)));
+    // Each advertising or night record parsed once.
+    const parsed = new Map();
+    const notices = [];
+    // Each kind's latest record so far: a withdrawal that follows no consent is a refusal.
+    const latestState = new Map();
+    for (const record of records) {
+        if (record.kind !== 'advertising' && record.kind !== 'night') {
+            continue;
+        }
+        const act = record.state === 'withdrawn' && latestState.get(record.kind) !== 'granted'
+            ? 'refused'
+            : record.state;
+        latestState.set(record.kind, record.state);
+        const instant = parseInstant(record.at);
+        const noticeRecord = {
+            kind: record.kind,
+            state: record.state,
+            at: formatNotificationTimestamp(instant),
+            textVersion: record.textVersion,
+        };
+        parsed.set(record, { instant, record: noticeRecord });
+        const dueBy = consentResultDueByOf(instant);
+        if (!givenNames.has(noticeNameOf('consent-result', record.kind, instant, dueBy))) {
+            // Each notice gets its own copy, so changing one never changes another.
+            notices.push({
+                kind: 'consent-result',
+                record: { ...noticeRecord },
+                dueBy,
+                variant: noticeVariantOf('consent-result', record.kind, act),
+            });
+        }
+    }
+    for (const kind of ['advertising', 'night']) {
+        const latest = latestNotificationConsent(records, kind);
+        const consent = latest === undefined ? undefined : parsed.get(latest);
+        if (consent === undefined || consent.record.state !== 'granted') {
+            continue;
+        }
+        // Each given notice has its own due date, so this ends after the last one given.
+        let ordinal = 1;
+        let dueBy = reconfirmationDueByOf(consent.instant, ordinal);
+        while (givenNames.has(noticeNameOf('reconfirmation', kind, consent.instant, dueBy))) {
+            ordinal += 1;
+            dueBy = reconfirmationDueByOf(consent.instant, ordinal);
+        }
+        if (calendarDaysBefore(dueBy, notificationReconfirmationListDays) <= today) {
+            notices.push({
+                kind: 'reconfirmation',
+                record: { ...consent.record },
+                dueBy,
+                variant: noticeVariantOf('reconfirmation', kind, 'granted'),
+            });
+        }
+    }
+    return notices.sort((left, right) => left.dueBy.localeCompare(right.dueBy) || left.kind.localeCompare(right.kind));
+}
+/** Days before `dueBy` from which the scheduler sends a notice nobody recorded. */
+export const notificationNoticeLeadDays = 7;
+/**
+ * The first Asia/Seoul calendar date the scheduler sends an unrecorded notice:
+ * `notificationNoticeLeadDays` days before `dueBy`.
+ */
+export function notificationNoticeSendFrom(dueBy) {
+    return calendarDaysBefore(dueBy, notificationNoticeLeadDays);
+}
+/** Whether `date` is a calendar date `YYYY-MM-DD` that exists, such as a notice's `dueBy`. */
+export function isNotificationCalendarDate(date) {
+    return !Number.isNaN(calendarDateMillis(date));
+}
+/** UTC midnight of a `YYYY-MM-DD` date; `NaN` when it does not match or does not exist. */
+function calendarDateMillis(date) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/u.exec(date);
+    if (match === null) {
+        return Number.NaN;
+    }
+    const [year, month, day] = match.slice(1, 4).map(Number);
+    if (year === undefined
+        || month === undefined
+        || day === undefined
+        || month < 1
+        || month > 12
+        || day < 1
+        || day > daysInMonth(year, month)) {
+        return Number.NaN;
+    }
+    const midnight = new Date(0);
+    midnight.setUTCFullYear(year, month - 1, day);
+    return midnight.getTime();
+}
+/** The calendar date `days` days before `date`; a date that does not exist is a caller error. */
+function calendarDaysBefore(date, days) {
+    const millis = calendarDateMillis(date);
+    if (Number.isNaN(millis)) {
+        throw new TypeError(`Invalid calendar date ${date}; expected YYYY-MM-DD.`);
+    }
+    return formatCalendarDate(millis - days * dayMs);
+}
+/**
+ * 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 function createNotificationNoticeIdempotencyKey(input) {
+    if (input.player.length === 0 || /[\uD800-\uDFFF]/u.test(input.player)) {
+        throw new TypeError('Notice idempotency keys need a well-formed, non-empty player.');
+    }
+    if ((input.kind !== 'consent-result' && input.kind !== 'reconfirmation')
+        || (input.record.kind !== 'advertising' && input.record.kind !== 'night')
+        || !isNotificationCalendarDate(input.dueBy)) {
+        throw new TypeError('Notice idempotency keys need a notice kind, an advertising or night record, and a dueBy date.');
+    }
+    return `notice:${encodeURIComponent(input.player)}:${input.kind}:${input.record.kind}:`
+        + `${normalizeNotificationTimestamp(input.record.at)}:${input.dueBy}`;
+}
+function deepFreeze(value) {
+    if (typeof value === 'object' && value !== null) {
+        for (const nested of Object.values(value)) {
+            deepFreeze(nested);
+        }
+        Object.freeze(value);
+    }
+    return value;
+}