@ibm-aspera/sdk 0.11.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, InitOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, TransferSpec, WebsocketEvent, ReadChunkAsArrayBufferResponse, ReadAsArrayBufferResponse, SdkCapabilities, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse } 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,149 @@ 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.
+ *
+ * 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}.
  *
- * - `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.
+ * @param options - Initialization options. See {@link InitOptions}.
  *
- * - `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 with SDK metadata when the transfer client is ready
  *
- * @returns a promise that resolves if IBM Aspera Desktop is running properly or
- * rejects if unable to connect
+ * @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.
+ *
+ * Supported for Connect and IBM Aspera for desktop. Not supported for HTTP Gateway.
+ *
+ * @param options options including the remote host, SSH port, and timeout.
+ *
+ * @returns a promise that resolves if the SSH port test is successful and rejects otherwise.
+ */
+export declare const testSshPorts: (options: TestSshPortsOptions) => Promise<any>;
+/**
+ * Authenticates a transfer specification against the remote server.
+ *
+ * Supported for Connect and IBM Aspera for desktop. Not supported for HTTP Gateway.
+ *
+ * @param transferSpec the transfer specification to authenticate.
+ *
+ * @returns a promise that resolves if authentication is successful and rejects otherwise.
+ */
+export declare const authenticate: (transferSpec: TransferSpec) => Promise<any>;
 /**
  * Start a transfer
  *
@@ -58,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
+ *
+ * @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: WebsocketEvent) => void) => string;
+export declare const registerStatusCallback: (callback: (status: SdkStatus) => void) => string;
 /**
  * Remove a callback from getting connection status events.
  *
@@ -116,6 +269,16 @@ export declare const showSelectFileDialog: (options?: FileDialogOptions) => Prom
  * @returns a promise that resolves with the selected folder(s) and rejects if user cancels dialog
  */
 export declare const showSelectFolderDialog: (options?: FolderDialogOptions) => Promise<DataTransferResponse>;
+/**
+ * Displays a save file dialog for the user to choose a save location and filename.
+ *
+ * Supported for Connect and IBM Aspera for desktop. Not supported for HTTP Gateway.
+ *
+ * @param options save file dialog options
+ *
+ * @returns a promise that resolves with the selected save path and rejects if user cancels dialog
+ */
+export declare const showSaveFileDialog: (options?: SaveFileDialogOptions) => Promise<DataTransferResponse>;
 /**
  * Shows the about page of the transfer client.
  *
@@ -138,6 +301,26 @@ export declare const showPreferences: () => Promise<any>;
  * @returns a promise that resolves when the transfer manager is opened.
  */
 export declare const showTransferManager: () => Promise<any>;
+/**
+ * Opens the preferences page of the transfer client to a specific tab.
+ *
+ * Supported for Connect and IBM Aspera for desktop. Not supported for HTTP Gateway.
+ *
+ * @param options options including the page (tab) to open
+ *
+ * @returns a promise that resolves when the preferences page is opened.
+ */
+export declare const showPreferencesPage: (options: ShowPreferencesPageOptions) => Promise<any>;
+/**
+ * Opens the transfer rate monitor graph for a specific transfer.
+ *
+ * Supported for Connect and IBM Aspera for desktop. Not supported for HTTP Gateway.
+ *
+ * @param transferId the unique identifier of the transfer to monitor.
+ *
+ * @returns a promise that resolves when the transfer monitor is opened.
+ */
+export declare const showTransferMonitor: (transferId: string) => Promise<any>;
 /**
  * Get all transfers associated with the current application.
  *