@idosgames/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to `@idosgames/core` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> While the version stays in the **`0.x`** range the public API is still stabilizing:
+> breaking changes may land in a **minor** bump. Once the surface is stable we cut
+> `1.0.0`, and from then on breaking changes require a **major** bump.
+>
+> Anything marked `@experimental` in the code is exempt from these guarantees until it
+> is promoted. See [RELEASING.md](../../RELEASING.md) for the full process.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-29
+
+### Added
+
+- Engine-agnostic core client (`createIDosGamesClient` / `IDosGamesClient`) that owns the
+  whole SDK graph: HTTP transport (retry, in-flight dedup, throttle, transparent 401
+  re-login), auth, local cache, and a typed event bus.
+- 24 feature domains exposed as services on the client: `auth`, `user`, `currency`,
+  `item`, `store`, `lootbox`, `reward`, `quest`, `timedEvent`, `leaderboard`, `season`,
+  `premium`, `character`, `match`, `craft`, `collection`, `coopEvent`, `dealOffer`,
+  `referral`, `social`, `timedBoost`, `userCustomData`, `title`, `gameLoop`.
+- `OperationResult<T>` discriminated result type — services never throw on expected
+  failures; callers branch on `result.ok`.
+- zod-validated response models (the schema is the source of truth via `z.infer`).
+- Platform adapters (`BrowserPlatformAdapter`, `NoopPlatformAdapter`) plus the
+  `@idosgames/core/platform` subpath export.
+
+---
+
+The game templates `@idosgames/board-game` and `@idosgames/idle-rpg` live in this repo
+as **starter projects** and are intentionally **not** published to npm; they are not
+tracked in this changelog.
+
+<!-- When the GitHub remote is known, add compare links here, e.g.:
+[Unreleased]: https://github.com/<org>/<repo>/compare/v0.1.0...HEAD
+-->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iDos Games
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @idosgames/core
+
+Engine-agnostic core of the **IDosGames SDK** — HTTP transport, authentication,
+local cache, 24 feature services, and a typed event bus. It knows nothing about
+any rendering engine (Three.js, Phaser, React…), so it works in any browser or
+JS runtime.
+
+- **Typed end to end.** Every backend response is validated at runtime with
+  [zod](https://zod.dev) before it reaches your code; the published type
+  declarations are flat and lightweight.
+- **No exceptions on expected failures.** Service calls return a discriminated
+  `OperationResult<T>` (`{ ok: true, data }` or `{ ok: false, reason, error }`).
+- **One client owns the whole graph.** Create it once; reach every service and
+  the local cache from it.
+
+## Install
+
+```bash
+npm install @idosgames/core
+```
+
+Peer runtime deps (`zod`, `decimal.js`) are installed automatically.
+
+## Quick start
+
+```ts
+import { createIDosGamesClient, isOk } from "@idosgames/core";
+import { BrowserPlatformAdapter } from "@idosgames/core/platform";
+
+const client = createIDosGamesClient({
+  titleID: "YOUR_TITLE_ID",
+  platform: new BrowserPlatformAdapter(), // storage + platform integration
+});
+
+// Authenticate (device id, Telegram, email, Google, or a platform token).
+const login = await client.auth.loginWithDeviceID();
+if (!isOk(login)) {
+  console.error("login failed:", login.reason, login.error);
+}
+
+// Call any service — results are discriminated, never thrown.
+const res = await client.currency.convert(
+  "Virtual",
+  "GOLD",
+  "Virtual",
+  "GEM",
+  100,
+);
+if (isOk(res)) {
+  console.log("credited:", res.data.TargetCredited);
+}
+
+// Read the local cache and react to changes via the typed event bus.
+const off = client.on("currency:converted", (payload) => {
+  console.log("balances updated", payload);
+});
+// later: off();
+```
+
+## What's on the client
+
+`client.auth`, `user`, `currency`, `item`, `store`, `lootbox`, `reward`, `quest`,
+`timedEvent`, `leaderboard`, `season`, `premium`, `character`, `match`, `craft`,
+`collection`, `coopEvent`, `dealOffer`, `referral`, `social`, `timedBoost`,
+`userCustomData`, `title`, `gameLoop` — plus `client.data` (local cache) and
+`client.on/once/off` (events).
+
+## Entry points
+
+| Import                     | What                                                                                                             |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `@idosgames/core`          | client, services, models, result & event types                                                                   |
+| `@idosgames/core/platform` | platform adapters & storage (`BrowserPlatformAdapter`, `NoopPlatformAdapter`, `BrowserStorage`, `MemoryStorage`) |
+
+## Versioning
+
+Semantic versioning. While on `0.x` the public API is still stabilizing, so
+breaking changes may land in a **minor** bump — see
+[CHANGELOG.md](./CHANGELOG.md). The backend HTTP API version (`/api/v2/…`) is
+independent of this package's version.
+
+## License
+
+[MIT](./LICENSE) © iDos Games

package/dist/chunk-QJVWT32O.js

@@ -0,0 +1 @@
+var n=class{getString(e){if(typeof localStorage>"u")return null;try{return localStorage.getItem(e)}catch{return null}}setString(e,t){if(!(typeof localStorage>"u"))try{localStorage.setItem(e,t);}catch{}}remove(e){if(!(typeof localStorage>"u"))try{localStorage.removeItem(e);}catch{}}},o=class{map=new Map;getString(e){return this.map.get(e)??null}setString(e,t){this.map.set(e,t);}remove(e){this.map.delete(e);}};function r(){return globalThis.Telegram?.WebApp??null}function l(){return crypto.randomUUID()}var s="idos_device_id",i=class{storage;constructor(e=new n){this.storage=e;}getPlatform(){return r()?.platform??"Web"}getFullURL(){return typeof location<"u"?location.href:""}getStartParameter(){let e=r()?.initDataUnsafe?.start_param;return typeof e=="string"?e:null}getTelegramInitDataRaw(){let e=r()?.initData;return e&&e.length>0?e:null}getDeviceID(){let e=this.storage.getString(s);return e||(e=l(),this.storage.setString(s,e)),e}getDeviceModel(){return typeof navigator<"u"&&navigator.userAgent?navigator.userAgent:"Web"}shareLink(e){let t=r();if(t?.openTelegramLink){t.openTelegramLink(e);return}typeof window<"u"&&window.open(e,"_blank");}openInvoice(e){let t=r();if(t?.openInvoice){t.openInvoice(e);return}typeof window<"u"&&window.open(e,"_blank");}async showAd(e){let t=globalThis;typeof t.showAd=="function"&&await t.showAd(e);}async copyToClipboard(e){typeof navigator<"u"&&navigator.clipboard&&await navigator.clipboard.writeText(e);}};var p="idos_device_id",g=class{storage;constructor(e=new o){this.storage=e;}getPlatform(){return "Web"}getFullURL(){return ""}getStartParameter(){return null}getTelegramInitDataRaw(){return null}getDeviceID(){let e=this.storage.getString(p);return e||(e="noop-device",this.storage.setString(p,e)),e}getDeviceModel(){return "Noop"}shareLink(){}openInvoice(){}async showAd(){}async copyToClipboard(){}};export{n as a,o as b,r as c,l as d,i as e,g as f};