@mpgd/game-services 0.8.2 → 0.9.0

package/dist/client.js

@@ -29,7 +29,7 @@ export function createGameServicesClient(input) {
     return {
         async purchase(purchaseInput) {
             const target = input.target;
-            if (!isGameServicesStoreTarget(target)) {
+            if (!isGameServicesCommerceTarget(target)) {
                 const purchase = {
                     status: 'failed',
                     entitlementIds: [],
@@ -48,6 +48,25 @@ export function createGameServicesClient(input) {
                 };
             }
             const purchase = await input.gateway.commerce.purchase(purchaseInput);
+            if (target === 'verse8') {
+                const status = purchase.status === 'completed' ? 'rejected' : purchase.status;
+                await analytics.track({
+                    name: 'purchase_rejected',
+                    properties: {
+                        productId: purchaseInput.productId,
+                        status,
+                        reason: purchase.status === 'completed'
+                            ? 'verse8_grants_require_agent8_purchase_event'
+                            : purchase.status === 'pending'
+                                ? 'agent8_purchase_event_pending'
+                                : undefined,
+                    },
+                });
+                return {
+                    status,
+                    purchase,
+                };
+            }
             if (purchase.status !== 'completed' || purchase.transactionId === undefined) {
                 await analytics.track({
                     name: 'purchase_rejected',
@@ -93,7 +112,7 @@ export function createGameServicesClient(input) {
         },
         async claimRewardedAd(rewardInput) {
             const target = input.target;
-            if (!isGameServicesStoreTarget(target)) {
+            if (!isGameServicesAdRewardTarget(target)) {
                 const reward = {
                     status: 'unavailable',
                     rewardGranted: false,
@@ -157,6 +176,23 @@ export function createGameServicesClient(input) {
             return result;
         },
         async submitLeaderboardScore(scoreInput) {
+            const target = input.target;
+            if (!isGameServicesLeaderboardTarget(target)) {
+                await analytics.track({
+                    name: 'leaderboard_submitted',
+                    properties: {
+                        leaderboardId: scoreInput.leaderboardId,
+                        score: scoreInput.score,
+                        submitted: false,
+                        reason: 'unsupported_target',
+                    },
+                });
+                return {
+                    submitted: false,
+                    platformSubmitted: false,
+                    alreadyProcessed: false,
+                };
+            }
             const platformResult = await input.gateway.leaderboard.submitScore(scoreInput);
             if (!platformResult.submitted) {
                 await analytics.track({
@@ -174,7 +210,7 @@ export function createGameServicesClient(input) {
                 };
             }
             const record = await input.backend.leaderboard.recordScore({
-                target: input.target,
+                target,
                 playerId: input.playerId,
                 ...scoreInput,
             });
@@ -281,8 +317,18 @@ export function createGameServicesIdempotencyKey(input) {
 function normalizeSegment(value) {
     return value.replaceAll(/[^a-zA-Z0-9_-]+/g, '-').replaceAll(/^-|-$/g, '').slice(0, 64);
 }
-function isGameServicesStoreTarget(target) {
-    return target === 'android' || target === 'ios' || target === 'ait';
+function isGameServicesCommerceTarget(target) {
+    return target === 'android' || target === 'ios' || target === 'ait' || target === 'verse8';
+}
+function isGameServicesAdRewardTarget(target) {
+    return target === 'android' || target === 'ios' || target === 'ait' || target === 'verse8';
+}
+function isGameServicesLeaderboardTarget(target) {
+    return target === 'browser'
+        || target === 'android'
+        || target === 'ios'
+        || target === 'ait'
+        || target === 'reddit';
 }
 async function sendGameServicesBackendRequest(transport, endpoint, body) {
     const response = await transport.send({

package/dist/notification-delivery.js

@@ -5,6 +5,7 @@ const platformTargets = new Set([
     'ios',
     'ait',
     'reddit',
+    'verse8',
     'telegram',
     'tauri',
 ]);

package/dist/runtime.js

@@ -59,7 +59,8 @@ export function resolveGameServicesLedgerTarget(target) {
         || target === 'android'
         || target === 'ios'
         || target === 'ait'
-        || target === 'reddit') {
+        || target === 'reddit'
+        || target === 'verse8') {
         return target;
     }
     return null;

package/dist/types.d.ts

@@ -2,7 +2,9 @@ import type { ProductGrant } from '@mpgd/catalog';
 import type { LeaderboardScoreInput, LogicalAdPlacementId, LogicalProductId, PlatformEvidenceEnvelope, PlatformTarget } from '@mpgd/platform';
 export type { PlatformEvidenceEnvelope } from '@mpgd/platform';
 export type GameServicesStoreTarget = Extract<PlatformTarget, 'android' | 'ios' | 'ait'>;
-export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'android' | 'ios' | 'ait' | 'reddit'>;
+export type GameServicesAdRewardTarget = Extract<PlatformTarget, 'android' | 'ios' | 'ait' | 'verse8'>;
+export type GameServicesLeaderboardTarget = Extract<PlatformTarget, 'browser' | 'android' | 'ios' | 'ait' | 'reddit'>;
+export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8'>;
 export type PurchaseIdempotencyKey = string;
 export type AdRewardIdempotencyKey = string;
 export type EntitlementIdempotencyKey = PurchaseIdempotencyKey | AdRewardIdempotencyKey;
@@ -24,7 +26,7 @@ export interface VerifyPurchaseResponse {
   readonly reason?: string;
 }
 export interface ClaimAdRewardRequest {
-  readonly target: GameServicesStoreTarget;
+  readonly target: GameServicesAdRewardTarget;
   readonly playerId: string;
   readonly placementId: LogicalAdPlacementId;
   readonly platformImpressionId?: string;
@@ -39,7 +41,7 @@ export interface ClaimAdRewardResponse {
   readonly reason?: string;
 }
 export interface RecordLeaderboardScoreRequest extends LeaderboardScoreInput {
-  readonly target: GameServicesLedgerTarget;
+  readonly target: GameServicesLeaderboardTarget;
   readonly playerId: string;
   readonly platformSubmissionId?: string;
 }

package/dist/types.js

@@ -19,7 +19,7 @@ export function assertVerifyPurchaseResponse(input) {
 }
 export function assertClaimAdRewardRequest(input) {
     assertRecord(input, 'ClaimAdRewardRequest');
-    assertStoreTarget(input.target);
+    assertAdRewardTarget(input.target);
     assertNonEmptyString(input.playerId, 'playerId');
     assertNonEmptyString(input.placementId, 'placementId');
     assertOptionalNonEmptyString(input.platformImpressionId, 'platformImpressionId');
@@ -106,6 +106,11 @@ function assertStoreTarget(input) {
         throw new Error('target must be android, ios, or ait.');
     }
 }
+function assertAdRewardTarget(input) {
+    if (input !== 'android' && input !== 'ios' && input !== 'ait' && input !== 'verse8') {
+        throw new Error('target must be android, ios, ait, or verse8.');
+    }
+}
 function assertLeaderboardTarget(input) {
     if (input !== 'browser'
         && input !== 'android'
@@ -153,7 +158,15 @@ function assertProductGrant(input) {
         assertNonEmptyString(input.entitlement, 'grant.entitlement');
         return;
     }
-    throw new Error('grant.type must be currency or entitlement.');
+    if (input.type === 'resource') {
+        assertNonEmptyString(input.resource, 'grant.resource');
+        assertFiniteNumber(input.amount, 'grant.amount');
+        if (input.amount <= 0) {
+            throw new Error('grant.amount must be greater than zero for a resource grant.');
+        }
+        return;
+    }
+    throw new Error('grant.type must be currency, entitlement, or resource.');
 }
 function assertPayload(input) {
     assertRecord(input, 'payload');

package/dist/verified-leaderboard-durability-conformance.d.ts

@@ -0,0 +1,39 @@
+import { type VerifiedLeaderboardService } from './verified-leaderboard';
+export declare const verifiedLeaderboardDurabilityConformanceScenarios: readonly ['replacement-after-interrupted-retained-write', 'concurrent-retry-after-interrupted-retained-write', 'snapshot-after-interrupted-retained-write'];
+export type VerifiedLeaderboardDurabilityConformanceScenario = (typeof verifiedLeaderboardDurabilityConformanceScenarios)[number];
+export interface CreateVerifiedLeaderboardDurabilityConformanceFixtureInput {
+  readonly scenario: VerifiedLeaderboardDurabilityConformanceScenario;
+  readonly now: string;
+}
+export interface VerifiedLeaderboardDurabilityConformanceFixture {
+  readonly service: VerifiedLeaderboardService;
+  /**
+  * Arms one retained record so its caller observes a failure after the
+  * provider has crossed the recovery boundary. Transactional providers may
+  * simulate a committed write with a lost response. Multi-write providers
+  * should interrupt at their recoverable handoff boundary.
+  */
+  readonly interruptNextRetainedRecord: () => void;
+  readonly dispose?: () => Promise<void> | void;
+}
+export type CreateVerifiedLeaderboardDurabilityConformanceFixture = (input: CreateVerifiedLeaderboardDurabilityConformanceFixtureInput) => Promise<VerifiedLeaderboardDurabilityConformanceFixture> | VerifiedLeaderboardDurabilityConformanceFixture;
+export interface RunVerifiedLeaderboardDurabilityConformanceInput {
+  /** Return an isolated fixture, or a uniquely namespaced fixture, per scenario. */
+  readonly createFixture: CreateVerifiedLeaderboardDurabilityConformanceFixture;
+  readonly now?: string;
+}
+export interface VerifiedLeaderboardDurabilityConformanceReport {
+  readonly passedScenarios: readonly VerifiedLeaderboardDurabilityConformanceScenario[];
+}
+/**
+* Runs provider-neutral recovery checks that require a provider-specific fault
+* boundary. It complements the semantic conformance suite and deliberately
+* does not prescribe a shared persistence implementation.
+*/
+export declare function runVerifiedLeaderboardDurabilityConformance(input: RunVerifiedLeaderboardDurabilityConformanceInput): Promise<VerifiedLeaderboardDurabilityConformanceReport>;
+/**
+* Wraps an atomic provider so the next armed record commits successfully but
+* its caller observes an interruption. Use a provider-specific fixture when
+* the implementation has a recoverable boundary inside a multi-write flow.
+*/
+export declare function createAmbiguousCommitVerifiedLeaderboardDurabilityFixture(provider: VerifiedLeaderboardService, dispose?: () => Promise<void> | void): VerifiedLeaderboardDurabilityConformanceFixture;

package/dist/verified-leaderboard-durability-conformance.js

@@ -0,0 +1,193 @@
+import { assertRecordVerifiedLeaderboardAttemptResponse, assertVerifiedLeaderboardSnapshot, } from './verified-leaderboard';
+export const verifiedLeaderboardDurabilityConformanceScenarios = [
+    'replacement-after-interrupted-retained-write',
+    'concurrent-retry-after-interrupted-retained-write',
+    'snapshot-after-interrupted-retained-write',
+];
+const durabilityScenarioRunners = {
+    'replacement-after-interrupted-retained-write': runReplacementAfterInterruptedRetainedWriteScenario,
+    'concurrent-retry-after-interrupted-retained-write': runConcurrentRetryAfterInterruptedRetainedWriteScenario,
+    'snapshot-after-interrupted-retained-write': runSnapshotAfterInterruptedRetainedWriteScenario,
+};
+/**
+ * Runs provider-neutral recovery checks that require a provider-specific fault
+ * boundary. It complements the semantic conformance suite and deliberately
+ * does not prescribe a shared persistence implementation.
+ */
+export async function runVerifiedLeaderboardDurabilityConformance(input) {
+    const now = input.now ?? '2030-01-02T03:04:05.000Z';
+    const passedScenarios = [];
+    for (const scenario of verifiedLeaderboardDurabilityConformanceScenarios) {
+        const runScenario = durabilityScenarioRunners[scenario];
+        let fixture;
+        let scenarioError;
+        let scenarioFailed = false;
+        try {
+            fixture = await input.createFixture({ scenario, now });
+            await runScenario(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(`Verified leaderboard durability conformance failed: ${scenario}.`, {
+                cause: cleanupFailed
+                    ? new AggregateError([scenarioError, cleanupError], `Scenario and fixture cleanup both failed: ${scenario}.`)
+                    : scenarioError,
+            });
+        }
+        if (cleanupFailed) {
+            const message = `Verified leaderboard durability conformance cleanup failed: ${scenario}.`;
+            throw new Error(message, { cause: cleanupError });
+        }
+        passedScenarios.push(scenario);
+    }
+    return { passedScenarios };
+}
+/**
+ * Wraps an atomic provider so the next armed record commits successfully but
+ * its caller observes an interruption. Use a provider-specific fixture when
+ * the implementation has a recoverable boundary inside a multi-write flow.
+ */
+export function createAmbiguousCommitVerifiedLeaderboardDurabilityFixture(provider, dispose) {
+    let interruptNextRecord = false;
+    return {
+        service: {
+            async recordVerifiedAttempt(input) {
+                const response = await provider.recordVerifiedAttempt(input);
+                if (interruptNextRecord) {
+                    interruptNextRecord = false;
+                    throw new Error('Simulated verified leaderboard response interruption.');
+                }
+                return response;
+            },
+            getSnapshot: (input) => provider.getSnapshot(input),
+        },
+        interruptNextRetainedRecord() {
+            if (interruptNextRecord) {
+                throw new Error('A verified leaderboard interruption is already armed.');
+            }
+            interruptNextRecord = true;
+        },
+        ...(dispose === undefined ? {} : { dispose }),
+    };
+}
+async function runReplacementAfterInterruptedRetainedWriteScenario(fixture) {
+    const interrupted = createAttempt('replacement-after-interrupted-retained-write', 'interrupted', 10, '2030-01-02T03:00:00.000Z');
+    const later = createAttempt('replacement-after-interrupted-retained-write', 'later-better', 20, '2030-01-02T03:01:00.000Z');
+    fixture.interruptNextRetainedRecord();
+    await assertRejects(() => fixture.service.recordVerifiedAttempt(interrupted), 'the armed retained record must surface an interruption');
+    const laterResponse = await fixture.service.recordVerifiedAttempt(later);
+    assertRecordVerifiedLeaderboardAttemptResponse(laterResponse);
+    assertEqual(laterResponse.retained, true, 'the later better attempt must be retained');
+    assertEqual(laterResponse.entry.attemptId, later.attempt.attemptId, 'the later better attempt must replace the interrupted retained entry');
+    const retry = await fixture.service.recordVerifiedAttempt(interrupted);
+    assertOriginalInterruptedDecision(retry, interrupted);
+    const snapshot = await fixture.service.getSnapshot({
+        leaderboardId: interrupted.definition.leaderboardId,
+        participantId: interrupted.attempt.participantId,
+    });
+    assert(snapshot !== undefined, 'the recovered board must return a snapshot');
+    assertVerifiedLeaderboardSnapshot(snapshot);
+    assertEqual(snapshot.totalParticipants, 1, 'the replacement must keep one participant');
+    assertEqual(snapshot.entries.length, 1, 'the replacement must keep one ranked entry');
+    assertEqual(snapshot.entries[0]?.participantId, later.attempt.participantId, 'the ranked snapshot must contain the replacement participant');
+    assertEqual(snapshot.entries[0]?.attemptId, later.attempt.attemptId, 'the ranked snapshot must contain the later better attempt');
+    assertEqual(snapshot.entries[0]?.score, later.attempt.score, 'the ranked snapshot must contain the later better score');
+    assertEqual(snapshot.participantEntry?.attemptId, later.attempt.attemptId, 'the final snapshot must retain the later better attempt');
+}
+async function runConcurrentRetryAfterInterruptedRetainedWriteScenario(fixture) {
+    const interrupted = createAttempt('concurrent-retry-after-interrupted-retained-write', 'interrupted', 10, '2030-01-02T03:00:00.000Z');
+    fixture.interruptNextRetainedRecord();
+    await assertRejects(() => fixture.service.recordVerifiedAttempt(interrupted), 'the armed retained record must surface an interruption');
+    const retries = await Promise.all([
+        fixture.service.recordVerifiedAttempt(interrupted),
+        fixture.service.recordVerifiedAttempt(interrupted),
+    ]);
+    for (const retry of retries) {
+        assertOriginalInterruptedDecision(retry, interrupted);
+    }
+    const snapshot = await fixture.service.getSnapshot({
+        leaderboardId: interrupted.definition.leaderboardId,
+    });
+    assert(snapshot !== undefined, 'the concurrently recovered board must return a snapshot');
+    assertVerifiedLeaderboardSnapshot(snapshot);
+    assertEqual(snapshot.totalParticipants, 1, 'concurrent retries must not duplicate participants');
+    assertEqual(snapshot.entries.length, 1, 'concurrent retries must not duplicate retained rows');
+}
+async function runSnapshotAfterInterruptedRetainedWriteScenario(fixture) {
+    const interrupted = createAttempt('snapshot-after-interrupted-retained-write', 'interrupted', 10, '2030-01-02T03:00:00.000Z');
+    fixture.interruptNextRetainedRecord();
+    await assertRejects(() => fixture.service.recordVerifiedAttempt(interrupted), 'the armed retained record must surface an interruption');
+    const snapshot = await fixture.service.getSnapshot({
+        leaderboardId: interrupted.definition.leaderboardId,
+        participantId: interrupted.attempt.participantId,
+    });
+    assert(snapshot !== undefined, 'reads must recover an interrupted retained record');
+    assertVerifiedLeaderboardSnapshot(snapshot);
+    assertEqual(snapshot.totalParticipants, 1, 'recovery must restore one participant');
+    assertEqual(snapshot.entries.length, 1, 'recovery must restore one ranked entry');
+    assertEqual(snapshot.entries[0]?.participantId, interrupted.attempt.participantId, 'reads must expose the recovered participant in ranked entries');
+    assertEqual(snapshot.entries[0]?.attemptId, interrupted.attempt.attemptId, 'reads must expose the recovered attempt in ranked entries');
+    assertEqual(snapshot.entries[0]?.score, interrupted.attempt.score, 'reads must expose the recovered score in ranked entries');
+    assertEqual(snapshot.participantEntry?.attemptId, interrupted.attempt.attemptId, 'reads must expose the recovered retained entry');
+    const retry = await fixture.service.recordVerifiedAttempt(interrupted);
+    assertOriginalInterruptedDecision(retry, interrupted);
+}
+function assertOriginalInterruptedDecision(response, interrupted) {
+    assertRecordVerifiedLeaderboardAttemptResponse(response);
+    assertEqual(response.alreadyProcessed, true, 'retries must detect the interrupted write');
+    assertEqual(response.retained, true, 'retries must preserve the original retained decision');
+    assertEqual(response.entry.attemptId, interrupted.attempt.attemptId, 'retries must preserve the original response entry');
+    assertEqual(response.entry.score, interrupted.attempt.score, 'retries must preserve the original response score');
+}
+function createAttempt(scenario, suffix, score, completedAt) {
+    return {
+        definition: {
+            leaderboardId: `durability:${scenario}`,
+            scoreOrder: 'descending',
+            attemptSelection: 'best',
+        },
+        attempt: {
+            participantId: `participant:${scenario}`,
+            attemptId: `attempt:${scenario}:${suffix}`,
+            score,
+            completedAt,
+            verification: {
+                authorityId: 'verified-leaderboard-durability-conformance',
+                evidenceId: `evidence:${scenario}:${suffix}`,
+                verifiedAt: completedAt,
+            },
+        },
+    };
+}
+async function assertRejects(callback, message) {
+    let rejected = false;
+    try {
+        await callback();
+    }
+    catch {
+        rejected = true;
+    }
+    assert(rejected, message);
+}
+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/game-services",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -76,6 +76,10 @@
     "./verified-leaderboard-conformance": {
       "types": "./dist/verified-leaderboard-conformance.d.ts",
       "default": "./dist/verified-leaderboard-conformance.js"
+    },
+    "./verified-leaderboard-durability-conformance": {
+      "types": "./dist/verified-leaderboard-durability-conformance.d.ts",
+      "default": "./dist/verified-leaderboard-durability-conformance.js"
     }
   },
   "files": [
@@ -85,9 +89,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/analytics": "0.3.6",
-    "@mpgd/catalog": "0.4.0",
-    "@mpgd/platform": "0.6.0"
+    "@mpgd/analytics": "0.3.7",
+    "@mpgd/catalog": "0.5.0",
+    "@mpgd/platform": "0.7.0"
   },
   "devDependencies": {
     "ttsc": "0.18.4",
@@ -103,6 +107,6 @@
     "lint": "ttsc --noEmit",
     "format": "ttsc format",
     "fix": "ttsc fix",
-    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts"
+    "test": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/runtime.test.ts && node tools/run-ttsx.mjs packages/game-services/src/types.test.ts && node tools/run-ttsx.mjs packages/game-services/src/server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/platform-order.test.ts && node tools/run-ttsx.mjs packages/game-services/src/progress-link.test.ts && node tools/run-ttsx.mjs packages/game-services/src/notification-delivery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-durability-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/verified-leaderboard-transport.test.ts"
   }
 }