<?php

namespace App\Services\Graph;

interface GraphClientInterface
{
    /**
     * List policies of a given type.
     *
     * Supported list query options (sanitized against the contract allowlists for the policy type):
     * - `select`: `string|string[]` Optional `$select` fields. Accepts comma-separated string or list of fields.
     * - `expand`: `string|string[]` Optional `$expand` expansions. Accepts comma-separated string or list of tokens.
     *   String input is split on top-level commas only (commas inside balanced parentheses are not separators).
     * - `filter`: `string` Optional `$filter`.
     * - `top`: `int` Optional `$top`.
     * - `platform`: `string` Optional platform filter (contract-specific).
     *
     * ManagedEnvironment/auth context options (typically resolved by `MicrosoftGraphOptionsResolver`):
     * - `tenant`, `client_id`, `client_secret`, `scope`, `token_url`, `access_token`, `client_request_id`
     *
     * @param  string  $policyType  Graph policy type identifier
     * @param  array{select?: string|string[], expand?: string|string[], filter?: string, top?: int, platform?: string, client_request_id?: string, tenant?: string, client_id?: string, client_secret?: string, scope?: string|string[], token_url?: string, access_token?: string}  $options
     */
    public function listPolicies(string $policyType, array $options = []): GraphResponse;

    /**
     * Fetch a single policy payload by type and identifier.
     */
    public function getPolicy(string $policyType, string $policyId, array $options = []): GraphResponse;

    /**
     * Fetch basic organization metadata for connectivity validation.
     */
    public function getOrganization(array $options = []): GraphResponse;

    /**
     * Apply or restore a policy payload.
     */
    public function applyPolicy(string $policyType, string $policyId, array $payload, array $options = []): GraphResponse;

    /**
     * Get granted OAuth2 permissions for the service principal.
     */
    public function getServicePrincipalPermissions(array $options = []): GraphResponse;

    /**
     * Execute an arbitrary Graph request (used for specialized operations like RBAC setup).
     *
     * Supported options: `query`, `json`, `tenant`, `client_id`, `client_secret`, `scope`, `token_url`, `access_token`.
     */
    public function request(string $method, string $path, array $options = []): GraphResponse;
}
