Front API

FrontendApi provides a secure interface for interacting with the Redux store and application functionality. The system includes authorization to protect mutating operations and prevents accidental state mutations.

Key Features

• Full backward compatibility — existing code continues to work without changes
• Single creation method — one createFrontApi() with different behavior depending on API key
• Protection from accidental mutations — state is returned as copies for unauthorized users
• Authorization via API keys — mutating operations require a valid API key
• Intuitive behavior — valid key = full access, invalid = read-only
• Simple integration — minimal changes to existing code

Usage

Secure API with Valid Key (full access)

// Create secure API with valid key
const api = await window.CPB.createFrontApi('<your-shop-key>');

// All operations are available
const state = api.State; // Original state
api.nextView(); // ✅ Works
api.updateOptions({...}); // ✅ Works

Secure API without Valid Key (read-only)

// Create secure API with invalid or missing key
const api = await window.CPB.createFrontApi('invalid-key');
// or (without key)
const api = await window.CPB.createFrontApi();

// Reading is available (returns state copy)
const state = api.State; // Copy, not original
console.log('State:', state);

// State mutations don't affect the real store
state.Product.panels[0].price = '999'; // Only copy is changed

// Mutating operations are blocked
try {
    api.updateOptions(); // ❌ Error: authorization required
} catch (error) {
    console.log('Access denied:', error.message);
}

Checking Authorization Status

const api = await window.CPB.createFrontApi('<your-shop-key>');

// Check status
const status = api.getAuthStatus();
console.log('Authorized:', status.isAuthorized);
console.log('API key:', status.apiKey); // shows only last 4 characters

// Reset authorization
api.logout();

Available Methods

Read-only Methods (no authorization required)

• State (getter) — get Redux state
• checkLogic(entity) — check logical rules
• getAuthStatus() — authorization status information
• getAvailableMethods() — list of available methods
• authorize(apiKey) — authorization
• logout() — reset authorization

Actions (no need for authorization)

• changeViewByName(viewName) — change view by name
• changeViewByIndex(index) — change view by index
• nextView() — switch to next view
• prevView() — switch to previous view
• changeLanguage(language) — change language

Actions (require authorization)

• updateOptions(params) — update product options
• dispatch(action) — dispatch Redux action

Usage Examples (actions)

Updating Product Options

const api = await window.CPB.createFrontApi('your-api-key');

await api.updateOptions({
    panel: {
        id: 'panel1',
        name: 'Main Panel'
    },
    category: {
        id: 'category1',
        options: [...]
    },
    options: [
        {
            id: 'option1',
            option: {
                data: {
                    value: 'new-value',
                    label: 'New Label'
                }
            }
        }
    ]
});

View Management

const api = await window.CPB.createFrontApi('your-api-key');

// Change view by name
api.changeViewByName('back');

// Change view by index
api.changeViewByIndex(1);

// Navigate through views
api.nextView();
api.prevView();

Other actions

const api = await window.CPB.createFrontApi('your-api-key');

// Change language by ISO format name
api.changeLanguage('fr')

API Creation Methods

// 1. Secure API with valid key (full access)
const secureApi = await window.CPB.createFrontApi('<your-shop-key>');

// 2. Secure API with invalid key (read-only)
const readOnlyApi = await window.CPB.createFrontApi('invalid-key');

// 3. Secure API without key (read-only)
const readOnlyApi2 = await window.CPB.createFrontApi();

How createFrontApi Works

The single createFrontApi() method behaves differently depending on the passed API key:

// 1. With valid API key - full access
const fullAccessApi = await window.CPB.createFrontApi('<your-shop-key>');
fullAccessApi.updateOptions(); // ✅ Works
const originalState = fullAccessApi.State; // Original state
fullAccessApi.dispatch(); // ✅ Works

// 2. With invalid API key - read-only
const readOnlyApi = await window.CPB.createFrontApi('invalid-key');
const stateCopy = readOnlyApi.State; // State copy

// Copy mutations don't affect the real store
stateCopy.Product.panels[0].price = '999'; // Safe

// Mutating methods are blocked
try {
    readOnlyApi.updateOptions(); // ❌ Error
} catch (error) {
    console.log('Access denied - invalid API key');
}

// 3. Without API key - read-only
const readOnlyApi2 = await window.CPB.createFrontApi();
const stateCopy = readOnlyApi2.State; // State copy

Security

• Single creation method — one createFrontApi() with intuitive behavior
• Valid key = full access — simple and clear logic
• Invalid key = read-only — protection from accidental mutations
• API keys are validated through the internal system
• Caching of validated keys for performance
• Deep copying of state to prevent mutations in read-only mode
• Logging of all authorization attempts for security monitoring

Error Handling

try {
    const api = await window.CPB.createFrontApi(); // no key → read-only

    // Attempt to perform mutating operation without authorization
    api.updateOptions({...});
} catch (error) {
    console.error('Error:', error.message);
    // Error: [FrontendApi] Access denied. Use authorize() method...
}