Untappd OpenClaw Skill

A comprehensive OpenClaw skill that integrates with Untappd, the world's largest social network for beer enthusiasts. Search for beers, check in with ratings and comments, view checkin history, and manage your beer-drinking social experience directly from your OpenClaw assistant.

✨ Features

🔍 Beer Search & Discovery

• Natural language search queries ("Find a Dogfish Head IPA")
• Comprehensive beer information with ratings and brewery details
• Smart brewery + beer name optimization
• JSON and formatted table output

🍺 Beer Check-ins

• Full-featured check-ins with 1-5 star ratings (supports half ratings)
• Add comments and tasting notes (up to 140 characters)
• GPS location integration
• Social media sharing (Facebook, Twitter, Foursquare)
• Automatic badge earning
• Dry-run mode for testing

📊 History & Analytics

• Personal checkin history viewing
• Public user profile access
• Drinking statistics and badge tracking
• Compact and detailed viewing formats
• JSON export for data analysis

🔐 Complete Authentication

• Client credentials for searches and public data
• OAuth 2.0 for authenticated actions
• Secure credential storage
• Interactive setup process

🚀 Quick Start

Prerequisites

• OpenClaw installed and running
• Python 3.8+
• Untappd API credentials (free from Untappd API)

Installation

1. Clone this repository into your OpenClaw skills directory:

   cd ~/.openclaw/skills
   git clone https://github.com/DexDevCode/openclaw-untappd-skill.git untappd

2. Install dependencies (if any additional packages are needed):

   cd untappd
   pip install -r requirements.txt  # If requirements.txt exists

3. Set up authentication:

   # Configure your Untappd API credentials
   python3 scripts/untappd_setup.py credentials
   
   # Complete OAuth flow for authenticated features
   python3 scripts/untappd_setup.py auth
   
   # Test your setup
   python3 scripts/untappd_setup.py test

Configuration

Getting API Credentials

1. Visit Untappd API and register your application
2. Note down your Client ID and Client Secret
3. Set redirect URI to http://localhost:8080/callback (for local OAuth)

Environment Setup

You can configure credentials via:

Option 1: Interactive Setup (Recommended)

python3 scripts/untappd_setup.py credentials

Option 2: Environment Variables

export UNTAPPD_CLIENT_ID="your_client_id_here"
export UNTAPPD_CLIENT_SECRET="your_client_secret_here"
export UNTAPPD_ACCESS_TOKEN="your_access_token_here"  # Optional, for authenticated features

Option 3: Configuration File Create ~/.openclaw/skills/untappd/credentials.ini:

[untappd]
client_id = your_client_id_here
client_secret = your_client_secret_here
access_token = your_access_token_here  # Optional

📚 Usage Examples

Via OpenClaw Chat

You: "Search for Russian River Pliny the Elder on Untappd"
Assistant: [Uses untappd skill to search and display results]

You: "Check in to that beer with a 5 star rating"  
Assistant: [Performs checkin with rating]

You: "Show my recent beer checkins"
Assistant: [Displays your checkin history]

Direct CLI Usage

# Search for beers
python3 scripts/untappd_search.py "Stone Arrogant Bastard"

# Check in to a beer (ID 12345) with rating and comment
python3 scripts/untappd_checkin.py 12345 --rating 4.5 --comment "Exceptional hop character!"

# View your recent checkins
python3 scripts/untappd_checkins.py --limit 10 --compact

# Get detailed beer information
python3 scripts/untappd_search.py "Guinness" --format json

🛠️ API Capabilities

Public Features (Client Credentials Only)

• ✅ Search beers and breweries
• ✅ Get detailed beer information
• ✅ View public user profiles
• ✅ Access trending beer data

Authenticated Features (OAuth Required)

• ✅ Check in to beers with ratings/comments
• ✅ Access private user data
• ✅ Share to social media platforms
• ✅ Manage wishlist and badges
• ✅ View personalized recommendations

📁 Project Structure

untappd/
├── SKILL.md                    # OpenClaw skill definition
├── README.md                   # This file
├── EXAMPLES.md                 # Usage examples and workflows
├── test_skill.py              # Comprehensive test suite
├── .gitignore                 # Git ignore rules
├── scripts/                   # CLI tools and core functionality
│   ├── untappd_client.py     # Core API client library
│   ├── untappd_setup.py      # Authentication setup tool
│   ├── untappd_search.py     # Beer search CLI
│   ├── untappd_checkin.py    # Beer checkin CLI
│   └── untappd_checkins.py   # Checkin history CLI
└── references/               # Detailed documentation
    ├── api.md               # Complete API reference
    └── authentication.md    # Authentication setup guide

🧪 Testing

Run the comprehensive test suite:

python3 test_skill.py

Tests include:

• Skill structure validation
• File permissions and executability
• Mock API functionality
• Error handling
• Authentication flow

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork this repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (python3 test_skill.py)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Code Style

• Follow PEP 8 for Python code
• Include docstrings for functions and classes
• Add tests for new functionality
• Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• OpenClaw - The AI assistant platform
• Untappd - The social beer platform
• Untappd API Documentation

⚠️ Disclaimer

This is an unofficial integration with Untappd. Please use responsibly and in accordance with Untappd's Terms of Service and API rate limits (100 requests per hour).

📞 Support

• Issues: Report bugs or request features via GitHub Issues
• OpenClaw Documentation: openclaw.com/docs
• Untappd API Support: untappd.com/api