#!/usr/local/cpanel/3rdparty/bin/perl

#                                      Copyright 2025 WebPros International, LLC
#                                                           All rights reserved.
# copyright@cpanel.net                                         http://cpanel.net
# This code is subject to the cPanel license. Unauthorized copying is prohibited.

package Cpanel::Exception::Sitejet::API;

use cPstrict;

# BEGIN Augment generated code block
# Sitejet API exception class following cPanel exception patterns
# Subclasses Cpanel::Exception to provide structured error handling
# for Sitejet API operations with localized error messages
# END Augment generated code block

use parent qw( Cpanel::Exception );

use Cpanel::Imports;

our $VERSION = '1.00';

# Exception definitions with message templates and parameter lists
our %EXCEPTION_DEFINITIONS = (

    # Account management errors
    'account_exists' => {
        message => translatable('Sitejet account already exists for user “[_1]”.'),
        params  => ['user'],
    },
    'account_creation_failed' => {
        message => translatable('Failed to create a Sitejet account associated with your cPanel account.'),
        params  => [],
    },
    'token_not_found' => {
        message => translatable('No Sitejet API token found for user “[_1]”.'),
        params  => ['user'],
    },

    # Website management errors
    'website_id_missing' => {
        message => translatable('Unable to obtain websiteId for domain “[_1]”.'),
        params  => ['domain'],
    },
    'website_assets_failed' => {
        message => translatable('Failed to [_1] website assets for “[_2]”.'),
        params  => [ 'operation', 'domain' ],
    },
    'website_not_found' => {
        message => translatable('Website not found for domain “[_1]”.'),
        params  => ['domain'],
    },

    # API communication errors
    'request_failed' => {
        message => translatable('The API call to “[_1]” failed with error code “[_2]” and the following response: “[_3]”.'),
        params  => [ 'endpoint', 'status_code', 'response' ],
    },

    # Preview and SSO errors
    'preview_failed' => {
        message => translatable('Failed to get preview data for domain “[_1]”.'),
        params  => ['domain'],
    },
    'sso_failed' => {
        message => translatable('Failed to get SSO link for domain “[_1]”.'),
        params  => ['domain'],
    },

    # Template and website management errors
    'templates_unavailable' => {
        message => translatable('Unable to access Sitejet templates. Try again later.'),
        params  => [],
    },
    'template_selection_failed' => {
        message => translatable('Unable to set Sitejet template for “[_1]”.'),
        params  => ['domain'],
    },

    # Access and permission errors
    'migration_in_progress' => {
        message => translatable('The publication process is not available during website migration. Try again later or contact your hosting provider for assistance.'),
        params  => [],
    },
    'insufficient_permissions' => {
        message => translatable('The Team User “[_1]” cannot access Sitejet with limited or no roles.'),
        params  => ['team_user'],
    },
    'domain_not_owned' => {
        message => translatable('The “[_1]” domain is not owned by this account.'),
        params  => ['domain'],
    },
    'domains_fetch_failed' => {
        message => translatable('Unable to fetch all the domains.'),
        params  => [],
    },
);

=encoding utf-8

=head1 NAME

Cpanel::Exception::Sitejet::API - Exception class for Sitejet API operations

=head1 DESCRIPTION

This module provides a structured exception class for Sitejet API operations,
following the cPanel exception pattern. It subclasses Cpanel::Exception and
provides localized error messages for various Sitejet API failure scenarios.

=head1 SYNOPSIS

    # Throw a Sitejet API exception
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'account_exists',
        user => $username
    });

    # Throw an API request failure exception
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'request_failed',
        endpoint => '/website',
        status_code => 404,
        response => 'Not Found'
    });

=head1 METHODS

=head2 translatable

Returns the string. Provides the string to the locale tool. ## no extract maketext

=cut

sub translatable ($string) { return $string; }    ## no extract maketext

=head2 _default_phrase()

Returns the default localized phrase for this exception based on the error_type parameter.

=cut

sub _default_phrase {
    my ($self) = @_;

    my $error_type = $self->get('error_type') || 'unknown';

    # Look up the exception definition
    my $definition = $EXCEPTION_DEFINITIONS{$error_type};

    if ( !$definition ) {

        # Fallback for unknown error types
        return locale()->maketext(
            'Sitejet API error: [_1]',
            $error_type
        );
    }

    # Build parameter list from the definition
    my @params = map { $self->get($_) || 'unknown' } @{ $definition->{params} };

    # Create and return the localized string
    return locale()->makevar( $definition->{message}, @params );
}

=head1 USAGE EXAMPLES

=head2 Account Management

    # Account already exists
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'account_exists',
        user => $username
    });

    # Account creation failed
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'account_creation_failed'
    });

    # API token not found
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'token_not_found',
        user => $username
    });

=head2 Website Management

    # Website ID missing
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'website_id_missing',
        domain => $domain
    });

    # Website assets operation failed
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'website_assets_failed',
        operation => 'get',
        domain => $domain
    });

=head2 API Communication

    # API request failed
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'request_failed',
        endpoint => '/website',
        status_code => 404,
        response => 'Not Found'
    });

=head1 MIGRATION FROM EXISTING EXCEPTIONS

Old pattern:
    die Cpanel::Exception::create('InvalidParameter', 'Unable to obtain websiteId for domain “[_1]”.', [$domain]);

New pattern:
    die Cpanel::Exception::create('Sitejet::API', {
        error_type => 'website_id_missing',
        domain => $domain
    });

=head1 SEE ALSO

L<Cpanel::Exception>, L<Cpanel::Sitejet::Connector>

=head1 AUTHOR

cPanel, L.L.C.

=head1 COPYRIGHT

Copyright (c) 2025, cPanel, L.L.C.
All rights reserved.
http://cpanel.net

This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See L<perlartistic>.

=cut

1;
