@ibm-aspera/sdk 0.16.0 → 0.19.0

package/README.md

@@ -20,6 +20,7 @@ To include this SDK via `script` tag directly in your web application's HTML, re
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@ibm-aspera/sdk@0.2.30/dist/js/aspera-sdk.js"></script>
 ```
+Check npmjs.com for the latest version (https://www.npmjs.com/package/@ibm-aspera/sdk).
 
 ## Usage
 

package/dist/commonjs/app/core.d.ts

@@ -1,5 +1,5 @@
 import { AsperaSdkInfo, TransferResponse } from '../models/aspera-sdk.model';
-import { CustomBrandingOptions, DataTransferResponse, DropzoneEventData, DropzoneOptions, AsperaSdkSpec, AsperaSdkTransfer, FileDialogOptions, FolderDialogOptions, SaveFileDialogOptions, InitOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, TransferSpec, WebsocketEvent, ReadChunkAsArrayBufferResponse, ReadAsArrayBufferResponse, SdkCapabilities, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse, ShowPreferencesPageOptions, TestSshPortsOptions } from '../models/models';
+import { CustomBrandingOptions, DataTransferResponse, DropzoneEventData, DropzoneOptions, AsperaSdkSpec, AsperaSdkTransfer, FileDialogOptions, FolderDialogOptions, SaveFileDialogOptions, InitOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, TransferSpec, ReadChunkAsArrayBufferResponse, ReadAsArrayBufferResponse, SdkCapabilities, SdkStatus, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse, ShowPreferencesPageOptions, TestSshPortsOptions } from '../models/models';
 /**
  * Check if IBM Aspera for Desktop connection works. This function is called by init
  * when initializing the SDK. This function can be used at any point for checking.
@@ -16,24 +16,129 @@ export declare const testConnection: () => Promise<any>;
  */
 export declare const initDragDrop: (initCall?: boolean) => Promise<boolean>;
 /**
- * Initialize IBM Aspera client. If client cannot (reject/catch), then
- * client should attempt fixing server URL or trying again. If still fails disable UI elements.
+ * Get the current SDK lifecycle status synchronously.
  *
- * @param options initialization options:
+ * @returns the current status, or undefined if no init has been called yet
+ */
+export declare const getStatus: () => SdkStatus | undefined;
+/**
+ * Initialize the SDK and connect to a transfer client. Returns a promise that resolves
+ * when the transfer client is ready, or rejects if it cannot be reached.
+ *
+ * By default, the SDK connects to IBM Aspera for desktop. Set `connectSettings.useConnect`
+ * to use IBM Aspera Connect instead. If `httpGatewaySettings` is provided, the gateway is
+ * set up first — when `forceGateway` is true it becomes the sole transport; when false it
+ * is set up as a supplementary transport and the primary client (Desktop or Connect) is
+ * still initialized afterward.
  *
- * - `appId` the unique ID for the website. Transfers initiated during this session
- * will be associated with this ID. It is recommended to use a unique ID to keep transfer
- * information private from other websites.
+ * Note that the promise behavior varies by transfer client. For Desktop, the promise
+ * remains pending until the application is detected. For Connect, the promise resolves
+ * immediately after initialization begins — use {@link registerStatusCallback} to track
+ * when Connect is actually ready. For a non-blocking alternative that provides consistent
+ * lifecycle status events across all transfer clients, see {@link initSession}.
  *
- * - `supportMultipleUsers` when enabled (defaults to false), the SDK will iterate over a port
- * range and generate a session id to determine the running instance of the desktop app for the
- * current user. This is needed when multiple users may be logged into the same machine
- * simultaneously, for example on a Windows Server.
+ * @param options - Initialization options. See {@link InitOptions}.
  *
- * @returns a promise that resolves if IBM Aspera Desktop is running properly or
- * rejects if unable to connect
+ * @returns a promise that resolves with SDK metadata when the transfer client is ready
+ *
+ * @example
+ * init({ appId: 'my-app' })
+ *   .then(() => {
+ *     // Transfer client is ready — enable UI
+ *   })
+ *   .catch(error => {
+ *     // Could not connect — prompt user to install or launch
+ *   });
  */
 export declare const init: (options?: InitOptions) => Promise<any>;
+/**
+ * Initialize the SDK and begin detecting a transfer client. This function returns
+ * immediately — lifecycle status is communicated asynchronously via {@link registerStatusCallback}.
+ *
+ * The SDK supports three transfer clients. By default, IBM Aspera for desktop is used.
+ * Set `connectSettings.useConnect` to use IBM Aspera Connect instead. Desktop and Connect
+ * are mutually exclusive — one or the other is detected, not both.
+ *
+ * ## HTTP Gateway
+ *
+ * HTTP Gateway is a server-side component that enables browser-based transfers without
+ * a desktop application. It can be used in two modes:
+ *
+ * - **Sole transport** (`forceGateway: true`): HTTP Gateway is the only transport.
+ *   No Desktop or Connect detection occurs. Status transitions to `RUNNING` when the
+ *   gateway responds successfully, or `FAILED` if it does not.
+ *
+ * - **Supplementary transport** (`forceGateway: false`): HTTP Gateway is set up first
+ *   as an additional transport for browser-based uploads and downloads. The primary
+ *   transfer client (Desktop or Connect) is then detected separately. If HTTP Gateway
+ *   setup fails, the primary client is still detected. Features that require a desktop
+ *   application (native file dialogs, drag and drop, etc.) are only available when the
+ *   primary client is running.
+ *
+ * ## Status lifecycle
+ *
+ * Use {@link registerStatusCallback} to receive status updates. Use {@link getStatus} to
+ * read the current status synchronously at any time.
+ *
+ * **Desktop path**: `INITIALIZING` → `RUNNING` (app detected), `DEGRADED` (timeout but
+ * HTTP Gateway is available as a supplementary transport), or `FAILED` (timeout, no
+ * fallback). Detection continues in the background after `DEGRADED` or `FAILED` — if the
+ * user launches the app later, the status transitions to `RUNNING`.
+ *
+ * **Connect path**: `INITIALIZING` → `RUNNING`, `FAILED`, `OUTDATED`, or
+ * `EXTENSION_INSTALL` depending on the state of the Connect browser extension
+ * and application.
+ *
+ * **HTTP Gateway path** (`forceGateway: true`): `INITIALIZING` → `RUNNING` or `FAILED`.
+ *
+ * @param options - Initialization options. See {@link InitOptions}.
+ *
+ * @example
+ * // Detect IBM Aspera for desktop (default)
+ * initSession({ appId: 'my-app' });
+ *
+ * @example
+ * // Detect IBM Aspera for desktop with status handling
+ * registerStatusCallback(status => {
+ *   if (status === 'RUNNING') {
+ *     // Transfer client is ready — enable UI
+ *   } else if (status === 'FAILED') {
+ *     // Not detected — prompt user to install or launch
+ *   }
+ * });
+ *
+ * initSession({ appId: 'my-app' });
+ *
+ * @example
+ * // Use IBM Aspera Connect
+ * initSession({
+ *   appId: 'my-app',
+ *   connectSettings: {
+ *     useConnect: true,
+ *   },
+ * });
+ *
+ * @example
+ * // Use HTTP Gateway as the sole transport (no desktop app needed)
+ * initSession({
+ *   appId: 'my-app',
+ *   httpGatewaySettings: {
+ *     url: 'https://example.com/aspera/http-gwy',
+ *     forceGateway: true,
+ *   },
+ * });
+ *
+ * @example
+ * // HTTP Gateway as supplementary transport with Desktop as primary
+ * initSession({
+ *   appId: 'my-app',
+ *   httpGatewaySettings: {
+ *     url: 'https://example.com/aspera/http-gwy',
+ *     forceGateway: false,
+ *   },
+ * });
+ */
+export declare const initSession: (options?: InitOptions) => void;
 /**
  * Tests SSH port connectivity to a transfer server.
  *
@@ -78,17 +183,45 @@ export declare const registerActivityCallback: (callback: (transfers: TransferRe
  */
 export declare const deregisterActivityCallback: (id: string) => void;
 /**
- * Register a callback for getting updates about the connection status of IBM Aspera SDK.
+ * Register a callback for SDK lifecycle status changes. The callback fires immediately
+ * with the current status (if one exists) and again whenever the status changes.
+ *
+ * Status values:
  *
- * For example, to be notified of when the SDK loses connection with the application or connection
- * is re-established. This can be useful if you want to handle the case where the user quits IBM Aspera
- * after `init` has already been called, and want to prompt the user to relaunch the application.
+ * - `INITIALIZING` — The SDK is detecting a transfer client.
+ * - `RUNNING` — A transfer client is ready. Full functionality is available.
+ * - `DEGRADED` — The primary transfer client (IBM Aspera for desktop) was not detected, but HTTP
+ *   Gateway is available as a fallback. This is only available if XXX...
+ * - `FAILED` — No transfer client could be reached. This could be because the user does
+ *    not have a transfer client installed, it is not running, or in the case of HTTP Gateway,
+ *    it was not reachable.
+ * - `DISCONNECTED` — The transfer client was previously running but lost connection. This is specific
+ *    to IBM Aspera for desktop. For example, if the user quits the app this status will trigger.
+ * - `OUTDATED` — (Connect only) The Connect installation needs updating.
+ * - `EXTENSION_INSTALL` — (Connect only) The browser extension needs to be installed.
  *
- * @param callback callback function to receive events
+ * For IBM Aspera for desktop, detection continues in the background after `FAILED` or `DEGRADED`.
+ * If the user launches the application later, the status transitions to `RUNNING`.
+ *
+ * @param callback callback function to receive status events
  *
  * @returns ID representing the callback for deregistration purposes
- */
-export declare const registerStatusCallback: (callback: (status: WebsocketEvent) => void) => string;
+ *
+ * @example
+ * const id = registerStatusCallback(status => {
+ *   if (status === 'RUNNING') {
+ *     // Full functionality — enable all UI
+ *   } else if (status === 'DEGRADED') {
+ *     // Transfers work via HTTP Gateway
+ *   } else if (status === 'FAILED') {
+ *     // Nothing available — prompt user to install
+ *   }
+ * });
+ *
+ * // Later, to stop listening:
+ * deregisterStatusCallback(id);
+ */
+export declare const registerStatusCallback: (callback: (status: SdkStatus) => void) => string;
 /**
  * Remove a callback from getting connection status events.
  *

package/dist/commonjs/app/core.js

@@ -11,14 +11,14 @@ var __assign = (this && this.__assign) || function () {
     return __assign.apply(this, arguments);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasCapability = exports.getCapabilities = exports.readDirectory = exports.getChecksum = exports.readChunkAsArrayBuffer = exports.readAsArrayBuffer = exports.getInfo = exports.removeDropzone = exports.createDropzone = exports.setBranding = exports.modifyTransfer = exports.showDirectory = exports.getFilesList = exports.getTransfer = exports.getAllTransfers = exports.showTransferMonitor = exports.showPreferencesPage = exports.showTransferManager = exports.showPreferences = exports.showAbout = exports.showSaveFileDialog = exports.showSelectFolderDialog = exports.showSelectFileDialog = exports.resumeTransfer = exports.stopTransfer = exports.removeTransfer = exports.deregisterStatusCallback = exports.registerStatusCallback = exports.deregisterActivityCallback = exports.registerActivityCallback = exports.startTransfer = exports.authenticate = exports.testSshPorts = exports.init = exports.initDragDrop = exports.testConnection = void 0;
+exports.hasCapability = exports.getCapabilities = exports.readDirectory = exports.getChecksum = exports.readChunkAsArrayBuffer = exports.readAsArrayBuffer = exports.getInfo = exports.removeDropzone = exports.createDropzone = exports.setBranding = exports.modifyTransfer = exports.showDirectory = exports.getFilesList = exports.getTransfer = exports.getAllTransfers = exports.showTransferMonitor = exports.showPreferencesPage = exports.showTransferManager = exports.showPreferences = exports.showAbout = exports.showSaveFileDialog = exports.showSelectFolderDialog = exports.showSelectFileDialog = exports.resumeTransfer = exports.stopTransfer = exports.removeTransfer = exports.deregisterStatusCallback = exports.registerStatusCallback = exports.deregisterActivityCallback = exports.registerActivityCallback = exports.startTransfer = exports.authenticate = exports.testSshPorts = exports.initSession = exports.init = exports.getStatus = exports.initDragDrop = exports.testConnection = void 0;
 var messages_1 = require("../constants/messages");
 var client_1 = require("../helpers/client/client");
 var helpers_1 = require("../helpers/helpers");
 var http_gateway_1 = require("../http-gateway");
 var core_1 = require("../http-gateway/core");
 var index_1 = require("../index");
-var connect_sdk_js_1 = require("@ibm-aspera/connect-sdk-js");
+var status_1 = require("./status");
 var core_2 = require("../connect/core");
 /**
  * Check if IBM Aspera for Desktop connection works. This function is called by init
@@ -27,8 +27,7 @@ var core_2 = require("../connect/core");
  * @returns a promise that resolves if server can connect or rejects if not
  */
 var testConnection = function () {
-    // FIXME: If force HTTP gateway is false this ends up preventing SDK from verifying IBM Aspera for desktop is running.
-    if (index_1.asperaSdk.useHttpGateway || index_1.asperaSdk.useConnect) {
+    if (index_1.asperaSdk.isReady || index_1.asperaSdk.useConnect) {
         return Promise.resolve(index_1.asperaSdk.globals.sdkResponseData);
     }
     return client_1.client.request('get_info')
@@ -40,12 +39,16 @@ var testConnection = function () {
 };
 exports.testConnection = testConnection;
 /**
- * RPC discovery used internally when initializing the SDK.
+ * RPC discovery used internally during IBM Aspera for desktop initialization to determine
+ * the supported RPC methods of the user's version of IBM Aspera for desktop.
+ *
+ * For convenience, this function will return an empty [] if the SDK is currently configured to use
+ * either HTTP Gateway or Connect transfer clients.
  *
  * @returns a promise that resolves if discovery is successful
  */
 var rpcDiscover = function () {
-    if (index_1.asperaSdk.useConnect || index_1.asperaSdk.useHttpGateway) {
+    if (index_1.asperaSdk.useHttpGateway || index_1.asperaSdk.useConnect) {
         return Promise.resolve({ methods: [] });
     }
     if (!index_1.asperaSdk.isReady) {
@@ -92,99 +95,222 @@ var initDragDrop = function (initCall) {
 };
 exports.initDragDrop = initDragDrop;
 /**
- * Initialize IBM Aspera client. If client cannot (reject/catch), then
- * client should attempt fixing server URL or trying again. If still fails disable UI elements.
- *
- * @param options initialization options:
- *
- * - `appId` the unique ID for the website. Transfers initiated during this session
- * will be associated with this ID. It is recommended to use a unique ID to keep transfer
- * information private from other websites.
+ * Get the current SDK lifecycle status synchronously.
  *
- * - `supportMultipleUsers` when enabled (defaults to false), the SDK will iterate over a port
- * range and generate a session id to determine the running instance of the desktop app for the
- * current user. This is needed when multiple users may be logged into the same machine
- * simultaneously, for example on a Windows Server.
- *
- * @returns a promise that resolves if IBM Aspera Desktop is running properly or
- * rejects if unable to connect
+ * @returns the current status, or undefined if no init has been called yet
  */
-var init = function (options) {
-    var _a, _b, _c;
-    var appId = (_a = options === null || options === void 0 ? void 0 : options.appId) !== null && _a !== void 0 ? _a : (0, helpers_1.randomUUID)();
-    index_1.asperaSdk.globals.appId = appId;
+var getStatus = function () {
+    return status_1.statusService.getStatus();
+};
+exports.getStatus = getStatus;
+var setupAppId = function (options) {
+    var _a;
+    index_1.asperaSdk.globals.appId = (_a = options === null || options === void 0 ? void 0 : options.appId) !== null && _a !== void 0 ? _a : (0, helpers_1.randomUUID)();
     if (options === null || options === void 0 ? void 0 : options.supportMultipleUsers) {
         index_1.asperaSdk.globals.supportMultipleUsers = true;
         index_1.asperaSdk.globals.sessionId = (0, helpers_1.randomUUID)();
     }
+};
+var connectDesktop = function () {
+    return index_1.asperaSdk.activityTracking.setup()
+        .then(function () { return (0, exports.testConnection)(); })
+        .then(function () { return rpcDiscover(); })
+        .then(function () { return (0, exports.initDragDrop)(true); })
+        .then(function () { return undefined; });
+};
+/**
+ * Initialize the SDK and connect to a transfer client. Returns a promise that resolves
+ * when the transfer client is ready, or rejects if it cannot be reached.
+ *
+ * By default, the SDK connects to IBM Aspera for desktop. Set `connectSettings.useConnect`
+ * to use IBM Aspera Connect instead. If `httpGatewaySettings` is provided, the gateway is
+ * set up first — when `forceGateway` is true it becomes the sole transport; when false it
+ * is set up as a supplementary transport and the primary client (Desktop or Connect) is
+ * still initialized afterward.
+ *
+ * Note that the promise behavior varies by transfer client. For Desktop, the promise
+ * remains pending until the application is detected. For Connect, the promise resolves
+ * immediately after initialization begins — use {@link registerStatusCallback} to track
+ * when Connect is actually ready. For a non-blocking alternative that provides consistent
+ * lifecycle status events across all transfer clients, see {@link initSession}.
+ *
+ * @param options - Initialization options. See {@link InitOptions}.
+ *
+ * @returns a promise that resolves with SDK metadata when the transfer client is ready
+ *
+ * @example
+ * init({ appId: 'my-app' })
+ *   .then(() => {
+ *     // Transfer client is ready — enable UI
+ *   })
+ *   .catch(error => {
+ *     // Could not connect — prompt user to install or launch
+ *   });
+ */
+var init = function (options) {
+    var _a;
+    setupAppId(options);
     var handleErrors = function (error) {
         (0, helpers_1.errorLog)(messages_1.messages.serverError, error);
         index_1.asperaSdk.globals.asperaAppVerified = false;
         throw (0, helpers_1.generateErrorBody)(messages_1.messages.serverError, error);
     };
-    var getConnectStartCalls = function () {
-        index_1.asperaSdk.globals.connect = new connect_sdk_js_1.Connect({
-            minVersion: options.connectSettings.minVersion || '3.10.1',
-            dragDropEnabled: options.connectSettings.dragDropEnabled,
-            connectMethod: options.connectSettings.method,
-        });
-        index_1.asperaSdk.globals.connectInstaller = new connect_sdk_js_1.ConnectInstaller({
-            sdkLocation: options.connectSettings.sdkLocation,
-            correlationId: options.connectSettings.correlationId,
-            style: 'carbon',
-            version: options.connectSettings.version,
-        });
-        index_1.asperaSdk.globals.connectAW4 = {
-            Connect: connect_sdk_js_1.Connect,
-            ConnectInstaller: connect_sdk_js_1.ConnectInstaller,
-        };
-        return (0, core_2.initConnect)(!options.connectSettings.hideIncludedInstaller);
-    };
     var getDesktopStartCalls = function () {
-        return index_1.asperaSdk.activityTracking.setup()
-            .then(function () { return (0, exports.testConnection)(); })
-            .then(function () { return rpcDiscover(); })
-            .then(function () { return (0, exports.initDragDrop)(true); })
+        return connectDesktop()
             .then(function () { return index_1.asperaSdk.globals.sdkResponseData; })
             .catch(handleErrors);
     };
-    if (((_b = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _b === void 0 ? void 0 : _b.url) && !index_1.asperaSdk.globals.httpGatewayVerified) {
-        var finalHttpGatewayUrl = options.httpGatewaySettings.url.trim();
-        if (finalHttpGatewayUrl.indexOf('http') !== 0) {
-            finalHttpGatewayUrl = "https://".concat(finalHttpGatewayUrl);
-        }
-        if (finalHttpGatewayUrl.endsWith('/')) {
-            finalHttpGatewayUrl = finalHttpGatewayUrl.slice(0, -1);
-        }
-        index_1.asperaSdk.globals.httpGatewayUrl = finalHttpGatewayUrl;
-        return fetch("".concat(index_1.asperaSdk.globals.httpGatewayUrl, "/info"), { method: 'GET' }).then(function (response) {
-            return response.json().then(function (responseData) {
-                if (response.status >= 400) {
-                    throw Error(responseData);
-                }
-                return responseData;
-            });
-        }).then(function (response) {
-            return (0, http_gateway_1.initHttpGateway)(response);
-        }).then(function () {
-            var _a, _b;
+    var getTransferClientCalls = function () {
+        var _a;
+        return ((_a = options === null || options === void 0 ? void 0 : options.connectSettings) === null || _a === void 0 ? void 0 : _a.useConnect) ? (0, core_2.initConnect)(options.connectSettings) : getDesktopStartCalls();
+    };
+    if (((_a = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _a === void 0 ? void 0 : _a.url) && !index_1.asperaSdk.globals.httpGatewayVerified) {
+        return (0, http_gateway_1.setupHttpGateway)(options.httpGatewaySettings.url).then(function () {
+            var _a;
             if ((_a = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _a === void 0 ? void 0 : _a.forceGateway) {
                 return Promise.resolve(index_1.asperaSdk.globals.sdkResponseData);
             }
-            return ((_b = options === null || options === void 0 ? void 0 : options.connectSettings) === null || _b === void 0 ? void 0 : _b.useConnect) ? getConnectStartCalls() : getDesktopStartCalls();
+            return getTransferClientCalls();
         }).catch(function (error) {
-            var _a, _b;
-            // If HTTP Gateway fails log and move on to transfer client
+            var _a;
             (0, helpers_1.errorLog)(messages_1.messages.httpInitFail, error);
             if ((_a = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _a === void 0 ? void 0 : _a.forceGateway) {
                 throw (0, helpers_1.generateErrorBody)(messages_1.messages.httpInitFail, error);
             }
-            return ((_b = options === null || options === void 0 ? void 0 : options.connectSettings) === null || _b === void 0 ? void 0 : _b.useConnect) ? getConnectStartCalls() : getDesktopStartCalls();
+            return getTransferClientCalls();
         });
     }
-    return ((_c = options === null || options === void 0 ? void 0 : options.connectSettings) === null || _c === void 0 ? void 0 : _c.useConnect) ? getConnectStartCalls() : getDesktopStartCalls();
+    return getTransferClientCalls();
 };
 exports.init = init;
+/**
+ * Initialize the SDK and begin detecting a transfer client. This function returns
+ * immediately — lifecycle status is communicated asynchronously via {@link registerStatusCallback}.
+ *
+ * The SDK supports three transfer clients. By default, IBM Aspera for desktop is used.
+ * Set `connectSettings.useConnect` to use IBM Aspera Connect instead. Desktop and Connect
+ * are mutually exclusive — one or the other is detected, not both.
+ *
+ * ## HTTP Gateway
+ *
+ * HTTP Gateway is a server-side component that enables browser-based transfers without
+ * a desktop application. It can be used in two modes:
+ *
+ * - **Sole transport** (`forceGateway: true`): HTTP Gateway is the only transport.
+ *   No Desktop or Connect detection occurs. Status transitions to `RUNNING` when the
+ *   gateway responds successfully, or `FAILED` if it does not.
+ *
+ * - **Supplementary transport** (`forceGateway: false`): HTTP Gateway is set up first
+ *   as an additional transport for browser-based uploads and downloads. The primary
+ *   transfer client (Desktop or Connect) is then detected separately. If HTTP Gateway
+ *   setup fails, the primary client is still detected. Features that require a desktop
+ *   application (native file dialogs, drag and drop, etc.) are only available when the
+ *   primary client is running.
+ *
+ * ## Status lifecycle
+ *
+ * Use {@link registerStatusCallback} to receive status updates. Use {@link getStatus} to
+ * read the current status synchronously at any time.
+ *
+ * **Desktop path**: `INITIALIZING` → `RUNNING` (app detected), `DEGRADED` (timeout but
+ * HTTP Gateway is available as a supplementary transport), or `FAILED` (timeout, no
+ * fallback). Detection continues in the background after `DEGRADED` or `FAILED` — if the
+ * user launches the app later, the status transitions to `RUNNING`.
+ *
+ * **Connect path**: `INITIALIZING` → `RUNNING`, `FAILED`, `OUTDATED`, or
+ * `EXTENSION_INSTALL` depending on the state of the Connect browser extension
+ * and application.
+ *
+ * **HTTP Gateway path** (`forceGateway: true`): `INITIALIZING` → `RUNNING` or `FAILED`.
+ *
+ * @param options - Initialization options. See {@link InitOptions}.
+ *
+ * @example
+ * // Detect IBM Aspera for desktop (default)
+ * initSession({ appId: 'my-app' });
+ *
+ * @example
+ * // Detect IBM Aspera for desktop with status handling
+ * registerStatusCallback(status => {
+ *   if (status === 'RUNNING') {
+ *     // Transfer client is ready — enable UI
+ *   } else if (status === 'FAILED') {
+ *     // Not detected — prompt user to install or launch
+ *   }
+ * });
+ *
+ * initSession({ appId: 'my-app' });
+ *
+ * @example
+ * // Use IBM Aspera Connect
+ * initSession({
+ *   appId: 'my-app',
+ *   connectSettings: {
+ *     useConnect: true,
+ *   },
+ * });
+ *
+ * @example
+ * // Use HTTP Gateway as the sole transport (no desktop app needed)
+ * initSession({
+ *   appId: 'my-app',
+ *   httpGatewaySettings: {
+ *     url: 'https://example.com/aspera/http-gwy',
+ *     forceGateway: true,
+ *   },
+ * });
+ *
+ * @example
+ * // HTTP Gateway as supplementary transport with Desktop as primary
+ * initSession({
+ *   appId: 'my-app',
+ *   httpGatewaySettings: {
+ *     url: 'https://example.com/aspera/http-gwy',
+ *     forceGateway: false,
+ *   },
+ * });
+ */
+var initSession = function (options) {
+    var _a, _b, _c;
+    setupAppId(options);
+    var retryInterval = (_a = options === null || options === void 0 ? void 0 : options.retryInterval) !== null && _a !== void 0 ? _a : 2000;
+    var retryTimeout = (_b = options === null || options === void 0 ? void 0 : options.retryTimeout) !== null && _b !== void 0 ? _b : 5000;
+    var startDesktopDetection = function () {
+        status_1.statusService.startPolling(connectDesktop, retryInterval, retryTimeout);
+    };
+    var startTransferClient = function () {
+        var _a;
+        if ((_a = options === null || options === void 0 ? void 0 : options.connectSettings) === null || _a === void 0 ? void 0 : _a.useConnect) {
+            (0, core_2.initConnect)(options.connectSettings);
+        }
+        else {
+            startDesktopDetection();
+        }
+    };
+    // HTTP Gateway path
+    if (((_c = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _c === void 0 ? void 0 : _c.url) && !index_1.asperaSdk.globals.httpGatewayVerified) {
+        status_1.statusService.setStatus('INITIALIZING');
+        (0, http_gateway_1.setupHttpGateway)(options.httpGatewaySettings.url).then(function () {
+            var _a;
+            if ((_a = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _a === void 0 ? void 0 : _a.forceGateway) {
+                status_1.statusService.setStatus('RUNNING');
+                return;
+            }
+            startTransferClient();
+        }).catch(function (error) {
+            var _a;
+            (0, helpers_1.errorLog)(messages_1.messages.httpInitFail, error);
+            if ((_a = options === null || options === void 0 ? void 0 : options.httpGatewaySettings) === null || _a === void 0 ? void 0 : _a.forceGateway) {
+                status_1.statusService.setStatus('FAILED');
+                return;
+            }
+            startTransferClient();
+        });
+        return;
+    }
+    startTransferClient();
+};
+exports.initSession = initSession;
 /**
  * Tests SSH port connectivity to a transfer server.
  *
@@ -319,18 +445,46 @@ var deregisterActivityCallback = function (id) {
 };
 exports.deregisterActivityCallback = deregisterActivityCallback;
 /**
- * Register a callback for getting updates about the connection status of IBM Aspera SDK.
+ * Register a callback for SDK lifecycle status changes. The callback fires immediately
+ * with the current status (if one exists) and again whenever the status changes.
  *
- * For example, to be notified of when the SDK loses connection with the application or connection
- * is re-established. This can be useful if you want to handle the case where the user quits IBM Aspera
- * after `init` has already been called, and want to prompt the user to relaunch the application.
+ * Status values:
  *
- * @param callback callback function to receive events
+ * - `INITIALIZING` — The SDK is detecting a transfer client.
+ * - `RUNNING` — A transfer client is ready. Full functionality is available.
+ * - `DEGRADED` — The primary transfer client (IBM Aspera for desktop) was not detected, but HTTP
+ *   Gateway is available as a fallback. This is only available if XXX...
+ * - `FAILED` — No transfer client could be reached. This could be because the user does
+ *    not have a transfer client installed, it is not running, or in the case of HTTP Gateway,
+ *    it was not reachable.
+ * - `DISCONNECTED` — The transfer client was previously running but lost connection. This is specific
+ *    to IBM Aspera for desktop. For example, if the user quits the app this status will trigger.
+ * - `OUTDATED` — (Connect only) The Connect installation needs updating.
+ * - `EXTENSION_INSTALL` — (Connect only) The browser extension needs to be installed.
+ *
+ * For IBM Aspera for desktop, detection continues in the background after `FAILED` or `DEGRADED`.
+ * If the user launches the application later, the status transitions to `RUNNING`.
+ *
+ * @param callback callback function to receive status events
  *
  * @returns ID representing the callback for deregistration purposes
+ *
+ * @example
+ * const id = registerStatusCallback(status => {
+ *   if (status === 'RUNNING') {
+ *     // Full functionality — enable all UI
+ *   } else if (status === 'DEGRADED') {
+ *     // Transfers work via HTTP Gateway
+ *   } else if (status === 'FAILED') {
+ *     // Nothing available — prompt user to install
+ *   }
+ * });
+ *
+ * // Later, to stop listening:
+ * deregisterStatusCallback(id);
  */
 var registerStatusCallback = function (callback) {
-    return index_1.asperaSdk.activityTracking.setWebSocketEventCallback(callback);
+    return status_1.statusService.registerCallback(callback);
 };
 exports.registerStatusCallback = registerStatusCallback;
 /**
@@ -339,7 +493,7 @@ exports.registerStatusCallback = registerStatusCallback;
  * @param id the ID returned by `registerStatusCallback`
  */
 var deregisterStatusCallback = function (id) {
-    index_1.asperaSdk.activityTracking.removeWebSocketEventCallback(id);
+    status_1.statusService.deregisterCallback(id);
 };
 exports.deregisterStatusCallback = deregisterStatusCallback;
 /**

package/dist/commonjs/app/status.d.ts

@@ -0,0 +1,24 @@
+import { SdkStatus } from '../models/models';
+type StatusCallback = (status: SdkStatus) => void;
+declare class StatusService {
+    private currentStatus;
+    private callbacks;
+    private pollTimerId;
+    private failTimeoutId;
+    getStatus(): SdkStatus | undefined;
+    setStatus(status: SdkStatus): void;
+    registerCallback(cb: StatusCallback): string;
+    deregisterCallback(id: string): void;
+    /**
+     * Start Desktop detection polling loop.
+     *
+     * @param detectFn async function that resolves if Desktop is found, rejects if not
+     * @param interval ms between attempts
+     * @param failTimeout ms before transitioning to FAILED or DEGRADED
+     */
+    startPolling(detectFn: () => Promise<void>, interval: number, failTimeout: number): void;
+    stopPolling(): void;
+    reset(): void;
+}
+export declare const statusService: StatusService;
+export {};