Skip to content
Loopstack
Color theme

API: @loopstack/google-workspace

Classes

GmailGetMessageTool

Tool that gets the full content of a single Gmail message. Takes a messageId and format, and returns headers, decoded body text, snippet, label ids, and attachment metadata, or { error: 'unauthorized' } when no valid Google token is available.

import { GmailGetMessageTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GmailGetMessageTool extends BaseTool<GmailGetMessageArgs, object, GmailGetMessageResult> {
  protected handle(args: GmailGetMessageArgs, ctx: RunContext): Promise<ToolEnvelope<GmailGetMessageResult>>;
}

GmailReplyToMessageTool

Tool that replies to an existing Gmail message in-thread. Fetches the original message to set proper reply headers, supports replyAll, and returns the sent reply’s id, thread id, and label ids, or { error: 'unauthorized' } when no valid Google token is available.

import { GmailReplyToMessageTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GmailReplyToMessageTool extends BaseTool<GmailReplyToMessageArgs, object, GmailReplyToMessageResult> {
  protected handle(args: GmailReplyToMessageArgs, ctx: RunContext): Promise<ToolEnvelope<GmailReplyToMessageResult>>;
}

GmailSearchMessagesTool

Tool that searches Gmail messages using Gmail query syntax. Takes a query, optional labelIds, and pagination, and returns message summaries with headers and snippets plus a nextPageToken, or { error: 'unauthorized' } when no valid Google token is available.

import { GmailSearchMessagesTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GmailSearchMessagesTool extends BaseTool<GmailSearchMessagesArgs, object, GmailSearchMessagesResult> {
  protected handle(args: GmailSearchMessagesArgs, ctx: RunContext): Promise<ToolEnvelope<GmailSearchMessagesResult>>;
}

GmailSendMessageTool

Tool that sends a new email via Gmail. Takes to/cc/bcc recipients, a subject, and plain-text (and optional HTML) body, and returns the sent message’s id, thread id, and label ids, or { error: 'unauthorized' } when no valid Google token is available.

import { GmailSendMessageTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GmailSendMessageTool extends BaseTool<GmailSendMessageArgs, object, GmailSendMessageResult> {
  protected handle(args: GmailSendMessageArgs, ctx: RunContext): Promise<ToolEnvelope<GmailSendMessageResult>>;
}

GoogleCalendarCreateEventTool

Tool that creates a new event on a Google Calendar. Takes a summary, start/end times, and optional description, location, attendees, and reminders, and returns the created event’s id and link, or { error: 'unauthorized' } when no valid Google token is available.

import { GoogleCalendarCreateEventTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleCalendarCreateEventTool extends BaseTool<
  GoogleCalendarCreateEventArgs,
  object,
  GoogleCalendarCreateEventResult
> {
  protected handle(
    args: GoogleCalendarCreateEventArgs,
    ctx: RunContext,
  ): Promise<ToolEnvelope<GoogleCalendarCreateEventResult>>;
}

GoogleCalendarFetchEventsTool

Tool that fetches events from a Google Calendar within a time range. Takes a timeMin/timeMax window (and optional calendarId, query, maxResults) and returns matching events with start/end, attendees, and links, or { error: 'unauthorized' } when no valid Google token is available.

import { GoogleCalendarFetchEventsTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleCalendarFetchEventsTool extends BaseTool<
  GoogleCalendarFetchEventsArgs,
  object,
  GoogleCalendarFetchEventsResult
> {
  protected handle(
    args: GoogleCalendarFetchEventsArgs,
    ctx: RunContext,
  ): Promise<ToolEnvelope<GoogleCalendarFetchEventsResult>>;
}

GoogleCalendarListCalendarsTool

Tool that lists all Google Calendars the authenticated user has access to. Returns each calendar’s id, summary, time zone, and primary flag, or { error: 'unauthorized' } when no valid Google token is available.

import { GoogleCalendarListCalendarsTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleCalendarListCalendarsTool extends BaseTool<
  GoogleCalendarListCalendarsArgs,
  object,
  GoogleCalendarListCalendarsResult
> {
  protected handle(
    args: GoogleCalendarListCalendarsArgs,
    ctx: RunContext,
  ): Promise<ToolEnvelope<GoogleCalendarListCalendarsResult>>;
}

GoogleDriveDownloadFileTool

Tool that downloads or exports a file from Google Drive. Takes a fileId and optional exportMimeType, automatically handles Google Docs/Sheets/Slides export, and returns text or base64-encoded content with its mime type, or { error: 'unauthorized' } when no valid Google token is available. exportMimeType applies to Google Docs/Sheets/Slides only; other files are returned as stored, with their own mime type.

import { GoogleDriveDownloadFileTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleDriveDownloadFileTool extends BaseTool<
  GoogleDriveDownloadFileArgs,
  object,
  GoogleDriveDownloadFileResult
> {
  protected handle(
    args: GoogleDriveDownloadFileArgs,
    ctx: RunContext,
  ): Promise<ToolEnvelope<GoogleDriveDownloadFileResult>>;
}

GoogleDriveGetFileMetadataTool

Tool that gets detailed metadata for a single Google Drive file. Takes a fileId and returns name, mime type, size, timestamps, owners, parents, and sharing state, or { error: 'unauthorized' } when no valid Google token is available.

import { GoogleDriveGetFileMetadataTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleDriveGetFileMetadataTool extends BaseTool<
  GoogleDriveGetFileMetadataArgs,
  object,
  GoogleDriveGetFileMetadataResult
> {
  protected handle(
    args: GoogleDriveGetFileMetadataArgs,
    ctx: RunContext,
  ): Promise<ToolEnvelope<GoogleDriveGetFileMetadataResult>>;
}

GoogleDriveListFilesTool

Tool that lists and searches files in Google Drive. Supports Drive query syntax, folder browsing, ordering, and pagination, and returns file metadata plus a nextPageToken, or { error: 'unauthorized' } when no valid Google token is available.

import { GoogleDriveListFilesTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleDriveListFilesTool extends BaseTool<GoogleDriveListFilesArgs, object, GoogleDriveListFilesResult> {
  protected handle(args: GoogleDriveListFilesArgs, ctx: RunContext): Promise<ToolEnvelope<GoogleDriveListFilesResult>>;
}

GoogleDriveUploadFileTool

Tool that uploads a new file to Google Drive using multipart upload. Takes a name, content, mime type, and optional folder and description, and returns the created file’s id, name, and link, or { error: 'unauthorized' } when no valid Google token is available.

import { GoogleDriveUploadFileTool } from '@loopstack/google-workspace';

Provided by: GoogleWorkspaceModule

export class GoogleDriveUploadFileTool extends BaseTool<
  GoogleDriveUploadFileArgs,
  object,
  GoogleDriveUploadFileResult
> {
  protected handle(
    args: GoogleDriveUploadFileArgs,
    ctx: RunContext,
  ): Promise<ToolEnvelope<GoogleDriveUploadFileResult>>;
}

GoogleWorkspaceModule

NestJS module that provides the Google OAuth 2.0 provider and 11 Google Workspace tools (Calendar, Gmail, and Drive) for use in workflows and agents.

Registration:

  • GoogleWorkspaceModule — a bare import is enough. It imports OAuthModule internally and registers GoogleWorkspaceOAuthProvider (provider id 'google') plus all Calendar, Gmail, and Drive tools as providers, so they are resolvable by DI with no static configuration method.

Requires: Google OAuth client credentials in the environment — GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are mandatory (optionally GOOGLE_OAUTH_REDIRECT_URI, defaults to /oauth/callback). Without them the OAuth flow cannot authenticate and tools return { error: 'unauthorized' }.

import { GoogleWorkspaceModule } from '@loopstack/google-workspace';
export class GoogleWorkspaceModule {}

Type Aliases

GmailGetMessageArgs

Args for GmailGetMessageTool.

import { GmailGetMessageArgs } from '@loopstack/google-workspace';
export type GmailGetMessageArgs = z.infer<typeof inputSchema>;

GmailGetMessageResult

Result for GmailGetMessageTool.

import { GmailGetMessageResult } from '@loopstack/google-workspace';
export type GmailGetMessageResult =
  | {
      id: string;
      threadId: string;
      from: string;
      to: string;
      cc: string;
      subject: string;
      date: string;
      body: string;
      snippet: string;
      labelIds: string[];
      attachments: Array<{
        attachmentId: string;
        filename: string;
        mimeType: string;
        size: number;
      }>;
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GmailReplyToMessageArgs

Args for GmailReplyToMessageTool.

import { GmailReplyToMessageArgs } from '@loopstack/google-workspace';
export type GmailReplyToMessageArgs = z.infer<typeof inputSchema>;

GmailReplyToMessageResult

Result for GmailReplyToMessageTool.

import { GmailReplyToMessageResult } from '@loopstack/google-workspace';
export type GmailReplyToMessageResult =
  | {
      id: string;
      threadId: string;
      labelIds: string[];
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GmailSearchMessagesArgs

Args for GmailSearchMessagesTool.

import { GmailSearchMessagesArgs } from '@loopstack/google-workspace';
export type GmailSearchMessagesArgs = z.infer<typeof inputSchema>;

GmailSearchMessagesResult

Result for GmailSearchMessagesTool.

import { GmailSearchMessagesResult } from '@loopstack/google-workspace';
export type GmailSearchMessagesResult =
  | {
      messages: Array<{
        id: string;
        threadId: string;
        snippet: string;
        from: string;
        to: string;
        subject: string;
        date: string;
      }>;
      nextPageToken?: string;
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GmailSendMessageArgs

Args for GmailSendMessageTool.

import { GmailSendMessageArgs } from '@loopstack/google-workspace';
export type GmailSendMessageArgs = z.infer<typeof inputSchema>;

GmailSendMessageResult

Result for GmailSendMessageTool.

import { GmailSendMessageResult } from '@loopstack/google-workspace';
export type GmailSendMessageResult =
  | {
      id: string;
      threadId: string;
      labelIds: string[];
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GoogleCalendarCreateEventArgs

Args for GoogleCalendarCreateEventTool.

import { GoogleCalendarCreateEventArgs } from '@loopstack/google-workspace';
export type GoogleCalendarCreateEventArgs = z.infer<typeof inputSchema>;

GoogleCalendarCreateEventResult

Result for GoogleCalendarCreateEventTool.

import { GoogleCalendarCreateEventResult } from '@loopstack/google-workspace';
export type GoogleCalendarCreateEventResult =
  | {
      event: {
        id: string;
        summary: string;
        start: string | undefined;
        end: string | undefined;
        htmlLink: string;
      };
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GoogleCalendarFetchEventsArgs

Args for GoogleCalendarFetchEventsTool.

import { GoogleCalendarFetchEventsArgs } from '@loopstack/google-workspace';
export type GoogleCalendarFetchEventsArgs = z.infer<typeof inputSchema>;

GoogleCalendarFetchEventsResult

Result for GoogleCalendarFetchEventsTool.

import { GoogleCalendarFetchEventsResult } from '@loopstack/google-workspace';
export type GoogleCalendarFetchEventsResult = {
  events?: Array<{
    id: string;
    summary?: string;
    description?: string;
    start: string | undefined;
    end: string | undefined;
    location?: string;
    attendees?: Array<{
      email: string;
      responseStatus?: string;
    }>;
    htmlLink?: string;
  }>;
  error?: string;
  message?: string;
};

GoogleCalendarListCalendarsArgs

Args for GoogleCalendarListCalendarsTool.

import { GoogleCalendarListCalendarsArgs } from '@loopstack/google-workspace';
export type GoogleCalendarListCalendarsArgs = z.infer<typeof inputSchema>;

GoogleCalendarListCalendarsResult

Result for GoogleCalendarListCalendarsTool.

import { GoogleCalendarListCalendarsResult } from '@loopstack/google-workspace';
export type GoogleCalendarListCalendarsResult =
  | {
      calendars: Array<{
        id: string;
        summary: string;
        description?: string;
        primary: boolean;
        timeZone?: string;
      }>;
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GoogleDriveDownloadFileArgs

Args for GoogleDriveDownloadFileTool.

import { GoogleDriveDownloadFileArgs } from '@loopstack/google-workspace';
export type GoogleDriveDownloadFileArgs = z.infer<typeof inputSchema>;

GoogleDriveDownloadFileResult

Result for GoogleDriveDownloadFileTool.

import { GoogleDriveDownloadFileResult } from '@loopstack/google-workspace';
export type GoogleDriveDownloadFileResult =
  | {
      content: string;
      mimeType: string;
    }
  | {
      content: string;
      mimeType: string;
      encoding: 'base64';
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GoogleDriveGetFileMetadataArgs

Args for GoogleDriveGetFileMetadataTool.

import { GoogleDriveGetFileMetadataArgs } from '@loopstack/google-workspace';
export type GoogleDriveGetFileMetadataArgs = z.infer<typeof inputSchema>;

GoogleDriveGetFileMetadataResult

Result for GoogleDriveGetFileMetadataTool.

import { GoogleDriveGetFileMetadataResult } from '@loopstack/google-workspace';
export type GoogleDriveGetFileMetadataResult =
  | {
      id: string;
      name: string;
      mimeType: string;
      size?: string;
      modifiedTime: string;
      createdTime: string;
      owners?: Array<{
        displayName: string;
        email: string;
      }>;
      webViewLink?: string;
      parents?: string[];
      description?: string;
      shared?: boolean;
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GoogleDriveListFilesArgs

Args for GoogleDriveListFilesTool.

import { GoogleDriveListFilesArgs } from '@loopstack/google-workspace';
export type GoogleDriveListFilesArgs = z.infer<typeof inputSchema>;

GoogleDriveListFilesResult

Result for GoogleDriveListFilesTool.

import { GoogleDriveListFilesResult } from '@loopstack/google-workspace';
export type GoogleDriveListFilesResult =
  | {
      files: Array<{
        id: string;
        name: string;
        mimeType: string;
        size?: string;
        modifiedTime: string;
        createdTime: string;
        owners?: Array<{
          displayName: string;
          email: string;
        }>;
        webViewLink?: string;
      }>;
      nextPageToken?: string;
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

GoogleDriveUploadFileArgs

Args for GoogleDriveUploadFileTool.

import { GoogleDriveUploadFileArgs } from '@loopstack/google-workspace';
export type GoogleDriveUploadFileArgs = z.infer<typeof inputSchema>;

GoogleDriveUploadFileResult

Result for GoogleDriveUploadFileTool.

import { GoogleDriveUploadFileResult } from '@loopstack/google-workspace';
export type GoogleDriveUploadFileResult =
  | {
      id: string;
      name: string;
      mimeType: string;
      webViewLink?: string;
    }
  | {
      error: 'unauthorized';
      message: string;
    }
  | {
      error: 'api_error';
      message: string;
    };

Variables

GmailGetMessageResultSchema

Zod schema for the success shape of GmailGetMessageResult — the message content and attachment metadata.

import { GmailGetMessageResultSchema } from '@loopstack/google-workspace';
GmailGetMessageResultSchema: z.ZodObject<
  {
    id: z.ZodString;
    threadId: z.ZodString;
    from: z.ZodString;
    to: z.ZodString;
    cc: z.ZodString;
    subject: z.ZodString;
    date: z.ZodString;
    body: z.ZodString;
    snippet: z.ZodString;
    labelIds: z.ZodArray<z.ZodString>;
    attachments: z.ZodArray<
      z.ZodObject<
        {
          attachmentId: z.ZodString;
          filename: z.ZodString;
          mimeType: z.ZodString;
          size: z.ZodNumber;
        },
        z.core.$strict
      >
    >;
  },
  z.core.$strict
>;

GmailReplyToMessageResultSchema

Zod schema for the success shape of GmailReplyToMessageResult — the sent reply.

import { GmailReplyToMessageResultSchema } from '@loopstack/google-workspace';
GmailReplyToMessageResultSchema: z.ZodObject<
  {
    id: z.ZodString;
    threadId: z.ZodString;
    labelIds: z.ZodArray<z.ZodString>;
  },
  z.core.$strict
>;

GmailSearchMessagesResultSchema

Zod schema for the success shape of GmailSearchMessagesResult — the message summaries and pagination token.

import { GmailSearchMessagesResultSchema } from '@loopstack/google-workspace';
GmailSearchMessagesResultSchema: z.ZodObject<
  {
    messages: z.ZodArray<
      z.ZodObject<
        {
          id: z.ZodString;
          threadId: z.ZodString;
          snippet: z.ZodString;
          from: z.ZodString;
          to: z.ZodString;
          subject: z.ZodString;
          date: z.ZodString;
        },
        z.core.$strict
      >
    >;
    nextPageToken: z.ZodOptional<z.ZodString>;
  },
  z.core.$strict
>;

GmailSendMessageResultSchema

Zod schema for the success shape of GmailSendMessageResult — the sent message.

import { GmailSendMessageResultSchema } from '@loopstack/google-workspace';
GmailSendMessageResultSchema: z.ZodObject<
  {
    id: z.ZodString;
    threadId: z.ZodString;
    labelIds: z.ZodArray<z.ZodString>;
  },
  z.core.$strict
>;

GoogleCalendarCreateEventResultSchema

Zod schema for the success shape of GoogleCalendarCreateEventResult — the created event.

import { GoogleCalendarCreateEventResultSchema } from '@loopstack/google-workspace';
GoogleCalendarCreateEventResultSchema: z.ZodObject<
  {
    event: z.ZodObject<
      {
        id: z.ZodString;
        summary: z.ZodString;
        start: z.ZodOptional<z.ZodString>;
        end: z.ZodOptional<z.ZodString>;
        htmlLink: z.ZodString;
      },
      z.core.$strict
    >;
  },
  z.core.$strict
>;

GoogleCalendarFetchEventsResultSchema

Zod schema for the success shape of GoogleCalendarFetchEventsResult — the fetched events.

import { GoogleCalendarFetchEventsResultSchema } from '@loopstack/google-workspace';
GoogleCalendarFetchEventsResultSchema: z.ZodObject<
  {
    events: z.ZodArray<
      z.ZodObject<
        {
          id: z.ZodString;
          summary: z.ZodOptional<z.ZodString>;
          description: z.ZodOptional<z.ZodString>;
          start: z.ZodOptional<z.ZodString>;
          end: z.ZodOptional<z.ZodString>;
          location: z.ZodOptional<z.ZodString>;
          attendees: z.ZodOptional<
            z.ZodArray<
              z.ZodObject<
                {
                  email: z.ZodString;
                  responseStatus: z.ZodOptional<z.ZodString>;
                },
                z.core.$strict
              >
            >
          >;
          htmlLink: z.ZodOptional<z.ZodString>;
        },
        z.core.$strict
      >
    >;
  },
  z.core.$strict
>;

GoogleCalendarListCalendarsResultSchema

Zod schema for the success shape of GoogleCalendarListCalendarsResult — the calendar list.

import { GoogleCalendarListCalendarsResultSchema } from '@loopstack/google-workspace';
GoogleCalendarListCalendarsResultSchema: z.ZodObject<
  {
    calendars: z.ZodArray<
      z.ZodObject<
        {
          id: z.ZodString;
          summary: z.ZodString;
          description: z.ZodOptional<z.ZodString>;
          primary: z.ZodBoolean;
          timeZone: z.ZodOptional<z.ZodString>;
        },
        z.core.$strict
      >
    >;
  },
  z.core.$strict
>;

GoogleDriveDownloadFileResultSchema

Zod schema for the success shape of GoogleDriveDownloadFileResult — the file content, base64-encoded when binary.

import { GoogleDriveDownloadFileResultSchema } from '@loopstack/google-workspace';
GoogleDriveDownloadFileResultSchema: z.ZodObject<
  {
    content: z.ZodString;
    mimeType: z.ZodString;
    encoding: z.ZodOptional<z.ZodLiteral<'base64'>>;
  },
  z.core.$strict
>;

GoogleDriveGetFileMetadataResultSchema

Zod schema for the success shape of GoogleDriveGetFileMetadataResult — the file metadata.

import { GoogleDriveGetFileMetadataResultSchema } from '@loopstack/google-workspace';
GoogleDriveGetFileMetadataResultSchema: z.ZodObject<
  {
    id: z.ZodString;
    name: z.ZodString;
    mimeType: z.ZodString;
    size: z.ZodOptional<z.ZodString>;
    modifiedTime: z.ZodString;
    createdTime: z.ZodString;
    owners: z.ZodOptional<
      z.ZodArray<
        z.ZodObject<
          {
            displayName: z.ZodString;
            email: z.ZodString;
          },
          z.core.$strict
        >
      >
    >;
    webViewLink: z.ZodOptional<z.ZodString>;
    parents: z.ZodOptional<z.ZodArray<z.ZodString>>;
    description: z.ZodOptional<z.ZodString>;
    shared: z.ZodOptional<z.ZodBoolean>;
  },
  z.core.$strict
>;

GoogleDriveListFilesResultSchema

Zod schema for the success shape of GoogleDriveListFilesResult — the file list and pagination token.

import { GoogleDriveListFilesResultSchema } from '@loopstack/google-workspace';
GoogleDriveListFilesResultSchema: z.ZodObject<
  {
    files: z.ZodArray<
      z.ZodObject<
        {
          id: z.ZodString;
          name: z.ZodString;
          mimeType: z.ZodString;
          size: z.ZodOptional<z.ZodString>;
          modifiedTime: z.ZodString;
          createdTime: z.ZodString;
          owners: z.ZodOptional<
            z.ZodArray<
              z.ZodObject<
                {
                  displayName: z.ZodString;
                  email: z.ZodString;
                },
                z.core.$strict
              >
            >
          >;
          webViewLink: z.ZodOptional<z.ZodString>;
        },
        z.core.$strict
      >
    >;
    nextPageToken: z.ZodOptional<z.ZodString>;
  },
  z.core.$strict
>;

GoogleDriveUploadFileResultSchema

Zod schema for the success shape of GoogleDriveUploadFileResult — the created file.

import { GoogleDriveUploadFileResultSchema } from '@loopstack/google-workspace';
GoogleDriveUploadFileResultSchema: z.ZodObject<
  {
    id: z.ZodString;
    name: z.ZodString;
    mimeType: z.ZodString;
    webViewLink: z.ZodOptional<z.ZodString>;
  },
  z.core.$strict
>;