@looplay/sdk 0.5.0 → 0.6.0

package/dist/types/apps/LooplaySDK.types.d.ts

@@ -1,4 +1,4 @@
-export type { GameEventKey, TrackMatchEndRequest, EmitGameEventRequest, EmitGameEventResponse } from '@looplay/types';
+export type { GameEventKey, EmitGameEventResponse } from '@looplay/types';
 export interface AuthResultDto {
     accessToken: string;
     refreshToken: string;
@@ -10,11 +10,6 @@ export interface TelegramLoginRequest {
 export interface RefreshTokenRequest {
     refreshToken: string;
 }
-export interface TrackGamePlayRequest {
-    playTimeSeconds?: number;
-    /** Canonical identifier for one play attempt — required by the backend, stable for retries. */
-    attemptId: string;
-}
 /**
  * Returned by `POST /sdk/games/tracking/bootstrap`. Anonymous runtimes must
  * fetch this first; logged-in runtimes should still attach `trackingSessionId`
@@ -26,31 +21,149 @@ export interface GameTrackingSessionDto {
     trackingToken: string;
     expiresAt: string;
 }
+export interface StartGameplayAttemptRequest {
+    /** Optional client-generated id. When omitted, the server creates one. */
+    attemptId?: string;
+}
+export interface GameplayAttemptSessionDto {
+    trackingSessionId: string;
+    attemptId: string;
+    attemptToken: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+export interface CompleteGameplayAttemptRequest {
+    /** Total play duration of this attempt, in seconds. */
+    playTimeSeconds?: number;
+    /** Canonical identifier for one play attempt. */
+    attemptId: string;
+    /** Signed by the server when the gameplay attempt starts — see `StartGameplayAttemptRequest`. */
+    attemptToken: string;
+}
+export interface CompleteGameplayMatchRequest {
+    attemptId: string;
+    attemptToken: string;
+    /** Idempotency anchor — same matchId = same event, dedup-safe. */
+    matchId: string;
+    matchDurationSeconds: number;
+    isCompleted?: boolean;
+    isWin?: boolean;
+}
+export interface RecordGameplayActionRequest {
+    attemptId: string;
+    attemptToken: string;
+    matchId?: string;
+    actionCode: string;
+    value?: number;
+    /**
+     * Stable refId for dedup. When present the event is idempotent per
+     * (userId, gameId, actionCode, refId). When absent a timestamp is used.
+     */
+    refId?: string;
+    /** Preferred name for the action occurrence id. Same semantics as refId. */
+    eventId?: string;
+    payload?: Record<string, unknown>;
+}
 export interface PagingResponse<T> {
     items: T[];
-    total: number;
-    page: number;
-    limit: number;
+    totalItems: number;
+    pageIndex: number;
+    pageSize: number;
+    totalPages: number;
 }
+export interface GameStoreOfferItemDto {
+    assetCode: string;
+    assetName: string;
+    quantity: number;
+}
+export interface GameStoreOfferDto {
+    id: string;
+    gameId: string;
+    storeId?: string;
+    offerCode: string;
+    name: string;
+    sectionCode?: string | null;
+    priceCoin: number;
+    discountPercent: number;
+    effectivePriceCoin: number;
+    startAt?: string | null;
+    endAt?: string | null;
+    sortOrder: number;
+    isActive: boolean;
+    items: GameStoreOfferItemDto[];
+}
+export interface GameStoreSectionWithOffersDto {
+    id: string;
+    gameId: string;
+    code: string;
+    name: string;
+    sortOrder: number;
+    isActive: boolean;
+    offers: GameStoreOfferDto[];
+}
+/** Player-facing storefront for a game. */
+export interface GameStoreDto {
+    storeId?: string;
+    sections: GameStoreSectionWithOffersDto[];
+    /** Active offers with no sectionCode — rendered outside any section. */
+    unsectionedOffers: GameStoreOfferDto[];
+}
+export interface GameStoreOfferPurchaseResultDto {
+    offerCode: string;
+    name: string;
+    quantity: number;
+    priceCoin: number;
+    totalCoin: number;
+    requestId: string;
+    items: GameStoreOfferItemDto[];
+}
+/** Public asset (SKU) catalog entry — no price; price lives on the offer that sells it. */
 export interface GameAssetDto {
     id: string;
     gameId: string;
     assetCode: string;
     name: string;
-    priceCoin: number;
     isActive: boolean;
 }
-export interface PurchaseGameAssetRequest {
+/** An asset the authenticated player currently owns. */
+export interface GameOwnedAssetDto {
+    assetCode: string;
+    assetName: string;
+    quantity: number;
+}
+/** JWT tier — `POST sdk/games/store/by-store-id/checkout-intent`. */
+export interface CreateGameStoreCheckoutIntentRequest {
+    storeId: string;
+    offerCode: string;
     /** Optional client-supplied dedupe key so a retried request returns the same result instead of charging twice. */
     requestId?: string;
     /** Defaults to 1 on the backend. */
     quantity?: number;
 }
-export interface GameAssetPurchaseResultDto {
-    assetCode: string;
-    name: string;
-    quantity: number;
-    priceCoin: number;
-    totalCoin: number;
+export interface GameStoreCheckoutIntentDto {
+    storeId: string;
+    offerCode: string;
     requestId: string;
+    quantity: number;
+    checkoutToken: string;
+    issuedAt: string;
+    expiresAt: string;
+}
+/** JWT tier — `POST sdk/games/store/by-store-id/purchase`. */
+export interface PurchaseGameStoreOfferRuntimeRequest extends CreateGameStoreCheckoutIntentRequest {
+    /** Signed by the server when the checkout intent is created — see `CreateGameStoreCheckoutIntentRequest`. */
+    checkoutToken: string;
+}
+/** Mirrors the backend's `AppPlatform` enum — kept as a literal union to avoid a cross-repo enum dependency. */
+export type AppPlatform = 'telegram' | 'tiktok' | 'web' | 'base' | 'worldapp';
+/** Mirrors the backend's `MobileOs` enum. */
+export type MobileOs = 'ios' | 'android';
+/**
+ * Query for `GET sdk/task` / `GET sdk/task/finished`.
+ * - `platform` defaults to `'telegram'` on the backend when omitted.
+ * - `os` is optional; when set, returns (os-specific + general) tasks.
+ */
+export interface TaskListQuery {
+    platform?: AppPlatform;
+    os?: MobileOs;
 }

package/dist/types/apps/api-client.d.ts

@@ -1,4 +1,4 @@
-import type { EmitGameEventResponse, GameAssetDto, GameAssetPurchaseResultDto, GameEventKey, PagingResponse, PurchaseGameAssetRequest, TrackMatchEndRequest } from './LooplaySDK.types';
+import type { EmitGameEventResponse, GameEventKey, GameStoreDto, GameStoreOfferPurchaseResultDto, PagingResponse, TaskListQuery } from './LooplaySDK.types';
 import { ServiceClient } from './service-client';
 import type { ServiceClientOptions } from './service-client';
 export interface ApiClientOptions extends Omit<ServiceClientOptions, 'baseUrl'> {
@@ -21,6 +21,8 @@ export declare class ApiClient {
     private trackingSession?;
     private trackingSessionPromise?;
     private currentAttemptId?;
+    private gameplayAttempt?;
+    private gameplayAttemptPromise?;
     constructor(options: ApiClientOptions);
     /** Expose the underlying route-level client (requires manual bearerToken passing). */
     unsafeRaw(): ServiceClient;
@@ -41,35 +43,57 @@ export declare class ApiClient {
      * just without unified session tracing.
      */
     private ensureTrackingSession;
+    /**
+     * Signs (and caches until near expiry) the `attemptToken` required by
+     * `trackPlay`/`trackMatch`/`emit` for the current attempt — does not
+     * swallow failures, unlike `ensureTrackingSession`, since these calls
+     * are rejected outright without a valid token.
+     */
+    private ensureGameplayAttempt;
     getGameDetail(gameId: string): Promise<any>;
+    private resolveStoreId;
     listRecentPlayed(query?: Record<string, any>): Promise<PagingResponse<any>>;
     /** Call once when the game view opens, before any play/match tracking. */
     trackView(gameId: string): Promise<boolean>;
     /**
      * Starts a new play attempt and returns its id. Call when the user
-     * presses Play; `trackPlay` reuses this id across calls until the next
+     * presses Play; `trackPlay`/`trackMatch`/`emit` reuse this id (and the
+     * signed `attemptToken` backing it) across calls until the next
      * `startAttempt()`, auto-starting one on first use if none was started.
      */
     startAttempt(): string;
     trackPlay(gameId: string, playTimeSeconds?: number): Promise<boolean>;
-    trackMatch(gameId: string, body: TrackMatchEndRequest): Promise<boolean>;
+    trackMatch(gameId: string, body: {
+        matchId: string;
+        matchDurationSeconds: number;
+        isCompleted?: boolean;
+        isWin?: boolean;
+    }): Promise<boolean>;
     emit(gameId: string, actionCode: GameEventKey | string, opts?: {
         value?: number;
         refId?: string;
         payload?: Record<string, unknown>;
     }): Promise<EmitGameEventResponse>;
-    /** Lists assets purchasable in `gameId`, defined by that game's creator. */
-    listGameAssets(gameId: string): Promise<GameAssetDto[]>;
-    /** Spends coin balance to purchase an asset — see PurchaseGameAssetRequest for dedupe/quantity. */
-    purchaseGameAsset(gameId: string, assetCode: string, opts?: PurchaseGameAssetRequest): Promise<GameAssetPurchaseResultDto>;
+    /** Fetches the storefront (sections + offers) for `gameId`, defined by that game's creator. */
+    getStore(gameId: string): Promise<GameStoreDto>;
+    /** Purchase history for the authenticated player in `gameId`'s store. */
+    listMyStorePurchases(gameId: string): Promise<GameStoreOfferPurchaseResultDto[]>;
+    /**
+     * Spends coin balance to purchase a store offer — signs a checkout intent
+     * first, then redeems it, mirroring the gameplay attempt flow above.
+     */
+    purchaseStoreOffer(gameId: string, offerCode: string, opts?: {
+        requestId?: string;
+        quantity?: number;
+    }): Promise<GameStoreOfferPurchaseResultDto>;
     getMyProfile(): Promise<any>;
     getMyBalance(): Promise<any>;
     getBalances(query?: Record<string, any>): Promise<any>;
     getBalanceHistory(query?: Record<string, any>): Promise<PagingResponse<any>>;
     listReferrals(query?: Record<string, any>): Promise<PagingResponse<any>>;
     setReferral(body: Record<string, any>): Promise<boolean>;
-    listTasks(): Promise<any[]>;
-    listFinishedTasks(): Promise<any[]>;
+    listTasks(query?: TaskListQuery): Promise<any[]>;
+    listFinishedTasks(query?: TaskListQuery): Promise<any[]>;
     startTask(body: Record<string, any>): Promise<any>;
     claimTask(body: Record<string, any>): Promise<any>;
 }

package/dist/types/apps/service-client.d.ts

@@ -1,14 +1,14 @@
 import { type HttpClientOptions } from './http';
-import type { AuthResultDto, EmitGameEventRequest, EmitGameEventResponse, GameAssetDto, GameAssetPurchaseResultDto, GameTrackingSessionDto, PagingResponse, PurchaseGameAssetRequest, TrackMatchEndRequest } from './LooplaySDK.types';
+import type { AuthResultDto, CompleteGameplayAttemptRequest, CompleteGameplayMatchRequest, CreateGameStoreCheckoutIntentRequest, EmitGameEventResponse, GameAssetDto, GameOwnedAssetDto, GameplayAttemptSessionDto, GameStoreCheckoutIntentDto, GameStoreDto, GameStoreOfferPurchaseResultDto, GameTrackingSessionDto, PagingResponse, PurchaseGameStoreOfferRuntimeRequest, RecordGameplayActionRequest, StartGameplayAttemptRequest, TaskListQuery } from './LooplaySDK.types';
 export interface ServiceClientOptions extends HttpClientOptions {
 }
 /**
- * Auth for the tracking endpoints (`view`/`play`/`end`/`emit`), which accept
+ * Auth for the tracking endpoints (view/attempt/match/action), which accept
  * either a real user's `bearerToken` (full tracking, eligible for
  * quest/reward) or an `anonId` for an unauthenticated device
  * (analytics-only — the backend never awards quest/reward progress to an
  * anonymous id). `trackingSessionId`/`anonTrackingToken` come from
- * `issueTrackingSession()` and should be attached either way, per the
+ * `bootstrapTrackingSession()` and should be attached either way, per the
  * platform's tracking contract.
  */
 export interface TrackingAuth {
@@ -30,27 +30,40 @@ export declare class ServiceClient {
     listGames(query?: Record<string, any>): Promise<PagingResponse<any>>;
     getGameDetail(gameId: string, bearerToken?: string): Promise<any>;
     listRecentPlayed(bearerToken: string, query?: Record<string, any>): Promise<PagingResponse<any>>;
-    trackView(auth: TrackingAuth, gameId: string): Promise<boolean>;
-    trackPlay(auth: TrackingAuth, gameId: string, attemptId: string, playTimeSeconds?: number): Promise<boolean>;
-    trackMatchEnd(auth: TrackingAuth, gameId: string, body: TrackMatchEndRequest): Promise<boolean>;
-    emitGameEvent(auth: TrackingAuth, gameId: string, body: EmitGameEventRequest): Promise<EmitGameEventResponse>;
+    recordGameView(auth: TrackingAuth, gameId: string): Promise<boolean>;
+    /** Signs a fresh `attemptToken` — required by `completeGameplayAttempt`/`completeGameplayMatch`/`recordGameplayAction`. */
+    startGameplayAttempt(auth: TrackingAuth, gameId: string, body?: StartGameplayAttemptRequest): Promise<GameplayAttemptSessionDto>;
+    completeGameplayAttempt(auth: TrackingAuth, gameId: string, body: CompleteGameplayAttemptRequest): Promise<boolean>;
+    completeGameplayMatch(auth: TrackingAuth, gameId: string, body: CompleteGameplayMatchRequest): Promise<boolean>;
+    recordGameplayAction(auth: TrackingAuth, gameId: string, body: RecordGameplayActionRequest): Promise<EmitGameEventResponse>;
     /**
      * Anonymous runtimes must call this before any tracking call; logged-in
      * runtimes should still call it to get a `trackingSessionId` for unified
      * tracing — see `GameTrackingSessionDto`.
      */
-    issueTrackingSession(anonId?: string): Promise<GameTrackingSessionDto>;
+    bootstrapTrackingSession(anonId?: string): Promise<GameTrackingSessionDto>;
     private trackingHeaders;
-    listGameAssets(gameId: string, bearerToken?: string): Promise<GameAssetDto[]>;
-    purchaseGameAsset(bearerToken: string, gameId: string, assetCode: string, body?: PurchaseGameAssetRequest): Promise<GameAssetPurchaseResultDto>;
+    getStoreByStoreId(storeId: string): Promise<GameStoreDto>;
+    listMyStorePurchasesByStoreId(bearerToken: string, storeId: string): Promise<GameStoreOfferPurchaseResultDto[]>;
+    createStoreCheckoutIntent(bearerToken: string, body: CreateGameStoreCheckoutIntentRequest, trackingSessionId?: string): Promise<GameStoreCheckoutIntentDto>;
+    purchaseStoreOffer(bearerToken: string, body: PurchaseGameStoreOfferRuntimeRequest, trackingSessionId?: string): Promise<GameStoreOfferPurchaseResultDto>;
+    recordGameViewForGameKey(gameKey: string, auth?: TrackingAuth): Promise<boolean>;
+    startGameplayAttemptForGameKey(gameKey: string, auth?: TrackingAuth, body?: StartGameplayAttemptRequest): Promise<GameplayAttemptSessionDto>;
+    completeGameplayAttemptForGameKey(gameKey: string, auth: TrackingAuth | undefined, body: CompleteGameplayAttemptRequest): Promise<boolean>;
+    completeGameplayMatchForGameKey(gameKey: string, auth: TrackingAuth | undefined, body: CompleteGameplayMatchRequest): Promise<boolean>;
+    recordGameplayActionForGameKey(gameKey: string, auth: TrackingAuth | undefined, body: RecordGameplayActionRequest): Promise<EmitGameEventResponse>;
+    getStoreForGameKey(gameKey: string): Promise<GameStoreDto>;
+    listGameAssetsForGameKey(gameKey: string): Promise<GameAssetDto[]>;
+    listMyOwnedAssetsForGameKey(bearerToken: string, gameKey: string): Promise<GameOwnedAssetDto[]>;
+    listMyStorePurchasesForGameKey(bearerToken: string, gameKey: string): Promise<GameStoreOfferPurchaseResultDto[]>;
     getBalances(bearerToken: string, query?: Record<string, any>): Promise<any>;
     getBalanceHistory(bearerToken: string, query?: Record<string, any>): Promise<PagingResponse<any>>;
     getMyProfile(bearerToken: string): Promise<any>;
     getMyBalance(bearerToken: string): Promise<any>;
     listReferrals(bearerToken: string, query?: Record<string, any>): Promise<PagingResponse<any>>;
     setReferral(bearerToken: string, body: Record<string, any>): Promise<boolean>;
-    listTasks(bearerToken: string): Promise<any[]>;
-    listFinishedTasks(bearerToken: string): Promise<any[]>;
+    listTasks(bearerToken: string, query?: TaskListQuery): Promise<any[]>;
+    listFinishedTasks(bearerToken: string, query?: TaskListQuery): Promise<any[]>;
     startTask(bearerToken: string, body: Record<string, any>): Promise<any>;
     claimTask(bearerToken: string, body: Record<string, any>): Promise<any>;
 }

package/dist/types/errors.d.ts

@@ -13,3 +13,6 @@ export declare class MissingAuthError extends LooplaySDKError {
 export declare class NotAuthenticatedError extends LooplaySDKError {
     constructor();
 }
+export declare class MissingStoreError extends LooplaySDKError {
+    constructor(gameId: string);
+}

package/dist/types/iframe/types.d.ts

@@ -36,9 +36,9 @@ export interface LooplayIframeAuthOptions {
     /** localStorage key for the persisted anonymous device id. Default `'looplay:anon-id'`. */
     anonymousIdStorageKey?: string;
     /**
-     * Optional auto-trigger for rewarded ads after play/match activity.
+     * Optional auto-trigger for rewarded ads after match activity.
      * When enabled, the SDK may call `requestAds()` after the configured
-     * total play/match threshold is reached and the random chance passes.
+     * match threshold is reached and the random chance passes.
      */
     autoRequestAds?: {
         enabled?: boolean;

package/dist/types/index.d.ts

@@ -5,4 +5,3 @@ export * from './auth';
 export * from './apps';
 export * from './iframe';
 export type { GameEventKey } from '@looplay/types';
-export type { TrackMatchEndRequest, EmitGameEventRequest, EmitGameEventResponse } from '@looplay/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looplay/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "LooplaySDK (auth + points) for game integrations",
   "license": "UNLICENSED",
   "type": "module",