geo-ai-core 0.1.0

package/README.md

@@ -0,0 +1,136 @@
+# geo-ai-core
+
+[![npm](https://img.shields.io/npm/v/geo-ai-core)](https://npmjs.com/package/geo-ai-core)
+
+Part of the [GEO AI ecosystem](https://github.com/madeburo/GEO-AI)
+
+Zero-dependency TypeScript engine for Generative Engine Optimization (GEO). Optimizes websites for AI search engines — ChatGPT, Claude, Gemini, Perplexity, DeepSeek, Grok and more.
+
+Works with any Node.js framework or plain server.
+
+## Installation
+
+```bash
+npm install geo-ai-core
+```
+
+## Quick Start
+
+```typescript
+import { createGeoAI } from 'geo-ai-core';
+
+const geo = createGeoAI({
+  siteName: 'My Site',
+  siteUrl: 'https://example.com',
+  provider: {
+    Products: [
+      { title: 'Widget', url: '/products/widget', description: 'A great widget' },
+    ],
+    Blog: [
+      { title: 'Hello World', url: '/blog/hello', description: 'First post' },
+    ],
+  },
+});
+
+// llms.txt / llms-full.txt
+const llmsTxt = await geo.generateLlms(false);
+const llmsFullTxt = await geo.generateLlms(true);
+
+// robots.txt block
+const robotsTxt = geo.generateRobotsTxt();
+
+// SEO signals
+const metaTags = geo.generateMetaTags();
+const linkHeader = geo.generateLinkHeader();
+const jsonLd = geo.generateJsonLd();
+```
+
+## ContentProvider
+
+For dynamic data sources, implement the `ContentProvider` interface:
+
+```typescript
+import { createGeoAI, type ContentProvider } from 'geo-ai-core';
+
+class MyProvider implements ContentProvider {
+  async getSections(options?: { locale?: string }) {
+    return [
+      { name: 'Products', type: 'product', resources: await fetchProducts() },
+      { name: 'Blog', type: 'page', resources: await fetchPosts() },
+    ];
+  }
+}
+
+const geo = createGeoAI({
+  siteName: 'My Site',
+  siteUrl: 'https://example.com',
+  provider: new MyProvider(),
+});
+```
+
+## AI Description Generation
+
+Separate entry point — only loaded when imported:
+
+```typescript
+import { AiGenerator } from 'geo-ai-core/ai';
+
+const ai = new AiGenerator({
+  provider: 'anthropic',
+  apiKey: 'sk-...',
+  model: 'claude-sonnet-4-20250514',
+});
+
+const description = await ai.generate({
+  title: 'Premium Widget',
+  content: 'A high-quality widget...',
+  type: 'product',
+  price: '$29.99',
+});
+```
+
+Bulk generation with progress:
+
+```typescript
+const results = await ai.bulkGenerate(items, {
+  batchSize: 5,
+  maxItems: 50,
+  onProgress: ({ completed, total }) => console.log(`${completed}/${total}`),
+});
+```
+
+## Configuration
+
+```typescript
+interface GeoAIConfig {
+  siteName: string;
+  siteUrl: string;
+  provider: ContentProvider | Record<string, Resource[]>;
+
+  siteDescription?: string;
+  crawlers?: Record<string, 'allow' | 'disallow'> | 'all';
+  cache?: CacheAdapter | string;  // '1h', '24h', '7d' or custom adapter
+  crypto?: { encryptionKey: string };  // 64-char hex for AES-256-GCM
+  crawlTracking?: { store?: CrawlStore; secret?: string } | true;
+}
+```
+
+## Entry Points
+
+| Entry | Import | Contents |
+|-------|--------|----------|
+| Main | `geo-ai-core` | `createGeoAI`, `LlmsGenerator`, `BotRulesEngine`, `CrawlTracker`, `SeoGenerator`, `CryptoService`, cache adapters, types |
+| AI | `geo-ai-core/ai` | `AiGenerator`, `RateLimiter`, `buildPrompt`, `classifyAiError` |
+
+## Supported AI Crawlers
+
+GPTBot, OAI-SearchBot, ClaudeBot, claude-web, Google-Extended, PerplexityBot, DeepSeekBot, GrokBot, meta-externalagent, PanguBot, YandexBot, SputnikBot, Bytespider, Baiduspider, Amazonbot, Applebot
+
+## Requirements
+
+- Node.js >= 20
+- TypeScript >= 5.5 (recommended)
+
+## License
+
+[GPL v2](../../LICENSE)

package/dist/ai/index.cjs

@@ -0,0 +1,252 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/ai/index.ts
+var ai_exports = {};
+__export(ai_exports, {
+  AiGenerator: () => AiGenerator,
+  AiProviderError: () => AiProviderError,
+  RateLimiter: () => RateLimiter,
+  buildPrompt: () => buildPrompt,
+  classifyAiError: () => classifyAiError
+});
+module.exports = __toCommonJS(ai_exports);
+
+// src/constants.ts
+var DEFAULT_RATE_LIMIT = 10;
+var DEFAULT_BATCH_SIZE = 5;
+var DEFAULT_MAX_ITEMS = 50;
+var DEFAULT_MAX_DESCRIPTION_LENGTH = 200;
+var DEFAULT_PROMPT = `Write a concise AI-optimized description (max 200 characters) for the following {type}.
+
+Title: {title}
+Content: {content}
+Price: {price}
+Category: {category}
+
+The description should be informative, keyword-rich, and suitable for AI search engines. Focus on the key features and value proposition.`;
+
+// src/ai/index.ts
+var RATE_WINDOW_MS = 6e4;
+var RateLimiter = class {
+  state;
+  limit;
+  _now;
+  constructor(limit = DEFAULT_RATE_LIMIT, nowFn) {
+    this.limit = limit;
+    this._now = nowFn ?? (() => Date.now());
+    this.state = { count: 0, windowStart: this._now() };
+  }
+  /** Returns true if a request is allowed, false if rate-limited. */
+  tryAcquire() {
+    const now = this._now();
+    if (now - this.state.windowStart >= RATE_WINDOW_MS) {
+      this.state = { count: 0, windowStart: now };
+    }
+    if (this.state.count >= this.limit) {
+      return false;
+    }
+    this.state.count++;
+    return true;
+  }
+  /** Reset the limiter state. */
+  reset() {
+    this.state = { count: 0, windowStart: this._now() };
+  }
+};
+function buildPrompt(template, context) {
+  return template.replace(/\{title\}/g, () => context.title ?? "").replace(/\{content\}/g, () => context.content ?? "").replace(/\{type\}/g, () => context.type ?? "").replace(/\{price\}/g, () => context.price ?? "").replace(/\{category\}/g, () => context.category ?? "");
+}
+function classifyAiError(statusCode, body) {
+  if (statusCode === 401 || statusCode === 403) {
+    return {
+      type: "auth_error",
+      message: "Invalid API key. Please check your key in settings.",
+      statusCode
+    };
+  }
+  if (statusCode === 429) {
+    return {
+      type: "rate_limit",
+      message: "AI provider rate limit exceeded. Please wait and try again.",
+      statusCode
+    };
+  }
+  if (statusCode >= 500) {
+    return {
+      type: "server_error",
+      message: "AI service is temporarily unavailable. Please try later.",
+      statusCode
+    };
+  }
+  return {
+    type: "unknown",
+    message: body?.error?.message ?? "Unknown AI provider error.",
+    statusCode
+  };
+}
+var AiProviderError = class extends Error {
+  type;
+  statusCode;
+  constructor(error) {
+    super(error.message);
+    this.name = "AiProviderError";
+    this.type = error.type;
+    this.statusCode = error.statusCode;
+  }
+};
+var AiGenerator = class {
+  config;
+  rateLimiter;
+  _fetch;
+  constructor(config, fetchFn) {
+    this.config = config;
+    this.rateLimiter = new RateLimiter(config.rateLimit ?? DEFAULT_RATE_LIMIT);
+    this._fetch = fetchFn ?? globalThis.fetch.bind(globalThis);
+  }
+  defaultModel() {
+    return this.config.provider === "anthropic" ? "claude-sonnet-4-5-20250514" : "gpt-4o-mini";
+  }
+  /** Generate a single AI description. */
+  async generate(context) {
+    if (!this.rateLimiter.tryAcquire()) {
+      throw new AiProviderError({
+        type: "rate_limit",
+        message: "Internal rate limit exceeded. Please wait before generating more descriptions."
+      });
+    }
+    const template = this.config.promptTemplate ?? DEFAULT_PROMPT;
+    const prompt = buildPrompt(template, context);
+    const model = this.config.model ?? this.defaultModel();
+    const maxLen = this.config.maxDescriptionLength ?? DEFAULT_MAX_DESCRIPTION_LENGTH;
+    const result = this.config.provider === "anthropic" ? await this.callClaude(model, prompt) : await this.callOpenAI(model, prompt);
+    return result.slice(0, maxLen);
+  }
+  // ── Provider calls ───────────────────────────────────────────────────
+  async callClaude(model, prompt) {
+    let response;
+    try {
+      response = await this._fetch("https://api.anthropic.com/v1/messages", {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "x-api-key": this.config.apiKey,
+          "anthropic-version": "2023-06-01"
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: 256,
+          messages: [{ role: "user", content: prompt }]
+        })
+      });
+    } catch {
+      throw new AiProviderError({
+        type: "network_error",
+        message: "Failed to connect to Anthropic API."
+      });
+    }
+    if (!response.ok) {
+      const body2 = await response.json().catch(() => ({}));
+      throw new AiProviderError(classifyAiError(response.status, body2));
+    }
+    const body = await response.json();
+    const text = body?.content?.[0]?.text;
+    if (typeof text !== "string") {
+      throw new AiProviderError({
+        type: "unknown",
+        message: "Unexpected Claude API response format."
+      });
+    }
+    return text.trim();
+  }
+  async callOpenAI(model, prompt) {
+    let response;
+    try {
+      response = await this._fetch(
+        "https://api.openai.com/v1/chat/completions",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.config.apiKey}`
+          },
+          body: JSON.stringify({
+            model,
+            max_tokens: 256,
+            messages: [{ role: "user", content: prompt }]
+          })
+        }
+      );
+    } catch {
+      throw new AiProviderError({
+        type: "network_error",
+        message: "Failed to connect to OpenAI API."
+      });
+    }
+    if (!response.ok) {
+      const body2 = await response.json().catch(() => ({}));
+      throw new AiProviderError(classifyAiError(response.status, body2));
+    }
+    const body = await response.json();
+    const text = body?.choices?.[0]?.message?.content;
+    if (typeof text !== "string") {
+      throw new AiProviderError({
+        type: "unknown",
+        message: "Unexpected OpenAI API response format."
+      });
+    }
+    return text.trim();
+  }
+  // ── Bulk generation ────────────────────────────────────────────────────
+  /**
+   * Bulk-generate AI descriptions for multiple contexts.
+   * Processes in batches with progress callback.
+   */
+  async bulkGenerate(contexts, options) {
+    const batchSize = options?.batchSize ?? DEFAULT_BATCH_SIZE;
+    const maxItems = options?.maxItems ?? DEFAULT_MAX_ITEMS;
+    const items = contexts.slice(0, maxItems);
+    const results = [];
+    for (let i = 0; i < items.length; i += batchSize) {
+      const batch = items.slice(i, i + batchSize);
+      for (const ctx of batch) {
+        try {
+          const result = await this.generate(ctx);
+          results.push({ context: ctx, result });
+        } catch (err) {
+          const aiErr = err instanceof AiProviderError ? { type: err.type, message: err.message, statusCode: err.statusCode } : { type: "unknown", message: String(err) };
+          results.push({ context: ctx, result: null, error: aiErr });
+        }
+        if (options?.onProgress) {
+          options.onProgress(results.length, items.length, ctx);
+        }
+      }
+    }
+    return results;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AiGenerator,
+  AiProviderError,
+  RateLimiter,
+  buildPrompt,
+  classifyAiError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/ai/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/ai/index.ts","../../src/constants.ts"],"sourcesContent":["/**\n * AiGenerator — AI description generation via Anthropic Claude or OpenAI.\n *\n * Separate entry point: `geo-ai-core/ai`\n * Supports single and bulk generation with rate limiting,\n * prompt template placeholders, and error classification.\n *\n * Requirements: 5.1–5.10\n */\n\nimport type {\n  AiContext,\n  AiBulkConfig,\n  AiError,\n  AiGeneratorConfig,\n  AiProvider,\n  Resource,\n} from '../types';\n\nimport {\n  DEFAULT_RATE_LIMIT,\n  DEFAULT_BATCH_SIZE,\n  DEFAULT_MAX_ITEMS,\n  DEFAULT_MAX_DESCRIPTION_LENGTH,\n  DEFAULT_PROMPT,\n} from '../constants';\n\n// Re-export types for consumers of geo-ai-core/ai\nexport type { AiContext, AiBulkConfig, AiError, AiGeneratorConfig, AiProvider };\n\n// ── Rate limiter (sliding window) ────────────────────────────────────────\n\nconst RATE_WINDOW_MS = 60_000; // 1 minute\n\ninterface RateLimiterState {\n  count: number;\n  windowStart: number;\n}\n\n/**\n * Simple sliding-window rate limiter for AI API calls.\n * In-memory, per-process — not shared across instances.\n */\nexport class RateLimiter {\n  private state: RateLimiterState;\n  private limit: number;\n  private _now: () => number;\n\n  constructor(limit = DEFAULT_RATE_LIMIT, nowFn?: () => number) {\n    this.limit = limit;\n    this._now = nowFn ?? (() => Date.now());\n    this.state = { count: 0, windowStart: this._now() };\n  }\n\n  /** Returns true if a request is allowed, false if rate-limited. */\n  tryAcquire(): boolean {\n    const now = this._now();\n    if (now - this.state.windowStart >= RATE_WINDOW_MS) {\n      this.state = { count: 0, windowStart: now };\n    }\n    if (this.state.count >= this.limit) {\n      return false;\n    }\n    this.state.count++;\n    return true;\n  }\n\n  /** Reset the limiter state. */\n  reset(): void {\n    this.state = { count: 0, windowStart: this._now() };\n  }\n}\n\n// ── Prompt template ──────────────────────────────────────────────────────\n\n/**\n * Replaces placeholders {title}, {content}, {type}, {price}, {category}\n * in the prompt template with actual values from the context.\n *\n * Uses function replacer to avoid issues with special replacement patterns\n * (e.g. `$` characters in values).\n */\nexport function buildPrompt(template: string, context: AiContext): string {\n  return template\n    .replace(/\\{title\\}/g, () => context.title ?? '')\n    .replace(/\\{content\\}/g, () => context.content ?? '')\n    .replace(/\\{type\\}/g, () => context.type ?? '')\n    .replace(/\\{price\\}/g, () => context.price ?? '')\n    .replace(/\\{category\\}/g, () => context.category ?? '');\n}\n\n// ── Error classification ─────────────────────────────────────────────────\n\n/**\n * Classifies an AI provider HTTP error into a user-friendly category.\n */\nexport function classifyAiError(\n  statusCode: number,\n  body?: unknown,\n): AiError {\n  if (statusCode === 401 || statusCode === 403) {\n    return {\n      type: 'auth_error',\n      message: 'Invalid API key. Please check your key in settings.',\n      statusCode,\n    };\n  }\n  if (statusCode === 429) {\n    return {\n      type: 'rate_limit',\n      message: 'AI provider rate limit exceeded. Please wait and try again.',\n      statusCode,\n    };\n  }\n  if (statusCode >= 500) {\n    return {\n      type: 'server_error',\n      message: 'AI service is temporarily unavailable. Please try later.',\n      statusCode,\n    };\n  }\n  return {\n    type: 'unknown',\n    message:\n      (body as Record<string, Record<string, string>>)?.error?.message ??\n      'Unknown AI provider error.',\n    statusCode,\n  };\n}\n\n// ── AiProviderError ──────────────────────────────────────────────────────\n\nexport class AiProviderError extends Error {\n  readonly type: AiError['type'];\n  readonly statusCode?: number;\n\n  constructor(error: AiError) {\n    super(error.message);\n    this.name = 'AiProviderError';\n    this.type = error.type;\n    this.statusCode = error.statusCode;\n  }\n}\n\n// ── Fetch type ───────────────────────────────────────────────────────────\n\ntype FetchFn = typeof globalThis.fetch;\n\n// ── AiGenerator ──────────────────────────────────────────────────────────\n\nexport class AiGenerator {\n  private config: AiGeneratorConfig;\n  private rateLimiter: RateLimiter;\n  private _fetch: FetchFn;\n\n  constructor(config: AiGeneratorConfig, fetchFn?: FetchFn) {\n    this.config = config;\n    this.rateLimiter = new RateLimiter(config.rateLimit ?? DEFAULT_RATE_LIMIT);\n    this._fetch = fetchFn ?? globalThis.fetch.bind(globalThis);\n  }\n\n  private defaultModel(): string {\n    return this.config.provider === 'anthropic'\n      ? 'claude-sonnet-4-5-20250514'\n      : 'gpt-4o-mini';\n  }\n\n  /** Generate a single AI description. */\n  async generate(context: AiContext): Promise<string> {\n    if (!this.rateLimiter.tryAcquire()) {\n      throw new AiProviderError({\n        type: 'rate_limit',\n        message: 'Internal rate limit exceeded. Please wait before generating more descriptions.',\n      });\n    }\n\n    const template = this.config.promptTemplate ?? DEFAULT_PROMPT;\n    const prompt = buildPrompt(template, context);\n    const model = this.config.model ?? this.defaultModel();\n    const maxLen = this.config.maxDescriptionLength ?? DEFAULT_MAX_DESCRIPTION_LENGTH;\n\n    const result =\n      this.config.provider === 'anthropic'\n        ? await this.callClaude(model, prompt)\n        : await this.callOpenAI(model, prompt);\n\n    return result.slice(0, maxLen);\n  }\n\n  // ── Provider calls ───────────────────────────────────────────────────\n\n  private async callClaude(model: string, prompt: string): Promise<string> {\n    let response: Response;\n    try {\n      response = await this._fetch('https://api.anthropic.com/v1/messages', {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n          'x-api-key': this.config.apiKey,\n          'anthropic-version': '2023-06-01',\n        },\n        body: JSON.stringify({\n          model,\n          max_tokens: 256,\n          messages: [{ role: 'user', content: prompt }],\n        }),\n      });\n    } catch {\n      throw new AiProviderError({\n        type: 'network_error',\n        message: 'Failed to connect to Anthropic API.',\n      });\n    }\n\n    if (!response.ok) {\n      const body = await response.json().catch(() => ({}));\n      throw new AiProviderError(classifyAiError(response.status, body));\n    }\n\n    const body = await response.json();\n    const text = body?.content?.[0]?.text;\n    if (typeof text !== 'string') {\n      throw new AiProviderError({\n        type: 'unknown',\n        message: 'Unexpected Claude API response format.',\n      });\n    }\n    return text.trim();\n  }\n\n  private async callOpenAI(model: string, prompt: string): Promise<string> {\n    let response: Response;\n    try {\n      response = await this._fetch(\n        'https://api.openai.com/v1/chat/completions',\n        {\n          method: 'POST',\n          headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${this.config.apiKey}`,\n          },\n          body: JSON.stringify({\n            model,\n            max_tokens: 256,\n            messages: [{ role: 'user', content: prompt }],\n          }),\n        },\n      );\n    } catch {\n      throw new AiProviderError({\n        type: 'network_error',\n        message: 'Failed to connect to OpenAI API.',\n      });\n    }\n\n    if (!response.ok) {\n      const body = await response.json().catch(() => ({}));\n      throw new AiProviderError(classifyAiError(response.status, body));\n    }\n\n    const body = await response.json();\n    const text = body?.choices?.[0]?.message?.content;\n    if (typeof text !== 'string') {\n      throw new AiProviderError({\n        type: 'unknown',\n        message: 'Unexpected OpenAI API response format.',\n      });\n    }\n    return text.trim();\n  }\n\n  // ── Bulk generation ────────────────────────────────────────────────────\n\n  /**\n   * Bulk-generate AI descriptions for multiple contexts.\n   * Processes in batches with progress callback.\n   */\n  async bulkGenerate(\n    contexts: AiContext[],\n    options?: AiBulkConfig,\n  ): Promise<Array<{ context: AiContext; result: string | null; error?: AiError }>> {\n    const batchSize = options?.batchSize ?? DEFAULT_BATCH_SIZE;\n    const maxItems = options?.maxItems ?? DEFAULT_MAX_ITEMS;\n    const items = contexts.slice(0, maxItems);\n    const results: Array<{ context: AiContext; result: string | null; error?: AiError }> = [];\n\n    for (let i = 0; i < items.length; i += batchSize) {\n      const batch = items.slice(i, i + batchSize);\n\n      for (const ctx of batch) {\n        try {\n          const result = await this.generate(ctx);\n          results.push({ context: ctx, result });\n        } catch (err) {\n          const aiErr: AiError =\n            err instanceof AiProviderError\n              ? { type: err.type, message: err.message, statusCode: err.statusCode }\n              : { type: 'unknown', message: String(err) };\n          results.push({ context: ctx, result: null, error: aiErr });\n        }\n\n        if (options?.onProgress) {\n          options.onProgress(results.length, items.length, ctx as unknown as Resource);\n        }\n      }\n    }\n\n    return results;\n  }\n}\n","/**\n * Supported AI crawlers: bot User-Agent identifier → human-readable name.\n * Minimum 13 bots per spec requirement 3.1.\n */\nexport const AI_BOTS: Record<string, string> = {\n  GPTBot: 'OpenAI / ChatGPT',\n  'OAI-SearchBot': 'OpenAI / Copilot Search',\n  ClaudeBot: 'Anthropic / Claude',\n  'Google-Extended': 'Google / Gemini',\n  PerplexityBot: 'Perplexity AI',\n  DeepSeekBot: 'DeepSeek',\n  GrokBot: 'xAI / Grok',\n  'meta-externalagent': 'Meta / LLaMA',\n  PanguBot: 'Alibaba / Qwen',\n  YandexBot: 'Yandex / YandexGPT',\n  SputnikBot: 'Sber / GigaChat',\n  Bytespider: 'ByteDance / Douyin',\n  Baiduspider: 'Baidu / ERNIE',\n  'claude-web': 'Anthropic / Claude Web',\n  Amazonbot: 'Amazon / Alexa',\n  Applebot: 'Apple / Siri & Spotlight',\n};\n\n/** Default maximum words for content in llms-full.txt */\nexport const DEFAULT_MAX_CONTENT_WORDS = 200;\n\n/** Default AI API requests per minute */\nexport const DEFAULT_RATE_LIMIT = 10;\n\n/** Default items per batch in bulk AI generation */\nexport const DEFAULT_BATCH_SIZE = 5;\n\n/** Default maximum items for bulk AI generation */\nexport const DEFAULT_MAX_ITEMS = 50;\n\n/** Default maximum AI description length (characters) */\nexport const DEFAULT_MAX_DESCRIPTION_LENGTH = 200;\n\n/** Default prompt template for AI description generation */\nexport const DEFAULT_PROMPT = `Write a concise AI-optimized description (max 200 characters) for the following {type}.\n\nTitle: {title}\nContent: {content}\nPrice: {price}\nCategory: {category}\n\nThe description should be informative, keyword-rich, and suitable for AI search engines. Focus on the key features and value proposition.`;\n"],"mappings":"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","names":["body"]}

package/dist/ai/index.d.cts

@@ -0,0 +1,67 @@
+import { g as AiGeneratorConfig, e as AiContext, A as AiBulkConfig, f as AiError } from '../types-B3qT6_qa.cjs';
+export { h as AiProvider } from '../types-B3qT6_qa.cjs';
+
+/**
+ * AiGenerator — AI description generation via Anthropic Claude or OpenAI.
+ *
+ * Separate entry point: `geo-ai-core/ai`
+ * Supports single and bulk generation with rate limiting,
+ * prompt template placeholders, and error classification.
+ *
+ * Requirements: 5.1–5.10
+ */
+
+/**
+ * Simple sliding-window rate limiter for AI API calls.
+ * In-memory, per-process — not shared across instances.
+ */
+declare class RateLimiter {
+    private state;
+    private limit;
+    private _now;
+    constructor(limit?: number, nowFn?: () => number);
+    /** Returns true if a request is allowed, false if rate-limited. */
+    tryAcquire(): boolean;
+    /** Reset the limiter state. */
+    reset(): void;
+}
+/**
+ * Replaces placeholders {title}, {content}, {type}, {price}, {category}
+ * in the prompt template with actual values from the context.
+ *
+ * Uses function replacer to avoid issues with special replacement patterns
+ * (e.g. `$` characters in values).
+ */
+declare function buildPrompt(template: string, context: AiContext): string;
+/**
+ * Classifies an AI provider HTTP error into a user-friendly category.
+ */
+declare function classifyAiError(statusCode: number, body?: unknown): AiError;
+declare class AiProviderError extends Error {
+    readonly type: AiError['type'];
+    readonly statusCode?: number;
+    constructor(error: AiError);
+}
+type FetchFn = typeof globalThis.fetch;
+declare class AiGenerator {
+    private config;
+    private rateLimiter;
+    private _fetch;
+    constructor(config: AiGeneratorConfig, fetchFn?: FetchFn);
+    private defaultModel;
+    /** Generate a single AI description. */
+    generate(context: AiContext): Promise<string>;
+    private callClaude;
+    private callOpenAI;
+    /**
+     * Bulk-generate AI descriptions for multiple contexts.
+     * Processes in batches with progress callback.
+     */
+    bulkGenerate(contexts: AiContext[], options?: AiBulkConfig): Promise<Array<{
+        context: AiContext;
+        result: string | null;
+        error?: AiError;
+    }>>;
+}
+
+export { AiBulkConfig, AiContext, AiError, AiGenerator, AiGeneratorConfig, AiProviderError, RateLimiter, buildPrompt, classifyAiError };

package/dist/ai/index.d.ts

@@ -0,0 +1,67 @@
+import { g as AiGeneratorConfig, e as AiContext, A as AiBulkConfig, f as AiError } from '../types-B3qT6_qa.js';
+export { h as AiProvider } from '../types-B3qT6_qa.js';
+
+/**
+ * AiGenerator — AI description generation via Anthropic Claude or OpenAI.
+ *
+ * Separate entry point: `geo-ai-core/ai`
+ * Supports single and bulk generation with rate limiting,
+ * prompt template placeholders, and error classification.
+ *
+ * Requirements: 5.1–5.10
+ */
+
+/**
+ * Simple sliding-window rate limiter for AI API calls.
+ * In-memory, per-process — not shared across instances.
+ */
+declare class RateLimiter {
+    private state;
+    private limit;
+    private _now;
+    constructor(limit?: number, nowFn?: () => number);
+    /** Returns true if a request is allowed, false if rate-limited. */
+    tryAcquire(): boolean;
+    /** Reset the limiter state. */
+    reset(): void;
+}
+/**
+ * Replaces placeholders {title}, {content}, {type}, {price}, {category}
+ * in the prompt template with actual values from the context.
+ *
+ * Uses function replacer to avoid issues with special replacement patterns
+ * (e.g. `$` characters in values).
+ */
+declare function buildPrompt(template: string, context: AiContext): string;
+/**
+ * Classifies an AI provider HTTP error into a user-friendly category.
+ */
+declare function classifyAiError(statusCode: number, body?: unknown): AiError;
+declare class AiProviderError extends Error {
+    readonly type: AiError['type'];
+    readonly statusCode?: number;
+    constructor(error: AiError);
+}
+type FetchFn = typeof globalThis.fetch;
+declare class AiGenerator {
+    private config;
+    private rateLimiter;
+    private _fetch;
+    constructor(config: AiGeneratorConfig, fetchFn?: FetchFn);
+    private defaultModel;
+    /** Generate a single AI description. */
+    generate(context: AiContext): Promise<string>;
+    private callClaude;
+    private callOpenAI;
+    /**
+     * Bulk-generate AI descriptions for multiple contexts.
+     * Processes in batches with progress callback.
+     */
+    bulkGenerate(contexts: AiContext[], options?: AiBulkConfig): Promise<Array<{
+        context: AiContext;
+        result: string | null;
+        error?: AiError;
+    }>>;
+}
+
+export { AiBulkConfig, AiContext, AiError, AiGenerator, AiGeneratorConfig, AiProviderError, RateLimiter, buildPrompt, classifyAiError };