# Supafolio & TypeSense API Documentation

Complete API documentation for book metadata search services, extracted from the [Supapress WordPress plugin](https://wordpress.org/plugins/supapress/).

## Overview

This repository contains comprehensive documentation for two book metadata APIs:

| API | Type | Use Case |
|-----|------|----------|
| **Supafolio** | Managed service | Quick setup, ONIX support, minimal technical overhead |
| **TypeSense** | Self-hosted | Large datasets, custom ranking, data privacy, full control |

Documentation was extracted because the vendor (Supadu) did not provide adequate API documentation.

## Quick Start

### Prerequisites

- API credentials for your chosen service
- `curl` or any HTTP client
- (TypeSense only) A running TypeSense instance

### Configuration

1. Copy the template and add your credentials:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your actual API keys:
   ```env
   SUPAFOLIO_API_KEY=your_supafolio_key_here
   TYPESENSE_API_KEY=your_typesense_key_here
   ```

3. Source the environment file before running commands:
   ```bash
   source .env
   ```

### Test Supafolio API

```bash
source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/search?keyword=javascript&amount=10"
```

### Test TypeSense API

```bash
source .env
curl -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  "https://your-typesense-host/collections/books/documents/search?q=javascript&query_by=title,description"
```

## Documentation Files

| File | Description |
|------|-------------|
| [supafolio-api-complete.md](supafolio-api-complete.md) | Full Supafolio API reference with endpoints, parameters, and response schemas |
| [typesense-api-complete.md](typesense-api-complete.md) | Full TypeSense API reference for self-hosted search |
| [api-comparison-guide.md](api-comparison-guide.md) | Side-by-side comparison with decision matrix and cost analysis |
| [supapress-api-analysis.md](supapress-api-analysis.md) | Original analysis of Supapress plugin integration |

## Choosing an API

### Use Supafolio When:

- Small to medium catalog (< 50,000 books)
- Limited technical resources
- Need ONIX data integration
- Quick setup required
- Managed service preferred

### Use TypeSense When:

- Large catalog (> 50,000 books)
- High search volume
- Custom ranking/faceting needed
- Data privacy/compliance required
- Technical team available for maintenance

See [api-comparison-guide.md](api-comparison-guide.md) for detailed comparison and scoring matrix.

## Common Operations

### Book Search

```bash
source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/search?keyword=programming&amount=20"
```

### ISBN Lookup

```bash
source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321"
```

### Predictive Search

```bash
source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/predictive?keyword=javascrip&amount=5"
```

### Get Filter Values

```bash
source .env
curl -H "x-apikey: $SUPAFOLIO_API_KEY" \
  "https://api.supafolio.com/v2/searchfilter?filters=format,collection,publisher"
```

## Source

- Extracted from: wordpress.org/plugins/supapress/
- Generated: 2026-01-24
- Supafolio API Version: v2.26.2
- TypeSense API Version: v29.0

## License

See [LICENSE](LICENSE) file for details.