@mpgd/game-services 0.28.1 → 0.30.0

package/dist/server.d.ts

@@ -2,9 +2,11 @@ import { type AnalyticsSink } from '@mpgd/analytics';
 import { type AdPlacements, type ProductCatalog } from '@mpgd/catalog';
 import { type GameServicesBackendApi, type GameServicesBackendTransport, type GameServicesBackendTransportRequest, type GameServicesBackendTransportResponse } from './client.js';
 import { type CommerceEvidenceRegistry } from './commerce-evidence-registry.js';
+import { type PlayerDataErasureInput, type PlayerDataErasureResult } from './account-deletion.js';
 import { type GameServicesHealthResponse } from './contract.js';
 import { type GameServicesEvidenceVerifier, type GameServicesPurchaseGrantFinalizer } from './evidence-verification.js';
-import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerResult, type EntitlementLedgerRevocation, type EntitlementRevocationTransaction, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type PurchaseLedgerStatusRequest, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
+import { type ClaimAdRewardRequest, type ClaimAdRewardResponse, type EntitlementLedgerGrant, type EntitlementLedgerNote, type EntitlementLedgerResult, type EntitlementLedgerRevocation, type EntitlementRevocationTransaction, type GameServicesAdRewardTarget, type GameServicesStoreTarget, type LeaderboardScoreTransaction, type ProductGrantTransaction, type PurchaseLedgerStatusRequest, type RecordLeaderboardScoreRequest, type RecordLeaderboardScoreResponse, type VerifyPurchaseRequest, type VerifyPurchaseResponse } from './types.js';
+import { type PurchaseRestoreSharingPolicy } from './purchase-sharing.js';
 export { gameServicesRequestLimits, GameServicesRequestValidationError } from './validation.js';
 export { listActiveEntitlementTransactions, readPurchaseLedgerStatuses, revokeEntitlementGrant, RevocationKeyConflictError, type RevokeEntitlementGrantResult, } from './commerce-ledger.js';
 type CorsHeaders = Record<string, string>;
@@ -33,6 +35,15 @@ export interface CreateGameServicesBackendInput {
   */
   readonly commerceEvidenceRegistry?: CommerceEvidenceRegistry;
   /**
+  * How a restored non-consumable that the store binds to another player is
+  * answered (RFC "Restore sharing"). `{ mode: 'share' }` grants the
+  * restoring player its own entitlement while earlier holders keep theirs,
+  * up to `maxHolders` (5) players per purchase. Defaults to
+  * `{ mode: 'refuse' }`, which keeps answering the binding mismatch; the
+  * reference Worker shares by default (`GAME_SERVICES_RESTORE_SHARING`).
+  */
+  readonly restoreSharing?: PurchaseRestoreSharingPolicy;
+  /**
   * Receives unexpected (non-validation) failures such as store errors before the
   * transport answers with the generic `INTERNAL_ERROR` code. Defaults to `console.error`.
   * The hook is diagnostics only: if it throws or returns a rejecting promise, the failure
@@ -87,11 +98,42 @@ export interface GameServicesStore {
   findEntitlementRevocations?(input: {
     readonly ledgerEntryIds: readonly string[];
   }): Promise<readonly EntitlementRevocationTransaction[]>;
+  /**
+  * The grants of `source` whose `evidenceVerificationId` starts with
+  * `prefix` (at most `limit`), any order: restore sharing lists a purchase's
+  * shared grants with it in one indexed read (RFC "Restore sharing").
+  * Optional: without it the shares are read slot by slot.
+  */
+  findEntitlementTransactionsByEvidencePrefix?(input: {
+    readonly source: EntitlementLedgerGrant['source'];
+    readonly prefix: string;
+    readonly limit: number;
+  }): Promise<readonly ProductGrantTransaction[]>;
+  /**
+  * Keeps a ledger note (a store event that grants nothing), once per
+  * `noteId`: a replay answers `alreadyRecorded: true` and keeps the first.
+  * Optional: a store without it still answers the event, with a log only.
+  */
+  recordEntitlementNote?(input: EntitlementLedgerNote): Promise<{
+    readonly alreadyRecorded: boolean;
+  }>;
+  /** The notes about the given grants, oldest first. */
+  findEntitlementNotes?(input: {
+    readonly ledgerEntryIds: readonly string[];
+  }): Promise<readonly EntitlementLedgerNote[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
     readonly recordedAt?: string;
   }): Promise<RecordLeaderboardScoreResponse>;
   getLeaderboardTransaction(ledgerEntryId: string): Promise<LeaderboardScoreTransaction | undefined>;
   listLeaderboardTransactions(): Promise<readonly LeaderboardScoreTransaction[]>;
+  /**
+  * Account deletion (`./account-deletion`): deletes the player's grants,
+  * revocations, notes, and scores, except purchase grants and what reverses
+  * or annotates them, which are kept detached from the player (new ids,
+  * `retainedPlayerId`, no `playerId` payload key). Idempotent. Optional: the
+  * Worker's D1 deployment erases its tables in one batch instead.
+  */
+  erasePlayerData?(input: PlayerDataErasureInput): Promise<PlayerDataErasureResult>;
 }
 export interface EntitlementPlatformEvidenceIdentity {
   readonly source: Extract<EntitlementLedgerGrant['source'], 'purchase' | 'ad_reward'>;
@@ -122,6 +164,7 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   private readonly revocationsByKey;
   private readonly revocationsByGrant;
   private readonly revocationsByEvidence;
+  private readonly notesById;
   private readonly leaderboardTransactionsByRun;
   private readonly leaderboardTransactionsById;
   recordEntitlementGrant(input: EntitlementLedgerGrant): Promise<EntitlementLedgerResult>;
@@ -134,6 +177,11 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
     readonly source: EntitlementLedgerGrant['source'];
     readonly evidenceVerificationId: string;
   }): Promise<ProductGrantTransaction | undefined>;
+  findEntitlementTransactionsByEvidencePrefix(input: {
+    readonly source: EntitlementLedgerGrant['source'];
+    readonly prefix: string;
+    readonly limit: number;
+  }): Promise<readonly ProductGrantTransaction[]>;
   findEntitlementTransactionByPlatformEvidence(input: EntitlementPlatformEvidenceIdentity): Promise<ProductGrantTransaction | undefined>;
   getEntitlementTransaction(ledgerEntryId: string): Promise<ProductGrantTransaction | undefined>;
   listEntitlementTransactions(): Promise<readonly ProductGrantTransaction[]>;
@@ -142,11 +190,22 @@ export declare class InMemoryGameServicesStore implements GameServicesStore {
   findEntitlementRevocations(input: {
     readonly ledgerEntryIds: readonly string[];
   }): Promise<readonly EntitlementRevocationTransaction[]>;
+  recordEntitlementNote(input: EntitlementLedgerNote): Promise<{
+    readonly alreadyRecorded: boolean;
+  }>;
+  findEntitlementNotes(input: {
+    readonly ledgerEntryIds: readonly string[];
+  }): Promise<readonly EntitlementLedgerNote[]>;
   recordLeaderboardScore(input: RecordLeaderboardScoreRequest, options?: {
     readonly recordedAt?: string;
   }): Promise<RecordLeaderboardScoreResponse>;
   getLeaderboardTransaction(ledgerEntryId: string): Promise<LeaderboardScoreTransaction | undefined>;
   listLeaderboardTransactions(): Promise<readonly LeaderboardScoreTransaction[]>;
+  erasePlayerData(input: PlayerDataErasureInput): Promise<PlayerDataErasureResult>;
+  private rememberEntitlementRevocation;
+  private forgetEntitlementRevocation;
+  private forgetEntitlementTransaction;
+  private rememberEntitlementTransaction;
   private rankFor;
   private sortedLeaderboardTransactions;
 }