<?php

namespace Maestro\Core\DataTables;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Http\Request;

/**
 * Contract for a server-driven DataTable resource.
 * Each resource defines its base query, columns, row transformation, and authorization.
 */
interface DataTableResource
{
    /**
     * Unique key for this resource (used in URL: /api/datatables/{resourceKey}).
     */
    public function key(): string;

    /**
     * Authorization and scoping hook. Must allow access or throw \Illuminate\Auth\Access\AuthorizationException.
     * Called by the controller before baseQuery(); use for permission checks and tenant/user scoping decisions.
     */
    public function authorize(Request $request): void;

    /**
     * Base Eloquent query for the table. Filtering/sort/pagination will be applied on top in B2/B3.
     * Apply tenant/user scoping here (e.g. ->where('user_id', $request->user()->id) or ->tenant($tenantId)).
     */
    public function baseQuery(Request $request): Builder;

    /**
     * Column definitions in the canonical schema (whitelist for sort/filter/search in B3).
     * Each item must be an associative array with:
     *   - key (string): frontend column key, unique within resource
     *   - expr (string): DB-safe expression, used only via query builder (no raw concat)
     *   - type (string): text|number|date|enum|boolean
     *   - sortable (bool)
     *   - searchable (bool)
     *   - filterable (bool)
     *   - filterMode (string): contains|equals|date_equals
     *
     * @return array<int, array{key: string, expr: string, type: string, sortable: bool, searchable: bool, filterable: bool, filterMode: string}>
     */
    public function columns(): array;

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