jamdesk 1.1.25 → 1.1.27

package/vendored/app/api/docs-search/[project]/search/route.ts

@@ -0,0 +1,168 @@
+/**
+ * Docs Search API — Semantic Search Endpoint
+ *
+ * REST API for external integrations (Intercom, Zendesk, custom chatbots)
+ * to search project documentation via vector similarity.
+ *
+ * Security:
+ * - Opaque API key auth (SHA-256 hash lookup in Upstash Redis; revocation
+ *   is a Redis DEL, so there is no separate blocklist)
+ * - Per-key rate limiting (60 req/min)
+ * - CORS enabled (cross-origin access by design)
+ *
+ * Usage:
+ *   POST https://acme.jamdesk.app/_api/search
+ *   Authorization: Bearer jd_live_<32 hex>
+ *   {"query": "How do I authenticate?", "limit": 5}
+ */
+import { NextRequest, NextResponse } from 'next/server';
+import { querySimilarChunks } from '@/lib/vector-store';
+import { verifyApiKey } from '@/lib/docs-search-auth';
+import { getBaseUrl, trackServerAnalytics } from '@/lib/route-helpers';
+import { redis } from '@/lib/redis';
+
+export const runtime = 'nodejs';
+export const maxDuration = 30;
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+const MAX_LIMIT = 20;
+const DEFAULT_LIMIT = 5;
+const MAX_QUERY_LENGTH = 500;
+const RATE_LIMIT_PER_MIN = 60;
+
+export async function OPTIONS(_request: NextRequest) {
+  return new NextResponse(null, { status: 204, headers: CORS_HEADERS });
+}
+
+export async function POST(
+  request: NextRequest,
+  context: { params: Promise<{ project: string }> },
+): Promise<NextResponse> {
+  const { project } = await context.params;
+
+  // --- Auth: verify opaque key against Upstash ---
+  // A revoked key is a Redis DEL, so "not found" and "revoked" collapse
+  // into the same invalid_key reason — no separate blocklist check.
+  // RFC 7235: scheme is case-insensitive. Accept `Bearer`, `bearer`, etc.,
+  // and tolerate stray whitespace rather than 401-ing strict clients.
+  const token = (request.headers.get('Authorization') || '')
+    .replace(/^Bearer\s+/i, '')
+    .trim();
+  const verify = await verifyApiKey(token, project);
+
+  if (!verify.ok) {
+    const status =
+      verify.reason === 'wrong_project' ? 403 :
+      verify.reason === 'lookup_failed' ||
+      verify.reason === 'redis_unavailable' ? 503 :
+      401;
+    return NextResponse.json(
+      { error: verify.reason },
+      { status, headers: CORS_HEADERS },
+    );
+  }
+
+  // --- Rate limiting: per key ID ---
+  // Always-call expire (not just on count === 1) — otherwise a transient
+  // failure between INCR and EXPIRE leaves the bucket immortal, slowly
+  // leaking Upstash keys. EXPIRE is idempotent.
+  if (redis) {
+    try {
+      const rlKey = `docs_search_rl:${verify.id}:${Math.floor(Date.now() / 60000)}`;
+      const count = await redis.incr(rlKey);
+      await redis.expire(rlKey, 120);
+
+      if (count > RATE_LIMIT_PER_MIN) {
+        return NextResponse.json(
+          { error: 'Rate limit exceeded' },
+          { status: 429, headers: { ...CORS_HEADERS, 'Retry-After': '60' } },
+        );
+      }
+    } catch {
+      // Redis down — allow through
+    }
+  }
+
+  // --- Parse & validate request body ---
+  let body: { query?: string; limit?: number };
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json(
+      { error: 'Invalid JSON body' },
+      { status: 400, headers: CORS_HEADERS },
+    );
+  }
+
+  const { query, limit: rawLimit } = body;
+
+  if (!query || typeof query !== 'string' || query.trim().length === 0) {
+    return NextResponse.json(
+      { error: 'Missing or empty "query" field' },
+      { status: 400, headers: CORS_HEADERS },
+    );
+  }
+
+  if (query.length > MAX_QUERY_LENGTH) {
+    return NextResponse.json(
+      { error: `Query exceeds ${MAX_QUERY_LENGTH} characters` },
+      { status: 400, headers: CORS_HEADERS },
+    );
+  }
+
+  // Use Number.isFinite so limit=0 clamps to 1 instead of falling to default
+  const parsedLimit = Number(rawLimit);
+  const effectiveLimit = Number.isFinite(parsedLimit)
+    ? parsedLimit
+    : DEFAULT_LIMIT;
+  const limit = Math.min(
+    Math.max(1, Math.floor(effectiveLimit)),
+    MAX_LIMIT,
+  );
+
+  // --- Semantic vector search ---
+  const startMs = Date.now();
+  let chunks;
+  try {
+    chunks = await querySimilarChunks(project, query.trim(), limit);
+  } catch (err) {
+    console.error('Vector search failed:', err);
+    return NextResponse.json(
+      { error: 'Search temporarily unavailable' },
+      { status: 502, headers: CORS_HEADERS },
+    );
+  }
+  const durationMs = Date.now() - startMs;
+
+  const resolvedHost = request.headers.get('x-jamdesk-forwarded-host')
+    || request.headers.get('x-original-host') || '';
+  const baseUrl = getBaseUrl(project, resolvedHost);
+
+  const results = chunks.map(chunk => ({
+    title: chunk.pageTitle,
+    section: chunk.sectionHeading || undefined,
+    slug: chunk.pageSlug,
+    content: chunk.content.slice(0, 500),
+    url: `${baseUrl}/${chunk.pageSlug}`,
+    score: Math.round(chunk.score * 1000) / 1000,
+  }));
+
+  // --- Analytics (fire-and-forget) ---
+  trackServerAnalytics({
+    projectSlug: project,
+    type: 'docs_search',
+    query: query.trim(),
+    resultsCount: results.length,
+    source: `key:${verify.id}`,
+  });
+
+  return NextResponse.json(
+    { results, query: query.trim(), total: results.length, durationMs },
+    { status: 200, headers: CORS_HEADERS },
+  );
+}

package/vendored/components/openapi/OpenApiError.tsx

@@ -0,0 +1,35 @@
+/**
+ * OpenApiError — visible warning when OpenAPI spec resolution fails.
+ * Renders in all environments (dev, ISR, CLI) so users see the problem
+ * instead of a silently blank page.
+ */
+
+interface OpenApiErrorProps {
+  message: string;
+  slug: string;
+}
+
+export function OpenApiError({ message, slug }: OpenApiErrorProps) {
+  return (
+    <div
+      role="alert"
+      style={{
+        margin: '1.5rem 0',
+        padding: '1rem 1.25rem',
+        borderRadius: '8px',
+        border: '1px solid #f59e0b',
+        backgroundColor: 'rgba(245, 158, 11, 0.08)',
+        fontSize: '0.875rem',
+        lineHeight: 1.5,
+        color: 'var(--color-text-primary, #1e293b)',
+      }}
+    >
+      <div style={{ fontWeight: 600, marginBottom: '0.375rem' }}>
+        OpenAPI Error
+      </div>
+      <div style={{ color: 'var(--color-text-muted, #64748b)' }}>
+        Failed to load the OpenAPI specification for <code>{slug}</code>: {message}
+      </div>
+    </div>
+  );
+}

package/vendored/lib/docs-search-auth.ts

@@ -0,0 +1,95 @@
+/**
+ * Docs Search API key verification.
+ *
+ * Tokens are opaque: `jd_live_<32 hex chars>` (40 chars total, 128 bits
+ * of entropy from crypto.randomBytes). The `_live_` segment reserves
+ * namespace for a future `jd_test_` mode. The server hashes the token
+ * with SHA-256 and looks up `apikey:<hash>` in Upstash Redis — the
+ * dashboard function dual-writes this record on generate and deletes
+ * it on revoke. No JWT, no signing secret, no expiration.
+ */
+import {createHash} from 'crypto';
+import {redis} from './redis';
+import {parseRedisConfig} from './domain-helpers';
+
+const KEY_FORMAT = /^jd_live_[0-9a-f]{32}$/;
+
+export type VerifyResult =
+  | {ok: true; id: string}
+  | {ok: false; reason: VerifyFailure};
+
+export type VerifyFailure =
+  | 'invalid_key_format'
+  | 'invalid_key'
+  | 'wrong_project'
+  | 'lookup_failed'
+  | 'redis_unavailable';
+
+interface StoredKey {
+  projectSlug: string;
+  id: string;
+}
+
+function hashApiKey(rawKey: string): string {
+  return createHash('sha256').update(rawKey).digest('hex');
+}
+
+function parseStoredKey(raw: unknown): StoredKey | null {
+  let parsed: Record<string, unknown> | null;
+  try {
+    parsed = parseRedisConfig(raw);
+  } catch {
+    return null;
+  }
+  if (
+    parsed &&
+    typeof parsed.projectSlug === 'string' &&
+    typeof parsed.id === 'string'
+  ) {
+    return parsed as unknown as StoredKey;
+  }
+  return null;
+}
+
+/**
+ * Verify a bearer token against the expected project slug.
+ *
+ * @param rawKey   The bearer token exactly as received (no trimming — the
+ *                 caller is responsible for stripping the `Bearer ` prefix).
+ * @param projectSlug The slug from the URL path (`[project]` param).
+ * @returns        `{ok: true, id}` on success, `{ok: false, reason}` otherwise.
+ *                 `id` is the short identifier suitable for audit logging;
+ *                 do NOT log the raw token or the hash.
+ */
+export async function verifyApiKey(
+  rawKey: string,
+  projectSlug: string,
+): Promise<VerifyResult> {
+  if (typeof rawKey !== 'string' || !KEY_FORMAT.test(rawKey)) {
+    return {ok: false, reason: 'invalid_key_format'};
+  }
+
+  if (!redis) {
+    return {ok: false, reason: 'redis_unavailable'};
+  }
+
+  const hash = hashApiKey(rawKey);
+
+  let raw: unknown;
+  try {
+    raw = await redis.get(`apikey:${hash}`);
+  } catch {
+    return {ok: false, reason: 'lookup_failed'};
+  }
+
+  const stored = parseStoredKey(raw);
+  if (!stored) {
+    return {ok: false, reason: 'invalid_key'};
+  }
+
+  if (stored.projectSlug !== projectSlug) {
+    return {ok: false, reason: 'wrong_project'};
+  }
+
+  return {ok: true, id: stored.id};
+}

package/vendored/lib/docs-types.ts

@@ -214,9 +214,13 @@ export interface TabConfig {
 }
 
 /**
- * Anchor configuration (top-level navigation sections)
- * @deprecated Use TabConfig instead. Anchors in navigation are deprecated.
- * For external links, use the top-level `anchors` field with ExternalAnchorConfig.
+ * Legacy anchor configuration (top-level navigation sections).
+ *
+ * Retained so NavigationConfig / DropdownConfig / ProductConfig /
+ * VersionConfig / LanguageConfig can continue to type customer configs
+ * that still carry the legacy shape. New configs should use TabConfig
+ * for internal sections and top-level ExternalAnchorConfig for external
+ * links; `validateConfig` rejects `navigation.anchors` at build time.
  */
 export interface AnchorConfig {
   anchor: string;
@@ -792,9 +796,15 @@ export interface DocsConfig {
   // Required fields
   theme: ThemeName;
   name: string;
-  colors: ColorsConfig;
   navigation: NavigationConfig;
 
+  // Boundary escape hatch — docs.json is user-authored and may carry fields
+  // not represented in this interface. Unknown keys read as `unknown`.
+  [key: string]: unknown;
+
+  // Optional — themes provide defaults at render time
+  colors?: ColorsConfig;
+
   // Optional fields
   description?: string;
   favicon?: Favicon;

package/vendored/lib/extract-highlights.ts

@@ -12,7 +12,7 @@ import type { DocsConfig } from './docs-types.js';
 export interface ExtractedHighlights {
   siteName: string;
   theme: 'jam' | 'nebula' | 'pulsar';
-  primaryColor: string;
+  primaryColor?: string;
   seoIndexable: boolean;
   analyticsIntegrations: string[];
   apiPlaygroundType: 'interactive' | 'simple' | 'hidden' | null;
@@ -118,7 +118,7 @@ export function extractConfigHighlights(config: DocsConfig, pageCount: number =
   return {
     siteName: config.name,
     theme: config.theme,
-    primaryColor: config.colors.primary,
+    primaryColor: config.colors?.primary,
     seoIndexable,
     analyticsIntegrations,
     apiPlaygroundType,

package/vendored/lib/mcp-search.ts

@@ -7,6 +7,7 @@
 import { create, insertMultiple, search as oramaSearch, type Orama } from '@orama/orama';
 import { restore } from '@orama/plugin-data-persistence';
 import { getFileBufferFromR2 } from './r2';
+import { querySimilarChunks } from './vector-store';
 
 // Types matching builder/build-service/lib/search-client.ts
 export interface SearchDocument {
@@ -28,6 +29,35 @@ export interface SearchResult {
   score: number;
 }
 
+/**
+ * Vector search adapter for MCP. Wraps querySimilarChunks()
+ * and maps to SearchResult[] format. Returns null if vector
+ * store is not configured (Orama fallback kicks in).
+ */
+export async function searchProjectWithVector(
+  project: string,
+  query: string,
+  limit: number,
+): Promise<SearchResult[] | null> {
+  if (!process.env.UPSTASH_VECTOR_REST_URL ||
+      !process.env.UPSTASH_VECTOR_REST_TOKEN) {
+    return null;
+  }
+
+  try {
+    const chunks = await querySimilarChunks(project, query, limit);
+    return chunks.map(chunk => ({
+      title: chunk.pageTitle,
+      url: chunk.pageSlug,
+      section: chunk.sectionHeading || undefined,
+      type: 'guide',
+      score: chunk.score,
+    }));
+  } catch {
+    return null; // Fall back to Orama on error
+  }
+}
+
 // Orama schema type
 type SearchSchema = {
   id: 'string';
@@ -74,6 +104,15 @@ export async function searchProject(
     return [];
   }
 
+  // Try vector search first for unfiltered queries
+  if (type === 'all') {
+    const vectorResults = await searchProjectWithVector(project, query, limit);
+    if (vectorResults) {
+      return vectorResults.map(r => ({ ...r, url: `${docsPath}/${r.url}` }));
+    }
+  }
+
+  // Fall back to Orama text search
   const db = await getOrCreateIndex(project, docsPath);
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/vendored/lib/middleware-helpers.ts

@@ -7,7 +7,6 @@
 
 import { log } from './logger';
 import {
-  resolveProject,
   resolveProjectFromHostname,
   resolveCustomDomain,
   getProjectConfig,
@@ -315,6 +314,7 @@ export const INTERNAL_API_ROUTES = [
   '/api/indexnow',   // IndexNow key verification (app/api/indexnow/[key])
   '/api/isr-health', // Health check endpoint (app/api/isr-health)
   '/api/chat',       // Chat endpoint (app/api/chat/[project])
+  '/api/docs-search', // Docs Search API (app/api/docs-search/[project]/search)
   '/api/mcp',        // MCP endpoint (app/api/mcp/[project])
   '/api/og',         // OG image generation (app/api/og)
   '/api/playground', // API playground (token, proxy, demo) — must skip hostAtDocs redirect
@@ -447,6 +447,26 @@ export function getChatApiPath(projectSlug: string): string {
   return `/api/chat/${projectSlug}`;
 }
 
+/**
+ * Check if this is a docs search request that needs routing.
+ *
+ * @param pathname - Request pathname
+ * @returns true if this is a docs search request
+ */
+export function isDocsSearchRequest(pathname: string): boolean {
+  return pathname === '/_api/search' || pathname === '/docs/_api/search';
+}
+
+/**
+ * Get the docs search API path for a project.
+ *
+ * @param projectSlug - Project identifier
+ * @returns Docs search API route path
+ */
+export function getDocsSearchApiPath(projectSlug: string): string {
+  return `/api/docs-search/${projectSlug}/search`;
+}
+
 const PLAYGROUND_PREFIX = '/_jd/playground/';
 
 /**

package/vendored/lib/openapi/parser.ts

@@ -27,7 +27,7 @@ const VALID_METHODS: HttpMethod[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'H
  * Full format: "/path/to/spec.yaml METHOD /endpoint/path"
  * Short format (with defaultSpecPath): "METHOD /endpoint/path"
  */
-export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string): ParsedOpenApiFrontmatter {
+export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string | string[]): ParsedOpenApiFrontmatter {
   const trimmed = value.trim();
   const parts = trimmed.split(/\s+/);
 
@@ -38,7 +38,7 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
 
     if (isMethodFirst) {
       // Short format: "METHOD /endpoint/path"
-      if (!defaultSpecPath) {
+      if (!defaultSpecPath || (Array.isArray(defaultSpecPath) && defaultSpecPath.length === 0)) {
         throw createFrontmatterError(
           value,
           'Short format (e.g., "GET /users") requires api.openapi to be configured in docs.json.\n' +
@@ -46,6 +46,8 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
         );
       }
 
+      const resolvedDefault = Array.isArray(defaultSpecPath) ? defaultSpecPath[0] : defaultSpecPath;
+
       const [method, ...pathParts] = parts;
       const endpointPath = pathParts.join(' ');
 
@@ -58,9 +60,10 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
       }
 
       return {
-        specPath: defaultSpecPath.startsWith('/') ? defaultSpecPath : `/${defaultSpecPath}`,
+        specPath: resolvedDefault.startsWith('/') ? resolvedDefault : `/${resolvedDefault}`,
         method: method.toUpperCase() as HttpMethod,
         path: endpointPath,
+        isShortFormat: true,
       };
     }
   }
@@ -106,6 +109,7 @@ export function parseOpenApiFrontmatter(value: string, defaultSpecPath?: string)
     specPath,
     method: upperMethod,
     path: endpointPath,
+    isShortFormat: false,
   };
 }
 

package/vendored/lib/openapi/types.ts

@@ -164,6 +164,7 @@ export interface ParsedOpenApiFrontmatter {
   specPath: string;
   method: HttpMethod;
   path: string;
+  isShortFormat: boolean;
 }
 
 /**