gas-client

library0.2.2jsnpmunverified

gas-client is a client-side utility library designed for Google Apps Script projects, providing a modern, promise-based interface for calling server-side Apps Script functions. It acts as a user-friendly wrapper around the native `google.script.run` API, abstracting away callback-based error and success handling in favor of standard JavaScript Promises and async/await syntax. The current stable version is 1.2.1, with minor releases and patches occurring as needed to address compatibility and improvements. A key differentiator is its ability to provide consistent access to `google.script.host` functions (like `close()` or `setHeight()`) in both production Apps Script environments and local development setups. It is specifically designed to integrate seamlessly with local development servers, such as those used in React Google Apps Script projects, by allowing explicit configuration of allowed development domains. This enables a more streamlined and conventional client-side development workflow for Apps Script.

gcp web-framework http-networking

npm install gas-client

github ↗package ↗

INSTALL

IMPORT

SIG · GAS-CLIENT

gas-client

gcpjavascriptv0.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

GASClient

✓ import { GASClient } from 'gas-client';

✗ const GASClient = require('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

✓ const { serverFunctions } = new GASClient();

✗ import { serverFunctions } from 'gas-client';

`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

✓ const { scriptHostFunctions } = new GASClient();

✗ import { scriptHostFunctions } from 'gas-client';

`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.

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');

Debug

Known issues

breakingThe `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`.

affects: <1.0.0

gotchaWhen 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.

affects: >=0.3.0

gotchaPrior 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.

affects: <1.2.1

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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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...

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

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.

Upgrade

Version history

0.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

35 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/enuchi/gas-client ↗

packagehttps://www.npmjs.com/package/gas-client ↗