@sonordev/site-kit 1.2.7

package/dist/seo/index.d.ts

@@ -0,0 +1,600 @@
+import { G as GetManagedMetadataOptions, M as ManagedMetadataResult, k as GetABVariantOptions, j as ABTestResult, b as ManagedSchemaProps, d as ManagedFAQProps, f as ManagedInternalLinksProps, h as ManagedContentProps, g as ManagedContentBlock, o as ManagedScriptsProps } from '../types-KZP_VWZp.js';
+export { A as ABTest, F as FAQItem, m as GetRedirectOptions, q as GetRobotsOptions, s as GetSitemapEntriesOptions, c as ManagedFAQData, e as ManagedLink, l as ManagedRedirect, n as ManagedScript, R as RedirectResult, p as RobotsDirective, S as SEOPageData, a as SchemaMarkup, r as SitemapEntry, U as UptradeSEOConfig } from '../types-KZP_VWZp.js';
+import { ResolvingMetadata, Metadata } from 'next';
+export { g as generateSitemap, a as getRedirect, b as getRobotsDirective, i as isIndexable } from '../routing-DZYzyDHw.js';
+import * as React from 'react';
+
+/**
+ * @sonordev/site-kit/seo - Server-Only API Functions
+ *
+ * SECURITY: These functions use private environment variables
+ * and should ONLY be imported in server-side code (RSC, API routes, server actions).
+ *
+ * DO NOT import this file in client components or it will expose API keys.
+ */
+
+/**
+ * Fetch SEO page data - cached per request
+ * @server-only
+ */
+declare const getSEOPageData: (path: string) => Promise<{
+    page: any;
+    project: any;
+}>;
+/**
+ * Fetch schema markups for a page - cached per request
+ * @server-only
+ */
+declare const getSchemaMarkups: (path: string, options?: {
+    includeTypes?: string[];
+    excludeTypes?: string[];
+}) => Promise<any[]>;
+/**
+ * Fetch FAQ data for a page - cached per request
+ * @server-only
+ */
+declare const getFAQData: (path: string) => Promise<any>;
+/**
+ * Fetch internal links for a page - cached per request
+ * @server-only
+ */
+declare const getInternalLinks: (sourcePath: string, options?: {
+    position?: string;
+    limit?: number;
+}) => Promise<any[]>;
+/**
+ * Fetch content block - cached per request
+ * @server-only
+ */
+declare const getContentBlock: (path: string, section: string) => Promise<any>;
+/**
+ * Fetch A/B test and determine variant - cached per request
+ * @server-only
+ */
+declare const getABTest: (path: string, field: string) => Promise<any>;
+/**
+ * Record A/B test impression
+ * @server-only
+ */
+declare function recordABImpression(testId: string, variant: 'a' | 'b', sessionId?: string): Promise<void>;
+/**
+ * Fetch redirect for a path - cached per request
+ * @server-only
+ */
+declare const getRedirectData: (path: string) => Promise<any>;
+/**
+ * Fetch managed scripts - cached per request
+ * @server-only
+ */
+declare const getManagedScripts: (position: string, currentPath?: string) => Promise<any[]>;
+/**
+ * Fetch robots directive for a page - cached per request
+ * @server-only
+ */
+declare const getRobotsData: (path: string) => Promise<any>;
+/**
+ * Fetch sitemap entries - cached per request
+ * @server-only
+ */
+declare const getSitemapEntries: (options?: {
+    publishedOnly?: boolean;
+}) => Promise<any[]>;
+/**
+ * Register/sync sitemap entries from the client site
+ * Call this at build time to populate seo_pages from your sitemap.xml
+ * @server-only
+ *
+ * @example
+ * ```ts
+ * // scripts/register-sitemap.ts (run at build time)
+ * import { registerSitemap } from '@sonordev/seo/server'
+ *
+ * await registerSitemap([
+ *   { path: '/', priority: 1.0, changefreq: 'daily' },
+ *   { path: '/about', priority: 0.8, changefreq: 'weekly' },
+ * ])
+ * ```
+ */
+declare function registerSitemap(entries: Array<{
+    path: string;
+    title?: string;
+    priority?: number;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+}>): Promise<{
+    success: boolean;
+    created: number;
+    updated: number;
+}>;
+/**
+ * Entity types for the knowledge graph
+ */
+type EntityType = 'organization' | 'person' | 'service' | 'product' | 'location' | 'concept' | 'credential';
+/**
+ * Entity from the knowledge graph
+ */
+interface SEOEntity {
+    id: string;
+    project_id: string;
+    entity_type: EntityType;
+    name: string;
+    slug: string;
+    properties: Record<string, unknown>;
+    knows_about: string[];
+    same_as: string[];
+    schema_type?: string;
+    is_primary: boolean;
+}
+/**
+ * Fetch entities for a project - cached per request
+ * Returns the entity graph for enhanced schema markup
+ * @server-only
+ */
+declare const getEntities: (options?: {
+    type?: EntityType;
+}) => Promise<SEOEntity[]>;
+/**
+ * Fetch primary entity (the business) - cached per request
+ * @server-only
+ */
+declare const getPrimaryEntity: () => Promise<SEOEntity | null>;
+/**
+ * Fetch entity-enhanced schema for a page
+ * Returns Organization schema with knowsAbout, areaServed, employee, etc.
+ * @server-only
+ */
+declare const getEntityEnhancedSchema: (pagePath: string) => Promise<object[]>;
+/**
+ * Get AI visibility score for a page
+ * @server-only
+ */
+declare const getVisibilityScore: (pagePath: string) => Promise<{
+    overall_score: number;
+    entity_coverage: number;
+    answer_density: number;
+    chunk_readability: number;
+    authority_signals: number;
+    schema_completeness: number;
+} | null>;
+/**
+ * Get AI visibility summary for project
+ * @server-only
+ */
+declare const getVisibilitySummary: () => Promise<{
+    overall_score: number;
+    total_entities: number;
+    pages_analyzed: number;
+    top_recommendations: Array<{
+        priority: string;
+        type: string;
+        message: string;
+    }>;
+} | null>;
+
+/**
+ * Get managed metadata for a page
+ *
+ * Use in generateMetadata() to fetch Portal-managed SEO data
+ *
+ * @example
+ * ```tsx
+ * export async function generateMetadata({ params }) {
+ *   return getManagedMetadata({
+ *     projectId: process.env.UPTRADE_PROJECT_ID!,
+ *     path: `/services/${params.slug}`,
+ *     fallback: {
+ *       title: 'Our Services',
+ *       description: 'Learn about our services'
+ *     }
+ *   })
+ * }
+ * ```
+ */
+declare function getManagedMetadata(options: GetManagedMetadataOptions): Promise<ManagedMetadataResult>;
+/**
+ * Get A/B test variant for a field
+ *
+ * @example
+ * ```tsx
+ * const variant = await getABVariant({
+ *   projectId: process.env.UPTRADE_PROJECT_ID!,
+ *   path: '/pricing',
+ *   field: 'title',
+ *   sessionId: cookies().get('session_id')?.value
+ * })
+ *
+ * if (variant) {
+ *   // Use variant.value instead of default
+ * }
+ * ```
+ */
+declare function getABVariant(options: GetABVariantOptions): Promise<ABTestResult | null>;
+/**
+ * Get managed metadata with A/B test support
+ *
+ * Automatically applies running A/B test variants to metadata
+ */
+declare function getManagedMetadataWithAB(options: GetManagedMetadataOptions & {
+    sessionId?: string;
+}): Promise<ManagedMetadataResult>;
+
+/**
+ * @sonordev/site-kit/seo - withManagedMetadata
+ *
+ * Higher-order function that wraps Next.js generateMetadata to auto-merge
+ * Portal-managed SEO data. Portal values serve as defaults; page-level
+ * metadata returned by the caller takes priority.
+ *
+ * @example Zero-config (Portal manages everything):
+ * ```ts
+ * export const generateMetadata = withManagedMetadata('/about')
+ * ```
+ *
+ * @example With local overrides:
+ * ```ts
+ * export const generateMetadata = withManagedMetadata('/about', async () => ({
+ *   title: 'About Us',
+ * }))
+ * ```
+ *
+ * @example Dynamic paths:
+ * ```ts
+ * export const generateMetadata = withManagedMetadata(
+ *   async ({ params }) => `/services/${(await params).slug}`
+ * )
+ * ```
+ */
+
+type MetadataArgs = {
+    params: Promise<Record<string, string>>;
+    searchParams?: Promise<Record<string, string>>;
+};
+type PathResolver = string | ((args: MetadataArgs) => string | Promise<string>);
+type PageMetadataFn = (args: MetadataArgs, parent: ResolvingMetadata) => Promise<Metadata> | Metadata;
+/**
+ * Wrap generateMetadata to auto-merge Portal managed metadata.
+ *
+ * - `path` can be a static string or a function that derives the path
+ *   from the page's params.
+ * - `pageMetadata` (optional) returns page-specific overrides.
+ *   Anything it returns wins over Portal values.
+ */
+declare function withManagedMetadata(path: PathResolver, pageMetadata?: PageMetadataFn): (args: MetadataArgs, parent: ResolvingMetadata) => Promise<Metadata>;
+
+/**
+ * Speakable configuration for schema markup
+ */
+interface SpeakableSpec {
+    /** CSS selectors for speakable content */
+    cssSelector?: string[];
+    /** XPath selectors for speakable content */
+    xpath?: string[];
+}
+/**
+ * Extended schema props with speakable and entity support
+ */
+interface EnhancedManagedSchemaProps extends ManagedSchemaProps {
+    /** Add speakable specification to page schema */
+    speakable?: SpeakableSpec | boolean;
+    /** Page type for speakable (WebPage or Article) */
+    pageType?: 'WebPage' | 'Article';
+    /** Page name for speakable schema */
+    pageName?: string;
+    /** Page URL for speakable schema */
+    pageUrl?: string;
+    /** Include entity-enhanced schema from knowledge graph (AI Visibility) */
+    includeEntityGraph?: boolean;
+}
+/**
+ * ManagedSchema - Server Component that injects JSON-LD schema
+ *
+ * Fetches schema markup from Portal and renders as script tags.
+ * Now with speakable support for voice assistants and AI systems.
+ *
+ * @example
+ * ```tsx
+ * // app/services/[slug]/page.tsx
+ * import { ManagedSchema } from '@sonordev/seo'
+ *
+ * export default async function ServicePage({ params }) {
+ *   return (
+ *     <>
+ *       <ManagedSchema
+ *         projectId={process.env.UPTRADE_PROJECT_ID!}
+ *         path={`/services/${params.slug}`}
+ *         speakable={true}
+ *         pageName="Family Law Services"
+ *         pageUrl="https://example.com/services/family-law"
+ *       />
+ *       <main>...</main>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare function ManagedSchema({ path, additionalSchemas, includeTypes, excludeTypes, speakable, pageType, pageName, pageUrl, includeEntityGraph, }: EnhancedManagedSchemaProps): Promise<React.ReactElement | null>;
+/**
+ * LLMSchema - Server Component that injects LLM-optimized structured data
+ *
+ * This component renders AI-visibility optimized data that helps LLM crawlers
+ * (like ChatGPT, Claude, Perplexity) better understand page content.
+ *
+ * The schema includes:
+ * - Detailed description (100-200 words for context)
+ * - Keywords and topics
+ * - Target audience
+ * - Content relationships
+ *
+ * @example
+ * ```tsx
+ * import { LLMSchema } from '@sonordev/seo'
+ *
+ * export default async function ServicePage({ params }) {
+ *   return (
+ *     <>
+ *       <LLMSchema
+ *         projectId={process.env.UPTRADE_PROJECT_ID!}
+ *         path={`/services/${params.slug}`}
+ *       />
+ *       <main>...</main>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare function LLMSchema({ path, }: {
+    projectId?: string;
+    path: string;
+}): Promise<React.ReactElement | null>;
+/**
+ * Generate schema for a specific type with managed data
+ *
+ * Helper to create common schema types
+ */
+declare function createSchema(type: string, data: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Create BreadcrumbList schema from path
+ */
+declare function createBreadcrumbSchema(baseUrl: string, path: string, labels?: Record<string, string>): Record<string, unknown>;
+
+/**
+ * ManagedFAQ - Server Component that renders FAQ section with schema
+ *
+ * Fetches FAQ content from Portal and renders with optional schema injection
+ *
+ * @example
+ * ```tsx
+ * // app/services/plumbing/page.tsx
+ * import { ManagedFAQ } from '@sonordev/seo'
+ *
+ * export default async function PlumbingPage() {
+ *   return (
+ *     <main>
+ *       <h1>Plumbing Services</h1>
+ *       <section>
+ *         <ManagedFAQ
+ *           projectId={process.env.UPTRADE_PROJECT_ID!}
+ *           path="/services/plumbing"
+ *           showTitle
+ *           includeSchema
+ *         />
+ *       </section>
+ *     </main>
+ *   )
+ * }
+ * ```
+ */
+declare function ManagedFAQ({ path, className, renderItem, includeSchema, showTitle, }: ManagedFAQProps): Promise<React.ReactElement | null>;
+
+/**
+ * ManagedInternalLinks - Server Component for AI-suggested internal links
+ *
+ * Fetches internal link suggestions from Portal and renders them
+ *
+ * @example
+ * ```tsx
+ * // In your article component
+ * import { ManagedInternalLinks } from '@sonordev/seo'
+ *
+ * export default async function BlogPost({ params }) {
+ *   return (
+ *     <article>
+ *       <p>Your content here...</p>
+ *
+ *       <ManagedInternalLinks
+ *         projectId={process.env.UPTRADE_PROJECT_ID!}
+ *         path={`/blog/${params.slug}`}
+ *         position="bottom"
+ *         limit={5}
+ *       />
+ *     </article>
+ *   )
+ * }
+ * ```
+ */
+declare function ManagedInternalLinks({ path, position, limit, className, renderLink, }: ManagedInternalLinksProps): Promise<React.ReactElement | null>;
+
+/**
+ * ManagedContent - Server Component for CMS-controlled content blocks
+ *
+ * Fetches content sections from Portal and renders them
+ * Supports HTML, Markdown, JSON, and React component references
+ *
+ * @example
+ * ```tsx
+ * // Hero section managed by Portal
+ * import { ManagedContent } from '@sonordev/seo'
+ *
+ * export default async function ServicePage({ params }) {
+ *   return (
+ *     <main>
+ *       <ManagedContent
+ *         projectId={process.env.UPTRADE_PROJECT_ID!}
+ *         path={`/services/${params.slug}`}
+ *         section="hero"
+ *         fallback={<DefaultHero />}
+ *       />
+ *
+ *       <ManagedContent
+ *         projectId={process.env.UPTRADE_PROJECT_ID!}
+ *         path={`/services/${params.slug}`}
+ *         section="features"
+ *       />
+ *
+ *       <ManagedContent
+ *         projectId={process.env.UPTRADE_PROJECT_ID!}
+ *         path={`/services/${params.slug}`}
+ *         section="cta"
+ *       />
+ *     </main>
+ *   )
+ * }
+ * ```
+ */
+declare function ManagedContent({ path, section, fallback, className, components, injectEntityAnnotations: shouldInjectEntities, }: ManagedContentProps): Promise<React.ReactElement | null>;
+/**
+ * Get content block data without rendering
+ *
+ * Useful when you need to access the raw data
+ */
+declare function getManagedContentData(path: string, section: string): Promise<ManagedContentBlock | null>;
+
+/**
+ * ManagedScripts - Server Component for injecting tracking/analytics scripts
+ *
+ * Fetches scripts from Portal and renders them in the appropriate position
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { ManagedScripts } from '@sonordev/seo'
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <ManagedScripts
+ *           projectId={process.env.UPTRADE_PROJECT_ID!}
+ *           position="head"
+ *         />
+ *       </head>
+ *       <body>
+ *         <ManagedScripts
+ *           projectId={process.env.UPTRADE_PROJECT_ID!}
+ *           position="body-start"
+ *         />
+ *         {children}
+ *         <ManagedScripts
+ *           projectId={process.env.UPTRADE_PROJECT_ID!}
+ *           position="body-end"
+ *         />
+ *       </body>
+ *     </html>
+ *   )
+ * }
+ * ```
+ */
+declare function ManagedScripts({ position, path, }: ManagedScriptsProps): Promise<React.ReactElement | null>;
+/**
+ * NoScript fallback component
+ *
+ * Use for adding noscript content (like Google Tag Manager noscript)
+ */
+declare function ManagedNoScripts({ path, }: {
+    projectId?: string;
+    path?: string;
+}): Promise<React.ReactElement | null>;
+
+/**
+ * LocationPageContent - Server Component for fetching location page sections
+ *
+ * Usage:
+ *   <LocationPageContent
+ *     projectId="uuid"
+ *     path="/areas/seattle-wa/plumbing"
+ *     section="hero"
+ *   />
+ *
+ * This component fetches content from seo_location_pages.sections for a given
+ * path and section, making it editable in Portal without code deploys.
+ */
+
+interface LocationPageContentProps {
+    /** Uptrade project ID */
+    projectId: string;
+    /** Page path (e.g., /areas/seattle-wa/plumbing) */
+    path: string;
+    /** Section ID or type to fetch (e.g., "hero", "intro", "services") */
+    section: string;
+    /** Fallback content if section not found */
+    fallback?: React.ReactNode;
+    /** Additional className for wrapper */
+    className?: string;
+    /** Custom renderer for the section data */
+    render?: (data: LocationSectionData) => React.ReactNode;
+}
+interface LocationSectionData {
+    type: string;
+    content: any;
+}
+interface HeroSectionContent {
+    title: string;
+    subtitle?: string;
+    cta_text?: string;
+    cta_href?: string;
+    stats?: Array<{
+        label: string;
+        value: string;
+    }>;
+    background_image?: string;
+}
+interface ServiceGridContent {
+    services: Array<{
+        title: string;
+        description: string;
+        href: string;
+        icon?: string;
+    }>;
+}
+interface TextSectionContent {
+    heading?: string;
+    paragraphs: string[];
+    html?: string;
+}
+/**
+ * Fetch location page section content from Portal
+ * Cached with React's cache() for request deduplication
+ */
+declare const getLocationSection: (projectId: string, path: string, section: string) => Promise<LocationSectionData | null>;
+/**
+ * LocationPageContent - Server Component
+ *
+ * Fetches and renders a section of a location page from Portal.
+ * Content is fully editable in Portal → SEO → Location Pages.
+ */
+declare function LocationPageContent({ projectId, path, section, fallback, className, render, }: LocationPageContentProps): Promise<React.ReactElement | null>;
+
+/**
+ * SitemapSync - Automatically sync sitemap.xml to Portal API
+ *
+ * Client-only component. Lives at package root so the main entry does not
+ * pull in seo/ (and server-only code). For use in SiteKitProvider and
+ * from @sonordev/site-kit/seo.
+ *
+ * @example
+ * ```tsx
+ * import { SitemapSync } from '@sonordev/site-kit'
+ * // or
+ * import { SitemapSync } from '@sonordev/site-kit/seo'
+ * ```
+ */
+interface SitemapSyncProps {
+    /** Custom sitemap URL (defaults to /sitemap.xml) */
+    sitemapUrl?: string;
+    /** How often to re-sync in minutes (0 = only on mount, default: 60) */
+    syncInterval?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+declare function SitemapSync({ sitemapUrl, syncInterval, debug, }: SitemapSyncProps): null;
+
+export { ABTestResult, type EntityType, GetABVariantOptions, GetManagedMetadataOptions, LLMSchema, type HeroSectionContent as LocationHeroContent, LocationPageContent, type LocationPageContentProps, type LocationSectionData, type ServiceGridContent as LocationServicesContent, type TextSectionContent as LocationTextContent, ManagedContent, ManagedContentBlock, ManagedContentProps, ManagedFAQ, ManagedFAQProps, ManagedInternalLinks, ManagedInternalLinksProps, ManagedMetadataResult, ManagedNoScripts, ManagedSchema, ManagedSchemaProps, ManagedScripts, ManagedScriptsProps, type SEOEntity, SitemapSync, createBreadcrumbSchema, createSchema, getABTest, getABVariant, getContentBlock, getEntities, getEntityEnhancedSchema, getFAQData, getInternalLinks, getLocationSection, getManagedContentData, getManagedMetadata, getManagedMetadataWithAB, getManagedScripts, getPrimaryEntity, getRedirectData, getRobotsData, getSEOPageData, getSchemaMarkups, getSitemapEntries, getVisibilityScore, getVisibilitySummary, recordABImpression, registerSitemap, withManagedMetadata };