npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@tesana/sdk

v1.5.0

Published

Tesana play-time SDK — players, cloud saves, leaderboards, achievements and the in-game coin shop for a web game.

Readme

@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

npm install @tesana/sdk

Use

An exported game boots from the global, because Tesana's own guidance forbids importing a package into game code:

<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:

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 — me / isGuest / login() (asks the host to sign in, like economy.signIn) | | tesana.vanity | The game's own address on tesana.ai | | tesana.ads | Ads, when the host allows them | | tesana.gameplay | Progression events — levelStart / levelComplete / levelFail / death / checkpoint / score | | tesana.track | Any other gameplay event, by name | | tesana.feedback | Player reports to the creator — open (host form) / submit; crashes are filed automatically | | tesana.config | Values the creator tunes without a rebuild — get(key, default) / getAll / ready | | tesana.share | Invite links — share({ roomCode, levelId, text }) / share.params() | | tesana.build | This build's id (its hash), from the host or the page's <meta name="tesana-build">; "" when neither says | | tesana.release | The release number when this build is the release players have, else null | | tesana.locale | The player's language as a BCP 47 tag, e.g. "ko-KR" (since 1.4.0; see Languages) | | tesana.l10n | The platform's translation of declared strings — t / locale (the site's language) / languages / onChange | | Tesana.reservedArea() | The top-right box the Tesana player keeps for its button on a phone (since 1.5.0; see The player's corner) |

The player's corner (since 1.5.0)

On a phone, the Tesana player draws one button over the game's top-right corner. Tesana.reservedArea() (also tesana.reservedArea()) says where, so a game keeps its pause button, minimap and score out of it: { top, right, width, height } in CSS px of the game's viewport, from its top-right corner. It is synchronous, needs no init(), and returns a fresh object each call: read it again on resize and on window's tesana-reservedareachange.

| Host | Box | |---|---| | Web player, or no host | { top: 12, right: 12, width: 36, height: 36 }, with top/right raised to the page's env(safe-area-inset-*) when that is larger (read on every call) | | Tesana app (a TesanaApp/<version> user agent) | { top: 8, right: 8, width: 36, height: 36 } | | A host that sends reservedArea | exactly that box ({ top: 0, right: 0, width: 0, height: 0 }: nothing reserved) |

A host names its box with reservedArea on the bootstrap, and moves it later (a rotation, a new safe-area inset) by posting { type: "tesana-reserved-area", reservedArea: { top, right, width, height } } into the frame. The newest box wins, and each one fires tesana-reservedareachange on window. A box with a missing, negative or non-number side is ignored.

function placeHud() {
  const r = window.Tesana?.reservedArea?.() ?? { top: 12, right: 12, width: 36, height: 36 };
  pauseButton.style.top = `${r.top}px`;
  pauseButton.style.right = `${r.right + r.width + 8}px`; // left of the Tesana button
}
placeHud();
addEventListener("resize", placeHud);
addEventListener("tesana-reservedareachange", placeHud);

The ?. form keeps a game working on an SDK older than 1.5.0.

Languages (since 1.4.0)

A game that ships its own translations picks one at start from tesana.locale: the site's language when the player picked it, English included (the host says so with localeChosen: true on the bootstrap and on each tesana-locale change; a host that does not say counts only a non-English language as picked), otherwise the browser's first language, as a canonical BCP 47 tag (ko-KR, fr, zh-Hant-TW). The site sends en to every visitor who has not picked a language, so tesana.l10n.locale() (the site's language, which the platform translates into) says en for most Korean or French players; tesana.locale does not. Match its base tag against the languages the game ships and fall back to English. A change while playing fires tesana.l10n.onChange.

const shipped = ["en", "ko", "fr", "ja"];
const base = tesana.locale.toLowerCase().split("-")[0];
const lang = shipped.includes(base) ? base : "en";

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.

Gameplay analytics

tesana.track and tesana.gameplay report what happened in the game so its creator can see where players get stuck and where they quit. They go to the Tesana page above the game, which files them against the play session; there is no key and no third-party provider.

tesana.gameplay.levelStart({ levelId: "forest", levelIndex: 1 });
tesana.gameplay.death({ levelId: "forest", x: player.x, y: player.y });
tesana.gameplay.checkpoint({ levelId: "forest", name: "bridge" });
tesana.gameplay.levelComplete({ levelId: "forest" });
tesana.gameplay.levelFail("forest", "out_of_time");
tesana.gameplay.score({ value: 4200 });
tesana.track("powerup_picked", { kind: "triple_shot" });
type GameplayProps = {
  levelId?: string | number;   // the join key: the same value in every call for one level
  levelIndex?: number;         // 0-based position, when levels are ordered
  x?: number; y?: number; z?: number;  // where it happened (deaths draw the heatmap)
  value?: number;              // a score, a count
  name?: string;               // a death's cause, a checkpoint's name
  [context: string]: string | number | boolean | null | undefined;
};

track(name: string, props?: GameplayProps): boolean;
gameplay.levelStart(props?: GameplayProps | string | number): boolean;     // bare value = levelId
gameplay.levelComplete(props?: GameplayProps | string | number): boolean;
gameplay.levelFail(props?: GameplayProps | string | number, reason?: string): boolean;  // since 1.3.0
gameplay.death(props?: GameplayProps | string | number): boolean;
gameplay.checkpoint(props?: GameplayProps | string | number): boolean;
gameplay.score(props?: GameplayProps | number): boolean;                   // bare value = value
  • Never throws, never async. Each call answers true when the event was handed on and false when it was dropped (a bad name, too many events, or no Tesana page and no runtime shell to hand it to). Call it inline, unguarded.
  • No init() needed. The same functions are on the global Tesana, so a game can report its first level before __TESANA_READY__ resolves.
  • Delivery. The runtime shell's window.__TESANA_EVENT__ when the page has it, else postMessage({ type: "tesana-gameplay-event", event }) to the parent. event is the shape POST /api/games/<id>/play/events/ stores: type (level_start, level_complete, death, checkpoint, score or custom), name, level_id, level_index, x, y, z, value, payload, ts.
  • track names. A name that is one of the types above files the event as that type; any other name is a custom event with that name.
  • Caps. Names are cut to 64 characters. Up to 20 context keys are kept (keys cut to 40 characters, strings to 64); objects, arrays, functions and non-finite numbers are dropped, and keys stop being added before the payload passes the endpoint's 2,000-character limit.
  • Rate. At most 10 events in any one second and 1,000 per page load. Report discrete moments — a level, a death, a run's end — never every frame.

First-party events (since 1.3.0)

The level calls also go to Tesana's event collector (POST /api/e on the API, TES-2197), and the SDK adds two events by itself: a play heartbeat for every 15 s the game is in front (active after a key, pointer, touch or gamepad input in the last 30 s, else open) and a quit when the page closes, naming the level the player was in. The heartbeat clock runs only while the page is visible and resumes where it stopped, so a return to the tab sends nothing at once (TES-2641). Types and properties are the backend registry's (one_tap/events/registry.py):

| Type | When | props | |---|---|---| | game.level.started@1 | levelStart | level, level_index | | game.level.ended@1 | levelComplete, levelFail | level, outcome (completed or failed), duration_ms, reason | | game.session.quit@1 | pagehide | level, in_level, seconds | | play.session.heartbeat@1 | each 15 s in front | state (open or active), level |

  • Where. Only from Tesana's play hosts: play.tesana.ai sends to production's API, play-staging.tesana.ai to staging's. A host can name the collector instead (eventsEndpoint in the bootstrap, for a desktop build's prelude; none does yet, so desktop builds send nothing). Any other page, localhost and preview sandboxes included, sends nothing, and so does a QA rig (__TESANA_QA_RIG__), an automated browser (navigator.webdriver), a test's DOM (jsdom) or a host that says events: false.
  • Only a real play page (TES-2640). Studio previews run on the same play host, so nothing is sent until the page is known not to be one: the host says studio: false, names its collector, or posts a play token without the studio claim the play service stamps on a Studio test session. Until then events wait in the queue; studio: true or a Studio token drops them.
  • The game. Named by the bootstrap's gameId: its public id goes as play_game_id (the collector stores the game's id), a site id as game_id. No id, nothing is sent.
  • Nothing personal (TES-2639). No device id: the SDK's device id can be traded for that guest's play token, so it never goes to analytics. The browser is named by its own random anonymous_id.
  • The account, named by the server (since 1.3.1, TES-2722). The SDK never sends a user id. A signed-in player's batch carries the site's play session token (the bootstrap's token, the one the shop calls send) as token in the body, since a beacon can't carry an Authorization header. The collector checks it (signature, expiry, and that it is this game's) and stores the events with the player's account; a guest's events, or a forged, expired or other game's token, stay anonymous. A play service token (a JWT, all a guest holds) never goes. The token goes only to Tesana's own collectors, never to one a host or the game names (TES-2729), and a host answer without it (a sign-out) takes it away at once, even one the session refuses to adopt (TES-2730).
  • Delivery. Batched every 30 s (at once at 50 events), and flushed by navigator.sendBeacon when the page is hidden or closed, as JSON labelled text/plain; a keepalive fetch when there is no beacon. Every event has its own UUID, so a batch that arrives twice is stored once. Offline, a batch is dropped. Never throws, never blocks.

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. config.get answers the last session's value or the game's default, and feedback.open() and share() resolve { ok: false, reason }. Writes that report something (scores.submit, feedback.submit) reject, so the game can say it did not send. 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:

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.