@mpgd/adapter-capacitor 0.4.12 → 0.6.0

package/dist/index.js

@@ -1,14 +1,121 @@
-import { decodeBridgeStorageLoadData, } from '@mpgd/bridge';
+import { decodeBridgeCredentialLoadData, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
 import { CapacitorGameServices } from '@mpgd/capacitor-game-services';
 import { PlatformOperationError, } from '@mpgd/platform';
+import { createCapacitorAppEvents, } from './app-events.js';
+import { assertProviderResponseData, createCapacitorProviderRegistry, } from './providers.js';
+import { createCapacitorViewport } from './viewport.js';
+export { createCapacitorProviderRegistry, } from './providers.js';
+export { createCapacitorAppEvents, } from './app-events.js';
+export { CapacitorNativeHttpError, createCapacitorNativeJsonTransport, } from './native-http.js';
+export { createCapacitorViewport, } from './viewport.js';
+const externalActivityMethods = new Set([
+    'commerce.purchase',
+    'ads.showRewarded',
+    'ads.showInterstitial',
+    'identity.requestUpgrade',
+    'notifications.requestSubscription',
+]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+const safeFallbackMethods = new Set([
+    'identity.getPlayer',
+    'identity.getSession',
+    'notifications.getStatus',
+]);
+const credentialKeyPattern = /^[A-Za-z0-9._:-]{1,128}$/u;
+const maximumCredentialBytes = 16 * 1024;
+function assertCredentialKey(key) {
+    if (typeof key !== 'string' || !credentialKeyPattern.test(key)) {
+        throw new PlatformOperationError({ code: 'NATIVE_CREDENTIAL_INVALID_KEY' });
+    }
+}
+function assertCredentialValue(value) {
+    if (typeof value !== 'string' || value.length === 0
+        || new TextEncoder().encode(value).byteLength > maximumCredentialBytes) {
+        throw new PlatformOperationError({ code: 'NATIVE_CREDENTIAL_INVALID_VALUE' });
+    }
+}
+function assertCredentialMutationResponse(input, field) {
+    if (!isRecord(input) || input[field] !== true) {
+        throw new PlatformOperationError({ code: 'NATIVE_CREDENTIAL_INVALID_RESPONSE' });
+    }
+}
 export function createCapacitorPlatformGateway(input) {
     const bridge = input.bridge ?? CapacitorGameServices;
-    async function request(method, payload) {
+    const providers = createCapacitorProviderRegistry(input.providers ?? []);
+    const lifecycle = createCapacitorAppEvents({
+        target: input.target,
+        ...(input.app === undefined ? {} : { app: input.app }),
+        ...(input.visibility === undefined ? {} : { visibility: input.visibility }),
+        ...(input.classifyIncomingUrl === undefined
+            ? {}
+            : { classifyIncomingUrl: input.classifyIncomingUrl }),
+        ...(input.historyBack === undefined ? {} : { historyBack: input.historyBack }),
+        ...(input.onAppEventError === undefined ? {} : { onError: input.onAppEventError }),
+    });
+    const viewport = input.viewport ?? createCapacitorViewport({
+        ...(input.onAppEventError === undefined ? {} : { onError: input.onAppEventError }),
+    });
+    const gatewayLifecycle = {
+        ...lifecycle,
+        async dispose() {
+            try {
+                await lifecycle.dispose?.();
+            }
+            finally {
+                if (input.viewport === undefined) {
+                    viewport.dispose?.();
+                }
+            }
+        },
+    };
+    async function request(method, payload, leaderboardRoute) {
+        const releaseExternalActivity = externalActivityMethods.has(method)
+            ? lifecycle.beginExternalActivity?.()
+            : undefined;
+        try {
+            const provider = leaderboardRoute === 'remote'
+                && (method === 'leaderboard.submitScore' || method === 'leaderboard.open')
+                ? undefined
+                : providers.byMethod.get(method);
+            if (provider !== undefined) {
+                let productType;
+                if (method === 'commerce.purchase'
+                    && provider.features.includes('nativeIap')
+                    && provider.features.includes('subscriptionIap')) {
+                    // The caller supplies only an ID. Resolve its provider-owned type before
+                    // selecting a store route; a forged or unknown ID must not bypass it.
+                    const products = await request('commerce.getProducts', {});
+                    const productId = isRecord(payload) ? payload.productId : undefined;
+                    const matches = products.filter((product) => product.id === productId);
+                    if (matches.length !== 1) {
+                        throw new PlatformOperationError({ code: 'NATIVE_PROVIDER_PRODUCT_UNKNOWN' });
+                    }
+                    productType = matches[0]?.type;
+                }
+                try {
+                    await providers.assertMethodReady(method, payload, productType);
+                    return await sendRequest(method, payload, provider);
+                }
+                catch (error) {
+                    // Only non-mutating guest/status queries may degrade. A stale readiness
+                    // snapshot, SDK rejection, or malformed provider response is no safer
+                    // than initialization failure for these queries.
+                    if (!safeFallbackMethods.has(method)) {
+                        throw error;
+                    }
+                }
+            }
+            return await sendRequest(method, payload, undefined);
+        }
+        finally {
+            releaseExternalActivity?.();
+        }
+    }
+    async function sendRequest(method, payload, provider) {
         const id = crypto.randomUUID();
-        const response = await bridge.request({
+        const response = await (provider?.bridge ?? bridge).request({
             id,
             method,
             payload,
@@ -32,6 +139,9 @@ export function createCapacitorPlatformGateway(input) {
                     message: `Native bridge omitted response data for ${method}.`,
                 });
             }
+            if (provider !== undefined) {
+                assertProviderResponseData(method, response.data);
+            }
             return response.data;
         }
         if (!isRecord(response.error)
@@ -48,7 +158,22 @@ export function createCapacitorPlatformGateway(input) {
     return {
         target: input.target,
         async getCapabilities() {
-            return { ...await request('runtime.getCapabilities', {}) };
+            const base = await request('runtime.getCapabilities', {});
+            const states = await providers.getAvailability();
+            const rewardedAds = states.rewardedAds === 'available';
+            const interstitialAds = states.interstitialAds === 'available';
+            const bannerAds = states.bannerAds === 'available';
+            return {
+                ...base,
+                nativeIap: states.nativeIap === 'available',
+                subscriptionIap: states.subscriptionIap === 'available',
+                nativeAds: rewardedAds || interstitialAds || bannerAds,
+                rewardedAds,
+                interstitialAds,
+                bannerAds,
+                nativeLeaderboard: states.nativeLeaderboard === 'available',
+                providerAvailability: states,
+            };
         },
         identity: {
             getPlayer: () => request('identity.getPlayer', {}),
@@ -77,24 +202,48 @@ export function createCapacitorPlatformGateway(input) {
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
             showInterstitial: (payload) => request('ads.showInterstitial', payload),
+            mountBanner: (payload) => request('ads.mountBanner', payload),
+            unmountBanner: (payload) => request('ads.unmountBanner', payload),
         },
         leaderboard: {
-            submitScore: (payload) => request('leaderboard.submitScore', payload),
-            open: (payload) => request('leaderboard.open', payload ?? {}),
-        },
-        lifecycle: {
-            onPause() {
-                return () => { };
-            },
-            onResume() {
-                return () => { };
+            submitScore: ({ route, ...payload }) => request('leaderboard.submitScore', payload, route),
+            open: (input) => {
+                const { route, ...payload } = input ?? {};
+                return request('leaderboard.open', payload, route);
             },
         },
+        lifecycle: gatewayLifecycle,
+        viewport,
         storage: {
             async load(payload) {
                 return decodeBridgeStorageLoadData(await request('storage.load', payload));
             },
             save: (payload) => request('storage.save', payload),
         },
+        secureCredentials: {
+            async load({ key }) {
+                assertCredentialKey(key);
+                const data = await request('credentials.load', { key });
+                try {
+                    const value = decodeBridgeCredentialLoadData(data);
+                    if (value !== null) {
+                        assertCredentialValue(value);
+                    }
+                    return value;
+                }
+                catch {
+                    throw new PlatformOperationError({ code: 'NATIVE_CREDENTIAL_INVALID_RESPONSE' });
+                }
+            },
+            async save({ key, value }) {
+                assertCredentialKey(key);
+                assertCredentialValue(value);
+                assertCredentialMutationResponse(await request('credentials.save', { key, value }), 'saved');
+            },
+            async remove({ key }) {
+                assertCredentialKey(key);
+                assertCredentialMutationResponse(await request('credentials.remove', { key }), 'removed');
+            },
+        },
     };
 }

package/dist/native-http.d.ts

@@ -0,0 +1,50 @@
+import { CapacitorHttp } from '@capacitor/core';
+export type CapacitorNativeHttpErrorCode = 'NATIVE_HTTP_CONFIGURATION' | 'NATIVE_HTTP_UNSUPPORTED' | 'NATIVE_HTTP_INVALID_REQUEST' | 'NATIVE_HTTP_REQUEST_TOO_LARGE' | 'NATIVE_HTTP_RESPONSE_TOO_LARGE' | 'NATIVE_HTTP_INVALID_RESPONSE' | 'NATIVE_HTTP_INVALID_JSON' | 'NATIVE_HTTP_REDIRECT_BLOCKED' | 'NATIVE_HTTP_CROSS_ORIGIN' | 'NATIVE_HTTP_TIMEOUT' | 'NATIVE_HTTP_ABORTED' | 'NATIVE_HTTP_FAILED';
+/** Deliberately omits URLs, headers, and native SDK exception details. */
+export declare class CapacitorNativeHttpError extends Error {
+  readonly code: CapacitorNativeHttpErrorCode;
+  constructor(code: CapacitorNativeHttpErrorCode);
+}
+export interface CapacitorJsonRequest {
+  readonly method: 'GET' | 'POST';
+  /** Relative API path beginning with one slash; a query string is allowed. */
+  readonly path: string;
+  readonly body?: unknown;
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Stops waiting in JS; it does not cancel an in-flight native request. */
+  readonly signal?: AbortSignal;
+}
+export interface CapacitorJsonResponse {
+  readonly status: number;
+  readonly body: unknown;
+}
+/**
+* A narrow JSON API that structurally satisfies GameServicesBackendTransport
+* without importing game-services or pretending to implement Fetch.
+*/
+export interface CapacitorNativeJsonTransport {
+  request(input: CapacitorJsonRequest): Promise<CapacitorJsonResponse>;
+  send(input: {
+    readonly method: 'POST';
+    readonly endpoint: string;
+    readonly body: unknown;
+    readonly headers?: Readonly<Record<string, string>>;
+  }): Promise<CapacitorJsonResponse>;
+}
+export interface CreateCapacitorNativeJsonTransportInput {
+  readonly target: 'android' | 'ios';
+  readonly baseUrl: string;
+  /** Exact HTTPS origin of the API; initial requests never use another origin. */
+  readonly allowedOrigin: string;
+  readonly connectTimeoutMs?: number;
+  readonly readTimeoutMs?: number;
+  readonly overallTimeoutMs?: number;
+  readonly maxRequestBytes?: number;
+  /** Checked after the native bridge has already returned data to JS. */
+  readonly maxResponseBytes?: number;
+  /** Inject only for tests or a host-owned native Http implementation. */
+  readonly http?: Pick<typeof CapacitorHttp, 'request'>;
+  /** Inject only for deterministic tests. */
+  readonly getPlatform?: () => string;
+}
+export declare function createCapacitorNativeJsonTransport(input: CreateCapacitorNativeJsonTransportInput): CapacitorNativeJsonTransport;

package/dist/native-http.js

@@ -0,0 +1,259 @@
+import { Capacitor, CapacitorHttp } from '@capacitor/core';
+/** Deliberately omits URLs, headers, and native SDK exception details. */
+export class CapacitorNativeHttpError extends Error {
+    code;
+    constructor(code) {
+        super(`Capacitor native JSON request failed: ${code}.`);
+        this.name = 'CapacitorNativeHttpError';
+        this.code = code;
+    }
+}
+const defaultMaxRequestBytes = 256 * 1024;
+const defaultMaxResponseBytes = 1024 * 1024;
+const defaultConnectTimeoutMs = 10_000;
+const defaultReadTimeoutMs = 15_000;
+const defaultOverallTimeoutMs = 25_000;
+const headerNamePattern = /^[!#$%&'*+.^_`|~0-9a-z-]+$/u;
+export function createCapacitorNativeJsonTransport(input) {
+    const base = parseHttpsUrl(input.baseUrl);
+    const allowedOrigin = parseHttpsUrl(input.allowedOrigin);
+    if (allowedOrigin.href !== `${allowedOrigin.origin}/` || allowedOrigin.origin !== base.origin
+        || base.username !== '' || base.password !== ''
+        || base.search !== '' || base.hash !== '') {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_CONFIGURATION');
+    }
+    const basePath = base.pathname.replace(/\/+$/u, '');
+    const maxRequestBytes = positiveInteger(input.maxRequestBytes, defaultMaxRequestBytes);
+    const maxResponseBytes = positiveInteger(input.maxResponseBytes, defaultMaxResponseBytes);
+    const connectTimeoutMs = positiveInteger(input.connectTimeoutMs, defaultConnectTimeoutMs);
+    const readTimeoutMs = positiveInteger(input.readTimeoutMs, defaultReadTimeoutMs);
+    const overallTimeoutMs = positiveInteger(input.overallTimeoutMs, defaultOverallTimeoutMs);
+    const http = input.http ?? CapacitorHttp;
+    const getPlatform = input.getPlatform ?? (() => Capacitor.getPlatform());
+    const encoder = new TextEncoder();
+    async function request(inputRequest) {
+        if (getPlatform() !== input.target) {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_UNSUPPORTED');
+        }
+        if (inputRequest.signal?.aborted === true) {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_ABORTED');
+        }
+        const url = resolvePath(inputRequest.path, base, basePath);
+        const headers = normalizeHeaders(inputRequest.headers);
+        let data;
+        let serializedData;
+        if (inputRequest.method === 'GET') {
+            if (inputRequest.body !== undefined) {
+                throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+            }
+        }
+        else if (inputRequest.method === 'POST') {
+            try {
+                assertJsonValue(inputRequest.body, new WeakSet(), 0);
+                serializedData = JSON.stringify(inputRequest.body);
+            }
+            catch {
+                throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+            }
+            if (serializedData === undefined) {
+                throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+            }
+            if (encoder.encode(serializedData).byteLength > maxRequestBytes) {
+                throw new CapacitorNativeHttpError('NATIVE_HTTP_REQUEST_TOO_LARGE');
+            }
+            // Native serializers must receive a JSON value, never its serialized
+            // string. Parse the size-checked snapshot so caller mutation cannot
+            // change the native request after validation.
+            data = JSON.parse(serializedData);
+            headers['content-type'] = 'application/json';
+        }
+        else {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+        }
+        headers.accept = 'application/json';
+        const options = {
+            url: url.href,
+            method: inputRequest.method,
+            headers,
+            responseType: 'json',
+            disableRedirects: true,
+            connectTimeout: connectTimeoutMs,
+            readTimeout: readTimeoutMs,
+            ...(inputRequest.method === 'POST' ? { data } : {}),
+        };
+        const response = await waitForNativeResponse(http, options, inputRequest.signal, overallTimeoutMs);
+        if (!isRecord(response) || !Number.isInteger(response.status)
+            || response.status < 100 || response.status > 599
+            || typeof response.url !== 'string') {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_RESPONSE');
+        }
+        if (response.status >= 300 && response.status < 400) {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_REDIRECT_BLOCKED');
+        }
+        let responseUrl;
+        try {
+            responseUrl = new URL(response.url);
+        }
+        catch {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_RESPONSE');
+        }
+        if (responseUrl.origin !== url.origin) {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_CROSS_ORIGIN');
+        }
+        if (responseUrl.username !== '' || responseUrl.password !== '' || responseUrl.hash !== ''
+            || normalizeNativePath(responseUrl.pathname) !== normalizeNativePath(url.pathname)
+            || new URLSearchParams(responseUrl.search).toString()
+                !== new URLSearchParams(url.search).toString()) {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_REDIRECT_BLOCKED');
+        }
+        const raw = response.data;
+        let serialized;
+        try {
+            serialized = typeof raw === 'string' ? raw : JSON.stringify(raw);
+        }
+        catch {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_JSON');
+        }
+        if (encoder.encode(serialized ?? '').byteLength > maxResponseBytes) {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_RESPONSE_TOO_LARGE');
+        }
+        if (raw === null || raw === undefined || (typeof raw === 'string' && raw.trim() === '')) {
+            return { status: response.status, body: null };
+        }
+        let body;
+        try {
+            body = typeof raw === 'string' ? JSON.parse(raw) : raw;
+            assertJsonValue(body, new WeakSet(), 0);
+        }
+        catch {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_JSON');
+        }
+        return { status: response.status, body };
+    }
+    return {
+        request,
+        send(inputRequest) {
+            return request({
+                method: 'POST',
+                path: inputRequest.endpoint,
+                body: inputRequest.body,
+                ...(inputRequest.headers === undefined ? {} : { headers: inputRequest.headers }),
+            });
+        },
+    };
+}
+function parseHttpsUrl(value) {
+    try {
+        const parsed = new URL(value);
+        if (parsed.protocol === 'https:' && parsed.username === '' && parsed.password === '') {
+            return parsed;
+        }
+    }
+    catch {
+        // Normalized to a stable, non-sensitive code below.
+    }
+    throw new CapacitorNativeHttpError('NATIVE_HTTP_CONFIGURATION');
+}
+function positiveInteger(value, fallback) {
+    const selected = value ?? fallback;
+    if (!Number.isSafeInteger(selected) || selected <= 0) {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_CONFIGURATION');
+    }
+    return selected;
+}
+function resolvePath(path, base, basePath) {
+    if (!path.startsWith('/') || path.startsWith('//') || path.includes('\\') || path.includes('#')) {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+    }
+    let resolved;
+    try {
+        resolved = new URL(`${base.origin}${basePath}${path}`);
+    }
+    catch {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+    }
+    if (resolved.origin !== base.origin
+        || (basePath !== '' && !resolved.pathname.startsWith(`${basePath}/`))) {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_CROSS_ORIGIN');
+    }
+    return resolved;
+}
+/** Native URL stacks may decode harmless path escapes while preserving the route. */
+function normalizeNativePath(path) {
+    return path.replace(/%([0-9a-f]{2})/giu, (_match, hex) => {
+        const character = String.fromCharCode(Number.parseInt(hex, 16));
+        return /^[A-Za-z0-9._~,*-]$/u.test(character) ? character : `%${hex.toUpperCase()}`;
+    });
+}
+function normalizeHeaders(input) {
+    const headers = {};
+    for (const [rawName, value] of Object.entries(input ?? {})) {
+        const name = rawName.toLowerCase();
+        if (!headerNamePattern.test(name) || typeof value !== 'string'
+            || /[\r\n]/u.test(value) || name === 'host' || name === 'content-length'
+            || name === 'accept' || name === 'content-type') {
+            throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+        }
+        headers[name] = value;
+    }
+    return headers;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertJsonValue(value, seen, depth) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean'
+        || (typeof value === 'number' && Number.isFinite(value))) {
+        return;
+    }
+    if (typeof value !== 'object' || depth >= 32 || seen.has(value)) {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+    }
+    if (Reflect.ownKeys(value).some((key) => typeof key === 'symbol')) {
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_INVALID_REQUEST');
+    }
+    seen.add(value);
+    for (const entry of Array.isArray(value) ? value : Object.values(value)) {
+        assertJsonValue(entry, seen, depth + 1);
+    }
+    seen.delete(value);
+}
+async function waitForNativeResponse(http, options, signal, timeoutMs) {
+    let timer;
+    let onAbort;
+    const pending = Promise.resolve().then(() => http.request(options));
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new CapacitorNativeHttpError('NATIVE_HTTP_TIMEOUT')), timeoutMs);
+    });
+    const abort = new Promise((_resolve, reject) => {
+        if (signal === undefined) {
+            return;
+        }
+        onAbort = () => reject(new CapacitorNativeHttpError('NATIVE_HTTP_ABORTED'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+        }
+    });
+    try {
+        return await Promise.race([pending, timeout, abort]);
+    }
+    catch (error) {
+        if (error instanceof CapacitorNativeHttpError) {
+            throw error;
+        }
+        throw new CapacitorNativeHttpError('NATIVE_HTTP_FAILED');
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        if (signal !== undefined && onAbort !== undefined) {
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+}

package/dist/providers.d.ts

@@ -0,0 +1,25 @@
+import type { BridgeMethod, BridgeRequest, BridgeResponse } from '@mpgd/bridge';
+import { type PlatformProviderAvailability, type PlatformProviderFeature, type ProductType } from '@mpgd/platform';
+export interface NativeBridge {
+  request(input: BridgeRequest): Promise<BridgeResponse>;
+}
+/**
+* An optional, separately installed provider handles only its declared bridge
+* methods. The base game-services plugin remains responsible for local storage.
+* A provider may be backed by a native plugin or by a server-backed adapter;
+* neither dependency is imported by the base Capacitor adapter.
+*/
+export interface CapacitorServiceProvider {
+  readonly id: string;
+  readonly bridge: NativeBridge;
+  readonly features: readonly PlatformProviderFeature[];
+  readonly methods: readonly BridgeMethod[];
+  getAvailability(): Promise<Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>>;
+}
+export interface CapacitorProviderRegistry {
+  readonly byMethod: ReadonlyMap<BridgeMethod, CapacitorServiceProvider>;
+  assertMethodReady(method: BridgeMethod, payload?: unknown, productType?: ProductType): Promise<void>;
+  getAvailability(): Promise<Readonly<Record<PlatformProviderFeature, PlatformProviderAvailability>>>;
+}
+export declare function createCapacitorProviderRegistry(input: readonly CapacitorServiceProvider[]): CapacitorProviderRegistry;
+export declare function assertProviderResponseData(method: BridgeMethod, data: unknown): void;