Add scriptHostFunctions for google.script.host (#36)

Now wraps google.script.host functions

Author: enuchi

.eslintrc.json

@@ -23,7 +23,7 @@
   "rules": {
     "prettier/prettier": "error",
     "camelcase": "warn",
-    "import/prefer-default-export": "warn",
+    "import/prefer-default-export": "off",
     "import/no-extraneous-dependencies": "warn",
     "prefer-object-spread": "warn",
     "@typescript-eslint/indent": "off",

.github/workflows/publish.yml

@@ -12,7 +12,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14, 16, 18]
+        node-version: [18, 20, 22]
 
     steps:
       - uses: actions/checkout@v2
@@ -29,7 +29,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v2
         with:
-          node-version: 18
+          node-version: 22
           registry-url: https://registry.npmjs.org/
       - run: yarn
       - run: npm publish

README.md

@@ -84,13 +84,47 @@ async () => {
 
 Now we can use familiar Promises in our client-side code and have easy access to all server functions.
 
+### Using the scriptHostFunctions
+
+The `GASClient` also provides a `scriptHostFunctions` property that gives you access to Google's script host functions, which allow you to control UI elements like dialogs and sidebars:
+
+```javascript
+import { GASClient } from 'gas-client';
+const { scriptHostFunctions } = new GASClient();
+
+// Close the current dialog or sidebar
+scriptHostFunctions.close();
+
+// Set the height of the current dialog (in pixels)
+scriptHostFunctions.setHeight(500);
+
+// Set the width of the current dialog (in pixels)
+scriptHostFunctions.setWidth(400);
+
+// Switch focus from dialog/sidebar to the editor
+scriptHostFunctions.focusEditor(); // calls google.script.host.editor.focus()
+```
+
+These functions provide the same functionality as the corresponding methods in `google.script.host` but work in both production and development environments:
+
+- `close()`: Closes the current dialog or sidebar
+- `setHeight(height)`: Sets the height of the current dialog (in pixels)
+- `setWidth(width)`: Sets the width of the current dialog (in pixels)
+- `focusEditor()`: Switches browser focus from the dialog or sidebar to the Google Docs, Sheets, or Forms editor
+
+See reference here: https://developers.google.com/apps-script/guides/html/reference/host
+
+In production, these functions call the native Google Apps Script host methods directly. In development mode, they dispatch appropriate messages to the parent iframe. See section below on how to set up the parent iframe.
+
+## Setting up the dev server wrapper
+
+Use the [React-Google-Apps-Script](https://github.com/enuchi/React-Google-Apps-Script/) project to get started. Or reference the [dev server wrapper](https://github.com/enuchi/React-Google-Apps-Script/blob/main/dev/dev-server-wrapper.html#L40-L41) on how to set up the parent wrapper to work with `gas-client`.
+
 ---
 
 ## Typescript
 
-This project now supports typescript!
-
-To use it, simply import your server functions and pass them as a type parameter when creating your server.
+This project supports typescript. To use it, simply import your server functions and pass them as a type parameter when creating your server.
 
 ### On your server-side code
 
@@ -152,19 +186,25 @@ The config object takes:
 
 ### Production mode
 
-In the normal Google Apps Script production environment, a `new GASClient()` instance will have one available method:
+In the normal Google Apps Script production environment, a `new GASClient()` instance will have the following available methods:
 
 - `serverFunctions`: an object containing all publicly exposed server functions (see example above).
+- `scriptHostFunctions`: an object containing methods to interact with the script host UI, including:
+  - `close()`: Close the current dialog or sidebar
+  - `setHeight(height)`: Set the dialog height in pixels
+  - `setWidth(width)`: Set the dialog width in pixels
+  - `focusEditor()`: Switch focus from dialog/sidebar to the editor
 
 Note that `allowedDevelopmentDomains` and `parentTargetOrigin` configurations will be ignored in production, so the same code can and should be used for development and production.
 
 ### Development mode
 
 Development mode for the `gas-client` helper class will be run when the `google` client API cannot be loaded.
 
-Calling `new GASClient({ allowedDevelopmentDomains })` will create an instance with the following method in development mode:
+Calling `new GASClient({ allowedDevelopmentDomains })` will create an instance with the following methods in development mode:
 
 - `serverFunctions`: a proxy object, used for development purposes, that mimics calling `google.script.run`. It will dispatch a message to the parent iframe (our custom Dev Server), which will call an app that actually interacts with the `google.script.run` API. Development mode will also handle the response and resolve or reject based on the response type. See the implementation for details on the event signature.
+- `scriptHostFunctions`: a proxy object that simulates the behavior of `google.script.host` methods in development mode by sending appropriate messages to the parent iframe.
 
 ## Contributors
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gas-client",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "A client-side utility class that can call server-side Google Apps Script functions",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",

src/classes/function-host.ts src/classes/function-provider.tssrc/classes/function-host.ts renamed to src/classes/function-provider.ts

@@ -1,11 +1,11 @@
 import { FunctionMap, ServerFunctions } from '../types/functions';
 
-abstract class FunctionHost<FM extends FunctionMap> {
+abstract class FunctionProvider<FM extends FunctionMap> {
   protected _serverFunctions: ServerFunctions<FM> = {} as ServerFunctions<FM>;
 
   get serverFunctions(): ServerFunctions<FM> {
     return this._serverFunctions;
   }
 }
 
-export { FunctionHost };
+export { FunctionProvider };

src/classes/gas-promises.ts

@@ -1,9 +1,9 @@
 import { ignoredFunctionNames } from '../utils/ignored-function-names';
 import { promisify } from '../utils/promisify';
-import { FunctionHost } from './function-host';
+import { FunctionProvider } from './function-provider';
 import { FunctionMap, ServerFunctions } from '../types/functions';
 
-class GASPromises<FM extends FunctionMap> extends FunctionHost<FM> {
+class GASPromises<FM extends FunctionMap> extends FunctionProvider<FM> {
   constructor() {
     super();
     this.promisifyGASFunctions();

src/classes/host-functions.ts

@@ -0,0 +1,19 @@
+import { ScriptHostProvider } from './script-host-provider';
+
+class ScriptHostFunctions extends ScriptHostProvider {
+  constructor() {
+    super();
+    this.initializeScriptHostFunctions();
+  }
+
+  private initializeScriptHostFunctions(): void {
+    this._hostFunctions = {
+      close: google.script.host.close,
+      setHeight: google.script.host.setHeight,
+      setWidth: google.script.host.setWidth,
+      focusEditor: google.script.host.editor.focus,
+    };
+  }
+}
+
+export { ScriptHostFunctions };

src/classes/script-host-provider.ts

@@ -0,0 +1,11 @@
+import { HostFunctions } from '../types/functions';
+
+abstract class ScriptHostProvider {
+  protected _hostFunctions = {} as HostFunctions;
+
+  get hostFunctions(): HostFunctions {
+    return this._hostFunctions;
+  }
+}
+
+export { ScriptHostProvider };

src/classes/script-host-proxy.ts

@@ -0,0 +1,12 @@
+import { proxyHandlerScriptHostFunction } from '../utils/proxy-handler';
+import { HostFunctions } from '../types/functions';
+import { ScriptHostProvider } from './script-host-provider';
+
+class ScriptHostProxy extends ScriptHostProvider {
+  constructor() {
+    super();
+    this._hostFunctions = new Proxy({}, { get: proxyHandlerScriptHostFunction }) as HostFunctions;
+  }
+}
+
+export { ScriptHostProxy };

src/classes/server-proxy.ts

@@ -1,29 +1,29 @@
 import { checkAllowList } from '../utils/check-allow-list';
-import { proxyHandler } from '../utils/proxy-handler';
-import { FunctionHost } from './function-host';
-import { AppWindow } from '../types/dev-server';
+import { proxyHandlerServerFunction } from '../utils/proxy-handler';
+import { FunctionProvider } from './function-provider';
+import { AppWindow, MessageType, ResponseStatus } from '../types/dev-server';
 import { FunctionMap, ServerFunctions } from '../types/functions';
 import { ServerConfig } from '../types/config';
 
 declare const window: AppWindow;
 
-class ServerProxy<FM extends FunctionMap> extends FunctionHost<FM> {
+class ServerProxy<FM extends FunctionMap> extends FunctionProvider<FM> {
   constructor(private _config?: ServerConfig) {
     super();
     window.gasStore = {};
     window.addEventListener('message', this.buildMessageListener(), false);
-    this._serverFunctions = new Proxy({}, { get: proxyHandler }) as ServerFunctions<FM>;
+    this._serverFunctions = new Proxy({}, { get: proxyHandlerServerFunction }) as ServerFunctions<FM>;
   }
 
   private buildMessageListener(): (event: MessageEvent) => void {
     return (event: MessageEvent) => {
       const allowOrigin = checkAllowList(event.origin, this._config?.allowedDevelopmentDomains);
-      if (!allowOrigin || event.data.type !== 'RESPONSE') return;
+      if (!allowOrigin || event.data.type !== MessageType.RESPONSE) return;
 
       const { response, status, id } = event.data;
       const { resolve, reject } = window.gasStore[id];
 
-      if (status === 'ERROR') {
+      if (status === ResponseStatus.ERROR) {
         reject(response);
       }
       resolve(response);