@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/implement-in-app-purchases/references/migration-v4-to-v5.md

@@ -0,0 +1,46 @@
+# Unity IAP v4 to v5 Migration Guide
+
+## Table of Contents
+
+- [Trigger Phrases](#trigger-phrases)
+- [Procedure](#procedure)
+- [Migration gotchas](#migration-gotchas)
+
+## Trigger Phrases
+
+- "Migrate from Unity IAP v4 to v5"
+- "Upgrade Unity IAP to v5"
+- "Update IAP from v4"
+- "Migrate IStoreListener to StoreController"
+- "Replace ConfigurationBuilder with v5 IAP"
+- "Update UnityPurchasing.Initialize to v5"
+
+## Procedure
+
+Unity IAP v5 replaces the listener-based `IStoreListener` pattern with `StoreController` events, so every IAP call site changes.
+
+1. Read [Upgrade from IAP v4 to v5](https://docs.unity.com/en-us/iap/upgrade-to-iap-v5.md) in full before changing code. It holds the official v4-to-v5 mapping for initialization, the purchase flow, `ConfigurationBuilder`, entitlement checks, `SubscriptionManager`, receipt validation, platform extensions and Codeless IAP. Reread the matching section whenever a migrated call fails to compile.
+2. List every v4 call site in the project (`IStoreListener`, `IDetailedStoreListener`, `UnityPurchasing.Initialize`, `ConfigurationBuilder`, `GetExtension<`, `SubscriptionManager`, `product.receipt`, `product.hasReceipt`).
+3. Migrate each call site using the docs mapping, then check it against the [gotchas](#migration-gotchas) below, because they are the mistakes agents make most often in this migration.
+4. For a type or member the upgrade page doesn't cover, look it up in the package's `xrefmap.yml` for the installed version.
+
+## Migration gotchas
+
+- **Subscribe before `Connect()`.** Pending purchases from a previous session can fire as soon as the store connects. A handler registered later misses them. Initialize in `Awake()` so IAP is ready before other `Start()` methods.
+- **`ProcessPurchase` logic goes in two places.** Put it in `OnPurchasePending` (new purchases) and in `OnPurchasesFetched` (restored and existing purchases), because v4 delivered both through `ProcessPurchase`.
+- **Returning `PurchaseProcessingResult.Pending`** becomes: keep the `PendingOrder` and don't call `ConfirmPurchase` until ready. There is no equivalent of returning `Complete`.
+- **`ConfirmPurchase` takes the `PendingOrder`, not the `Product`.**
+- **`OnPurchaseConfirmed` receives the `Order` base type.** Pattern-match `ConfirmedOrder` against `FailedOrder`, because confirmation can fail.
+- **Ownership checks.** Replace `product.hasReceipt` and `product.receipt == null` with `store.CheckEntitlement(product)` and `OnCheckEntitlement`, because it handles refunds and expiry across platforms. Use a manual `bool` flag only if the user's design needs it.
+- **Subscribe to every failure event and to `OnPurchaseDeferred`.** Missing failure events cause runtime warnings, and missing `OnPurchaseDeferred` silently drops Ask-to-Buy and Google deferred purchases.
+- **Failure property names.** `StoreConnectionFailureDescription` has `.Message`, not `.reason`. `ProductFetchFailed` has `.FailureReason`, not `.Message`.
+- **Platform config moves after `Connect()`.** `SetAppAccountToken`, `SetObfuscatedAccountId`, `SetObfuscatedProfileId` and `canMakePayments` used to be set on `ConfigurationBuilder` before initialization. In v5 they are on the extended services, which exist only after `await store.Connect()`.
+- **`SetApplicationUsername(hash)` becomes `SetAppAccountToken(Guid)`.** It takes a `Guid` that identifies the user's account, not a hash.
+- **Platform events are on the extended services, not `StoreController`.** `OnPromotionalPurchaseIntercepted` and `OnEntitlementRevoked` are on `AppleStoreExtendedPurchaseService`. `OnDeferredPaymentUntilRenewalDate` is on `GooglePlayStoreExtendedPurchaseService` and receives a `DeferredPaymentUntilRenewalDateOrder`, not a `Product`. Null-check the service with `if`, because `?.` doesn't work with `+=`.
+- **`OnEntitlementRevoked` receives one product ID `string`**, not `List<Product>`.
+- **`UpgradeDowngradeSubscription` takes `Order` and `Product` objects** instead of string IDs, and a `GooglePlayReplacementMode`, not the deprecated `GooglePlayProrationMode`.
+- **Apple promotion and intro-price APIs moved, not removed.** `GetIntroductoryPriceDictionary`, `GetProductDetails` and the `StorePromotion` methods are on `AppleStoreExtendedProductService`. `AppleProductMetadata` has no intro-price properties, so use the `SubscriptionInfo` methods instead.
+- **`SubscriptionManager` is replaced** by `order.Info.PurchasedProductInfo`. Subscription info is NOT on `CartItem`. Methods are PascalCase (`IsSubscribed()`) and still return `Result`, so compare with `== Result.True`, not `?? false`.
+- **Receipt validation.** Under StoreKit 2, Apple local validation returns an empty array. Use the Google-only `CrossPlatformValidator(GooglePlayTangle.Data(), Application.identifier)` constructor, and send `order.Info.Apple?.jwsRepresentation` to a server for Apple.
+- **Don't recommend `ProcessPendingOrdersOnPurchasesFetched(false)`.** It restores v4 behavior but loses the v5 re-delivery of unconfirmed purchases.
+- **Codeless:** `CodelessIAPStoreListener.initializationComplete` becomes `CodelessIAPStoreListener.IsInitialized()`.

package/skills/implement-in-app-purchases/references/path-add-iap-to-new-project.md

@@ -0,0 +1,197 @@
+# Add Unity IAP 5 to a Project With No IAP
+
+## Table of Contents
+
+- [Step 1 — Package Installation](#step-1--package-installation)
+- [Step 2 — Project Scan](#step-2--project-scan)
+- [Step 3 — Product Discovery](#step-3--product-discovery)
+- [Step 4 — IAPManager Architecture](#step-4--iapmanager-architecture)
+- [Step 5 — Purchase Handling Contract](#step-5--purchase-handling-contract)
+- [Step 6 — Product Type Behavior Rules](#step-6--product-type-behavior-rules)
+- [Step 7 — Cloud Save Integration](#step-7--cloud-save-integration)
+- [Step 8 — UI Integration](#step-8--ui-integration)
+- [Step 9 — Verification Report](#step-9--verification-report)
+
+Use this reference when the project has no existing in-app purchase implementation and needs Unity IAP 5 added from scratch.
+
+## Step 1 — Package Installation
+
+Check `Packages/manifest.json` for `com.unity.purchasing`:
+
+- **If absent:** Install via **Window > Package Manager > Unity Registry > In App Purchasing**. Do not edit `manifest.json` directly unless the user explicitly allows it. Confirm installation before proceeding.
+- **If present but below v5.0:** Instruct the user to upgrade via Package Manager to the latest stable v5 release. Do not proceed until the upgrade is confirmed.
+- **If v5.0+ is already present:** Note the exact version and proceed.
+
+Always use the latest stable v5 release unless the user specifies a version. Never downgrade an existing package.
+
+## Step 2 — Project Scan
+
+### 2a — Code scan
+
+Search `Assets/**/*.cs` for any existing IAP signals:
+
+```
+ProductType|ProductDefinition|StoreController|IAPButton|CodelessIAP
+ProcessPurchase|PendingOrder|DeferredOrder|ConfirmPurchase|FetchPurchases
+IStoreListener|UnityPurchasing\.Initialize|ConfigurationBuilder
+```
+
+### 2b — Inventory and economy scan
+
+Search `Assets/**/*.cs` for terms that indicate what needs to be credited after purchase:
+
+```
+\bcoins\b|\bgems\b|\blives\b|\binventory\b|\bcurrency\b
+PlayerData|SaveAsync|CloudSave|SaveDataAsync|SaveGame
+Economy
+```
+
+### 2c — Shop UI scan
+
+Search `Assets/**/*.unity`, `*.prefab`, `*.asset` for shop-related GameObjects and scripts:
+```
+Shop|Store|Purchase|Buy|IAP|Product|Monetiz
+```
+
+Collect: scene names, prefab paths, button component names, and any serialized product ID strings.
+
+## Step 3 — Product Discovery
+
+### If product definitions are already found (from Step 2a/2b/2c)
+
+Use them. Confirm types with the user if ambiguous.
+
+### If no product definitions exist
+
+**Stop and ask:**
+
+> "Please provide the first IAP product ID and type — for example `com.mygame.coins100` as Consumable — and tell me which inventory field, currency, or item should be credited after purchase."
+
+- If the user provides only a product ID with no type, **default to Consumable** but state the assumption explicitly before proceeding.
+- Collect all products before writing any code. For each product record: `productId`, `ProductType`, reward target (field name / method name / amount).
+
+## Step 4 — IAPManager Architecture
+
+### Match the project's existing patterns
+
+Before generating code:
+- Check whether the project uses MonoBehaviour singletons, ScriptableObject services, or dependency injection.
+- Check the namespace convention used in `Assets/Scripts/`.
+- Prefer the pattern already in use rather than introducing a new one.
+
+### IAPManager responsibilities
+
+Create a single `IAPManager` (MonoBehaviour singleton or service, matching project pattern) that:
+
+- Holds the `StoreController` instance.
+- Exposes `Buy(string productId)`.
+- Exposes `RestorePurchases()` — **only** if the product list contains `NonConsumable` or `Subscription` types.
+- Fires UI-friendly events or callbacks for: `OnInitialized`, `OnProductsLoaded`, `OnPurchaseSuccess`, `OnPurchaseFailed`, `OnPurchaseDeferred`.
+- Initializes once in `Awake()` — see **Core rules > Initialization** in the parent skill file for the event subscription and `Connect()` ordering rules.
+- Registers all products from a single authoritative product list (not scattered across UI handlers).
+
+### Product catalog
+
+Define products in one place, never inside button click handlers, so IDs can't drift between the shop UI and the store. By default, use a static class that holds the product ID constants and builds the `List<ProductDefinition>` passed to `FetchProducts()`. Use a `ScriptableObject` instead only if the project already configures game data through ScriptableObjects, or the user wants designers to edit products in the Inspector. Wire button click handlers to `IAPManager.Buy(productId)` using those constants, not hardcoded strings.
+
+## Step 5 — Purchase Handling Contract
+
+For API mechanics (two-step flow, event names, `ConfirmPurchase` signature) read the [Purchases](https://docs.unity.com/en-us/iap/purchases.md) page and **Core rules > Purchases** in the parent skill file. This section covers only the grant-and-save contract that is specific to this path.
+
+### PendingOrder — the save-before-confirm rule
+
+```
+OnPurchasePending fires
+  → grant reward to inventory / currency / entitlement
+  → save player data (see Cloud Save Integration below)
+  → ONLY IF save succeeds: call ConfirmPurchase(pendingOrder)
+  → IF save fails: do NOT confirm — store will re-deliver on next launch
+```
+
+Never call `ConfirmPurchase` before the save completes. An unconfirmed purchase is safe — it re-delivers. A confirmed purchase that was never saved is a lost reward.
+
+### Duplicate grant prevention
+
+`OnPurchasePending` may fire more than once for the same purchase (app restart before confirmation). Track processed order IDs (e.g., in Cloud Save or a local ledger) and skip grant if the order ID was already processed.
+
+### DeferredOrder
+
+Do not grant anything. Fire `OnPurchaseDeferred` event to update UI ("Purchase pending approval"). Wait for `OnPurchasePending` when the purchase is approved.
+
+### FailedOrder
+
+Do not grant anything. Fire `OnPurchaseFailed` with the reason. See **Core rules > Compile errors** in the parent skill file for the correct property names per type.
+
+## Step 6 — Product Type Behavior Rules
+
+### Consumable
+
+- Credit inventory or currency after purchase.
+- Persist the credited state in save data before confirming.
+- **Do not restore** old consumable orders — confirmed consumables are not returned by `FetchPurchases` and must not be re-granted.
+- Track consumable grants yourself (order ID ledger in Cloud Save or local save).
+
+### NonConsumable
+
+- Unlock a durable entitlement (feature flag, item ownership).
+- Include `RestorePurchases()` — required on iOS, good practice on Android.
+- Re-apply the entitlement on app startup: call `store.FetchPurchases()` and re-check ownership in `OnPurchasesFetched`, or use `store.CheckEntitlement(product)`. See **Core rules > Ownership and subscriptions** in the parent skill file.
+
+### Subscription
+
+- Restore or check subscription state on app startup, not only at purchase time. Subscriptions can expire or be cancelled externally.
+- Use `store.CheckEntitlement(product)` or inspect `OnPurchasesFetched` results to update active/expired/unknown state.
+- See **Core rules > Ownership and subscriptions** in the parent skill file for the correct access path (`order.Info.PurchasedProductInfo`, `IsSubscribed() == Result.True`).
+
+## Step 7 — Cloud Save Integration
+
+### Detect the existing save system first
+
+Search for any of these patterns before writing save code:
+
+```
+\.SaveAsync\(\)|CloudSaveService\.Instance
+SaveGame\(|SaveDataAsync\(|PlayerPrefs\.SetInt|JsonUtility\.ToJson|JsonConvert\.Serialize
+```
+
+### Rules
+
+- **Use the existing save abstraction** — do not create a new save system. If the project has more than one, use the one that already stores the currency or inventory the purchase credits, so the grant and the balance are saved together.
+- If no save system exists, use `PlayerPrefs` as the fallback, because it needs no new package or backend, and list it as a follow-up in the report, since `PlayerPrefs` is local to the device and not safe against tampering.
+- Save **must complete before `ConfirmPurchase`** is called (see Step 5).
+
+## Step 8 — UI Integration
+
+### Wiring
+
+- Wire existing shop buttons to `IAPManager.Buy(productId)` — do not embed product IDs in button click handlers directly.
+- Subscribe to `IAPManager` events in the shop UI script to drive state changes.
+
+### States to handle in UI
+
+| State | Trigger | UI action |
+|---|---|---|
+| Initializing | Before `OnInitialized` | Disable buy buttons or show spinner |
+| Products loaded | `OnProductsLoaded` | Display localized price from `product.metadata.localizedPriceString` |
+| Product unavailable | Product missing from `OnProductsFetched` result | Hide or grey out the button |
+| Purchase pending | `PurchaseProduct()` called | Disable button, show loading state |
+| Purchase deferred | `OnPurchaseDeferred` | Show "pending approval" message |
+| Purchase success | `OnPurchaseSuccess` | Show confirmation, update inventory display |
+| Purchase failed | `OnPurchaseFailed` | Show error message, re-enable button |
+
+### Restore button
+
+Add a "Restore Purchases" button **only** if the product list contains `NonConsumable` or `Subscription` products. Required on iOS. Wire to `IAPManager.RestorePurchases()`.
+
+## Step 9 — Verification Report
+
+After applying changes, produce a report with these sections:
+
+1. **Files changed** — list with nature of each change
+2. **Product IDs and types** — final catalog
+3. **Reward mapping** — product ID → field/method credited
+4. **Save behavior** — which save method is called, when
+5. **Restore behavior** — which products are restorable, how
+6. **Pending / deferred handling** — confirmation of save-before-confirm and deferred UI
+7. **Duplicate grant prevention** — how order IDs are tracked
+8. **Manual steps still required** — Unity Editor steps (Receipt Validation Obfuscator if using local Google Play validation), App Store Connect / Play Console product setup, sandbox testing accounts

package/skills/implement-in-app-purchases/references/path-convert-native-google-billing.md

@@ -0,0 +1,302 @@
+# Convert Native Google Billing to Unity IAP 5
+
+Links to other reference files point to files in this `references/` folder. Any other relative paths resolve to the skill directory.
+
+## Table of Contents
+
+- [Trigger Phrases](#trigger-phrases)
+- [Important Constraints](#important-constraints)
+- [Step 1 — Pre-Conversion Scan](#step-1--pre-conversion-scan)
+- [Step 2 — Product Classification](#step-2--product-classification)
+- [Step 3 — Migration Report (produce before any edits)](#step-3--migration-report-produce-before-any-edits)
+- [Step 4 — Blocker Detection](#step-4--blocker-detection)
+- [Step 5 — Target Architecture](#step-5--target-architecture)
+- [Step 6 — Migration Phases](#step-6--migration-phases)
+- [Step 7 — Behavior Change Rules](#step-7--behavior-change-rules)
+- [Step 8 — Native → Unity IAP Concept Mapping](#step-8--native--unity-iap-concept-mapping)
+- [Step 9 — Rollback Plan](#step-9--rollback-plan)
+- [Step 10 — Test Checklist](#step-10--test-checklist)
+- [Step 11 — Questions to Ask (only when required)](#step-11--questions-to-ask-only-when-required)
+
+Use this reference when the project uses C# → Java/Kotlin AndroidJavaObject calls to Google Play BillingClient and needs to be migrated to `com.unity.purchasing`. Always install the latest stable version.
+
+## Trigger Phrases
+
+- "Convert native Google Billing to the latest Unity IAP"
+- "Migrate BillingClient integration to Unity IAP"
+- "Replace AndroidJavaObject Google billing bridge with Unity IAP"
+- "Upgrade custom Google Play Billing to the latest stable version of com.unity.purchasing"
+- "Remove native BillingClient and use Unity IAP"
+
+## Important Constraints
+
+- **Do not delete existing native billing files unless explicitly requested.** Always preserve with `#if !USE_UNITY_IAP_V5` guards.
+- **Create the new Unity IAP adapter first**, then mark the old native adapter as deprecated.
+- **Preserve public game-facing APIs** via a compatibility facade so gameplay code does not need large rewrites.
+- **Do not change product IDs.**
+- **Do not change backend validation endpoints** unless the receipt format change makes it unavoidable — document any backend change required.
+- **Do not grant purchases on the client** if the existing project uses server-side validation.
+- **Do not assume all products are consumables.** Detect and classify each product.
+- **Do not assume subscriptions are simple.** Detect base plans, offer tokens, pricing phases, and `SubscriptionOfferDetails`. If found, surface as a migration blocker and let the user choose a path (see Subscription Blocker Options below).
+- **If the project contains RevenueCat, Adapty, or Essential Kit**, stop and notify the user — this skill does not support converting those packages.
+- **If Google-specific features are not cleanly expressible in Unity IAP**, report them as migration blockers rather than silently removing them.
+
+## Step 1 — Pre-Conversion Scan
+
+Scan before making any changes. Do not edit files until the migration report is accepted.
+
+### 1a — Unity C# Bridge Patterns
+
+Search `Assets/**/*.cs`:
+
+```
+AndroidJavaObject|AndroidJavaClass|UnityPlayer\.currentActivity
+UnitySendMessage
+GoogleBilling|BillingManager|BillingClient|BillingBridge|AndroidBillingBridge|PlayBilling
+purchaseToken|originalJson|signature|productId|orderId
+\backnowledge\b|\bconsume\b
+restore.?purchases|query.?products|query.?purchases
+subscription.?status|receipt.?valid|entitlement.?grant
+```
+
+### 1b — Android Java/Kotlin Patterns
+
+Search `Assets/Plugins/Android/**/*.java`, `*.kt`:
+
+```
+com\.android\.billingclient\.api\.BillingClient
+PurchasesUpdatedListener|BillingClientStateListener
+ProductDetails|ProductDetails\.SubscriptionOfferDetails
+QueryProductDetailsParams|BillingFlowParams
+AcknowledgePurchaseParams|ConsumeParams|QueryPurchasesParams
+launchBillingFlow|acknowledgePurchase|consumeAsync
+queryProductDetailsAsync|queryPurchasesAsync|enablePendingPurchases
+offerToken|basePlanId|offerId|pricingPhases
+```
+
+### 1c — Gradle / Manifest Patterns
+
+Search `mainTemplate.gradle`, `launcherTemplate.gradle`, `baseProjectTemplate.gradle`, `AndroidManifest.xml`:
+
+```
+com\.android\.billingclient:billing
+com\.android\.billingclient:billing-ktx
+```
+
+Also list all `.jar`/`.aar` files under `Assets/Plugins/Android/` — these may contain pre-compiled billing code.
+
+### 1d — Scene / Prefab / Asset Scan
+
+Search `.unity`, `.prefab`, `.asset` files for references to billing-related MonoBehaviour names found in 1a.
+
+## Step 2 — Product Classification
+
+Classify every detected product into one of: **Consumable**, **NonConsumable**, **Subscription**, **Unknown**.
+
+Infer from (in priority order):
+1. `BillingClient.ProductType.INAPP` (consumable or non-consumable) / `BillingClient.ProductType.SUBS`
+2. `consumeAsync` calls → Consumable; `acknowledgePurchase` without consume → NonConsumable
+3. Product ID naming conventions (e.g., `coins`, `gems`, `pack` → Consumable; `remove_ads`, `unlock` → NonConsumable; `monthly`, `annual`, `sub` → Subscription)
+4. Entitlement / backend grant code
+5. Comments or config files
+
+If type cannot be confidently inferred, mark as **Unknown** and add to the blocker question list.
+
+## Step 3 — Migration Report (produce before any edits)
+
+Generate all 18 sections. Do not skip any.
+
+1. **Current native billing architecture** — describe the bridge pattern (C# wrapper → JNI → BillingClient)
+2. **Files using native Google Billing** — full list with role of each file
+3. **Product catalog discovered** — all product IDs found
+4. **Product type mapping** — inferred type + confidence + source of inference for each product
+5. **Purchase flow mapping** — native → Unity IAP step-by-step
+6. **Restore purchase flow mapping** — `queryPurchasesAsync` → `FetchPurchases` + `RestoreTransactions`
+7. **Backend validation mapping** — what data the old flow sent (`purchaseToken`, `originalJson`, `signature`, `packageName`) vs what Unity IAP provides (`order.Info.Receipt`, `order.Info.Apple?.jwsRepresentation`)
+8. **Consumable consume behavior mapping** — native `consumeAsync` → Unity IAP `ConfirmPurchase` (only after grant)
+9. **Non-consumable acknowledgement behavior mapping** — native `acknowledgePurchase` → Unity IAP `ConfirmPurchase` (only after grant)
+10. **Subscription behavior mapping** — detected subscription products, restore path, renewal handling
+11. **Google-specific features detected** — list each (see Blocker Detection below)
+12. **Unity IAP 5.x migration blockers** — features that cannot be cleanly mapped
+13. **Proposed new Unity IAP architecture** — new files and their roles
+14. **Code files to create** — with paths
+15. **Code files to modify** — with nature of each change
+16. **Manual Play Console checks** — product IDs, base plan compatibility, billing permissions
+17. **Test plan** — from the checklist in this document
+18. **Rollback plan** — from the rollback plan section in this document
+
+## Step 4 — Blocker Detection
+
+Report these as migration blockers if detected. Do not silently remove them.
+
+| Feature | Detection Signal | Blocker Level |
+|---|---|---|
+| Multiple subscription base plans | `basePlanId` usage, multiple `SubscriptionOfferDetails` per product | **Hard** — ask user to choose option A/B/C (see below) |
+| Explicit offer token selection | `offerToken` set on `BillingFlowParams` | **Hard** |
+| Introductory offer selection by `offerId` | `offerId` in offer params | **Hard** |
+| Offer tags | `offerTags` access on `SubscriptionOfferDetails` | **Soft** — document loss |
+| Pricing phase inspection | `pricingPhases` / `PricingPhase` fields read | **Soft** — document loss |
+| Multi-quantity purchases | `quantity` > 1 in `BillingFlowParams` | **Hard** |
+| Alternative billing / external offers | `setExternalOfferToken` or alternative billing config | **Hard** |
+| Personalized price disclosure | `setIsPersonalizedPrice(true)` | **Hard** |
+| Obfuscated account / profile IDs | `setObfuscatedAccountId`, `setObfuscatedProfileId` | **Soft** — Unity IAP exposes `SetObfuscatedAccountId/ProfileId` post-`Connect()` on `GooglePlayStoreExtendedService` |
+| Custom `BillingFlowParams` fields | Any `BillingFlowParams.Builder` method not listed above | **Soft** — document loss |
+| Direct `ProductDetails` metadata | Reading `ProductDetails` fields not available on `Product.metadata` | **Soft** — document loss |
+
+### Subscription Blocker Options (present to user when hard subscription blockers found)
+
+**A mixed Unity IAP + native BillingClient architecture is not recommended and must not be offered as an option.** Both systems compete for the same `PurchasesUpdatedListener` slot on the device — only one receives purchase callbacks, the other silently drops purchases. This risks lost purchases, double grants, and unacknowledged tokens. If the user asks about a mixed approach, explain this risk and redirect to Option A or B.
+
+**Option A — Simplify Play Console setup for Unity IAP compatibility**
+Remove extra base plans/offers in Play Console so one product has one base plan. Unity IAP then handles all products including subscriptions. This is the recommended path — single system, no coexistence risk.
+
+**Option B — Stay on native Google Billing for all products**
+Do not migrate at this time. Keep the native BillingClient implementation as-is until the Play Console subscription configuration can be simplified or Unity IAP exposes the required subscription features. Stop the conversion and document the blocker and this decision in `IapMigrationNotes.md`.
+
+## Step 5 — Target Architecture
+
+Create under `Assets/Scripts/IAP/`:
+
+| File | Purpose |
+|---|---|
+| `IStorePurchaseService.cs` | Game-facing interface (stable public API) |
+| `UnityIapStorePurchaseService.cs` | Unity IAP 5.x implementation |
+| `ProductCatalogDefinition.cs` | ScriptableObject or plain class holding all `ProductDefinitionEntry` |
+| `ProductDefinitionEntry.cs` | Per-product data: ID, type, store-specific IDs |
+| `PurchaseEntitlementMapper.cs` | Maps Unity IAP order data → game grant calls |
+| `PurchaseValidationRequest.cs` | DTO sent to backend |
+| `PurchaseValidationResult.cs` | DTO received from backend |
+| `PurchaseRestoreResult.cs` | Result of restore operation |
+| `LegacyGoogleBillingAdapterDeprecated.cs` | Compatibility facade (only if game code calls old billing API) |
+| `IapMigrationNotes.md` | Human-readable notes on what changed, blockers found, manual steps |
+
+### Game-Facing Interface (preserve or adapt from existing API surface)
+
+```csharp
+public interface IStorePurchaseService
+{
+    Task InitializeAsync();
+    Task FetchProductsAsync();
+    IReadOnlyList<StoreProductInfo> GetProducts();
+    Task PurchaseAsync(string productId);
+    Task RestorePurchasesAsync();
+    bool IsInitialized { get; }
+}
+```
+
+## Step 6 — Migration Phases
+
+### Phase 1 — Package Check
+
+- Verify `com.unity.purchasing` exists in `Packages/manifest.json`.
+- If `com.unity.purchasing` is absent or outdated, install the latest stable version via Package Manager.
+- If missing or outdated, provide Package Manager instructions. Do not auto-edit `manifest.json` unless the user explicitly allows it.
+
+### Phase 2 — Product Catalog Extraction
+
+- Extract all product IDs and inferred types from the scan.
+- Generate `ProductCatalogDefinition.cs` / `ProductDefinitionEntry.cs`.
+- Each entry: `productId`, `ProductType`, optional `storeSpecificIds`, `notes`.
+
+### Phase 3 — New Unity IAP Service
+
+Create `UnityIapStorePurchaseService`:
+
+1. **Initialization** — `UnityIAPServices.StoreController()`, subscribe all events **before** `Connect()`.
+2. **Product fetching** — build `List<ProductDefinition>` from catalog, call `store.FetchProducts()`, handle `OnProductsFetched` / `OnProductsFetchFailed`.
+3. **Purchase initiation** — `store.PurchaseProduct(product)`.
+4. **Purchase callback** — `OnPurchasePending`: validate receipt → grant entitlement → `ConfirmPurchase(pendingOrder)`. **Never confirm before grant.**
+5. **Deferred purchases** — `OnPurchaseDeferred`: show pending UI, do not grant.
+6. **Failed purchases** — `OnPurchaseFailed`: map `FailureReason` to user-facing error.
+7. **Restore / fetch** — `store.FetchPurchases()` (re-delivers unconfirmed via `OnPurchasePending`) + `store.RestoreTransactions(callback)` for explicit iOS restore button.
+8. **Validation handoff** — send `order.Info.Receipt` (and `order.Info.Apple?.jwsRepresentation` on Apple) to backend in place of legacy `purchaseToken` + `originalJson` + `signature`. Document any backend change required.
+
+### Phase 4 — Compatibility Facade
+
+If game code calls the old billing API directly (e.g., `GoogleBillingManager.Purchase(id)`):
+
+- Create `LegacyGoogleBillingAdapterDeprecated.cs` that implements the same method signatures.
+- Delegate all calls to `UnityIapStorePurchaseService`.
+- Mark all methods `[Obsolete("Use IStorePurchaseService — remove after migration validation")]`.
+
+### Phase 5 — Remove Native Dependency from Active Path
+
+- Stop calling `AndroidJavaObject` bridge for migrated products.
+- Wrap native calls in `#if !USE_UNITY_IAP_V5` — do not delete them.
+- Leave Gradle billing dependencies unless user explicitly requests removal.
+
+### Phase 6 — Test Scaffolding
+
+- Add editor stubs for sandbox testing.
+- Add the QA checklist from the test plan below to `IapMigrationNotes.md`.
+
+## Step 7 — Behavior Change Rules
+
+These are the changes that break games or backends after the switch. For the Unity IAP side of each call, read the docs page named in the Full topic map of the parent skill file.
+
+- **One call replaces acknowledge and consume.** `ConfirmPurchase(pendingOrder)` replaces both `acknowledgePurchase` and `consumeAsync`. Call it only after the entitlement is granted and saved, because a confirmed purchase is never re-delivered.
+- **The receipt format changes for the backend.** `purchaseToken`, `originalJson` and `signature` are no longer separate values; they are embedded in `order.Info.Receipt`. If the backend reads them directly, list the receipt format change as a required backend update in `IapMigrationNotes.md`.
+- **Obfuscated IDs move after `Connect()`.** Native code sets them on `BillingFlowParams` per purchase. In Unity IAP, set them once on `GooglePlayStoreExtendedService` after `await store.Connect()`, and read them back per order from `GooglePlayStoreExtendedPurchaseService`. See the Google Play notes in [platform-notes.md](platform-notes.md).
+- **Pending purchases become deferred orders.** Native `PENDING` purchase state maps to `store.OnPurchaseDeferred`. Show a pending state and don't grant; the approved purchase arrives later through `OnPurchasePending`.
+- **Subscription changes take objects, not IDs.** `launchBillingFlow` with `subscriptionUpdateParams` maps to `UpgradeDowngradeSubscription(currentOrder, newProduct, mode)`. Choose the mode as the Google Play notes in [platform-notes.md](platform-notes.md) describe.
+
+## Step 8 — Native → Unity IAP Concept Mapping
+
+Only the mappings that aren't one-to-one renames, or that agents commonly get wrong:
+
+| Native Google Billing | Unity IAP 5.x |
+|---|---|
+| `ProductDetails` | `Product`, from `store.GetProductById` after `OnProductsFetched` |
+| `Purchase` | `PendingOrder`, from `OnPurchasePending` |
+| `queryPurchasesAsync` | `store.FetchPurchases()` → `OnPurchasesFetched` |
+| `BillingResult` / `BillingResponseCode` | `FailedOrder.FailureReason` / `StoreConnectionFailureDescription` |
+| `ProductType.INAPP` | `ProductType.Consumable` or `ProductType.NonConsumable`, decided by whether the native code consumes it |
+| `ProductType.SUBS` | `ProductType.Subscription` |
+| `offerToken` / `basePlanId` / `pricingPhases` | **Not exposed** — report as a blocker (Step 4) |
+
+## Step 9 — Rollback Plan
+
+- Wrap all new IAP code in `#if USE_UNITY_IAP_V5`.
+- Wrap all replaced native bridge calls in `#if !USE_UNITY_IAP_V5`.
+- To revert: remove `USE_UNITY_IAP_V5` from **Edit > Project Settings > Player > Scripting Define Symbols**. The native billing path is restored without any code changes.
+- Never activate both purchase systems for the same product simultaneously.
+- Document the rollback steps in `IapMigrationNotes.md`.
+
+## Step 10 — Test Checklist
+
+Include this in `IapMigrationNotes.md` after migration:
+
+- [ ] Fresh install — products load and display prices
+- [ ] Upgrade from old app version to migrated version — no duplicate entitlements
+- [ ] Consumable purchase — content granted
+- [ ] Repeat consumable purchase — repeatable, no block
+- [ ] Non-consumable purchase — content granted once
+- [ ] Non-consumable restore — content restored on reinstall
+- [ ] Subscription purchase — subscription active
+- [ ] Subscription restore — status refreshed on launch
+- [ ] Pending purchase (if applicable) — deferred UI shown, no premature grant
+- [ ] Interrupted purchase flow — re-delivered on next launch via `OnPurchasePending`
+- [ ] Backend validation success — entitlement granted
+- [ ] Backend validation failure — entitlement NOT granted, purchase not confirmed
+- [ ] Network failure during validation — purchase left pending, re-delivered on next launch
+- [ ] App killed during purchase — pending order re-delivered on next launch
+- [ ] App resumed after Google purchase UI — `OnPurchasePending` fires correctly
+- [ ] Sandbox tester account — no real charges
+- [ ] Internal testing track build
+- [ ] Play Console product ID match — all IDs match exactly
+- [ ] Play Console base plan compatibility — no advanced offer config that Unity IAP cannot reach
+- [ ] No duplicate entitlement grant
+- [ ] No unacknowledged purchases remaining
+- [ ] No double consumption of consumables
+
+## Step 11 — Questions to Ask (only when required)
+
+Ask only when the information cannot be inferred:
+
+1. Which product IDs are consumable, non-consumable, or subscription?
+2. Does the backend currently validate Google purchase tokens directly (raw `purchaseToken` field)?
+3. Are any subscriptions using multiple base plans or offer tokens?
+4. Should the skill preserve the old public C# billing API as a compatibility facade?
+5. Should native billing files be kept, disabled, or removed?
+
+If enough information can be inferred, proceed with a best-effort plan and mark uncertain items as **TODO**.