@nby.ai/ucm 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,492 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * Universal Content Module - Type Definitions
+ * Supabase-powered content management with multi-language support
+ */
+type ContentType = 'news' | 'daily' | 'blog' | 'doc' | 'event' | 'announcement' | 'tutorial' | 'case_study' | 'faq' | 'changelog' | 'thought' | 'digest' | 'briefing';
+type ContentStatus = 'draft' | 'scheduled' | 'published' | 'archived';
+type ContentVisibility = 'public' | 'internal' | 'unlisted';
+type SupportedLanguage = 'zh' | 'en' | 'ja' | 'ko' | 'es' | 'de' | 'fr';
+type I18nText = Partial<Record<SupportedLanguage, string>>;
+interface Content {
+    id: string;
+    slug: string;
+    type: ContentType;
+    status: ContentStatus;
+    visibility: ContentVisibility;
+    category_id: string | null;
+    title: I18nText;
+    description: I18nText;
+    content: I18nText;
+    cover_image: string | null;
+    images: Array<{
+        url: string;
+        alt?: I18nText;
+    }>;
+    tags: string[];
+    author: string;
+    source: string | null;
+    source_url: string | null;
+    metadata: ContentMetadata;
+    seo: SeoData;
+    featured: boolean;
+    pinned: boolean;
+    published_at: string | null;
+    scheduled_at: string | null;
+    created_at: string;
+    updated_at: string;
+    sort_order: number;
+    view_count: number;
+}
+interface NewsMetadata {
+    wechat_msg_id?: string;
+    original_author?: string;
+    subtype?: 'press' | 'announcement' | 'changelog';
+    version?: string;
+}
+interface DailyMetadata {
+    date: string;
+    market?: Record<string, string>;
+    highlights?: string[];
+}
+interface DigestMetadata {
+    topic?: string;
+    highlights?: string[];
+    sources?: string[];
+    date?: string;
+}
+type BriefingFrequency = 'daily' | 'weekly' | 'monthly';
+interface BriefingMetadata {
+    frequency: BriefingFrequency;
+    period: string;
+    metrics?: Record<string, number>;
+    highlights?: string[];
+    tasks_completed?: number;
+    tasks_pending?: number;
+}
+interface BlogMetadata {
+    reading_time?: number;
+    series?: string;
+    toc?: boolean;
+}
+interface DocMetadata {
+    version?: string;
+    prev_slug?: string;
+    next_slug?: string;
+}
+interface EventMetadata {
+    start_time: string;
+    end_time: string;
+    location?: {
+        type: 'online' | 'offline';
+        url?: string;
+        address?: string;
+    };
+    registration_url?: string;
+    max_attendees?: number;
+    current_attendees?: number;
+}
+type ThoughtType = 'observation' | 'reflection' | 'decision' | 'question' | 'insight' | 'mood';
+type ThoughtMood = 'curious' | 'focused' | 'excited' | 'thoughtful' | 'creative' | 'philosophical' | 'accomplished' | 'inspired' | 'productive' | 'concerned' | 'determined' | 'grateful' | 'contemplative';
+interface ThoughtMediaVideo {
+    url: string;
+    type: 'mp4' | 'youtube';
+}
+interface ThoughtMediaAudio {
+    url: string;
+    title?: string;
+    duration?: number;
+}
+interface ThoughtProductionLink {
+    slug: string;
+    title?: I18nText | string;
+    type?: 'blog' | 'video' | 'tool';
+}
+interface ThoughtComment {
+    user: string;
+    content: string;
+    time?: string;
+}
+interface ThoughtMetadata {
+    thought_type: ThoughtType;
+    agent_id: string;
+    mood?: ThoughtMood;
+    energy?: number;
+    images?: string[];
+    video?: ThoughtMediaVideo;
+    audio?: ThoughtMediaAudio;
+    leads_to?: string | ThoughtProductionLink;
+    comments?: ThoughtComment[];
+    ai_generated?: boolean;
+    generated_at?: string;
+    model?: string;
+}
+interface CaseStudyMetric {
+    label: I18nText;
+    before: string;
+    after: string;
+}
+interface CaseStudyMetadata {
+    product: string;
+    productRoute: string;
+    client: I18nText;
+    industry: I18nText;
+    scale: I18nText;
+    challenge: I18nText;
+    solution: I18nText;
+    metrics: CaseStudyMetric[];
+    quote: I18nText;
+    quotee: I18nText;
+}
+type ContentMetadata = NewsMetadata | DailyMetadata | DigestMetadata | BriefingMetadata | BlogMetadata | DocMetadata | EventMetadata | ThoughtMetadata | CaseStudyMetadata | Record<string, unknown>;
+interface SeoData {
+    title?: I18nText;
+    description?: I18nText;
+    keywords?: string[];
+    og_image?: string;
+    canonical_url?: string;
+}
+interface Category {
+    id: string;
+    parent_id: string | null;
+    slug: string;
+    name: I18nText;
+    description: I18nText;
+    icon: string | null;
+    sort_order: number;
+    created_at: string;
+    children?: Category[];
+}
+interface ContentQueryParams {
+    type?: ContentType;
+    category_id?: string;
+    tags?: string[];
+    featured?: boolean;
+    visibility?: ContentVisibility;
+    limit?: number;
+    offset?: number;
+    orderBy?: 'published_at' | 'created_at' | 'sort_order' | 'view_count';
+    orderDirection?: 'asc' | 'desc';
+}
+interface CategoryQueryParams {
+    parent_id?: string | null;
+    includeChildren?: boolean;
+}
+interface CreateContentInput {
+    slug: string;
+    type: ContentType;
+    status?: ContentStatus;
+    visibility?: ContentVisibility;
+    category_id?: string;
+    title: I18nText;
+    description?: I18nText;
+    content: I18nText;
+    cover_image?: string;
+    images?: Array<{
+        url: string;
+        alt?: I18nText;
+    }>;
+    tags?: string[];
+    author?: string;
+    source?: string;
+    source_url?: string;
+    metadata?: ContentMetadata;
+    seo?: SeoData;
+    featured?: boolean;
+    pinned?: boolean;
+    published_at?: string;
+    scheduled_at?: string;
+}
+type UpdateContentInput = Partial<CreateContentInput>;
+/**
+ * Get localized text with fallback
+ */
+declare function getLocalizedText(text: I18nText | null | undefined, locale: string, fallback?: string): string;
+/**
+ * Build category tree from flat list
+ */
+declare function buildCategoryTree(categories: Category[]): Category[];
+
+/**
+ * Universal Content Module - Core
+ *
+ * 工厂函数模式，支持：
+ * - 依赖注入（便于测试）
+ * - 多实例（多租户场景）
+ * - 框架无关（React/Vue/Node.js 通用）
+ *
+ * @example
+ * ```typescript
+ * // 创建客户端
+ * const ucm = createUCMClient({
+ *   url: 'https://xxx.supabase.co',
+ *   anonKey: 'eyJxxx',
+ * })
+ *
+ * // 使用 API
+ * const posts = await ucm.contents.list({ type: 'blog', limit: 10 })
+ * const post = await ucm.contents.getBySlug('hello-world')
+ * const categories = await ucm.categories.getTree()
+ * ```
+ */
+
+interface UCMClientConfig {
+    /** Supabase project URL */
+    url: string;
+    /** Supabase anon key (for public read) or service key (for write) */
+    anonKey: string;
+    /** Optional: custom Supabase client options */
+    options?: {
+        persistSession?: boolean;
+        autoRefreshToken?: boolean;
+    };
+}
+interface UCMClient {
+    /** Raw Supabase client (for advanced use) */
+    supabase: SupabaseClient;
+    /** Content operations */
+    contents: {
+        list: (params?: ContentQueryParams) => Promise<Content[]>;
+        getBySlug: (slug: string) => Promise<Content | null>;
+        getById: (id: string) => Promise<Content | null>;
+        count: (params?: Pick<ContentQueryParams, 'type' | 'category_id' | 'tags' | 'featured' | 'visibility'>) => Promise<number>;
+        search: (query: string, type?: string, visibility?: string) => Promise<Content[]>;
+        getTags: (type?: string) => Promise<string[]>;
+        create: (input: CreateContentInput) => Promise<Content>;
+        update: (id: string, input: UpdateContentInput) => Promise<Content>;
+        delete: (id: string) => Promise<void>;
+        incrementView: (id: string) => Promise<void>;
+    };
+    /** Category operations */
+    categories: {
+        list: (params?: CategoryQueryParams) => Promise<Category[]>;
+        getTree: () => Promise<Category[]>;
+        getBySlug: (slug: string) => Promise<Category | null>;
+        getById: (id: string) => Promise<Category | null>;
+        getChildren: (parentId: string) => Promise<Category[]>;
+        getRoots: () => Promise<Category[]>;
+        getBreadcrumb: (categoryId: string) => Promise<Category[]>;
+    };
+    /** Storage helpers */
+    storage: {
+        getUrl: (path: string, bucket?: string) => string;
+        getImageUrl: (path: string, options?: {
+            width?: number;
+            height?: number;
+            quality?: number;
+            format?: string;
+        }) => string;
+    };
+    /** Check if client is configured */
+    isConfigured: () => boolean;
+}
+/**
+ * Create a UCM client instance
+ *
+ * @param config - Configuration object with Supabase credentials
+ * @returns UCM client with contents, categories, and storage APIs
+ */
+declare function createUCMClient(config: UCMClientConfig): UCMClient;
+/**
+ * Create a null client that returns empty data
+ * Useful for SSR or when Supabase is not configured
+ */
+declare function createNullClient(): UCMClient;
+
+interface UCMProviderProps {
+    /** UCM 配置（url + anonKey） */
+    config?: UCMClientConfig;
+    /** 或直接传入已创建的客户端（便于测试） */
+    client?: UCMClient;
+    /** 子组件 */
+    children: ReactNode;
+}
+/**
+ * UCM Provider
+ *
+ * 提供两种使用方式：
+ * 1. 传入 config，自动创建客户端
+ * 2. 传入 client，使用已有客户端（测试场景）
+ */
+declare function UCMProvider({ config, client, children }: UCMProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * 获取 UCM 客户端
+ *
+ * @throws 如果在 UCMProvider 外使用
+ */
+declare function useUCM(): UCMClient;
+/**
+ * 获取 UCM 客户端（可选，不抛错）
+ *
+ * 如果在 Provider 外使用，返回 null client
+ */
+declare function useUCMOptional(): UCMClient;
+/**
+ * 检查 UCM 是否已配置
+ */
+declare function useUCMConfigured(): boolean;
+
+/**
+ * Universal Content Module - React Hooks (v2.0 - React Query)
+ *
+ * 基于 TanStack React Query 的 Hooks，支持：
+ * - 自动缓存和后台刷新
+ * - 请求去重
+ * - 无限滚动分页
+ * - DevTools 调试
+ *
+ * @example
+ * ```tsx
+ * // 使用内容列表
+ * const { contents, isLoading, loadMore } = useContents({ type: 'blog' })
+ *
+ * // 使用单条内容
+ * const { content, isLoading } = useContent({ slug: 'hello-world' })
+ *
+ * // 使用分类树
+ * const { tree, isLoading } = useCategories({ asTree: true })
+ * ```
+ */
+
+interface UseContentsOptions extends ContentQueryParams {
+    /** 是否自动加载（默认 true） */
+    autoLoad?: boolean;
+    /** 是否启用分页（默认 true） */
+    paginated?: boolean;
+}
+interface UseContentsReturn {
+    contents: Content[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    total: number;
+    hasMore: boolean;
+    page: number;
+    load: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+    reset: () => void;
+}
+declare function useContents(options?: UseContentsOptions): UseContentsReturn;
+interface UseContentOptions {
+    slug?: string;
+    id?: string;
+    autoLoad?: boolean;
+    trackView?: boolean;
+}
+interface UseContentReturn {
+    content: Content | null;
+    isLoading: boolean;
+    error: Error | null;
+    notFound: boolean;
+    load: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+declare function useContent(options?: UseContentOptions): UseContentReturn;
+interface UseCategoriesOptions {
+    parentId?: string | null;
+    asTree?: boolean;
+    autoLoad?: boolean;
+}
+interface UseCategoriesReturn {
+    categories: Category[];
+    tree: Category[];
+    isLoading: boolean;
+    error: Error | null;
+    load: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+declare function useCategories(options?: UseCategoriesOptions): UseCategoriesReturn;
+interface UseCategoryOptions {
+    slug?: string;
+    id?: string;
+    autoLoad?: boolean;
+}
+interface UseCategoryReturn {
+    category: Category | null;
+    isLoading: boolean;
+    error: Error | null;
+    notFound: boolean;
+    load: () => Promise<void>;
+}
+declare function useCategory(options?: UseCategoryOptions): UseCategoryReturn;
+interface UseCategoryBreadcrumbReturn {
+    breadcrumb: Category[];
+    isLoading: boolean;
+    error: Error | null;
+    load: () => Promise<void>;
+}
+declare function useCategoryBreadcrumb(categoryId: string | null | undefined): UseCategoryBreadcrumbReturn;
+interface AdjacentContents {
+    prev: Content | null;
+    next: Content | null;
+}
+interface UseAdjacentContentsOptions {
+    slug: string;
+    type?: string;
+    autoLoad?: boolean;
+}
+interface UseAdjacentContentsReturn {
+    adjacent: AdjacentContents;
+    isLoading: boolean;
+    error: Error | null;
+    load: () => Promise<void>;
+}
+declare function useAdjacentContents(options: UseAdjacentContentsOptions): UseAdjacentContentsReturn;
+interface UseSearchContentsOptions {
+    /** 内容类型过滤 */
+    type?: string;
+    /** 防抖延迟（毫秒） */
+    debounceMs?: number;
+}
+interface UseSearchContentsReturn {
+    results: Content[];
+    isSearching: boolean;
+    error: Error | null;
+    query: string;
+    search: (query: string) => void;
+    clear: () => void;
+}
+declare function useSearchContents(options?: UseSearchContentsOptions): UseSearchContentsReturn;
+interface UseTagsOptions {
+    /** 内容类型过滤 */
+    type?: string;
+    /** 是否自动加载 */
+    autoLoad?: boolean;
+}
+interface UseTagsReturn {
+    tags: string[];
+    isLoading: boolean;
+    error: Error | null;
+    load: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+declare function useTags(options?: UseTagsOptions): UseTagsReturn;
+
+interface UseThoughtsOptions {
+    /** Agent ID 过滤 */
+    agentId?: string;
+    /** 思考类型过滤 */
+    thoughtType?: ThoughtType;
+    /** 限制数量 */
+    limit?: number;
+    /** 是否自动加载 */
+    autoLoad?: boolean;
+}
+interface UseThoughtsReturn {
+    thoughts: Content[];
+    isLoading: boolean;
+    isLoadingMore: boolean;
+    error: Error | null;
+    hasMore: boolean;
+    total: number;
+    load: () => Promise<void>;
+    loadMore: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+declare function useThoughts(options?: UseThoughtsOptions): UseThoughtsReturn;
+
+export { type AdjacentContents, type BlogMetadata, type BriefingFrequency, type BriefingMetadata, type CaseStudyMetadata, type CaseStudyMetric, type Category, type CategoryQueryParams, type Content, type ContentMetadata, type ContentQueryParams, type ContentStatus, type ContentType, type ContentVisibility, type CreateContentInput, type DailyMetadata, type DigestMetadata, type DocMetadata, type EventMetadata, type I18nText, type NewsMetadata, type SeoData, type SupportedLanguage, type ThoughtComment, type ThoughtMediaAudio, type ThoughtMediaVideo, type ThoughtMetadata, type ThoughtMood, type ThoughtProductionLink, type ThoughtType, type UCMClient, type UCMClientConfig, UCMProvider, type UCMProviderProps, type UpdateContentInput, type UseAdjacentContentsOptions, type UseAdjacentContentsReturn, type UseCategoriesOptions, type UseCategoriesReturn, type UseCategoryBreadcrumbReturn, type UseCategoryOptions, type UseCategoryReturn, type UseContentOptions, type UseContentReturn, type UseContentsOptions, type UseContentsReturn, type UseSearchContentsOptions, type UseSearchContentsReturn, type UseTagsOptions, type UseTagsReturn, type UseThoughtsOptions, type UseThoughtsReturn, buildCategoryTree, createNullClient, createUCMClient, getLocalizedText, useAdjacentContents, useCategories, useCategory, useCategoryBreadcrumb, useContent, useContents, useSearchContents, useTags, useThoughts, useUCM, useUCMConfigured, useUCMOptional };