@sowonai/nestjs-google-oauth-integration NPM

@sowonai/nestjs-google-oauth-integration

NestJS module for Google OAuth 2.0 integration, with flexible token storage strategies for server-side Google API access and service integration.

This module provides a complete solution for server-side integration with Google APIs in NestJS applications. It simplifies Google API integration through token management, automated authentication flows, and various storage options.

Installation

npm install @sowonai/nestjs-google-oauth-integration googleapis @google-cloud/local-auth

Features

Supports Google OAuth 2.0 authentication and server-to-server API integration
Flexible token storage strategies (file system, in-memory, database, custom)
Automatic token management and refresh
Multi-tenant support (user ID-based)
Optimized for server-side Google API access
Easy integration with user accounts and Google services
Simple integration as a NestJS module
Integrated logging system that respects NestJS application logger settings

Usage

Basic Setup (No Token Storage)

import { Module } from '@nestjs/common';
import { GoogleOAuthModule } from '@sowonai/nestjs-google-oauth-integration';

@Module({
  imports: [
    GoogleOAuthModule.forRoot({
      name: 'my-app',
      credentialsFilename: 'credentials.json',
      scopes: [
        'https://www.googleapis.com/auth/gmail.readonly',
        'https://www.googleapis.com/auth/gmail.send'
      ]
      // If tokenRepository is not specified, tokens are not persisted
    }),
  ],
})
export class AppModule {}

Using File System Token Repository

import { Module } from '@nestjs/common';
import { GoogleOAuthModule, FileSystemTokenRepository } from '@sowonai/nestjs-google-oauth-integration';
import * as path from 'path';
import * as os from 'os';

const tokenDir = path.join(os.homedir(), '.my-app');

@Module({
  imports: [
    GoogleOAuthModule.forRoot({
      name: 'my-app',
      credentialsFilename: 'credentials.json',
      tokenRepository: new FileSystemTokenRepository({
        tokenDir: tokenDir,
        tokenPath: path.join(tokenDir, 'google-token.json')
      }),
      scopes: [
        'https://www.googleapis.com/auth/gmail.readonly',
        'https://www.googleapis.com/auth/gmail.send'
      ]
    }),
  ],
})
export class AppModule {}

Using In-Memory Token Repository (Test Environment)

import { Module } from '@nestjs/common';
import { GoogleOAuthModule, InMemoryTokenRepository } from '@sowonai/nestjs-google-oauth-integration';

@Module({
  imports: [
    GoogleOAuthModule.forRoot({
      name: 'my-test-app',
      credentialsFilename: 'test-credentials.json',
      scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
      tokenRepository: InMemoryTokenRepository
    }),
  ],
})
export class TestAppModule {}

Using a Custom Token Repository (Server Environment)

import { Module, Injectable } from '@nestjs/common';
import { GoogleOAuthModule, TokenRepository } from '@sowonai/nestjs-google-oauth-integration';
import { TypeOrmModule } from '@nestjs/typeorm';
import { TokenEntity } from './entities/token.entity';
import { Repository } from 'typeorm';
import { InjectRepository } from '@nestjs/typeorm';
import { Credentials } from 'google-auth-library';

// Custom token repository implementation
@Injectable()
class CustomTokenRepository implements TokenRepository {
  constructor(@InjectRepository(TokenEntity) private repo: Repository<TokenEntity>) {}
  
  async saveToken(token: Credentials, userId?: string): Promise<void> {
    // Logic to save token in the database
  }
  
  async getToken(userId?: string): Promise<Credentials | null> {
    // Logic to retrieve token from the database
  }
  
  async hasToken(userId?: string): Promise<boolean> {
    // Logic to check token existence in the database
  }
}

@Module({
  imports: [
    TypeOrmModule.forFeature([TokenEntity]),
    GoogleOAuthModule.forRoot({
      name: 'my-server-app',
      credentialsFilename: 'server-credentials.json',
      scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
      tokenRepository: CustomTokenRepository
    }),
  ],
  providers: [CustomTokenRepository]
})
export class ServerAppModule {}

Configuring Logging

The module integrates with NestJS's built-in logging system. You can configure logging in two ways:

Using the module's logging options:

GoogleOAuthModule.forRoot({
  name: 'my-app',
  credentialsFilename: 'credentials.json',
  scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
  logging: {
    enabled: true,  // Set to false to disable logging from this module
    level: 'error'  // Set the log level: 'error', 'warn', 'log', 'debug', or 'verbose'
  }
})

Using NestJS's application logger configuration:

// In your main.ts file
const app = await NestFactory.create(AppModule, {
  logger: ['error', 'warn'], // Only error and warning logs will be shown from all modules
});

The module's logger respects both configurations, giving you fine-grained control over log output.

Example: Using the Service

import { Injectable } from '@nestjs/common';
import { GoogleOAuthService } from '@sowonai/nestjs-google-oauth-integration';

@Injectable()
export class GmailService {
  constructor(private readonly googleOAuthService: GoogleOAuthService) {}

  async sendEmail(to: string, subject: string, body: string) {
    // Check authentication
    const isAuth = await this.googleOAuthService.isAuthenticated();
    if (!isAuth) {
      await this.googleOAuthService.authenticate();
    }
    // Email sending logic using Google APIs
    // ...
  }
  
  // Example for multi-tenant environments
  async sendEmailAsUser(userId: string, to: string, subject: string, body: string) {
    // Check authentication for a specific user
    const isAuth = await this.googleOAuthService.isAuthenticated(userId);
    if (!isAuth) {
      await this.googleOAuthService.authenticate(userId);
    }
    // Email sending logic for a specific user using Google APIs
    // ...
  }
}

Use Cases

This module is especially useful for the following scenarios:

Server-to-Server Integration

Integrate with Google Cloud/API from MCP (Multi-Cloud Platform) servers
Use Google services in background jobs (e.g., automated document processing, email sending)
Leverage Google APIs for server-side analytics and report generation

Account Integration

Integrate Google services per user in apps with their own login system
Access Google services on behalf of users (e.g., manage Google Drive files, create calendar events)
Securely manage tokens for multiple users