@mpgd/game-services 0.34.0 → 0.35.0

package/dist/notifications/ait-functional-delivery.d.ts

@@ -43,6 +43,27 @@ import type { AppsInTossMutualTlsFetcher } from '../apps-in-toss-partner-api.js'
 */
 export declare const aitFunctionalMessageProviderId: "apps-in-toss";
 export declare const aitFunctionalMessagePath = "api-partner/v1/apps-in-toss/messenger/send-message";
+/**
+* The bulk functional-message API (BK1), checked 2026-11-01 in
+* https://developers-apps-in-toss.toss.im/documentation/common/growth/smart-message.md
+* ("대량 메시지 발송하기") and the partner API's `sendBulkMessage` operation in
+* https://developers-apps-in-toss.toss.im/api/push.md:
+* - `POST /api-partner/v1/apps-in-toss/messenger/send-bulk-message` with
+*   `{ templateSetCode, contextList }`, each item `{ userKey | anonKey, context }`
+*   (the recipient goes in the body, not a header).
+* - It is meant for 50 or more recipients, and one call takes at most 2,500.
+* - Messages requested from 21:00 to before 08:00 are held and sent after
+*   08:00.
+* - The answer has the `send-message` shape: per-channel counts and lists of
+*   `{ contentId, reachedFailReason? }`, which name no recipient. Its
+*   business errors are 5004, 4034, and 4095 as for `send-message`, and the
+*   API is limited to 3,000 calls per minute per app.
+*/
+export declare const aitFunctionalBulkMessagePath = "api-partner/v1/apps-in-toss/messenger/send-bulk-message";
+/** The fewest recipients the bulk API is meant for; fewer go one `send-message` call each. */
+export declare const aitFunctionalBulkMessageMinRecipients = 50;
+/** The most recipients one `send-bulk-message` call takes. */
+export declare const aitFunctionalBulkMessageMaxRecipients = 2500;
 export declare const defaultAitFunctionalMessageBaseUrl = "https://apps-in-toss-api.toss.im";
 /**
 * Hosts the partner certificate and the recipient key may be sent to.
@@ -84,6 +105,10 @@ export type AitFunctionalMessageAnswer = {
   readonly status: 'rate-limited';
   readonly retryAfterSeconds?: number;
   readonly providerCode?: string;
+}
+/** A bulk request no call was started for (past `startWithinMs`): nothing was sent. */
+| {
+  readonly status: 'not-sent';
 } | {
   readonly status: 'rejected';
   readonly reason: AitFunctionalMessageRejection;
@@ -92,6 +117,8 @@ export type AitFunctionalMessageAnswer = {
 } | {
   readonly status: 'ambiguous';
   readonly providerCode?: string;
+  /** A bulk call that reached some recipients without saying which: not replayed. */
+  readonly unattributed?: true;
 };
 /**
 * Who one delivery goes to. Apps in Toss recipients are platform users whose
@@ -109,7 +136,7 @@ export type AitFunctionalMessageRecipient = {
 export interface AitFunctionalMessageDeliveryRequest {
   readonly recipient: AitFunctionalMessageRecipient;
   /** The topic as declared for this provider: its mapping carries `templateSetCode`. */
-  readonly topic: Pick<NotificationTopicDeclaration, 'id' | 'mapping'>;
+  readonly topic: Pick<NotificationTopicDeclaration, 'id' | 'mapping'> & Partial<Pick<NotificationTopicDeclaration, 'purpose'>>;
   /** The template's `context` values. */
   readonly templateData?: NotificationTemplateData;
   readonly signal?: AbortSignal;
@@ -151,6 +178,43 @@ export interface AitFunctionalMessageDeliveryProvider {
   /** The registry entry the policy gate reads for this provider. */
   readonly entry: NotificationDeliveryProviderEntry;
   send(request: AitFunctionalMessageDeliveryRequest): Promise<AitFunctionalMessageAnswer>;
+  /**
+  * The bulk path: 50 to 2,500 recipients a call, answered as a whole (the
+  * answer names no recipient), and held by the host from 21:00 to 08:00
+  * Asia/Seoul. The declared window starts at 20:55, so a call in flight
+  * never lands in the hold; the service sends one by one inside it.
+  */
+  readonly bulk: {
+    readonly maxRecipients: number;
+    readonly minRecipients: number;
+    readonly perRecipientOutcomes: false;
+    callKey(request: AitFunctionalMessageDeliveryRequest): string;
+    readonly holdWindow: {
+      readonly start: string;
+      readonly end: string;
+      readonly timeZone: string;
+    };
+  };
+  /**
+  * One `send-bulk-message` call per template set code, answered in the
+  * order of `requests`. Every recipient of a call gets the call's answer:
+  * `accepted` only when one channel's sent count equals the recipients
+  * (the kit reads a channel as reaching each recipient at most once per
+  * message, which the documentation does not state) or the channels'
+  * sent counts add up to exactly the recipients (read as each recipient
+  * reached on at most one channel per message, also not stated), `rejected` with
+  * reason `recipient` when nothing was sent on any channel, and otherwise
+  * `ambiguous` with `unattributed` (code `BULK_PARTIAL`): some were
+  * reached, and a replay would reach them again. A failure of the whole
+  * call maps as for `send` (4095 and HTTP 429 `rate-limited`, 5004 and 4034
+  * `configuration`), except that an `agreement` code reads as `recipient`,
+  * since the call names no recipient whose agreement is missing. A request
+  * `send` would refuse, or an `advertising` topic (functional messages
+  * carry no advertising), is `rejected` without a call.
+  */
+  sendBatch(requests: readonly AitFunctionalMessageDeliveryRequest[], options?: {
+    readonly startWithinMs?: number;
+  }): Promise<readonly AitFunctionalMessageAnswer[]>;
 }
 /**
 * Creates the provider. `send` never throws for a partner API answer: every

package/dist/notifications/ait-functional-delivery.js

@@ -42,6 +42,27 @@ import { notificationTemplateDataIssue, referenceNotificationProviders, } from '
  */
 export const aitFunctionalMessageProviderId = 'apps-in-toss';
 export const aitFunctionalMessagePath = 'api-partner/v1/apps-in-toss/messenger/send-message';
+/**
+ * The bulk functional-message API (BK1), checked 2026-11-01 in
+ * https://developers-apps-in-toss.toss.im/documentation/common/growth/smart-message.md
+ * ("대량 메시지 발송하기") and the partner API's `sendBulkMessage` operation in
+ * https://developers-apps-in-toss.toss.im/api/push.md:
+ * - `POST /api-partner/v1/apps-in-toss/messenger/send-bulk-message` with
+ *   `{ templateSetCode, contextList }`, each item `{ userKey | anonKey, context }`
+ *   (the recipient goes in the body, not a header).
+ * - It is meant for 50 or more recipients, and one call takes at most 2,500.
+ * - Messages requested from 21:00 to before 08:00 are held and sent after
+ *   08:00.
+ * - The answer has the `send-message` shape: per-channel counts and lists of
+ *   `{ contentId, reachedFailReason? }`, which name no recipient. Its
+ *   business errors are 5004, 4034, and 4095 as for `send-message`, and the
+ *   API is limited to 3,000 calls per minute per app.
+ */
+export const aitFunctionalBulkMessagePath = 'api-partner/v1/apps-in-toss/messenger/send-bulk-message';
+/** The fewest recipients the bulk API is meant for; fewer go one `send-message` call each. */
+export const aitFunctionalBulkMessageMinRecipients = 50;
+/** The most recipients one `send-bulk-message` call takes. */
+export const aitFunctionalBulkMessageMaxRecipients = 2_500;
 // The same values as `appsInTossPartnerApiBaseUrl` and
 // `defaultAppsInTossPartnerApiTimeoutMs` (a test keeps them equal), kept here
 // so this module loads none of the partner client's code.
@@ -78,6 +99,8 @@ const channelFields = {
     friendtalk: 'sentFriendtalk',
 };
 const maximumResponseBodyBytes = 256 * 1_024;
+/** A bulk answer lists up to 2,500 messages per channel. */
+const maximumBulkResponseBodyBytes = 4 * 1_024 * 1_024;
 /** The longest `reachedFailReason` the provider keeps; a longer one is cut to this. */
 const maximumFailReasonLength = 1_024;
 const maximumIdentifierLength = 2_048;
@@ -152,9 +175,140 @@ export function createAitFunctionalMessageDeliveryProvider(options) {
             ? { status: 'rejected', reason: 'recipient', providerCode: code }
             : { status: 'ambiguous', providerCode: code };
     };
+    const bulkUrl = new URL(aitFunctionalBulkMessagePath, normalizeBaseUrl(options.baseUrl ?? defaultAitFunctionalMessageBaseUrl, {
+        allowUnlistedHost: options.allowUnlistedHost === true,
+    })).href;
+    const bulkKey = options.recipientKey === 'anonymous' ? 'anonKey' : 'userKey';
+    /** One `send-bulk-message` call's answer, the same for each of its `count` recipients. */
+    const sendBulkGroup = async (templateSetCode, contextList) => {
+        const response = await post({
+            mtls: options.mtls,
+            url: bulkUrl,
+            headers: {},
+            body: { templateSetCode, contextList },
+            timeoutMs,
+            // Per-channel lists of up to 2,500 messages each outgrow the single
+            // send's 256 KiB.
+            maxBodyBytes: maximumBulkResponseBodyBytes,
+        });
+        if (response.kind === 'failed') {
+            return { status: 'ambiguous', providerCode: response.reason };
+        }
+        const { status, body } = response;
+        if (status >= 200 && status < 300 && body === undefined) {
+            // Taken, but its counts cannot be read: some or all may have been sent,
+            // and a replay would reach them again.
+            return { status: 'ambiguous', providerCode: 'BULK_UNREADABLE', unattributed: true };
+        }
+        if (status >= 500 || status === 408 || status === 425) {
+            return { status: 'ambiguous', ...providerCodeOf(body) };
+        }
+        if (status === 429) {
+            const error = isRecord(body) && isRecord(body['error']) ? body['error'] : undefined;
+            const retryAfterSeconds = retryAfterOf(error, response.retryAfter);
+            return {
+                status: 'rate-limited',
+                ...providerCodeOf(body),
+                ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }),
+            };
+        }
+        const resultType = isRecord(body) ? body['resultType'] : undefined;
+        if (resultType === 'SUCCESS') {
+            return status >= 200 && status < 300
+                ? readBulkSuccess(isRecord(body) ? body['success'] : undefined, contextList.length)
+                : { status: 'ambiguous', providerCode: 'SUCCESS' };
+        }
+        if (resultType === 'FAIL' && isRecord(body)) {
+            const error = isRecord(body['error']) ? body['error'] : undefined;
+            const code = errorCodeOf(error?.['errorCode']);
+            if (code === undefined) {
+                return { status: 'ambiguous', providerCode: 'FAIL' };
+            }
+            const answer = classifyFailCode(code, status);
+            if (answer.status === 'rate-limited') {
+                const retryAfterSeconds = retryAfterOf(error, response.retryAfter);
+                return retryAfterSeconds === undefined ? answer : { ...answer, retryAfterSeconds };
+            }
+            // The call names no recipient: an agreement code cannot be one player's denial.
+            return answer.status === 'rejected' && answer.reason === 'agreement'
+                ? { ...answer, reason: 'recipient' }
+                : answer;
+        }
+        if (typeof resultType === 'string' && ambiguousResultTypes.has(resultType)) {
+            return { status: 'ambiguous', providerCode: resultType };
+        }
+        if (refusedRequestStatuses.has(status)) {
+            return { status: 'rejected', reason: 'configuration', ...providerCodeOf(body) };
+        }
+        return { status: 'ambiguous', ...providerCodeOf(body) };
+    };
     return {
         id: aitFunctionalMessageProviderId,
         entry: referenceNotificationProviders['apps-in-toss'],
+        bulk: {
+            maxRecipients: aitFunctionalBulkMessageMaxRecipients,
+            minRecipients: aitFunctionalBulkMessageMinRecipients,
+            perRecipientOutcomes: false,
+            // One template set code a `send-bulk-message`.
+            callKey: (request) => {
+                const code = request.topic.mapping?.['templateSetCode'];
+                return typeof code === 'string' ? code : '';
+            },
+            // Five minutes early, so a call still in flight never lands in the hold.
+            holdWindow: { start: '20:55', end: '08:00', timeZone: 'Asia/Seoul' },
+        },
+        async sendBatch(requests, batchOptions = {}) {
+            const startedAt = globalThis.performance.now();
+            const answers = requests.map(() => undefined);
+            const groups = new Map();
+            requests.forEach((request, index) => {
+                if (request.signal?.aborted === true) {
+                    // Aborted before its call: it joins none, and nothing is sent to it.
+                    answers[index] = { status: 'not-sent' };
+                    return;
+                }
+                const templateSetCode = request.topic.mapping?.['templateSetCode'];
+                const context = request.templateData ?? {};
+                if (request.topic.purpose === 'advertising'
+                    || typeof templateSetCode !== 'string'
+                    || !isIdentifier(templateSetCode)
+                    || notificationTemplateDataIssue(context) !== undefined
+                    || request.recipient.kind !== 'platform-user') {
+                    answers[index] = { status: 'rejected', reason: 'configuration' };
+                    return;
+                }
+                const id = request.recipient.id;
+                if (!isHeaderValue(id) || (bulkKey === 'userKey' && !/^\d+$/u.test(id))) {
+                    answers[index] = { status: 'rejected', reason: 'recipient' };
+                    return;
+                }
+                // The documentation types userKey as a number (int64) or a string; a
+                // number past 2^53 would lose digits in JSON, so it stays a string.
+                const key = bulkKey === 'userKey' && Number.isSafeInteger(Number(id)) ? Number(id) : id;
+                let group = groups.get(templateSetCode);
+                if (group === undefined) {
+                    group = { indexes: [], contexts: [] };
+                    groups.set(templateSetCode, group);
+                }
+                group.indexes.push(index);
+                group.contexts.push({ [bulkKey]: key, context });
+            });
+            for (const [templateSetCode, group] of groups) {
+                for (let start = 0; start < group.contexts.length; start += aitFunctionalBulkMessageMaxRecipients) {
+                    const contexts = group.contexts.slice(start, start + aitFunctionalBulkMessageMaxRecipients);
+                    const late = batchOptions.startWithinMs !== undefined
+                        && globalThis.performance.now() - startedAt >= batchOptions.startWithinMs;
+                    // Too late to start another call within the recipients' claims: nothing was sent to them.
+                    const answer = late
+                        ? { status: 'not-sent' }
+                        : await sendBulkGroup(templateSetCode, contexts);
+                    for (const index of group.indexes.slice(start, start + contexts.length)) {
+                        answers[index] = answer;
+                    }
+                }
+            }
+            return answers.map((answer) => answer ?? { status: 'ambiguous' });
+        },
         async send(request) {
             const templateSetCode = request.topic.mapping?.['templateSetCode'];
             if (typeof templateSetCode !== 'string' || !isIdentifier(templateSetCode)) {
@@ -272,6 +426,86 @@ function readSuccess(success, agreementFailReasons) {
         && agreementFailReasons.has(failure.reachedFailReason.trim())));
     return { status: 'rejected', reason: agreement ? 'agreement' : 'recipient', channels };
 }
+/**
+ * A `send-bulk-message` `SUCCESS` for `recipients` recipients. The answer
+ * names no recipient, so the counts decide, under two readings the
+ * documentation does not state:
+ * - a channel reaches each recipient at most once per message, so one
+ *   channel that sent exactly as many messages as there were recipients
+ *   reached each of them;
+ * - a recipient is reached on at most one channel per message (push, else
+ *   inbox, and so on), so per-channel sent counts that add up to exactly
+ *   the recipients, none above it, reached each of them once.
+ * It proves nothing sent only when every count is zero. Anything else is
+ * some recipients reached and some not, without saying which: each is
+ * `unattributed`, its row stays in flight and is never replayed. Such a
+ * row writes no delivery history, so the app-wide pace (the registry
+ * `rate`) never counts it; the gate still counts it toward the player's
+ * frequency caps and per-user limits as an attempted in-flight send.
+ */
+function readBulkSuccess(success, recipients) {
+    if (!isRecord(success) || !isCount(success['msgCount'])) {
+        return { status: 'ambiguous', providerCode: 'SUCCESS' };
+    }
+    const detail = success['detail'];
+    const fail = success['fail'];
+    const countFields = {
+        push: 'sentPushCount',
+        inbox: 'sentInboxCount',
+        sms: 'sentSmsCount',
+        alimtalk: 'sentAlimtalkCount',
+        friendtalk: 'sentFriendtalkCount',
+    };
+    const channelNames = Object.keys(channelFields);
+    /** A channel's sent list: its entries, and how many name their message (a string `contentId`). */
+    const listedOn = (channel) => {
+        const listed = isRecord(detail) ? detail[channelFields[channel]] : undefined;
+        if (!Array.isArray(listed)) {
+            return undefined;
+        }
+        const valid = listed.filter((item) => isRecord(item) && typeof item['contentId'] === 'string' && item['contentId'].length > 0).length;
+        return { entries: listed.length, valid };
+    };
+    const sentOn = (channel) => {
+        const counted = success[countFields[channel]];
+        return Math.max(isCount(counted) ? counted : 0, listedOn(channel)?.valid ?? 0);
+    };
+    // A count and a list of sent messages that disagree, or a list entry that
+    // names no message, prove nothing about who was reached. An empty list is
+    // a list the answer left out, and the count stands.
+    const disagree = Object.keys(channelFields).some((channel) => {
+        const counted = success[countFields[channel]];
+        const listed = listedOn(channel);
+        if (listed === undefined || listed.entries === 0) {
+            return false;
+        }
+        return listed.valid !== listed.entries || (isCount(counted) && listed.entries !== counted);
+    });
+    if (disagree) {
+        return { status: 'ambiguous', providerCode: 'BULK_COUNTS_DISAGREE', unattributed: true };
+    }
+    const channels = Object.fromEntries(channelNames.map((channel) => [
+        channel,
+        {
+            sent: readContents(isRecord(detail) ? detail[channelFields[channel]] : undefined),
+            failed: readContents(isRecord(fail) ? fail[channelFields[channel]] : undefined),
+        },
+    ]));
+    const messageCount = success['msgCount'];
+    if (channelNames.some((channel) => sentOn(channel) === recipients)) {
+        return { status: 'accepted', messageCount, channels };
+    }
+    // Split across channels (some by push, the rest by inbox): exactly one message each.
+    const counts = channelNames.map(sentOn);
+    if (counts.reduce((sum, count) => sum + count, 0) === recipients
+        && counts.every((count) => count <= recipients)) {
+        return { status: 'accepted', messageCount, channels };
+    }
+    if (messageCount === 0 && channelNames.every((channel) => sentOn(channel) === 0)) {
+        return { status: 'rejected', reason: 'recipient', channels };
+    }
+    return { status: 'ambiguous', providerCode: 'BULK_PARTIAL', unattributed: true };
+}
 function readContents(input) {
     if (!Array.isArray(input)) {
         return [];
@@ -323,7 +557,7 @@ async function post(input) {
             redirect: 'manual',
             signal: controller.signal,
         });
-        const text = await readBoundedText(response);
+        const text = await readBoundedText(response, input.maxBodyBytes ?? maximumResponseBodyBytes);
         let body;
         if (text !== undefined && text.length > 0) {
             try {
@@ -353,12 +587,12 @@ async function post(input) {
         controller.abort();
     }
 }
-/** The body as UTF-8 text, or `undefined` when it is larger than 256 KiB or not UTF-8. */
-async function readBoundedText(response) {
+/** The body as UTF-8 text, or `undefined` when it is larger than `maxBytes` or not UTF-8. */
+async function readBoundedText(response, maxBytes) {
     const declaredLength = response.headers.get('content-length');
     if (declaredLength !== null
         && /^\d+$/u.test(declaredLength)
-        && Number(declaredLength) > maximumResponseBodyBytes) {
+        && Number(declaredLength) > maxBytes) {
         await response.body?.cancel().catch(() => { });
         return undefined;
     }
@@ -375,7 +609,7 @@ async function readBoundedText(response) {
                 break;
             }
             length += chunk.value.byteLength;
-            if (length > maximumResponseBodyBytes) {
+            if (length > maxBytes) {
                 await reader.cancel().catch(() => { });
                 return undefined;
             }

package/dist/notifications/bulk.d.ts

@@ -0,0 +1,158 @@
+import { type NotificationDeliveryOutcome } from '@mpgd/platform/notifications';
+import type { NotificationRemoteBulkCapability } from './delivery-provider.js';
+/**
+* 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 declare const maxNotificationBulkRecipients = 10000;
+/** One recipient of a bulk send. Its own fields replace the send's shared ones. */
+export interface NotificationBulkRecipientInput {
+  readonly player: string;
+  readonly templateData?: Readonly<Record<string, string | number | boolean>>;
+  readonly data?: Readonly<Record<string, string>>;
+  /** The locale the gate resolves this recipient's copy for, else the registered one. */
+  readonly locale?: string;
+  readonly link?: string;
+}
+/**
+* A bulk send from the game's server or an operator tool, never from a
+* client session (the Worker serves it only on the service binding).
+*/
+export interface NotificationBulkDeliverInput {
+  /**
+  * The bulk send's key. Each recipient's send key is
+  * `<idempotencyKey>:<encodeURIComponent(player)>`, so the same call
+  * retried answers recipients already sent from the ledger and sends only
+  * the rest.
+  */
+  readonly idempotencyKey: string;
+  /** The one provider every recipient is sent through. */
+  readonly provider: string;
+  readonly topic: string;
+  /** 1 to `maxNotificationBulkRecipients` recipients, each player once. */
+  readonly recipients: readonly NotificationBulkRecipientInput[];
+  readonly templateData?: Readonly<Record<string, string | number | boolean>>;
+  readonly data?: Readonly<Record<string, string>>;
+  readonly locale?: string;
+  readonly link?: string;
+  /**
+  * Recipients per provider call, at most the provider's
+  * `bulk.maxRecipients` (its maximum by default; 100 for a provider that
+  * sends one by one).
+  */
+  readonly batchSize?: number;
+}
+/** What the host that serves `deliverBulk` bounds a call by. */
+export interface NotificationBulkDeliverOptions {
+  /** Wall time after which no further batch starts; 20 seconds by default. */
+  readonly budgetMs?: number;
+  /**
+  * Deliveries one call attempts at most (sends it makes or replays, one
+  * per device of a device provider); recipients past it answer
+  * `not-attempted` (`count-budget`). A recipient answered from the ledger
+  * does not count. A device past it stays queued for the scheduler.
+  */
+  readonly maxRecipients?: number;
+  /**
+  * Recipients whose key one call reads at most, in the order of the
+  * request, whether or not they then need an attempt; the rest answer
+  * `not-attempted` (`count-budget`). It bounds the ledger reads of a large
+  * retry, which `maxRecipients` does not.
+  */
+  readonly maxLookups?: number;
+}
+/** Why a recipient was not attempted in this call; the same call retried attempts it. */
+export type NotificationBulkNotAttemptedReason = 
+/** The provider's app-wide `rate` (Devvit: 25,000 a day) has no room left now. */
+'provider-rate'
+/** The call's wall-time budget ran out before this recipient's batch. */
+| 'time-budget'
+/** The host's per-call recipient or read budget ran out. */
+| 'count-budget';
+export type NotificationBulkRecipientResult = {
+  readonly player: string;
+  readonly idempotencyKey: string;
+  readonly status: 'answered';
+  /** What `deliver` would answer for this recipient's key. */
+  readonly outcome: NotificationDeliveryOutcome;
+} | {
+  readonly player: string;
+  readonly idempotencyKey: string;
+  readonly status: 'not-attempted';
+  readonly reason: NotificationBulkNotAttemptedReason;
+} | {
+  readonly player: string;
+  readonly idempotencyKey: string;
+  readonly status: 'failed';
+  /** As `deliver` would have thrown it: a retryable error may pass on a retry of the call. */
+  readonly error: {
+    readonly code: string;
+    readonly message: string;
+    readonly retryable: boolean;
+  };
+};
+export interface NotificationBulkSummary {
+  /** Delivered by this call. */
+  readonly delivered: number;
+  /** Delivered by an earlier call with the same key. */
+  readonly alreadyProcessed: number;
+  readonly deferred: number;
+  readonly inFlight: number;
+  readonly suppressed: number;
+  readonly unavailable: number;
+  readonly notAttempted: number;
+  readonly failed: number;
+}
+export interface NotificationBulkDeliveryResult {
+  /** One per recipient, in the order of the request. */
+  readonly recipients: readonly NotificationBulkRecipientResult[];
+  readonly summary: NotificationBulkSummary;
+  /** Provider calls this call made: bulk calls, and recipients sent one per call. */
+  readonly providerCalls: {
+    readonly batch: number;
+    readonly single: number;
+  };
+}
+/** A checked bulk request with its recipients' send keys. */
+export interface ParsedNotificationBulkRequest {
+  readonly input: NotificationBulkDeliverInput;
+  readonly keys: readonly string[];
+}
+/** The send key of one recipient of a bulk send. */
+export declare function notificationBulkRecipientKey(idempotencyKey: string, player: string): string;
+/**
+* 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 declare function parseNotificationBulkRequest(raw: unknown): ParsedNotificationBulkRequest;
+/**
+* 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 declare function assertNotificationBulkCapability(capability: NotificationRemoteBulkCapability, at: string): void;
+/** Whether `at` (epoch milliseconds) falls inside a provider's hold window. */
+export declare function isInsideNotificationHoldWindow(window: NotificationRemoteBulkCapability['holdWindow'], at: number): boolean;
+/** A counting semaphore: at most `concurrency` holders at once, served in order. */
+export declare function createNotificationLimiter(concurrency: number): {
+  acquire(): Promise<void>;
+  release(): void;
+};
+/**
+* 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 declare function createNotificationBatchBarrier<Item, Answer>(participants: number, flush: (items: readonly Item[]) => Promise<readonly Answer[]>): {
+  arrive(item: Item): Promise<Answer>;
+  leave(): void;
+};