@mpgd/game-services 0.11.1 → 0.12.0

package/dist/apps-in-toss-partner-api.d.ts

@@ -27,12 +27,61 @@ export interface AppsInTossFunctionalMessageResult {
   readonly sentFriendtalkCount: number;
   readonly contentIds: readonly string[];
 }
+/** The source environment returned by the Apps in Toss login SDK. */
+export type AppsInTossLoginReferrer = 'DEFAULT' | 'SANDBOX';
+/**
+* Short-lived OAuth token material returned by the partner API.
+*
+* Callers should use this only to immediately resolve a login identity or
+* securely persist it in a dedicated credential store. It must never be sent
+* back to a game client.
+*/
+export interface AppsInTossLoginToken {
+  readonly tokenType: 'bearer';
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  readonly expiresInSeconds: number;
+  readonly scope: string;
+}
+/** App-scoped user identity returned by the Apps in Toss login API. */
+export interface AppsInTossLoginUser {
+  /** Serialized because the documented API returns a numeric user key. */
+  readonly userKey: string;
+  readonly scope: string;
+}
+export type AppsInTossIapOrderStatus = 'PURCHASED' | 'PAYMENT_COMPLETED' | 'FAILED' | 'REFUNDED' | 'ORDER_IN_PROGRESS' | 'NOT_FOUND' | 'MINIAPP_MISMATCH' | 'ERROR';
+/** Authoritative order status returned from the mTLS Apps in Toss partner API. */
+export interface AppsInTossIapOrderStatusResult {
+  readonly orderId: string;
+  readonly sku: string;
+  readonly statusDeterminedAt: string;
+  readonly status: AppsInTossIapOrderStatus;
+  readonly reason?: string;
+}
 export interface AppsInTossPartnerApiClient {
   verifyAnonymousKey(input: {
     readonly anonymousKey: string;
     readonly signal?: AbortSignal;
   }): Promise<boolean>;
   sendFunctionalMessage(input: SendAppsInTossFunctionalMessageInput): Promise<AppsInTossFunctionalMessageResult>;
+  exchangeLoginAuthorizationCode(input: {
+    readonly authorizationCode: string;
+    readonly referrer: AppsInTossLoginReferrer;
+    readonly signal?: AbortSignal;
+  }): Promise<AppsInTossLoginToken>;
+  getLoginUser(input: {
+    readonly accessToken: string;
+    readonly signal?: AbortSignal;
+  }): Promise<AppsInTossLoginUser>;
+  getIapOrderStatus(input: {
+    readonly orderId: string;
+    /**
+    * A user key resolved through Apps in Toss login. Supplying it binds the
+    * lookup to the same authenticated user that initiated the purchase.
+    */
+    readonly tossUserKey: string;
+    readonly signal?: AbortSignal;
+  }): Promise<AppsInTossIapOrderStatusResult>;
 }
 export interface CreateAppsInTossPartnerApiClientInput {
   readonly mtls: AppsInTossMutualTlsFetcher;

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

@@ -2,6 +2,9 @@ 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 exchangeLoginAuthorizationCodePath = 'api-partner/v1/apps-in-toss/user/oauth2/generate-token';
+const getLoginUserPath = 'api-partner/v1/apps-in-toss/user/oauth2/login-me';
+const getIapOrderStatusPath = 'api-partner/v1/apps-in-toss/order/get-order-status';
 const maximumResponseBodyBytes = 256 * 1024;
 export class AppsInTossPartnerApiError extends Error {
     status;
@@ -19,8 +22,9 @@ export function createAppsInTossPartnerApiClient(input) {
     return {
         async verifyAnonymousKey(request) {
             const anonymousKey = normalizeIdentifier(request.anonymousKey, 'anonymousKey');
-            const response = await postJson({
+            const response = await requestJson({
                 mtls: input.mtls,
+                method: 'POST',
                 url: new URL(verifyAnonymousKeyPath, baseUrl).href,
                 headers: { 'x-anon-key': anonymousKey },
                 body: undefined,
@@ -39,8 +43,9 @@ export function createAppsInTossPartnerApiClient(input) {
         async sendFunctionalMessage(request) {
             const recipient = normalizeRecipient(request.recipient);
             const templateSetCode = normalizeIdentifier(request.templateSetCode, 'templateSetCode');
-            const response = await postJson({
+            const response = await requestJson({
                 mtls: input.mtls,
+                method: 'POST',
                 url: new URL(sendFunctionalMessagePath, baseUrl).href,
                 headers: recipient.type === 'anonymous'
                     ? { 'x-anon-key': recipient.key }
@@ -55,26 +60,83 @@ export function createAppsInTossPartnerApiClient(input) {
             const envelope = requireSuccessEnvelope(response);
             return parseFunctionalMessageResult(envelope.success, response.status);
         },
+        async exchangeLoginAuthorizationCode(request) {
+            const authorizationCode = normalizeIdentifier(request.authorizationCode, 'authorizationCode');
+            const referrer = normalizeLoginReferrer(request.referrer);
+            const response = await requestJson({
+                mtls: input.mtls,
+                method: 'POST',
+                url: new URL(exchangeLoginAuthorizationCodePath, baseUrl).href,
+                headers: {},
+                body: { authorizationCode, referrer },
+                timeoutMs,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+            const envelope = requireSuccessEnvelope(response);
+            return parseLoginToken(envelope.success, response.status);
+        },
+        async getLoginUser(request) {
+            const accessToken = normalizeOpaqueValue(request.accessToken, 'accessToken', 16384);
+            const response = await requestJson({
+                mtls: input.mtls,
+                method: 'GET',
+                url: new URL(getLoginUserPath, baseUrl).href,
+                headers: { authorization: `Bearer ${accessToken}` },
+                body: undefined,
+                timeoutMs,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+            const envelope = requireSuccessEnvelope(response);
+            return parseLoginUser(envelope.success, response.status);
+        },
+        async getIapOrderStatus(request) {
+            const orderId = normalizeIdentifier(request.orderId, 'orderId');
+            const tossUserKey = normalizeTossUserKey(request.tossUserKey, 'tossUserKey');
+            const response = await requestJson({
+                mtls: input.mtls,
+                method: 'POST',
+                url: new URL(getIapOrderStatusPath, baseUrl).href,
+                headers: { 'x-toss-user-key': tossUserKey },
+                body: { orderId },
+                timeoutMs,
+                ...(request.signal === undefined ? {} : { signal: request.signal }),
+            });
+            const envelope = requireSuccessEnvelope(response);
+            const orderStatus = parseIapOrderStatus(envelope.success, response.status);
+            if (orderStatus.orderId !== orderId) {
+                throw new AppsInTossPartnerApiError('Apps in Toss returned a mismatched order id.', response.status);
+            }
+            return orderStatus;
+        },
     };
 }
-async function postJson(input) {
+async function requestJson(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);
+        // while still declaring application/json. GET requests must omit a body.
+        let requestBody;
+        if (input.method === 'GET') {
+            requestBody = undefined;
+        }
+        else if (input.body === undefined) {
+            requestBody = '';
+        }
+        else {
+            requestBody = JSON.stringify(input.body);
+        }
         const headers = new Headers({
             accept: 'application/json',
-            'content-type': 'application/json',
+            ...(input.method === 'GET' ? {} : { 'content-type': 'application/json' }),
             ...input.headers,
         });
         let response;
         let text;
         try {
             response = await input.mtls.fetch(input.url, {
-                method: 'POST',
+                method: input.method,
                 headers,
-                body: requestBody,
+                ...(requestBody === undefined ? {} : { body: requestBody }),
                 signal: timeout.signal,
             });
             text = await readBoundedResponseText(response);
@@ -181,6 +243,60 @@ function parseFunctionalMessageResult(input, status) {
         contentIds: readContentIds(input.detail),
     };
 }
+function parseLoginToken(input, status) {
+    if (!isRecord(input)) {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an invalid login token.', status);
+    }
+    const tokenType = requireOpaqueValue(input.tokenType, 'tokenType', status, 64).toLowerCase();
+    if (tokenType !== 'bearer') {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an unsupported token type.', status);
+    }
+    return {
+        tokenType,
+        accessToken: requireOpaqueValue(input.accessToken, 'accessToken', status, 16384),
+        refreshToken: requireOpaqueValue(input.refreshToken, 'refreshToken', status, 16384),
+        expiresInSeconds: requirePositiveInteger(input.expiresIn, 'expiresIn', status),
+        scope: requireOpaqueValue(input.scope, 'scope', status, 4096),
+    };
+}
+function parseLoginUser(input, status) {
+    if (!isRecord(input)) {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an invalid login user.', status);
+    }
+    return {
+        userKey: requireTossUserKey(input.userKey, 'userKey', status),
+        scope: requireOpaqueValue(input.scope, 'scope', status, 4096),
+    };
+}
+function parseIapOrderStatus(input, status) {
+    if (!isRecord(input)) {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an invalid IAP order status.', status);
+    }
+    const orderStatus = requireOpaqueValue(input.status, 'status', status, 64);
+    if (!appsInTossIapOrderStatuses.has(orderStatus)) {
+        throw new AppsInTossPartnerApiError('Apps in Toss returned an unknown IAP order status.', status);
+    }
+    const reason = input.reason;
+    return {
+        orderId: requireOpaqueValue(input.orderId, 'orderId', status, 2048),
+        sku: requireOpaqueValue(input.sku, 'sku', status, 2048),
+        statusDeterminedAt: requireOpaqueValue(input.statusDeterminedAt, 'statusDeterminedAt', status, 2048),
+        status: orderStatus,
+        ...(reason === undefined
+            ? {}
+            : { reason: requireOpaqueValue(reason, 'reason', status, 4096) }),
+    };
+}
+const appsInTossIapOrderStatuses = new Set([
+    'PURCHASED',
+    'PAYMENT_COMPLETED',
+    'FAILED',
+    'REFUNDED',
+    'ORDER_IN_PROGRESS',
+    'NOT_FOUND',
+    'MINIAPP_MISMATCH',
+    'ERROR',
+]);
 function readContentIds(detail) {
     if (!isRecord(detail)) {
         return [];
@@ -240,6 +356,72 @@ function normalizeIdentifier(value, field) {
     }
     return normalized;
 }
+function normalizeLoginReferrer(value) {
+    if (value !== 'DEFAULT' && value !== 'SANDBOX') {
+        throw new TypeError('referrer must be DEFAULT or SANDBOX.');
+    }
+    return value;
+}
+function normalizeOpaqueValue(value, field, maximumLength) {
+    if (value.length === 0
+        || value.length > maximumLength
+        || value.trim() !== value
+        || /[\p{Cc}\p{Cf}]/u.test(value)) {
+        throw new TypeError(`${field} must contain 1 to ${maximumLength} characters without surrounding whitespace, control, or format characters.`);
+    }
+    return value;
+}
+function requireOpaqueValue(value, field, status, maximumLength) {
+    if (typeof value !== 'string') {
+        throw new AppsInTossPartnerApiError(`Apps in Toss returned an invalid ${field}.`, status);
+    }
+    try {
+        return normalizeOpaqueValue(value, field, maximumLength);
+    }
+    catch {
+        throw new AppsInTossPartnerApiError(`Apps in Toss returned an invalid ${field}.`, status);
+    }
+}
+function requirePositiveInteger(value, field, status) {
+    let parsed;
+    if (typeof value === 'number') {
+        parsed = value;
+    }
+    else if (typeof value === 'string' && /^\d+$/u.test(value)) {
+        parsed = Number(value);
+    }
+    else {
+        parsed = Number.NaN;
+    }
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) {
+        throw new AppsInTossPartnerApiError(`Apps in Toss returned an invalid ${field}.`, status);
+    }
+    return parsed;
+}
+function parseTossUserKey(value) {
+    let normalized;
+    if (typeof value === 'number') {
+        normalized = Number.isSafeInteger(value) && value > 0 ? String(value) : undefined;
+    }
+    else if (typeof value === 'string' && /^[1-9]\d*$/u.test(value)) {
+        normalized = value;
+    }
+    return normalized;
+}
+function normalizeTossUserKey(value, field) {
+    const normalized = parseTossUserKey(value);
+    if (normalized === undefined) {
+        throw new TypeError(`${field} must be a positive Apps in Toss user key.`);
+    }
+    return normalized;
+}
+function requireTossUserKey(value, field, status) {
+    const normalized = parseTossUserKey(value);
+    if (normalized === undefined) {
+        throw new AppsInTossPartnerApiError(`Apps in Toss returned an invalid ${field}.`, status);
+    }
+    return normalized;
+}
 function normalizeBaseUrl(input) {
     const url = new URL(input);
     if (url.protocol !== 'https:'

package/dist/client.js

@@ -67,13 +67,30 @@ export function createGameServicesClient(input) {
                     purchase,
                 };
             }
+            if (isAuthoritativeMicrosoftStoreCompletion(target, purchase)) {
+                const result = {
+                    status: 'granted',
+                    purchase,
+                    ledgerEntryId: purchase.transactionId,
+                };
+                await analytics.track({
+                    name: 'purchase_granted',
+                    properties: {
+                        productId: purchaseInput.productId,
+                        status: result.status,
+                        ledgerEntryId: purchase.transactionId,
+                        alreadyProcessed: purchase.authoritativeGrant?.alreadyProcessed,
+                    },
+                });
+                return result;
+            }
             if (purchase.status !== 'completed' || purchase.transactionId === undefined) {
                 await analytics.track({
                     name: 'purchase_rejected',
                     properties: {
                         productId: purchaseInput.productId,
                         status: purchase.status,
-                        reason: purchase.transactionId === undefined ? 'missing_transaction_id' : undefined,
+                        reason: purchaseRejectionReason(purchase),
                     },
                 });
                 return {
@@ -323,14 +340,34 @@ export function createGameServicesIdempotencyKey(input) {
 function normalizeSegment(value) {
     return value.replaceAll(/[^a-zA-Z0-9_-]+/g, '-').replaceAll(/^-|-$/g, '').slice(0, 64);
 }
+function purchaseRejectionReason(purchase) {
+    if (purchase.status === 'completed' && purchase.transactionId === undefined) {
+        return 'missing_transaction_id';
+    }
+    if (purchase.status === 'pending') {
+        return 'purchase_pending';
+    }
+    return undefined;
+}
+function isAuthoritativeMicrosoftStoreCompletion(target, purchase) {
+    return target === 'microsoft-store'
+        && purchase.status === 'completed'
+        && purchase.transactionId !== undefined
+        && purchase.authoritativeGrant?.ledgerEntryId === purchase.transactionId;
+}
 function isGameServicesCommerceTarget(target) {
-    return target === 'android' || target === 'ios' || target === 'ait' || target === 'verse8';
+    return target === 'microsoft-store'
+        || 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 === 'microsoft-store'
         || target === 'android'
         || target === 'ios'
         || target === 'ait'

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export * from './client';
 export * from './contract';
 export * from './evidence-verification';
 export * from './google-play-purchase';
+export * from './microsoft-store-purchase';
 export * from './notification-delivery';
 export * from './platform-order';
 export * from './progress-link';

package/dist/index.js

@@ -6,6 +6,7 @@ export * from './client';
 export * from './contract';
 export * from './evidence-verification';
 export * from './google-play-purchase';
+export * from './microsoft-store-purchase';
 export * from './notification-delivery';
 export * from './platform-order';
 export * from './progress-link';

package/dist/microsoft-store-purchase.d.ts

@@ -0,0 +1,131 @@
+import type { GameServicesEvidenceVerifier, GameServicesPurchaseGrantFinalizer, VerifyPurchaseEvidenceInput } from './evidence-verification';
+export declare const microsoftStoreDigitalGoodsEvidenceSchema: 'mpgd.microsoft-store.digital-goods.v1';
+export declare const microsoftStoreCollectionsQueryUrl: 'https://collections.mp.microsoft.com/v9.0/collections/publisherQuery';
+export declare const microsoftStoreCollectionsConsumeUrl: 'https://collections.mp.microsoft.com/v8.0/collections/consume';
+export interface MicrosoftStoreCollectionsCredentials {
+  /** Runtime-generated Microsoft Entra service access token. */
+  readonly accessToken: string;
+  /** Server-resolved User Store ID. Never accept this value from purchase evidence. */
+  readonly userStoreId: string;
+  /**
+  * Stable opaque ID for the trusted player-to-Store-account link. It must survive User Store ID
+  * renewal, resolve to the same value whenever the same Store account appears, and change only
+  * when the player links a different Store account. Never use the User Store ID, a player-pair
+  * identifier, or another renewable credential as this value.
+  */
+  readonly accountBindingId: string;
+  /** Omit for RETAIL. Non-RETAIL developer-managed consume requires delegated XSTS. */
+  readonly sandbox?: string;
+}
+export interface MicrosoftStoreCollectionsClient {
+  queryProduct(input: {
+    readonly credentials: MicrosoftStoreCollectionsCredentials;
+    readonly storeId: string;
+    readonly signal: AbortSignal;
+  }): Promise<unknown>;
+  consumeProduct(input: {
+    readonly credentials: MicrosoftStoreCollectionsCredentials;
+    readonly storeId: string;
+    readonly trackingId: string;
+    readonly signal: AbortSignal;
+  }): Promise<unknown>;
+}
+export interface MicrosoftStoreFetchResponse {
+  readonly status: number;
+  readonly body: ReadableStream<Uint8Array> | null;
+}
+export type MicrosoftStoreFetch = (url: string, init: {
+  readonly method: 'POST';
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly signal: AbortSignal;
+}) => Promise<MicrosoftStoreFetchResponse>;
+export interface CreateMicrosoftStoreCollectionsClientInput {
+  readonly fetch?: MicrosoftStoreFetch;
+  readonly userAgent?: string;
+  readonly maxResponseBytes?: number;
+}
+export interface CreateMicrosoftStorePurchaseBoundaryInput {
+  readonly client: MicrosoftStoreCollectionsClient;
+  /** Trusted logical-product to current Digital Goods Product ID mapping. */
+  readonly inAppOfferTokens: Readonly<Record<string, string>>;
+  readonly storeIds: Readonly<Record<string, string>>;
+  /** Keep old Digital Goods token/Collections ID pairs until pending purchases are settled. */
+  readonly historicalProductMappings?: Readonly<Record<string, readonly MicrosoftStoreHistoricalProductMapping[]>>;
+  readonly resolveCredentials: (playerId: string, signal: AbortSignal) => Promise<MicrosoftStoreCollectionsCredentials> | MicrosoftStoreCollectionsCredentials;
+  /**
+  * Durable, atomic ownership registry. Browser storage is never an authorization source.
+  * Production implementations must share this state across every game-service instance.
+  */
+  readonly recoveryOwnershipStore: MicrosoftStoreRecoveryOwnershipStore;
+  readonly now?: () => string;
+}
+export interface MicrosoftStoreHistoricalProductMapping {
+  readonly inAppOfferToken: string;
+  readonly storeId: string;
+}
+export interface MicrosoftStoreRecoveryOwnershipInput {
+  readonly playerId: string;
+  readonly productId: string;
+  readonly inAppOfferToken: string;
+  readonly purchaseToken: string;
+  /** Stable checkout identity used as an opaque ownership generation. */
+  readonly idempotencyKey?: string;
+  readonly evidence: {
+    readonly schema: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+  };
+  readonly signal: AbortSignal;
+}
+export interface MicrosoftStoreRecoveryOwnershipRecord {
+  readonly accountBindingHash: string;
+  readonly storeId: string;
+  readonly playerId: string;
+  readonly generation: string;
+  /** Stable identity derived from the exact Collections item being granted. */
+  readonly providerPurchaseId: string;
+}
+export type MicrosoftStoreRecoveryOwnershipLookup = Omit<MicrosoftStoreRecoveryOwnershipRecord, 'generation' | 'providerPurchaseId'> & {
+  readonly generation?: string;
+  readonly providerPurchaseId?: string;
+};
+export type MicrosoftStoreRecoveryOwnershipResult = {
+  readonly status: 'granted';
+  readonly idempotencyKey: string;
+} | {
+  readonly status: 'denied';
+} | {
+  readonly status: 'unavailable';
+};
+export interface MicrosoftStoreRecoveryOwnershipStore {
+  /**
+  * Atomically claims an unconsumed Store product for one authenticated game player. An
+  * existing claim for the same provider purchase remains unchanged so a retry cannot replace
+  * its generation. A different provider purchase may atomically replace the same player's
+  * consumed purchase claim. Return the effective record, or undefined when another player owns
+  * the Store product binding.
+  */
+  claim(input: MicrosoftStoreRecoveryOwnershipRecord): Promise<MicrosoftStoreRecoveryOwnershipRecord | undefined>;
+  get(input: MicrosoftStoreRecoveryOwnershipLookup): Promise<MicrosoftStoreRecoveryOwnershipRecord | undefined>;
+  /** Atomically releases only the exact player, generation, and provider purchase supplied. */
+  release(input: MicrosoftStoreRecoveryOwnershipRecord): Promise<void>;
+}
+export interface MicrosoftStorePurchaseBoundary extends GameServicesPurchaseGrantFinalizer {
+  claimRecoveryOwnership(input: MicrosoftStoreRecoveryOwnershipInput): Promise<MicrosoftStoreRecoveryOwnershipResult>;
+  hasRecoveryOwnership(input: MicrosoftStoreRecoveryOwnershipInput): Promise<MicrosoftStoreRecoveryOwnershipResult>;
+  verifyPurchase(input: VerifyPurchaseEvidenceInput): ReturnType<GameServicesEvidenceVerifier['verifyPurchase']>;
+}
+/** Process-local test/development store. Production requires durable atomic shared storage. */
+export declare class InMemoryMicrosoftStoreRecoveryOwnershipStore implements MicrosoftStoreRecoveryOwnershipStore {
+  private readonly owners;
+  claim(input: MicrosoftStoreRecoveryOwnershipRecord): Promise<MicrosoftStoreRecoveryOwnershipRecord | undefined>;
+  get(input: MicrosoftStoreRecoveryOwnershipLookup): Promise<MicrosoftStoreRecoveryOwnershipRecord | undefined>;
+  release(input: MicrosoftStoreRecoveryOwnershipRecord): Promise<void>;
+}
+export declare function createInMemoryMicrosoftStoreRecoveryOwnershipStore(): MicrosoftStoreRecoveryOwnershipStore;
+export declare class MicrosoftStoreCollectionsUnavailableError extends Error {
+  readonly cause: unknown;
+  constructor(message: string, cause?: unknown);
+}
+export declare function createMicrosoftStoreCollectionsClient(input?: CreateMicrosoftStoreCollectionsClientInput): MicrosoftStoreCollectionsClient;
+export declare function createMicrosoftStorePurchaseBoundary(input: CreateMicrosoftStorePurchaseBoundaryInput): MicrosoftStorePurchaseBoundary;