# API Comparison Guide: TypeSense vs Supafolio

## Overview Comparison

| Feature | TypeSense | Supafolio |
|---------|-----------|-----------|
| **Type** | Open-source search engine | Proprietary book metadata service |
| **Cost Model** | Infrastructure costs only | Per-record/usage pricing |
| **Hosting** | Self-hosted required | Fully managed service |
| **Data Format** | JSON/JSONL | ONIX + JSON |
| **Performance** | Millisecond responses | Variable response times |
| **Scalability** | RAM-limited | Cloud-based scaling |
| **Setup Complexity** | High (devops required) | Low (plug-and-play) |
| **Privacy** | Full data control | Vendor-managed data |
| **Updates** | Manual version upgrades | Automatic service updates |

## Feature-by-Feature Comparison

### Search & Discovery

| Feature | TypeSense | Supafolio |
|---------|-----------|-----------|
| **Text Search** | Configurable typo tolerance | Industry-optimized ranking |
| **Faceted Search** | Real-time faceting | Pre-configured filters |
| **Autocomplete** | Prefix/infix search | Predictive search API |
| **Bulk Operations** | Document import/export | Multi-ISBN lookup |
| **Vector Search** | Built-in semantic search | Not available |
| **Geo Search** | Location-based queries | Geographic search |

### Data Management

| Feature | TypeSense | Supafolio |
|---------|-----------|-----------|
| **Schema Control** | Custom field definitions | ONIX-based structure |
| **Data Import** | JSONL, CSV, JSON import | ONIX file upload |
| **Real-time Updates** | Manual reindexing | Automatic daily sync |
| **Validation** | Schema validation | ONIX compliance |
| **Data Enrichment** | Manual enrichment | Built-in metadata features |

### Publishing Industry

| Feature | TypeSense | Supafolio |
|---------|-----------|-----------|
| **Industry Focus** | General-purpose | Book publishing specialized |
| **Standards Support** | None | ONIX 2.1/3.0 native |
| **Business Rules** | Custom implementation | Built-in pricing/rules |
| **Retailer Integration** | Manual setup | Pre-configured retailers |
| **Multi-currency** | Custom implementation | Built-in currency support |
| **SEO Features** | Manual optimization | Built-in SEO overrides |

## Use Case Recommendations

### Choose TypeSense When:

✅ **Large Datasets** (>100,000 books)  
✅ **High Search Volume** (>1,000 queries/day)  
✅ **Custom Ranking Required**  
✅ **Real-time Search Needed** (<100ms response)  
✅ **Data Privacy Concerns**  
✅ **Cost Predictability Important**  
✅ **Technical Team Available**  
✅ **Custom Schema Requirements**  

### Choose Supafolio When:

✅ **Small Publishers** (<10,000 books)  
✅ **Limited Technical Resources**  
✅ **Industry-Specific Features Needed**  
✅ **Quick Setup Required**  
✅ **Managed Service Preference**  
✅ **ONIX Data Integration Required**  
✅ **SEO/WCMS Integration Priority**  
✅ **Minimal DevOps Overhead**  

## Implementation Comparison

### Setup Complexity

#### TypeSense Setup
```bash
# 1. Install TypeSense
curl -O- https://dl.typesense.org/gpu-server/linux-amd64.tar.gz

# 2. Extract and start server
tar -xvf typesense-server-linux-amd64.tar.gz
cd typesense-server-linux-amd64
./typesense-server --data-dir /path/to/data --api-key=your-key --listen-port=8108

# 3. Import book data
./typesense-server import-books.jsonl

# 4. Configure plugin (WordPress)
define('TYPESENSE_API', true);
// Set typesense_api_key, typesense_host, typesense_catalog in WordPress admin
```

#### Supafolio Setup
```bash
# 1. Install plugin (WordPress)
wp plugin install supapress

# 2. Configure API key (WordPress admin)
# Settings → Supapress → API Key: your-credential-here

# 3. Plugin is ready
```

## Migration Considerations

### Data Structure Mapping

| TypeSense Field | Supafolio Field | Notes |
|---------------|-----------------|-------|
| `title` | `title` | Direct mapping |
| `authors[].contributor.name` | `contributors[].contributor.name` | Array to array |
| `publicationDate` | `date.date` | Timestamp to date object |
| `prices.USD.amount` | `prices[].amount` where `locale=USD` | Object to array |
| `categories` | `categories[].category.name` | Array to array mapping |
| `isbn13` | `isbn13` | Direct mapping |

### Response Format Transformation

#### TypeSense → Supafolio Mapping
```php
function supapress_map_search_ts_data($results) {
    $result = [];
    foreach ($results["hits"] as $item) {
        if (!isset($item['document'])) {
            continue;
        }
        $result[] = (object) $item['document'];
    }
    
    return (object) [
        "search" => $result
    ];
}
```

## Performance Comparison

### Response Time Analysis

| Operation | TypeSense | Supafolio |
|-----------|-----------|-----------|
| **Simple Search** | 5-50ms | 200-2000ms |
| **Complex Filter** | 10-100ms | 500-3000ms |
| **Faceted Search** | 20-150ms | 800-1500ms |
| **Bulk Lookup** | 50-200ms | 1000-5000ms |
| **Autocomplete** | 2-20ms | 100-500ms |

### Throughput Analysis

| Metric | TypeSense | Supafolio |
|----------|-----------|-----------|
| **Concurrent Users** | 10,000+ | 100-1,000+ |
| **Queries/Second** | 1,000+ | 100-500+ |
| **Document Size** | 1-2MB RAM per book | N/A |
| **Storage Efficiency** | RAM-based compression | Cloud-based optimization |

## Cost Analysis

### TypeSense Cost Breakdown
```yaml
Infrastructure:
  - Server: $50-200/month (depends on specs)
  - RAM: 64GB @ $800 = $51,200
  - Bandwidth: 100GB @ $50 = $6,000
  - DevOps: 0.25 FTE @ $80,000 = $20,000
Total Monthly: ~$77,200

Scaling:
  - Additional nodes: $50-200 each
  - Load balancer: $20-50/month
Total at 1M docs: ~$100,000/month initial + ~$20,000/month scaling
```

### Supafolio Cost Structure
```yaml
Per-Record Pricing:
  - <10,000 books: Custom pricing
  - 10,000-50,000: Standard tier pricing
  - 50,000-100,000: Enterprise tier pricing
  - 100,000+: Custom enterprise pricing

Estimated Monthly:
  - 25,000 books: ~$2,000-5,000/month
  - 100,000 books: ~$8,000-15,000/month
```

## Decision Matrix

### Quick Selection Guide

| Factor | Weight | Questions to Ask |
|---------|--------|-------------------|
| **Dataset Size** | 30% | How many books in catalog? |
| **Search Volume** | 25% | What's your daily query load? |
| **Response Time Requirement** | 20% | What's your acceptable search speed? |
| **Technical Team** | 15% | Who will maintain the system? |
| **Budget** | 20% | What's your monthly budget? |
| **Privacy Needs** | 10% | Any data compliance requirements? |

**Scoring Guide:**
- **0-25 points**: Supafolio recommended
- **26-50 points**: Hybrid approach considered
- **51-75 points**: TypeSense recommended  
- **76-100 points**: TypeSense strongly recommended

---

**Generated**: 2026-01-24  
**TypeSense Version**: v29.0  
**Supafolio Version**: v2.26.2