@ibm-aspera/sdk 0.2.2

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} 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: JSON.stringify(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,318 @@
+import Client from './client';
+import {randomUUID} 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 statusInterval = 100;
+  private keepAliveInterval = 1000;
+  private promiseExecutors: Map<string, PromiseExecutor>;
+
+  private isFirstPing = true;
+  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.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: ${JSON.stringify(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>) => {
+      this.handleResponse(event.detail);
+    });
+  }
+
+  /**
+   * Listens for 'AsperaDesktop.TransferActivity' events.
+   */
+  private listenTransferActivityEvents() {
+    document.addEventListener('AsperaDesktop.TransferActivity', (event: any) => {
+      asperaSdk.activityTracking.handleTransferActivity(event.detail);
+    });
+  }
+
+  /**
+   * Listens for 'AsperaDesktop.Status' events.
+   */
+  private listenStatusEvents() {
+    document.addEventListener('AsperaDesktop.Status', (event: any) => {
+      asperaSdk.activityTracking.handleWebSocketEvents(event.detail);
+    });
+  }
+
+  /**
+   * 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);
+
+    if (this.isFirstPing) {
+      this.isFirstPing = false;
+    } else {
+      setTimeout(() => {
+        this.checkSafariExtensionStatus();
+      }, this.statusInterval);
+    }
+
+    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
+};

package/src/helpers/helpers.ts

@@ -0,0 +1,200 @@
+import {ErrorResponse, PromiseObject, TransferSpec} from '../models/models';
+
+/**
+ * Generates promise object that can be resolved or rejected via functions
+ *
+ * @returns an object containing the promise, the resolver and rejecter
+ */
+export const generatePromiseObjects = (): PromiseObject => {
+  let resolver: (response: any) => void;
+  let rejecter: (response: any) => void;
+  const promise = new Promise((resolve, reject) => {
+    resolver = resolve;
+    rejecter = reject;
+  });
+  return {
+    promise,
+    resolver,
+    rejecter
+  };
+};
+
+/**
+ * Log errors from Aspera SDK
+ *
+ * @param message the message indicating the error encountered
+ * @param debugData the data with useful debugging information
+ */
+export const errorLog = (message: string, debugData?: any): void => {
+  if (debugData && debugData.code && debugData.message) {
+    debugData = {
+      code: debugData.code,
+      message: debugData.message,
+      data: debugData.data
+    };
+  }
+
+  if (typeof (<any>window) === 'object') {
+    if (!Array.isArray((<any>window).asperaSdkLogs)) {
+      (<any>window).asperaSdkLogs = [];
+    }
+    (<any>window).asperaSdkLogs.push({message, debugData});
+  }
+
+  console.warn(`Aspera SDK: ${message}`, debugData);
+};
+
+/**
+ * Generate error object for rejecter responses
+ *
+ * @param message the message indicating the error encountered
+ * @param debugData the data with useful debugging information
+ *
+ * @returns object containing standardized error response
+ */
+export const generateErrorBody = (message: string, debugData?: any): ErrorResponse => {
+  const errorResponse: ErrorResponse = {
+    error: true,
+    message
+  };
+
+  if (debugData && debugData.code && debugData.message) {
+    errorResponse.debugData = {
+      code: debugData.code,
+      message: debugData.message,
+      data: debugData.data
+    };
+  }
+
+  return errorResponse;
+};
+
+/**
+ * Validate if transferSpec is valid for server communication
+ *
+ * @param transferSpec the transferSpec to test
+ *
+ * @returns boolean indicating whether supplied transferSpec is valid
+ */
+export const isValidTransferSpec = (transferSpec: TransferSpec): boolean => {
+  if (
+    transferSpec &&
+    typeof transferSpec === 'object' &&
+    typeof transferSpec.direction === 'string' &&
+    typeof transferSpec.remote_host === 'string' &&
+    Array.isArray(transferSpec.paths)
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+/**
+ * Returns a string indicating the websocket URL to use for talking to the server
+ *
+ * @returns a string of the full Websocket URL
+ */
+export const getWebsocketUrl = (serverUrl: string): string => {
+  let wsProtocol;
+  if (serverUrl.indexOf('http:') === 0) {
+    wsProtocol = 'ws';
+  } else if (serverUrl.indexOf('https:') === 0) {
+    wsProtocol = 'wss';
+  }
+  const url = serverUrl.replace('http://', '//').replace('https://', '//');
+
+  return `${wsProtocol}:${url}`;
+};
+
+/**
+ * Simple function to get the current platform.
+ *
+ * @returns a string indicating the current platform
+ */
+export const getCurrentPlatform = (): 'macos'|'windows'|'linux'|'unknown' => {
+  const ua = navigator.userAgent;
+
+  if (/Mac/.test(ua)) {
+    return 'macos';
+  } else if (/Win/.test(ua)) {
+    return 'windows';
+  } else if (/Linux/.test(ua)) {
+    return 'linux';
+  } else {
+    return 'unknown';
+  }
+};
+
+/**
+ * Function used to create a random UUID
+ *
+ * @returns string
+ */
+export const randomUUID = (): string => {
+  const fallback = (): string => {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function (c) {
+      let r = Number(((new Date().getTime() + 16) * Math.random()).toFixed()) % 16;
+      if (c !== 'x') {
+        // eslint-disable-next-line no-bitwise
+        r = r & 0x3 | 0x8;
+      }
+      return r.toString(16);
+    });
+  };
+
+  return window.crypto?.randomUUID ? window.crypto.randomUUID() : fallback();
+};
+
+/**
+ * Return a rejected promise
+ *
+ * @param message the message indicating the error encountered
+ * @param debugData the data with useful debugging information
+ *
+ * @returns a rejected promise
+ */
+export const throwError = (message: string, debugData?: any): Promise<any> => {
+  errorLog(message, debugData);
+  return new Promise((resolve, reject) => {
+    reject(generateErrorBody(message, debugData));
+  });
+};
+
+/**
+ * Check if the given string is a valid URL
+ *
+ * @param url string to check if valid URL
+ *
+ * @returns boolean
+ */
+export const isValidURL = (url: string): boolean => {
+  try {
+    new URL(url);
+    return true;
+  } catch(error) {
+    return false;
+  }
+};
+
+/**
+ * Checks if the current browser is Safari.
+ * @returns {boolean} Whether the browser is Safari.
+ */
+export const isSafari = (): boolean => {
+  // eslint-disable-next-line
+  return /^((?!chrome|android).)*safari/i.test(navigator.userAgent) && !(window as any).MSStream;
+};
+
+export default {
+  errorLog,
+  generateErrorBody,
+  generatePromiseObjects,
+  getCurrentPlatform,
+  getWebsocketUrl,
+  isSafari,
+  isValidURL,
+  isValidTransferSpec,
+  randomUUID,
+  throwError,
+};

package/src/helpers/http.ts

@@ -0,0 +1,39 @@
+import {generatePromiseObjects} from './helpers';
+
+/**
+ * Check HTTP promise response for server error response (non 2XX status) and reject promise is error
+ *
+ * @param promise the HTTP promise to check for HTTP status code of 2XX for success
+ *
+ * @returns promise for the HTTP connection with catch supporting error
+ */
+export const handlePromiseErrors = (promise: Promise<any>): Promise<any> => {
+  const promiseInfo = generatePromiseObjects();
+  promise.then(response => {
+    if (response.ok) {
+      promiseInfo.resolver(response);
+    } else {
+      promiseInfo.rejecter(response);
+    }
+    return response;
+  }).catch(error => {
+    promiseInfo.rejecter(error);
+  });
+  return promiseInfo.promise;
+};
+
+
+/**
+ * Make a GET for retrieving data from a server
+ *
+ * @param url the url string of the resource on the server
+ *
+ * @returns a promise that will resolve with the response from the server or reject if network/server error
+ */
+export const apiGet = (url: string): Promise<any> => {
+  return handlePromiseErrors(fetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  }));
+};