@aravindc26/velu 0.11.14 → 0.11.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aravindc26/velu",
-  "version": "0.11.14",
+  "version": "0.11.16",
   "description": "A modern documentation site generator powered by Markdown and JSON configuration",
   "type": "module",
   "license": "MIT",

package/src/build.ts

@@ -9,11 +9,12 @@ import { normalizeConfigNavigation } from "./navigation-normalize.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PACKAGED_ENGINE_DIR = join(__dirname, "engine");
-const DEV_ENGINE_DIR = join(__dirname, "..", "src", "engine");
-const ENGINE_DIR = existsSync(DEV_ENGINE_DIR) ? DEV_ENGINE_DIR : PACKAGED_ENGINE_DIR;
-const PRIMARY_CONFIG_NAME = "docs.json";
-const LEGACY_CONFIG_NAME = "velu.json";
-const SOURCE_MIRROR_DIR = "velu-imports";
+const DEV_ENGINE_DIR = join(__dirname, "..", "src", "engine");
+const ENGINE_DIR = existsSync(DEV_ENGINE_DIR) ? DEV_ENGINE_DIR : PACKAGED_ENGINE_DIR;
+const CLI_PACKAGE_JSON_PATH = join(__dirname, "..", "package.json");
+const PRIMARY_CONFIG_NAME = "docs.json";
+const LEGACY_CONFIG_NAME = "velu.json";
+const SOURCE_MIRROR_DIR = "velu-imports";
 
 const SOURCE_MIRROR_EXTENSIONS = new Set([
   ".md", ".mdx", ".jsx", ".js", ".tsx", ".ts",
@@ -630,10 +631,24 @@ function resolveProjectDescription(config: VeluConfig): string {
   return "";
 }
 
+function resolveCliVersion(): string {
+  try {
+    const raw = readFileSync(CLI_PACKAGE_JSON_PATH, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+      return parsed.version.trim();
+    }
+  } catch {
+    // ignore and fallback
+  }
+  return "unknown";
+}
+
 function writeProjectConstFile(config: VeluConfig, outDir: string) {
   const constPayload = {
     name: resolveProjectName(config),
     description: resolveProjectDescription(config),
+    version: resolveCliVersion(),
   };
 
   const constPath = join(outDir, "public", "const.json");

package/src/cli.ts

@@ -35,6 +35,7 @@ function printHelp() {
   velu — documentation site generator
 
   Usage:
+    velu version           Print Velu CLI version
     velu init              Scaffold a new docs project with example files
     velu lint              Validate docs.json (or velu.json) and check referenced pages
     velu run [--port N]    Build site and start dev server (default: 4321)
@@ -42,6 +43,7 @@ function printHelp() {
     velu paths             Output navigation paths and source files as JSON (grouped by language)
 
   Options:
+    --version         Show Velu CLI version
     --port <number>   Port for the dev server (default: 4321)
     --help            Show this help message
 
@@ -49,6 +51,24 @@ function printHelp() {
 `);
 }
 
+function getCliVersion(): string {
+  try {
+    const pkgPath = join(PACKAGE_ROOT, "package.json");
+    const raw = readFileSync(pkgPath, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+      return parsed.version.trim();
+    }
+  } catch {
+    // ignore and fallback
+  }
+  return "unknown";
+}
+
+function printVersion() {
+  console.log(getCliVersion());
+}
+
 // ── init ────────────────────────────────────────────────────────────────────────
 
 function init(targetDir: string) {
@@ -495,6 +515,11 @@ if (!command || command === "--help" || command === "-h") {
   process.exit(0);
 }
 
+if (command === "version" || command === "--version" || command === "-v") {
+  printVersion();
+  process.exit(0);
+}
+
 const docsDir = process.cwd();
 
 // init doesn't require docs.json

package/src/engine/components/page-feedback-api.test.ts

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildPublicFeedbackPayload,
+  PUBLIC_API_BASE_URL,
+  PUBLIC_FEEDBACK_ENDPOINT_PATH,
+  resolvePublicFeedbackEndpoint,
+  submitPublicFeedback,
+} from './page-feedback-api';
+
+test('buildPublicFeedbackPayload returns contract body with optional fields', () => {
+  const payload = buildPublicFeedbackPayload({
+    pageUrl: 'https://docs.example.com/guide',
+    helpful: true,
+    reasonText: 'The guide worked as expected',
+    details: '  Extra details  ',
+    email: '  user@example.com  ',
+  });
+
+  assert.deepEqual(payload, {
+    page_url: 'https://docs.example.com/guide',
+    helpful: true,
+    reason_text: 'The guide worked as expected',
+    details: 'Extra details',
+    email: 'user@example.com',
+  });
+});
+
+test('resolvePublicFeedbackEndpoint appends the fixed endpoint path', () => {
+  assert.equal(
+    resolvePublicFeedbackEndpoint(),
+    `${PUBLIC_API_BASE_URL}${PUBLIC_FEEDBACK_ENDPOINT_PATH}`,
+  );
+});
+
+test('submitPublicFeedback posts the expected payload and headers', async () => {
+  let receivedUrl = '';
+  let receivedInit: RequestInit | undefined;
+
+  const fetchImpl: typeof fetch = async (input, init) => {
+    receivedUrl = String(input);
+    receivedInit = init;
+    return new Response(null, { status: 204 });
+  };
+
+  const result = await submitPublicFeedback({
+    pageUrl: 'https://docs.example.com/page',
+    helpful: false,
+    reasonText: 'Update this documentation',
+    details: '',
+    email: undefined,
+    siteHost: 'docs.example.com',
+    fetchImpl,
+  });
+
+  assert.deepEqual(result, { ok: true });
+  assert.equal(receivedUrl, `${PUBLIC_API_BASE_URL}${PUBLIC_FEEDBACK_ENDPOINT_PATH}`);
+  assert.equal(receivedInit?.method, 'POST');
+  assert.equal(receivedInit?.credentials, 'include');
+  assert.equal(receivedInit?.body, JSON.stringify({
+    page_url: 'https://docs.example.com/page',
+    helpful: false,
+    reason_text: 'Update this documentation',
+  }));
+
+  const headers = receivedInit?.headers as Record<string, string>;
+  assert.deepEqual(headers, {
+    'Content-Type': 'application/json',
+    'x-velu-site-host': 'docs.example.com',
+  });
+});
+
+test('submitPublicFeedback reports non-2xx responses as request_failed', async () => {
+  const result = await submitPublicFeedback({
+    pageUrl: 'https://docs.example.com/page',
+    helpful: true,
+    reasonText: 'Something else',
+    siteHost: 'docs.example.com',
+    fetchImpl: async () => new Response(null, { status: 500 }),
+  });
+
+  assert.deepEqual(result, { ok: false, reason: 'request_failed', status: 500 });
+});

package/src/engine/components/page-feedback-api.ts

@@ -0,0 +1,89 @@
+export const PUBLIC_FEEDBACK_ENDPOINT_PATH = '/api/v1/public/feedback';
+export const PUBLIC_API_BASE_URL = 'https://api.getvelu.com';
+
+export interface PublicFeedbackPayload {
+  page_url: string;
+  helpful: boolean;
+  reason_text: string;
+  details?: string;
+  email?: string;
+}
+
+interface BuildPayloadInput {
+  pageUrl: string;
+  helpful: boolean;
+  reasonText: string;
+  details?: string;
+  email?: string;
+}
+
+export interface SubmitPublicFeedbackInput extends BuildPayloadInput {
+  siteHost: string;
+  fetchImpl?: typeof fetch;
+}
+
+type SubmitErrorReason = 'invalid_payload' | 'request_failed' | 'network_error';
+
+export type SubmitPublicFeedbackResult =
+  | { ok: true }
+  | { ok: false; reason: SubmitErrorReason; status?: number };
+
+function trimOptional(value: string | undefined): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function resolvePublicFeedbackEndpoint(): string {
+  return `${PUBLIC_API_BASE_URL}${PUBLIC_FEEDBACK_ENDPOINT_PATH}`;
+}
+
+export function buildPublicFeedbackPayload(input: BuildPayloadInput): PublicFeedbackPayload | null {
+  const pageUrl = trimOptional(input.pageUrl);
+  const reasonText = trimOptional(input.reasonText);
+  if (!pageUrl || !reasonText) return null;
+
+  const payload: PublicFeedbackPayload = {
+    page_url: pageUrl,
+    helpful: input.helpful,
+    reason_text: reasonText,
+  };
+
+  const details = trimOptional(input.details);
+  if (details) payload.details = details;
+
+  const email = trimOptional(input.email);
+  if (email) payload.email = email;
+
+  return payload;
+}
+
+export async function submitPublicFeedback(input: SubmitPublicFeedbackInput): Promise<SubmitPublicFeedbackResult> {
+  const payload = buildPublicFeedbackPayload(input);
+  if (!payload) return { ok: false, reason: 'invalid_payload' };
+
+  const fetchImpl = input.fetchImpl ?? fetch;
+  try {
+    const response = await fetchImpl(resolvePublicFeedbackEndpoint(), {
+      method: 'POST',
+      credentials: 'include',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-velu-site-host': input.siteHost,
+      },
+      body: JSON.stringify(payload),
+    });
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        reason: 'request_failed',
+        status: response.status,
+      };
+    }
+
+    return { ok: true };
+  } catch {
+    return { ok: false, reason: 'network_error' };
+  }
+}

package/src/engine/components/page-feedback.tsx

@@ -2,6 +2,7 @@
 
 import { useState, type MouseEvent as ReactMouseEvent } from 'react';
 import { ThumbsDown, ThumbsUp } from 'lucide-react';
+import { submitPublicFeedback } from '@/components/page-feedback-api';
 
 type Vote = 'yes' | 'no';
 
@@ -26,10 +27,13 @@ export function PageFeedback() {
   const [selectedReason, setSelectedReason] = useState<string>('');
   const [details, setDetails] = useState('');
   const [email, setEmail] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitError, setSubmitError] = useState(false);
 
   const showForm = vote !== null;
   const options = vote === 'yes' ? YES_OPTIONS : NO_OPTIONS;
   const showOptionalInputs = selectedReason === 'Something else';
+  const canSubmit = vote !== null && selectedReason.trim().length > 0 && !isSubmitting;
 
   const onChooseVote = (value: Vote) => {
     if (vote === value) return;
@@ -37,6 +41,7 @@ export function PageFeedback() {
     setSelectedReason('');
     setDetails('');
     setEmail('');
+    setSubmitError(false);
   };
 
   const stopEvent = (event: ReactMouseEvent) => {
@@ -49,11 +54,32 @@ export function PageFeedback() {
     setSelectedReason('');
     setDetails('');
     setEmail('');
+    setIsSubmitting(false);
+    setSubmitError(false);
   };
 
-  const onSubmit = () => {
-    // Placeholder for analytics/reporting integration.
-    onCancel();
+  const onSubmit = async () => {
+    if (!vote || !selectedReason.trim() || isSubmitting) return;
+
+    setIsSubmitting(true);
+    setSubmitError(false);
+
+    const result = await submitPublicFeedback({
+      helpful: vote === 'yes',
+      reasonText: selectedReason,
+      details: showOptionalInputs ? details : undefined,
+      email: showOptionalInputs ? email : undefined,
+      pageUrl: window.location.href,
+      siteHost: window.location.host,
+    });
+
+    if (result.ok) {
+      onCancel();
+      return;
+    }
+
+    setSubmitError(true);
+    setIsSubmitting(false);
   };
 
   return (
@@ -65,6 +91,7 @@ export function PageFeedback() {
             type="button"
             className={['velu-page-feedback-btn', vote === 'yes' ? 'is-active' : ''].filter(Boolean).join(' ')}
             aria-label="Mark page as helpful"
+            disabled={isSubmitting}
             onClick={(event) => {
               stopEvent(event);
               onChooseVote('yes');
@@ -77,6 +104,7 @@ export function PageFeedback() {
             type="button"
             className={['velu-page-feedback-btn', vote === 'no' ? 'is-active' : ''].filter(Boolean).join(' ')}
             aria-label="Mark page as not helpful"
+            disabled={isSubmitting}
             onClick={(event) => {
               stopEvent(event);
               onChooseVote('no');
@@ -103,10 +131,12 @@ export function PageFeedback() {
                   type="button"
                   role="radio"
                   aria-checked={checked}
+                  disabled={isSubmitting}
                   className={['velu-page-feedback-option', checked ? 'is-checked' : ''].filter(Boolean).join(' ')}
                   onClick={(event) => {
                     stopEvent(event);
                     setSelectedReason(option);
+                    setSubmitError(false);
                   }}
                 >
                   <span className="velu-page-feedback-radio" aria-hidden="true" />
@@ -123,6 +153,7 @@ export function PageFeedback() {
                 rows={3}
                 placeholder="(Optional) Could you share more about your experience?"
                 value={details}
+                disabled={isSubmitting}
                 onChange={(event) => setDetails(event.target.value)}
               />
               <input
@@ -130,6 +161,7 @@ export function PageFeedback() {
                 type="email"
                 placeholder="(Optional) Email"
                 value={email}
+                disabled={isSubmitting}
                 onChange={(event) => setEmail(event.target.value)}
               />
             </div>
@@ -139,6 +171,7 @@ export function PageFeedback() {
             <button
               type="button"
               className="velu-page-feedback-cancel"
+              disabled={isSubmitting}
               onClick={(event) => {
                 stopEvent(event);
                 onCancel();
@@ -149,9 +182,12 @@ export function PageFeedback() {
             <button
               type="button"
               className="velu-page-feedback-submit"
+              disabled={!canSubmit}
+              aria-busy={isSubmitting}
+              title={submitError ? 'Unable to submit feedback right now. Please try again.' : undefined}
               onClick={(event) => {
                 stopEvent(event);
-                onSubmit();
+                void onSubmit();
               }}
             >
               Submit feedback