@sendoracloud/sdk-react-native-gaming 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 1.0.0 — Game Center / Play Games native module (split out of the main SDK)
+
+First release. The Game Center (iOS GameKit) + Play Games (Android PGS v2) native
+Expo module + its config plugin, extracted from `@sendoracloud/sdk-react-native`
+1.23.0 into an **optional companion** so non-gaming apps don't pull the Android
+`play-services-games-v2` dependency.
+
+- `expo-module.config.json` + `ios/SendoraGameAuthModule.swift` (GameKit
+  `fetchItems(forIdentityVerificationSignature:)`) + podspec.
+- `android/…/SendoraGameAuthModule.kt` (PGS v2 `requestServerSideAccess`) +
+  `build.gradle` (`play-services-games-v2:21.0.0`).
+- `app.plugin.js` — opt-in `{ gameCenter }` (iOS entitlement) +
+  `{ playGamesWebClientId, playGamesProjectId }` (Android `APP_ID` string resource
+  + web-client-id meta-data). Pure transforms unit-tested (`test/plugin.test.ts`).
+
+Registers `SendoraGameAuth` on `globalThis.expo.modules`; the main SDK's
+`auth.signInWithGameCenter()` / `auth.signInWithPlayGames()` (no-arg) read it.
+Requires `@sendoracloud/sdk-react-native >= 1.23.0` + a Dev Client.
+
+**On-device smoke (real Game Center + Play Games accounts) is the release gate.**

package/README.md

@@ -0,0 +1,68 @@
+# @sendoracloud/sdk-react-native-gaming
+
+Game Center (iOS) + Play Games (Android) native module for
+[`@sendoracloud/sdk-react-native`](https://www.npmjs.com/package/@sendoracloud/sdk-react-native).
+
+Install this **optional companion** only if your app uses email-less gaming
+sign-in. It ships the native code (GameKit / Play Games) that lets the main SDK's
+`auth.signInWithGameCenter()` / `auth.signInWithPlayGames()` run with **no
+arguments** — the SDK fetches the provider identity payload for you.
+
+Non-gaming apps should **not** install this package: it adds the Android
+`play-services-games-v2` dependency. The main SDK works fine without it (the
+no-arg calls throw a clear "install this package" error; the explicit-payload
+overloads still work everywhere).
+
+## Install
+
+```sh
+npx expo install @sendoracloud/sdk-react-native @sendoracloud/sdk-react-native-gaming
+```
+
+Needs a **Dev Client** — `npx expo prebuild` (or EAS Build). It does **not** work
+in Expo Go (native code).
+
+## Configure (app.json / app.config.js)
+
+```jsonc
+{
+  "plugins": [
+    ["@sendoracloud/sdk-react-native-gaming", {
+      "gameCenter": true,                                              // iOS: Game Center capability
+      "playGamesWebClientId": "<web-oauth-client-id>.apps.googleusercontent.com", // Android: from Google Cloud (Web app OAuth)
+      "playGamesProjectId": "1234567890"                              // Android: Play Games project id (Play Console)
+    }]
+  ]
+}
+```
+
+- `gameCenter: true` → adds the `com.apple.developer.game-center` entitlement (iOS).
+- `playGamesWebClientId` + `playGamesProjectId` (**both required**) → writes the
+  mandatory `com.google.android.gms.games.APP_ID` and the Web OAuth client id the
+  native module reads for `requestServerSideAccess` (Android).
+
+Then `npx expo prebuild` and rebuild.
+
+## Use (from the main SDK)
+
+```ts
+import { Sendora } from "@sendoracloud/sdk-react-native";
+
+// iOS — drives the Game Center sheet + verifies natively:
+await Sendora.auth.signInWithGameCenter();
+// Android — drives Play Games sign-in + returns a server auth code:
+await Sendora.auth.signInWithPlayGames();
+// Link an anonymous device in place (keep the same user id):
+await Sendora.auth.signInWithGameCenter({ link: true });
+```
+
+Configure the matching provider in the Sendora dashboard (Auth Service → Settings
+→ Gaming sign-in): the Game Center bundle-id allow-list, or the Play Games **Web**
+OAuth client id + secret.
+
+## Notes
+
+- Player-keyed + **email-less**: Game Center = stable `teamPlayerID`; Play Games =
+  stable per-game `playerId`. No email or verified name.
+- The native module registers as `SendoraGameAuth` on `globalThis.expo.modules`;
+  the main SDK reads it zero-dependency.

package/android/build.gradle

@@ -0,0 +1,25 @@
+// Sendora Cloud — Play Games sign-in native module (Expo Modules API).
+//
+// `expo-module-gradle-plugin` (bundled with expo-modules-core) wires the
+// ExpoModulesCore dependency, Kotlin, compile/min/target SDK (inherited from the
+// host app), namespace publication, and JSI registration. We only add our own
+// Play Games dependency + namespace.
+//
+// NOTE (app-size): `play-services-games-v2` is compiled into EVERY Android app
+// that installs this SDK and runs `expo prebuild` — including non-gaming apps.
+// It is a modest Google Play Services module (heavily R8-shrinkable in release).
+// The runtime code only runs when `signInWithPlayGames()` is actually called.
+apply plugin: 'com.android.library'
+apply plugin: 'expo-module-gradle-plugin'
+
+group = 'cloud.sendora.gameauth'
+version = '1.0.0'
+
+android {
+  namespace 'cloud.sendora.gameauth'
+}
+
+dependencies {
+  // Google Play Games Services v2 sign-in (GamesSignInClient.requestServerSideAccess).
+  implementation 'com.google.android.gms:play-services-games-v2:21.0.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/cloud/sendora/gameauth/SendoraGameAuthModule.kt

@@ -0,0 +1,118 @@
+// Sendora Cloud — Play Games sign-in native module (Expo Modules API).
+//
+// Exposes ONE async function to JS, `fetchServerAuthCode()`, which:
+//   1. reads the Web OAuth client id from the manifest meta-data written by the
+//      Sendora Expo config plugin (`com.sendoracloud.play_games_web_client_id`),
+//   2. ensures the player is signed in to Play Games (v2 GamesSignInClient),
+//   3. calls `requestServerSideAccess(webClientId, false)` and returns the
+//      one-time `serverAuthCode` the Sendora backend exchanges for the stable
+//      per-game `playerId`.
+//
+// The JS SDK's `auth.signInWithPlayGames()` (no args) reads this module off
+// `globalThis.expo.modules.SendoraGameAuth` (zero-dependency, Metro-safe) and
+// POSTs `{ serverAuthCode }` to `/auth-service/login/play-games`. Email-less,
+// player-keyed.
+//
+// Requires the `com.google.android.gms.games.APP_ID` meta-data (the numeric Play
+// Games project id) — wired by the config plugin's `{ playGamesProjectId,
+// playGamesWebClientId }` props. Without it, Play Games init throws.
+package cloud.sendora.gameauth
+
+import android.app.Activity
+import android.content.pm.PackageManager
+import com.google.android.gms.games.GamesSignInClient
+import com.google.android.gms.games.PlayGames
+import com.google.android.gms.games.PlayGamesSdk
+import expo.modules.kotlin.Promise
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+private const val META_WEB_CLIENT_ID = "com.sendoracloud.play_games_web_client_id"
+
+class SendoraGameAuthModule : Module() {
+  override fun definition() = ModuleDefinition {
+    Name("SendoraGameAuth")
+
+    AsyncFunction("fetchServerAuthCode") { promise: Promise ->
+      val activity = appContext.currentActivity
+      if (activity == null) {
+        promise.reject("E_NO_ACTIVITY", "No current Activity for Play Games sign-in.", null)
+        return@AsyncFunction
+      }
+
+      val webClientId = readMetaData(activity, META_WEB_CLIENT_ID)
+      if (webClientId.isNullOrBlank()) {
+        promise.reject(
+          "E_PLAY_GAMES_CONFIG",
+          "Play Games web client id not configured. Add the Sendora config plugin with " +
+            "{ playGamesWebClientId, playGamesProjectId } and rebuild the app.",
+          null,
+        )
+        return@AsyncFunction
+      }
+
+      // v2 must be initialized before the sign-in client is used. Idempotent;
+      // reads the mandatory APP_ID meta-data (throws if it is missing/invalid).
+      try {
+        PlayGamesSdk.initialize(activity.application)
+      } catch (e: Throwable) {
+        promise.reject(
+          "E_PLAY_GAMES_INIT",
+          "Play Games failed to initialize — is the com.google.android.gms.games.APP_ID meta-data set?",
+          e,
+        )
+        return@AsyncFunction
+      }
+
+      val client = PlayGames.getGamesSignInClient(activity)
+      client.isAuthenticated().addOnCompleteListener { authTask ->
+        val authed = authTask.isSuccessful && authTask.result.isAuthenticated
+        if (authed) {
+          requestServerAuthCode(client, webClientId, promise)
+        } else {
+          client.signIn().addOnCompleteListener { signInTask ->
+            if (signInTask.isSuccessful && signInTask.result.isAuthenticated) {
+              requestServerAuthCode(client, webClientId, promise)
+            } else {
+              promise.reject(
+                "E_PLAY_GAMES_SIGNIN",
+                "Google Play Games sign-in failed or was cancelled.",
+                signInTask.exception,
+              )
+            }
+          }
+        }
+      }
+    }
+  }
+
+  private fun requestServerAuthCode(client: GamesSignInClient, webClientId: String, promise: Promise) {
+    // 2-arg overload → Task<String>: the one-time server auth code. `false` =
+    // online access only (the backend needs no long-lived refresh token).
+    client.requestServerSideAccess(webClientId, false).addOnCompleteListener { task ->
+      // `task.result` THROWS if the task failed — check isSuccessful first.
+      val code = if (task.isSuccessful) task.result else null
+      if (!code.isNullOrBlank()) {
+        promise.resolve(mapOf("serverAuthCode" to code))
+      } else {
+        promise.reject(
+          "E_PLAY_GAMES_AUTHCODE",
+          "Failed to obtain a Play Games server auth code.",
+          task.exception,
+        )
+      }
+    }
+  }
+
+  private fun readMetaData(activity: Activity, key: String): String? {
+    return try {
+      val ai = activity.packageManager.getApplicationInfo(
+        activity.packageName,
+        PackageManager.GET_META_DATA,
+      )
+      ai.metaData?.getString(key)?.trim()
+    } catch (e: Exception) {
+      null
+    }
+  }
+}

package/app.plugin.js

@@ -0,0 +1,97 @@
+// Sendora gaming Expo config plugin — wires the platform config the Game Center
+// (iOS) / Play Games (Android) native module needs, so games don't hand-edit
+// entitlements / manifests.
+//
+// Usage in app.json / app.config.js:
+//   { "plugins": [["@sendoracloud/sdk-react-native-gaming", {
+//       "gameCenter": true,
+//       "playGamesWebClientId": "<web-oauth-client-id>.apps.googleusercontent.com",
+//       "playGamesProjectId": "1234567890"
+//   }]] }
+//
+// - iOS   `{ gameCenter: true }` → `com.apple.developer.game-center` entitlement.
+// - Android `{ playGamesWebClientId, playGamesProjectId }` → the mandatory
+//   `com.google.android.gms.games.APP_ID` (as a `game_services_project_id` string
+//   resource) + the `com.sendoracloud.play_games_web_client_id` meta-data the
+//   native module reads for `requestServerSideAccess`. BOTH ids are required.
+//
+// SAFE / backward-compatible: opt-in + build-time only (runs at `expo prebuild`),
+// MERGE/dedupe (an app that already declared these keeps them);
+// `createRunOncePlugin` guards double-apply. ESM (the package is `type: module`)
+// → Expo SDK 50+. Bug-prone transforms live in ./plugin/apply.js (pure,
+// unit-tested); this file wires them into the Expo mod pipeline.
+import {
+  withEntitlementsPlist,
+  withStringsXml,
+  withAndroidManifest,
+  AndroidConfig,
+  createRunOncePlugin,
+  WarningAggregator,
+} from "@expo/config-plugins";
+import { createRequire } from "node:module";
+import {
+  resolveGameProps,
+  setGameCenterEntitlement,
+  upsertStringResource,
+  addManifestMetaData,
+} from "./plugin/apply.js";
+
+const pkg = createRequire(import.meta.url)("./package.json");
+
+const PLAY_GAMES_PROJECT_ID_RES = "game_services_project_id";
+const PLAY_GAMES_APP_ID_META = "com.google.android.gms.games.APP_ID";
+const PLAY_GAMES_WEB_CLIENT_ID_META = "com.sendoracloud.play_games_web_client_id";
+
+// iOS: Game Center capability entitlement (required for identity verification).
+function withGameCenter(config) {
+  return withEntitlementsPlist(config, (cfg) => {
+    cfg.modResults = setGameCenterEntitlement(cfg.modResults);
+    return cfg;
+  });
+}
+
+// Android: the mandatory Play Games APP_ID (a string resource referenced by the
+// games meta-data) + the Web OAuth client id the native module reads.
+function withPlayGames(config, playGames) {
+  config = withStringsXml(config, (cfg) => {
+    cfg.modResults = upsertStringResource(
+      cfg.modResults,
+      PLAY_GAMES_PROJECT_ID_RES,
+      playGames.projectId,
+      { translatable: false },
+    );
+    return cfg;
+  });
+  config = withAndroidManifest(config, (cfg) => {
+    const app = AndroidConfig.Manifest.getMainApplicationOrThrow(cfg.modResults);
+    addManifestMetaData(app, PLAY_GAMES_APP_ID_META, `@string/${PLAY_GAMES_PROJECT_ID_RES}`);
+    addManifestMetaData(app, PLAY_GAMES_WEB_CLIENT_ID_META, playGames.webClientId);
+    return cfg;
+  });
+  return config;
+}
+
+const withSendoraGaming = (config, props) => {
+  const game = resolveGameProps(props);
+  if (!game.gameCenter && !game.playGames) {
+    const partial = props && (props.playGamesWebClientId || props.playGamesProjectId);
+    WarningAggregator.addWarningIOS(
+      pkg.name,
+      partial
+        ? "Play Games not wired — set BOTH { playGamesWebClientId } and { playGamesProjectId }."
+        : "No gaming props configured — pass { gameCenter: true } and/or { playGamesWebClientId, playGamesProjectId }.",
+    );
+    return config;
+  }
+  if (game.gameCenter) config = withGameCenter(config);
+  if (game.playGames) config = withPlayGames(config, game.playGames);
+  else if (props && (props.playGamesWebClientId || props.playGamesProjectId)) {
+    WarningAggregator.addWarningAndroid(
+      pkg.name,
+      "Play Games not wired — set BOTH { playGamesWebClientId } and { playGamesProjectId }.",
+    );
+  }
+  return config;
+};
+
+export default createRunOncePlugin(withSendoraGaming, pkg.name, pkg.version);

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["SendoraGameAuthModule"]
+  },
+  "android": {
+    "modules": ["cloud.sendora.gameauth.SendoraGameAuthModule"]
+  }
+}

package/ios/SendoraGameAuth.podspec

@@ -0,0 +1,33 @@
+# Sendora Cloud — Game Center identity native module (Expo Modules API).
+#
+# Autolinked by Expo when the host app runs `expo prebuild` / `pod install`
+# (discovered via ../expo-module.config.json). GameKit is a system framework —
+# no third-party pods, no app-size cost on iOS. The module is OPTIONAL at
+# runtime: apps that never call `signInWithGameCenter()` never touch it.
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'SendoraGameAuth'
+  s.version        = package['version']
+  s.summary        = 'Game Center identity verification for Sendora Cloud auth.'
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = 'Sendora Cloud'
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '15.1', :tvos => '15.1' }
+  s.swift_version  = '5.9'
+  s.source         = { git: 'https://github.com/sendoracloud/sdk-react-native' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+
+  # GameKit is linked implicitly via `import GameKit` in the Swift source.
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+    'SWIFT_COMPILATION_MODE' => 'wholemodule'
+  }
+
+  s.source_files = '**/*.{h,m,mm,swift,hpp,cpp}'
+end

package/ios/SendoraGameAuthModule.swift

@@ -0,0 +1,128 @@
+// Sendora Cloud — Game Center identity native module (Expo Modules API).
+//
+// Exposes ONE async function to JS, `fetchGameCenterIdentity()`, which:
+//   1. ensures the local player is authenticated (drives the Game Center
+//      sign-in sheet via `authenticateHandler` if needed), then
+//   2. calls `GKLocalPlayer.local.fetchItems(forIdentityVerificationSignature:)`
+//      — the current, non-deprecated identity API — and returns the exact
+//      payload the Sendora backend verifies:
+//        { publicKeyUrl, signature(b64), salt(b64), timestamp(ms), teamPlayerId, bundleId }
+//
+// The JS SDK's `auth.signInWithGameCenter()` (no args) reads this module off
+// `globalThis.expo.modules.SendoraGameAuth` (zero-dependency, Metro-safe) and
+// POSTs the result to `/auth-service/login/game-center`. Email-less, player-keyed
+// — `teamPlayerId` is the stable per-developer-Team account key; there is no
+// email or verified name.
+//
+// Requires the Game Center capability (`com.apple.developer.game-center`
+// entitlement) on a Game Center-enabled App ID — wired by the Sendora Expo
+// config plugin's `{ gameCenter: true }` prop.
+import ExpoModulesCore
+import GameKit
+import UIKit
+
+public class SendoraGameAuthModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("SendoraGameAuth")
+
+    // Runs on the main queue so the GameKit auth flow + view-controller
+    // presentation are main-thread safe (Expo AsyncFunctions default to a
+    // background queue).
+    AsyncFunction("fetchGameCenterIdentity") { (promise: Promise) in
+      let local = GKLocalPlayer.local
+
+      // Already authenticated (the common case once the app has signed in
+      // to Game Center) → straight to the signature.
+      if local.isAuthenticated {
+        Self.fetchItems(local, promise)
+        return
+      }
+
+      // Not authenticated — drive the Game Center auth flow. Assigning the
+      // handler starts it; it can fire MORE THAN ONCE (once to hand back a
+      // sign-in view controller to present, again when auth resolves), so a
+      // `settled` guard ensures the JS promise is resolved/rejected exactly
+      // once. `authenticateHandler` is a GameKit singleton — the JS SDK
+      // serializes all auth ops (single-flight), so two SDK-driven sign-ins
+      // can't race to overwrite it; an app that ALSO sets its own handler
+      // should let the SDK own Game Center auth when using this no-arg path.
+      var settled = false
+      local.authenticateHandler = { viewController, error in
+        if settled { return }
+
+        if let error = error {
+          settled = true
+          promise.reject("E_GAME_CENTER_AUTH", error.localizedDescription)
+          return
+        }
+
+        if let viewController = viewController {
+          // Present the Game Center sign-in sheet from the TOP-most presented VC
+          // — presenting on the root VC throws if a modal (an RN modal, an auth
+          // sheet) is already up.
+          guard let top = Self.topViewController() else {
+            settled = true
+            promise.reject("E_NO_VIEW_CONTROLLER", "No view controller available to present the Game Center sign-in sheet.")
+            return
+          }
+          top.present(viewController, animated: true)
+          return // wait for the handler to fire again once auth resolves
+        }
+
+        // viewController == nil && error == nil → authentication resolved.
+        guard local.isAuthenticated else {
+          settled = true
+          promise.reject("E_GAME_CENTER_CANCELLED", "Game Center sign-in was cancelled or is unavailable.")
+          return
+        }
+        settled = true
+        Self.fetchItems(local, promise)
+      }
+    }.runOnQueue(.main)
+  }
+
+  /// Fetch the identity-verification items and resolve the JSON-safe payload.
+  private static func fetchItems(_ local: GKLocalPlayer, _ promise: Promise) {
+    local.fetchItems(forIdentityVerificationSignature: { publicKeyURL, signature, salt, timestamp, error in
+      if let error = error {
+        promise.reject("E_GAME_CENTER_FETCH", error.localizedDescription)
+        return
+      }
+      guard let publicKeyURL = publicKeyURL, let signature = signature, let salt = salt else {
+        promise.reject("E_GAME_CENTER_FETCH", "Game Center returned an incomplete identity signature.")
+        return
+      }
+      // timestamp is ms since epoch (~1.7e12) — well under 2^53, so it is exact
+      // as a JS number (Double). The backend schema expects `timestamp: number`.
+      promise.resolve([
+        "publicKeyUrl": publicKeyURL.absoluteString,
+        "signature": signature.base64EncodedString(),
+        "salt": salt.base64EncodedString(),
+        "timestamp": Double(timestamp),
+        "teamPlayerId": local.teamPlayerID,
+        "bundleId": Bundle.main.bundleIdentifier ?? "",
+      ])
+    })
+  }
+
+  /// The foreground window scene's root view controller (main thread).
+  private static func rootViewController() -> UIViewController? {
+    return UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .first(where: { $0.activationState == .foregroundActive })?
+      .keyWindow?.rootViewController
+      ?? UIApplication.shared.connectedScenes
+        .compactMap { ($0 as? UIWindowScene)?.keyWindow }
+        .first?.rootViewController
+  }
+
+  /// Walk the modal presentation chain to the top-most VC — the only VC that can
+  /// present another. Presenting on a VC that is already presenting throws.
+  private static func topViewController() -> UIViewController? {
+    var top = rootViewController()
+    while let presented = top?.presentedViewController, !presented.isBeingDismissed {
+      top = presented
+    }
+    return top
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@sendoracloud/sdk-react-native-gaming",
+  "version": "1.0.0",
+  "description": "Game Center (iOS) + Play Games (Android) native module for @sendoracloud/sdk-react-native — enables the no-arg auth.signInWithGameCenter() / auth.signInWithPlayGames(). Optional companion so non-gaming apps don't pull the Play Games dependency. Needs a Dev Client (EAS Build or `npx expo prebuild`).",
+  "type": "module",
+  "keywords": [
+    "sendora",
+    "react-native",
+    "expo",
+    "game-center",
+    "play-games",
+    "auth",
+    "gaming"
+  ],
+  "files": [
+    "expo-module.config.json",
+    "ios",
+    "android",
+    "app.plugin.js",
+    "plugin",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react-native": ">=0.70.0",
+    "@sendoracloud/sdk-react-native": ">=1.23.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native": { "optional": true },
+    "@sendoracloud/sdk-react-native": { "optional": true }
+  },
+  "scripts": {
+    "test": "tsx test/plugin.test.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.21.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sendoracloud/sdk-react-native"
+  },
+  "homepage": "https://sendoracloud.com/sdks",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/plugin/apply.js

@@ -0,0 +1,68 @@
+// Pure, dependency-free helpers for the Sendora gaming Expo config plugin
+// (../app.plugin.js). Extracted so the bug-prone logic is unit-testable WITHOUT
+// `@expo/config-plugins` (which only exists in the consumer's Expo prebuild env).
+//
+// ESM — the package is `type: module`.
+//
+// The plugin writes the platform CONFIG the native module needs:
+//   iOS      — the `com.apple.developer.game-center` entitlement.
+//   Android  — the mandatory `com.google.android.gms.games.APP_ID` meta-data
+//              (as a string resource) + the Web OAuth client id meta-data the
+//              module reads for `requestServerSideAccess`.
+// All opt-in: nothing is added unless the corresponding prop is set.
+
+/** Normalize the gaming plugin props. Play Games needs BOTH ids to wire. */
+export function resolveGameProps(props) {
+  const p = props || {};
+  const gameCenter = p.gameCenter === true;
+  const webClientId =
+    typeof p.playGamesWebClientId === "string" && p.playGamesWebClientId.trim()
+      ? p.playGamesWebClientId.trim()
+      : null;
+  const projectId =
+    typeof p.playGamesProjectId === "string" && p.playGamesProjectId.trim()
+      ? p.playGamesProjectId.trim()
+      : typeof p.playGamesProjectId === "number"
+        ? String(p.playGamesProjectId)
+        : null;
+  return { gameCenter, playGames: webClientId && projectId ? { webClientId, projectId } : null };
+}
+
+/** iOS: enable the Game Center capability (`com.apple.developer.game-center: true`). */
+export function setGameCenterEntitlement(entitlements) {
+  const e = entitlements && typeof entitlements === "object" ? entitlements : {};
+  e["com.apple.developer.game-center"] = true;
+  return e;
+}
+
+/**
+ * Android: add/replace a `<string name="...">value</string>` resource. Mutates +
+ * returns the parsed strings.xml object (`{ resources: { string: [...] } }`).
+ */
+export function upsertStringResource(resourcesXml, name, value, opts) {
+  const xml = resourcesXml && typeof resourcesXml === "object" ? resourcesXml : {};
+  xml.resources = xml.resources || {};
+  const arr = Array.isArray(xml.resources.string) ? xml.resources.string : [];
+  const item = { _: String(value), $: { name } };
+  if (opts && opts.translatable === false) item.$.translatable = "false";
+  const idx = arr.findIndex((s) => s && s.$ && s.$.name === name);
+  if (idx >= 0) arr[idx] = item;
+  else arr.push(item);
+  xml.resources.string = arr;
+  return xml;
+}
+
+/**
+ * Android: add/replace a `<meta-data android:name=".." android:value="..">`
+ * under the application node (dedupe by name). Mutates + returns the app node.
+ */
+export function addManifestMetaData(application, name, value) {
+  if (!application) return application;
+  application["meta-data"] = application["meta-data"] || [];
+  const arr = application["meta-data"];
+  const item = { $: { "android:name": name, "android:value": String(value) } };
+  const idx = arr.findIndex((m) => m && m.$ && m.$["android:name"] === name);
+  if (idx >= 0) arr[idx] = item;
+  else arr.push(item);
+  return application;
+}