@sonordev/site-kit 2.8.2 → 3.0.0

package/dist/server-l6LMNvF1.d.ts

@@ -0,0 +1,360 @@
+import { G as GetManagedMetadataOptions, M as ManagedMetadataResult, l as GetABVariantOptions, k as ABTestResult, n as GetRedirectOptions, R as RedirectResult, q as GetRobotsOptions, p as RobotsDirective, s as GetSitemapEntriesOptions, r as SitemapEntry } from './types-DPsbBKiu.js';
+
+/**
+ * @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.
+ */
+
+/** Response shape for POST /api/public/seo/page-context */
+type PageSeoContext = {
+    page: any | null;
+    schemas: any[];
+    project: {
+        id: string;
+        title?: string | null;
+        domain?: string | null;
+        logo_url?: string | null;
+        site_url?: string | null;
+    } | null;
+};
+/**
+ * Fetch SEO page data - cached per request
+ * @server-only
+ */
+declare const getSEOPageData: (path: string) => Promise<{
+    page: any;
+    project: {
+        id: string;
+        title?: string | null;
+        domain?: string | null;
+        logo_url?: string | null;
+        site_url?: string | null;
+    } | null;
+}>;
+/**
+ * Fetch schema markups for a page - cached per request (shares loadPageSeoContext with getSEOPageData)
+ * @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';
+}>, options?: {
+    /**
+     * Sync mode:
+     * - 'full-replace': replaces the entire page set (default for build-time sync)
+     * - 'additive': adds/updates pages but never deletes existing ones
+     */
+    mode?: 'additive' | 'full-replace';
+}): 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({
+ *     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({
+ *   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>;
+
+/**
+ * Get redirect for a path if one exists
+ *
+ * Use in Next.js middleware to handle managed redirects
+ *
+ * @example
+ * ```tsx
+ * // middleware.ts
+ * import { getRedirect } from '@sonordev/seo'
+ *
+ * export async function middleware(request) {
+ *   const redirect = await getRedirect({
+ *     projectId: process.env.SONOR_PROJECT_ID!,
+ *     path: request.nextUrl.pathname
+ *   })
+ *
+ *   if (redirect) {
+ *     return NextResponse.redirect(redirect.destination, redirect.statusCode)
+ *   }
+ * }
+ * ```
+ */
+declare function getRedirect(options: GetRedirectOptions): Promise<RedirectResult | null>;
+/**
+ * Get robots directive for a page
+ *
+ * @example
+ * ```tsx
+ * const robots = await getRobotsDirective({
+ *   projectId: process.env.SONOR_PROJECT_ID!,
+ *   path: '/private-page'
+ * })
+ *
+ * if (!robots.index) {
+ *   // Page should not be indexed
+ * }
+ * ```
+ */
+declare function getRobotsDirective(options: GetRobotsOptions): Promise<RobotsDirective>;
+/**
+ * Get sitemap entries for a project
+ *
+ * Use in sitemap.ts to generate dynamic sitemap
+ *
+ * @example
+ * ```tsx
+ * // app/sitemap.ts
+ * import { generateSitemap } from '@sonordev/seo'
+ *
+ * export default async function sitemap() {
+ *   return generateSitemap({
+ *     projectId: process.env.SONOR_PROJECT_ID!,
+ *     baseUrl: 'https://example.com',
+ *     publishedOnly: true
+ *   })
+ * }
+ * ```
+ */
+declare function generateSitemap(options: GetSitemapEntriesOptions): Promise<SitemapEntry[]>;
+/**
+ * Register local sitemap entries with Sonor
+ *
+ * Call this at build time to sync your local routes to seo_pages.
+ * This ensures analytics only tracks real pages.
+ *
+ * After registration, Signal AI will generate optimized meta titles
+ * and descriptions for pages that don't have managed meta yet.
+ *
+ * @example
+ * ```ts
+ * // scripts/register-sitemap.ts
+ * import { registerLocalSitemap } from '@sonordev/seo'
+ *
+ * // Option 1: Provide entries directly
+ * await registerLocalSitemap({
+ *   entries: [
+ *     { path: '/', title: 'Home', priority: 1.0 },
+ *     { path: '/about', title: 'About Us', priority: 0.8 },
+ *   ]
+ * })
+ *
+ * // Option 2: Auto-discover from Next.js app directory
+ * await registerLocalSitemap({ autoDiscover: true })
+ *
+ * // Option 3: Skip Signal AI meta optimization
+ * await registerLocalSitemap({ autoDiscover: true, optimize_meta: false })
+ * ```
+ */
+declare function registerLocalSitemap(options: {
+    entries?: Array<{
+        path: string;
+        title?: string;
+        priority?: number;
+        changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    }>;
+    autoDiscover?: boolean;
+    /** Trigger Signal AI to generate optimized meta titles/descriptions (default: true) */
+    optimize_meta?: boolean;
+    /**
+     * Sync mode. Defaults to 'additive' for explicit entries (a partial list must
+     * never delete the rest of the site's pages) and 'full-replace' for
+     * autoDiscover (which enumerates the complete route set).
+     */
+    mode?: 'additive' | 'full-replace';
+}): Promise<{
+    success: boolean;
+    created: number;
+    updated: number;
+    removed?: number;
+    meta_optimization?: {
+        triggered: boolean;
+        pages_queued: number;
+    } | null;
+}>;
+/**
+ * Check if a path should be indexed
+ *
+ * Quick helper to check indexability without full directive parsing
+ */
+declare function isIndexable(projectId: string, path: string): Promise<boolean>;
+
+export { type EntityType as E, type PageSeoContext as P, type SEOEntity as S, getManagedMetadataWithAB as a, getABVariant as b, getRedirect as c, getRobotsDirective as d, generateSitemap as e, getSEOPageData as f, getManagedMetadata as g, getSchemaMarkups as h, isIndexable as i, getFAQData as j, getInternalLinks as k, getContentBlock as l, getABTest as m, getRedirectData as n, getManagedScripts as o, getRobotsData as p, getSitemapEntries as q, recordABImpression as r, registerSitemap as s, getEntities as t, getPrimaryEntity as u, getEntityEnhancedSchema as v, getVisibilityScore as w, getVisibilitySummary as x, registerLocalSitemap as y };

package/dist/server-mX5At_6x.d.mts

@@ -0,0 +1,360 @@
+import { G as GetManagedMetadataOptions, M as ManagedMetadataResult, l as GetABVariantOptions, k as ABTestResult, n as GetRedirectOptions, R as RedirectResult, q as GetRobotsOptions, p as RobotsDirective, s as GetSitemapEntriesOptions, r as SitemapEntry } from './types-DPsbBKiu.mjs';
+
+/**
+ * @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.
+ */
+
+/** Response shape for POST /api/public/seo/page-context */
+type PageSeoContext = {
+    page: any | null;
+    schemas: any[];
+    project: {
+        id: string;
+        title?: string | null;
+        domain?: string | null;
+        logo_url?: string | null;
+        site_url?: string | null;
+    } | null;
+};
+/**
+ * Fetch SEO page data - cached per request
+ * @server-only
+ */
+declare const getSEOPageData: (path: string) => Promise<{
+    page: any;
+    project: {
+        id: string;
+        title?: string | null;
+        domain?: string | null;
+        logo_url?: string | null;
+        site_url?: string | null;
+    } | null;
+}>;
+/**
+ * Fetch schema markups for a page - cached per request (shares loadPageSeoContext with getSEOPageData)
+ * @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';
+}>, options?: {
+    /**
+     * Sync mode:
+     * - 'full-replace': replaces the entire page set (default for build-time sync)
+     * - 'additive': adds/updates pages but never deletes existing ones
+     */
+    mode?: 'additive' | 'full-replace';
+}): 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({
+ *     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({
+ *   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>;
+
+/**
+ * Get redirect for a path if one exists
+ *
+ * Use in Next.js middleware to handle managed redirects
+ *
+ * @example
+ * ```tsx
+ * // middleware.ts
+ * import { getRedirect } from '@sonordev/seo'
+ *
+ * export async function middleware(request) {
+ *   const redirect = await getRedirect({
+ *     projectId: process.env.SONOR_PROJECT_ID!,
+ *     path: request.nextUrl.pathname
+ *   })
+ *
+ *   if (redirect) {
+ *     return NextResponse.redirect(redirect.destination, redirect.statusCode)
+ *   }
+ * }
+ * ```
+ */
+declare function getRedirect(options: GetRedirectOptions): Promise<RedirectResult | null>;
+/**
+ * Get robots directive for a page
+ *
+ * @example
+ * ```tsx
+ * const robots = await getRobotsDirective({
+ *   projectId: process.env.SONOR_PROJECT_ID!,
+ *   path: '/private-page'
+ * })
+ *
+ * if (!robots.index) {
+ *   // Page should not be indexed
+ * }
+ * ```
+ */
+declare function getRobotsDirective(options: GetRobotsOptions): Promise<RobotsDirective>;
+/**
+ * Get sitemap entries for a project
+ *
+ * Use in sitemap.ts to generate dynamic sitemap
+ *
+ * @example
+ * ```tsx
+ * // app/sitemap.ts
+ * import { generateSitemap } from '@sonordev/seo'
+ *
+ * export default async function sitemap() {
+ *   return generateSitemap({
+ *     projectId: process.env.SONOR_PROJECT_ID!,
+ *     baseUrl: 'https://example.com',
+ *     publishedOnly: true
+ *   })
+ * }
+ * ```
+ */
+declare function generateSitemap(options: GetSitemapEntriesOptions): Promise<SitemapEntry[]>;
+/**
+ * Register local sitemap entries with Sonor
+ *
+ * Call this at build time to sync your local routes to seo_pages.
+ * This ensures analytics only tracks real pages.
+ *
+ * After registration, Signal AI will generate optimized meta titles
+ * and descriptions for pages that don't have managed meta yet.
+ *
+ * @example
+ * ```ts
+ * // scripts/register-sitemap.ts
+ * import { registerLocalSitemap } from '@sonordev/seo'
+ *
+ * // Option 1: Provide entries directly
+ * await registerLocalSitemap({
+ *   entries: [
+ *     { path: '/', title: 'Home', priority: 1.0 },
+ *     { path: '/about', title: 'About Us', priority: 0.8 },
+ *   ]
+ * })
+ *
+ * // Option 2: Auto-discover from Next.js app directory
+ * await registerLocalSitemap({ autoDiscover: true })
+ *
+ * // Option 3: Skip Signal AI meta optimization
+ * await registerLocalSitemap({ autoDiscover: true, optimize_meta: false })
+ * ```
+ */
+declare function registerLocalSitemap(options: {
+    entries?: Array<{
+        path: string;
+        title?: string;
+        priority?: number;
+        changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    }>;
+    autoDiscover?: boolean;
+    /** Trigger Signal AI to generate optimized meta titles/descriptions (default: true) */
+    optimize_meta?: boolean;
+    /**
+     * Sync mode. Defaults to 'additive' for explicit entries (a partial list must
+     * never delete the rest of the site's pages) and 'full-replace' for
+     * autoDiscover (which enumerates the complete route set).
+     */
+    mode?: 'additive' | 'full-replace';
+}): Promise<{
+    success: boolean;
+    created: number;
+    updated: number;
+    removed?: number;
+    meta_optimization?: {
+        triggered: boolean;
+        pages_queued: number;
+    } | null;
+}>;
+/**
+ * Check if a path should be indexed
+ *
+ * Quick helper to check indexability without full directive parsing
+ */
+declare function isIndexable(projectId: string, path: string): Promise<boolean>;
+
+export { type EntityType as E, type PageSeoContext as P, type SEOEntity as S, getManagedMetadataWithAB as a, getABVariant as b, getRedirect as c, getRobotsDirective as d, generateSitemap as e, getSEOPageData as f, getManagedMetadata as g, getSchemaMarkups as h, isIndexable as i, getFAQData as j, getInternalLinks as k, getContentBlock as l, getABTest as m, getRedirectData as n, getManagedScripts as o, getRobotsData as p, getSitemapEntries as q, recordABImpression as r, registerSitemap as s, getEntities as t, getPrimaryEntity as u, getEntityEnhancedSchema as v, getVisibilityScore as w, getVisibilitySummary as x, registerLocalSitemap as y };