@looplay/sdk 0.6.0 → 0.8.1

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

@@ -24,6 +24,19 @@ export interface GameTrackingSessionDto {
 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;
@@ -131,9 +144,15 @@ export interface GameOwnedAssetDto {
     assetName: string;
     quantity: number;
 }
-/** JWT tier — `POST sdk/games/store/by-store-id/checkout-intent`. */
-export interface CreateGameStoreCheckoutIntentRequest {
-    storeId: string;
+/**
+ * Body shape shared by both purchase tiers: self-serve
+ * (`POST sdk/games/store/checkout-intent/me`, public `x-game-key` + the
+ * purchasing player's own JWT — see `ServiceClient.createMyStoreCheckoutIntent`)
+ * and server-to-server (`POST sdk/games/store/checkout-intent`, creator+game
+ * secret pair — see `ServiceClient.createGameStoreCheckoutIntent`). Signs a
+ * short-lived `checkoutToken`, mirroring the gameplay attempt flow.
+ */
+export interface SdkCreateGameStoreCheckoutIntentRequest {
     offerCode: string;
     /** Optional client-supplied dedupe key so a retried request returns the same result instead of charging twice. */
     requestId?: string;
@@ -149,11 +168,40 @@ export interface GameStoreCheckoutIntentDto {
     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`. */
+/** Shared by both purchase tiers — see `SdkCreateGameStoreCheckoutIntentRequest`. */
+export interface SdkPurchaseGameStoreOfferRuntimeRequest extends SdkCreateGameStoreCheckoutIntentRequest {
+    /** Signed by the server when the checkout intent is created — see `SdkCreateGameStoreCheckoutIntentRequest`. */
     checkoutToken: string;
 }
+/** Pushed on every balance change — purchases, quest rewards, referral payouts, etc. */
+export interface BalanceChangeEvent {
+    balanceType: string;
+    changeAmount: number;
+    changeType: string;
+    /** Present when multiple balance changes were batched into one push. */
+    changes?: Array<{
+        balanceType: string;
+        changeAmount: number;
+        changeType: string;
+    }>;
+}
+/**
+ * Pushed once a store purchase finishes — full result (items granted,
+ * quantity, price), unlike `BalanceChangeEvent` which only reports the coin
+ * delta. Fires for purchases made via either tier (self-serve or
+ * server-to-server), so a hosted-checkout backend flow can complete a
+ * purchase and have the game's own client react without polling.
+ */
+export interface StorePurchaseCompletedEvent {
+    gameId: string;
+    offerCode: string;
+    name: string;
+    quantity: number;
+    priceCoin: number;
+    totalCoin: number;
+    requestId: string;
+    items: GameStoreOfferItemDto[];
+}
 /** 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. */

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

@@ -1,4 +1,4 @@
-import type { EmitGameEventResponse, GameEventKey, GameStoreDto, GameStoreOfferPurchaseResultDto, PagingResponse, TaskListQuery } 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'> {
@@ -24,9 +24,8 @@ export declare class ApiClient {
     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
@@ -50,11 +49,11 @@ export declare class ApiClient {
      * 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>;
+    /**
+     * 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`/`trackMatch`/`emit` reuse this id (and the
@@ -62,27 +61,34 @@ export declare class ApiClient {
      * `startAttempt()`, auto-starting one on first use if none was started.
      */
     startAttempt(): string;
-    trackPlay(gameId: string, playTimeSeconds?: number): Promise<boolean>;
-    trackMatch(gameId: string, body: {
+    trackPlay(gameKey: string, playTimeSeconds?: number): Promise<boolean>;
+    trackMatch(gameKey: string, body: {
         matchId: string;
         matchDurationSeconds: number;
         isCompleted?: boolean;
         isWin?: boolean;
     }): Promise<boolean>;
-    emit(gameId: string, actionCode: GameEventKey | string, opts?: {
+    emit(gameKey: string, actionCode: GameEventKey | string, opts?: {
         value?: number;
         refId?: string;
         payload?: Record<string, unknown>;
     }): Promise<EmitGameEventResponse>;
-    /** 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[]>;
+    /** 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[]>;
     /**
      * Spends coin balance to purchase a store offer — signs a checkout intent
      * first, then redeems it, mirroring the gameplay attempt flow above.
+     * Self-serve: only the player's own access token is used, no secret pair
+     * required, safe to call directly from the game client. Also see
+     * `onStorePurchase` to react to the result in real time from any tab.
      */
-    purchaseStoreOffer(gameId: string, offerCode: string, opts?: {
+    purchaseStoreOffer(gameKey: string, offerCode: string, opts?: {
         requestId?: string;
         quantity?: number;
     }): Promise<GameStoreOfferPurchaseResultDto>;

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

@@ -1,5 +1,5 @@
 import { type HttpClientOptions } from './http';
-import type { AuthResultDto, CompleteGameplayAttemptRequest, CompleteGameplayMatchRequest, CreateGameStoreCheckoutIntentRequest, EmitGameEventResponse, GameAssetDto, GameOwnedAssetDto, GameplayAttemptSessionDto, GameStoreCheckoutIntentDto, GameStoreDto, GameStoreOfferPurchaseResultDto, GameTrackingSessionDto, PagingResponse, PurchaseGameStoreOfferRuntimeRequest, RecordGameplayActionRequest, StartGameplayAttemptRequest, TaskListQuery } from './LooplaySDK.types';
+import type { AuthResultDto, CompleteGameplayAttemptRequest, CompleteGameplayMatchRequest, EmitGameEventResponse, GameAssetDto, GameOwnedAssetDto, GameplayAttemptSessionDto, GameStoreCheckoutIntentDto, GameStoreDto, GameStoreOfferPurchaseResultDto, GameTrackingSessionDto, PagingResponse, RecordGameplayActionRequest, SdkCreateGameStoreCheckoutIntentRequest, SdkPurchaseGameStoreOfferRuntimeRequest, StartGameplayAttemptRequest, TaskListQuery } from './LooplaySDK.types';
 export interface ServiceClientOptions extends HttpClientOptions {
 }
 /**
@@ -17,6 +17,19 @@ export interface TrackingAuth {
     trackingSessionId?: string;
     anonTrackingToken?: string;
 }
+/**
+ * Auth for the creator-secret tier (`createGameStoreCheckoutIntent`/
+ * `purchaseGameStoreOffer`) — moves real coin balance. `creatorKey`/
+ * `gameSecret` identify your integration (never embed these in
+ * client/browser code); `bearerToken` identifies the player you're
+ * purchasing on behalf of, same as any other authenticated call.
+ */
+export interface SdkKeyPairAuth {
+    creatorKey: string;
+    gameSecret: string;
+    bearerToken: string;
+    trackingSessionId?: string;
+}
 /**
  * Low-level HTTP client that maps 1:1 to backend routes.
  * Methods requiring user auth accept `bearerToken` explicitly.
@@ -27,15 +40,12 @@ 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>>;
-    recordGameView(auth: TrackingAuth, gameId: string): Promise<boolean>;
+    recordGameView(gameKey: string, auth?: TrackingAuth): 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>;
+    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
@@ -43,19 +53,20 @@ export declare class ServiceClient {
      */
     bootstrapTrackingSession(anonId?: string): Promise<GameTrackingSessionDto>;
     private trackingHeaders;
-    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[]>;
+    /** 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[]>;
+    /** Signs a `checkoutToken` for one purchase — required by `purchaseMyStoreOffer`. */
+    createMyStoreCheckoutIntent(gameKey: string, bearerToken: string, body: SdkCreateGameStoreCheckoutIntentRequest, trackingSessionId?: string): Promise<GameStoreCheckoutIntentDto>;
+    purchaseMyStoreOffer(gameKey: string, bearerToken: string, body: SdkPurchaseGameStoreOfferRuntimeRequest, trackingSessionId?: string): Promise<GameStoreOfferPurchaseResultDto>;
+    /** Signs a `checkoutToken` for one purchase — required by `purchaseGameStoreOffer`. */
+    createGameStoreCheckoutIntent(auth: SdkKeyPairAuth, body: SdkCreateGameStoreCheckoutIntentRequest): Promise<GameStoreCheckoutIntentDto>;
+    purchaseGameStoreOffer(auth: SdkKeyPairAuth, body: SdkPurchaseGameStoreOfferRuntimeRequest): 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>;

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

@@ -0,0 +1,35 @@
+import type { BalanceChangeEvent, StorePurchaseCompletedEvent } from './LooplaySDK.types';
+export interface WsClientOptions {
+    baseUrl: string;
+    /** Resolves the current player's access token — re-checked on every (re)connect. */
+    getAccessToken: () => Promise<string | undefined>;
+}
+type Listener<T> = (payload: T) => void;
+/**
+ * Lazy-connecting Socket.IO client mirroring gbs-service's AppGateway.
+ * Both events it exposes (`balance_change`, `store_purchase_completed`) are
+ * pushed only to the authenticated player's own room — there is nothing to
+ * receive without an access token, so `subscribe*` is a no-op until one is
+ * available.
+ *
+ * The connection is opened on the first subscription and closed once the
+ * last listener unsubscribes — a game that never calls `onBalanceChange`/
+ * `onStorePurchase` never opens a socket at all.
+ */
+export declare class WsClient {
+    private readonly options;
+    private socket?;
+    private connectPromise?;
+    private readonly balanceListeners;
+    private readonly purchaseListeners;
+    constructor(options: WsClientOptions);
+    /** Fires on every balance change — purchases, quest rewards, referral payouts, etc. */
+    onBalanceChange(listener: Listener<BalanceChangeEvent>): () => void;
+    /** Fires once a store purchase finishes — see `StorePurchaseCompletedEvent`. */
+    onStorePurchase(listener: Listener<StorePurchaseCompletedEvent>): () => void;
+    /** Closes the socket immediately, regardless of active listeners. */
+    disconnect(): void;
+    private ensureConnected;
+    private disconnectIfIdle;
+}
+export {};

package/dist/types/errors.d.ts

@@ -13,6 +13,3 @@ 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/realtime.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Optional real-time subpath — `import { WsClient } from '@looplay/sdk/realtime'`.
+ * Kept out of the main `@looplay/sdk` entry point (and its browser IIFE
+ * bundle) because it pulls in `socket.io-client`, which most integrations
+ * — tracking-only or store-browsing-only — don't need.
+ */
+export { WsClient } from './apps/ws-client';
+export type { WsClientOptions } from './apps/ws-client';
+export type { BalanceChangeEvent, StorePurchaseCompletedEvent } from './apps/LooplaySDK.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.6.0",
+  "version": "0.8.1",
   "description": "LooplaySDK (auth + points) for game integrations",
   "license": "UNLICENSED",
   "type": "module",
@@ -17,6 +17,14 @@
     },
     "./browser": {
       "default": "./dist/looplay-sdk.min.js"
+    },
+    "./realtime": {
+      "types": "./dist/types/realtime.d.ts",
+      "import": "./dist/looplay-sdk-realtime.esm.js",
+      "require": "./dist/looplay-sdk-realtime.cjs.js"
+    },
+    "./realtime/browser": {
+      "default": "./dist/looplay-sdk-realtime.min.js"
     }
   },
   "files": [
@@ -30,6 +38,14 @@
   "dependencies": {
     "@looplay/types": "^0.1.0"
   },
+  "peerDependencies": {
+    "socket.io-client": "^4.8.3"
+  },
+  "peerDependenciesMeta": {
+    "socket.io-client": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "npm run build:js && npm run build:types",
     "build:js": "tsup",