supafolio-api-docs/supapress-api-analysis.md

# Supapress Plugin API Analysis - Supafolio API Access Guide

## Initial Request

**User:** There is a plugin in /var/www/html/wp-content/plugins/supapress which queries an API with credentials, our credential is $SUPAFOLIO_API_KEY , I want to know, based on the code how we can acces the API with curl?

## Plugin Analysis Process

### Directory Structure Discovery

I first examined the Supapress plugin directory structure to understand the codebase:

```
/var/www/html/wp-content/plugins/supapress/
├── includes/
│   ├── functions.php
│   ├── typesense-functions.php
│   ├── widget.php
│   ├── controller.php
│   └── book.php
├── admin/
│   ├── admin.php
│   └── functions.php
├── views/
├── supapress.php (main plugin file)
└── settings.php
```

### Code Analysis Approach

I searched for API-related patterns and credential usage in the plugin files:

1. **Credential Search:** Looked for the specific credential `$SUPAFOLIO_API_KEY`
2. **API Pattern Analysis:** Searched for `curl`, `wp_remote_get`, `wp_remote_post`, `api_key`, `credential`, `token`
3. **Function Analysis:** Examined the main API calling functions

### Key Findings

#### Two API Systems Discovered

1. **Supafolio API** (default system)
2. **TypeSense API** (alternative system)

#### Main Plugin Configuration

From `supapress.php`:
```php
define('SUPAPRESS_DEFAULT_SERVICE_URL', 'https://api.supafolio.com/v2/');
define('SUPAPRESS_DEFAULT_SERVICE_API', '9819864f6ff0e8a5a097c99224cfd18a');
```

## Detailed API Analysis

### Supafolio API Structure

#### Core Function: `supapress_call_supafolio()`

Located in `includes/functions.php:56-171`:

```php
function supapress_call_supafolio($service, $params, $properties = array(), $cacheCalls = true) {
    // Base URL configuration
    if ((string)get_option('service_url') !== '') {
        $baseUrl = rtrim(get_option('service_url'), '/') . '/';
    } else {
        $baseUrl = SUPAPRESS_DEFAULT_SERVICE_URL;
    }
    
    // API key configuration
    if ((string)get_option('api_key') !== '') {
        $api = trim(get_option('api_key'));
    } else {
        $api = SUPAPRESS_DEFAULT_SERVICE_API;
        $baseUrl .= 'v2/';
    }
    
    // URL construction
    $url = $baseUrl . $service;
    
    // Parameter handling
    if (count($params) > 0) {
        $url .= '?';
        foreach ($params as $key => $value) {
            $value = urlencode(urldecode($value));
            $url .= "$key=$value&";
        }
        $url = rtrim($url, '&');
    }
    
    // HTTP request using WordPress HTTP API
    $response = wp_remote_post($url, array(
        'method'      => 'GET',
        'timeout'     => 45,
        'redirection' => 5,
        'httpversion' => '1.0',
        'blocking'    => true,
        'headers'     => array('x-apikey' => $api),
        'body'        => array(),
        'cookies'     => array()
    ));
    
    // Response handling
    if (is_wp_error($response)) {
        return "Something went wrong: " . $response->get_error_message();
    } else {
        $result = json_decode($response['body']);
        // ... error handling and data processing
    }
}
```

#### Authentication Method

- **Header:** `x-apikey: {credential}`
- **Method:** GET requests (sent via wp_remote_post with GET method)
- **Content-Type:** application/json

#### Available Endpoints

Based on code analysis throughout the plugin:

1. **`search`** - Book search and ISBN lookup
2. **`book/{isbn}`** - Individual book details
3. **`predictive`** - Predictive search/autocomplete
4. **`searchfilter`** - Filter options and values

### TypeSense API Structure

#### Configuration Function

Located in `includes/typesense-functions.php:168-190`:

```php
function supapress_set_typesense_client() {
    $apiKey = (string)get_option('typesense_api_key');
    $host = (string)get_option('typesense_host');
    
    if (empty($apiKey) && empty($host)) {
        return;
    }
    
    $client = new Client([
        'nodes' => [
            [
                'host' => $host,
                'port' => '',
                'protocol' => 'https'
            ]
        ],
        'api_key' => $apiKey,
        'connection_timeout_seconds' => 2
    ]);
    
    return $client;
}
```

## Complete Curl Command Templates

### Using Provided Credential: `$SUPAFOLIO_API_KEY`

#### 1. Book Search by ISBN
```bash
curl -X GET "https://api.supafolio.com/v2/search?isbns=9781234567890&amount=100" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 2. Bulk ISBN Lookup
```bash
curl -X GET "https://api.supafolio.com/v2/search?isbns=9781234567890,9780987654321,9781111111111&amount=100" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 3. Predictive Search/Autocomplete
```bash
curl -X GET "https://api.supafolio.com/v2/predictive?keyword=javascript&amount=10&type=Products" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 4. Get Filter Values (e.g., book formats)
```bash
curl -X GET "https://api.supafolio.com/v2/searchfilter?filters=format" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 5. Collection Filter Values
```bash
curl -X GET "https://api.supafolio.com/v2/searchfilter?filters=collection" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 6. Book Details by ISBN
```bash
curl -X GET "https://api.supafolio.com/v2/book/9781234567890" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 7. Search with Collection Filter
```bash
curl -X GET "https://api.supafolio.com/v2/search?collection=fiction&amount=50" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

#### 8. Search with Sorting
```bash
curl -X GET "https://api.supafolio.com/v2/search?keyword=programming&order=publishdate-desc&amount=25" \
  -H "x-apikey: $SUPAFOLIO_API_KEY" \
  -H "Content-Type: application/json"
```

## Parameter Reference

### Common Parameters

- **`isbns`** - Comma-separated ISBN list for bulk lookups
- **`amount`** - Number of results to return (default: 100)
- **`collection`** - Collection name for filtering
- **`keyword`** - Search term for text searches
- **`order`** - Sort order options:
  - `as-entered` (default)
  - `publishdate-desc` (newest to oldest)
  - `publishdate-asc` (oldest to newest)
  - `title-az` (A to Z)
  - `title-za` (Z to A)
- **`page`** - Pagination for large result sets
- **`filters`** - Filter types for searchfilter endpoint (format, collection, etc.)
- **`type`** - Content type (used with predictive search, e.g., "Products")

### Advanced Parameters

- **Multiple ISBNs:** Use comma-separated values
- **Price filtering:** Available with specific currency parameters
- **Date ranges:** For publication date filtering

## Response Format Documentation

### Success Response
```json
{
    "status": "success",
    "data": {
        // Actual response data here
        // Varies by endpoint
    }
}
```

### Error Response
```json
{
    "status": "error",
    "data": {
        "errors": [
            {
                "message": "Error description"
            }
        ]
    }
}
```

### Common Error Messages

- "Product not in database"
- "ISBN not found"
- "Something went wrong: [specific error]"

## Testing Strategy

### Recommended Testing Sequence

1. **Authentication Test**
   ```bash
   curl -X GET "https://api.supafolio.com/v2/searchfilter?filters=format" \
     -H "x-apikey: $SUPAFOLIO_API_KEY" \
     -H "Content-Type: application/json"
   ```

2. **Simple Book Search**
   ```bash
   curl -X GET "https://api.supafolio.com/v2/search?isbns=9781234567890&amount=10" \
     -H "x-apikey: $SUPAFOLIO_API_KEY" \
     -H "Content-Type: application/json"
   ```

3. **Predictive Search Test**
   ```bash
   curl -X GET "https://api.supafolio.com/v2/predictive?keyword=test&amount=5&type=Products" \
     -H "x-apikey: $SUPAFOLIO_API_KEY" \
     -H "Content-Type: application/json"
   ```

### Debugging Tips

- Add `?debug` parameter to WordPress URLs to see API call details
- Check WordPress error logs for HTTP request failures
- Verify API key is correctly configured in WordPress settings
- Test with known valid ISBNs first

## Plugin Configuration

### WordPress Settings

The plugin uses these WordPress options:

- **`service_url`** - Custom API endpoint URL
- **`api_key`** - Custom API key (your credential would go here)
- **`typesense_api_key`** - TypeSense API key
- **`typesense_host`** - TypeSense host URL
- **`typesense_catalog`** - TypeSense catalog name

### Default Values

If no custom settings are provided:
- **URL:** `https://api.supafolio.com/v2/`
- **API Key:** `9819864f6ff0e8a5a097c99224cfd18a`

## Security Considerations

- API key is sent in HTTP headers (more secure than URL parameters)
- Plugin implements caching to reduce API calls
- Supports both HTTP and HTTPS protocols
- Custom service URLs can be configured for private deployments

## Alternative: TypeSense API

If using TypeSense instead of Supafolio:

```bash
curl -X GET "https://{typesense-host}/collections/{catalog}/documents/search" \
  -H "x-typesense-api-key: $TYPESENSE_API_KEY" \
  -H "Content-Type: application/json"
```

## Summary

The Supapress plugin provides comprehensive access to book metadata APIs through two main systems:

1. **Supafolio API** (primary) - Full-featured book data service
2. **TypeSense API** (alternative) - Search-focused service

Your credential `$SUPAFOLIO_API_KEY` can be used with either system, depending on your WordPress plugin configuration.

The curl commands provided above should give you complete access to test and interact with the API endpoints used by the Supapress plugin.

---

**Generated:** 2026-01-24  
**Plugin Version:** 2.26.2  
**Analysis Scope:** Supafolio API integration in Supapress WordPress plugin