@oyna360/game-sdk 0.5.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 oyna360
+
+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,173 @@
+# @oyna360/game-sdk
+
+SDK رسمی اتصال **بازی شما** به **پلتفرم oyna360**.
+
+با این پکیج بازی می‌تواند:
+
+- هویت بازیکن و سشن را بگیرد
+- امتیاز، لیدربورد، دستاورد و کیف‌پول جِم را صدا بزند
+- در **Production** داخل iframe پلتفرم کار کند
+- در **Development** بدون iframe، مستقیم به سرور oyna360 وصل شود
+
+**نسخه:** `0.5.1` · بدون وابستگی runtime · TypeScript داخل پکیج
+
+> این SDK مسئول لابی ۳D نیست. برای لابی از [`@oyna360/lobby-sdk`](https://github.com/mamadjavadrasti/oyna360-lobby-sdk) استفاده کنید. این دو پکیج را ادغام نکنید.
+
+---
+
+## نصب
+
+```bash
+npm install github:mamadjavadrasti/oyna360-game-sdk#v0.5.1
+# یا
+pnpm add github:mamadjavadrasti/oyna360-game-sdk#v0.5.1
+```
+
+```json
+{
+  "dependencies": {
+    "@oyna360/game-sdk": "github:mamadjavadrasti/oyna360-game-sdk#v0.5.1"
+  }
+}
+```
+
+همیشه تگ نسخه‌ای را پین کنید که `dist/` داخل ریپو دارد.
+
+---
+
+## دو حالت اجرا
+
+| حالت | چطور بازی باز می‌شود | `init()` از کجا Context می‌گیرد |
+|------|----------------------|----------------------------------|
+| **Production** | بازیکن از `https://oyna360.ir/play/{slug}` وارد می‌شود؛ بازی داخل iframe است | `postMessage` → `platform:init` از parent |
+| **Direct Development** | شما `npm run dev` می‌زنید و بازی را مستقیم روی origin خودتان باز می‌کنید | Authorize با اکانت واقعی → سشن موقت → همان `SdkInitPayload` |
+
+در هر دو حالت API بازی یکسان است:
+
+```ts
+import { PlatformSDK } from '@oyna360/game-sdk';
+
+const { user, game, session, avatar, lobby } = await PlatformSDK.init({
+  // فقط برای Direct Development لازم است:
+  // platformUrl: 'https://oyna360.ir/api',
+  // platformWebUrl: 'https://oyna360.ir',
+  // gameSlug: 'my-game',
+});
+```
+
+---
+
+## شروع سریع — Production
+
+1. بازی را روی URL عمومی host کنید.
+2. در پنل ادمین oyna360: `slug`، `entryUrl`، `allowedOrigins`، `minSdkVersion`.
+3. بازیکن از `/play/{slug}` وارد شود.
+
+```ts
+import { PlatformSDK } from '@oyna360/game-sdk';
+
+async function boot() {
+  const { user, game } = await PlatformSDK.init({ timeout: 15_000 });
+  console.log(user.displayName, game.slug);
+
+  // گیم‌پلی…
+  await PlatformSDK.submitScore(4200);
+  await PlatformSDK.endSession();
+}
+
+boot().catch(console.error);
+```
+
+---
+
+## شروع سریع — Direct Development
+
+بدون کلون کردن پلتفرم:
+
+```ts
+await PlatformSDK.init({
+  platformUrl: 'https://oyna360.ir/api',
+  platformWebUrl: 'https://oyna360.ir',
+  gameSlug: 'my-game',
+});
+```
+
+یا قبل از `init`:
+
+```ts
+window.__OYNA360_DEV__ = {
+  platformUrl: 'https://oyna360.ir/api',
+  platformWebUrl: 'https://oyna360.ir',
+  gameSlug: 'my-game',
+};
+await PlatformSDK.init();
+```
+
+پنجرهٔ ورود oyna360 باز می‌شود؛ با اکانت واقعی وارد می‌شوید؛ SDK Context کامل (شامل `avatar` و `lobby`) را می‌گیرد.
+
+در Direct Development همان APIهای امتیاز، لیدربورد، دستاورد و کیف‌پول از طریق REST مستقیم به `platformUrl` صدا زده می‌شوند (بدون iframe). Origin بازی باید در `DEV_GAME_ORIGINS` / `allowedOrigins` و CORS باشد.
+
+جزئیات و تنظیم Origin: [docs/09-direct-development.md](./docs/09-direct-development.md)
+
+---
+
+## مستندات
+
+| موضوع | فایل |
+|--------|------|
+| این SDK چیست / مرز با lobby-sdk | [docs/00-overview.md](./docs/00-overview.md) |
+| نصب و پیش‌نیاز ادمین | [docs/01-shoro.md](./docs/01-shoro.md) |
+| `init()` و `SdkInitPayload` | [docs/02-init.md](./docs/02-init.md) |
+| user / session | [docs/03-user-session.md](./docs/03-user-session.md) |
+| پایان سشن | [docs/04-end-session.md](./docs/04-end-session.md) |
+| امتیاز | [docs/05-scores.md](./docs/05-scores.md) |
+| لیدربورد | [docs/06-leaderboard.md](./docs/06-leaderboard.md) |
+| پروتکل postMessage | [docs/07-postmessage-protocol.md](./docs/07-postmessage-protocol.md) |
+| جِم و سکه | [docs/08-wallet.md](./docs/08-wallet.md) |
+| Direct Development Mode | [docs/09-direct-development.md](./docs/09-direct-development.md) |
+| دستاوردها | [docs/10-achievements.md](./docs/10-achievements.md) |
+| عیب‌یابی | [docs/11-troubleshooting.md](./docs/11-troubleshooting.md) |
+
+---
+
+## API خلاصه
+
+| متد | توضیح | Production | Direct Dev |
+|-----|--------|:----------:|:----------:|
+| `init(options?)` | دریافت Context پلتفرم | ✅ | ✅ |
+| `getUser()` / `getSession()` / `getInitPayload()` / `isReady()` | خواندن وضعیت | ✅ | ✅ |
+| `endSession()` | بستن سشن | ✅ | ✅ |
+| `submitScore` / `getLeaderboard` | امتیاز | ✅ | ✅ |
+| `unlockAchievement` / `getAchievements` | دستاورد | ✅ | ✅ |
+| `getWallet` / `convertGems` | جِم | ✅ | ✅ |
+
+Production از `postMessage` به parent استفاده می‌کند؛ Direct Dev همان endpointهای REST را با session token صدا می‌زند.
+
+`PlatformSDK.version` → `'0.5.1'`
+
+---
+
+## اتصال به lobby-sdk
+
+بعد از `init()`:
+
+```ts
+import { PlatformSDK } from '@oyna360/game-sdk';
+import { PlatformLobby } from '@oyna360/lobby-sdk';
+
+const init = await PlatformSDK.init({ /* … */ });
+const lobby = await PlatformLobby.create({
+  canvas,
+  platformInit: init,
+  roomId: init.lobby!.roomId,
+  wsUrl: init.lobby!.wsUrl,
+});
+```
+
+`lobby.wsUrl` را هاردکد نکنید.
+
+---
+
+## لایسنس
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+import { SDK_VERSION, type PlatformInitMessage, type PlatformSdkInitOptions, type AchievementsResponse, type SdkInitPayload, type SdkSession, type SdkUser, type LeaderboardResponse, type SubmitScoreResponse, type UnlockAchievementResponse, type WalletBalanceResponse, type ConvertGemsResponse } from './types';
+export { SDK_VERSION };
+export type { SdkInitPayload, SdkLobbyAvatar, SdkSession, SdkUser, SdkGameInfo, PlatformInitMessage, PlatformSdkInitOptions, LeaderboardEntry, LeaderboardResponse, SubmitScoreResponse, AchievementItem, AchievementsResponse, UnlockAchievementResponse, WalletBalanceResponse, ConvertGemsResponse, } from './types';
+declare global {
+    interface Window {
+        __OYNA360_PLATFORM_INIT__?: PlatformInitMessage;
+        __OYNA360_DEV__?: {
+            platformUrl?: string;
+            platformWebUrl?: string;
+            gameSlug?: string;
+        };
+    }
+}
+/**
+ * Wait for platform init payload.
+ * - Production iframe: receives `platform:init` from parent.
+ * - Direct Development: Oyna360 authorize → one-time code → standard SdkInitPayload.
+ */
+export declare function init(options?: PlatformSdkInitOptions): Promise<SdkInitPayload>;
+export declare function getUser(): SdkUser | null;
+export declare function getSession(): SdkSession | null;
+export declare function getInitPayload(): SdkInitPayload | null;
+export declare function isReady(): boolean;
+/** Submit score (keeps best score per player). Requires active session. */
+export declare function submitScore(score: number): Promise<SubmitScoreResponse>;
+/** Fetch game leaderboard via platform bridge (iframe) or REST (Direct Dev). */
+export declare function getLeaderboard(limit?: number): Promise<LeaderboardResponse>;
+/** Unlock an achievement for the current player. Idempotent. */
+export declare function unlockAchievement(key: string): Promise<UnlockAchievementResponse>;
+/** List achievements with unlock status for the current player. */
+export declare function getAchievements(): Promise<AchievementsResponse>;
+/** Platform gem balance + coins-per-gem rate for this game. */
+export declare function getWallet(): Promise<WalletBalanceResponse>;
+/**
+ * Convert platform gems into in-game coins.
+ * Platform deducts gems; the game must credit `coinsReceived` to its own economy.
+ */
+export declare function convertGems(gems: number): Promise<ConvertGemsResponse>;
+export declare function endSession(): Promise<void>;
+export declare const PlatformSDK: {
+    version: string;
+    init: typeof init;
+    getUser: typeof getUser;
+    getSession: typeof getSession;
+    getInitPayload: typeof getInitPayload;
+    isReady: typeof isReady;
+    submitScore: typeof submitScore;
+    getLeaderboard: typeof getLeaderboard;
+    unlockAchievement: typeof unlockAchievement;
+    getAchievements: typeof getAchievements;
+    getWallet: typeof getWallet;
+    convertGems: typeof convertGems;
+    endSession: typeof endSession;
+};
+export default PlatformSDK;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,EACzB,KAAK,cAAc,EAEnB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,WAAW,EAAE,CAAC;AACvB,YAAY,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,yBAAyB,EACzB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AAQjB,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,yBAAyB,CAAC,EAAE,mBAAmB,CAAC;QAChD,eAAe,CAAC,EAAE;YAChB,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,cAAc,CAAC,EAAE,MAAM,CAAC;YACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;SACnB,CAAC;KACH;CACF;AA6aD;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,cAAc,CAAC,CAuDpF;AAED,wBAAgB,OAAO,IAAI,OAAO,GAAG,IAAI,CAExC;AAED,wBAAgB,UAAU,IAAI,UAAU,GAAG,IAAI,CAE9C;AAED,wBAAgB,cAAc,IAAI,cAAc,GAAG,IAAI,CAEtD;AAED,wBAAgB,OAAO,IAAI,OAAO,CAEjC;AAED,2EAA2E;AAC3E,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiB7E;AAED,gFAAgF;AAChF,wBAAsB,cAAc,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAa7E;AAED,gEAAgE;AAChE,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAiBvF;AAED,mEAAmE;AACnE,wBAAsB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAQrE;AAED,+DAA+D;AAC/D,wBAAsB,SAAS,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAQhE;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgB5E;AAED,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CA0BhD;AAED,eAAO,MAAM,WAAW;;;;;;;;;;;;;;CAcvB,CAAC;AAEF,eAAe,WAAW,CAAC"}