jamdesk 1.0.11 → 1.0.13

package/vendored/components/snippets/generated/HeaderAPI.tsx

@@ -0,0 +1,44 @@
+// Auto-generated file - do not edit manually
+// @ts-nocheck
+
+import React from 'react';
+
+// Import built-in MDX components that snippets can use
+import { Note, Info, Warning, Tip, Check, Danger, Callout } from '@/components/mdx/Callouts';
+import { Card } from '@/components/mdx/Card';
+import { CardGroup } from '@/components/mdx/CardGroup';
+import { ParamField } from '@/components/mdx/ParamField';
+import { ResponseField } from '@/components/mdx/ResponseField';
+import { Accordion, AccordionGroup } from '@/components/mdx/Accordion';
+import { CodeGroup } from '@/components/mdx/CodeGroup';
+import { Steps, Step } from '@/components/mdx/Steps';
+
+
+const HeaderAPI = ({ noProfileKey, profileKeyRequired }: any) => (
+  <>
+    <ParamField header="Authorization" type="string" required>
+      <a href="/apis/overview#authorization">API Key</a> of the Primary Profile.
+      <br />
+      <br />
+      Format: <code>Authorization: Bearer API_KEY</code>
+    </ParamField>
+    {!noProfileKey &&
+      (profileKeyRequired ? (
+        <ParamField header="Profile-Key" type="string" required>
+          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
+          <br />
+          <br />
+          Format: <code>Profile-Key: PROFILE_KEY</code>
+        </ParamField>
+      ) : (
+        <ParamField header="Profile-Key" type="string">
+          <a href="/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
+          <br />
+          <br />
+          Format: <code>Profile-Key: PROFILE_KEY</code>
+        </ParamField>
+      ))}
+  </>
+);
+
+export default HeaderAPI;

package/vendored/components/snippets/generated/PlansAvailable.tsx

@@ -0,0 +1,53 @@
+// Auto-generated file - do not edit manually
+// @ts-nocheck
+
+import React from 'react';
+
+// Import built-in MDX components that snippets can use
+import { Note, Info, Warning, Tip, Check, Danger, Callout } from '@/components/mdx/Callouts';
+import { Card } from '@/components/mdx/Card';
+import { CardGroup } from '@/components/mdx/CardGroup';
+import { ParamField } from '@/components/mdx/ParamField';
+import { ResponseField } from '@/components/mdx/ResponseField';
+import { Accordion, AccordionGroup } from '@/components/mdx/Accordion';
+import { CodeGroup } from '@/components/mdx/CodeGroup';
+import { Steps, Step } from '@/components/mdx/Steps';
+
+
+const PlansAvailable = ({ plans, maxPackRequired }: any) => {
+  let displayPlans = plans;
+
+if (plans.length === 1) {
+const lowerCasePlan = plans[0].toLowerCase();
+if (lowerCasePlan === "basic") {
+displayPlans = ["Basic", "Premium", "Business", "Enterprise"];
+} else if (lowerCasePlan === "business") {
+displayPlans = ["Business", "Enterprise"];
+} else if (lowerCasePlan === "premium") {
+displayPlans = ["Premium", "Business", "Enterprise"];
+}
+}
+
+return (
+
+<Note>
+Available on {displayPlans.length === 1 ? "the " : ""}
+{displayPlans.join(", ").replace(/\b\w/g, (l) => l.toUpperCase())}{" "}
+{displayPlans.length > 1 ? "plans" : "plan"}.
+
+{maxPackRequired && (
+
+  <a href="https://www.acme.com/docs/additional/maxpack"
+ className="flex items-center mt-2 cursor-pointer"
+>
+ <span className="px-1.5 py-0.5 rounded text-sm" style={{backgroundColor: '#C264B6', color: 'white', fontSize: '12px'}}>
+   Max Pack required
+ </span>
+</a>
+)}
+</Note>
+
+);
+};
+
+export default PlansAvailable;

package/vendored/components/snippets/generated/SnippetIntro.tsx

@@ -0,0 +1,43 @@
+// Auto-generated file - do not edit manually
+// @ts-nocheck
+
+import React from 'react';
+
+// Import built-in MDX components that snippets can use
+import { Note, Info, Warning, Tip, Check, Danger, Callout } from '@/components/mdx/Callouts';
+import { Card } from '@/components/mdx/Card';
+import { CardGroup } from '@/components/mdx/CardGroup';
+import { ParamField } from '@/components/mdx/ParamField';
+import { ResponseField } from '@/components/mdx/ResponseField';
+import { Accordion, AccordionGroup } from '@/components/mdx/Accordion';
+import { CodeGroup } from '@/components/mdx/CodeGroup';
+import { Steps, Step } from '@/components/mdx/Steps';
+
+
+// Helper component for rendering plain MDX snippets
+// Content is from project snippets (controlled source), not user input
+const PlainMdxSnippet = ({ content }: { content: string }) => {
+  const formattedContent = content
+    .split('\n\n')
+    .map((paragraph) => {
+      let html = paragraph.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+      html = html.replace(/\*([^*]+)\*/g, '<em>$1</em>');
+      html = html.replace(/\`([^\`]+)\`/g, '<code>$1</code>');
+      return html;
+    })
+    .filter(p => p.trim());
+
+  return (
+    <div className="snippet-content">
+      {formattedContent.map((p, i) => (
+        <p key={i} dangerouslySetInnerHTML={{ __html: p }} />
+      ))}
+    </div>
+  );
+};
+
+const SnippetIntro = () => {
+  return <PlainMdxSnippet content={"One of the core principles of software development is DRY (Don't Repeat\nYourself). This is a principle that apply to documentation as\nwell. If you find yourself repeating the same content in multiple places, you\nshould consider creating a custom snippet to keep your content in sync."} />;
+};
+
+export default SnippetIntro;

package/vendored/components/ui/CodePanel.tsx

@@ -121,6 +121,7 @@ export function CodePanel({
   const [scrollRatio, setScrollRatio] = useState(0); // 0 to 1, for custom scrollbar position
   const [thumbWidth, setThumbWidth] = useState(30); // Percentage width of thumb
   const [isDragging, setIsDragging] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
   const tabsRef = useRef<HTMLDivElement>(null);
   const trackRef = useRef<HTMLDivElement>(null);
   const contentRef = useRef<HTMLDivElement>(null);
@@ -149,6 +150,11 @@ export function CodePanel({
     }
   };
 
+  // Notify parent (ApiPage) after tab content re-renders so sidebar heights recalculate
+  useEffect(() => {
+    panelRef.current?.dispatchEvent(new CustomEvent('codepanel-tab-change', { bubbles: true }));
+  }, [activeTab]);
+
   // Check for overflow and scroll position
   useEffect(() => {
     const checkOverflow = () => {
@@ -246,6 +252,7 @@ export function CodePanel({
 
   return (
     <div
+      ref={panelRef}
       className={`rounded-xl overflow-hidden not-prose w-full flex flex-col ${className}`}
       style={{ border: `0.5px solid ${codePanelColors.border}`, boxShadow: 'var(--shadow-lg)' }}
       data-code-panel={panelType || 'inline'}

package/vendored/lib/analytics-script.ts

@@ -0,0 +1,147 @@
+/**
+ * Analytics script generation for ISR layout
+ *
+ * Generates the inline tracking script injected into documentation pages.
+ * The slug can be server-injected (ISR mode) or null (static mode, uses
+ * client-side hostname detection as fallback).
+ */
+
+/** Same pattern as validSlugPattern in path-safety.ts */
+const SAFE_SLUG_PATTERN = /^[a-z0-9-]+$/;
+
+/**
+ * Sanitize a project slug for safe injection into an inline <script>.
+ * Only allows lowercase alphanumeric characters and hyphens.
+ * Returns null if the slug is invalid, empty, or contains unsafe characters.
+ */
+export function sanitizeSlugForScript(slug: string | null | undefined): string | null {
+  if (!slug || typeof slug !== 'string') return null;
+  return SAFE_SLUG_PATTERN.test(slug) ? slug : null;
+}
+
+/**
+ * Generate the analytics tracking script content for inline injection.
+ *
+ * When slug is provided (ISR mode), it's injected directly — works on any domain
+ * including bare domains (jamdesk.com) and custom domains (docs.acme.com).
+ * When slug is null (static mode), falls back to client-side subdomain detection.
+ */
+export function getAnalyticsScript(rawSlug: string | null): string {
+  const slug = sanitizeSlugForScript(rawSlug);
+  const slugLiteral = slug ? `'${slug}'` : 'null';
+
+  return `
+(function() {
+  var h = location.hostname;
+
+  // Server-injected slug (ISR mode) or client-side detection (static mode)
+  var slug = ${slugLiteral};
+
+  // Fallback: extract from subdomain (static/dev mode)
+  if (!slug) {
+    var parts = h.split('.');
+    if ((h.endsWith('.jamdesk.com') || h.endsWith('.jamdesk.dev') || h.endsWith('.jamdesk.app')) && parts.length >= 3) {
+      slug = parts[0];
+    }
+  }
+
+  // Skip tracking for localhost or if no valid slug
+  if (!slug || h.indexOf('localhost') !== -1) {
+    console.log('[Jamdesk Analytics] Skipped: no valid project slug');
+    return;
+  }
+
+  // Generate session ID (persisted for 30 minutes of inactivity)
+  var SESSION_KEY = 'jd_sid';
+  var SESSION_TIMEOUT = 30 * 60 * 1000; // 30 minutes
+
+  function getSessionId() {
+    var stored = sessionStorage.getItem(SESSION_KEY);
+    var data = stored ? JSON.parse(stored) : null;
+    var now = Date.now();
+
+    if (data && (now - data.lastActivity) < SESSION_TIMEOUT) {
+      data.lastActivity = now;
+      sessionStorage.setItem(SESSION_KEY, JSON.stringify(data));
+      return data.id;
+    }
+
+    // New session
+    var newId = Math.random().toString(36).substr(2, 9) + Date.now().toString(36);
+    sessionStorage.setItem(SESSION_KEY, JSON.stringify({ id: newId, lastActivity: now }));
+    return newId;
+  }
+
+  // Get timezone for country fallback
+  function getTimezone() {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // Track page view
+  function trackPageView() {
+    var data = {
+      projectSlug: slug,
+      path: location.pathname,
+      referrer: document.referrer || null,
+      userAgent: navigator.userAgent,
+      sessionId: getSessionId(),
+      type: 'pageview',
+      eventId: slug + '-' + location.pathname + '-' + Date.now(),
+      timezone: getTimezone()
+    };
+
+    // Send to analytics endpoint (proxied via first-party domain to avoid ad blockers)
+    fetch('/_jd/ev', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+      keepalive: true
+    }).catch(function() { /* Ignore errors */ });
+  }
+
+  // Track current path to avoid duplicate tracking
+  var lastTrackedPath = location.pathname;
+
+  // Track page view (with deduplication)
+  function trackIfNewPath() {
+    var currentPath = location.pathname;
+    if (currentPath !== lastTrackedPath) {
+      lastTrackedPath = currentPath;
+      trackPageView();
+    }
+  }
+
+  // Track initial page view
+  trackPageView();
+
+  // Track SPA navigation (History API)
+  var origPushState = history.pushState;
+  history.pushState = function() {
+    origPushState.apply(this, arguments);
+    setTimeout(trackIfNewPath, 0);
+  };
+
+  var origReplaceState = history.replaceState;
+  history.replaceState = function() {
+    origReplaceState.apply(this, arguments);
+    setTimeout(trackIfNewPath, 0);
+  };
+
+  window.addEventListener('popstate', function() {
+    setTimeout(trackIfNewPath, 0);
+  });
+
+  // Fallback: Poll for URL changes (catches Next.js soft navigation)
+  setInterval(function() {
+    if (location.pathname !== lastTrackedPath) {
+      lastTrackedPath = location.pathname;
+      trackPageView();
+    }
+  }, 1000);
+})();
+`;
+}

package/vendored/lib/crypto-helpers.ts

@@ -0,0 +1,25 @@
+// DO NOT EDIT — this file is auto-synced from shared/. Edit the source in shared/ and run ./scripts/sync-shared.sh
+
+/**
+ * Shared Cryptographic Helpers
+ *
+ * Constant-time comparison using HMAC to avoid length-leak timing attacks.
+ *
+ * SYNC TARGET: This file is the source of truth.
+ * Synced to: builder/build-service/lib, proxy/lib
+ */
+import { timingSafeEqual, createHmac } from 'crypto';
+
+/**
+ * Constant-time string comparison using HMAC.
+ *
+ * Unlike naive timingSafeEqual (which requires equal-length buffers and
+ * leaks length via early return), this HMACs both values first so
+ * comparisons are always on fixed-length 32-byte digests.
+ */
+export function secretsEqual(a: string, b: string): boolean {
+  const key = 'jamdesk-secret-comparison';
+  const hmacA = createHmac('sha256', key).update(a).digest();
+  const hmacB = createHmac('sha256', key).update(b).digest();
+  return timingSafeEqual(hmacA, hmacB);
+}

package/vendored/lib/enhance-navigation.ts

@@ -0,0 +1,175 @@
+/**
+ * Navigation Enhancement
+ *
+ * Enhances docs.json navigation entries with metadata from MDX frontmatter:
+ * - Sidebar titles (sidebarTitle > title)
+ * - HTTP method badges (from openapi: or api: frontmatter)
+ * - Icons and tags
+ *
+ * Port of scripts/enhance-navigation.cjs for use in the production build pipeline.
+ */
+
+import type {
+  DocsConfig,
+  NavigationPage,
+  NavigationPageObject,
+  GroupConfig,
+} from './docs-types.js';
+
+type HttpMethod = NonNullable<NavigationPageObject['method']>;
+
+export interface PageInfo {
+  path: string;
+  frontmatter: Record<string, unknown>;
+  content: string;
+}
+
+const VALID_METHODS: readonly string[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+
+/**
+ * Parse HTTP method from `api:` frontmatter field.
+ * Example: "POST /analytics/post" -> "POST"
+ */
+export function parseApiMethod(apiField: unknown): HttpMethod | null {
+  if (!apiField || typeof apiField !== 'string') return null;
+  const trimmed = apiField.trim().toUpperCase();
+  for (const method of VALID_METHODS) {
+    if (trimmed.startsWith(method)) return method as HttpMethod;
+  }
+  return null;
+}
+
+/**
+ * Parse HTTP method from `openapi:` frontmatter field.
+ * Example: "/openapi/spec.yml GET /api/v1/users" -> "GET"
+ */
+export function parseOpenApiMethod(openapiField: unknown): HttpMethod | null {
+  if (!openapiField || typeof openapiField !== 'string') return null;
+  const parts = openapiField.trim().split(/\s+/);
+  for (const part of parts) {
+    const upper = part.toUpperCase();
+    if (VALID_METHODS.includes(upper)) return upper as HttpMethod;
+  }
+  return null;
+}
+
+function buildFrontmatterMap(
+  pageInfos: PageInfo[],
+): Map<string, Record<string, unknown>> {
+  const map = new Map<string, Record<string, unknown>>();
+  for (const info of pageInfos) {
+    const pagePath = info.path.replace(/\.mdx?$/, '');
+    map.set(pagePath, info.frontmatter);
+  }
+  return map;
+}
+
+/**
+ * Enhance a single page entry with frontmatter data.
+ * Preserves existing explicit values — only fills in missing ones.
+ */
+function enhancePage(
+  page: NavigationPage,
+  map: Map<string, Record<string, unknown>>,
+): NavigationPage {
+  const pagePath = typeof page === 'string' ? page : page.page;
+  const existing: Partial<NavigationPageObject> =
+    typeof page === 'object' ? page : {};
+
+  const fm = map.get(pagePath);
+  if (!fm) return page;
+
+  // sidebarTitle takes priority over title for sidebar display
+  const title =
+    existing.title ||
+    (fm.sidebarTitle as string | undefined) ||
+    (fm.title as string | undefined);
+  const method =
+    existing.method || parseApiMethod(fm.api) || parseOpenApiMethod(fm.openapi);
+  const icon = existing.icon || (fm.icon as string | undefined);
+  const tag = existing.tag || (fm.tag as string | undefined);
+
+  if (title || method || icon || tag) {
+    return {
+      page: pagePath,
+      ...(title && { title }),
+      ...(method && { method }),
+      ...(icon && { icon }),
+      ...(tag && { tag }),
+    };
+  }
+
+  return page;
+}
+
+/**
+ * Recursively enhance all pages/groups in a navigation array.
+ */
+function enhancePages(
+  pages: (NavigationPage | GroupConfig)[],
+  map: Map<string, Record<string, unknown>>,
+): (NavigationPage | GroupConfig)[] {
+  return pages.map((item) => {
+    if (typeof item === 'object' && 'group' in item) {
+      return enhanceNavNode(
+        item as unknown as Record<string, unknown>,
+        map,
+      ) as unknown as GroupConfig;
+    }
+    return enhancePage(item as NavigationPage, map);
+  });
+}
+
+/** Navigation keys whose children are sub-nodes (recurse with enhanceNavNode). */
+const RECURSE_KEYS = [
+  'groups', 'tabs', 'anchors', 'dropdowns',
+  'products', 'versions', 'languages', 'menu',
+] as const;
+
+/**
+ * Generic recursive walker — enhances any navigation node that has
+ * pages, groups, tabs, anchors, dropdowns, products, versions,
+ * languages, or menu keys.
+ */
+function enhanceNavNode(
+  node: Record<string, unknown>,
+  map: Map<string, Record<string, unknown>>,
+): Record<string, unknown> {
+  const result = { ...node };
+
+  // Pages contain leaf page entries (strings or objects) mixed with nested groups
+  if (Array.isArray(node.pages)) {
+    result.pages = enhancePages(node.pages, map);
+  }
+
+  // All other array keys contain sub-nodes that need recursive enhancement
+  for (const key of RECURSE_KEYS) {
+    if (Array.isArray(node[key])) {
+      result[key] = (node[key] as Record<string, unknown>[]).map((child) =>
+        enhanceNavNode(child, map),
+      );
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Enhance docs.json navigation with frontmatter metadata.
+ * Returns a new config — does NOT mutate the input.
+ */
+export function enhanceConfigNavigation(
+  config: DocsConfig,
+  pageInfos: PageInfo[],
+): DocsConfig {
+  const nav = config.navigation;
+  if (!nav || Object.keys(nav).length === 0) return config;
+
+  const map = buildFrontmatterMap(pageInfos);
+  const enhanced = enhanceNavNode(
+    nav as Record<string, unknown>,
+    map,
+  );
+
+  return { ...config, navigation: enhanced as DocsConfig['navigation'] };
+}

package/vendored/lib/heading-extractor.ts

@@ -0,0 +1,117 @@
+/**
+ * Heading extractor for link validation.
+ * Extracts heading slugs from MDX content to validate #fragment links.
+ *
+ * Uses the same slug generation as TableOfContents.tsx (client-side DOM IDs).
+ */
+
+export interface HeadingInfo {
+  id: string;
+  text: string;
+  level: number;
+  line: number; // 1-indexed
+}
+
+/**
+ * Generate a URL-friendly slug from heading text.
+ * Must stay in sync with TableOfContents.tsx:207-209.
+ */
+export function generateSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+const HEADING_REGEX = /^(#{1,6})\s+(.+)$/;
+const FENCE_REGEX = /^(`{3,}|~{3,})/;
+const UPDATE_LABEL_REGEX = /<Update\s+label=["']([^"']+)["']/;
+
+/**
+ * Extract all heading slugs from MDX content.
+ * Includes markdown headings and <Update label="..."> component anchors.
+ * Skips content inside fenced code blocks.
+ */
+export function extractHeadings(content: string): HeadingInfo[] {
+  const headings: HeadingInfo[] = [];
+  const lines = content.split('\n');
+  let inCodeBlock = false;
+  let fencePattern = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(FENCE_REGEX);
+
+    if (fenceMatch) {
+      if (!inCodeBlock) {
+        inCodeBlock = true;
+        fencePattern = fenceMatch[1];
+        continue;
+      } else if (line.startsWith(fencePattern)) {
+        inCodeBlock = false;
+        fencePattern = '';
+        continue;
+      }
+    }
+
+    if (inCodeBlock) continue;
+
+    const headingMatch = line.match(HEADING_REGEX);
+    if (headingMatch) {
+      const level = headingMatch[1].length;
+      const text = headingMatch[2].trim();
+      const id = generateSlug(text);
+      if (id) {
+        headings.push({ id, text, level, line: i + 1 });
+      }
+    }
+
+    const updateMatch = line.match(UPDATE_LABEL_REGEX);
+    if (updateMatch) {
+      const text = updateMatch[1];
+      const id = generateSlug(text);
+      if (id) {
+        headings.push({ id, text, level: 2, line: i + 1 });
+      }
+    }
+  }
+
+  return headings;
+}
+
+/**
+ * Check if MDX content has api: or openapi: in its frontmatter.
+ * API endpoint pages generate dynamic anchor IDs at render time (#param-*, etc.)
+ * that aren't in the MDX source, so fragment validation is skipped for them.
+ */
+function hasApiFrontmatter(content: string): boolean {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return false;
+  return /^(openapi|api):/m.test(match[1]);
+}
+
+/**
+ * Build a map of page path -> heading slug set.
+ * Keys are page paths without .mdx extension (matching docs.json navigation format).
+ * Skips API endpoint pages (they generate dynamic anchors at render time).
+ *
+ * Unlike buildHeadingMapFromFiles() in validate-links.cjs, this doesn't add dual
+ * keys for index pages. The CJS validator handles index resolution via
+ * getTargetHeadingSlugs() which derives the key from the filesystem path.
+ *
+ * @param fileContents - Map of relative file paths (with .mdx) to content.
+ *   Keys come from build.ts fileContents Map (e.g., 'getting-started.mdx', 'api/auth.mdx').
+ */
+export function buildHeadingMap(
+  fileContents: Map<string, string>
+): Map<string, Set<string>> {
+  const map = new Map<string, Set<string>>();
+  for (const [filePath, content] of fileContents) {
+    if (hasApiFrontmatter(content)) continue;
+    const headings = extractHeadings(content);
+    const slugs = new Set(headings.map((h) => h.id));
+    const pagePath = filePath.replace(/\.mdx$/, '');
+    map.set(pagePath, slugs);
+  }
+  return map;
+}

package/vendored/lib/mdx.ts

@@ -68,7 +68,7 @@ export function generateTableOfContents(content: string): { id: string; text: st
     const id = text
       .toLowerCase()
       .replace(/[^a-z0-9]+/g, '-')
-      .replace(/(^-|-$)/g, '');
+      .replace(/^-+|-+$/g, '');
 
     headings.push({ id, text, level });
   }