@astro-minimax/ai 0.2.0

package/README.md

@@ -0,0 +1,223 @@
+# @astro-minimax/ai
+
+Vendor-agnostic AI integration package with full RAG pipeline for astro-minimax blogs. Supports OpenAI-compatible APIs, Cloudflare Workers AI, and mock fallback.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  Components (ChatPanel / AIChatWidget / AIChatContainer) │
+│  → useChat + DefaultChatTransport                        │
+└──────────────────────────┬──────────────────────────────┘
+                           │ POST /api/chat
+┌──────────────────────────▼──────────────────────────────┐
+│  Server (chat-handler.ts)                                │
+│  Rate Limit → Validate → Search → Evidence → Prompt →   │
+│  Provider Manager → streamText → SSE Response            │
+└──────────────────────────┬──────────────────────────────┘
+                           │
+     ┌─────────────────────┼──────────────────────┐
+     │                     │                      │
+ ┌───▼───┐          ┌─────▼─────┐          ┌─────▼────┐
+ │OpenAI │          │Workers AI │          │   Mock   │
+ │Compat │          │ Binding   │          │ Fallback │
+ └───────┘          └───────────┘          └──────────┘
+```
+
+### Modules
+
+| Module              | Purpose                                                                |
+| ------------------- | ---------------------------------------------------------------------- |
+| `server/`           | Reusable API handlers (`handleChatRequest`, `initializeMetadata`)      |
+| `provider-manager/` | Multi-provider management with priority, failover, health tracking     |
+| `search/`           | In-memory article/project search with session caching                  |
+| `intelligence/`     | Keyword extraction, evidence analysis, citation guard                  |
+| `prompt/`           | Three-layer system prompt builder (static → semi-static → dynamic)     |
+| `data/`             | Build-time metadata loading (summaries, author context, voice profile) |
+| `stream/`           | Stream helpers and response utilities                                  |
+| `components/`       | Preact UI components (ChatPanel, AIChatWidget, AIChatContainer)        |
+
+## Installation
+
+```bash
+pnpm add @astro-minimax/ai
+```
+
+The `@astro-minimax/core` integration auto-detects this package and renders the AI chat widget.
+
+## Configuration
+
+In `src/config.ts`:
+
+```typescript
+export const SITE = {
+  ai: {
+    enabled: true,
+    mockMode: false,
+    apiEndpoint: "/api/chat",
+    welcomeMessage: undefined, // auto-generated
+    placeholder: undefined,
+  },
+};
+```
+
+### Environment Variables
+
+| Variable            | Required    | Description                                                 |
+| ------------------- | ----------- | ----------------------------------------------------------- |
+| `AI_BASE_URL`       | For OpenAI  | Base URL of OpenAI-compatible API                           |
+| `AI_API_KEY`        | For OpenAI  | API key                                                     |
+| `AI_MODEL`          | Recommended | Model name for OpenAI provider (default: `gpt-4o-mini`)     |
+| `AI_KEYWORD_MODEL`  | Optional    | Model for keyword extraction (defaults to `AI_MODEL`)       |
+| `AI_EVIDENCE_MODEL` | Optional    | Model for evidence analysis (defaults to keyword model)     |
+| `AI_BINDING_NAME`   | For Workers | Cloudflare AI binding name (default: `minimaxAI`)           |
+| `AI_WORKERS_MODEL`  | For Workers | Model for Workers AI (default: `@cf/zai-org/glm-4.7-flash`) |
+| `SITE_AUTHOR`       | Recommended | Author name for prompts                                     |
+| `SITE_URL`          | Recommended | Site URL for article links                                  |
+
+### Response Cache Configuration
+
+| Variable                           | Default | Description                               |
+| ---------------------------------- | ------- | ----------------------------------------- |
+| `AI_RESPONSE_CACHE_ENABLED`        | `false` | Enable AI response caching                |
+| `AI_RESPONSE_CACHE_TTL`            | `3600`  | Cache TTL in seconds (1 hour)             |
+| `AI_RESPONSE_CACHE_PLAYBACK_DELAY` | `20`    | Delay between chunks during playback (ms) |
+| `AI_RESPONSE_CACHE_CHUNK_SIZE`     | `15`    | Characters per chunk during playback      |
+| `AI_RESPONSE_CACHE_THINKING_DELAY` | `5`     | Delay for thinking content playback (ms)  |
+
+When enabled, the system caches complete AI responses (including thinking/reasoning content) for public questions like "What tech stack does this blog use?". Subsequent identical queries are served from cache with simulated streaming playback, reducing API costs and response time.
+
+## Server Module
+
+The server module provides reusable request handlers, decoupled from any specific runtime (Cloudflare, Node.js, etc.).
+
+### Usage in Cloudflare Pages Functions
+
+```typescript
+// functions/api/chat.ts
+import { handleChatRequest, initializeMetadata } from '@astro-minimax/ai/server';
+import summaries from '../../datas/ai-summaries.json';
+import authorContext from '../../datas/author-context.json';
+import voiceProfile from '../../datas/voice-profile.json';
+
+export const onRequest: PagesFunction = async (context) => {
+  initializeMetadata({ summaries, authorContext, voiceProfile }, context.env);
+  return handleChatRequest({ env: context.env, request: context.request });
+};
+```
+
+### Chat API Contract
+
+**Request:** `POST /api/chat`
+
+```json
+{
+  "context": {
+    "scope": "article",
+    "article": {
+      "slug": "my-post",
+      "title": "My Post Title",
+      "summary": "Brief summary...",
+      "keyPoints": ["Point 1", "Point 2"],
+      "categories": ["tech"]
+    }
+  },
+  "id": "article:my-post",
+  "messages": [...]
+}
+```
+
+`context.scope` values:
+
+- `"global"` — General blog chat (default)
+- `"article"` — Reading companion mode, focused on a specific article
+
+**Response:** UI Message Stream Protocol (SSE)
+
+- `text-start` / `text-delta` / `text-end` — Streaming text content
+- `source` — RAG article references
+- `message-metadata` — Processing status updates
+- `finish` — Stream completion
+
+**Error Response:**
+
+```json
+{
+  "error": "请求太频繁，请稍后再试",
+  "code": "RATE_LIMITED",
+  "retryable": true,
+  "retryAfter": 10
+}
+```
+
+| Code                   | Status | Retryable | Description           |
+| ---------------------- | ------ | --------- | --------------------- |
+| `RATE_LIMITED`         | 429    | Yes       | Too many requests     |
+| `PROVIDER_UNAVAILABLE` | 503    | Yes       | All providers failed  |
+| `TIMEOUT`              | 504    | Yes       | Request timeout       |
+| `INPUT_TOO_LONG`       | 400    | No        | Message exceeds limit |
+| `INVALID_REQUEST`      | 400    | No        | Malformed request     |
+| `INTERNAL_ERROR`       | 500    | Yes       | Server error          |
+
+## Provider System
+
+### Priority & Failover
+
+```
+Workers AI (weight: 100) → OpenAI Compatible (weight: 90) → Mock (weight: 0)
+```
+
+When a provider fails, the next one is tried automatically. Mock fallback ensures users always get a response.
+
+### Timeout Budget (per request: 45s total)
+
+| Stage              | Timeout | Behavior on timeout              |
+| ------------------ | ------- | -------------------------------- |
+| Keyword extraction | 5s      | Falls back to local search query |
+| Evidence analysis  | 8s      | Skipped                          |
+| LLM streaming      | 30s     | Tries next provider, then mock   |
+
+## "Read & Chat" (边读边聊)
+
+When a user opens the AI chat on an article page, the system enters **reading companion mode**:
+
+1. **Article context** flows from `PostDetails.astro` → `Layout.astro` → `AIChatWidget` → `ChatPanel`
+2. **Welcome message** references the current article title
+3. **Quick prompts** are article-specific (summarize, explain, related topics)
+4. **API request** includes `context: { scope: "article", article: {...} }`
+5. **Server** enhances the prompt with article summary, key points, and reading companion instructions
+
+## Components
+
+### AIChatWidget.astro
+
+Astro entry point. Accepts `lang` and optional `articleContext` props. Renders `AIChatContainer` with `client:idle`.
+
+### AIChatContainer.tsx
+
+Manages open/close state. Exposes `window.__aiChatToggle` for the floating action button.
+
+### ChatPanel.tsx
+
+Core chat UI built on `useChat` from `@ai-sdk/react`:
+
+- `DefaultChatTransport` with `prepareSendMessagesRequest` for context injection
+- Parts-based message rendering (`text`, `source`, custom data parts)
+- Error display with retry button (`regenerate()`)
+- Status indicators from message metadata
+- Mock mode with character-by-character streaming simulation
+
+## Exports
+
+| Path             | Contents                                                        |
+| ---------------- | --------------------------------------------------------------- |
+| `.`              | All modules                                                     |
+| `./server`       | `handleChatRequest`, `initializeMetadata`, error helpers, types |
+| `./providers`    | Mock response/stream utilities                                  |
+| `./middleware`   | Rate limiting                                                   |
+| `./search`       | Article/project search, session cache                           |
+| `./intelligence` | Keyword extraction, evidence analysis, citation guard           |
+| `./prompt`       | System prompt builder                                           |
+| `./data`         | Metadata loading                                                |
+| `./stream`       | Stream utilities                                                |
+| `./components/*` | Astro/Preact components                                         |

package/dist/cache/global-cache.d.ts

@@ -0,0 +1,31 @@
+import type { CacheAdapter, CachedSearchContext } from './types.js';
+export type PublicQuestionType = 'tech' | 'recommend' | 'build' | 'summary' | 'author' | 'about';
+export interface PublicQuestionPattern {
+    type: PublicQuestionType;
+    keywords: string[];
+    patterns: RegExp[];
+    ttl: number;
+    needsContext: boolean;
+}
+export declare const PUBLIC_QUESTION_PATTERNS: PublicQuestionPattern[];
+export interface DetectedPublicQuestion {
+    type: PublicQuestionType;
+    confidence: number;
+    ttl: number;
+    needsContext: boolean;
+}
+export declare function detectPublicQuestion(query: string): DetectedPublicQuestion | null;
+export declare function buildGlobalCacheKey(type: PublicQuestionType, context?: {
+    articleSlug?: string;
+    lang?: string;
+}): string;
+export declare function getGlobalSearchCache(cache: CacheAdapter, type: PublicQuestionType, context?: {
+    articleSlug?: string;
+    lang?: string;
+}): Promise<CachedSearchContext | null>;
+export declare function setGlobalSearchCache(cache: CacheAdapter, type: PublicQuestionType, data: CachedSearchContext, ttl: number, context?: {
+    articleSlug?: string;
+    lang?: string;
+}): Promise<void>;
+export declare function getGlobalCacheTTL(type: PublicQuestionType): number;
+//# sourceMappingURL=global-cache.d.ts.map

package/dist/cache/global-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-cache.d.ts","sourceRoot":"","sources":["../../src/cache/global-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEpE,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,WAAW,GACX,OAAO,GACP,SAAS,GACT,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,wBAAwB,EAAE,qBAAqB,EAiF3D,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,kBAAkB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CAkCjF;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,kBAAkB,EACxB,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,MAAM,CAYR;AAUD,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,kBAAkB,EACxB,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAIrC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAGlE"}

package/dist/cache/global-cache.js

@@ -0,0 +1,141 @@
+export const PUBLIC_QUESTION_PATTERNS = [
+    {
+        type: 'tech',
+        keywords: ['技术栈', '技术', '框架', '用了什么', 'built with', 'tech stack', 'framework'],
+        patterns: [
+            /这个博客用了什么/,
+            /博客.*技术栈/,
+            /用了什么技术/,
+            /what.*tech.*stack/,
+            /built with/,
+            /用什么框架/,
+        ],
+        ttl: 86400,
+        needsContext: false,
+    },
+    {
+        type: 'recommend',
+        keywords: ['推荐', '文章推荐', '好文', 'recommend', 'suggest'],
+        patterns: [
+            /推荐.*文章/,
+            /有哪些推荐/,
+            /文章推荐/,
+            /recommend.*article/,
+            /any.*recommend/,
+        ],
+        ttl: 1800,
+        needsContext: false,
+    },
+    {
+        type: 'build',
+        keywords: ['搭建', '部署', '怎么建', 'how to build', 'deploy', 'setup'],
+        patterns: [
+            /怎么搭建/,
+            /如何搭建/,
+            /怎么部署/,
+            /how to build/,
+            /how to deploy/,
+            /搭建.*博客/,
+        ],
+        ttl: 86400,
+        needsContext: false,
+    },
+    {
+        type: 'summary',
+        keywords: ['总结', '概括', '摘要', 'summarize', 'summary', 'tl;dr'],
+        patterns: [
+            /总结(一下|这篇文章)/,
+            /概括(一下|这篇文章)/,
+            /文章摘要/,
+            /summarize/,
+            /summary/,
+            /主要讲了什么/,
+        ],
+        ttl: 14400,
+        needsContext: true,
+    },
+    {
+        type: 'author',
+        keywords: ['作者', '博主', '谁', 'author', 'who'],
+        patterns: [
+            /作者是谁/,
+            /博主是谁/,
+            /关于作者/,
+            /who.*author/,
+            /about author/,
+        ],
+        ttl: 86400,
+        needsContext: false,
+    },
+    {
+        type: 'about',
+        keywords: ['关于', '介绍', 'about', 'intro'],
+        patterns: [
+            /关于.*博客/,
+            /博客介绍/,
+            /about.*blog/,
+            /介绍一下/,
+        ],
+        ttl: 86400,
+        needsContext: false,
+    },
+];
+export function detectPublicQuestion(query) {
+    const normalized = normalizeQuery(query);
+    let bestMatch = null;
+    let bestScore = 0;
+    for (const pattern of PUBLIC_QUESTION_PATTERNS) {
+        let score = 0;
+        for (const keyword of pattern.keywords) {
+            if (normalized.includes(keyword.toLowerCase())) {
+                score += 1;
+            }
+        }
+        for (const regex of pattern.patterns) {
+            if (regex.test(normalized)) {
+                score += 3;
+            }
+        }
+        if (score > bestScore && score >= 2) {
+            bestScore = score;
+            const confidence = Math.min(score / 5, 1);
+            bestMatch = {
+                type: pattern.type,
+                confidence,
+                ttl: pattern.ttl,
+                needsContext: pattern.needsContext,
+            };
+        }
+    }
+    return bestMatch;
+}
+export function buildGlobalCacheKey(type, context) {
+    const parts = ['global', type];
+    if (context?.articleSlug) {
+        parts.push(context.articleSlug);
+    }
+    if (context?.lang) {
+        parts.push(context.lang);
+    }
+    return parts.join(':');
+}
+function normalizeQuery(query) {
+    return query
+        .toLowerCase()
+        .replace(/[？?!！。，,.]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+export async function getGlobalSearchCache(cache, type, context) {
+    const key = buildGlobalCacheKey(type, context);
+    const entry = await cache.get(key);
+    return entry?.value ?? null;
+}
+export async function setGlobalSearchCache(cache, type, data, ttl, context) {
+    const key = buildGlobalCacheKey(type, context);
+    await cache.set(key, data, { ttl });
+}
+export function getGlobalCacheTTL(type) {
+    const pattern = PUBLIC_QUESTION_PATTERNS.find(p => p.type === type);
+    return pattern?.ttl ?? 3600;
+}

package/dist/cache/index.d.ts

@@ -0,0 +1,8 @@
+export { MemoryCacheAdapter, type MemoryCacheOptions, } from './memory-adapter.js';
+export { KVCacheAdapter, type KVCacheOptions, } from './kv-adapter.js';
+export { createCacheKeyBuilder, type CacheAdapter, type CacheEntry, type CacheEntryMetadata, type CacheSetOptions, type CacheGetOptions, type CacheManagerConfig, type CacheEnv, type CachedSearchContext, type CacheResult, type CacheKeyBuilder, } from './types.js';
+export { detectPublicQuestion, buildGlobalCacheKey, getGlobalSearchCache, setGlobalSearchCache, getGlobalCacheTTL, PUBLIC_QUESTION_PATTERNS, type PublicQuestionType, type PublicQuestionPattern, type DetectedPublicQuestion, } from './global-cache.js';
+export { getResponseCache, setResponseCache, deleteResponseCache, getResponseCacheConfig, buildResponseCacheKey, createResponsePlaybackGenerator, DEFAULT_RESPONSE_CACHE_CONFIG, type CachedAIResponse, type ResponseCacheConfig, type ResponseCacheEnv, type PlaybackChunk, } from './response-cache.js';
+import type { CacheAdapter, CacheEnv, CacheManagerConfig } from './types.js';
+export declare function createCacheAdapter(env: CacheEnv, config?: CacheManagerConfig): CacheAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,cAAc,EACd,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,EACjB,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,+BAA+B,EAC/B,6BAA6B,EAC7B,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAc7E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,QAAQ,EACb,MAAM,CAAC,EAAE,kBAAkB,GAC1B,YAAY,CAcd"}

package/dist/cache/index.js

@@ -0,0 +1,62 @@
+export { MemoryCacheAdapter, } from './memory-adapter.js';
+export { KVCacheAdapter, } from './kv-adapter.js';
+export { createCacheKeyBuilder, } from './types.js';
+export { detectPublicQuestion, buildGlobalCacheKey, getGlobalSearchCache, setGlobalSearchCache, getGlobalCacheTTL, PUBLIC_QUESTION_PATTERNS, } from './global-cache.js';
+export { getResponseCache, setResponseCache, deleteResponseCache, getResponseCacheConfig, buildResponseCacheKey, createResponsePlaybackGenerator, DEFAULT_RESPONSE_CACHE_CONFIG, } from './response-cache.js';
+import { MemoryCacheAdapter } from './memory-adapter.js';
+import { KVCacheAdapter } from './kv-adapter.js';
+const DEFAULT_TTL = 600;
+const DEFAULT_MAX_ENTRIES = 400;
+let globalMemoryCache = null;
+function getGlobalMemoryCache(ttl, maxEntries) {
+    if (!globalMemoryCache) {
+        globalMemoryCache = new MemoryCacheAdapter({ defaultTtl: ttl, maxEntries });
+    }
+    return globalMemoryCache;
+}
+export function createCacheAdapter(env, config) {
+    const ttl = config?.defaultTtl ?? parseTtl(env.CACHE_TTL) ?? DEFAULT_TTL;
+    const maxEntries = config?.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    if (isCacheDisabled(env)) {
+        return getGlobalMemoryCache(ttl, maxEntries);
+    }
+    const kvBinding = getKVBinding(env);
+    if (kvBinding) {
+        return new KVCacheAdapter(kvBinding, { defaultTtl: ttl });
+    }
+    return getGlobalMemoryCache(ttl, maxEntries);
+}
+function isCacheDisabled(env) {
+    const val = env.CACHE_DISABLED;
+    if (val === true || val === 'true' || val === '1') {
+        return true;
+    }
+    return false;
+}
+function getKVBinding(env) {
+    const customBinding = env.CACHE_KV_BINDING;
+    if (customBinding && typeof customBinding === 'string') {
+        const binding = env[customBinding];
+        return isKVNamespace(binding) ? binding : null;
+    }
+    if (env.CACHE_KV && isKVNamespace(env.CACHE_KV)) {
+        return env.CACHE_KV;
+    }
+    const defaultBinding = env['CACHE_KV'];
+    return isKVNamespace(defaultBinding) ? defaultBinding : null;
+}
+function isKVNamespace(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'get' in value &&
+        'put' in value &&
+        'delete' in value);
+}
+function parseTtl(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'number')
+        return value;
+    const parsed = parseInt(value, 10);
+    return isNaN(parsed) ? undefined : parsed;
+}

package/dist/cache/kv-adapter.d.ts

@@ -0,0 +1,21 @@
+import type { CacheAdapter, CacheEntry, CacheSetOptions, CacheGetOptions } from './types.js';
+export interface KVCacheOptions {
+    defaultTtl?: number;
+    prefix?: string;
+}
+export declare class KVCacheAdapter implements CacheAdapter {
+    readonly name = "cloudflare-kv";
+    private kv;
+    private defaultTtl;
+    private prefix;
+    constructor(kv: KVNamespace, options?: KVCacheOptions);
+    private buildKey;
+    get<T>(key: string, options?: CacheGetOptions): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    isAvailable(): Promise<boolean>;
+    dispose(): void;
+}
+//# sourceMappingURL=kv-adapter.d.ts.map

package/dist/cache/kv-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-adapter.d.ts","sourceRoot":"","sources":["../../src/cache/kv-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EAEV,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAOpB,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,mBAAmB;IAChC,OAAO,CAAC,EAAE,CAAc;IACxB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAS;gBAEX,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc;IAMrD,OAAO,CAAC,QAAQ;IAIV,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA0B7E,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BvE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAerC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUlC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IASrC,OAAO,IAAI,IAAI;CAGhB"}

package/dist/cache/kv-adapter.js

@@ -0,0 +1,102 @@
+const DEFAULT_TTL_SECONDS = 600;
+const MIN_TTL_SECONDS = 60;
+export class KVCacheAdapter {
+    name = 'cloudflare-kv';
+    kv;
+    defaultTtl;
+    prefix;
+    constructor(kv, options) {
+        this.kv = kv;
+        this.defaultTtl = options?.defaultTtl ?? DEFAULT_TTL_SECONDS;
+        this.prefix = options?.prefix ?? '';
+    }
+    buildKey(key) {
+        return this.prefix ? `${this.prefix}:${key}` : key;
+    }
+    async get(key, options) {
+        try {
+            const fullKey = this.buildKey(key);
+            const result = await this.kv.getWithMetadata(fullKey, 'json');
+            if (!result.value) {
+                return null;
+            }
+            const storedEntry = result.value;
+            if (!storedEntry.value || !storedEntry.metadata) {
+                return null;
+            }
+            return {
+                value: storedEntry.value,
+                metadata: storedEntry.metadata,
+            };
+        }
+        catch (error) {
+            if (!options?.silent) {
+                console.error('[KVCacheAdapter] Get error:', error);
+            }
+            return null;
+        }
+    }
+    async set(key, value, options) {
+        try {
+            const now = Date.now();
+            const ttl = options?.ttl ?? this.defaultTtl;
+            const entry = {
+                value,
+                metadata: {
+                    createdAt: now,
+                    updatedAt: now,
+                    custom: options?.metadata,
+                },
+            };
+            const fullKey = this.buildKey(key);
+            const effectiveTtl = Math.max(ttl, MIN_TTL_SECONDS);
+            await this.kv.put(fullKey, JSON.stringify(entry), {
+                expirationTtl: effectiveTtl,
+            });
+        }
+        catch (error) {
+            console.error('[KVCacheAdapter] Set error:', error);
+            throw error;
+        }
+    }
+    async delete(key) {
+        try {
+            const fullKey = this.buildKey(key);
+            const existing = await this.kv.get(fullKey);
+            if (existing === null) {
+                return false;
+            }
+            await this.kv.delete(fullKey);
+            return true;
+        }
+        catch (error) {
+            console.error('[KVCacheAdapter] Delete error:', error);
+            return false;
+        }
+    }
+    async clear() {
+        console.warn('[KVCacheAdapter] Clear not supported for KV namespace');
+    }
+    async has(key) {
+        try {
+            const fullKey = this.buildKey(key);
+            const value = await this.kv.get(fullKey);
+            return value !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    async isAvailable() {
+        try {
+            await this.kv.get('__health_check__');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    dispose() {
+        // KV adapter doesn't hold any resources that need cleanup
+    }
+}

package/dist/cache/memory-adapter.d.ts

@@ -0,0 +1,24 @@
+import type { CacheAdapter, CacheEntry, CacheSetOptions, CacheGetOptions } from './types.js';
+export interface MemoryCacheOptions {
+    maxEntries?: number;
+    defaultTtl?: number;
+    cleanupInterval?: number;
+}
+export declare class MemoryCacheAdapter implements CacheAdapter {
+    readonly name = "memory";
+    private cache;
+    private maxEntries;
+    private defaultTtl;
+    private cleanupTimer?;
+    constructor(options?: MemoryCacheOptions);
+    get<T>(key: string, _options?: CacheGetOptions): Promise<CacheEntry<T> | null>;
+    set<T>(key: string, value: T, options?: CacheSetOptions): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    isAvailable(): Promise<boolean>;
+    private cleanup;
+    private evictLRU;
+    dispose(): void;
+}
+//# sourceMappingURL=memory-adapter.d.ts.map

package/dist/cache/memory-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-adapter.d.ts","sourceRoot":"","sources":["../../src/cache/memory-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,UAAU,EAEV,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD,qBAAa,kBAAmB,YAAW,YAAY;IACrD,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,KAAK,CAA6C;IAC1D,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAAC,CAAiC;gBAE1C,OAAO,CAAC,EAAE,kBAAkB;IAYlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmB9E,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBvE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYlC,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAIrC,OAAO,CAAC,OAAO;IASf,OAAO,CAAC,QAAQ;IAYhB,OAAO,IAAI,IAAI;CAOhB"}