@chigisoft-web/cms-sdk 1.0.3

package/README.md

@@ -0,0 +1,278 @@
+# @chigisoft-web/cms-sdk
+
+A lightweight, TypeScript-first SDK to dynamically fetch and display content from ChigiSoft CMS in your custom frontend applications. Works out-of-the-box in **Nuxt 3/4** and **Next.js**.
+
+## Installation
+
+Install the package via npm or yarn:
+
+```bash
+npm install @chigisoft-web/cms-sdk
+# or
+yarn add @chigisoft-web/cms-sdk
+```
+
+### Quick Setup Wizard ⚡
+
+You can automatically configure your project's environment variables (`CHIGISOFT_PROJECT_ID`, `CHIGISOFT_API_TOKEN`, and `CHIGISOFT_STUDIO_URL`), generate the client setup helpers, and create the dynamic `/studio` routing pages using the interactive CLI wizard:
+
+```bash
+npx @chigisoft-web/cms-sdk
+```
+*(If the package is already installed locally in your workspace, you can run `npx chigisoft` instead).*
+
+---
+
+## Getting Started
+
+### 1. Zero-Configuration (Recommended)
+If you have set the environment variables `CHIGISOFT_PROJECT_ID` and `CHIGISOFT_API_TOKEN` in your project (`.env` file or hosting provider), you can initialize the client without arguments:
+
+```typescript
+import { createClient } from '@chigisoft-web/cms-sdk';
+
+const chigisoft = createClient();
+```
+
+### 2. Manual Configuration
+You can also pass config values explicitly:
+
+```typescript
+import { createClient } from '@chigisoft-web/cms-sdk';
+
+const chigisoft = createClient({
+  projectId: 'your-project-id',
+  token: 'your-access-token',
+  // Optional: override API endpoint for local development
+  // baseUrl: 'http://localhost:3000',
+  // useCdn: true
+});
+```
+
+### Browser / Script Tag (cPanel / Static HTML)
+
+For static HTML sites or environments like cPanel where you do not run a Node build step, you can include the pre-built global script:
+
+1. Upload the `dist/index.global.js` bundle to your host.
+2. Load it in your HTML:
+
+```html
+<!-- Load the global SDK client -->
+<script src="./dist/index.global.js"></script>
+<script>
+  // The SDK is exposed on the global `ChigiSoft` object
+  const chigisoft = ChigiSoft.createClient({
+    projectId: 'your-project-id',
+    token: 'your-access-token'
+  });
+
+  // Fetch blogs
+  chigisoft.getBlogs().then(blogs => {
+    console.log('Blogs:', blogs);
+  });
+</script>
+```
+
+---
+
+## Content Module Integration Guides
+
+ChigiSoft CMS organizes your website content into four core modules: **Pages**, **Blogs**, **Menus**, and **Testimonies**.
+
+### 1. Pages Module
+
+Dynamic pages consist of structured visual blocks (such as headings, rich text, images, and call-to-actions) constructed inside the CMS Page Builder.
+
+```tsx
+// Example: Rendering a page inside a Next.js Server Component
+import { createClient } from '@chigisoft-web/cms-sdk';
+import { notFound } from 'next/navigation';
+
+const chigisoft = createClient();
+
+export default async function CMSPage({ params }: { params: { slug: string } }) {
+  const page = await chigisoft.getPageBySlug(params.slug);
+  if (!page) notFound();
+
+  return (
+    <main className="max-w-4xl mx-auto py-12 px-6">
+      <h1 className="text-4xl font-bold mb-8">{page.title}</h1>
+      
+      {/* Loop through blocks and render corresponding UI components */}
+      <div className="space-y-8">
+        {page.blocks.map((block) => {
+          switch (block.type) {
+            case 'heading':
+              return <h2 key={block.id} className="text-2xl font-semibold">{block.content.text}</h2>;
+            case 'richText':
+              return <div key={block.id} className="prose" dangerouslySetInnerHTML={{ __html: block.content.html || block.content.text }} />;
+            case 'image':
+              return <img key={block.id} src={block.content.mediaUrl} alt={block.content.alt || ''} className="rounded-lg shadow-lg" />;
+            case 'ctaStrip':
+              return (
+                <div key={block.id} className="p-6 bg-brand-50 border rounded-xl flex items-center justify-between">
+                  <div>
+                    <h3 className="text-lg font-bold">{block.content.heading}</h3>
+                    <p className="text-sm text-gray-600">{block.content.body}</p>
+                  </div>
+                  <a href={block.content.primaryUrl} className="px-4 py-2 bg-brand-600 text-white rounded-lg">{block.content.primaryLabel}</a>
+                </div>
+              );
+            default:
+              return null;
+          }
+        })}
+      </div>
+    </main>
+  );
+}
+```
+
+### 2. Blogs Module
+
+Blog posts represent long-form articles/news which can contain structured blocks similar to pages.
+
+```vue
+<!-- Example: Fetching and rendering a blog in a Vue / Nuxt Page component -->
+<script setup lang="ts">
+import { createClient } from '@chigisoft-web/cms-sdk';
+
+const route = useRoute();
+const chigisoft = createClient();
+
+const { data: blog } = await useAsyncData(`blog-${route.params.slug}`, () => 
+  chigisoft.getBlogBySlug(route.params.slug as string)
+);
+</script>
+
+<template>
+  <article v-if="blog" class="max-w-3xl mx-auto py-12">
+    <h1 class="text-4xl font-extrabold mb-4">{{ blog.title }}</h1>
+    <p class="text-gray-500 mb-8">Published on {{ new Date(blog.createdAt).toLocaleDateString() }}</p>
+    
+    <div class="space-y-6">
+      <div v-for="block in blog.blocks" :key="block.id">
+        <p v-if="block.type === 'richText'" v-html="block.content.html || block.content.text"></p>
+        <img v-else-if="block.type === 'image'" :src="block.content.mediaUrl" :alt="block.content.alt" class="rounded-lg" />
+      </div>
+    </div>
+  </article>
+</template>
+```
+
+### 3. Menus Module
+
+Retrieve navigation structures (headers, sidebars, footers) and their items, supporting custom external links as well as items linked to internal CMS pages.
+
+```typescript
+// Fetching a navigation structure by name
+import { createClient } from '@chigisoft-web/cms-sdk';
+
+const chigisoft = createClient();
+
+async function renderHeader() {
+  const menu = await chigisoft.getMenuByName('header');
+  if (!menu) return;
+
+  console.log(`Menu: ${menu.name}`);
+  // items are sorted by their configured order
+  menu.items.forEach((item) => {
+    const linkUrl = item.pageId ? `/pages/${item.pageId}` : item.url;
+    console.log(` - Link: ${item.label} -> ${linkUrl} (New Tab: ${item.openInNewTab})`);
+  });
+}
+```
+
+### 4. Testimonies Module
+
+Testimonies capture user feedback, reviews, and quotes.
+
+```typescript
+// Fetch and display client testimonials
+import { createClient } from '@chigisoft-web/cms-sdk';
+
+const chigisoft = createClient();
+
+async function loadTestimonials() {
+  const testimonies = await chigisoft.getTestimonies();
+  testimonies.forEach((testimony) => {
+    console.log(`Client: ${testimony.title}`);
+    console.log(`Quote: ${testimony.description}`);
+  });
+}
+```
+
+---
+
+## API Reference
+
+### `ChigiSoftClient`
+
+#### `getPages(options?)`
+Fetches all pages matching the configured project ID.
+* **Arguments:** `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSPage[]>`
+
+#### `getPageBySlug(slug, options?)`
+Fetches a specific page by its URL slug or ID. Returns `null` if not found.
+* **Arguments:**
+  - `slug: string`
+  - `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSPage | null>`
+
+#### `getBlogs(options?)`
+Fetches all blog posts matching the configured project ID.
+* **Arguments:** `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSBlog[]>`
+
+#### `getBlogBySlug(slug, options?)`
+Fetches a specific blog post by its URL slug or ID. Returns `null` if not found.
+* **Arguments:**
+  - `slug: string`
+  - `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSBlog | null>`
+
+#### `getTestimonies(options?)`
+Fetches all client testimonies matching the configured project ID.
+* **Arguments:** `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSTestimony[]>`
+
+#### `getTestimonyBySlug(slug, options?)`
+Fetches a specific testimony by its slug or ID. Returns `null` if not found.
+* **Arguments:**
+  - `slug: string`
+  - `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSTestimony | null>`
+
+#### `getMenus(options?)`
+Fetches all navigation menus for the project.
+* **Arguments:** `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSMenu[]>`
+
+#### `getMenuById(id, options?)`
+Fetches a specific menu structure by its ID.
+* **Arguments:**
+  - `id: string`
+  - `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSMenu | null>`
+
+#### `getMenuByName(name, options?)`
+Fetches a specific menu structure by its name (e.g., `'header'`, `'sidebar'`).
+* **Arguments:**
+  - `name: string`
+  - `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<CMSMenu | null>`
+
+#### `fetch(path, options?)`
+Executes a generic GET request to any endpoint on the CMS. Useful for querying custom endpoints.
+* **Arguments:**
+  - `path: string` (e.g., `'/v1/audits'`)
+  - `options?: ChigiSoftRequestInit`
+* **Returns:** `Promise<T>`
+
+#### `mountStudio(target, options?)`
+Embeds the CMS dashboard iframe inside the DOM container.
+* **Arguments:**
+  - `target: string | HTMLElement`
+  - `options?: { studioUrl?: string; style?: Partial<CSSStyleDeclaration> }`
+* **Returns:** `HTMLIFrameElement`

package/dist/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_readline = __toESM(require("readline"));
+var import_fs = __toESM(require("fs"));
+var import_path = __toESM(require("path"));
+var rl = import_readline.default.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+var askQuestion = (query) => {
+  return new Promise((resolve) => {
+    rl.question(query, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+};
+function writeEnv(envFile, projectId, token) {
+  const envPath = import_path.default.join(process.cwd(), envFile);
+  let content = "";
+  if (import_fs.default.existsSync(envPath)) {
+    content = import_fs.default.readFileSync(envPath, "utf8");
+  }
+  if (content && !content.endsWith("\n")) {
+    content += "\n";
+  }
+  let updated = false;
+  if (!content.includes("CHIGISOFT_PROJECT_ID")) {
+    content += `CHIGISOFT_PROJECT_ID="${projectId}"
+`;
+    updated = true;
+  } else {
+    console.log(`\u26A0\uFE0F  CHIGISOFT_PROJECT_ID is already defined in ${envFile}. Skipping overwrite.`);
+  }
+  if (!content.includes("CHIGISOFT_API_TOKEN")) {
+    content += `CHIGISOFT_API_TOKEN="${token}"
+`;
+    updated = true;
+  } else {
+    console.log(`\u26A0\uFE0F  CHIGISOFT_API_TOKEN is already defined in ${envFile}. Skipping overwrite.`);
+  }
+  if (!content.includes("CHIGISOFT_STUDIO_URL")) {
+    content += `CHIGISOFT_STUDIO_URL="https://cms.staging.chigisoft.co"
+`;
+    updated = true;
+  } else {
+    console.log(`\u26A0\uFE0F  CHIGISOFT_STUDIO_URL is already defined in ${envFile}. Skipping overwrite.`);
+  }
+  if (updated) {
+    import_fs.default.writeFileSync(envPath, content, "utf8");
+    console.log(`\u2705 Updated ${envFile} successfully with configurations.`);
+  }
+}
+function ensureDir(dirPath) {
+  const absolutePath = import_path.default.join(process.cwd(), dirPath);
+  if (!import_fs.default.existsSync(absolutePath)) {
+    import_fs.default.mkdirSync(absolutePath, { recursive: true });
+  }
+}
+async function main() {
+  console.log("\n===========================================");
+  console.log("      chigisoft-cms SDK Setup Wizard \u{1F680}    ");
+  console.log("===========================================\n");
+  console.log("Choose your framework:");
+  console.log("1. Next.js (App Router)");
+  console.log("2. Nuxt.js (3/4)");
+  console.log("3. Vanilla HTML / JS");
+  const frameworkChoice = await askQuestion("\nEnter framework number (1-3): ");
+  if (!["1", "2", "3"].includes(frameworkChoice)) {
+    console.error("\u274C Invalid choice. Exiting setup.");
+    rl.close();
+    process.exit(1);
+  }
+  const projectId = await askQuestion("Enter your ChigiSoft Project ID/Slug: ");
+  if (!projectId) {
+    console.error("\u274C Project ID is required. Exiting setup.");
+    rl.close();
+    process.exit(1);
+  }
+  const token = await askQuestion("Enter your ChigiSoft Access Token: ");
+  if (!token) {
+    console.error("\u274C Access Token is required. Exiting setup.");
+    rl.close();
+    process.exit(1);
+  }
+  if (frameworkChoice === "1") {
+    console.log("\n\u{1F527} Setting up Next.js integration...");
+    writeEnv(".env.local", projectId, token);
+    ensureDir("lib");
+    const clientFileContent = `import { createClient } from '@chigisoft-web/cms-sdk';
+
+export const chigisoft = createClient();
+`;
+    import_fs.default.writeFileSync(import_path.default.join(process.cwd(), "lib/chigisoft.ts"), clientFileContent, "utf8");
+    console.log("\u2705 Created library helper at lib/chigisoft.ts");
+    ensureDir("app/studio");
+    const studioClientContent = `"use client";
+
+import { useEffect, useRef } from "react";
+import { createClient } from "@chigisoft-web/cms-sdk";
+
+interface StudioClientProps {
+  projectId: string;
+  token: string;
+  studioUrl?: string;
+}
+
+export default function StudioClient({ projectId, token, studioUrl }: StudioClientProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    try {
+      const client = createClient({
+        projectId,
+        token,
+      });
+
+      client.mountStudio(containerRef.current, {
+        studioUrl: studioUrl || "http://localhost:3000",
+        style: {
+          width: "100%",
+          height: "100vh",
+          border: "none",
+        }
+      });
+    } catch (error) {
+      console.error("[ChigiSoft] Failed to mount studio:", error);
+    }
+  }, [projectId, token, studioUrl]);
+
+  return (
+    <div style={{ width: "100%", height: "100vh", overflow: "hidden", background: "#111" }}>
+      <div ref={containerRef} />
+    </div>
+  );
+}
+`;
+    import_fs.default.writeFileSync(import_path.default.join(process.cwd(), "app/studio/StudioClient.tsx"), studioClientContent, "utf8");
+    console.log("\u2705 Created studio UI component at app/studio/StudioClient.tsx");
+    const studioPageContent = `import StudioClient from "./StudioClient";
+
+export default function StudioPage() {
+  const projectId = process.env.CHIGISOFT_PROJECT_ID || "";
+  const token = process.env.CHIGISOFT_API_TOKEN || "";
+  const studioUrl = process.env.CHIGISOFT_STUDIO_URL || "https://cms.staging.chigisoft.co";
+
+  if (!projectId || !token) {
+    return (
+      <div style={{ padding: "40px", fontFamily: "sans-serif", color: "#fff", background: "#1e1f21", height: "100vh" }}>
+        <h1>ChigiSoft CMS Setup Incomplete</h1>
+        <p>Please check your <code>.env.local</code> file and configure:</p>
+        <pre style={{ background: "#2a2b2d", padding: "16px", borderRadius: "8px", color: "#60a5fa" }}>
+{\`CHIGISOFT_PROJECT_ID="your-project-id"
+CHIGISOFT_API_TOKEN="your-api-token"
+CHIGISOFT_STUDIO_URL="https://cms.staging.chigisoft.co" (optional)\`}
+        </pre>
+      </div>
+    );
+  }
+
+  return (
+    <StudioClient
+      projectId={projectId}
+      token={token}
+      studioUrl={studioUrl}
+    />
+  );
+}
+`;
+    import_fs.default.writeFileSync(import_path.default.join(process.cwd(), "app/studio/page.tsx"), studioPageContent, "utf8");
+    console.log("\u2705 Created studio page router at app/studio/page.tsx");
+    console.log("\n\u{1F389} Next.js Setup Complete!");
+    console.log("You can now:");
+    console.log('1. Import the client helper in components: `import { chigisoft } from "@/lib/chigisoft";`');
+    console.log("2. Access the CMS login/dashboard from the `/studio` route of your site.");
+  } else if (frameworkChoice === "2") {
+    console.log("\n\u{1F527} Setting up Nuxt.js integration...");
+    writeEnv(".env", projectId, token);
+    ensureDir("plugins");
+    const pluginContent = `import { createClient } from '@chigisoft-web/cms-sdk';
+
+export default defineNuxtPlugin(() => {
+  // Auto-resolves CHIGISOFT_PROJECT_ID and CHIGISOFT_API_TOKEN from your .env variables
+  const client = createClient();
+
+  return {
+    provide: {
+      chigisoft: client
+    }
+  };
+});
+`;
+    import_fs.default.writeFileSync(import_path.default.join(process.cwd(), "plugins/chigisoft.ts"), pluginContent, "utf8");
+    console.log("\u2705 Created Nuxt client plugin at plugins/chigisoft.ts");
+    const isNuxt4 = import_fs.default.existsSync(import_path.default.join(process.cwd(), "app"));
+    const pagesDir = isNuxt4 ? "app/pages" : "pages";
+    ensureDir(pagesDir);
+    const nuxtStudioPageContent = `<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+import { createClient } from '@chigisoft-web/cms-sdk';
+
+const containerRef = ref<HTMLElement | null>(null);
+
+onMounted(() => {
+  if (!containerRef.value) return;
+
+  const client = createClient();
+  const env = (globalThis as any).process?.env || {};
+  const studioUrl = env.CHIGISOFT_STUDIO_URL || 'https://cms.staging.chigisoft.co';
+
+  client.mountStudio(containerRef.value, {
+    studioUrl,
+    style: {
+      width: '100%',
+      height: '100vh',
+      border: 'none',
+    }
+  });
+});
+</script>
+
+<template>
+  <div style="width: 100%; height: 100vh; overflow: hidden; background: #111;">
+    <div ref="containerRef" />
+  </div>
+</template>
+`;
+    import_fs.default.writeFileSync(import_path.default.join(process.cwd(), pagesDir, "studio.vue"), nuxtStudioPageContent, "utf8");
+    console.log(`\u2705 Created studio page at ${pagesDir}/studio.vue`);
+    console.log("\n\u{1F389} Nuxt.js Setup Complete!");
+    console.log("You can now:");
+    console.log("1. Access the client from Nuxt context: `const { $chigisoft } = useNuxtApp();`");
+    console.log("2. Access the CMS login/dashboard from the `/studio` route of your site.");
+  } else if (frameworkChoice === "3") {
+    console.log("\n\u{1F527} Setting up Vanilla HTML/JS demo...");
+    const demoHtmlContent = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>ChigiSoft CMS Demo</title>
+  <!-- Load the global SDK client -->
+  <script src="https://cdn.jsdelivr.net/npm/@chigisoft-web/cms-sdk/dist/index.global.js"></script>
+</head>
+<body>
+  <h1>ChigiSoft CMS Integration</h1>
+  <div id="blogs-container">Loading blogs...</div>
+
+  <script>
+    // Initialize the CMS client
+    const chigisoft = ChigiSoft.createClient({
+      projectId: '${projectId}',
+      token: '${token}'
+    });
+
+    // Fetch and display blogs
+    chigisoft.getBlogs()
+      .then(blogs => {
+        const container = document.getElementById('blogs-container');
+        if (blogs.length === 0) {
+          container.textContent = 'No blog posts found.';
+          return;
+        }
+        container.innerHTML = '<ul>' + blogs.map(blog => '<li>' + blog.title + '</li>').join('') + '</ul>';
+      })
+      .catch(error => {
+        console.error('Error fetching blogs:', error);
+        document.getElementById('blogs-container').textContent = 'Error loading content.';
+      });
+  </script>
+</body>
+</html>
+`;
+    import_fs.default.writeFileSync(import_path.default.join(process.cwd(), "chigisoft-demo.html"), demoHtmlContent, "utf8");
+    console.log("\u2705 Created demo file at chigisoft-demo.html");
+    console.log("\n\u{1F389} Vanilla Setup Complete!");
+    console.log("Open `chigisoft-demo.html` in your browser to view your dynamic CMS contents!");
+  }
+  console.log("\n===========================================");
+  console.log("             Enjoy building! \u{1F4BB}            ");
+  console.log("===========================================\n");
+  rl.close();
+}
+main().catch((error) => {
+  console.error("\u274C An unexpected error occurred during setup:", error);
+  rl.close();
+  process.exit(1);
+});