@veluai/velu 0.2.48 → 0.2.49

package/docs/mintlify-migration.md

@@ -121,9 +121,11 @@ The presets are not a certification of pixel equality for every component or cus
 
 Features without full Velu equivalents require review: remaining Mintlify themes, advanced
 fonts and styling, redirects, analytics/support integrations, hosting settings,
-authentication, personalization, hidden-page routing, legacy version filtering,
+authentication, standalone public personalization, hidden-page routing, legacy version filtering,
 complex dropdown/global navigation, AsyncAPI, manually authored `api:` pages,
-multi-file/remote endpoint snapshots, OpenAPI overlays and `x-mint` extensions.
+multi-file/remote endpoint snapshots, and OpenAPI overlays.
+OpenAPI `x-mint` / `x-mint-enum` personalization keys are rewritten to `x-velu` /
+`x-velu-enum`. The generator still reads leftover `x-mint` keys in unmigrated specs.
 Access/visibility settings are reported as errors; they must be migrated before
 publishing. Unlisted content is copied but Velu currently renders navigation
 pages only. Snapshot API pages must be regenerated or edited when their specs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veluai/velu",
-  "version": "0.2.48",
+  "version": "0.2.49",
   "type": "module",
   "bin": "./dist/cli.js",
   "publishConfig": {

package/runtime/velu-ui/components/ApiReferencePage.jsx

@@ -11,6 +11,24 @@ import CodeBlock, { CodeGroup } from './CodeBlock.jsx';
 import ApiSamples from './ApiSamples.jsx';
 import Callout from './Callout.jsx';
 import { sendApiRequest } from '../lib/api-send.js';
+import {
+  getReaderGroups,
+  visibleToGroups,
+  initialPlaygroundValues,
+  persistPlaygroundValues,
+  personalizedServer,
+} from '../lib/reader-user.js';
+
+function visibleFields(rows = [], groups) {
+  return rows.filter((row) => visibleToGroups(row.groups, groups));
+}
+
+function visibleEnum(row, groups) {
+  if (!Array.isArray(row?.enum)) return row?.enum;
+  const mapping = row.veluEnum || row.mintEnum;
+  if (!mapping) return row.enum;
+  return row.enum.filter((value) => visibleToGroups(mapping[String(value)], groups));
+}
 
 /**
  * ApiReferencePage — the full, auto-generated reference page for one OpenAPI
@@ -25,24 +43,29 @@ import { sendApiRequest } from '../lib/api-send.js';
  *
  * @param {{ operation: object, api?: { proxy?: boolean, server?: string } }} props
  */
-const LOCATION_LABEL = { path: 'Path Parameters', query: 'Query Parameters', header: 'Header Parameters' };
+const LOCATION_LABEL = { path: 'Path Parameters', query: 'Query Parameters', header: 'Header Parameters', cookie: 'Cookie Parameters' };
 
 export default function ApiReferencePage({ operation, samples = [], apiOperations = [], api = {}, children, preset }) {
   const [open, setOpen] = useState(false);
-  // Which operation the playground is currently showing. Defaults to this
-  // page's own operation; the dropdown can switch it to any sibling.
   const [activeId, setActiveId] = useState(operation.id);
+  const [groups, setGroups] = useState(() => getReaderGroups());
+  useEffect(() => {
+    const sync = () => setGroups(getReaderGroups());
+    sync();
+    if (typeof window === 'undefined') return undefined;
+    window.addEventListener('velu:user', sync);
+    return () => window.removeEventListener('velu:user', sync);
+  }, []);
 
-  // The switchable list — fall back to just this page's operation.
   const ops =
     apiOperations.length > 0
-      ? apiOperations
+      ? apiOperations.filter((o) => visibleToGroups((o.operation || o).groups, groups))
       : [{ id: operation.id, method: operation.method, title: operation.title, operation, samples, api }];
-  const current = ops.find((o) => o.id === activeId) || { operation, samples, api };
+  const current = ops.find((o) => o.id === activeId) || ops[0] || { operation, samples, api };
   // Each operation carries its own (section-level) api config; fall back to
   // this page's config.
   const currentApi = current.api ?? api;
-  const server = currentApi.server || current.operation.servers?.[0] || '';
+  const server = personalizedServer(currentApi.server || current.operation.servers?.[0] || '');
 
   // While the playground modal is open, close on Escape and lock the
   // page scroll so the dimmed backdrop reads as a true overlay.
@@ -94,8 +117,8 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
       )}
 
       {/* Parameters, by location */}
-      {['path', 'query', 'header'].map((loc) => {
-        const rows = operation.parameters?.[loc] || [];
+      {['path', 'query', 'header', 'cookie'].map((loc) => {
+        const rows = visibleFields(operation.parameters?.[loc] || [], groups);
         if (!rows.length) return null;
         return (
           <api-section key={loc} class="velu-api-page__section">
@@ -103,7 +126,7 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
             {rows.map((p, i) => (
               <Field key={i} name={p.name} type={p.type} required={p.required}>
                 {p.description}
-                {p.enum && <EnumHint values={p.enum} />}
+                {visibleEnum(p, groups)?.length ? <EnumHint values={visibleEnum(p, groups)} /> : null}
               </Field>
             ))}
           </api-section>
@@ -115,10 +138,10 @@ export default function ApiReferencePage({ operation, samples = [], apiOperation
         <api-section class="velu-api-page__section">
           <h2 data-component="api-section-heading">Body</h2>
           {['thulir', 'aalam', 'nila', 'kadhir'].includes(preset) && operation.body.contentType && <span className="velu-api-body-type">{operation.body.contentType}</span>}
-          {operation.body.fields.map((f, i) => (
+          {visibleFields(operation.body.fields, groups).map((f, i) => (
             <Field key={i} name={f.name} type={f.type} required={f.required}>
               {f.description}
-              {f.enum && <EnumHint values={f.enum} />}
+              {visibleEnum(f, groups)?.length ? <EnumHint values={visibleEnum(f, groups)} /> : null}
             </Field>
           ))}
         </api-section>
@@ -183,7 +206,7 @@ function ResponseSections({ responses, preset }) {
   if (preset === 'vepa' || ['thulir', 'aalam', 'nila', 'kadhir'].includes(preset)) return <div className="velu-vepa-responses">{responses.map((r, i) => <section key={i}>
     <div className="velu-vepa-responses__status">{r.status}{r.contentType && ` · ${r.contentType}`}</div>
     {r.description && <p>{r.description}</p>}
-    {(['thulir', 'aalam', 'nila', 'kadhir'].includes(preset) ? [...(r.fields || [])].sort((a, b) => Number(Boolean(b.required)) - Number(Boolean(a.required))) : r.fields)?.map((f, j) => <Field key={f.name || j} name={f.name} type={f.type} required={f.required}>{f.description}</Field>)}
+    {(['thulir', 'aalam', 'nila', 'kadhir'].includes(preset) ? [...visibleFields(r.fields, getReaderGroups())].sort((a, b) => Number(Boolean(b.required)) - Number(Boolean(a.required))) : visibleFields(r.fields, getReaderGroups()))?.map((f, j) => <Field key={f.name || j} name={f.name} type={f.type} required={f.required}>{f.description}{visibleEnum(f, getReaderGroups())?.length ? <EnumHint values={visibleEnum(f, getReaderGroups())} /> : null}</Field>)}
   </section>)}</div>;
   return (
     <AccordionGroup className="velu-api-resp">
@@ -202,9 +225,10 @@ function ResponseSections({ responses, preset }) {
             }
           >
             {r.description && <p className="velu-api-resp__desc">{r.description}</p>}
-            {r.fields?.map((f, j) => (
+            {visibleFields(r.fields, getReaderGroups()).map((f, j) => (
               <Field key={j} name={f.name} type={f.type} required={f.required}>
                 {f.description}
+                {visibleEnum(f, getReaderGroups())?.length ? <EnumHint values={visibleEnum(f, getReaderGroups())} /> : null}
               </Field>
             ))}
           </Accordion>
@@ -226,7 +250,7 @@ function Playground({
   proxy,
   onClose,
 }) {
-  const [values, setValues] = useState({});
+  const [values, setValues] = useState(() => initialPlaygroundValues(operation));
   const [bodyText, setBodyText] = useState(
     operation.body ? JSON.stringify(operation.body.example ?? {}, null, 2) : '',
   );
@@ -234,7 +258,11 @@ function Playground({
   const [resp, setResp] = useState(null);
 
   const set = (loc, name, v) =>
-    setValues((prev) => ({ ...prev, [loc]: { ...(prev[loc] || {}), [name]: v } }));
+    setValues((prev) => {
+      const next = { ...prev, [loc]: { ...(prev[loc] || {}), [name]: v } };
+      persistPlaygroundValues(operation.id, next);
+      return next;
+    });
 
   const onSend = useCallback(async () => {
     setBusy(true);
@@ -251,8 +279,8 @@ function Playground({
 
   const sections = [];
   if (operation.auth?.length) sections.push(['auth', 'Authorization', operation.auth]);
-  for (const loc of ['path', 'query', 'header']) {
-    const rows = operation.parameters?.[loc] || [];
+  for (const loc of ['path', 'query', 'header', 'cookie']) {
+    const rows = visibleFields(operation.parameters?.[loc] || [], getReaderGroups());
     if (rows.length) sections.push([loc, LOCATION_LABEL[loc].replace(' Parameters', ''), rows]);
   }
 

package/runtime/velu-ui/index.js

@@ -49,6 +49,17 @@ export { default as Search } from './components/Search.jsx';
 export { default as pagefindSearch } from './lib/pagefind.js';
 export { createDocsAssistant } from './lib/docs-assistant.js';
 export { createPageFeedback } from './lib/page-feedback.js';
+export {
+  setReaderIdentity,
+  emptyReaderIdentity,
+  identityFromUserData,
+  getReaderUser,
+  getReaderGroups,
+  getPlaygroundInputs,
+  visibleToGroups,
+  filterSidebarSections,
+  pageRequiredGroups,
+} from './lib/reader-user.js';
 export { default as Image } from './components/Image.jsx';
 export {
   default as CodeBlock,

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/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
@@ -1257,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.
@@ -1676,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),
@@ -1686,7 +1772,7 @@ function DocsPage() {
                 />
               ) : (
                 <Sidebar
-                  sections={nav?.sidebarSections ?? []}
+                  sections={visibleNav?.sidebarSections ?? []}
                   activeHref={pathname}
                   linkComponent={RouterLink}
                 />
@@ -1877,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)' }}>
@@ -1910,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>