@mpgd/game-services 0.24.1 → 0.25.0

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

@@ -0,0 +1,121 @@
+import type { NotificationDeliveryContent, NotificationPermissionState, NotificationProviderId, NotificationTemplateData, NotificationTopicDeclaration } from '@mpgd/platform/notifications';
+/**
+* The server-side remote delivery provider contract (notifications v2 RFC,
+* "Delivery providers" and "Provider answers"). It is built only from
+* `@mpgd/platform/notifications` types and literal unions, so a provider
+* module (FCM here, Apps in Toss in its own module) fits it structurally
+* without importing anything from this package.
+*
+* A provider sends exactly what the policy gate rendered: the service runs
+* `evaluateNotificationDelivery` immediately before every call, and a provider
+* never decides policy.
+*/
+/**
+* Why a Firebase installation id (FID, `fcm-installation`) is refused, at
+* registration and at send. The kind is reserved: FCM is moving to FIDs, but
+* HTTP v1 has no FID send target yet. It lives here, beside the address
+* kinds, so the service can use it without importing the FCM provider.
+*/
+export declare const fcmInstallationIdRefusal = "Firebase installation ids (fcm-installation) are reserved and refused until FCM can send to them; register the FCM registration token (fcm-token).";
+/** A device address as the endpoint registry stores it; FCM keeps the kinds apart. */
+export interface NotificationDeviceAddress {
+  readonly kind: 'fcm-token' | 'fcm-installation';
+  readonly value: string;
+  readonly environment?: 'production' | 'sandbox';
+}
+/** Who one delivery goes to: a device endpoint, or a resolved platform identity. */
+export type NotificationRemoteRecipient = {
+  readonly kind: 'device';
+  /** The game-services session's installation the endpoint belongs to. */
+  readonly installationId: string;
+  readonly address: NotificationDeviceAddress;
+} | {
+  readonly kind: 'platform-user';
+  /**
+  * The provider's own recipient id, resolved by the backend from the
+  * player's authenticated identity (an Apps in Toss user key, a Reddit
+  * user id), never from a key the client sent.
+  */
+  readonly id: string;
+};
+/** One recipient's delivery of one send, after the gate allowed it. */
+export interface NotificationRemoteDeliveryRequest {
+  /**
+  * The ledger key of this delivery: the send key for a platform-user
+  * recipient, `<send key>:<encodeURIComponent(installationId)>` for a device
+  * endpoint. A replay of the same delivery carries the same key, so a
+  * provider that can deduplicate (a provider-side idempotency key or
+  * outbox) uses it.
+  */
+  readonly idempotencyKey: string;
+  /** The send's own idempotency key. */
+  readonly sendKey: string;
+  readonly provider: NotificationProviderId;
+  readonly player: string;
+  /** The topic as declared for the recipient's target, with that target's mapping. */
+  readonly topic: NotificationTopicDeclaration;
+  readonly recipient: NotificationRemoteRecipient;
+  /** The content the gate rendered; under `kr` it already carries the advertising label, sender, opt-out line, and action. */
+  readonly content: NotificationDeliveryContent;
+  /** RFC 3339: the message must not be shown after this instant (FCM `android.ttl` and `apns-expiration`). */
+  readonly expiresAt?: string;
+  readonly templateData?: NotificationTemplateData;
+  /** Untrusted routing data the open carries; never a grant. */
+  readonly data?: Readonly<Record<string, string>>;
+  /** The send's post or comment link, else the mapping's (providers whose entry sets `link`). */
+  readonly link?: string;
+  /** The locale the content was resolved for. */
+  readonly locale?: string;
+  /** The time of the call, RFC 3339; a provider computes relative expiries from it. */
+  readonly at: string;
+}
+/**
+* Every provider answer maps to one of five kinds (RFC "Provider answers"):
+*
+* - `accepted`: the provider took the message.
+* - `unregistered`: the address is dead; the endpoint is invalidated.
+* - `rate-limited`: the provider proves nothing was sent; the delivery waits
+*   `retryAfterSeconds` (60 when absent), then backs off.
+* - `rejected`: the provider proves nothing was sent and the same send would
+*   fail again. `agreement` also records a provider denial.
+* - `ambiguous`: the provider cannot say whether it sent (a timeout, a 5xx
+*   answer). The claim is kept until its lease ends.
+*
+* A provider that throws is treated as `ambiguous`.
+*/
+export type NotificationRemoteDeliveryAnswer = {
+  readonly status: 'accepted';
+  readonly providerMessageId?: string;
+} | {
+  readonly status: 'unregistered';
+} | {
+  readonly status: 'rate-limited';
+  readonly retryAfterSeconds?: number;
+} | {
+  readonly status: 'rejected';
+  readonly reason: 'configuration' | 'recipient' | 'agreement';
+  /** The provider's own error code, for logs; never shown to players. */
+  readonly providerCode?: string;
+} | {
+  readonly status: 'ambiguous';
+  readonly providerCode?: string;
+};
+/**
+* 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.
+*/
+export declare const notificationExpiredProviderCode = "MESSAGE_EXPIRED";
+/** A server-side remote delivery provider: `{ id, send }`. */
+export interface NotificationRemoteDeliveryProvider {
+  /** Equals the registry entry's `provider`. */
+  readonly id: NotificationProviderId;
+  send(request: NotificationRemoteDeliveryRequest): Promise<NotificationRemoteDeliveryAnswer>;
+  /**
+  * The host's permission at send time, for a provider whose registry entry
+  * is `serverReadable` (Devvit `isOptedIn`). The gate requires it there.
+  */
+  readPermission?(input: {
+    readonly player: string;
+    readonly topic: string;
+  }): Promise<NotificationPermissionState>;
+}

package/dist/notifications/delivery-provider.js

@@ -0,0 +1,23 @@
+/**
+ * The server-side remote delivery provider contract (notifications v2 RFC,
+ * "Delivery providers" and "Provider answers"). It is built only from
+ * `@mpgd/platform/notifications` types and literal unions, so a provider
+ * module (FCM here, Apps in Toss in its own module) fits it structurally
+ * without importing anything from this package.
+ *
+ * A provider sends exactly what the policy gate rendered: the service runs
+ * `evaluateNotificationDelivery` immediately before every call, and a provider
+ * never decides policy.
+ */
+/**
+ * Why a Firebase installation id (FID, `fcm-installation`) is refused, at
+ * registration and at send. The kind is reserved: FCM is moving to FIDs, but
+ * HTTP v1 has no FID send target yet. It lives here, beside the address
+ * kinds, so the service can use it without importing the FCM provider.
+ */
+export const fcmInstallationIdRefusal = 'Firebase installation ids (fcm-installation) are reserved and refused until FCM can send to them; register the FCM registration token (fcm-token).';
+/**
+ * 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.
+ */
+export const notificationExpiredProviderCode = 'MESSAGE_EXPIRED';

package/dist/notifications/fcm.d.ts

@@ -0,0 +1,138 @@
+import { notificationExpiredProviderCode, type NotificationRemoteDeliveryAnswer, type NotificationRemoteDeliveryProvider, type NotificationRemoteDeliveryRequest } from './delivery-provider.js';
+import type { NotificationProviderRegistration } from './registry.js';
+/**
+* The FCM remote delivery provider (notifications v2 RFC, "Delivery
+* providers"): HTTP v1 `messages:send` with an OAuth access token minted from
+* a service-account JWT signed through WebCrypto. It needs only `fetch` and
+* `crypto.subtle`, so it runs on Cloudflare Workers (no HTTP/2, no Node
+* crypto). iOS devices register through Firebase Messaging, so FCM relays to
+* APNs.
+*
+* Payload, as the Capacitor provider reads it (RFC "Capacitor"): the gate's
+* title and body as the FCM `notification`; `data` carries the send's routing
+* data plus `topic` (the topic id) and `route` (its root-relative route).
+* Android posts to the mapping's `channelId`, else to `mpgd-service`,
+* `mpgd-requested`, or `mpgd-advertising` by purpose. An advertising send
+* names the iOS category `mpgd-advertising`, whose opt-out action the app
+* registers; an Android FCM notification message cannot carry actions, so
+* the shell renders advertising natively (C1). An expiry becomes
+* `android.ttl` and the `apns-expiration` header.
+*/
+export declare const fcmMessagingScope = "https://www.googleapis.com/auth/firebase.messaging";
+export declare const fcmTokenEndpoint = "https://oauth2.googleapis.com/token";
+/**
+* The FCM HTTP v1 API takes registration tokens. A Firebase installation id
+* (FID, the `fcm-installation` kind) is reserved: the kit types it because
+* FCM is moving to FIDs, but HTTP v1 has no FID send target, so this
+* provider refuses one at registration and at send until FCM supports it.
+*/
+export declare const fcmAddressKinds: readonly ["fcm-token"];
+/** Data keys this provider writes; a send's routing data may not use them. */
+export declare const fcmReservedDataKeys: readonly ["topic", "route"];
+/** The iOS notification category of advertising, which carries the opt-out action. */
+export declare const fcmAdvertisingCategory = "mpgd-advertising";
+/** The fields of a Google service-account key this provider reads. */
+export interface FcmServiceAccount {
+  readonly projectId: string;
+  readonly clientEmail: string;
+  /** A PKCS #8 PEM `PRIVATE KEY` block, as a service-account key file holds it. */
+  readonly privateKey: string;
+  readonly privateKeyId?: string;
+}
+/**
+* Reads a service-account key file (its JSON text or the parsed object).
+* Errors name the missing field and never include a value.
+*/
+export declare function parseFcmServiceAccount(input: unknown): FcmServiceAccount;
+type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export interface FcmAccessTokenSource {
+  /** A valid access token, minted or from the cache. */
+  get(): Promise<string>;
+  /** Drops `token` from the cache after FCM refused it. */
+  invalidate(token: string): void;
+}
+/** Why no access token could be minted, and whether trying again later can help. */
+export declare class FcmAccessTokenError extends Error {
+  readonly name = "FcmAccessTokenError";
+  readonly retryable: boolean;
+  readonly code: string;
+  readonly retryAfterSeconds: number | undefined;
+  constructor(code: string, retryable: boolean, retryAfterSeconds?: number, options?: {
+    readonly cause?: unknown;
+  });
+}
+/**
+* Mints and caches OAuth access tokens for the FCM scope. The token lives
+* only in this object's memory: it is never logged, persisted, or put in an
+* error. Concurrent callers share one request, a failed request is not
+* cached, and a token is refreshed five minutes before it expires.
+*/
+export declare function createFcmAccessTokenSource(input: {
+  readonly serviceAccount: FcmServiceAccount;
+  readonly fetch?: FetchLike;
+  readonly now?: () => number;
+  readonly subtle?: SubtleCrypto;
+  readonly timeoutMs?: number;
+}): FcmAccessTokenSource;
+export interface CreateFcmDeliveryProviderInput {
+  readonly serviceAccount: FcmServiceAccount;
+  /** Defaults to the service account's project. */
+  readonly projectId?: string;
+  /** The provider id; `fcm` by default. */
+  readonly id?: string;
+  readonly fetch?: FetchLike;
+  readonly now?: () => number;
+  readonly subtle?: SubtleCrypto;
+  /** Per HTTP request; 10 seconds by default. */
+  readonly timeoutMs?: number;
+  /** A shared token source, for example one per isolate. */
+  readonly tokens?: FcmAccessTokenSource;
+}
+/** The FCM HTTP v1 message this provider sends, or why it cannot send one. */
+export type FcmMessageBuild = {
+  readonly status: 'ready';
+  readonly message: Readonly<Record<string, unknown>>;
+} | {
+  readonly status: 'invalid';
+  readonly reason: string;
+  /**
+  * `MESSAGE_EXPIRED` (`notificationExpiredProviderCode`) for a message
+  * that would arrive too late, `INSTALLATION_ID_RESERVED` for an FID
+  * recipient, else `INVALID_MESSAGE`.
+  */
+  readonly code: 'INVALID_MESSAGE' | 'INSTALLATION_ID_RESERVED' | typeof notificationExpiredProviderCode;
+};
+/**
+* Builds the HTTP v1 `message` for one delivery and checks it against FCM's
+* rules before anything is sent: a registration token address, a title and
+* a body, string routing data without FCM's or this provider's reserved
+* keys, an expiry at least a second away, and a payload within FCM's limit
+* with room for what APNs adds. A message that passes is "known valid", so an
+* `INVALID_ARGUMENT` answer that names the token means a dead token.
+*/
+export declare function buildFcmMessage(request: NotificationRemoteDeliveryRequest): FcmMessageBuild;
+/**
+* Maps an FCM error answer to the provider answer kinds (RFC "Delivery
+* providers"): `UNREGISTERED` is `unregistered`, and so is
+* `INVALID_ARGUMENT` for a message `buildFcmMessage` passed when the answer
+* names the token and no other field; `QUOTA_EXCEEDED` is
+* `rate-limited`; `UNAVAILABLE` and `INTERNAL` are `ambiguous`;
+* `SENDER_ID_MISMATCH`, `THIRD_PARTY_AUTH_ERROR`, and every other refusal are
+* `rejected` with reason `configuration`. An answer without an FCM error code
+* falls back on its HTTP status: 5xx is `ambiguous`, 429 `rate-limited`.
+*/
+export declare function classifyFcmError(input: {
+  readonly status: number;
+  readonly body: unknown;
+  readonly retryAfterSeconds?: number;
+}): NotificationRemoteDeliveryAnswer;
+/** The FCM provider: `{ id, send }` over HTTP v1. */
+export declare function createFcmDeliveryProvider(input: CreateFcmDeliveryProviderInput): NotificationRemoteDeliveryProvider;
+/**
+* The registry registration for FCM: the reference `fcm` entry, the
+* `android` and `ios` targets, and registration-token addresses only.
+*/
+export declare function createFcmProviderRegistration(input: CreateFcmDeliveryProviderInput & {
+  readonly targets?: readonly string[];
+}): NotificationProviderRegistration;
+export {};