feat(ww): Support appID, appName, and output folder (#408)

* feat(web-wrapper): Support appID, appName, and output folder configuration

* output fix

* Update build.mjs

* add links for publishing instructions

* Update MainActivity.kt.handlebars

* Update Config.kt.handlebars

* Update build.gradle.handlebars

* switch from entry domain to entry url

* absolute file path

* oops!

* space

* missed a spot

* feedback

* positional required arguments

* fixes

Author: daniellacosse

x/examples/website-wrapper-app/.scripts/build_sdk_mobileproxy.sh renamed to x/examples/website-wrapper-app/.scripts/build_mobileproxy.sh

@@ -16,9 +16,15 @@
 
 PLATFORM="$1"
 TAG="${2:-"x/v0.0.1"}"
+OUTPUT="${3:-output}"
 
-git clone --depth 1 --branch "${TAG}" https://github.com/Jigsaw-Code/outline-sdk.git output/outline-sdk
-cd output/outline-sdk/x
+if [[ "$OUTPUT" = "/" ]] || [[ "$OUTPUT" = "*" ]]; then
+  echo "Error: OUTPUT cannot be '/' or '*'. These are dangerous values."
+  exit 1
+fi
+
+git clone --depth 1 --branch "$TAG" https://github.com/Jigsaw-Code/outline-sdk.git "$OUTPUT/outline-sdk"
+cd "$OUTPUT/outline-sdk/x" || exit
 go build -o "$(pwd)/out/" golang.org/x/mobile/cmd/gomobile golang.org/x/mobile/cmd/gobind
 
 if [ "$PLATFORM" = "ios" ]; then
@@ -33,5 +39,5 @@ else
 fi
 
 cd ../..
-rm -rf "$(pwd)/mobileproxy"
-mv "$(pwd)/outline-sdk/x/out" "$(pwd)/mobileproxy"
+rm -rf "$OUTPUT/mobileproxy"
+mv "$(pwd)/outline-sdk/x/out" "mobileproxy"

x/examples/website-wrapper-app/.scripts/start.mjs

@@ -27,8 +27,12 @@ import chalk from "chalk";
     throw new Error(`Parameter \`--platform\` not provided.`);
   }
 
-  if (!args.entryDomain) {
-    throw new Error(`Parameter \`--entryDomain\` not provided.`);
+  if (!args.entryUrl) {
+    throw new Error(`Parameter \`--entryUrl\` not provided.`);
+  }
+
+  if (args.output) {
+    throw new Error(`Parameter \`output\` is not supported in the 'start' script`);
   }
 
   let proxyLocations = {};

x/examples/website-wrapper-app/README.md

@@ -20,7 +20,7 @@ To verify that your system has the necessary dependencies to generate your web w
 > [!WARNING]
 > You can only build iOS apps on MacOS.
 
-* You will need your site's domain.
+* You will need the url you want to load initially in your app.
 * You will need [go](https://golang.org/) to build the SDK library.
 * You will need [Node.js](https://nodejs.org/en/) for the project setup and web server.
 * You will need [XCode](https://developer.apple.com/xcode/). 
@@ -30,7 +30,7 @@ To verify that your system has the necessary dependencies to generate your web w
 
 ```sh
 npm run reset
-npm run build:project -- --platform=ios --entryDomain="www.example.com"
+npm run build:project -- --platform=ios --entryUrl="https://www.example.com"
 npm run open:ios
 ```
 
@@ -62,16 +62,20 @@ Many sites don't handle their own navigation - if this applies to you, you can r
 * You will need an [ngrok account](https://ngrok.com/), from which you can get your [`--navigatorToken`](https://dashboard.ngrok.com/get-started/your-authtoken)
 
 ```sh
-npm run start -- --platform=ios --entryDomain="www.example.com" \
+npm run start -- --platform=ios --entryUrl="https://www.example.com" \
   --navigatorToken="<YOUR_NGROK_AUTH_TOKEN>" --navigatorPath="/nav"
 ```
 
+### Publishing your app in the App Store
+
+[Follow these instructions on how to publish your app for beta testing and the App Store.](https://developer.apple.com/documentation/xcode/distributing-your-app-for-beta-testing-and-releases)
+
 ## Building the app project for **Android**
 
 > [!WARNING]
 > If you want to build Android on Windows, please use [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install)
 
-* You will need your site's domain.
+* You will need the url you want to load initially in your app.
 * You will need [Node.js](https://nodejs.org/en/) for the project setup and web server.
 * You will need [go](https://golang.org/) to build the SDK library.
 * You will need [JDK 17](https://stackoverflow.com/a/70649641) to build the app.
@@ -83,7 +87,7 @@ npm run start -- --platform=ios --entryDomain="www.example.com" \
 
 ```sh
 npm run reset
-npm run build:project -- --platform=android --entryDomain="www.example.com"
+npm run build:project -- --platform=android --entryUrl="https://www.example.com"
 npm run open:android
 ```
 
@@ -115,16 +119,23 @@ Many sites don't handle their own navigation - if this applies to you, you can r
 * You will need an [ngrok account](https://ngrok.com/), from which you can get your [`--navigatorToken`](https://dashboard.ngrok.com/get-started/your-authtoken)
 
 ```sh
-npm run start -- --platform=android  --entryDomain="www.example.com" \
+npm run start -- --platform=android  --entryUrl="https://www.example.com" \
   --navigatorToken="<YOUR_NGROK_AUTH_TOKEN>" --navigatorPath="/nav"
 ```
 
+### Publishing your app in the Google Play Store
+
+[Follow these instructions to learn how to publish your app to the Google Play Store](https://developer.android.com/studio/publish)
+
 ## Available Configuration Options
 
 | Option              | Description                                                                     | Possible Values          |
 | ------------------- | ------------------------------------------------------------------------------- | ------------------------ |
 | `--platform`        | **(Required)** Specifies the target platform for the build.                                    | `"ios"` or `"android"`   |
-| `--entryDomain`     | **(Required)** The primary domain of your website.                                             | Any valid domain name    |
+| `--entryUrl`     | **(Required)** The primary url of your website.                                             | Any valid url    |
+| `--appId`           | The unique identifier for the app (e.g., iOS Bundle ID, Android Application ID). | A reverse domain name string (e.g., `com.company.appname`) |
+| `--appName`         | The user-visible name of the application.                                       | Any valid application name string (e.g., "My Awesome App") |
+| `--output`          | The directory where the generated app project files will be saved.              | A valid, absolute file path (e.g., `/users/me/my-generated-app`) |
 | `--additionalDomains` | A list of other domains that should be accessible within the app.               | Comma-separated domains |
 | `--smartDialerConfig` | A JSON string containing the configuration for the [smart dialer feature](../../smart#yaml-config-for-the-smart-dialer).       | Valid JSON string       |
 | `--navigatorToken`  | Your ngrok authentication token for using the navigation proxy.                 | Your [ngrok auth token](https://dashboard.ngrok.com/get-started/your-authtoken)    |

x/examples/website-wrapper-app/package.json

@@ -14,7 +14,7 @@
   },
   "license": "Apache-2.0",
   "scripts": {
-    "build:sdk_mobileproxy": "bash ./.scripts/build_sdk_mobileproxy.sh",
+    "build:mobileproxy": "bash ./.scripts/build_mobileproxy.sh",
     "build:project": "node ./wrapper_app_project/.scripts/build.mjs",
     "clean": "npx rimraf node_modules/ output/",
     "doctor": "./doctor",

x/examples/website-wrapper-app/wrapper_app_project/.scripts/build.mjs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { exec } from "node:child_process";
+import { exec, execFile } from "node:child_process";
 import { glob } from "glob";
 import { promisify } from "node:util";
 import chalk from "chalk";
@@ -23,19 +23,10 @@ import path from "node:path";
 import minimist from "minimist";
 
 const OUTPUT_DIR = path.join(process.cwd(), "output");
-
 const WRAPPER_APP_TEMPLATE_DIR = path.join(
   process.cwd(),
   "wrapper_app_project/template",
 );
-const WRAPPER_APP_OUTPUT_DIR = path.join(OUTPUT_DIR, "wrapper_app_project");
-const WRAPPER_APP_OUTPUT_ZIP = path.join(OUTPUT_DIR, "wrapper_app_project.zip");
-
-const SDK_MOBILEPROXY_OUTPUT_DIR = path.join(OUTPUT_DIR, "mobileproxy");
-const WRAPPER_APP_OUTPUT_SDK_MOBILEPROXY_DIR = path.join(
-  WRAPPER_APP_OUTPUT_DIR,
-  "mobileproxy",
-);
 
 const DEFAULT_SMART_DIALER_CONFIG = {
   dns: [{
@@ -46,18 +37,41 @@ const DEFAULT_SMART_DIALER_CONFIG = {
 
 export default async function main(
   {
+    additionalDomains = [],
+    appId,
+    appName,
+    entryUrl = "https://www.example.com",
+    navigationUrl,
+    output = OUTPUT_DIR,
     platform,
     sdkVersion = "x/v0.0.1",
-    entryDomain = "www.example.com",
-    navigationUrl,
     smartDialerConfig = DEFAULT_SMART_DIALER_CONFIG,
-    additionalDomains = [],
   },
 ) {
+  const WRAPPER_APP_OUTPUT_DIR = path.resolve(output, "wrapper_app_project");
+  const WRAPPER_APP_OUTPUT_ZIP = path.resolve(
+    output,
+    "wrapper_app_project.zip",
+  );
+
+  const SDK_MOBILEPROXY_OUTPUT_DIR = path.resolve(output, "mobileproxy");
+  const WRAPPER_APP_OUTPUT_SDK_MOBILEPROXY_DIR = path.resolve(
+    WRAPPER_APP_OUTPUT_DIR,
+    "mobileproxy",
+  );
+
   if (!fs.existsSync(SDK_MOBILEPROXY_OUTPUT_DIR)) {
-    console.log(`Building the Outline SDK mobileproxy library for ${platform}...`);
+    console.log(
+      `Building the Outline SDK mobileproxy library for ${platform}...`,
+    );
 
-    await promisify(exec)(`npm run build:sdk_mobileproxy ${platform} ${sdkVersion}`);
+    await promisify(execFile)("npm", [
+      "run",
+      "build:mobileproxy",
+      platform,
+      sdkVersion,
+      output,
+    ], { shell: false });
   }
 
   const sourceFilepaths = await glob(
@@ -70,6 +84,22 @@ export default async function main(
 
   console.log("Building project from template...");
 
+  let templateArguments;
+
+  try {
+    templateArguments = resolveTemplateArguments(platform, entryUrl, {
+      additionalDomains,
+      appId,
+      appName,
+      navigationUrl,
+      smartDialerConfig,
+    });
+  } catch (cause) {
+    throw new TypeError("Failed to resolve the project template arguments", {
+      cause,
+    });
+  }
+
   for (const sourceFilepath of sourceFilepaths) {
     const destinationFilepath = path.join(
       WRAPPER_APP_OUTPUT_DIR,
@@ -91,22 +121,9 @@ export default async function main(
       fs.readFileSync(sourceFilepath, "utf8"),
     );
 
-    if (typeof additionalDomains === "string") {
-      additionalDomains = [additionalDomains];
-    }
-
     fs.writeFileSync(
       destinationFilepath.replace(/\.handlebars$/, ""),
-      template({
-        platform,
-        entryDomain,
-        navigationUrl: navigationUrl
-          ? navigationUrl
-          : `https://${entryDomain}/`,
-        domainList: [entryDomain, ...additionalDomains].join("\\n"),
-        smartDialerConfig: typeof smartDialerConfig === "object" ? JSON.stringify(smartDialerConfig).replaceAll('"',  '\\"') : smartDialerConfig,
-        additionalDomains,
-      }),
+      template(templateArguments),
       "utf8",
     );
   }
@@ -149,21 +166,93 @@ function zip(root, destination) {
   });
 }
 
+function resolveTemplateArguments(
+  platform,
+  entryUrl,
+  {
+    appId,
+    appName,
+    navigationUrl,
+    additionalDomains,
+    smartDialerConfig,
+  },
+) {
+  const result = {
+    platform,
+    entryUrl,
+    entryDomain: new URL(entryUrl).hostname,
+  };
+
+  if (!appId) {
+    // Infer an app ID from the entry domain by reversing it (e.g. `www.example.com` becomes `com.example.www`)
+    // It must be lower case, and hyphens are not allowed.
+    result.appId = result.entryDomain.replaceAll("-", "")
+      .toLocaleLowerCase().split(".").reverse().join(".");
+  }
+
+  if (!appName) {
+    // Infer an app name from the base entry domain part by title casing the root domain:
+    // (e.g. `www.my-example-app.com` becomes "My Example App")
+    const rootDomain = result.entryDomain.split(".").reverse()[1];
+
+    result.appName = rootDomain.toLocaleLowerCase().replaceAll(
+      /\w[a-z0-9]*[-_]*/g,
+      (match) => {
+        match = match.replace(/[-_]+/, " ");
+
+        return match.charAt(0).toUpperCase() + match.slice(1).toLowerCase();
+      },
+    );
+  }
+
+  if (navigationUrl) {
+    result.entryUrl = navigationUrl;
+    result.entryDomain = new URL(navigationUrl).hostname;
+  }
+
+  if (typeof additionalDomains === "string") {
+    result.additionalDomains = additionalDomains.split(/,\s*/);
+    result.domainList = [result.entryDomain, ...result.additionalDomains].join(
+      "\\n",
+    );
+  } else if (typeof additionalDomains === "object") {
+    result.additionalDomains = additionalDomains;
+    result.domainList = [result.entryDomain, ...result.additionalDomains].join(
+      "\\n",
+    );
+  } else {
+    result.domainList = [result.entryDomain];
+  }
+
+  if (typeof smartDialerConfig === "string") {
+    result.smartDialerConfig = smartDialerConfig.replaceAll('"', '\\"');
+  } else if (typeof smartDialerConfig === "object") {
+    result.smartDialerConfig = JSON.stringify(smartDialerConfig).replaceAll(
+      '"',
+      '\\"',
+    );
+  }
+
+  return result;
+}
+
 if (import.meta.url.endsWith(process.argv[1])) {
   const args = minimist(process.argv.slice(2));
 
   if (!args.platform) {
     throw new Error(`Parameter \`--platform\` not provided.`);
   }
 
-  if (!args.entryDomain) {
-    throw new Error(`Parameter \`--entryDomain\` not provided.`);
+  if (!args.entryUrl) {
+    throw new Error(`Parameter \`--entryUrl\` not provided.`);
   }
 
   main({
     ...args,
     additionalDomains: args.additionalDomains?.split(/,\s*/) ?? [],
-    smartDialerConfig: args.smartDialerConfig ? JSON.parse(args.smartDialerConfig) : undefined,
+    smartDialerConfig: args.smartDialerConfig
+      ? JSON.parse(args.smartDialerConfig)
+      : undefined,
   })
     .catch(console.error);
 }

x/examples/website-wrapper-app/wrapper_app_project/template/android/app/build.gradle renamed to x/examples/website-wrapper-app/wrapper_app_project/template/android/app/build.gradle.handlebars

@@ -1,10 +1,10 @@
 apply plugin: 'com.android.application'
 
 android {
-    namespace "org.getoutline.pwa"
+    namespace "{{appId}}"
     compileSdk rootProject.ext.compileSdkVersion
     defaultConfig {
-        applicationId "org.getoutline.pwa"
+        applicationId "{{appId}}"
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
         versionCode 1

x/examples/website-wrapper-app/wrapper_app_project/template/android/app/src/main/java/org/getoutline/pwa/Config.kt.handlebars

@@ -1,4 +1,4 @@
-package org.getoutline.pwa
+package {{appId}}
 
 object Config {
     var domainList: String = "{{domainList}}"

x/examples/website-wrapper-app/wrapper_app_project/template/android/app/src/main/java/org/getoutline/pwa/MainActivity.kt renamed to x/examples/website-wrapper-app/wrapper_app_project/template/android/app/src/main/java/org/getoutline/pwa/MainActivity.kt.handlebars

@@ -1,4 +1,4 @@
-package org.getoutline.pwa
+package {{appId}}
 
 import android.os.Bundle
 import com.getcapacitor.BridgeActivity
@@ -63,4 +63,4 @@ class MainActivity : BridgeActivity() {
 
         return true
     }
-}
+}

x/examples/website-wrapper-app/wrapper_app_project/template/android/app/src/main/res/values/strings.xml

@@ -0,0 +1,7 @@
+<?xml version='1.0' encoding='utf-8'?>
+<resources>
+    <string name="app_name">{{appName}}</string>
+    <string name="title_activity_main">{{appName}}</string>
+    <string name="package_name">{{appId}}</string>
+    <string name="custom_url_scheme">{{appId}}</string>
+</resources>