@veluai/velu 0.2.47 → 0.2.49

package/runtime/velu-ui/lib/reader-user.js

@@ -0,0 +1,135 @@
+/** Identified-reader personalization (Mintlify-compatible `user` + playground). */
+
+export function emptyReaderIdentity() {
+  return { user: {}, groups: [], apiPlaygroundInputs: {} };
+}
+
+export function identityFromUserData(data) {
+  const empty = emptyReaderIdentity();
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return empty;
+  if (typeof data.expiresAt === 'number' && data.expiresAt * 1000 <= Date.now()) return empty;
+  const groups = Array.isArray(data.groups)
+    ? [...new Set(data.groups.filter((g) => typeof g === 'string' && g.trim()).map((g) => g.trim()))].slice(0, 200)
+    : [];
+  const user = data.content && typeof data.content === 'object' && !Array.isArray(data.content) ? data.content : {};
+  const apiPlaygroundInputs =
+    data.apiPlaygroundInputs && typeof data.apiPlaygroundInputs === 'object' && !Array.isArray(data.apiPlaygroundInputs)
+      ? data.apiPlaygroundInputs
+      : {};
+  return { user, groups, apiPlaygroundInputs };
+}
+
+export function pageRequiredGroups(page) {
+  const fromFrontmatter = page?.frontmatter?.groups;
+  if (Array.isArray(fromFrontmatter) && fromFrontmatter.length) return fromFrontmatter;
+  const fromOperation = page?.operation?.groups;
+  if (Array.isArray(fromOperation) && fromOperation.length) return fromOperation;
+  return [];
+}
+
+export function filterSidebarSections(sections = [], groups = getReaderGroups(), pagesMap = {}) {
+  const keepItems = (items) =>
+    (items || []).flatMap((item) => {
+      if (item?.items) {
+        const nested = keepItems(item.items);
+        return nested.length ? [{ ...item, items: nested }] : [];
+      }
+      const required = Array.isArray(item?.groups) && item.groups.length
+        ? item.groups
+        : pageRequiredGroups(pagesMap[item?.href]);
+      return visibleToGroups(required, groups) ? [item] : [];
+    });
+  return (sections || [])
+    .map((section) => {
+      const items = keepItems(section.items);
+      return items.length ? { ...section, items } : null;
+    })
+    .filter(Boolean);
+}
+
+export function setReaderIdentity(identity = {}) {
+  const next = {
+    user: identity.user && typeof identity.user === 'object' && !Array.isArray(identity.user) ? identity.user : {},
+    groups: Array.isArray(identity.groups) ? identity.groups.filter((g) => typeof g === 'string') : [],
+    apiPlaygroundInputs:
+      identity.apiPlaygroundInputs && typeof identity.apiPlaygroundInputs === 'object' && !Array.isArray(identity.apiPlaygroundInputs)
+        ? identity.apiPlaygroundInputs
+        : {},
+  };
+  if (typeof globalThis === 'undefined') return next;
+  globalThis.velu = { ...(globalThis.velu || {}), ...next };
+  globalThis.mintlify = { ...(globalThis.mintlify || {}), user: next.user };
+  if (typeof globalThis.dispatchEvent === 'function' && typeof globalThis.Event === 'function') {
+    globalThis.dispatchEvent(new Event('velu:user'));
+    globalThis.dispatchEvent(new Event('mintlify:user'));
+  }
+  return next;
+}
+
+export function getReaderUser() {
+  return globalThis.velu?.user && typeof globalThis.velu.user === 'object' ? globalThis.velu.user : {};
+}
+
+export function getReaderGroups() {
+  return Array.isArray(globalThis.velu?.groups) ? globalThis.velu.groups : [];
+}
+
+export function getPlaygroundInputs() {
+  const inputs = globalThis.velu?.apiPlaygroundInputs;
+  return inputs && typeof inputs === 'object' ? inputs : {};
+}
+
+export function visibleToGroups(required, groups = getReaderGroups()) {
+  if (!Array.isArray(required) || required.length === 0) return true;
+  return groups.some((g) => required.includes(g));
+}
+
+export function initialPlaygroundValues(operation) {
+  const inputs = getPlaygroundInputs();
+  const values = { auth: {}, path: {}, query: {}, header: {}, cookie: {} };
+  for (const a of operation?.auth || []) {
+    const raw = inputs.header?.[a.name];
+    if (typeof raw !== 'string' || !raw) continue;
+    values.auth[a.name] = a.prefix && raw.startsWith(`${a.prefix} `) ? raw.slice(a.prefix.length + 1) : raw;
+  }
+  for (const loc of ['path', 'query', 'header', 'cookie']) {
+    for (const p of operation?.parameters?.[loc] || []) {
+      const raw = inputs[loc]?.[p.name];
+      if (typeof raw === 'string') values[loc][p.name] = raw;
+    }
+  }
+  if (typeof globalThis.localStorage === 'undefined') return values;
+  try {
+    const stored = JSON.parse(globalThis.localStorage.getItem(`velu-playground:${operation?.id}`) || 'null');
+    if (stored && typeof stored === 'object') {
+      for (const loc of Object.keys(values)) {
+        values[loc] = { ...values[loc], ...(stored[loc] || {}) };
+      }
+    }
+  } catch {
+    /* ignore malformed local overrides */
+  }
+  return values;
+}
+
+export function persistPlaygroundValues(operationId, values) {
+  if (typeof globalThis.localStorage === 'undefined' || !operationId) return;
+  try {
+    globalThis.localStorage.setItem(`velu-playground:${operationId}`, JSON.stringify(values || {}));
+  } catch {
+    /* quota / private mode */
+  }
+}
+
+export function personalizedServer(fallback) {
+  const vars = getPlaygroundInputs().server || {};
+  let url = (typeof vars.baseUrl === 'string' && vars.baseUrl)
+    || (typeof vars.url === 'string' && vars.url)
+    || fallback
+    || '';
+  for (const [key, value] of Object.entries(vars)) {
+    if (key === 'baseUrl' || key === 'url' || typeof value !== 'string') continue;
+    url = url.replaceAll(`{${key}}`, value);
+  }
+  return url;
+}

package/runtime/velu-ui/themes/thulir.css

@@ -304,7 +304,9 @@
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block { border-radius: 16px; border-color: rgb(from var(--vepa-gray-950) r g b / 10%); }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block :is(pre,code) { font: 400 14px/24px var(--font-mono); }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__body { padding: 16px; border-radius: 16px; }
-:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__copy { border: 0; background: transparent; width: 24px; height: 24px; top: 12px; right: 12px; }
+:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__actions { top: 12px; right: 12px; }
+:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__copy,
+:is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__report-btn { border: 0; background: transparent; width: 24px; height: 24px; }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__header { height: 36px; padding: 0 12px; align-items: stretch; }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__tabs { gap: 16px; }
 :is([data-site-theme='thulir'],[data-site-theme='aalam'],[data-site-theme='nila'],[data-site-theme='kadhir']) .velu-code-block__tab { padding: 0 6px; border-radius: 0; font: 400 12px/20px var(--font-sans); height: 36px; }

package/src/navigation.js

@@ -478,5 +478,9 @@ function itemFor(pageNode, pagesMap, ctx) {
   }
   const method = pageNode.method ?? pagesMap[href]?.operation?.method;
   if (method) item.method = method;
+  const groups = pageNode.groups
+    ?? (Array.isArray(fm?.groups) && fm.groups.length ? fm.groups : undefined)
+    ?? pagesMap[href]?.operation?.groups;
+  if (Array.isArray(groups) && groups.length) item.groups = groups;
   return item;
 }

package/src/runtime/App.jsx

@@ -58,6 +58,10 @@ import {
   ApiReferencePage,
   NotFound,
   VeluMark,
+  setReaderIdentity,
+  emptyReaderIdentity,
+  identityFromUserData,
+  filterSidebarSections,
 } from 'velu-ui';
 import { X, ChevronDown } from 'lucide-react';
 import ErrorBoundary from './ErrorBoundary.jsx';
@@ -107,14 +111,29 @@ function sectionToEndpoints(items) {
     else
       out.push({
         method: it.method,
-        label: it.label,
+        name: it.label,
         href: it.href,
-        icon: it.icon,
       });
   }
   return out;
 }
 
+function flattenSidebarPages(sections) {
+  const out = [];
+  const walk = (items) => {
+    for (const it of items ?? []) {
+      if (it.items) walk(it.items);
+      else {
+        const page = { label: it.label, href: it.href };
+        if (it.description) page.description = it.description;
+        out.push(page);
+      }
+    }
+  };
+  for (const section of sections ?? []) walk(section.items);
+  return out;
+}
+
 const CALLOUT_TYPES = [
   'note',
   'warning',
@@ -788,6 +807,53 @@ function DocsPage() {
   const location = useLocation();
   const navigate = useNavigate();
   const pathname = normalizeUrl(location.pathname);
+  const [readerUser, setReaderUser] = React.useState(() =>
+    typeof window === 'undefined' ? {} : window.velu?.user || {},
+  );
+  const [readerGroups, setReaderGroups] = React.useState(() =>
+    typeof window === 'undefined' ? [] : window.velu?.groups || [],
+  );
+  const [sharedSession, setSharedSession] = React.useState(null);
+  React.useEffect(() => {
+    const sync = () => {
+      setReaderUser(window.velu?.user || {});
+      setReaderGroups(Array.isArray(window.velu?.groups) ? window.velu.groups : []);
+    };
+    sync();
+    window.addEventListener('velu:user', sync);
+    return () => window.removeEventListener('velu:user', sync);
+  }, []);
+  React.useEffect(() => {
+    if (IS_DEV_PREVIEW || site.readerPrivate || site.guarded) return undefined;
+    let alive = true;
+    (async () => {
+      try {
+        const config = await fetch(`${BASE_PATH}/@velu-reader/personalization`, {
+          credentials: 'same-origin',
+          cache: 'no-store',
+        }).then((response) => (response.ok ? response.json() : null));
+        if (!alive || config?.method !== 'shared_session' || !config.infoUrl) return;
+        setSharedSession({ loginUrl: config.loginUrl || null, identified: false });
+        const response = await fetch(config.infoUrl, { credentials: 'include', cache: 'no-store' });
+        if (!alive) return;
+        if (!response.ok) {
+          setReaderIdentity(emptyReaderIdentity());
+          return;
+        }
+        const identity = identityFromUserData(await response.json());
+        setReaderIdentity(identity);
+        setSharedSession({
+          loginUrl: config.loginUrl || null,
+          identified: identity.groups.length > 0 || Object.keys(identity.user).length > 0,
+        });
+      } catch {
+        if (alive) setReaderIdentity(emptyReaderIdentity());
+      }
+    })();
+    return () => {
+      alive = false;
+    };
+  }, []);
   const entry = pages[pathname];
   // `navigation`/`pages` are module constants in dev/build (the deps never
   // change there); the instant preview's virtual-site substitute reassigns
@@ -797,6 +863,18 @@ function DocsPage() {
     () => resolve(pathname, navigation, pages),
     [pathname, navigation, pages],
   );
+  const visibleNav = React.useMemo(() => {
+    if (!nav || site.readerPrivate || site.guarded) return nav;
+    const sidebarSections = filterSidebarSections(nav.sidebarSections, readerGroups, pages);
+    const ordered = flattenSidebarPages(sidebarSections);
+    const idx = ordered.findIndex((page) => page.href === pathname);
+    return {
+      ...nav,
+      sidebarSections,
+      prev: idx > 0 ? ordered[idx - 1] : undefined,
+      next: idx >= 0 && idx < ordered.length - 1 ? ordered[idx + 1] : undefined,
+    };
+  }, [nav, pathname, readerGroups]);
 
   // Search source: Pagefind for content/excerpts, but resolve each result's
   // breadcrumb from the real NAVIGATION (a page's nav group can differ from its
@@ -849,6 +927,31 @@ function DocsPage() {
     return createPageFeedback({ apiBase, host: site.assistant?.host });
   }, []);
 
+  React.useEffect(() => {
+    if (IS_DEV_PREVIEW) return undefined;
+    const onReport = (e) => {
+      const d = e.detail || {};
+      pageFeedback?.submit({
+        helpful: false,
+        reason: 'Incorrect code example',
+        detail: d.body || d.detail || '',
+      });
+    };
+    window.addEventListener('velu:report-code', onReport);
+    return () => window.removeEventListener('velu:report-code', onReport);
+  }, [pageFeedback]);
+
+  React.useEffect(() => {
+    if (IS_DEV_PREVIEW || !pageFeedback?.config) return undefined;
+    let alive = true;
+    pageFeedback.config().then((cfg) => {
+      if (!alive || !cfg.codeReportsEnabled) return;
+      document.documentElement.dataset.veluCodeReports = 'on';
+      window.dispatchEvent(new Event('velu:code-reports-enabled'));
+    }).catch(() => {});
+    return () => { alive = false; };
+  }, [pageFeedback]);
+
   const frontmatter = entry?.frontmatter ?? {};
   const PageComponent = entry?.Component ?? null;
   const pageToc = entry?.toc ?? [];
@@ -1232,6 +1335,14 @@ function DocsPage() {
       kind: 'outlined',
       component: 'logout-link',
     });
+  } else if (sharedSession?.loginUrl && !sharedSession.identified) {
+    navActions.push({
+      label: 'Log in',
+      href: sharedSession.loginUrl,
+      kind: 'outlined',
+      external: true,
+      component: 'login-link',
+    });
   }
 
   // Callback ref so this rebinds when the footer mounts/unmounts.
@@ -1651,7 +1762,7 @@ function DocsPage() {
                   the sidebar shape). */}
               {nav?.sidebarHasApi ? (
                 <ApiSidebar
-                  sections={(nav?.sidebarSections ?? []).map((s) => ({
+                  sections={(visibleNav?.sidebarSections ?? []).map((s) => ({
                     title: s.title,
                     icon: s.icon,
                     endpoints: sectionToEndpoints(s.items),
@@ -1661,7 +1772,7 @@ function DocsPage() {
                 />
               ) : (
                 <Sidebar
-                  sections={nav?.sidebarSections ?? []}
+                  sections={visibleNav?.sidebarSections ?? []}
                   activeHref={pathname}
                   linkComponent={RouterLink}
                 />
@@ -1852,7 +1963,7 @@ function DocsPage() {
             <mdx-content key={site.theme === 'vepa' ? pathname : undefined} id={(site.theme === 'vepa' || ['thulir', 'aalam', 'nila', 'kadhir'].includes(site.theme)) && !entry?.api ? 'content' : undefined} class="velu-prose">
               {PageComponent ? (
                 <ErrorBoundary key={pathname} file={entry?.relPath}>
-                  {entry?.mdxApi ? <ApiReferencePage {...entry.mdxApi} preset={site.theme}><PageComponent /></ApiReferencePage> : <PageComponent />}
+                  {entry?.mdxApi ? <ApiReferencePage {...entry.mdxApi} preset={site.theme}><PageComponent user={readerUser} /></ApiReferencePage> : <PageComponent user={readerUser} />}
                 </ErrorBoundary>
               ) : (
                 <p style={{ color: 'var(--muted-color)' }}>
@@ -1885,14 +1996,14 @@ function DocsPage() {
               sidebar reading order of the active section. The wrapper
               doubles as the AskBar fade anchor on themes without a
               PageFeedback widget (see the observer above). */}
-          {chrome.articleChrome && !frontmatter.hidePagination && (nav?.prev || nav?.next) && (
+          {chrome.articleChrome && !frontmatter.hidePagination && (visibleNav?.prev || visibleNav?.next) && (
           <div ref={setNavAnchorEl}>
           <PageNav
             id="pagination"
             style={['thulir', 'aalam', 'nila', 'kadhir'].includes(site.theme) ? undefined : { marginTop: 'var(--s2)' }}
             variant={site.theme === 'aalam' ? 'aalam' : 'default'}
-            prev={nav?.prev}
-            next={nav?.next}
+            prev={visibleNav?.prev}
+            next={visibleNav?.next}
             linkComponent={RouterLink}
           />
           </div>