@magentrix-corp/magentrix-cli 1.0.0

package/utils/downloadAssets.js

@@ -0,0 +1,75 @@
+import { EXPORT_ROOT } from "../vars/global.js";
+import { downloadAssetsZip, listAssets } from "./magentrix/api/assets.js";
+import fs from 'fs';
+import extract from 'extract-zip';
+import { v4 as uuidv4 } from 'uuid';
+import fspath from 'path';
+import { setFileTag } from "./filetag.js";
+
+export const walkAssets = async (instanceUrl, token, assetPath) => {
+    const assetResults = await listAssets(instanceUrl, token, assetPath);
+    const walkedAssets = [];
+
+    for (const asset of assetResults.Assets) {
+        if (asset.Type === 'Folder') {
+            walkedAssets.push({
+                ...asset,
+                Path: asset.Path.replace('/contents/assets', '/Contents/Assets'),
+                Children: await walkAssets(instanceUrl, token, asset.Path),
+                ParentFolder: assetResults.CurrentPath.replace("/contents/assets", "/Contents/Assets"),
+            })
+        } else {
+            walkedAssets.push({
+                ...asset,
+                Path: asset.Path.replace("/contents/assets", "/Contents/Assets"),
+                ParentFolder: assetResults.CurrentPath.replace("/contents/assets", "/Contents/Assets"),
+            });
+        }
+    }
+
+    return walkedAssets;
+}
+
+export const downloadAssets = async (instanceUrl, token, path) => {
+    const allAssets = await walkAssets(instanceUrl, token, path);
+
+    const iterateDownload = async (assets) => {
+        const parentOfAssets = assets?.[0]?.ParentFolder;
+        const folders = assets.filter(asset => asset.Type === 'Folder');
+        const files = assets.filter(asset => asset.Type === 'File');
+
+        for (const folder of folders) {
+            fs.mkdirSync(fspath.join(EXPORT_ROOT, folder.Path), { recursive: true });
+            await iterateDownload(folder?.Children || []);
+        }
+
+        if (files.length > 0) {
+            const savedAs = await downloadAssetsZip({
+                baseUrl: instanceUrl,
+                token: token, // "Bearer" prefix added in code
+                path: parentOfAssets,
+                names: files.map(file => file.Name),
+                outFile: fspath.join(EXPORT_ROOT, parentOfAssets, 'assets.zip'), // optional
+            });
+
+            await extract(savedAs, {
+                dir: fspath.resolve(fspath.join(EXPORT_ROOT, parentOfAssets))
+            });
+
+            // for (const file of files) {
+            //     // Ensure the file was created properly
+            //     // TODO: Create some error handling incase it wasn't
+            //     const downloadedPath = fspath.join(EXPORT_ROOT, file.Path);
+            //     if (!fs.existsSync(downloadedPath)) continue;
+            // }
+
+            fs.rmSync(savedAs);
+        }
+    }
+
+    await iterateDownload(allAssets);
+
+    return {
+        tree: allAssets
+    };
+}

package/utils/filetag.js

@@ -0,0 +1,115 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import Config from './config.js';
+
+
+const platform = os.platform();
+const config = new Config(); // uses default project config
+
+/**
+ * Generates a unique key from a file's stat object
+ * @param {fs.Stats} stats
+ * @returns {string}
+ */
+function getFileKey(stats) {
+    return `${stats.dev}:${stats.ino}`;
+}
+
+/**
+ * Tags a file with a persistent ID using platform-specific methods and stores it via Config.
+ *
+ * @param {string} filePath - Path to the file.
+ * @param {string} tag - Tag to assign.
+ * @returns {Promise<void>}
+ */
+export async function setFileTag(filePath, tag) {
+    const absPath = path.resolve(filePath);
+    const stats = fs.statSync(absPath);
+    const key = getFileKey(stats);
+
+    // Try platform tagging
+    try {
+        if (platform === 'darwin' || platform === 'linux') {
+            const xattr = await import('xattr');
+            await xattr.set(absPath, 'user.fileTag', Buffer.from(tag));
+        } else if (platform === 'win32') {
+            const streamPath = `${absPath}:fileTag`;
+            fs.writeFileSync(streamPath, tag);
+        }
+    } catch {
+        // xattr/ADS is optional; we fall back to config
+    }
+
+    const tracked = config.read('trackedFileTags', { global: false, filename: 'fileIdIndex.json' }) || {};
+    tracked[key] = { tag, lastKnownPath: absPath };
+    config.save('trackedFileTags', tracked, { global: false, filename: 'fileIdIndex.json' });
+}
+
+/**
+ * Retrieves a file tag from metadata or Config, even after renames.
+ *
+ * @param {string} filePath - Current path to the file.
+ * @returns {Promise<string|null>}
+ */
+export async function getFileTag(filePath) {
+    const absPath = path.resolve(filePath);
+    let stats;
+
+    try {
+        stats = fs.statSync(absPath);
+    } catch {
+        return null;
+    }
+
+    const key = getFileKey(stats);
+    const tracked = config.read('trackedFileTags', { global: false, filename: 'fileIdIndex.json' }) || {};
+
+    // Try platform method first
+    try {
+        if (platform === 'darwin' || platform === 'linux') {
+            const xattr = await import('xattr');
+            const buf = await xattr.get(absPath, 'user.fileTag');
+            return buf.toString();
+        } else if (platform === 'win32') {
+            const streamPath = `${absPath}:fileTag`;
+            return fs.readFileSync(streamPath, 'utf8');
+        }
+    } catch {
+        // fallback below
+    }
+
+    return tracked[key]?.tag ?? null;
+}
+
+/**
+ * Retrieves a file path from its tag.
+ *
+ * @param {string} tag - The file tag.
+ * @returns {Promise<string|null>}
+ */
+export function findFileByTag(tag) {
+    const tracked = config.read('trackedFileTags', { global: false, filename: 'fileIdIndex.json' }) || {};
+    for (const record of Object.values(tracked)) {
+        if (record.tag === tag) return record.lastKnownPath;
+    }
+    return null;
+}
+
+/**
+ * Checks if the given file path is tracked in fileIdIndex.json as a lastKnownPath.
+ * Returns the tag if found, or null if not linked.
+ *
+ * @param {string} filePath - Path to check.
+ * @returns {string|null} The tag if the path is tracked, otherwise null.
+ */
+export function isPathLinkedToTagByLastKnownPath(filePath) {
+    const absPath = path.resolve(filePath);
+    const tracked = config.read('trackedFileTags', { global: false, filename: 'fileIdIndex.json' }) || {};
+    for (const record of Object.values(tracked)) {
+        if (record.lastKnownPath === absPath) {
+            return record.tag;
+        }
+    }
+    return null;
+}

package/utils/hash.js

@@ -0,0 +1,14 @@
+import crypto from 'crypto';
+
+/**
+ * Hash any data to a lowercase hex SHA-256 string.
+ * @param {string|Buffer} input
+ * @returns {string}
+ */
+export function sha256(input) {
+    return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+// --- Usage Example ---
+// import sha256 from './lib/sha256.js';
+// const hash = sha256('some string to hash');

package/utils/magentrix/api/assets.js

@@ -0,0 +1,145 @@
+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.");
+
+    let reqPath = `/api/3.0/staticassets?path=${path}&names=${names.join(",")}`;
+
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: reqPath,
+        method: "DELETE",
+        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 */
+        }
+        throw new Error(`Download failed (${res.status}): ${detail || res.statusText}`);
+    }
+
+    // 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

@@ -0,0 +1,56 @@
+import { fetchMagentrix } from "../fetch.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) => {
+    try {
+        const data = await fetchMagentrix({
+            instanceUrl,
+            path: '/api/3.0/token',
+            body: {
+                grant_type: "refresh_token",
+                refresh_token: apiKey
+            },
+            method: "POST"
+        })
+
+        // Success
+        return {
+            token: data.token,
+            validUntil: data.validUntil
+        };
+    } catch (error) {
+        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) {
+        throw new Error(
+            `❌ Failed to authenticate with Magentrix:\n` +
+            `The API key and/or instance URL you provided are incorrect or do not match.\n` +
+            `Please double-check both values and try again.\n\n` +
+            `Details: ${error.message || error}`
+        );
+    }
+};
+

package/utils/magentrix/api/createEntity.js

@@ -0,0 +1,61 @@
+import { fetchMagentrix } from "../fetch.js";
+
+/**
+ * Creates a new ActiveClass or ActivePage entity in Magentrix via the REST API.
+ *
+ * @async
+ * @function createEntity
+ * @param {string} instanceUrl - The base URL of the Magentrix instance.
+ * @param {string} token - The OAuth2 bearer token for authentication.
+ * @param {string} entityName - The Magentrix entity type. Allowed: 'ActiveClass' or 'ActivePage' (case-insensitive).
+ * @param {Object} data - The entity data to create. Must include 'Name' and 'Type'.
+ * @returns {Promise<Object>} The response data from Magentrix API if successful.
+ * @throws {Error} Throws if required parameters are missing, entityName is invalid, or if required fields in data are missing.
+ *
+ * @example
+ * const entity = await createEntity('https://your.magentrix.com', 'yourToken', 'ActiveClass', {
+ *   Name: "MyNewClass",
+ *   Body: "...",
+ *   Description: "A test class",
+ *   Type: "Class"
+ * });
+ */
+export const createEntity = async (instanceUrl, token, entityName, data) => {
+    // --- Validate required parameters ---
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+    if (!entityName || typeof entityName !== 'string') {
+        throw new Error("Missing required 'entityName' (must be 'ActiveClass' or 'ActivePage')");
+    }
+
+    // Allowed entity types
+    const allowedEntities = ['activeclass', 'activepage'];
+    const entity = entityName.trim().toLowerCase();
+    if (!allowedEntities.includes(entity)) {
+        throw new Error("Invalid 'entityName'. Allowed values: 'ActiveClass' or 'ActivePage'");
+    }
+
+    // Validate data object and required fields
+    if (!data || typeof data !== 'object') {
+        throw new Error('Missing required data object for entity creation');
+    }
+    if (!data.Name) {
+        throw new Error("Missing required field: 'Name' in data");
+    }
+    if (!data.Type) {
+        throw new Error("Missing required field: 'Type' in data");
+    }
+
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: `/api/3.0/entity/${entity}`,
+        method: "POST",
+        body: data,
+        returnErrorObject: true
+    });
+
+    // --- Success: return parsed response ---
+    return response;
+};

package/utils/magentrix/api/deleteEntity.js

@@ -0,0 +1,55 @@
+import { fetchMagentrix } from "../fetch.js";
+
+/**
+ * Deletes an existing ActiveClass or ActivePage entity in Magentrix via the REST API.
+ *
+ * @async
+ * @function deleteEntity
+ * @param {string} instanceUrl - The base URL of the Magentrix instance (e.g. "https://your.magentrix.com").
+ * @param {string} token - The OAuth2 bearer token for authentication.
+ * @param {string} entityName - The Magentrix entity type. Allowed: "ActiveClass" or "ActivePage" (case-insensitive).
+ * @param {string} recordId - The unique Magentrix record ID of the entity to delete.
+ * @returns {Promise<Object>} The API response object, or an error object if the deletion fails.
+ * @throws {Error} If required parameters are missing or invalid.
+ *
+ * @example
+ * const deleted = await deleteEntity(
+ *   "https://your.magentrix.com",
+ *   "yourToken",
+ *   "ActiveClass",
+ *   "06bdc45e-8222-44f5-9ed2-40f5a7bc6cb3"
+ * );
+ */
+export const deleteEntity = async (instanceUrl, token, entityName, recordId) => {
+    // --- Validate required parameters ---
+    if (!instanceUrl || typeof instanceUrl !== 'string') {
+        throw new Error('Missing or invalid Magentrix instanceUrl');
+    }
+    if (!token || typeof token !== 'string') {
+        throw new Error('Missing or invalid Magentrix token');
+    }
+    if (!entityName || typeof entityName !== 'string') {
+        throw new Error("Missing or invalid 'entityName' (must be 'ActiveClass' or 'ActivePage')");
+    }
+    if (!recordId || typeof recordId !== 'string') {
+        throw new Error("Missing or invalid 'recordId' (must be a Magentrix record GUID string)");
+    }
+
+    // --- Validate entity type ---
+    const allowedEntities = ['activeclass', 'activepage'];
+    const entity = entityName.trim().toLowerCase();
+    if (!allowedEntities.includes(entity)) {
+        throw new Error("Invalid 'entityName'. Allowed: 'ActiveClass' or 'ActivePage'");
+    }
+
+    // --- Make DELETE request to Magentrix API ---
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: `/api/3.0/entity/${entity}/${recordId}`,
+        method: "DELETE",
+        returnErrorObject: true
+    });
+
+    return response;
+};

package/utils/magentrix/api/meqlQuery.js

@@ -0,0 +1,31 @@
+import { fetchMagentrix } from "../fetch.js";
+
+/**
+ * Executes a Magentrix Entity Query Language (MEQL) query via the REST API v3.
+ *
+ * @async
+ * @param {string} instanceUrl - Base URL of the Magentrix instance.
+ * @param {string} token - Bearer token string.
+ * @param {string} query - MEQL query string.
+ * @returns {Promise<object>} The API response data.
+ * @throws {Error} On HTTP or API-level error.
+ */
+export const meqlQuery = async (instanceUrl, token, query = '') => {
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+    if (!query.trim()) {
+        throw new Error('MEQL query string is required');
+    }
+
+    const data = await fetchMagentrix({
+        instanceUrl,
+        token,
+        method: "POST",
+        path: '/api/3.0/query',
+        body: query
+    })
+
+    // --- Success ---
+    return data;
+};

package/utils/magentrix/api/retrieveEntity.js

@@ -0,0 +1,32 @@
+import { fetchMagentrix } from "../fetch.js";
+
+/**
+ * Lists all entities available from the Magentrix API.
+ *
+ * Makes an authenticated GET request to `/api/3.0/entity` to retrieve metadata 
+ * about all available entities (objects) in the Magentrix instance.
+ *
+ * Handles and throws both network errors and API-level errors with detailed messages.
+ *
+ * @async
+ * @param {string} instanceUrl - The base URL of the Magentrix instance.
+ * @param {string} token - The OAuth or access token for authentication.
+ * @returns {Promise<Object>} Parsed JSON response with entities metadata.
+ * @throws {Error} If required arguments are missing, network error occurs,
+ *         HTTP error is returned, or API-level errors are found in the response.
+ */
+export const listEntities = async (instanceUrl, token) => {
+    // --- Validate required input parameters ---
+    if (!instanceUrl || !token) {
+        throw new Error('Missing required Magentrix instanceUrl or token');
+    }
+
+    const data = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: '/api/3.0/entity',
+        method: "GET"
+    })
+
+    return data;
+};

package/utils/magentrix/api/updateEntity.js

@@ -0,0 +1,66 @@
+import { fetchMagentrix } from "../fetch.js";
+
+/**
+ * Updates an existing ActiveClass or ActivePage entity in Magentrix via the REST API.
+ *
+ * @async
+ * @function updateEntity
+ * @param {string} instanceUrl - The base URL of the Magentrix instance (e.g. "https://your.magentrix.com").
+ * @param {string} token - The OAuth2 bearer token for authentication.
+ * @param {string} entityName - The Magentrix entity type. Allowed: "ActiveClass" or "ActivePage" (case-insensitive).
+ * @param {string} recordId - The unique Magentrix record ID to update.
+ * @param {Object} data - The fields to update on the entity. Provide any subset of updatable fields (e.g. Name, Description, Body, Type, etc).
+ * @returns {Promise<Object>} The API response object containing updated record data.
+ * @throws {Error} If required parameters are missing, entityName is invalid, recordId is not provided, or data is not an object.
+ *
+ * @example
+ * const updated = await updateEntity(
+ *   "https://your.magentrix.com",
+ *   "yourToken",
+ *   "ActiveClass",
+ *   "06bdc45e-8222-44f5-9ed2-40f5a7bc6cb3",
+ *   { Name: "RenamedClass", Description: "Updated" }
+ * );
+ */
+export const updateEntity = async (instanceUrl, token, entityName, recordId, data) => {
+    // --- Validate required parameters ---
+    if (!instanceUrl || typeof instanceUrl !== 'string') {
+        throw new Error('Missing or invalid Magentrix instanceUrl');
+    }
+    if (!token || typeof token !== 'string') {
+        throw new Error('Missing or invalid Magentrix token');
+    }
+    if (!entityName || typeof entityName !== 'string') {
+        throw new Error("Missing or invalid 'entityName' (must be 'ActiveClass' or 'ActivePage')");
+    }
+    if (!recordId || typeof recordId !== 'string') {
+        throw new Error("Missing or invalid 'recordId' (must be a Magentrix record GUID string)");
+    }
+
+    // --- Validate entity type ---
+    const allowedEntities = ['activeclass', 'activepage'];
+    const entity = entityName.trim().toLowerCase();
+    if (!allowedEntities.includes(entity)) {
+        throw new Error("Invalid 'entityName'. Allowed: 'ActiveClass' or 'ActivePage'");
+    }
+
+    // --- Validate update data ---
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+        throw new Error('Missing or invalid data object for entity update');
+    }
+    if (Object.keys(data).length === 0) {
+        throw new Error('No fields provided to update');
+    }
+
+    // --- Make PATCH request to Magentrix API ---
+    const response = await fetchMagentrix({
+        instanceUrl,
+        token,
+        path: `/api/3.0/entity/${entity}/${recordId}`,
+        method: "PATCH",
+        body: data,
+        returnErrorObject: true
+    });
+
+    return response;
+};