@mpgd/adapter-ait 0.6.0 → 0.8.0

package/dist/host.d.ts

@@ -1,22 +1,68 @@
-import { getTossShareLink, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';
-import type { ShareResult } from '@mpgd/platform';
+import { getTossShareLink, grantPromotionRewardForGame as grantPromotionReward, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';
+import type { NotificationTopic, ShareResult } from '@mpgd/platform';
 import type { GamePlatformBridge } from './index.js';
 export type AitIdentityProvider = () => Promise<unknown>;
 export interface AitHostDependencies {
   readonly identityProvider: AitIdentityProvider;
-  readonly storage: Pick<typeof Storage, 'getItem' | 'setItem'>;
+  readonly storage: Pick<typeof Storage, 'getItem' | 'removeItem' | 'setItem'>;
   readonly getTossShareLink: typeof getTossShareLink;
   readonly share: typeof share;
+  readonly grantPromotionReward: typeof grantPromotionReward;
+  readonly requestNotificationAgreement: typeof requestNotificationAgreement;
   readonly isMinVersionSupported: typeof isMinVersionSupported;
   readonly loadFullScreenAd: typeof loadFullScreenAd;
   readonly showFullScreenAd: typeof showFullScreenAd;
   readonly openGameCenterLeaderboard: typeof openGameCenterLeaderboard;
   readonly submitGameCenterLeaderBoardScore: typeof submitGameCenterLeaderBoardScore;
 }
+export interface AitPromotionRewardConfig {
+  readonly promotionCode: string;
+  readonly amount: number;
+}
+export interface AitPendingPromotionGrantInput {
+  readonly campaignId: string;
+  readonly idempotencyKey: string;
+  /** Missing for legacy or malformed pending markers; resolvers must fail closed. */
+  readonly pendingSince?: string;
+}
+export type AitPendingPromotionGrantResolution = {
+  readonly status: 'granted';
+  readonly receiptKey: string;
+} | {
+  readonly status: 'retry' | 'pending';
+};
+/**
+* Server-backed reconciliation hook for an ambiguous native promotion call.
+* Returning `retry` must only happen after the game authority decides that a
+* second provider call is safe for this single-use claim id.
+*/
+export type AitPendingPromotionGrantResolver = (input: AitPendingPromotionGrantInput) => Promise<AitPendingPromotionGrantResolution>;
+export interface AitPromotionGrantAuthorizationInput {
+  readonly campaignId: string;
+  /** Single-use claim id issued by the game backend. */
+  readonly idempotencyKey: string;
+}
+export type AitPromotionGrantAuthorization = {
+  readonly status: 'authorized';
+} | {
+  readonly status: 'pending' | 'rejected';
+};
+/**
+* Server-backed gate for the first provider call. A configured campaign is not
+* available until this hook confirms that the idempotency key is a genuine,
+* single-use game claim.
+*/
+export type AitPromotionGrantAuthorizer = (input: AitPromotionGrantAuthorizationInput) => Promise<AitPromotionGrantAuthorization>;
 export interface InstallAitHostBridgeOptions {
   readonly appName?: string;
   readonly adGroupIds?: Readonly<Record<string, string>>;
   readonly adPlacementTypes?: Readonly<Record<string, 'rewarded' | 'interstitial'>>;
+  /** Logical campaign ids mapped to console-issued Apps in Toss promotion configuration. */
+  readonly promotionRewards?: Readonly<Record<string, AitPromotionRewardConfig>>;
+  readonly authorizePromotionGrant?: AitPromotionGrantAuthorizer;
+  readonly resolvePendingPromotionGrant?: AitPendingPromotionGrantResolver;
+  /** Logical notification topics mapped to approved Apps in Toss template codes. */
+  readonly notificationTemplateCodes?: Partial<Readonly<Record<NotificationTopic, string>>>;
   /** Maximum total wait for the native show request before display is observed. */
   readonly adTimeoutMs?: number;
   /** Maximum wait to acquire the process-wide native full-screen load slot. */

package/dist/host.js

@@ -1,4 +1,4 @@
-import { getTossShareLink, getUserKeyForGame, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore, } from '@apps-in-toss/web-framework';
+import { getTossShareLink, getUserKeyForGame, grantPromotionRewardForGame as grantPromotionReward, isMinVersionSupported, loadFullScreenAd, openGameCenterLeaderboard, requestNotificationAgreement, share, showFullScreenAd, Storage, submitGameCenterLeaderBoardScore, } from '@apps-in-toss/web-framework';
 import { assertBridgeRequest, bridgeStorageLoadProtocol, } from '@mpgd/bridge';
 import { dispatchAitLifecycleEvent } from './lifecycle.js';
 const defaultAdTimeoutMs = 60000;
@@ -7,6 +7,14 @@ const defaultAdDisplayStartTimeoutMs = 60000;
 const defaultAdMaximumDisplayMs = 30 * 60000;
 const invalidBridgeRequestId = 'ait-invalid-request';
 const rewardedAdEvidenceSchema = 'apps-in-toss.rewarded-ad.callback.v1';
+const minimumPromotionTossAppVersion = '5.232.0';
+const promotionGrantStoragePrefix = 'mpgd:ait:promotion-grant:v1:';
+const defaultNotificationAgreementTimeoutMs = 120000;
+const notificationTopics = new Set([
+    'daily-ready',
+    'streak-at-risk',
+    'friend-challenge',
+]);
 const launchEntries = new Set([
     'home',
     'daily',
@@ -21,6 +29,8 @@ const defaultDependencies = {
     storage: Storage,
     getTossShareLink,
     share,
+    grantPromotionReward,
+    requestNotificationAgreement,
     isMinVersionSupported,
     loadFullScreenAd,
     showFullScreenAd,
@@ -37,6 +47,12 @@ export function createAitHostBridge(options = {}) {
     const appName = normalizeAppName(options.appName ?? 'mpgd-kit');
     const adGroupIds = normalizeAdGroupIds(options.adGroupIds);
     const adPlacementTypes = normalizeAdPlacementTypes(options.adPlacementTypes);
+    const promotionRewards = normalizePromotionRewards(options.promotionRewards);
+    const authorizePromotionGrant = options.authorizePromotionGrant;
+    const resolvePendingPromotionGrant = options.resolvePendingPromotionGrant;
+    const notificationTemplateCodes = normalizeNotificationTemplateCodes(options.notificationTemplateCodes);
+    const promotionGrantsInFlight = new Map();
+    const notificationSubscriptions = new Set();
     const loadedAdGroupIds = new Set();
     const loadingAdGroups = new Map();
     const activeAdGroupIds = new Set();
@@ -111,9 +127,67 @@ export function createAitHostBridge(options = {}) {
             case 'share.readInboundShare':
                 return ok(request, readInboundShare());
             case 'notifications.getStatus':
-                return ok(request, 'unsupported');
-            case 'notifications.requestSubscription':
-                return ok(request, 'unavailable');
+                return ok(request, getNotificationStatus(readNotificationTopic(request.payload), notificationTemplateCodes, notificationSubscriptions, dependencies));
+            case 'notifications.requestSubscription': {
+                const topic = readNotificationTopic(request.payload);
+                const templateCode = notificationTemplateCodes.get(topic);
+                if (templateCode === undefined
+                    || !isCapabilitySupported(() => dependencies.requestNotificationAgreement.isSupported())) {
+                    return ok(request, 'unavailable');
+                }
+                const result = await requestAitNotificationAgreement(dependencies.requestNotificationAgreement, templateCode);
+                if (result === 'subscribed') {
+                    notificationSubscriptions.add(topic);
+                }
+                return ok(request, result);
+            }
+            case 'promotions.getAvailability': {
+                const campaignId = readCampaignId(request.payload);
+                const availability = getPromotionAvailability(campaignId, promotionRewards, authorizePromotionGrant, dependencies);
+                return ok(request, availability);
+            }
+            case 'promotions.grantReward': {
+                const campaignId = readCampaignId(request.payload);
+                const reward = promotionRewards.get(campaignId);
+                const idempotencyKey = readRequiredIdempotencyKey(request.payload);
+                if (reward === undefined
+                    || !isPromotionSupported(dependencies)) {
+                    return ok(request, { status: 'unavailable' });
+                }
+                const persisted = await resolvePersistedPromotionGrant({
+                    campaignId,
+                    idempotencyKey,
+                    storage: dependencies.storage,
+                    ...(resolvePendingPromotionGrant === undefined
+                        ? {}
+                        : { resolver: resolvePendingPromotionGrant }),
+                });
+                if (persisted.result !== undefined) {
+                    return ok(request, persisted.result);
+                }
+                const existing = promotionGrantsInFlight.get(idempotencyKey);
+                if (existing !== undefined) {
+                    return ok(request, await existing);
+                }
+                const pending = authorizeAndGrantAitPromotionReward({
+                    campaignId,
+                    idempotencyKey,
+                    reward,
+                    dependencies,
+                    ...(authorizePromotionGrant === undefined
+                        ? {}
+                        : { authorizer: authorizePromotionGrant }),
+                });
+                promotionGrantsInFlight.set(idempotencyKey, pending);
+                try {
+                    return ok(request, await pending);
+                }
+                finally {
+                    if (promotionGrantsInFlight.get(idempotencyKey) === pending) {
+                        promotionGrantsInFlight.delete(idempotencyKey);
+                    }
+                }
+            }
             // IAP must be installed with game-owned server verification. Never return demo grants.
             case 'commerce.getProducts':
                 return ok(request, []);
@@ -228,6 +302,227 @@ export function createAitHostBridge(options = {}) {
         }
     }
 }
+function getNotificationStatus(topic, templateCodes, subscriptions, dependencies) {
+    if (!templateCodes.has(topic)) {
+        return 'configuration-required';
+    }
+    if (!isCapabilitySupported(() => dependencies.requestNotificationAgreement.isSupported())) {
+        return 'unsupported';
+    }
+    return subscriptions.has(topic) ? 'subscribed' : 'not-subscribed';
+}
+function requestAitNotificationAgreement(requestAgreement, templateCode) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let cleanup = () => { };
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            globalThis.clearTimeout(timer);
+            cleanup();
+            resolve(result);
+        };
+        const timer = globalThis.setTimeout(() => finish('unavailable'), defaultNotificationAgreementTimeoutMs);
+        try {
+            const unregister = requestAgreement({
+                options: { templateCode },
+                onEvent: ({ type }) => {
+                    finish(type === 'agreementRejected' ? 'rejected' : 'subscribed');
+                },
+                onError: () => finish('unavailable'),
+            });
+            cleanup = unregister;
+            if (settled) {
+                cleanup();
+            }
+        }
+        catch {
+            finish('unavailable');
+        }
+    });
+}
+function getPromotionAvailability(campaignId, rewards, authorizer, dependencies) {
+    if (!rewards.has(campaignId) || authorizer === undefined) {
+        return 'configuration-required';
+    }
+    return isPromotionSupported(dependencies) ? 'available' : 'unsupported';
+}
+async function authorizeAndGrantAitPromotionReward(input) {
+    if (input.authorizer === undefined) {
+        return { status: 'unavailable' };
+    }
+    let authorization;
+    try {
+        authorization = await input.authorizer({
+            campaignId: input.campaignId,
+            idempotencyKey: input.idempotencyKey,
+        });
+    }
+    catch (error) {
+        console.warn('AIT promotion grant authorization failed; keeping the claim pending.', input.campaignId, error);
+        return { status: 'pending' };
+    }
+    if (authorization.status !== 'authorized') {
+        return {
+            status: authorization.status === 'pending' ? 'pending' : 'unavailable',
+        };
+    }
+    return grantAitPromotionReward(input.dependencies, input.reward, input.idempotencyKey);
+}
+function isPromotionSupported(dependencies) {
+    return isCapabilitySupported(() => dependencies.isMinVersionSupported({
+        android: minimumPromotionTossAppVersion,
+        ios: minimumPromotionTossAppVersion,
+    }));
+}
+async function grantAitPromotionReward(dependencies, reward, idempotencyKey) {
+    const storageKey = promotionGrantStorageKey(idempotencyKey);
+    await dependencies.storage.setItem(storageKey, JSON.stringify({
+        status: 'pending',
+        pendingSince: new Date().toISOString(),
+    }));
+    try {
+        const response = await dependencies.grantPromotionReward({
+            params: {
+                promotionCode: reward.promotionCode,
+                amount: reward.amount,
+            },
+        });
+        if (isExplicitPromotionFailure(response)) {
+            return clearFailedPromotionGrant(dependencies.storage, storageKey);
+        }
+        if (!isRecord(response)
+            || typeof response.key !== 'string'
+            || response.key.trim().length === 0) {
+            // An undocumented shape is ambiguous after native dispatch. Preserve the
+            // marker so a backend resolver can determine whether a grant happened.
+            return { status: 'pending' };
+        }
+        const result = { status: 'granted', receiptKey: response.key };
+        try {
+            await dependencies.storage.setItem(storageKey, JSON.stringify(result));
+        }
+        catch (error) {
+            console.warn('AIT native promotion receipt could not be cached; keeping it terminal.', reward.promotionCode, error);
+        }
+        return result;
+    }
+    catch {
+        // Keep the pending marker. A provider error after dispatch is ambiguous and
+        // retrying the same promotion blindly can double-grant Toss points.
+        return { status: 'pending' };
+    }
+}
+function isExplicitPromotionFailure(value) {
+    if (value === 'ERROR') {
+        return true;
+    }
+    return isRecord(value)
+        && typeof value.errorCode === 'string'
+        && value.errorCode.trim().length > 0
+        && typeof value.message === 'string';
+}
+async function clearFailedPromotionGrant(storage, storageKey) {
+    try {
+        await storage.removeItem(storageKey);
+        return { status: 'failed' };
+    }
+    catch (error) {
+        console.warn('AIT failed promotion marker could not be cleared; keeping the claim pending.', storageKey, error);
+        return { status: 'pending' };
+    }
+}
+async function resolvePersistedPromotionGrant(input) {
+    const storageKey = promotionGrantStorageKey(input.idempotencyKey);
+    const serialized = await input.storage.getItem(storageKey);
+    if (serialized === null) {
+        return {};
+    }
+    let state;
+    try {
+        state = JSON.parse(serialized);
+    }
+    catch (error) {
+        console.warn('AIT persisted promotion state is unreadable; keeping the claim pending.', input.campaignId, error);
+        return { result: { status: 'pending' } };
+    }
+    if (!isRecord(state)) {
+        console.warn('AIT persisted promotion state is malformed; keeping the claim pending.', input.campaignId);
+        return { result: { status: 'pending' } };
+    }
+    try {
+        if (state.status === 'granted'
+            && typeof state.receiptKey === 'string'
+            && state.receiptKey.trim().length > 0) {
+            return { result: { status: 'granted', receiptKey: state.receiptKey } };
+        }
+        if (state.status === 'pending') {
+            const pendingSince = normalizePendingSince(state.pendingSince);
+            if (pendingSince === undefined) {
+                return { result: { status: 'pending' } };
+            }
+            if (input.resolver === undefined) {
+                return { result: { status: 'pending' } };
+            }
+            let resolution;
+            try {
+                resolution = await input.resolver({
+                    campaignId: input.campaignId,
+                    idempotencyKey: input.idempotencyKey,
+                    pendingSince,
+                });
+            }
+            catch (error) {
+                console.warn('AIT pending promotion grant resolver failed; keeping the claim pending.', input.campaignId, error);
+                return { result: { status: 'pending' } };
+            }
+            if (resolution.status === 'pending') {
+                return { result: { status: 'pending' } };
+            }
+            if (resolution.status === 'granted') {
+                if (typeof resolution.receiptKey !== 'string'
+                    || resolution.receiptKey.trim().length === 0) {
+                    return { result: { status: 'pending' } };
+                }
+                const result = { status: 'granted', receiptKey: resolution.receiptKey };
+                try {
+                    await input.storage.setItem(storageKey, JSON.stringify(result));
+                }
+                catch (error) {
+                    console.warn('AIT reconciled promotion receipt could not be cached; keeping it terminal.', input.campaignId, error);
+                }
+                return { result };
+            }
+            return removeInvalidPersistedPromotionGrant(input.storage, storageKey);
+        }
+        console.warn('AIT persisted promotion state has an unknown status; keeping the claim pending.', input.campaignId);
+        return { result: { status: 'pending' } };
+    }
+    catch (error) {
+        console.warn('AIT persisted promotion state could not be reconciled; keeping the claim pending.', input.campaignId, error);
+        return { result: { status: 'pending' } };
+    }
+}
+async function removeInvalidPersistedPromotionGrant(storage, storageKey) {
+    try {
+        await storage.removeItem(storageKey);
+        return {};
+    }
+    catch {
+        return { result: { status: 'pending' } };
+    }
+}
+function promotionGrantStorageKey(idempotencyKey) {
+    return `${promotionGrantStoragePrefix}${encodeURIComponent(idempotencyKey)}`;
+}
+function normalizePendingSince(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return undefined;
+    }
+    return Number.isFinite(Date.parse(value)) ? value : undefined;
+}
 export async function shareIntent(payload, dependencies) {
     const intent = readPayloadRecord(payload);
     if (typeof intent.text !== 'string' || typeof intent.deepLink !== 'string') {
@@ -655,6 +950,32 @@ function normalizeAdPlacementTypes(input) {
         .map(([placementId, type]) => [placementId.trim(), type])
         .filter(([placementId]) => placementId.length > 0));
 }
+function normalizePromotionRewards(input) {
+    const rewards = new Map();
+    for (const [rawCampaignId, rawReward] of Object.entries(input ?? {})) {
+        const campaignId = rawCampaignId.trim();
+        const promotionCode = rawReward.promotionCode.trim();
+        if (campaignId.length === 0 || promotionCode.length === 0) {
+            continue;
+        }
+        if (!Number.isSafeInteger(rawReward.amount) || rawReward.amount <= 0) {
+            console.warn(`AIT promotion amount must be a positive safe integer; disabling campaign: ${campaignId}`);
+            continue;
+        }
+        rewards.set(campaignId, { promotionCode, amount: rawReward.amount });
+    }
+    return rewards;
+}
+function normalizeNotificationTemplateCodes(input) {
+    const templateCodes = new Map();
+    for (const topic of notificationTopics) {
+        const templateCode = input?.[topic]?.trim();
+        if (templateCode !== undefined && templateCode.length > 0) {
+            templateCodes.set(topic, templateCode);
+        }
+    }
+    return templateCodes;
+}
 function normalizeAppName(value) {
     const normalized = value.trim();
     if (!/^[A-Za-z0-9-]+$/u.test(normalized)) {
@@ -701,6 +1022,27 @@ function readIdempotencyKey(payload, fallback) {
     const value = readPayloadRecord(payload).idempotencyKey;
     return typeof value === 'string' && value.length > 0 ? value : fallback;
 }
+function readRequiredIdempotencyKey(payload) {
+    const value = readPayloadRecord(payload).idempotencyKey;
+    if (typeof value !== 'string' || value.length === 0 || value.length > 256) {
+        throw new TypeError('AIT promotion idempotencyKey must contain 1 to 256 characters.');
+    }
+    return value;
+}
+function readCampaignId(payload) {
+    const value = readPayloadRecord(payload).campaignId;
+    if (typeof value !== 'string' || value.length === 0 || value.length > 128) {
+        throw new TypeError('AIT promotion campaignId must contain 1 to 128 characters.');
+    }
+    return value;
+}
+function readNotificationTopic(payload) {
+    const value = readPayloadRecord(payload).topic;
+    if (typeof value !== 'string' || !notificationTopics.has(value)) {
+        throw new TypeError('AIT notification topic is invalid.');
+    }
+    return value;
+}
 function readFiniteScore(payload) {
     const score = readPayloadRecord(payload).score;
     if (typeof score !== 'number' || !Number.isFinite(score)) {

package/dist/index.js

@@ -44,6 +44,10 @@ export function createAitPlatformGateway(input) {
             getStatus: (topic) => request('notifications.getStatus', { topic }),
             requestSubscription: (topic) => request('notifications.requestSubscription', { topic }),
         },
+        promotions: {
+            getAvailability: (payload) => request('promotions.getAvailability', payload),
+            grantReward: (payload) => request('promotions.grantReward', payload),
+        },
         commerce: {
             getProducts: () => request('commerce.getProducts', {}),
             purchase: (payload) => request('commerce.purchase', payload),
@@ -132,6 +136,10 @@ export function createAitSandboxBridge(options = {}) {
                     return ok(input, 'configuration-required');
                 case 'notifications.requestSubscription':
                     return ok(input, 'unavailable');
+                case 'promotions.getAvailability':
+                    return ok(input, 'configuration-required');
+                case 'promotions.grantReward':
+                    return ok(input, { status: 'unavailable' });
                 case 'commerce.getProducts':
                     return ok(input, [
                         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/adapter-ait",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Apps in Toss WebView platform adapter for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -47,11 +47,11 @@
     "dist"
   ],
   "dependencies": {
-    "@mpgd/bridge": "0.6.1",
-    "@mpgd/platform": "0.7.0"
+    "@mpgd/platform": "0.8.0",
+    "@mpgd/bridge": "0.7.0"
   },
   "peerDependencies": {
-    "@apps-in-toss/web-framework": ">=2.10.4 <3"
+    "@apps-in-toss/web-framework": ">=3.0.0-beta <4"
   },
   "peerDependenciesMeta": {
     "@apps-in-toss/web-framework": {
@@ -59,7 +59,7 @@
     }
   },
   "devDependencies": {
-    "@apps-in-toss/web-framework": "^2.10.6",
+    "@apps-in-toss/web-framework": "3.0.0-beta.da14818",
     "ttsc": "0.18.4",
     "typescript": "7.0.2",
     "vitest": "^4.0.0"