@swyng/react-native-code-push 1.0.0

package/LICENSE.md

@@ -0,0 +1,13 @@
+SwyngPush React Native Plugin
+
+Copyright (c) 2024 Swyng
+
+All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+#### [Sign up with SwyngPush](https://swyngpush.site) to use CodePush
+
+# React Native Module for SwyngPush
+
+This plugin provides client-side integration for the [SwyngPush service](https://swyngpush.site), allowing you to easily add over-the-air updates to your React Native app(s).
+
+- [How does it work?](#how-does-it-work)
+- [Supported React Native Platforms](#supported-react-native-platforms)
+- [Supported Components](#supported-components)
+- [Getting Started](#getting-started)
+  - [iOS Setup](docs/setup-ios.md)
+  - [Android Setup](docs/setup-android.md)
+  - [Windows Setup](docs/setup-windows.md)
+- [Plugin Usage](#plugin-usage)
+  - [Store Guideline Compliance](#store-guideline-compliance)
+- [Releasing Updates](#releasing-updates)
+- [Multi-Deployment Testing](#multi-deployment-testing)
+  - [Android](docs/multi-deployment-testing-android.md)
+  - [iOS](docs/multi-deployment-testing-ios.md)
+- [Dynamic Deployment Assignment](#dynamic-deployment-assignment)
+- [API Reference](#api-reference)
+  - [JavaScript API](docs/api-js.md)
+  - [Objective-C API Reference (iOS)](docs/api-ios.md)
+  - [Java API Reference (Android)](docs/api-android.md)
+- [Debugging / Troubleshooting](#debugging--troubleshooting)
+- [Example Apps / Starters](#example-apps--starters)
+- [TypeScript Consumption](#typescript-consumption)
+
+## How does it work?
+
+A React Native app is composed of JavaScript files and any accompanying [images](https://reactnative.dev/docs/image), which are bundled together by the [metro bundler](https://github.com/facebook/metro) and distributed as part of a platform-specific binary (i.e. an `.ipa` or `.apk` file). Once the app is released, updating either the JavaScript code (e.g. making bug fixes, adding new features) or image assets, requires you to recompile and redistribute the entire binary, which of course, includes any review time associated with the store(s) you are publishing to.
+
+The SwyngPush plugin helps get product improvements in front of your end users instantly, by keeping your JavaScript and images synchronized with updates you release to the SwyngPush server. This way, your app gets the benefits of an offline mobile experience, as well as the "web-like" agility of side-loading updates as soon as they are available.
+
+In order to ensure that your end users always have a functioning version of your app, the SwyngPush plugin maintains a copy of the previous update, so that in the event that you accidentally push an update which includes a crash, it can automatically roll back. This way, you can rest assured that your newfound release agility won't result in users becoming blocked before you have a chance to roll back on the server.
+
+_Note: Any product changes which touch native code (e.g. modifying your `AppDelegate.m`/`MainActivity.java` file, adding a new plugin) cannot be distributed via CodePush, and therefore, must be updated via the appropriate store(s)._
+
+## Supported React Native platforms
+
+- iOS (7+)
+- Android (4.1+) on TLS 1.2 compatible devices
+
+We try our best to maintain backwards compatibility of our plugin with previous versions of React Native, but due to the nature of the platform, and the existence of breaking changes between releases, it is possible that you need to use a specific version of the CodePush plugin in order to support the exact version of React Native you are using. The following table outlines which CodePush plugin versions officially support the respective React Native versions:
+
+| React Native version(s)  | Supporting CodePush version(s)                    |
+| ------------------------ | ------------------------------------------------- |
+| v0.76, v0.77, 0.78, 0.79 | v1.0+ _(Old/New Architecture)_                   |
+| v0.80                    | v1.0+ _(Old/New Architecture)_                    |
+| v0.81+                   | v1.0+ _(Old/New Architecture)_                    |
+| v0.82+                   | v1.0+ _(New Architecture)_                        |
+
+### Supported Components
+
+When using the React Native assets system (i.e. using the `require("./foo.png")` syntax), the following list represents the set of core components (and props) that support having their referenced images and videos updated via CodePush:
+
+| Component                                                                                                                | Prop(s)                                  |
+| ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| `Image`                                                                                                                  | `source`                                 |
+| `MapView.Marker` <br />_(Requires [react-native-maps](https://github.com/lelandrichardson/react-native-maps) `>=O.3.2`)_ | `image`                                  |
+| `ProgressViewIOS`                                                                                                        | `progressImage`, `trackImage`            |
+| `TabBarIOS.Item`                                                                                                         | `icon`, `selectedIcon`                   |
+| `ToolbarAndroid` <br />_(React Native 0.21.0+)_                                                                          | `actions[].icon`, `logo`, `overflowIcon` |
+| `Video`                                                                                                                  | `source`                                 |
+
+_Note: CodePush only works with Video components when using `require` in the source prop. For example:_
+
+```javascript
+<Video source={require("./foo.mp4")} />
+```
+
+## Getting Started
+
+Once you've followed the general-purpose ["getting started"](https://console.swyngpush.site/docs) instructions for setting up your SwyngPush account, you can start CodePush-ifying your React Native app by running the following command from within your app's root directory:
+
+```shell
+yarn add @swyng/react-native-code-push
+```
+
+As with all other React Native plugins, the integration experience is different for iOS and Android, so perform the following setup steps depending on which platform(s) you are targeting. Note, if you are targeting both platforms it is recommended to create separate CodePush applications for each platform.
+
+Then continue with installing the native module:
+
+- [iOS Setup](docs/setup-ios.md)
+- [Android Setup](docs/setup-android.md)
+- [Windows Setup](docs/setup-windows.md)
+
+## Plugin Usage
+
+With the CodePush plugin downloaded and linked, and your app asking CodePush where to get the right JS bundle from, the only thing left is to add the necessary code to your app to control the following policies:
+
+1. When (and how often) to check for an update? (for example app start, in response to clicking a button in a settings page, periodically at some fixed interval)
+
+2. When an update is available, how to present it to the end user?
+
+The simplest way to do this is to "CodePush-ify" your app's root component. To do so, you can choose one of the following two options:
+
+- **Option 1: Wrap your root component with the `codePush` higher-order component:**
+
+  - For class component
+
+    ```javascript
+    import codePush from "@swyng/react-native-code-push";
+
+    class MyApp extends Component {}
+
+    MyApp = codePush(MyApp);
+    ```
+
+  - For functional component
+
+    ```javascript
+    import codePush from "@swyng/react-native-code-push";
+
+    let MyApp: () => React$Node = () => {};
+
+    MyApp = codePush(MyApp);
+    ```
+
+- **Option 2: Use the [ES7 decorator](https://github.com/wycats/javascript-decorators) syntax:**
+
+  _NOTE: Decorators are not yet supported in Babel 6.x pending proposal update._ You may need to enable it by installing and using [babel-preset-react-native-stage-0](https://github.com/skevy/babel-preset-react-native-stage-0#babel-preset-react-native-stage-0).
+
+  - For class component
+
+    ```javascript
+    import codePush from "@swyng/react-native-code-push";
+
+    @codePush
+    class MyApp extends Component {}
+    ```
+
+  - For functional component
+
+    ```javascript
+    import codePush from "@swyng/react-native-code-push";
+
+    const MyApp: () => React$Node = () => {};
+
+    export default codePush(MyApp);
+    ```
+
+By default, CodePush will check for updates on every app start. If an update is available, it will be silently downloaded, and installed the next time the app is restarted (either explicitly by the end user or by the OS), which ensures the least invasive experience for your end users. If an available update is mandatory, then it will be installed immediately, ensuring that the end user gets it as soon as possible.
+
+If you would like your app to discover updates more quickly, you can also choose to sync up with the CodePush server every time the app resumes from the background.
+
+```javascript
+let codePushOptions = {
+  checkFrequency: codePush.CheckFrequency.ON_APP_RESUME,
+};
+
+let MyApp: () => React$Node = () => {};
+
+MyApp = codePush(codePushOptions)(MyApp);
+```
+
+Alternatively, if you want fine-grained control over when the check happens (like a button press or timer interval), you can call [`CodePush.sync()`](docs/api-js.md#codepushsync) at any time with your desired `SyncOptions`, and optionally turn off CodePush's automatic checking by specifying a manual `checkFrequency`:
+
+```javascript
+let codePushOptions = { checkFrequency: codePush.CheckFrequency.MANUAL };
+
+class MyApp extends Component {
+  onButtonPress() {
+    codePush.sync({
+      updateDialog: true,
+      installMode: codePush.InstallMode.IMMEDIATE,
+    });
+  }
+
+  render() {
+    return (
+      <View>
+        <TouchableOpacity onPress={this.onButtonPress}>
+          <Text>Check for updates</Text>
+        </TouchableOpacity>
+      </View>
+    );
+  }
+}
+
+MyApp = codePush(codePushOptions)(MyApp);
+```
+
+If you would like to display an update confirmation dialog (an "active install"), configure when an available update is installed (like force an immediate restart) or customize the update experience in any other way, refer to the [`codePush()`](docs/api-js.md#codepush) API reference for information on how to tweak this default behavior.
+
+### For Expo users with CNG (Continuous Native Generation)
+
+```json
+// app.json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@swyng/react-native-code-push/expo",
+        {
+          "ios": {
+            "CodePushDeploymentKey": "your-deployment-key",
+            "CodePushServerURL": "https://bl-prod-2-ap-south-1.swyng.site"
+          },
+          "android": {
+            "CodePushDeploymentKey": "your-deployment-key",
+            "CodePushServerURL": "https://bl-prod-2-ap-south-1.swyng.site"
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+Currently, the SwyngPush CLI doesn't support expo-cli build. To make it work, you need to customize metro.config.js in the root directory:
+
+```
+npx expo customize metro.config.js
+```
+
+### Store Guideline Compliance
+
+Android Google Play and iOS App Store have corresponding guidelines that have rules you should be aware of before integrating the CodePush solution within your application.
+
+#### Google Play
+
+Third paragraph of [Device and Network Abuse](https://support.google.com/googleplay/android-developer/answer/9888379?hl=en) topic describes that updating source code by any method other than Google Play's update mechanism is restricted. But this restriction does not apply to updating JavaScript bundles.
+
+> This restriction does not apply to code that runs in a virtual machine and has limited access to Android APIs (such as JavaScript in a webview or browser).
+
+That fully allows CodePush as it updates just JS bundles and can't update native code.
+
+#### App Store
+
+Paragraph **3.3.2** of the [Apple Developer Program License Agreement](https://developer.apple.com/terms/) fully allows performing over-the-air updates of JavaScript and assets:
+
+> Interpreted code may be downloaded to an Application but only so long as such code: (a) does not change the primary purpose of the Application by providing features or functionality that are inconsistent with the intended and advertised purpose of the Application as submitted to the App Store, (b) does not create a store or storefront for other code or applications, and (c) does not bypass signing, sandbox, or other security features of the OS.
+
+CodePush allows you to follow these rules in full compliance so long as the update you push does not significantly deviate your product from its original App Store approved intent.
+
+To further remain in compliance with Apple's guidelines we suggest that App Store-distributed apps don't enable the `updateDialog` option when calling `sync`, since in the [App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/) it is written that:
+
+> Apps must not force users to rate the app, review the app, download other apps, or other similar actions in order to access functionality, content, or use of the app.
+
+This is not necessarily the case for `updateDialog`, since it won't force the user to download the new version, but at least you should be aware of that ruling if you decide to show it.
+
+## Releasing Updates
+
+Once your app is configured and distributed to your users, and you have made some JS or asset changes, it's time to release them. The recommended way to release them is using the `create_bundle` command in the SwyngPush CLI, which will bundle your JavaScript files, asset files, and release the update to the SwyngPush server.
+
+*NOTE: Before you can start releasing updates, please log into [SwyngPush](https://swyngpush.site) by running the `npx @swyng/cli login -u <username> -p <password>` command.*
+
+In its most basic form, this command only requires some parameters:
+
+```shell
+npx @swyng/cli create_bundle -t <TargetVersion> -n <AppName> -d <deployment>
+
+npx @swyng/cli create_bundle -t 1.0.0 -n Demo1 -d Staging
+```
+
+The `create_bundle` command enables such a simple workflow because it provides many sensible defaults (like generating a release bundle, assuming your app's entry file on iOS is either `index.ios.js` or `index.js`). However, all of these defaults can be customized to allow incremental flexibility as necessary, which makes it a good fit for most scenarios.
+
+The CodePush client supports differential updates, so even though you are releasing your JS bundle and assets on every update, your end users will only actually download the files they need. The service handles this automatically so that you can focus on creating awesome apps and we can worry about optimizing end user downloads.
+
+For more details about how the `create_bundle` command works, as well as the various parameters it exposes, refer to the [CLI docs](https://console.swyngpush.site/docs).
+
+### Dynamic Deployment Assignment
+
+The above section illustrated how you can leverage multiple CodePush deployments in order to effectively test your updates before broadly releasing them to your end users. However, since that workflow statically embeds the deployment assignment into the actual binary, a staging or production build will only ever sync updates from that deployment. In many cases, this is sufficient, since you only want your team, customers, stakeholders, etc. to sync with your pre-production releases, and therefore, only they need a build that knows how to sync with staging. However, if you want to be able to perform A/B tests, or provide early access of your app to certain users, it can prove very useful to be able to dynamically place specific users (or audiences) into specific deployments at runtime.
+
+In order to achieve this kind of workflow, all you need to do is specify the deployment key you want the current user to synchronize with when calling the `codePush` method. When specified, this key will override the "default" one that was provided in your app's `Info.plist` (iOS) or `MainActivity.java` (Android) files. This allows you to produce a build for staging or production, that is also capable of being dynamically "redirected" as needed.
+
+```javascript
+// Imagine that "userProfile" is a prop that this component received
+// which includes the deployment key that the current user should use.
+codePush.sync({ deploymentKey: userProfile.CODEPUSH_KEY });
+```
+
+With that change in place, now it's just a matter of choosing how your app determines the right deployment key for the current user. In practice, there are typically two solutions for this:
+
+1. Expose a user-visible mechanism for changing deployments at any time. For example, your settings page could have a toggle for enabling "beta" access.
+
+2. Annotate the server-side profile of your users with an additional piece of metadata that indicates the deployment they should sync with. By default, your app could just use the binary-embedded key, but after a user has authenticated, your server can choose to "redirect" them to a different deployment.
+
+```javascript
+// #1) Create your new deployment to hold releases of a specific app variant
+npx @swyng/cli app create_deployment -n <AppName> -dn <DeploymentName>
+
+// #2) Target any new releases at that custom deployment
+npx @swyng/cli create_bundle -t <TargetVersion> -n <AppName> -d <deployment>
+```
+
+---
+
+## API Reference
+
+- [JavaScript API](docs/api-js.md)
+- [Objective-C API Reference (iOS)](docs/api-ios.md)
+- [Java API Reference (Android)](docs/api-android.md)
+
+### Debugging / Troubleshooting
+
+The `sync` method includes a lot of diagnostic logging out-of-the-box, so if you're encountering an issue when using it, the best thing to try first is examining the output logs of your app. This will tell you whether the app is configured correctly (like can the plugin find your deployment key?), if the app is able to reach the server, if an available update is being discovered, if the update is being successfully downloaded/installed, etc.
+
+The simplest way to view these logs is to add the flag `--debug` for each command. This will output a log stream that is filtered to just CodePush messages. This makes it easy to identify issues, without needing to use a platform-specific tool, or wade through a potentially high volume of logs.
+
+Additionally, you can also use any of the platform-specific tools to view the CodePush logs. Start up the Chrome DevTools Console, the Xcode Console (iOS), and/or ADB logcat (Android), and look for messages which are prefixed with `[CodePush]`.
+
+| Issue / Symptom | Possible Solution |
+|-----------------|-------------------|
+| Compilation Error | Double-check that your version of React Native is [compatible](#supported-react-native-platforms) with the CodePush version you are using. |
+| Network timeout / hang when calling `sync` or `checkForUpdate` in the iOS Simulator | Try resetting the simulator by selecting the `Simulator -> Reset Content and Settings..` menu item, and then re-running your app. |
+| Server responds with a `404` when calling `sync` or `checkForUpdate` | Double-check that the deployment key you added to your `Info.plist` (iOS), `build.gradle` (Android) or that you're passing to `sync`/`checkForUpdate`, is in fact correct. You can run `npx @swyng/cli app ls_deployment -n <AppName> -k` to view the correct keys for your app deployments. |
+| Update not being discovered | Double-check that the version of your running app (like `1.0.0`) matches the version you specified when releasing the update to CodePush. Additionally, make sure that you are releasing to the same deployment that your app is configured to sync with. |
+| Update not being displayed after restart | If you're not calling `sync` on app start (like within `componentDidMount` of your root component), then you need to explicitly call `notifyApplicationReady` on app start, otherwise, the plugin will think your update failed and roll it back. |
+| I've released an update for iOS but my Android app also shows an update and it breaks it | Be sure you have different deployment keys for each platform in order to receive updates correctly. |
+| I've released new update but changes are not reflected | Be sure that you are running app in modes other than Debug. In Debug mode, React Native app always downloads JS bundle generated by packager, so JS bundle downloaded by CodePush does not apply. |
+
+### TypeScript Consumption
+
+This module ships its `*.d.ts` file as part of its NPM package, which allows you to simply `import` it, and receive intellisense in supporting editors (like Visual Studio Code), as well as compile-time type checking if you're using TypeScript. For the most part, this behavior should just work out of the box, however, if you've specified `es6` as the value for either the `target` or `module` [compiler option](http://www.typescriptlang.org/docs/handbook/compiler-options.html) in your [`tsconfig.json`](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html) file, then just make sure that you also set the `moduleResolution` option to `node`. This ensures that the TypeScript compiler will look within the `node_modules` for the type definitions of imported modules.
+
+---
+
+## License
+
+MIT - See [LICENSE.md](LICENSE.md)

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you believe you have found a security vulnerability in this repository, please report it responsibly.
+
+**Please do NOT report security vulnerabilities through public GitHub issues.**
+
+Instead, please send an email to [security@swyngpush.site](mailto:security@swyngpush.site).
+
+You should receive a response within 48 hours. If for some reason you do not, please follow up via email to ensure we received your original message.
+
+Please include the following information in your report:
+- Type of issue (e.g., buffer overflow, SQL injection, cross-site scripting, etc.)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit it
+
+## Preferred Languages
+
+We prefer all communications to be in English.

package/android/app/build.gradle

@@ -0,0 +1,48 @@
+apply plugin: "com.android.library"
+
+def isNewArchitectureEnabled() {
+    // To opt-in for the New Architecture, you can either:
+    // - Set `newArchEnabled` to true inside the `gradle.properties` file
+    // - Invoke gradle with `-newArchEnabled=true`
+    // - Set an environment variable `ORG_GRADLE_PROJECT_newArchEnabled=true`
+    return project.hasProperty("newArchEnabled") && project.newArchEnabled == "true"
+}
+
+def IS_NEW_ARCHITECTURE_ENABLED = isNewArchitectureEnabled()
+
+def DEFAULT_COMPILE_SDK_VERSION = 26
+def DEFAULT_BUILD_TOOLS_VERSION = "26.0.3"
+def DEFAULT_TARGET_SDK_VERSION = 26
+def DEFAULT_MIN_SDK_VERSION = 16
+
+android {
+    namespace "com.swyngpush.codepush.react"
+
+    compileSdkVersion rootProject.hasProperty('compileSdkVersion') ? rootProject.compileSdkVersion : DEFAULT_COMPILE_SDK_VERSION
+    buildToolsVersion rootProject.hasProperty('buildToolsVersion') ? rootProject.buildToolsVersion : DEFAULT_BUILD_TOOLS_VERSION
+
+    defaultConfig {
+        minSdkVersion rootProject.hasProperty('minSdkVersion') ? rootProject.minSdkVersion : DEFAULT_MIN_SDK_VERSION
+        targetSdkVersion rootProject.hasProperty('targetSdkVersion') ? rootProject.targetSdkVersion : DEFAULT_TARGET_SDK_VERSION
+        versionCode 1
+        versionName "1.0"
+        buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", IS_NEW_ARCHITECTURE_ENABLED.toString()
+    }
+
+    lintOptions {
+        abortOnError false
+    }
+
+    defaultConfig {
+        consumerProguardFiles 'proguard-rules.pro'
+    }
+
+    buildFeatures {
+        buildConfig true
+    }
+}
+
+dependencies {
+    implementation 'com.facebook.react:react-android:0.82.1'
+    implementation 'com.nimbusds:nimbus-jose-jwt:9.37.3'
+}

package/android/app/proguard-rules.pro

@@ -0,0 +1,33 @@
+# Add project specific ProGuard rules here.
+# By default, the flags in this file are appended to flags specified
+# in /usr/local/Cellar/android-sdk/24.3.3/tools/proguard/proguard-android.txt
+# You can edit the include path and order by changing the proguardFiles
+# directive in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# Add any project specific keep options here:
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Invoked via reflection, when setting js bundle.
+-keepclassmembers class com.facebook.react.ReactInstanceManager {
+    private final ** mBundleLoader;
+}
+
+-keepclassmembers class com.facebook.react.runtime.ReactHostImpl {
+    private final ** mReactHostDelegate;
+}
+
+-keep interface com.facebook.react.runtime.ReactHostDelegate { *; }
+
+-keep class * implements com.facebook.react.runtime.ReactHostDelegate { *; }
+
+# Can't find referenced class org.bouncycastle.**
+-dontwarn com.nimbusds.jose.**

package/android/app/src/main/AndroidManifest.xml

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