@totop/platform-sdk

Browser SDK for reviewed ToTop applications and games. It provides unified identity, protected API access, cloud saves, token rotation, and local/global logout separation.

npm install @totop/[email protected]

import { ToTop } from '@totop/platform-sdk'

await ToTop.init('/totop.auth.json')
await ToTop.login()

// Use this only for an explicit “Switch account” action, or when a product
// wants account choice after its own local sign-out.
await ToTop.login({ selectAccount: true })

const user = ToTop.getUser()

// Games get cloud save without implementing HTTP, tokens or revision handling.
const save = await ToTop.cloudSave.save({ level: 4, score: 1200 })
await ToTop.cloudSave.restore((payload) => game.restore(payload))

// Use authorizedFetch only for other reviewed ToTop APIs.
const response = await ToTop.authorizedFetch('https://api.totop.ai/game-api/games/ID/custom-resource')
await ToTop.logout()

The reviewed totop.auth.json is public configuration and contains no secret. Access tokens stay in memory; rotating refresh tokens are limited to the current browser tab's sessionStorage for at most eight hours.

Cloud save (game clients)

ToTop.cloudSave is available only when totop.auth.json has type: "game" and a reviewed game:<uuid> client.

const saved = await ToTop.cloudSave.save(state, {
  slot: 0,           // 0-9; default 0
  schemaVersion: 1,  // default 1
})

const cloud = await ToTop.cloudSave.load(0) // null when the slot is empty
const all = await ToTop.cloudSave.list()
await ToTop.cloudSave.restore((payload, save) => game.restore(payload), 0)

The SDK remembers each loaded revision and sends the correct optimistic-concurrency value automatically. A concurrent write throws ToTopCloudSaveConflictError, whose currentSave is the authoritative cloud copy. A save payload must be a JSON object and is limited to 1 MiB per slot.

Run npx totop-platform verify in the integrating project before publishing.

logout() ends only the current SDK client session; it intentionally keeps the shared auth.totop.ai browser session so other ToTop services remain signed in. A later login() may reuse that account. Use login({ selectAccount: true }) for an explicit account-choice flow. Reserve logout({ global: true }) for a separately labelled “Sign out everywhere” action.