@mpgd/game-services 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -2,5 +2,8 @@ export * from './client';
 export * from './contract';
 export * from './notification-delivery';
 export * from './progress-link';
+export * from './runtime.js';
 export * from './server';
 export * from './types';
+export * from './verified-leaderboard';
+export * from './verified-leaderboard-transport';

package/dist/index.js

@@ -2,5 +2,8 @@ export * from './client';
 export * from './contract';
 export * from './notification-delivery';
 export * from './progress-link';
+export * from './runtime.js';
 export * from './server';
 export * from './types';
+export * from './verified-leaderboard';
+export * from './verified-leaderboard-transport';

package/dist/runtime.d.ts

@@ -0,0 +1,31 @@
+import type { AnalyticsSink } from '@mpgd/analytics';
+import type { PlatformGateway, PlatformTarget } from '@mpgd/platform';
+import { type GameServicesBackendApi, type GameServicesClient } from './client.js';
+import type { GameServicesLedgerTarget } from './types.js';
+export type GameServicesAuthorityMode = 'production' | 'non-production';
+export type GameServicesRuntimeMode = 'disabled' | 'local' | 'http' | 'orpc';
+export type GameServicesDisabledReason = 'unsupported_target' | 'missing_authoritative_backend' | 'invalid_authoritative_backend' | 'local_backend_not_allowed' | 'local_backend_unavailable';
+export interface GameServicesRuntime {
+  readonly mode: GameServicesRuntimeMode;
+  readonly reason?: GameServicesDisabledReason;
+  readonly baseUrl?: string;
+  readonly target?: GameServicesLedgerTarget;
+  readonly client?: GameServicesClient;
+}
+export interface CreateGameServicesRuntimeInput {
+  readonly gateway: PlatformGateway;
+  readonly playerId: string;
+  readonly authorityMode: GameServicesAuthorityMode;
+  readonly target?: PlatformTarget | string;
+  readonly baseUrl?: string;
+  readonly transport?: 'http' | 'orpc';
+  readonly allowLocalBackend?: boolean;
+  readonly localBackend?: GameServicesBackendApi;
+  readonly analytics?: AnalyticsSink;
+  readonly analyticsSessionId?: string;
+  readonly now?: () => string;
+}
+export declare function createGameServicesRuntime(input: CreateGameServicesRuntimeInput): GameServicesRuntime;
+export declare function resolveGameServicesLedgerTarget(target: PlatformTarget | string): GameServicesLedgerTarget | null;
+export declare function resolveGameServicesAuthorityMode(profile: string): GameServicesAuthorityMode;
+export declare function resolveGameServicesTransport(transport: string | undefined): 'http' | 'orpc';

package/dist/runtime.js

@@ -0,0 +1,198 @@
+import { createGameServicesClient, createGameServicesFetchBackendTransport, createGameServicesHttpBackendApi, createGameServicesOrpcBackendApi, createGameServicesOrpcClient, } from './client.js';
+export function createGameServicesRuntime(input) {
+    assertAuthorityMode(input.authorityMode);
+    assertTransport(input.transport);
+    const target = resolveGameServicesLedgerTarget(input.target ?? input.gateway.target);
+    if (target === null) {
+        return disabledRuntime('unsupported_target');
+    }
+    const baseUrl = normalizeBaseUrl(input.baseUrl);
+    let backend;
+    let mode;
+    if (baseUrl !== undefined) {
+        const url = parseAbsoluteUrl(baseUrl);
+        if (input.authorityMode === 'production' && !isPublicHttpsUrl(url)) {
+            return disabledRuntime('invalid_authoritative_backend', target);
+        }
+        if (url === undefined) {
+            throw new Error('Game Services baseUrl must be a valid absolute URL.');
+        }
+        mode = input.transport === 'orpc' ? 'orpc' : 'http';
+        backend = mode === 'orpc'
+            ? createGameServicesOrpcBackendApi(createGameServicesOrpcClient({ url: baseUrl }))
+            : createGameServicesHttpBackendApi({
+                transport: createGameServicesFetchBackendTransport({ baseUrl }),
+            });
+    }
+    else {
+        if (input.authorityMode === 'production') {
+            return disabledRuntime('missing_authoritative_backend', target);
+        }
+        if (input.allowLocalBackend !== true) {
+            return disabledRuntime('local_backend_not_allowed', target);
+        }
+        if (input.localBackend === undefined) {
+            return disabledRuntime('local_backend_unavailable', target);
+        }
+        mode = 'local';
+        backend = input.localBackend;
+    }
+    return {
+        mode,
+        ...(baseUrl === undefined ? {} : { baseUrl }),
+        target,
+        client: createGameServicesClient({
+            gateway: input.gateway,
+            backend,
+            playerId: input.playerId,
+            target,
+            ...(input.analytics === undefined ? {} : { analytics: input.analytics }),
+            ...(input.analyticsSessionId === undefined
+                ? {}
+                : { analyticsSessionId: input.analyticsSessionId }),
+            ...(input.now === undefined ? {} : { now: input.now }),
+        }),
+    };
+}
+export function resolveGameServicesLedgerTarget(target) {
+    if (target === 'browser'
+        || target === 'android'
+        || target === 'ios'
+        || target === 'ait'
+        || target === 'reddit') {
+        return target;
+    }
+    return null;
+}
+export function resolveGameServicesAuthorityMode(profile) {
+    if (profile.length === 0 || profile.trim() !== profile) {
+        throw new Error('Game Services profile must be non-empty without surrounding whitespace.');
+    }
+    return profile === 'production' ? 'production' : 'non-production';
+}
+export function resolveGameServicesTransport(transport) {
+    if (transport === undefined || transport.length === 0 || transport === 'http') {
+        return 'http';
+    }
+    if (transport === 'orpc') {
+        return 'orpc';
+    }
+    throw new Error('Game Services transport must be http or orpc.');
+}
+function disabledRuntime(reason, target) {
+    return {
+        mode: 'disabled',
+        reason,
+        ...(target === undefined ? {} : { target }),
+    };
+}
+function normalizeBaseUrl(baseUrl) {
+    const normalized = baseUrl?.trim();
+    return normalized === undefined || normalized.length === 0 ? undefined : normalized;
+}
+function isPublicHttpsUrl(url) {
+    return url !== undefined
+        && url.protocol === 'https:'
+        && url.username.length === 0
+        && url.password.length === 0
+        && !isNonPublicHostname(url.hostname);
+}
+function parseAbsoluteUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isNonPublicHostname(hostname) {
+    const normalized = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/u, '');
+    if (normalized === 'localhost'
+        || normalized.endsWith('.localhost')
+        || normalized.endsWith('.local')) {
+        return true;
+    }
+    if (/^(?:\d{1,3}\.){3}\d{1,3}$/u.test(normalized)) {
+        return isNonPublicIpv4(normalized);
+    }
+    return normalized.includes(':') && isNonPublicIpv6(normalized);
+}
+function isNonPublicIpv4(address) {
+    const [first = 0, second = 0, third = 0] = address.split('.').map(Number);
+    return first === 0
+        || first === 10
+        || first === 127
+        || (first === 100 && second >= 64 && second <= 127)
+        || (first === 169 && second === 254)
+        || (first === 172 && second >= 16 && second <= 31)
+        || (first === 192 && second === 0 && third === 0)
+        || (first === 192 && second === 0 && third === 2)
+        || (first === 192 && second === 168)
+        || (first === 198 && (second === 18 || second === 19))
+        || (first === 198 && second === 51 && third === 100)
+        || (first === 203 && second === 0 && third === 113)
+        || first >= 224;
+}
+function isNonPublicIpv6(address) {
+    const words = expandIpv6(address);
+    if (words === undefined) {
+        return true;
+    }
+    if (words.slice(0, 7).every((word) => word === 0)) {
+        return true;
+    }
+    if (words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff) {
+        return isNonPublicIpv4(wordsToIpv4(words));
+    }
+    if (words.slice(0, 6).every((word) => word === 0)) {
+        return isNonPublicIpv4(wordsToIpv4(words));
+    }
+    const first = words[0] ?? 0;
+    return (first & 0xfe00) === 0xfc00
+        || (first & 0xffc0) === 0xfe80
+        || (first & 0xff00) === 0xff00
+        || (first === 0x2001 && words[1] === 0x0db8);
+}
+function wordsToIpv4(words) {
+    return `${(words[6] ?? 0) >> 8}.${(words[6] ?? 0) & 0xff}.`
+        + `${(words[7] ?? 0) >> 8}.${(words[7] ?? 0) & 0xff}`;
+}
+function expandIpv6(address) {
+    const sections = address.split('::');
+    if (sections.length > 2) {
+        return undefined;
+    }
+    const head = ipv6Words(sections[0] ?? '');
+    const tail = ipv6Words(sections[1] ?? '');
+    if (head === undefined || tail === undefined) {
+        return undefined;
+    }
+    const omitted = 8 - head.length - tail.length;
+    if ((sections.length === 1 && omitted !== 0) || (sections.length === 2 && omitted < 1)) {
+        return undefined;
+    }
+    return [...head, ...Array.from({ length: omitted }, () => 0), ...tail];
+}
+function ipv6Words(section) {
+    if (section.length === 0) {
+        return [];
+    }
+    const words = [];
+    for (const segment of section.split(':')) {
+        if (!/^[0-9a-f]{1,4}$/u.test(segment)) {
+            return undefined;
+        }
+        words.push(Number.parseInt(segment, 16));
+    }
+    return words;
+}
+function assertAuthorityMode(authorityMode) {
+    if (authorityMode !== 'production' && authorityMode !== 'non-production') {
+        throw new Error('authorityMode must be production or non-production.');
+    }
+}
+function assertTransport(transport) {
+    if (transport !== undefined && transport !== 'http' && transport !== 'orpc') {
+        throw new Error('Game Services transport must be http or orpc.');
+    }
+}

package/dist/verified-leaderboard-conformance.d.ts

@@ -0,0 +1,29 @@
+import { type VerifiedLeaderboardService } from './verified-leaderboard';
+export declare const verifiedLeaderboardConformanceScenarios: readonly ['first-selection-and-snapshot', 'best-selection-and-retry', 'deterministic-ties', 'identity-and-definition-conflicts', 'concurrent-idempotency', 'mutation-isolation', 'runtime-validation'];
+export type VerifiedLeaderboardConformanceScenario = (typeof verifiedLeaderboardConformanceScenarios)[number];
+export interface CreateVerifiedLeaderboardConformanceFixtureInput {
+  readonly scenario: VerifiedLeaderboardConformanceScenario;
+  readonly now: string;
+}
+export interface VerifiedLeaderboardConformanceFixture {
+  readonly service: VerifiedLeaderboardService;
+  readonly dispose?: () => Promise<void> | void;
+}
+export type CreateVerifiedLeaderboardConformanceFixture = (input: CreateVerifiedLeaderboardConformanceFixtureInput) => Promise<VerifiedLeaderboardConformanceFixture> | VerifiedLeaderboardConformanceFixture;
+export interface RunVerifiedLeaderboardConformanceInput {
+  /**
+  * Return an isolated provider fixture for each scenario. Durable adapters may
+  * instead namespace every fixture in a shared test database.
+  */
+  readonly createFixture: CreateVerifiedLeaderboardConformanceFixture;
+  readonly now?: string;
+}
+export interface VerifiedLeaderboardConformanceReport {
+  readonly passedScenarios: readonly VerifiedLeaderboardConformanceScenario[];
+}
+/**
+* Runs the provider-neutral verified leaderboard contract against an adapter.
+* The helper is test-framework independent and throws with the failed scenario
+* name when a provider diverges from the public service semantics.
+*/
+export declare function runVerifiedLeaderboardConformance(input: RunVerifiedLeaderboardConformanceInput): Promise<VerifiedLeaderboardConformanceReport>;