@mpgd/platform 0.22.0 → 0.23.0

package/dist/notifications.d.ts

@@ -0,0 +1,265 @@
+import { type tags } from 'typia';
+import { PlatformOperationError, type NotificationSubscriptionAdapter, type NotificationSubscriptionResult, type NotificationSubscriptionStatus } from './index.js';
+import type { CancelLocalNotificationsInput, LocalNotificationEntry, LocalNotificationRequest, LocalScheduleResult, NotificationCapabilities, NotificationEndpointRegistration, NotificationEvent, NotificationPermissionOutcome, NotificationPermissionResult, NotificationPermissionSnapshot, NotificationPermissionState, NotificationProviderId, NotificationSettingsResult, NotificationTopicId, NotificationTopicsInput } from './notifications-contract.js';
+import { type NotificationConsentRecord, type NotificationDeliveryProviderEntry, type NotificationDeployment, type NotificationNotice, type NotificationNoticeIdentity, type NotificationTemplateData, type NotificationTopicDefinition, type ReminderResult } from './notifications-policy.js';
+/**
+* Notifications v2 contract module (docs/specs/notifications/notifications-v2-rfc.md).
+* Pure types, validators, and helpers only: no provider lives here, and
+* nothing in this module sends a notification or grants anything. The
+* contract is a draft until the protocol version is released as 2.0.0.
+*/
+export declare const notificationsProtocolVersion: '2.0.0-draft.1';
+export declare const notificationsProtocol: 'mpgd.notifications.v2';
+export type { CancelLocalNotificationsInput, LocalNotificationEntry, LocalNotificationRequest, LocalScheduleResult, NotificationCapabilities, NotificationChannel, NotificationEndpointAddress, NotificationEndpointRegistration, NotificationEvent, NotificationLocalCapabilities, NotificationOpenPath, NotificationPermissionAllowance, NotificationPermissionCapabilities, NotificationPermissionOutcome, NotificationPermissionPrompt, NotificationPermissionResult, NotificationPermissionScope, NotificationPermissionSnapshot, NotificationPermissionState, NotificationProvider, NotificationProviderId, NotificationPurpose, NotificationRemoteAddressing, NotificationRemoteCapabilities, NotificationRemoteContent, NotificationRequiredAction, NotificationSettingsResult, NotificationTopicId, NotificationTopicsInput, } from './notifications-contract.js';
+export { applyNotificationAdvertisingLabel, checkNotificationNightWindow, checkNotificationQuietHours, createNotificationNoticeIdempotencyKey, createNotificationReminderIdempotencyKey, evaluateLocalNotificationReminder, evaluateNotificationDelivery, evaluateNotificationReminderConsent, fillNotificationTemplate, findNotificationCopy, isNotificationCalendarDate, isNotificationTimestamp, isRecordableNotificationPermissionState, isRootRelativeNotificationRoute, isSameNotificationNotice, isValidNotificationTimeZone, latestNotificationConsent, listNotificationNotices, normalizeNotificationTimestamp, notificationAdvertisingOptOutActionId, notificationAdvertisingPrefix, notificationConsentResultDueBy, notificationDefaultDeploymentTimeZone, notificationDefaultOptOutLine, notificationInputBounds, notificationKeyIssue, notificationNightWindow, notificationNoticeCopyIssues, notificationNoticeLeadDays, notificationNoticeSendFrom, notificationNoticeTopic, notificationNoticeVariantCopy, notificationNoticeVariantFallbacks, notificationNoticeVariants, notificationPermissionConsentKind, notificationPermissionStateOf, notificationProviderCarriesNotices, notificationReconfirmationDueBy, notificationReconfirmationListDays, notificationRegistryMismatch, notificationReservedKeyPrefix, notificationReservedKeyPrefixes, notificationSendFingerprint, notificationSuppressionReasons, notificationTemplateDataIssue, notificationTopicDefinitionIssues, notificationTopicNeedsNoAgreement, readNotificationTemplate, recordableNotificationPermissionStates, referenceNotificationProviders, referenceNotificationTargetProviders, renderNotificationAdvertisement, resolveNotificationAdvertisingSettings, resolveNotificationContent, routeNotificationReminder, toSeoulCalendarDate, type EvaluateLocalNotificationReminderInput, type EvaluateNotificationDeliveryInput, type EvaluateNotificationReminderConsentInput, type LocalNotificationReminderDecision, type NotificationAction, type NotificationAdvertisingRules, type NotificationAdvertisingSender, type NotificationAdvertisingSettings, type NotificationClockTime, type NotificationConsentKind, type NotificationConsentRecord, type NotificationConsentSource, type NotificationConsentState, type NotificationDeferralReason, type NotificationDeliveryContent, type NotificationDeliveryDecision, type NotificationDeliveryHistoryEntry, type NotificationDeliveryOutcome, type NotificationDeliveryProviderEntry, type NotificationDeliveryRefusal, type NotificationDeliveryStatus, type NotificationDeployment, type NotificationMappingField, type NotificationNotice, type NotificationNoticeCopy, type NotificationNoticeIdentity, type NotificationNoticeKind, type NotificationNoticeLocaleCopy, type NotificationNoticeSettings, type NotificationNoticeVariant, type NotificationProviderLimit, type NotificationProviderRegistryEntry, type NotificationQuietHours, type NotificationRecordablePermissionState, type NotificationReminderRoute, type NotificationReminderStatus, type NotificationSendRequest, type NotificationSuppressionReason, type NotificationTemplateData, type NotificationTopicCopy, type NotificationTopicDeclaration, type NotificationTopicDefinition, type NotificationTopicFrequency, type NotificationTopicIssue, type NotificationTopicMapping, type NotificationUnavailableReason, type NotificationWindowCheck, type ReminderResult, type ResolveNotificationContentInput, } from './notifications-policy.js';
+type NonEmptyString = string & tags.MinLength<1>;
+type NonNegativeInteger = number & tags.Type<'uint32'>;
+export type NotificationErrorCode = 
+/** A method the provider does not implement. */
+'NOTIFICATIONS_UNSUPPORTED'
+/** The host's own code is kept as `hostCode`. */
+| 'NOTIFICATIONS_CONFIGURATION_REQUIRED' | 'NOTIFICATIONS_USER_GESTURE_REQUIRED' | 'NOTIFICATIONS_HOST_VERSION_UNSUPPORTED'
+/** Input outside the bounds, a reserved key prefix, or a timestamp without an offset. */
+| 'NOTIFICATIONS_INVALID_INPUT'
+/** A key stored for another request. */
+| 'NOTIFICATIONS_IDEMPOTENCY_CONFLICT' | 'NOTIFICATIONS_TEMPORARILY_UNAVAILABLE'
+/** A bridge without the v2 methods; not retryable. */
+| 'NOTIFICATIONS_V2_UNAVAILABLE';
+export declare const notificationErrorCodes: readonly ["NOTIFICATIONS_UNSUPPORTED", "NOTIFICATIONS_CONFIGURATION_REQUIRED", "NOTIFICATIONS_USER_GESTURE_REQUIRED", "NOTIFICATIONS_HOST_VERSION_UNSUPPORTED", "NOTIFICATIONS_INVALID_INPUT", "NOTIFICATIONS_IDEMPOTENCY_CONFLICT", "NOTIFICATIONS_TEMPORARILY_UNAVAILABLE", "NOTIFICATIONS_V2_UNAVAILABLE"];
+export declare function isNotificationErrorCode(value: unknown): value is NotificationErrorCode;
+export interface NotificationErrorOptions {
+  readonly message?: string;
+  /** Only `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` is retryable unless a caller says otherwise. */
+  readonly retryable?: boolean;
+  /** The host's own code, kept verbatim with `NOTIFICATIONS_CONFIGURATION_REQUIRED`. */
+  readonly hostCode?: string;
+  readonly cause?: unknown;
+}
+/** Normalized notifications failure; only `NOTIFICATIONS_TEMPORARILY_UNAVAILABLE` is retryable by default. */
+export declare class NotificationError extends PlatformOperationError {
+  readonly code: NotificationErrorCode;
+  readonly hostCode: string | undefined;
+  constructor(code: NotificationErrorCode, options?: NotificationErrorOptions);
+}
+export interface NotificationRuntimePermissionSnapshot extends NotificationPermissionSnapshot {
+  /** Whether the host answered each topic, or the latest backend record did. */
+  readonly sources: Readonly<Record<NotificationTopicId, 'host' | 'record'>>;
+}
+export interface NotificationRuntimeRequestPermissionInput extends NotificationTopicsInput {
+  /** Whether the call runs inside a player gesture. */
+  readonly gesture: boolean;
+}
+export interface NotificationTopicPreferenceInput {
+  readonly topic: NotificationTopicId;
+  readonly enabled: boolean;
+}
+export interface NotificationAdvertisingConsentInput {
+  readonly advertising?: 'granted' | 'withdrawn';
+  readonly night?: 'granted' | 'withdrawn';
+  readonly textVersion: string;
+}
+export interface SetNotificationReminderInput {
+  readonly key: string;
+  readonly topic: NotificationTopicId;
+  /** RFC 3339 with an explicit offset. */
+  readonly fireAt: string;
+  readonly templateData?: NotificationTemplateData;
+  /** A post or comment id for providers whose sends need a link (Devvit). */
+  readonly link?: string;
+}
+export interface CancelNotificationReminderInput {
+  readonly key: string;
+}
+/**
+* The notice `notices.recordShown` records: a notice as `notices.list()` gave
+* it, or exactly its name (its kind, the kind and time of the record it
+* reports on, and its `dueBy`).
+*/
+export type RecordNotificationNoticeInput = NotificationNoticeIdentity | NotificationNotice;
+/**
+* The game-facing notifications surface: the provider composed with the
+* backend. Games call this, never the provider. Consent records are written
+* here (RFC "Runtime" rules); remote sends happen only on the server.
+*/
+export interface NotificationRuntime {
+  getPermission(input: NotificationTopicsInput): Promise<NotificationRuntimePermissionSnapshot>;
+  requestPermission(input: NotificationRuntimeRequestPermissionInput): Promise<NotificationPermissionResult>;
+  /** Game-rendered consent only (`permission.prompt` is 'game'). */
+  revokePermission(input: NotificationTopicsInput): Promise<NotificationPermissionResult>;
+  register(): Promise<void>;
+  /** Unbinds this installation's address from the player, for example at logout. */
+  unregister(): Promise<void>;
+  setTopicPreference(input: NotificationTopicPreferenceInput): Promise<void>;
+  setAdvertisingConsent(input: NotificationAdvertisingConsentInput): Promise<void>;
+  readonly reminders: {
+    set(input: SetNotificationReminderInput): Promise<ReminderResult>;
+    cancel(input: CancelNotificationReminderInput): Promise<ReminderResult>;
+  };
+  readonly notices: {
+    list(): Promise<readonly NotificationNotice[]>;
+    recordShown(input: RecordNotificationNoticeInput): Promise<void>;
+  };
+  openSettings(): Promise<NotificationSettingsResult>;
+  subscribe(listener: (event: NotificationEvent) => void): () => void;
+}
+/** Bridge event envelope; `sequence` is per session and starts at 0. */
+export interface NotificationEventEnvelope {
+  readonly protocol: typeof notificationsProtocol;
+  readonly sequence: NonNegativeInteger;
+  readonly event: NotificationEvent;
+}
+export interface NotificationBridgeProtocolPayload {
+  readonly protocol: typeof notificationsProtocol;
+}
+export type NotificationBridgeGetCapabilitiesPayload = NotificationBridgeProtocolPayload;
+export interface NotificationBridgeGetCapabilitiesResult {
+  readonly protocolVersion: NonEmptyString;
+  readonly provider: NotificationProviderId;
+  readonly capabilities: NotificationCapabilities;
+}
+export type NotificationBridgeGetPermissionPayload = NotificationTopicsInput;
+export type NotificationBridgeGetPermissionResult = NotificationPermissionSnapshot;
+export interface NotificationBridgeRequestPermissionPayload {
+  readonly topics: readonly NotificationTopicId[] & tags.MinItems<1>;
+}
+export type NotificationBridgeRequestPermissionResult = NotificationPermissionResult;
+export type NotificationBridgeRevokePermissionPayload = NotificationBridgeRequestPermissionPayload;
+export type NotificationBridgeRevokePermissionResult = NotificationPermissionResult;
+export type NotificationBridgeRegisterPayload = NotificationBridgeProtocolPayload;
+export interface NotificationBridgeRegisterResult {
+  /** `null` when the provider has no address yet, or none to register. */
+  readonly registration: NotificationEndpointRegistration | null;
+}
+export type NotificationBridgeScheduleLocalPayload = LocalNotificationRequest;
+export type NotificationBridgeScheduleLocalResult = LocalScheduleResult;
+export type NotificationBridgeCancelLocalPayload = CancelLocalNotificationsInput;
+export interface NotificationBridgeCancelLocalResult {
+  readonly cancelled: boolean;
+}
+export type NotificationBridgeListLocalPayload = NotificationBridgeProtocolPayload;
+export interface NotificationBridgeListLocalResult {
+  readonly pending: readonly LocalNotificationEntry[];
+}
+export type NotificationBridgeOpenSettingsPayload = NotificationBridgeProtocolPayload;
+export interface NotificationBridgeOpenSettingsResult {
+  readonly status: NotificationSettingsResult;
+}
+export interface NotificationBridgeMethods {
+  readonly 'notifications.v2.getCapabilities': {
+    readonly payload: NotificationBridgeGetCapabilitiesPayload;
+    readonly result: NotificationBridgeGetCapabilitiesResult;
+  };
+  readonly 'notifications.v2.getPermission': {
+    readonly payload: NotificationBridgeGetPermissionPayload;
+    readonly result: NotificationBridgeGetPermissionResult;
+  };
+  readonly 'notifications.v2.requestPermission': {
+    readonly payload: NotificationBridgeRequestPermissionPayload;
+    readonly result: NotificationBridgeRequestPermissionResult;
+  };
+  readonly 'notifications.v2.revokePermission': {
+    readonly payload: NotificationBridgeRevokePermissionPayload;
+    readonly result: NotificationBridgeRevokePermissionResult;
+  };
+  readonly 'notifications.v2.register': {
+    readonly payload: NotificationBridgeRegisterPayload;
+    readonly result: NotificationBridgeRegisterResult;
+  };
+  readonly 'notifications.v2.scheduleLocal': {
+    readonly payload: NotificationBridgeScheduleLocalPayload;
+    readonly result: NotificationBridgeScheduleLocalResult;
+  };
+  readonly 'notifications.v2.cancelLocal': {
+    readonly payload: NotificationBridgeCancelLocalPayload;
+    readonly result: NotificationBridgeCancelLocalResult;
+  };
+  readonly 'notifications.v2.listLocal': {
+    readonly payload: NotificationBridgeListLocalPayload;
+    readonly result: NotificationBridgeListLocalResult;
+  };
+  readonly 'notifications.v2.openSettings': {
+    readonly payload: NotificationBridgeOpenSettingsPayload;
+    readonly result: NotificationBridgeOpenSettingsResult;
+  };
+}
+export type NotificationBridgeMethod = keyof NotificationBridgeMethods;
+export declare const notificationBridgeMethods: readonly ["notifications.v2.getCapabilities", "notifications.v2.getPermission", "notifications.v2.requestPermission", "notifications.v2.revokePermission", "notifications.v2.register", "notifications.v2.scheduleLocal", "notifications.v2.cancelLocal", "notifications.v2.listLocal", "notifications.v2.openSettings"];
+/** A fresh capability block for a provider that has no notification path; callers must not share it. */
+export declare function createUnsupportedNotificationCapabilities(): NotificationCapabilities;
+/** Validates a capability block, including `remote.addressing: 'none'` exactly when `remote.supported` is false. */
+export declare function assertNotificationCapabilities(input: unknown): NotificationCapabilities;
+export declare function isNotificationCapabilities(input: unknown): input is NotificationCapabilities;
+export declare const assertNotificationPermissionSnapshot: (input: unknown) => NotificationPermissionSnapshot;
+export declare const assertNotificationPermissionResult: (input: unknown) => NotificationPermissionResult;
+export declare const isNotificationPermissionResult: (input: unknown) => input is NotificationPermissionResult;
+/** Validates a registration's shape and that `Intl` knows its `timeZone`, which quiet hours read. */
+export declare function assertNotificationEndpointRegistration(input: unknown): NotificationEndpointRegistration;
+/** Validates a local reminder request, including a root-relative `route`. */
+export declare function assertLocalNotificationRequest(input: unknown): LocalNotificationRequest;
+export declare const assertLocalScheduleResult: (input: unknown) => LocalScheduleResult;
+export declare const assertLocalNotificationEntry: (input: unknown) => LocalNotificationEntry;
+/** Validates an event; an `endpoint-changed` registration follows `assertNotificationEndpointRegistration`. */
+export declare function assertNotificationEvent(input: unknown): NotificationEvent;
+export declare function isNotificationEvent(input: unknown): input is NotificationEvent;
+/** Validates an envelope; its event follows `assertNotificationEvent`. */
+export declare function assertNotificationEventEnvelope(input: unknown): NotificationEventEnvelope;
+export declare function isNotificationEventEnvelope(input: unknown): input is NotificationEventEnvelope;
+export declare const assertNotificationConsentRecord: (input: unknown) => NotificationConsentRecord;
+export declare const assertNotificationNotice: (input: unknown) => NotificationNotice;
+/**
+* Validates a `notices.recordShown` input: a listed notice as is, or exactly
+* its name (kind, record kind and time, `dueBy`), with no other key in either
+* form. The time parses strictly with an offset, and `dueBy` is a date that
+* exists.
+*/
+export declare const assertRecordNotificationNoticeInput: (input: unknown) => RecordNotificationNoticeInput;
+export declare const assertNotificationDeliveryProviderEntry: (input: unknown) => NotificationDeliveryProviderEntry;
+/** Validates deployment settings, including a `timeZone` that `Intl` knows, which quiet hours read. */
+export declare function assertNotificationDeployment(input: unknown): NotificationDeployment;
+/** Validates a topic definition's shape and the rules of `notificationTopicDefinitionIssues`. */
+export declare function assertNotificationTopicDefinition(input: unknown): NotificationTopicDefinition;
+export declare const assertNotificationBridgeGetCapabilitiesPayload: (input: unknown) => NotificationBridgeProtocolPayload;
+/** Validates a `getCapabilities` answer, whose block follows `assertNotificationCapabilities`. */
+export declare function assertNotificationBridgeGetCapabilitiesResult(input: unknown): NotificationBridgeGetCapabilitiesResult;
+export declare const assertNotificationBridgeGetPermissionPayload: (input: unknown) => NotificationTopicsInput;
+export declare const assertNotificationBridgeGetPermissionResult: (input: unknown) => NotificationPermissionSnapshot;
+export declare const assertNotificationBridgeRequestPermissionPayload: (input: unknown) => NotificationBridgeRequestPermissionPayload;
+export declare const assertNotificationBridgeRequestPermissionResult: (input: unknown) => NotificationPermissionResult;
+export declare const assertNotificationBridgeRevokePermissionPayload: (input: unknown) => NotificationBridgeRequestPermissionPayload;
+export declare const assertNotificationBridgeRevokePermissionResult: (input: unknown) => NotificationPermissionResult;
+export declare const assertNotificationBridgeRegisterPayload: (input: unknown) => NotificationBridgeProtocolPayload;
+/** Validates a `register` answer, whose registration follows `assertNotificationEndpointRegistration`. */
+export declare function assertNotificationBridgeRegisterResult(input: unknown): NotificationBridgeRegisterResult;
+export declare const assertNotificationBridgeScheduleLocalPayload: typeof assertLocalNotificationRequest;
+export declare const assertNotificationBridgeScheduleLocalResult: (input: unknown) => LocalScheduleResult;
+export declare const assertNotificationBridgeCancelLocalPayload: (input: unknown) => CancelLocalNotificationsInput;
+export declare const assertNotificationBridgeCancelLocalResult: (input: unknown) => NotificationBridgeCancelLocalResult;
+export declare const assertNotificationBridgeListLocalPayload: (input: unknown) => NotificationBridgeProtocolPayload;
+export declare const assertNotificationBridgeListLocalResult: (input: unknown) => NotificationBridgeListLocalResult;
+export declare const assertNotificationBridgeOpenSettingsPayload: (input: unknown) => NotificationBridgeProtocolPayload;
+export declare const assertNotificationBridgeOpenSettingsResult: (input: unknown) => NotificationBridgeOpenSettingsResult;
+/**
+* v1 status for a topic's v2 permission state. `unknown` reaches this only when
+* no granted record answered for it, so it is not subscribed.
+*/
+export declare function toNotificationSubscriptionStatus(state: NotificationPermissionState): NotificationSubscriptionStatus;
+/** v1 result for a v2 permission outcome; a missing outcome is `unavailable`. */
+export declare function toNotificationSubscriptionResult(outcome: NotificationPermissionOutcome | undefined): NotificationSubscriptionResult;
+/**
+* Serves v1 `NotificationSubscriptionAdapter` callers from the v2 runtime, so
+* reads see backend records (RFC "Migration and PR plan" table).
+*
+* - `catalog` holds the topics resolved for the runtime's target, as the
+*   runtime reads them (`resolveNotificationTopicsForTarget` in
+*   `@mpgd/catalog`). A v1 topic that is not among them, because the catalog
+*   does not declare it or the target does not map it, reads
+*   `configuration-required` and requests `unavailable`. So does an entry
+*   that still carries a catalog's `targets`, which names no single target.
+* - Reads map a failure whose code is `NOTIFICATIONS_CONFIGURATION_REQUIRED`
+*   to `configuration-required`, whether it is a `NotificationError`, another
+*   `PlatformOperationError`, or a bridge error with that `code`, and rethrow
+*   other failures.
+* - Requests run with `gesture: true`, as v1 callers ask from a player
+*   action, and any thrown error answers `unavailable`.
+*/
+export declare function toNotificationSubscriptionAdapter(runtime: Pick<NotificationRuntime, 'getPermission' | 'requestPermission'>, catalog: readonly Pick<NotificationTopicDefinition, 'id'>[]): NotificationSubscriptionAdapter;