@mpgd/platform 0.9.0 → 0.11.0

package/dist/capability-conformance.d.ts

@@ -1,5 +1,6 @@
 import type { PlatformCapabilities, PlatformGateway, PlatformTarget } from './index.js';
 export declare const platformCapabilityKeys: readonly ["nativeIap", "nativeAds", "rewardedAds", "interstitialAds", "nativeLeaderboard", "remoteLeaderboard", "achievements", "cloudSave", "socialShare", "haptics", "localizedContent"];
+export declare const optionalPlatformCapabilityKeys: readonly ["bannerAds"];
 export interface PlatformGatewayCapabilityConformanceTransition {
   readonly update: () => Promise<void> | void;
   readonly expectedCapabilities: PlatformCapabilities;

package/dist/capability-conformance.js

@@ -11,6 +11,15 @@ export const platformCapabilityKeys = Object.freeze([
     'haptics',
     'localizedContent',
 ]);
+export const optionalPlatformCapabilityKeys = Object.freeze([
+    'bannerAds',
+]);
+const allowedPlatformCapabilityKeys = Object.freeze([
+    ...platformCapabilityKeys,
+    ...optionalPlatformCapabilityKeys,
+]);
+const allowedPlatformCapabilityKeySet = new Set(allowedPlatformCapabilityKeys);
+const optionalPlatformCapabilityKeySet = new Set(optionalPlatformCapabilityKeys);
 /**
  * Runs provider-neutral capability checks against real adapter gateways or
  * target-configured wrappers. Every read must return a complete boolean
@@ -61,11 +70,15 @@ async function runFixture(fixture) {
 }
 function assertCapabilitySnapshot(actual, expected) {
     const actualKeys = Object.keys(actual).sort();
-    const expectedKeys = [...platformCapabilityKeys].sort();
-    assertEqual(JSON.stringify(actualKeys), JSON.stringify(expectedKeys), 'capability snapshots must contain exactly the public capability keys');
-    for (const key of platformCapabilityKeys) {
-        assertEqual(typeof actual[key], 'boolean', `capability ${key} must be a boolean`);
-        assertEqual(actual[key], expected[key], `capability ${key} must match the expected provider state`);
+    const missingKeys = platformCapabilityKeys.filter((key) => !Object.hasOwn(actual, key));
+    const unexpectedKeys = actualKeys.filter((key) => !allowedPlatformCapabilityKeySet.has(key));
+    assertEqual(JSON.stringify({ missingKeys, unexpectedKeys }), JSON.stringify({ missingKeys: [], unexpectedKeys: [] }), 'capability snapshots must contain all required keys and no unknown keys');
+    for (const key of allowedPlatformCapabilityKeys) {
+        const optional = optionalPlatformCapabilityKeySet.has(key);
+        if (!optional || Object.hasOwn(actual, key)) {
+            assertEqual(typeof actual[key], 'boolean', `capability ${key} must be a boolean`);
+        }
+        assertEqual(optional ? (actual[key] ?? false) : actual[key], optional ? (expected[key] ?? false) : expected[key], `capability ${key} must match the expected provider state`);
     }
 }
 function tryMutateSnapshot(snapshot) {
@@ -77,7 +90,8 @@ function tryMutateSnapshot(snapshot) {
     }
 }
 function hasCapabilityDifference(first, second) {
-    return platformCapabilityKeys.some((key) => first[key] !== second[key]);
+    return allowedPlatformCapabilityKeys
+        .some((key) => (first[key] ?? false) !== (second[key] ?? false));
 }
 function assert(condition, message) {
     if (!condition) {

package/dist/index.d.ts

@@ -24,6 +24,28 @@ export interface PlatformEvidenceEnvelope {
   readonly schema: string;
   readonly payload: Readonly<Record<string, string | number | boolean>>;
 }
+export interface PlatformOperationFailure {
+  readonly code: string;
+  readonly retryable: boolean;
+}
+/**
+* Provider-neutral error raised when a platform bridge rejects an operation.
+*
+* Adapters preserve a stable, non-sensitive code and retry hint so game UI can
+* distinguish configuration, environment, and transient failures without
+* importing a provider SDK or parsing localized error messages.
+*/
+export declare class PlatformOperationError extends Error implements PlatformOperationFailure {
+  readonly name = "PlatformOperationError";
+  readonly code: string;
+  readonly retryable: boolean;
+  constructor(input?: Readonly<{
+    readonly code?: unknown;
+    readonly message?: unknown;
+    readonly retryable?: unknown;
+  }>);
+}
+export declare function readPlatformOperationFailure(error: unknown): PlatformOperationFailure | null;
 export interface PurchaseResult {
   readonly status: 'completed' | 'cancelled' | 'pending' | 'failed';
   readonly transactionId?: string;
@@ -47,6 +69,16 @@ export interface RewardedAdResult {
 export interface InterstitialAdResult {
   readonly status: 'shown' | 'skipped' | 'unavailable';
 }
+/**
+* Result of mounting a platform-rendered inline banner into a game-owned surface.
+* The platform host owns the native/SDK attachment; games only reserve and name
+* a surface, so this contract does not leak DOM or provider types. Adapters must
+* release any partial attachment before resolving `unavailable` or `failed`;
+* games only need to unmount a successfully mounted banner.
+*/
+export interface BannerAdMountResult {
+  readonly status: 'mounted' | 'unavailable' | 'failed';
+}
 export interface CommerceAdapter {
   getProducts(): Promise<readonly ProductInfo[]>;
   purchase(input: {
@@ -68,6 +100,14 @@ export interface AdAdapter {
   showInterstitial?(input: {
     readonly placementId: LogicalAdPlacementId;
   }): Promise<InterstitialAdResult>;
+  mountBanner?(input: {
+    readonly placementId: LogicalAdPlacementId;
+    /** Host-resolvable identifier for an empty, game-owned inline ad surface. */
+    readonly surfaceId: string;
+  }): Promise<BannerAdMountResult>;
+  unmountBanner?(input: {
+    readonly surfaceId: string;
+  }): Promise<void>;
 }
 export type PromotionRewardAvailability = 'available' | 'configuration-required' | 'unsupported';
 export type PromotionRewardResult = {
@@ -115,6 +155,8 @@ export interface PlatformCapabilities {
   readonly nativeAds: boolean;
   readonly rewardedAds: boolean;
   readonly interstitialAds: boolean;
+  /** Optional for compatibility with adapters published before inline ads. */
+  readonly bannerAds?: boolean;
   readonly nativeLeaderboard: boolean;
   /** A game-owned server leaderboard is available without a native platform surface. */
   readonly remoteLeaderboard: boolean;

package/dist/index.js

@@ -1,3 +1,46 @@
+/**
+ * Provider-neutral error raised when a platform bridge rejects an operation.
+ *
+ * Adapters preserve a stable, non-sensitive code and retry hint so game UI can
+ * distinguish configuration, environment, and transient failures without
+ * importing a provider SDK or parsing localized error messages.
+ */
+export class PlatformOperationError extends Error {
+    name = 'PlatformOperationError';
+    code;
+    retryable;
+    constructor(input) {
+        const diagnostics = input ?? {};
+        super(typeof diagnostics.message === 'string'
+            ? diagnostics.message
+            : 'The platform operation failed.');
+        this.code = normalizePlatformOperationCode(diagnostics.code);
+        this.retryable = diagnostics.retryable === true;
+    }
+}
+export function readPlatformOperationFailure(error) {
+    if (error instanceof PlatformOperationError) {
+        return { code: error.code, retryable: error.retryable };
+    }
+    if (typeof error !== 'object' || error === null || Array.isArray(error)) {
+        return null;
+    }
+    const record = error;
+    return typeof record.code === 'string'
+        && isPlatformOperationCode(record.code)
+        && typeof record.retryable === 'boolean'
+        ? { code: record.code, retryable: record.retryable }
+        : null;
+}
+function normalizePlatformOperationCode(code) {
+    return isPlatformOperationCode(code) ? code : 'PLATFORM_OPERATION_FAILED';
+}
+function isPlatformOperationCode(code) {
+    return typeof code === 'string'
+        && code.length > 0
+        && code.length <= 128
+        && /^[A-Z][A-Z0-9_:-]*$/u.test(code);
+}
 export function resolveShareCompletion(result) {
     if (result.status !== 'shared') {
         return undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/platform",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Shared platform gateway, monetization, ads, leaderboard, identity, lifecycle, and storage contracts for mpgd games.",
   "license": "MIT",
   "repository": {