@mpgd/game-services 0.33.1 → 0.35.0

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>;
   /**