<?php

declare(strict_types=1);

namespace App\Helpers;

use App\Data\ConnectedApp\ConnectedAppData;
use App\Enums\ConnectedAppPermissonEnum;

class AppPermission
{
    /**
     * The standard scope name for connected app permissions.
     */
    public const SCOPE = 'app';

    /**
     * Generates the standard permission string following the scope:resource:action convention.
     * Format: app:{slug}:{action}
     *
     * @param  ConnectedAppPermissonEnum  $permission  The action to perform (e.g., 'use')
     * @param  string|ConnectedAppData  $app  The connected app object or its slug
     *
     * @return string The formatted permission name
     */
    public static function name(ConnectedAppPermissonEnum $permission, string|ConnectedAppData $app): string
    {
        $slug = is_string($app) ? $app : $app->slug;

        return sprintf('%s:%s:%s', self::SCOPE, $slug, $permission->value);
    }

    /**
     * Parses the permission string to extract the ConnectedAppPermissonEnum type (action).
     *
     * @param  string  $permissionName  The constructed permission name
     *
     * @return ?ConnectedAppPermissonEnum The matching enum or null
     */
    public static function type(string $permissionName): ?ConnectedAppPermissonEnum
    {
        $parts = explode(':', $permissionName);

        if (3 === count($parts) && self::SCOPE === $parts[0]) {
            return ConnectedAppPermissonEnum::tryFrom($parts[2]);
        }

        return null;
    }

    /**
     * Parses the permission string to extract the connected app slug (resource).
     *
     * @param  string  $permissionName  The constructed permission name
     *
     * @return ?string The app slug or null
     */
    public static function slug(string $permissionName): ?string
    {
        $parts = explode(':', $permissionName);

        if (3 === count($parts) && self::SCOPE === $parts[0]) {
            return $parts[1];
        }

        return null;
    }
}