@appzung/react-native-code-push 10.0.1 → 10.1.0

package/src/enums/UpdateState.enum.ts

@@ -5,20 +5,21 @@ import { NativeRNAppZungCodePushModule } from '../internals/NativeRNAppZungCodeP
  */
 export enum UpdateState {
   /**
-   * Indicates that an update represents the
-   * version of the app that is currently running.
+   * Indicates that an update represents the version of the app that is currently running.
+   *
+   * This can be useful for identifying attributes about the app, for scenarios such as displaying the release description in a "what's new?" dialog or reporting the latest version to an analytics and/or crash reporting service.
    */
   RUNNING = NativeRNAppZungCodePushModule.getConstants().codePushUpdateStateRunning,
 
   /**
-   * Indicates than an update has been installed, but the
-   * app hasn't been restarted yet in order to apply it.
+   * Indicates than an update has been installed, but the app hasn't been restarted yet in order to apply it.
+   *
+   * This can be useful for determining whether there is a pending update, which you may want to force a programmatic restart (via `restartApp`) in order to apply.
    */
   PENDING = NativeRNAppZungCodePushModule.getConstants().codePushUpdateStatePending,
 
   /**
-   * Indicates than an update represents the latest available
-   * release, and can be either currently running or pending.
+   * Indicates than an update represents the latest available release, and can be either currently running or pending.
    */
   LATEST = NativeRNAppZungCodePushModule.getConstants().codePushUpdateStateLatest,
 }

package/src/getClientUniqueId.ts

@@ -0,0 +1,9 @@
+import { getConfiguration } from './internals/getConfiguration';
+
+/**
+ * Gets the client's unique ID set by the module. You may also see `resetClientUniqueId`.
+ */
+export const getClientUniqueId = async () => {
+  const nativeConfig = await getConfiguration();
+  return nativeConfig.clientUniqueId;
+};

package/src/index.ts

@@ -8,6 +8,8 @@ export * from './getUpdateMetadata';
 export * from './notifyAppReady';
 export * from './restartApp';
 export * from './sync';
+export * from './getClientUniqueId';
+export * from './resetClientUniqueId';
 
 export * from './types';
 

package/src/internals/RNAppZungCodePushModuleSpec.ts

@@ -20,6 +20,7 @@ export interface Spec extends TurboModule {
   };
 
   getConfiguration(): Promise<Configuration>;
+  resetClientUniqueId(): Promise<string>;
 
   getUpdateMetadata(updateState: UpdateState): Promise<OmitFunctions<LocalPackage>>;
   installUpdate(

package/src/internals/getConfiguration.ts

@@ -10,3 +10,7 @@ export async function getConfiguration() {
 
   return config;
 }
+
+export async function reloadCachedConfiguration() {
+  config = await NativeRNAppZungCodePushModule.getConfiguration();
+}

package/src/internals/version.ts

@@ -1,2 +1,2 @@
 // Generated by genversion.
-export const version = '10.0.1';
+export const version = '10.1.0';

package/src/notifyAppReady.ts

@@ -8,6 +8,8 @@ import type { StatusReport } from './types';
 
 /**
  * Notifies the CodePush runtime that an installed update is considered successful.
+ *
+ * If you are manually checking for and installing updates (i.e. not using the `sync` method to handle it all for you), then this method **MUST** be called; otherwise CodePush will treat the update as failed and rollback to the previous version when the app next restarts.
  */
 export const notifyAppReady = (() => {
   // This ensures that notifyApplicationReadyInternal is only called once

package/src/resetClientUniqueId.ts

@@ -0,0 +1,11 @@
+import { NativeRNAppZungCodePushModule } from './internals/NativeRNAppZungCodePushModule';
+import { reloadCachedConfiguration } from './internals/getConfiguration';
+
+/**
+ * Resets the client's unique ID. You may use this in some GDPR compliance scenarios. Note that this will create a new MAU if a new request is sent later.
+ */
+export const resetClientUniqueId = async () => {
+  const newId = await NativeRNAppZungCodePushModule.resetClientUniqueId();
+  await reloadCachedConfiguration();
+  return newId;
+};

package/src/restartApp.ts

@@ -3,6 +3,8 @@ import { NativeRNAppZungCodePushModule } from './internals/NativeRNAppZungCodePu
 /**
  * Immediately restarts the app.
  *
+ * If there is an update pending, it will be immediately displayed to the end user. Otherwise, calling this method simply has the same behavior as the end user killing and restarting the process.
+ *
  * @param onlyIfUpdateIsPending Indicates whether you want the restart to no-op if there isn't currently a pending update.
  */
 export async function restartApp(onlyIfUpdateIsPending = false) {

package/src/sync.ts

@@ -206,6 +206,8 @@ async function syncInternal(
 /**
  * Allows checking for an update, downloading it and installing it, all with a single call.
  *
+ * Unless you need custom UI and/or behavior, we recommend most developers to use this method when integrating CodePush into their apps, if they are not using the `withCodePush` HOC.
+ *
  * @param options Options used to configure the end-user update experience (e.g. show a prompt?, install the update immediately?).
  * @param syncStatusChangedCallback An optional callback that allows tracking the status of the sync operation, as opposed to simply checking the resolved state via the returned Promise.
  * @param downloadProgressCallback An optional callback that allows tracking the progress of an update while it is being downloaded.
@@ -222,17 +224,17 @@ export const sync = (() => {
 
   return (
     options?: SyncOptions,
-    syncStatusChangeCallback?: SyncStatusChangedCallback,
+    syncStatusChangedCallback?: SyncStatusChangedCallback,
     downloadProgressCallback?: DownloadProgressCallback,
     handleBinaryVersionMismatchCallback?: HandleBinaryVersionMismatchCallback,
   ): Promise<SyncStatus> => {
     let syncStatusCallbackWithTryCatch: SyncStatusChangedCallback | undefined;
     let downloadProgressCallbackWithTryCatch: DownloadProgressCallback | undefined;
 
-    if (typeof syncStatusChangeCallback === 'function') {
+    if (typeof syncStatusChangedCallback === 'function') {
       syncStatusCallbackWithTryCatch = (...args) => {
         try {
-          syncStatusChangeCallback(...args);
+          syncStatusChangedCallback(...args);
         } catch (error) {
           log(`An error has occurred : ${error instanceof Error ? error.stack : 'unknown'}`);
         }

package/src/types.ts

@@ -6,50 +6,78 @@ import type { SyncStatus } from './enums/SyncStatus.enum';
 export interface UpdateDialog {
   /**
    * Indicates whether you would like to append the description of an available release to the
-   * notification message which is displayed to the end user. Defaults to false.
+   * notification message which is displayed to the end user.
+   *
+   * Defaults to false.
    */
   appendReleaseDescription?: boolean;
 
   /**
    * Indicates the string you would like to prefix the release description with, if any, when
-   * displaying the update notification to the end user. Defaults to " Description: "
+   * displaying the update notification to the end user.
+   *
+   * Defaults to " Description: "
    */
   descriptionPrefix?: string;
 
   /**
-   * The text to use for the button the end user must press in order to install a mandatory update. Defaults to "Continue".
+   * The text to use for the button the end user must press in order to install a mandatory update.
+   *
+   * Defaults to "Continue".
    */
   mandatoryContinueButtonLabel?: string;
 
   /**
    * The text used as the body of an update notification, when the update is specified as mandatory.
+   *
    * Defaults to "An update is available that must be installed.".
    */
   mandatoryUpdateMessage?: string;
 
   /**
-   * The text to use for the button the end user can press in order to ignore an optional update that is available. Defaults to "Ignore".
+   * The text to use for the button the end user can press in order to ignore an optional update that is available.
+   *
+   * Defaults to "Ignore".
    */
   optionalIgnoreButtonLabel?: string;
 
   /**
-   * The text to use for the button the end user can press in order to install an optional update. Defaults to "Install".
+   * The text to use for the button the end user can press in order to install an optional update.
+   *
+   * Defaults to "Install".
    */
   optionalInstallButtonLabel?: string;
 
   /**
-   * The text used as the body of an update notification, when the update is optional. Defaults to "An update is available. Would you like to install it?".
+   * The text used as the body of an update notification, when the update is optional.
+   *
+   * Defaults to "An update is available. Would you like to install it?".
    */
   optionalUpdateMessage?: string;
 
   /**
-   * The text used as the header of an update notification that is displayed to the end user. Defaults to "Update available".
+   * The text used as the header of an update notification that is displayed to the end user.
+   *
+   * Defaults to "Update available".
    */
   title?: string;
 }
 
+/**
+ * Called periodically when an available update is being downloaded from the CodePush server.
+ */
 export type DownloadProgressCallback = (progress: DownloadProgress) => void;
+
+/**
+ * Called when the sync process moves from one stage to another in the overall update process.
+ *
+ * The method is called with a status code which represents the current state, and can be any of the `SyncStatus` values.
+ */
 export type SyncStatusChangedCallback = (status: SyncStatus) => void;
+
+/**
+ * Called when there are any binary update available.
+ */
 export type HandleBinaryVersionMismatchCallback = (update: NativeUpdateNotification) => void;
 
 export interface DownloadProgress {
@@ -64,6 +92,9 @@ export interface DownloadProgress {
   receivedBytes: number;
 }
 
+/**
+ * Represents a downloaded update that is either already running, or has been installed and is pending an app restart.
+ */
 export interface LocalPackage extends Package {
   /**
    * Installs the update by saving it to the location on disk where the runtime expects to find the latest version of the app.
@@ -82,7 +113,7 @@ export interface LocalPackage extends Package {
 export interface Package {
   /**
    * The app binary version that this update is dependent on. This is the value that was
-   * specified via the appStoreVersion parameter when calling the CLI's release command.
+   * specified via the --target-binary-version parameter when calling the CLI's release command.
    */
   appVersion: string;
 
@@ -98,11 +129,15 @@ export interface Package {
 
   /**
    * Indicates whether this update has been previously installed but was rolled back.
+   *
+   * The `sync` method will automatically ignore updates which have previously failed, so you only need to worry about this property if using `checkForUpdate`.
    */
   failedInstall: boolean;
 
   /**
    * Indicates whether this is the first time the update has been run after being installed.
+   *
+   * This is useful for determining whether you would like to show a "What's New?" UI to the end user after installing an update.
    */
   isFirstRun: boolean;
 
@@ -133,6 +168,9 @@ export interface Package {
   packageSize: number;
 }
 
+/**
+ * Represents an available update on the CodePush server that hasn't been downloaded yet.
+ */
 export interface RemotePackage extends Package {
   /**
    * Downloads the available update from the CodePush service.
@@ -143,27 +181,31 @@ export interface RemotePackage extends Package {
 
   /**
    * The URL at which the package is available for download.
+   *
+   * This property is only needed for advanced usage, since the `download` method will automatically handle the acquisition of updates for you.
    */
   downloadUrl: string;
 }
 
 export interface SyncOptions {
   /**
-   * Specifies the release channel you want to query for an update against. By default, this value is derived from the Info.plist
-   * file (iOS) and strings resources (Android), but this option allows you to override it from the script-side if you need to
-   * dynamically use a different release channel for a specific call to sync.
+   * Specifies the release channel you want to query for an update against.
+   *
+   * By default, this value is derived from the Info.plist file (iOS) and strings resources (Android), but this option allows you to override it from the JS-side if you need to dynamically use a different release channel for a specific call to sync.
    */
   releaseChannelPublicId?: string;
 
   /**
-   * Specifies when you would like to install optional updates (i.e. those that aren't marked as mandatory).
-   * Defaults to codePush.InstallMode.ON_NEXT_RESTART.
+   * Specifies when you would like to install regular updates (i.e. those that aren't marked as mandatory).
+   *
+   * Defaults to InstallMode.ON_NEXT_RESTART.
    */
   installMode?: InstallMode;
 
   /**
    * Specifies when you would like to install updates which are marked as mandatory.
-   * Defaults to codePush.InstallMode.IMMEDIATE.
+   *
+   * Defaults to InstallMode.IMMEDIATE.
    */
   mandatoryInstallMode?: InstallMode;
 
@@ -176,19 +218,18 @@ export interface SyncOptions {
   minimumBackgroundDuration?: number;
 
   /**
-   * An "options" object used to determine whether a confirmation dialog should be displayed to the end user when an update is available,
-   * and if so, what strings to use. Defaults to null, which has the effect of disabling the dialog completely. Setting this to any truthy
-   * value will enable the dialog with the default strings, and passing an object to this parameter allows enabling the dialog as well as
-   * overriding one or more of the default strings.
+   * Used to determine whether a confirmation dialog should be displayed to the end user when an update is available, and if so, what strings to use.
+   *
+   * Defaults to null, which has the effect of disabling the dialog completely.
+   * Setting this to true will enable the dialog with the default strings, and passing an object to this parameter allows enabling the dialog as well as overriding one or more of the default strings.
    */
   updateDialog?: UpdateDialog | true;
 
   /**
-   * The rollback retry mechanism allows the application to attempt to reinstall an update that was previously rolled back (with the restrictions
-   * specified in the options). It is an "options" object used to determine whether a rollback retry should occur, and if so, what settings to use
-   * for the rollback retry. This defaults to null, which has the effect of disabling the retry mechanism. Setting this to true will enable
-   * the retry mechanism with the default settings, and passing an object to this parameter allows enabling the rollback retry as well as overriding
-   * one or more of the default values.
+   * The rollback retry mechanism allows the application to attempt to reinstall an update that was previously rolled back (with the restrictions specified in the options).
+   *
+   * This defaults to null, which has the effect of disabling the retry mechanism.
+   * Setting this to true will enable the retry mechanism with the default settings, and passing an object to this parameter allows enabling the rollback retry as well as overriding one or more of the default values.
    */
   rollbackRetryOptions?: RollbackRetryOptions | true;
 
@@ -197,14 +238,17 @@ export interface SyncOptions {
 
 export interface RollbackRetryOptions {
   /**
-   * Specifies the minimum time in hours that the app will wait after the latest rollback
-   * before attempting to reinstall same rolled-back package. Defaults to `24`.
+   * Specifies the minimum time in hours that the app will wait after the latest rollback before attempting to reinstall same rolled-back package.
+   *
+   * Defaults to `24`.
    */
   delayInHours?: number;
 
   /**
    * Specifies the maximum number of retry attempts that the app can make before it stops trying.
-   * Cannot be less than `1`. Defaults to `1`.
+   * Cannot be less than `1`.
+   *
+   * Defaults to `1`.
    */
   maxRetryAttempts?: number;
 }

package/typedoc.json

@@ -0,0 +1,9 @@
+{
+  "plugin": ["typedoc-plugin-markdown"],
+  "entryPoints": ["./src/index.ts"],
+  "out": "./docs/api-js",
+  "readme": "none",
+  "formatWithPrettier": true,
+  "includeVersion": true,
+  "disableSources": true
+}

package/docs/advanced-usage.md

@@ -1,56 +0,0 @@
-## Advanced usage
-
-### Multiple environments
-
-#### Staging / Production
-
-In a real-world scenario you would have `Staging` and `Production` apps that are different binaries, each using specific environment config (different package name, bundle identifier, API, feature flags etc). Create a release channel for each of these environments with `appzung release-channels create` and change the `CodePushReleaseChannelPublicId` on the native side with environment variables. You might want to use a module like [react-native-config](https://github.com/lugg/react-native-config) (or do it manually using build variants and configurations).
-
-```groovy
-// android/app/build.gradle
-android {
-    // ...
-    defaultConfig {
-        // ...
-        resValue 'string', "CodePushReleaseChannelPublicId", project.env.get("CODEPUSH_RELEASE_CHANNEL_PUBLIC_ID_ANDROID")
-    }
-}
-```
-
-```
-// ios/myapp/Info.plist
-
-<key>CodePushReleaseChannelPublicId</key>
-<string>$(CODEPUSH_RELEASE_CHANNEL_PUBLIC_ID_IOS)</string>
-```
-
-#### QA / Production
-
-In the case where you have a `QA` environment that is completely iso-prod (meaning you can swap the JS bundle between those two apps), you may take advantage of the `promote` feature:
-
-1. Release a CodePush update to your `QA` release channel using the `appzung releases deploy-react-native` command (or `appzung releases deploy` if you need more control)
-2. Let QA test the build
-3. Promote the tested release from `QA` to `Production` using the `appzung releases promote` command
-
-_NOTE: If you want to take a more cautious approach, you can even choose to perform a "staged rollout" as part of #3, which allows you to mitigate additional potential risk with the update (like did your testing in #2 touch all possible devices/conditions?) by only making the production update available to a percentage of your users (for example `appzung releases promote -r 20`). Then, after waiting for a reasonable amount of time to see if any crash reports or customer feedback comes in, you can expand it to your entire audience by running `appzung releases edit -r 100`._
-
-### Dynamic release channel assignment
-
-The above section illustrated how you can leverage multiple CodePush release channels in order to effectively test your updates before broadly releasing them to your end users. However, since that workflow statically embeds the release channel assignment into the actual binary, a staging or production build will only ever sync updates from that release channel. 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 release channels at runtime.
-
-In order to achieve this kind of workflow, all you need to do is specify the release channel public ID 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 strings resources (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 release channel public ID that the current user should use.
-codePush.sync({ releaseChannelPublicId: userProfile.RELEASE_CHANNEL_PUBLIC_ID });
-```
-
-With that change in place, now it's just a matter of choosing how your app determines the right release channel for the current user. In practice, there are typically two solutions for this:
-
-1. Expose a user-visible mechanism for changing release channels at any time. For example, your settings page could have a toggle for enabling "beta" access. This model works well if you're not concerned with the privacy of your pre-production updates, and you have power users that may want to opt-in to earlier (and potentially buggy) updates at their own will (kind of like Chrome channels). However, this solution puts the decision in the hands of your users, which doesn't help you perform A/B tests transparently.
-2. Annotate the server-side profile of your users with an additional piece of metadata that indicates the release channel 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 release channel, which allows you to incrementally place certain users or groups in different release channels as needed. You could even choose to store the server-response in local storage so that it becomes the new default. How you store the key alongside your user's profiles is entirely up to your authentication solution (for example Auth0, Firebase, custom DB + REST API), but is generally pretty trivial to do.
-
-_NOTE: If needed, you could also implement a hybrid solution that allowed your end-users to toggle between different release channels, while also allowing your server to override that decision. This way, you have a hierarchy of "release channel resolution" that ensures your app has the ability to update itself out-of-the-box, your end users can feel rewarded by getting early access to bits, but you also have the ability to run A/B tests on your users as needed._
-
-Are you using dynamic release channel assignments? Contact us at hello@appzung.com so that we may provide better integration.

package/docs/api-android.md

@@ -1,22 +0,0 @@
-## Java API reference (Android)
-
-You can customize CodePush by placing these values in string resources.
-
-- **Release channel Public ID** - The default release channel's **public ID** that will be used to check updates. For example:
-
-  ```xml
-  <string moduleConfig="true" name="CodePushReleaseChannelPublicId">sU0Eikse9JFCDLZmAT-_lUSwDWACrSGgTKCXyWqcE0</string>
-  ```
-
-- **Public Key** - used for bundle verification in the Code Signing Feature. Please refer to [Code Signing](setup-android.md#code-signing-setup) section for more details about the Code Signing Feature.
-  To set the public key, you should add the content of the public key to `strings.xml` with name `CodePushSigningPublicKey`. CodePush automatically gets this property and enables the Code Signing feature. For example:
-
-  ```xml
-  <string moduleConfig="true" name="CodePushSigningPublicKey">your-public-key</string>
-  ```
-
-- **Server Url** - used for specifying CodePush Server Url (as an Enterprise customer we may setup a custom infra for your needs).
-  The Default value: "https://codepush.appzung.com/" is overridden by adding your path to `strings.xml` with name `CodePushServerUrl`. CodePush automatically gets this property and will use this path to send requests. For example:
-  ```xml
-  <string moduleConfig="true" name="CodePushServerUrl">https://codepush.yourdomain.com</string>
-  ```

package/docs/api-ios.md

@@ -1,19 +0,0 @@
-## Objective-C API reference (iOS)
-
-The Objective-C API is made available by importing the `CodePush.h` header into your `AppDelegate.m` file, and consists of a single public class named `CodePush`.
-
-### CodePush
-
-Contains static methods for retrieving the `NSURL` that represents the most recent JavaScript bundle file, and can be passed to the `RCTRootView`'s `initWithBundleURL` method when bootstrapping your app in the `AppDelegate.m` file.
-
-#### Methods
-
-- **(NSURL \*)bundleURL** - Returns the most recent JS bundle `NSURL` as described above. This method assumes that the name of the JS bundle contained within your app binary is `main.jsbundle`.
-
-- **(NSURL \*)bundleURLForResource:(NSString \*)resourceName** - Equivalent to the `bundleURL` method, but also allows customizing the name of the JS bundle that is looked for within the app binary. This is useful if you aren't naming this file `main` (which is the default convention). This method assumes that the JS bundle's extension is `*.jsbundle`.
-
-- **(NSURL \*)bundleURLForResource:(NSString \*)resourceName withExtension:(NSString \*)resourceExtension**: Equivalent to the `bundleURLForResource:` method, but also allows customizing the extension used by the JS bundle that is looked for within the app binary. This is useful if you aren't naming this file `*.jsbundle` (which is the default convention).
-
-- **(void)overrideAppVersion:(NSString \*)appVersionOverride** - Sets the version of the application's binary interface, which would otherwise default to the App Store version specified as the `CFBundleShortVersionString` in the `Info.plist`. This should be called a single time, before the bundle URL is loaded.
-
-- **(void)setReleaseChannelPublicId:(NSString \*)releaseChannelPublicId** - Sets the release channel public ID that the app should use when querying for updates. This is a dynamic alternative to setting the release channel in your `Info.plist` and/or specifying a release channel in JS when calling `checkForUpdate` or `sync`.