Skip to content

juan-carlos-macias/chatbot

BranchesTags

Repository files navigation

Assistant API

REST API for an intelligent assistant with conversational capabilities using OpenAI, Google Calendar integration, and user management with Firebase Authentication.

📋 Description

This project is a backend API built with Node.js, TypeScript, and Express that provides an intelligent virtual assistant capable of:

  • Maintaining contextual conversations using OpenAI Assistants API
  • Automatically scheduling meetings in Google Calendar
  • Storing client/user information
  • Managing files to enrich the assistant's context
  • Authenticating users via Firebase

🚀 Key Features

🤖 Intelligent Assistant

  • Contextual Conversations: Maintains conversation history in threads
  • Function Calling: Ability to execute specific functions:
    • storeUserData: Stores user data (name, email, phone)
    • scheduleMeeting: Schedules meetings in Google Calendar with Google Meet
  • File Management: Supports file uploads to enrich the assistant's knowledge
  • Token Tracking: Monitors OpenAI token usage per user

📅 Google Calendar Integration

  • Automatic meeting scheduling
  • Google Meet link generation
  • Support for multiple attendees
  • Per-user timezone management

🔐 Authentication & Security

  • Authentication via Firebase Authentication
  • Authorization middleware on protected routes
  • Helmet for HTTP security
  • Configured CORS

📁 File Management

  • Support for multiple file types
  • Secure temporary storage
  • AWS S3 integration
  • Batch processing

🛠️ Technologies

Backend

  • Node.js - Runtime environment
  • TypeScript - Typed language
  • Express - Web framework
  • MongoDB + Mongoose - NoSQL database

External Services

  • OpenAI API - Intelligent assistant and natural language processing
  • Google Calendar API - Event and meeting management
  • Firebase Admin - Authentication and authorization
  • AWS S3 - File storage

Utilities

  • Winston - Logging system
  • Helmet - HTTP security
  • Express Validator - Data validation
  • Axios - HTTP client
  • Moment Timezone - Timezone management

📁 Project Structure

chatbot/
├── config/                          # Application configuration
│   ├── default.js                   # Default configuration
│   ├── production.js                # Production configuration
│   ├── test.js                      # Test configuration
│   └── custom-environment-variables.js
├── src/
│   ├── index.ts                     # Entry point
│   ├── app/
│   │   ├── index.ts                 # Express configuration
│   │   └── config/
│   │       └── winston.config.ts    # Logging configuration
│   ├── middlewares/
│   │   ├── auth.ts                  # Firebase authentication
│   │   ├── response.ts              # Response formatting
│   │   └── fileUploadMiddleware.ts  # File handling
│   ├── modules/
│   │   ├── db.module.ts             # MongoDB connection
│   │   ├── assistant/               # Assistant module
│   │   │   ├── assistant.model.ts
│   │   │   ├── assistant.service.ts
│   │   │   ├── assistant.interface.ts
│   │   │   └── assistant.validation.ts
│   │   ├── user/                    # User module
│   │   │   ├── user.model.ts
│   │   │   ├── user.service.ts
│   │   │   ├── user.interface.ts
│   │   │   └── user.validation.ts
│   │   ├── functionCalling/         # OpenAI function calling
│   │   │   ├── functionCalling.service.ts
│   │   │   └── functionCalling.interfaces.ts
│   │   ├── common/                  # Common services
│   │   │   ├── openai/
│   │   │   │   ├── openAI.ts
│   │   │   │   ├── axiosOpenAI.ts
│   │   │   │   └── functionCalling/
│   │   │   │       ├── functions.ts
│   │   │   │       └── toolsDefinition.ts
│   │   │   ├── google/
│   │   │   │   ├── googleAuth.service.ts
│   │   │   │   ├── googleCalendar.service.ts
│   │   │   │   └── googleCalendarFileBuilder.ts
│   │   │   └── plugins/
│   │   │       ├── firebase.ts
│   │   │       ├── catchAsync.ts
│   │   │       └── icsFileManager.ts
│   │   └── errors/                  # Error handling
│   │       ├── ApiError.ts
│   │       └── index.ts
│   └── routes/
│       ├── routes.ts                # Route configuration
│       └── apiv1/
│           ├── api.routes.ts
│           ├── assistant/           # Assistant routes
│           ├── users/               # User routes
│           ├── functionCalling/     # Function routes
│           └── google/              # Google Calendar routes
├── .env.example                     # Environment variables example
├── package.json
└── tsconfig.json

⚙️ Installation

Prerequisites

  • Node.js >= 14.x
  • MongoDB >= 4.x
  • OpenAI account with API access
  • Configured Firebase project
  • Google Cloud account with Calendar API enabled
  • AWS account (optional, for file storage)

Installation Steps

  1. Clone the repository
git clone git@github.com:jcmn182/chatbot.git
cd chatbot
  1. Install dependencies
npm install
  1. Configure environment variables

Copy the .env.example file to .env and configure the variables:

cp .env.example .env

Edit .env with your credentials:

# Server
PORT=3000
ENVIRONMENT=development

# Database
MONGODB_URI=mongodb://localhost:27017/assistant-db

# Basic authentication (optional)
AUTH_API_USERNAME=admin
AUTH_API_PASSWORD=secret

# Firebase
FIRE_BASE_TYPE=service_account
FIRE_BASE_PROJECT_ID=your-project-id
FIRE_BASE_PRIVATE_KEY_ID=your-private-key-id
FIRE_BASE_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n
FIRE_BASE_CLIENT_EMAIL=firebase-adminsdk@your-project.iam.gserviceaccount.com
FIRE_BASE_CLIENT_ID=your-client-id
FIRE_BASE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
FIRE_BASE_TOKEN_URI=https://oauth2.googleapis.com/token
FIRE_BASE_AUTH_PROVIDER_X509_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
FIRE_BASE_CLIENT_X509_CERT_URL=your-cert-url
FIRE_BASE_UNIVERSE_DOMAIN=googleapis.com

# OpenAI
OPENAI_TOKEN=sk-...your-openai-api-key

# Google OAuth (for Calendar API)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
  1. Build the project
npm run build
  1. Start the server

Development mode (with hot reload):

npm run start:dev

Production mode:

npm start

The server will start on the configured port (default: 3000).

📚 API Documentation

Base URL

http://localhost:3000/api/v1

Authentication

Most endpoints require Firebase Authentication. Include the Firebase ID token in the Authorization header:

Authorization: Bearer <firebase-id-token>

Endpoints

👤 Users

Create User

POST /api/v1/user
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "timeZone": "America/New_York"
}

Get User

GET /api/v1/user/:userId
Authorization: Bearer <token>

Update User

PATCH /api/v1/user/:userId
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "John Smith",
  "timeZone": "America/Los_Angeles"
}

🤖 Assistant

Create Assistant

POST /api/v1/assistant
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "My Personal Assistant"
}

Chat with Assistant

POST /api/v1/assistant/chat
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Schedule a meeting for tomorrow at 2pm",
  "threadId": "thread_abc123" // Optional, for continuing a conversation
}

Upload File to Assistant

POST /api/v1/assistant/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <your-file>

Supported file types:

  • PDF (.pdf)
  • Word documents (.docx)
  • Text files (.txt)
  • Code files (.py, .js, .ts, etc.)

📅 Google Calendar

Connect Google Calendar

POST /api/v1/calendar/connect
Authorization: Bearer <token>
Content-Type: application/json

{
  "accessToken": "ya29...",
  "refreshToken": "1//...",
  "redirectUri": "http://localhost:3000/callback"
}

Schedule Meeting

POST /api/v1/calendar/schedule
Authorization: Bearer <token>
Content-Type: application/json

{
  "summary": "Project Review Meeting",
  "description": "Review Q1 project progress",
  "start": "2025-01-15T14:00:00-05:00",
  "end": "2025-01-15T15:00:00-05:00",
  "attendees": ["colleague@example.com"]
}

🔧 Function Calling

Store User Data

POST /api/v1/functions/store-user-data
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "number": "+1234567890"
}

Response Format

All endpoints return responses in the following format:

Success Response:

{
  "response": {
    // Response data
  }
}

Error Response:

{
  "code": 400,
  "message": "Error description",
  "stack": "..." // Only in development mode
}

🔧 Configuration

MongoDB Configuration

Edit config/default.js to configure MongoDB connection:

mongodb: {
    uri: process.env.MONGODB_URI
}

OpenAI Configuration

The assistant uses OpenAI's Assistants API. Configure your API key in the environment variables.

Google Calendar Configuration

To enable Google Calendar integration:

  1. Create a project in Google Cloud Console
  2. Enable Calendar API
  3. Create OAuth 2.0 credentials
  4. Configure redirect URIs
  5. Add credentials to environment variables

Firebase Configuration

  1. Create a Firebase project
  2. Generate a service account key
  3. Add all Firebase configuration to environment variables

🧪 Testing

Run linting:

npm run lint

Fix linting issues:

npm run lint:fix

📊 Key Features Explained

Assistant Thread Management

The API maintains conversation context using OpenAI threads:

  • Each conversation has a unique threadId
  • Messages are stored in threads for context
  • Threads are associated with users
  • Token usage is tracked per user

Function Calling Flow

  1. User sends message to assistant
  2. Assistant determines if a function should be called
  3. Function is executed (e.g., scheduling meeting)
  4. Result is returned to assistant
  5. Assistant formulates response with action confirmation

Google Calendar Integration Flow

  1. User authorizes Google Calendar access
  2. Refresh token is stored securely
  3. When scheduling is needed, access token is obtained
  4. Meeting is created with Google Meet link
  5. ICS file can be generated for email invitations

🔐 Security Considerations

  • All sensitive routes are protected with Firebase authentication
  • Environment variables are used for all credentials
  • Helmet middleware provides HTTP security headers
  • CORS is configured to control cross-origin requests
  • File uploads are stored in temporary directories with size limits
  • MongoDB connection uses secure URI with authentication

🚀 Deployment

Environment Variables for Production

Ensure all production environment variables are set:

  • Use strong authentication credentials
  • Configure production MongoDB URI
  • Use production Firebase credentials
  • Set ENVIRONMENT=production

Building for Production

npm run build
npm start

Recommended Hosting Platforms

  • Heroku: Easy deployment with add-ons for MongoDB
  • AWS EC2/ECS: Full control and scalability
  • Google Cloud Run: Serverless container deployment
  • DigitalOcean: Simple VPS deployment

📝 Development

Code Style

This project uses:

  • ESLint for code linting (Airbnb style guide)
  • Prettier for code formatting
  • TypeScript for type

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages