<?php

namespace MintyPHP\App\Module\Contracts;

/**
 * Provides search resources contributed by a module.
 *
 * Each provider returns a list of search resources (with SQL for count/preview/result),
 * maps result rows to display items, and provides list URLs for deep-linking.
 */
interface SearchResourceProvider
{
    /**
     * Return search resource definitions.
     *
     * Supported SQL placeholders (replaced before parameter binding):
     * - `{{tenantFilter}}` — replaced with a tenant-scope WHERE clause (or empty string)
     * - `{{userId}}`       — replaced with the current user's ID (integer, safe for inline SQL)
     *
     * All remaining `?` placeholders are bound to the LIKE search term.
     * The last `?` in preview_sql is reserved for the preview limit.
     *
     * @return array<string, array{
     *     label: string,
     *     permission: string,
     *     count_sql: string,
     *     preview_sql: string,
     *     result_sql: string,
     *     tenant_filter?: string
     * }>
     */
    public function resources(): array;

    /**
     * Map a raw result row to a display-ready item.
     *
     * @param array<string, mixed> $row
     * @return array{title: string, subtitle?: string, url: string, icon?: string}|null
     */
    public function mapResultItem(string $resourceKey, array $row): ?array;

    /**
     * Return the list URL for the given resource key and encoded search term.
     */
    public function listUrl(string $resourceKey, string $encodedSearch): string;
}