@ibm-aspera/sdk 0.2.9 → 0.2.29

package/src/app/installer.ts

@@ -0,0 +1,53 @@
+import {asperaSdk} from '../index';
+import {errorLog, generateErrorBody, generatePromiseObjects, getCurrentPlatform, isValidURL, throwError} from '../helpers/helpers';
+import {apiGet} from '../helpers/http';
+import {messages} from '../constants/messages';
+import {InstallerInfoResponse, InstallerOptions} from '../models/models';
+
+/**
+ * Get the latest Aspera SDK installer information such as download URL and version.
+ *
+ * @param options Installer info options
+ *
+ * @returns a promise that resolves with the installer info and rejects if there is an error
+ */
+export const getInstallerInfo = (options: InstallerOptions = {}): Promise<InstallerInfoResponse> => {
+  let url = options.endpoint || asperaSdk.globals.installerUrl;
+
+  if (url.endsWith('/latest.json')) {
+    url = url.replace('/latest.json', '');
+  }
+
+  if (!isValidURL(url)) {
+    return throwError(messages.invalidEndpoint, {url});
+  }
+
+  const promiseInfo = generatePromiseObjects();
+
+  apiGet(`${url}/latest.json`).then(response => {
+    response.json().then((data: InstallerInfoResponse) => {
+      if (options.endpoint) {
+        for (const entry of data.entries) {
+          if (!isValidURL(entry.url)) {
+            entry.url = `${options.endpoint}/${entry.url}`;
+          }
+        }
+      }
+
+      if (options.all) {
+        promiseInfo.resolver(data);
+      } else {
+        const platform = getCurrentPlatform();
+        data.entries = data.entries.filter(entry => entry.platform === platform);
+
+        promiseInfo.resolver(data);
+      }
+    });
+  }).catch(error => {
+    errorLog(messages.getInstallerError, error);
+
+    promiseInfo.rejecter(generateErrorBody(messages.getInstallerError, error));
+  });
+
+  return promiseInfo.promise;
+};

package/src/connect/core.ts

@@ -0,0 +1,83 @@
+import {asperaSdk} from '../index';
+import {Connect} from '@ibm-aspera/connect-sdk-js';
+import * as ConnectTypes from '@ibm-aspera/connect-sdk-js/dist/esm/core/types';
+
+let transferMonitorActivated = false;
+let installerFlowActivated = false;
+
+/**
+ * Connect Core Logic
+ *
+ * @remarks
+ * Most logic is called directly by Desktop SDK functions
+ * You may not need to import anything from this file.
+ */
+
+export const handleTransfers = (transfers: ConnectTypes.TransferInfo[]): void => {
+  asperaSdk.activityTracking.handleTransferActivity({
+    type: 'transferUpdated',
+    data: {transfers},
+  });
+};
+
+export const connectInstallationFlow = (): void => {
+  if (installerFlowActivated) {
+    return;
+  }
+
+  installerFlowActivated = true;
+
+  const handleInstallerEvent = (eventType: ConnectTypes.EventString, eventStatus: ConnectTypes.ConnectStatusStrings) => {
+    // Verify that the event matches
+    if (asperaSdk.globals.connectAW4.Connect.EVENT.STATUS !== eventType) {
+      return;
+    }
+
+    // Depending on status show the proper installer screen
+    switch (eventStatus) {
+    case asperaSdk.globals.connectAW4.Connect.STATUS.INITIALIZING:
+      asperaSdk.globals.connectInstaller.showLaunching();
+      break;
+    case asperaSdk.globals.connectAW4.Connect.STATUS.EXTENSION_INSTALL:
+      asperaSdk.globals.connectInstaller.showExtensionInstall();
+      break;
+    case asperaSdk.globals.connectAW4.Connect.STATUS.FAILED:
+      asperaSdk.globals.connectInstaller.showDownload();
+      break;
+    case asperaSdk.globals.connectAW4.Connect.STATUS.OUTDATED:
+      asperaSdk.globals.connectInstaller.showUpdate();
+      break;
+    case asperaSdk.globals.connectAW4.Connect.STATUS.RUNNING:
+      asperaSdk.globals.connectInstaller.connected();
+      break;
+    }
+  };
+
+  asperaSdk.globals.connect.addEventListener(asperaSdk.globals.connectAW4.Connect.EVENT.STATUS, handleInstallerEvent);
+};
+
+export const initConnect = (useIncludedInstaller?: boolean): Promise<unknown> => {
+  asperaSdk.globals.connect.addEventListener(Connect.EVENT.STATUS, (eventType, eventStatus: ConnectTypes.ConnectStatusStrings) => {
+    if (eventType === Connect.EVENT.STATUS) {
+      asperaSdk.globals.connectStatus = eventStatus;
+
+      asperaSdk.activityTracking.sendManualEventCallback(eventStatus);
+
+      if (eventStatus === 'RUNNING' && !transferMonitorActivated) {
+        transferMonitorActivated = true;
+        asperaSdk.globals.connect.addEventListener(Connect.EVENT.TRANSFER, (_event, data: ConnectTypes.AllTransfersInfo) => {
+          handleTransfers(data.transfers);
+        });
+      }
+    }
+  });
+
+  asperaSdk.globals.connect.initSession(asperaSdk.globals.appId);
+
+  if (useIncludedInstaller) {
+    connectInstallationFlow();
+  }
+
+
+  return Promise.resolve({connectMode: true});
+};

package/src/constants/constants.ts

@@ -0,0 +1,19 @@
+/** @ignore */
+export const hiddenStyleList = `
+  display: none !important;
+  width: 1px !important;
+  height: 1px !important;
+  position: fixed !important;
+  z-index: -99 !important;
+  bottom: 0px !important;
+  right: 0px !important;
+`;
+
+/** @ignore */
+export const protocol = 'aspera://';
+
+/** @ignore */
+export const baseInstallerUrl = 'https://downloads.ibmaspera.com/downloads/desktop';
+
+/** @ignore */
+export const installerUrl = `${baseInstallerUrl}/latest/stable`;

package/src/constants/messages.ts

@@ -0,0 +1,35 @@
+/** @ignore */
+export const messages = {
+  callbackIsNotFunction: 'The provided callback is not a function',
+  dragDropInitFailed: 'Unable to initialize drag-drop',
+  dragDropInitFailedInit: 'Unable to initialize drag-drop as part of init flow',
+  failedToGenerateIframe: 'Unable to generate IFRAME for download. Using new window',
+  getInstallerError: 'Unable to get latest installers',
+  getAllTransfersFailed: 'Unable to get all transfers',
+  getTransferFailed: 'Unable to get transfer',
+  invalidEndpoint: 'The specified endpoint is not a valid URL',
+  loadingProtocol: 'Launching IBM Aspera for Desktop',
+  modifyTransferFailed: 'Unable to modify transfer',
+  notValidTransferSpec: 'The supplied transferSpec is not valid',
+  removeTransferFailed: 'Unable to remove transfer',
+  resumeTransferFailed: 'Unable to resume transfer',
+  serverError: 'Unable to connect to IBM Aspera for Desktop server',
+  serverNotVerified: 'IBM Aspera SDK has not been verified. Run test or init first',
+  setBrandingFailed: 'Unable to set custom branding',
+  showDirectoryFailed: 'Unable to show transfer directory',
+  showSelectFileDialogFailed: 'Unable to show select file dialog',
+  showSelectFolderDialogFailed: 'Unable to show select folder dialog',
+  showPreferencesFailed: 'Unable to show preferences',
+  stopTransferFailed: 'Unable to stop transfer',
+  transferFailed: 'The transfer failed to initiate',
+  unableToFindElementOnPage: 'Unable to find the element on the current page',
+  unableToReadDropped: 'The dropped item could not be parsed. Please try selecting via the select file/folder option',
+  websocketClosedError: 'The websocket was closed due to an error',
+  websocketClosedUnexpect: 'The websocket was closed unexpectedly',
+  websocketNotReady: 'The websocket is not ready. Run init first',
+  httpNotAvailable: 'IBM Aspera HTTP Gateway is not available',
+  httpInitFail: 'IBM Aspera HTTP Gateway could not be started',
+  filePickerCancel: 'User canceled the select file or folder dialog.',
+  fileNotAllowed: 'TransferSpec contained file not selected by user.',
+  httpNetworkFail: 'HTTP network encountered unknown error.',
+};

package/src/helpers/client/client.ts

@@ -0,0 +1,11 @@
+import {httpClient} from './http-client';
+import {safariClient} from './safari-client';
+import {isSafari} from '../helpers';
+
+interface Client {
+  request(method: String, payload?: any): Promise<any>;
+}
+
+export const client: Client = isSafari() ? safariClient : httpClient;
+
+export default Client;

package/src/helpers/client/http-client.ts

@@ -0,0 +1,92 @@
+import {JSONRPCClient, JSONRPCRequest} from 'json-rpc-2.0';
+import Client from './client';
+import {generatePromiseObjects, safeJsonString} from '../helpers';
+import {asperaSdk} from '../../index';
+
+export const getRpcServerUrl = (): string => {
+  return `${asperaSdk.globals.asperaAppUrl}:${asperaSdk.globals.rpcPort}`;
+};
+
+/**
+ * Wraps a promise like object and returns a promise that supports catch.
+ *
+ * @param promise the HTTP promise like to wrap
+ *
+ * @returns promise for the HTTP connection with catch supporting error
+ */
+export const handlePromiseLikeErrors = (promise: PromiseLike<any>): Promise<any> => {
+  const promiseInfo = generatePromiseObjects();
+
+  promise.then(response => {
+    promiseInfo.resolver(response);
+  }, error => {
+    promiseInfo.rejecter(error);
+  });
+
+  return promiseInfo.promise;
+};
+
+/**
+ * JSON RPC client using HTTP (fetch) as transport.
+ */
+class JSONRPCHttpClient {
+  /** JSON-RPC client used to make requests */
+  client: JSONRPCClient;
+
+  constructor() {
+    this.client = new JSONRPCClient(this.handleRequest);
+  }
+
+  /**
+   * Request handler for the JSON-RPC client. This function is called by the JSON-RPC library
+   * after forming the RPC request.
+   *
+   * @param request JSON-RPC request to send to the server
+   */
+  private handleRequest = (request: JSONRPCRequest) => {
+    const options = {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+      },
+      body: safeJsonString(request),
+    };
+
+    const rpcServerURL = getRpcServerUrl();
+
+    return fetch(rpcServerURL, options).then(response => {
+      if (response.ok) {
+        return response.json().then(rpcResponse => this.client.receive(rpcResponse));
+      } else if (request.id !== undefined) {
+        throw Promise.reject(response.statusText);
+      }
+    });
+  };
+
+  request = (method: string, data: any): PromiseLike<any> => {
+    return this.client.request(method, data);
+  };
+}
+
+/**
+ * Client used for making requests to Aspera.
+ */
+class HttpClient implements Client {
+  /** HTTP client used to make requests */
+  httpClient: JSONRPCHttpClient;
+
+  constructor() {
+    this.httpClient = new JSONRPCHttpClient();
+  };
+
+  request = (method: string, payload: any = {}): Promise<any> => {
+    return handlePromiseLikeErrors(this.httpClient.request(method, payload));
+  };
+}
+
+export const httpClient = new HttpClient();
+
+export default {
+  httpClient,
+  handlePromiseLikeErrors,
+};

package/src/helpers/client/safari-client.ts

@@ -0,0 +1,334 @@
+import Client from './client';
+import {randomUUID, safeJsonString} from '../helpers';
+import {asperaSdk} from '../../index';
+
+/**
+ * Enum defining different types of Safari extension events.
+ */
+enum SafariExtensionEventType {
+  Monitor = 'Monitor',
+  Ping = 'Ping',
+  Request = 'Request'
+}
+
+/**
+ * Interface representing a JSON-RPC request object.
+ */
+interface JSONRPCRequest {
+  id: string;
+  jsonrpc: string;
+  method: string;
+  params: any;
+}
+
+/**
+ * Interface representing a JSON-RPC response object.
+ */
+interface JSONRPCResponse {
+  id: string;
+  jsonrpc: string;
+  result?: any;
+  error?: any;
+}
+
+/**
+ * Interface representing a promise executor used in a promise.
+ */
+export interface PromiseExecutor {
+  resolve: (value: any) => void;
+  reject: (error: any) => void;
+}
+
+/**
+ * Global keep alive timeout to prevent recursion.
+ */
+let keepAliveTimeout: ReturnType<typeof setTimeout>;
+
+/**
+ * Handles communication with the Safari extension using JSON-RPC over custom events.
+ */
+export class SafariClient implements Client {
+  private keepAliveInterval = 1000;
+  private promiseExecutors: Map<string, PromiseExecutor>;
+
+  private lastPing: number|null = null;
+  private lastPong: number|null = null;
+  private safariExtensionEnabled = false;
+  private subscribedTransferActivity = false;
+
+  /**
+   * Initializes the SafariExtensionHandler instance.
+   * Sets up the promise executor map and starts listening to extension events.
+   */
+  constructor() {
+    this.promiseExecutors = new Map();
+    this.listenResponseEvents();
+    this.listenTransferActivityEvents();
+    this.listenStatusEvents();
+    this.listenClientStatusEvents();
+    this.listenPongEvents();
+
+    if (keepAliveTimeout) {
+      clearTimeout(keepAliveTimeout);
+    }
+
+    this.keepAlive();
+  }
+
+  /**
+   * Sends a JSON-RPC request to the Safari extension.
+   * @param method The method name to invoke on the extension.
+   * @param payload Optional payload for the request.
+   * @returns A Promise that resolves with the response from the extension.
+   */
+  request = (method: string, payload: any = {}): Promise<any> => {
+    return this.dispatchPromiseEvent(
+      SafariExtensionEventType.Request,
+      method,
+      payload
+    );
+  };
+
+  /**
+   * Monitors transfer activity.
+   * @returns A Promise that resolves with the response from the extension.
+   */
+  public monitorTransferActivity(): Promise<unknown> {
+    const dispatchMonitorEvent = (): Promise<unknown> => {
+      const promise =  this.dispatchPromiseEvent(
+        SafariExtensionEventType.Monitor,
+        'subscribe_transfer_activity',
+        [asperaSdk.globals.appId]
+      );
+
+      return promise.then(() => {
+        this.subscribedTransferActivity = true;
+      });
+    };
+
+    if (this.safariExtensionEnabled) {
+      return dispatchMonitorEvent();
+    }
+
+    return new Promise((resolve, reject) => {
+      const extensionInterval = setInterval(() => {
+        if (!this.safariExtensionEnabled) {
+          return;
+        }
+
+        dispatchMonitorEvent()
+          .then(resolve)
+          .catch(reject);
+
+        clearInterval(extensionInterval);
+      }, 1000);
+    });
+  }
+
+  /**
+   * Builds a JSON-RPC request object with a unique identifier.
+   * @param method The method name to invoke on the extension.
+   * @param payload Optional parameters for the method.
+   * @returns The constructed JSON-RPC request object.
+   */
+  private buildRPCRequest(method: string, payload?: unknown): JSONRPCRequest {
+    return {
+      jsonrpc: '2.0',
+      method,
+      params: payload,
+      id: randomUUID()
+    };
+  }
+
+  /**
+   * Dispatches a custom event to the document to communicate with the Safari extension.
+   * @param type The type of Safari extension event to dispatch.
+   * @param request Optional JSON-RPC request payload to send with the event.
+   */
+  private dispatchEvent(type: SafariExtensionEventType, request?: JSONRPCRequest) {
+    const payload = {
+      detail: request ?? {}
+    };
+
+    document.dispatchEvent(new CustomEvent(`AsperaDesktop.${type}`, payload));
+  }
+
+  /**
+   * Dispatches a custom event to the document to communicate with the Safari extension.
+   * @param type The type of Safari extension event to dispatch.
+   * @param method The method name to invoke on the extension.
+   * @param payload Optional parameters for the method.
+   */
+  private dispatchPromiseEvent(type: SafariExtensionEventType, method: string, payload?: unknown): Promise<any> {
+    const request = this.buildRPCRequest(method, payload);
+
+    return new Promise<any>((resolve, reject) => {
+      if (this.safariExtensionEnabled) {
+        this.promiseExecutors.set(request.id, {resolve, reject});
+
+        this.dispatchEvent(type, request);
+      } else {
+        console.warn('The Safari extension is disabled or unresponsive (dispatch event)');
+        console.warn(`Failed event: ${safeJsonString(request)}`);
+
+        reject('The Safari extension is disabled or unresponsive (dispatch event)');
+      }
+    });
+  }
+
+  /**
+   * Handles incoming JSON-RPC responses from the Safari extension.
+   * Resolves or rejects promises based on the response.
+   * @param response The JSON-RPC response object received from the extension.
+   */
+  private handleResponse(response: JSONRPCResponse) {
+    const requestId = response.id;
+    const executor = this.promiseExecutors.get(requestId);
+
+    if (!executor) {
+      console.warn(`Unable to find a promise executor for ${requestId}`);
+      console.warn(`Response: ${response}`);
+      return;
+    }
+
+    this.promiseExecutors.delete(requestId);
+
+    if (response.error) {
+      executor.reject(response.error);
+      return;
+    }
+
+    executor.resolve(response.result);
+  }
+
+  /**
+   * Listens for 'AsperaDesktop.Response' events.
+   */
+  private listenResponseEvents() {
+    document.addEventListener('AsperaDesktop.Response', (event: CustomEvent<JSONRPCResponse>) => {
+      if (!event.detail) {
+        return;
+      }
+
+      this.handleResponse(event.detail);
+    });
+  }
+
+  /**
+   * Listens for 'AsperaDesktop.TransferActivity' events.
+   */
+  private listenTransferActivityEvents() {
+    document.addEventListener('AsperaDesktop.TransferActivity', (event: any) => {
+      if (!event.detail) {
+        return;
+      }
+
+      asperaSdk.activityTracking.handleTransferActivity(event.detail);
+    });
+  }
+
+  /**
+   * Listens for 'AsperaDesktop.Status' events.
+   */
+  private listenStatusEvents() {
+    document.addEventListener('AsperaDesktop.Status', (event: any) => {
+      if (!event.detail) {
+        return;
+      }
+
+      asperaSdk.activityTracking.handleWebSocketEvents(event.detail);
+    });
+  }
+
+  /**
+   * Listens for 'isAppAlive' events. This was introduced in version 1.0.9.
+   */
+  private listenClientStatusEvents() {
+    document.addEventListener('isAppAlive', (event: any) => {
+      if (!event.detail?.running) {
+        return;
+      }
+
+      asperaSdk.activityTracking.handleClientEvents(event.detail.running);
+    });
+  }
+
+  /**
+   * Listens for 'AsperaDesktop.Pong' events.
+   */
+  private listenPongEvents() {
+    document.addEventListener('AsperaDesktop.Pong', () => {
+      this.lastPong = Date.now();
+      this.safariExtensionStatusChanged(true);
+    });
+  }
+
+  /**
+   * Sends a keep alive ping according to the defined interval.
+   */
+  private keepAlive() {
+    this.lastPing = Date.now();
+    this.dispatchEvent(SafariExtensionEventType.Ping);
+
+    keepAliveTimeout = setTimeout(() => {
+      this.keepAlive();
+    }, this.keepAliveInterval);
+  }
+
+  /**
+   * Listens for Safari extension status changes.
+   * If the extension was disabled and enabled again after initializing the SDK, it
+   * will call 'monitorTransferActivity' to resume transfer activities.
+   */
+  private safariExtensionStatusChanged(isEnabled: boolean) {
+    if (isEnabled === this.safariExtensionEnabled) {
+      return;
+    }
+
+    this.safariExtensionEnabled = isEnabled;
+
+    if (isEnabled) {
+      if (this.subscribedTransferActivity) {
+        const resumeTransferActivity = () => {
+          this.monitorTransferActivity()
+            .catch(() => {
+              console.error('Failed to resume transfer activity, will try again in 1s');
+
+              setTimeout(() => {
+                resumeTransferActivity();
+              }, 1000);
+            });
+        };
+
+        resumeTransferActivity();
+      }
+    } else {
+      asperaSdk.activityTracking.handleWebSocketEvents('CLOSED');
+
+      this.promiseExecutors.forEach((promiseExecutor) => {
+        promiseExecutor.reject('The Safari extension is disabled or unresponsive (extension status)');
+      });
+
+      this.promiseExecutors.clear();
+    }
+
+    asperaSdk.activityTracking.handleSafariExtensionEvents(this.safariExtensionEnabled ? 'ENABLED' : 'DISABLED');
+  }
+
+  /**
+   * Checks if the last pong received was longer than the max interval.
+   */
+  private checkSafariExtensionStatus() {
+    const pingPongDiff = this.lastPong - this.lastPing;
+
+    if (this.lastPong == null || pingPongDiff < 0 || pingPongDiff > 500) {
+      this.safariExtensionStatusChanged(false);
+    }
+  }
+}
+
+export const safariClient = new SafariClient();
+
+export default {
+  safariClient
+};