@paizogames/sdk 0.0.0-stage → 1.0.0

package/PROTOCOL.md

@@ -0,0 +1,54 @@
+# SDK ⇄ portal protocol (v1)
+
+The game iframe and the portal talk with `window.postMessage`. Every message
+is an object with `paizo: 1`.
+
+- SDK side: `sdk/v1/paizo-sdk.js`
+- Portal side: `src/lib/paizo-host/` and `src/components/Portal/GamePlayer.jsx`
+  in `paizogames-nextjs`
+
+## Envelope
+
+| Direction | Shape | Meaning |
+|---|---|---|
+| game → portal | `{ paizo, type, id, payload }` | Request. Gets exactly one reply. |
+| game → portal | `{ paizo, type, payload }` | Notification. No reply. |
+| portal → game | `{ paizo, id, ok: true, result }` | Reply. |
+| portal → game | `{ paizo, id, ok: false, error }` | Failed reply. |
+| portal → game | `{ paizo, event, id }` | Event tied to the request `id`. |
+
+## Messages
+
+| `type` | Kind | Payload | Result |
+|---|---|---|---|
+| `init` | request | `{ sdkVersion, saveUpdatedAt }` | `{ user, save }` where `user` is `{ username, avatarUrl }` or `null`, and `save` is `{ updatedAt, data }` or `null` |
+| `loaded` | notification | `{}` | |
+| `gameplay` | notification | `{ playing: boolean }` | |
+| `save` | notification | `{ updatedAt, data }` — `data` is the game's whole `localStorage` as `{ key: string }` | |
+| `ad` | request | `{ kind: "commercial" \| "rewarded" }` | `{ shown: boolean }` |
+| `login` | request | `{}` | `{ user }`, or an error while accounts do not exist |
+
+Events: `adStarted` — sent before the `ad` reply, only if an ad actually starts.
+
+## Trust
+
+- The SDK accepts messages only from `window.parent`, and only if the parent's
+  origin is `paizogames.com`, a subdomain of it, or `localhost`. The first
+  message is sent to `*` (it carries nothing private); after the handshake the
+  SDK talks only to the origin that answered.
+- The portal accepts messages only from the game iframe's window and only from
+  the game's own origin.
+
+## Save conflict rule
+
+Both sides keep `updatedAt` (ms). On `init`, the newer copy wins: if the
+portal's is newer the SDK replaces the game's `localStorage` with it, otherwise
+the SDK pushes the local copy. The portal ignores a `save` older than what it has.
+
+## Ad rules (portal)
+
+- `commercial`: shown only if the configured interval has passed since the last
+  ad of any kind. The interval starts when the game opens.
+- `rewarded`: always attempted; resets the interval.
+- With no ad provider configured, `commercial` replies `shown: false` and
+  `rewarded` replies `shown: true`, so games stay fully playable.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# Paizo Games SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SDK every game on [paizogames.com](https://paizogames.com) loads. It connects
+a game, running in a cross-origin iframe, to the portal that embeds it.
+
+```
+sdk/v1/paizo-sdk.js   the SDK (plain JS, no build step)
+games/<slug>/         games; games/glide is the reference integration
+scripts/serve.mjs     local stand-in for the games CDN
+PROTOCOL.md           the postMessage protocol between SDK and portal
+```
+
+## Run locally
+
+```bash
+npm run dev
+```
+
+Serves every game on its own origin, `http://<slug>.localhost:4100/`, and the
+SDK at `/sdk/v1/paizo-sdk.js` on each of them. Start the portal
+(`paizogames-nextjs`, port 3002) to play a game embedded the way players see it.
+
+## Integrating a game
+
+A game is a static folder with an `index.html`. Rules:
+
+1. Load the SDK by URL, before the game's own scripts. Never copy it into the game.
+   ```html
+   <script src="/sdk/v1/paizo-sdk.js"></script>
+   ```
+   Games built with a bundler can use the npm package instead. It is the same
+   file, plus TypeScript types:
+   ```bash
+   npm install @paizogames/sdk
+   ```
+   ```js
+   import PaizoSDK from "@paizogames/sdk";
+   ```
+   The script tag is preferred: the portal can then ship SDK fixes without the
+   game being rebuilt.
+2. Call `PaizoSDK.init()` first and wait for it.
+3. Save progress with plain `localStorage`. The SDK syncs it; there is no save API.
+4. No login, no accounts and no ads of your own inside the game.
+5. The game must work when an ad is not shown and when opened outside the portal.
+
+```js
+await PaizoSDK.init();
+// ...load assets...
+PaizoSDK.gameLoadingFinished();
+
+PaizoSDK.gameplayStart();            // level starts / unpause
+PaizoSDK.gameplayStop();             // level ends / pause / menu
+
+await PaizoSDK.commercialBreak();    // between levels; may show nothing
+startNextLevel();
+
+const rewarded = await PaizoSDK.rewardedBreak();   // player clicked "watch ad"
+if (rewarded) giveReward();
+```
+
+## API
+
+| Call | Returns | Notes |
+|---|---|---|
+| `init()` | `Promise<void>` | Never rejects. Every other call waits for it. |
+| `environment` | `"paizo"` \| `"local"` | `local` = not embedded in the portal. |
+| `gameLoadingFinished()` | `Promise<void>` | Hides the portal's loading screen. |
+| `gameplayStart()` / `gameplayStop()` | `Promise<void>` | Used for play-time stats. |
+| `commercialBreak(onStart?)` | `Promise<void>` | Resolves when the game may continue. The portal decides whether an ad plays. |
+| `rewardedBreak(onStart?)` | `Promise<boolean>` | `true` only if the reward should be granted. |
+| `getUser()` | `Promise<{ username, avatarUrl } \| null>` | `null` for guests (everyone, for now). |
+| `login()` | `Promise<user>` | Rejects until the portal has accounts. |
+
+`onStart` is called only if an ad really starts; mute audio there.
+
+Call `commercialBreak()` at every natural break. Frequency is the portal's job.
+
+### Saves
+
+The SDK watches the game's `localStorage` and mirrors it to the portal (at most
+every 2 seconds, and when the page is hidden). On `init()` it restores the
+portal's copy if that one is newer. Limits and escape hatch:
+
+- 1 MB as JSON. Past that, syncing stops for that player.
+- Keys starting with `paizo_ignore` are never synced (caches, temporary state).
+
+### Local mode
+
+Opened directly, or when no portal answers within 1.5 s, the SDK runs in
+`local` mode: ads are a one-second placeholder, rewards are granted, saves stay
+in `localStorage`. Games never need to branch on the environment.
+
+## Publishing a game
+
+1. Upload `games/<slug>/` to the games host so it is served at
+   `https://<slug>.games.paizogames.com/`. The same host must serve this repo's
+   `sdk/` folder at `/sdk/`.
+2. Add the game to the portal catalog: `src/data/games.js` in `paizogames-nextjs`.
+
+Each game gets its own origin so that games cannot read each other's storage
+or the portal's.

package/index.d.ts

@@ -0,0 +1,36 @@
+export interface PaizoUser {
+  username: string;
+  avatarUrl: string | null;
+}
+
+export interface PaizoSDKApi {
+  /** SDK version, e.g. "1.0.0". */
+  readonly version: string;
+  /** "paizo" inside the portal, "local" anywhere else (stubs, still playable). */
+  readonly environment: "paizo" | "local";
+  /** Connects to the portal and restores the save. Call once, before the game starts. */
+  init(): Promise<void>;
+  /** The game has loaded and can be shown. */
+  gameLoadingFinished(): void;
+  /** The player is actively playing. */
+  gameplayStart(): void;
+  /** Play paused or ended (menu, level complete, game over). */
+  gameplayStop(): void;
+  /** Ad between rounds. The portal decides whether one is shown. Always resolves. */
+  commercialBreak(onStart?: () => void): Promise<void>;
+  /** Opt-in ad. Resolves true only if the player earned the reward. */
+  rewardedBreak(onStart?: () => void): Promise<boolean>;
+  /** The signed-in player, or null for a guest. */
+  getUser(): Promise<PaizoUser | null>;
+  /** Opens the portal's sign-in. Rejects while accounts are unavailable. */
+  login(): Promise<PaizoUser | null>;
+}
+
+export declare const PaizoSDK: PaizoSDKApi;
+export default PaizoSDK;
+
+declare global {
+  interface Window {
+    PaizoSDK: PaizoSDKApi;
+  }
+}

package/index.js

@@ -0,0 +1,6 @@
+// npm entry. The SDK is a browser script that defines window.PaizoSDK; this
+// module runs it and hands the same object back for bundler-based games.
+import "./sdk/v1/paizo-sdk.js";
+
+export const PaizoSDK = window.PaizoSDK;
+export default PaizoSDK;

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@paizogames/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Paizo Games SDK: ads, saves and user identity for games running on paizogames.com.",
+  "keywords": ["paizo", "paizogames", "html5-games", "game-sdk", "web-games"],
+  "homepage": "https://paizogames.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lowtechteam/paizogames-sdk.git"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "unpkg": "./sdk/v1/paizo-sdk.js",
+  "jsdelivr": "./sdk/v1/paizo-sdk.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./script": "./sdk/v1/paizo-sdk.js",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": true,
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "sdk/v1/paizo-sdk.js",
+    "PROTOCOL.md"
+  ],
+  "scripts": {
+    "dev": "node scripts/serve.mjs",
+    "levels:glide": "node scripts/gen-glide-levels.mjs"
+  }
+}

package/sdk/v1/paizo-sdk.js

@@ -0,0 +1,379 @@
+/*!
+ * Paizo Games SDK v1
+ *
+ * Loaded by every game with:
+ *   <script src="/sdk/v1/paizo-sdk.js"></script>
+ *
+ * The game runs in a cross-origin iframe on the portal. This file is a thin
+ * postMessage client: the portal ("host") decides whether an ad is shown,
+ * who the user is and where saves are kept. See PROTOCOL.md.
+ */
+(function (global) {
+  "use strict";
+
+  if (global.PaizoSDK) return;
+
+  var VERSION = "1.0.0";
+  var PROTOCOL = 1;
+  var HANDSHAKE_TIMEOUT_MS = 1500;
+  var AD_TIMEOUT_MS = 120000;
+  var SAVE_POLL_MS = 2000;
+  var SAVE_LIMIT_BYTES = 1024 * 1024;
+  var IGNORE_PREFIX = "paizo_ignore";
+  var META_KEY = IGNORE_PREFIX + ":meta";
+
+  // Only these parents are accepted as a host.
+  var TRUSTED_HOST = [
+    /^https:\/\/([a-z0-9-]+\.)*paizogames\.com$/,
+    /^http:\/\/localhost(:\d+)?$/,
+    /^http:\/\/127\.0\.0\.1(:\d+)?$/,
+  ];
+
+  var environment = "local"; // "paizo" once the portal answers the handshake
+  var hostOrigin = null;
+  var user = null;
+  var initPromise = null;
+  var seq = 0;
+  var pending = {}; // id -> { resolve, reject, onStart, timer }
+  var playing = false;
+  var loadedSent = false;
+  var adInProgress = false;
+
+  function log() {
+    if (!global.console) return;
+    var args = ["[PaizoSDK]"].concat([].slice.call(arguments));
+    console.log.apply(console, args);
+  }
+
+  function isTrusted(origin) {
+    for (var i = 0; i < TRUSTED_HOST.length; i++) {
+      if (TRUSTED_HOST[i].test(origin)) return true;
+    }
+    return false;
+  }
+
+  // ---------------------------------------------------------------- transport
+
+  function post(message, targetOrigin) {
+    message.paizo = PROTOCOL;
+    global.parent.postMessage(message, targetOrigin || hostOrigin || "*");
+  }
+
+  function request(type, payload, timeoutMs, onStart) {
+    return new Promise(function (resolve, reject) {
+      var id = "r" + ++seq;
+      var entry = { resolve: resolve, reject: reject, onStart: onStart };
+      if (timeoutMs) {
+        entry.timer = setTimeout(function () {
+          delete pending[id];
+          reject(new Error("PaizoSDK: '" + type + "' timed out"));
+        }, timeoutMs);
+      }
+      pending[id] = entry;
+      post({ type: type, id: id, payload: payload || {} });
+    });
+  }
+
+  function notify(type, payload) {
+    if (environment !== "paizo") return;
+    post({ type: type, payload: payload || {} });
+  }
+
+  global.addEventListener("message", function (event) {
+    var data = event.data;
+    if (!data || data.paizo !== PROTOCOL) return;
+    if (event.source !== global.parent) return;
+    if (hostOrigin ? event.origin !== hostOrigin : !isTrusted(event.origin)) {
+      return;
+    }
+
+    if (data.event === "adStarted") {
+      var ad = pending[data.id];
+      if (ad && typeof ad.onStart === "function") {
+        try {
+          ad.onStart();
+        } catch (e) {
+          log("onStart callback threw", e);
+        }
+      }
+      return;
+    }
+
+    var entry = pending[data.id];
+    if (!entry) return;
+    delete pending[data.id];
+    if (entry.timer) clearTimeout(entry.timer);
+    if (!hostOrigin) hostOrigin = event.origin;
+    if (data.ok) entry.resolve(data.result);
+    else entry.reject(new Error(data.error || "PaizoSDK: request failed"));
+  });
+
+  // -------------------------------------------------------------------- saves
+  // Games just use localStorage. The SDK mirrors it to the portal, which keeps
+  // a copy per game (and, once accounts exist, syncs that copy to the cloud).
+
+  var saveEnabled = true;
+  var lastSnapshot = "{}";
+
+  function storage() {
+    try {
+      return global.localStorage;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function readMeta() {
+    try {
+      return JSON.parse(storage().getItem(META_KEY)) || {};
+    } catch (e) {
+      return {};
+    }
+  }
+
+  function writeMeta(meta) {
+    try {
+      storage().setItem(META_KEY, JSON.stringify(meta));
+    } catch (e) {}
+  }
+
+  function snapshot() {
+    var ls = storage();
+    var keys = [];
+    for (var i = 0; i < ls.length; i++) {
+      var key = ls.key(i);
+      if (key.indexOf(IGNORE_PREFIX) !== 0) keys.push(key);
+    }
+    keys.sort();
+    var data = {};
+    for (var j = 0; j < keys.length; j++) data[keys[j]] = ls.getItem(keys[j]);
+    return JSON.stringify(data);
+  }
+
+  function restore(data) {
+    var ls = storage();
+    var remove = [];
+    for (var i = 0; i < ls.length; i++) {
+      var key = ls.key(i);
+      if (key.indexOf(IGNORE_PREFIX) !== 0) remove.push(key);
+    }
+    remove.forEach(function (key) {
+      ls.removeItem(key);
+    });
+    Object.keys(data).forEach(function (key) {
+      ls.setItem(key, data[key]);
+    });
+  }
+
+  function flushSave() {
+    if (!saveEnabled || environment !== "paizo") return;
+    var current;
+    try {
+      current = snapshot();
+    } catch (e) {
+      saveEnabled = false;
+      return;
+    }
+    if (current === lastSnapshot) return;
+    if (current.length > SAVE_LIMIT_BYTES) {
+      saveEnabled = false;
+      log("save data is over 1MB, sync is now off for this player");
+      return;
+    }
+    lastSnapshot = current;
+    var updatedAt = Date.now();
+    writeMeta({ updatedAt: updatedAt });
+    notify("save", { updatedAt: updatedAt, data: JSON.parse(current) });
+  }
+
+  function startSaveSync(hostSave) {
+    if (!storage()) {
+      saveEnabled = false;
+      return;
+    }
+    try {
+      var localAt = readMeta().updatedAt || 0;
+      if (hostSave && hostSave.data && hostSave.updatedAt > localAt) {
+        // The portal has a newer copy (e.g. from another device): use it.
+        restore(hostSave.data);
+        writeMeta({ updatedAt: hostSave.updatedAt });
+        lastSnapshot = snapshot();
+      } else {
+        // Local copy wins; anything the portal is missing is pushed below.
+        lastSnapshot = JSON.stringify((hostSave && hostSave.data) || {});
+      }
+    } catch (e) {
+      saveEnabled = false;
+      return;
+    }
+    flushSave();
+    setInterval(flushSave, SAVE_POLL_MS);
+    global.addEventListener("pagehide", flushSave);
+    document.addEventListener("visibilitychange", function () {
+      if (document.visibilityState === "hidden") flushSave();
+    });
+  }
+
+  // ------------------------------------------------------------ local fallback
+  // Outside the portal (opened directly, or on localhost during development)
+  // every call still works, so a game never has to branch on the environment.
+
+  function localAd(kind) {
+    return new Promise(function (resolve) {
+      var el = document.createElement("div");
+      el.textContent = "Paizo SDK (local) — " + kind + " ad placeholder";
+      el.style.cssText =
+        "position:fixed;inset:0;z-index:2147483647;display:flex;" +
+        "align-items:center;justify-content:center;background:rgba(0,0,0,.85);" +
+        "color:#fff;font:600 16px system-ui,sans-serif;text-align:center;padding:24px";
+      document.body.appendChild(el);
+      setTimeout(function () {
+        el.remove();
+        resolve();
+      }, 1200);
+    });
+  }
+
+  // --------------------------------------------------------------- public API
+
+  function init() {
+    if (initPromise) return initPromise;
+    initPromise = new Promise(function (resolve) {
+      function finish() {
+        log("v" + VERSION + " ready, environment: " + environment);
+        resolve();
+      }
+      if (global.parent === global) return finish();
+
+      var localAt = 0;
+      try {
+        localAt = readMeta().updatedAt || 0;
+      } catch (e) {}
+
+      request(
+        "init",
+        { sdkVersion: VERSION, saveUpdatedAt: localAt },
+        HANDSHAKE_TIMEOUT_MS
+      ).then(
+        function (result) {
+          environment = "paizo";
+          user = (result && result.user) || null;
+          startSaveSync(result && result.save);
+          finish();
+        },
+        function () {
+          hostOrigin = null;
+          finish();
+        }
+      );
+    });
+    return initPromise;
+  }
+
+  function gameLoadingFinished() {
+    return init().then(function () {
+      if (loadedSent) return;
+      loadedSent = true;
+      notify("loaded");
+    });
+  }
+
+  function setPlaying(value) {
+    return init().then(function () {
+      if (playing === value) return;
+      playing = value;
+      notify("gameplay", { playing: value });
+      if (!value) flushSave();
+    });
+  }
+
+  function adBreak(kind, onStart) {
+    return init().then(function () {
+      if (adInProgress) return false;
+      adInProgress = true;
+      var done = function (shown) {
+        adInProgress = false;
+        return shown;
+      };
+
+      if (environment !== "paizo") {
+        if (typeof onStart === "function") onStart();
+        return localAd(kind).then(function () {
+          return done(true);
+        });
+      }
+
+      return request("ad", { kind: kind }, AD_TIMEOUT_MS, onStart).then(
+        function (result) {
+          return done(!!(result && result.shown));
+        },
+        function () {
+          return done(false);
+        }
+      );
+    });
+  }
+
+  global.PaizoSDK = {
+    version: VERSION,
+
+    /** Call once, before anything else. Never rejects. */
+    init: init,
+
+    /** "paizo" inside the portal, "local" anywhere else. Valid after init(). */
+    get environment() {
+      return environment;
+    },
+
+    /** The game has finished loading and is ready to be played. */
+    gameLoadingFinished: gameLoadingFinished,
+
+    /** The player is actively playing (level start, unpause). */
+    gameplayStart: function () {
+      return setPlaying(true);
+    },
+
+    /** The player stopped playing (level end, game over, pause, menu). */
+    gameplayStop: function () {
+      return setPlaying(false);
+    },
+
+    /**
+     * Ask for an ad at a natural break. The portal decides whether one is
+     * actually shown. Resolves when the game may continue.
+     * @param {Function} [onStart] called if an ad really starts: mute here.
+     */
+    commercialBreak: function (onStart) {
+      return adBreak("commercial", onStart).then(function () {});
+    },
+
+    /**
+     * Offer a rewarded ad the player chose to watch.
+     * Resolves true only if the reward should be granted.
+     * @param {Function} [onStart] called if an ad really starts: mute here.
+     */
+    rewardedBreak: function (onStart) {
+      return adBreak("rewarded", onStart);
+    },
+
+    /** Resolves { username, avatarUrl } or null for a guest. */
+    getUser: function () {
+      return init().then(function () {
+        return user;
+      });
+    },
+
+    /** Opens the portal's sign-in. Rejects while accounts are unavailable. */
+    login: function () {
+      return init().then(function () {
+        if (environment !== "paizo") {
+          throw new Error("PaizoSDK: login is unavailable outside the portal");
+        }
+        return request("login", {}, AD_TIMEOUT_MS).then(function (result) {
+          user = (result && result.user) || null;
+          return user;
+        });
+      });
+    },
+  };
+})(window);