@mpgd/adapter-ait 0.12.7 → 0.13.0

package/dist/ad-provider.d.ts

@@ -0,0 +1,18 @@
+import { type AdProvider, type AdShowInput, type AdShowResult } from '@mpgd/platform/ads';
+import type { AitHostDependencies } from './host.js';
+import type { AitAdPlacementType } from './ad-config.js';
+/** SDK event interpretation only. Game execution and backend grants are separate owners. */
+export declare function createAitAdProvider(input: {
+  readonly dependencies: Pick<AitHostDependencies, 'showFullScreenAd'>;
+  readonly groups: ReadonlyMap<string, string>;
+  readonly types: ReadonlyMap<string, AitAdPlacementType>;
+  readonly isSupported: () => boolean;
+  readonly prepare: (group: string) => Promise<void>;
+  readonly consume: (group: string) => boolean;
+  readonly requestTimeoutMs: number;
+  readonly startTimeoutMs: number;
+  readonly displayTimeoutMs: number;
+  readonly onLegacyPhase?: (active: boolean) => void;
+}): AdProvider & {
+  showLegacy(request: AdShowInput): Promise<AdShowResult>;
+};

package/dist/ad-provider.js

@@ -0,0 +1,295 @@
+import { adProtocol, adProtocolVersion, assertAdPresentationEvent, assertAdShowInput, assertAdShowResult, } from '@mpgd/platform/ads';
+const nativeOwners = new WeakMap();
+/** SDK event interpretation only. Game execution and backend grants are separate owners. */
+export function createAitAdProvider(input) {
+    const id = 'apps-in-toss-ads';
+    const sdk = input.dependencies.showFullScreenAd;
+    const listeners = new Set();
+    function availability(request) {
+        if (!input.isSupported()) {
+            return { state: 'unsupported', reason: 'unsupported' };
+        }
+        if (input.types.has(request.placementId) && input.types.get(request.placementId) !== request.format) {
+            return {
+                state: 'unsupported',
+                reason: 'unsupported',
+            };
+        }
+        if (!input.groups.has(request.placementId) || !input.types.has(request.placementId)) {
+            return {
+                state: 'configuration-required',
+                reason: 'configuration-required',
+            };
+        }
+        const owner = nativeOwners.get(sdk);
+        if (owner?.state === 'unknown') {
+            return {
+                state: 'action-required',
+                reason: 'action-required',
+            };
+        }
+        if (owner !== undefined) {
+            return { state: 'temporarily-unavailable', reason: 'busy' };
+        }
+        return { state: 'available' };
+    }
+    async function show(supplied, legacy) {
+        const request = assertAdShowInput(supplied);
+        if (request.idempotencyKey.length > 256 || /[\p{Cc}\p{Cf}]/u.test(request.idempotencyKey)) {
+            throw new TypeError('AIT ad correlation must contain 1 to 256 visible characters.');
+        }
+        const makeResult = (state) => assertAdShowResult({ providerId: id, invocationId: request.invocationId, format: request.format, ...state });
+        const noStart = (outcome, reason) => makeResult({
+            outcome,
+            presentation: 'not-started',
+            eligibility: request.format === 'rewarded' ? 'not-earned' : 'not-applicable',
+            ...(reason === undefined ? {} : { reason }),
+        });
+        const available = availability(request);
+        if (available.state !== 'available') {
+            return noStart('unavailable', available.reason);
+        }
+        const group = input.groups.get(request.placementId);
+        if (group === undefined) {
+            return noStart('unavailable', 'configuration-required');
+        }
+        const owned = { state: 'requested' };
+        nativeOwners.set(sdk, owned);
+        const legacyPhase = (active) => {
+            if (!legacy) {
+                return;
+            }
+            try {
+                input.onLegacyPhase?.(active);
+            }
+            catch { /* Isolate lifecycle observation. */ }
+        };
+        const release = () => {
+            if (nativeOwners.get(sdk) === owned) {
+                nativeOwners.delete(sdk);
+            }
+        };
+        try {
+            await input.prepare(group);
+        }
+        catch {
+            release();
+            return noStart('failed', 'transient-failure');
+        }
+        if (!input.consume(group)) {
+            release();
+            return noStart('failed', 'transient-failure');
+        }
+        let started = false;
+        let closed = false;
+        let earned;
+        let sequence = 0;
+        let cleanup;
+        let cleaned = false;
+        let timer;
+        let displayTimerArmed = false;
+        let delivered = false;
+        let resolve;
+        const result = new Promise((done) => {
+            resolve = done;
+        });
+        const startedAt = Date.now();
+        const emit = (event) => {
+            const safe = assertAdPresentationEvent({
+                ...event,
+                providerId: id,
+                invocationId: request.invocationId,
+                sequence: ++sequence,
+            });
+            for (const listener of [...listeners]) {
+                try {
+                    void Promise.resolve(listener(safe)).catch(() => undefined);
+                }
+                catch { /* Keep native terminal observation alive. */ }
+            }
+        };
+        const clean = () => {
+            if (cleaned || cleanup === undefined || !closed || request.format === 'rewarded' && earned === undefined) {
+                return;
+            }
+            cleaned = true;
+            try {
+                cleanup();
+            }
+            catch { /* Cleanup does not change native closure. */ }
+        };
+        const finish = (value) => {
+            if (!delivered) {
+                delivered = true;
+                resolve(value);
+            }
+        };
+        const eligibility = () => {
+            if (request.format === 'interstitial') {
+                return 'not-applicable';
+            }
+            return earned === undefined ? 'unknown' : 'eligible';
+        };
+        const uncertain = () => {
+            if (closed || owned.state === 'unknown') {
+                return;
+            }
+            owned.state = 'unknown';
+            emit({ type: 'unknown' });
+            finish(makeResult({
+                outcome: 'pending',
+                presentation: 'unknown',
+                eligibility: eligibility(),
+                reason: 'outcome-unknown',
+                ...(earned === undefined ? {} : { evidence: earned }),
+            }));
+        };
+        const close = (failed) => {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            release();
+            legacyPhase(false);
+            emit(failed ? { type: 'failed', reason: 'transient-failure' } : { type: 'closed' });
+            if (failed && !started && earned === undefined) {
+                finish(noStart('failed', 'transient-failure'));
+            }
+            else {
+                finish(makeResult({
+                    outcome: failed ? 'failed' : 'shown',
+                    presentation: 'closed',
+                    eligibility: eligibility(),
+                    ...(failed ? { reason: 'transient-failure' } : {}),
+                    ...(earned === undefined ? {} : { evidence: earned }),
+                }));
+            }
+            // Failure before presentation proves no earning is forthcoming. After a
+            // started presentation, retain the scoped callback for a delayed reward.
+            if (failed && !started && earned === undefined) {
+                cleaned = true;
+                if (cleanup !== undefined) {
+                    try {
+                        cleanup();
+                    }
+                    catch { /* Isolate cleanup. */ }
+                }
+            }
+            else {
+                clean();
+            }
+        };
+        const startedEvent = () => {
+            if (closed) {
+                return;
+            }
+            if (!started) {
+                started = true;
+                owned.state = 'open';
+                emit({ type: 'started' });
+            }
+            if (!displayTimerArmed) {
+                displayTimerArmed = true;
+                if (timer !== undefined) {
+                    clearTimeout(timer);
+                }
+                timer = setTimeout(uncertain, input.displayTimeoutMs);
+            }
+        };
+        legacyPhase(true);
+        emit({ type: 'requested' });
+        timer = setTimeout(uncertain, input.requestTimeoutMs);
+        try {
+            cleanup = sdk({
+                options: { adGroupId: group },
+                onEvent(event) {
+                    switch (event.type) {
+                        case 'requested':
+                            if (!closed && !started) {
+                                if (timer !== undefined) {
+                                    clearTimeout(timer);
+                                }
+                                timer = setTimeout(uncertain, Math.min(input.startTimeoutMs, Math.max(0, input.requestTimeoutMs - (Date.now() - startedAt))));
+                            }
+                            break;
+                        case 'show':
+                        case 'impression':
+                        case 'clicked':
+                            startedEvent();
+                            break;
+                        case 'userEarnedReward':
+                            if (request.format !== 'rewarded' || earned !== undefined || cleaned) {
+                                break;
+                            }
+                            if (!closed) {
+                                startedEvent();
+                            }
+                            earned = { schema: 'apps-in-toss.rewarded-ad.callback.v1', payload: { event: 'user-earned-reward', correlationId: request.idempotencyKey, placementId: group } };
+                            emit({ type: 'reward-earned', evidence: earned });
+                            clean();
+                            break;
+                        case 'dismissed':
+                            close(false);
+                            break;
+                        case 'failedToShow':
+                            close(true);
+                            break;
+                    }
+                },
+                // A bridge error does not prove the native UI never opened.
+                onError() { uncertain(); },
+            });
+            if (cleaned) {
+                try {
+                    cleanup();
+                }
+                catch { /* Isolate synchronous terminal cleanup. */ }
+            }
+            else {
+                clean();
+            }
+        }
+        catch {
+            uncertain();
+        }
+        return result;
+    }
+    return {
+        id,
+        protocol: adProtocol,
+        protocolVersion: adProtocolVersion,
+        rewardSignal: 'delayed',
+        getAvailability: async (request) => availability(request),
+        async preload(request) {
+            const available = availability(request);
+            if (available.state !== 'available') {
+                return {
+                    status: 'unavailable',
+                    ...(available.reason === undefined ? {} : { reason: available.reason }),
+                };
+            }
+            const group = input.groups.get(request.placementId);
+            if (group === undefined) {
+                return { status: 'unavailable', reason: 'configuration-required' };
+            }
+            try {
+                await input.prepare(group);
+                return { status: 'ready' };
+            }
+            catch {
+                return { status: 'failed', reason: 'transient-failure' };
+            }
+        },
+        show: (request) => show(request, false),
+        showLegacy: (request) => show(request, true),
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}

package/dist/host.d.ts

@@ -149,7 +149,7 @@ export interface InstallAitHostBridgeOptions {
   readonly adLoadQueueTimeoutMs?: number;
   /** Upper bound for the requested-to-display portion of the total show timeout. */
   readonly adDisplayStartTimeoutMs?: number;
-  /** Last-resort cleanup when the native SDK omits its terminal display callback. */
+  /** Caller wait limit; a missing native terminal callback keeps presentation unknown. */
   readonly adMaximumDisplayMs?: number;
   /** Maximum wait for an inline banner to render or report no-fill/failure. */
   readonly bannerRenderTimeoutMs?: number;

package/dist/host.js

@@ -1,5 +1,7 @@
 import { getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame as grantPromotionReward, IAP, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore, TossAds, } from '@apps-in-toss/web-framework';
 import { assertBridgeRequest, bridgeStorageLoadProtocol, } from '@mpgd/bridge';
+import { assertAdShowInput, toAdAdapter } from '@mpgd/platform/ads';
+import { createAitAdProvider } from './ad-provider.js';
 import { dispatchAitLifecycleEvent } from './lifecycle.js';
 const defaultAdTimeoutMs = 60_000;
 const defaultAdLoadQueueTimeoutMs = 5_000;
@@ -13,7 +15,6 @@ const defaultIapPurchaseSessionTimeoutMs = 30 * 60_000;
 /** A provider response is untrusted input; keep restore work bounded per launch. */
 const maximumPendingIapOrders = 20;
 const invalidBridgeRequestId = 'ait-invalid-request';
-const rewardedAdEvidenceSchema = 'apps-in-toss.rewarded-ad.callback.v1';
 const iapEvidenceSchema = 'apps-in-toss.iap.callback.v1';
 const minimumPromotionTossAppVersion = '5.232.0';
 /**
@@ -115,7 +116,6 @@ export function createAitHostBridge(options = {}) {
     const notificationSubscriptions = new Set();
     const loadedAdGroupIds = new Set();
     const loadingAdGroups = new Map();
-    const activeAdGroupIds = new Set();
     const activeBannerAttachments = new Map();
     const bannerMountOwners = new Map();
     const pendingBannerMountSettlements = new Map();
@@ -131,10 +131,20 @@ export function createAitHostBridge(options = {}) {
         tone: options.bannerAppearance?.tone ?? 'blackAndWhite',
         variant: options.bannerAppearance?.variant ?? 'expanded',
     };
-    const adLoadCoordinator = {
-        active: undefined,
-        waitTimeoutMs: adLoadQueueTimeoutMs,
-    };
+    const adLoadCoordinator = createAdLoadCoordinator(dependencies.loadFullScreenAd, adLoadQueueTimeoutMs);
+    const nativeAds = createAitAdProvider({
+        dependencies,
+        groups: adGroupIds,
+        types: adPlacementTypes,
+        isSupported: () => areFullScreenAdsSupported(dependencies),
+        prepare: (group) => preloadAdGroup(dependencies, group, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, adTimeoutMs),
+        consume: (group) => consumeLoadedAd(group, loadedAdGroupIds),
+        requestTimeoutMs: adTimeoutMs,
+        startTimeoutMs: adDisplayStartTimeoutMs,
+        displayTimeoutMs: adMaximumDisplayMs,
+        onLegacyPhase: (active) => dispatchAitLifecycleEvent(active ? 'pause' : 'resume'),
+    });
+    const legacyAds = toAdAdapter({ ...nativeAds, show: nativeAds.showLegacy });
     const enqueueCompletedIapAttemptRetention = (storage, storageKey) => {
         const scheduled = completedIapAttemptRetention.then(async () => {
             await retainCompletedAitIapPurchaseAttempt(storage, storageKey, iapProductGrantTimeoutMs);
@@ -145,6 +155,13 @@ export function createAitHostBridge(options = {}) {
         return next;
     };
     return {
+        advertising: {
+            id: nativeAds.id,
+            protocol: nativeAds.protocol,
+            protocolVersion: nativeAds.protocolVersion,
+            rewardSignal: nativeAds.rewardSignal,
+            subscribe: (listener) => nativeAds.subscribe(listener),
+        },
         async request(input) {
             try {
                 return await handleRequest(parseBridgeRequest(input));
@@ -377,54 +394,24 @@ export function createAitHostBridge(options = {}) {
                 await preloadAdGroupWithDiagnostics(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, adTimeoutMs, placementType);
                 return ok(request, {});
             }
-            case 'ads.showRewarded': {
-                const placementId = readPlacementId(request.payload);
-                const correlationId = readRewardedAdCorrelationId(request.payload, request.id);
-                const adGroupId = adGroupIds.get(placementId);
-                if (adGroupId === undefined
-                    || adPlacementTypes.get(placementId) !== 'rewarded'
-                    || !areFullScreenAdsSupported(dependencies)) {
-                    return ok(request, { status: 'unavailable', rewardGranted: false });
-                }
-                const shown = await withLoadedAdSlot(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, activeAdGroupIds, adTimeoutMs, 'rewarded', async () => {
-                    const result = await showRewardedAd(dependencies, adGroupId, adTimeoutMs, adDisplayStartTimeoutMs, adMaximumDisplayMs);
-                    return result.rewardGranted
-                        ? {
-                            ...result,
-                            // The correlationId is client-supplied evidence, not a native receipt:
-                            // the Apps in Toss show call only carries the adGroupId, so nothing
-                            // native echoes it back. game-services forwards it as
-                            // platformImpressionId; the backend rewardAuthority must verify it
-                            // (and the rest of this evidence) before granting any reward.
-                            ledgerEntryId: correlationId,
-                            evidence: {
-                                schema: rewardedAdEvidenceSchema,
-                                payload: {
-                                    event: 'user-earned-reward',
-                                    correlationId,
-                                    placementId: adGroupId,
-                                },
-                            },
-                        }
-                        : result;
+            case 'ads.getAvailability':
+            case 'ads.prepare': {
+                const payload = readPayloadRecord(request.payload);
+                const query = assertAdShowInput({
+                    ...payload,
+                    invocationId: 'host-query',
+                    idempotencyKey: 'host-query',
                 });
-                if (!shown.acquired) {
-                    return ok(request, { status: 'unavailable', rewardGranted: false });
-                }
-                return ok(request, shown.value);
-            }
-            case 'ads.showInterstitial': {
-                const placementId = readPlacementId(request.payload);
-                const adGroupId = adGroupIds.get(placementId);
-                if (adGroupId === undefined
-                    || adPlacementTypes.get(placementId) !== 'interstitial'
-                    || !areFullScreenAdsSupported(dependencies)) {
-                    return ok(request, { status: 'unavailable' });
-                }
-                const showInterstitial = () => showInterstitialAd(dependencies, adGroupId, adTimeoutMs, adDisplayStartTimeoutMs, adMaximumDisplayMs);
-                const shown = await withLoadedAdSlot(dependencies, adGroupId, loadedAdGroupIds, loadingAdGroups, adLoadCoordinator, activeAdGroupIds, adTimeoutMs, 'interstitial', showInterstitial);
-                return ok(request, shown.acquired ? shown.value : { status: 'unavailable' });
+                return ok(request, request.method === 'ads.prepare'
+                    ? await nativeAds.preload(query)
+                    : await nativeAds.getAvailability(query));
             }
+            case 'ads.show':
+                return ok(request, await nativeAds.show(assertAdShowInput(request.payload)));
+            case 'ads.showRewarded':
+                return ok(request, await legacyAds.showRewarded({ placementId: readPlacementId(request.payload), idempotencyKey: readRewardedAdCorrelationId(request.payload, request.id) }));
+            case 'ads.showInterstitial':
+                return ok(request, await legacyAds.showInterstitial?.({ placementId: readPlacementId(request.payload) }));
             case 'ads.mountBanner': {
                 const placementId = readPlacementId(request.payload);
                 const surfaceId = readBannerSurfaceId(request.payload);
@@ -838,6 +825,24 @@ async function preloadAdGroup(dependencies, adGroupId, loaded, loading, coordina
         }
     }
 }
+const nativeAdLoadScopes = new WeakMap();
+function createAdLoadCoordinator(sdk, waitTimeoutMs) {
+    let shared = nativeAdLoadScopes.get(sdk);
+    if (shared === undefined) {
+        shared = { active: undefined };
+        nativeAdLoadScopes.set(sdk, shared);
+    }
+    const owned = shared;
+    return {
+        get active() {
+            return owned.active;
+        },
+        set active(value) {
+            owned.active = value;
+        },
+        waitTimeoutMs,
+    };
+}
 async function runSerializedAdLoad(coordinator, adGroupId, startNativeLoad) {
     const waitDeadline = Date.now() + coordinator.waitTimeoutMs;
     while (coordinator.active !== undefined) {
@@ -881,22 +886,6 @@ function waitForAdLoadSettlement(active, timeoutMs, adGroupId) {
         void active.then(() => finish(), () => finish());
     });
 }
-async function acquireLoadedAdSlot(dependencies, adGroupId, loaded, loading, coordinator, active, timeoutMs, placementType) {
-    if (active.has(adGroupId)) {
-        return false;
-    }
-    const loadedSuccessfully = await preloadAdGroupWithDiagnostics(dependencies, adGroupId, loaded, loading, coordinator, timeoutMs, placementType);
-    if (!loadedSuccessfully) {
-        return false;
-    }
-    // Re-check after the asynchronous load so concurrent callers cannot consume
-    // or display the same native ad slot twice.
-    if (active.has(adGroupId) || !consumeLoadedAd(adGroupId, loaded)) {
-        return false;
-    }
-    active.add(adGroupId);
-    return true;
-}
 async function preloadAdGroupWithDiagnostics(dependencies, adGroupId, loaded, loading, coordinator, timeoutMs, placementType) {
     // The first caller enters preloadAdGroup synchronously and publishes its promise
     // before yielding. Remember that ownership so concurrent waiters do not emit the
@@ -915,131 +904,6 @@ async function preloadAdGroupWithDiagnostics(dependencies, adGroupId, loaded, lo
         return false;
     }
 }
-async function withLoadedAdSlot(dependencies, adGroupId, loaded, loading, coordinator, active, timeoutMs, placementType, display) {
-    const acquired = await acquireLoadedAdSlot(dependencies, adGroupId, loaded, loading, coordinator, active, timeoutMs, placementType);
-    if (!acquired) {
-        return { acquired: false };
-    }
-    try {
-        return { acquired: true, value: await display() };
-    }
-    finally {
-        active.delete(adGroupId);
-    }
-}
-async function showRewardedAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs) {
-    let rewardGranted = false;
-    const status = await showAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs, (eventType) => {
-        if (eventType === 'userEarnedReward') {
-            rewardGranted = true;
-        }
-    });
-    let resultStatus;
-    if (status === 'shown' && rewardGranted) {
-        resultStatus = 'completed';
-    }
-    else if (status === 'failed') {
-        resultStatus = 'failed';
-    }
-    else {
-        resultStatus = 'skipped';
-    }
-    return {
-        status: resultStatus,
-        rewardGranted,
-    };
-}
-async function showInterstitialAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs) {
-    const status = await showAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs);
-    return { status: status === 'failed' ? 'skipped' : status };
-}
-function showAd(dependencies, adGroupId, timeoutMs, displayStartTimeoutMs, maximumDisplayMs, observe) {
-    dispatchAitLifecycleEvent('pause');
-    return new Promise((resolve) => {
-        const startedAt = Date.now();
-        let cleanup = () => { };
-        let settled = false;
-        let maximumDisplayTimeoutArmed = false;
-        let adTimer;
-        const clearAdTimer = () => {
-            if (adTimer !== undefined) {
-                globalThis.clearTimeout(adTimer);
-                adTimer = undefined;
-            }
-        };
-        const finish = (status) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            clearAdTimer();
-            cleanup();
-            dispatchAitLifecycleEvent('resume');
-            resolve(status);
-        };
-        const armDisplayStartTimeout = () => {
-            clearAdTimer();
-            const elapsedMs = Math.max(0, Date.now() - startedAt);
-            const remainingMs = Math.max(0, timeoutMs - elapsedMs);
-            adTimer = globalThis.setTimeout(() => finish('failed'), Math.min(displayStartTimeoutMs, remainingMs));
-        };
-        const armMaximumDisplayTimeout = () => {
-            if (maximumDisplayTimeoutArmed) {
-                return;
-            }
-            maximumDisplayTimeoutArmed = true;
-            clearAdTimer();
-            adTimer = globalThis.setTimeout(() => {
-                console.warn('AIT full-screen ad omitted its terminal callback; recovering the game lifecycle.', adGroupId);
-                finish('shown');
-            }, maximumDisplayMs);
-        };
-        const failShow = (error) => {
-            if (settled) {
-                return;
-            }
-            console.warn('Failed to show AIT full-screen ad.', adGroupId, error ?? 'unknown native error');
-            finish('failed');
-        };
-        adTimer = globalThis.setTimeout(() => finish('failed'), timeoutMs);
-        try {
-            const unregister = dependencies.showFullScreenAd({
-                options: { adGroupId },
-                onEvent: (event) => {
-                    observe?.(event.type);
-                    switch (event.type) {
-                        case 'requested':
-                            armDisplayStartTimeout();
-                            break;
-                        case 'show':
-                        case 'impression':
-                        case 'clicked':
-                        case 'userEarnedReward':
-                            // Native terminal callbacks remain authoritative. A long, one-shot
-                            // recovery timeout prevents a broken SDK callback from deadlocking
-                            // the game forever without treating ordinary end-card dwell as failure.
-                            armMaximumDisplayTimeout();
-                            break;
-                        case 'dismissed':
-                            finish('shown');
-                            break;
-                        case 'failedToShow':
-                            finish('failed');
-                            break;
-                    }
-                },
-                onError: failShow,
-            });
-            cleanup = unregister;
-            if (settled) {
-                cleanup();
-            }
-        }
-        catch (error) {
-            failShow(error);
-        }
-    });
-}
 /**
  * Launch and inbound-share parameters arrive from untrusted deep links. Bound
  * each forwarded value and the nested `queryParams` JSON so a hostile link

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 import { type BridgeRequest, type BridgeResponse } from '@mpgd/bridge';
 import { type PlatformGateway } from '@mpgd/platform';
+import { type AdProvider } from '@mpgd/platform/ads';
 export interface GamePlatformBridge {
   request(input: BridgeRequest): Promise<BridgeResponse>;
+  /** Native observations are scoped to this host; SDK commands still use request envelopes. */
+  readonly advertising?: Pick<AdProvider, 'id' | 'protocol' | 'protocolVersion' | 'rewardSignal' | 'subscribe'>;
 }
 export interface AitSandboxStorage {
   readonly getItem: (key: string) => string | null;

package/dist/index.js

@@ -1,7 +1,48 @@
-import { bridgeStorageLoadProtocol, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
+import { assertBridgeResponse, bridgeStorageLoadProtocol, decodeBridgeStorageLoadData, } from '@mpgd/bridge';
 import { PlatformOperationError, } from '@mpgd/platform';
+import { assertAdAvailability, assertAdPreparationResult, assertAdPresentationEvent, assertAdShowInput, assertAdShowResult, toAdAdapter, } from '@mpgd/platform/ads';
 import { createAitLifecycleAdapter } from './lifecycle.js';
 export function createAitPlatformGateway(input) {
+    const advertisingBridge = input.bridge ?? getBridge() ?? input.fallbackBridge;
+    const advertising = advertisingBridge?.advertising;
+    async function requestAdvertising(method, payload) {
+        if (advertisingBridge === undefined) {
+            throw new PlatformOperationError({
+                code: 'AIT_BRIDGE_NOT_INSTALLED',
+            });
+        }
+        const id = crypto.randomUUID();
+        const response = assertBridgeResponse(await advertisingBridge.request({ id, method, payload, meta: { target: 'ait', appVersion: input.appVersion, buildId: input.buildId, sentAt: new Date().toISOString() } }));
+        if (response.id !== id) {
+            throw new TypeError('Advertising response belongs to another bridge request.');
+        }
+        if (!response.ok) {
+            throw new PlatformOperationError(response.error);
+        }
+        return response.data;
+    }
+    const provider = advertising === undefined
+        ? undefined
+        : {
+            id: advertising.id,
+            protocol: advertising.protocol,
+            protocolVersion: advertising.protocolVersion,
+            rewardSignal: advertising.rewardSignal,
+            getAvailability: async (payload) => assertAdAvailability(await requestAdvertising('ads.getAvailability', payload)),
+            preload: async (payload) => assertAdPreparationResult(await requestAdvertising('ads.prepare', payload)),
+            show: async (supplied) => {
+                const request = assertAdShowInput(supplied);
+                const result = assertAdShowResult(await requestAdvertising('ads.show', request));
+                if (result.providerId !== advertising.id || result.invocationId !== request.invocationId || result.format !== request.format) {
+                    throw new TypeError('Advertising result belongs to another invocation.');
+                }
+                return result;
+            },
+            subscribe: (listener) => advertising.subscribe((event) => listener(assertAdPresentationEvent(event))),
+        };
+    if (provider !== undefined) {
+        toAdAdapter(provider);
+    }
     async function request(method, payload) {
         const bridge = input.bridge ?? getBridge() ?? input.fallbackBridge;
         if (bridge === undefined) {
@@ -60,6 +101,7 @@ export function createAitPlatformGateway(input) {
             getEntitlements: () => request('commerce.getEntitlements', {}),
         },
         ads: {
+            ...(provider === undefined ? {} : { provider }),
             preload: (payload) => request('ads.preload', payload),
             showRewarded: (payload) => request('ads.showRewarded', payload),
             showInterstitial: (payload) => request('ads.showInterstitial', payload),

package/dist/lifecycle.d.ts

@@ -1,5 +1,6 @@
 import type { LifecycleAdapter } from '@mpgd/platform';
 export declare const aitLifecyclePauseEvent = "mpgd:ait:pause";
 export declare const aitLifecycleResumeEvent = "mpgd:ait:resume";
+/** Legacy SDK presentation, page lifetime, and visibility are independent owners. */
 export declare function createAitLifecycleAdapter(): LifecycleAdapter;
 export declare function dispatchAitLifecycleEvent(type: 'pause' | 'resume'): void;

package/dist/lifecycle.js

@@ -1,45 +1,92 @@
 export const aitLifecyclePauseEvent = 'mpgd:ait:pause';
 export const aitLifecycleResumeEvent = 'mpgd:ait:resume';
-const lifecycleEventDedupeWindowMs = 500;
+/** Legacy SDK presentation, page lifetime, and visibility are independent owners. */
 export function createAitLifecycleAdapter() {
-    return {
-        onPause(callback) {
-            return subscribeToAitLifecycle('pause', callback);
-        },
-        onResume(callback) {
-            return subscribeToAitLifecycle('resume', callback);
-        },
-    };
-}
-export function dispatchAitLifecycleEvent(type) {
-    globalThis.dispatchEvent?.(new Event(type === 'pause' ? aitLifecyclePauseEvent : aitLifecycleResumeEvent));
-}
-function subscribeToAitLifecycle(type, callback) {
     const target = globalThis;
     const documentTarget = target.document;
-    const eventName = type === 'pause' ? aitLifecyclePauseEvent : aitLifecycleResumeEvent;
-    let lastFiredAt = Number.NEGATIVE_INFINITY;
-    const fire = () => {
-        const now = Date.now();
-        if (now - lastFiredAt < lifecycleEventDedupeWindowMs) {
-            return;
+    const pauses = new Set();
+    const resumes = new Set();
+    let nativePaused = false;
+    let pageActive = true;
+    let attached = false;
+    let active = documentTarget?.visibilityState !== 'hidden';
+    const notify = (callback) => {
+        try {
+            void Promise.resolve(callback()).catch(() => undefined);
         }
-        lastFiredAt = now;
-        callback();
+        catch { /* Keep lifecycle observation alive. */ }
     };
-    const handleCustomEvent = () => fire();
-    const handleVisibilityChange = () => {
-        if (documentTarget?.visibilityState === (type === 'pause' ? 'hidden' : 'visible')) {
-            fire();
+    function reconcile() {
+        const next = !nativePaused && pageActive && documentTarget?.visibilityState !== 'hidden';
+        if (next === active) {
+            return;
+        }
+        active = next;
+        for (const callback of [...(active ? resumes : pauses)]) {
+            notify(callback);
         }
+    }
+    const nativePause = () => {
+        nativePaused = true;
+        reconcile();
+    };
+    const nativeResume = () => {
+        nativePaused = false;
+        reconcile();
     };
-    const handlePageTransition = () => fire();
-    target.addEventListener?.(eventName, handleCustomEvent);
-    documentTarget?.addEventListener('visibilitychange', handleVisibilityChange);
-    target.addEventListener?.(type === 'pause' ? 'pagehide' : 'pageshow', handlePageTransition);
-    return () => {
-        target.removeEventListener?.(eventName, handleCustomEvent);
-        documentTarget?.removeEventListener('visibilitychange', handleVisibilityChange);
-        target.removeEventListener?.(type === 'pause' ? 'pagehide' : 'pageshow', handlePageTransition);
+    const pageHide = () => {
+        pageActive = false;
+        reconcile();
     };
+    const pageShow = () => {
+        pageActive = true;
+        reconcile();
+    };
+    function attach() {
+        if (attached) {
+            return;
+        }
+        attached = true;
+        target.addEventListener?.(aitLifecyclePauseEvent, nativePause);
+        target.addEventListener?.(aitLifecycleResumeEvent, nativeResume);
+        target.addEventListener?.('pagehide', pageHide);
+        target.addEventListener?.('pageshow', pageShow);
+        documentTarget?.addEventListener('visibilitychange', reconcile);
+    }
+    function detach() {
+        if (!attached) {
+            return;
+        }
+        attached = false;
+        target.removeEventListener?.(aitLifecyclePauseEvent, nativePause);
+        target.removeEventListener?.(aitLifecycleResumeEvent, nativeResume);
+        target.removeEventListener?.('pagehide', pageHide);
+        target.removeEventListener?.('pageshow', pageShow);
+        documentTarget?.removeEventListener('visibilitychange', reconcile);
+    }
+    function subscribe(callbacks, callback) {
+        callbacks.add(callback);
+        attach();
+        if (callbacks === pauses && !active) {
+            notify(callback);
+        }
+        return () => {
+            callbacks.delete(callback);
+            if (pauses.size + resumes.size === 0) {
+                detach();
+            }
+        };
+    }
+    return {
+        onPause: (callback) => subscribe(pauses, callback),
+        onResume: (callback) => subscribe(resumes, callback),
+        async dispose() {
+            pauses.clear();
+            resumes.clear();
+            detach();
+        },
+    };
+}
+export function dispatchAitLifecycleEvent(type) {
+    globalThis.dispatchEvent?.(new Event(type === 'pause' ? aitLifecyclePauseEvent : aitLifecycleResumeEvent));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-ait",
-  "version": "0.12.7",
+  "version": "0.13.0",
   "description": "Apps in Toss WebView platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -59,8 +59,8 @@
     "dist"
   ],
   "dependencies": {
-    "@mpgd/bridge": "0.10.0",
-    "@mpgd/platform": "0.14.0"
+    "@mpgd/platform": "0.15.0",
+    "@mpgd/bridge": "0.11.0"
   },
   "peerDependencies": {
     "@apps-in-toss/web-framework": ">=3.0.0 <4"
@@ -71,10 +71,12 @@
     }
   },
   "devDependencies": {
+    "@types/node": "^24.0.0",
     "@apps-in-toss/web-framework": "3.5.0",
     "ttsc": "0.30.4",
     "typescript": "7.0.2",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "@mpgd/game-runtime": "0.3.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",