@mpgd/adapter-verse8 0.1.0 → 0.2.1

package/dist/agent8.d.ts

@@ -0,0 +1,37 @@
+import type { ProductCatalog } from '@mpgd/catalog';
+import type { Entitlement, LogicalProductId } from '@mpgd/platform';
+export * from './agent8-services.js';
+export interface Verse8Agent8PurchaseEvent {
+  readonly account: string;
+  readonly purchaseId: number;
+  readonly productId: string;
+  readonly quantity: number;
+  readonly metadata?: unknown;
+}
+export interface Verse8Agent8Context {
+  getUserState(account: string): Promise<Readonly<Record<string, unknown>>>;
+  updateUserState(account: string, state: Readonly<Record<string, unknown>>): Promise<Readonly<Record<string, unknown>>>;
+  lock<T>(key: string, callback: () => T | Promise<T>): Promise<T>;
+}
+export interface Verse8Agent8CommerceOptions {
+  readonly catalog: ProductCatalog;
+  readonly stateNamespace?: string;
+  readonly now?: () => string;
+}
+export interface Verse8Agent8PurchaseResult {
+  readonly success: true;
+  readonly alreadyProcessed: boolean;
+  readonly purchaseId: string;
+  readonly logicalProductId: LogicalProductId;
+  readonly entitlementIds: readonly string[];
+}
+export interface Verse8Agent8CommerceSnapshot {
+  readonly balances: Readonly<Record<'coin' | 'gem', number>>;
+  readonly entitlements: readonly Entitlement[];
+}
+export interface Verse8Agent8CommerceService {
+  handleItemPurchased(event: Verse8Agent8PurchaseEvent, context: Verse8Agent8Context): Promise<Verse8Agent8PurchaseResult>;
+  getEntitlements(account: string, context: Pick<Verse8Agent8Context, 'getUserState'>): Promise<readonly Entitlement[]>;
+  getSnapshot(account: string, context: Pick<Verse8Agent8Context, 'getUserState'>): Promise<Verse8Agent8CommerceSnapshot>;
+}
+export declare function createVerse8Agent8CommerceService(options: Verse8Agent8CommerceOptions): Verse8Agent8CommerceService;

package/dist/agent8.js

@@ -0,0 +1,276 @@
+export * from './agent8-services.js';
+const defaultStateNamespace = 'mpgdVerse8Commerce';
+export function createVerse8Agent8CommerceService(options) {
+    const namespace = normalizeNamespace(options.stateNamespace ?? defaultStateNamespace);
+    const now = options.now ?? (() => new Date().toISOString());
+    const products = createPlatformProductMap(options.catalog);
+    return {
+        async handleItemPurchased(event, context) {
+            const normalized = assertPurchaseEvent(event);
+            const product = products.get(normalized.productId);
+            const purchaseId = String(normalized.purchaseId);
+            const lockAccount = normalizeLockAccount(normalized.account);
+            return context.lock(`mpgd:vxshop:${lockAccount}`, async () => {
+                const userState = await context.getUserState(normalized.account);
+                const current = readCommerceState(userState[namespace]);
+                const existing = current.purchasesById[purchaseId];
+                if (existing !== undefined) {
+                    assertSamePurchase(existing, normalized, product?.id);
+                    return {
+                        success: true,
+                        alreadyProcessed: true,
+                        purchaseId,
+                        logicalProductId: existing.logicalProductId,
+                        entitlementIds: existing.entitlementIds,
+                    };
+                }
+                if (product === undefined) {
+                    throw new Error('Unknown Verse8 VXShop product.');
+                }
+                const grantedAt = now();
+                assertNonEmptyString(grantedAt, 'now() result');
+                const applied = applyGrant(current, product.grant, normalized.quantity, grantedAt);
+                const purchase = {
+                    purchaseId,
+                    platformProductId: normalized.productId,
+                    logicalProductId: product.id,
+                    quantity: normalized.quantity,
+                    grantedAt,
+                    entitlementIds: applied.entitlementIds,
+                };
+                const next = {
+                    ...applied.state,
+                    purchasesById: {
+                        ...applied.state.purchasesById,
+                        [purchaseId]: purchase,
+                    },
+                };
+                // The grant and its consume-once marker share one Agent8 user-state
+                // update so a retry cannot observe one without the other.
+                await context.updateUserState(normalized.account, { [namespace]: next });
+                return {
+                    success: true,
+                    alreadyProcessed: false,
+                    purchaseId,
+                    logicalProductId: product.id,
+                    entitlementIds: applied.entitlementIds,
+                };
+            });
+        },
+        async getEntitlements(account, context) {
+            return (await readSnapshot(account, context, namespace)).entitlements;
+        },
+        async getSnapshot(account, context) {
+            return readSnapshot(account, context, namespace);
+        },
+    };
+}
+async function readSnapshot(account, context, namespace) {
+    assertNonEmptyString(account, 'account');
+    const userState = await context.getUserState(account);
+    const state = readCommerceState(userState[namespace]);
+    return {
+        balances: { ...state.balances },
+        entitlements: [...state.entitlements],
+    };
+}
+function createPlatformProductMap(catalog) {
+    const products = new Map();
+    for (const product of catalog.products) {
+        const platformProductId = product.platformProductIds.verse8?.trim();
+        if (platformProductId === undefined || platformProductId.length === 0) {
+            continue;
+        }
+        if (products.has(platformProductId)) {
+            throw new Error(`Duplicate Verse8 platform product ID: ${platformProductId}`);
+        }
+        products.set(platformProductId, product);
+    }
+    return products;
+}
+function assertPurchaseEvent(event) {
+    assertNonEmptyString(event.account, 'account');
+    assertNonEmptyString(event.productId, 'productId');
+    if (!Number.isSafeInteger(event.purchaseId) || event.purchaseId < 0) {
+        throw new Error('purchaseId must be a non-negative safe integer.');
+    }
+    if (!Number.isSafeInteger(event.quantity) || event.quantity <= 0) {
+        throw new Error('quantity must be a positive safe integer.');
+    }
+    return event;
+}
+function assertSamePurchase(existing, event, logicalProductId) {
+    if (existing.platformProductId !== event.productId
+        || existing.quantity !== event.quantity
+        || (logicalProductId !== undefined
+            && existing.logicalProductId !== logicalProductId)) {
+        throw new Error('Verse8 purchase ID was reused with different purchase data.');
+    }
+}
+function applyGrant(state, grant, quantity, grantedAt) {
+    if (grant.type === 'currency') {
+        const amount = grant.amount * quantity;
+        if (!Number.isSafeInteger(amount) || amount <= 0) {
+            throw new Error('Verse8 currency grant exceeds the safe integer range.');
+        }
+        const balance = state.balances[grant.currency] + amount;
+        if (!Number.isSafeInteger(balance)) {
+            throw new Error('Verse8 currency balance exceeds the safe integer range.');
+        }
+        return {
+            state: {
+                ...state,
+                balances: {
+                    ...state.balances,
+                    [grant.currency]: balance,
+                },
+            },
+            entitlementIds: [],
+        };
+    }
+    if (grant.type === 'resource') {
+        throw new Error('Verse8 resource grants are not supported.');
+    }
+    if (quantity !== 1) {
+        throw new Error('Verse8 entitlement purchases must have quantity 1.');
+    }
+    const existing = state.entitlements.find((entitlement) => entitlement.id === grant.entitlement);
+    const entitlements = existing === undefined
+        ? [
+            ...state.entitlements,
+            {
+                id: grant.entitlement,
+                source: 'purchase',
+                grantedAt,
+            },
+        ]
+        : state.entitlements;
+    return {
+        state: {
+            ...state,
+            entitlements,
+        },
+        entitlementIds: [grant.entitlement],
+    };
+}
+function readCommerceState(value) {
+    if (value === undefined) {
+        return emptyCommerceState();
+    }
+    if (!isRecord(value) || value.version !== 1) {
+        throw invalidStoredState();
+    }
+    return {
+        version: 1,
+        balances: readBalances(value.balances),
+        entitlements: readEntitlements(value.entitlements),
+        purchasesById: readPurchaseIndex(value.purchasesById),
+    };
+}
+function emptyCommerceState() {
+    return {
+        version: 1,
+        balances: { coin: 0, gem: 0 },
+        entitlements: [],
+        purchasesById: {},
+    };
+}
+function readBalances(value) {
+    if (!isRecord(value)) {
+        throw invalidStoredState();
+    }
+    return {
+        coin: assertSafeNonNegativeInteger(value.coin),
+        gem: assertSafeNonNegativeInteger(value.gem),
+    };
+}
+function readEntitlements(value) {
+    if (!Array.isArray(value)) {
+        throw invalidStoredState();
+    }
+    const entitlementIds = new Set();
+    return value.map((entry) => {
+        if (!isRecord(entry)
+            || typeof entry.id !== 'string'
+            || entry.id.length === 0
+            || entry.source !== 'purchase'
+            || typeof entry.grantedAt !== 'string'
+            || entry.grantedAt.length === 0
+            || entitlementIds.has(entry.id)) {
+            throw invalidStoredState();
+        }
+        entitlementIds.add(entry.id);
+        return {
+            id: entry.id,
+            source: 'purchase',
+            grantedAt: entry.grantedAt,
+        };
+    });
+}
+function readPurchaseIndex(value) {
+    if (!isRecord(value)) {
+        throw invalidStoredState();
+    }
+    const purchasesById = {};
+    for (const [purchaseId, entry] of Object.entries(value)) {
+        if (!isCanonicalPurchaseId(purchaseId)
+            || !isRecord(entry)
+            || entry.purchaseId !== purchaseId
+            || typeof entry.platformProductId !== 'string'
+            || entry.platformProductId.length === 0
+            || typeof entry.logicalProductId !== 'string'
+            || entry.logicalProductId.length === 0
+            || !Number.isSafeInteger(entry.quantity)
+            || entry.quantity <= 0
+            || typeof entry.grantedAt !== 'string'
+            || entry.grantedAt.length === 0
+            || !Array.isArray(entry.entitlementIds)
+            || !entry.entitlementIds.every((id) => typeof id === 'string' && id.length > 0)) {
+            throw invalidStoredState();
+        }
+        purchasesById[purchaseId] = {
+            purchaseId,
+            platformProductId: entry.platformProductId,
+            logicalProductId: entry.logicalProductId,
+            quantity: entry.quantity,
+            grantedAt: entry.grantedAt,
+            entitlementIds: entry.entitlementIds,
+        };
+    }
+    return purchasesById;
+}
+function isCanonicalPurchaseId(value) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed >= 0 && String(parsed) === value;
+}
+function assertSafeNonNegativeInteger(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw invalidStoredState();
+    }
+    return value;
+}
+function normalizeNamespace(value) {
+    const normalized = value.trim();
+    if (!/^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/.test(normalized)) {
+        throw new Error('stateNamespace must be a safe non-empty state key.');
+    }
+    return normalized;
+}
+function normalizeLockAccount(value) {
+    const normalized = value.trim();
+    if (normalized !== value || normalized.length > 256) {
+        throw new Error('account must be a canonical bounded string.');
+    }
+    return encodeURIComponent(normalized);
+}
+function invalidStoredState() {
+    return new Error('Stored Verse8 commerce state is invalid.');
+}
+function assertNonEmptyString(value, name) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`${name} must be a non-empty string.`);
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -1,4 +1,7 @@
-import { type PlatformGateway } from '@mpgd/platform';
+import { type InterstitialAdResult as Verse8InterstitialAdResult, type RewardedAdResult as Verse8RewardedAdResult } from '@verse8/ads';
+import type { ProductCatalog } from '@mpgd/catalog';
+import { type Entitlement, type LogicalAdPlacementId, type LogicalProductId, type PlatformGateway, type ProductType, type StorageAdapter } from '@mpgd/platform';
+export { verse8AdsRewardEvidenceSchema } from './ads-contract.js';
 export interface Verse8Credential {
   readonly account: `0x${string}`;
   readonly verse: string;
@@ -13,13 +16,77 @@ export interface Verse8Storage {
   getItem(key: string): string | null;
   setItem(key: string, value: string): void;
 }
+/**
+* Game-owned Agent8 RPC wrapper. The adapter deliberately does not import the
+* React-based Agent8 browser SDK.
+*/
+export interface Verse8Agent8StorageClient extends StorageAdapter {
+}
 export interface Verse8VisibilitySource {
   readonly hidden: boolean;
   addEventListener(type: 'visibilitychange', callback: () => void): void;
   removeEventListener(type: 'visibilitychange', callback: () => void): void;
 }
+export interface Verse8AdsClient {
+  showRewarded(input: {
+    readonly placementId: string;
+    readonly timeoutMs?: number;
+    readonly meta?: Record<string, unknown>;
+  }): Promise<Verse8RewardedAdResult>;
+  showInterstitial(input: {
+    readonly placementId: string;
+    readonly timeoutMs?: number;
+    readonly meta?: Record<string, unknown>;
+  }): Promise<Verse8InterstitialAdResult>;
+}
+export interface Verse8VXShopItem {
+  readonly productId: string;
+  readonly name: string;
+  readonly description: string;
+  readonly price: number;
+  readonly purchasable: boolean;
+  readonly purchaseLimitReached: boolean;
+}
+export interface Verse8VXShopClient {
+  init(options?: {
+    readonly verseId?: string;
+    readonly account?: string;
+    readonly autoRefresh?: boolean;
+  }): void;
+  getItem(productId: string): Verse8VXShopItem | undefined;
+  getItems(): readonly Verse8VXShopItem[];
+  buyItem(productId: string): void;
+  refresh(): Promise<void>;
+}
+export interface Verse8CommerceProduct {
+  readonly id: LogicalProductId;
+  readonly type: ProductType;
+  readonly platformProductId: string;
+}
+export interface Verse8CommerceOptions {
+  /**
+  * Explicitly acknowledges that grants are handled only by Verse8's reserved
+  * Agent8 `$onItemPurchased` server event, never by the client dialog callback.
+  */
+  readonly purchaseEventAuthority: 'agent8-server';
+  readonly products: readonly Verse8CommerceProduct[];
+  readonly loadEntitlements: () => Promise<readonly Entitlement[]>;
+  readonly client?: Verse8VXShopClient;
+  readonly init?: {
+    readonly verseId?: string;
+    readonly account?: string;
+    readonly autoRefresh?: boolean;
+  };
+  readonly canOpenShop?: () => boolean;
+}
+export declare function createVerse8CommerceProducts(catalog: ProductCatalog): readonly Verse8CommerceProduct[];
 export interface Verse8PlatformGatewayOptions {
   readonly authClient?: Verse8AuthClient;
+  readonly adsClient?: Verse8AdsClient;
+  readonly adsTimeoutMs?: number;
+  readonly resolveAdPlacementId?: (placementId: LogicalAdPlacementId) => string | undefined;
+  readonly vxShop?: Verse8CommerceOptions;
+  readonly agent8Storage?: Verse8Agent8StorageClient;
   readonly storage?: Verse8Storage;
   readonly visibility?: Verse8VisibilitySource;
 }