@uptrademedia/site-kit 1.0.37 → 1.0.40

package/dist/api-BoW4FSlW.d.mts

@@ -0,0 +1,671 @@
+import * as React$1 from 'react';
+
+/**
+ * @uptrade/site-kit/llms - Types
+ *
+ * LLM Visibility Types for Answer Engine Optimization (AEO)
+ */
+interface LLMBusinessInfo {
+    /** Business/organization name */
+    name: string;
+    /** One-line tagline or mission */
+    tagline?: string;
+    /** Longer description (1-3 paragraphs) */
+    description: string;
+    /** Industry/category */
+    industry?: string;
+    /** Primary service area (city, region, or "nationwide") */
+    service_area?: string;
+    /** Year established */
+    founded?: string;
+    /** Website URL */
+    website: string;
+}
+interface LLMContactInfo {
+    /** Primary phone */
+    phone?: string;
+    /** Primary email */
+    email?: string;
+    /** Street address */
+    address?: string;
+    /** City */
+    city?: string;
+    /** State/province */
+    state?: string;
+    /** ZIP/postal code */
+    postal_code?: string;
+    /** Country */
+    country?: string;
+    /** Business hours (e.g., "Mon-Fri 9am-5pm EST") */
+    hours?: string;
+}
+interface LLMService {
+    /** Service name */
+    name: string;
+    /** Brief description */
+    description: string;
+    /** URL path to service page */
+    url?: string;
+}
+interface LLMFAQItem {
+    /** Question */
+    question: string;
+    /** Answer */
+    answer: string;
+}
+interface LLMPageSummary {
+    /** Page path */
+    path: string;
+    /** Page title */
+    title: string;
+    /** Brief description of page content */
+    description?: string;
+}
+interface GenerateLLMSTxtOptions {
+    /** Project ID for fetching data (optional - uses API key's project) */
+    projectId?: string;
+    /** Include business info section */
+    includeBusinessInfo?: boolean;
+    /** Include services list */
+    includeServices?: boolean;
+    /** Include FAQ section */
+    includeFAQ?: boolean;
+    /** Include page index */
+    includePages?: boolean;
+    /** Include contact info */
+    includeContact?: boolean;
+    /** Maximum number of FAQ items */
+    maxFAQItems?: number;
+    /** Maximum number of pages to list */
+    maxPages?: number;
+    /** Custom sections to append */
+    customSections?: Array<{
+        title: string;
+        content: string;
+    }>;
+}
+interface LLMSTxtContent {
+    /** Raw markdown content */
+    markdown: string;
+    /** Metadata about generation */
+    metadata: {
+        generated_at: string;
+        project_id: string;
+        sections: string[];
+    };
+}
+interface SpeakableConfig {
+    /** CSS selectors for speakable content */
+    cssSelectors?: string[];
+    /** XPath selectors for speakable content */
+    xPaths?: string[];
+}
+interface SpeakableSchemaProps {
+    /** Page type - Article or WebPage */
+    type: 'Article' | 'WebPage';
+    /** Page name/title */
+    name: string;
+    /** Page URL */
+    url: string;
+    /** Speakable content selectors */
+    speakable: SpeakableConfig;
+    /** Additional schema properties */
+    additionalProperties?: Record<string, unknown>;
+}
+interface AEOBlockProps {
+    /** Block ID for speakable reference */
+    id?: string;
+    /** Type of content block */
+    type: 'summary' | 'definition' | 'answer' | 'list' | 'steps' | 'comparison';
+    /** Optional question (for Q&A format) */
+    question?: string;
+    /** Whether to mark as speakable */
+    speakable?: boolean;
+    /** Entity ID for knowledge graph linking */
+    entityId?: string;
+    /** Children content */
+    children: React.ReactNode;
+    /** Optional CSS class */
+    className?: string;
+}
+interface AEOSummaryProps {
+    /** Title for the summary */
+    title?: string;
+    /** Key points to highlight */
+    points: string[];
+    /** Whether to mark as speakable */
+    speakable?: boolean;
+    /** Entity ID for knowledge graph linking */
+    entityId?: string;
+    /** Optional CSS class */
+    className?: string;
+}
+interface AEODefinitionProps {
+    /** Term being defined */
+    term: string;
+    /** Definition */
+    definition: string;
+    /** Whether to mark as speakable */
+    speakable?: boolean;
+    /** Entity ID for knowledge graph linking */
+    entityId?: string;
+    /** Source for the definition (e.g., statute code) */
+    source?: string;
+    /** Optional CSS class */
+    className?: string;
+}
+/**
+ * AEOClaimProps - AI-Verifiable Claim with Provenance
+ *
+ * For wrapping factual claims with machine-readable source attribution.
+ * LLMs heavily favor content with verifiable sources and confidence scores.
+ */
+interface AEOClaimProps {
+    /** Source reference (e.g., "KRS 281A.170", "NIH Study 2024") */
+    source: string;
+    /** URL to source document */
+    sourceUrl?: string;
+    /** Confidence score 0-1 */
+    confidence?: number;
+    /** Type of claim */
+    claimType?: 'fact' | 'statute' | 'study' | 'quote' | 'statistic';
+    /** When the source was retrieved */
+    retrievedAt?: string;
+    /** Children content */
+    children: React.ReactNode;
+    /** Optional CSS class */
+    className?: string;
+}
+/**
+ * AEOEntityProps - Inline Entity Annotation
+ *
+ * For annotating entity mentions with knowledge graph IDs.
+ */
+interface AEOEntityProps {
+    /** Entity ID from knowledge graph */
+    entityId: string;
+    /** Entity type */
+    entityType: 'organization' | 'person' | 'service' | 'product' | 'location' | 'concept' | 'credential';
+    /** Canonical entity name */
+    name: string;
+    /** Entity URL */
+    url?: string;
+    /** Children content */
+    children: React.ReactNode;
+    /** Optional CSS class */
+    className?: string;
+}
+/**
+ * ContentProvenance - Source attribution for content
+ *
+ * Links content to authoritative sources for AI verification.
+ */
+interface ContentProvenance {
+    /** Unique provenance ID */
+    id: string;
+    /** Type of source */
+    source_type: 'press_release' | 'news_article' | 'legal_statute' | 'research_paper' | 'official_document' | 'internal' | 'citation';
+    /** Source title */
+    title: string;
+    /** Source URL */
+    url?: string;
+    /** Publisher/organization name */
+    publisher?: string;
+    /** Publication date */
+    published_at?: string;
+    /** Date accessed */
+    accessed_at?: string;
+    /** Brief excerpt or summary */
+    excerpt?: string;
+    /** Confidence score 0-1 */
+    confidence?: number;
+    /** DOI or other identifier */
+    identifier?: string;
+}
+/**
+ * AEOProvenanceListProps - Display provenance sources
+ */
+interface AEOProvenanceListProps {
+    /** List of provenance sources */
+    sources: ContentProvenance[];
+    /** Title for the section */
+    title?: string;
+    /** Optional CSS class */
+    className?: string;
+}
+/**
+ * AEOCitedContentProps - Content with inline citations
+ *
+ * Wraps content that has numbered citations referencing provenance sources.
+ */
+interface AEOCitedContentProps {
+    /** Content with [1], [2] style inline citations */
+    children: React.ReactNode;
+    /** Provenance sources (index matches citation number) */
+    sources: ContentProvenance[];
+    /** Whether to show sources list at bottom */
+    showSourcesList?: boolean;
+    /** Optional CSS class */
+    className?: string;
+}
+interface LLMsDataResponse {
+    business: LLMBusinessInfo;
+    contact?: LLMContactInfo;
+    services: LLMService[];
+    faq: LLMFAQItem[];
+    pages: LLMPageSummary[];
+}
+
+/**
+ * @uptrade/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 '@uptrade/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>;
+
+/**
+ * @uptrade/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 (for build-time optimized output) */
+    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 '@uptrade/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 '@uptrade/site-kit/llms'
+ *
+ * export const GET = createLLMsFullTxtHandler()
+ * ```
+ */
+declare function createLLMsFullTxtHandler(options?: LLMsTxtHandlerOptions): () => Promise<Response>;
+
+/**
+ * @uptrade/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$1.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[];
+
+/**
+ * @uptrade/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$1.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$1.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$1.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$1.ReactNode;
+    speakable?: boolean;
+    entityId?: string;
+    className?: string;
+}): React$1.ReactElement;
+/**
+ * AEOStep - Individual step within AEOSteps
+ */
+declare function AEOStep({ number, name, children, }: {
+    number: number;
+    name: string;
+    children: React$1.ReactNode;
+}): React$1.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$1.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$1.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$1.ReactNode;
+    className?: string;
+}): React$1.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$1.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$1.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$1.ReactElement;
+
+/**
+ * @uptrade/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>;
+
+export { AEOBlock as A, createSpeakableSchema as B, type ContentProvenance as C, DEFAULT_SPEAKABLE_SELECTORS as D, generateLLMsFullTxt as E, generateLLMsTxt as F, type GenerateLLMSTxtOptions as G, getBusinessInfo as H, getFAQItems as I, getLLMsData as J, getOptimizedLLMsTxt as K, type LLMBusinessInfo as L, getPageSummaries as M, getServices as N, getSpeakableSelectorsForPage as O, type SpeakableConfig as S, type AEOBlockProps as a, AEOCitedContent as b, type AEOCitedContentProps as c, AEOClaim as d, type AEOClaimProps as e, AEOComparison as f, AEODefinition as g, type AEODefinitionProps as h, AEOEntity as i, type AEOEntityProps as j, AEOProvenanceList as k, type AEOProvenanceListProps as l, AEOStep as m, AEOSteps as n, AEOSummary as o, type AEOSummaryProps as p, type LLMContactInfo as q, type LLMFAQItem as r, type LLMPageSummary as s, type LLMSTxtContent as t, type LLMService as u, type LLMsDataResponse as v, SpeakableSchema as w, type SpeakableSchemaProps as x, createLLMsFullTxtHandler as y, createLLMsTxtHandler as z };