email-oauth-flows

Files (22)

• README.md
• SKILL.md
• 01-gmail-connect.tsx · examples/
• 02-send-gmail.ts · examples/
• 03-outlook-connect.tsx · examples/
• 04-token-refresh.ts · examples/
• 05-email-dashboard.tsx · examples/
• package-lock.json
• package.json
• GMAIL_OAUTH.md · references/
• OUTLOOK_OAUTH.md · references/
• TOKEN_MANAGEMENT.md · references/
• gmail.ts · src/
• index.ts · src/
• outlook.ts · src/
• token-refresh.ts · src/
• types.ts · src/
• index.test.ts · tests/
• token-refresh.test.ts · tests/
• types.test.ts · tests/
• tsconfig.json
• vitest.config.ts

SKILL.md (first lines)

# Email OAuth Flows

Complete Gmail and Outlook OAuth integration for Next.js applications using Supabase Auth with automatic token refresh and email API access.

## When to Use

Use this skill when building Next.js applications that need:
- Gmail OAuth with email scopes (send, read, modify)
- Outlook/Microsoft OAuth with Microsoft Graph API
- Automatic OAuth token refresh
- Secure storage of email credentials
- Send emails via user's Gmail/Outlook account
- Read emails from user's inbox
- Email drafts and compose functionality

**Don't use this skill if:**
- You only need basic auth (email/password)
- You're using a different email service (SendGrid, AWS SES)
- You don't need user's email account access

## Stack

- Next.js 14+ (App Router)
- Supabase Auth (@supabase/ssr)
- Gmail API (Google OAuth)
- Microsoft Graph API (Azure OAuth)
- TypeScript (strict mode)

## Quick Start

### 1. Install Dependencies

```bash
npm install @supabase/ssr @supabase/supabase-js
npm install -D @project-forge/email-oauth-flows
```

### 2. Configure OAuth Providers in Supabase

**Gmail (Google):**
1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create OAuth 2.0 credentials
3. Add scopes: `gmail.send`, `gmail.modify`, `gmail.readonly`
4. Add redirect URI: `https://your-project.supabase.co/auth/v1/callback`
5. Copy Client ID & Secret to Supabase Dashboard

**Outlook (Azure):**
1. Go to [Azure Portal](https://portal.azure.com)
2. Register app in Azure Entra ID
3. Add API permissions: `Mail.Read`, `Mail.ReadWrite`, `Mail.Send`
4. Add redirect URI: `https://your-project.supabase.co/auth/v1/callback`
5. Copy Client ID & Secret to Supabase Dashboard

### 3. Setup Environment Variables

```bash
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
NEXT_PUBLIC_APP_URL=http://localhost:3000
```

### 4. Implement Gmail OAuth

```typescript
'use client'

import { signInWithGmail } from '@project-forge/email-oauth-flows/gmail'
import { createClient } from '@supabase/supabase-js'

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)

export function GmailConnectButton() {
  const handleConnect = async () => {
    await signInWithGmail(supabase, {
      redirectTo: `${process.env.NEXT_PUBLIC_APP_URL}/auth/callback`,
      scopes: ['gmail.send', 'gmail.modify', 'gmail.readonly'],
    })
  }

  return <button onClick={handleConnect}>Connect Gmail</button>
}
```

### 5. Handle OAuth Callback

```typescript
// app/auth/callback/route.ts
import { createRouteHandlerClient } from '@supabase/auth-helpers-nextjs'
import { cookies } from 'next/headers'
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const requestUrl = new URL(request.url)
  const code = requestUrl.searchParams.get('code')

  if (code) {
    const supabase = createRouteHandlerClient({ cookies })
    await supabase.auth.exchangeCodeForSession(code)
  }

  return NextResponse.redirect(new URL('/dashboard', request.url))
}
```

### 6. Send Email via Gmail API

```typescript
import { sendGmailEmail } from '@project-forge/email-oauth-flows/gmail'

const { data, error } = await sendGmailEmail({
  accessToken: session.provider_token,
  to: 'recipient@example.com',
  subject: 'Hello from Gmail',
  body: 'This email was sent via Gmail API',
})
```

From JimmyBlanquet/project-forge, MIT.

More from JimmyBlanquet/project-forge