@idosgames/core 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -14,6 +14,154 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-08-10
+
+Real-money payment support. Every configured price becomes a **`PriceOptions` dictionary**, a
+store SKU becomes one of the ways to pay, and the client now tells the server which platform it
+runs on. Breaking — see below.
+
+### Added
+
+- **`PriceOption` / `PriceOptions` (`zPriceOption`, `zPriceOptions`)** — the platform-wide price
+  standard. A `ResourceConsume` is charged as a whole ("and"); a price across platforms is a
+  choice ("or") — a store SKU on mobile, a token on web. The dictionary key is the `OptionID`,
+  and the server substitutes it when the field is empty.
+- **`ResourceEntryType.Purchase` + `ResourceEntry.ProductID`** — an entry that means "paid in a
+  store". `ProductID` addresses `Purchase.Products`, our stable id, not a per-store SKU.
+- **`PaymentProof` (`zPaymentProof`)** — the receipt attached to a request. Required exactly when
+  the chosen option holds a `Purchase` entry: the server never takes money itself, it verifies
+  what the store issued to this client.
+- **`client.purchase` (`PurchaseService`)** — `getDefinitions`, `getUserState`,
+  `validatePurchase`, `validatePurchasesBatch`. `Resources` is applied only when `Granted` is
+  true: `AlreadyProcessed` and `Restored` carry the same block, and crediting it would pay the
+  reward twice for one payment — which is exactly what a store's re-delivered receipt looks like.
+- **`client.checkout` (`CheckoutService`)** — `availableOptions`, `isAvailable`, `requirementOf`,
+  `storeProductOf`, `cryptoShortfallOf`. It deliberately buys nothing: the purchase belongs to the
+  module that owns the entity (`client.store.purchase`, `client.lootbox.open`, …), which is the
+  only place that knows count, target ids and the idempotency key.
+- **`ClientPlatform`** (`Unknown | Web | Android | Ios`) and `IDosGamesClientConfig.clientPlatform`.
+  Auto-detected by `detectClientPlatform()` and sent as **`X-IG-Platform`** on every request —
+  once, in the transport, because a service that forgot to pass it would silently get a different
+  price list. Detection is conservative: a browser is `Web` even on a phone, only a real native
+  wrapper (Capacitor / Cordova) counts as `Android`/`Ios`, and no `navigator` at all is `Unknown`
+  rather than `Web`.
+- `SegmentGate.Platforms` — gate any definition on the client platform.
+- Optional **`selectedOptionID`** on every call that charges a configured price —
+  `store.purchase`, `lootbox.open`, `craft.craft`, `premium.purchaseItemOrCurrency`,
+  `character.unlockCharacter`, `collection.openPack`, `dealOffer.executeNode`,
+  `timedBoost.activate`, `item.upgradeLevel`, `coopEvent.spin`, `gameLoop.boardSpecialChoose`,
+  `match.createMatch`, `marketplace.createListing` / `createAuction`. Omitting it keeps
+  single-price entities working with no client change: the server takes the first option
+  available on this platform.
+- Optional **`payment`** (a `PaymentProof`) on the calls the server can settle against a store
+  receipt: `store.purchase`, `lootbox.open`, `character.unlockCharacter`, `collection.openPack`,
+  `dealOffer.executeNode`, `timedBoost.activate`. The rest deliberately have none — an upgrade
+  priced by a level formula, a per-fact coop spin, a refundable listing fee and a P2P match stake
+  cannot be one store SKU, and the server rejects a `Purchase` entry in those places.
+
+### Changed
+
+- **Every price field is now `PriceOptions`.** `StoreOfferDefinition.Cost`,
+  `CraftDefinition.RequiredResources`, `LootboxDefinition.PriceOptions` (was a list of
+  `LootboxPriceOption`), `PremiumDefinition.PriceOptions`, `CollectionPackDefinition.Cost`,
+  `CharacterDefinition.Unlock.Cost` / stat & level `BaseCostResource` / `UpgradeCost`,
+  `ItemUpgrade.BaseCostResource`, `TimedBoostDefinition.ActivationCost`,
+  `CoopEventBuildObjects.SpinCost`, `GameLoop` special-mode choice `EntryCost`,
+  `DealOfferPurchaseAction.DirectCost`, `MatchCreationSettings.Cost`,
+  `MarketplaceListingSettings.ListingFee` — all replaced by a `PriceOptions` dictionary.
+- `lootbox.open`'s `selectedOptionID` is a **string** (was `number`) and is now optional.
+- Prices come back **already filtered by the request's platform**, and the charge re-checks it.
+  The client renders what the server gave; a hidden option cannot be paid anyway.
+
+### Removed
+
+- **`ResourceEntryType.UsdCent`** — it was declared but never worked (any operation with it
+  failed inside the inventory layer), so a price in real money looked configurable while the
+  entity was impossible to buy. `Purchase` replaces it.
+
+### Migration
+
+Read a price through `client.checkout.availableOptions(entity.PriceOptions)` instead of the old
+single cost field, and pass the chosen `OptionID` to the module's buying call. A price paid in a
+store additionally needs a `PaymentProof` — buy in the store first, then hand the receipt to the
+same call. Nothing else changes for entities that keep a single price.
+
+## [0.6.0] - 2026-08-09
+
+### Added
+
+- **`client.tutorial` (`TutorialService`)** — onboarding flows: `getTutorialDefinitions`,
+  `getUserTutorialState`, `startFlow`, `reportStepShown`, `completeStep`,
+  `completeStepsBatch`, `skipStep`, `skipFlow`, `claimFlowReward`, `resetFlow`. Definitions
+  are cached like the rest of the title config.
+- **Tutorial progress rides on every response.** A tutorial step is usually closed by an
+  ordinary game action (a purchase, a dice roll), not by a tutorial call — so the backend puts
+  an optional `TutorialProgress` block into the envelope of **any** response, the transport
+  lifts it out, and `UserData` merges it into the state. Subscribe to `tutorial:systemProgress`
+  instead of polling `getUserTutorialState`: the state is already fresh after any request, and
+  polling also skews the `ReportStepShown` funnel.
+- `SegmentGate.Tutorial` (`TutorialGateCondition` / `TutorialGateMode`) — gate any module's
+  definitions on the player's onboarding progress.
+- **`client.localization` (`LocalizationService`)** — `t(key, params)`, `has`, `locale`,
+  `fallbackLocale`, `locales`, `setLocale`, `getManifest`. Resolution is
+  **own table → fallback table → the key itself**, so a title whose config holds literal
+  display names ("Iron Sword") keeps working without migration: the literal is a key with no
+  translation. Plural forms come from `Intl.PluralRules` (suffixes `.one/.few/.many/.other`).
+- Translation tables arrive **with the player state** — no separate load. `UserService` sends
+  the locale and the versions of the tables it already has and resolves what comes back
+  through the same source chain as the title config (storage → CDN → endpoint → stale copy),
+  with one deliberate difference: a failure here does **not** fail the login. No config means
+  nothing to play; no translations means the UI shows keys.
+- `settings.locale` (`SettingsInput.locale`) — the starting locale, defaulting to the device
+  language. It is a **wish**, not a fact: the server folds it to what the title is actually
+  translated into (`pt-BR` → `pt` → `en`), and the answer is `client.localization.locale`.
+- `TitlePublicConfigurationModel.Localization` — locale settings only. The tables are
+  delivered separately, one file per locale.
+- `localization:changed` event (login, `setLocale`, new tables). `t()` is synchronous, so
+  already-rendered labels need this signal to repaint.
+- `PostOptions.throttleKey` — override the throttle / in-flight-dedup key when one route
+  serves genuinely different requests back to back. Added for the localization tables: own and
+  fallback both go through `Localization/GetLocalizationTable`, and under the default key
+  (the endpoint) the second call would be dropped as a duplicate — the fallback table would
+  never arrive, silently, and only for players whose language is partially translated. The
+  throttle window still applies, just per key.
+- **Batch claims** — `season.claimTierRewardsBatch(seasonChainID, tierNumbers)` and
+  `referral.claimInviteRewardsBatch(inviteRewardIDs)`. Season tiers in particular are reached
+  in batches: one token grant can raise a player through several at once. The merged
+  `Resources` is applied **once** from the top level; per-item `Data.Resources` is null by
+  contract so summing both cannot double count.
+- **Multi-open ceilings** — `collection.openPack(collectionID, packTypeID, count?)`,
+  `collection.openCollectionChest(collectionID, chestID, count?)` and
+  `coopEvent.spin(chainID, groupID, count?)` open/spin `count` times in one atomic operation
+  (`count` defaults to 1, so existing calls are unaffected). Each roll sees the state left by
+  the previous one, so a repeat drop is correctly counted as a duplicate. The count is clamped
+  server-side; responses report what actually happened (`OpenedCount` + per-item `Packs` /
+  `Chests`, `RequestedSpins` / `SpinsUsed` / `Sectors`). Only spins that happen are charged —
+  a run stops at the spin that completes the object.
+- Config for those ceilings: `LootboxDefinitions.Settings` (`LootboxGlobalSettings`) and
+  `LootboxDefinition.MaxOpenCount`, `CollectionDefinitions.Settings`
+  (`CollectionGlobalSettings`), `CollectionPackTypeDefinition.MaxOpenCount`,
+  `CollectionChestDefinition.MaxOpenCount`, `CoopBuildObjectsDefinition.MaxSpinsPerCall`.
+- `FriendActionResponse.Target` (the other side's public profile) and `.Counters`
+  (`SocialCounters`) — a new friend can be shown without a second `getFriendsList()`.
+- New events: `tutorial:definitionsLoaded` / `:userStateLoaded` / `:flowStarted` /
+  `:flowSkipped` / `:flowReset` / `:stepChanged` / `:stepsCompletedBatch` / `:rewardClaimed` /
+  `:systemProgress`, `localization:changed`, `season:tierRewardsBatchClaimed`,
+  `referral:inviteRewardsBatchClaimed`, `user:tutorialUpdated`.
+
+### Notes
+
+- Everything here is additive: the new `count` parameters default to `1`, the new response
+  fields are optional, and no existing signature changed.
+- `TutorialStepPolicy.TimeoutSeconds` is carried in the schema but **not applied** — neither
+  the backend (it has no "N seconds passed" moment) nor `core` (it renders no UI) can enforce
+  it. Whoever draws the tutorial implements it, and only for `ClientAck` steps; on a step
+  waiting for a game event the backend rejects `completeStep`.
+
+## [0.5.1] - 2026-08-05
+
+Version-only republish of 0.5.0 — no source changes.
+
 ## [0.5.0] - 2026-08-04
 
 ### Added