@deepcitation/deepcitation-js 1.0.4 → 1.0.6

package/README.md

@@ -41,7 +41,7 @@ Get a free API key at [deepcitation.com](https://deepcitation.com/signup) — no
 
 ```bash
 # .env
-DEEPCITATION_API_KEY=dc_live_your_api_key_here
+DEEPCITATION_API_KEY=sk-dc-your_api_key_here
 ```
 
 ---
@@ -60,7 +60,7 @@ import { DeepCitation, wrapCitationPrompt } from "@deepcitation/deepcitation-js"
 const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
 
 // Upload source files
-const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
+const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
   { file: pdfBuffer, filename: "report.pdf" },
 ]);
 
@@ -68,7 +68,7 @@ const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
 const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
   systemPrompt: "You are a helpful assistant...",
   userPrompt: "Analyze this document",
-  fileDeepText: fileDeepTexts,
+  deepTextPromptPortion,
 });
 
 // Call your LLM
@@ -123,7 +123,7 @@ function Response({ citations, verifications }) {
 
 ```typescript
 const dc = new DeepCitation({
-  apiKey: string,      // Your API key (dc_live_* or dc_test_*)
+  apiKey: string,      // Your API key (sk-dc-*)
   apiUrl?: string,     // Optional: Custom API URL
 });
 

package/lib/client/DeepCitation.d.ts

@@ -1,5 +1,5 @@
 import type { Citation } from "../types/index";
-import type { CitationInput, ConvertFileInput, ConvertFileResponse, DeepCitationConfig, FileInput, PrepareConvertedFileOptions, PrepareFilesResult, UploadFileOptions, UploadFileResponse, VerifyCitationsFromLlmOutputInput, VerifyCitationsOptions, VerifyCitationsResponse } from "./types";
+import type { CitationInput, ConvertFileInput, ConvertFileResponse, DeepCitationConfig, FileInput, PrepareConvertedFileOptions, PrepareFilesResult, UploadFileOptions, UploadFileResponse, VerifyCitationsFromLlmOutput, VerifyCitationsOptions, VerifyCitationsResponse } from "./types";
 /**
  * DeepCitation client for file upload and citation verification.
  *
@@ -33,6 +33,8 @@ export declare class DeepCitation {
      * This allows users to reference files by their own IDs
      */
     private fileIdMap;
+    /** Store file mapping and return public response */
+    private storeAndReturnResponse;
     /**
      * Create a new DeepCitation client instance.
      *
@@ -91,7 +93,7 @@ export declare class DeepCitation {
      * });
      *
      * // Then prepare the file for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: result.fileId
      * });
      * ```
@@ -99,7 +101,7 @@ export declare class DeepCitation {
     convertToPdf(input: ConvertFileInput | string): Promise<ConvertFileResponse>;
     /**
      * Prepare a previously converted file for citation verification.
-     * Use this after calling convertToPdf() to extract text and get fileDeepText.
+     * Use this after calling convertToPdf() to extract text and get deepTextPromptPortion.
      *
      * @param options - Options with fileId from convertFile
      * @returns Upload response with fileId and extracted text
@@ -110,11 +112,11 @@ export declare class DeepCitation {
      * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
      *
      * // Then prepare it for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: converted.fileId
      * });
      *
-     * // Use fileDeepText in your LLM prompt...
+     * // Use deepTextPromptPortion in your LLM prompt...
      * ```
      */
     prepareConvertedFile(options: PrepareConvertedFileOptions): Promise<UploadFileResponse>;
@@ -123,20 +125,20 @@ export declare class DeepCitation {
      * This is the recommended way to prepare files for LLM prompts.
      *
      * @param files - Array of files to upload with optional filenames and fileIds
-     * @returns Object containing fileDataParts for verification and fileDeepTexts for LLM
+     * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
      *
      * @example
      * ```typescript
-     * const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
+     * const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
      *   { file: pdfBuffer, filename: "report.pdf" },
      *   { file: invoiceBuffer, filename: "invoice.pdf" },
      * ]);
      *
-     * // Use fileDeepTexts in wrapCitationPrompt
+     * // Use deepTextPromptPortion in wrapCitationPrompt
      * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
      *   systemPrompt,
      *   userPrompt,
-     *   fileDeepText: fileDeepTexts
+     *   deepTextPromptPortion
      * });
      *
      * // Use fileDataParts later for verification
@@ -185,7 +187,7 @@ export declare class DeepCitation {
      * }
      * ```
      */
-    verifyCitationsFromLlmOutput(input: VerifyCitationsFromLlmOutputInput, citations?: {
+    verifyCitationsFromLlmOutput(input: VerifyCitationsFromLlmOutput, citations?: {
         [key: string]: Citation;
     }): Promise<VerifyCitationsResponse>;
     /**

package/lib/client/DeepCitation.js

@@ -1,6 +1,25 @@
 import { getAllCitationsFromLlmOutput } from "../parsing/parseCitation";
 import { generateCitationKey } from "../react/utils";
 const DEFAULT_API_URL = "https://api.deepcitation.com";
+/** Convert File/Blob/Buffer to a Blob suitable for FormData */
+function toBlob(file, filename) {
+    if (typeof Buffer !== "undefined" && Buffer.isBuffer(file)) {
+        const uint8 = Uint8Array.from(file);
+        return { blob: new Blob([uint8]), name: filename || "document" };
+    }
+    if (file instanceof Blob) {
+        return {
+            blob: file,
+            name: filename || (file instanceof File ? file.name : "document"),
+        };
+    }
+    throw new Error("Invalid file type. Expected File, Blob, or Buffer.");
+}
+/** Extract error message from API response */
+async function extractErrorMessage(response, fallbackAction) {
+    const error = await response.json().catch(() => ({}));
+    return error?.error?.message || `${fallbackAction} failed with status ${response.status}`;
+}
 /**
  * DeepCitation client for file upload and citation verification.
  *
@@ -34,6 +53,12 @@ export class DeepCitation {
      * This allows users to reference files by their own IDs
      */
     fileIdMap = new Map();
+    /** Store file mapping and return public response */
+    storeAndReturnResponse(apiResponse) {
+        this.fileIdMap.set(apiResponse.fileId, { attachmentId: apiResponse.attachmentId });
+        const { attachmentId: _, ...publicResponse } = apiResponse;
+        return publicResponse;
+    }
     /**
      * Create a new DeepCitation client instance.
      *
@@ -71,51 +96,22 @@ export class DeepCitation {
      * ```
      */
     async uploadFile(file, options) {
+        const { blob, name } = toBlob(file, options?.filename);
         const formData = new FormData();
-        // Handle different input types
-        if (typeof Buffer !== "undefined" && Buffer.isBuffer(file)) {
-            // Node.js Buffer - copy to a new ArrayBuffer for Blob compatibility
-            const filename = options?.filename || "document";
-            // Use Uint8Array.from to create a copy that's definitely backed by ArrayBuffer (not SharedArrayBuffer)
-            const uint8 = Uint8Array.from(file);
-            const blob = new Blob([uint8]);
-            formData.append("file", blob, filename);
-        }
-        else if (file instanceof Blob) {
-            // File or Blob
-            const filename = options?.filename || (file instanceof File ? file.name : "document");
-            formData.append("file", file, filename);
-        }
-        else {
-            throw new Error("Invalid file type. Expected File, Blob, or Buffer.");
-        }
-        // Add optional fields
-        if (options?.fileId) {
+        formData.append("file", blob, name);
+        if (options?.fileId)
             formData.append("fileId", options.fileId);
-        }
-        if (options?.filename) {
+        if (options?.filename)
             formData.append("filename", options.filename);
-        }
         const response = await fetch(`${this.apiUrl}/prepareFile`, {
             method: "POST",
-            headers: {
-                Authorization: `Bearer ${this.apiKey}`,
-            },
+            headers: { Authorization: `Bearer ${this.apiKey}` },
             body: formData,
         });
         if (!response.ok) {
-            const error = await response.json().catch(() => ({}));
-            throw new Error(error?.error?.message || `Upload failed with status ${response.status}`);
+            throw new Error(await extractErrorMessage(response, "Upload"));
         }
-        // Internal response includes attachmentId which we need for verification
-        const apiResponse = (await response.json());
-        // Store the mapping for later verification calls
-        this.fileIdMap.set(apiResponse.fileId, {
-            attachmentId: apiResponse.attachmentId,
-        });
-        // Return public response without internal fields
-        const { attachmentId: _attachmentId, ...publicResponse } = apiResponse;
-        return publicResponse;
+        return this.storeAndReturnResponse(await response.json());
     }
     /**
      * Convert a URL or Office file to PDF for citation verification.
@@ -144,85 +140,53 @@ export class DeepCitation {
      * });
      *
      * // Then prepare the file for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: result.fileId
      * });
      * ```
      */
     async convertToPdf(input) {
-        // Handle string URL shorthand
         const inputObj = typeof input === "string" ? { url: input } : input;
-        const { url, file, filename, fileId, singlePage } = inputObj;
+        const { url, file, filename, fileId } = inputObj;
         if (!url && !file) {
             throw new Error("Either url or file must be provided");
         }
         let response;
         if (url) {
-            // URL conversion - send as JSON
             response = await fetch(`${this.apiUrl}/convertFile`, {
                 method: "POST",
                 headers: {
                     Authorization: `Bearer ${this.apiKey}`,
                     "Content-Type": "application/json",
                 },
-                body: JSON.stringify({
-                    url,
-                    filename,
-                    fileId,
-                    singlePage,
-                }),
+                body: JSON.stringify({ url, filename, fileId }),
             });
         }
-        else if (file) {
-            // Office file conversion - send as multipart
+        else {
+            const { blob, name } = toBlob(file, filename);
             const formData = new FormData();
-            if (typeof Buffer !== "undefined" && Buffer.isBuffer(file)) {
-                const fname = filename || "document";
-                const uint8 = Uint8Array.from(file);
-                const blob = new Blob([uint8]);
-                formData.append("file", blob, fname);
-            }
-            else if (file instanceof Blob) {
-                const fname = filename || (file instanceof File ? file.name : "document");
-                formData.append("file", file, fname);
-            }
-            else {
-                throw new Error("Invalid file type. Expected File, Blob, or Buffer.");
-            }
-            if (fileId) {
+            formData.append("file", blob, name);
+            if (fileId)
                 formData.append("fileId", fileId);
-            }
-            if (filename) {
+            if (filename)
                 formData.append("filename", filename);
-            }
             response = await fetch(`${this.apiUrl}/convertFile`, {
                 method: "POST",
-                headers: {
-                    Authorization: `Bearer ${this.apiKey}`,
-                },
+                headers: { Authorization: `Bearer ${this.apiKey}` },
                 body: formData,
             });
         }
-        else {
-            throw new Error("Either url or file must be provided");
-        }
         if (!response.ok) {
-            const error = await response.json().catch(() => ({}));
-            throw new Error(error?.error?.message || `Conversion failed with status ${response.status}`);
+            throw new Error(await extractErrorMessage(response, "Conversion"));
         }
-        // Internal response includes attachmentId which we need for the two-step flow
         const apiResponse = (await response.json());
-        // Store the mapping for later verification and prepareConvertedFile calls
-        this.fileIdMap.set(apiResponse.fileId, {
-            attachmentId: apiResponse.attachmentId,
-        });
-        // Return public response without internal fields
-        const { attachmentId: _attachmentId, ...publicResponse } = apiResponse;
+        this.fileIdMap.set(apiResponse.fileId, { attachmentId: apiResponse.attachmentId });
+        const { attachmentId: _, ...publicResponse } = apiResponse;
         return publicResponse;
     }
     /**
      * Prepare a previously converted file for citation verification.
-     * Use this after calling convertToPdf() to extract text and get fileDeepText.
+     * Use this after calling convertToPdf() to extract text and get deepTextPromptPortion.
      *
      * @param options - Options with fileId from convertFile
      * @returns Upload response with fileId and extracted text
@@ -233,15 +197,14 @@ export class DeepCitation {
      * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
      *
      * // Then prepare it for verification
-     * const { fileDeepText, fileId } = await dc.prepareConvertedFile({
+     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
      *   fileId: converted.fileId
      * });
      *
-     * // Use fileDeepText in your LLM prompt...
+     * // Use deepTextPromptPortion in your LLM prompt...
      * ```
      */
     async prepareConvertedFile(options) {
-        // Look up the internal attachmentId from the fileId
         const fileInfo = this.fileIdMap.get(options.fileId);
         if (!fileInfo) {
             throw new Error(`File ID "${options.fileId}" not found. Make sure to call convertToPdf() first.`);
@@ -258,38 +221,29 @@ export class DeepCitation {
             }),
         });
         if (!response.ok) {
-            const error = await response.json().catch(() => ({}));
-            throw new Error(error?.error?.message || `Prepare failed with status ${response.status}`);
+            throw new Error(await extractErrorMessage(response, "Prepare"));
         }
-        // Internal response includes attachmentId
-        const apiResponse = (await response.json());
-        // Update the mapping (attachmentId should remain the same)
-        this.fileIdMap.set(apiResponse.fileId, {
-            attachmentId: apiResponse.attachmentId,
-        });
-        // Return public response without internal fields
-        const { attachmentId: _attachmentId, ...publicResponse } = apiResponse;
-        return publicResponse;
+        return this.storeAndReturnResponse(await response.json());
     }
     /**
      * 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 fileIds
-     * @returns Object containing fileDataParts for verification and fileDeepTexts for LLM
+     * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
      *
      * @example
      * ```typescript
-     * const { fileDataParts, fileDeepTexts } = await dc.prepareFiles([
+     * const { fileDataParts, deepTextPromptPortion } = await dc.prepareFiles([
      *   { file: pdfBuffer, filename: "report.pdf" },
      *   { file: invoiceBuffer, filename: "invoice.pdf" },
      * ]);
      *
-     * // Use fileDeepTexts in wrapCitationPrompt
+     * // Use deepTextPromptPortion in wrapCitationPrompt
      * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
      *   systemPrompt,
      *   userPrompt,
-     *   fileDeepText: fileDeepTexts
+     *   deepTextPromptPortion
      * });
      *
      * // Use fileDataParts later for verification
@@ -298,17 +252,17 @@ export class DeepCitation {
      */
     async prepareFiles(files) {
         if (files.length === 0) {
-            return { fileDataParts: [], fileDeepTexts: [] };
+            return { fileDataParts: [], deepTextPromptPortion: [] };
         }
         // Upload all files in parallel
         const uploadPromises = files.map(({ file, filename, fileId }) => this.uploadFile(file, { filename, fileId }));
         const results = await Promise.all(uploadPromises);
         // Extract file data parts and file deep texts
-        const fileDataParts = results.map(result => ({
+        const fileDataParts = results.map((result) => ({
             fileId: result.fileId,
         }));
-        const fileDeepTexts = results.map(result => result.fileDeepText);
-        return { fileDataParts, fileDeepTexts };
+        const deepTextPromptPortion = results.map((result) => result.deepTextPromptPortion);
+        return { fileDataParts, deepTextPromptPortion };
     }
     /**
      * Verify citations against a previously uploaded file.
@@ -376,8 +330,7 @@ export class DeepCitation {
             }),
         });
         if (!response.ok) {
-            const error = await response.json().catch(() => ({}));
-            throw new Error(error?.error?.message || `Verification failed with status ${response.status}`);
+            throw new Error(await extractErrorMessage(response, "Verification"));
         }
         return (await response.json());
     }
@@ -412,7 +365,7 @@ export class DeepCitation {
         // Note: fileDataParts is now only used to identify which files to verify
         // The mapping from fileId to attachmentId must be registered via uploadFile() or prepareFiles()
         // in the same session. For Zero Data Retention scenarios, use verifyCitations() directly.
-        // Group citations by fileId and verify each group
+        // Group citations by fileId
         const citationsByFile = new Map();
         for (const [key, citation] of Object.entries(citations)) {
             const fileId = citation.fileId || "";
@@ -421,34 +374,16 @@ export class DeepCitation {
             }
             citationsByFile.get(fileId)[key] = citation;
         }
-        // Verify citations for each file
-        const allHighlights = {};
+        // Filter to only registered files and verify in parallel
+        const verificationPromises = [];
         for (const [fileId, fileCitations] of citationsByFile) {
-            // Check if we have the file registered
-            const fileInfo = this.fileIdMap.get(fileId);
-            if (!fileInfo) {
-                // Skip citations for unregistered files
-                continue;
+            if (this.fileIdMap.has(fileId)) {
+                verificationPromises.push(this.verifyCitations(fileId, fileCitations, { outputImageFormat }));
             }
-            const response = await fetch(`${this.apiUrl}/verifyCitation`, {
-                method: "POST",
-                headers: {
-                    Authorization: `Bearer ${this.apiKey}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify({
-                    data: {
-                        attachmentId: fileInfo.attachmentId,
-                        citations: fileCitations,
-                        outputImageFormat,
-                    },
-                }),
-            });
-            if (!response.ok) {
-                const error = await response.json().catch(() => ({}));
-                throw new Error(error?.error?.message || `Verification failed with status ${response.status}`);
-            }
-            const result = (await response.json());
+        }
+        const results = await Promise.all(verificationPromises);
+        const allHighlights = {};
+        for (const result of results) {
             Object.assign(allHighlights, result.foundHighlights);
         }
         return { foundHighlights: allHighlights };

package/lib/client/index.d.ts

@@ -1,2 +1,2 @@
 export { DeepCitation } from "./DeepCitation";
-export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutputInput, ConvertFileInput, ConvertFileResponse, PrepareConvertedFileOptions, } from "./types";
+export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutput, ConvertFileInput, ConvertFileResponse, PrepareConvertedFileOptions, } from "./types";

package/lib/client/types.d.ts

@@ -3,7 +3,7 @@ import type { Citation, FoundHighlightLocation } from "../types/index";
  * Configuration options for the DeepCitation client
  */
 export interface DeepCitationConfig {
-    /** Your DeepCitation API key (starts with dc_live_ or dc_test_) */
+    /** Your DeepCitation API key (starts with sk-dc-) */
     apiKey: string;
     /** Optional custom API base URL. Defaults to https://api.deepcitation.com */
     apiUrl?: string;
@@ -15,7 +15,7 @@ export interface UploadFileResponse {
     /** The file ID assigned by DeepCitation (custom or auto-generated) */
     fileId: string;
     /** The full text content formatted for LLM prompts with page markers and line IDs. Use this in your user prompts. */
-    fileDeepText: string;
+    deepTextPromptPortion: string;
     /** Form fields extracted from PDF forms */
     formFields?: Array<{
         name: string;
@@ -89,12 +89,12 @@ export interface PrepareFilesResult {
     /** Array of file references for verification */
     fileDataParts: FileDataPart[];
     /** Array of formatted text content for LLM prompts (with page markers and line IDs) */
-    fileDeepTexts: string[];
+    deepTextPromptPortion: string[];
 }
 /**
  * Input for verifyCitationsFromLlmOutput
  */
-export interface VerifyCitationsFromLlmOutputInput {
+export interface VerifyCitationsFromLlmOutput {
     /** The LLM response containing citations */
     llmOutput: string;
     /** Optional file references (required for Zero Data Retention or after storage expires) */
@@ -114,8 +114,6 @@ export interface ConvertFileInput {
     filename?: string;
     /** Optional custom file ID */
     fileId?: string;
-    /** For URLs: render as single long page instead of paginated */
-    singlePage?: boolean;
 }
 /**
  * Response from convertFile
@@ -146,12 +144,3 @@ export interface PrepareConvertedFileOptions {
     /** The file ID from a previous convertFile call */
     fileId: string;
 }
-/**
- * @deprecated Use PrepareConvertedFileOptions instead
- */
-export interface PrepareFileFromAttachmentOptions {
-    /** The attachment ID from a previous convertFile call */
-    attachmentId: string;
-    /** Optional custom file ID */
-    fileId?: string;
-}

package/lib/index.d.ts

@@ -3,15 +3,15 @@
  * @packageDocumentation
  */
 export { DeepCitation } from "./client/index.js";
-export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutputInput, } from "./client/index.js";
+export type { DeepCitationConfig, UploadFileResponse, UploadFileOptions, VerifyCitationsResponse, VerifyCitationsOptions, CitationInput, FileInput, FileDataPart, PrepareFilesResult, VerifyCitationsFromLlmOutput, } from "./client/index.js";
 export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByFileId, groupCitationsByFileIdObject, } from "./parsing/parseCitation.js";
-export { normalizeCitations, getCitationPageNumber } from "./parsing/normalizeCitation.js";
-export { isGeminiGarbage, cleanRepeatingLastSentence } from "./parsing/parseWorkAround.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 { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
+export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";
 export type { FoundHighlightLocation } from "./types/foundHighlight.js";
 export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./types/foundHighlight.js";
-export type { SearchState, SearchStatus, SearchMethod, SearchAttempt } from "./types/search.js";
+export type { SearchState, SearchStatus, SearchMethod, SearchAttempt, } from "./types/search.js";
 export type { ScreenBox, PdfSpaceItem, IVertex } from "./types/boxes.js";
 export { sha1Hash } from "./utils/sha.js";
 export { generateCitationKey } from "./react/utils.js";
@@ -19,7 +19,6 @@ export { 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 { removeLineIdMetadata, removePageNumberMetadata, removeCitations, } from "./parsing/normalizeCitation.js";
+export { compressPromptIds, decompressPromptIds, } from "./prompts/promptCompression.js";
 export type { CompressedResult } from "./prompts/types.js";
-export { CitationComponent } from "./react/CitationComponent.js";

package/lib/index.js

@@ -6,9 +6,9 @@
 export { DeepCitation } from "./client/index.js";
 // Parsing
 export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByFileId, groupCitationsByFileIdObject, } from "./parsing/parseCitation.js";
-export { normalizeCitations, getCitationPageNumber } from "./parsing/normalizeCitation.js";
-export { isGeminiGarbage, cleanRepeatingLastSentence } from "./parsing/parseWorkAround.js";
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.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_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./types/foundHighlight.js";
 // Utilities
 export { sha1Hash } from "./utils/sha.js";
@@ -17,6 +17,5 @@ export { 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 { CitationComponent } from "./react/CitationComponent.js";
+export { removeLineIdMetadata, removePageNumberMetadata, removeCitations, } from "./parsing/normalizeCitation.js";
+export { compressPromptIds, decompressPromptIds, } from "./prompts/promptCompression.js";

package/lib/parsing/normalizeCitation.js

@@ -35,7 +35,7 @@ export const normalizeCitations = (response) => {
         return normalizeCitationContent(trimmedResponse);
     }
     trimmedResponse = citationParts
-        .map(part => (part.startsWith("<cite") ? normalizeCitationContent(part) : part))
+        .map((part) => part.startsWith("<cite") ? normalizeCitationContent(part) : part)
         .join("");
     return trimmedResponse;
 };
@@ -49,10 +49,14 @@ const normalizeCitationContent = (input) => {
             return "full_phrase";
         if (key === "lineIds" || key === "line_ids")
             return "line_ids";
-        if (key === "startPageKey" || key === "start_pageKey" || key === "start_page_key")
+        if (key === "startPageKey" ||
+            key === "start_pageKey" ||
+            key === "start_page_key")
             return "start_page_key";
         if (key === "fileID" || key === "fileId" || key === "file_id")
             return "file_id";
+        if (key === "keySpan" || key === "key_span")
+            return "key_span";
         return key;
     };
     // Helper to decode HTML entities (simple implementation, expand if needed)
@@ -67,7 +71,7 @@ const normalizeCitationContent = (input) => {
     // 2. ROBUST TEXT ATTRIBUTE PARSING (reasoning, value, full_phrase)
     // This regex matches: Key = Quote -> Content (lazy) -> Lookahead for (Next Attribute OR End of Tag)
     // It effectively ignores quotes inside the content during the initial capture.
-    const textAttributeRegex = /(fullPhrase|full_phrase|reasoning|value)\s*=\s*(['"])([\s\S]*?)(?=\s+(?:line_ids|lineIds|timestamps|fileId|file_id|start_page_key|start_pageKey|startPageKey|reasoning|value|full_phrase)|\s*\/?>)/gm;
+    const textAttributeRegex = /(fullPhrase|full_phrase|keySpan|key_span|reasoning|value)\s*=\s*(['"])([\s\S]*?)(?=\s+(?:line_ids|lineIds|timestamps|fileId|file_id|start_page_key|start_pageKey|startPageKey|keySpan|key_span|reasoning|value|full_phrase)|\s*\/?>)/gm;
     normalized = normalized.replace(textAttributeRegex, (_match, key, openQuote, rawContent) => {
         let content = rawContent;
         // The lazy match usually captures the closing quote because the lookahead
@@ -139,7 +143,7 @@ const normalizeCitationContent = (input) => {
         if (keys.length === 0)
             return tag;
         const hasTimestamps = typeof attrs.timestamps === "string" && attrs.timestamps.length > 0;
-        const startPageKeys = keys.filter(k => k.startsWith("start_page"));
+        const startPageKeys = keys.filter((k) => k.startsWith("start_page"));
         const ordered = [];
         // Shared first
         if (attrs.file_id)
@@ -151,15 +155,17 @@ const normalizeCitationContent = (input) => {
             ordered.push("timestamps");
         }
         else {
-            // Document citations: fileId, start_page*, full_phrase, line_ids, (optional reasoning/value), then any extras
+            // Document citations: fileId, start_page*, full_phrase, key_span, line_ids, (optional reasoning/value), then any extras
             if (startPageKeys.includes("start_page_key"))
                 ordered.push("start_page_key");
             startPageKeys
-                .filter(k => k !== "start_page_key")
+                .filter((k) => k !== "start_page_key")
                 .sort()
-                .forEach(k => ordered.push(k));
+                .forEach((k) => ordered.push(k));
             if (attrs.full_phrase)
                 ordered.push("full_phrase");
+            if (attrs.key_span)
+                ordered.push("key_span");
             if (attrs.line_ids)
                 ordered.push("line_ids");
         }
@@ -171,12 +177,12 @@ const normalizeCitationContent = (input) => {
         // Any remaining attributes, stable + deterministic (alpha)
         const used = new Set(ordered);
         keys
-            .filter(k => !used.has(k))
+            .filter((k) => !used.has(k))
             .sort()
-            .forEach(k => ordered.push(k));
-        const rebuiltAttrs = ordered.map(k => `${k}='${attrs[k]}'`).join(" ");
+            .forEach((k) => ordered.push(k));
+        const rebuiltAttrs = ordered.map((k) => `${k}='${attrs[k]}'`).join(" ");
         return `<cite ${rebuiltAttrs} />`;
     };
-    normalized = normalized.replace(/<cite\b[\s\S]*?\/>/gm, tag => reorderCiteTagAttributes(tag));
+    normalized = normalized.replace(/<cite\b[\s\S]*?\/>/gm, (tag) => reorderCiteTagAttributes(tag));
     return normalized;
 };

package/lib/parsing/parseCitation.js

@@ -16,8 +16,13 @@ export function getCitationStatus(foundHighlight) {
         searchState?.status === "found_on_other_page" ||
         searchState?.status === "found_on_other_line" ||
         searchState?.status === "first_word_found";
-    const isVerified = searchState?.status === "found" || isFoundValueMissedFullMatch || isPartialMatch || isFullMatchWithMissedValue;
-    const isPending = searchState?.status === "pending" || searchState?.status === "loading" || !searchState;
+    const isVerified = searchState?.status === "found" ||
+        isFoundValueMissedFullMatch ||
+        isPartialMatch ||
+        isFullMatchWithMissedValue;
+    const isPending = searchState?.status === "pending" ||
+        searchState?.status === "loading" ||
+        !searchState;
     return { isVerified, isMiss, isPartialMatch, isPending };
 }
 export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVerbose) => {
@@ -30,19 +35,24 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         // Replace escaped single quotes with actual single quotes
         return trimmed.replace(/\\'/g, "'");
     };
-    const citationNumber = citationCounterRef?.current ? citationCounterRef.current++ : undefined;
+    const citationNumber = citationCounterRef?.current
+        ? citationCounterRef.current++
+        : undefined;
     const beforeCite = fragment.substring(0, fragment.indexOf("<cite"));
-    const afterCite = fragment.includes("/>") ? fragment.slice(fragment.indexOf("/>") + 2) : "";
+    const afterCite = fragment.includes("/>")
+        ? fragment.slice(fragment.indexOf("/>") + 2)
+        : "";
     const middleCite = fragment.substring(fragment.indexOf("<cite"), fragment.indexOf("/>") + 2);
     // GROUPS:
     // 1: fileId
     // 2: start_page number
     // 3: index number
     // 4: full_phrase content (escaped)
-    // 5: line_ids content
+    // 5: key_span content (escaped)
+    // 6: line_ids content
     // 6: Optional Key (value|reasoning)
     // 7: Optional Value content (escaped)
-    const citationRegex = /<cite\s+file(?:_id|Id)='(\w{0,25})'\s+start_page[\_a-zA-Z]*='page[\_a-zA-Z]*(\d+)_index_(\d+)'\s+full_phrase='((?:[^'\\]|\\.)*)'\s+line(?:_ids|Ids)='([^']+)'(?:\s+(value|reasoning)='((?:[^'\\]|\\.)*)')?\s*\/>/g;
+    const citationRegex = /<cite\s+file(?:_id|Id)='(\w{0,25})'\s+start_page[\_a-zA-Z]*='page[\_a-zA-Z]*(\d+)_index_(\d+)'\s+full_phrase='((?:[^'\\]|\\.)*)'\s+key_span='((?:[^'\\]|\\.)*)'\s+line(?:_ids|Ids)='([^']+)'(?:\s+(value|reasoning)='((?:[^'\\]|\\.)*)')?\s*\/>/g;
     const citationMatches = [...middleCite.matchAll(citationRegex)];
     const match = citationMatches?.[0];
     const rawCitationMd = match?.[0];
@@ -51,11 +61,12 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     let attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || match?.[1];
     // Use helper to handle escaped quotes inside the phrase
     let fullPhrase = cleanAndUnescape(match?.[4]);
+    let keySpan = cleanAndUnescape(match?.[5]);
     // Handle the optional attribute (value or reasoning)
     let value;
     let reasoning;
-    const optionalKey = match?.[6]; // "value" or "reasoning"
-    const optionalContent = cleanAndUnescape(match?.[7]);
+    const optionalKey = match?.[7]; // "value" or "reasoning"
+    const optionalContent = cleanAndUnescape(match?.[8]);
     if (optionalKey === "value") {
         value = optionalContent;
     }
@@ -65,12 +76,12 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     let lineIds;
     try {
         // match[5] is line_ids
-        const lineIdsString = match?.[5]?.replace(/[A-Za-z_[\](){}:]/g, "");
+        const lineIdsString = match?.[6]?.replace(/[A-Za-z_[\](){}:]/g, "");
         lineIds = lineIdsString
             ? lineIdsString
                 .split(",")
-                .map(id => (isNaN(parseInt(id)) ? undefined : parseInt(id)))
-                .filter(id => id !== undefined)
+                .map((id) => (isNaN(parseInt(id)) ? undefined : parseInt(id)))
+                .filter((id) => id !== undefined)
                 .sort((a, b) => a - b)
             : undefined;
     }
@@ -90,7 +101,8 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     let timestamps;
     if (avMatch) {
         fileId = avMatch?.[1];
-        attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || avMatch?.[1];
+        attachmentId =
+            fileId?.length === 20 ? fileId : mdAttachmentId || avMatch?.[1];
         fullPhrase = cleanAndUnescape(avMatch?.[2]);
         const timestampsString = avMatch?.[3]?.replace(/timestamps=['"]|['"]/g, "");
         const [startTime, endTime] = timestampsString?.split("-") || [];
@@ -110,6 +122,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         fileId: attachmentId,
         pageNumber,
         fullPhrase,
+        keySpan,
         citationNumber,
         lineIds,
         rawCitationMd,
@@ -139,6 +152,7 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
     // Support both camelCase and snake_case property names
     const fullPhrase = jsonCitation.fullPhrase ?? jsonCitation.full_phrase;
     const startPageKey = jsonCitation.startPageKey ?? jsonCitation.start_page_key;
+    const keySpan = jsonCitation.keySpan ?? jsonCitation.key_span;
     const rawLineIds = jsonCitation.lineIds ?? jsonCitation.line_ids;
     const fileId = jsonCitation.fileId ?? jsonCitation.file_id;
     const reasoning = jsonCitation.reasoning;
@@ -155,13 +169,16 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
         }
     }
     // Sort lineIds if present
-    const lineIds = rawLineIds?.length ? [...rawLineIds].sort((a, b) => a - b) : undefined;
+    const lineIds = rawLineIds?.length
+        ? [...rawLineIds].sort((a, b) => a - b)
+        : undefined;
     const citation = {
         fileId,
         pageNumber,
         fullPhrase,
         citationNumber,
         lineIds,
+        keySpan,
         reasoning,
         value,
     };
@@ -176,6 +193,8 @@ const hasCitationProperties = (item) => typeof item === "object" &&
         "full_phrase" in item ||
         "startPageKey" in item ||
         "start_page_key" in item ||
+        "keySpan" in item ||
+        "key_span" in item ||
         "lineIds" in item ||
         "line_ids" in item);
 /**
@@ -220,7 +239,9 @@ const findJsonCitationsInObject = (obj, found) => {
         found.push(...items);
     }
     if (obj.citations && isJsonCitationFormat(obj.citations)) {
-        const items = Array.isArray(obj.citations) ? obj.citations : [obj.citations];
+        const items = Array.isArray(obj.citations)
+            ? obj.citations
+            : [obj.citations];
         found.push(...items);
     }
     // Recurse into object properties

package/lib/prompts/citationPrompts.d.ts

@@ -1,5 +1,5 @@
-export declare const CITATION_MARKDOWN_SYNTAX_PROMPT = "\nCitation syntax to use within Markdown:\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text /> (remember to escape quotes and newlines inside the full_phrase to remain as valid JSON)' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />\n\n\u2022 Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.\n\u2022 start_page_key, full_phrase, and line_ids are required for each citation.\n\u2022 Infer line_ids, as we only provide the first, last, and every 5th line. When copying a previous <cite />, use the full info from the previous citation without changing the start_page_key, line_ids, or any other <cite /> attributes.\n\u2022 Use refer to line_ids inclusively, and use a range (or single) for each citation, split multiple sequential line_ids into multiple citations.\n\u2022 These citations will be replaced and displayed in-line as a numeric element (e.g. [1]), the markdown preceding <cite /> should read naturally with only one <cite /> per sentence with rare exceptions for two <cite /> in a sentence. <cite /> often present best at the end of the sentence, and are not grouped at the end of the document.\n\u2022 The full_phrase should be the exact verbatim text of the phrase or paragraph from the source document to support the insight or idea.\n\u2022 We do NOT put the full_phrase inside <cite ...></cite>; we only use full_phrase inside the full_phrase attribute.\n";
-export declare const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = "\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' full_phrase='the verbatim text of the phrase (remember to escape quotes and newlines inside the full_phrase to remain as valid JSON)' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' reasoning='the logic connecting the form section requirements to the supporting source citation' />\n\u2022 These citations are displayed in-line or in the relevant list item, and are not grouped at the end of the document.\n";
+export declare const CITATION_MARKDOWN_SYNTAX_PROMPT = "\nCitation syntax to use within Markdown:\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim value or words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />\n\n\u2022 Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.\n\u2022 start_page_key, full_phrase, and line_ids are required for each citation.\n\u2022 Infer line_ids, as we only provide the first, last, and every 5th line. When copying a previous <cite />, use the full info from the previous citation without changing the start_page_key, line_ids, or any other <cite /> attributes.\n\u2022 Use refer to line_ids inclusively, and use a range (or single) for each citation, split multiple sequential line_ids into multiple citations.\n\u2022 These citations will be replaced and displayed in-line as a numeric element (e.g. [1]), the markdown preceding <cite /> should read naturally with only one <cite /> per sentence with rare exceptions for two <cite /> in a sentence. <cite /> often present best at the end of the sentence, and are not grouped at the end of the document.\n\u2022 The full_phrase should be the exact verbatim text of the phrase or paragraph from the source document to support the insight or idea.\n\u2022 We do NOT put the full_phrase inside <cite ...></cite>; we only use full_phrase inside the full_phrase attribute.\n";
+export declare const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = "\n\u2022 To support any ideas or information that requires a citation from the provided content, use the following citation syntax:\n<cite file_id='file_id' full_phrase='the verbatim text of the phrase; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' reasoning='the logic connecting the form section requirements to the supporting source citation' />\n\u2022 These citations are displayed in-line or in the relevant list item, and are not grouped at the end of the document.\n";
 export interface WrapSystemPromptOptions {
     /** The original system prompt to wrap with citation instructions */
     systemPrompt: string;
@@ -13,7 +13,7 @@ export interface WrapCitationPromptOptions {
     /** The original user prompt */
     userPrompt: string;
     /** The extracted file text with metadata (from uploadFile response). Can be a single string or array for multiple files. */
-    fileDeepText?: string | string[];
+    deepTextPromptPortion?: string | string[];
     /** Whether to use audio/video citation format (with timestamps) instead of text-based (with line IDs) */
     isAudioVideo?: boolean;
 }
@@ -54,14 +54,14 @@ export declare function wrapSystemCitationPrompt(options: WrapSystemPromptOption
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Analyze this document and summarize it.",
- *   fileDeepText, // from uploadFile response
+ *   deepTextPromptPortion, // from uploadFile response
  * });
  *
  * // Multiple files
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Compare these documents.",
- *   fileDeepText: [fileDeepText1, fileDeepText2], // array of file texts
+ *   deepTextPromptPortion: [deepTextPromptPortion1, deepTextPromptPortion2], // array of file texts
  * });
  *
  * // Use enhanced prompts with your LLM
@@ -92,6 +92,10 @@ export declare const CITATION_JSON_OUTPUT_FORMAT: {
             type: string;
             description: string;
         };
+        keySpan: {
+            type: string;
+            description: string;
+        };
         lineIds: {
             type: string;
             items: {

package/lib/prompts/citationPrompts.js

@@ -1,7 +1,7 @@
 export const CITATION_MARKDOWN_SYNTAX_PROMPT = `
 Citation syntax to use within Markdown:
 • To support any ideas or information that requires a citation from the provided content, use the following citation syntax:
-<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text /> (remember to escape quotes and newlines inside the full_phrase to remain as valid JSON)' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />
+<cite file_id='file_id' start_page_key='page_number_PAGE_index_INDEX' full_phrase='the verbatim text of the terse phrase inside <file_text />; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' key_span='the verbatim value or words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />
 
 • Very important: for page numbers, only use the page number and page index info from the page_number_PAGE_index_INDEX format (e.g. <page_number_1_index_0>) and never from the contents inside the page.
 • start_page_key, full_phrase, and line_ids are required for each citation.
@@ -13,7 +13,7 @@ Citation syntax to use within Markdown:
 `;
 export const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = `
 • To support any ideas or information that requires a citation from the provided content, use the following citation syntax:
-<cite file_id='file_id' full_phrase='the verbatim text of the phrase (remember to escape quotes and newlines inside the full_phrase to remain as valid JSON)' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' reasoning='the logic connecting the form section requirements to the supporting source citation' />
+<cite file_id='file_id' full_phrase='the verbatim text of the phrase; remember to escape quotes and newlines inside the full_phrase to remain as valid JSON' timestamps='HH:MM:SS.SSS-HH:MM:SS.SSS' reasoning='the logic connecting the form section requirements to the supporting source citation' />
 • These citations are displayed in-line or in the relevant list item, and are not grouped at the end of the document.
 `;
 /**
@@ -35,8 +35,10 @@ export const AV_CITATION_MARKDOWN_SYNTAX_PROMPT = `
  * ```
  */
 export function wrapSystemCitationPrompt(options) {
-    const { systemPrompt, isAudioVideo = false, prependCitationInstructions = false } = options;
-    const citationPrompt = isAudioVideo ? AV_CITATION_MARKDOWN_SYNTAX_PROMPT : CITATION_MARKDOWN_SYNTAX_PROMPT;
+    const { systemPrompt, isAudioVideo = false, prependCitationInstructions = false, } = options;
+    const citationPrompt = isAudioVideo
+        ? AV_CITATION_MARKDOWN_SYNTAX_PROMPT
+        : CITATION_MARKDOWN_SYNTAX_PROMPT;
     if (prependCitationInstructions) {
         return `${citationPrompt.trim()}
 
@@ -59,14 +61,14 @@ ${citationPrompt.trim()}`;
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Analyze this document and summarize it.",
- *   fileDeepText, // from uploadFile response
+ *   deepTextPromptPortion, // from uploadFile response
  * });
  *
  * // Multiple files
  * const { enhancedSystemPrompt, enhancedUserPrompt } = wrapCitationPrompt({
  *   systemPrompt: "You are a helpful assistant.",
  *   userPrompt: "Compare these documents.",
- *   fileDeepText: [fileDeepText1, fileDeepText2], // array of file texts
+ *   deepTextPromptPortion: [deepTextPromptPortion1, deepTextPromptPortion2], // array of file texts
  * });
  *
  * // Use enhanced prompts with your LLM
@@ -79,21 +81,23 @@ ${citationPrompt.trim()}`;
  * ```
  */
 export function wrapCitationPrompt(options) {
-    const { systemPrompt, userPrompt, fileDeepText, isAudioVideo = false } = options;
+    const { systemPrompt, userPrompt, deepTextPromptPortion, isAudioVideo = false, } = options;
     const enhancedSystemPrompt = wrapSystemCitationPrompt({
         systemPrompt,
         isAudioVideo,
     });
     // Build enhanced user prompt with file content if provided
     let enhancedUserPrompt = userPrompt;
-    if (fileDeepText) {
-        const fileTexts = Array.isArray(fileDeepText) ? fileDeepText : [fileDeepText];
+    if (deepTextPromptPortion) {
+        const fileTexts = Array.isArray(deepTextPromptPortion)
+            ? deepTextPromptPortion
+            : [deepTextPromptPortion];
         const fileContent = fileTexts
             .map((text, index) => {
             if (fileTexts.length === 1) {
-                return `<file_text>\n${text}\n</file_text>`;
+                return `\n${text}`;
             }
-            return `<file_text file_index="${index + 1}">\n${text}\n</file_text>`;
+            return `\n${text}`;
         })
             .join("\n\n");
         enhancedUserPrompt = `${fileContent}\n\n${userPrompt}`;
@@ -119,13 +123,24 @@ export const CITATION_JSON_OUTPUT_FORMAT = {
             type: "string",
             description: "The verbatim text of the terse phrase inside <file_text /> to support the value description (if there is a detected OCR correction, use the corrected text)",
         },
+        keySpan: {
+            type: "string",
+            description: "the verbatim value or words within fullPhrase that best support the citation",
+        },
         lineIds: {
             type: "array",
             items: { type: "number" },
             description: "Infer lineIds, as we only provide the first, last, and every 5th line. Provide inclusive lineIds for the fullPhrase.",
         },
     },
-    required: ["fileId", "startPageKey", "reasoning", "fullPhrase", "lineIds"],
+    required: [
+        "fileId",
+        "startPageKey",
+        "reasoning",
+        "fullPhrase",
+        "keySpan",
+        "lineIds",
+    ],
 };
 export const CITATION_AV_BASED_JSON_OUTPUT_FORMAT = {
     type: "object",

package/lib/types/citation.d.ts

@@ -1,6 +1,5 @@
 import { type ScreenBox } from "./boxes";
 import { type FoundHighlightLocation } from "./foundHighlight";
-export declare const VERIFICATION_VERSION_NUMBER = "0.4.37";
 export type OutputImageFormat = "jpeg" | "png" | "avif" | undefined | null;
 export declare const DEFAULT_OUTPUT_IMAGE_FORMAT: "avif";
 export interface VerifyCitationResponse {
@@ -19,6 +18,7 @@ export interface VerifyCitationRequest {
 export interface Citation {
     fileId?: string;
     fullPhrase?: string | null;
+    keySpan?: string | null;
     value?: string | null;
     startPageKey?: string | null;
     pageNumber?: number | null;
@@ -33,8 +33,6 @@ export interface Citation {
     fragmentContext?: string | null;
     rawCitationMd?: string;
     beforeCite?: string;
-    formFieldName?: string | null;
-    formFieldValue?: string | null;
 }
 export interface CitationStatus {
     isVerified: boolean;

package/lib/types/citation.js

@@ -1,2 +1 @@
-export const VERIFICATION_VERSION_NUMBER = "0.4.37";
 export const DEFAULT_OUTPUT_IMAGE_FORMAT = "avif";

package/lib/types/foundHighlight.d.ts

@@ -1,4 +1,4 @@
-import { VERIFICATION_VERSION_NUMBER, type Citation } from "./citation";
+import { type Citation } from "./citation";
 import { type SearchState } from "./search";
 import { type PdfSpaceItem } from "./boxes";
 export declare const NOT_FOUND_HIGHLIGHT_INDEX = -1;
@@ -18,6 +18,6 @@ export interface FoundHighlightLocation {
     matchSnippet?: string | null;
     pdfSpaceItem?: PdfSpaceItem;
     verificationImageBase64?: string | null;
-    source?: typeof VERIFICATION_VERSION_NUMBER | string | null;
+    source?: string | null;
     verifiedAt?: Date;
 }

package/lib/types/index.d.ts

@@ -4,7 +4,7 @@
  * @packageDocumentation
  */
 export type { Citation, CitationStatus, VerifyCitationRequest, VerifyCitationResponse, OutputImageFormat, } from "./citation.js";
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
+export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
 export type { FoundHighlightLocation } from "./foundHighlight.js";
 export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./foundHighlight.js";
 export type { SearchState, SearchStatus } from "./search.js";

package/lib/types/index.js

@@ -3,5 +3,5 @@
  *
  * @packageDocumentation
  */
-export { VERIFICATION_VERSION_NUMBER, DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
+export { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./citation.js";
 export { NOT_FOUND_HIGHLIGHT_INDEX, PENDING_HIGHLIGHT_INDEX, BLANK_HIGHLIGHT_LOCATION, deterministicIdFromHighlightLocation, } from "./foundHighlight.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@deepcitation/deepcitation-js",
-    "version": "1.0.4",
+    "version": "1.0.6",
     "description": "DeepCitation JavaScript SDK for deterministic AI citation verification",
     "type": "module",
     "private": false,