@mpgd/adapter-capacitor 0.4.11 → 0.5.0

package/dist/providers.js

@@ -0,0 +1,309 @@
+import { PlatformOperationError, } from '@mpgd/platform';
+const featureMethods = {
+    nativeIap: [
+        'commerce.getProducts',
+        'commerce.purchase',
+        'commerce.restore',
+        'commerce.getEntitlements',
+    ],
+    subscriptionIap: [
+        'commerce.getProducts',
+        'commerce.purchase',
+        'commerce.restore',
+        'commerce.getEntitlements',
+    ],
+    rewardedAds: ['ads.preload', 'ads.showRewarded'],
+    interstitialAds: ['ads.preload', 'ads.showInterstitial'],
+    bannerAds: ['ads.mountBanner', 'ads.unmountBanner'],
+    nativeLeaderboard: ['leaderboard.submitScore', 'leaderboard.open'],
+    identityUpgrade: ['identity.getPlayer', 'identity.getSession', 'identity.requestUpgrade'],
+    pushNotifications: ['notifications.getStatus', 'notifications.requestSubscription'],
+};
+const providerFeatures = Object.keys(featureMethods);
+const providerMethodSet = new Set(Object.values(featureMethods).flat());
+const availabilitySet = new Set([
+    'unsupported',
+    'configuration-required',
+    'action-required',
+    'temporarily-unavailable',
+    'available',
+]);
+const availabilityTimeoutMs = 3_000;
+export function createCapacitorProviderRegistry(input) {
+    const providers = input.map((provider) => ({
+        ...provider,
+        methods: [...provider.methods],
+        features: [...provider.features],
+        getAvailability: () => provider.getAvailability(),
+    }));
+    const byMethod = new Map();
+    const byFeature = new Map();
+    const ids = new Set();
+    for (const provider of providers) {
+        if (provider.id.trim() === '' || ids.has(provider.id)) {
+            throw new Error(`Capacitor provider ID is empty or registered twice: ${provider.id}`);
+        }
+        ids.add(provider.id);
+        if (provider.features.length === 0 || provider.methods.length === 0) {
+            throw new Error(`Capacitor provider ${provider.id} must declare features and methods.`);
+        }
+        const methods = new Set(provider.methods);
+        if (methods.size !== provider.methods.length) {
+            throw new Error(`Capacitor provider ${provider.id} repeats a bridge method.`);
+        }
+        for (const method of methods) {
+            if (!providerMethodSet.has(method)) {
+                throw new Error(`Capacitor provider ${provider.id} cannot replace base method ${method}.`);
+            }
+            if (byMethod.has(method)) {
+                throw new Error(`Capacitor bridge method ${method} has multiple providers.`);
+            }
+        }
+        for (const feature of provider.features) {
+            const required = featureMethods[feature];
+            if (required === undefined || byFeature.has(feature)) {
+                throw new Error(`Capacitor feature ${feature} has multiple or invalid providers.`);
+            }
+            if (required.some((method) => !methods.has(method))) {
+                throw new Error(`Capacitor provider ${provider.id} lacks methods for ${feature}.`);
+            }
+            byFeature.set(feature, provider);
+        }
+        if ([...methods].some((method) => !provider.features.some((feature) => featureMethods[feature].includes(method)))) {
+            throw new Error(`Capacitor provider ${provider.id} declares an unowned method.`);
+        }
+        for (const method of methods) {
+            byMethod.set(method, provider);
+        }
+    }
+    const readProviderStates = async (provider) => {
+        let reported;
+        let timer;
+        try {
+            reported = await Promise.race([
+                Promise.resolve().then(() => provider.getAvailability()),
+                new Promise((_resolve, reject) => {
+                    timer = setTimeout(() => reject(new Error('Provider availability timed out.')), availabilityTimeoutMs);
+                }),
+            ]);
+            if (!isRecord(reported)) {
+                throw new Error('Invalid provider availability.');
+            }
+        }
+        catch {
+            reported = {};
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        }
+        const states = {};
+        for (const feature of provider.features) {
+            const state = reported[feature];
+            states[feature] = availabilitySet.has(state)
+                ? state
+                : 'temporarily-unavailable';
+        }
+        return states;
+    };
+    const getAvailability = async () => {
+        const states = {};
+        for (const feature of providerFeatures) {
+            states[feature] = 'unsupported';
+        }
+        const snapshots = await Promise.all(providers.map(readProviderStates));
+        for (const snapshot of snapshots) {
+            Object.assign(states, snapshot);
+        }
+        return states;
+    };
+    return {
+        byMethod,
+        getAvailability,
+        async assertMethodReady(method, payload, productType) {
+            const provider = byMethod.get(method);
+            if (provider === undefined) {
+                return;
+            }
+            if (method === 'ads.unmountBanner') {
+                // Teardown must reach the provider that mounted the banner even after
+                // its serving state becomes unavailable.
+                return;
+            }
+            // An unrelated provider must not delay a purchase, ad, or identity call.
+            const states = await readProviderStates(provider);
+            let relevant = provider.features.filter((feature) => featureMethods[feature].includes(method));
+            if (method === 'commerce.purchase' && relevant.length > 1) {
+                relevant = relevant.filter((feature) => feature === (productType === 'subscription' ? 'subscriptionIap'
+                    : productType === 'consumable' || productType === 'non_consumable'
+                        ? 'nativeIap' : undefined));
+            }
+            const preloadFormat = method === 'ads.preload' && isRecord(payload)
+                ? payload.format
+                : undefined;
+            if (method === 'ads.preload' && preloadFormat !== undefined) {
+                const feature = preloadFormat === 'rewarded'
+                    ? 'rewardedAds'
+                    : preloadFormat === 'interstitial'
+                        ? 'interstitialAds'
+                        : undefined;
+                relevant = feature === undefined ? [] : relevant.filter((item) => item === feature);
+            }
+            if (relevant.length === 0) {
+                throw new PlatformOperationError({
+                    code: method === 'commerce.purchase'
+                        ? 'NATIVE_PROVIDER_PRODUCT_TYPE_REQUIRED'
+                        : 'NATIVE_PROVIDER_UNSUPPORTED',
+                });
+            }
+            const ready = (method === 'ads.preload' && preloadFormat === undefined)
+                || ((method === 'commerce.restore' || method === 'commerce.getEntitlements')
+                    && relevant.length > 1)
+                ? relevant.every((feature) => states[feature] === 'available')
+                : relevant.some((feature) => states[feature] === 'available');
+            if (ready) {
+                return;
+            }
+            // These methods exist to explain or resolve an action-required state.
+            if ((method === 'identity.getPlayer' || method === 'identity.getSession'
+                || method === 'identity.requestUpgrade'
+                || method === 'notifications.getStatus'
+                || method === 'notifications.requestSubscription')
+                && relevant.some((feature) => states[feature] === 'action-required')) {
+                return;
+            }
+            const state = relevant.map((feature) => states[feature] ?? 'temporarily-unavailable').find((value) => value !== 'unsupported' && value !== 'available') ?? 'unsupported';
+            const code = {
+                unsupported: 'NATIVE_PROVIDER_UNSUPPORTED',
+                'configuration-required': 'NATIVE_PROVIDER_CONFIGURATION_REQUIRED',
+                'action-required': 'NATIVE_PROVIDER_ACTION_REQUIRED',
+                'temporarily-unavailable': 'NATIVE_PROVIDER_TEMPORARILY_UNAVAILABLE',
+                available: 'NATIVE_PROVIDER_NOT_READY',
+            };
+            throw new PlatformOperationError({
+                code: code[state],
+                retryable: state === 'temporarily-unavailable',
+            });
+        },
+    };
+}
+export function assertProviderResponseData(method, data) {
+    const valid = isValidProviderData(method, data);
+    if (!valid) {
+        throw new PlatformOperationError({
+            code: 'NATIVE_PROVIDER_INVALID_RESPONSE',
+            message: `Capacitor provider returned invalid data for ${method}.`,
+        });
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isString);
+}
+function isVoidData(value) {
+    return value === undefined || value === null || (isRecord(value) && Object.keys(value).length === 0);
+}
+function isValidProviderData(method, value) {
+    switch (method) {
+        case 'commerce.getProducts':
+            return Array.isArray(value) && value.every((product) => isRecord(product)
+                && isString(product.id)
+                && ['consumable', 'non_consumable', 'subscription'].includes(product.type)
+                && isString(product.title)
+                && isString(product.description)
+                && isRecord(product.price)
+                && isString(product.price.formatted)
+                && isString(product.price.currencyCode));
+        case 'commerce.purchase':
+            return isRecord(value)
+                && ['completed', 'cancelled', 'pending', 'failed'].includes(value.status)
+                && isStringArray(value.entitlementIds)
+                && (value.transactionId === undefined || isString(value.transactionId))
+                && (value.authoritativeGrant === undefined || (value.status === 'completed'
+                    && isString(value.transactionId)
+                    && isRecord(value.authoritativeGrant)
+                    && isString(value.authoritativeGrant.ledgerEntryId)
+                    && value.authoritativeGrant.ledgerEntryId.length > 0
+                    && (value.authoritativeGrant.alreadyProcessed === undefined
+                        || typeof value.authoritativeGrant.alreadyProcessed === 'boolean')))
+                && (value.evidence === undefined || isEvidence(value.evidence));
+        case 'commerce.restore':
+            return isRecord(value)
+                && Array.isArray(value.restoredEntitlements)
+                && value.restoredEntitlements.every(isEntitlement)
+                && (value.settledPurchases === undefined || (Array.isArray(value.settledPurchases)
+                    && value.settledPurchases.every((settlement) => isRecord(settlement)
+                        && isString(settlement.transactionId)
+                        && isString(settlement.productId)
+                        && ['granted', 'refunded'].includes(settlement.status)
+                        && (settlement.ledgerEntryId === undefined || isString(settlement.ledgerEntryId))
+                        && (settlement.alreadyProcessed === undefined
+                            || typeof settlement.alreadyProcessed === 'boolean'))));
+        case 'commerce.getEntitlements':
+            return Array.isArray(value) && value.every(isEntitlement);
+        case 'ads.preload':
+        case 'ads.unmountBanner':
+        case 'leaderboard.open':
+            return isVoidData(value);
+        case 'ads.showRewarded':
+            return isRecord(value)
+                && ['completed', 'skipped', 'unavailable', 'failed'].includes(value.status)
+                && typeof value.rewardGranted === 'boolean'
+                && (!value.rewardGranted || (value.status === 'completed'
+                    && isString(value.ledgerEntryId)
+                    && value.ledgerEntryId.length > 0))
+                && (value.evidence === undefined || isEvidence(value.evidence));
+        case 'ads.showInterstitial':
+            return isRecord(value)
+                && ['shown', 'skipped', 'unavailable'].includes(value.status);
+        case 'ads.mountBanner':
+            return isRecord(value)
+                && ['mounted', 'unavailable', 'failed'].includes(value.status);
+        case 'leaderboard.submitScore':
+            return isRecord(value)
+                && typeof value.submitted === 'boolean'
+                && (value.rank === undefined || (typeof value.rank === 'number' && Number.isFinite(value.rank)));
+        case 'identity.getPlayer':
+            return value === null || (isRecord(value)
+                && isString(value.playerId)
+                && (value.displayName === undefined || isString(value.displayName))
+                && (value.avatarUrl === undefined || isString(value.avatarUrl)));
+        case 'identity.getSession':
+            return isRecord(value)
+                && ['guest', 'platform-anonymous', 'authenticated'].includes(value.identityLevel)
+                && ['local', 'platform-asserted', 'server-verified'].includes(value.trustLevel)
+                && (value.playerId === undefined || isString(value.playerId));
+        case 'identity.requestUpgrade':
+            return isRecord(value)
+                && ['completed', 'cancelled', 'unavailable'].includes(value.status)
+                && typeof value.reloadExpected === 'boolean';
+        case 'notifications.getStatus':
+            return [
+                'subscribed', 'not-subscribed', 'approval-required',
+                'configuration-required', 'unsupported',
+            ].includes(value);
+        case 'notifications.requestSubscription':
+            return ['subscribed', 'rejected', 'unavailable'].includes(value);
+        default:
+            return false;
+    }
+}
+function isEntitlement(value) {
+    return isRecord(value)
+        && isString(value.id)
+        && ['purchase', 'promotion', 'admin'].includes(value.source)
+        && isString(value.grantedAt)
+        && (value.expiresAt === undefined || isString(value.expiresAt));
+}
+function isEvidence(value) {
+    return isRecord(value)
+        && isString(value.schema)
+        && isRecord(value.payload)
+        && Object.values(value.payload).every((entry) => isString(entry) || typeof entry === 'number' || typeof entry === 'boolean');
+}

package/dist/viewport.d.ts

@@ -0,0 +1,25 @@
+import type { PlatformViewportOccupiedSurface, PlatformViewportState, ViewportAdapter } from '@mpgd/platform';
+export type CapacitorViewportBaseState = Omit<PlatformViewportState, 'occupiedSurfaces'>;
+export interface CapacitorViewportHost {
+  readState(): CapacitorViewportBaseState;
+  onChange(callback: () => void): () => void;
+}
+export interface CapacitorOccupiedSurfaceInput extends PlatformViewportOccupiedSurface {
+  /** Native providers report physical pixels with their own density scale. */
+  readonly unit: 'css-px' | 'physical-px';
+  readonly pixelsPerCssPixel?: number;
+}
+export interface CapacitorViewportController extends ViewportAdapter {
+  setOccupiedSurface(input: CapacitorOccupiedSurfaceInput): void;
+  clearOccupiedSurface(surfaceId: string): void;
+  dispose(): void;
+}
+/**
+* Owns only its viewport listeners. CSS safe-area values are the default
+* system-inset source; a host can inject separate native system-bar readings
+* without summing the same occupied pixels twice.
+*/
+export declare function createCapacitorViewport(input?: {
+  readonly host?: CapacitorViewportHost;
+  readonly onError?: (error: unknown) => void;
+}): CapacitorViewportController;

package/dist/viewport.js

@@ -0,0 +1,221 @@
+import { readTargetViewportSafeAreaInsets } from '@mpgd/target-config';
+/**
+ * Owns only its viewport listeners. CSS safe-area values are the default
+ * system-inset source; a host can inject separate native system-bar readings
+ * without summing the same occupied pixels twice.
+ */
+export function createCapacitorViewport(input = {}) {
+    const host = input.host ?? createWebViewHost();
+    const listeners = new Set();
+    const surfaces = new Map();
+    let unsubscribeHost;
+    let disposed = false;
+    let lastStateJson;
+    function reportError(error) {
+        try {
+            input.onError?.(error);
+        }
+        catch {
+            // A diagnostic callback must not prevent another viewport subscriber
+            // from seeing the same state change.
+        }
+    }
+    function getState() {
+        if (disposed) {
+            throw new Error('Capacitor viewport is disposed.');
+        }
+        const base = host.readState();
+        if (!Number.isFinite(base.width) || !Number.isFinite(base.height)
+            || base.width <= 0 || base.height <= 0) {
+            throw new Error('Capacitor viewport dimensions must be positive CSS pixels.');
+        }
+        const occupiedSurfaces = [...surfaces.values()].map((surface) => ({
+            ...surface,
+            bounds: clipBounds(surface.bounds, base.width, base.height),
+        }));
+        return {
+            width: base.width,
+            height: base.height,
+            safeAreaInsets: { ...base.safeAreaInsets },
+            systemBarInsets: { ...base.systemBarInsets },
+            keyboardInsets: { ...base.keyboardInsets },
+            occupiedSurfaces,
+        };
+    }
+    function notify() {
+        if (disposed) {
+            return;
+        }
+        let state;
+        try {
+            state = getState();
+        }
+        catch (error) {
+            reportError(error);
+            return;
+        }
+        const stateJson = JSON.stringify(state);
+        if (stateJson === lastStateJson) {
+            return;
+        }
+        lastStateJson = stateJson;
+        for (const listener of [...listeners]) {
+            try {
+                listener(state);
+            }
+            catch (error) {
+                reportError(error);
+            }
+        }
+    }
+    return {
+        getState,
+        onChange(callback) {
+            if (disposed) {
+                throw new Error('Capacitor viewport is disposed.');
+            }
+            listeners.add(callback);
+            if (unsubscribeHost === undefined) {
+                try {
+                    lastStateJson = JSON.stringify(getState());
+                    unsubscribeHost = host.onChange(notify);
+                }
+                catch (error) {
+                    listeners.delete(callback);
+                    lastStateJson = undefined;
+                    throw error;
+                }
+            }
+            let active = true;
+            return () => {
+                if (!active) {
+                    return;
+                }
+                active = false;
+                listeners.delete(callback);
+                if (listeners.size === 0) {
+                    unsubscribeHost?.();
+                    unsubscribeHost = undefined;
+                    lastStateJson = undefined;
+                }
+            };
+        },
+        setOccupiedSurface(surface) {
+            if (disposed) {
+                throw new Error('Capacitor viewport is disposed.');
+            }
+            if (surface.surfaceId.trim() === '') {
+                throw new Error('Occupied surface ID is required.');
+            }
+            if (!['top', 'right', 'bottom', 'left'].includes(surface.edge)) {
+                throw new Error('Occupied surface edge is invalid.');
+            }
+            if (surface.unit !== 'css-px' && surface.unit !== 'physical-px') {
+                throw new Error('Occupied surface unit is invalid.');
+            }
+            const scale = surface.unit === 'physical-px' ? surface.pixelsPerCssPixel : 1;
+            if (scale === undefined || !Number.isFinite(scale) || scale <= 0) {
+                throw new Error('Native occupied surfaces require a positive pixels-per-CSS-pixel scale.');
+            }
+            const { x, y, width, height } = surface.bounds;
+            if (![x, y, width, height].every(Number.isFinite)
+                || x < 0 || y < 0 || width < 0 || height < 0) {
+                throw new Error('Occupied surface bounds must be non-negative finite pixels.');
+            }
+            surfaces.set(surface.surfaceId, {
+                surfaceId: surface.surfaceId,
+                edge: surface.edge,
+                bounds: { x: x / scale, y: y / scale, width: width / scale, height: height / scale },
+            });
+            if (listeners.size > 0) {
+                notify();
+            }
+        },
+        clearOccupiedSurface(surfaceId) {
+            if (disposed) {
+                return;
+            }
+            if (surfaces.delete(surfaceId) && listeners.size > 0) {
+                notify();
+            }
+        },
+        dispose() {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            unsubscribeHost?.();
+            unsubscribeHost = undefined;
+            listeners.clear();
+            surfaces.clear();
+            lastStateJson = undefined;
+        },
+    };
+}
+function clipBounds(bounds, width, height) {
+    const x = Math.max(0, Math.min(width, bounds.x));
+    const y = Math.max(0, Math.min(height, bounds.y));
+    return {
+        x,
+        y,
+        width: Math.max(0, Math.min(width - x, bounds.width)),
+        height: Math.max(0, Math.min(height - y, bounds.height)),
+    };
+}
+function createWebViewHost() {
+    const systemBarCssVariables = {
+        top: '--safe-area-inset-top',
+        right: '--safe-area-inset-right',
+        bottom: '--safe-area-inset-bottom',
+        left: '--safe-area-inset-left',
+    };
+    function readState() {
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            throw new Error('Capacitor viewport requires a WebView host.');
+        }
+        const width = Math.max(1, Math.round(window.innerWidth));
+        const height = Math.max(1, Math.round(window.innerHeight));
+        const visual = window.visualViewport;
+        const style = getComputedStyle(document.documentElement);
+        // The visual viewport can be panned above the keyboard. At scale 1 and
+        // full layout width, both its top offset and remaining bottom gap obscure
+        // persistent controls; zoom/pan at another scale is not a keyboard inset.
+        const visualUsable = visual !== null && visual !== undefined
+            && visual.scale === 1 && visual.width >= width - 1;
+        const keyboardTop = visualUsable ? Math.max(0, Math.round(visual.offsetTop)) : 0;
+        const keyboardBottom = visualUsable
+            ? Math.max(0, Math.round(height - visual.offsetTop - visual.height))
+            : 0;
+        return {
+            width,
+            height,
+            safeAreaInsets: readTargetViewportSafeAreaInsets(style),
+            systemBarInsets: readTargetViewportSafeAreaInsets(style, systemBarCssVariables),
+            keyboardInsets: { top: keyboardTop, right: 0, bottom: keyboardBottom, left: 0 },
+        };
+    }
+    return {
+        readState,
+        onChange(callback) {
+            window.addEventListener('resize', callback);
+            window.addEventListener('orientationchange', callback);
+            const visual = window.visualViewport;
+            visual?.addEventListener('resize', callback);
+            visual?.addEventListener('scroll', callback);
+            const rootStyleObserver = typeof MutationObserver === 'undefined'
+                ? undefined
+                : new MutationObserver(callback);
+            rootStyleObserver?.observe(document.documentElement, {
+                attributes: true,
+                attributeFilter: ['style', 'class'],
+            });
+            return () => {
+                window.removeEventListener('resize', callback);
+                window.removeEventListener('orientationchange', callback);
+                visual?.removeEventListener('resize', callback);
+                visual?.removeEventListener('scroll', callback);
+                rootStyleObserver?.disconnect();
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-capacitor",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "Capacitor platform adapter for mpgd Android and iOS shells.",
   "license": "MIT",
   "repository": {
@@ -34,14 +34,21 @@
     "dist"
   ],
   "dependencies": {
-    "@mpgd/bridge": "0.9.1",
-    "@mpgd/capacitor-game-services": "0.5.3",
-    "@mpgd/platform": "0.12.1"
+    "@capacitor/app": "8.1.1",
+    "@mpgd/capacitor-game-services": "0.6.0",
+    "@mpgd/platform": "0.13.0",
+    "@mpgd/target-config": "0.16.0",
+    "@mpgd/bridge": "0.10.0"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.5.1"
   },
   "devDependencies": {
+    "@capacitor/core": "8.5.2",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@mpgd/game-services": "0.16.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -53,6 +60,7 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "vitest run"
+    "test:native-http-runtime": "node test/native-http-runtime.mjs",
+    "test": "vitest run && node test/package-import.mjs && node test/native-http-runtime.mjs"
   }
 }