@openinc/parse-server-opendash 3.19.2 → 3.20.0

package/dist/features/documentation/services/GitHubClient.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubClient = void 0;
+/**
+ * GitHub API Client for fetching repository data
+ */
+class GitHubClient {
+    constructor(token) {
+        this.baseUrl = "https://api.github.com";
+        this.headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/vnd.github.v3+json",
+            "User-Agent": "OpenInc-Documentation-Importer",
+        };
+    }
+    /**
+     * Validate the GitHub token
+     */
+    async validateToken() {
+        const response = await fetch(`${this.baseUrl}/user`, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Invalid token: ${response.status} ${response.statusText} - ${error}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get repository information
+     */
+    async getRepository(owner, repo) {
+        const response = await fetch(`${this.baseUrl}/repos/${owner}/${repo}`, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to access repository: ${response.status} ${response.statusText} - ${error}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get all branches for a repository
+     */
+    async getBranches(owner, repo) {
+        const response = await fetch(`${this.baseUrl}/repos/${owner}/${repo}/branches`, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch branches: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get a specific branch
+     */
+    async getBranch(owner, repo, branch) {
+        const response = await fetch(`${this.baseUrl}/repos/${owner}/${repo}/branches/${branch}`, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Failed to fetch branch '${branch}': ${response.status} ${response.statusText} - ${error}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get repository tree (file structure)
+     */
+    async getTree(owner, repo, sha, recursive = true) {
+        const url = `${this.baseUrl}/repos/${owner}/${repo}/git/trees/${sha}${recursive ? "?recursive=1" : ""}`;
+        const response = await fetch(url, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch repository tree: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get file content
+     */
+    async getFileContent(owner, repo, path, ref) {
+        const url = `${this.baseUrl}/repos/${owner}/${repo}/contents/${path}${ref ? `?ref=${ref}` : ""}`;
+        const response = await fetch(url, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch file content: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    }
+    /**
+     * Get the last commit information for a specific file
+     */
+    async getFileLastCommit(owner, repo, path, ref) {
+        const url = `${this.baseUrl}/repos/${owner}/${repo}/commits?path=${encodeURIComponent(path)}&per_page=1${ref ? `&sha=${ref}` : ""}`;
+        const response = await fetch(url, {
+            headers: this.headers,
+        });
+        if (!response.ok) {
+            throw new Error(`Failed to fetch file commit info: ${response.status} ${response.statusText}`);
+        }
+        const commits = (await response.json());
+        return commits.length > 0 ? commits[0] : null;
+    }
+    /**
+     * Get commit information for multiple files in batch
+     */
+    async getMultipleFileCommits(owner, repo, paths, ref) {
+        const commitMap = new Map();
+        // Process files in batches to avoid rate limiting
+        const batchSize = 5;
+        for (let i = 0; i < paths.length; i += batchSize) {
+            const batch = paths.slice(i, i + batchSize);
+            const promises = batch.map(async (path) => {
+                try {
+                    const commit = await this.getFileLastCommit(owner, repo, path, ref);
+                    return { path, commit };
+                }
+                catch (error) {
+                    console.warn(`⚠️ Failed to get commit info for ${path}:`, error);
+                    return { path, commit: null };
+                }
+            });
+            const results = await Promise.all(promises);
+            results.forEach(({ path, commit }) => {
+                if (commit) {
+                    commitMap.set(path, commit);
+                }
+            });
+            // Small delay to be respectful to GitHub API
+            if (i + batchSize < paths.length) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        }
+        return commitMap;
+    }
+}
+exports.GitHubClient = GitHubClient;

package/dist/features/documentation/services/MetadataEnricher.d.ts

@@ -0,0 +1,5 @@
+import { DocumentationFile } from "../types";
+import { GitHubClient } from "./GitHubClient";
+export declare class MetadataEnricher {
+    static enrichCommits(files: DocumentationFile[], githubClient: GitHubClient, owner: string, repo: string, branch?: string, rootPath?: string): Promise<void>;
+}

package/dist/features/documentation/services/MetadataEnricher.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataEnricher = void 0;
+class MetadataEnricher {
+    static async enrichCommits(files, githubClient, owner, repo, branch, rootPath) {
+        const normalizedRoot = rootPath?.replace(/^\/+/g, "").replace(/\/+$/g, "");
+        const fullPaths = files.map((f) => normalizedRoot ? `${normalizedRoot}/${f.path}` : f.path);
+        try {
+            const commitMap = await githubClient.getMultipleFileCommits(owner, repo, fullPaths, branch);
+            let enriched = 0;
+            files.forEach((file, idx) => {
+                const commit = commitMap.get(fullPaths[idx]);
+                if (commit?.commit) {
+                    file.lastModified = new Date(commit.commit.author.date);
+                    file.lastModifiedBy = commit.commit.author.name;
+                    file.lastCommitSha = commit.sha;
+                    file.lastCommitMessage = commit.commit.message.split("\n")[0];
+                    if (!file.fileLastModifiedAt)
+                        file.fileLastModifiedAt = file.lastModified;
+                    enriched++;
+                }
+            });
+        }
+        catch (e) {
+            console.warn("Failed to fetch commit information:", e);
+        }
+    }
+}
+exports.MetadataEnricher = MetadataEnricher;

package/dist/features/documentation/services/StructureBuilder.d.ts

@@ -0,0 +1,7 @@
+import { DocumentationFolder, DocumentationFile, FolderConfig } from "../types";
+export declare class StructureBuilder {
+    static build(files: DocumentationFile[], rootPath?: string, defaultFolderConfig?: Partial<FolderConfig>): {
+        root: DocumentationFolder;
+        configFiles: DocumentationFile[];
+    };
+}

package/dist/features/documentation/services/StructureBuilder.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StructureBuilder = void 0;
+class StructureBuilder {
+    static build(files, rootPath, defaultFolderConfig) {
+        const root = {
+            name: rootPath || "root",
+            path: "",
+            files: [],
+            subfolders: new Map(),
+            config: { ...defaultFolderConfig },
+        };
+        const configFiles = [];
+        for (const file of files) {
+            const pathParts = file.path.split("/");
+            // folder navigation (all but last segment)
+            let current = root;
+            for (let i = 0; i < pathParts.length - 1; i++) {
+                const folderName = pathParts[i];
+                const folderPath = pathParts.slice(0, i + 1).join("/");
+                if (!current.subfolders.has(folderName)) {
+                    current.subfolders.set(folderName, {
+                        name: folderName,
+                        path: folderPath,
+                        files: [],
+                        subfolders: new Map(),
+                        config: { ...defaultFolderConfig },
+                    });
+                }
+                current = current.subfolders.get(folderName);
+            }
+            // classify file
+            if (file.originalFilename === "config.json") {
+                configFiles.push(file);
+            }
+            else if (file.extension === "md") {
+                current.files.push(file);
+            }
+        }
+        return { root, configFiles };
+    }
+}
+exports.StructureBuilder = StructureBuilder;

package/dist/features/documentation/services/TreeNormalizer.d.ts

@@ -0,0 +1,10 @@
+import { GitHubTreeResponse, DocumentationFile, FileFilterOptions } from "../types";
+/** Handles path normalization, root trimming and initial file object creation + filtering. */
+export declare class TreeNormalizer {
+    static normalize(treeData: GitHubTreeResponse, rootPath?: string, fileFilter?: FileFilterOptions): {
+        files: DocumentationFile[];
+        normalizedRootPath: string;
+    };
+    private static shouldIncludeFile;
+    private static matchesPattern;
+}

package/dist/features/documentation/services/TreeNormalizer.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeNormalizer = void 0;
+/** Handles path normalization, root trimming and initial file object creation + filtering. */
+class TreeNormalizer {
+    static normalize(treeData, rootPath, fileFilter) {
+        const normalizedRootPath = rootPath
+            ? rootPath.replace(/^\/+/g, "").replace(/\/+$/g, "")
+            : "";
+        const rootPrefix = normalizedRootPath ? normalizedRootPath + "/" : "";
+        const files = [];
+        for (const item of treeData.tree) {
+            if (item.type !== "blob")
+                continue;
+            if (normalizedRootPath && !item.path.startsWith(rootPrefix))
+                continue;
+            let relativePath = item.path;
+            if (normalizedRootPath)
+                relativePath = item.path.substring(rootPrefix.length);
+            if (!relativePath)
+                continue;
+            const pathParts = relativePath.split("/");
+            const fileName = pathParts[pathParts.length - 1];
+            const extension = fileName.includes(".")
+                ? (fileName.split(".").pop() || "").toLowerCase()
+                : "";
+            const baseName = extension
+                ? fileName.slice(0, fileName.lastIndexOf("."))
+                : fileName;
+            const file = {
+                name: baseName,
+                originalFilename: fileName,
+                path: relativePath,
+                sha: item.sha,
+                size: item.size,
+                extension,
+                url: item.url,
+            };
+            if (fileFilter && !this.shouldIncludeFile(file, fileFilter))
+                continue;
+            files.push(file);
+        }
+        return { files, normalizedRootPath };
+    }
+    static shouldIncludeFile(file, filter) {
+        if (filter.excludeExtensions?.includes(file.extension))
+            return false;
+        if (filter.includeExtensions?.length &&
+            !filter.includeExtensions.includes(file.extension))
+            return false;
+        if (filter.excludePaths?.length) {
+            for (const p of filter.excludePaths)
+                if (this.matchesPattern(file.path, p))
+                    return false;
+        }
+        if (filter.includePaths?.length) {
+            let inc = false;
+            for (const p of filter.includePaths)
+                if (this.matchesPattern(file.path, p)) {
+                    inc = true;
+                    break;
+                }
+            if (!inc)
+                return false;
+        }
+        return true;
+    }
+    static matchesPattern(path, pattern) {
+        const regexPattern = pattern.replace(/\*/g, ".*").replace(/\?/g, ".");
+        return new RegExp(`^${regexPattern}$`, "i").test(path);
+    }
+}
+exports.TreeNormalizer = TreeNormalizer;

package/dist/features/documentation/services/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./GitHubClient";
+export * from "./FeatureFilter";
+export * from "./ConfigApplier";
+export * from "./ContentLoader";
+export * from "./MetadataEnricher";
+export * from "./StructureBuilder";
+export * from "./TreeNormalizer";

package/dist/features/documentation/services/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./GitHubClient"), exports);
+__exportStar(require("./FeatureFilter"), exports);
+__exportStar(require("./ConfigApplier"), exports);
+__exportStar(require("./ContentLoader"), exports);
+__exportStar(require("./MetadataEnricher"), exports);
+__exportStar(require("./StructureBuilder"), exports);
+__exportStar(require("./TreeNormalizer"), exports);

package/dist/features/documentation/types/GitHubTypes.d.ts

@@ -0,0 +1,25 @@
+export type GitHubTreeItem = {
+    path: string;
+    mode: string;
+    type: "blob" | "tree";
+    sha: string;
+    size?: number;
+    url: string;
+};
+export type GitHubTreeResponse = {
+    sha: string;
+    url: string;
+    tree: GitHubTreeItem[];
+    truncated: boolean;
+};
+export type GitHubBranch = {
+    name: string;
+    commit: {
+        sha: string;
+    };
+};
+export type GitHubRepository = {
+    name: string;
+    private: boolean;
+    default_branch: string;
+};

package/dist/features/documentation/types/GitHubTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/features/documentation/types/StructureTypes.d.ts

@@ -0,0 +1,114 @@
+import { Feature } from "../../config/helper/isFeatureEnabled";
+/**
+ * Configuration for an individual file within a documentation folder.
+ */
+export type FileConfig = {
+    /** Sort order for this file (lower first). Defaults to 999 if not provided. */
+    order?: number;
+    /** Icon identifier (e.g., fa:file). Defaults to fa:file */
+    icon?: string;
+    /** Optional display title overriding file name */
+    title?: string;
+    /** Location Pattern */
+    locationPattern?: string;
+    /** locations */
+    locations?: string[];
+    /** Optional feature flag controlling visibility */
+    feature?: Feature;
+};
+/**
+ * Configuration for a documentation folder (from config.json)
+ */
+export type FolderConfig = {
+    /** Display title for the folder (overrides folder name) */
+    title?: string;
+    /** Sort order for this folder (lower numbers first) */
+    order?: number;
+    /** Icon identifier for display */
+    icon?: string;
+    /** Per-file configuration map (key = file name without extension) */
+    files?: Record<string, FileConfig>;
+    /** Optional feature flag controlling the entire folder */
+    feature?: Feature;
+};
+export type DocumentationFile = {
+    /** Base name without extension */
+    name: string;
+    /** Original filename including extension */
+    originalFilename?: string;
+    path: string;
+    sha: string;
+    size?: number;
+    extension: string;
+    url: string;
+    lastModified?: Date;
+    lastModifiedBy?: string;
+    lastCommitSha?: string;
+    lastCommitMessage?: string;
+    /** Raw textual content of the file (decoded UTF-8 for text-based files) */
+    content?: string;
+    /** Timestamp from source control representing when the source was last modified (alias of lastModified for persistence clarity) */
+    fileLastModifiedAt?: Date;
+    /** File-specific configuration (inherited from parent folder config.files entry) */
+    config?: FileConfig;
+};
+export type DocumentationFolder = {
+    name: string;
+    path: string;
+    files: DocumentationFile[];
+    subfolders: Map<string, DocumentationFolder>;
+    /** Configuration from config.json file or default config (always present) */
+    config: FolderConfig;
+};
+export type DocumentationStructure = {
+    root: DocumentationFolder;
+    allFiles: DocumentationFile[];
+    filesByExtension: Map<string, DocumentationFile[]>;
+};
+export type ImportOptions = {
+    branch?: string;
+    repository: string;
+    organization: string;
+    token: string;
+    fileFilter?: FileFilterOptions;
+    /** Root path within the repository to start from (e.g., "docs" to start from docs folder) */
+    rootPath?: string;
+    /** Default folder configuration to apply to folders without config.json */
+    defaultFolderConfig?: Partial<FolderConfig>;
+    /** If provided, skip calling getBranch() and use this commit SHA directly (e.g., provided by external scheduler) */
+    preResolvedCommitSha?: string;
+};
+export type FileFilterOptions = {
+    /** Array of file extensions to include (without dots). If not provided, all files are included. */
+    includeExtensions?: string[];
+    /** Array of file extensions to exclude (without dots). Takes precedence over includeExtensions. */
+    excludeExtensions?: string[];
+    /** Path patterns to include (supports wildcards) */
+    includePaths?: string[];
+    /** Path patterns to exclude (supports wildcards) */
+    excludePaths?: string[];
+};
+export type ImportResult = {
+    /** Documentation structure for this import. Undefined when skipped (no new commit). */
+    structure?: DocumentationStructure;
+    metadata: {
+        totalFiles: number;
+        fileTypes: string[];
+        importedAt: Date;
+        repository: string;
+        branch: string;
+        /** Latest commit SHA observed for the branch at import time */
+        commitSha: string;
+        /** Previously imported commit SHA (if any) */
+        previousCommitSha?: string;
+        /** Indicates the import was skipped because the commit SHA is unchanged */
+        skipped?: boolean;
+        /** Reason for skipping (e.g., 'unchanged') */
+        skipReason?: string;
+        /** Cleanup information when old documentation was removed */
+        cleanup?: {
+            deletedDocuments: number;
+            deletedCategories: number;
+        };
+    };
+};

package/dist/features/documentation/types/StructureTypes.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/features/documentation/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./GitHubTypes";
+export * from "./StructureTypes";

package/dist/features/documentation/types/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./GitHubTypes"), exports);
+__exportStar(require("./StructureTypes"), exports);

package/dist/functions/openinc-documentation-import-docs.d.ts

@@ -0,0 +1 @@
+export declare function init(name: string): Promise<void>;

package/dist/functions/openinc-documentation-import-docs.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const config_1 = require("../features/config");
+const importDocs_1 = require("../features/documentation/functions/importDocs");
+async function init(name) {
+    Parse.Cloud.define(name, async function (request) {
+        if (!request.master)
+            return { success: false, error: "Master key is required" };
+        try {
+            if ((0, config_1.isFeatureEnabled)("DOCUMENTATION")) {
+                await (0, importDocs_1.importDocs)();
+                return { status: "ok" };
+            }
+            console.log("Feature DOCUMENTATION is disabled");
+            return { status: "feature_disabled" };
+        }
+        catch (e) {
+            console.error("Error in importDocs:", e);
+            return { status: "error", error: e };
+        }
+    });
+}

package/dist/hooks/Documentation_Config.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;

package/dist/hooks/Documentation_Config.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = init;
+const __1 = require("..");
+const types_1 = require("../types");
+async function init() {
+    (0, __1.beforeSaveHook)(types_1.Documentation_Config, async (request) => {
+        const { object, original, user } = request;
+        await (0, __1.defaultHandler)(request);
+        await (0, __1.defaultAclHandler)(request);
+        // TODO
+    });
+    (0, __1.afterSaveHook)(types_1.Documentation_Config, async (request) => {
+        const { object, original, user } = request;
+        // TODO
+    });
+}

package/dist/index.js

@@ -42,6 +42,7 @@ const Core_Email_1 = require("./hooks/Core_Email");
 const openservice_1 = require("./features/openservice");
 const _init_1 = require("./functions/_init");
 const _init_2 = require("./hooks/_init");
+const importDocs_1 = require("./features/documentation/functions/importDocs");
 dayjs_1.default.extend(objectSupport_1.default);
 dayjs_1.default.extend(weekday_1.default);
 dayjs_1.default.extend(dayOfYear_1.default);
@@ -96,6 +97,8 @@ async function init() {
     await (0, settings_1.initUserSettings)();
     if ((0, config_1.isFeatureEnabled)("MAINTENANCE"))
         await (0, openservice_1.init)();
+    if ((0, config_1.isFeatureEnabled)("DOCUMENTATION"))
+        await (0, importDocs_1.importDocs)();
 }
 async function initTranslations() {
     // try {

package/dist/types/Documentation_Category.d.ts

@@ -5,7 +5,9 @@ export interface Documentation_CategoryAttributes {
     objectId: string;
     createdAt: Date;
     updatedAt: Date;
+    gitPath?: string;
     icon?: string;
+    isDefault: boolean;
     name: string;
     order: number;
     parent?: Documentation_Category;
@@ -15,8 +17,12 @@ export interface Documentation_CategoryAttributes {
 export declare class Documentation_Category extends Parse.Object<Documentation_CategoryAttributes> {
     static className: string;
     constructor(data?: Partial<Documentation_CategoryAttributes>);
+    get gitPath(): string | undefined;
+    set gitPath(value: string | undefined);
     get icon(): string | undefined;
     set icon(value: string | undefined);
+    get isDefault(): boolean;
+    set isDefault(value: boolean);
     get name(): string;
     set name(value: string);
     get order(): number;

package/dist/types/Documentation_Category.js

@@ -5,12 +5,24 @@ class Documentation_Category extends Parse.Object {
     constructor(data) {
         super("OD3_Documentation_Category", data);
     }
+    get gitPath() {
+        return super.get("gitPath");
+    }
+    set gitPath(value) {
+        super.set("gitPath", value);
+    }
     get icon() {
         return super.get("icon");
     }
     set icon(value) {
         super.set("icon", value);
     }
+    get isDefault() {
+        return super.get("isDefault");
+    }
+    set isDefault(value) {
+        super.set("isDefault", value);
+    }
     get name() {
         return super.get("name");
     }

package/dist/types/Documentation_Config.d.ts

@@ -0,0 +1,21 @@
+import type { _User } from "./_User";
+import { Tenant } from "./Tenant";
+export interface Documentation_ConfigAttributes {
+    id: string;
+    objectId: string;
+    createdAt: Date;
+    updatedAt: Date;
+    lastCommitSha?: string;
+    tenant?: Tenant;
+    user?: _User;
+}
+export declare class Documentation_Config extends Parse.Object<Documentation_ConfigAttributes> {
+    static className: string;
+    constructor(data?: Partial<Documentation_ConfigAttributes>);
+    get lastCommitSha(): string | undefined;
+    set lastCommitSha(value: string | undefined);
+    get tenant(): Tenant | undefined;
+    set tenant(value: Tenant | undefined);
+    get user(): _User | undefined;
+    set user(value: _User | undefined);
+}