convex-cms 0.0.1

package/dist/component/lib/mutationAuth.js

@@ -0,0 +1,146 @@
+/**
+ * Mutation-Level Authorization Helper
+ *
+ * Provides defense-in-depth authorization for component mutations.
+ * When auth context is provided, mutations verify the role has permission.
+ *
+ * This complements the client wrapper's authorization:
+ * - Client wrapper: Primary authorization layer (runs hooks, RBAC)
+ * - Mutation auth: Secondary validation layer (pure RBAC check)
+ *
+ * @example
+ * ```typescript
+ * import { requireMutationAuth } from "./lib/mutationAuth.js";
+ *
+ * export const createEntry = mutation({
+ *   args: {
+ *     ...createContentEntryArgs.fields,
+ *     _auth: v.optional(mutationAuthContext),
+ *   },
+ *   handler: async (ctx, args) => {
+ *     requireMutationAuth(args._auth, "contentEntries", "create");
+ *     // ... mutation logic
+ *   },
+ * });
+ * ```
+ */
+import { hasPermission } from "../roles.js";
+import { permissionDenied } from "./errors.js";
+/**
+ * Verify the auth context has permission for the requested operation.
+ *
+ * This function:
+ * 1. If `_auth` is undefined, does nothing (backwards compatible)
+ * 2. If `_auth` is provided, checks the role has permission
+ * 3. Throws CMSError with PERMISSION_DENIED if check fails
+ *
+ * For ownership-scoped permissions (e.g., author editing their own content):
+ * - If the role only has "own" scope, verifies resourceOwnerId matches userId
+ * - If the role has "all" scope, ownership is not checked
+ *
+ * @param auth - The auth context from mutation args (may be undefined)
+ * @param resource - The resource being accessed (e.g., "contentEntries")
+ * @param action - The action being performed (e.g., "create", "update")
+ * @param options - Optional configuration including custom roles
+ * @throws CMSError with code PERMISSION_DENIED if authorization fails
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - check if role can create content entries
+ * requireMutationAuth(args._auth, "contentEntries", "create");
+ *
+ * // For update/delete - include resource owner for "own" scope check
+ * const entry = await ctx.db.get(args.id);
+ * requireMutationAuth(
+ *   { ...args._auth, resourceOwnerId: entry.createdBy },
+ *   "contentEntries",
+ *   "update"
+ * );
+ * ```
+ */
+export function requireMutationAuth(auth, resource, action, options) {
+    // If no auth context provided, skip authorization (backwards compatible)
+    // Security note: Caller is responsible for ensuring authorization was done elsewhere
+    if (!auth) {
+        return;
+    }
+    const { userId, role, resourceOwnerId } = auth;
+    // No role means no permissions
+    if (!role) {
+        throw permissionDenied(action, resource);
+    }
+    // Check if role has "all" scope permission
+    const hasAllScope = hasPermission(role, { resource, action, scope: "all" }, options?.customRoles);
+    if (hasAllScope) {
+        return; // Authorized with "all" scope
+    }
+    // Check if role has "own" scope permission
+    const hasOwnScope = hasPermission(role, { resource, action, scope: "own" }, options?.customRoles);
+    if (hasOwnScope) {
+        // "own" scope requires ownership verification
+        if (resourceOwnerId && resourceOwnerId === userId) {
+            return; // Authorized - user owns the resource
+        }
+        // For create operations, ownership is always satisfied (user will own it)
+        if (action === "create") {
+            return; // Authorized - creating own resource
+        }
+        // Ownership check failed
+        throw permissionDenied(`${action} other users'`, resource);
+    }
+    // No permission found
+    throw permissionDenied(action, resource);
+}
+/**
+ * Check if auth context has permission without throwing.
+ *
+ * Useful for conditional logic based on permissions.
+ *
+ * @param auth - The auth context from mutation args
+ * @param resource - The resource being accessed
+ * @param action - The action being performed
+ * @param options - Optional configuration including custom roles
+ * @returns true if authorized, false otherwise
+ */
+export function hasMutationAuth(auth, resource, action, options) {
+    if (!auth) {
+        return true; // No auth = no restriction (backwards compatible)
+    }
+    const { userId, role, resourceOwnerId } = auth;
+    if (!role) {
+        return false;
+    }
+    // Check "all" scope first
+    if (hasPermission(role, { resource, action, scope: "all" }, options?.customRoles)) {
+        return true;
+    }
+    // Check "own" scope
+    if (hasPermission(role, { resource, action, scope: "own" }, options?.customRoles)) {
+        // For "own" scope, verify ownership or it's a create action
+        if (action === "create") {
+            return true;
+        }
+        if (resourceOwnerId && resourceOwnerId === userId) {
+            return true;
+        }
+        return false;
+    }
+    return false;
+}
+/**
+ * Augment auth context with resource owner information.
+ *
+ * Use this when you have an auth context and need to add ownership info
+ * for permission checks on existing resources.
+ *
+ * @param auth - The original auth context
+ * @param resourceOwnerId - The owner of the resource being accessed
+ * @returns Auth context with resourceOwnerId set
+ */
+export function withResourceOwner(auth, resourceOwnerId) {
+    if (!auth) {
+        return undefined;
+    }
+    return { ...auth, resourceOwnerId };
+}
+//# sourceMappingURL=mutationAuth.js.map

package/dist/component/lib/mutationAuth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutationAuth.js","sourceRoot":"","sources":["../../../src/component/lib/mutationAuth.ts"],"names":[],"mappings":"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"}

package/dist/component/lib/queries.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Common query helpers for the CMS component.
+ *
+ * Provides reusable query patterns for looking up documents by name,
+ * ID, or other common patterns with soft-delete awareness.
+ */
+import type { QueryCtx } from "../_generated/server.js";
+import type { Id, Doc, TableNames } from "../_generated/dataModel.js";
+export interface GetByIdOptions {
+    includeDeleted?: boolean;
+}
+export declare function getContentTypeByName(ctx: QueryCtx, name: string, options?: GetByIdOptions): Promise<Doc<"contentTypes"> | null>;
+export declare function getTaxonomyByName(ctx: QueryCtx, name: string, options?: GetByIdOptions): Promise<Doc<"taxonomies"> | null>;
+export declare function contentTypeExists(ctx: QueryCtx, name: string, options?: GetByIdOptions): Promise<boolean>;
+export declare function taxonomyExists(ctx: QueryCtx, name: string, options?: GetByIdOptions): Promise<boolean>;
+export declare function getActiveById<T extends TableNames>(ctx: QueryCtx, id: Id<T>, options?: GetByIdOptions): Promise<Doc<T> | null>;
+//# sourceMappingURL=queries.d.ts.map

package/dist/component/lib/queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/lib/queries.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAGtE,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,CASrC;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CASnC;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wBAAsB,aAAa,CAAC,CAAC,SAAS,UAAU,EACtD,GAAG,EAAE,QAAQ,EACb,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EACT,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAWxB"}

package/dist/component/lib/queries.js

@@ -0,0 +1,49 @@
+/**
+ * Common query helpers for the CMS component.
+ *
+ * Provides reusable query patterns for looking up documents by name,
+ * ID, or other common patterns with soft-delete awareness.
+ */
+import { isDeleted } from "./softDelete.js";
+export async function getContentTypeByName(ctx, name, options = {}) {
+    const contentType = await ctx.db
+        .query("contentTypes")
+        .withIndex("by_name", (q) => q.eq("name", name))
+        .first();
+    if (!contentType)
+        return null;
+    if (!options.includeDeleted && isDeleted(contentType))
+        return null;
+    return contentType;
+}
+export async function getTaxonomyByName(ctx, name, options = {}) {
+    const taxonomy = await ctx.db
+        .query("taxonomies")
+        .withIndex("by_name", (q) => q.eq("name", name))
+        .first();
+    if (!taxonomy)
+        return null;
+    if (!options.includeDeleted && isDeleted(taxonomy))
+        return null;
+    return taxonomy;
+}
+export async function contentTypeExists(ctx, name, options = {}) {
+    const contentType = await getContentTypeByName(ctx, name, options);
+    return contentType !== null;
+}
+export async function taxonomyExists(ctx, name, options = {}) {
+    const taxonomy = await getTaxonomyByName(ctx, name, options);
+    return taxonomy !== null;
+}
+export async function getActiveById(ctx, id, options = {}) {
+    const doc = await ctx.db.get(id);
+    if (!doc)
+        return null;
+    if (!options.includeDeleted &&
+        "deletedAt" in doc &&
+        doc.deletedAt !== undefined) {
+        return null;
+    }
+    return doc;
+}
+//# sourceMappingURL=queries.js.map

package/dist/component/lib/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../../src/component/lib/queries.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM5C,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAa,EACb,IAAY,EACZ,UAA0B,EAAE;IAE5B,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,EAAE;SAC7B,KAAK,CAAC,cAAc,CAAC;SACrB,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;SAC/C,KAAK,EAAE,CAAC;IAEX,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,SAAS,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC;IACnE,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAa,EACb,IAAY,EACZ,UAA0B,EAAE;IAE5B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,EAAE;SAC1B,KAAK,CAAC,YAAY,CAAC;SACnB,SAAS,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;SAC/C,KAAK,EAAE,CAAC;IAEX,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,GAAa,EACb,IAAY,EACZ,UAA0B,EAAE;IAE5B,MAAM,WAAW,GAAG,MAAM,oBAAoB,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACnE,OAAO,WAAW,KAAK,IAAI,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAa,EACb,IAAY,EACZ,UAA0B,EAAE;IAE5B,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7D,OAAO,QAAQ,KAAK,IAAI,CAAC;AAC3B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,GAAa,EACb,EAAS,EACT,UAA0B,EAAE;IAE5B,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,IACE,CAAC,OAAO,CAAC,cAAc;QACvB,WAAW,IAAI,GAAG;QACjB,GAA8B,CAAC,SAAS,KAAK,SAAS,EACvD,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/component/lib/ragContentChunker.d.ts

@@ -0,0 +1,423 @@
+/**
+ * RAG Content Chunker
+ *
+ * Utility to extract and structure content from CMS entries for @convex-dev/rag indexing.
+ * This module provides:
+ *
+ * 1. **Content Extraction**: Extracts text from various CMS field types (text, richText, json, etc.)
+ * 2. **Semantic Chunking**: Splits content into meaningful chunks optimized for embedding
+ * 3. **Metadata Tagging**: Attaches relevant metadata (content type, field source, locale, etc.)
+ * 4. **Reference Handling**: Processes embedded references and includes contextual information
+ *
+ * The output is designed to be directly compatible with @convex-dev/rag's `add()` function.
+ *
+ * @example
+ * ```typescript
+ * import { extractContentForRag, chunkContentEntry } from "@convex-cms/core/lib";
+ * import { rag } from "@convex-dev/rag";
+ *
+ * // In a Convex action
+ * const chunks = await chunkContentEntry(ctx, entry, contentType, {
+ *   includeMetadata: true,
+ *   chunkOptions: { maxCharsSoftLimit: 1000 },
+ * });
+ *
+ * await rag.add(ctx, {
+ *   namespace: "cms-content",
+ *   key: entry._id,
+ *   chunks: chunks.map(c => c.text),
+ *   title: chunks[0]?.metadata?.title,
+ * });
+ * ```
+ *
+ * @module
+ */
+/**
+ * Field definition structure from the CMS schema.
+ */
+export interface FieldDefinition {
+    name: string;
+    label: string;
+    type: string;
+    required: boolean;
+    searchable?: boolean;
+    localized?: boolean;
+    description?: string;
+    options?: {
+        allowedContentTypes?: string[];
+        multiple?: boolean;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Content type structure from the CMS.
+ */
+export interface ContentTypeInfo {
+    _id: string;
+    name: string;
+    displayName: string;
+    fields: FieldDefinition[];
+    titleField?: string;
+    slugField?: string;
+}
+/**
+ * Content entry structure from the CMS.
+ */
+export interface ContentEntryInfo {
+    _id: string;
+    contentTypeId: string;
+    slug: string;
+    status: string;
+    data: Record<string, unknown>;
+    locale?: string;
+    version: number;
+    _creationTime: number;
+    firstPublishedAt?: number;
+    lastPublishedAt?: number;
+}
+/**
+ * A resolved reference for context enrichment.
+ */
+export interface ResolvedReferenceInfo {
+    id: string;
+    contentTypeName: string;
+    title?: string;
+    slug?: string;
+}
+/**
+ * Metadata attached to each content chunk.
+ * This metadata helps with filtering and relevance scoring during retrieval.
+ */
+export interface ChunkMetadata {
+    /** The content entry ID this chunk came from */
+    entryId: string;
+    /** The content type name (e.g., "blog_post") */
+    contentType: string;
+    /** The content type display name (e.g., "Blog Post") */
+    contentTypeDisplayName: string;
+    /** The entry's URL slug */
+    slug: string;
+    /** Publishing status of the entry */
+    status: string;
+    /** Locale code if localized content */
+    locale?: string;
+    /** The field name(s) this chunk was extracted from */
+    sourceFields: string[];
+    /** The chunk index within the entry (0-based) */
+    chunkIndex: number;
+    /** Total number of chunks for this entry */
+    totalChunks: number;
+    /** The entry's title (if available) */
+    title?: string;
+    /** ISO timestamp when the entry was created */
+    createdAt: string;
+    /** ISO timestamp when the entry was first published */
+    firstPublishedAt?: string;
+    /** ISO timestamp when the entry was last published */
+    lastPublishedAt?: string;
+    /** Version number of the entry */
+    version: number;
+    /** IDs of referenced content entries (for relationship tracking) */
+    referencedEntryIds?: string[];
+    /** IDs of referenced media assets */
+    referencedMediaIds?: string[];
+    /** Semantic type of the chunk (heading, paragraph, list, etc.) */
+    semanticType?: ChunkSemanticType;
+}
+/**
+ * Semantic type classification for chunks.
+ * Helps with relevance scoring and filtering.
+ */
+export type ChunkSemanticType = "title" | "heading" | "paragraph" | "list" | "quote" | "code" | "table" | "mixed" | "field_value";
+/**
+ * A single content chunk ready for RAG indexing.
+ */
+export interface ContentChunk {
+    /** The text content of the chunk */
+    text: string;
+    /** Metadata for filtering and context */
+    metadata: ChunkMetadata;
+    /** Optional custom embedding text (if different from display text) */
+    embeddingText?: string;
+}
+/**
+ * Options for the chunking algorithm.
+ */
+export interface ChunkOptions {
+    /**
+     * Minimum number of lines before creating a chunk.
+     * Helps avoid very small chunks.
+     * @default 1
+     */
+    minLines?: number;
+    /**
+     * Soft minimum character limit for chunks.
+     * Chunker will try to create chunks at least this size.
+     * @default 100
+     */
+    minCharsSoftLimit?: number;
+    /**
+     * Soft maximum character limit for chunks.
+     * Chunker will try to split at natural boundaries before this limit.
+     * @default 1000
+     */
+    maxCharsSoftLimit?: number;
+    /**
+     * Hard maximum character limit for chunks.
+     * Chunks will be force-split at this limit.
+     * @default 4000
+     */
+    maxCharsHardLimit?: number;
+    /**
+     * Primary delimiter for splitting text into chunks.
+     * @default "\n\n" (paragraph breaks)
+     */
+    delimiter?: string;
+    /**
+     * Secondary delimiters to try when primary doesn't work.
+     * @default ["\n", ". ", ", "]
+     */
+    fallbackDelimiters?: string[];
+    /**
+     * Whether to preserve heading context in each chunk.
+     * When true, includes the most recent heading at the start of each chunk.
+     * @default true
+     */
+    preserveHeadingContext?: boolean;
+    /**
+     * Overlap characters between chunks for context continuity.
+     * @default 50
+     */
+    overlapChars?: number;
+}
+/**
+ * Options for content extraction and chunking.
+ */
+export interface RagExtractionOptions {
+    /**
+     * Whether to include metadata with each chunk.
+     * @default true
+     */
+    includeMetadata?: boolean;
+    /**
+     * Field names to include in extraction.
+     * If not specified, all text-bearing fields are included.
+     */
+    includeFields?: string[];
+    /**
+     * Field names to exclude from extraction.
+     */
+    excludeFields?: string[];
+    /**
+     * Whether to extract text from rich text fields.
+     * @default true
+     */
+    extractRichText?: boolean;
+    /**
+     * Whether to extract text from JSON fields.
+     * @default true
+     */
+    extractJson?: boolean;
+    /**
+     * Whether to include reference context (titles of referenced entries).
+     * Requires passing resolved references.
+     * @default true
+     */
+    includeReferenceContext?: boolean;
+    /**
+     * Chunking algorithm options.
+     */
+    chunkOptions?: ChunkOptions;
+    /**
+     * Custom prefix for each chunk (e.g., for entry context).
+     * Supports placeholders: {contentType}, {title}, {slug}
+     */
+    chunkPrefix?: string;
+    /**
+     * Custom suffix for each chunk.
+     */
+    chunkSuffix?: string;
+    /**
+     * Whether to create a separate "summary" chunk with key fields.
+     * @default false
+     */
+    createSummaryChunk?: boolean;
+    /**
+     * Fields to include in the summary chunk.
+     * @default ["title", first searchable field]
+     */
+    summaryFields?: string[];
+}
+/**
+ * Result of content extraction before chunking.
+ */
+export interface ExtractedContent {
+    /** Combined text content from all fields */
+    fullText: string;
+    /** Text content organized by field name */
+    fieldTexts: Record<string, string>;
+    /** Entry title (if available) */
+    title?: string;
+    /** Referenced entry IDs found in content */
+    referencedEntryIds: string[];
+    /** Referenced media IDs found in content */
+    referencedMediaIds: string[];
+    /** Source field information for tracking */
+    sourceInfo: Array<{
+        fieldName: string;
+        fieldLabel: string;
+        fieldType: string;
+        charCount: number;
+    }>;
+}
+declare const DEFAULT_CHUNK_OPTIONS: Required<ChunkOptions>;
+declare const DEFAULT_EXTRACTION_OPTIONS: Required<RagExtractionOptions>;
+/**
+ * Extracts plain text from a rich text field value.
+ *
+ * Handles common rich text formats:
+ * - HTML strings (strips tags)
+ * - ProseMirror/Tiptap JSON structure
+ * - Markdown strings
+ * - Plain text strings
+ *
+ * @param value - The rich text field value
+ * @returns Plain text content
+ */
+export declare function extractTextFromRichText(value: unknown): string;
+/**
+ * Strips HTML tags from a string, preserving structure where possible.
+ */
+export declare function stripHtmlTags(html: string): string;
+/**
+ * Extracts text from a JSON field value.
+ *
+ * Recursively extracts string values from objects and arrays.
+ * Useful for structured data fields that may contain text content.
+ *
+ * @param value - The JSON field value
+ * @param maxDepth - Maximum recursion depth
+ * @returns Extracted text content
+ */
+export declare function extractTextFromJson(value: unknown, maxDepth?: number): string;
+/**
+ * Extracts text from a select or multiSelect field value.
+ */
+export declare function extractTextFromSelect(value: unknown): string;
+/**
+ * Extracts text content from a content entry based on its content type schema.
+ *
+ * This function:
+ * 1. Iterates through fields defined in the content type
+ * 2. Extracts text from each field based on its type
+ * 3. Tracks references (content and media)
+ * 4. Builds a combined text representation
+ *
+ * @param entry - The content entry to extract from
+ * @param contentType - The content type definition
+ * @param options - Extraction options
+ * @param resolvedReferences - Optional map of resolved reference information
+ * @returns Extracted content with metadata
+ *
+ * @example
+ * ```typescript
+ * const extracted = extractContent(entry, contentType, {
+ *   includeFields: ["title", "content", "excerpt"],
+ *   extractRichText: true,
+ * });
+ *
+ * console.log(extracted.fullText);
+ * // "My Blog Post\n\nThis is the main content...\n\nA brief excerpt."
+ * ```
+ */
+export declare function extractContent(entry: ContentEntryInfo, contentType: ContentTypeInfo, options?: Partial<RagExtractionOptions>, resolvedReferences?: Map<string, ResolvedReferenceInfo>): ExtractedContent;
+/**
+ * Splits text into semantic chunks optimized for embedding.
+ *
+ * The algorithm:
+ * 1. First tries to split on paragraph breaks (default delimiter)
+ * 2. Falls back to line breaks if paragraphs are too large
+ * 3. Falls back to sentence boundaries if lines are too large
+ * 4. Force-splits at hard limit if necessary
+ * 5. Optionally preserves heading context
+ *
+ * @param text - The text to chunk
+ * @param options - Chunking options
+ * @returns Array of text chunks
+ *
+ * @example
+ * ```typescript
+ * const chunks = chunkText(longArticle, {
+ *   maxCharsSoftLimit: 1000,
+ *   preserveHeadingContext: true,
+ * });
+ * ```
+ */
+export declare function chunkText(text: string, options?: Partial<ChunkOptions>): string[];
+/**
+ * Processes a content entry into chunks ready for RAG indexing.
+ *
+ * This is the main function to use for preparing CMS content for @convex-dev/rag.
+ * It combines extraction and chunking with full metadata.
+ *
+ * @param entry - The content entry to process
+ * @param contentType - The content type definition
+ * @param options - Extraction and chunking options
+ * @param resolvedReferences - Optional map of resolved references for context
+ * @returns Array of content chunks with metadata
+ *
+ * @example
+ * ```typescript
+ * // In a Convex action
+ * export const indexEntry = action({
+ *   args: { entryId: v.id("contentEntries") },
+ *   handler: async (ctx, { entryId }) => {
+ *     const entry = await ctx.runQuery(api.contentEntries.get, { id: entryId });
+ *     const contentType = await ctx.runQuery(api.contentTypes.get, {
+ *       id: entry.contentTypeId
+ *     });
+ *
+ *     const chunks = chunkContentEntry(entry, contentType, {
+ *       chunkOptions: { maxCharsSoftLimit: 800 },
+ *       includeMetadata: true,
+ *     });
+ *
+ *     // Add to RAG index
+ *     await rag.add(ctx, {
+ *       namespace: `cms:${contentType.name}`,
+ *       key: entryId,
+ *       chunks: chunks.map(c => c.text),
+ *       title: entry.data.title,
+ *     });
+ *
+ *     return { indexed: chunks.length };
+ *   },
+ * });
+ * ```
+ */
+export declare function chunkContentEntry(entry: ContentEntryInfo, contentType: ContentTypeInfo, options?: Partial<RagExtractionOptions>, resolvedReferences?: Map<string, ResolvedReferenceInfo>): ContentChunk[];
+/**
+ * Processes multiple content entries into chunks.
+ *
+ * Useful for batch indexing operations.
+ *
+ * @param entries - Array of content entries
+ * @param contentTypes - Map of content type ID to content type
+ * @param options - Extraction options
+ * @returns Map of entry ID to chunks
+ */
+export declare function chunkMultipleEntries(entries: ContentEntryInfo[], contentTypes: Map<string, ContentTypeInfo>, options?: Partial<RagExtractionOptions>): Map<string, ContentChunk[]>;
+/**
+ * Calculates the total character count and chunk count for entries.
+ *
+ * Useful for estimating indexing costs.
+ */
+export declare function estimateChunkingStats(entries: ContentEntryInfo[], contentTypes: Map<string, ContentTypeInfo>, options?: Partial<RagExtractionOptions>): {
+    totalEntries: number;
+    totalChunks: number;
+    totalCharacters: number;
+    averageChunksPerEntry: number;
+    averageCharsPerChunk: number;
+};
+export { DEFAULT_CHUNK_OPTIONS, DEFAULT_EXTRACTION_OPTIONS };
+//# sourceMappingURL=ragContentChunker.d.ts.map

package/dist/component/lib/ragContentChunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ragContentChunker.d.ts","sourceRoot":"","sources":["../../../src/component/lib/ragContentChunker.ts"],"names":[],"mappings":"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"}