@mpgd/game-services 0.9.0 → 0.11.0

package/dist/apps-in-toss-partner-api.js

@@ -0,0 +1,282 @@
+export const appsInTossPartnerApiBaseUrl = 'https://apps-in-toss-api.toss.im';
+export const defaultAppsInTossPartnerApiTimeoutMs = 10000;
+const verifyAnonymousKeyPath = 'api-partner/v1/apps-in-toss/users/anon-key/verify';
+const sendFunctionalMessagePath = 'api-partner/v1/apps-in-toss/messenger/send-message';
+const maximumResponseBodyBytes = 256 * 1024;
+export class AppsInTossPartnerApiError extends Error {
+    status;
+    code;
+    name = 'AppsInTossPartnerApiError';
+    constructor(message, status, code, options) {
+        super(message, options);
+        this.status = status;
+        this.code = code;
+    }
+}
+export function createAppsInTossPartnerApiClient(input) {
+    const baseUrl = normalizeBaseUrl(input.baseUrl ?? appsInTossPartnerApiBaseUrl);
+    const timeoutMs = normalizeTimeout(input.timeoutMs);
+    return {
+        async verifyAnonymousKey(request) {
+            const anonymousKey = normalizeIdentifier(request.anonymousKey, 'anonymousKey');
+            const response = await postJson({
+                mtls: input.mtls,
+                url: new URL(verifyAnonymousKeyPath, baseUrl).href,
+                headers: { 'x-anon-key': anonymousKey },
+                body: undefined,
+                timeoutMs,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+            if (response.status === 401) {
+                return false;
+            }
+            const envelope = requireSuccessEnvelope(response);
+            if (envelope.success !== 'true') {
+                throw new AppsInTossPartnerApiError('Apps in Toss returned an invalid anonymous-key verification response.', response.status);
+            }
+            return true;
+        },
+        async sendFunctionalMessage(request) {
+            const recipient = normalizeRecipient(request.recipient);
+            const templateSetCode = normalizeIdentifier(request.templateSetCode, 'templateSetCode');
+            const response = await postJson({
+                mtls: input.mtls,
+                url: new URL(sendFunctionalMessagePath, baseUrl).href,
+                headers: recipient.type === 'anonymous'
+                    ? { 'x-anon-key': recipient.key }
+                    : { 'x-toss-user-key': recipient.key },
+                body: {
+                    templateSetCode,
+                    context: normalizeContext(request.context),
+                },
+                timeoutMs,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+            const envelope = requireSuccessEnvelope(response);
+            return parseFunctionalMessageResult(envelope.success, response.status);
+        },
+    };
+}
+async function postJson(input) {
+    const timeout = createTimeoutSignal(input.signal, input.timeoutMs);
+    try {
+        // The documented anonymous-key verification request uses an empty body
+        // while still declaring application/json.
+        const requestBody = input.body === undefined ? '' : JSON.stringify(input.body);
+        const headers = new Headers({
+            accept: 'application/json',
+            'content-type': 'application/json',
+            ...input.headers,
+        });
+        let response;
+        let text;
+        try {
+            response = await input.mtls.fetch(input.url, {
+                method: 'POST',
+                headers,
+                body: requestBody,
+                signal: timeout.signal,
+            });
+            text = await readBoundedResponseText(response);
+        }
+        catch (error) {
+            throw normalizeTransportError(error, input.signal, timeout.signal);
+        }
+        let body;
+        try {
+            body = text.length === 0 ? undefined : JSON.parse(text);
+        }
+        catch {
+            throw new AppsInTossPartnerApiError('Apps in Toss returned a non-JSON response.', response.status);
+        }
+        return { status: response.status, ok: response.ok, body };
+    }
+    finally {
+        timeout.cleanup();
+    }
+}
+function normalizeTransportError(error, upstream, effective) {
+    if (error instanceof AppsInTossPartnerApiError) {
+        return error;
+    }
+    if (effective.aborted && upstream?.aborted !== true) {
+        return new AppsInTossPartnerApiError('Apps in Toss partner API request timed out.', 0, 'TIMEOUT', { cause: error });
+    }
+    if (upstream?.aborted === true) {
+        return new AppsInTossPartnerApiError('Apps in Toss partner API request was aborted.', 0, 'ABORTED', { cause: error });
+    }
+    return new AppsInTossPartnerApiError('Apps in Toss partner API transport failed.', 0, 'TRANSPORT_ERROR', { cause: error });
+}
+async function readBoundedResponseText(response) {
+    const declaredLength = response.headers.get('content-length');
+    if (declaredLength !== null
+        && /^\d+$/u.test(declaredLength)
+        && Number(declaredLength) > maximumResponseBodyBytes) {
+        throw responseTooLarge(response.status);
+    }
+    if (response.body === null) {
+        return '';
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let byteLength = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done) {
+                break;
+            }
+            byteLength += chunk.value.byteLength;
+            if (byteLength > maximumResponseBodyBytes) {
+                await reader.cancel().catch(() => { });
+                throw responseTooLarge(response.status);
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(byteLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned a non-UTF-8 response.', response.status);
+    }
+}
+function responseTooLarge(status) {
+    return new AppsInTossPartnerApiError('Apps in Toss response exceeded the maximum accepted size.', status);
+}
+function requireSuccessEnvelope(response) {
+    if (!isRecord(response.body)) {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an invalid response envelope.', response.status);
+    }
+    if (response.ok && response.body.resultType === 'SUCCESS') {
+        return response.body;
+    }
+    const error = isRecord(response.body.error) ? response.body.error : undefined;
+    const code = typeof error?.errorCode === 'string' ? error.errorCode : undefined;
+    const reason = typeof error?.reason === 'string'
+        ? error.reason.slice(0, 1024)
+        : 'Apps in Toss partner API request failed.';
+    throw new AppsInTossPartnerApiError(reason, response.status, code);
+}
+function parseFunctionalMessageResult(input, status) {
+    if (!isRecord(input)) {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an invalid message result.', status);
+    }
+    return {
+        messageCount: requireCount(input.msgCount, 'msgCount', status),
+        sentPushCount: requireCount(input.sentPushCount, 'sentPushCount', status),
+        sentInboxCount: requireCount(input.sentInboxCount, 'sentInboxCount', status),
+        sentSmsCount: requireCount(input.sentSmsCount, 'sentSmsCount', status),
+        sentAlimtalkCount: requireCount(input.sentAlimtalkCount, 'sentAlimtalkCount', status),
+        sentFriendtalkCount: requireCount(input.sentFriendtalkCount, 'sentFriendtalkCount', status),
+        contentIds: readContentIds(input.detail),
+    };
+}
+function readContentIds(detail) {
+    if (!isRecord(detail)) {
+        return [];
+    }
+    const ids = new Set();
+    for (const channel of ['sentPush', 'sentInbox', 'sentSms', 'sentAlimtalk', 'sentFriendtalk']) {
+        const entries = detail[channel];
+        if (!Array.isArray(entries)) {
+            continue;
+        }
+        for (const entry of entries) {
+            if (isRecord(entry) && typeof entry.contentId === 'string' && entry.contentId.length > 0) {
+                ids.add(entry.contentId);
+            }
+        }
+    }
+    return [...ids];
+}
+function requireCount(value, field, status) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new AppsInTossPartnerApiError(`Apps in Toss returned an invalid ${field}.`, status);
+    }
+    return value;
+}
+function normalizeRecipient(input) {
+    if (input.type !== 'anonymous' && input.type !== 'toss-user') {
+        throw new TypeError('AIT message recipient type is invalid.');
+    }
+    return { type: input.type, key: normalizeIdentifier(input.key, 'recipient.key') };
+}
+function normalizeContext(input) {
+    const entries = Object.entries(input);
+    if (entries.length > 128) {
+        throw new TypeError('AIT message context cannot contain more than 128 values.');
+    }
+    const output = Object.create(null);
+    for (const [key, value] of entries) {
+        const normalizedKey = normalizeIdentifier(key, 'context key');
+        if (typeof value !== 'string'
+            && typeof value !== 'number'
+            && typeof value !== 'boolean') {
+            throw new TypeError(`AIT message context value is invalid: ${normalizedKey}`);
+        }
+        if (typeof value === 'number' && !Number.isFinite(value)) {
+            throw new TypeError(`AIT message context number is invalid: ${normalizedKey}`);
+        }
+        output[normalizedKey] = value;
+    }
+    return output;
+}
+function normalizeIdentifier(value, field) {
+    const normalized = value.trim();
+    if (normalized.length === 0
+        || normalized.length > 2048
+        || /[\p{Cc}\p{Cf}]/u.test(normalized)) {
+        throw new TypeError(`${field} must contain 1 to 2048 characters without control or format characters.`);
+    }
+    return normalized;
+}
+function normalizeBaseUrl(input) {
+    const url = new URL(input);
+    if (url.protocol !== 'https:'
+        || url.username.length > 0
+        || url.password.length > 0
+        || url.search.length > 0
+        || url.hash.length > 0) {
+        throw new TypeError('AIT partner API baseUrl must be a credential-free HTTPS URL.');
+    }
+    url.pathname = url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`;
+    return url;
+}
+function normalizeTimeout(value) {
+    const timeoutMs = value ?? defaultAppsInTossPartnerApiTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > 60000) {
+        throw new TypeError('AIT partner API timeoutMs must be between 1 and 60000.');
+    }
+    return timeoutMs;
+}
+function createTimeoutSignal(upstream, timeoutMs) {
+    const controller = new AbortController();
+    const abortFromUpstream = () => controller.abort(upstream?.reason);
+    if (upstream?.aborted === true) {
+        abortFromUpstream();
+    }
+    else {
+        upstream?.addEventListener('abort', abortFromUpstream, { once: true });
+    }
+    const timer = globalThis.setTimeout(() => controller.abort(new Error('Apps in Toss partner API request timed out.')), timeoutMs);
+    return {
+        signal: controller.signal,
+        cleanup() {
+            globalThis.clearTimeout(timer);
+            upstream?.removeEventListener('abort', abortFromUpstream);
+        },
+    };
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/evidence-verification.d.ts

@@ -1,10 +1,15 @@
 import type { AdPlacements, ProductCatalog } from '@mpgd/catalog';
-import type { ClaimAdRewardRequest, EntitlementLedgerPayload, VerifyPurchaseRequest } from './types';
+import type { ClaimAdRewardRequest, EntitlementLedgerPayload, PurchaseGrantFinalization, VerifyPurchaseRequest } from './types';
 export type EvidenceVerificationDecision = {
   readonly status: 'verified';
   readonly verificationId: string;
   readonly verifiedAt: string;
   readonly payload?: EntitlementLedgerPayload;
+  /**
+  * An authoritative provider identity for cross-idempotency replay checks.
+  * `null` explicitly suppresses the client-reported platform identity.
+  */
+  readonly platformEvidenceId?: string | null;
 } | {
   readonly status: 'pending';
   readonly reason?: string;
@@ -26,6 +31,21 @@ export interface VerifyAdRewardEvidenceInput {
   readonly signal: AbortSignal;
   readonly timeoutMs: number;
 }
+export interface FinalizePurchaseGrantInput {
+  readonly request: VerifyPurchaseRequest;
+  readonly product: ProductCatalog['products'][number];
+  readonly platformProductId: string;
+  readonly evidenceVerificationId: string;
+  readonly evidencePayload?: EntitlementLedgerPayload;
+  readonly ledgerEntryId: string;
+  readonly alreadyProcessed: boolean;
+  readonly signal: AbortSignal;
+  readonly timeoutMs: number;
+}
+export interface GameServicesPurchaseGrantFinalizer {
+  supportsPurchaseGrant?(input: Omit<FinalizePurchaseGrantInput, 'signal'>): boolean;
+  finalizePurchaseGrant(input: FinalizePurchaseGrantInput): Promise<PurchaseGrantFinalization>;
+}
 export interface GameServicesEvidenceVerifier {
   verifyPurchase(input: VerifyPurchaseEvidenceInput): Promise<EvidenceVerificationDecision>;
   verifyAdReward(input: VerifyAdRewardEvidenceInput): Promise<EvidenceVerificationDecision>;

package/dist/google-play-purchase-conformance.d.ts

@@ -0,0 +1,26 @@
+import { type GooglePlayAcknowledgementState, type GooglePlayConsumptionState, type GooglePlayPurchaseState } from './google-play-purchase';
+export declare const googlePlayProductPurchaseConformanceEvidence: Readonly<{
+  schema: "google-play.product-purchase.v2";
+  payload: Readonly<{
+    purchaseToken: "google-play-conformance-token";
+  }>;
+}>;
+export interface CreateGooglePlayProductPurchaseConformanceFixtureInput {
+  readonly productId?: string;
+  readonly orderId?: string;
+  readonly purchaseState?: Exclude<GooglePlayPurchaseState, 'PURCHASE_STATE_UNSPECIFIED'>;
+  readonly purchaseCompletionTime?: string;
+  readonly consumptionState?: Exclude<GooglePlayConsumptionState, 'CONSUMPTION_STATE_UNSPECIFIED'>;
+  readonly acknowledgementState?: Exclude<GooglePlayAcknowledgementState, 'ACKNOWLEDGEMENT_STATE_UNSPECIFIED'>;
+  readonly quantity?: number;
+  readonly refundableQuantity?: number;
+  readonly rentOffer?: boolean;
+  readonly obfuscatedExternalAccountId?: string;
+  readonly obfuscatedExternalProfileId?: string;
+}
+/**
+* Builds a deterministic `purchases.productsv2` response for boundary and
+* provider-client conformance tests. It intentionally contains no credentials,
+* live purchase tokens, or environment-specific endpoints.
+*/
+export declare function createGooglePlayProductPurchaseConformanceFixture(input?: CreateGooglePlayProductPurchaseConformanceFixtureInput): Readonly<Record<string, unknown>>;

package/dist/google-play-purchase-conformance.js

@@ -0,0 +1,39 @@
+import { googlePlayProductPurchaseEvidenceSchema, } from './google-play-purchase';
+export const googlePlayProductPurchaseConformanceEvidence = Object.freeze({
+    schema: googlePlayProductPurchaseEvidenceSchema,
+    payload: Object.freeze({
+        purchaseToken: 'google-play-conformance-token',
+    }),
+});
+/**
+ * Builds a deterministic `purchases.productsv2` response for boundary and
+ * provider-client conformance tests. It intentionally contains no credentials,
+ * live purchase tokens, or environment-specific endpoints.
+ */
+export function createGooglePlayProductPurchaseConformanceFixture(input = {}) {
+    return {
+        productLineItem: [
+            {
+                productId: input.productId ?? 'coins_100_android',
+                productOfferDetails: {
+                    quantity: input.quantity ?? 1,
+                    refundableQuantity: input.refundableQuantity ?? 1,
+                    consumptionState: input.consumptionState ?? 'CONSUMPTION_STATE_YET_TO_BE_CONSUMED',
+                    ...(input.rentOffer === true ? { rentOfferDetails: {} } : {}),
+                },
+            },
+        ],
+        purchaseStateContext: {
+            purchaseState: input.purchaseState ?? 'PURCHASED',
+        },
+        orderId: input.orderId ?? 'GPA.conformance-1',
+        purchaseCompletionTime: input.purchaseCompletionTime ?? '2030-01-02T03:04:05.000Z',
+        acknowledgementState: input.acknowledgementState ?? 'ACKNOWLEDGEMENT_STATE_PENDING',
+        ...(input.obfuscatedExternalAccountId === undefined
+            ? {}
+            : { obfuscatedExternalAccountId: input.obfuscatedExternalAccountId }),
+        ...(input.obfuscatedExternalProfileId === undefined
+            ? {}
+            : { obfuscatedExternalProfileId: input.obfuscatedExternalProfileId }),
+    };
+}

package/dist/google-play-purchase.d.ts

@@ -0,0 +1,40 @@
+import type { GameServicesEvidenceVerifier, GameServicesPurchaseGrantFinalizer, VerifyPurchaseEvidenceInput } from './evidence-verification';
+export declare const googlePlayProductPurchaseEvidenceSchema = "google-play.product-purchase.v2";
+export type GooglePlayPurchaseState = 'PURCHASED' | 'CANCELLED' | 'PENDING' | 'PURCHASE_STATE_UNSPECIFIED';
+export type GooglePlayConsumptionState = 'CONSUMPTION_STATE_YET_TO_BE_CONSUMED' | 'CONSUMPTION_STATE_CONSUMED' | 'CONSUMPTION_STATE_UNSPECIFIED';
+export type GooglePlayAcknowledgementState = 'ACKNOWLEDGEMENT_STATE_PENDING' | 'ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED' | 'ACKNOWLEDGEMENT_STATE_UNSPECIFIED';
+export interface GooglePlayProductPurchaseClient {
+  getProductPurchaseV2(input: {
+    readonly packageName: string;
+    readonly purchaseToken: string;
+    readonly signal: AbortSignal;
+  }): Promise<unknown>;
+  acknowledgeProductPurchase(input: {
+    readonly packageName: string;
+    readonly productId: string;
+    readonly purchaseToken: string;
+    readonly signal: AbortSignal;
+  }): Promise<void>;
+  consumeProductPurchase(input: {
+    readonly packageName: string;
+    readonly productId: string;
+    readonly purchaseToken: string;
+    readonly signal: AbortSignal;
+  }): Promise<void>;
+}
+export interface CreateGooglePlayProductPurchaseBoundaryInput {
+  readonly client: GooglePlayProductPurchaseClient;
+  readonly packageName: string;
+  readonly now?: () => string;
+  /**
+  * Explicitly permits purchases without a Google account identifier. Use only
+  * when the caller binds `playerId` to an authenticated application account.
+  */
+  readonly allowUnboundAuthenticatedPlayer?: boolean;
+  readonly resolveObfuscatedAccountId?: (playerId: string, signal: AbortSignal) => Promise<string | undefined> | string | undefined;
+  readonly resolveObfuscatedProfileId?: (playerId: string, signal: AbortSignal) => Promise<string | undefined> | string | undefined;
+}
+export interface GooglePlayProductPurchaseBoundary extends GameServicesPurchaseGrantFinalizer {
+  verifyPurchase(input: VerifyPurchaseEvidenceInput): ReturnType<GameServicesEvidenceVerifier['verifyPurchase']>;
+}
+export declare function createGooglePlayProductPurchaseBoundary(input: CreateGooglePlayProductPurchaseBoundaryInput): GooglePlayProductPurchaseBoundary;