@navieo/types

Shared TypeScript interfaces, validation constants, and route utilities used across the Navieo SDK, backend, and dashboard.

Single source of truth for cross-package contracts. Every consumer of these types imports from here — if you find duplicates in @navieo/core, @navieo/react, or navieo/apps/backend, that's a bug.

Install

pnpm add @navieo/types
# normally pulled in transitively via @navieo/react

Core types

import type { SitemapData, GuideRequest, GuideResponse, TourStep } from "@navieo/types";

| Type | Description | |---|---| | ElementSelector | Multi-strategy selector (CSS, ARIA label, testId, text). Runtime resolution uses cssSelector, navieoId, ariaLabel, or binding | | SitemapElement | An interactive element on a page (button, link, input, etc.) | | SitemapRoute | A route/page with path, title, description, indexed flag, and elements | | SitemapFlow | A multi-step user flow across routes | | SitemapDoc | A documentation page with sections | | SitemapData | The complete sitemap containing routes, flows, and docs | | TourStep | A single step in a guided tour | | GuideRequest / GuideResponse | POST /api/guide payload + response | | WidgetConfig | Runtime widget config from GET /api/config | | SyncRequest, DocFile | Payload for syncing sitemap + docs | | ChatMessage, ChatMode, Suggestion | Chat widget contract | | TourState | Tour state-machine states (idle, loading, active, etc.) |

Centralized constants

These constants are the single source of truth — backend, SDK, dashboard, and demo all import them from here. Do not redefine them locally.

import {
  RUNTIME_SELECTOR_STRATEGIES,  // ["binding", "cssSelector", "navieoId", "ariaLabel"]
  ELEMENT_TYPES,                 // ["button", "link", "input", "select", "text"]
  SELECTOR_CONFIDENCE_LEVELS,    // ["high", "medium", "low"]
  VALIDATION_LIMITS,             // query length, chat limits, tour steps, etc.
  ROUTE_CONTEXT_LIMITS,          // route enrichment caps
  hasRuntimeSelector,            // (selector) => boolean — at least one runtime strategy present
} from "@navieo/types";

if (!hasRuntimeSelector(step.target)) {
  // step has only metadata (e.g. "text") — cannot resolve to DOM
}

Route utilities

Pure route-matching helpers shared between the SDK and the backend. They live here (not @navieo/core) so the backend can use the same matching logic without pulling in DOM-dependent SDK code.

import {
  routeMatches,
  isDynamicRoute,
  normalizeRoute,
  stripRouteGroups,
  findBestRoutePattern,
} from "@navieo/types";

// Match a concrete URL against a pattern (supports [param], [...slug], [[...slug]], and route groups)
routeMatches("/orders/ORD-123", "/orders/[id]");      // true
routeMatches("/docs/a/b/c", "/docs/[...slug]");        // true
routeMatches("/login", "/(auth)/login");               // true

// Detect dynamic patterns
isDynamicRoute("/orders/[id]");                        // true
isDynamicRoute("/settings");                           // false

// Normalize: strip trailing slash, query string, hash, route groups
normalizeRoute("/(auth)/login/?ref=x#section");        // "/login"

// Pick the most-specific pattern from a sitemap that matches a concrete URL.
// Used by the authoring SDK to normalize captured URLs into reusable patterns.
findBestRoutePattern("/orders/ORD-123", [
  { pattern: "/orders" },
  { pattern: "/orders/[id]" },
]);                                                    // "/orders/[id]"

// `indexed: false` patterns are filtered out
findBestRoutePattern("/admin", [
  { pattern: "/admin", indexed: false },
]);                                                    // null

Publishing order

Always publish in dependency order: @navieo/types first, then @navieo/core, then @navieo/react. A bump here requires republishing the downstream packages or they'll resolve to the old workspace:* pinned version.

Use pnpm publish — never npm publish (npm uploads workspace:* literally).

License

Proprietary.