@tesana/sdk 1.0.0

package/README.md

@@ -0,0 +1,86 @@
+# @tesana/sdk
+
+Tesana's play-time SDK. It gives a web game a player identity, cloud saves that
+follow that player to another device, leaderboards, achievements, and the
+in-game coin shop — without the game talking to any of those services directly.
+
+The SDK is what the global `window.Tesana` is. In a game published on Tesana the
+platform injects it and hands over the player and the game's identity; the game
+just calls it.
+
+## Install
+
+```bash
+npm install @tesana/sdk
+```
+
+## Use
+
+An exported game boots from the global, because Tesana's own guidance forbids
+importing a package into game code:
+
+```html
+<script src="https://unpkg.com/@tesana/sdk/dist/tesana.iife.js"></script>
+<script type="module">
+  const tesana = await window.__TESANA_READY__;
+  const save = await tesana.db.get("save");
+</script>
+```
+
+Bundled or module code can import it instead, which is the same client:
+
+```js
+import Tesana from "@tesana/sdk";
+
+const tesana = await Tesana.init();
+await tesana.db.set("save", { level: 7 });
+```
+
+`init()` accepts `{ gameId, endpoint, playerToken }`. With none of them it reads
+`window.__TESANA__`, then asks the host page over `postMessage`, and finally
+falls back to a guest identity — so a game still runs with no host, no network
+and nobody signed in. Never gate the game itself behind a service call
+succeeding.
+
+### Surfaces
+
+| | |
+|---|---|
+| `tesana.db` | Cloud saves — `get` / `set` / `list` / `collection` |
+| `tesana.scores` | Leaderboards — `submit` / `top` / `me` / `best` |
+| `tesana.achievements` | Badges — `list` / `unlocked` / `unlock` / `progress` |
+| `tesana.shop` | In-game shop — `catalog` / `items` / `buy` / `entitlements` / `inventory` |
+| `tesana.economy` | Coins — `balance` / `packs` / `topUp` / `signIn` |
+| `tesana.multiplayer` | Open lobbies — `list` / `create` / `join` / `quickJoin` / `send` / `on` |
+| `tesana.player` | Identity — `login({ tesanaUserId })` |
+| `tesana.vanity` | The game's own address on tesana.ai |
+| `tesana.ads` | Ads, when the host allows them |
+
+Leaderboards and achievements are client-reported, so they are a ranking to show
+off rather than a prize table; nothing here mints coins or grants entitlements.
+A counted achievement is decided by the server, not the game.
+
+### Offline behaviour
+
+Every call resolves rather than throwing when there is no host, no endpoint or
+no network. Saves read as empty, the shop reports `no_host`, and the game plays.
+Real money is never the game's business — `topUp()` asks the host to run
+checkout, and the price shown is read from the service.
+
+## Building this package
+
+The published artifact is generated, not hand-written:
+
+```bash
+npm run build:sdk        # writes dist/tesana.iife.js and dist/tesana.esm.js
+npm run version:sdk -- 1.2.0   # bumps VERSION and package.json together
+```
+
+`build.js` refuses to build if `VERSION` in `src/tesana.js` and `version` in
+`package.json` disagree — the engine derives each game's pinned `/sdk/v<major>/`
+URL from the first and npm resolves the second, so a mismatch would publish a
+package whose declared version is not the SDK inside it.
+
+## License
+
+Proprietary. Copyright Tesana. All rights reserved. Not for redistribution.