Class Reference

// Identity
$index->get_id(): int;
$index->get_slug(): string;
$index->get_name(): string;
$index->get_type(): string;

// Associated service & stored configuration
$index->get_service(): BaseService;
$index->get_index_config(): IndexConfig;

// Search
$index->search(string $query, array $params = []): IndexResponse|SearchResponse|ErrorResponse;

// Document operations (delegate to the service)
$index->sync_item(IIndexableObject $item): IndexResponse|SuccessResponse|ErrorResponse;
$index->delete_item(IIndexableObject $item): IndexResponse|SuccessResponse|ErrorResponse;
$index->count_items(): IndexResponse|ValueResponse|ErrorResponse;

// Index lifecycle (delegate to the service)
$index->check(): IndexResponse|SuccessResponse|ErrorResponse;   // does the index exist?
$index->touch(): IndexResponse|SuccessResponse|ErrorResponse;   // create if missing
$index->clear(): IndexResponse|SuccessResponse|ErrorResponse;   // delete all documents
$index->delete(): IndexResponse|SuccessResponse|ErrorResponse;  // delete the index
$index->push_settings(): IndexResponse|SuccessResponse|ErrorResponse;

// Rebuilding
$index->rebuild_index(int $page): void;                 // one batch page; page 1 recreates the index
$index->rebuild_index_specific(array $object_ids): void;
$index->get_candidate_batch_size(): int;

// Attribute whitelists shown in the admin UI (override for curated labels)
$index->get_available_searchable_attributes(): array;   // [['name' => ..., 'label' => ...], ...]
$index->get_available_filterable_attributes(): array;
$index->get_available_sortable_attributes(): array;
$index->required_filterable_attributes(): array;        // default: ['status'] — always kept filterable

// Sorting
$index->resolve_sort(string $sort_key): array;          // e.g. 'date' → ['created_at:desc']

// Stores the ServiceConfig as $this->details and calls init()
public function __construct(ServiceConfig $details);

$service->get_provider(): string;                 // e.g. 'meilisearch'
$service->get_settings(BaseIndex $index): array;  // build_settings() + filters
$service->get_setting_impacts(): array;           // setting key → 'reindex' | 'rebuild'

abstract class BaseObserver {
    protected BaseIndex $index;

    public function __construct(BaseIndex $index);

    // Returns the observed index
    public function get_index(): BaseIndex;

    // Must implement - register WordPress hooks
    abstract public function observe(): void;

    // Sync a raw item (e.g. WP_Post) to the index
    protected function sync_item($item): void;

    // Delete a raw item from the index
    protected function delete_item($item): void;

    // Delete all records for a post ID (handles content splits)
    protected function delete_post_records(int $post_id): void;

    // Public wrappers used by queue processing
    public function process_sync($item): void;
    public function process_delete($item): void;

    // Schedule sync/delete via the queue
    protected function queue_sync(string $item_type, $item_id): void;
    protected function queue_delete(string $item_type, $item_id): void;

    // Check if queue processing should be used
    protected function should_use_queue(): bool;
}

// Create index by its integer database ID (NOT an IndexConfig object)
$index = IndexFactory::create(int $id): BaseIndex;

// Get all supported index types (filterable via celersearch_supported_indices)
$types = IndexFactory::get_supported_indices(): array;

// Create a throwaway index bound to a service, for connection testing
$index = IndexFactory::create_for_testing(ServiceConfig $service_config): BaseIndex;

// Create service by its integer database ID
$service = ServiceFactory::create(int $id): BaseService;

// Create a service instance from an unsaved config (connection testing)
$service = ServiceFactory::create_for_testing(ServiceConfig|array $conf): BaseService;

// Get all supported providers (filterable via celersearch_supported_providers)
$providers = ProviderFactory::get_supported_providers(): array;

// Get a single provider definition by slug (e.g. 'meilisearch'), or null
$provider = ProviderFactory::get_provider(string $slug): ?array;

// Create observer for specific index
$observer = ObserverFactory::create_for_index(BaseIndex $index): ?BaseObserver;

// Create all observers for active indices
$observers = ObserverFactory::create_all(): array;

// All available area type descriptors (filterable via celersearch_area_types)
$types = SearchAreaFactory::get_available_types(): array;

// Single descriptor by type slug, or null
$type = SearchAreaFactory::get_type(string $type): ?array;

// Does a type exist?
SearchAreaFactory::type_exists(string $type): bool;

use CelerSearch\SearchAreas\SearchAreaRegistry;

add_action('celersearch_register_search_areas', function () {
    SearchAreaRegistry::register('my_custom_search', \MyPlugin\SearchAreas\MyCustomSearchArea::class);
});

// Available on every response
$response->is_error_response(): bool;

// Async task info (MeiliSearch operations are asynchronous)
$response->has_task(): bool;
$response->get_task_id(): ?string;
$response->get_task_object(): mixed;

$response = $index->search('query');

if ($response->is_error_response()) {
    error_log($response->get_error_message());
    return;
}

foreach ($response->get_hits() as $hit) {
    // ...
}

use CelerSearch\Builders\IndexResponseBuilder;

// A 2xx response_code builds (by method name):
//   'search'                                        → SearchResponse
//   'list_documents'                                → DocumentListResponse
//   'count_items' | 'get_document' | 'get_index_config' → ValueResponse
//   anything else                                   → SuccessResponse
// A non-2xx response_code always builds an ErrorResponse.

$response = (new IndexResponseBuilder('count_items'))
    ->response_code(200)
    ->response_body($raw)
    ->value(42)
    ->build();

$error = (new IndexResponseBuilder('sync_item'))
    ->response_code(500)
    ->error_message('Connection failed')
    ->build();