@loopstack/google-workspace-module

Google Workspace integration module for the Loopstack  automation framework.

Provides a Google OAuth 2.0 provider and 11 tools for interacting with Google Calendar, Gmail, and Drive. Registers a Google OAuth provider with @loopstack/oauth-module so any workflow can authenticate users via their Google account.

When to Use

• Your workflow needs to read or create calendar events — use the Calendar tools.
• Your workflow needs to search, read, or send emails — use the Gmail tools.
• Your workflow needs to browse, download, or upload files in Google Drive — use the Drive tools.
• You’re building an agent that works across Google services — register all tools and let the LLM pick the right one.

Installation

npm install @loopstack/google-workspace-module

Register the module alongside OAuthModule:

import { Module } from '@nestjs/common';
import { GoogleWorkspaceModule } from '@loopstack/google-workspace-module';
import { OAuthModule } from '@loopstack/oauth-module';
 
@Module({
  imports: [OAuthModule, GoogleWorkspaceModule],
  providers: [MyWorkflow],
})
export class MyModule {}

Environment Variables

Obtain credentials from the Google Cloud Console .

Quick Start

Use Google tools in an agent workflow:

import { AgentWorkflow } from '@loopstack/agent';
import { BaseWorkflow, Transition, Workflow } from '@loopstack/common';
 
@Workflow({ title: 'Google Assistant' })
export class GoogleAssistantWorkflow extends BaseWorkflow {
  constructor(private readonly agent: AgentWorkflow) {
    super();
  }
 
  @Transition({ to: 'chatting' })
  async start(state: Record<string, unknown>): Promise<Record<string, unknown>> {
    await this.agent.run(
      {
        system: 'You are a Google Workspace assistant with access to Calendar, Gmail, and Drive.',
        tools: [
          'google_calendar_list_calendars',
          'google_calendar_fetch_events',
          'google_calendar_create_event',
          'gmail_search_messages',
          'gmail_get_message',
          'gmail_send_message',
          'gmail_reply_to_message',
          'google_drive_list_files',
          'google_drive_get_file_metadata',
          'google_drive_download_file',
          'google_drive_upload_file',
        ],
        userMessage: 'Summarize my calendar events for today.',
      },
      { callback: { transition: 'agentDone' }, show: 'inline', label: 'Working...' },
    );
    return state;
  }
}

All tools return { error: 'unauthorized' } when no valid token is available, so your workflow can trigger authentication on demand.

How It Works

Provider Registration

GoogleWorkspaceOAuthProvider implements OAuthProviderInterface and registers itself with the OAuthProviderRegistry at startup. After that, the generic OAuthWorkflow from @loopstack/oauth-module handles provider: 'google' automatically.

Additional scopes (Calendar, Gmail, Drive) should be requested when launching the OAuth flow depending on which tools your workflow uses.

Authentication Pattern

Tools check for a valid OAuth token via OAuthTokenStore. When no token exists (or it’s expired), the tool returns { error: 'unauthorized' }. Your workflow should catch this and launch the OAuth flow:

const result = await this.oAuth.run(
  { provider: 'google', scopes: ['https://www.googleapis.com/auth/calendar.readonly'] },
  { callback: { transition: 'authCompleted' } },
);

See the google-oauth-example for a complete implementation of this pattern.

Tools Reference

Calendar

google_calendar_list_calendars

Lists all calendars the authenticated user has access to.

google_calendar_fetch_events

Fetches events from a calendar within a time range.

google_calendar_create_event

Creates a new calendar event.

Gmail

gmail_search_messages

Searches Gmail messages using Gmail query syntax.

gmail_get_message

Gets full content of a single message including body and attachment metadata.

gmail_send_message

Sends a new email.

gmail_reply_to_message

Replies to an existing message in-thread.

Drive

google_drive_list_files

Lists and searches files. Supports Drive query syntax and folder browsing.

google_drive_get_file_metadata

Gets detailed metadata for a single file.

google_drive_download_file

Downloads or exports a file. Automatically handles Google Docs/Sheets/Slides export.

google_drive_upload_file

Uploads a new file using multipart upload.

Public API

• Module: GoogleWorkspaceModule
• Provider: GoogleWorkspaceOAuthProvider
• Calendar Tools: GoogleCalendarListCalendarsTool, GoogleCalendarFetchEventsTool, GoogleCalendarCreateEventTool
• Gmail Tools: GmailSearchMessagesTool, GmailGetMessageTool, GmailSendMessageTool, GmailReplyToMessageTool
• Drive Tools: GoogleDriveListFilesTool, GoogleDriveGetFileMetadataTool, GoogleDriveDownloadFileTool, GoogleDriveUploadFileTool

Dependencies

• @loopstack/oauth-module — OAuthProviderRegistry, OAuthProviderInterface, OAuthTokenStore

Related

• OAuth Integration — OAuth flow patterns and token management
• google-oauth-example — full example with agent workflow, Calendar/Gmail/Drive tools, and authentication handling

About

Author: Jakob Klippel 

License: MIT