feat: showSaveFileDialog() (#228)

Author: dwosk

examples/index.ts

@@ -7,7 +7,7 @@
 // Import all example functions
 import { initializeAspera } from './initialize';
 import { testAspera } from './test-connection';
-import { selectItemsAspera } from './select-items';
+import { selectItemsAspera, showSaveFileDialogAspera } from './select-items';
 import { selectAndPreviewImageAspera } from './image-preview';
 import { selectAndCalculateChecksumAspera } from './file-checksum';
 import { startTransferAspera, authenticateAspera, testSshPortsAspera } from './start-transfer';
@@ -34,6 +34,7 @@ declare global {
     initializeAspera: typeof initializeAspera;
     testAspera: typeof testAspera;
     selectItemsAspera: typeof selectItemsAspera;
+    showSaveFileDialogAspera: typeof showSaveFileDialogAspera;
     selectAndPreviewImageAspera: typeof selectAndPreviewImageAspera;
     selectAndCalculateChecksumAspera: typeof selectAndCalculateChecksumAspera;
     startTransferAspera: typeof startTransferAspera;
@@ -62,6 +63,7 @@ declare global {
 window.initializeAspera = initializeAspera;
 window.testAspera = testAspera;
 window.selectItemsAspera = selectItemsAspera;
+window.showSaveFileDialogAspera = showSaveFileDialogAspera;
 window.selectAndPreviewImageAspera = selectAndPreviewImageAspera;
 window.selectAndCalculateChecksumAspera = selectAndCalculateChecksumAspera;
 window.startTransferAspera = startTransferAspera;
@@ -89,6 +91,7 @@ export {
   initializeAspera,
   testAspera,
   selectItemsAspera,
+  showSaveFileDialogAspera,
   selectAndPreviewImageAspera,
   selectAndCalculateChecksumAspera,
   startTransferAspera,

examples/select-items.ts

@@ -3,7 +3,7 @@
  * This example demonstrates how to let users select items from their local filesystem.
  */
 
-import { showSelectFileDialog, showSelectFolderDialog } from '@ibm-aspera/sdk';
+import { showSelectFileDialog, showSelectFolderDialog, showSaveFileDialog } from '@ibm-aspera/sdk';
 
 // Global state for selected files (used by the example app)
 declare global {
@@ -38,3 +38,18 @@ export function selectItemsAspera(selectFolders: boolean) {
     }
   });
 }
+
+export function showSaveFileDialogAspera() {
+  /** Open a save file dialog for the user to choose a save location. */
+  showSaveFileDialog({title: 'Save file'}).then(response => {
+    console.info('Save file dialog response', response);
+    alert(`Save file dialog response:\n\n${JSON.stringify(response, undefined, 2)}`);
+  }).catch(error => {
+    if (error.debugData?.code === -32002) {
+      alert('User canceled save file dialog');
+    } else {
+      console.error('Save file dialog failed', error);
+      alert(`Save file dialog failed\n\n${JSON.stringify(error, undefined, 2)}`);
+    }
+  });
+}

examples/src/Views/SelectItems.tsx

@@ -88,7 +88,7 @@ export default function SelectItems() {
     window.readDirectoryAspera(options);
   };
 
-  const codeSnippet = [window.selectItemsAspera.toString(), window.readDirectoryAspera.toString()].join('\n\n');
+  const codeSnippet = [window.selectItemsAspera.toString(), window.showSaveFileDialogAspera.toString(), window.readDirectoryAspera.toString()].join('\n\n');
 
   const visibleEntries = directoryData?.entries.slice(0, MAX_VISIBLE_ENTRIES) ?? [];
   const totalEntries = directoryData?.totalCount ?? 0;
@@ -101,6 +101,7 @@ export default function SelectItems() {
       <h2>Try it out</h2>
       <Button onClick={() => window.selectItemsAspera(false)}>Select files</Button>
       <Button onClick={() => window.selectItemsAspera(true)}>Select folder</Button>
+      <Button onClick={() => window.showSaveFileDialogAspera()}>Save file dialog</Button>
       <div className="ending-content">
         {window.selectedFiles.length ? (
           <UnorderedList>

src/app/core.ts

@@ -5,7 +5,7 @@ import {httpDownload, httpUpload, initHttpGateway} from '../http-gateway';
 import {handleHttpGatewayDrop, httpGatewayReadAsArrayBuffer, httpGatewayReadChunkAsArrayBuffer, httpGatewaySelectFileFolderDialog, httpGetAllTransfers, httpGetTransfer, httpRemoveTransfer, httpStopTransfer, sendTransferUpdate} from '../http-gateway/core';
 import {asperaSdk} from '../index';
 import {AsperaSdkInfo, AsperaSdkClientInfo, TransferResponse} from '../models/aspera-sdk.model';
-import {CustomBrandingOptions, DataTransferResponse, DropzoneEventData, DropzoneEventType, DropzoneOptions, AsperaSdkSpec, BrowserStyleFile, AsperaSdkTransfer, FileDialogOptions, FolderDialogOptions, InitOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, TransferSpec, WebsocketEvent, ReadChunkAsArrayBufferResponse, ReadAsArrayBufferResponse, OpenRpcSpec, SdkCapabilities, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse, ShowPreferencesPageOptions, PreferencesPage, TestSshPortsOptions} from '../models/models';
+import {CustomBrandingOptions, DataTransferResponse, DropzoneEventData, DropzoneEventType, DropzoneOptions, AsperaSdkSpec, BrowserStyleFile, AsperaSdkTransfer, FileDialogOptions, FolderDialogOptions, SaveFileDialogOptions, InitOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, TransferSpec, WebsocketEvent, ReadChunkAsArrayBufferResponse, ReadAsArrayBufferResponse, OpenRpcSpec, SdkCapabilities, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse, ShowPreferencesPageOptions, PreferencesPage, TestSshPortsOptions} from '../models/models';
 import {Connect, ConnectInstaller} from '@ibm-aspera/connect-sdk-js';
 import {initConnect} from '../connect/core';
 import * as ConnectTypes from '@ibm-aspera/connect-sdk-js/dist/esm/core/types';
@@ -544,6 +544,50 @@ export const showSelectFolderDialog = (options?: FolderDialogOptions): Promise<D
   return promiseInfo.promise;
 };
 
+/**
+ * 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 const showSaveFileDialog = (options?: SaveFileDialogOptions): Promise<DataTransferResponse> => {
+  if (asperaSdk.useHttpGateway) {
+    return throwError(messages.showSaveFileDialogNotSupported);
+  }
+
+  if (asperaSdk.useConnect) {
+    const connectPromiseInfo = generatePromiseObjects();
+    asperaSdk.globals.connect.showSaveFileDialog({
+      success: (data: any) => connectPromiseInfo.resolver(data as unknown as DataTransferResponse),
+      error: (error: any) => connectPromiseInfo.rejecter(error),
+    }, options);
+    return connectPromiseInfo.promise;
+  }
+
+  if (!asperaSdk.isReady) {
+    return throwError(messages.serverNotVerified);
+  }
+
+  const promiseInfo = generatePromiseObjects();
+
+  const payload = {
+    options: options || {},
+    app_id: asperaSdk.globals.appId,
+  };
+
+  client.request('show_save_file_dialog', payload)
+    .then((data: any) => promiseInfo.resolver(data))
+    .catch(error => {
+      errorLog(messages.showSaveFileDialogFailed, error);
+      promiseInfo.rejecter(generateErrorBody(messages.showSaveFileDialogFailed, error));
+    });
+
+  return promiseInfo.promise;
+};
+
 /**
  * Shows the about page of the transfer client.
  *
@@ -1295,7 +1339,7 @@ const supportsMethod = (method: string): boolean => {
   // We currently do not support calculating file checksums when using HTTP Gateway. In theory it should be possible
   // to calculate this directly in the browser similar to how `readAsArrayBuffer()` is implemented.
   // HTTP Gateway also does not support showing native transfer client UI (about, preferences, etc.).
-  if (asperaSdk.useHttpGateway && (method === 'get_checksum' || method === 'show_about' || method === 'open_preferences' || method === 'show_transfer_manager' || method === 'show_transfer_monitor' || method === 'authenticate' || method === 'test_ssh_ports' || method === 'read_directory')) {
+  if (asperaSdk.useHttpGateway && (method === 'get_checksum' || method === 'show_about' || method === 'open_preferences' || method === 'show_transfer_manager' || method === 'show_transfer_monitor' || method === 'authenticate' || method === 'test_ssh_ports' || method === 'show_save_file_dialog' || method === 'read_directory')) {
     return false;
   }
 
@@ -1342,6 +1386,7 @@ export const getCapabilities = (): SdkCapabilities => {
     showTransferMonitor: supportsMethod('show_transfer_monitor'),
     authenticate: supportsMethod('authenticate'),
     testSshPorts: supportsMethod('test_ssh_ports'),
+    showSaveFileDialog: supportsMethod('show_save_file_dialog'),
     readDirectory: supportsMethod('read_directory'),
   };
 };

src/constants/messages.ts

@@ -53,4 +53,6 @@ export const messages = {
   authenticateNotSupported: 'Authenticate is not supported for current transfer client',
   testSshPortsFailed: 'Unable to test SSH ports',
   testSshPortsNotSupported: 'Test SSH ports is not supported for current transfer client',
+  showSaveFileDialogFailed: 'Unable to show save file dialog',
+  showSaveFileDialogNotSupported: 'Show save file dialog is not supported for current transfer client',
 };

src/index.ts

@@ -1,5 +1,5 @@
 import {AsperaSdk} from './models/aspera-sdk.model';
-import {authenticate, createDropzone, deregisterActivityCallback, deregisterStatusCallback, getAllTransfers, getCapabilities, getChecksum, getFilesList, getInfo, getTransfer, hasCapability, init, initDragDrop, modifyTransfer, showPreferencesPage, readAsArrayBuffer, readChunkAsArrayBuffer, readDirectory, registerActivityCallback, registerStatusCallback, removeDropzone, removeTransfer, resumeTransfer, setBranding, showAbout, showDirectory, showPreferences, showSelectFileDialog, showSelectFolderDialog, showTransferManager, showTransferMonitor, startTransfer, stopTransfer, testConnection, testSshPorts,} from './app/core';
+import {authenticate, createDropzone, deregisterActivityCallback, deregisterStatusCallback, getAllTransfers, getCapabilities, getChecksum, getFilesList, getInfo, getTransfer, hasCapability, init, initDragDrop, modifyTransfer, showPreferencesPage, readAsArrayBuffer, readChunkAsArrayBuffer, readDirectory, registerActivityCallback, registerStatusCallback, removeDropzone, removeTransfer, resumeTransfer, setBranding, showAbout, showDirectory, showPreferences, showSaveFileDialog, showSelectFileDialog, showSelectFolderDialog, showTransferManager, showTransferMonitor, startTransfer, stopTransfer, testConnection, testSshPorts,} from './app/core';
 import {getInstallerInfo} from './app/installer';
 import {getInstallerUrls, isSafari} from './helpers/helpers';
 import * as httpGatewayCalls from './http-gateway';
@@ -23,6 +23,7 @@ asperaSdk.getTransfer = getTransfer;
 asperaSdk.getFilesList = getFilesList;
 asperaSdk.showSelectFileDialog = showSelectFileDialog;
 asperaSdk.showSelectFolderDialog = showSelectFolderDialog;
+asperaSdk.showSaveFileDialog = showSaveFileDialog;
 asperaSdk.showPreferences = showPreferences;
 asperaSdk.showTransferManager = showTransferManager;
 asperaSdk.showTransferMonitor = showTransferMonitor;
@@ -73,6 +74,7 @@ export {
   getFilesList,
   showSelectFileDialog,
   showSelectFolderDialog,
+  showSaveFileDialog,
   showPreferences,
   showTransferManager,
   showTransferMonitor,
@@ -116,6 +118,7 @@ export type {
   FileStat,
   FileStatus,
   FolderDialogOptions,
+  SaveFileDialogOptions,
   GetChecksumOptions,
   InitOptions,
   InstallerInfo,

src/models/aspera-sdk.model.ts

@@ -1,4 +1,4 @@
-import {CustomBrandingOptions, DataTransferResponse, DropzoneEventData, DropzoneEventType, DropzoneOptions, AsperaSdkSpec, AsperaSdkTransfer, FileDialogOptions, FolderDialogOptions, InitOptions, InstallerInfoResponse, InstallerOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, SafariExtensionEvent, TransferSpec, WebsocketEvent, InstallerUrlInfo, RpcMethod, SdkCapabilities, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse, ShowPreferencesPageOptions, TestSshPortsOptions} from './models';
+import {CustomBrandingOptions, DataTransferResponse, DropzoneEventData, DropzoneEventType, DropzoneOptions, AsperaSdkSpec, AsperaSdkTransfer, FileDialogOptions, FolderDialogOptions, SaveFileDialogOptions, InitOptions, InstallerInfoResponse, InstallerOptions, ModifyTransferOptions, Pagination, PaginatedFilesResponse, ResumeTransferOptions, SafariExtensionEvent, TransferSpec, WebsocketEvent, InstallerUrlInfo, RpcMethod, SdkCapabilities, GetChecksumOptions, ChecksumFileResponse, ReadDirectoryOptions, ReadDirectoryResponse, ShowPreferencesPageOptions, TestSshPortsOptions} from './models';
 import {hiddenStyleList, installerUrl, protocol} from '../constants/constants';
 import {messages} from '../constants/messages';
 import {safariClient} from '../helpers/client/safari-client';
@@ -391,6 +391,8 @@ export class AsperaSdk {
   showSelectFileDialog: (options?: FileDialogOptions) => Promise<DataTransferResponse>;
   /** Function to display a folder dialog for the user to select folders. */
   showSelectFolderDialog: (options?: FolderDialogOptions) => Promise<DataTransferResponse>;
+  /** Function to display a save file dialog for the user to choose a save location */
+  showSaveFileDialog: (options?: SaveFileDialogOptions) => Promise<DataTransferResponse>;
   /** Function to show the about page of the transfer client */
   showAbout: () => Promise<any>;
   /** Function to display the IBM Aspera preferences page */

src/models/models.ts

@@ -33,6 +33,15 @@ export interface FolderDialogOptions {
   multiple?: boolean;
 }
 
+export interface SaveFileDialogOptions {
+  /** Filter the files displayed by file extension. */
+  allowedFileTypes?: any;
+  /** The filename to pre-fill the dialog with. */
+  suggestedName?: string;
+  /** The name of the dialog window. */
+  title?: string;
+}
+
 /**
  * Options related to fetching the latest Aspera installer information.
  *
@@ -1029,6 +1038,13 @@ export interface SdkCapabilities {
    * but not HTTP Gateway.
    */
   testSshPorts: boolean,
+  /**
+   * Whether the transfer client supports showing the save file dialog.
+   *
+   * This is supported when using Connect or IBM Aspera for desktop with the required RPC methods,
+   * but not HTTP Gateway.
+   */
+  showSaveFileDialog: boolean,
   /**
    * Whether the SDK can read directory contents.
    *

tests/integration/connect.spec.ts

@@ -5,6 +5,7 @@ import {
   resumeTransfer,
   showSelectFileDialog,
   showSelectFolderDialog,
+  showSaveFileDialog,
   showAbout,
   showPreferences,
   getAllTransfers,
@@ -102,6 +103,18 @@ describe('Connect SDK', () => {
     });
   });
 
+  describe('showSaveFileDialog', () => {
+    it('should call showSaveFileDialog on Connect SDK with callbacks and options', async () => {
+      await showSaveFileDialog({title: 'Save file', suggestedName: 'report.pdf'});
+
+      const mock = getConnectMock();
+      expect(mock.showSaveFileDialog).toHaveBeenCalledWith(
+        expect.objectContaining({success: expect.any(Function), error: expect.any(Function)}),
+        {title: 'Save file', suggestedName: 'report.pdf'},
+      );
+    });
+  });
+
   describe('showAbout', () => {
     it('should call showAbout on Connect SDK', async () => {
       await showAbout();
@@ -313,6 +326,7 @@ describe('Connect SDK', () => {
       expect(hasCapability('showTransferMonitor')).toBe(true);
       expect(hasCapability('authenticate')).toBe(true);
       expect(hasCapability('testSshPorts')).toBe(true);
+      expect(hasCapability('showSaveFileDialog')).toBe(true);
       expect(hasCapability('imagePreview')).toBe(true);
       expect(hasCapability('fileChecksum')).toBe(true);
     });

tests/integration/desktop-app.spec.ts

@@ -5,6 +5,7 @@ import {
   resumeTransfer,
   showSelectFileDialog,
   showSelectFolderDialog,
+  showSaveFileDialog,
   showAbout,
   showPreferences,
   getAllTransfers,
@@ -118,6 +119,19 @@ describe('Desktop App', () => {
     });
   });
 
+  describe('showSaveFileDialog', () => {
+    it('should call show_save_file_dialog RPC', async () => {
+      await showSaveFileDialog({title: 'Save file', suggestedName: 'report.pdf'});
+
+      const call = lastFetchCall();
+      expect(call.body.method).toBe('show_save_file_dialog');
+      expect(call.body.params).toEqual({
+        options: {title: 'Save file', suggestedName: 'report.pdf'},
+        app_id: APP_ID,
+      });
+    });
+  });
+
   describe('showAbout', () => {
     it('should call show_about RPC', async () => {
       await showAbout();
@@ -386,14 +400,15 @@ describe('Desktop App', () => {
 
   describe('hasCapability', () => {
     it('should return true for capabilities whose RPC methods are discovered', () => {
-      asperaSdk.globals.rpcMethods = ['show_about', 'open_preferences', 'show_transfer_manager', 'show_transfer_monitor', 'authenticate', 'test_ssh_ports', 'read_as_array_buffer', 'read_chunk_as_array_buffer', 'get_checksum', 'read_directory'];
+      asperaSdk.globals.rpcMethods = ['show_about', 'open_preferences', 'show_transfer_manager', 'show_transfer_monitor', 'authenticate', 'test_ssh_ports', 'show_save_file_dialog', 'read_as_array_buffer', 'read_chunk_as_array_buffer', 'get_checksum', 'read_directory'];
 
       expect(hasCapability('showAbout')).toBe(true);
       expect(hasCapability('showPreferences')).toBe(true);
       expect(hasCapability('showTransferManager')).toBe(true);
       expect(hasCapability('showTransferMonitor')).toBe(true);
       expect(hasCapability('authenticate')).toBe(true);
       expect(hasCapability('testSshPorts')).toBe(true);
+      expect(hasCapability('showSaveFileDialog')).toBe(true);
       expect(hasCapability('imagePreview')).toBe(true);
       expect(hasCapability('fileChecksum')).toBe(true);
       expect(hasCapability('readDirectory')).toBe(true);
@@ -408,6 +423,7 @@ describe('Desktop App', () => {
       expect(hasCapability('showTransferMonitor')).toBe(false);
       expect(hasCapability('authenticate')).toBe(false);
       expect(hasCapability('testSshPorts')).toBe(false);
+      expect(hasCapability('showSaveFileDialog')).toBe(false);
       expect(hasCapability('imagePreview')).toBe(false);
       expect(hasCapability('fileChecksum')).toBe(false);
       expect(hasCapability('readDirectory')).toBe(false);