@mpgd/game-services 0.34.0 → 0.35.0

package/dist/notifications/bulk.js

@@ -0,0 +1,229 @@
+import { isValidNotificationTimeZone, NotificationError, notificationKeyIssue, notificationReservedKeyPrefix, } from '@mpgd/platform/notifications';
+/**
+ * Bulk sends (notifications v2 RFC, open question 5; BK1): the request and
+ * answer types of `NotificationService.deliverBulk`, and the small pieces it
+ * is built from. A bulk send is many single sends that share provider calls:
+ * each recipient keeps its own key, ledger row, gate check, and answer.
+ */
+/** Most recipients one `deliverBulk` call takes. */
+export const maxNotificationBulkRecipients = 10_000;
+/** The send key of one recipient of a bulk send. */
+export function notificationBulkRecipientKey(idempotencyKey, player) {
+    return `${idempotencyKey}:${encodeURIComponent(player)}`;
+}
+/**
+ * A well-formed bulk request, or `NOTIFICATIONS_INVALID_INPUT` for the whole
+ * call. Each recipient's own request (its template data, data, locale, and
+ * link, and its derived key) is checked later as a single send's is, and
+ * fails that recipient alone.
+ */
+export function parseNotificationBulkRequest(raw) {
+    if (!isPlainObject(raw)) {
+        throw invalid('A bulk send is an object.');
+    }
+    const known = new Set([
+        'idempotencyKey',
+        'provider',
+        'topic',
+        'recipients',
+        'templateData',
+        'data',
+        'locale',
+        'link',
+        'batchSize',
+    ]);
+    const unknown = Object.keys(raw).find((key) => !known.has(key));
+    if (unknown !== undefined) {
+        throw invalid(`Invalid bulk send: ${unknown}: not a bulk send field.`);
+    }
+    if (typeof raw.idempotencyKey !== 'string') {
+        throw invalid('Invalid bulk send: idempotencyKey: expected a string.');
+    }
+    const keyIssue = notificationKeyIssue(raw.idempotencyKey);
+    if (keyIssue !== undefined) {
+        throw invalid(`Invalid bulk send: idempotencyKey: ${keyIssue}.`);
+    }
+    const reserved = notificationReservedKeyPrefix(raw.idempotencyKey);
+    if (reserved !== undefined) {
+        throw invalid(`Invalid bulk send: idempotencyKey: the ${reserved} prefix is reserved for the scheduler.`);
+    }
+    for (const name of ['provider', 'topic']) {
+        if (typeof raw[name] !== 'string' || raw[name].length === 0 || raw[name].length > 2048) {
+            throw invalid(`Invalid bulk send: ${name}: expected a non-empty string.`);
+        }
+    }
+    if (raw.batchSize !== undefined
+        && !(typeof raw.batchSize === 'number' && Number.isSafeInteger(raw.batchSize) && raw.batchSize >= 1)) {
+        throw invalid('Invalid bulk send: batchSize: expected a positive integer.');
+    }
+    const recipients = raw.recipients;
+    if (!Array.isArray(recipients) || recipients.length === 0 || recipients.length > maxNotificationBulkRecipients) {
+        throw invalid(`Invalid bulk send: recipients: expected 1 to ${maxNotificationBulkRecipients} recipients.`);
+    }
+    const recipientFields = new Set(['player', 'templateData', 'data', 'locale', 'link']);
+    const players = new Set();
+    const keys = [];
+    for (const [index, recipient] of recipients.entries()) {
+        if (!isPlainObject(recipient)) {
+            throw invalid(`Invalid bulk send: recipients[${index}]: expected an object.`);
+        }
+        const field = Object.keys(recipient).find((key) => !recipientFields.has(key));
+        if (field !== undefined) {
+            throw invalid(`Invalid bulk send: recipients[${index}].${field}: not a recipient field.`);
+        }
+        const player = recipient.player;
+        if (typeof player !== 'string' || player.length === 0 || player.length > 2048) {
+            throw invalid(`Invalid bulk send: recipients[${index}].player: expected a non-empty string.`);
+        }
+        if (players.has(player)) {
+            // One send per player: a second would be a second key for the same push.
+            throw invalid(`Invalid bulk send: recipients[${index}].player: a player is named once.`);
+        }
+        players.add(player);
+        try {
+            keys.push(notificationBulkRecipientKey(raw.idempotencyKey, player));
+        }
+        catch {
+            // `encodeURIComponent` refuses a lone surrogate, which no key may hold.
+            throw invalid(`Invalid bulk send: recipients[${index}].player: holds a lone surrogate.`);
+        }
+    }
+    return { input: raw, keys };
+}
+/**
+ * A provider's bulk capability as the registry accepts it: whole numbers,
+ * a minimum no larger than the maximum, and a hold window of two `HH:MM`
+ * times in a valid time zone. Throws a `TypeError` naming the issue.
+ */
+export function assertNotificationBulkCapability(capability, at) {
+    const { maxRecipients, minRecipients, perRecipientOutcomes, holdWindow } = capability;
+    if (!Number.isSafeInteger(maxRecipients) || maxRecipients < 1) {
+        throw new TypeError(`${at}.bulk.maxRecipients must be a positive integer.`);
+    }
+    if (minRecipients !== undefined
+        && (!Number.isSafeInteger(minRecipients) || minRecipients < 1 || minRecipients > maxRecipients)) {
+        throw new TypeError(`${at}.bulk.minRecipients must be a positive integer no larger than maxRecipients.`);
+    }
+    if (typeof perRecipientOutcomes !== 'boolean') {
+        throw new TypeError(`${at}.bulk.perRecipientOutcomes must be a boolean.`);
+    }
+    if (holdWindow !== undefined) {
+        if (minutesOf(holdWindow.start) === undefined
+            || minutesOf(holdWindow.end) === undefined
+            || holdWindow.start === holdWindow.end
+            || !isValidNotificationTimeZone(holdWindow.timeZone)) {
+            throw new TypeError(`${at}.bulk.holdWindow needs two different HH:MM times and a valid time zone.`);
+        }
+    }
+}
+/** Whether `at` (epoch milliseconds) falls inside a provider's hold window. */
+export function isInsideNotificationHoldWindow(window, at) {
+    if (window === undefined) {
+        return false;
+    }
+    const start = minutesOf(window.start);
+    const end = minutesOf(window.end);
+    if (start === undefined || end === undefined) {
+        return false;
+    }
+    const parts = new Intl.DateTimeFormat('en-GB', {
+        timeZone: window.timeZone,
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23',
+    }).formatToParts(new Date(at));
+    const hour = Number(parts.find((part) => part.type === 'hour')?.value);
+    const minute = Number(parts.find((part) => part.type === 'minute')?.value);
+    const now = hour * 60 + minute;
+    return start < end ? now >= start && now < end : now >= start || now < end;
+}
+function minutesOf(time) {
+    const match = /^([01]\d|2[0-3]):([0-5]\d)$/u.exec(time);
+    return match === null ? undefined : Number(match[1]) * 60 + Number(match[2]);
+}
+/** A counting semaphore: at most `concurrency` holders at once, served in order. */
+export function createNotificationLimiter(concurrency) {
+    let active = 0;
+    const waiting = [];
+    return {
+        acquire() {
+            if (active < concurrency) {
+                active += 1;
+                return Promise.resolve();
+            }
+            return new Promise((resolve) => {
+                waiting.push(resolve);
+            });
+        },
+        release() {
+            const next = waiting.shift();
+            if (next === undefined) {
+                active -= 1;
+            }
+            else {
+                // The slot passes to the next waiter.
+                next();
+            }
+        },
+    };
+}
+/**
+ * Gathers the provider calls of a known number of participants into one
+ * flush. Each participant either arrives with its item, and waits for its
+ * answer, or leaves without one; once every participant did one or the
+ * other, `flush` runs once with the arrived items and answers each in
+ * order. A participant that holds a concurrency slot gives it up before it
+ * waits (see `deliverBulk`), so the barrier never waits on a participant
+ * that cannot run.
+ */
+export function createNotificationBatchBarrier(participants, flush) {
+    const arrived = [];
+    let left = 0;
+    let flushed = false;
+    const maybeFlush = () => {
+        if (flushed || arrived.length + left < participants) {
+            return;
+        }
+        flushed = true;
+        if (arrived.length === 0) {
+            return;
+        }
+        const items = arrived.map((entry) => entry.item);
+        flush(items).then((answers) => {
+            arrived.forEach((entry, index) => {
+                const answer = answers[index];
+                if (answer === undefined) {
+                    entry.reject(new TypeError('The batch flush answered fewer items than it took.'));
+                }
+                else {
+                    entry.resolve(answer);
+                }
+            });
+        }, (error) => {
+            for (const entry of arrived) {
+                entry.reject(error);
+            }
+        });
+    };
+    return {
+        arrive(item) {
+            if (flushed) {
+                return Promise.reject(new TypeError('The batch was already flushed.'));
+            }
+            return new Promise((resolve, reject) => {
+                arrived.push({ item, resolve, reject });
+                maybeFlush();
+            });
+        },
+        leave() {
+            left += 1;
+            maybeFlush();
+        },
+    };
+}
+function invalid(message) {
+    return new NotificationError('NOTIFICATIONS_INVALID_INPUT', { message });
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/notifications/copy.d.ts

@@ -0,0 +1,87 @@
+import { type NotificationNoticeVariant, type NotificationResolvedCopy, type NotificationTemplateData, type NotificationTopicCopy, type NotificationTopicDeclaration } from '@mpgd/platform/notifications';
+/**
+* Server-side copy for remote sends (notifications v2 RFC, "Remote copy",
+* open question 4). A send's title and body come from a copy resolver: by
+* default the catalog's `copy` for the recipient's locale
+* (`resolveCatalogNotificationCopy`), or a project's own resolver passed to
+* `createNotificationService` as `resolveCopy`. The service asks the
+* resolver only where the content comes from copy
+* (`notificationContentSource` is `catalog`): a target mapping's own title
+* and body (Devvit) and a host template (Apps in Toss) never reach it.
+*
+* The text never comes from the request: a send or a reminder carries no
+* title or body, only template data for the `{{name}}` placeholders of the
+* text the resolver answers. The policy gate then renders the answer exactly
+* as it renders catalog copy, so under the Korean rules an advertising send
+* still gets the `(광고)` label, the sender line, the opt-out line, and the
+* opt-out action.
+*/
+/** What a copy resolver is asked: one topic, for one recipient's locale, on one provider. */
+export interface NotificationCopyResolverInput {
+  /**
+  * The topic as declared for the recipient's target, with its mapping and
+  * its catalog `copy`; for a consent notice, the notice topic with the
+  * variant's `notices.copy` as its `copy`.
+  */
+  readonly topic: NotificationTopicDeclaration;
+  /** The provider the send goes through. */
+  readonly provider: string;
+  /**
+  * The send's locale, else the recipient's registered locale; absent when
+  * neither names one. A resolver falls back from it as the catalog lookup
+  * does: the exact locale, then its language, then `defaultLocale`.
+  */
+  readonly locale?: string;
+  /** The catalog's `defaultLocale`. */
+  readonly defaultLocale: string;
+  /**
+  * The send's template data, which fills the answer's placeholders after
+  * the resolver answers. It may come from a player's reminder: a resolver
+  * must not copy it into the text it answers.
+  */
+  readonly templateData?: NotificationTemplateData;
+  /** Set for a consent notice the scheduler pushes: the variant whose text it sends. */
+  readonly notice?: {
+    readonly variant: NotificationNoticeVariant;
+  };
+}
+/**
+* Chooses the title and body templates of one send for one locale, or
+* answers `undefined` when it has none: the send is then skipped as
+* `unavailable: copy-missing`, never sent with empty text. The answer's
+* `{{name}}` placeholders are filled from the send's template data, as
+* catalog copy is. A resolver that throws fails the attempt, and the send
+* is retried: a `NotificationError` keeps its own code, and any other throw
+* is a copy outage (`NOTIFICATIONS_TEMPORARILY_UNAVAILABLE`).
+*/
+export type NotificationCopyResolver = (input: NotificationCopyResolverInput) => NotificationTopicCopy | undefined | Promise<NotificationTopicCopy | undefined>;
+/**
+* The default resolver: the topic's catalog `copy` for the locale, then its
+* language (`en` for `en-US`), then the catalog's `defaultLocale`, each
+* matched without regard to case (`findNotificationCopy`). A project's
+* resolver can fall back to it for the topics or locales it does not cover:
+* `(input) => mine(input) ?? resolveCatalogNotificationCopy(input)`.
+*/
+export declare const resolveCatalogNotificationCopy: NotificationCopyResolver;
+/** A resolver's answer as a send uses it, with why an answer was not usable. */
+export interface NotificationCopyResolution extends NotificationResolvedCopy {
+  /** Set when the resolver answered something that cannot be sent; `copy` is then absent. */
+  readonly issue?: string;
+}
+/**
+* Asks `resolver` once and checks the answer: a title and a body that are
+* strings and not blank, and for a consent notice the notice text rules
+* (`notificationNoticeTextIssues`: only `{{consentDate}}`, which one of them
+* uses). An answer that fails is no copy, with the reason in `issue`. The
+* result's `copy` is what the gate takes as `resolvedCopy`.
+*/
+export declare function resolveNotificationCopy(resolver: NotificationCopyResolver, input: NotificationCopyResolverInput): Promise<NotificationCopyResolution>;
+/**
+* Resolves one topic for several locales, asking `resolver` once per
+* distinct locale (an absent locale counts as one): a bulk send groups its
+* recipients by locale and sends each group the copy resolved for it. The
+* map is keyed by the locales as given.
+*/
+export declare function resolveNotificationCopyByLocale(resolver: NotificationCopyResolver, input: Omit<NotificationCopyResolverInput, 'locale'> & {
+  readonly locales: Iterable<string | undefined>;
+}): Promise<Map<string | undefined, NotificationCopyResolution>>;

package/dist/notifications/copy.js

@@ -0,0 +1,70 @@
+import { findNotificationCopy, notificationNoticeTextIssues, } from '@mpgd/platform/notifications';
+/**
+ * The default resolver: the topic's catalog `copy` for the locale, then its
+ * language (`en` for `en-US`), then the catalog's `defaultLocale`, each
+ * matched without regard to case (`findNotificationCopy`). A project's
+ * resolver can fall back to it for the topics or locales it does not cover:
+ * `(input) => mine(input) ?? resolveCatalogNotificationCopy(input)`.
+ */
+export const resolveCatalogNotificationCopy = (input) => findNotificationCopy(input.topic, input.locale, input.defaultLocale);
+/**
+ * Asks `resolver` once and checks the answer: a title and a body that are
+ * strings and not blank, and for a consent notice the notice text rules
+ * (`notificationNoticeTextIssues`: only `{{consentDate}}`, which one of them
+ * uses). An answer that fails is no copy, with the reason in `issue`. The
+ * result's `copy` is what the gate takes as `resolvedCopy`.
+ */
+export async function resolveNotificationCopy(resolver, input) {
+    const answer = await resolver(input);
+    if (answer === undefined || answer === null) {
+        return {};
+    }
+    const issue = copyIssue(answer, input);
+    if (issue !== undefined) {
+        return { issue };
+    }
+    const { title, body } = answer;
+    return { copy: { title, body } };
+}
+/**
+ * Resolves one topic for several locales, asking `resolver` once per
+ * distinct locale (an absent locale counts as one): a bulk send groups its
+ * recipients by locale and sends each group the copy resolved for it. The
+ * map is keyed by the locales as given.
+ */
+export async function resolveNotificationCopyByLocale(resolver, input) {
+    const { locales, ...shared } = input;
+    const resolved = new Map();
+    for (const locale of locales) {
+        if (!resolved.has(locale)) {
+            resolved.set(locale, await resolveNotificationCopy(resolver, {
+                ...shared,
+                ...(locale === undefined ? {} : { locale }),
+            }));
+        }
+    }
+    return resolved;
+}
+function copyIssue(answer, input) {
+    if (typeof answer !== 'object' || answer === null || Array.isArray(answer)) {
+        return 'the copy resolver answered something other than a title and a body';
+    }
+    const { title, body } = answer;
+    if (typeof title !== 'string' || typeof body !== 'string') {
+        return 'the copy resolver answered no string title and body';
+    }
+    if (title.trim().length === 0 || body.trim().length === 0) {
+        return 'the copy resolver answered a blank title or body';
+    }
+    if (input.notice !== undefined) {
+        // Every notice variant follows the same text rules (`notificationNoticeCopyIssues`
+        // applies them to each one); the path names the answer as notices.copy would.
+        const issues = notificationNoticeTextIssues({ title, body }, `notices.copy[${JSON.stringify(input.locale ?? input.defaultLocale)}][${JSON.stringify(input.notice.variant)}]`);
+        if (issues.length > 0) {
+            return `the copy resolver's notice text breaks the notice rules: ${issues
+                .map((issue) => `${issue.path}: ${issue.message}`)
+                .join('; ')}`;
+        }
+    }
+    return undefined;
+}

package/dist/notifications/delivery-provider.d.ts

@@ -89,10 +89,17 @@ export interface NotificationRemoteDeliveryRequest {
 *   answer). The claim is kept until its lease ends.
 *
 * A provider that throws is treated as `ambiguous`.
+*
+* A batch may also answer `not-sent` for a request it made no call for (its
+* calls ran past `startWithinMs`): the row goes back as it was, due again
+* shortly, without a rate-limit backoff or the 24-hour give-up, since no
+* provider refused anything.
 */
 export type NotificationRemoteDeliveryAnswer = {
   readonly status: 'accepted';
   readonly providerMessageId?: string;
+} | {
+  readonly status: 'not-sent';
 } | {
   readonly status: 'unregistered';
 } | {
@@ -106,8 +113,69 @@ export type NotificationRemoteDeliveryAnswer = {
 } | {
   readonly status: 'ambiguous';
   readonly providerCode?: string;
+  /**
+  * A bulk call that reached some of its recipients and did not say which
+  * (BK1). A replay would reach those recipients again, so the delivery is
+  * not replayed: it stays in flight until its key's retention ends, and
+  * the backend reports it. Only a batch answer sets it.
+  */
+  readonly unattributed?: true;
 };
 /**
+* A provider's bulk path (RFC open question 5, BK1): one provider call for
+* several recipients of one topic, each with its own ledger key and answer.
+* A provider without it sends one recipient per call.
+*/
+export interface NotificationRemoteBulkCapability {
+  /** The most recipients one `sendBatch` call takes. */
+  readonly maxRecipients: number;
+  /**
+  * The fewest recipients the bulk API is meant for; a smaller batch goes
+  * one recipient per `send` call. 2 by default.
+  */
+  readonly minRecipients?: number;
+  /**
+  * Whether the provider's answer names each recipient. `false` means it
+  * answers the batch as a whole (counts only): the provider then gives
+  * every recipient the same answer, `accepted` only when the counts prove
+  * each one, and `ambiguous` with `unattributed` when they prove only that
+  * some were reached.
+  */
+  readonly perRecipientOutcomes: boolean;
+  /**
+  * A daily window, in a time zone, in which the host holds bulk messages
+  * until it ends (Apps in Toss holds `send-bulk-message` from 21:00 to
+  * 08:00). The service sends one recipient per call inside it, so the
+  * gate's timing stands.
+  */
+  /**
+  * The provider's call group of a request: requests with different keys
+  * never share a call (Devvit takes one title and body a call). The
+  * service makes one `sendBatch` per group and runs the gate again for
+  * each request just before its group's call, so a later call never sends
+  * on a stale gate check. One group when absent.
+  */
+  callKey?(request: NotificationRemoteDeliveryRequest): string;
+  readonly holdWindow?: {
+    /** `HH:MM`, inclusive. */
+    readonly start: string;
+    /** `HH:MM`, exclusive; earlier than `start` when the window spans midnight. */
+    readonly end: string;
+    /** An IANA time zone. */
+    readonly timeZone: string;
+  };
+}
+/** How long a provider may keep starting calls for one `sendBatch`. */
+export interface NotificationRemoteBatchOptions {
+  /**
+  * Milliseconds from the start of `sendBatch` after which the provider
+  * starts no further call (one batch may take several, such as one per
+  * text): the requests' claims must outlive the calls. A request it did not
+  * start answers `not-sent`.
+  */
+  readonly startWithinMs?: number;
+}
+/**
 * The provider code of a `rejected` answer for a message that would arrive
 * after its expiry: nothing was sent, and it is routine, not a setup error.
 */
@@ -117,6 +185,17 @@ export interface NotificationRemoteDeliveryProvider {
   /** Equals the registry entry's `provider`. */
   readonly id: NotificationProviderId;
   send(request: NotificationRemoteDeliveryRequest): Promise<NotificationRemoteDeliveryAnswer>;
+  /** The bulk path, declared with `sendBatch`; without it every recipient is one `send`. */
+  readonly bulk?: NotificationRemoteBulkCapability;
+  /**
+  * One provider call for `requests` (at most `bulk.maxRecipients`, each a
+  * different recipient of the same send kind): the answers in the order of
+  * the requests, one per request. The service runs the gate for each
+  * request before the call and settles each answer on that request's own
+  * ledger key; an answer that is missing or not one of the five kinds is
+  * `ambiguous`, as a throw is for every request.
+  */
+  sendBatch?(requests: readonly NotificationRemoteDeliveryRequest[], options?: NotificationRemoteBatchOptions): Promise<readonly NotificationRemoteDeliveryAnswer[]>;
   /**
   * The host's permission at send time, for a provider whose registry entry
   * is `serverReadable` (Devvit `isOptedIn`). The gate requires it there.

package/dist/notifications/index.d.ts

@@ -3,8 +3,11 @@
 * "Server"): the provider registry, the endpoint registry, consent records
 * and the notices API, sends through the policy gate, server reminders and
 * the scheduler (consent notice pushes, paced due rows), and the remote
-* delivery provider contract, with the FCM provider.
+* delivery provider contract, with the FCM provider, and the copy resolver
+* port that chooses a send's localized title and body.
 */
+export * from './bulk.js';
+export * from './copy.js';
 export * from './delivery-provider.js';
 export * from './fcm.js';
 export * from './registry.js';

package/dist/notifications/index.js

@@ -3,8 +3,11 @@
  * "Server"): the provider registry, the endpoint registry, consent records
  * and the notices API, sends through the policy gate, server reminders and
  * the scheduler (consent notice pushes, paced due rows), and the remote
- * delivery provider contract, with the FCM provider.
+ * delivery provider contract, with the FCM provider, and the copy resolver
+ * port that chooses a send's localized title and body.
  */
+export * from './bulk.js';
+export * from './copy.js';
 export * from './delivery-provider.js';
 export * from './fcm.js';
 export * from './registry.js';

package/dist/notifications/registry.js

@@ -1,5 +1,6 @@
 import { assertNotificationTopicCatalog, resolveNotificationTopicsForTarget, } from '@mpgd/catalog';
 import { assertNotificationDeliveryProviderEntry, assertNotificationDeployment, referenceNotificationTargetProviders, } from '@mpgd/platform/notifications';
+import { assertNotificationBulkCapability } from './bulk.js';
 import { describeError as describe } from './text.js';
 /**
  * The server-side provider registry (notifications v2 RFC, "Provider
@@ -50,6 +51,13 @@ export function createNotificationProviderRegistry(registrations) {
         if (entry.permission.serverReadable && registration.delivery.readPermission === undefined) {
             throw new TypeError(`${at}: provider ${entry.provider} is server-readable but its delivery provider has no readPermission.`);
         }
+        const { bulk, sendBatch } = registration.delivery;
+        if ((bulk === undefined) !== (sendBatch === undefined)) {
+            throw new TypeError(`${at}: provider ${entry.provider} declares a bulk capability and sendBatch together, or neither.`);
+        }
+        if (bulk !== undefined) {
+            assertNotificationBulkCapability(bulk, at);
+        }
         for (const limit of entry.limits ?? []) {
             if (limit.windowSeconds > maxHistoryWindowSeconds) {
                 throw new TypeError(`${at}: a limit window of ${limit.windowSeconds} seconds is longer than the ${notificationHistoryRetentionDays}-day delivery history.`);

package/dist/notifications/service.d.ts

@@ -1,4 +1,6 @@
 import { NotificationError, type NotificationConsentRecord, type NotificationDeliveryOutcome, type NotificationDeployment, type NotificationNotice, type NotificationTemplateData } from '@mpgd/platform/notifications';
+import { type NotificationBulkDeliverOptions, type NotificationBulkDeliveryResult } from './bulk.js';
+import { type NotificationCopyResolver } from './copy.js';
 import { type NotificationProviderRegistry, type NotificationProviderRegistrySnapshot, type NotificationServiceCatalog } from './registry.js';
 import { type NotificationNoticeChannel, type NotificationPurgeCounts, type NotificationStore } from './store.js';
 /**
@@ -70,6 +72,17 @@ export interface CreateNotificationServiceInput {
     readonly player: string;
   }) => string | undefined | Promise<string | undefined>;
   /**
+  * Chooses a send's title and body per recipient locale where the content
+  * comes from copy (not a mapping's own text or a host template): reminders,
+  * consent notices, and direct sends alike. It replaces the default,
+  * `resolveCatalogNotificationCopy` (the catalog's `copy`, falling back to
+  * the language and then `defaultLocale`); a resolver that wants that
+  * fallback calls it. No copy skips the recipient as `unavailable:
+  * copy-missing`, and a resolver that throws is retried as a host that
+  * cannot answer is.
+  */
+  readonly resolveCopy?: NotificationCopyResolver;
+  /**
   * Runs dispatch jobs later, so a fan-out never exceeds one invocation's
   * subrequest limit. Without it every job runs inline before `deliver`
   * answers.
@@ -159,6 +172,25 @@ export interface NotificationService {
   }): Promise<void>;
   /** One send through the ledger, the gate, and the providers. */
   deliver(input: unknown): Promise<NotificationDeliveryOutcome>;
+  /**
+  * A bulk send (RFC open question 5): one topic to many players through one
+  * provider, each recipient a single send with its own key
+  * (`<idempotencyKey>:<encodeURIComponent(player)>`), ledger row, and gate
+  * check, made immediately before its batch's provider call. Recipients the
+  * gate refuses never reach the provider. A provider with a bulk capability
+  * gets one `sendBatch` call per batch of allowed recipients (one `send`
+  * each below its `minRecipients` or inside its hold window); any other
+  * provider gets one `send` per recipient. The same call retried answers
+  * recipients already sent from the ledger and sends only the rest.
+  *
+  * It is an operator action from the game's server, like `deliver`: never
+  * serve it to a client session. `options` are the host's bounds: no batch
+  * starts after `budgetMs`, and recipients past `maxRecipients` attempts, or
+  * past the provider's `rate` budget, answer `not-attempted`. A recipient
+  * answered from the ledger is no attempt, though its key is still read:
+  * resend only the `not-attempted` recipients to keep a retry small.
+  */
+  deliverBulk(input: unknown, options?: NotificationBulkDeliverOptions): Promise<NotificationBulkDeliveryResult>;
   /** Runs one queued dispatch job; a job that is no longer due does nothing. */
   dispatch(job: NotificationDispatchJob): Promise<void>;
   /**