@mpgd/game-services 0.21.1 → 0.22.0

package/dist/types.d.ts

@@ -1,9 +1,24 @@
 import type { ProductGrant } from '@mpgd/catalog';
 import type { LeaderboardScoreInput, LogicalAdPlacementId, LogicalProductId, PlatformEvidenceEnvelope, PlatformTarget } from '@mpgd/platform';
-import type { ClaimAdRewardResponse, PurchaseGrantFinalization, VerifyPurchaseResponse } from './operation-results.js';
-export type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseGrantFinalizationAction, VerifyPurchaseResponse, } from './operation-results.js';
+import type { StoreId } from '@mpgd/platform/commerce';
+import type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, VerifyPurchaseResponse } from './operation-results.js';
+export type { ClaimAdRewardResponse, PurchaseGrantFinalization, PurchaseGrantFinalizationAction, PurchaseLedgerStatus, PurchaseLedgerStatusRequest, PurchaseLedgerStatusResponse, VerifyPurchaseResponse, } from './operation-results.js';
 export type { PlatformEvidenceEnvelope } from '@mpgd/platform';
-export type GameServicesStoreTarget = Extract<PlatformTarget, 'microsoft-store' | 'android' | 'ios' | 'ait' | 'oneplay'>;
+/**
+* The closed v1 purchase target list. The deployment target of a v1 verify
+* request names its store implicitly (`android` is Google Play, `ios` the App
+* Store, `ait` Apps in Toss); `resolveLegacyCommerceStoreId` is that mapping.
+*
+* @deprecated `VerifyPurchaseRequest.target` is open since commerce v2 C2
+* (`GameServicesStoreTarget` is `StoreId`); C4 removes this alias.
+*/
+export type GameServicesLegacyStoreTarget = Extract<PlatformTarget, 'microsoft-store' | 'android' | 'ios' | 'ait' | 'oneplay'>;
+/**
+* An open store or deployment target identifier (RFC "Open store ids"). The
+* request validator bounds its shape; the backend's commerce evidence
+* registry decides which stores it serves.
+*/
+export type GameServicesStoreTarget = StoreId;
 export type GameServicesAdRewardTarget = GameServicesLedgerTarget;
 export type GameServicesLeaderboardTarget = Extract<PlatformTarget, 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit'>;
 export type GameServicesLedgerTarget = Extract<PlatformTarget, 'browser' | 'microsoft-store' | 'android' | 'ios' | 'ait' | 'reddit' | 'verse8' | 'oneplay'>;
@@ -13,7 +28,17 @@ export type EntitlementIdempotencyKey = PurchaseIdempotencyKey | AdRewardIdempot
 export type EntitlementLedgerSource = 'purchase' | 'ad_reward' | 'admin';
 export type EntitlementLedgerPayload = Record<string, string | number | boolean>;
 export interface VerifyPurchaseRequest {
+  /** The ledger (deployment platform) target; see `store` for the store the purchase was made in. */
   readonly target: GameServicesStoreTarget;
+  /**
+  * The open store id the purchase was made in (RFC "Open store ids"), for
+  * example `google-play` or `credit-wallet`. A v1 request without it names
+  * its store through `target`: `android` is `google-play`, `ios` is
+  * `app-store`, `ait` is `apps-in-toss`, `reddit` is `devvit`, and every
+  * other target (`microsoft-store`, `verse8`, `oneplay`) is its own store id
+  * (`resolveLegacyCommerceStoreId`).
+  */
+  readonly store?: StoreId;
   /** Deployment config key used to resolve game-owned platform product identifiers. */
   readonly deploymentTarget?: string;
   readonly playerId: string;
@@ -62,6 +87,44 @@ export interface EntitlementLedgerResult {
   readonly ledgerEntryId: string;
   readonly alreadyProcessed: boolean;
 }
+/** Why a grant was reversed (RFC "Revocation and expiry entries"). */
+export type EntitlementRevocationReason = 'refund' | 'chargeback' | 'voided' | 'admin';
+/**
+* A `revoke` ledger entry: it references the grant it reverses and never
+* removes it, so the ledger stays append-only. Store notification handlers
+* (a Play voided purchase, an App Store refund, an Apps in Toss or Devvit
+* refunded order) write one through `revokeEntitlementGrant`; the entry's
+* `idempotencyKey` makes the notification replay-safe.
+*/
+export interface EntitlementLedgerRevocation {
+  readonly playerId: string;
+  /** The `ledgerEntryId` of the grant this entry reverses. */
+  readonly revokesLedgerEntryId: string;
+  readonly idempotencyKey: string;
+  readonly reason: EntitlementRevocationReason;
+  readonly revokedAt: string;
+  readonly payload: EntitlementLedgerPayload;
+  /** The notification's own authority identity, when the handler has one. */
+  readonly evidenceVerificationId?: string;
+}
+export interface EntitlementRevocationTransaction extends EntitlementLedgerRevocation {
+  readonly ledgerEntryId: string;
+}
+/**
+* A subscription `period` ledger entry: it extends an earlier grant with a
+* renewal period and its expiry. This is the shape only; no reference store
+* verifier writes one until a subscription verifier exists.
+*/
+export interface EntitlementLedgerPeriod {
+  readonly playerId: string;
+  /** The `ledgerEntryId` of the subscription grant this period extends. */
+  readonly extendsLedgerEntryId: string;
+  readonly idempotencyKey: string;
+  readonly periodIndex: number;
+  readonly startedAt: string;
+  readonly expiresAt: string;
+  readonly payload: EntitlementLedgerPayload;
+}
 export interface ProductGrantTransaction {
   readonly ledgerEntryId: string;
   readonly playerId: string;
@@ -83,6 +146,14 @@ export interface LeaderboardScoreTransaction extends RecordLeaderboardScoreReque
 */
 export declare function assertVerifyPurchaseRequest(input: VerifyPurchaseRequest): VerifyPurchaseRequest;
 export declare function assertVerifyPurchaseResponse(input: VerifyPurchaseResponse): VerifyPurchaseResponse;
+/** Bounds one ledger status read; a client asks for the grants of one journal window. */
+export declare const maxPurchaseLedgerStatusEntries = 256;
+/**
+* Validates an untrusted ledger status read. Failures throw
+* `GameServicesRequestValidationError` so transports can answer with a stable 400.
+*/
+export declare function assertPurchaseLedgerStatusRequest(input: PurchaseLedgerStatusRequest): PurchaseLedgerStatusRequest;
+export declare function assertPurchaseLedgerStatusResponse(input: PurchaseLedgerStatusResponse): PurchaseLedgerStatusResponse;
 export declare function assertPurchaseGrantFinalization(input: PurchaseGrantFinalization): PurchaseGrantFinalization;
 /**
 * Validates an untrusted ad reward claim. Failures throw
@@ -98,6 +169,11 @@ export declare function assertRecordLeaderboardScoreRequest(input: RecordLeaderb
 export declare function assertRecordLeaderboardScoreResponse(input: RecordLeaderboardScoreResponse): RecordLeaderboardScoreResponse;
 export declare function assertEntitlementLedgerGrant(input: EntitlementLedgerGrant): EntitlementLedgerGrant;
 export declare function assertEntitlementLedgerResult(input: EntitlementLedgerResult): EntitlementLedgerResult;
+export declare function assertEntitlementLedgerRevocation(input: EntitlementLedgerRevocation): EntitlementLedgerRevocation;
+export declare function assertEntitlementRevocationTransaction(input: EntitlementRevocationTransaction): EntitlementRevocationTransaction;
+export declare function assertEntitlementLedgerPeriod(input: EntitlementLedgerPeriod): EntitlementLedgerPeriod;
 export declare function assertProductGrantTransaction(input: ProductGrantTransaction): ProductGrantTransaction;
 export declare function assertLeaderboardScoreTransaction(input: LeaderboardScoreTransaction): LeaderboardScoreTransaction;
+/** A store id is a bounded kebab-case identifier such as `google-play` or `credit-wallet`. */
+export declare function assertCommerceStoreId(input: unknown, label?: string): asserts input is StoreId;
 export declare function assertGameServicesDeploymentTarget(input: unknown): asserts input is string;

package/dist/types.js

@@ -7,6 +7,9 @@ export function assertVerifyPurchaseRequest(input) {
     return validateRequest(() => {
         assertRecord(input, 'VerifyPurchaseRequest');
         assertStoreTarget(input.target);
+        if (input.store !== undefined) {
+            assertCommerceStoreId(input.store, 'store');
+        }
         assertOptionalGameServicesDeploymentTarget(input.deploymentTarget);
         assertRequestString(input.playerId, 'playerId');
         assertRequestString(input.productId, 'productId');
@@ -29,6 +32,49 @@ export function assertVerifyPurchaseResponse(input) {
     }
     return input;
 }
+/** Bounds one ledger status read; a client asks for the grants of one journal window. */
+export const maxPurchaseLedgerStatusEntries = 256;
+/**
+ * Validates an untrusted ledger status read. Failures throw
+ * `GameServicesRequestValidationError` so transports can answer with a stable 400.
+ */
+export function assertPurchaseLedgerStatusRequest(input) {
+    return validateRequest(() => {
+        assertRecord(input, 'PurchaseLedgerStatusRequest');
+        if (!Array.isArray(input.ledgerEntryIds)) {
+            throw new Error('ledgerEntryIds must be an array.');
+        }
+        if (input.ledgerEntryIds.length > maxPurchaseLedgerStatusEntries) {
+            throw new Error(`ledgerEntryIds must not exceed ${String(maxPurchaseLedgerStatusEntries)} entries.`);
+        }
+        for (const ledgerEntryId of input.ledgerEntryIds) {
+            assertRequestString(ledgerEntryId, 'ledgerEntryIds[]');
+        }
+        assertRequestString(input.playerId, 'playerId');
+        return input;
+    });
+}
+export function assertPurchaseLedgerStatusResponse(input) {
+    assertRecord(input, 'PurchaseLedgerStatusResponse');
+    if (!Array.isArray(input.statuses)) {
+        throw new Error('statuses must be an array.');
+    }
+    for (const status of input.statuses) {
+        assertRecord(status, 'statuses[]');
+        assertNonEmptyString(status.ledgerEntryId, 'statuses[].ledgerEntryId');
+        if (status.status !== 'active' && status.status !== 'reversed' && status.status !== 'unknown') {
+            throw new Error('statuses[].status must be active, reversed, or unknown.');
+        }
+        assertOptionalNonEmptyString(status.reversedBy, 'statuses[].reversedBy');
+        if (status.status === 'reversed' && status.reversedBy === undefined) {
+            throw new Error('a reversed status names the entry that reversed it.');
+        }
+        if (status.status !== 'reversed' && status.reversedBy !== undefined) {
+            throw new Error('only a reversed status names a reversing entry.');
+        }
+    }
+    return input;
+}
 export function assertPurchaseGrantFinalization(input) {
     assertRecord(input, 'PurchaseGrantFinalization');
     if (input.status !== 'completed' && input.status !== 'pending') {
@@ -124,6 +170,38 @@ export function assertEntitlementLedgerResult(input) {
     assertBoolean(input.alreadyProcessed, 'alreadyProcessed');
     return input;
 }
+export function assertEntitlementLedgerRevocation(input) {
+    assertRecord(input, 'EntitlementLedgerRevocation');
+    assertNonEmptyString(input.playerId, 'playerId');
+    assertNonEmptyString(input.revokesLedgerEntryId, 'revokesLedgerEntryId');
+    assertNonEmptyString(input.idempotencyKey, 'idempotencyKey');
+    assertRevocationReason(input.reason);
+    assertNonEmptyString(input.revokedAt, 'revokedAt');
+    assertPayload(input.payload);
+    assertOptionalNonEmptyString(input.evidenceVerificationId, 'evidenceVerificationId');
+    return input;
+}
+export function assertEntitlementRevocationTransaction(input) {
+    assertEntitlementLedgerRevocation(input);
+    assertNonEmptyString(input.ledgerEntryId, 'ledgerEntryId');
+    return input;
+}
+export function assertEntitlementLedgerPeriod(input) {
+    assertRecord(input, 'EntitlementLedgerPeriod');
+    assertNonEmptyString(input.playerId, 'playerId');
+    assertNonEmptyString(input.extendsLedgerEntryId, 'extendsLedgerEntryId');
+    assertNonEmptyString(input.idempotencyKey, 'idempotencyKey');
+    if (!Number.isSafeInteger(input.periodIndex) || input.periodIndex < 0) {
+        throw new Error('periodIndex must be a non-negative integer.');
+    }
+    assertNonEmptyString(input.startedAt, 'startedAt');
+    assertNonEmptyString(input.expiresAt, 'expiresAt');
+    if (!(Date.parse(input.expiresAt) > Date.parse(input.startedAt))) {
+        throw new Error('expiresAt must be a timestamp after startedAt.');
+    }
+    assertPayload(input.payload);
+    return input;
+}
 export function assertProductGrantTransaction(input) {
     assertRecord(input, 'ProductGrantTransaction');
     assertNonEmptyString(input.ledgerEntryId, 'ledgerEntryId');
@@ -150,13 +228,21 @@ function assertRecord(input, label) {
         throw new Error(`${label} must be an object.`);
     }
 }
+/**
+ * The purchase target is open (RFC "Open store ids"): any bounded kebab-case
+ * identifier passes here, and the backend's commerce evidence registry decides
+ * whether the store it names is served.
+ */
 function assertStoreTarget(input) {
-    if (input !== 'microsoft-store'
-        && input !== 'android'
-        && input !== 'ios'
-        && input !== 'ait'
-        && input !== 'oneplay') {
-        throw new Error('target must be microsoft-store, android, ios, ait, or oneplay.');
+    assertCommerceStoreId(input, 'target');
+}
+/** A store id is a bounded kebab-case identifier such as `google-play` or `credit-wallet`. */
+export function assertCommerceStoreId(input, label = 'store') {
+    if (typeof input !== 'string'
+        || input.length === 0
+        || input.length > 64
+        || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(input)) {
+        throw new Error(`${label} must be a lowercase kebab-case store identifier.`);
     }
 }
 function assertAdRewardTarget(input) {
@@ -262,6 +348,11 @@ function assertPurchaseGrantFinalizationAction(input) {
         throw new Error('finalization.action must be acknowledge, consume, finish, or complete.');
     }
 }
+function assertRevocationReason(input) {
+    if (input !== 'refund' && input !== 'chargeback' && input !== 'voided' && input !== 'admin') {
+        throw new Error('reason must be refund, chargeback, voided, or admin.');
+    }
+}
 function assertLedgerSource(input) {
     if (input !== 'purchase' && input !== 'ad_reward' && input !== 'admin') {
         throw new Error('source must be purchase, ad_reward, or admin.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/game-services",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Client, contract, server, store, and test helpers for authoritative mpgd game services.",
   "license": "MIT",
   "repository": {
@@ -77,6 +77,18 @@
       "types": "./dist/apps-in-toss-partner-api.d.ts",
       "default": "./dist/apps-in-toss-partner-api.js"
     },
+    "./commerce-evidence-registry": {
+      "types": "./dist/commerce-evidence-registry.d.ts",
+      "default": "./dist/commerce-evidence-registry.js"
+    },
+    "./commerce-reconciler": {
+      "types": "./dist/commerce-reconciler.d.ts",
+      "default": "./dist/commerce-reconciler.js"
+    },
+    "./monetization-operation-store": {
+      "types": "./dist/monetization-operation-store.d.ts",
+      "default": "./dist/monetization-operation-store.js"
+    },
     "./client": {
       "types": "./dist/client.d.ts",
       "default": "./dist/client.js"
@@ -190,9 +202,9 @@
     "@orpc/client": "2.0.0-beta.14",
     "@orpc/contract": "2.0.0-beta.14",
     "@orpc/server": "2.0.0-beta.14",
-    "@mpgd/catalog": "0.9.2",
-    "@mpgd/platform": "0.21.0",
-    "@mpgd/analytics": "0.4.7"
+    "@mpgd/analytics": "0.4.8",
+    "@mpgd/catalog": "0.9.3",
+    "@mpgd/platform": "0.22.0"
   },
   "peerDependencies": {
     "@apple/app-store-server-library": "^3.1.0"
@@ -221,8 +233,8 @@
     "fix": "ttsc fix",
     "build": "cd ../.. && node tools/run-ttsx.mjs tools/package/build-packages.ts @mpgd/game-services",
     "test:packed-transport": "pnpm build && node test/runtime-transport-package-import.mjs && node test/reward-evidence-import.mjs",
-    "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.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/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.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/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.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 && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-reward-evidence.test.ts && node tools/run-ttsx.mjs packages/game-services/src/ad-reward-verifier-registry.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-reward.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-purchase.test.ts",
-    "test:recovery": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/monetization-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-recovery.test.ts",
+    "test:unit": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-progress.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/google-play-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/google-play-publisher-client.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/microsoft-store-identity.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/admob-ssv.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-verifier.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-evidence-verification-conformance.test.ts && node tools/run-ttsx.mjs packages/game-services/src/apps-in-toss-partner-api.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 && node tools/run-ttsx.mjs packages/game-services/src/guest-session.test.ts && node tools/run-ttsx.mjs packages/game-services/src/client-reward-evidence.test.ts && node tools/run-ttsx.mjs packages/game-services/src/ad-reward-verifier-registry.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-reward.test.ts && node tools/run-ttsx.mjs packages/game-services/src/oneplay-purchase.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-registry-routing.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-registry-server.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-ledger-revocation.test.ts",
+    "test:recovery": "cd ../.. && node tools/run-ttsx.mjs packages/game-services/src/monetization-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/app-store-recovery.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-reconciler.test.ts && node tools/run-ttsx.mjs packages/game-services/src/commerce-reconciler-conformance.test.ts",
     "test": "pnpm test:unit && pnpm test:app-store-server && pnpm test:recovery && pnpm test:packed-transport",
     "test:app-store-server": "vitest run"
   }