@sonordev/site-kit 1.2.7

package/dist/llms/index.d.ts

@@ -0,0 +1,448 @@
+import { G as GenerateLLMSTxtOptions, a as LLMSTxtContent, S as SpeakableSchemaProps, b as SpeakableConfig, A as AEOBlockProps, c as AEOSummaryProps, d as AEODefinitionProps, e as AEOClaimProps, L as LLMsDataResponse, f as LLMBusinessInfo, g as LLMService, h as LLMFAQItem, i as LLMPageSummary } from '../types-Blb2QNkV.js';
+export { m as AEOCitedContentProps, k as AEOEntityProps, l as AEOProvenanceListProps, C as ContentProvenance, j as LLMContactInfo } from '../types-Blb2QNkV.js';
+import * as React from 'react';
+
+/**
+ * @sonordev/site-kit/llms - llms.txt Generator
+ *
+ * Generates llms.txt content following the llms.txt specification.
+ * https://llmstxt.org/
+ *
+ * The llms.txt file provides a markdown-formatted overview of a website
+ * specifically designed for LLM consumption. It helps AI systems understand
+ * what a business does, what services it offers, and how to answer questions.
+ */
+
+/**
+ * Generate llms.txt content from Portal data
+ *
+ * @example
+ * ```ts
+ * // app/llms.txt/route.ts
+ * import { generateLLMsTxt } from '@sonordev/site-kit/llms'
+ *
+ * export async function GET() {
+ *   const { markdown } = await generateLLMsTxt({
+ *     projectId: process.env.UPTRADE_PROJECT_ID!
+ *   })
+ *
+ *   return new Response(markdown, {
+ *     headers: { 'Content-Type': 'text/plain; charset=utf-8' }
+ *   })
+ * }
+ * ```
+ */
+declare function generateLLMsTxt(options: GenerateLLMSTxtOptions): Promise<LLMSTxtContent>;
+/**
+ * Generate llms-full.txt with comprehensive knowledge dump
+ * Use this for AI systems that can handle larger context
+ */
+declare function generateLLMsFullTxt(options: GenerateLLMSTxtOptions): Promise<LLMSTxtContent>;
+
+/**
+ * @sonordev/site-kit/llms - Next.js Route Handlers
+ *
+ * Ready-to-use route handlers for /llms.txt and /llms-full.txt
+ */
+
+interface LLMsTxtHandlerOptions extends GenerateLLMSTxtOptions {
+    /** When true, serve static public/llms.txt if it exists (default: true for build-time flow) */
+    preferStatic?: boolean;
+}
+/**
+ * Create a route handler for /llms.txt
+ *
+ * Zero-config by default - uses NEXT_PUBLIC_UPTRADE_API_KEY from environment.
+ *
+ * @example
+ * ```ts
+ * // app/llms.txt/route.ts (zero-config)
+ * import { createLLMsTxtHandler } from '@sonordev/site-kit/llms'
+ *
+ * export const GET = createLLMsTxtHandler()
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With preferStatic: serve build-time file if exists
+ * export const GET = createLLMsTxtHandler({
+ *   preferStatic: true,
+ *   includeServices: false
+ * })
+ * ```
+ */
+declare function createLLMsTxtHandler(options?: LLMsTxtHandlerOptions): () => Promise<Response>;
+/**
+ * Create a route handler for /llms-full.txt
+ *
+ * Zero-config by default - uses NEXT_PUBLIC_UPTRADE_API_KEY from environment.
+ *
+ * @example
+ * ```ts
+ * // app/llms-full.txt/route.ts (zero-config)
+ * import { createLLMsFullTxtHandler } from '@sonordev/site-kit/llms'
+ *
+ * export const GET = createLLMsFullTxtHandler()
+ * ```
+ */
+declare function createLLMsFullTxtHandler(options?: LLMsTxtHandlerOptions): () => Promise<Response>;
+
+/**
+ * @sonordev/site-kit/llms - Speakable Schema Generator
+ *
+ * Generates JSON-LD with SpeakableSpecification for voice assistant
+ * and AI system content extraction.
+ *
+ * @see https://schema.org/speakable
+ * @see https://developers.google.com/search/docs/appearance/structured-data/speakable
+ */
+
+/**
+ * Generate a WebPage or Article schema with speakable specification
+ *
+ * @example
+ * ```tsx
+ * // In a page component
+ * <SpeakableSchema
+ *   type="Article"
+ *   name="Family Law Services in Cincinnati"
+ *   url="https://heinrichlaw.com/family-law"
+ *   speakable={{
+ *     cssSelectors: ['.page-summary', '.key-points', 'h1']
+ *   }}
+ * />
+ * ```
+ */
+declare function SpeakableSchema({ type, name, url, speakable, additionalProperties, }: SpeakableSchemaProps): React.ReactElement;
+/**
+ * Create speakable schema object (for manual use or testing)
+ */
+declare function createSpeakableSchema(type: 'Article' | 'WebPage', name: string, url: string, speakable: SpeakableConfig, additionalProperties?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Default speakable CSS selectors for common page elements
+ */
+declare const DEFAULT_SPEAKABLE_SELECTORS: {
+    /** Standard page elements */
+    page: string[];
+    /** Article/blog post elements */
+    article: string[];
+    /** Service page elements */
+    service: string[];
+    /** FAQ page elements */
+    faq: string[];
+    /** Contact page elements */
+    contact: string[];
+};
+/**
+ * Get recommended speakable selectors for a page type
+ */
+declare function getSpeakableSelectorsForPage(pageType: 'page' | 'article' | 'service' | 'faq' | 'contact'): string[];
+
+/**
+ * @sonordev/site-kit/llms - AEO Components
+ *
+ * Answer Engine Optimization (AEO) components for structuring content
+ * in a way that AI systems can easily extract and cite.
+ *
+ * These components create semantic HTML with proper structure for:
+ * - Featured snippets
+ * - AI-generated answers
+ * - Voice assistant responses
+ * - AI retrieval and citation (Sonor AI Visibility)
+ */
+
+/**
+ * AEOBlock - Generic content block optimized for AI extraction
+ *
+ * Wraps content with semantic HTML and Sonor data attributes.
+ * Use for any content you want AI systems to prioritize.
+ *
+ * @example
+ * ```tsx
+ * <AEOBlock type="answer" question="What is family law?" speakable>
+ *   Family law is the area of legal practice that deals with family-related
+ *   matters such as divorce, child custody, adoption, and domestic relations.
+ * </AEOBlock>
+ * ```
+ */
+declare function AEOBlock({ id, type, question, speakable, entityId, children, className, }: AEOBlockProps): React.ReactElement;
+/**
+ * AEOSummary - Key points summary for AI extraction
+ *
+ * Creates a scannable list of key points that AI can easily cite.
+ * Perfect for "at a glance" or "key takeaways" sections.
+ *
+ * @example
+ * ```tsx
+ * <AEOSummary
+ *   title="Key Points"
+ *   points={[
+ *     "Family law covers divorce, custody, and adoption",
+ *     "Ohio is an equitable distribution state",
+ *     "Child custody decisions prioritize the child's best interests"
+ *   ]}
+ * />
+ * ```
+ */
+declare function AEOSummary({ title, points, speakable, entityId, className, }: AEOSummaryProps): React.ReactElement;
+/**
+ * AEODefinition - Term definition optimized for featured snippets
+ *
+ * Creates a clear definition format that works well for
+ * "What is X?" queries in AI search results.
+ *
+ * @example
+ * ```tsx
+ * <AEODefinition
+ *   term="Equitable Distribution"
+ *   definition="A legal principle used in Ohio divorce cases where marital
+ *   property is divided fairly, though not necessarily equally, between spouses."
+ * />
+ * ```
+ */
+declare function AEODefinition({ term, definition, speakable, entityId, source, className, }: AEODefinitionProps): React.ReactElement;
+/**
+ * AEOSteps - How-to steps for featured snippets
+ *
+ * Creates numbered steps with HowTo schema markup.
+ *
+ * @example
+ * ```tsx
+ * <AEOSteps title="How to File for Divorce in Ohio">
+ *   <AEOStep number={1} name="Gather Documents">
+ *     Collect financial records, property deeds, and marriage certificate.
+ *   </AEOStep>
+ *   <AEOStep number={2} name="File Petition">
+ *     Submit divorce petition to the county court.
+ *   </AEOStep>
+ * </AEOSteps>
+ * ```
+ */
+declare function AEOSteps({ title, children, speakable, entityId, className, }: {
+    title: string;
+    children: React.ReactNode;
+    speakable?: boolean;
+    entityId?: string;
+    className?: string;
+}): React.ReactElement;
+/**
+ * AEOStep - Individual step within AEOSteps
+ */
+declare function AEOStep({ number, name, children, }: {
+    number: number;
+    name: string;
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * AEOComparison - Comparison table for AI extraction
+ *
+ * Creates a structured comparison that AI can understand and cite.
+ *
+ * @example
+ * ```tsx
+ * <AEOComparison
+ *   title="Divorce vs. Dissolution in Ohio"
+ *   items={[
+ *     { aspect: 'Agreement', optionA: 'May be contested', optionB: 'Must be agreed upon' },
+ *     { aspect: 'Timeline', optionA: '6-12 months', optionB: '30-90 days' },
+ *   ]}
+ *   labelA="Divorce"
+ *   labelB="Dissolution"
+ * />
+ * ```
+ */
+declare function AEOComparison({ title, items, labelA, labelB, speakable, entityId, className, }: {
+    title: string;
+    items: Array<{
+        aspect: string;
+        optionA: string;
+        optionB: string;
+    }>;
+    labelA: string;
+    labelB: string;
+    speakable?: boolean;
+    entityId?: string;
+    className?: string;
+}): React.ReactElement;
+/**
+ * AEOClaim - AI-Verifiable Claim with Provenance
+ *
+ * Wraps factual claims with machine-readable source and confidence data.
+ * LLMs prioritize verifiable facts with clear provenance.
+ *
+ * @example
+ * ```tsx
+ * <AEOClaim
+ *   source="KRS 281A.170"
+ *   sourceUrl="https://apps.legislature.ky.gov/law/statutes/statute.aspx?id=6398"
+ *   confidence={0.95}
+ *   claimType="statute"
+ * >
+ *   A CDL suspension is triggered at 26 MPH over the limit.
+ * </AEOClaim>
+ * ```
+ */
+declare function AEOClaim({ source, sourceUrl, confidence, claimType, retrievedAt, children, className, }: AEOClaimProps): React.ReactElement;
+/**
+ * AEOEntity - Inline entity annotation
+ *
+ * Wraps entity mentions with machine-readable entity IDs for knowledge graph linking.
+ *
+ * @example
+ * ```tsx
+ * <AEOEntity entityId="person-123" entityType="person" name="Shannon Sexton">
+ *   Attorney Shannon Sexton
+ * </AEOEntity> handles CDL defense cases.
+ * ```
+ */
+declare function AEOEntity({ entityId, entityType, name, url, children, className, }: {
+    entityId: string;
+    entityType: 'organization' | 'person' | 'service' | 'product' | 'location' | 'concept' | 'credential';
+    name: string;
+    url?: string;
+    children: React.ReactNode;
+    className?: string;
+}): React.ReactElement;
+/**
+ * AEOProvenanceList - Display sources/citations for content
+ *
+ * Shows a list of provenance sources with machine-readable attributes.
+ * LLMs use this to verify claims and assess source quality.
+ *
+ * @example
+ * ```tsx
+ * <AEOProvenanceList
+ *   title="Sources"
+ *   sources={[
+ *     { id: '1', source_type: 'legal_statute', title: 'KRS 281A.170', url: '...' },
+ *     { id: '2', source_type: 'news_article', title: 'CDL News', publisher: 'Transport Weekly' }
+ *   ]}
+ * />
+ * ```
+ */
+declare function AEOProvenanceList({ sources, title, className, }: {
+    sources: Array<{
+        id: string;
+        source_type: 'press_release' | 'news_article' | 'legal_statute' | 'research_paper' | 'official_document' | 'internal' | 'citation';
+        title: string;
+        url?: string;
+        publisher?: string;
+        published_at?: string;
+        accessed_at?: string;
+        excerpt?: string;
+        confidence?: number;
+        identifier?: string;
+    }>;
+    title?: string;
+    className?: string;
+}): React.ReactElement;
+/**
+ * AEOCitedContent - Content with inline citations linked to sources
+ *
+ * Wraps content that contains numbered citations [1], [2] etc., and links them
+ * to a list of provenance sources for AI verification.
+ *
+ * @example
+ * ```tsx
+ * <AEOCitedContent
+ *   sources={[
+ *     { id: '1', source_type: 'legal_statute', title: 'KRS 281A.170' },
+ *     { id: '2', source_type: 'news_article', title: 'FMCSA Guidelines 2024' }
+ *   ]}
+ *   showSourcesList={true}
+ * >
+ *   <p>Kentucky law requires CDL holders to report violations within 30 days [1].
+ *   Federal guidelines add additional requirements [2].</p>
+ * </AEOCitedContent>
+ * ```
+ */
+declare function AEOCitedContent({ children, sources, showSourcesList, className, }: {
+    children: React.ReactNode;
+    sources: Array<{
+        id: string;
+        source_type: 'press_release' | 'news_article' | 'legal_statute' | 'research_paper' | 'official_document' | 'internal' | 'citation';
+        title: string;
+        url?: string;
+        publisher?: string;
+        published_at?: string;
+        accessed_at?: string;
+        excerpt?: string;
+        confidence?: number;
+        identifier?: string;
+    }>;
+    showSourcesList?: boolean;
+    className?: string;
+}): React.ReactElement;
+
+/**
+ * @sonordev/site-kit/llms - API Functions
+ *
+ * Data fetching for LLM visibility content.
+ * Pulls from Signal knowledge base and project data.
+ */
+
+/**
+ * Fetch all LLM visibility data for a project - cached per request
+ * This is the main data source for llms.txt generation
+ *
+ * @param projectId - Optional project ID (API key identifies project if omitted)
+ */
+declare const getLLMsData: (projectId?: string) => Promise<LLMsDataResponse | null>;
+/**
+ * Fetch business info only - cached per request
+ */
+declare const getBusinessInfo: (projectId?: string) => Promise<LLMBusinessInfo | null>;
+/**
+ * Fetch services list - cached per request
+ */
+declare const getServices: (projectId?: string) => Promise<LLMService[]>;
+/**
+ * Fetch FAQ items - cached per request
+ */
+declare const getFAQItems: (projectId?: string, limit?: number) => Promise<LLMFAQItem[]>;
+/**
+ * Fetch page summaries for sitemap - cached per request
+ */
+declare const getPageSummaries: (projectId?: string, limit?: number) => Promise<LLMPageSummary[]>;
+/**
+ * Fetch AI-optimized llms.txt markdown from Portal API (build-time)
+ * Used by writeLLMsTxtToPublic for static file generation
+ */
+declare function getOptimizedLLMsTxt(options?: {
+    full?: boolean;
+    apiUrl?: string;
+    apiKey?: string;
+}): Promise<string | null>;
+
+/**
+ * @sonordev/site-kit/llms - Build-Time Write
+ *
+ * Fetches AI-optimized llms.txt from Portal API and writes to public/llms.txt
+ * at build time. Integrates with sitemap flow when optimizedLLMsTxt is enabled.
+ */
+
+interface WriteLLMsTxtOptions {
+    /** Output directory (default: public, relative to cwd) */
+    outputDir?: string;
+    /** Write llms-full.txt as well */
+    full?: boolean;
+    /** Portal API URL */
+    apiUrl?: string;
+    /** Portal API key */
+    apiKey?: string;
+    /** Fallback to non-optimized when API fails */
+    fallbackToLocal?: boolean;
+    /** When Portal returns empty services/faq/pages, use this to supply local site data */
+    getLocalData?: () => Promise<LLMsDataResponse | null>;
+}
+/**
+ * Fetch optimized llms.txt from Portal and write to public/llms.txt
+ * Called at build time after sitemap sync (when optimizedLLMsTxt is enabled)
+ */
+declare function writeLLMsTxtToPublic(options?: WriteLLMsTxtOptions): Promise<{
+    success: boolean;
+    path: string;
+    optimized: boolean;
+}>;
+
+export { AEOBlock, AEOBlockProps, AEOCitedContent, AEOClaim, AEOClaimProps, AEOComparison, AEODefinition, AEODefinitionProps, AEOEntity, AEOProvenanceList, AEOStep, AEOSteps, AEOSummary, AEOSummaryProps, DEFAULT_SPEAKABLE_SELECTORS, GenerateLLMSTxtOptions, LLMBusinessInfo, LLMFAQItem, LLMPageSummary, LLMSTxtContent, LLMService, LLMsDataResponse, SpeakableConfig, SpeakableSchema, SpeakableSchemaProps, type WriteLLMsTxtOptions, createLLMsFullTxtHandler, createLLMsTxtHandler, createSpeakableSchema, generateLLMsFullTxt, generateLLMsTxt, getBusinessInfo, getFAQItems, getLLMsData, getOptimizedLLMsTxt, getPageSummaries, getServices, getSpeakableSelectorsForPage, writeLLMsTxtToPublic };