@saltcorn/mobile-builder 1.6.3-beta.1 → 1.7.0-alpha.1

package/dist/utils/common-build-utils.js

@@ -20,9 +20,10 @@ exports.prepareSplashIcon = prepareSplashIcon;
 exports.prepareExportOptionsPlist = prepareExportOptionsPlist;
 exports.modifyInfoPlist = modifyInfoPlist;
 exports.writeEntitlementsPlist = writeEntitlementsPlist;
-exports.runAddEntitlementsScript = runAddEntitlementsScript;
+exports.injectCodeSignEntitlements = injectCodeSignEntitlements;
 exports.copyShareExtFiles = copyShareExtFiles;
 exports.modifyShareViewController = modifyShareViewController;
+exports.createShareExtensionTarget = createShareExtensionTarget;
 exports.modifyAppDelegate = modifyAppDelegate;
 exports.writePrivacyInfo = writePrivacyInfo;
 exports.copyServerFiles = copyServerFiles;
@@ -76,6 +77,7 @@ function prepareBuildDir(buildDir, templateDir, pushEnabled, backgroundFetchEnab
         "@capacitor/core@7.4.5",
         "@capacitor/assets@3.0.5",
         "@capacitor/filesystem@7.1.6",
+        "@capacitor/file-transfer@1.0.12",
         "@capacitor/camera@7.0.3",
         "@capacitor/network@7.0.3",
         "@capacitor-community/sqlite@7.0.3",
@@ -107,6 +109,11 @@ function prepareBuildDir(buildDir, templateDir, pushEnabled, backgroundFetchEnab
         maxBuffer: 1024 * 1024 * 10,
     });
 }
+/**
+ * Write `capacitor.config.ts` into the build directory.
+ * @param buildDir directory where the app will be built
+ * @param config capacitor build settings
+ */
 function writeCapacitorConfig(buildDir, config) {
     const cfgFile = (0, path_1.join)(buildDir, "capacitor.config.ts");
     const content = `
@@ -116,9 +123,8 @@ const config: CapacitorConfig  = {
   appId: '${config.appId ? config.appId : "com.saltcorn.mobile.app"}',
   appName: '${config.appName ? config.appName : "SaltcornMobileApp"}',
   webDir: "www",
-  ios: {
-    scheme: "SaltcornMobileApp",
-  },
+  // ios.limitsNavigationsToAppBoundDomains was dropped - it caused noisy
+  // script-injection warnings and wasn't needed for the cookie fix to work.
   android: {
     buildOptions: {
       ${config.keystorePath && config.buildType === "release"
@@ -130,15 +136,21 @@ const config: CapacitorConfig  = {
         : ""}
       releaseType: '${config.buildType === "release" ? "AAB" : "APK"}',
     },
-    ${config.unsecureNetwork ? "allowMixedContent: true," : ""}
   },
-  ${config.unsecureNetwork
-        ? `server: {
-    cleartext: true,
-    androidScheme: 'http',
-  },`
-        : ""}
+  server: {
+    // App's origin on iOS - must match MOBILE_APP_ORIGINS in server/app.js.
+    iosScheme: 'SaltcornMobileApp',
+  },
   plugins: {
+    // Needed together with WKAppBoundDomains (see modifyInfoPlist) to
+    // exempt the remote server's session cookie from iOS's third-party
+    // cookie blocking.
+    CapacitorHttp: {
+      enabled: true,
+    },
+    CapacitorCookies: {
+      enabled: true,
+    },
     CapacitorSQLite: {
       iosDatabaseLocation: 'Library/CapacitorDatabase',
       iosIsEncryption: true,
@@ -165,6 +177,11 @@ const config: CapacitorConfig  = {
 export default config;`;
     (0, fs_extra_1.writeFileSync)(cfgFile, content);
 }
+/**
+ * Copy the app icon into all required asset slots (icon, splash variants).
+ * @param buildDir directory where the app will be built
+ * @param appIcon path to the source PNG
+ */
 function prepAppIcon(buildDir, appIcon) {
     for (const icon of [
         "icon-only",
@@ -178,6 +195,11 @@ function prepAppIcon(buildDir, appIcon) {
         });
     }
 }
+/**
+ * Returns the Android permissions required for the build.
+ * @param allowFCM include FCM/push notification permissions
+ * @returns array of Android permission strings
+ */
 function androidPermissions(allowFCM) {
     const state = (0, state_1.getState)();
     if (!state)
@@ -199,6 +221,10 @@ function androidPermissions(allowFCM) {
     }
     return Array.from(permissions);
 }
+/**
+ * Returns the Android hardware features required for the build.
+ * @returns array of Android feature strings
+ */
 function androidFeatures() {
     const state = (0, state_1.getState)();
     if (!state)
@@ -211,7 +237,14 @@ function androidFeatures() {
     }
     return Array.from(features);
 }
-async function modifyAndroidManifest(buildDir, allowShareTo, allowFCM, allowAuthIntent, allowClearTextTraffic) {
+/**
+ * Patch `AndroidManifest.xml` with permissions, features, and optional intents.
+ * @param buildDir directory where the app will be built
+ * @param allowShareTo add share-to intent filter
+ * @param allowFCM add FCM push notification support
+ * @param allowAuthIntent add authentication intent
+ */
+async function modifyAndroidManifest(buildDir, allowShareTo, allowFCM, allowAuthIntent) {
     console.log("modifyAndroidManifest");
     try {
         const androidManifest = (0, path_1.join)(buildDir, "android", "app", "src", "main", "AndroidManifest.xml");
@@ -229,9 +262,6 @@ async function modifyAndroidManifest(buildDir, allowShareTo, allowFCM, allowAuth
             "android:fullBackupContent": "false",
             "android:dataExtractionRules": "@xml/data_extraction_rules",
             "android:networkSecurityConfig": "@xml/network_security_config",
-            ...(allowClearTextTraffic
-                ? { "android:usesCleartextTraffic": "true" }
-                : {}),
         };
         if (allowFCM) {
             parsed.manifest.application[0]["meta-data"] = [
@@ -302,6 +332,11 @@ async function modifyAndroidManifest(buildDir, allowShareTo, allowFCM, allowAuth
         console.log(`Unable to modify the AndroidManifest.xml: ${error.message ? error.message : "Unknown error"}`);
     }
 }
+/**
+ * Returns true if any of the included plugins exposes an authentication method.
+ * @param plugins list of included plugin names
+ * @returns whether an auth method is available
+ */
 function hasAuthMethod(plugins) {
     const state = (0, state_1.getState)();
     for (const pluginName of plugins) {
@@ -311,6 +346,10 @@ function hasAuthMethod(plugins) {
     }
     return false;
 }
+/**
+ * Write the Android data extraction rules XML (excludes app data from backups).
+ * @param buildDir directory where the app will be built
+ */
 function writeDataExtractionRules(buildDir) {
     console.log("writeDataExtractionRules");
     const dataExtractionRules = (0, path_1.join)(buildDir, "android", "app", "src", "main", "res", "xml", "data_extraction_rules.xml");
@@ -331,6 +370,11 @@ function writeDataExtractionRules(buildDir) {
 </data-extraction-rules>
 `);
 }
+/**
+ * Copy the pre-populated SQLite database into the platform asset directories.
+ * @param buildDir directory where the app will be built
+ * @param platforms target platforms (`"android"` / `"ios"`)
+ */
 function copyPrepopulatedDb(buildDir, platforms) {
     console.log("copyPrepopulatedDb", buildDir, platforms);
     if (platforms.includes("android")) {
@@ -340,6 +384,11 @@ function copyPrepopulatedDb(buildDir, platforms) {
         (0, fs_extra_1.copySync)((0, path_1.join)(buildDir, "www", "scdb.sqlite"), (0, path_1.join)(buildDir, "ios", "App", "App", "public", "assets", "databases", "prepopulated.db"));
     }
 }
+/**
+ * Extract the bare domain name from a URL (strips protocol, port, trailing slash).
+ * @param url full server URL
+ * @returns domain string
+ */
 function extractDomain(url) {
     let domain = url;
     if (domain.startsWith("http://"))
@@ -352,17 +401,26 @@ function extractDomain(url) {
         domain = domain.substring(0, domain.indexOf(":"));
     return domain;
 }
-function writeNetworkSecurityConfig(buildDir, serverPath) {
+/**
+ * Write the Android network security config. HTTPS is required, so this is
+ * always the restrictive (no cleartext) version.
+ * @param buildDir directory where the app will be built
+ */
+function writeNetworkSecurityConfig(buildDir) {
     console.log("writeNetworkSecurityConfig");
     const networkSecurityConfig = (0, path_1.join)(buildDir, "android", "app", "src", "main", "res", "xml", "network_security_config.xml");
-    (0, fs_extra_1.writeFileSync)(networkSecurityConfig, `<?xml version="1.0" encoding="utf-8"?>
+    const content = `<?xml version="1.0" encoding="utf-8"?>
 <network-security-config>
-  <domain-config cleartextTrafficPermitted="true">
-    <domain includeSubdomains="true">${extractDomain(serverPath)}</domain>
-  </domain-config>
-</network-security-config>
-  `);
+  <base-config cleartextTrafficPermitted="false" />
+</network-security-config>`;
+    (0, fs_extra_1.writeFileSync)(networkSecurityConfig, content);
 }
+/**
+ *
+ * Patch `config.xml` with app name, app ID, and version.
+ * @param buildDir directory where the app will be built
+ * @param config object with optional `appName`, `appId`, and `appVersion` fields
+ */
 async function modifyConfigXml(buildDir, config) {
     try {
         const configXml = (0, path_1.join)(buildDir, "config.xml");
@@ -425,6 +483,11 @@ async function prepareSplashIcon(buildDir, splashIcon, platforms) {
         console.log(`Unable to set the splash icon '${splashIcon}': ${error.message ? error.message : "Unknown error"}`);
     }
 }
+/**
+ * Generate the iOS `AppIcon.appiconset` with all required sizes.
+ * @param buildDir directory where the app will be built
+ * @param appIcon path to the source PNG
+ */
 async function prepareAppIconSet(buildDir, appIcon) {
     console.log("prepareAppIconSet", buildDir, appIcon);
     const dir = (0, path_1.join)(buildDir, "AppIcon.appiconset");
@@ -463,6 +526,10 @@ async function prepareAppIconSet(buildDir, appIcon) {
         console.log(`Unable to generate appicon set for '${appIcon}': ${error.message ? error.message : "Unknown error"}`);
     }
 }
+/**
+ * Write `ExportOptions.plist` used by `xcodebuild -exportArchive`.
+ * @param param0 buildDir, appId, and iOS provisioning parameters
+ */
 function prepareExportOptionsPlist({ buildDir, appId, iosParams }) {
     console.log("prepareExportOptionsPlist", buildDir, appId, iosParams);
     const buildShareExtBloock = () => {
@@ -474,12 +541,13 @@ function prepareExportOptionsPlist({ buildDir, appId, iosParams }) {
             <string>${iosParams.shareExtensionProvisioningProfile.guuid}</string>`;
     };
     try {
+        const method = iosParams.isAdHoc ? "ad-hoc" : "app-store-connect";
         (0, fs_extra_1.writeFileSync)((0, path_1.join)(buildDir, "ExportOptions.plist"), `<?xml version="1.0" encoding="UTF-8"?>
       <!DOCTYPE plist PUBLIC "~//Apple/DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
       <plist version="1.0">
         <dict>
           <key>method</key>
-          <string>app-store-connect</string>
+          <string>${method}</string>
           <key>provisioningProfiles</key>
           <dict>          
             <key>${appId}</key>
@@ -494,26 +562,52 @@ function prepareExportOptionsPlist({ buildDir, appId, iosParams }) {
         console.log(`Unable to write the ExportOptionsPlist file: ${error.message ? error.message : "Unknown error"}`);
     }
 }
-function modifyInfoPlist(buildDir, allowShareTo, backgroundSyncEnabled, pushSyncEnabled, allowClearTextTraffic) {
+/**
+ * Patch `Info.plist` with background modes, usage descriptions, and optional URL schemes.
+ * @param buildDir directory where the app will be built
+ * @param allowShareTo add URL scheme for share-to integration
+ * @param backgroundSyncEnabled background sync task is scheduled
+ * @param pushSyncEnabled add remote-notification background mode
+ * @param backgroundFetchEnabled background.js is included (sync or heartbeat configured)
+ * @param serverURL server URL, added to WKAppBoundDomains for the iOS cookie
+ * fix - changing servers (e.g. a new ngrok URL) needs a rebuild to apply.
+ */
+function modifyInfoPlist(buildDir, allowShareTo, backgroundSyncEnabled, pushSyncEnabled, backgroundFetchEnabled = false, serverURL) {
     const infoPlist = (0, path_1.join)(buildDir, "ios", "App", "App", "Info.plist");
     const content = (0, fs_extra_1.readFileSync)(infoPlist, "utf8");
+    let appBoundHostname;
+    if (serverURL) {
+        try {
+            appBoundHostname = new URL(serverURL).hostname;
+        }
+        catch {
+            // invalid/missing URL - skip WKAppBoundDomains rather than write a broken plist
+        }
+    }
+    const backgroundModes = [
+        ...(backgroundFetchEnabled ? ["fetch", "processing"] : []),
+        ...(pushSyncEnabled ? ["remote-notification"] : []),
+    ];
+    const taskIds = [
+        "com.transistorsoft.fetch",
+        ...(backgroundSyncEnabled ? ["com.transistorsoft.background_sync"] : []),
+        ...(backgroundFetchEnabled
+            ? ["com.transistorsoft.push_sync_heartbeat"]
+            : []),
+    ];
     const newCfgs = `
-  ${backgroundSyncEnabled
+  ${backgroundFetchEnabled
         ? `<key>BGTaskSchedulerPermittedIdentifiers</key>
   <array>
-    <string>com.transistorsoft.fetch</string>
-  </array>
-  <key>UIBackgroundModes</key>
-  <array>
-    <string>fetch</string>
+    ${taskIds.map((id) => `<string>${id}</string>`).join("\n    ")}
   </array>
   `
         : ""}
 
-  ${pushSyncEnabled
+  ${backgroundModes.length > 0
         ? `<key>UIBackgroundModes</key>
   <array>
-    <string>remote-notification</string>
+    ${backgroundModes.map((m) => `<string>${m}</string>`).join("\n    ")}
   </array>
   `
         : ""}
@@ -531,6 +625,12 @@ function modifyInfoPlist(buildDir, allowShareTo, backgroundSyncEnabled, pushSync
   <true/>
   <key>LSSupportsOpeningDocumentsInPlace</key>
   <true/>
+  ${appBoundHostname
+        ? `<key>WKAppBoundDomains</key>
+  <array>
+    <string>${appBoundHostname}</string>
+  </array>`
+        : ""}
   ${allowShareTo
         ? `<key>CFBundleURLTypes</key>
   <array>
@@ -546,29 +646,38 @@ function modifyInfoPlist(buildDir, allowShareTo, backgroundSyncEnabled, pushSync
     </dict>
   </array>`
         : ""}
-  ${allowClearTextTraffic
-        ? `<key>NSAppTransportSecurity</key>
-  <dict>
-    <key>NSAllowsArbitraryLoads</key>
-    <true/>
-  </dict>`
-        : ""}
 `;
     // add newCfgs after the first <dict> tag
     const newContent = content.replace(/<dict>/, `<dict>${newCfgs}`);
     (0, fs_extra_1.writeFileSync)(infoPlist, newContent, "utf8");
 }
-function writeEntitlementsPlist(buildDir) {
+/**
+ * Write `App.entitlements` with the optional APNs environment and app group.
+ * @param buildDir directory where the app will be built
+ * @param buildType `"debug"` → development APNs, `"release"` → production APNs
+ * @param pushSync include the APNs environment entitlement
+ * @param appGroupId optional app group ID for share extension data sharing
+ */
+function writeEntitlementsPlist(buildDir, buildType, pushSync, appGroupId) {
     const file = (0, path_1.join)(buildDir, "ios", "App", "App", "App.entitlements");
+    const apsEnv = buildType === "release" ? "production" : "development";
+    const apsEnvEntry = pushSync
+        ? `    <key>aps-environment</key>
+    <string>${apsEnv}</string>`
+        : "";
+    const appGroupsEntry = appGroupId
+        ? `    <key>com.apple.security.application-groups</key>
+    <array>
+        <string>${appGroupId}</string>
+    </array>`
+        : "";
     try {
         (0, fs_extra_1.writeFileSync)(file, `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
-    <key>aps-environment</key>
-    <string>production</string>
-    <key>com.apple.security.application-groups</key>
-    <array />
+${apsEnvEntry}
+${appGroupsEntry}
 </dict>
 </plist>`);
     }
@@ -576,23 +685,45 @@ function writeEntitlementsPlist(buildDir) {
         console.log(`Unable to write the Entitlements plist file: ${error.message ? error.message : "Unknown error"}`);
     }
 }
-function runAddEntitlementsScript(buildDir) {
+/**
+ * Inject `CODE_SIGN_ENTITLEMENTS` into `project.pbxproj` for the App target.
+ * Uses `INFOPLIST_FILE = App/Info.plist;` as an anchor (unique to the App target).
+ * Idempotent — skips if the key is already present.
+ * @param buildDir directory where the app will be built
+ */
+function injectCodeSignEntitlements(buildDir) {
+    const pbxprojPath = (0, path_1.join)(buildDir, "ios", "App", "App.xcodeproj", "project.pbxproj");
     try {
-        const result = (0, child_process_1.spawnSync)("ruby", ["add_entitlements.rb"], {
-            cwd: buildDir,
-        });
-        console.log(result.output.toString());
+        let content = (0, fs_extra_1.readFileSync)(pbxprojPath, "utf8");
+        // check for this exact insertion, not just any CODE_SIGN_ENTITLEMENTS -
+        // the share-ext target sets its own, which isn't the same thing
+        if (content.includes("CODE_SIGN_ENTITLEMENTS = App/App.entitlements;")) {
+            console.log("CODE_SIGN_ENTITLEMENTS already set in project.pbxproj");
+            return;
+        }
+        content = content.replaceAll("INFOPLIST_FILE = App/Info.plist;", `CODE_SIGN_ENTITLEMENTS = App/App.entitlements;\n\t\t\t\tINFOPLIST_FILE = App/Info.plist;`);
+        (0, fs_extra_1.writeFileSync)(pbxprojPath, content, "utf8");
+        console.log("CODE_SIGN_ENTITLEMENTS set in project.pbxproj for App target");
     }
     catch (error) {
-        console.log(`Unable to run the add_entitlements.rb script: ${error.message ? error.message : "Unknown error"}`);
+        console.log(`Unable to set CODE_SIGN_ENTITLEMENTS in project.pbxproj: ${error.message ?? "Unknown error"}`);
     }
 }
+/**
+ * Copy share extension source files into the iOS project directory.
+ * @param buildDir directory where the app will be built
+ */
 function copyShareExtFiles(buildDir) {
     const iosAppDir = (0, path_1.join)(buildDir, "ios", "App");
     const sefDir = (0, path_1.join)(buildDir, "share_extension_files");
     (0, fs_extra_1.copySync)((0, path_1.join)(sefDir, "ShareViewController.swift"), (0, path_1.join)(iosAppDir, "share-ext", "ShareViewController.swift"), { overwrite: true });
     (0, fs_extra_1.copySync)((0, path_1.join)(sefDir, "Info.plist"), (0, path_1.join)(iosAppDir, "share-ext", "Info.plist"), { overwrite: true });
 }
+/**
+ * Replace `YOUR_APP_GROUP_ID` placeholder in `ShareViewController.swift`.
+ * @param buildDir directory where the app will be built
+ * @param groupId app group identifier
+ */
 function modifyShareViewController(buildDir, groupId) {
     const shareVCFile = (0, path_1.join)(buildDir, "ios", "App", "share-ext", "ShareViewController.swift");
     let content = (0, fs_extra_1.readFileSync)(shareVCFile, "utf8");
@@ -600,15 +731,68 @@ function modifyShareViewController(buildDir, groupId) {
     content = content.replace(/YOUR_APP_GROUP_ID/g, groupId);
     (0, fs_extra_1.writeFileSync)(shareVCFile, content, "utf8");
 }
-function modifyAppDelegate(buildDir, backgroundSyncEnabled, pushSyncEnabled, allowShareTo) {
+/**
+ * Write the entitlements plist for the share extension target (app group
+ * only - no APNs entry, extensions don't receive push notifications).
+ * @param buildDir directory where the app will be built
+ * @param appGroupId app group ID shared with the main app
+ * @returns path to the entitlements file, relative to `ios/App`
+ */
+function writeShareExtEntitlementsPlist(buildDir, appGroupId) {
+    const relPath = (0, path_1.join)("share-ext", "ShareExtension.entitlements");
+    const file = (0, path_1.join)(buildDir, "ios", "App", relPath);
+    (0, fs_extra_1.writeFileSync)(file, `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>com.apple.security.application-groups</key>
+    <array>
+        <string>${appGroupId}</string>
+    </array>
+</dict>
+</plist>`);
+    return relPath;
+}
+/**
+ * Add a "share-ext" Share Extension target to `App.xcodeproj`, so the app
+ * can be built with iOS share-to support without ever opening Xcode.
+ * @param buildDir directory where the app will be built
+ * @param appId main app's bundle id - the extension's is `${appId}.share-ext`
+ * @param appGroupId optional app group ID, wired into a matching
+ *   entitlements plist for the new target
+ */
+function createShareExtensionTarget(buildDir, appId, appGroupId) {
+    const iosAppDir = (0, path_1.join)(buildDir, "ios", "App");
+    const projectPath = (0, path_1.join)(iosAppDir, "App.xcodeproj");
+    const entitlementsRelPath = appGroupId
+        ? writeShareExtEntitlementsPlist(buildDir, appGroupId)
+        : undefined;
+    const scriptPath = (0, path_1.join)(__dirname, "xcode", "create_share_extension.rb");
+    const args = [scriptPath, projectPath, `${appId}.share-ext`];
+    if (entitlementsRelPath)
+        args.push(entitlementsRelPath);
+    const result = (0, child_process_1.spawnSync)("ruby", args, { cwd: iosAppDir });
+    if (result.status !== 0) {
+        throw new Error(`Unable to create the share extension target: ${result.stderr?.toString() || result.error?.message || "unknown error"}`);
+    }
+    console.log(result.stdout?.toString());
+}
+/**
+ * Patch `AppDelegate.swift` to register background tasks and push handlers.
+ * @param buildDir directory where the app will be built
+ * @param pushSyncEnabled register remote-notification handler
+ * @param allowShareTo register URL scheme handler for share-to
+ * @param backgroundFetchEnabled initialize TSBackgroundFetch (sync or heartbeat)
+ */
+function modifyAppDelegate(buildDir, pushSyncEnabled, allowShareTo, backgroundFetchEnabled = false) {
     const appDelegateFile = (0, path_1.join)(buildDir, "ios", "App", "App", "AppDelegate.swift");
     let content = (0, fs_extra_1.readFileSync)(appDelegateFile, "utf8");
     // modify cusomization point after application launch
     content = content.replace(/func application\(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: \[UIApplication.LaunchOptionsKey: Any\]\?\) -> Bool {/, `func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
         // Override point for customization after application launch.
 
-       
-       ${backgroundSyncEnabled
+
+       ${backgroundFetchEnabled
         ? `// [capacitor-background-fetch]
        let fetchManager = TSBackgroundFetch.sharedInstance();
        fetchManager?.didFinishLaunching();`
@@ -616,7 +800,7 @@ function modifyAppDelegate(buildDir, backgroundSyncEnabled, pushSyncEnabled, all
 
        self.window?.rootViewController?.navigationController?.interactivePopGestureRecognizer?.isEnabled = false;
 `);
-    if (backgroundSyncEnabled) {
+    if (backgroundFetchEnabled) {
         // add "import TSBackgroundFetch" before "@UIApplicationMain"
         content = content.replace(/@UIApplicationMain/, `import TSBackgroundFetch
 
@@ -729,7 +913,7 @@ function modifyAppDelegate(buildDir, backgroundSyncEnabled, pushSyncEnabled, all
     }
     (0, fs_extra_1.writeFileSync)(appDelegateFile, content, "utf8");
 }
-function writePrivacyInfo(buildDir, backgroundSyncEnabled) {
+function writePrivacyInfo(buildDir, backgroundFetchEnabled) {
     const infoFile = (0, path_1.join)(buildDir, "ios", "App", "PrivacyInfo.xcprivacy");
     const content = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -747,7 +931,7 @@ function writePrivacyInfo(buildDir, backgroundSyncEnabled) {
         </array>
       </dict>
 
-      ${backgroundSyncEnabled
+      ${backgroundFetchEnabled
         ? `
       <!-- [1] background_fetch: UserDefaults -->
       <dict>
@@ -776,7 +960,7 @@ function copyServerFiles(buildDir) {
     if (!(0, fs_extra_1.existsSync)(assetsDst)) {
         (0, fs_extra_1.mkdirSync)(assetsDst, { recursive: true });
     }
-    const serverRoot = (0, path_1.join)(require.resolve("@saltcorn/server"), "..");
+    const serverRoot = (0, path_1.join)(require.resolve("@saltcorn/server/package.json"), "..");
     const srcPrefix = (0, path_1.join)(serverRoot, "public");
     const srcAssests = [
         "jquery-3.6.0.min.js",
@@ -835,7 +1019,7 @@ async function copySiteLogo(buildDir) {
  * create a cfg file, the app use this configs
  * @param param0
  */
-function writeCfgFile({ buildDir, entryPoint, entryPointType, serverPath, synchedTables, tenantAppName, autoPublicLogin, showContinueAsPublicUser, allowOfflineMode, syncOnReconnect, syncOnAppResume, pushSync, syncInterval, allowShareTo, }) {
+function writeCfgFile({ buildDir, entryPoint, entryPointType, serverPath, synchedTables, tenantAppName, autoPublicLogin, showContinueAsPublicUser, allowOfflineMode, syncOnReconnect, syncOnAppResume, pushSync, syncInterval, pushSyncHeartbeatInterval, allowShareTo, apnsEnvironment, }) {
     const wwwDir = (0, path_1.join)(buildDir, "www");
     let cfg = {
         version_tag: index_1.default.connectObj.version_tag,
@@ -851,7 +1035,9 @@ function writeCfgFile({ buildDir, entryPoint, entryPointType, serverPath, synche
         syncOnAppResume,
         pushSync,
         syncInterval,
+        pushSyncHeartbeatInterval,
         allowShareTo,
+        apnsEnvironment,
     };
     if (entryPointType !== "byrole") {
         cfg.entry_point = `get/${entryPointType === "pagegroup" ? "page" : entryPointType}/${entryPoint}`;
@@ -975,7 +1161,7 @@ async function buildTablesFile(buildDir, includedPlugins) {
  * @param buildDir directory where the app will be build
  */
 function copyTranslationFiles(buildDir) {
-    const localesDir = (0, path_1.join)(require.resolve("@saltcorn/server"), "..", "locales");
+    const localesDir = (0, path_1.join)(require.resolve("@saltcorn/server/package.json"), "..", "locales");
     (0, fs_extra_1.copySync)(localesDir, (0, path_1.join)(buildDir, "www", "data", "locales"));
 }
 /**
@@ -1037,7 +1223,7 @@ async function prepareSplashPage(buildDir, pageName, serverUrl, tenantAppName, u
             title: page.title,
             body: !contents
                 ? { above: [] }
-                : contents.above
+                : "above" in contents
                     ? contents
                     : { above: [contents] },
             alerts: [],
@@ -1067,6 +1253,13 @@ async function prepareSplashPage(buildDir, pageName, serverUrl, tenantAppName, u
         console.log(error);
     }
 }
+/**
+ * Write the iOS `Podfile` and run `pod install`.
+ * @param buildDir directory where the app will be built
+ * @param hasPush include push notification pods
+ * @param hasBackgroundFetch include background fetch pod
+ * @param hasSilentPush include silent-notifications pod
+ */
 function writePodfile(buildDir, hasPush, hasBackgroundFetch, hasSilentPush) {
     const state = (0, state_1.getState)();
     let hasGeolocation = false;
@@ -1095,7 +1288,10 @@ function writePodfile(buildDir, hasPush, hasBackgroundFetch, hasSilentPush) {
     pod 'CapacitorCommunitySqlite', :path => '../../node_modules/@capacitor-community/sqlite'
     pod 'CapacitorCamera', :path => '../../node_modules/@capacitor/camera'
     pod 'CapacitorFilesystem', :path => '../../node_modules/@capacitor/filesystem'
-    ${hasGeolocation ? `pod 'CapacitorGeolocation', :path => '../../node_modules/@capacitor/geolocation'` : ""}
+    pod 'CapacitorFileTransfer', :path => '../../node_modules/@capacitor/file-transfer'
+    ${hasGeolocation
+        ? `pod 'CapacitorGeolocation', :path => '../../node_modules/@capacitor/geolocation'`
+        : ""}
     pod 'CapacitorNetwork', :path => '../../node_modules/@capacitor/network'
     pod 'CapacitorScreenOrientation', :path => '../../node_modules/@capacitor/screen-orientation'
     pod 'SendIntent', :path => '../../node_modules/send-intent'
@@ -1105,8 +1301,12 @@ function writePodfile(buildDir, hasPush, hasBackgroundFetch, hasSilentPush) {
         ? `pod 'CapacitorPushNotifications', :path => '../../node_modules/@capacitor/push-notifications'
     pod 'CapacitorDevice', :path => '../../node_modules/@capacitor/device'`
         : ""}
-    ${hasSilentPush ? `pod 'CapacitorPluginSilentNotifications', :path => '../../node_modules/capacitor-plugin-silent-notifications'` : ""}
-    ${hasBackgroundFetch ? `pod 'TransistorsoftCapacitorBackgroundFetch', :path => '../../node_modules/@transistorsoft/capacitor-background-fetch'` : ""}
+    ${hasSilentPush
+        ? `pod 'CapacitorPluginSilentNotifications', :path => '../../node_modules/capacitor-plugin-silent-notifications'`
+        : ""}
+    ${hasBackgroundFetch
+        ? `pod 'TransistorsoftCapacitorBackgroundFetch', :path => '../../node_modules/@transistorsoft/capacitor-background-fetch'`
+        : ""}
   end
   
   target 'App' do
@@ -1167,6 +1367,11 @@ function modifyXcodeProjectFile(buildDir, appVersion, iosCfg) {
     fileContent = fileContent.replaceAll(/MARKETING_VERSION = 1.0;/g, `MARKETING_VERSION = ${appVersion};`);
     (0, fs_extra_1.writeFileSync)(projectFile, fileContent, "utf8");
 }
+/**
+ * Convert a semver string to an Android integer version code (`major*1e6 + minor*1e3 + patch`).
+ * @param appVersion semver string e.g. `"1.2.3"`
+ * @returns integer version code
+ */
 function generateAndroidVersionCode(appVersion) {
     if (!/^\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(appVersion) || appVersion === "0.0.0")
         throw new Error(`Invalid app version '${appVersion}'`);
@@ -1175,6 +1380,12 @@ function generateAndroidVersionCode(appVersion) {
         parseInt(parts[1]) * 1000 +
         parseInt(parts[2]));
 }
+/**
+ * Patch `build.gradle` with the app version and optional keystore signing config.
+ * @param buildDir directory where the app will be built
+ * @param appVersion semver string used for `versionName` and `versionCode`
+ * @param keyStoreData signing credentials; omit for unsigned debug builds
+ */
 function modifyGradleConfig(buildDir, appVersion, keyStoreData) {
     console.log("modifyGradleConfig");
     const gradleFile = (0, path_1.join)(buildDir, "android", "app", "build.gradle");