@magentrix-corp/magentrix-cli 1.3.16 → 1.3.17

package/utils/magentrix/api/assets.js

@@ -1,220 +1,220 @@
-import { fetchMagentrix } from "../fetch.js"
-import { createWriteStream, readFileSync } from "node:fs";
-import { pipeline } from "node:stream/promises";
-import { Readable } from "node:stream";
-import { Blob, File } from "node:buffer";
-import fsPath from 'path';
-
-async function fileToFileObj(fp, type = "application/octet-stream") {
-    let buf = readFileSync(fp);
-
-    // If file is empty, inject a single space (or any character)
-    if (!buf || buf.length === 0) {
-        buf = Buffer.from(" "); // could also use Buffer.from("x") or Buffer.alloc(1)
-    }
-
-    return new File([buf], fsPath.basename(fp), { type });
-}
-
-export const listAssets = async (instanceUrl, token, path) => {
-    if (!instanceUrl || !token) {
-        throw new Error('Missing required Magentrix instanceUrl or token');
-    }
-
-    let reqPath = `/api/3.0/staticassets`;
-
-    if (path) {
-        reqPath += `?path=${encodeURIComponent(path)}`
-    }
-
-    const response = await fetchMagentrix({
-        instanceUrl,
-        token,
-        path: reqPath,
-        method: "GET",
-        returnErrorObject: true
-    });
-
-    return response;
-}
-
-export const uploadAsset = async (instanceUrl, token, targetPath, uploadPaths = []) => {
-    if (!instanceUrl || !token) {
-        throw new Error('Missing required Magentrix instanceUrl or token');
-    }
-
-    let reqPath = `/api/3.0/staticassets`;
-
-    if (targetPath) {
-        reqPath += `?path=${targetPath}`
-    }
-
-    const formData = new FormData();
-    for (const fp of uploadPaths) {
-        formData.append("files", await fileToFileObj(fp));
-    }
-
-    const response = await fetchMagentrix({
-        instanceUrl,
-        token,
-        path: reqPath,
-        ignoreContentType: true,
-        // headers: {
-        //     'Content-Type': "multipart/form-data"
-        // },
-        body: formData,
-        method: "POST",
-        returnErrorObject: true
-    });
-
-    return response;
-}
-
-// Name = asset names (including folders)
-// Path = path to assets
-export const deleteAsset = async (instanceUrl, token, path = '/contents/assets', names = []) => {
-    if (!instanceUrl || !token) {
-        throw new Error('Missing required Magentrix instanceUrl or token');
-    }
-
-    if (!path) throw new Error("Path is required when deleting assets.");
-    if (!Array.isArray(names) || names?.length === 0) throw new Error("At least one file name is required when deleting static assets.");
-
-    // Batch deletes dynamically to avoid URL length limits
-    // Most servers/proxies have a 2048-8192 character limit for URLs
-    // We use 2000 as a safe limit to account for other URL components
-    const MAX_URL_LENGTH = 2000;
-    const results = [];
-
-    // Calculate base URL length (without file names)
-    const basePath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=`;
-    const baseLength = instanceUrl.length + basePath.length;
-
-    let currentBatch = [];
-    let currentUrlLength = baseLength;
-
-    for (const name of names) {
-        // Calculate the additional length this file would add
-        const encodedName = encodeURIComponent(name);
-        const additionalLength = encodedName.length + (currentBatch.length > 0 ? 1 : 0); // +1 for comma
-
-        // Check if adding this file would exceed the URL limit
-        if (currentUrlLength + additionalLength > MAX_URL_LENGTH && currentBatch.length > 0) {
-            // Execute the current batch
-            const reqPath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=${currentBatch.map(n => encodeURIComponent(n)).join(",")}`;
-            const response = await fetchMagentrix({
-                instanceUrl,
-                token,
-                path: reqPath,
-                method: "DELETE",
-                returnErrorObject: true
-            });
-            results.push(response);
-
-            // Start new batch
-            currentBatch = [name];
-            currentUrlLength = baseLength + encodedName.length;
-        } else {
-            // Add to current batch
-            currentBatch.push(name);
-            currentUrlLength += additionalLength;
-        }
-    }
-
-    // Execute the last batch if it has files
-    if (currentBatch.length > 0) {
-        const reqPath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=${currentBatch.map(n => encodeURIComponent(n)).join(",")}`;
-        const response = await fetchMagentrix({
-            instanceUrl,
-            token,
-            path: reqPath,
-            method: "DELETE",
-            returnErrorObject: true
-        });
-        results.push(response);
-    }
-
-    // Return the last response, or combine all responses if needed
-    // For now, return the last one since deleteAsset is typically called with single files
-    return results[results.length - 1];
-}
-
-export const createFolder = async (instanceUrl, token, path = '/contents/assets', name) => {
-    if (!instanceUrl || !token) {
-        throw new Error('Missing required Magentrix instanceUrl or token');
-    }
-
-    if (!name) throw new Error("Folder name is required when creating a folder.");
-
-    let reqPath = `/api/3.0/staticassets/folder?path=${encodeURIComponent(path)}&name=${encodeURIComponent(name)}`;
-
-    const response = await fetchMagentrix({
-        instanceUrl,
-        token,
-        path: reqPath,
-        method: "POST",
-        returnErrorObject: true
-    });
-
-    return response;
-}
-
-/**
- * Download multiple static assets as a ZIP.
- * @param {object} opts
- * @param {string} opts.baseUrl - e.g. "https://your-app.com"
- * @param {string} opts.token   - Bearer token
- * @param {string} opts.path    - e.g. "/contents/assets/images"
- * @param {string[]} opts.names - e.g. ["logo.png","banner.jpg"]
- * @param {string} [opts.outFile] - Optional explicit output filename
- */
-export async function downloadAssetsZip({ baseUrl, token, path, names, outFile }) {
-    if (!Array.isArray(names) || names.length === 0) {
-        throw new Error("names must be a non-empty string[]");
-    }
-
-    const url = new URL("/api/3.0/staticassets/download", baseUrl);
-    if (path) url.searchParams.set("path", path);
-    url.searchParams.set('download-format', 'zip'); // Ensure even one file gets downloaded as a zip
-    url.searchParams.set("names", names.join(",")); // API expects comma-separated names
-
-    const res = await fetch(url, {
-        method: "GET",
-        headers: { Authorization: `Bearer ${token}` },
-    });
-
-    if (!res.ok) {
-        // Try to surface server error body if JSON
-        let detail = "";
-        try {
-            const data = await res.json();
-            detail = data?.message || JSON.stringify(data);
-        } catch {
-            /* ignore */
-        }
-
-        // Create a more informative error message
-        const errorInfo = [
-            `Download failed (${res.status}): ${detail || res.statusText}`,
-            `Path: ${path || '(root)'}`,
-            `Files requested: ${names.join(', ')}`,
-            `URL: ${url.toString()}`
-        ].join('\n');
-
-        throw new Error(errorInfo);
-    }
-
-    // Determine filename: use header if present, else fallback
-    const cd = res.headers.get("content-disposition") || "";
-    const match = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(cd);
-    const filename = outFile || (match ? decodeURIComponent(match[1]) : "assets.zip");
-
-    // Stream to disk (no buffering whole file)
-    const fileStream = createWriteStream(filename);
-    const body = res.body; // ReadableStream (web)
-    // Convert web stream -> node stream for pipeline
-    const nodeReadable = Readable.fromWeb ? Readable.fromWeb(body) : body;
-
-    await pipeline(nodeReadable, fileStream);
-    return filename;
-}
+import { fetchMagentrix } from "../fetch.js"
+import { createWriteStream, readFileSync } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import { Readable } from "node:stream";
+import { Blob, File } from "node:buffer";
+import fsPath from 'path';
+
+async function fileToFileObj(fp, type = "application/octet-stream") {
+    let buf = readFileSync(fp);
+
+    // If file is empty, inject a single space (or any character)
+    if (!buf || buf.length === 0) {
+        buf = Buffer.from(" "); // could also use Buffer.from("x") or Buffer.alloc(1)
+    }
+
+    return new File([buf], fsPath.basename(fp), { type });
+}
+
+export const listAssets = async (instanceUrl, token, path) => {
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+
+    let reqPath = `/api/3.0/staticassets`;
+
+    if (path) {
+        reqPath += `?path=${encodeURIComponent(path)}`
+    }
+
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: reqPath,
+        method: "GET",
+        returnErrorObject: true
+    });
+
+    return response;
+}
+
+export const uploadAsset = async (instanceUrl, token, targetPath, uploadPaths = []) => {
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+
+    let reqPath = `/api/3.0/staticassets`;
+
+    if (targetPath) {
+        reqPath += `?path=${targetPath}`
+    }
+
+    const formData = new FormData();
+    for (const fp of uploadPaths) {
+        formData.append("files", await fileToFileObj(fp));
+    }
+
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: reqPath,
+        ignoreContentType: true,
+        // headers: {
+        //     'Content-Type': "multipart/form-data"
+        // },
+        body: formData,
+        method: "POST",
+        returnErrorObject: true
+    });
+
+    return response;
+}
+
+// Name = asset names (including folders)
+// Path = path to assets
+export const deleteAsset = async (instanceUrl, token, path = '/contents/assets', names = []) => {
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+
+    if (!path) throw new Error("Path is required when deleting assets.");
+    if (!Array.isArray(names) || names?.length === 0) throw new Error("At least one file name is required when deleting static assets.");
+
+    // Batch deletes dynamically to avoid URL length limits
+    // Most servers/proxies have a 2048-8192 character limit for URLs
+    // We use 2000 as a safe limit to account for other URL components
+    const MAX_URL_LENGTH = 2000;
+    const results = [];
+
+    // Calculate base URL length (without file names)
+    const basePath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=`;
+    const baseLength = instanceUrl.length + basePath.length;
+
+    let currentBatch = [];
+    let currentUrlLength = baseLength;
+
+    for (const name of names) {
+        // Calculate the additional length this file would add
+        const encodedName = encodeURIComponent(name);
+        const additionalLength = encodedName.length + (currentBatch.length > 0 ? 1 : 0); // +1 for comma
+
+        // Check if adding this file would exceed the URL limit
+        if (currentUrlLength + additionalLength > MAX_URL_LENGTH && currentBatch.length > 0) {
+            // Execute the current batch
+            const reqPath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=${currentBatch.map(n => encodeURIComponent(n)).join(",")}`;
+            const response = await fetchMagentrix({
+                instanceUrl,
+                token,
+                path: reqPath,
+                method: "DELETE",
+                returnErrorObject: true
+            });
+            results.push(response);
+
+            // Start new batch
+            currentBatch = [name];
+            currentUrlLength = baseLength + encodedName.length;
+        } else {
+            // Add to current batch
+            currentBatch.push(name);
+            currentUrlLength += additionalLength;
+        }
+    }
+
+    // Execute the last batch if it has files
+    if (currentBatch.length > 0) {
+        const reqPath = `/api/3.0/staticassets?path=${encodeURIComponent(path)}&names=${currentBatch.map(n => encodeURIComponent(n)).join(",")}`;
+        const response = await fetchMagentrix({
+            instanceUrl,
+            token,
+            path: reqPath,
+            method: "DELETE",
+            returnErrorObject: true
+        });
+        results.push(response);
+    }
+
+    // Return the last response, or combine all responses if needed
+    // For now, return the last one since deleteAsset is typically called with single files
+    return results[results.length - 1];
+}
+
+export const createFolder = async (instanceUrl, token, path = '/contents/assets', name) => {
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+
+    if (!name) throw new Error("Folder name is required when creating a folder.");
+
+    let reqPath = `/api/3.0/staticassets/folder?path=${encodeURIComponent(path)}&name=${encodeURIComponent(name)}`;
+
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: reqPath,
+        method: "POST",
+        returnErrorObject: true
+    });
+
+    return response;
+}
+
+/**
+ * Download multiple static assets as a ZIP.
+ * @param {object} opts
+ * @param {string} opts.baseUrl - e.g. "https://your-app.com"
+ * @param {string} opts.token   - Bearer token
+ * @param {string} opts.path    - e.g. "/contents/assets/images"
+ * @param {string[]} opts.names - e.g. ["logo.png","banner.jpg"]
+ * @param {string} [opts.outFile] - Optional explicit output filename
+ */
+export async function downloadAssetsZip({ baseUrl, token, path, names, outFile }) {
+    if (!Array.isArray(names) || names.length === 0) {
+        throw new Error("names must be a non-empty string[]");
+    }
+
+    const url = new URL("/api/3.0/staticassets/download", baseUrl);
+    if (path) url.searchParams.set("path", path);
+    url.searchParams.set('download-format', 'zip'); // Ensure even one file gets downloaded as a zip
+    url.searchParams.set("names", names.join(",")); // API expects comma-separated names
+
+    const res = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!res.ok) {
+        // Try to surface server error body if JSON
+        let detail = "";
+        try {
+            const data = await res.json();
+            detail = data?.message || JSON.stringify(data);
+        } catch {
+            /* ignore */
+        }
+
+        // Create a more informative error message
+        const errorInfo = [
+            `Download failed (${res.status}): ${detail || res.statusText}`,
+            `Path: ${path || '(root)'}`,
+            `Files requested: ${names.join(', ')}`,
+            `URL: ${url.toString()}`
+        ].join('\n');
+
+        throw new Error(errorInfo);
+    }
+
+    // Determine filename: use header if present, else fallback
+    const cd = res.headers.get("content-disposition") || "";
+    const match = /filename\*?=(?:UTF-8'')?["']?([^"';]+)["']?/i.exec(cd);
+    const filename = outFile || (match ? decodeURIComponent(match[1]) : "assets.zip");
+
+    // Stream to disk (no buffering whole file)
+    const fileStream = createWriteStream(filename);
+    const body = res.body; // ReadableStream (web)
+    // Convert web stream -> node stream for pipeline
+    const nodeReadable = Readable.fromWeb ? Readable.fromWeb(body) : body;
+
+    await pipeline(nodeReadable, fileStream);
+    return filename;
+}

package/utils/magentrix/api/auth.js

@@ -1,107 +1,107 @@
-import { fetchMagentrix } from "../fetch.js";
-import chalk from "chalk";
-import debug from '../../debug.js';
-
-/**
- * Authenticates with Magentrix and retrieves an access token using the API key as a refresh token.
- *
- * @async
- * @param {string} apiKey - The Magentrix API key (used as refresh_token).
- * @param {string} instanceUrl - The full Magentrix instance URL (e.g., https://yourorg.magentrixcloud.com).
- * @throws {Error} If the request fails, the server returns an error, or the response is invalid.
- * @returns {Promise<string>} Resolves to the Magentrix access token string.
- */
-export const getAccessToken = async (apiKey, instanceUrl) => {
-    debug.auth(`Requesting access token from ${instanceUrl}/api/3.0/token`);
-    try {
-        const data = await fetchMagentrix({
-            instanceUrl,
-            path: '/api/3.0/token',
-            body: {
-                grant_type: "refresh_token",
-                refresh_token: apiKey
-            },
-            method: "POST"
-        })
-
-        debug.auth('Token received successfully', { validUntil: data.validUntil });
-        // Success
-        return {
-            token: data.token,
-            validUntil: data.validUntil
-        };
-    } catch (error) {
-        debug.auth(`Token request failed: ${error.message}`);
-        throw new Error(`Error retrieving Magentrix access token: ${error.message}`);
-    }
-};
-
-/**
- * Attempts to authenticate with the given API key and instance URL.
- * If authentication fails, throws an error with a friendly message and error details.
- *
- * @async
- * @param {string} apiKey - The Magentrix API key to authenticate with.
- * @param {string} instanceUrl - The Magentrix instance URL to authenticate against.
- * @returns {Promise<Object>} The token data returned by getAccessToken if successful.
- * @throws {Error} If authentication fails, with a message explaining the failure.
- */
-export const tryAuthenticate = async (apiKey, instanceUrl) => {
-    try {
-        return await getAccessToken(apiKey, instanceUrl);
-    } catch (error) {
-        const errorMessage = error.message || String(error);
-
-        // Build formatted error message with colors and spacing
-        let formattedMessage = '\n' + chalk.red.bold('✖ Authentication Failed') + '\n';
-        formattedMessage += chalk.dim('─'.repeat(50)) + '\n\n';
-
-        debug.auth(`Authentication failed, categorizing error: ${errorMessage.substring(0, 100)}`);
-
-        if (errorMessage.includes('Network error')) {
-            debug.auth('Error category: Network error (unable to reach instance)');
-            formattedMessage += chalk.cyan.bold('🌐 Unable to reach the Magentrix instance') + '\n\n';
-            formattedMessage += chalk.yellow('  Possible causes:') + '\n';
-            formattedMessage += chalk.gray('  • Check your internet connection') + '\n';
-            formattedMessage += chalk.gray('  • Verify the instance URL is correct') + '\n';
-            formattedMessage += chalk.gray('  • Ensure the server is online and accessible') + '\n';
-        } else if (errorMessage.includes('HTTP 401') || errorMessage.includes('HTTP 403') || errorMessage.includes('Unauthorized')) {
-            debug.auth('Error category: Invalid API key (401/403)');
-            formattedMessage += chalk.cyan.bold('🔑 Invalid API Key') + '\n\n';
-            formattedMessage += chalk.yellow('  What to do:') + '\n';
-            formattedMessage += chalk.gray('  • The API key you entered is incorrect') + '\n';
-            formattedMessage += chalk.gray('  • Verify your API key from the Magentrix admin panel') + '\n';
-        } else if (errorMessage.includes('HTTP 404')) {
-            debug.auth('Error category: Invalid instance URL (404)');
-            formattedMessage += chalk.cyan.bold('🔍 Invalid Magentrix Instance URL') + '\n\n';
-            formattedMessage += chalk.yellow('  What to do:') + '\n';
-            formattedMessage += chalk.gray('  • The URL does not appear to be a valid Magentrix server') + '\n';
-            formattedMessage += chalk.gray('  • Verify the URL matches your Magentrix instance') + '\n';
-        } else if (errorMessage.includes('HTTP 5')) {
-            debug.auth('Error category: Server error (5xx)');
-            formattedMessage += chalk.cyan.bold('⚠️  Magentrix Server Error') + '\n\n';
-            formattedMessage += chalk.yellow('  What to do:') + '\n';
-            formattedMessage += chalk.gray('  • The server is experiencing issues') + '\n';
-            formattedMessage += chalk.gray('  • Please try again in a few moments') + '\n';
-            formattedMessage += chalk.gray('  • Contact support if the issue persists') + '\n';
-        } else if (errorMessage.includes('timeout') || errorMessage.includes('ETIMEDOUT')) {
-            debug.auth('Error category: Connection timeout');
-            formattedMessage += chalk.cyan.bold('⏱️  Connection Timeout') + '\n\n';
-            formattedMessage += chalk.yellow('  What to do:') + '\n';
-            formattedMessage += chalk.gray('  • The server took too long to respond') + '\n';
-            formattedMessage += chalk.gray('  • Check your internet connection') + '\n';
-            formattedMessage += chalk.gray('  • Try again in a moment') + '\n';
-        } else {
-            debug.auth('Error category: Unknown error');
-            formattedMessage += chalk.cyan.bold('❓ Unable to Authenticate') + '\n\n';
-            formattedMessage += chalk.yellow('  What to do:') + '\n';
-            formattedMessage += chalk.gray('  • Verify both your API key and instance URL are correct') + '\n';
-            formattedMessage += chalk.gray('  • Ensure the API key matches the instance URL') + '\n';
-        }
-
-        formattedMessage += '\n' + chalk.dim('─'.repeat(50)) + '\n';
-
-        throw new Error(formattedMessage);
-    }
-};
-
+import { fetchMagentrix } from "../fetch.js";
+import chalk from "chalk";
+import debug from '../../debug.js';
+
+/**
+ * Authenticates with Magentrix and retrieves an access token using the API key as a refresh token.
+ *
+ * @async
+ * @param {string} apiKey - The Magentrix API key (used as refresh_token).
+ * @param {string} instanceUrl - The full Magentrix instance URL (e.g., https://yourorg.magentrixcloud.com).
+ * @throws {Error} If the request fails, the server returns an error, or the response is invalid.
+ * @returns {Promise<string>} Resolves to the Magentrix access token string.
+ */
+export const getAccessToken = async (apiKey, instanceUrl) => {
+    debug.auth(`Requesting access token from ${instanceUrl}/api/3.0/token`);
+    try {
+        const data = await fetchMagentrix({
+            instanceUrl,
+            path: '/api/3.0/token',
+            body: {
+                grant_type: "refresh_token",
+                refresh_token: apiKey
+            },
+            method: "POST"
+        })
+
+        debug.auth('Token received successfully', { validUntil: data.validUntil });
+        // Success
+        return {
+            token: data.token,
+            validUntil: data.validUntil
+        };
+    } catch (error) {
+        debug.auth(`Token request failed: ${error.message}`);
+        throw new Error(`Error retrieving Magentrix access token: ${error.message}`);
+    }
+};
+
+/**
+ * Attempts to authenticate with the given API key and instance URL.
+ * If authentication fails, throws an error with a friendly message and error details.
+ *
+ * @async
+ * @param {string} apiKey - The Magentrix API key to authenticate with.
+ * @param {string} instanceUrl - The Magentrix instance URL to authenticate against.
+ * @returns {Promise<Object>} The token data returned by getAccessToken if successful.
+ * @throws {Error} If authentication fails, with a message explaining the failure.
+ */
+export const tryAuthenticate = async (apiKey, instanceUrl) => {
+    try {
+        return await getAccessToken(apiKey, instanceUrl);
+    } catch (error) {
+        const errorMessage = error.message || String(error);
+
+        // Build formatted error message with colors and spacing
+        let formattedMessage = '\n' + chalk.red.bold('✖ Authentication Failed') + '\n';
+        formattedMessage += chalk.dim('─'.repeat(50)) + '\n\n';
+
+        debug.auth(`Authentication failed, categorizing error: ${errorMessage.substring(0, 100)}`);
+
+        if (errorMessage.includes('Network error')) {
+            debug.auth('Error category: Network error (unable to reach instance)');
+            formattedMessage += chalk.cyan.bold('🌐 Unable to reach the Magentrix instance') + '\n\n';
+            formattedMessage += chalk.yellow('  Possible causes:') + '\n';
+            formattedMessage += chalk.gray('  • Check your internet connection') + '\n';
+            formattedMessage += chalk.gray('  • Verify the instance URL is correct') + '\n';
+            formattedMessage += chalk.gray('  • Ensure the server is online and accessible') + '\n';
+        } else if (errorMessage.includes('HTTP 401') || errorMessage.includes('HTTP 403') || errorMessage.includes('Unauthorized')) {
+            debug.auth('Error category: Invalid API key (401/403)');
+            formattedMessage += chalk.cyan.bold('🔑 Invalid API Key') + '\n\n';
+            formattedMessage += chalk.yellow('  What to do:') + '\n';
+            formattedMessage += chalk.gray('  • The API key you entered is incorrect') + '\n';
+            formattedMessage += chalk.gray('  • Verify your API key from the Magentrix admin panel') + '\n';
+        } else if (errorMessage.includes('HTTP 404')) {
+            debug.auth('Error category: Invalid instance URL (404)');
+            formattedMessage += chalk.cyan.bold('🔍 Invalid Magentrix Instance URL') + '\n\n';
+            formattedMessage += chalk.yellow('  What to do:') + '\n';
+            formattedMessage += chalk.gray('  • The URL does not appear to be a valid Magentrix server') + '\n';
+            formattedMessage += chalk.gray('  • Verify the URL matches your Magentrix instance') + '\n';
+        } else if (errorMessage.includes('HTTP 5')) {
+            debug.auth('Error category: Server error (5xx)');
+            formattedMessage += chalk.cyan.bold('⚠️  Magentrix Server Error') + '\n\n';
+            formattedMessage += chalk.yellow('  What to do:') + '\n';
+            formattedMessage += chalk.gray('  • The server is experiencing issues') + '\n';
+            formattedMessage += chalk.gray('  • Please try again in a few moments') + '\n';
+            formattedMessage += chalk.gray('  • Contact support if the issue persists') + '\n';
+        } else if (errorMessage.includes('timeout') || errorMessage.includes('ETIMEDOUT')) {
+            debug.auth('Error category: Connection timeout');
+            formattedMessage += chalk.cyan.bold('⏱️  Connection Timeout') + '\n\n';
+            formattedMessage += chalk.yellow('  What to do:') + '\n';
+            formattedMessage += chalk.gray('  • The server took too long to respond') + '\n';
+            formattedMessage += chalk.gray('  • Check your internet connection') + '\n';
+            formattedMessage += chalk.gray('  • Try again in a moment') + '\n';
+        } else {
+            debug.auth('Error category: Unknown error');
+            formattedMessage += chalk.cyan.bold('❓ Unable to Authenticate') + '\n\n';
+            formattedMessage += chalk.yellow('  What to do:') + '\n';
+            formattedMessage += chalk.gray('  • Verify both your API key and instance URL are correct') + '\n';
+            formattedMessage += chalk.gray('  • Ensure the API key matches the instance URL') + '\n';
+        }
+
+        formattedMessage += '\n' + chalk.dim('─'.repeat(50)) + '\n';
+
+        throw new Error(formattedMessage);
+    }
+};
+