<?php

declare(strict_types=1);

namespace Maestro\Core\DataTables;

use Illuminate\Auth\Access\AuthorizationException;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Http\Request;

/**
 * Contract for a server-driven DataTable resource.
 */
interface DataTableResource
{
    /**
     * Unique key for this resource (URL: /api/datatables/{resourceKey}).
     */
    public function key(): string;

    /**
     * Authorization hook; throw {@see AuthorizationException} when forbidden.
     */
    public function authorize(Request $request): void;

    /**
     * Base query for the table (tenant scoping belongs here).
     */
    public function baseQuery(Request $request): Builder;

    /**
     * Column whitelist for filters, search, sort, export.
     *
     * @return array<int, array<string, mixed>>
     */
    public function columns(): array;

    /**
     * Transform a single model to a row for JSON/CSV.
     *
     * @return array<string, mixed>
     */
    public function transformRow(object $model): array;
}
