cc-assistant

Self-hosted scheduling assistant via Gmail and Calendar.

Overview

cc-assistant is a Next.js application that integrates with Google Gmail and Calendar APIs to provide scheduling automation. It uses lightweight, fetch-based API wrappers — no heavyweight SDK dependencies.

Tech Stack

• Runtime: Bun
• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4 + shadcn/ui
• Auth: Better Auth with Google OAuth2

Getting Started

Prerequisites

• Bun v1.3+
• Google Cloud project with OAuth2 credentials
• Gmail and Calendar API scopes enabled

Setup

# Install dependencies
bun install

# Copy environment variables
cp .env.example .env

# Fill in your Google OAuth credentials in .env

Environment Variables

Variable	Description
GOOGLE_CLIENT_ID	Google OAuth client ID
GOOGLE_CLIENT_SECRET	Google OAuth client secret
CC_AUTHORIZED_DOMAINS	Comma-separated allowed email domains
CC_AUTHORIZED_EMAILS	Comma-separated allowed email addresses
CC_CALENDAR_ID	Google Calendar ID (defaults to primary)

Development

bun dev

Testing

bun test

Project Structure

app/                  # Next.js App Router pages and layouts
components/           # React components (UI, chat, dashboard)
lib/
  google/             # Fetch-based Google API wrappers
    gmail.ts          # Gmail: threads, messages, drafts, search
    calendar.ts       # Calendar: events, free/busy
    oauth.ts          # OAuth2 token exchange and refresh
    authorized.ts     # Email authorization checks
    fetch.ts          # Shared authenticated fetch wrapper
    types.ts          # TypeScript types for all API responses
    constants.ts      # API base URLs and OAuth scopes
  gmail.ts            # Re-exports from google/gmail
  calendar.ts         # Re-exports from google/calendar
tests/                # Unit tests

API Wrappers

All Google API wrappers use plain fetch and return a discriminated union — they never throw:

type GoogleApiResult<T> =
  | { ok: true; data: T }
  | { ok: false; status: number; error: string };

Gmail

• listMessages — search messages by query
• listThreads — search/list threads
• getThread — fetch a full thread with all messages
• getMessage — fetch a single message
• createDraft — create a draft reply in a thread
• listDrafts — list drafts with optional query
• sendDraft — send a previously created draft

Calendar

• listEvents — list events in a time range
• getEvent — fetch a single event
• createEvent — create a new event with attendees
• queryFreeBusy — check availability across calendars

License

MIT