@mpgd/platform 0.22.0 → 0.23.1

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import type { AdProvider } from './ads.js';
 import type { CommerceProvider } from './commerce-contract.js';
+import { createUnsupportedCommerceCapabilities } from './commerce-capabilities.js';
+import type { NotificationCapabilities, NotificationProvider } from './notifications-contract.js';
+export { createUnsupportedCommerceCapabilities };
 export type PlatformTarget = 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'crazygames' | 'oneplay' | 'telegram' | 'tauri' | 'wechat' | 'tiktok';
 export type StarterLogicalProductId = 'COINS_100' | 'COINS_500' | 'REMOVE_ADS';
 export type LogicalProductId = StarterLogicalProductId | (string & Record<never, never>);
@@ -57,12 +60,23 @@ export interface CommerceDiagnostic extends PlatformOperationFailure {
   /** Provider SDK error code, passed through only when it is a safe identifier. */
   readonly providerCode?: string;
 }
+/**
+* Purchase result vocabulary of the adapter engines and of
+* `GameServicesPurchaseResult.purchase`. It is no gateway surface: a gateway
+* sells through `PlatformGateway.commerce`, and nothing here is ever an input
+* to a grant.
+*/
 export interface PurchaseResult {
   readonly status: 'completed' | 'cancelled' | 'pending' | 'failed';
   readonly transactionId?: string;
   readonly entitlementIds: readonly string[];
   readonly evidence?: PlatformEvidenceEnvelope;
-  /** Present only when the adapter already completed the authoritative server grant. */
+  /**
+  * An adapter engine's record that its own authority already wrote a ledger
+  * entry. Informational only: no client code reads it to grant, and a
+  * provider's `settlement` pointer is verified through the backend by the
+  * reconciler like any other evidence.
+  */
   readonly authoritativeGrant?: Readonly<{
     readonly ledgerEntryId: string;
     readonly alreadyProcessed?: boolean;
@@ -86,19 +100,6 @@ export interface PurchaseSettlement {
   /** Client purchase idempotency key the order was started with, when the adapter can link it. */
   readonly idempotencyKey?: string;
 }
-/**
-* Resolve a specific purchase from authoritative checkout or restore evidence.
-* A completed native checkout without authoritativeGrant is still unconfirmed.
-* This is UI status evidence, never permission to credit a wallet locally.
-* The caller must pair `purchase` with its requested `productId` because
-* PurchaseResult itself does not carry a product identifier.
-*/
-export declare function findAuthoritativePurchaseSettlement(input: {
-  readonly productId: LogicalProductId;
-  readonly transactionId?: string;
-  readonly purchase?: PurchaseResult;
-  readonly restore?: PurchaseRestoreResult;
-}): PurchaseSettlement | null;
 export interface RewardedAdResult {
   readonly status: 'completed' | 'pending' | 'skipped' | 'unavailable' | 'failed';
   readonly rewardGranted: boolean;
@@ -123,20 +124,6 @@ export interface PlatformPurchasePresentationEvent {
   readonly sequence: number;
   readonly state: 'open' | 'closed' | 'not-started' | 'unknown';
 }
-export interface CommerceAdapter {
-  /** Trusted native presentation facts, independent of the purchase grant result. */
-  readonly presentation?: {
-    subscribe(listener: (event: PlatformPurchasePresentationEvent) => void): () => void;
-  };
-  getProducts(): Promise<readonly ProductInfo[]>;
-  purchase(input: {
-    readonly productId: LogicalProductId;
-    readonly source: 'shop' | 'stage_fail' | 'result' | 'event';
-    readonly idempotencyKey: string;
-  }): Promise<PurchaseResult>;
-  restore?(): Promise<PurchaseRestoreResult>;
-  getEntitlements(): Promise<readonly Entitlement[]>;
-}
 export interface AdAdapter {
   /** Optional versioned provider surface; v1 methods remain compatible. */
   readonly provider?: AdProvider;
@@ -208,7 +195,7 @@ export interface LeaderboardAdapter {
 /** Readiness of an installed platform provider, independent of target policy. */
 export type PlatformProviderAvailability = 'unsupported' | 'configuration-required' | 'action-required' | 'temporarily-unavailable' | 'available';
 /** Existing capabilities and integrations annotated by optional providers. */
-export type PlatformProviderFeature = 'nativeIap' | 'subscriptionIap' | 'rewardedAds' | 'interstitialAds' | 'bannerAds' | 'nativeLeaderboard' | 'identityUpgrade' | 'pushNotifications';
+export type PlatformProviderFeature = 'rewardedAds' | 'interstitialAds' | 'bannerAds' | 'nativeLeaderboard' | 'identityUpgrade' | 'pushNotifications';
 export type CommerceFinishOwner = 'client' | 'server' | 'host' | 'none';
 export type CommerceEvidenceAuthority = 'client-token' | 'host-callback' | 'adapter-settled' | 'server-push';
 export type CommerceAccountBindingPolicy = 'required' | 'optional' | 'host';
@@ -249,9 +236,6 @@ export interface CommerceCapabilities {
   readonly availability: PlatformProviderAvailability;
 }
 export interface PlatformCapabilities {
-  readonly nativeIap: boolean;
-  /** Optional for adapters published before subscription-specific support. */
-  readonly subscriptionIap?: boolean;
   readonly nativeAds: boolean;
   readonly rewardedAds: boolean;
   readonly interstitialAds: boolean;
@@ -268,11 +252,23 @@ export interface PlatformCapabilities {
   /** Explains a false capability without claiming an unavailable SDK works. */
   readonly providerAvailability?: Readonly<Partial<Record<PlatformProviderFeature, PlatformProviderAvailability>>>;
   /**
-  * Optional commerce v2 capability block. When present it must be a fresh
-  * object on every read with no unknown keys, and `nativeIap` and
-  * `subscriptionIap` must equal `deriveLegacyCommerceCapabilities(commerce)`.
+  * The one source of commerce capabilities: what the gateway's commerce
+  * provider sells, who finishes a purchase, and what evidence authorizes a
+  * grant. A gateway without a commerce provider reports
+  * `createUnsupportedCommerceCapabilities()`. The block must be a fresh object
+  * on every read with no unknown keys.
   */
-  readonly commerce?: CommerceCapabilities;
+  readonly commerce: CommerceCapabilities;
+  /**
+  * Optional notifications v2 capability block of the `notificationsV2`
+  * provider the gateway exposes: present exactly when the gateway exposes
+  * one, raw adapters included. `withTargetAvailability` in
+  * `@mpgd/target-config` adds it from that provider and leaves it out while
+  * the provider is hidden. When present it must be a fresh object on every
+  * read with no unknown keys, and `providerAvailability.pushNotifications`
+  * must equal its `availability`.
+  */
+  readonly notifications?: NotificationCapabilities;
 }
 export interface PlayerIdentity {
   readonly playerId: string;
@@ -317,6 +313,18 @@ export interface ShareIntent {
   readonly kind: 'daily-result' | 'friend-challenge' | 'invite';
   readonly title: string;
   readonly text: string;
+  /**
+  * A root-relative link on the game's origin (`/daily?challengeToken=…`) or an
+  * absolute `https://` (or `http://`) link. Every adapter whose host builds or
+  * receives a share URL checks it with `normalizeShareLink` from
+  * `@mpgd/platform/routes`, most through that module's `withShareIntentCheck`,
+  * hands the host the normalized link, and answers `unavailable` when the rule
+  * refuses it: a link that could name another host, contains a control
+  * character, or has another form, such as a page-relative link. Apps in Toss
+  * also accepts its own `intoss://<app>` links. An adapter whose host shares
+  * no link ignores it: WeChat's card reopens the game with `query` built from
+  * `kind` and `payload`.
+  */
   readonly deepLink: string;
   readonly payload?: SharePayload;
   readonly previewImageUrl?: string;
@@ -357,6 +365,18 @@ export interface NotificationSubscriptionAdapter {
 export interface NativeOpenUrlEvent {
   readonly url: string;
   readonly source: 'cold' | 'warm';
+  /**
+  * For a game link, the URL's path, query, and fragment, normalized with
+  * `normalizeRootRelativeRoute` from `@mpgd/platform/routes`. The host is not
+  * part of it: `mygame://game/daily` and `https://game.example/daily` give
+  * `/daily`, and `mygame://level/3` gives `/3`. Adapters do not deliver a game
+  * link whose path that rule refuses, so a router that routes by path opens
+  * this route as is. It is absent when the URL has no path to check, such as
+  * `mygame:daily` or `mygame://daily`. A router that builds its route from
+  * anything else in the URL, such as a custom-scheme host, checks that route
+  * with `normalizeRootRelativeRoute` and opens only what it returns.
+  */
+  readonly route?: string;
 }
 export interface NativeBackButtonEvent {
   /** Whether the WebView history can navigate back, not the game's own scene stack. */
@@ -413,7 +433,11 @@ export interface LifecycleAdapter {
   * are not guaranteed to run before process termination.
   */
   onBackButton?(handler: (event: NativeBackButtonEvent) => boolean | Promise<boolean>): () => void;
-  /** Game links and OAuth redirects use separate callbacks. */
+  /**
+  * Game links and OAuth redirects use separate callbacks. A game link is
+  * untrusted input: open its checked `route`, or check any route built from
+  * `url` with `normalizeRootRelativeRoute` (see `NativeOpenUrlEvent.route`).
+  */
   onGameUrlOpen?(callback: (event: NativeOpenUrlEvent) => void): () => void;
   onOAuthRedirect?(callback: (event: NativeOpenUrlEvent) => void): () => void;
   getInitialGameUrl?(): Promise<NativeOpenUrlEvent | null>;
@@ -481,14 +505,14 @@ export interface PlatformGateway {
   readonly gameLoading?: GameLoadingAdapter;
   getCapabilities(): Promise<PlatformCapabilities>;
   readonly identity: IdentityAdapter;
-  readonly commerce: CommerceAdapter;
   /**
-  * Optional commerce v2 provider (`@mpgd/platform/commerce`). Transitional:
-  * adapters expose it next to the v1 `commerce` adapter until C4 removes v1,
-  * and the game-services reconciler (C1) prefers it when present. Absent on
-  * gateways whose target has no v2 provider.
+  * The commerce provider (`@mpgd/platform/commerce`), the only commerce
+  * surface of a gateway. Games purchase through `@mpgd/game-services`, whose
+  * reconciler drives it; a scene never calls it directly. Absent on gateways
+  * whose target sells nothing, which then report
+  * `createUnsupportedCommerceCapabilities()`.
   */
-  readonly commerceV2?: CommerceProvider;
+  readonly commerce?: CommerceProvider;
   readonly ads: AdAdapter;
   readonly leaderboard: LeaderboardAdapter;
   readonly lifecycle: LifecycleAdapter;
@@ -499,6 +523,19 @@ export interface PlatformGateway {
   readonly presentation?: PresentationAdapter;
   readonly sharing?: ShareAdapter;
   readonly notifications?: NotificationSubscriptionAdapter;
+  /**
+  * Optional notifications v2 provider (`@mpgd/platform/notifications`).
+  * Transitional: adapters expose it next to the v1 `notifications` adapter
+  * until the major release that removes v1. Games do not call it directly:
+  * the game-services client composes it with the backend into the
+  * notifications runtime, and `toNotificationSubscriptionAdapter` serves v1
+  * callers from that runtime with the topics resolved for the target. Absent
+  * on gateways whose target has no v2 provider. `withTargetAvailability` in
+  * `@mpgd/target-config` exposes it only while `integrations.notifications`
+  * lets the game call notifications, as it does the v1 adapter, and then
+  * adds `PlatformCapabilities.notifications` from it.
+  */
+  readonly notificationsV2?: NotificationProvider;
   readonly promotions?: PromotionRewardAdapter;
   readonly gameActivity?: GameActivityAdapter;
   readonly gameSettings?: GameSettingsAdapter;

package/dist/index.js

@@ -1,3 +1,5 @@
+import { createUnsupportedCommerceCapabilities } from './commerce-capabilities.js';
+export { createUnsupportedCommerceCapabilities };
 /**
  * Provider-neutral error raised when a platform bridge rejects an operation.
  *
@@ -41,41 +43,6 @@ function isPlatformOperationCode(code) {
         && code.length <= 128
         && /^[A-Z][A-Z0-9_:-]*$/u.test(code);
 }
-/**
- * Resolve a specific purchase from authoritative checkout or restore evidence.
- * A completed native checkout without authoritativeGrant is still unconfirmed.
- * This is UI status evidence, never permission to credit a wallet locally.
- * The caller must pair `purchase` with its requested `productId` because
- * PurchaseResult itself does not carry a product identifier.
- */
-export function findAuthoritativePurchaseSettlement(input) {
-    const effectiveTransactionId = input.transactionId ?? input.purchase?.transactionId;
-    const matchingRestored = input.restore?.settledPurchases?.filter((settlement) => settlement.productId === input.productId
-        && (effectiveTransactionId === undefined || settlement.transactionId === effectiveTransactionId));
-    // Without an order ID, multiple historical outcomes are ambiguous.
-    if (matchingRestored !== undefined && matchingRestored.length > 1) {
-        return null;
-    }
-    if (matchingRestored?.[0] !== undefined) {
-        return matchingRestored[0];
-    }
-    const purchase = input.purchase;
-    if (purchase?.status !== 'completed'
-        || purchase.transactionId === undefined
-        || purchase.authoritativeGrant === undefined
-        || (effectiveTransactionId !== undefined && effectiveTransactionId !== purchase.transactionId)) {
-        return null;
-    }
-    return {
-        transactionId: purchase.transactionId,
-        productId: input.productId,
-        status: 'granted',
-        ledgerEntryId: purchase.authoritativeGrant.ledgerEntryId,
-        ...(purchase.authoritativeGrant.alreadyProcessed === undefined
-            ? {}
-            : { alreadyProcessed: purchase.authoritativeGrant.alreadyProcessed }),
-    };
-}
 export function resolveShareCompletion(result) {
     if (result.status !== 'shared') {
         return undefined;
@@ -87,7 +54,6 @@ export function isShareCompleted(result) {
 }
 export function createUnsupportedCapabilities() {
     return {
-        nativeIap: false,
         nativeAds: false,
         rewardedAds: false,
         interstitialAds: false,
@@ -98,5 +64,6 @@ export function createUnsupportedCapabilities() {
         socialShare: false,
         haptics: false,
         localizedContent: false,
+        commerce: createUnsupportedCommerceCapabilities(),
     };
 }