@ibm-aspera/sdk 0.16.0 → 0.19.1

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:
+ *
+ * - `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 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.
+ * 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 events
+ * @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.
  *
@@ -304,11 +437,12 @@ export declare const readDirectory: (options: ReadDirectoryOptions) => Promise<R
  * Returns an object describing the high-level capabilities supported by the user's
  * transfer client (e.g. IBM Aspera for desktop, Connect, or HTTP Gateway).
  *
- * Use this for feature detection at a semantic level rather than checking individual RPC methods.
- * Capabitilies may depend on multiple underlying RPC methods and also may vary by transfer client.
+ * Use this for feature detection at a semantic level as capabilities may change depending on the
+ * transfer client.
  *
- * Some capabitilies may depend on newer versions of the transfer client. This function may be useful
- * if you want to conditionally perform certain actions rather than potentially getting an error.
+ * Rather than caching the return value of this function, it's recommended to call it on the fly as
+ * capabilities may change if your application supports multiple transfer clients. As a result, it's
+ * recommend to use the slightly more ergonomic {@link hasCapability}.
  *
  * @returns an object with boolean flags for each capability.
  *
@@ -322,10 +456,18 @@ export declare const readDirectory: (options: ReadDirectoryOptions) => Promise<R
  */
 export declare const getCapabilities: () => SdkCapabilities;
 /**
- * Check if the SDK and underlying transfer client supports a specific capability.
+ * Check if the SDK and underlying transfer client supports a specific capability or feature.
  *
  * Capabilities depend on the transfer client being used (HTTP Gateway, Connect, or IBM Aspera for desktop).
- * Use this function to conditionally enable/disable features in your application.
+ *
+ * This function may be useful if you want to conditionally perform certain actions rather than
+ * potentially getting an error.
+ *
+ * For example, only IBM Aspera for desktop supports traversing a folder's contents. An application can
+ * check `hasCapability('readDirectory')` to optionally show a folder browser only when the feature is available.
+ * For example, when a user does not have IBM Aspera for desktop installed and is using HTTP Gateway, your
+ * application can disable this feature. Later, if that same user installs IBM Aspera for desktop, your application
+ * will show the feature as enabled without any additional changes.
  *
  * @param capability the capability to check.
  *
@@ -335,7 +477,7 @@ export declare const getCapabilities: () => SdkCapabilities;
  * ```typescript
  * // Determine if your web application can render image previews for user selected files
  * if (asperaSdk.hasCapability('imagePreview')) {
- *   asperaSdk.readAsArrayBuffer(path);
+ *   const response = await asperaSdk.readAsArrayBuffer(path);
  * }
  * ```
  */