Google Apps Script Client

Common errors

• TypeError: Cannot read properties of undefined (reading 'someServerFunction')

  cause Attempting to call a server function directly on the `GASClient` instance or without correctly destructuring `serverFunctions`.
  fix Ensure `serverFunctions` is properly destructured from a `new GASClient()` instance: `const { serverFunctions } = new GASClient(config); serverFunctions.someServerFunction();`

• Refused to connect to 'https://localhost:3000/' because it violates the following Content Security Policy directive...

  cause The `allowedDevelopmentDomains` configuration is either missing, incorrect, or doesn't match the actual URL of your local development server, preventing communication between the client and the mock server.
  fix Set `allowedDevelopmentDomains` in your `GASClient` constructor options to the exact `https://localhost:PORT` URL of your running development server (e.g., `{ allowedDevelopmentDomains: 'https://localhost:3000' }`).

• Unhandled promise rejection

  cause Server functions called via `serverFunctions` return Promises, and if an error occurs on the server-side Apps Script or during the call, the Promise will reject without being caught.
  fix Always attach a `.catch()` handler to your promise chain (e.g., `serverFunctions.myFunc().then(...).catch(err => console.error(err))`) or wrap `await` calls in `try...catch` blocks (`try { await serverFunctions.myFunc(); } catch (err) { console.error(err); }`) to handle potential errors.

Warnings

• breaking The `v1.0.0` release introduced full TypeScript support and significant internal improvements, moving from a `v0.x` pre-release status to a stable major version. While specific breaking changes are not detailed, upgrading from `0.x` to `1.0.0` or higher may require code adjustments, particularly around type definitions and module resolution if you were using custom workarounds for types.
  Fix: Review your codebase for compatibility, especially if you had custom type declarations or relied on previous internal structures. Update client-side code to leverage the officially supported TypeScript types and new API patterns introduced in `v1.0.0`.
• gotcha When developing locally, the `allowedDevelopmentDomains` configuration option is crucial. If omitted or incorrectly specified, client-side communication with your local development server (e.g., via `Google Apps Script Webpack Dev Server`) will fail, preventing server function calls.
  Fix: Ensure that the `allowedDevelopmentDomains` property in your `GASClient` configuration exactly matches the full `https://localhost:PORT` URL of your local development server. This config is ignored in production.
• gotcha Prior to `v1.2.1`, attempts to use `scriptHostFunctions.focusEditor()` within a Google Apps Script web app (as opposed to dialogs or sidebars) could potentially lead to errors if `google.script.host.editor` was not fully available in that context, causing `gas-client` to fail loading.
  Fix: Upgrade to `gas-client@1.2.1` or newer. This version includes optional chaining (`?.`) when accessing `google.script.host.editor`, mitigating the error in web app contexts.
• gotcha `gas-client` wraps the native `google.script.run` with Promises. Developers accustomed to `google.script.run.withSuccessHandler().withFailureHandler()` must transition to standard Promise handling (`.then().catch()`) or `async/await` (`try...catch`) for all server function calls made via `serverFunctions`.
  Fix: Always use `.then((response) => {...}).catch((error) => {...})` or `try { const response = await serverFunctions.myFunction(); } catch (error) {...}` to ensure proper error handling and response processing.

Install

• npm install gas-client npm
• yarn add gas-client yarn
• pnpm add gas-client pnpm

Imports

• GASClient
  wrong:

  const GASClient = require('gas-client');

  correct:

  import { GASClient } from 'gas-client';

  The `GASClient` class is a named export. While the package publishes as UMD, it is primarily designed for ESM consumption. Using `require()` may require specific bundler configurations or lead to unexpected behavior.
• serverFunctions
  wrong:

  import { serverFunctions } from 'gas-client';

  correct:

  const { serverFunctions } = new GASClient();

  `serverFunctions` is an instance property obtained by destructuring a `GASClient` instance, not a direct module export. It provides promise-based wrappers for your server-side Apps Script functions.
• scriptHostFunctions
  wrong:

  import { scriptHostFunctions } from 'gas-client';

  correct:

  const { scriptHostFunctions } = new GASClient();

  `scriptHostFunctions` is also an instance property, similar to `serverFunctions`. It offers a consistent interface for `google.script.host` methods, functioning identically in both development and production environments.

Quickstart

Demonstrates how to initialize `GASClient`, call a server-side Apps Script function using promises or async/await, optionally configure it for local development, and utilize `scriptHostFunctions`.

import { GASClient } from 'gas-client';

// Initialize GASClient, optionally for local development
const clientConfig = {
  // In development mode, replace 3000 with your local dev server port
  // This setting is ignored in production Apps Script environments.
  allowedDevelopmentDomains: process.env.NODE_ENV === 'development' ? 'https://localhost:3000' : undefined,
};
const { serverFunctions, scriptHostFunctions } = new GASClient(clientConfig);

// Example 1: Calling a server function with Promises
const sheetTitle = 'MyNewSheet';
serverFunctions.addSheet(sheetTitle)
  .then((response) => {
    console.log('Sheet added successfully:', response);
    scriptHostFunctions.setHeight(500); // Example of using a host function
  })
  .catch((err) => {
    console.error('Failed to add sheet:', err);
  });

// Example 2: Calling a server function with async/await
async function createAndLogSheet(title: string) {
  try {
    const response = await serverFunctions.addSheet(title);
    console.log('Sheet created via async/await:', response);
    scriptHostFunctions.focusEditor(); // Switch focus to the editor
  } catch (err) {
    console.error('Error in async/await:', err);
  }
}

// Call the async function
createAndLogSheet('AnotherSheet');