@oyna360/game-sdk 0.7.0 → 0.7.1

package/docs/06-leaderboard.md

@@ -1,19 +1,19 @@
-# لیدربورد — `getLeaderboard`
-
-```ts
-const board = await PlatformSDK.getLeaderboard(20);
-// { gameSlug, entries: [{ rank, score, achievedAt, user: { displayName, username, avatarUrl } }] }
-```
-
-- `limit` پیش‌فرض ۲۰
-- نیاز به `init()` دارد
-- **Production** و **Direct Dev** هر دو کار می‌کنند (iframe یا REST)
-
-```ts
-const { entries } = await PlatformSDK.getLeaderboard(10);
-for (const row of entries) {
-  console.log(row.rank, row.user.displayName, row.score);
-}
-```
-
-بعدی: [07-postmessage-protocol.md](./07-postmessage-protocol.md)
+# لیدربورد — `getLeaderboard`
+
+```ts
+const board = await PlatformSDK.getLeaderboard(20);
+// { gameSlug, entries: [{ rank, score, achievedAt, user: { displayName, username, avatarUrl } }] }
+```
+
+- `limit` پیش‌فرض ۲۰
+- نیاز به `init()` دارد
+- **Production** و **Direct Dev** هر دو کار می‌کنند (iframe یا REST)
+
+```ts
+const { entries } = await PlatformSDK.getLeaderboard(10);
+for (const row of entries) {
+  console.log(row.rank, row.user.displayName, row.score);
+}
+```
+
+بعدی: [07-postmessage-protocol.md](./07-postmessage-protocol.md)

package/docs/07-postmessage-protocol.md

@@ -43,3 +43,11 @@
 به‌جای parent، Authorize HTTP استفاده می‌شود؛ ولی **شکل نهایی Context همان `SdkInitPayload` است** تا lobby-sdk و کد بازی یکسان بمانند.
 
 بعدی: [08-wallet.md](./08-wallet.md)
+
+## Commerce 0.7
+
+Game → parent: `{type: 'platform:commerce:request', requestId, operation, args}`.
+Parent → game: `{type: 'platform:commerce:result', requestId, result?, error?}`.
+The top-level requestId correlates the RPC; args.requestId is the persisted business operation ID.
+Operations: products, purchase, purchaseStatus, receipts, inventory, consume, exchange, exchangeStatus.
+Only accept replies from the real parent and pinned platform origin. The parent binds every REST call to the authenticated launched game session.

package/docs/08-wallet.md

@@ -1,32 +1,65 @@
-# کیف‌پول جِم — `getWallet` / `convertGems`
+# کیف پول، خرید محصول و موجودی آیتم — نسخهٔ ۰٫۷٫۰
 
-جِم ارز پلتفرم است. تبدیل به «سکه داخل بازی» با نرخ `coinsPerGem` همان بازی انجام می‌شود.
+این نسخه علاوه بر `getWallet`، خرید مستقیم محصول، رسیدهای قابل بازیابی و موجودی/مصرف آیتم را در هر دو حالت iframe و Direct Development دارد.
+
+> ابتدا بک‌اند و پل والدِ سازگار با Commerce 0.7 را منتشر کنید. اضافه‌کردن SDK به‌تنهایی سرور قدیمی را ارتقا نمی‌دهد. سرور قدیمی ممکن است 404 یا timeout بدهد؛ در این حالت هیچ آیتم یا سکه‌ای به کاربر اعطا نکنید.
+
+## محصولات و خرید
 
 ```ts
-const wallet = await PlatformSDK.getWallet();
-// { gems, coinsPerGem, gameSlug }
+const { products } = await PlatformSDK.getProducts();
+// {itemId, title, priceGems, quantity, consumable}[] — قیمت فقط روی سرور تعیین می‌شود.
+const requestId = crypto.randomUUID();
+// قبل از ارسال، شناسه را کنار خرید در ذخیره‌سازی پایدارِ بازی نگه دارید.
+const receipt = await PlatformSDK.purchaseProduct(products[0].itemId, requestId);
+// {id, requestId, itemId, gemsSpent, gemsRemaining, quantity, consumable, gameSlug, createdAt, ...}
+```
 
-const result = await PlatformSDK.convertGems(5);
-// { gemsSpent, coinsReceived, coinsPerGem, gemsRemaining, gameSlug }
+تکرار **همان شناسه و محصول**، همان رسید را بدون کسر مجدد جم و بدون اعطای دوباره برمی‌گرداند. استفاده از همان شناسه برای محصول دیگر خطاست. برای خرید مستقل بعدی، شناسهٔ جدید بسازید. شناسه ۸ تا ۱۲۸ کاراکتر از حروف انگلیسی، عدد، `_` و `-` است.
+
+برای محصولات دائمی، خرید مجدد با شناسهٔ متفاوت رد می‌شود. محصول مصرفی می‌تواند چند بار و با شناسه‌های مستقل خریده شود.
+
+## بازیابی بعد از خطا، قطع اینترنت یا بسته‌شدن بازی
+
+```ts
+const status = await PlatformSDK.getPurchaseStatus(savedRequestId);
+if (status.status === 'COMPLETED') applyReceiptOnce(status.receipt.id, status.receipt);
+// NOT_FOUND یعنی هنوز رسید نهایی ثبت نشده؛ اثبات شکست پرداخت نیست.
+// اگر خرید هنوز لازم است، با همان requestId دوباره purchaseProduct را صدا بزنید.
+const page = await PlatformSDK.getPurchaseReceipts();
+const nextPage = page.next ? await PlatformSDK.getPurchaseReceipts(page.next) : null;
 ```
 
-## مسئولیت بازی
+رسیدها به همان **کاربر و بازی** محدودند و صفحه‌بندی ۱۰۰تایی دارند. `getPurchaseStatus` فقط ثبت نهایی (COMPLETED) یا نبود رسید نهایی (NOT_FOUND) را اعلام می‌کند؛ پرداخت بانکی یا صف خرید معلق نیست.
 
-پلتفرم جِم را کم می‌کند و `coinsReceived` را برمی‌گرداند.  
-**اعتبار سکه داخل اقتصاد خودتان** با شماست (در سرور/کلاینت بازی اعمال کنید).
+## موجودی و مصرف آیتم
 
-## نکات
+```ts
+const inventory = await PlatformSDK.getInventory();
+// {gameSlug, items: [{itemId, quantity, consumable}]}
+const useId = crypto.randomUUID(); // پیش از مصرف ذخیره شود
+const used = await PlatformSDK.consumeItem('potion', 1, useId);
+// {id, requestId, itemId, quantity, remaining, gameSlug}
+```
 
-- `gems` باید عدد صحیح مثبت باشد.
-- در **Production** و **Direct Dev** هر دو کار می‌کند (iframe یا REST با session token).
+مصرف در سرور اتمیک است؛ موجودی منفی نمی‌شود، آیتم دائمی مصرف نمی‌شود و تکرار یک مصرف با همان شناسه، دوباره کم نمی‌کند. برای بازیابی نتیجهٔ مصرف، همان `consumeItem` و همان شناسه را تکرار کنید. استفادهٔ مجدد شناسه با مقدار یا آیتم متفاوت خطاست.
+
+## تبدیل جم به سکهٔ اقتصاد خود بازی
 
 ```ts
-try {
-  const { coinsReceived } = await PlatformSDK.convertGems(amount);
-  await creditLocalCoins(coinsReceived);
-} catch (e) {
-  showError(e);
-}
+const wallet = await PlatformSDK.getWallet();
+const id = crypto.randomUUID(); // پیش از ارسال نگه دارید
+const result = await PlatformSDK.convertGems(5, id);
+// {id, requestId, gemsSpent, coinsReceived, coinsPerGem, gemsRemaining, gameSlug}
+const recovered = await PlatformSDK.getExchangeStatus(id);
 ```
 
-بعدی: [09-direct-development.md](./09-direct-development.md) · [10-achievements.md](./10-achievements.md)
+بک‌اند سازگار با این نسخه، تبدیل و نتیجه را در یک تراکنش با `(userId, gameId, requestId)` ذخیره می‌کند. تلاش مجدد کسر جدید ندارد و مبلغ ناسازگار خطا می‌دهد. **اعطای سکه در اقتصاد مستقل بازی همچنان مسئولیت سرور بازی است**؛ `result.id` را فقط یک بار اعمال کنید. رسید را از کاربر دیگر یا فقط از پیام دلخواه کلاینت قبول نکنید.
+
+اگر `requestId` را در خرید/مصرف/تبدیل ندهید، SDK برای همان فراخوانی یکی می‌سازد؛ برای بازیابی پس از بسته‌شدن بازی کافی نیست. در عملیات مهم همیشه شناسهٔ ذخیره‌شدهٔ خودتان را بدهید.
+
+## پیکربندی محصولات
+
+قیمت و مقدار در پلتفرم تعریف می‌شود؛ SDK قیمت دلخواه قبول نمی‌کند. پلتفرم مسیر ادمین محافظت‌شدهٔ `PUT /api/admin/games/:gameId/products/:itemId` دارد با بدنهٔ `{title, priceGems, quantity, consumable, active}`. این مسیر را از کلاینت بازی صدا نزنید و توکن ادمین را داخل بازی قرار ندهید.
+
+محصول دائمی باید `quantity: 1` داشته باشد. برای تغییر مصرفی/دائمی بودن، شناسهٔ آیتم جدید تعریف کنید. کاتالوگ قدیمی گانچیکو حفظ می‌شود، ولی بازی‌های دیگر باید محصولات خود را روی سرور تعریف کنند.

package/docs/12-commerce-release.md

@@ -0,0 +1,12 @@
+# Commerce 0.7 release
+
+- Package version, `SDK_VERSION` and `PlatformSDK.version` are all `0.7.0`.
+- New: `getProducts`, `purchaseProduct`, `getPurchaseStatus`, `getPurchaseReceipts`, `getInventory`, `consumeItem`, `getExchangeStatus`.
+- Commerce operations work via authenticated REST in Direct Development and trusted parent RPC in an iframe.
+- Business operation IDs are separate from transport correlation IDs, so concurrent retries do not mix their replies.
+- `convertGems` now uses the commerce route; it requires the matching platform backend and parent bridge. Deploy platform migration/API/web before upgrading games to this version.
+- Stable operation IDs must be persisted by the game before sending. Replay protection is provided by the matching backend's database transactions, not local SDK storage.
+- The platform owns item balances and consumption. External in-game coin credits/effects still require the game server to apply each receipt once.
+- GitHub source/dist updates do not publish a release to npm. Until npm is published by the owner, install the exact Git commit or a locally packed tarball.
+
+Run `npm run build`, then `npm test`. Tests cover both transports, operation IDs, input rejection, version alignment and forged-parent replies.

package/package.json

@@ -1,56 +1,57 @@
-{
-  "name": "@oyna360/game-sdk",
-  "version": "0.7.0",
-  "description": "oyna360 Game SDK — postMessage bridge, Developer Environment credentials, and Direct Development Mode.",
-  "license": "MIT",
-  "author": "oyna360",
-  "keywords": [
-    "oyna360",
-    "game-sdk",
-    "iframe",
-    "postmessage",
-    "leaderboard",
-    "achievements"
-  ],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build",
-    "typecheck": "tsc --noEmit",
-    "lint": "echo \"No lint configured for @oyna360/game-sdk\""
-  },
-  "devDependencies": {
-    "typescript": "^5.7.2"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mamadjavadrasti/oyna360-game-sdk.git"
-  },
-  "bugs": {
-    "url": "https://github.com/mamadjavadrasti/oyna360-game-sdk/issues"
-  },
-  "homepage": "https://github.com/mamadjavadrasti/oyna360-game-sdk#readme",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@oyna360/game-sdk",
+  "version": "0.7.1",
+  "description": "oyna360 Game SDK — postMessage bridge, Developer Environment credentials, and Direct Development Mode.",
+  "license": "MIT",
+  "author": "oyna360",
+  "keywords": [
+    "oyna360",
+    "game-sdk",
+    "iframe",
+    "postmessage",
+    "leaderboard",
+    "achievements"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"No lint configured for @oyna360/game-sdk\"",
+    "test": "node --test tests/*.cjs"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mamadjavadrasti/oyna360-game-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mamadjavadrasti/oyna360-game-sdk/issues"
+  },
+  "homepage": "https://github.com/mamadjavadrasti/oyna360-game-sdk#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}