@vikukumar/propvault-pdk 0.1.4

package/README.md

@@ -0,0 +1,129 @@
+# PropVault CMS — Plugin Development Kit (PDK)
+
+Extend the functionality of the PropVault Real Estate CMS and Page Builder platform with dynamic plugins. Custom plugins can register Action hooks to trigger custom logic on events (e.g. sending CRM leads) and Filter hooks to intercept and mutate variables/configs before operations complete.
+
+---
+
+## Getting Started
+
+### 1. Requirements
+Ensure you have **Node.js >= 18** and **TypeScript** installed locally.
+
+### 2. Scaffold a New Plugin
+Run the PDK CLI initializer inside the directory where you want to scaffold your plugin.
+
+```bash
+# Initialize a new plugin template
+npx @vikukumar/propvault-pdk create my-custom-plugin
+```
+
+This scaffolds the following plugin directory structure:
+```
+my-custom-plugin/
+├── src/
+│   └── index.ts          # Core plugin logic & hooks registration
+├── dist/                 # Compiled distribution (created on build)
+├── package.json          # Node config & build scripts
+├── tsconfig.json         # TypeScript compiler configurations
+└── plugin.json           # Plugin manifest metadata block
+```
+
+### 3. Install Scaffolding Dependencies
+```bash
+cd my-custom-plugin
+npm install
+```
+
+---
+
+## Writing Plugin Logic
+
+Plugins register hook handlers inside `src/index.ts` using `addAction` and `addFilter` from the `@vikukumar/propvault-pdk` package.
+
+### 1. Action Hooks
+Action hooks trigger custom operations when specific system events occur (e.g., lead submission, newsletter registration, theme swap).
+
+```typescript
+import { addAction } from "@vikukumar/propvault-pdk";
+
+// Send WhatsApp telemetry notifications on new lead submissions
+addAction("after_lead_submit", async (lead: any) => {
+  console.log("New Lead submitted in CMS:", lead.email);
+  
+  // Call webhook endpoint
+  await fetch("https://api.mycrm.com/v1/leads", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(lead),
+  });
+}, 10);
+```
+
+### 2. Filter Hooks
+Filter hooks intercept, modify, and return modified values/variables before the CMS processes them.
+
+```typescript
+import { addFilter } from "@vikukumar/propvault-pdk";
+
+// Force a premium badge suffix on project titles before they are stored in the database
+addFilter("before_project_save", async (project: any) => {
+  if (project.title && !project.title.includes("[Verified]")) {
+    project.title = `${project.title} [Verified]`;
+  }
+  return project;
+});
+```
+
+---
+
+## Core Hooks Registry API
+
+### Action Hooks
+| Hook Slug | Arguments | Description |
+|---|---|---|
+| `after_lead_submit` | `(lead: Lead)` | Fires after a contact form submission is registered. |
+| `after_newsletter_subscribe` | `(subscription: Subscription)` | Fires after a newsletter email subscription is verified. |
+
+### Filter Hooks
+| Hook Slug | Arguments | Description |
+|---|---|---|
+| `before_project_save` | `(project: Project)` | Filters project attributes before SQLite/PostgreSQL insertion. |
+| `before_lead_save` | `(lead: Lead)` | Filters lead fields before database submission. |
+
+---
+
+## Build & Packaging
+
+Once development is complete, compile and compress your plugin files into a distribution-ready bundle:
+
+```bash
+# 1. Compile TypeScript to JavaScript dist/index.js
+npm run build
+
+# 2. Package manifest and built script into plugin.zip
+npm run package
+```
+
+The CLI outputs a **`plugin.zip`** package.
+
+---
+
+## Publishing and Installation Options
+
+PropVault CMS supports three installation pathways:
+
+### Option A: Direct Zip Upload (Recommended)
+1. Go to **PropVault Admin Panel** -> **Plugins**.
+2. Locate the **Upload Zip Archive** card.
+3. Select your built `plugin.zip` file.
+4. Click **Upload** and toggle **Activate**.
+
+### Option B: Package Manager (NPM Release)
+Publish your compiled folder structure containing `plugin.json` to npm:
+```bash
+npm publish
+```
+CMS administrators can install it in their workspace by entering the package name (e.g. `my-propvault-plugin`) in the **NPM Package Registry** dashboard card.
+
+### Option C: Git Releases
+Host your plugin repository on GitHub/GitLab. Make sure it contains `plugin.json` in the root (or pre-compiled outputs). Administrators can install it dynamically by entering the Git clone URL inside the **Clone Git Repository** card.

package/bin/build.js

@@ -0,0 +1,46 @@
+import { build } from "esbuild";
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.join(__dirname, "..");
+
+async function run() {
+  console.log("Building PropVault PDK package...");
+  
+  // Clean dist
+  const distDir = path.join(rootDir, "dist");
+  if (fs.existsSync(distDir)) {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+
+  // 1. Compile TS with esbuild
+  await build({
+    entryPoints: [path.join(rootDir, "src", "index.ts")],
+    bundle: true,
+    platform: "node",
+    format: "esm",
+    outfile: path.join(distDir, "index.js"),
+    minify: false,
+    sourcemap: true,
+    external: []
+  });
+  console.log("✔ Compiled PDK ES modules successfully.");
+
+  // 2. Generate typings (.d.ts) using TypeScript compiler
+  try {
+    console.log("Generating typings (.d.ts)...");
+    execSync("npx tsc", { cwd: rootDir, stdio: "inherit" });
+    console.log("✔ Generated types successfully.");
+  } catch (err) {
+    console.warn("⚠ Warning: Failed to generate typings with tsc compiler:", err);
+  }
+
+  console.log("✔ PDK Build complete!");
+}
+
+run();

package/bin/pdk-cli.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+/**
+ * PropVault CMS — PDK CLI Utility
+ * Scaffolds, builds, and packages custom plugins for PropVault CMS.
+ */
+
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import archiver from "archiver";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const BANNER = `
+\x1b[38;5;214m  _____                 __   __            _ _     ____  ____  _  __
+ |  __ \\               \\ \\ / /           | | |   |  _ \\|  _ \\| |/ /
+ | |__) | __ ___  _ __  \\ V /__ _ _   _ _| | |_  | |_) | |_) | ' / 
+ |  ___/ '__/ _ \\| '_ \\  \\ / _\` | | | | | | __| |  __/|  _ <|  <  
+ | |   | | | (_) | |_) | | | (_| | |_| | | | |_  | |   | |_) | . \\ 
+ |_|   |_|  \\___/| .__/  |_|\\__,_|\\__,_|_|_|\\__| |_|   |____/|_|\\_\\
+                 |_|                                               
+\x1b[39m
+\x1b[90m  PropVault CMS Plugin Development Kit (PDK) CLI — v0.1.0\x1b[0m
+`;
+
+function printHelp() {
+  console.log(BANNER);
+  console.log("\x1b[1mUsage:\x1b[0m");
+  console.log("  npx propvault-pdk <command> [options]\n");
+  console.log("\x1b[1mCommands:\x1b[0m");
+  console.log("  \x1b[32mcreate <name>\x1b[0m         Scaffold a new custom plugin directory");
+  console.log("  \x1b[32mbuild\x1b[0m                 Compile TS/JS files and assemble distribution");
+  console.log("  \x1b[32mpackage\x1b[0m               Compress build distribution into plugin.zip for CMS upload");
+  console.log("\n\x1b[1mExamples:\x1b[0m");
+  console.log("  npx propvault-pdk create my-custom-integration");
+  console.log("  npx propvault-pdk build\n");
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  const workspaceRoot = process.cwd();
+
+  switch (command) {
+    case "create": {
+      const pluginName = args[1];
+      if (!pluginName) {
+        console.error("\x1b[31m[Error]\x1b[0m Please specify the plugin folder name: npx propvault-pdk create <plugin-name>");
+        process.exit(1);
+      }
+      
+      const slug = pluginName.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+      const destDir = path.join(workspaceRoot, slug);
+      
+      if (fs.existsSync(destDir)) {
+        console.error(`\x1b[31m[Error]\x1b[0m Directory "${slug}" already exists.`);
+        process.exit(1);
+      }
+
+      console.log(BANNER);
+      console.log(`\x1b[34m[Scaffold]\x1b[0m Creating plugin template for "${slug}"...`);
+
+      // Load local PDK version dynamically
+      let pdkVersion = "0.1.0";
+      try {
+        const pdkPkgPath = path.join(__dirname, "..", "package.json");
+        if (fs.existsSync(pdkPkgPath)) {
+          const pdkPkg = JSON.parse(fs.readFileSync(pdkPkgPath, "utf8"));
+          pdkVersion = pdkPkg.version || "0.1.0";
+        }
+      } catch {}
+
+      // 1. Create folders
+      fs.mkdirSync(path.join(destDir, "src"), { recursive: true });
+
+      // 2. Write package.json
+      const pkgContent = {
+        name: slug,
+        version: "1.0.0",
+        description: "Custom plugin integration for PropVault CMS",
+        main: "./dist/index.js",
+        type: "module",
+        scripts: {
+          "build": "npx propvault-pdk build",
+          "package": "npx propvault-pdk package"
+        },
+        dependencies: {},
+        devDependencies: {
+          "@vikukumar/propvault-pdk": `^${pdkVersion}`,
+          "typescript": "^5.3.3"
+        }
+      };
+      fs.writeFileSync(path.join(destDir, "package.json"), JSON.stringify(pkgContent, null, 2) + "\n");
+
+      // 3. Write tsconfig.json
+      const tsconfigContent = {
+        compilerOptions: {
+          target: "ES2022",
+          module: "NodeNext",
+          moduleResolution: "NodeNext",
+          strict: true,
+          skipLibCheck: true,
+          esModuleInterop: true,
+          outDir: "./dist"
+        },
+        include: ["src/**/*"]
+      };
+      fs.writeFileSync(path.join(destDir, "tsconfig.json"), JSON.stringify(tsconfigContent, null, 2) + "\n");
+
+      // 4. Write plugin.json manifest
+      const manifestContent = {
+        name: slug.split("-").map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(" "),
+        slug: slug,
+        version: "1.0.0",
+        description: "A custom plugin for real-time CRM webhooks and layout filters.",
+        author: "Developer",
+        entry: "./dist/index.js"
+      };
+      fs.writeFileSync(path.join(destDir, "plugin.json"), JSON.stringify(manifestContent, null, 2) + "\n");
+
+      // 5. Write src/index.ts (sample hooks integration)
+      const srcContent = `import { addAction, addFilter } from "@vikukumar/propvault-pdk";
+
+// Example Action: Triggered whenever a new lead is submitted on the website
+addAction("after_lead_submit", async (lead: any) => {
+  console.log("[${slug.toUpperCase()}] New lead submitted:", lead.email);
+  // Add custom integrations here (e.g. call Slack webhooks, SendGrid, Salesforce CRM, etc.)
+}, 10);
+
+// Example Filter: Modify the RERA project title before saving in database
+addFilter("before_project_save", async (project: any) => {
+  if (project.title) {
+    // Append verified suffix
+    project.title = \`\${project.title} [Verified]\`;
+  }
+  return project;
+});
+`;
+      fs.writeFileSync(path.join(destDir, "src", "index.ts"), srcContent);
+
+      console.log(`\x1b[32m✔ Scaffold complete! Plugin directory created at ./${slug}\x1b[0m`);
+      console.log("\x1b[1mNext Steps:\x1b[0m");
+      console.log(`  cd ${slug}`);
+      console.log("  npm install");
+      console.log("  npm run build && npm run package\n");
+      break;
+    }
+
+    case "build": {
+      console.log("\x1b[34m[Build]\x1b[0m Compiling custom plugin TypeScript entry points...");
+      
+      const pkgPath = path.join(workspaceRoot, "package.json");
+      if (!fs.existsSync(pkgPath)) {
+        console.error("\x1b[31m[Error]\x1b[0m package.json not found in active directory. Run from the plugin root directory.");
+        process.exit(1);
+      }
+
+      // Compile using local typescript compiler
+      try {
+        execSync("npx tsc", { cwd: workspaceRoot, stdio: "inherit" });
+        console.log("\x1b[32m✔ TypeScript compilation complete!\x1b[0m");
+      } catch (err) {
+        console.error("\x1b[31m[Error]\x1b[0m Compilation failed. Check syntax.");
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "package": {
+      console.log("\x1b[34m[Package]\x1b[0m Bundling plugin into zip distribution...");
+      
+      const manifestPath = path.join(workspaceRoot, "plugin.json");
+      const distJsPath = path.join(workspaceRoot, "dist", "index.js");
+
+      if (!fs.existsSync(manifestPath) || !fs.existsSync(distJsPath)) {
+        console.error("\x1b[31m[Error]\x1b[0m Build artifacts not found. Run 'npm run build' first.");
+        process.exit(1);
+      }
+
+      const archiveName = path.join(workspaceRoot, "plugin.zip");
+      const output = fs.createWriteStream(archiveName);
+      const archive = archiver("zip", { zlib: { level: 9 } });
+
+      output.on("close", () => {
+        console.log(`\x1b[32m✔ Zip packaging complete! Created archive: ./plugin.zip (${archive.pointer()} bytes)\x1b[0m`);
+        console.log("You can now upload this plugin.zip file in the PropVault CMS Plugins dashboard panel!");
+      });
+
+      archive.on("error", (err) => {
+        throw err;
+      });
+
+      archive.pipe(output);
+      
+      // Add compiled folder
+      archive.directory(path.join(workspaceRoot, "dist"), "dist");
+      // Add manifest
+      archive.file(manifestPath, { name: "plugin.json" });
+
+      await archive.finalize();
+      break;
+    }
+
+    default:
+      console.error(`\x1b[31m[Error]\x1b[0m Unknown command: ${command}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error("\x1b[31m[Error]\x1b[0m Operation failed:", err);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * PropVault CMS — Plugin Development Kit (PDK) Core API
+ */
+export interface HookAction {
+    slug: string;
+    handler: (...args: any[]) => void | Promise<void>;
+    priority?: number;
+}
+export interface HookFilter {
+    slug: string;
+    handler: (value: any, ...args: any[]) => any | Promise<any>;
+    priority?: number;
+}
+export interface PluginManifest {
+    name: string;
+    slug: string;
+    version: string;
+    description: string;
+    author: string;
+    entry: string;
+}
+/**
+ * Registers an action hook handler. Action hooks trigger code at specific system events.
+ */
+export declare function addAction(slug: string, handler: (...args: any[]) => void | Promise<void>, priority?: number): void;
+/**
+ * Registers a filter hook handler. Filter hooks allow modifying variables/inputs before they are stored/saved.
+ */
+export declare function addFilter(slug: string, handler: (value: any, ...args: any[]) => any | Promise<any>, priority?: number): void;

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * PropVault CMS — Plugin Development Kit (PDK) Core API
+ */
+/**
+ * Registers an action hook handler. Action hooks trigger code at specific system events.
+ */
+export function addAction(slug, handler, priority = 10) {
+    if (typeof window !== "undefined")
+        return;
+    // Register dynamic handler into global hooks registry
+    const globalHooks = globalThis.__propvault_hooks || { actions: {}, filters: {} };
+    if (!globalHooks.actions[slug]) {
+        globalHooks.actions[slug] = [];
+    }
+    globalHooks.actions[slug].push({ handler, priority });
+    globalHooks.actions[slug].sort((a, b) => a.priority - b.priority);
+    globalThis.__propvault_hooks = globalHooks;
+}
+/**
+ * Registers a filter hook handler. Filter hooks allow modifying variables/inputs before they are stored/saved.
+ */
+export function addFilter(slug, handler, priority = 10) {
+    if (typeof window !== "undefined")
+        return;
+    const globalHooks = globalThis.__propvault_hooks || { actions: {}, filters: {} };
+    if (!globalHooks.filters[slug]) {
+        globalHooks.filters[slug] = [];
+    }
+    globalHooks.filters[slug].push({ handler, priority });
+    globalHooks.filters[slug].sort((a, b) => a.priority - b.priority);
+    globalThis.__propvault_hooks = globalHooks;
+}

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["/**\n * PropVault CMS \u2014 Plugin Development Kit (PDK) Core API\n */\n\nexport interface HookAction {\n  slug: string;\n  handler: (...args: any[]) => void | Promise<void>;\n  priority?: number;\n}\n\nexport interface HookFilter {\n  slug: string;\n  handler: (value: any, ...args: any[]) => any | Promise<any>;\n  priority?: number;\n}\n\nexport interface PluginManifest {\n  name: string;\n  slug: string;\n  version: string;\n  description: string;\n  author: string;\n  entry: string;\n}\n\n/**\n * Registers an action hook handler. Action hooks trigger code at specific system events.\n */\nexport function addAction(slug: string, handler: (...args: any[]) => void | Promise<void>, priority = 10): void {\n  if (typeof window !== \"undefined\") return;\n  \n  // Register dynamic handler into global hooks registry\n  const globalHooks = (globalThis as any).__propvault_hooks || { actions: {}, filters: {} };\n  if (!globalHooks.actions[slug]) {\n    globalHooks.actions[slug] = [];\n  }\n  \n  globalHooks.actions[slug].push({ handler, priority });\n  globalHooks.actions[slug].sort((a: any, b: any) => a.priority - b.priority);\n  \n  (globalThis as any).__propvault_hooks = globalHooks;\n}\n\n/**\n * Registers a filter hook handler. Filter hooks allow modifying variables/inputs before they are stored/saved.\n */\nexport function addFilter(slug: string, handler: (value: any, ...args: any[]) => any | Promise<any>, priority = 10): void {\n  if (typeof window !== \"undefined\") return;\n  \n  const globalHooks = (globalThis as any).__propvault_hooks || { actions: {}, filters: {} };\n  if (!globalHooks.filters[slug]) {\n    globalHooks.filters[slug] = [];\n  }\n  \n  globalHooks.filters[slug].push({ handler, priority });\n  globalHooks.filters[slug].sort((a: any, b: any) => a.priority - b.priority);\n  \n  (globalThis as any).__propvault_hooks = globalHooks;\n}\n"],
+  "mappings": ";AA4BO,SAAS,UAAU,MAAc,SAAmD,WAAW,IAAU;AAC9G,MAAI,OAAO,WAAW;AAAa;AAGnC,QAAM,cAAe,WAAmB,qBAAqB,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC,EAAE;AACxF,MAAI,CAAC,YAAY,QAAQ,IAAI,GAAG;AAC9B,gBAAY,QAAQ,IAAI,IAAI,CAAC;AAAA,EAC/B;AAEA,cAAY,QAAQ,IAAI,EAAE,KAAK,EAAE,SAAS,SAAS,CAAC;AACpD,cAAY,QAAQ,IAAI,EAAE,KAAK,CAAC,GAAQ,MAAW,EAAE,WAAW,EAAE,QAAQ;AAE1E,EAAC,WAAmB,oBAAoB;AAC1C;AAKO,SAAS,UAAU,MAAc,SAA6D,WAAW,IAAU;AACxH,MAAI,OAAO,WAAW;AAAa;AAEnC,QAAM,cAAe,WAAmB,qBAAqB,EAAE,SAAS,CAAC,GAAG,SAAS,CAAC,EAAE;AACxF,MAAI,CAAC,YAAY,QAAQ,IAAI,GAAG;AAC9B,gBAAY,QAAQ,IAAI,IAAI,CAAC;AAAA,EAC/B;AAEA,cAAY,QAAQ,IAAI,EAAE,KAAK,EAAE,SAAS,SAAS,CAAC;AACpD,cAAY,QAAQ,IAAI,EAAE,KAAK,CAAC,GAAQ,MAAW,EAAE,WAAW,EAAE,QAAQ;AAE1E,EAAC,WAAmB,oBAAoB;AAC1C;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@vikukumar/propvault-pdk",
+  "version": "0.1.4",
+  "description": "Plugin Development Kit (PDK) for the PropVault CMS Platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "propvault-pdk": "./bin/pdk-cli.js"
+  },
+  "scripts": {
+    "build": "node bin/build.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "archiver": "^6.0.2",
+    "esbuild": "^0.20.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,59 @@
+/**
+ * PropVault CMS — Plugin Development Kit (PDK) Core API
+ */
+
+export interface HookAction {
+  slug: string;
+  handler: (...args: any[]) => void | Promise<void>;
+  priority?: number;
+}
+
+export interface HookFilter {
+  slug: string;
+  handler: (value: any, ...args: any[]) => any | Promise<any>;
+  priority?: number;
+}
+
+export interface PluginManifest {
+  name: string;
+  slug: string;
+  version: string;
+  description: string;
+  author: string;
+  entry: string;
+}
+
+/**
+ * Registers an action hook handler. Action hooks trigger code at specific system events.
+ */
+export function addAction(slug: string, handler: (...args: any[]) => void | Promise<void>, priority = 10): void {
+  if (typeof window !== "undefined") return;
+  
+  // Register dynamic handler into global hooks registry
+  const globalHooks = (globalThis as any).__propvault_hooks || { actions: {}, filters: {} };
+  if (!globalHooks.actions[slug]) {
+    globalHooks.actions[slug] = [];
+  }
+  
+  globalHooks.actions[slug].push({ handler, priority });
+  globalHooks.actions[slug].sort((a: any, b: any) => a.priority - b.priority);
+  
+  (globalThis as any).__propvault_hooks = globalHooks;
+}
+
+/**
+ * Registers a filter hook handler. Filter hooks allow modifying variables/inputs before they are stored/saved.
+ */
+export function addFilter(slug: string, handler: (value: any, ...args: any[]) => any | Promise<any>, priority = 10): void {
+  if (typeof window !== "undefined") return;
+  
+  const globalHooks = (globalThis as any).__propvault_hooks || { actions: {}, filters: {} };
+  if (!globalHooks.filters[slug]) {
+    globalHooks.filters[slug] = [];
+  }
+  
+  globalHooks.filters[slug].push({ handler, priority });
+  globalHooks.filters[slug].sort((a: any, b: any) => a.priority - b.priority);
+  
+  (globalThis as any).__propvault_hooks = globalHooks;
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"]
+}