@mpgd/platform 0.12.1 → 0.12.2

package/dist/capability-conformance.d.ts

@@ -26,5 +26,11 @@ export interface PlatformGatewayCapabilityConformanceReport {
 * Runs provider-neutral capability checks against real adapter gateways or
 * target-configured wrappers. Every read must return a complete boolean
 * snapshot, a fresh object, and the provider's latest state.
+* @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #f83948b Reviewed the required keys, optional banner default, and fresh reread in runFixture.
+* @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
+* @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.
+* @evidenceReview docs/specs/platform-capability-snapshots.md#fixture-validation #d566052 Checked the nonempty and unique name guards and target assertion.
 */
 export declare function runPlatformGatewayCapabilityConformance(input: RunPlatformGatewayCapabilityConformanceInput): Promise<PlatformGatewayCapabilityConformanceReport>;

package/dist/capability-conformance.js

@@ -24,6 +24,12 @@ 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
  * snapshot, a fresh object, and the provider's latest state.
+ * @evidence docs/specs/platform-capability-snapshots.md#snapshot-shape Checks each gateway read against the required boolean keys and expected provider state.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#snapshot-shape #f83948b Reviewed the required keys, optional banner default, and fresh reread in runFixture.
+ * @evidence docs/specs/platform-capability-snapshots.md#provider-transitions Checks a fresh provider read after the optional transition update.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#provider-transitions #839c0c8 Reviewed the changed-state guard and post-update snapshot assertion.
+ * @evidence docs/specs/platform-capability-snapshots.md#fixture-validation Rejects invalid fixture sets and returns the names of passing fixtures.
+ * @evidenceReview docs/specs/platform-capability-snapshots.md#fixture-validation #d566052 Checked the nonempty and unique name guards and target assertion.
  */
 export async function runPlatformGatewayCapabilityConformance(input) {
     if (input.fixtures.length === 0) {
@@ -52,21 +58,28 @@ export async function runPlatformGatewayCapabilityConformance(input) {
     return { passedFixtures };
 }
 async function runFixture(fixture) {
+    // A fixture may accidentally share its expected object with the provider.
+    // Keep the oracle independent before tryMutateSnapshot probes isolation.
+    const initialExpected = { ...fixture.expectedCapabilities };
+    const transitionExpected = fixture.transition === undefined
+        ? undefined
+        : { ...fixture.transition.expectedCapabilities };
     assertEqual(fixture.gateway.target, fixture.expectedTarget, 'gateway target must match the fixture target');
     const first = await fixture.gateway.getCapabilities();
-    assertCapabilitySnapshot(first, fixture.expectedCapabilities);
+    assertCapabilitySnapshot(first, initialExpected);
     tryMutateSnapshot(first);
     const second = await fixture.gateway.getCapabilities();
     assert(second !== first, 'getCapabilities must return a fresh snapshot object for every read');
-    assertCapabilitySnapshot(second, fixture.expectedCapabilities);
-    if (fixture.transition === undefined) {
+    assertCapabilitySnapshot(second, initialExpected);
+    if (fixture.transition === undefined || transitionExpected === undefined) {
         return;
     }
-    assert(hasCapabilityDifference(fixture.expectedCapabilities, fixture.transition.expectedCapabilities), 'a transition fixture must change at least one capability');
+    assert(hasCapabilityDifference(initialExpected, transitionExpected), 'a transition fixture must change at least one capability');
     await fixture.transition.update();
     const updated = await fixture.gateway.getCapabilities();
     assert(updated !== second, 'getCapabilities must return a fresh snapshot after a provider transition');
-    assertCapabilitySnapshot(updated, fixture.transition.expectedCapabilities);
+    assert(updated !== first, 'getCapabilities must not reuse an earlier snapshot after a provider transition');
+    assertCapabilitySnapshot(updated, transitionExpected);
 }
 function assertCapabilitySnapshot(actual, expected) {
     const actualKeys = Object.keys(actual).sort();

package/dist/index.d.ts

@@ -59,7 +59,29 @@ export interface PurchaseResult {
 }
 export interface PurchaseRestoreResult {
   readonly restoredEntitlements: readonly Entitlement[];
+  /** Server-confirmed consumable outcomes; native order visibility alone is not a grant. */
+  readonly settledPurchases?: readonly PurchaseSettlement[];
 }
+export interface PurchaseSettlement {
+  readonly transactionId: string;
+  readonly productId: LogicalProductId;
+  readonly status: 'granted' | 'refunded';
+  readonly ledgerEntryId?: string;
+  readonly alreadyProcessed?: boolean;
+}
+/**
+* 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' | 'skipped' | 'unavailable' | 'failed';
   readonly rewardGranted: boolean;

package/dist/index.js

@@ -41,6 +41,41 @@ 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;

package/package.json

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