@mpgd/game-services 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './client';
 export * from './contract';
+export * from './notification-delivery';
+export * from './progress-link';
 export * from './server';
 export * from './types';

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from './client';
 export * from './contract';
+export * from './notification-delivery';
+export * from './progress-link';
 export * from './server';
 export * from './types';

package/dist/notification-delivery.d.ts

@@ -0,0 +1,106 @@
+import type { NotificationTopic, PlatformTarget } from '@mpgd/platform';
+export type NotificationTemplateValue = string | number | boolean;
+export type NotificationTemplateData = Readonly<Record<string, NotificationTemplateValue>>;
+export interface NotificationDeliveryRequest {
+  readonly target: PlatformTarget;
+  readonly topic: NotificationTopic;
+  readonly recipient: string;
+  readonly idempotencyKey: string;
+  readonly deepLink: string;
+  readonly templateData: NotificationTemplateData;
+}
+export interface DeliveryReceipt {
+  readonly providerMessageId: string;
+  readonly acceptedAt: string;
+}
+export interface NotificationDeliveryProvider {
+  readonly target: PlatformTarget;
+  /**
+  * MUST durably deduplicate concurrent and repeated calls by idempotencyKey
+  * before sending externally, using a provider key or a durable outbox.
+  */
+  deliverIdempotently(request: NotificationDeliveryRequest): Promise<DeliveryReceipt>;
+}
+/** Throw only when the provider can prove that no external send was attempted. */
+export declare class NotificationDeliveryNotSentError extends Error {
+  readonly name = "NotificationDeliveryNotSentError";
+}
+export interface NotificationDeepLinkPolicy {
+  /** Exact HTTP(S) origins permitted for absolute links. Root-relative links are always allowed. */
+  readonly allowedOrigins?: readonly string[];
+}
+export interface NotificationDeliveryClaimOptions extends NotificationDeepLinkPolicy {
+  readonly claimedAt: string;
+  readonly leaseDurationMs: number;
+}
+export type NotificationDeliveryClaimResult = {
+  readonly status: 'claimed';
+  readonly claimToken: string;
+  readonly leaseExpiresAt: string;
+} | {
+  readonly status: 'in-flight';
+} | {
+  readonly status: 'completed';
+  readonly receipt: DeliveryReceipt;
+};
+export interface NotificationDeliveryLedger {
+  /**
+  * Atomically claims or returns an existing delivery for the idempotency key.
+  * Expired claims must be reclaimable so a crashed worker cannot block delivery forever.
+  * Implementations MUST bind the key to the full normalized request and reject payload reuse.
+  */
+  claim(request: NotificationDeliveryRequest, options: NotificationDeliveryClaimOptions): Promise<NotificationDeliveryClaimResult>;
+  /**
+  * MUST atomically fence on the current claimToken and idempotently persist one stable receipt.
+  * A stale token must never overwrite a reclaimed or completed delivery.
+  */
+  complete(input: {
+    readonly idempotencyKey: string;
+    readonly claimToken: string;
+    readonly receipt: DeliveryReceipt;
+  }): Promise<void>;
+  /** MUST delete only the current in-flight claim; stale tokens must not affect newer state. */
+  release(input: {
+    readonly idempotencyKey: string;
+    readonly claimToken: string;
+  }): Promise<void>;
+}
+export type NotificationDeliveryResult = {
+  readonly status: 'delivered';
+  readonly alreadyProcessed: boolean;
+  readonly receipt: DeliveryReceipt;
+} | {
+  readonly status: 'in-flight';
+  readonly alreadyProcessed: true;
+} | {
+  readonly status: 'unavailable';
+  readonly alreadyProcessed: false;
+};
+export interface NotificationDeliveryService {
+  deliver(request: NotificationDeliveryRequest): Promise<NotificationDeliveryResult>;
+}
+/** Process-local test helper. Production services must provide a durable ledger. */
+export declare class InMemoryNotificationDeliveryLedger implements NotificationDeliveryLedger {
+  private readonly deliveriesByIdempotencyKey;
+  private nextClaimId;
+  claim(input: NotificationDeliveryRequest, options: NotificationDeliveryClaimOptions): Promise<NotificationDeliveryClaimResult>;
+  complete(input: {
+    readonly idempotencyKey: string;
+    readonly claimToken: string;
+    readonly receipt: DeliveryReceipt;
+  }): Promise<void>;
+  release(input: {
+    readonly idempotencyKey: string;
+    readonly claimToken: string;
+  }): Promise<void>;
+}
+export declare function createInMemoryNotificationDeliveryLedger(): InMemoryNotificationDeliveryLedger;
+export declare function createNotificationDeliveryService(input: {
+  readonly providers: readonly NotificationDeliveryProvider[];
+  readonly ledger: NotificationDeliveryLedger;
+  readonly deepLinkPolicy?: NotificationDeepLinkPolicy;
+  readonly claimLeaseMs?: number;
+  readonly now?: () => string;
+}): NotificationDeliveryService;
+export declare function normalizeNotificationDeliveryRequest(input: unknown, policy?: NotificationDeepLinkPolicy): NotificationDeliveryRequest;
+export declare function normalizeDeliveryReceipt(input: unknown): DeliveryReceipt;

package/dist/notification-delivery.js

@@ -0,0 +1,444 @@
+import { assertOwnEnumerablePropertyLimit } from './validation';
+const platformTargets = new Set([
+    'browser',
+    'android',
+    'ios',
+    'ait',
+    'reddit',
+    'telegram',
+    'tauri',
+]);
+const notificationTopics = new Set([
+    'daily-ready',
+    'streak-at-risk',
+    'friend-challenge',
+]);
+const defaultClaimLeaseMs = 5 * 60 * 1000;
+const maxCompletionAttempts = 3;
+const maxNotificationTemplateDataEntries = 128;
+/** Throw only when the provider can prove that no external send was attempted. */
+export class NotificationDeliveryNotSentError extends Error {
+    name = 'NotificationDeliveryNotSentError';
+}
+/** Process-local test helper. Production services must provide a durable ledger. */
+export class InMemoryNotificationDeliveryLedger {
+    deliveriesByIdempotencyKey = new Map();
+    nextClaimId = 1;
+    async claim(input, options) {
+        const policy = options.allowedOrigins === undefined
+            ? {}
+            : { allowedOrigins: options.allowedOrigins };
+        const request = normalizeNotificationDeliveryRequest(input, policy);
+        const claimedAt = normalizeTimestamp(options.claimedAt, 'claimedAt');
+        const leaseDurationMs = normalizeLeaseDuration(options.leaseDurationMs);
+        const leaseExpiresAt = new Date(Date.parse(claimedAt) + leaseDurationMs).toISOString();
+        const fingerprint = createNotificationDeliveryFingerprint(request);
+        const existing = this.deliveriesByIdempotencyKey.get(request.idempotencyKey);
+        if (existing !== undefined) {
+            if (existing.fingerprint !== fingerprint) {
+                throw new Error('idempotencyKey cannot be reused for another notification delivery.');
+            }
+            if (existing.status === 'completed') {
+                return {
+                    status: 'completed',
+                    receipt: existing.receipt,
+                };
+            }
+            if (Date.parse(existing.leaseExpiresAt) > Date.parse(claimedAt)) {
+                return { status: 'in-flight' };
+            }
+        }
+        const claimToken = `notification-claim-${String(this.nextClaimId)}`;
+        this.nextClaimId += 1;
+        this.deliveriesByIdempotencyKey.set(request.idempotencyKey, {
+            status: 'claiming',
+            fingerprint,
+            claimToken,
+            leaseExpiresAt,
+        });
+        return {
+            status: 'claimed',
+            claimToken,
+            leaseExpiresAt,
+        };
+    }
+    async complete(input) {
+        const idempotencyKey = normalizeIdentifier(input.idempotencyKey, 'idempotencyKey');
+        const claimToken = normalizeIdentifier(input.claimToken, 'claimToken');
+        const receipt = normalizeDeliveryReceipt(input.receipt);
+        const existing = this.deliveriesByIdempotencyKey.get(idempotencyKey);
+        if (existing === undefined) {
+            throw new Error('Cannot complete an unclaimed notification delivery.');
+        }
+        if (existing.claimToken !== claimToken) {
+            throw new Error('claimToken does not own this notification delivery.');
+        }
+        if (existing.status === 'completed') {
+            if (!deliveryReceiptsEqual(existing.receipt, receipt)) {
+                throw new Error('A completed notification delivery cannot change its receipt.');
+            }
+            return;
+        }
+        this.deliveriesByIdempotencyKey.set(idempotencyKey, {
+            status: 'completed',
+            fingerprint: existing.fingerprint,
+            claimToken,
+            receipt,
+        });
+    }
+    async release(input) {
+        const idempotencyKey = normalizeIdentifier(input.idempotencyKey, 'idempotencyKey');
+        const claimToken = normalizeIdentifier(input.claimToken, 'claimToken');
+        const existing = this.deliveriesByIdempotencyKey.get(idempotencyKey);
+        if (existing === undefined) {
+            return;
+        }
+        if (existing.claimToken !== claimToken) {
+            throw new Error('claimToken does not own this notification delivery.');
+        }
+        if (existing.status === 'completed') {
+            throw new Error('A completed notification delivery cannot be released.');
+        }
+        this.deliveriesByIdempotencyKey.delete(idempotencyKey);
+    }
+}
+export function createInMemoryNotificationDeliveryLedger() {
+    return new InMemoryNotificationDeliveryLedger();
+}
+export function createNotificationDeliveryService(input) {
+    const providersByTarget = new Map();
+    const allowedDeepLinkOrigins = normalizeAllowedDeepLinkOrigins(input.deepLinkPolicy?.allowedOrigins);
+    const ledger = input.ledger;
+    const claimLeaseMs = normalizeLeaseDuration(input.claimLeaseMs ?? defaultClaimLeaseMs);
+    const now = input.now ?? (() => new Date().toISOString());
+    for (const provider of input.providers) {
+        const target = normalizePlatformTarget(provider.target);
+        if (providersByTarget.has(target)) {
+            throw new Error(`Only one notification provider can be registered for ${target}.`);
+        }
+        providersByTarget.set(target, provider);
+    }
+    const claimDelivery = async (request) => {
+        const claimedAt = normalizeTimestamp(now(), 'now()');
+        const result = await ledger.claim(request, {
+            claimedAt,
+            leaseDurationMs: claimLeaseMs,
+            allowedOrigins: [...allowedDeepLinkOrigins],
+        });
+        return normalizeNotificationDeliveryClaimResult(result, claimedAt);
+    };
+    const completeDelivery = async (request, initialClaimToken, receipt) => {
+        let claimToken = initialClaimToken;
+        let firstCompletionError;
+        // Bound total persistence attempts (the initial claim plus at most two reclaimed claims).
+        for (let attempt = 0; attempt < maxCompletionAttempts; attempt += 1) {
+            try {
+                await ledger.complete({
+                    idempotencyKey: request.idempotencyKey,
+                    claimToken,
+                    receipt,
+                });
+                return undefined;
+            }
+            catch (completionError) {
+                if (firstCompletionError === undefined) {
+                    firstCompletionError = completionError;
+                }
+                else {
+                    attachSecondaryError(firstCompletionError, completionError);
+                }
+                let reconciledClaim;
+                try {
+                    reconciledClaim = await claimDelivery(request);
+                }
+                catch (reconciliationError) {
+                    attachSecondaryError(firstCompletionError, reconciliationError);
+                    throw firstCompletionError;
+                }
+                if (reconciledClaim.status === 'completed') {
+                    return {
+                        status: 'delivered',
+                        alreadyProcessed: true,
+                        receipt: reconciledClaim.receipt,
+                    };
+                }
+                if (reconciledClaim.status === 'in-flight') {
+                    return {
+                        status: 'in-flight',
+                        alreadyProcessed: true,
+                    };
+                }
+                claimToken = reconciledClaim.claimToken;
+            }
+        }
+        try {
+            await ledger.release({
+                idempotencyKey: request.idempotencyKey,
+                claimToken,
+            });
+        }
+        catch (releaseError) {
+            attachSecondaryError(firstCompletionError, releaseError);
+        }
+        throw firstCompletionError;
+    };
+    return {
+        async deliver(deliveryInput) {
+            const request = normalizeNotificationDeliveryRequest(deliveryInput, {
+                allowedOrigins: [...allowedDeepLinkOrigins],
+            });
+            const claim = await claimDelivery(request);
+            if (claim.status === 'completed') {
+                return {
+                    status: 'delivered',
+                    alreadyProcessed: true,
+                    receipt: claim.receipt,
+                };
+            }
+            if (claim.status === 'in-flight') {
+                return {
+                    status: 'in-flight',
+                    alreadyProcessed: true,
+                };
+            }
+            const provider = providersByTarget.get(request.target);
+            if (provider === undefined) {
+                await ledger.release({
+                    idempotencyKey: request.idempotencyKey,
+                    claimToken: claim.claimToken,
+                });
+                return {
+                    status: 'unavailable',
+                    alreadyProcessed: false,
+                };
+            }
+            let receiptInput;
+            try {
+                receiptInput = await provider.deliverIdempotently(request);
+            }
+            catch (error) {
+                if (error instanceof NotificationDeliveryNotSentError) {
+                    try {
+                        await ledger.release({
+                            idempotencyKey: request.idempotencyKey,
+                            claimToken: claim.claimToken,
+                        });
+                    }
+                    catch (releaseError) {
+                        attachSecondaryError(error, releaseError);
+                    }
+                }
+                throw error;
+            }
+            // Once a provider resolves, delivery may already have happened. Keep the
+            // claim on validation or completion failure so an immediate retry cannot
+            // send a duplicate; the lease provides explicit recovery semantics.
+            const receipt = normalizeDeliveryReceipt(receiptInput);
+            const reconciliation = await completeDelivery(request, claim.claimToken, receipt);
+            if (reconciliation !== undefined) {
+                return reconciliation;
+            }
+            return {
+                status: 'delivered',
+                alreadyProcessed: false,
+                receipt,
+            };
+        },
+    };
+}
+export function normalizeNotificationDeliveryRequest(input, policy = {}) {
+    assertRecord(input, 'NotificationDeliveryRequest');
+    const allowedDeepLinkOrigins = normalizeAllowedDeepLinkOrigins(policy.allowedOrigins);
+    return {
+        target: normalizePlatformTarget(input.target),
+        topic: normalizeNotificationTopic(input.topic),
+        recipient: normalizeIdentifier(input.recipient, 'recipient'),
+        idempotencyKey: normalizeIdentifier(input.idempotencyKey, 'idempotencyKey'),
+        deepLink: normalizeDeepLink(input.deepLink, allowedDeepLinkOrigins),
+        templateData: normalizeTemplateData(input.templateData),
+    };
+}
+function normalizePlatformTarget(input) {
+    const target = normalizeIdentifier(input, 'target');
+    if (!platformTargets.has(target)) {
+        throw new Error('target must be a supported PlatformTarget.');
+    }
+    return target;
+}
+function normalizeNotificationTopic(input) {
+    const topic = normalizeIdentifier(input, 'topic');
+    if (!notificationTopics.has(topic)) {
+        throw new Error('topic must be a supported NotificationTopic.');
+    }
+    return topic;
+}
+export function normalizeDeliveryReceipt(input) {
+    assertRecord(input, 'DeliveryReceipt');
+    return {
+        providerMessageId: normalizeIdentifier(input.providerMessageId, 'providerMessageId'),
+        acceptedAt: normalizeTimestamp(input.acceptedAt, 'acceptedAt'),
+    };
+}
+function normalizeNotificationDeliveryClaimResult(input, claimedAt) {
+    assertRecord(input, 'NotificationDeliveryClaimResult');
+    switch (input.status) {
+        case 'claimed': {
+            const leaseExpiresAt = normalizeTimestamp(input.leaseExpiresAt, 'leaseExpiresAt');
+            if (Date.parse(leaseExpiresAt) <= Date.parse(claimedAt)) {
+                throw new Error('Notification delivery claim lease must expire in the future.');
+            }
+            return {
+                status: 'claimed',
+                claimToken: normalizeIdentifier(input.claimToken, 'claimToken'),
+                leaseExpiresAt,
+            };
+        }
+        case 'in-flight':
+            return { status: 'in-flight' };
+        case 'completed':
+            return {
+                status: 'completed',
+                receipt: normalizeDeliveryReceipt(input.receipt),
+            };
+        default:
+            throw new Error('NotificationDeliveryClaimResult has an unsupported status.');
+    }
+}
+function normalizeTemplateData(input) {
+    assertRecord(input, 'templateData');
+    assertOwnEnumerablePropertyLimit(input, maxNotificationTemplateDataEntries, 'templateData');
+    const inputEntries = Object.entries(input);
+    const entries = inputEntries.map(([key, value]) => {
+        const normalizedKey = normalizeIdentifier(key, 'templateData key');
+        if (typeof value !== 'string'
+            && typeof value !== 'number'
+            && typeof value !== 'boolean') {
+            throw new Error(`templateData.${key} must be a string, number, or boolean.`);
+        }
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            throw new Error(`templateData.${key} must be a finite number.`);
+        }
+        if (typeof value === 'string' && value.length > 16384) {
+            throw new Error(`templateData.${key} must contain at most 16384 characters.`);
+        }
+        return [normalizedKey, value];
+    });
+    entries.sort(([left], [right]) => compareCodeUnits(left, right));
+    return Object.fromEntries(entries);
+}
+function normalizeDeepLink(input, allowedOrigins) {
+    const deepLink = normalizeIdentifier(input, 'deepLink');
+    if (/[\x00-\x1F\x7F]/u.test(deepLink)) {
+        throw new Error('deepLink must not contain control characters.');
+    }
+    if (deepLink.startsWith('/') && !deepLink.startsWith('//')) {
+        const baseUrl = new URL('https://mpgd.invalid');
+        const parsed = new URL(deepLink, baseUrl);
+        if (parsed.origin !== baseUrl.origin) {
+            throw new Error('deepLink must stay on the configured game origin.');
+        }
+        return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(deepLink);
+    }
+    catch {
+        throw new Error('deepLink must be an absolute URL or root-relative path.');
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error('deepLink must use an HTTP(S) URL.');
+    }
+    if (parsed.username !== '' || parsed.password !== '') {
+        throw new Error('deepLink must not contain URL credentials.');
+    }
+    if (!allowedOrigins.has(parsed.origin)) {
+        throw new Error('deepLink origin is not allowed.');
+    }
+    return parsed.toString();
+}
+function normalizeAllowedDeepLinkOrigins(input) {
+    const origins = new Set();
+    for (const [index, value] of (input ?? []).entries()) {
+        const originInput = normalizeIdentifier(value, `allowedOrigins[${String(index)}]`);
+        let parsed;
+        try {
+            parsed = new URL(originInput);
+        }
+        catch {
+            throw new Error(`allowedOrigins[${String(index)}] must be an HTTP(S) origin.`);
+        }
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            throw new Error(`allowedOrigins[${String(index)}] must be an HTTP(S) origin.`);
+        }
+        if (parsed.username !== ''
+            || parsed.password !== ''
+            || parsed.pathname !== '/'
+            || parsed.search !== ''
+            || parsed.hash !== '') {
+            throw new Error(`allowedOrigins[${String(index)}] must not include credentials or a path.`);
+        }
+        origins.add(parsed.origin);
+    }
+    return origins;
+}
+function normalizeLeaseDuration(input) {
+    if (typeof input !== 'number'
+        || !Number.isSafeInteger(input)
+        || input <= 0
+        || input > 24 * 60 * 60 * 1000) {
+        throw new Error('claimLeaseMs must be a positive integer no greater than 24 hours.');
+    }
+    return input;
+}
+function createNotificationDeliveryFingerprint(request) {
+    return JSON.stringify([
+        request.target,
+        request.topic,
+        request.recipient,
+        request.deepLink,
+        request.templateData,
+    ]);
+}
+function deliveryReceiptsEqual(left, right) {
+    return (left.providerMessageId === right.providerMessageId
+        && left.acceptedAt === right.acceptedAt);
+}
+function compareCodeUnits(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    return left > right ? 1 : 0;
+}
+function attachSecondaryError(primary, secondary) {
+    if (primary instanceof Error && primary.cause === undefined) {
+        primary.cause = secondary;
+    }
+}
+function assertRecord(input, label) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error(`${label} must be an object.`);
+    }
+}
+function normalizeIdentifier(input, label) {
+    if (typeof input !== 'string'
+        || input.length === 0
+        || input.length > 2048
+        || input.trim() !== input) {
+        throw new Error(`${label} must be a non-empty, trimmed string.`);
+    }
+    if (/[\x00-\x1F\x7F]/u.test(input)) {
+        throw new Error(`${label} must not contain control characters.`);
+    }
+    return input;
+}
+function normalizeTimestamp(input, label) {
+    if (typeof input !== 'string') {
+        throw new Error(`${label} must be a valid timestamp.`);
+    }
+    const timestamp = Date.parse(input);
+    if (!Number.isFinite(timestamp)) {
+        throw new Error(`${label} must be a valid timestamp.`);
+    }
+    return new Date(timestamp).toISOString();
+}

package/dist/progress-link.d.ts

@@ -0,0 +1,96 @@
+export type GameProgressValue = null | boolean | number | string | readonly GameProgressValue[] | {
+  readonly [key: string]: GameProgressValue;
+};
+export interface ActiveGameProgress {
+  readonly id: string;
+  readonly updatedAt: string;
+  readonly payload: {
+    readonly [key: string]: GameProgressValue;
+  };
+}
+export interface GameProgressSnapshot {
+  readonly completedIds: readonly string[];
+  readonly bestTimesMs: Readonly<Record<string, number>>;
+  readonly bestScores: Readonly<Record<string, number>>;
+  readonly activeProgress?: ActiveGameProgress;
+}
+export declare const gameProgressLimits: {
+  readonly maxIdentifierLength: 256;
+  readonly maxCompletedIds: 512;
+  readonly maxMetricEntries: 512;
+  readonly maxPayloadDepth: 16;
+  readonly maxPayloadNodes: 2048;
+  readonly maxPayloadStringUnits: 32768;
+};
+export interface ServerResolvedPlayerContext {
+  readonly authoritativePlayerId: string;
+}
+export interface GuestProgressHandoffRequest {
+  readonly guestId: string;
+  readonly handoffNonce: string;
+  readonly idempotencyKey: string;
+  readonly guestProgress: GameProgressSnapshot;
+}
+export interface ReconcileGuestProgressRequest extends GuestProgressHandoffRequest {
+  readonly authoritativePlayerId: string;
+}
+export interface ProgressHandoffVerificationRequest {
+  readonly handoffNonce: string;
+}
+export interface VerifiedProgressHandoff {
+  readonly handoffNonce: string;
+  readonly authoritativePlayerId: string;
+  readonly guestId: string;
+  readonly issuedAt: string;
+  readonly expiresAt: string;
+}
+export interface ProgressHandoffVerifier {
+  verify(request: ProgressHandoffVerificationRequest): Promise<VerifiedProgressHandoff | undefined>;
+}
+export interface VerifyGuestProgressRequest {
+  readonly authoritativePlayerId: string;
+  readonly guestId: string;
+  readonly handoffNonce: string;
+  readonly progress: GameProgressSnapshot;
+}
+export interface GuestProgressVerifier {
+  /** Validates client metrics and returns only server-accepted, non-authoritative progress. */
+  verify(request: VerifyGuestProgressRequest): Promise<GameProgressSnapshot>;
+}
+export type ProgressLinkDeduplication = 'none' | 'idempotency-key' | 'handoff-nonce';
+export interface ReconcileGuestProgressResult {
+  readonly authoritativePlayerId: string;
+  readonly progress: GameProgressSnapshot;
+  readonly alreadyProcessed: boolean;
+  readonly deduplicatedBy: ProgressLinkDeduplication;
+}
+export interface ProgressLinkStore {
+  /** Atomically deduplicates by both idempotency key and handoff nonce before merging. */
+  reconcile(request: ReconcileGuestProgressRequest): Promise<ReconcileGuestProgressResult>;
+}
+export interface ProgressLinkService {
+  reconcileGuestProgress(context: ServerResolvedPlayerContext, request: GuestProgressHandoffRequest): Promise<ReconcileGuestProgressResult>;
+}
+export interface AuthoritativeProgressRecord {
+  readonly authoritativePlayerId: string;
+  readonly progress: GameProgressSnapshot;
+}
+/** Process-local test helper. Production services must provide a durable store. */
+export declare class InMemoryProgressLinkStore implements ProgressLinkStore {
+  private readonly progressByPlayerId;
+  private readonly reconciliationsByIdempotencyKey;
+  private readonly reconciliationsByHandoffNonce;
+  constructor(initialProgress?: readonly AuthoritativeProgressRecord[]);
+  reconcile(input: ReconcileGuestProgressRequest): Promise<ReconcileGuestProgressResult>;
+  getProgress(authoritativePlayerId: string): Promise<GameProgressSnapshot | undefined>;
+}
+export declare function createInMemoryProgressLinkStore(initialProgress?: readonly AuthoritativeProgressRecord[]): InMemoryProgressLinkStore;
+export declare function createProgressLinkService(input: {
+  readonly store: ProgressLinkStore;
+  readonly handoffVerifier: ProgressHandoffVerifier;
+  readonly progressVerifier: GuestProgressVerifier;
+  readonly now?: () => string;
+}): ProgressLinkService;
+export declare function createEmptyGameProgressSnapshot(): GameProgressSnapshot;
+export declare function normalizeGameProgressSnapshot(input: unknown): GameProgressSnapshot;
+export declare function mergeGameProgressSnapshots(serverInput: GameProgressSnapshot, guestInput: GameProgressSnapshot): GameProgressSnapshot;

package/dist/progress-link.js

@@ -0,0 +1,394 @@
+import { assertOwnEnumerablePropertyLimit } from './validation';
+export const gameProgressLimits = {
+    maxIdentifierLength: 256,
+    maxCompletedIds: 512,
+    maxMetricEntries: 512,
+    maxPayloadDepth: 16,
+    maxPayloadNodes: 2048,
+    maxPayloadStringUnits: 32768,
+};
+const snapshotFields = new Set(['completedIds', 'bestTimesMs', 'bestScores', 'activeProgress']);
+const activeProgressFields = new Set(['id', 'updatedAt', 'payload']);
+/** Process-local test helper. Production services must provide a durable store. */
+export class InMemoryProgressLinkStore {
+    progressByPlayerId = new Map();
+    reconciliationsByIdempotencyKey = new Map();
+    reconciliationsByHandoffNonce = new Map();
+    constructor(initialProgress = []) {
+        for (const record of initialProgress) {
+            const authoritativePlayerId = normalizeIdentifier(record.authoritativePlayerId, 'authoritativePlayerId');
+            this.progressByPlayerId.set(authoritativePlayerId, normalizeGameProgressSnapshot(record.progress));
+        }
+    }
+    async reconcile(input) {
+        const request = normalizeReconcileGuestProgressRequest(input);
+        const byIdempotencyKey = this.reconciliationsByIdempotencyKey.get(request.idempotencyKey);
+        const byHandoffNonce = this.reconciliationsByHandoffNonce.get(request.handoffNonce);
+        if (byIdempotencyKey !== undefined
+            && byHandoffNonce !== undefined
+            && byIdempotencyKey !== byHandoffNonce) {
+            throw new Error('idempotencyKey and handoffNonce belong to different reconciliations.');
+        }
+        const existing = byIdempotencyKey ?? byHandoffNonce;
+        if (existing !== undefined) {
+            assertMatchingProgressLinkIdentity(existing, request);
+            this.reconciliationsByIdempotencyKey.set(request.idempotencyKey, existing);
+            this.reconciliationsByHandoffNonce.set(request.handoffNonce, existing);
+            return {
+                authoritativePlayerId: existing.authoritativePlayerId,
+                progress: normalizeGameProgressSnapshot(existing.progress),
+                alreadyProcessed: true,
+                deduplicatedBy: byIdempotencyKey === undefined ? 'handoff-nonce' : 'idempotency-key',
+            };
+        }
+        const serverProgress = this.progressByPlayerId.get(request.authoritativePlayerId)
+            ?? createEmptyGameProgressSnapshot();
+        const progress = mergeGameProgressSnapshots(serverProgress, request.guestProgress);
+        const reconciliation = {
+            authoritativePlayerId: request.authoritativePlayerId,
+            guestId: request.guestId,
+            progress,
+        };
+        this.progressByPlayerId.set(request.authoritativePlayerId, progress);
+        this.reconciliationsByIdempotencyKey.set(request.idempotencyKey, reconciliation);
+        this.reconciliationsByHandoffNonce.set(request.handoffNonce, reconciliation);
+        return {
+            authoritativePlayerId: request.authoritativePlayerId,
+            progress: normalizeGameProgressSnapshot(progress),
+            alreadyProcessed: false,
+            deduplicatedBy: 'none',
+        };
+    }
+    async getProgress(authoritativePlayerId) {
+        const progress = this.progressByPlayerId.get(normalizeIdentifier(authoritativePlayerId, 'authoritativePlayerId'));
+        return progress === undefined ? undefined : normalizeGameProgressSnapshot(progress);
+    }
+}
+export function createInMemoryProgressLinkStore(initialProgress = []) {
+    return new InMemoryProgressLinkStore(initialProgress);
+}
+export function createProgressLinkService(input) {
+    const now = input.now ?? (() => new Date().toISOString());
+    return {
+        async reconcileGuestProgress(contextInput, handoffInput) {
+            const context = normalizeServerResolvedPlayerContext(contextInput);
+            const metadata = normalizeGuestProgressHandoffMetadata(handoffInput);
+            await verifyProgressHandoff(input.handoffVerifier, context, metadata, now);
+            // These validations deliberately stay at separate trust boundaries: the
+            // client request, verifier output, store input, and store output may each
+            // come from independently implemented code. Payload limits keep every
+            // traversal bounded while preventing a typed-but-unvalidated value from
+            // skipping runtime validation.
+            const guestProgress = normalizeGameProgressSnapshot(handoffInput.guestProgress);
+            const verifiedProgress = normalizeGameProgressSnapshot(await input.progressVerifier.verify({
+                authoritativePlayerId: context.authoritativePlayerId,
+                guestId: metadata.guestId,
+                handoffNonce: metadata.handoffNonce,
+                progress: guestProgress,
+            }));
+            const result = await input.store.reconcile({
+                authoritativePlayerId: context.authoritativePlayerId,
+                ...metadata,
+                guestProgress: verifiedProgress,
+            });
+            return normalizeReconcileGuestProgressResult(result, context.authoritativePlayerId);
+        },
+    };
+}
+export function createEmptyGameProgressSnapshot() {
+    return {
+        completedIds: [],
+        bestTimesMs: {},
+        bestScores: {},
+    };
+}
+export function normalizeGameProgressSnapshot(input) {
+    assertRecord(input, 'GameProgressSnapshot');
+    assertOnlyFields(input, snapshotFields, 'GameProgressSnapshot');
+    if (!Array.isArray(input.completedIds)) {
+        throw new Error('completedIds must be an array.');
+    }
+    assertCollectionLimit(input.completedIds.length, gameProgressLimits.maxCompletedIds, 'completedIds');
+    const completedIds = [...new Set(Array.from(input.completedIds, (id, index) => (normalizeIdentifier(id, `completedIds[${String(index)}]`))))].sort();
+    const bestTimesMs = normalizeMetricMap(input.bestTimesMs, 'bestTimesMs', (value, label) => {
+        if (value < 0) {
+            throw new Error(`${label} must be greater than or equal to zero.`);
+        }
+    });
+    const bestScores = normalizeMetricMap(input.bestScores, 'bestScores');
+    if (input.activeProgress === undefined) {
+        return {
+            completedIds,
+            bestTimesMs,
+            bestScores,
+        };
+    }
+    return {
+        completedIds,
+        bestTimesMs,
+        bestScores,
+        activeProgress: normalizeActiveProgress(input.activeProgress),
+    };
+}
+export function mergeGameProgressSnapshots(serverInput, guestInput) {
+    // This exported helper is also a runtime boundary; TypeScript types alone do
+    // not prove that either snapshot came from a trusted or validated source.
+    const server = normalizeGameProgressSnapshot(serverInput);
+    const guest = normalizeGameProgressSnapshot(guestInput);
+    const activeProgress = selectActiveProgress(server.activeProgress, guest.activeProgress);
+    const completedIds = [...new Set([...server.completedIds, ...guest.completedIds])].sort();
+    assertCollectionLimit(completedIds.length, gameProgressLimits.maxCompletedIds, 'merged completedIds');
+    return {
+        completedIds,
+        bestTimesMs: mergeMetricMaps(server.bestTimesMs, guest.bestTimesMs, Math.min),
+        bestScores: mergeMetricMaps(server.bestScores, guest.bestScores, Math.max),
+        ...(activeProgress === undefined ? {} : { activeProgress }),
+    };
+}
+function normalizeReconcileGuestProgressRequest(input) {
+    assertRecord(input, 'ReconcileGuestProgressRequest');
+    const metadata = normalizeGuestProgressHandoffMetadata(input);
+    return {
+        authoritativePlayerId: normalizeIdentifier(input.authoritativePlayerId, 'authoritativePlayerId'),
+        ...metadata,
+        guestProgress: normalizeGameProgressSnapshot(input.guestProgress),
+    };
+}
+function normalizeServerResolvedPlayerContext(input) {
+    assertRecord(input, 'ServerResolvedPlayerContext');
+    return {
+        authoritativePlayerId: normalizeIdentifier(input.authoritativePlayerId, 'authoritativePlayerId'),
+    };
+}
+function normalizeGuestProgressHandoffMetadata(input) {
+    assertRecord(input, 'GuestProgressHandoffRequest');
+    return {
+        guestId: normalizeIdentifier(input.guestId, 'guestId'),
+        handoffNonce: normalizeIdentifier(input.handoffNonce, 'handoffNonce'),
+        idempotencyKey: normalizeIdentifier(input.idempotencyKey, 'idempotencyKey'),
+    };
+}
+async function verifyProgressHandoff(verifier, context, request, now) {
+    const handoff = await verifier.verify({ handoffNonce: request.handoffNonce });
+    if (handoff === undefined) {
+        throw new Error('Progress handoff is invalid or expired.');
+    }
+    const verified = normalizeVerifiedProgressHandoff(handoff);
+    const currentTime = Date.parse(normalizeTimestamp(now(), 'now()'));
+    const issuedAt = Date.parse(verified.issuedAt);
+    const expiresAt = Date.parse(verified.expiresAt);
+    if (verified.handoffNonce !== request.handoffNonce
+        || verified.authoritativePlayerId !== context.authoritativePlayerId
+        || verified.guestId !== request.guestId
+        || issuedAt > currentTime
+        || expiresAt <= issuedAt
+        || expiresAt <= currentTime) {
+        throw new Error('Progress handoff is invalid or expired.');
+    }
+}
+function normalizeReconcileGuestProgressResult(input, expectedPlayerId) {
+    assertRecord(input, 'ReconcileGuestProgressResult');
+    const authoritativePlayerId = normalizeIdentifier(input.authoritativePlayerId, 'result authoritativePlayerId');
+    if (authoritativePlayerId !== expectedPlayerId) {
+        throw new Error('Progress link store returned a result for another player.');
+    }
+    if (typeof input.alreadyProcessed !== 'boolean') {
+        throw new Error('Progress link store returned an invalid alreadyProcessed value.');
+    }
+    if (input.deduplicatedBy !== 'none'
+        && input.deduplicatedBy !== 'idempotency-key'
+        && input.deduplicatedBy !== 'handoff-nonce') {
+        throw new Error('Progress link store returned an invalid deduplicatedBy value.');
+    }
+    if (input.alreadyProcessed !== (input.deduplicatedBy !== 'none')) {
+        throw new Error('Progress link store returned inconsistent deduplication state.');
+    }
+    return {
+        authoritativePlayerId,
+        progress: normalizeGameProgressSnapshot(input.progress),
+        alreadyProcessed: input.alreadyProcessed,
+        deduplicatedBy: input.deduplicatedBy,
+    };
+}
+function normalizeVerifiedProgressHandoff(input) {
+    assertRecord(input, 'VerifiedProgressHandoff');
+    return {
+        handoffNonce: normalizeIdentifier(input.handoffNonce, 'verified handoffNonce'),
+        authoritativePlayerId: normalizeIdentifier(input.authoritativePlayerId, 'verified authoritativePlayerId'),
+        guestId: normalizeIdentifier(input.guestId, 'verified guestId'),
+        issuedAt: normalizeTimestamp(input.issuedAt, 'verified issuedAt'),
+        expiresAt: normalizeTimestamp(input.expiresAt, 'verified expiresAt'),
+    };
+}
+function normalizeActiveProgress(input) {
+    assertRecord(input, 'activeProgress');
+    assertOnlyFields(input, activeProgressFields, 'activeProgress');
+    return {
+        id: normalizeIdentifier(input.id, 'activeProgress.id'),
+        updatedAt: normalizeTimestamp(input.updatedAt, 'activeProgress.updatedAt'),
+        payload: normalizeProgressPayload(input.payload),
+    };
+}
+function normalizeMetricMap(input, label, validate) {
+    assertRecord(input, label);
+    assertOwnEnumerablePropertyLimit(input, gameProgressLimits.maxMetricEntries, label);
+    const inputEntries = Object.entries(input);
+    const entries = inputEntries.map(([key, value]) => {
+        const normalizedKey = normalizeIdentifier(key, `${label} key`);
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            throw new Error(`${label}.${key} must be a finite number.`);
+        }
+        validate?.(value, `${label}.${key}`);
+        return [normalizedKey, value];
+    });
+    entries.sort(([left], [right]) => compareCodeUnits(left, right));
+    return Object.fromEntries(entries);
+}
+function mergeMetricMaps(server, guest, select) {
+    const keys = [...new Set([...Object.keys(server), ...Object.keys(guest)])].sort();
+    assertCollectionLimit(keys.length, gameProgressLimits.maxMetricEntries, 'merged metric map');
+    const mergedEntries = [];
+    for (const key of keys) {
+        const serverValue = Object.hasOwn(server, key) ? server[key] : undefined;
+        const guestValue = Object.hasOwn(guest, key) ? guest[key] : undefined;
+        if (serverValue === undefined) {
+            if (guestValue !== undefined) {
+                mergedEntries.push([key, guestValue]);
+            }
+            continue;
+        }
+        if (guestValue === undefined) {
+            mergedEntries.push([key, serverValue]);
+            continue;
+        }
+        mergedEntries.push([key, select(serverValue, guestValue)]);
+    }
+    return Object.fromEntries(mergedEntries);
+}
+function selectActiveProgress(server, guest) {
+    if (server === undefined) {
+        return guest;
+    }
+    if (guest === undefined) {
+        return server;
+    }
+    return Date.parse(guest.updatedAt) > Date.parse(server.updatedAt) ? guest : server;
+}
+function normalizeProgressPayload(input) {
+    assertRecord(input, 'activeProgress.payload');
+    const normalized = normalizeGameProgressValue(input, 'activeProgress.payload', new Set(), { nodes: 0, stringUnits: 0 }, 0);
+    if (!isGameProgressRecord(normalized)) {
+        throw new Error('activeProgress.payload must be an object.');
+    }
+    return normalized;
+}
+function normalizeGameProgressValue(input, label, ancestors, budget, depth) {
+    if (depth > gameProgressLimits.maxPayloadDepth) {
+        throw new Error(`activeProgress.payload must not exceed depth ${String(gameProgressLimits.maxPayloadDepth)}.`);
+    }
+    budget.nodes += 1;
+    if (budget.nodes > gameProgressLimits.maxPayloadNodes) {
+        throw new Error(`activeProgress.payload must not exceed ${String(gameProgressLimits.maxPayloadNodes)} nodes.`);
+    }
+    if (input === null
+        || typeof input === 'boolean') {
+        return input;
+    }
+    if (typeof input === 'string') {
+        consumePayloadStringBudget(budget, input.length);
+        return input;
+    }
+    if (typeof input === 'number') {
+        if (!Number.isFinite(input)) {
+            throw new Error(`${label} must contain only finite numbers.`);
+        }
+        return input;
+    }
+    if (typeof input !== 'object') {
+        throw new Error(`${label} must be JSON-compatible.`);
+    }
+    if (ancestors.has(input)) {
+        throw new Error(`${label} must not contain circular references.`);
+    }
+    ancestors.add(input);
+    if (Array.isArray(input)) {
+        assertCollectionLimit(input.length, gameProgressLimits.maxPayloadNodes, 'activeProgress.payload array');
+        const output = Array.from(input, (value, index) => {
+            return normalizeGameProgressValue(value, `${label}[${String(index)}]`, ancestors, budget, depth + 1);
+        });
+        ancestors.delete(input);
+        return output;
+    }
+    assertRecord(input, label);
+    assertOwnEnumerablePropertyLimit(input, gameProgressLimits.maxPayloadNodes, label);
+    const entries = Object.entries(input)
+        .sort(([left], [right]) => compareCodeUnits(left, right))
+        .map(([key, value]) => {
+        const normalizedKey = normalizeIdentifier(key, `${label} key`);
+        consumePayloadStringBudget(budget, normalizedKey.length);
+        return [
+            normalizedKey,
+            normalizeGameProgressValue(value, `${label}.${key}`, ancestors, budget, depth + 1),
+        ];
+    });
+    ancestors.delete(input);
+    return Object.fromEntries(entries);
+}
+function consumePayloadStringBudget(budget, stringUnits) {
+    budget.stringUnits += stringUnits;
+    if (budget.stringUnits > gameProgressLimits.maxPayloadStringUnits) {
+        throw new Error(`activeProgress.payload strings must not exceed ${String(gameProgressLimits.maxPayloadStringUnits)} total characters.`);
+    }
+}
+function isGameProgressRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
+function compareCodeUnits(left, right) {
+    if (left < right) {
+        return -1;
+    }
+    return left > right ? 1 : 0;
+}
+function assertMatchingProgressLinkIdentity(existing, request) {
+    if (existing.authoritativePlayerId !== request.authoritativePlayerId
+        || existing.guestId !== request.guestId) {
+        throw new Error('A reconciliation key cannot be reused for another player or guest.');
+    }
+}
+function assertOnlyFields(input, allowedFields, label) {
+    for (const key of Object.keys(input)) {
+        if (!allowedFields.has(key)) {
+            throw new Error(`${label} contains unsupported field ${key}.`);
+        }
+    }
+}
+function assertCollectionLimit(length, maximum, label) {
+    if (length > maximum) {
+        throw new Error(`${label} must not contain more than ${String(maximum)} entries.`);
+    }
+}
+function assertRecord(input, label) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error(`${label} must be an object.`);
+    }
+}
+function normalizeIdentifier(input, label) {
+    if (typeof input !== 'string' || input.length === 0 || input.trim() !== input) {
+        throw new Error(`${label} must be a non-empty, trimmed string.`);
+    }
+    if (input.length > gameProgressLimits.maxIdentifierLength) {
+        throw new Error(`${label} must not exceed ${String(gameProgressLimits.maxIdentifierLength)} characters.`);
+    }
+    if (/[\x00-\x1F\x7F]/u.test(input)) {
+        throw new Error(`${label} must not contain control characters.`);
+    }
+    return input;
+}
+function normalizeTimestamp(input, label) {
+    const value = normalizeIdentifier(input, label);
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp)) {
+        throw new Error(`${label} must be a valid timestamp.`);
+    }
+    return new Date(timestamp).toISOString();
+}

package/dist/server.d.ts

@@ -75,4 +75,5 @@ export declare function createGameServicesRouter(backend: GameServicesBackendApi
 };
 export declare function createGameServicesRpcFetchHandler(router: ReturnType<typeof createGameServicesRouter>, options?: CreateGameServicesRpcFetchHandlerOptions): (request: Request) => Promise<Response>;
 export declare function createGameServicesHttpFetchHandler(handler: GameServicesBackendApiHandler, options?: CreateGameServicesFetchHandlerOptions): (request: Request) => Promise<Response>;
-export {};
+export * from './notification-delivery';
+export * from './progress-link';

package/dist/server.js

@@ -472,3 +472,5 @@ function applyCorsHeaders(headers, corsHeaders) {
         headers.set(key, value);
     }
 }
+export * from './notification-delivery';
+export * from './progress-link';

package/dist/validation.d.ts

@@ -0,0 +1 @@
+export declare function assertOwnEnumerablePropertyLimit(input: Record<string, unknown>, maximum: number, label: string): void;

package/dist/validation.js

@@ -0,0 +1,11 @@
+export function assertOwnEnumerablePropertyLimit(input, maximum, label) {
+    let propertyCount = 0;
+    for (const key in input) {
+        if (Object.hasOwn(input, key)) {
+            propertyCount += 1;
+            if (propertyCount > maximum) {
+                throw new Error(`${label} must not contain more than ${String(maximum)} entries.`);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -37,6 +37,14 @@
       "types": "./dist/contract.d.ts",
       "default": "./dist/contract.js"
     },
+    "./notification-delivery": {
+      "types": "./dist/notification-delivery.d.ts",
+      "default": "./dist/notification-delivery.js"
+    },
+    "./progress-link": {
+      "types": "./dist/progress-link.d.ts",
+      "default": "./dist/progress-link.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
@@ -53,9 +61,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/catalog": "0.3.2",
-    "@mpgd/platform": "0.3.2",
-    "@mpgd/analytics": "0.3.2"
+    "@mpgd/analytics": "0.3.3",
+    "@mpgd/catalog": "0.3.3",
+    "@mpgd/platform": "0.4.0"
   },
   "devDependencies": {
     "ttsc": "0.16.9",
@@ -71,6 +79,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts"
+    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts"
   }
 }