@leonxin/meetgames 0.1.7 → 0.1.11

package/src/ops/handlers.ts

@@ -0,0 +1,304 @@
+import fs from "node:fs";
+import path from "node:path";
+import type { StepResult, WorkspaceContext } from "../contracts/types.js";
+import { applicationModuleRelPath } from "../android/detect.js";
+import { updateModuleBuildGradleDependencies, updateRootBuildGradleRepositories } from "../android/gradle.js";
+import {
+  detectModuleGradlePluginStyle,
+  updateModuleBuildGradleMeetSdkRemote,
+  updateRootBuildGradleMeetSdkRemote,
+  updateSettingsGradleMeetSdkRemote,
+} from "../android/meetSdkRemoteGradle.js";
+import {
+  MEETSDK_REMOTE_CONFIG_FILENAME,
+  applyMeetSdkDefaultConfig,
+  collectMeetSdkRemoteApplyPlugins,
+  collectMeetSdkRemoteBuildscriptClasspaths,
+  collectMeetSdkRemoteBuildscriptRepositories,
+  collectMeetSdkRemotePluginsDslForModule,
+  collectMeetSdkRemotePluginsDslForRoot,
+  collectMeetSdkRemoteRepositories,
+  tryParseAsMeetSdkRemoteConfig,
+  validateMeetSdkRemoteConfig,
+} from "../config/meetSdkRemoteConfig.js";
+import { loadMeetSdkDefaultConfigWithLatestAndroidVersion } from "../config/meetSdkDefaultConfig.js";
+import { insertPermissions } from "../android/manifest.js";
+import type { TextFileStore } from "./fileStore.js";
+
+function ok(changed: string[], warnings: string[] = []): StepResult {
+  return { ok: true, changedFiles: changed, warnings, errors: [] };
+}
+
+function fail(errors: string[]): StepResult {
+  return { ok: false, changedFiles: [], warnings: [], errors };
+}
+
+function readRootBuildGradle(projectRoot: string): { rel: string; abs: string } | null {
+  const a = path.join(projectRoot, "build.gradle");
+  if (fs.existsSync(a)) return { rel: "build.gradle", abs: a };
+  const b = path.join(projectRoot, "build.gradle.kts");
+  if (fs.existsSync(b)) return { rel: "build.gradle.kts", abs: b };
+  return null;
+}
+
+function readSettingsGradle(projectRoot: string): { rel: string; abs: string } | null {
+  const a = path.join(projectRoot, "settings.gradle");
+  if (fs.existsSync(a)) return { rel: "settings.gradle", abs: a };
+  const b = path.join(projectRoot, "settings.gradle.kts");
+  if (fs.existsSync(b)) return { rel: "settings.gradle.kts", abs: b };
+  return null;
+}
+
+function moduleGradleRel(ctx: WorkspaceContext): string | null {
+  if (!ctx.android?.ok) return null;
+  const moduleDir = ctx.android.moduleDir;
+  const a = path.join(moduleDir, "build.gradle");
+  if (fs.existsSync(a)) return path.relative(ctx.projectRoot, a).split(path.sep).join("/");
+  const b = path.join(moduleDir, "build.gradle.kts");
+  if (fs.existsSync(b)) return path.relative(ctx.projectRoot, b).split(path.sep).join("/");
+  return null;
+}
+
+export interface BinaryCopy {
+  fromAbs: string;
+  relTo: string;
+}
+
+export type OpHandler = (
+  ctx: WorkspaceContext,
+  store: TextFileStore,
+  args: Record<string, unknown>,
+  dryRun: boolean,
+  binaryCopies: BinaryCopy[]
+) => StepResult | Promise<StepResult>;
+
+export const opHandlers: Record<string, OpHandler> = {
+  /**
+   * Reads meetsdk-remote-config.json (or args.configFile) and writes TOPSDK-managed blocks
+   * into root `build.gradle` (repositories) and the app module `build.gradle` (resValue + TOPSDK dependencies),
+   * matching sdk-integration-agent `gradleEditor.js` behavior.
+   */
+  "gradle.applyMeetSdkRemoteConfig": async (ctx, store, args, _dry, _bc) => {
+    if (!ctx.android?.ok) return fail(["android application module not detected"]);
+    const configRel =
+      typeof args.configFile === "string" && args.configFile.trim()
+        ? args.configFile.trim().replace(/\\/g, "/")
+        : MEETSDK_REMOTE_CONFIG_FILENAME;
+    const abs = path.join(ctx.projectRoot, configRel);
+    if (!fs.existsSync(abs)) return fail([`meet sdk remote config not found: ${configRel}`]);
+    let raw: unknown;
+    try {
+      raw = JSON.parse(fs.readFileSync(abs, "utf8")) as unknown;
+    } catch {
+      return fail([`failed to parse JSON: ${configRel}`]);
+    }
+    const parsed = tryParseAsMeetSdkRemoteConfig(raw);
+    if (!parsed) return fail([`not a meetsdk-remote-config document: ${configRel}`]);
+    const v = validateMeetSdkRemoteConfig(parsed);
+    if (!v.ok) {
+      return fail([`meetsdk-remote-config validation failed (${configRel}): ${v.missing.join(", ")}`]);
+    }
+    const resolved = applyMeetSdkDefaultConfig(
+      parsed,
+      await loadMeetSdkDefaultConfigWithLatestAndroidVersion({
+        sdkHomeApiBaseUrl: ctx.sdkHomeApiBaseUrl,
+        packageRoot: ctx.packageRoot,
+      })
+    );
+
+    const repositories = collectMeetSdkRemoteRepositories(resolved);
+    const buildscriptRepositories = collectMeetSdkRemoteBuildscriptRepositories(resolved);
+    const buildscriptClasspaths = collectMeetSdkRemoteBuildscriptClasspaths(resolved);
+
+    const modRel = moduleGradleRel(ctx);
+    if (!modRel) return fail(["module build.gradle not found"]);
+    if (modRel.endsWith(".kts")) {
+      return fail(["gradle.applyMeetSdkRemoteConfig: module build.gradle.kts not supported in MVP"]);
+    }
+    const modBefore = store.read(modRel);
+    const modulePluginStyle = detectModuleGradlePluginStyle(modBefore);
+    const usesPluginsDsl = modulePluginStyle === "plugins-dsl";
+
+    const changed: string[] = [];
+    const warnings: string[] = [];
+
+    const settings = readSettingsGradle(ctx.projectRoot);
+    let repositoriesWrittenInSettings = false;
+    if (settings && repositories.length > 0) {
+      if (settings.rel.endsWith(".kts")) {
+        warnings.push("gradle.applyMeetSdkRemoteConfig: settings.gradle.kts repositories edit not supported yet; fallback to root build.gradle");
+      } else {
+        const settingsBefore = store.read(settings.rel);
+        const settingsU = updateSettingsGradleMeetSdkRemote(settingsBefore, repositories);
+        if (!settingsU.ok) {
+          warnings.push(settingsU.error);
+        } else {
+          store.write(settings.rel, settingsU.content);
+          if (settingsU.changed) changed.push(settings.rel);
+          warnings.push(...settingsU.warnings);
+          repositoriesWrittenInSettings = true;
+        }
+      }
+    }
+
+    const root = readRootBuildGradle(ctx.projectRoot);
+    if (!root) {
+      if (!repositoriesWrittenInSettings) return fail(["root build.gradle not found"]);
+      if (buildscriptRepositories.length > 0 || buildscriptClasspaths.length > 0) {
+        warnings.push("root build.gradle not found; skipped buildscript repositories/classpaths");
+      }
+    } else {
+      if (root.rel.endsWith(".kts")) {
+        return fail(["gradle.applyMeetSdkRemoteConfig: root build.gradle.kts not supported in MVP"]);
+      }
+      const rootBefore = store.read(root.rel);
+      const rootU = updateRootBuildGradleMeetSdkRemote(rootBefore, {
+        repositories: repositoriesWrittenInSettings ? [] : repositories,
+        buildscriptRepositories: usesPluginsDsl ? [] : buildscriptRepositories,
+        buildscriptClasspaths: usesPluginsDsl ? [] : buildscriptClasspaths,
+        rootPluginsDsl: usesPluginsDsl ? collectMeetSdkRemotePluginsDslForRoot(resolved) : [],
+        stripBuildscriptClasspaths: usesPluginsDsl ? buildscriptClasspaths : [],
+        stripPluginsDslIds: usesPluginsDsl ? [] : collectMeetSdkRemotePluginsDslForModule(resolved).map((p) => p.id),
+      });
+      if (!rootU.ok) return fail([rootU.error]);
+      store.write(root.rel, rootU.content);
+      if (rootU.changed) changed.push(root.rel);
+      warnings.push(...rootU.warnings);
+    }
+
+    const modU = updateModuleBuildGradleMeetSdkRemote(modBefore, resolved, {
+      style: modulePluginStyle,
+      applyPlugins: usesPluginsDsl ? [] : collectMeetSdkRemoteApplyPlugins(resolved),
+      pluginsDsl: usesPluginsDsl ? collectMeetSdkRemotePluginsDslForModule(resolved) : [],
+    });
+    if (!modU.ok) return fail([modU.error]);
+
+    store.write(modRel, modU.content);
+    if (modU.changed) changed.push(modRel);
+    return ok(changed, [...warnings, ...modU.warnings]);
+  },
+
+  "gradle.insertRepositories": (ctx, store, args, _dry, _bc) => {
+    if (!ctx.android?.ok) return fail(["android application module not detected"]);
+    const urls = args.urls;
+    if (!Array.isArray(urls) || !urls.every((u) => typeof u === "string")) {
+      return fail(["gradle.insertRepositories requires args.urls: string[]"]);
+    }
+    const root = readRootBuildGradle(ctx.projectRoot);
+    if (!root) return fail(["root build.gradle not found"]);
+    if (root.rel.endsWith(".kts")) return fail(["gradle.insertRepositories: build.gradle.kts not supported in MVP"]);
+    const rel = root.rel;
+    const before = store.read(rel);
+    const res = updateRootBuildGradleRepositories(before, urls as string[]);
+    if (!res.ok) return fail([res.error]);
+    store.write(rel, res.content);
+    const changed = res.changed ? [rel] : [];
+    return ok(changed, res.warnings);
+  },
+
+  "gradle.addDependency": (ctx, store, args, _dry, _bc) => {
+    if (!ctx.android?.ok) return fail(["android application module not detected"]);
+    const modRel = moduleGradleRel(ctx);
+    if (!modRel) return fail(["module build.gradle not found"]);
+    if (modRel.endsWith(".kts")) return fail(["gradle.addDependency: build.gradle.kts not supported in MVP"]);
+    let depLines: string[] = [];
+    if (Array.isArray(args.lines)) {
+      depLines = (args.lines as unknown[]).map((x) => String(x));
+    } else if (typeof args.coordinate === "string") {
+      const cfg = typeof args.configuration === "string" ? args.configuration : "implementation";
+      depLines = [`    ${cfg} '${args.coordinate}'`];
+    } else {
+      return fail(["gradle.addDependency requires args.lines: string[] or args.coordinate: string"]);
+    }
+    const before = store.read(modRel);
+    const res = updateModuleBuildGradleDependencies(before, depLines);
+    if (!res.ok) return fail([res.error]);
+    store.write(modRel, res.content);
+    return ok(res.changed ? [modRel] : [], res.warnings);
+  },
+
+  "android.manifest.insertPermissions": (ctx, store, args, _dry, _bc) => {
+    if (!ctx.android?.ok) return fail(["android application module not detected"]);
+    const perms = args.permissions;
+    if (!Array.isArray(perms) || !perms.every((p) => typeof p === "string")) {
+      return fail(["android.manifest.insertPermissions requires args.permissions: string[]"]);
+    }
+    const rel = path.relative(ctx.projectRoot, ctx.android.manifestPath).split(path.sep).join("/");
+    const before = store.read(rel);
+    const { content, changed } = insertPermissions(before, perms as string[]);
+    store.write(rel, content);
+    return ok(changed ? [rel] : []);
+  },
+
+  "ios.integrateTopSdk": async (ctx, store, args, dryRun, binaryCopies) => {
+    if (!ctx.ios?.ok) return fail(["iOS project not detected"]);
+    const { runIosIntegrateTopSdk } = await import("../ios/integrate.js");
+    const targetName = typeof args.targetName === "string" ? args.targetName : undefined;
+    const executeAppDelegate = args.executeAppDelegate === false ? false : true;
+    return runIosIntegrateTopSdk(ctx, store, binaryCopies, {
+      dryRun,
+      targetName,
+      executeAppDelegate,
+    });
+  },
+
+  "files.downloadGoogleServicesJson": async (ctx, _store, args, dryRun, _bc) => {
+    if (!ctx.android?.ok) return fail(["android application module not detected"]);
+    const configRel =
+      typeof args.configFile === "string" && args.configFile.trim()
+        ? args.configFile.trim().replace(/\\/g, "/")
+        : MEETSDK_REMOTE_CONFIG_FILENAME;
+    const abs = path.join(ctx.projectRoot, configRel);
+    if (!fs.existsSync(abs)) return fail([`meet sdk remote config not found: ${configRel}`]);
+    let raw: unknown;
+    try {
+      raw = JSON.parse(fs.readFileSync(abs, "utf8")) as unknown;
+    } catch {
+      return fail([`failed to parse JSON: ${configRel}`]);
+    }
+    const parsed = tryParseAsMeetSdkRemoteConfig(raw);
+    if (!parsed) return fail([`not a meetsdk-remote-config document: ${configRel}`]);
+    const resolved = applyMeetSdkDefaultConfig(
+      parsed,
+      await loadMeetSdkDefaultConfigWithLatestAndroidVersion({
+        sdkHomeApiBaseUrl: ctx.sdkHomeApiBaseUrl,
+        packageRoot: ctx.packageRoot,
+      })
+    );
+    const firebase = resolved.sdkModules.analytics.firebase;
+    if (typeof firebase !== "object" || firebase === null) {
+      return ok([], ["files.downloadGoogleServicesJson: analytics.firebase not enabled, skipped"]);
+    }
+
+    const moduleRel = applicationModuleRelPath(ctx.projectRoot, ctx.android);
+
+    const { downloadGoogleServicesJson } = await import("../android/downloadGoogleServicesJson.js");
+    const result = await downloadGoogleServicesJson(ctx.projectRoot, firebase, {
+      applicationModuleRelPath: moduleRel,
+      dryRun,
+    });
+    if (!result.ok) return fail([`files.downloadGoogleServicesJson: ${result.error}`]);
+    return ok(dryRun ? [] : [result.relPath], [
+      dryRun
+        ? `would download google-services.json to ${result.relPath}`
+        : `downloaded google-services.json to ${result.relPath}`,
+    ]);
+  },
+
+  "files.copyBundled": (ctx, _store, args, _dry, binaryCopies) => {
+    const from = args.from;
+    const to = args.to;
+    if (typeof from !== "string" || typeof to !== "string") {
+      return fail(["files.copyBundled requires args.from and args.to as strings"]);
+    }
+    const fromAbs = path.join(ctx.packageRoot, "bundled", from);
+    if (!fs.existsSync(fromAbs)) return fail([`bundled source not found: bundled/${from}`]);
+    const relTo = to.replace(/\\/g, "/");
+    binaryCopies.push({ fromAbs, relTo });
+    return ok([relTo]);
+  },
+};
+
+export function getOpHandler(name: string): OpHandler | undefined {
+  return opHandlers[name];
+}

package/src/remote/fetchJson.ts

@@ -0,0 +1,22 @@
+/**
+ * GET a URL and parse JSON (Node 18+ fetch).
+ */
+export async function fetchJsonGet(url: string, init?: RequestInit): Promise<unknown> {
+  const res = await fetch(url, {
+    redirect: "follow",
+    ...init,
+    headers: {
+      Accept: "application/json",
+      ...(init?.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`GET ${url} failed: HTTP ${res.status}`);
+  }
+  const text = await res.text();
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new Error("Remote response is not valid JSON");
+  }
+}

package/src/remote/sdkHomeDownload.ts

@@ -0,0 +1,274 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { defaultBundledIosSdkRoot } from "../ios/sdkBundle.js";
+import { syncMeetSdkIosVersionToConfig } from "../config/meetSdkIosConfig.js";
+
+export const defaultSdkHomeApiBaseUrl = "https://business-api.meetgames.com";
+export const DEFAULT_IOS_SDK_PLUGINS = ["guest", "facebook", "google", "apple", "apple_pay", "dataAppsFlyer"] as const;
+export const DEFAULT_IOS_SDK_PACKAGE_TYPE = "native";
+
+const SDK_HOME_VERSION_PATH = "sdk/home/version";
+const SDK_HOME_DOWNLOAD_URL_PATH = "sdk/home/sdk-download/getDownLoadUrl";
+
+type JsonRecord = Record<string, unknown>;
+
+export interface SdkHomePlatformVersion {
+  ver: string;
+  date: string;
+}
+
+export interface SdkHomeVersions {
+  android: SdkHomePlatformVersion;
+  ios: SdkHomePlatformVersion;
+}
+
+export interface SdkHomeDownloadUrlRequest {
+  baseUrl: string;
+  version: string;
+  platform?: "ios";
+  plugins?: readonly string[] | string;
+  packageType?: string;
+}
+
+export interface DownloadIosSdkOptions {
+  baseUrl?: string;
+  version?: string;
+  plugins?: readonly string[] | string;
+  packageType?: string;
+  outputDir?: string;
+  signal?: AbortSignal;
+}
+
+export interface DownloadIosSdkResult {
+  version: string;
+  versionDate: string;
+  versionUrl: string;
+  downloadApiUrl: string;
+  sdkZipUrl: string;
+  zipPath: string;
+  extractDir: string;
+  resolvedSdkRoot: string;
+  iosConfigPath: string;
+}
+
+function isRecord(value: unknown): value is JsonRecord {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function joinBaseAndPath(baseUrl: string, subPath: string): URL {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL(subPath, base);
+}
+
+function pluginsToCsv(plugins: readonly string[] | string | undefined): string {
+  if (typeof plugins === "string") return plugins;
+  return (plugins ?? DEFAULT_IOS_SDK_PLUGINS).join(",");
+}
+
+function pluginsToList(plugins: readonly string[] | string | undefined): string[] {
+  return pluginsToCsv(plugins)
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function buildSdkHomeVersionUrl(baseUrl: string): string {
+  return joinBaseAndPath(baseUrl, SDK_HOME_VERSION_PATH).toString();
+}
+
+export function buildSdkHomeDownloadUrl(params: SdkHomeDownloadUrlRequest): string {
+  const u = joinBaseAndPath(params.baseUrl, SDK_HOME_DOWNLOAD_URL_PATH);
+  u.searchParams.set("version", params.version);
+  u.searchParams.set("platform", params.platform ?? "ios");
+  u.searchParams.set("plugins", pluginsToCsv(params.plugins));
+  u.searchParams.set("packageType", params.packageType || DEFAULT_IOS_SDK_PACKAGE_TYPE);
+  return u.toString();
+}
+
+function parseJsonResponseEnvelope(body: unknown, label: string): JsonRecord {
+  if (!isRecord(body)) throw new Error(`${label} response is not an object`);
+  const code = body.code;
+  if (Number(code) !== 200) {
+    const message = typeof body.message === "string" ? body.message : JSON.stringify(body);
+    throw new Error(`${label} API error (code=${String(code)}): ${message}`);
+  }
+  return body;
+}
+
+async function fetchJson(url: string, signal?: AbortSignal): Promise<unknown> {
+  let res: Response;
+  try {
+    res = await fetch(url, { redirect: "follow", signal, headers: { Accept: "application/json" } });
+  } catch (e) {
+    const cause = e instanceof Error && "cause" in e && e.cause instanceof Error ? e.cause.message : null;
+    const detail = cause && cause !== (e instanceof Error ? e.message : String(e)) ? ` (${cause})` : "";
+    throw new Error(`GET ${url} failed: ${e instanceof Error ? e.message : String(e)}${detail}`);
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    const detail = text.trim() ? `: ${text.trim().slice(0, 1000)}` : "";
+    throw new Error(`GET ${url} failed: HTTP ${res.status}${detail}`);
+  }
+  const text = await res.text();
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new Error(`GET ${url} did not return valid JSON`);
+  }
+}
+
+export async function fetchSdkHomeIosVersion(params: {
+  baseUrl?: string;
+  signal?: AbortSignal;
+} = {}): Promise<{ url: string; ios: SdkHomePlatformVersion }> {
+  const { url, versions } = await fetchSdkHomeVersions(params);
+  return { url, ios: versions.ios };
+}
+
+function parseSdkHomePlatformVersion(value: unknown, platform: "android" | "ios"): SdkHomePlatformVersion {
+  if (!isRecord(value) || typeof value.ver !== "string" || typeof value.date !== "string") {
+    throw new Error(`sdk-home version response does not contain data.result.${platform}.ver/date`);
+  }
+  return { ver: value.ver, date: value.date };
+}
+
+export async function fetchSdkHomeVersions(params: {
+  baseUrl?: string;
+  signal?: AbortSignal;
+} = {}): Promise<{ url: string; versions: SdkHomeVersions }> {
+  const baseUrl = params.baseUrl || defaultSdkHomeApiBaseUrl;
+  const url = buildSdkHomeVersionUrl(baseUrl);
+  const body = parseJsonResponseEnvelope(await fetchJson(url, params.signal), "sdk-home version");
+  const data = body.data;
+  const result = isRecord(data) ? data.result : undefined;
+  if (!isRecord(result)) {
+    throw new Error("sdk-home version response does not contain data.result");
+  }
+  return {
+    url,
+    versions: {
+      android: parseSdkHomePlatformVersion(result.android, "android"),
+      ios: parseSdkHomePlatformVersion(result.ios, "ios"),
+    },
+  };
+}
+
+export async function fetchSdkHomeIosDownloadUrl(params: SdkHomeDownloadUrlRequest & {
+  signal?: AbortSignal;
+}): Promise<{ url: string; sdkZipUrl: string }> {
+  const url = buildSdkHomeDownloadUrl(params);
+  const body = parseJsonResponseEnvelope(await fetchJson(url, params.signal), "sdk-home getDownLoadUrl");
+  if (typeof body.data !== "string" || !body.data.trim()) {
+    throw new Error("sdk-home getDownLoadUrl response does not contain a download URL in data");
+  }
+  return { url, sdkZipUrl: body.data };
+}
+
+export function resolveIosSdkZipFileName(version: string): string {
+  return `topSDK-ios--V${version}.zip`;
+}
+
+export function resolveIosSdkRootFromDirectory(bundledDir: string): string {
+  if (!fs.existsSync(bundledDir)) {
+    throw new Error(`iOS SDK not found at ${bundledDir} (expected sdk/ and plugins/ inside).`);
+  }
+  if (fs.existsSync(path.join(bundledDir, "sdk")) && fs.existsSync(path.join(bundledDir, "plugins"))) {
+    return bundledDir;
+  }
+  const children = fs
+    .readdirSync(bundledDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && !d.name.startsWith("."))
+    .map((d) => path.join(bundledDir, d.name));
+  for (const dir of children) {
+    if (fs.existsSync(path.join(dir, "sdk")) && fs.existsSync(path.join(dir, "plugins"))) {
+      return dir;
+    }
+  }
+  throw new Error(`iOS SDK layout invalid under ${bundledDir}: need sdk/ + plugins/ at top level or under one version directory.`);
+}
+
+export async function downloadBinaryFile(url: string, absPath: string, signal?: AbortSignal): Promise<void> {
+  let res: Response;
+  try {
+    res = await fetch(url, { redirect: "follow", signal });
+  } catch (e) {
+    const cause = e instanceof Error && "cause" in e && e.cause instanceof Error ? e.cause.message : null;
+    const detail = cause && cause !== (e instanceof Error ? e.message : String(e)) ? ` (${cause})` : "";
+    throw new Error(`GET ${url} failed: ${e instanceof Error ? e.message : String(e)}${detail}`);
+  }
+  if (!res.ok) {
+    throw new Error(`GET ${url} failed: HTTP ${res.status} ${res.statusText}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, buf);
+}
+
+export async function extractZip(zipPath: string, destDir: string): Promise<void> {
+  fs.mkdirSync(destDir, { recursive: true });
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn("unzip", ["-q", "-o", zipPath, "-d", destDir], { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (e) => reject(new Error(`failed to start unzip: ${e.message}`)));
+    child.on("close", (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        const detail = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+        reject(new Error(`unzip failed with exit code ${code}${detail ? `: ${detail}` : ""}`));
+      }
+    });
+  });
+}
+
+export async function downloadIosSdkToBundled(
+  packageRoot: string,
+  options: DownloadIosSdkOptions = {}
+): Promise<DownloadIosSdkResult> {
+  const baseUrl = options.baseUrl || defaultSdkHomeApiBaseUrl;
+  const packageType = options.packageType || DEFAULT_IOS_SDK_PACKAGE_TYPE;
+  const plugins = pluginsToList(options.plugins);
+  const versionResult = options.version
+    ? { url: buildSdkHomeVersionUrl(baseUrl), ios: { ver: options.version, date: "" } }
+    : await fetchSdkHomeIosVersion({ baseUrl, signal: options.signal });
+  const version = versionResult.ios.ver;
+  const downloadResult = await fetchSdkHomeIosDownloadUrl({
+    baseUrl,
+    version,
+    plugins,
+    packageType,
+    signal: options.signal,
+  });
+  const extractDir = path.resolve(options.outputDir || defaultBundledIosSdkRoot(packageRoot));
+  const zipPath = path.join(extractDir, resolveIosSdkZipFileName(version));
+
+  await downloadBinaryFile(downloadResult.sdkZipUrl, zipPath, options.signal);
+  await extractZip(zipPath, extractDir);
+  const iosConfigPath = syncMeetSdkIosVersionToConfig({
+    packageRoot,
+    version,
+    date: versionResult.ios.date,
+    packageType,
+    plugins,
+  });
+
+  return {
+    version,
+    versionDate: versionResult.ios.date,
+    versionUrl: versionResult.url,
+    downloadApiUrl: downloadResult.url,
+    sdkZipUrl: downloadResult.sdkZipUrl,
+    zipPath,
+    extractDir,
+    resolvedSdkRoot: resolveIosSdkRootFromDirectory(extractDir),
+    iosConfigPath,
+  };
+}

package/src/remote/topsdkDownloadSdkConfig.ts

@@ -0,0 +1,93 @@
+import { topsdkMd5Base64Sign } from "./topsdkSign.js";
+import { defaultTopSdkBaseUrl, type TopSdkApiEnv } from "./topsdkGetSdkConfig.js";
+
+export { defaultTopSdkBaseUrl, type TopSdkApiEnv };
+
+const DOWNLOAD_SDK_CONFIG_PATH = "console/openSDK/downloadSDKConfig";
+
+function joinBaseAndPath(baseUrl: string, path: string): URL {
+  const base = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+  return new URL(path, base);
+}
+
+/**
+ * GET `console/openSDK/downloadSDKConfig` — same sign as `getSDKConfig`:
+ * sign = base64(md5(appId + appSecret + timestampMillis)), timestamp within 60s.
+ */
+export function buildTopSdkDownloadSdkConfigUrl(params: {
+  baseUrl: string;
+  appId: string;
+  appSecret: string;
+  channelType: string;
+  timestampMillis?: number;
+}): { url: string; timestampMillis: number } {
+  const timestampMillis = params.timestampMillis ?? Date.now();
+  const sign = topsdkMd5Base64Sign(params.appId, params.appSecret, timestampMillis);
+  const u = joinBaseAndPath(params.baseUrl, DOWNLOAD_SDK_CONFIG_PATH);
+  u.searchParams.set("appId", params.appId);
+  u.searchParams.set("channelType", params.channelType);
+  u.searchParams.set("sign", sign);
+  u.searchParams.set("timestamp", String(timestampMillis));
+  return { url: u.toString(), timestampMillis };
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** gp-sdk error envelope when the handler throws before streaming JSON. */
+export function parseTopSdkApiErrorBody(body: unknown): string | null {
+  if (!isRecord(body)) return null;
+  const code = body.code;
+  if (code === undefined || code === null) return null;
+  if (Number(code) === 200) return null;
+  const message = typeof body.message === "string" ? body.message : typeof body.error === "string" ? body.error : JSON.stringify(body);
+  return `TOPSDK API error (code=${code}): ${message}`;
+}
+
+export async function fetchTopSdkDownloadSdkConfig(params: {
+  baseUrl: string;
+  appId: string;
+  appSecret: string;
+  channelType: string;
+  timestampMillis?: number;
+  signal?: AbortSignal;
+}): Promise<{ url: string; body: unknown; text: string }> {
+  const { url } = buildTopSdkDownloadSdkConfigUrl(params);
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      redirect: "follow",
+      signal: params.signal,
+      headers: { Accept: "application/json" },
+    });
+  } catch (e) {
+    const cause = e instanceof Error && "cause" in e && e.cause instanceof Error ? e.cause.message : null;
+    const detail = cause && cause !== (e instanceof Error ? e.message : String(e)) ? ` (${cause})` : "";
+    throw new Error(`GET ${url} failed: ${e instanceof Error ? e.message : String(e)}${detail}`);
+  }
+  if (!res.ok) {
+    let detail = "";
+    try {
+      const text = await res.text();
+      if (text.trim()) {
+        detail = `: ${text.trim().slice(0, 1000)}`;
+      }
+    } catch {
+      // Keep the original status-only error if the response body cannot be read.
+    }
+    throw new Error(`GET ${url} failed: HTTP ${res.status}${detail}`);
+  }
+  const text = await res.text();
+  let body: unknown;
+  try {
+    body = JSON.parse(text) as unknown;
+  } catch {
+    throw new Error("Remote response is not valid JSON");
+  }
+  const apiErr = parseTopSdkApiErrorBody(body);
+  if (apiErr) {
+    throw new Error(apiErr);
+  }
+  return { url, body, text };
+}