@mpgd/game-services 0.4.0 → 0.6.0

package/dist/verified-leaderboard-transport.js

@@ -0,0 +1,169 @@
+import { assertGetVerifiedLeaderboardSnapshotRequest, assertVerifiedLeaderboardSnapshot, VerifiedLeaderboardCursorError, } from './verified-leaderboard.js';
+export const verifiedLeaderboardSnapshotPath = '/game-services/verified-leaderboard/snapshot';
+export function createVerifiedLeaderboardSnapshotFetchHandler(input) {
+    const path = input.path ?? verifiedLeaderboardSnapshotPath;
+    return async (request) => {
+        const requestUrl = new URL(request.url);
+        if (requestUrl.pathname !== path) {
+            return undefined;
+        }
+        if (request.method === 'OPTIONS') {
+            return emptyResponse(204, input.corsHeaders);
+        }
+        if (request.method !== 'GET') {
+            return jsonResponse({ error: 'METHOD_NOT_ALLOWED' }, 405, input.corsHeaders, {
+                Allow: 'GET, OPTIONS',
+            });
+        }
+        let principal;
+        try {
+            principal = await input.authenticate(request);
+            if (principal !== undefined) {
+                assertPrincipal(principal);
+            }
+        }
+        catch {
+            return jsonResponse({ error: 'AUTHENTICATION_FAILED' }, 500, input.corsHeaders);
+        }
+        if (principal === undefined) {
+            return jsonResponse({ error: 'UNAUTHORIZED' }, 401, input.corsHeaders);
+        }
+        let snapshotRequest;
+        try {
+            snapshotRequest = readSnapshotRequest(requestUrl);
+            assertGetVerifiedLeaderboardSnapshotRequest(snapshotRequest);
+        }
+        catch (error) {
+            if (error instanceof VerifiedLeaderboardCursorError) {
+                return jsonResponse({ error: 'INVALID_CURSOR' }, 400, input.corsHeaders);
+            }
+            return jsonResponse({ error: error instanceof Error ? error.message : 'BAD_REQUEST' }, 400, input.corsHeaders);
+        }
+        try {
+            const snapshot = await input.reader.getSnapshot({
+                ...snapshotRequest,
+                participantId: principal.participantId,
+            });
+            if (snapshot === undefined) {
+                return jsonResponse({ error: 'LEADERBOARD_NOT_FOUND' }, 404, input.corsHeaders);
+            }
+            assertVerifiedLeaderboardSnapshot(snapshot);
+            return jsonResponse(snapshot, 200, input.corsHeaders);
+        }
+        catch (error) {
+            return error instanceof VerifiedLeaderboardCursorError
+                ? jsonResponse({ error: 'INVALID_CURSOR' }, 400, input.corsHeaders)
+                : jsonResponse({ error: 'INTERNAL_ERROR' }, 500, input.corsHeaders);
+        }
+    };
+}
+export function createVerifiedLeaderboardSnapshotFetchClient(input) {
+    const fetcher = input.fetch ?? globalThis.fetch;
+    if (fetcher === undefined) {
+        throw new Error('A fetch implementation is required for leaderboard snapshot reads.');
+    }
+    const endpoint = createEndpointUrl(input.baseUrl, input.path ?? verifiedLeaderboardSnapshotPath);
+    return {
+        async getSnapshot(requestInput) {
+            assertGetVerifiedLeaderboardSnapshotRequest(requestInput);
+            const authorization = await input.authorization();
+            if (typeof authorization !== 'string' || authorization.length === 0) {
+                throw new Error('authorization must be a non-empty string.');
+            }
+            const url = new URL(endpoint);
+            url.searchParams.set('leaderboardId', requestInput.leaderboardId);
+            if (requestInput.limit !== undefined) {
+                url.searchParams.set('limit', String(requestInput.limit));
+            }
+            if (requestInput.cursor !== undefined) {
+                url.searchParams.set('cursor', requestInput.cursor);
+            }
+            const response = await fetcher(url, {
+                method: 'GET',
+                headers: {
+                    Authorization: authorization,
+                },
+            });
+            let body;
+            try {
+                body = await response.json();
+            }
+            catch {
+                throw new Error(`Verified leaderboard snapshot response was not JSON (status ${response.status}).`);
+            }
+            if (response.status === 404 && readErrorCode(body) === 'LEADERBOARD_NOT_FOUND') {
+                return undefined;
+            }
+            if (!response.ok) {
+                const error = readErrorCode(body);
+                throw new Error(`Verified leaderboard snapshot request failed: ${error}.`);
+            }
+            assertVerifiedLeaderboardSnapshot(body);
+            return body;
+        },
+    };
+}
+function readSnapshotRequest(url) {
+    const allowedParameters = new Set(['leaderboardId', 'limit', 'cursor']);
+    for (const parameter of url.searchParams.keys()) {
+        if (!allowedParameters.has(parameter)) {
+            throw new Error(`Unsupported snapshot query parameter: ${parameter}.`);
+        }
+    }
+    for (const parameter of allowedParameters) {
+        if (url.searchParams.getAll(parameter).length > 1) {
+            throw new Error(`Snapshot query parameter must not be repeated: ${parameter}.`);
+        }
+    }
+    const leaderboardId = url.searchParams.get('leaderboardId') ?? '';
+    const limitValue = url.searchParams.get('limit');
+    const cursor = url.searchParams.get('cursor') ?? undefined;
+    const limit = limitValue === null ? undefined : Number(limitValue);
+    return {
+        leaderboardId,
+        ...(limit === undefined ? {} : { limit }),
+        ...(cursor === undefined ? {} : { cursor }),
+    };
+}
+function assertPrincipal(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        throw new Error('Verified leaderboard principal must be an object.');
+    }
+    const participantId = input.participantId;
+    if (typeof participantId !== 'string' || participantId.length === 0) {
+        throw new Error('Verified leaderboard principal participantId must be non-empty.');
+    }
+}
+function readErrorCode(input) {
+    if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+        return 'UNKNOWN_ERROR';
+    }
+    const error = input.error;
+    return typeof error === 'string' && error.length > 0 ? error : 'UNKNOWN_ERROR';
+}
+function createEndpointUrl(baseUrl, path) {
+    const normalizedBaseUrl = new URL(baseUrl);
+    normalizedBaseUrl.search = '';
+    normalizedBaseUrl.hash = '';
+    if (!normalizedBaseUrl.pathname.endsWith('/')) {
+        normalizedBaseUrl.pathname = `${normalizedBaseUrl.pathname}/`;
+    }
+    return new URL(path.replace(/^\/+/u, ''), normalizedBaseUrl);
+}
+function jsonResponse(body, status, corsHeaders, additionalHeaders) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: {
+            ...corsHeaders,
+            ...additionalHeaders,
+            'Content-Type': 'application/json; charset=utf-8',
+            'Cache-Control': 'private, no-store',
+        },
+    });
+}
+function emptyResponse(status, corsHeaders) {
+    return new Response(null, {
+        status,
+        ...(corsHeaders === undefined ? {} : { headers: corsHeaders }),
+    });
+}

package/dist/verified-leaderboard.d.ts

@@ -0,0 +1,112 @@
+export type VerifiedLeaderboardScoreOrder = 'ascending' | 'descending';
+export type VerifiedLeaderboardAttemptSelection = 'first' | 'best';
+export declare const verifiedLeaderboardIdentifierMaximumLength = 512;
+export interface VerifiedLeaderboardDefinition {
+  readonly leaderboardId: string;
+  readonly scoreOrder: VerifiedLeaderboardScoreOrder;
+  readonly attemptSelection: VerifiedLeaderboardAttemptSelection;
+}
+export interface LeaderboardVerificationEvidence {
+  readonly authorityId: string;
+  readonly evidenceId: string;
+  readonly verifiedAt: string;
+}
+export interface VerifiedLeaderboardAttempt {
+  readonly participantId: string;
+  readonly participantLabel?: string;
+  readonly attemptId: string;
+  readonly score: number;
+  readonly completedAt: string;
+  readonly verification: LeaderboardVerificationEvidence;
+}
+export interface RecordVerifiedLeaderboardAttemptRequest {
+  readonly definition: VerifiedLeaderboardDefinition;
+  readonly attempt: VerifiedLeaderboardAttempt;
+}
+export interface LeaderboardRankedEntry {
+  readonly rank: number;
+  readonly participantId: string;
+  readonly participantLabel?: string;
+  readonly attemptId: string;
+  readonly score: number;
+  readonly completedAt: string;
+}
+export interface RecordVerifiedLeaderboardAttemptResponse {
+  readonly recorded: true;
+  readonly alreadyProcessed: boolean;
+  readonly retained: boolean;
+  readonly entry: LeaderboardRankedEntry;
+  readonly reason?: 'ATTEMPT_NOT_RETAINED';
+}
+export interface GetVerifiedLeaderboardSnapshotRequest {
+  readonly leaderboardId: string;
+  readonly participantId?: string;
+  readonly limit?: number;
+  readonly cursor?: string;
+}
+export interface VerifiedLeaderboardSnapshot {
+  readonly definition: VerifiedLeaderboardDefinition;
+  readonly entries: readonly LeaderboardRankedEntry[];
+  readonly participantEntry?: LeaderboardRankedEntry;
+  readonly totalParticipants: number;
+  readonly generatedAt: string;
+  readonly nextCursor?: string;
+}
+export interface VerifiedLeaderboardCursorPosition {
+  readonly score: number;
+  readonly completedAtMs: number;
+  readonly attemptId: string;
+}
+export declare class VerifiedLeaderboardCursorError extends Error {
+  readonly name = "VerifiedLeaderboardCursorError";
+}
+/**
+* Safe to expose through a game-facing read transport after the caller supplies
+* any required authentication and participant scoping.
+*/
+export interface VerifiedLeaderboardReader {
+  getSnapshot(input: GetVerifiedLeaderboardSnapshotRequest): Promise<VerifiedLeaderboardSnapshot | undefined>;
+}
+/**
+* Server-only write boundary. Call this only after an authoritative attempt
+* coordinator has verified the completion. Never expose it as a client score
+* submission endpoint.
+*/
+export interface TrustedLeaderboardRecorder {
+  recordVerifiedAttempt(input: RecordVerifiedLeaderboardAttemptRequest): Promise<RecordVerifiedLeaderboardAttemptResponse>;
+}
+export interface VerifiedLeaderboardService extends VerifiedLeaderboardReader, TrustedLeaderboardRecorder {
+}
+export interface CreateInMemoryVerifiedLeaderboardServiceInput {
+  readonly now?: () => string;
+}
+export declare function createInMemoryVerifiedLeaderboardService(input?: CreateInMemoryVerifiedLeaderboardServiceInput): VerifiedLeaderboardService;
+/**
+* Process-local reference adapter for tests and development. It keeps every
+* definition and processed attempt for its full lifetime and fully sorts the
+* retained attempts for each write and read. Use a durable adapter with
+* eviction and an indexed ranking strategy for long-lived or large boards.
+*/
+export declare class InMemoryVerifiedLeaderboardService implements VerifiedLeaderboardService {
+  private readonly now;
+  private readonly definitions;
+  private readonly attemptsById;
+  private readonly retainedByLeaderboard;
+  constructor(now?: () => string);
+  recordVerifiedAttempt(input: RecordVerifiedLeaderboardAttemptRequest): Promise<RecordVerifiedLeaderboardAttemptResponse>;
+  getSnapshot(input: GetVerifiedLeaderboardSnapshotRequest): Promise<VerifiedLeaderboardSnapshot | undefined>;
+  private createRecordResponse;
+  private ensureDefinition;
+  private getRetainedAttempts;
+  private createRankedEntries;
+}
+export declare function assertVerifiedLeaderboardDefinition(input: unknown): asserts input is VerifiedLeaderboardDefinition;
+export declare function assertLeaderboardVerificationEvidence(input: unknown): asserts input is LeaderboardVerificationEvidence;
+export declare function assertVerifiedLeaderboardAttempt(input: unknown): asserts input is VerifiedLeaderboardAttempt;
+export declare function assertRecordVerifiedLeaderboardAttemptRequest(input: unknown): asserts input is RecordVerifiedLeaderboardAttemptRequest;
+export declare function assertRecordVerifiedLeaderboardAttemptResponse(input: unknown): asserts input is RecordVerifiedLeaderboardAttemptResponse;
+export declare function assertGetVerifiedLeaderboardSnapshotRequest(input: unknown): asserts input is GetVerifiedLeaderboardSnapshotRequest;
+export declare function assertLeaderboardRankedEntry(input: unknown): asserts input is LeaderboardRankedEntry;
+export declare function assertVerifiedLeaderboardSnapshot(input: unknown): asserts input is VerifiedLeaderboardSnapshot;
+export declare function createVerifiedLeaderboardCursor(definition: VerifiedLeaderboardDefinition, entry: LeaderboardRankedEntry): string;
+export declare function parseVerifiedLeaderboardCursor(cursor: string, definition: VerifiedLeaderboardDefinition): VerifiedLeaderboardCursorPosition;