@looplay/sdk 0.5.1 → 0.7.0

package/README.md

@@ -1,7 +1,45 @@
-# Looplay
+# @looplay/sdk
+
+Client SDK for games integrating with Looplay: player tracking (views, play
+attempts, matches, custom actions), the game's coin store (read-only), and
+authentication.
 
 API Reference: https://docs.looplay.gg/build-on-loopplay/looplay-sdk
 
+- [Install](#install)
+- [Core concept: one SDK integration = one game](#core-concept-one-sdk-integration--one-game)
+- [Tracking a game — hosted on Looplay or published anywhere else](#tracking-a-game--hosted-on-looplay-or-published-anywhere-else)
+- [`LooplaySDK` — direct integration (your own backend/auth)](#looplaysdk--direct-integration-your-own-backendauth)
+- [Store — read-only browsing](#store--read-only-browsing)
+- [Purchases require your own backend](#purchases-require-your-own-backend)
+- [Rewarded ads via parent window](#rewarded-ads-via-parent-window)
+- [Drop-in `<script>` tag (no build step required)](#drop-in-script-tag-no-build-step-required)
+- [Auth storage tradeoff](#auth-storage-tradeoff)
+- [Errors](#errors)
+
+## Install
+
+```bash
+npm install @looplay/sdk
+```
+
+## Core concept: one SDK integration = one game
+
+Every tracking and store call is scoped to **one game**, identified by its
+public `appId` (also called `gameKey` — the same value, sent as the
+`x-game-key` header under the hood). There is no multi-game catalog
+browsing in this SDK; register your game with a Looplay creator account
+first and use that `appId` everywhere below.
+
+```ts
+import { LooplayIframeAuth } from '@looplay/sdk';
+
+export const looplayAuth = new LooplayIframeAuth({
+  appId: 'YOUR_APP_ID', // from your creator dashboard — required
+  apiUrl: 'https://api.looplay.gg',
+});
+```
+
 ## Tracking a game — hosted on Looplay or published anywhere else
 
 `LooplayIframeAuth` is the single class for tracking, in two modes that the
@@ -38,13 +76,88 @@ looplayAuth.initLifecycleTracking(); // auto-emits GAME_STARTED once per session
 // Anywhere in the game — identical code whether hosted on Looplay or not:
 looplayAuth.canTrack();
 looplayAuth.subscribe((state) => { /* re-render when auth arrives/clears */ });
+await looplayAuth.trackView();
+looplayAuth.startAttempt(); // call once when the user presses Play
 await looplayAuth.trackPlay(playTimeSeconds);
 await looplayAuth.trackMatch(matchId, { durationSeconds, isWin: true });
 await looplayAuth.emitGameEvent('CUSTOM_ACTION', { value: 1 });
 await looplayAuth.requestAds();
 ```
 
-### Rewarded ads via parent window
+Every play attempt is backed by a short-lived, server-signed token — the SDK
+fetches and caches it automatically the first time `trackPlay`/`trackMatch`/
+`emitGameEvent` needs it after `startAttempt()`. You never see or manage
+this token directly.
+
+### Tracking call reference
+
+| Call | When |
+| --- | --- |
+| `trackView()` | Once when the game view opens, before any play/match tracking |
+| `startAttempt()` | Once when the user presses Play. Synchronous — returns an id immediately |
+| `trackPlay(playTimeSeconds?)` | Periodically / on pause, to report accumulated play time for the current attempt |
+| `trackMatch(matchId, { durationSeconds, isCompleted?, isWin? })` | Once per round/match end. `matchId` is the idempotency anchor — safe to call twice |
+| `emitGameEvent(actionCode, { value?, refId?, payload? })` | For quest/task progress and custom analytics — e.g. `'LEVEL_UP'`, `'ITEM_COLLECTED'` |
+
+## `LooplaySDK` — direct integration (your own backend/auth)
+
+If you're not embedding via iframe (e.g. a native/Telegram Mini App
+integration with your own auth flow), use `LooplaySDK` directly:
+
+```ts
+import { LooplaySDK } from '@looplay/sdk';
+
+const sdk = new LooplaySDK({
+  baseUrl: 'https://api.looplay.gg',
+  auth: { provider: telegramAuthProvider }, // any AuthProvider — see auth/types.ts
+});
+
+await sdk.init({ gameId: 'YOUR_APP_ID', verifyMode: 'strict' });
+// `gameId` here is the game's public appId (same as `x-game-key`/`appId` above).
+
+await sdk.trackView();
+sdk.startAttempt();
+await sdk.trackPlay(playTimeSeconds);
+await sdk.trackMatch(matchId, { durationSeconds, isWin: true });
+await sdk.emit('CUSTOM_ACTION', { value: 1 });
+
+const profile = await sdk.getMyProfile();
+```
+
+`verifyMode: 'strict'` resolves `gameId` against the backend on `init()` and
+throws if the game doesn't exist or isn't live — a lightweight, read-only,
+unauthenticated check. Use `'none'` (default) to skip it.
+
+## Store — read-only browsing
+
+The SDK exposes read-only access to the game's coin store — storefront,
+public asset catalog, and (when authenticated) the caller's own owned
+assets and purchase history:
+
+```ts
+const store = await sdk.api!.getStore(gameId);          // sections + offers, no auth required
+const assets = await sdk.api!.listGameAssets(gameId);     // public asset catalog, no auth required
+const owned = await sdk.api!.listMyGameAssets(gameId);    // requires a logged-in user
+const purchases = await sdk.api!.listMyStorePurchases(gameId); // requires a logged-in user
+```
+
+## Purchases require your own backend
+
+There is **no purchase call in this SDK** — spending a player's coin
+balance always requires the creator+game *secret* pair
+(`x-creator-key`/`x-game-secret`), which must never be embedded in
+client/browser code. To let players buy a store offer:
+
+1. Implement a checkout endpoint on your own backend.
+2. From that backend, call gbs-service directly with your secret pair:
+   `POST /sdk/games/store/checkout-intent` then `POST /sdk/games/store/purchase`.
+3. Have the game client call your backend endpoint, not gbs-service
+   directly, for the purchase step.
+
+Browsing (storefront, catalog, owned assets, purchase history) is safe
+client-side and covered by the read-only calls above.
+
+## Rewarded ads via parent window
 
 When the game runs inside an iframe, you can ask the parent page to open a
 rewarded ad by sending `LOOPLAY_REQUEST_ADS`. This is the right pattern for a
@@ -88,7 +201,7 @@ window.addEventListener('message', async (event) => {
 });
 ```
 
-### Drop-in `<script>` tag (no build step required)
+## Drop-in `<script>` tag (no build step required)
 
 Games not built from a Looplay template — plain HTML5, Construct, GameMaker
 exports, a Unity WebGL wrapper page, etc. — can use the browser (IIFE) bundle
@@ -104,7 +217,8 @@ directly, no bundler needed:
   looplayAuth.init();
   looplayAuth.initLifecycleTracking();
 
-  // call looplayAuth.trackPlay(...) / trackMatch(...) / emitGameEvent(...) from your game code
+  // call looplayAuth.trackView() / startAttempt() / trackPlay(...) /
+  // trackMatch(...) / emitGameEvent(...) from your game code
 </script>
 ```
 
@@ -131,3 +245,26 @@ but readable by any script on the page (XSS exposure). Prefer it only for
 games where that tradeoff is acceptable; for higher-security needs, keep the
 default in-memory storage or implement an `AuthStorage` backed by a more
 restrictive mechanism.
+
+## Errors
+
+All SDK-thrown errors extend `LooplaySDKError`:
+
+| Error | Thrown when |
+| --- | --- |
+| `NotInitializedError` | Calling `LooplaySDK` methods before `init()` |
+| `MissingBaseUrlError` | Constructing without `baseUrl` |
+| `MissingAuthError` | An operation needs `auth` and none was configured |
+| `NotAuthenticatedError` | Calling an authenticated endpoint with no access token and (for tracking) no anonymous id |
+
+```ts
+import { NotAuthenticatedError } from '@looplay/sdk';
+
+try {
+  await sdk.getMyProfile();
+} catch (err) {
+  if (err instanceof NotAuthenticatedError) {
+    // prompt login
+  }
+}
+```

package/dist/looplay-sdk.cjs.js

@@ -246,47 +246,49 @@ var ServiceClient = class {
     return this.http.request("POST", "/account/logout", { body });
   }
   // ─────────────────────────────────────────────────────────────────────────────
-  // Games
+  // Games — one SDK integration = one game, resolved on every call from the
+  // public `x-game-key` header (the game's `appId`). There is no multi-game
+  // catalog browsing here (list/search/detail across games) and no `:id`/
+  // `storeId` path segments — that's the app-facing surface, out of scope
+  // for this per-game SDK. Never use the creator-secret tier
+  // (`x-creator-key`/`x-game-secret`) from client/browser code — that would
+  // leak the secret to every player.
   // ─────────────────────────────────────────────────────────────────────────────
-  async listGames(query) {
-    return this.http.request("GET", "/sdk/games", { query });
-  }
-  async getGameDetail(gameId, bearerToken) {
-    return this.http.request("GET", `/sdk/games/${encodeURIComponent(gameId)}`, {
-      bearerToken
+  async recordGameView(gameKey, auth = {}) {
+    await this.http.request("POST", "/sdk/games/views/record", {
+      ...auth,
+      headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) }
     });
+    return true;
   }
-  async listRecentPlayed(bearerToken, query) {
-    return this.http.request("GET", "/sdk/games/recent-play", { bearerToken, query });
-  }
-  async trackView(auth, gameId) {
-    await this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/view`, {
+  /** Signs a fresh `attemptToken` — required by `completeGameplayAttempt`/`completeGameplayMatch`/`recordGameplayAction`. */
+  async startGameplayAttempt(gameKey, auth = {}, body = {}) {
+    return this.http.request("POST", "/sdk/games/attempts/start", {
       ...auth,
-      headers: this.trackingHeaders(auth)
+      headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) },
+      body
     });
-    return true;
   }
-  async trackPlay(auth, gameId, attemptId, playTimeSeconds) {
-    const body = { playTimeSeconds, attemptId };
-    await this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/play`, {
+  async completeGameplayAttempt(gameKey, auth, body) {
+    await this.http.request("POST", "/sdk/games/attempts/complete", {
       ...auth,
-      headers: this.trackingHeaders(auth),
+      headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) },
       body
     });
     return true;
   }
-  async trackMatchEnd(auth, gameId, body) {
-    await this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/end`, {
+  async completeGameplayMatch(gameKey, auth, body) {
+    await this.http.request("POST", "/sdk/games/matches/complete", {
       ...auth,
-      headers: this.trackingHeaders(auth),
+      headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) },
       body
     });
     return true;
   }
-  async emitGameEvent(auth, gameId, body) {
-    return this.http.request("POST", `/sdk/games/${encodeURIComponent(gameId)}/emit`, {
+  async recordGameplayAction(gameKey, auth, body) {
+    return this.http.request("POST", "/sdk/games/actions/record", {
       ...auth,
-      headers: this.trackingHeaders(auth),
+      headers: { "x-game-key": gameKey, ...this.trackingHeaders(auth) },
       body
     });
   }
@@ -295,7 +297,7 @@ var ServiceClient = class {
    * runtimes should still call it to get a `trackingSessionId` for unified
    * tracing — see `GameTrackingSessionDto`.
    */
-  async issueTrackingSession(anonId) {
+  async bootstrapTrackingSession(anonId) {
     return this.http.request("POST", "/sdk/games/tracking/bootstrap", {
       headers: { "x-looplay-anon-id": anonId }
     });
@@ -306,22 +308,36 @@ var ServiceClient = class {
       "x-looplay-anon-token": auth.anonTrackingToken
     };
   }
-  // ─────────────────────────────────────────────────────────────────────────────
-  // Game assets — spend coin balance on assets defined by the game's
-  // creator. Coin balance itself comes from getBalances()/getMyBalance().
-  // ─────────────────────────────────────────────────────────────────────────────
-  async listGameAssets(gameId, bearerToken) {
-    return this.http.request("GET", `/sdk/games/${encodeURIComponent(gameId)}/assets`, {
-      bearerToken
+  /** Public storefront (sections + offers) for the integration's game. Read-only. */
+  async getStore(gameKey) {
+    return this.http.request("GET", "/sdk/games/store/current", {
+      headers: { "x-game-key": gameKey }
     });
   }
-  async purchaseGameAsset(bearerToken, gameId, assetCode, body = {}) {
-    return this.http.request(
-      "POST",
-      `/sdk/games/${encodeURIComponent(gameId)}/assets/${encodeURIComponent(assetCode)}/purchase`,
-      { bearerToken, body }
-    );
+  /** Public catalog of purchasable/ownable assets for the game. Read-only. */
+  async listGameAssets(gameKey) {
+    return this.http.request("GET", "/sdk/games/store/assets", {
+      headers: { "x-game-key": gameKey }
+    });
   }
+  /** Assets the authenticated player already owns for this game. */
+  async listMyGameAssets(bearerToken, gameKey) {
+    return this.http.request("GET", "/sdk/games/store/assets/me", {
+      bearerToken,
+      headers: { "x-game-key": gameKey }
+    });
+  }
+  /** The authenticated player's past store purchases for this game. */
+  async listMyStorePurchases(bearerToken, gameKey) {
+    return this.http.request("GET", "/sdk/games/store/purchases/me", {
+      bearerToken,
+      headers: { "x-game-key": gameKey }
+    });
+  }
+  // No purchase route is reachable from client/browser code — spending coin
+  // balance always requires the creator+game secret pair
+  // (`x-creator-key`/`x-game-secret`), called from the game's own backend.
+  // This SDK intentionally never wires that tier up.
   // ─────────────────────────────────────────────────────────────────────────────
   // Balance
   // ─────────────────────────────────────────────────────────────────────────────
@@ -352,11 +368,11 @@ var ServiceClient = class {
   // ─────────────────────────────────────────────────────────────────────────────
   // Tasks
   // ─────────────────────────────────────────────────────────────────────────────
-  async listTasks(bearerToken) {
-    return this.http.request("GET", "/sdk/task", { bearerToken });
+  async listTasks(bearerToken, query) {
+    return this.http.request("GET", "/sdk/task", { bearerToken, query: { ...query } });
   }
-  async listFinishedTasks(bearerToken) {
-    return this.http.request("GET", "/sdk/task/finished", { bearerToken });
+  async listFinishedTasks(bearerToken, query) {
+    return this.http.request("GET", "/sdk/task/finished", { bearerToken, query: { ...query } });
   }
   async startTask(bearerToken, body) {
     return this.http.request("POST", "/sdk/task/start", { bearerToken, body });
@@ -384,6 +400,8 @@ var ApiClient = class {
   trackingSession;
   trackingSessionPromise;
   currentAttemptId;
+  gameplayAttempt;
+  gameplayAttemptPromise;
   constructor(options) {
     if (!options.baseUrl) throw new MissingBaseUrlError();
     this.raw = new ServiceClient({
@@ -394,15 +412,10 @@ var ApiClient = class {
     this.getAccessToken = options.getAccessToken;
     this.getAnonymousId = options.getAnonymousId;
   }
-  /** Expose the underlying route-level client (requires manual bearerToken passing). */
+  /** Expose the underlying route-level client (requires manual bearerToken/gameKey passing). */
   unsafeRaw() {
     return this.raw;
   }
-  // Public endpoints
-  async listGames(query) {
-    return this.raw.listGames(query);
-  }
-  // Authenticated endpoints
   async requireToken() {
     const token = await this.getAccessToken?.();
     if (!token) throw new NotAuthenticatedError();
@@ -439,7 +452,7 @@ var ApiClient = class {
       return this.trackingSession;
     }
     if (!this.trackingSessionPromise) {
-      this.trackingSessionPromise = this.raw.issueTrackingSession(anonId).then((dto) => {
+      this.trackingSessionPromise = this.raw.bootstrapTrackingSession(anonId).then((dto) => {
         this.trackingSession = {
           trackingSessionId: dto.trackingSessionId,
           anonTrackingToken: dto.trackingToken,
@@ -452,57 +465,99 @@ var ApiClient = class {
     }
     return this.trackingSessionPromise;
   }
-  async getGameDetail(gameId) {
-    const token = await this.getAccessToken?.();
-    return this.raw.getGameDetail(gameId, token);
-  }
-  async listRecentPlayed(query) {
-    const token = await this.requireToken();
-    return this.raw.listRecentPlayed(token, query);
+  /**
+   * 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.
+   */
+  async ensureGameplayAttempt(gameKey, auth, attemptId) {
+    const now = Date.now();
+    if (this.gameplayAttempt && this.gameplayAttempt.gameKey === gameKey && this.gameplayAttempt.attemptId === attemptId && this.gameplayAttempt.expiresAtMs > now + 1e4) {
+      return this.gameplayAttempt;
+    }
+    if (!this.gameplayAttemptPromise) {
+      this.gameplayAttemptPromise = this.raw.startGameplayAttempt(gameKey, auth, { attemptId }).then((dto) => {
+        this.gameplayAttempt = {
+          gameKey,
+          attemptId: dto.attemptId,
+          attemptToken: dto.attemptToken,
+          expiresAtMs: new Date(dto.expiresAt).getTime()
+        };
+        return this.gameplayAttempt;
+      }).finally(() => {
+        this.gameplayAttemptPromise = void 0;
+      });
+    }
+    return this.gameplayAttemptPromise;
   }
-  /** Call once when the game view opens, before any play/match tracking. */
-  async trackView(gameId) {
+  /**
+   * Call once when the game view opens, before any play/match tracking.
+   * `gameKey` is the game's public `appId`.
+   */
+  async trackView(gameKey) {
     const auth = await this.resolveTrackingAuth();
-    return this.raw.trackView(auth, gameId);
+    return this.raw.recordGameView(gameKey, auth);
   }
   /**
    * 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() {
     this.currentAttemptId = generateId();
+    this.gameplayAttempt = void 0;
     return this.currentAttemptId;
   }
-  async trackPlay(gameId, playTimeSeconds) {
+  async trackPlay(gameKey, playTimeSeconds) {
     const auth = await this.resolveTrackingAuth();
     const attemptId = this.currentAttemptId ?? this.startAttempt();
-    return this.raw.trackPlay(auth, gameId, attemptId, playTimeSeconds);
+    const { attemptToken } = await this.ensureGameplayAttempt(gameKey, auth, attemptId);
+    return this.raw.completeGameplayAttempt(gameKey, auth, { playTimeSeconds, attemptId, attemptToken });
   }
-  async trackMatch(gameId, body) {
+  async trackMatch(gameKey, body) {
     const auth = await this.resolveTrackingAuth();
-    return this.raw.trackMatchEnd(auth, gameId, body);
+    const attemptId = this.currentAttemptId ?? this.startAttempt();
+    const { attemptToken } = await this.ensureGameplayAttempt(gameKey, auth, attemptId);
+    return this.raw.completeGameplayMatch(gameKey, auth, { ...body, attemptId, attemptToken });
   }
-  async emit(gameId, actionCode, opts) {
+  async emit(gameKey, actionCode, opts) {
     const auth = await this.resolveTrackingAuth();
+    const attemptId = this.currentAttemptId ?? this.startAttempt();
+    const { attemptToken } = await this.ensureGameplayAttempt(gameKey, auth, attemptId);
     const body = {
+      attemptId,
+      attemptToken,
       actionCode,
       value: opts?.value,
       refId: opts?.refId,
       payload: opts?.payload
     };
-    return this.raw.emitGameEvent(auth, gameId, body);
+    return this.raw.recordGameplayAction(gameKey, auth, body);
   }
-  /** Lists assets purchasable in `gameId`, defined by that game's creator. */
-  async listGameAssets(gameId) {
-    const token = await this.getAccessToken?.();
-    return this.raw.listGameAssets(gameId, token);
+  /** Fetches the storefront (sections + offers) for the integration's game. Read-only, no auth required. */
+  async getStore(gameKey) {
+    return this.raw.getStore(gameKey);
+  }
+  /** Public catalog of purchasable/ownable assets for the game. Read-only, no auth required. */
+  async listGameAssets(gameKey) {
+    return this.raw.listGameAssets(gameKey);
+  }
+  /** Assets the authenticated player already owns for this game. */
+  async listMyGameAssets(gameKey) {
+    const token = await this.requireToken();
+    return this.raw.listMyGameAssets(token, gameKey);
   }
-  /** Spends coin balance to purchase an asset — see PurchaseGameAssetRequest for dedupe/quantity. */
-  async purchaseGameAsset(gameId, assetCode, opts) {
+  /** Purchase history for the authenticated player in the game's store. */
+  async listMyStorePurchases(gameKey) {
     const token = await this.requireToken();
-    return this.raw.purchaseGameAsset(token, gameId, assetCode, opts);
+    return this.raw.listMyStorePurchases(token, gameKey);
   }
+  // There is no purchaseStoreOffer() here by design — spending coin balance
+  // requires the creator+game secret pair, which must be called from the
+  // game's own backend, never from this client-side SDK. Implement a
+  // checkout endpoint on your backend that calls gbs-service directly.
   async getMyProfile() {
     const token = await this.requireToken();
     return this.raw.getMyProfile(token);
@@ -527,13 +582,13 @@ var ApiClient = class {
     const token = await this.requireToken();
     return this.raw.setReferral(token, body);
   }
-  async listTasks() {
+  async listTasks(query) {
     const token = await this.requireToken();
-    return this.raw.listTasks(token);
+    return this.raw.listTasks(token, query);
   }
-  async listFinishedTasks() {
+  async listFinishedTasks(query) {
     const token = await this.requireToken();
-    return this.raw.listFinishedTasks(token);
+    return this.raw.listFinishedTasks(token, query);
   }
   async startTask(body) {
     const token = await this.requireToken();
@@ -633,9 +688,8 @@ var LooplaySDK = class {
   }
   async verifyGameId(params) {
     if ((params.verifyMode ?? "none") === "none") return;
-    if (!this.auth) throw new MissingAuthError();
     if (!this.api) throw new MissingBaseUrlError();
-    await this.api.getGameDetail(params.gameId);
+    await this.api.listGameAssets(params.gameId);
   }
 };