Fresha Plugin for OpenPets

A comprehensive OpenPets plugin that integrates with Fresha's GraphQL API to search for beauty salons, spas, and wellness venues worldwide.

Features

• Geographic Search: Find venues by latitude/longitude with customizable radius
• Advanced Filtering: Filter by category, price, deals, gender, and more
• Venue Details: Get comprehensive venue information including services and pricing
• Featured Venues: Quickly find top-rated and featured locations
• Category Support: Browse available service categories
• No Authentication Required: Uses Fresha's public venue search API

Quick Start

1. Install Dependencies

npm install

2. Test Connection

npm run test:connection

3. Search for Venues

# Find beauty salons in New York
opencode run "search for beauty salons near latitude 40.7128 longitude -74.0060"

# Get featured venues in Paris
opencode run "get featured venues in latitude 48.8566 longitude 2.3522 radius 10km"

Available Tools

fresha-test-connection

Test connectivity to Fresha's GraphQL API.

// Returns connection status and sample data
{
  success: true,
  status: "connected",
  message: "Successfully connected to Fresha API"
}

fresha-search-venues

Advanced venue search with comprehensive filtering options.

Parameters:

• latitude (number, required): Search center latitude
• longitude (number, required): Search center longitude
• radius (number, optional): Search radius in km (default: 5)
• categoryId (string, optional): Filter by category ID
• maxPrice (number, optional): Maximum price filter
• hasDeals (boolean, optional): Only venues with deals
• sort (enum, optional): Sort order (RECOMMENDED, DISTANCE, PRICE_LOW, PRICE_HIGH, RATING)
• gender (enum, optional): Gender filter (EVERYONE, MALE, FEMALE)
• first (number, optional): Number of results (default: 20)

Example:

# Search for affordable salons with deals in London
fresha-search-venues latitude 51.5074 longitude -0.1278 radius 5km maxPrice 50 hasDeals true sort PRICE_LOW

fresha-near-me

Simplified venue search for finding nearby locations.

Parameters:

• latitude (number, required): Your latitude
• longitude (number, required): Your longitude
• radius (number, optional): Search radius in km (default: 5)
• query (string, optional): Search text (optional)

Example:

# Find venues near your location
fresha-near-me latitude 37.7749 longitude -122.4194 radius 3km

fresha-featured-venues

Get featured and top-rated venues in an area.

Parameters:

• latitude (number, required): Search center latitude
• longitude (number, required): Search center longitude
• radius (number, optional): Search radius in km (default: 10)
• limit (number, optional): Maximum results (default: 10)

Example:

# Get top 20 featured venues in Tokyo
fresha-featured-venues latitude 35.6762 longitude 139.6503 radius 15km limit 20

fresha-venue-details

Get detailed information about a specific venue.

Note: Currently limited by available persisted queries. Use search filters instead.

fresha-categories

Get available service categories for filtering.

Example:

fresha-categories

Environment Variables

The plugin works out of the box with no required configuration. Optional variables:

# Custom Fresha GraphQL endpoint
FRESHA_BASE_URL=https://www.fresha.com/graphql

# Request timeout in milliseconds
FRESHA_TIMEOUT=10000

Response Format

All tools return structured JSON:

// Success response
{
  success: true,
  data: {
    venues: [...],
    total: 42,
    summary: {
      currency: "EUR",
      averageRating: 4.8,
      featuredCount: 5
    }
  },
  message: "Found 42 venues"
}

// Error response  
{
  success: false,
  error: "Invalid latitude provided"
}

Use Cases

For Consumers

• Find nearby beauty salons and spas
• Compare prices and services
• Discover venues with special deals
• Read reviews and ratings

For Businesses

• Research local competition
• Analyze market areas
• Find similar venues in different locations

For Developers

• Integration into beauty/wellness applications
• Location-based venue discovery
• Price comparison tools

Geographic Search Examples

# New York City
fresha-near-me latitude 40.7128 longitude -74.0060

# London  
fresha-near-me latitude 51.5074 longitude -0.1278

# Paris
fresha-near-me latitude 48.8566 longitude 2.3522

# Tokyo
fresha-near-me latitude 35.6762 longitude 139.6503

# Sydney
fresha-near-me latitude -33.8688 longitude 151.2093

Advanced Filtering

# Budget-friendly with deals
fresha-search-venues latitude 40.7128 longitude -74.0060 maxPrice 30 hasDeals true

# High-rated venues only
fresha-search-venues latitude 51.5074 longitude -0.1278 sort RATING

# Gender-specific services
fresha-search-venues latitude 48.8566 longitude 2.3522 gender FEMALE

# Large radius search
fresha-near-me latitude 35.6762 longitude 139.6503 radius 25km

Development

The plugin uses a custom GraphQL client built specifically for Fresha's persisted queries:

• Persisted Query Hashes: Uses pre-compiled GraphQL queries for optimal performance
• Error Handling: Comprehensive error handling with detailed messages
• Type Safety: Full TypeScript support with generated types
• Rate Limiting: Built-in timeout handling and retry logic

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your improvements
4. Submit a pull request

License

MIT License - see LICENSE file for details.