@looplay/sdk 0.5.1 → 0.7.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,139 @@ export interface GameTrackingSessionDto {
     trackingToken: string;
     expiresAt: string;
 }
+export interface StartGameplayAttemptRequest {
+    /** Optional client-generated id. When omitted, the server creates one. */
+    attemptId?: string;
+    /**
+     * One-call convenience: when set, the server also records this action
+     * (e.g. `"GAME_STARTED"`) right after issuing the attempt, using the
+     * freshly signed `attemptId`/`attemptToken` — skips a separate
+     * `recordGameplayAction` call. See `matchId`/`value`/`refId`/`eventId`/
+     * `payload` below for the action's own fields.
+     */
+    actionCode?: string;
+    matchId?: string;
+    value?: number;
+    refId?: string;
+    eventId?: string;
+    payload?: Record<string, unknown>;
+}
+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 GameAssetDto {
+export interface GameStoreOfferItemDto {
+    assetCode: string;
+    assetName: string;
+    quantity: number;
+}
+export interface GameStoreOfferDto {
     id: string;
     gameId: string;
-    assetCode: 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 PurchaseGameAssetRequest {
-    /** 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 GameStoreSectionWithOffersDto {
+    id: string;
+    gameId: string;
+    code: string;
+    name: string;
+    sortOrder: number;
+    isActive: boolean;
+    offers: GameStoreOfferDto[];
 }
-export interface GameAssetPurchaseResultDto {
-    assetCode: string;
+/** 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;
+    isActive: boolean;
+}
+/** An asset the authenticated player currently owns. */
+export interface GameOwnedAssetDto {
+    assetCode: string;
+    assetName: string;
+    quantity: number;
+}
+/** 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, GameAssetDto, GameEventKey, GameOwnedAssetDto, 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,10 +21,11 @@ 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). */
+    /** Expose the underlying route-level client (requires manual bearerToken/gameKey passing). */
     unsafeRaw(): ServiceClient;
-    listGames(query?: Record<string, any>): Promise<PagingResponse<any>>;
     private requireToken;
     /**
      * Resolves auth for the tracking endpoints: a real bearer token if logged
@@ -41,35 +42,53 @@ export declare class ApiClient {
      * just without unified session tracing.
      */
     private ensureTrackingSession;
-    getGameDetail(gameId: string): Promise<any>;
-    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>;
+    /**
+     * 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;
+    /**
+     * Call once when the game view opens, before any play/match tracking.
+     * `gameKey` is the game's public `appId`.
+     */
+    trackView(gameKey: 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>;
-    emit(gameId: string, actionCode: GameEventKey | string, opts?: {
+    trackPlay(gameKey: string, playTimeSeconds?: number): Promise<boolean>;
+    trackMatch(gameKey: string, body: {
+        matchId: string;
+        matchDurationSeconds: number;
+        isCompleted?: boolean;
+        isWin?: boolean;
+    }): Promise<boolean>;
+    emit(gameKey: 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 the integration's game. Read-only, no auth required. */
+    getStore(gameKey: string): Promise<GameStoreDto>;
+    /** Public catalog of purchasable/ownable assets for the game. Read-only, no auth required. */
+    listGameAssets(gameKey: string): Promise<GameAssetDto[]>;
+    /** Assets the authenticated player already owns for this game. */
+    listMyGameAssets(gameKey: string): Promise<GameOwnedAssetDto[]>;
+    /** Purchase history for the authenticated player in the game's store. */
+    listMyStorePurchases(gameKey: string): 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, EmitGameEventResponse, GameAssetDto, GameOwnedAssetDto, GameplayAttemptSessionDto, GameStoreDto, GameStoreOfferPurchaseResultDto, GameTrackingSessionDto, PagingResponse, 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 {
@@ -27,30 +27,35 @@ export declare class ServiceClient {
     telegramLogin(telegramInitData: string): Promise<AuthResultDto>;
     refresh(refreshToken: string): Promise<AuthResultDto>;
     logout(refreshToken: string): Promise<boolean>;
-    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(gameKey: string, auth?: TrackingAuth): Promise<boolean>;
+    /** Signs a fresh `attemptToken` — required by `completeGameplayAttempt`/`completeGameplayMatch`/`recordGameplayAction`. */
+    startGameplayAttempt(gameKey: string, auth?: TrackingAuth, body?: StartGameplayAttemptRequest): Promise<GameplayAttemptSessionDto>;
+    completeGameplayAttempt(gameKey: string, auth: TrackingAuth, body: CompleteGameplayAttemptRequest): Promise<boolean>;
+    completeGameplayMatch(gameKey: string, auth: TrackingAuth, body: CompleteGameplayMatchRequest): Promise<boolean>;
+    recordGameplayAction(gameKey: string, auth: TrackingAuth, 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>;
+    /** Public storefront (sections + offers) for the integration's game. Read-only. */
+    getStore(gameKey: string): Promise<GameStoreDto>;
+    /** Public catalog of purchasable/ownable assets for the game. Read-only. */
+    listGameAssets(gameKey: string): Promise<GameAssetDto[]>;
+    /** Assets the authenticated player already owns for this game. */
+    listMyGameAssets(bearerToken: string, gameKey: string): Promise<GameOwnedAssetDto[]>;
+    /** The authenticated player's past store purchases for this game. */
+    listMyStorePurchases(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/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/dist/types/types.d.ts

@@ -7,7 +7,8 @@ export interface LooplaySDKCreateOptions {
     defaultHeaders?: Record<string, string>;
 }
 export interface LooplayInitParams {
+    /** The game's public `appId` — same value as `x-game-key`, from your creator dashboard. */
     gameId: string;
-    /** 'none': skip verification | 'strict': verify via /games/:id (requires auth) */
+    /** 'none': skip verification | 'strict': resolve gameId via a read-only, unauthenticated call */
     verifyMode?: 'none' | 'strict';
 }

package/package.json

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