GASKit-API

GASKit-API is a robust, lightweight, Express-like framework for building APIs in Google Apps Script. It provides routing, middleware, sub-app mounting, and security features out of the box.

Features

• Robust Routing: Define routes for GET, POST, PUT, DELETE, PATCH. Supports wildcards and regex.
• Modular Architecture: Use GASKit.Router() to create modular sub-apps and mount them (e.g., app.use('/api', apiRouter)).
• Security First:
  • App Sealing: Locks the app configuration after the first request to prevent memory leaks in persistent GAS containers.
  • Error Masking: Automatically catches internal errors and returns generic messages to clients to prevent information leakage.
  • XSS Protection: Safe redirect implementation.
• Middleware Support: Global and route-specific middleware.
• Path Parameters: /users/:id support.
• Request Helpers: access req.query, req.parameters (for arrays), and parsed req.body (JSON/Form).
• Response Helpers: res.json(), res.html(), res.redirect().

Installation

Method 1: Use as a Library (Recommended)

1. Open your Google Apps Script project.
2. In the left sidebar, click on Libraries (+).
3. Enter the Script ID (check release notes for latest ID).
4. Click Look up.
5. Select the latest version.
6. Set the Identifier to GASKit.
7. Click Add.

Method 2: Manual Copy-Paste

1. Create a new Google Apps Script project.
2. Create a file named GASKit.js and paste the content of the GASKit.js file from this repository.
3. Create a file named App.js (or any name) for your application logic.

Usage

Basic Setup

In your App.js (or your main script file):

// Initialize the App
// Assumes library identifier is 'GASKit' or code is pasted locally.
var app = GASKit.create();

// Define a route
app.get('/hello', function(req, res) {
  res.json({ message: 'Hello World' });
});

// Required: Hook into GAS Triggers
function doGet(e) {
  return app.doGet(e);
}

function doPost(e) {
  return app.doPost(e);
}

Modular Routing (Sub-Apps)

You can organize your code into separate routers.

var api = GASKit.Router();

api.get('/users', function(req, res) {
  res.json({ users: [] });
});

// Mount the router at /api
// This will handle requests to /api/users
app.use('/api', api);

Routing

app.get('/users', function(req, res) {
  res.json([{ name: 'Alice' }, { name: 'Bob' }]);
});

app.post('/users', function(req, res) {
  var user = req.body; // JSON body is automatically parsed
  // save user...
  res.status(201).json({ created: true });
});

// Path Parameters
app.get('/users/:id', function(req, res) {
  var id = req.params.id;
  res.json({ userId: id });
});

Redirects

app.get('/old-page', function(req, res) {
  res.redirect('/new-page');
});

Middleware

Middleware functions run before your route handlers. They can be used for logging, auth, etc.

// Global Middleware
app.use(function(req, res, next) {
  console.log('Request to ' + req.path);
  next();
});

// Route-specific Middleware
function auth(req, res, next) {
  if (!req.query.token) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
}

app.get('/protected', auth, function(req, res) {
  res.json({ secret: 'data' });
});

Request Object (req)

• req.path: The request path (e.g., /users).
• req.method: The HTTP method.
• req.query: Query parameters object (from e.parameter).
• req.parameters: Query parameters array support (from e.parameters).
• req.params: Route parameters (e.g., { id: '123' }).
• req.body: Parsed JSON body or raw content.
• req.e: The original Event object from Google Apps Script.

Response Object (res)

• res.status(code): Set HTTP status code.
• res.json(data): Return a JSON response.
• res.html(content): Return an HTML response.
• res.send(text): Return a plain text response.
• res.redirect(url): Redirect the client to a new URL.

Deployment

Deploy your script as a Web App.

• Execute as: Me (or User accessing the web app depending on needs).
• Who has access: Anyone (or specific domain).

The API endpoint will be your Web App URL. You can append paths like ?path=/users or if using pathInfo (e.g. /exec/users), the router will handle it.

Security Note

GASKit automatically "seals" the app after handling the first request. Any attempt to add routes or middleware inside a request handler (a common mistake in GAS) will throw an error to prevent memory leaks in the GAS execution environment.