@looplay/sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,3 +1,88 @@
 # Looplay
 
-API Reference: https://docs.looplay.gg/build-on-loopplay/looplay-sdk
+API Reference: https://docs.looplay.gg/build-on-loopplay/looplay-sdk
+
+## Tracking a game — hosted on Looplay or published anywhere else
+
+`LooplayIframeAuth` is the single class for tracking, in two modes that the
+**same game code** doesn't need to branch on:
+
+1. **Embedded in the Looplay web app's iframe.** The host page pushes
+   `{ type: 'LOOPLAY_AUTH', jwt, gameId, apiUrl }` via postMessage once the
+   game requests it. Tracking calls use the real user's bearer token — full
+   tracking, eligible for quest/reward.
+2. **Standalone — published anywhere else** (your own domain, itch.io, a
+   non-Vite build, ...), or the iframe parent never responds. The SDK falls
+   back to a locally-generated, `localStorage`-persisted anonymous device
+   id. Tracking still works and counts toward play/analytics stats, but
+   **never** feeds the quest/reward engine — there's no real account to
+   award.
+
+Either way you need an **`appId`**: register your game with a Looplay
+creator account first — anonymous tracking is rejected for games without one
+(authenticated tracking inside the iframe still works without it, for
+backward compatibility, but you should set one regardless).
+
+```ts
+import { LooplayIframeAuth } from '@looplay/sdk';
+
+export const looplayAuth = new LooplayIframeAuth({
+  appId: 'YOUR_APP_ID', // from your creator dashboard
+  apiUrl: 'https://api.looplay.gg', // required for standalone builds; optional inside the iframe
+  parentOrigin: import.meta.env.VITE_PARENT_ORIGIN, // restrict the accepted postMessage origin
+});
+
+looplayAuth.init();
+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.trackPlay(playTimeSeconds);
+await looplayAuth.trackMatch(matchId, { durationSeconds, isWin: true });
+await looplayAuth.emitGameEvent('CUSTOM_ACTION', { value: 1 });
+```
+
+### 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
+directly, no bundler needed:
+
+```html
+<script src="https://unpkg.com/@looplay/sdk/browser"></script>
+<script>
+  const looplayAuth = new LooplaySDK.LooplayIframeAuth({
+    appId: 'YOUR_APP_ID',
+    apiUrl: 'https://api.looplay.gg',
+  });
+  looplayAuth.init();
+  looplayAuth.initLifecycleTracking();
+
+  // call looplayAuth.trackPlay(...) / trackMatch(...) / emitGameEvent(...) from your game code
+</script>
+```
+
+**Security note**: the origin check relies on `parentOrigin` (explicit option)
+or `document.referrer`. Referrer can be stripped by `Referrer-Policy`, browser
+privacy settings, or extensions — when that happens the check is skipped and
+`LooplayIframeAuth` logs a `console.warn`. Always pass `parentOrigin` explicitly
+in production embeds instead of relying on the referrer fallback.
+
+**Lifecycle**: call `dispose()` when tearing down (route change, HMR, test
+cleanup) to remove the `message` listener and clear subscribers:
+
+```ts
+looplayAuth.dispose();
+```
+
+## Auth storage tradeoff
+
+`LooplayAuth` (used by `TelegramAuthProvider` and other explicit-login
+providers) defaults to in-memory session storage — nothing persists across a
+reload unless you opt in. `BrowserLocalStorageAuthStorage` persists the
+session (including the refresh token) in `localStorage`, which is convenient
+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.

package/dist/looplay-sdk.cjs.js

@@ -176,6 +176,8 @@ var HttpClient = class {
     );
     if (options?.bearerToken) {
       headers.Authorization = `Bearer ${options.bearerToken}`;
+    } else if (options?.anonId) {
+      headers["x-looplay-anon-id"] = options.anonId;
     }
     let body;
     if (options?.body !== void 0) {
@@ -257,24 +259,24 @@ var ServiceClient = class {
   async listRecentPlayed(bearerToken, query) {
     return this.http.request("GET", "/games/recent-play", { bearerToken, query });
   }
-  async trackPlay(bearerToken, gameId, playTimeSeconds) {
+  async trackPlay(auth, gameId, playTimeSeconds) {
     const body = { playTimeSeconds };
     await this.http.request("POST", `/games/${encodeURIComponent(gameId)}/play`, {
-      bearerToken,
+      ...auth,
       body
     });
     return true;
   }
-  async trackMatchEnd(bearerToken, gameId, body) {
+  async trackMatchEnd(auth, gameId, body) {
     await this.http.request("POST", `/games/${encodeURIComponent(gameId)}/end`, {
-      bearerToken,
+      ...auth,
       body
     });
     return true;
   }
-  async emitGameEvent(bearerToken, gameId, body) {
+  async emitGameEvent(auth, gameId, body) {
     return this.http.request("POST", `/games/${encodeURIComponent(gameId)}/emit`, {
-      bearerToken,
+      ...auth,
       body
     });
   }
@@ -347,6 +349,7 @@ var ServiceClient = class {
 var ApiClient = class {
   raw;
   getAccessToken;
+  getAnonymousId;
   constructor(options) {
     if (!options.baseUrl) throw new MissingBaseUrlError();
     this.raw = new ServiceClient({
@@ -355,6 +358,7 @@ var ApiClient = class {
       defaultHeaders: options.defaultHeaders
     });
     this.getAccessToken = options.getAccessToken;
+    this.getAnonymousId = options.getAnonymousId;
   }
   /** Expose the underlying route-level client (requires manual bearerToken passing). */
   unsafeRaw() {
@@ -370,8 +374,20 @@ var ApiClient = class {
     if (!token) throw new NotAuthenticatedError();
     return token;
   }
+  /**
+   * Resolves auth for the tracking endpoints: a real bearer token if logged
+   * in, otherwise an anonymous device id. Throws only when neither is
+   * available — anonymous tracking still requires *some* identity.
+   */
+  async resolveTrackingAuth() {
+    const bearerToken = await this.getAccessToken?.();
+    if (bearerToken) return { bearerToken };
+    const anonId = this.getAnonymousId?.();
+    if (anonId) return { anonId };
+    throw new NotAuthenticatedError();
+  }
   async getGameDetail(gameId) {
-    const token = await this.requireToken();
+    const token = await this.getAccessToken?.();
     return this.raw.getGameDetail(gameId, token);
   }
   async listRecentPlayed(query) {
@@ -379,22 +395,22 @@ var ApiClient = class {
     return this.raw.listRecentPlayed(token, query);
   }
   async trackPlay(gameId, playTimeSeconds) {
-    const token = await this.requireToken();
-    return this.raw.trackPlay(token, gameId, playTimeSeconds);
+    const auth = await this.resolveTrackingAuth();
+    return this.raw.trackPlay(auth, gameId, playTimeSeconds);
   }
   async trackMatch(gameId, body) {
-    const token = await this.requireToken();
-    return this.raw.trackMatchEnd(token, gameId, body);
+    const auth = await this.resolveTrackingAuth();
+    return this.raw.trackMatchEnd(auth, gameId, body);
   }
   async emit(gameId, actionCode, opts) {
-    const token = await this.requireToken();
+    const auth = await this.resolveTrackingAuth();
     const body = {
       actionCode,
       value: opts?.value,
       refId: opts?.refId,
       payload: opts?.payload
     };
-    return this.raw.emitGameEvent(token, gameId, body);
+    return this.raw.emitGameEvent(auth, gameId, body);
   }
   async getMyProfile() {
     const token = await this.requireToken();
@@ -535,6 +551,26 @@ var LooplaySDK = class {
   }
 };
 
+// src/auth/jwt.ts
+function decodeJwtClaims(token) {
+  if (!token) return void 0;
+  const parts = token.split(".");
+  if (parts.length < 2) return void 0;
+  try {
+    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = payload + "===".slice((payload.length + 3) % 4);
+    if (typeof globalThis.atob !== "function") return void 0;
+    const json = globalThis.atob(padded);
+    return JSON.parse(json);
+  } catch {
+    return void 0;
+  }
+}
+function decodeJwtExpMs(token) {
+  const exp = decodeJwtClaims(token)?.exp;
+  return typeof exp === "number" ? exp * 1e3 : void 0;
+}
+
 // src/auth/providers/telegram-auth-provider.ts
 var MissingTelegramInitDataError = class extends LooplaySDKError {
   constructor() {
@@ -548,22 +584,6 @@ var MissingRefreshTokenError = class extends LooplaySDKError {
     this.name = "MissingRefreshTokenError";
   }
 };
-function decodeJwtExpMs(token) {
-  if (!token) return void 0;
-  const parts = token.split(".");
-  if (parts.length < 2) return void 0;
-  try {
-    const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
-    const padded = payload + "===".slice((payload.length + 3) % 4);
-    if (typeof globalThis.atob !== "function") return void 0;
-    const json = globalThis.atob(padded);
-    const parsed = JSON.parse(json);
-    if (typeof parsed.exp !== "number") return void 0;
-    return parsed.exp * 1e3;
-  } catch {
-    return void 0;
-  }
-}
 var TelegramAuthProvider = class {
   id = "telegram";
   client;
@@ -629,11 +649,280 @@ var TelegramAuthProvider = class {
   }
 };
 
+// src/iframe/iframe-auth.ts
+var DEFAULT_ANON_ID_STORAGE_KEY = "looplay:anon-id";
+var DEFAULT_ANONYMOUS_FALLBACK_TIMEOUT_MS = 4e3;
+var INITIAL_STATE = {
+  jwt: null,
+  gameId: null,
+  apiUrl: null,
+  anonymousId: null,
+  origin: null,
+  receivedAt: null
+};
+var isRecord = (value) => typeof value === "object" && value !== null;
+var toOptionalString = (value) => {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized ? normalized : null;
+};
+function generateAnonymousId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+function readStoredAnonymousId(key) {
+  if (typeof window === "undefined" || !window.localStorage) return null;
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function writeStoredAnonymousId(key, value) {
+  if (typeof window === "undefined" || !window.localStorage) return;
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+  }
+}
+var LooplayIframeAuth = class {
+  state = INITIAL_STATE;
+  initialized = false;
+  lifecycleTrackingInitialized = false;
+  lastGameStartedKey = null;
+  client = null;
+  listeners = /* @__PURE__ */ new Set();
+  options;
+  messageListener = null;
+  anonymousFallbackTimer = null;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  getState() {
+    return this.state;
+  }
+  getJwt() {
+    return this.state.jwt;
+  }
+  getApiUrl() {
+    return this.options.apiUrl ?? this.state.apiUrl;
+  }
+  /** Resolves to the configured `appId`, falling back to whatever the parent pushed as `gameId`. */
+  getGameId() {
+    return this.options.appId ?? this.state.gameId;
+  }
+  getAnonymousId() {
+    return this.state.anonymousId;
+  }
+  /** True once authenticated (bearer) or anonymous tracking is ready, given a configured `apiUrl`/`appId`. */
+  canTrack() {
+    if (!this.getApiUrl() || !this.getGameId()) return false;
+    return Boolean(this.state.jwt || this.state.anonymousId);
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    listener(this.state);
+    return () => this.listeners.delete(listener);
+  }
+  requestAuth() {
+    if (typeof window === "undefined" || window.parent === window) {
+      this.debug("standalone mode detected; auth request skipped");
+      return;
+    }
+    this.debug("requesting auth from parent", { targetOrigin: this.resolveParentOrigin() ?? "*" });
+    window.parent.postMessage({ type: "LOOPLAY_AUTH_REQUEST" }, this.resolveParentOrigin() ?? "*");
+  }
+  /** Idempotent; attaches the postMessage listener (if embedded) and arms the anonymous fallback. */
+  init() {
+    if (this.initialized || typeof window === "undefined") return;
+    this.initialized = true;
+    const isEmbedded = window.parent !== window;
+    this.debug("auth listener initialized", {
+      isIframe: isEmbedded,
+      parentOrigin: this.resolveParentOrigin()
+    });
+    if (!isEmbedded) {
+      this.activateAnonymousMode();
+      return;
+    }
+    const parentOrigin = this.resolveParentOrigin();
+    if (!parentOrigin) {
+      console.warn(
+        "[LooplaySDK] LooplayIframeAuth could not resolve a parent origin to verify postMessage against (document.referrer is empty). Auth messages from window.parent will be accepted regardless of origin. Pass `parentOrigin` explicitly to harden this."
+      );
+    }
+    this.messageListener = (event) => {
+      if (event.source !== window.parent) return;
+      if (parentOrigin && event.origin !== parentOrigin) {
+        this.debug("ignored auth message from unexpected origin", {
+          expectedOrigin: parentOrigin,
+          receivedOrigin: event.origin
+        });
+        return;
+      }
+      if (!isRecord(event.data) || event.data.type !== "LOOPLAY_AUTH") return;
+      this.handleAuthMessage(event.data, event.origin);
+    };
+    window.addEventListener("message", this.messageListener);
+    this.anonymousFallbackTimer = setTimeout(() => {
+      if (this.state.jwt) return;
+      this.activateAnonymousMode();
+    }, this.options.anonymousFallbackTimeoutMs ?? DEFAULT_ANONYMOUS_FALLBACK_TIMEOUT_MS);
+    this.requestAuth();
+  }
+  /** Removes the postMessage listener, cancels timers, and clears subscribers; safe to call multiple times. */
+  dispose() {
+    if (typeof window !== "undefined" && this.messageListener) {
+      window.removeEventListener("message", this.messageListener);
+    }
+    if (this.anonymousFallbackTimer !== null) {
+      clearTimeout(this.anonymousFallbackTimer);
+    }
+    this.messageListener = null;
+    this.anonymousFallbackTimer = null;
+    this.initialized = false;
+    this.lifecycleTrackingInitialized = false;
+    this.listeners.clear();
+  }
+  /** Lazily builds (and rebuilds on auth change) the `ApiClient` bound to the current auth mode. */
+  getClient() {
+    if (this.client) return this.client;
+    const baseUrl = this.getApiUrl();
+    this.debug("creating sdk ApiClient", { baseUrl });
+    this.client = new ApiClient({
+      baseUrl: baseUrl ?? void 0,
+      getAccessToken: async () => this.getJwt() ?? void 0,
+      getAnonymousId: () => this.getAnonymousId() ?? void 0
+    });
+    return this.client;
+  }
+  trackPlay(playTimeSeconds) {
+    const gameId = this.getGameId();
+    if (!this.canTrack() || !gameId) {
+      this.debug("trackPlay skipped; auth is not ready", { hasGameId: Boolean(gameId) });
+      return Promise.resolve(false);
+    }
+    this.debug("trackPlay dispatched", { gameId, playTimeSeconds });
+    return this.getClient().trackPlay(gameId, playTimeSeconds);
+  }
+  trackMatch(matchId, opts) {
+    const gameId = this.getGameId();
+    if (!this.canTrack() || !gameId) {
+      this.debug("trackMatch skipped; auth is not ready", { matchId });
+      return Promise.resolve(false);
+    }
+    this.debug("trackMatch dispatched", { gameId, matchId, ...opts });
+    return this.getClient().trackMatch(gameId, {
+      matchId,
+      matchDurationSeconds: opts.durationSeconds,
+      isCompleted: opts.isCompleted,
+      isWin: opts.isWin
+    });
+  }
+  emitGameEvent(actionCode, opts) {
+    const gameId = this.getGameId();
+    if (!this.canTrack() || !gameId) {
+      this.debug("emitGameEvent skipped; auth is not ready", { actionCode });
+      return Promise.resolve(null);
+    }
+    this.debug("emitGameEvent dispatched", { gameId, actionCode, ...opts });
+    return this.getClient().emit(gameId, actionCode, opts);
+  }
+  /** Idempotent; auto-emits GAME_STARTED exactly once per distinct auth session (bearer or anonymous). */
+  initLifecycleTracking() {
+    if (this.lifecycleTrackingInitialized || typeof window === "undefined") return;
+    this.lifecycleTrackingInitialized = true;
+    this.debug("lifecycle tracking initialized");
+    this.subscribe(() => {
+      const key = this.getTrackingKey();
+      if (!key || this.lastGameStartedKey === key) return;
+      this.lastGameStartedKey = key;
+      this.debug("auto GAME_STARTED dispatch");
+      void this.emitGameEvent("GAME_STARTED");
+    });
+  }
+  getTrackingKey() {
+    const gameId = this.getGameId();
+    const apiUrl = this.getApiUrl();
+    const identity = this.state.jwt ?? this.state.anonymousId;
+    if (!gameId || !apiUrl || !identity) return null;
+    return `${apiUrl}
+${gameId}
+${identity}`;
+  }
+  /** Generates (or restores) a persisted anonymous device id and activates anonymous tracking. */
+  activateAnonymousMode() {
+    if (this.state.anonymousId) return;
+    const key = this.options.anonymousIdStorageKey ?? DEFAULT_ANON_ID_STORAGE_KEY;
+    const anonymousId = readStoredAnonymousId(key) ?? generateAnonymousId();
+    writeStoredAnonymousId(key, anonymousId);
+    this.lastGameStartedKey = null;
+    this.setState({ ...this.state, anonymousId, receivedAt: Date.now() });
+    this.debug("anonymous tracking mode active", { anonymousId });
+  }
+  handleAuthMessage(data, origin) {
+    if (this.anonymousFallbackTimer !== null) {
+      clearTimeout(this.anonymousFallbackTimer);
+      this.anonymousFallbackTimer = null;
+    }
+    const jwt = toOptionalString(data.jwt);
+    const gameId = toOptionalString(data.gameId);
+    const apiUrl = toOptionalString(data.apiUrl);
+    if (!jwt || !gameId || !apiUrl) {
+      this.lastGameStartedKey = null;
+      this.setState({ ...this.state, jwt: null, gameId: null, apiUrl: null, origin, receivedAt: Date.now() });
+      this.debug("auth cleared by parent; falling back to anonymous tracking");
+      this.activateAnonymousMode();
+      return;
+    }
+    this.lastGameStartedKey = null;
+    this.setState({
+      jwt,
+      gameId,
+      apiUrl,
+      anonymousId: null,
+      origin,
+      receivedAt: Date.now()
+    });
+  }
+  setState(next) {
+    this.state = next;
+    this.client = null;
+    this.debug("auth state updated", {
+      gameId: this.getGameId(),
+      apiUrl: this.getApiUrl(),
+      origin: next.origin,
+      hasJwt: Boolean(next.jwt),
+      hasAnonymousId: Boolean(next.anonymousId)
+    });
+    this.listeners.forEach((listener) => listener(next));
+  }
+  resolveParentOrigin() {
+    if (this.options.parentOrigin) return this.options.parentOrigin;
+    if (typeof document === "undefined" || !document.referrer) return null;
+    try {
+      return new URL(document.referrer).origin;
+    } catch {
+      return null;
+    }
+  }
+  debug(message, details) {
+    this.options.onDebug?.(message, details);
+  }
+};
+
 exports.ApiClient = ApiClient;
 exports.BrowserLocalStorageAuthStorage = BrowserLocalStorageAuthStorage;
 exports.HttpClient = HttpClient;
 exports.HttpError = HttpError;
 exports.LooplayAuth = LooplayAuth;
+exports.LooplayIframeAuth = LooplayIframeAuth;
 exports.LooplaySDK = LooplaySDK;
 exports.LooplaySDKError = LooplaySDKError;
 exports.MemoryAuthStorage = MemoryAuthStorage;