ReturnClaw App

Voice-first AI agent for retail returns. Real OAuth. Real email search. Real returns.

Quick Start

# Clone
git clone https://github.com/KelleyHuntPLLC/returnclaw.git
cd returnclaw-app

# Install
npm install

# Configure (requires Google OAuth credentials)
cp .env.example .env
# Edit .env with your Google Cloud OAuth credentials

# Run
npm start
# Open http://localhost:3000

Google OAuth Setup

1. Go to https://console.cloud.google.com/apis/credentials
2. Create a project or select existing
3. Create OAuth 2.0 Client ID (Web application)
4. Add authorized redirect URI: http://localhost:3000/auth/google/callback
5. Copy Client ID and Client Secret to .env

Static Mode (No Backend)

The app also works as a static site (e.g., GitHub Pages) with simulated data. Just open public/index.html — no server needed for the demo experience.

Architecture

returnclaw-app/
├── server.js           # Express backend (OAuth, email search, API)
├── public/
│   ├── index.html      # Landing page + full agent interface
│   ├── style.css       # All styles
│   └── app.js          # Frontend agent engine (dual-mode)
├── package.json
├── .env.example
└── README.md

Dual Mode

The frontend automatically detects whether it's running with the backend:

• Live Mode (with node server.js): Real Google OAuth, real Gmail search, real policy API
• Demo Mode (static HTML): Simulated email connection, mock order data

Detection happens via a health check to /api/health on page load.

API Endpoints

Endpoint	Method	Description
/api/health	GET	Health check & mode detection
/auth/google	GET	Generate Gmail OAuth URL
/auth/google/callback	GET	OAuth callback handler
/auth/status/:sessionId	GET	Check connection status
/api/email/search	POST	Search Gmail for order emails
/api/policy/:retailer	GET	Get return policy for retailer
/api/return/link	POST	Generate return deep link

Built by Kelley Hunt, PLLC

Copyright (c) 2026 Kelley Hunt, PLLC. All rights reserved.