@mpgd/platform 0.6.0 → 0.7.0

package/dist/capability-conformance.d.ts

@@ -0,0 +1,29 @@
+import type { PlatformCapabilities, PlatformGateway, PlatformTarget } from './index.js';
+export declare const platformCapabilityKeys: readonly ["nativeIap", "nativeAds", "rewardedAds", "interstitialAds", "nativeLeaderboard", "achievements", "cloudSave", "socialShare", "haptics", "localizedContent"];
+export interface PlatformGatewayCapabilityConformanceTransition {
+  readonly update: () => Promise<void> | void;
+  readonly expectedCapabilities: PlatformCapabilities;
+}
+export interface PlatformGatewayCapabilityConformanceFixture {
+  readonly name: string;
+  readonly gateway: PlatformGateway;
+  readonly expectedTarget: PlatformTarget;
+  readonly expectedCapabilities: PlatformCapabilities;
+  /**
+  * Optional provider transition used to prove that capability reads are live
+  * rather than permanently cached by an adapter or target-config wrapper.
+  */
+  readonly transition?: PlatformGatewayCapabilityConformanceTransition;
+}
+export interface RunPlatformGatewayCapabilityConformanceInput {
+  readonly fixtures: readonly PlatformGatewayCapabilityConformanceFixture[];
+}
+export interface PlatformGatewayCapabilityConformanceReport {
+  readonly passedFixtures: readonly string[];
+}
+/**
+* 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.
+*/
+export declare function runPlatformGatewayCapabilityConformance(input: RunPlatformGatewayCapabilityConformanceInput): Promise<PlatformGatewayCapabilityConformanceReport>;

package/dist/capability-conformance.js

@@ -0,0 +1,90 @@
+export const platformCapabilityKeys = Object.freeze([
+    'nativeIap',
+    'nativeAds',
+    'rewardedAds',
+    'interstitialAds',
+    'nativeLeaderboard',
+    'achievements',
+    'cloudSave',
+    'socialShare',
+    'haptics',
+    'localizedContent',
+]);
+/**
+ * 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.
+ */
+export async function runPlatformGatewayCapabilityConformance(input) {
+    if (input.fixtures.length === 0) {
+        throw new Error('Platform gateway capability conformance requires at least one fixture.');
+    }
+    const fixtureNames = new Set();
+    const passedFixtures = [];
+    for (const fixture of input.fixtures) {
+        if (fixture.name.trim().length === 0) {
+            throw new Error('Platform capability conformance fixture names must not be empty.');
+        }
+        if (fixtureNames.has(fixture.name)) {
+            throw new Error(`Duplicate platform capability conformance fixture: ${fixture.name}.`);
+        }
+        fixtureNames.add(fixture.name);
+        try {
+            await runFixture(fixture);
+        }
+        catch (error) {
+            throw new Error(`Platform gateway capability conformance failed: ${fixture.name}.`, {
+                cause: error,
+            });
+        }
+        passedFixtures.push(fixture.name);
+    }
+    return { passedFixtures };
+}
+async function runFixture(fixture) {
+    assertEqual(fixture.gateway.target, fixture.expectedTarget, 'gateway target must match the fixture target');
+    const first = await fixture.gateway.getCapabilities();
+    assertCapabilitySnapshot(first, fixture.expectedCapabilities);
+    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) {
+        return;
+    }
+    assert(hasCapabilityDifference(fixture.expectedCapabilities, fixture.transition.expectedCapabilities), '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);
+}
+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`);
+    }
+}
+function tryMutateSnapshot(snapshot) {
+    try {
+        Reflect.set(snapshot, 'nativeIap', !snapshot.nativeIap);
+    }
+    catch {
+        // Frozen snapshots already satisfy the isolation requirement.
+    }
+}
+function hasCapabilityDifference(first, second) {
+    return platformCapabilityKeys.some((key) => first[key] !== second[key]);
+}
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+function assertEqual(actual, expected, message) {
+    if (actual !== expected) {
+        throw new Error(`${message}. Expected ${String(expected)}, received ${String(actual)}.`);
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type PlatformTarget = 'browser' | 'android' | 'ios' | 'ait' | 'reddit' | 'telegram' | 'tauri';
+export type PlatformTarget = 'browser' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'telegram' | 'tauri';
 export type StarterLogicalProductId = 'COINS_100' | 'COINS_500' | 'REMOVE_ADS';
 export type LogicalProductId = StarterLogicalProductId | (string & Record<never, never>);
 export type StarterLogicalAdPlacementId = 'CONTINUE_AFTER_FAIL' | 'STAGE_END_INTERSTITIAL';
@@ -182,6 +182,7 @@ export interface StorageAdapter {
   load(input: {
     readonly key: string;
   }): Promise<StorageLoadResult | null>;
+  /** Persist a JSON-serializable value or reject without replacing the prior value. */
   save(input: {
     readonly key: string;
     readonly value: unknown;

package/dist/storage-conformance.d.ts

@@ -0,0 +1,37 @@
+import type { StorageAdapter } from './index.js';
+export declare const storageAdapterConformanceScenarios: readonly ['missing-read', 'round-trip-and-overwrite', 'storage-scope-isolation', 'mutation-isolation', 'quota-rejection-preserves-value', 'save-failure-is-fail-closed', 'load-failure-is-fail-closed'];
+export type StorageAdapterConformanceScenario = (typeof storageAdapterConformanceScenarios)[number];
+export interface CreateStorageAdapterConformanceFixtureInput {
+  readonly scenario: StorageAdapterConformanceScenario;
+}
+export interface StorageAdapterConformanceFixture {
+  /** Storage area under test. */
+  readonly storage: StorageAdapter;
+  /**
+  * A distinct account, namespace, browser profile, or equivalent storage
+  * scope backed by the same kind of provider.
+  */
+  readonly isolatedStorage: StorageAdapter;
+  /** A value that the fixture's configured provider quota must reject. */
+  readonly oversizedValue: unknown;
+  /** Fail the next primary-scope save before it becomes visible. */
+  readonly armNextSaveFailure: () => void;
+  /** Fail the next primary-scope load instead of reporting a missing value. */
+  readonly armNextLoadFailure: () => void;
+  readonly dispose?: () => Promise<void> | void;
+}
+export type CreateStorageAdapterConformanceFixture = (input: CreateStorageAdapterConformanceFixtureInput) => Promise<StorageAdapterConformanceFixture> | StorageAdapterConformanceFixture;
+export interface RunStorageAdapterConformanceInput {
+  /** Return an isolated fixture, or a uniquely namespaced fixture, per scenario. */
+  readonly createFixture: CreateStorageAdapterConformanceFixture;
+}
+export interface StorageAdapterConformanceReport {
+  readonly passedScenarios: readonly StorageAdapterConformanceScenario[];
+}
+/**
+* Runs provider-neutral persistence checks against a StorageAdapter. The
+* suite distinguishes a missing value from a provider failure, requires
+* quota and fault rejection to preserve the last committed value, and checks
+* JSON-style value isolation across the adapter boundary.
+*/
+export declare function runStorageAdapterConformance(input: RunStorageAdapterConformanceInput): Promise<StorageAdapterConformanceReport>;

package/dist/storage-conformance.js

@@ -0,0 +1,193 @@
+export const storageAdapterConformanceScenarios = [
+    'missing-read',
+    'round-trip-and-overwrite',
+    'storage-scope-isolation',
+    'mutation-isolation',
+    'quota-rejection-preserves-value',
+    'save-failure-is-fail-closed',
+    'load-failure-is-fail-closed',
+];
+const scenarioRunners = {
+    'missing-read': runMissingReadScenario,
+    'round-trip-and-overwrite': runRoundTripAndOverwriteScenario,
+    'storage-scope-isolation': runStorageScopeIsolationScenario,
+    'mutation-isolation': runMutationIsolationScenario,
+    'quota-rejection-preserves-value': runQuotaRejectionPreservesValueScenario,
+    'save-failure-is-fail-closed': runSaveFailureIsFailClosedScenario,
+    'load-failure-is-fail-closed': runLoadFailureIsFailClosedScenario,
+};
+/**
+ * Runs provider-neutral persistence checks against a StorageAdapter. The
+ * suite distinguishes a missing value from a provider failure, requires
+ * quota and fault rejection to preserve the last committed value, and checks
+ * JSON-style value isolation across the adapter boundary.
+ */
+export async function runStorageAdapterConformance(input) {
+    const passedScenarios = [];
+    for (const scenario of storageAdapterConformanceScenarios) {
+        let fixture;
+        let scenarioError;
+        let scenarioFailed = false;
+        try {
+            fixture = await input.createFixture({ scenario });
+            await scenarioRunners[scenario](fixture);
+        }
+        catch (error) {
+            scenarioError = error;
+            scenarioFailed = true;
+        }
+        let cleanupError;
+        let cleanupFailed = false;
+        try {
+            await fixture?.dispose?.();
+        }
+        catch (error) {
+            cleanupError = error;
+            cleanupFailed = true;
+        }
+        if (scenarioFailed) {
+            throw new Error(`Storage adapter conformance failed: ${scenario}.`, {
+                cause: cleanupFailed
+                    ? new AggregateError([scenarioError, cleanupError], `Scenario and fixture cleanup both failed: ${scenario}.`)
+                    : scenarioError,
+            });
+        }
+        if (cleanupFailed) {
+            throw new Error(`Storage adapter conformance cleanup failed: ${scenario}.`, {
+                cause: cleanupError,
+            });
+        }
+        passedScenarios.push(scenario);
+    }
+    return { passedScenarios };
+}
+async function runMissingReadScenario(fixture) {
+    const key = scenarioKey('missing-read');
+    assertEqual(await fixture.storage.load({ key }), null, 'missing values must return null');
+}
+async function runRoundTripAndOverwriteScenario(fixture) {
+    const key = scenarioKey('round-trip-and-overwrite');
+    const first = { revision: 1, progress: { stage: 2, coins: 10 } };
+    const second = { revision: 2, progress: { stage: 3, coins: 25 } };
+    await fixture.storage.save({ key, value: first });
+    assertJsonEqual(await fixture.storage.load({ key }), { value: first }, 'saved values must round-trip');
+    await fixture.storage.save({ key, value: second });
+    assertJsonEqual(await fixture.storage.load({ key }), { value: second }, 'later saves must replace the value for the same key');
+    await fixture.storage.save({ key, value: null });
+    assertJsonEqual(await fixture.storage.load({ key }), { value: null }, 'a stored top-level JSON null must remain distinguishable from a missing value');
+}
+async function runStorageScopeIsolationScenario(fixture) {
+    const key = scenarioKey('storage-scope-isolation');
+    const primaryValue = { owner: 'primary', coins: 10 };
+    const isolatedValue = { owner: 'isolated', coins: 20 };
+    await fixture.storage.save({ key, value: primaryValue });
+    assertEqual(await fixture.isolatedStorage.load({ key }), null, 'a distinct storage scope must not observe the primary value');
+    await fixture.isolatedStorage.save({ key, value: isolatedValue });
+    assertJsonEqual(await fixture.storage.load({ key }), { value: primaryValue }, 'writing an isolated scope must not replace the primary value');
+    assertJsonEqual(await fixture.isolatedStorage.load({ key }), { value: isolatedValue }, 'the isolated scope must retain its own value');
+}
+async function runMutationIsolationScenario(fixture) {
+    const key = scenarioKey('mutation-isolation');
+    const savedInput = {
+        revision: 1,
+        progress: { stage: 4, coins: 40 },
+        inventory: ['starter'],
+    };
+    const committedValue = {
+        revision: 1,
+        progress: { stage: 4, coins: 40 },
+        inventory: ['starter'],
+    };
+    await fixture.storage.save({ key, value: savedInput });
+    savedInput.progress.coins = 999;
+    savedInput.inventory.push('mutated-after-save');
+    const firstLoad = await fixture.storage.load({ key });
+    assertJsonEqual(firstLoad, { value: committedValue }, 'mutating the saved input must not mutate committed storage');
+    assert(firstLoad !== null, 'the committed value must remain readable');
+    const mutableLoadedValue = firstLoad.value;
+    try {
+        mutableLoadedValue.progress.coins = -1;
+    }
+    catch {
+        // Immutable values are acceptable; the later read still proves isolation.
+    }
+    try {
+        mutableLoadedValue.inventory.push('mutated-after-load');
+    }
+    catch {
+        // Immutable values are acceptable; each nested branch is probed independently.
+    }
+    assertJsonEqual(await fixture.storage.load({ key }), { value: committedValue }, 'mutating a loaded value must not mutate later reads');
+}
+async function runQuotaRejectionPreservesValueScenario(fixture) {
+    const key = scenarioKey('quota-rejection-preserves-value');
+    const committedValue = { revision: 1, state: 'committed-before-quota' };
+    await fixture.storage.save({ key, value: committedValue });
+    await assertRejects(() => fixture.storage.save({ key, value: fixture.oversizedValue }), 'an oversized value must reject instead of reporting success');
+    assertJsonEqual(await fixture.storage.load({ key }), { value: committedValue }, 'quota rejection must preserve the last committed value');
+}
+async function runSaveFailureIsFailClosedScenario(fixture) {
+    const key = scenarioKey('save-failure-is-fail-closed');
+    const committedValue = { revision: 1, state: 'committed-before-save-failure' };
+    await fixture.storage.save({ key, value: committedValue });
+    fixture.armNextSaveFailure();
+    await assertRejects(() => fixture.storage.save({ key, value: { revision: 2, state: 'must-not-commit' } }), 'provider save failures must reject instead of falling back or reporting success');
+    assertJsonEqual(await fixture.storage.load({ key }), { value: committedValue }, 'a failed save must preserve the last committed value');
+}
+async function runLoadFailureIsFailClosedScenario(fixture) {
+    const key = scenarioKey('load-failure-is-fail-closed');
+    const committedValue = { revision: 1, state: 'committed-before-load-failure' };
+    await fixture.storage.save({ key, value: committedValue });
+    fixture.armNextLoadFailure();
+    await assertRejects(() => fixture.storage.load({ key }), 'provider load failures must reject instead of returning a missing or fallback value');
+    assertJsonEqual(await fixture.storage.load({ key }), { value: committedValue }, 'the next load must recover the committed value after a transient failure');
+}
+function scenarioKey(scenario) {
+    return `storage-conformance:${scenario}`;
+}
+async function assertRejects(run, message) {
+    let rejected = false;
+    try {
+        await run();
+    }
+    catch {
+        rejected = true;
+    }
+    assert(rejected, message);
+}
+function assertJsonEqual(actual, expected, message) {
+    if (!jsonValuesEqual(actual, expected)) {
+        throw new Error(`${message}. Expected ${JSON.stringify(expected)}, received ${JSON.stringify(actual)}.`);
+    }
+}
+function jsonValuesEqual(actual, expected) {
+    if (actual === expected) {
+        return true;
+    }
+    if (Array.isArray(actual) || Array.isArray(expected)) {
+        return (Array.isArray(actual) &&
+            Array.isArray(expected) &&
+            actual.length === expected.length &&
+            actual.every((value, index) => jsonValuesEqual(value, expected[index])));
+    }
+    if (!isJsonObject(actual) || !isJsonObject(expected)) {
+        return false;
+    }
+    const actualKeys = Object.keys(actual);
+    const expectedKeys = Object.keys(expected);
+    return (actualKeys.length === expectedKeys.length &&
+        actualKeys.every((key) => Object.hasOwn(expected, key) && jsonValuesEqual(actual[key], expected[key])));
+}
+function isJsonObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(message);
+    }
+}
+function assertEqual(actual, expected, message) {
+    if (actual !== expected) {
+        throw new Error(`${message}. Expected ${String(expected)}, received ${String(actual)}.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/platform",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared platform gateway, monetization, ads, leaderboard, identity, lifecycle, and storage contracts for mpgd games.",
   "license": "MIT",
   "repository": {
@@ -28,6 +28,14 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./capability-conformance": {
+      "types": "./dist/capability-conformance.d.ts",
+      "default": "./dist/capability-conformance.js"
+    },
+    "./storage-conformance": {
+      "types": "./dist/storage-conformance.d.ts",
+      "default": "./dist/storage-conformance.js"
     }
   },
   "files": [
@@ -48,6 +56,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "vitest run"
+    "test": "vitest run && node test/capability-conformance-dist-import.mjs && node test/storage-conformance-dist-import.mjs"
   }
 }