@seoengine.ai/next-llm-ready 1.0.0

package/dist/api/index.d.ts

@@ -0,0 +1,295 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * next-llm-ready - TypeScript Type Definitions
+ * Make your Next.js content AI-ready
+ */
+/**
+ * Content metadata for LLM-ready output
+ */
+interface LLMContent {
+    /** Page/post title */
+    title: string;
+    /** Main content (HTML or Markdown) */
+    content: string;
+    /** Short description/excerpt */
+    excerpt?: string;
+    /** Canonical URL */
+    url: string;
+    /** Publication date (ISO 8601) */
+    date?: string;
+    /** Last modified date (ISO 8601) */
+    modifiedDate?: string;
+    /** Author name */
+    author?: string;
+    /** Categories/sections */
+    categories?: string[];
+    /** Tags/keywords */
+    tags?: string[];
+    /** Custom prompt prefix for AI context */
+    promptPrefix?: string;
+    /** Featured image URL */
+    image?: string;
+    /** Reading time in minutes */
+    readingTime?: number;
+}
+/**
+ * Copy action types for analytics
+ */
+type CopyAction = 'copy' | 'view' | 'download';
+/**
+ * Analytics event
+ */
+interface AnalyticsEvent {
+    /** Event type */
+    action: CopyAction;
+    /** Page/content identifier */
+    contentId?: string;
+    /** Page URL */
+    url?: string;
+    /** Timestamp */
+    timestamp?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Custom analytics storage adapter
+ */
+interface AnalyticsStorageAdapter {
+    /** Save event */
+    save: (event: AnalyticsEvent) => Promise<void>;
+    /** Get all events */
+    getAll: () => Promise<AnalyticsEvent[]>;
+    /** Clear events */
+    clear: () => Promise<void>;
+}
+/**
+ * Single item in LLMs.txt listing
+ */
+interface LLMsTxtItem {
+    /** Content title */
+    title: string;
+    /** Page URL */
+    url: string;
+    /** Content type (post, page, etc.) */
+    type?: string;
+    /** Publication date */
+    date?: string;
+    /** Short description */
+    description?: string;
+}
+/**
+ * Markdown API handler options
+ */
+interface MarkdownHandlerOptions {
+    /** Function to fetch content by slug/id */
+    getContent: (slug: string) => Promise<LLMContent | null>;
+    /** Cache control header value */
+    cacheControl?: string;
+    /** Enable CORS */
+    cors?: boolean;
+}
+/**
+ * Analytics API handler options
+ */
+interface AnalyticsHandlerOptions {
+    /** Storage adapter */
+    storage: AnalyticsStorageAdapter;
+    /** Rate limiting (requests per minute) */
+    rateLimit?: number;
+    /** Enable CORS */
+    cors?: boolean;
+}
+
+/**
+ * LLMs.txt API Route Handler
+ * Creates an API route handler for serving /llms.txt
+ */
+
+interface LLMsTxtHandlerOptions {
+    /** Function to get site configuration */
+    getSiteConfig: () => Promise<{
+        siteName: string;
+        siteDescription?: string;
+        siteUrl: string;
+    }>;
+    /** Function to get all content items */
+    getContent: () => Promise<LLMsTxtItem[]>;
+    /** Cache control header (default: 1 hour) */
+    cacheControl?: string;
+    /** Custom header text */
+    headerText?: string;
+    /** Custom footer text */
+    footerText?: string;
+}
+/**
+ * Create an API route handler for /llms.txt
+ *
+ * @example
+ * ```ts
+ * // app/llms.txt/route.ts
+ * import { createLLMsTxtHandler } from 'next-llm-ready/api';
+ *
+ * export const GET = createLLMsTxtHandler({
+ *   getSiteConfig: async () => ({
+ *     siteName: 'My Site',
+ *     siteDescription: 'A great website',
+ *     siteUrl: 'https://example.com',
+ *   }),
+ *   getContent: async () => {
+ *     const posts = await getAllPosts();
+ *     return posts.map(post => ({
+ *       title: post.title,
+ *       url: `https://example.com/blog/${post.slug}`,
+ *       type: 'post',
+ *       date: post.date,
+ *     }));
+ *   },
+ * });
+ * ```
+ */
+declare function createLLMsTxtHandler(options: LLMsTxtHandlerOptions): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Create a Pages Router API handler for /api/llms.txt
+ *
+ * @example
+ * ```ts
+ * // pages/api/llms.txt.ts
+ * import { createLLMsTxtPageHandler } from 'next-llm-ready/api';
+ *
+ * export default createLLMsTxtPageHandler({
+ *   getSiteConfig: async () => ({ ... }),
+ *   getContent: async () => { ... },
+ * });
+ * ```
+ */
+declare function createLLMsTxtPageHandler(options: LLMsTxtHandlerOptions): (req: {
+    method?: string;
+}, res: {
+    status: (code: number) => {
+        end: (body?: string) => void;
+        json: (body: unknown) => void;
+    };
+    setHeader: (name: string, value: string) => void;
+}) => Promise<void>;
+
+/**
+ * Markdown API Route Handler
+ * Serves markdown content for ?llm=1 requests
+ */
+
+/**
+ * Create middleware to handle ?llm=1 query parameter
+ *
+ * @example
+ * ```ts
+ * // middleware.ts
+ * import { withLLMParam } from 'next-llm-ready/api';
+ *
+ * export default withLLMParam({
+ *   getContent: async (pathname) => {
+ *     // Extract slug and fetch content
+ *     const slug = pathname.split('/').pop();
+ *     const post = await getPostBySlug(slug);
+ *     if (!post) return null;
+ *     return {
+ *       title: post.title,
+ *       content: post.content,
+ *       url: `https://example.com${pathname}`,
+ *       date: post.date,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+declare function withLLMParam(options: MarkdownHandlerOptions): (request: NextRequest) => Promise<NextResponse | undefined>;
+/**
+ * Create an API route handler for markdown endpoints
+ *
+ * @example
+ * ```ts
+ * // app/api/content/[slug]/route.ts
+ * import { createMarkdownHandler } from 'next-llm-ready/api';
+ *
+ * export const GET = createMarkdownHandler({
+ *   getContent: async (slug) => {
+ *     const post = await getPostBySlug(slug);
+ *     if (!post) return null;
+ *     return {
+ *       title: post.title,
+ *       content: post.content,
+ *       url: `https://example.com/blog/${slug}`,
+ *     };
+ *   },
+ * });
+ * ```
+ */
+declare function createMarkdownHandler(options: Omit<MarkdownHandlerOptions, 'getContent'> & {
+    getContent: (slug: string) => Promise<LLMContent | null>;
+}): (request: NextRequest, { params }: {
+    params: {
+        slug?: string;
+    };
+}) => Promise<NextResponse>;
+/**
+ * Helper to check if request has ?llm=1 parameter
+ */
+declare function hasLLMParam(request: NextRequest): boolean;
+
+/**
+ * Analytics API Route Handler
+ * Tracks copy/view/download events
+ */
+
+/**
+ * In-memory analytics storage (for development/testing)
+ */
+declare function createInMemoryStorage(): AnalyticsStorageAdapter;
+/**
+ * Create an API route handler for analytics tracking
+ *
+ * @example
+ * ```ts
+ * // app/api/analytics/route.ts
+ * import { createAnalyticsHandler, createInMemoryStorage } from 'next-llm-ready/api';
+ *
+ * const storage = createInMemoryStorage();
+ *
+ * export const POST = createAnalyticsHandler({
+ *   storage,
+ *   rateLimit: 100,
+ * });
+ *
+ * export const GET = async () => {
+ *   const events = await storage.getAll();
+ *   return NextResponse.json({ events });
+ * };
+ * ```
+ */
+declare function createAnalyticsHandler(options: AnalyticsHandlerOptions): (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Create a Pages Router API handler for analytics
+ */
+declare function createAnalyticsPageHandler(options: AnalyticsHandlerOptions): (req: {
+    method?: string;
+    body?: unknown;
+    headers?: {
+        [key: string]: string | string[] | undefined;
+    };
+}, res: {
+    status: (code: number) => {
+        end: (body?: string) => void;
+        json: (body: unknown) => void;
+    };
+    setHeader: (name: string, value: string) => void;
+}) => Promise<void>;
+/**
+ * Aggregate analytics events by action type
+ */
+declare function aggregateEvents(storage: AnalyticsStorageAdapter): Promise<Record<string, number>>;
+/**
+ * Get events for a specific content ID
+ */
+declare function getEventsForContent(storage: AnalyticsStorageAdapter, contentId: string): Promise<AnalyticsEvent[]>;
+
+export { type AnalyticsEvent, type AnalyticsHandlerOptions, type AnalyticsStorageAdapter, type LLMsTxtHandlerOptions, type MarkdownHandlerOptions, aggregateEvents, createAnalyticsHandler, createAnalyticsPageHandler, createInMemoryStorage, createLLMsTxtHandler, createLLMsTxtPageHandler, createMarkdownHandler, getEventsForContent, hasLLMParam, withLLMParam };