@deepcitation/deepcitation-js 1.1.27 → 1.1.28

package/lib/client/index.d.ts

@@ -1,2 +1,342 @@
-export { DeepCitation } from "./DeepCitation.js";
-export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutput, ConvertFileInput, ConvertFileResponse, PrepareConvertedFileOptions, } from "./types.js";
+import { Citation, Verification } from '../types/index.js';
+
+/**
+ * Configuration options for the DeepCitation client
+ */
+interface DeepCitationConfig {
+    /** Your DeepCitation API key (starts with sk-dc-) */
+    apiKey: string;
+    /** Optional custom API base URL. Defaults to https://api.deepcitation.com */
+    apiUrl?: string;
+}
+/**
+ * Response from uploading a file for citation verification
+ */
+interface UploadFileResponse {
+    /** The attachment ID assigned by DeepCitation (custom or auto-generated) */
+    attachmentId: string;
+    /** The full text content formatted for LLM prompts with page markers and line IDs. Use this in your user prompts. */
+    deepTextPromptPortion: string;
+    /** Form fields extracted from PDF forms */
+    formFields?: Array<{
+        name: string;
+        value?: string;
+        pageIndex?: number;
+        type?: string;
+    }>;
+    /** Metadata about the processed file */
+    metadata: {
+        filename: string;
+        mimeType: string;
+        pageCount: number;
+        textByteSize: number;
+    };
+    /** Processing status */
+    status: "ready" | "error";
+    /** Time taken to process the file in milliseconds */
+    processingTimeMs?: number;
+    /** Error message if status is "error" */
+    error?: string;
+}
+/**
+ * Options for file upload
+ */
+interface UploadFileOptions {
+    /** Optional custom attachment ID to use instead of auto-generated one */
+    attachmentId?: string;
+    /** Optional custom filename (uses File.name if not provided) */
+    filename?: string;
+}
+/**
+ * Response from verifying citations
+ */
+interface VerifyCitationsResponse {
+    /** Map of citation keys to their verification results */
+    verifications: Record<string, Verification>;
+}
+/**
+ * Options for citation verification
+ */
+interface VerifyCitationsOptions {
+    /** Output image format for verification screenshots */
+    outputImageFormat?: "jpeg" | "png" | "avif";
+}
+/**
+ * Simplified citation input for verification
+ */
+type CitationInput = Citation | Record<string, Citation>;
+/**
+ * Input for file upload in prepareFiles
+ */
+interface FileInput {
+    /** The file content (File, Blob, or Buffer) */
+    file: File | Blob | Buffer;
+    /** Optional filename */
+    filename?: string;
+    /** Optional custom attachment ID */
+    attachmentId?: string;
+}
+/**
+ * File reference returned from prepareFiles
+ */
+interface FileDataPart {
+    /** The attachment ID assigned by DeepCitation */
+    attachmentId: string;
+    /** The formatted text content for LLM prompts (with page markers and line IDs) */
+    deepTextPromptPortion: string;
+    /** Optional filename for display purposes */
+    filename?: string;
+}
+/**
+ * Result from prepareFiles
+ */
+interface PrepareFilesResult {
+    /** Array of file references for verification (includes deepTextPromptPortion for each file) */
+    fileDataParts: FileDataPart[];
+    /**
+     * Array of formatted text content for LLM prompts (with page markers and line IDs).
+     * @deprecated Use fileDataParts[].deepTextPromptPortion instead for single source of truth.
+     * This is kept for backwards compatibility but will be removed in a future version.
+     */
+    deepTextPromptPortion: string[];
+}
+/**
+ * Input for verifyCitationsFromLlmOutput
+ */
+interface VerifyCitationsFromLlmOutput {
+    /** The LLM response containing citations */
+    llmOutput: string;
+    /** Optional file references (required for Zero Data Retention or after storage expires) */
+    fileDataParts?: FileDataPart[];
+    /** Output image format for verification screenshots */
+    outputImageFormat?: "jpeg" | "png" | "avif";
+}
+/**
+ * Input for convertFile - convert URL or Office file to PDF
+ */
+interface ConvertFileInput {
+    /** URL to convert to PDF (for web pages or direct PDF links) */
+    url?: string;
+    /** Office file to convert (doc, docx, xls, xlsx, ppt, pptx, odt, ods, odp) */
+    file?: File | Blob | Buffer;
+    /** Optional custom filename for the converted PDF */
+    filename?: string;
+    /** Optional custom attachment ID */
+    attachmentId?: string;
+}
+/**
+ * Response from convertFile
+ */
+interface ConvertFileResponse {
+    /** The attachment ID assigned by DeepCitation. Pass this to prepareConvertedFile(). */
+    attachmentId: string;
+    /** Metadata about the conversion */
+    metadata: {
+        /** Original filename before conversion */
+        originalFilename: string;
+        /** Original MIME type before conversion */
+        originalMimeType: string;
+        /** MIME type after conversion (always application/pdf) */
+        convertedMimeType: string;
+        /** Time taken for conversion in milliseconds */
+        conversionTimeMs: number;
+    };
+    /** Conversion status */
+    status: "converted" | "error";
+    /** Error message if status is "error" */
+    error?: string;
+}
+/**
+ * Options for processing a converted file
+ */
+interface PrepareConvertedFileOptions {
+    /** The attachment ID from a previous convertFile call */
+    attachmentId: string;
+}
+
+/**
+ * DeepCitation client for file upload and citation verification.
+ *
+ * @example
+ * ```typescript
+ * import { DeepCitation } from '@deepcitation/deepcitation-js';
+ *
+ * const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
+ *
+ * // Upload a file
+ * const { attachmentId, promptContent } = await dc.uploadFile(file);
+ *
+ * // Include promptContent in your LLM messages
+ * const response = await llm.chat({
+ *   messages: [
+ *     { role: "system", content: wrapSystemCitationPrompt({ systemPrompt }) },
+ *     { role: "user", content: userMessage + "\n\n" + promptContent },
+ *   ]
+ * });
+ *
+ * // Verify citations in the LLM output
+ * const citations = getAllCitationsFromLlmOutput(response);
+ * const verified = await dc.verifyCitations(attachmentId, citations);
+ * ```
+ */
+declare class DeepCitation {
+    private readonly apiKey;
+    private readonly apiUrl;
+    /**
+     * Create a new DeepCitation client instance.
+     *
+     * @param config - Configuration options
+     * @throws Error if apiKey is not provided
+     */
+    constructor(config: DeepCitationConfig);
+    /**
+     * Upload a file for citation verification.
+     *
+     * Supported file types:
+     * - PDF documents
+     * - Images (PNG, JPEG, WebP, AVIF, HEIC)
+     * - Coming soon: DOCX, XLSX, plain text
+     *
+     * @param file - The file to upload (File, Blob, or Buffer)
+     * @param options - Optional upload options
+     * @returns Upload response with attachmentId and extracted text
+     *
+     * @example
+     * ```typescript
+     * // Browser with File object
+     * const file = document.querySelector('input[type="file"]').files[0];
+     * const result = await dc.uploadFile(file);
+     *
+     * // Node.js with Buffer
+     * const buffer = fs.readFileSync('document.pdf');
+     * const result = await dc.uploadFile(buffer, { filename: 'document.pdf' });
+     * ```
+     */
+    uploadFile(file: File | Blob | Buffer, options?: UploadFileOptions): Promise<UploadFileResponse>;
+    /**
+     * Convert a URL or Office file to PDF for citation verification.
+     * The converted file can then be processed with prepareConvertedFile().
+     *
+     * Supported Office formats:
+     * - Microsoft Word (.doc, .docx)
+     * - Microsoft Excel (.xls, .xlsx)
+     * - Microsoft PowerPoint (.ppt, .pptx)
+     * - OpenDocument (.odt, .ods, .odp)
+     * - Rich Text Format (.rtf)
+     * - CSV (.csv)
+     *
+     * @param input - URL string or object with URL/file options
+     * @returns Conversion result with attachmentId for prepareConvertedFile
+     *
+     * @example
+     * ```typescript
+     * // Convert a URL to PDF
+     * const result = await dc.convertToPdf({ url: "https://example.com/article" });
+     *
+     * // Convert an Office document
+     * const result = await dc.convertToPdf({
+     *   file: docxBuffer,
+     *   filename: "report.docx"
+     * });
+     *
+     * // Then prepare the file for verification
+     * const { deepTextPromptPortion, attachmentId } = await dc.prepareConvertedFile({
+     *   attachmentId: result.attachmentId
+     * });
+     * ```
+     */
+    convertToPdf(input: ConvertFileInput | string): Promise<ConvertFileResponse>;
+    /**
+     * Prepare a previously converted file for citation verification.
+     * Use this after calling convertToPdf() to extract text and get deepTextPromptPortion.
+     *
+     * @param options - Options with attachmentId from convertFile
+     * @returns Upload response with attachmentId and extracted text
+     *
+     * @example
+     * ```typescript
+     * // First convert the file
+     * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
+     *
+     * // Then prepare it for verification
+     * const { deepTextPromptPortion, attachmentId } = await dc.prepareConvertedFile({
+     *   attachmentId: converted.attachmentId
+     * });
+     *
+     * // Use deepTextPromptPortion in your LLM prompt...
+     * ```
+     */
+    prepareConvertedFile(options: PrepareConvertedFileOptions): Promise<UploadFileResponse>;
+    /**
+     * Upload multiple files for citation verification and get structured content.
+     * This is the recommended way to prepare files for LLM prompts.
+     *
+     * @param files - Array of files to upload with optional filenames and attachmentIds
+     * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
+     *
+     * @example
+     * ```typescript
+     * const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
+     *   { file: pdfBuffer, filename: "report.pdf" },
+     *   { file: invoiceBuffer, filename: "invoice.pdf" },
+     * ]);
+     *
+     * // Use deepTextPromptPortion in wrapCitationPrompt
+     * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
+     *   systemPrompt,
+     *   userPrompt,
+     *   deepTextPromptPortion
+     * });
+     *
+     * // Use fileDataParts later for verification
+     * const result = await dc.verifyCitationsFromLlmOutput({ llmOutput, fileDataParts });
+     * ```
+     */
+    prepareFiles(files: FileInput[]): Promise<PrepareFilesResult>;
+    /**
+     * Verify citations against a previously uploaded file.
+     *
+     * @param attachmentId - The attachment ID returned from uploadFile
+     * @param citations - Citations to verify (from getAllCitationsFromLlmOutput)
+     * @param options - Optional verification options
+     * @returns Verification results with status and proof images
+     *
+     * @example
+     * ```typescript
+     * import { getAllCitationsFromLlmOutput } from '@deepcitation/deepcitation-js';
+     *
+     * const citations = getAllCitationsFromLlmOutput(llmResponse);
+     * const verified = await dc.verifyCitations(attachmentId, citations);
+     *
+     * for (const [key, result] of Object.entries(verified.verifications)) {
+     *   console.log(key, result.searchState?.status);
+     *   // "found", "partial_text_found", "not_found", etc.
+     * }
+     * ```
+     */
+    verifyCitations(attachmentId: string, citations: CitationInput, options?: VerifyCitationsOptions): Promise<VerifyCitationsResponse>;
+    /**
+     * Verify citations from LLM output with automatic parsing.
+     * This is the recommended way to verify citations for new integrations.
+     *
+     * @param input - Object containing llmOutput and optional fileDataParts
+     * @returns Verification results with status and proof images
+     *
+     * @example
+     * ```typescript
+     * const result = await dc.verifyCitationsFromLlmOutput({
+     *   llmOutput: response.content,
+     *   fileDataParts, // From prepareFiles()
+     * });
+     *
+     * for (const [key, result] of Object.entries(result.verifications)) {
+     *   console.log(key, result.searchState?.status);
+     * }
+     * ```
+     */
+    verifyCitationsFromLlmOutput(input: VerifyCitationsFromLlmOutput, citations?: {
+        [key: string]: Citation;
+    }): Promise<VerifyCitationsResponse>;
+}
+
+export { type CitationInput, type ConvertFileInput, type ConvertFileResponse, DeepCitation, type DeepCitationConfig, type FileDataPart, type FileInput, type PrepareConvertedFileOptions, type PrepareFilesResult, type UploadFileOptions, type UploadFileResponse, type VerifyCitationsFromLlmOutput, type VerifyCitationsOptions, type VerifyCitationsResponse };

package/lib/client/index.js

@@ -1 +1 @@
-export { DeepCitation } from "./DeepCitation.js";
+export{q as DeepCitation}from'../chunk-DEUSSEFH.js';import'../chunk-O2XFH626.js';

package/lib/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunkJ7U6YFOI_cjs=require('./chunk-J7U6YFOI.cjs'),chunk4FGOHQFP_cjs=require('./chunk-4FGOHQFP.cjs'),chunkCFXDRAJL_cjs=require('./chunk-CFXDRAJL.cjs');require('./chunk-F2MMVEVC.cjs');var H=t=>{if(!t)return  false;let e=t.trim();if(e.length<64)return  false;let a=e?.[0];for(let n=1;n<e.length;n++)if(e[n]!==a)return  false;return  true};function Y(t){t=t.trim();let e=2,a=10,n=/[.?!](?=\s+|$)/g,m,r=[];for(;(m=n.exec(t))!==null;)r.push(m.index);if(r.length<2)return t;let I=r[r.length-1],N=r[r.length-2],o=t.substring(N+1,I+1),p=o.length;if(o.trim().slice(0,-1).length<a||p<=0||t.length<p*e)return t;let c=0,s=I+1;t.endsWith(o)&&(s=t.length);let f=-1;for(;;){let i=s-p;if(i<0)break;if(t.substring(i,s)===o)c++,f=i,s=i;else break}return c>=e?t.substring(0,f)+o:t}Object.defineProperty(exports,"CITATION_X_PADDING",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.j}});Object.defineProperty(exports,"CITATION_Y_PADDING",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.k}});Object.defineProperty(exports,"DeepCitation",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.q}});Object.defineProperty(exports,"generateCitationInstanceId",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.i}});Object.defineProperty(exports,"generateCitationKey",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.g}});Object.defineProperty(exports,"generateVerificationKey",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.h}});Object.defineProperty(exports,"getAllCitationsFromLlmOutput",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.n}});Object.defineProperty(exports,"getCitationPageNumber",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.d}});Object.defineProperty(exports,"getCitationStatus",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.l}});Object.defineProperty(exports,"groupCitationsByAttachmentId",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.o}});Object.defineProperty(exports,"groupCitationsByAttachmentIdObject",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.p}});Object.defineProperty(exports,"normalizeCitations",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.e}});Object.defineProperty(exports,"parseCitation",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.m}});Object.defineProperty(exports,"removeCitations",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.a}});Object.defineProperty(exports,"removeLineIdMetadata",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.c}});Object.defineProperty(exports,"removePageNumberMetadata",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.b}});Object.defineProperty(exports,"sha1Hash",{enumerable:true,get:function(){return chunkJ7U6YFOI_cjs.f}});Object.defineProperty(exports,"AV_CITATION_MARKDOWN_SYNTAX_PROMPT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.b}});Object.defineProperty(exports,"CITATION_AV_BASED_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.h}});Object.defineProperty(exports,"CITATION_AV_REMINDER",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.d}});Object.defineProperty(exports,"CITATION_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.g}});Object.defineProperty(exports,"CITATION_MARKDOWN_SYNTAX_PROMPT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.a}});Object.defineProperty(exports,"CITATION_REMINDER",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.c}});Object.defineProperty(exports,"compressPromptIds",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.i}});Object.defineProperty(exports,"decompressPromptIds",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.j}});Object.defineProperty(exports,"wrapCitationPrompt",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.f}});Object.defineProperty(exports,"wrapSystemCitationPrompt",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.e}});Object.defineProperty(exports,"BLANK_VERIFICATION",{enumerable:true,get:function(){return chunkCFXDRAJL_cjs.d}});Object.defineProperty(exports,"DEFAULT_OUTPUT_IMAGE_FORMAT",{enumerable:true,get:function(){return chunkCFXDRAJL_cjs.a}});Object.defineProperty(exports,"NOT_FOUND_VERIFICATION_INDEX",{enumerable:true,get:function(){return chunkCFXDRAJL_cjs.b}});Object.defineProperty(exports,"PENDING_VERIFICATION_INDEX",{enumerable:true,get:function(){return chunkCFXDRAJL_cjs.c}});exports.cleanRepeatingLastSentence=Y;exports.isGeminiGarbage=H;

package/lib/index.d.cts

@@ -0,0 +1,127 @@
+export { CitationInput, DeepCitation, DeepCitationConfig, FileDataPart, FileInput, PrepareFilesResult, UploadFileOptions, UploadFileResponse, VerifyCitationsFromLlmOutput, VerifyCitationsOptions, VerifyCitationsResponse } from './client/index.cjs';
+import { Citation, Verification, CitationStatus } from './types/index.cjs';
+export { BLANK_VERIFICATION, DEFAULT_OUTPUT_IMAGE_FORMAT, IVertex, NOT_FOUND_VERIFICATION_INDEX, OutputImageFormat, PENDING_VERIFICATION_INDEX, PdfSpaceItem, ScreenBox, SearchAttempt, SearchMethod, SearchStatus, VerifyCitationRequest, VerifyCitationResponse } from './types/index.cjs';
+export { AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, CITATION_AV_REMINDER, CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_REMINDER, CompressedResult, WrapCitationPromptOptions, WrapCitationPromptResult, WrapSystemPromptOptions, compressPromptIds, decompressPromptIds, wrapCitationPrompt, wrapSystemCitationPrompt } from './prompts/index.cjs';
+
+/**
+ * Calculates the verification status of a citation based on the found highlight and search state.
+ *
+ * @param verification - The found highlight location, or null/undefined if not found
+ * @returns An object containing boolean flags for verification status
+ */
+declare function getCitationStatus(verification: Verification | null | undefined): CitationStatus;
+declare const parseCitation: (fragment: string, mdAttachmentId?: string | null, citationCounterRef?: any | null, isVerbose?: boolean) => {
+    beforeCite: string;
+    afterCite: string;
+    citation: Citation;
+};
+/**
+ * Extracts all citations from LLM output.
+ * Supports both XML <cite ... /> tags (embedded in strings/markdown) and JSON-based citation formats.
+ *
+ * For object input:
+ * - Traverses the object looking for `citation` or `citations` properties matching JSON format
+ * - Also stringifies the object to find embedded XML citations in markdown content
+ *
+ * @param llmOutput - The LLM output (string or object)
+ * @returns Dictionary of parsed Citation objects keyed by citation key
+ */
+declare const getAllCitationsFromLlmOutput: (llmOutput: any) => {
+    [key: string]: Citation;
+};
+/**
+ * Groups citations by their attachmentId for multi-file verification scenarios.
+ * This is useful when you have citations from multiple files and need to
+ * verify them against their respective source documents.
+ *
+ * @param citations - Array of Citation objects or a dictionary of citations
+ * @returns Map of attachmentId to dictionary of citations from that file
+ *
+ * @example
+ * ```typescript
+ * const citations = getAllCitationsFromLlmOutput(response.content);
+ * const citationsByAttachment = groupCitationsByAttachmentId(citations);
+ *
+ * // Verify citations for each file
+ * for (const [attachmentId, fileCitations] of citationsByAttachment) {
+ *   const verified = await dc.verifyCitations(attachmentId, fileCitations);
+ *   // Process verification results...
+ * }
+ * ```
+ */
+declare function groupCitationsByAttachmentId(citations: Citation[] | {
+    [key: string]: Citation;
+}): Map<string, {
+    [key: string]: Citation;
+}>;
+/**
+ * Groups citations by their attachmentId and returns as a plain object.
+ * Alternative to groupCitationsByAttachmentId that returns a plain object instead of a Map.
+ *
+ * @param citations - Array of Citation objects or a dictionary of citations
+ * @returns Object with attachmentId keys mapping to citation dictionaries
+ *
+ * @example
+ * ```typescript
+ * const citations = getAllCitationsFromLlmOutput(response.content);
+ * const citationsByAttachment = groupCitationsByAttachmentIdObject(citations);
+ *
+ * // Verify citations for each file using Promise.all
+ * const verificationPromises = Object.entries(citationsByAttachment).map(
+ *   ([attachmentId, fileCitations]) => dc.verifyCitations(attachmentId, fileCitations)
+ * );
+ * const results = await Promise.all(verificationPromises);
+ * ```
+ */
+declare function groupCitationsByAttachmentIdObject(citations: Citation[] | {
+    [key: string]: Citation;
+}): {
+    [attachmentId: string]: {
+        [key: string]: Citation;
+    };
+};
+
+declare const removeCitations: (pageText: string, leaveKeySpanBehind?: boolean) => string;
+declare const removePageNumberMetadata: (pageText: string) => string;
+declare const removeLineIdMetadata: (pageText: string) => string;
+declare const getCitationPageNumber: (startPageKey?: string | null) => number | null;
+declare const normalizeCitations: (response: string) => string;
+
+declare const isGeminiGarbage: (content: string) => boolean;
+declare function cleanRepeatingLastSentence(text: string): string;
+
+/**
+ * Pure JavaScript SHA-1 implementation.
+ * Based on the FIPS 180-4 specification.
+ * No external dependencies.
+ */
+/**
+ * Computes a SHA-1 hash of the provided data.
+ * Used internally by generateCitationKey in react/utils.ts
+ */
+declare function sha1Hash(data: string | any): string;
+
+/**
+ * Generates a unique, deterministic key for a citation based on its content.
+ *  @param citation - The citation to generate a key for
+ * @returns A unique, deterministic key for the citation
+ */
+declare function generateCitationKey(citation: Citation): string;
+/**
+ * Generates a unique, deterministic key for a verification based on its content.
+ * @param verification - The verification to generate a key for
+ * @returns
+ */
+declare function generateVerificationKey(verification: Verification): string;
+/**
+ * Generates a unique instance ID for a citation component render.
+ * Combines the citation key with a random suffix for uniqueness.
+ */
+declare function generateCitationInstanceId(citationKey: string): string;
+/**
+ * Default padding values for citation styling.
+ */
+declare const CITATION_X_PADDING = 4;
+declare const CITATION_Y_PADDING = 1;
+
+export { CITATION_X_PADDING, CITATION_Y_PADDING, Citation, CitationStatus, Verification, cleanRepeatingLastSentence, generateCitationInstanceId, generateCitationKey, generateVerificationKey, getAllCitationsFromLlmOutput, getCitationPageNumber, getCitationStatus, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, isGeminiGarbage, normalizeCitations, parseCitation, removeCitations, removeLineIdMetadata, removePageNumberMetadata, sha1Hash };

package/lib/index.d.ts

@@ -1,23 +1,127 @@
+export { CitationInput, DeepCitation, DeepCitationConfig, FileDataPart, FileInput, PrepareFilesResult, UploadFileOptions, UploadFileResponse, VerifyCitationsFromLlmOutput, VerifyCitationsOptions, VerifyCitationsResponse } from './client/index.js';
+import { Citation, Verification, CitationStatus } from './types/index.js';
+export { BLANK_VERIFICATION, DEFAULT_OUTPUT_IMAGE_FORMAT, IVertex, NOT_FOUND_VERIFICATION_INDEX, OutputImageFormat, PENDING_VERIFICATION_INDEX, PdfSpaceItem, ScreenBox, SearchAttempt, SearchMethod, SearchStatus, VerifyCitationRequest, VerifyCitationResponse } from './types/index.js';
+export { AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, CITATION_AV_REMINDER, CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_REMINDER, CompressedResult, WrapCitationPromptOptions, WrapCitationPromptResult, WrapSystemPromptOptions, compressPromptIds, decompressPromptIds, wrapCitationPrompt, wrapSystemCitationPrompt } from './prompts/index.js';
+
 /**
- * DeepCitation - Citation parsing, verification, and rendering library
- * @packageDocumentation
- */
-export { DeepCitation } from "./client/index.js";
-export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutput, } from "./client/index.js";
-export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, } from "./parsing/parseCitation.js";
-export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
-export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
-export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./types/citation.js";
-export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
-export type { Verification } from "./types/verification.js";
-export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, } from "./types/verification.js";
-export type { SearchStatus, SearchMethod, SearchAttempt, } from "./types/search.js";
-export type { ScreenBox, PdfSpaceItem, IVertex } from "./types/boxes.js";
-export { sha1Hash } from "./utils/sha.js";
-export { generateCitationKey, generateVerificationKey, generateCitationInstanceId, } from "./react/utils.js";
-export { CITATION_X_PADDING, CITATION_Y_PADDING } from "./react/utils.js";
-export { CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, wrapSystemCitationPrompt, wrapCitationPrompt, } from "./prompts/citationPrompts.js";
-export type { WrapSystemPromptOptions, WrapCitationPromptOptions, WrapCitationPromptResult, } from "./prompts/citationPrompts.js";
-export { removeLineIdMetadata, removePageNumberMetadata, removeCitations, } from "./parsing/normalizeCitation.js";
-export { compressPromptIds, decompressPromptIds, } from "./prompts/promptCompression.js";
-export type { CompressedResult } from "./prompts/types.js";
+ * Calculates the verification status of a citation based on the found highlight and search state.
+ *
+ * @param verification - The found highlight location, or null/undefined if not found
+ * @returns An object containing boolean flags for verification status
+ */
+declare function getCitationStatus(verification: Verification | null | undefined): CitationStatus;
+declare const parseCitation: (fragment: string, mdAttachmentId?: string | null, citationCounterRef?: any | null, isVerbose?: boolean) => {
+    beforeCite: string;
+    afterCite: string;
+    citation: Citation;
+};
+/**
+ * Extracts all citations from LLM output.
+ * Supports both XML <cite ... /> tags (embedded in strings/markdown) and JSON-based citation formats.
+ *
+ * For object input:
+ * - Traverses the object looking for `citation` or `citations` properties matching JSON format
+ * - Also stringifies the object to find embedded XML citations in markdown content
+ *
+ * @param llmOutput - The LLM output (string or object)
+ * @returns Dictionary of parsed Citation objects keyed by citation key
+ */
+declare const getAllCitationsFromLlmOutput: (llmOutput: any) => {
+    [key: string]: Citation;
+};
+/**
+ * Groups citations by their attachmentId for multi-file verification scenarios.
+ * This is useful when you have citations from multiple files and need to
+ * verify them against their respective source documents.
+ *
+ * @param citations - Array of Citation objects or a dictionary of citations
+ * @returns Map of attachmentId to dictionary of citations from that file
+ *
+ * @example
+ * ```typescript
+ * const citations = getAllCitationsFromLlmOutput(response.content);
+ * const citationsByAttachment = groupCitationsByAttachmentId(citations);
+ *
+ * // Verify citations for each file
+ * for (const [attachmentId, fileCitations] of citationsByAttachment) {
+ *   const verified = await dc.verifyCitations(attachmentId, fileCitations);
+ *   // Process verification results...
+ * }
+ * ```
+ */
+declare function groupCitationsByAttachmentId(citations: Citation[] | {
+    [key: string]: Citation;
+}): Map<string, {
+    [key: string]: Citation;
+}>;
+/**
+ * Groups citations by their attachmentId and returns as a plain object.
+ * Alternative to groupCitationsByAttachmentId that returns a plain object instead of a Map.
+ *
+ * @param citations - Array of Citation objects or a dictionary of citations
+ * @returns Object with attachmentId keys mapping to citation dictionaries
+ *
+ * @example
+ * ```typescript
+ * const citations = getAllCitationsFromLlmOutput(response.content);
+ * const citationsByAttachment = groupCitationsByAttachmentIdObject(citations);
+ *
+ * // Verify citations for each file using Promise.all
+ * const verificationPromises = Object.entries(citationsByAttachment).map(
+ *   ([attachmentId, fileCitations]) => dc.verifyCitations(attachmentId, fileCitations)
+ * );
+ * const results = await Promise.all(verificationPromises);
+ * ```
+ */
+declare function groupCitationsByAttachmentIdObject(citations: Citation[] | {
+    [key: string]: Citation;
+}): {
+    [attachmentId: string]: {
+        [key: string]: Citation;
+    };
+};
+
+declare const removeCitations: (pageText: string, leaveKeySpanBehind?: boolean) => string;
+declare const removePageNumberMetadata: (pageText: string) => string;
+declare const removeLineIdMetadata: (pageText: string) => string;
+declare const getCitationPageNumber: (startPageKey?: string | null) => number | null;
+declare const normalizeCitations: (response: string) => string;
+
+declare const isGeminiGarbage: (content: string) => boolean;
+declare function cleanRepeatingLastSentence(text: string): string;
+
+/**
+ * Pure JavaScript SHA-1 implementation.
+ * Based on the FIPS 180-4 specification.
+ * No external dependencies.
+ */
+/**
+ * Computes a SHA-1 hash of the provided data.
+ * Used internally by generateCitationKey in react/utils.ts
+ */
+declare function sha1Hash(data: string | any): string;
+
+/**
+ * Generates a unique, deterministic key for a citation based on its content.
+ *  @param citation - The citation to generate a key for
+ * @returns A unique, deterministic key for the citation
+ */
+declare function generateCitationKey(citation: Citation): string;
+/**
+ * Generates a unique, deterministic key for a verification based on its content.
+ * @param verification - The verification to generate a key for
+ * @returns
+ */
+declare function generateVerificationKey(verification: Verification): string;
+/**
+ * Generates a unique instance ID for a citation component render.
+ * Combines the citation key with a random suffix for uniqueness.
+ */
+declare function generateCitationInstanceId(citationKey: string): string;
+/**
+ * Default padding values for citation styling.
+ */
+declare const CITATION_X_PADDING = 4;
+declare const CITATION_Y_PADDING = 1;
+
+export { CITATION_X_PADDING, CITATION_Y_PADDING, Citation, CitationStatus, Verification, cleanRepeatingLastSentence, generateCitationInstanceId, generateCitationKey, generateVerificationKey, getAllCitationsFromLlmOutput, getCitationPageNumber, getCitationStatus, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, isGeminiGarbage, normalizeCitations, parseCitation, removeCitations, removeLineIdMetadata, removePageNumberMetadata, sha1Hash };

package/lib/index.js

@@ -1,20 +1 @@
-/**
- * DeepCitation - Citation parsing, verification, and rendering library
- * @packageDocumentation
- */
-// Client
-export { DeepCitation } from "./client/index.js";
-// Parsing
-export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByAttachmentId, groupCitationsByAttachmentIdObject, } from "./parsing/parseCitation.js";
-export { normalizeCitations, getCitationPageNumber, } from "./parsing/normalizeCitation.js";
-export { isGeminiGarbage, cleanRepeatingLastSentence, } from "./parsing/parseWorkAround.js";
-export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
-export { NOT_FOUND_VERIFICATION_INDEX, PENDING_VERIFICATION_INDEX, BLANK_VERIFICATION, } from "./types/verification.js";
-// Utilities
-export { sha1Hash } from "./utils/sha.js";
-export { generateCitationKey, generateVerificationKey, generateCitationInstanceId, } from "./react/utils.js";
-export { CITATION_X_PADDING, CITATION_Y_PADDING } from "./react/utils.js";
-// Prompts
-export { CITATION_JSON_OUTPUT_FORMAT, CITATION_MARKDOWN_SYNTAX_PROMPT, AV_CITATION_MARKDOWN_SYNTAX_PROMPT, CITATION_AV_BASED_JSON_OUTPUT_FORMAT, wrapSystemCitationPrompt, wrapCitationPrompt, } from "./prompts/citationPrompts.js";
-export { removeLineIdMetadata, removePageNumberMetadata, removeCitations, } from "./parsing/normalizeCitation.js";
-export { compressPromptIds, decompressPromptIds, } from "./prompts/promptCompression.js";
+export{j as CITATION_X_PADDING,k as CITATION_Y_PADDING,q as DeepCitation,i as generateCitationInstanceId,g as generateCitationKey,h as generateVerificationKey,n as getAllCitationsFromLlmOutput,d as getCitationPageNumber,l as getCitationStatus,o as groupCitationsByAttachmentId,p as groupCitationsByAttachmentIdObject,e as normalizeCitations,m as parseCitation,a as removeCitations,c as removeLineIdMetadata,b as removePageNumberMetadata,f as sha1Hash}from'./chunk-DEUSSEFH.js';export{b as AV_CITATION_MARKDOWN_SYNTAX_PROMPT,h as CITATION_AV_BASED_JSON_OUTPUT_FORMAT,d as CITATION_AV_REMINDER,g as CITATION_JSON_OUTPUT_FORMAT,a as CITATION_MARKDOWN_SYNTAX_PROMPT,c as CITATION_REMINDER,i as compressPromptIds,j as decompressPromptIds,f as wrapCitationPrompt,e as wrapSystemCitationPrompt}from'./chunk-2IZXUOQR.js';export{d as BLANK_VERIFICATION,a as DEFAULT_OUTPUT_IMAGE_FORMAT,b as NOT_FOUND_VERIFICATION_INDEX,c as PENDING_VERIFICATION_INDEX}from'./chunk-RQPZSRID.js';import'./chunk-O2XFH626.js';var H=t=>{if(!t)return  false;let e=t.trim();if(e.length<64)return  false;let a=e?.[0];for(let n=1;n<e.length;n++)if(e[n]!==a)return  false;return  true};function Y(t){t=t.trim();let e=2,a=10,n=/[.?!](?=\s+|$)/g,m,r=[];for(;(m=n.exec(t))!==null;)r.push(m.index);if(r.length<2)return t;let I=r[r.length-1],N=r[r.length-2],o=t.substring(N+1,I+1),p=o.length;if(o.trim().slice(0,-1).length<a||p<=0||t.length<p*e)return t;let c=0,s=I+1;t.endsWith(o)&&(s=t.length);let f=-1;for(;;){let i=s-p;if(i<0)break;if(t.substring(i,s)===o)c++,f=i,s=i;else break}return c>=e?t.substring(0,f)+o:t}export{Y as cleanRepeatingLastSentence,H as isGeminiGarbage};

package/lib/prompts/index.cjs

@@ -0,0 +1 @@
+'use strict';var chunk4FGOHQFP_cjs=require('../chunk-4FGOHQFP.cjs');require('../chunk-F2MMVEVC.cjs');Object.defineProperty(exports,"AV_CITATION_MARKDOWN_SYNTAX_PROMPT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.b}});Object.defineProperty(exports,"CITATION_AV_BASED_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.h}});Object.defineProperty(exports,"CITATION_AV_REMINDER",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.d}});Object.defineProperty(exports,"CITATION_JSON_OUTPUT_FORMAT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.g}});Object.defineProperty(exports,"CITATION_MARKDOWN_SYNTAX_PROMPT",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.a}});Object.defineProperty(exports,"CITATION_REMINDER",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.c}});Object.defineProperty(exports,"compressPromptIds",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.i}});Object.defineProperty(exports,"decompressPromptIds",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.j}});Object.defineProperty(exports,"wrapCitationPrompt",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.f}});Object.defineProperty(exports,"wrapSystemCitationPrompt",{enumerable:true,get:function(){return chunk4FGOHQFP_cjs.e}});