@deepcitation/deepcitation-js 1.1.16 → 1.1.18

package/lib/client/DeepCitation.d.ts

@@ -10,7 +10,7 @@ import type { CitationInput, ConvertFileInput, ConvertFileResponse, DeepCitation
  * const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
  *
  * // Upload a file
- * const { fileId, promptContent } = await dc.uploadFile(file);
+ * const { attachmentId, promptContent } = await dc.uploadFile(file);
  *
  * // Include promptContent in your LLM messages
  * const response = await llm.chat({
@@ -22,7 +22,7 @@ import type { CitationInput, ConvertFileInput, ConvertFileResponse, DeepCitation
  *
  * // Verify citations in the LLM output
  * const citations = getAllCitationsFromLlmOutput(response);
- * const verified = await dc.verifyCitations(fileId, citations);
+ * const verified = await dc.verifyCitations(attachmentId, citations);
  * ```
  */
 export declare class DeepCitation {
@@ -45,7 +45,7 @@ export declare class DeepCitation {
      *
      * @param file - The file to upload (File, Blob, or Buffer)
      * @param options - Optional upload options
-     * @returns Upload response with fileId and extracted text
+     * @returns Upload response with attachmentId and extracted text
      *
      * @example
      * ```typescript
@@ -86,8 +86,8 @@ export declare class DeepCitation {
      * });
      *
      * // Then prepare the file for verification
-     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
-     *   fileId: result.fileId
+     * const { deepTextPromptPortion, attachmentId } = await dc.prepareConvertedFile({
+     *   attachmentId: result.attachmentId
      * });
      * ```
      */
@@ -96,8 +96,8 @@ export declare class DeepCitation {
      * Prepare a previously converted file for citation verification.
      * 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
+     * @param options - Options with attachmentId from convertFile
+     * @returns Upload response with attachmentId and extracted text
      *
      * @example
      * ```typescript
@@ -105,8 +105,8 @@ export declare class DeepCitation {
      * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
      *
      * // Then prepare it for verification
-     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
-     *   fileId: converted.fileId
+     * const { deepTextPromptPortion, attachmentId } = await dc.prepareConvertedFile({
+     *   attachmentId: converted.attachmentId
      * });
      *
      * // Use deepTextPromptPortion in your LLM prompt...
@@ -117,7 +117,7 @@ export declare class DeepCitation {
      * 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
+     * @param files - Array of files to upload with optional filenames and attachmentIds
      * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
      *
      * @example
@@ -142,7 +142,7 @@ export declare class DeepCitation {
     /**
      * Verify citations against a previously uploaded file.
      *
-     * @param fileId - The file ID returned from uploadFile
+     * @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
@@ -152,7 +152,7 @@ export declare class DeepCitation {
      * import { getAllCitationsFromLlmOutput } from '@deepcitation/deepcitation-js';
      *
      * const citations = getAllCitationsFromLlmOutput(llmResponse);
-     * const verified = await dc.verifyCitations(fileId, citations);
+     * const verified = await dc.verifyCitations(attachmentId, citations);
      *
      * for (const [key, result] of Object.entries(verified.verifications)) {
      *   console.log(key, result.searchState?.status);
@@ -160,7 +160,7 @@ export declare class DeepCitation {
      * }
      * ```
      */
-    verifyCitations(fileId: string, citations: CitationInput, options?: VerifyCitationsOptions): Promise<VerifyCitationsResponse>;
+    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.

package/lib/client/DeepCitation.js

@@ -31,7 +31,7 @@ async function extractErrorMessage(response, fallbackAction) {
  * const dc = new DeepCitation({ apiKey: process.env.DEEPCITATION_API_KEY });
  *
  * // Upload a file
- * const { fileId, promptContent } = await dc.uploadFile(file);
+ * const { attachmentId, promptContent } = await dc.uploadFile(file);
  *
  * // Include promptContent in your LLM messages
  * const response = await llm.chat({
@@ -43,7 +43,7 @@ async function extractErrorMessage(response, fallbackAction) {
  *
  * // Verify citations in the LLM output
  * const citations = getAllCitationsFromLlmOutput(response);
- * const verified = await dc.verifyCitations(fileId, citations);
+ * const verified = await dc.verifyCitations(attachmentId, citations);
  * ```
  */
 export class DeepCitation {
@@ -72,7 +72,7 @@ export class DeepCitation {
      *
      * @param file - The file to upload (File, Blob, or Buffer)
      * @param options - Optional upload options
-     * @returns Upload response with fileId and extracted text
+     * @returns Upload response with attachmentId and extracted text
      *
      * @example
      * ```typescript
@@ -89,8 +89,8 @@ export class DeepCitation {
         const { blob, name } = toBlob(file, options?.filename);
         const formData = new FormData();
         formData.append("file", blob, name);
-        if (options?.fileId)
-            formData.append("fileId", options.fileId);
+        if (options?.attachmentId)
+            formData.append("attachmentId", options.attachmentId);
         if (options?.filename)
             formData.append("filename", options.filename);
         const response = await fetch(`${this.apiUrl}/prepareFile`, {
@@ -130,14 +130,14 @@ export class DeepCitation {
      * });
      *
      * // Then prepare the file for verification
-     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
-     *   fileId: result.fileId
+     * const { deepTextPromptPortion, attachmentId } = await dc.prepareConvertedFile({
+     *   attachmentId: result.attachmentId
      * });
      * ```
      */
     async convertToPdf(input) {
         const inputObj = typeof input === "string" ? { url: input } : input;
-        const { url, file, filename, fileId } = inputObj;
+        const { url, file, filename, attachmentId } = inputObj;
         if (!url && !file) {
             throw new Error("Either url or file must be provided");
         }
@@ -149,15 +149,15 @@ export class DeepCitation {
                     Authorization: `Bearer ${this.apiKey}`,
                     "Content-Type": "application/json",
                 },
-                body: JSON.stringify({ url, filename, fileId }),
+                body: JSON.stringify({ url, filename, attachmentId }),
             });
         }
         else {
             const { blob, name } = toBlob(file, filename);
             const formData = new FormData();
             formData.append("file", blob, name);
-            if (fileId)
-                formData.append("fileId", fileId);
+            if (attachmentId)
+                formData.append("attachmentId", attachmentId);
             if (filename)
                 formData.append("filename", filename);
             response = await fetch(`${this.apiUrl}/convertFile`, {
@@ -175,8 +175,8 @@ export class DeepCitation {
      * Prepare a previously converted file for citation verification.
      * 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
+     * @param options - Options with attachmentId from convertFile
+     * @returns Upload response with attachmentId and extracted text
      *
      * @example
      * ```typescript
@@ -184,8 +184,8 @@ export class DeepCitation {
      * const converted = await dc.convertToPdf({ url: "https://example.com/article" });
      *
      * // Then prepare it for verification
-     * const { deepTextPromptPortion, fileId } = await dc.prepareConvertedFile({
-     *   fileId: converted.fileId
+     * const { deepTextPromptPortion, attachmentId } = await dc.prepareConvertedFile({
+     *   attachmentId: converted.attachmentId
      * });
      *
      * // Use deepTextPromptPortion in your LLM prompt...
@@ -199,7 +199,7 @@ export class DeepCitation {
                 "Content-Type": "application/json",
             },
             body: JSON.stringify({
-                fileId: options.fileId,
+                attachmentId: options.attachmentId,
             }),
         });
         if (!response.ok) {
@@ -211,7 +211,7 @@ export class DeepCitation {
      * 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
+     * @param files - Array of files to upload with optional filenames and attachmentIds
      * @returns Object containing fileDataParts for verification and deepTextPromptPortion for LLM
      *
      * @example
@@ -237,14 +237,14 @@ export class DeepCitation {
             return { fileDataParts: [], deepTextPromptPortion: [] };
         }
         // Upload all files in parallel
-        const uploadPromises = files.map(({ file, filename, fileId }) => this.uploadFile(file, { filename, fileId }).then((result) => ({
+        const uploadPromises = files.map(({ file, filename, attachmentId }) => this.uploadFile(file, { filename, attachmentId }).then((result) => ({
             result,
             filename,
         })));
         const uploadResults = await Promise.all(uploadPromises);
         // Extract file data parts with deepTextPromptPortion included (single source of truth)
         const fileDataParts = uploadResults.map(({ result, filename }) => ({
-            fileId: result.fileId,
+            attachmentId: result.attachmentId,
             deepTextPromptPortion: result.deepTextPromptPortion,
             filename: filename || result.metadata?.filename,
         }));
@@ -255,7 +255,7 @@ export class DeepCitation {
     /**
      * Verify citations against a previously uploaded file.
      *
-     * @param fileId - The file ID returned from uploadFile
+     * @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
@@ -265,7 +265,7 @@ export class DeepCitation {
      * import { getAllCitationsFromLlmOutput } from '@deepcitation/deepcitation-js';
      *
      * const citations = getAllCitationsFromLlmOutput(llmResponse);
-     * const verified = await dc.verifyCitations(fileId, citations);
+     * const verified = await dc.verifyCitations(attachmentId, citations);
      *
      * for (const [key, result] of Object.entries(verified.verifications)) {
      *   console.log(key, result.searchState?.status);
@@ -273,7 +273,7 @@ export class DeepCitation {
      * }
      * ```
      */
-    async verifyCitations(fileId, citations, options) {
+    async verifyCitations(attachmentId, citations, options) {
         // Normalize citations to a map with citation keys
         const citationMap = {};
         if (Array.isArray(citations)) {
@@ -301,7 +301,7 @@ export class DeepCitation {
         const requestUrl = `${this.apiUrl}/verifyCitations`;
         const requestBody = {
             data: {
-                fileId,
+                attachmentId,
                 citations: citationMap,
                 outputImageFormat: options?.outputImageFormat || "avif",
             },
@@ -348,20 +348,20 @@ export class DeepCitation {
         if (Object.keys(citations).length === 0) {
             return { verifications: {} };
         }
-        // Group citations by fileId
-        const citationsByFile = new Map();
+        // Group citations by attachmentId
+        const citationsByAttachment = new Map();
         for (const [key, citation] of Object.entries(citations)) {
-            const fileId = citation.fileId || "";
-            if (!citationsByFile.has(fileId)) {
-                citationsByFile.set(fileId, {});
+            const attachmentId = citation.attachmentId || "";
+            if (!citationsByAttachment.has(attachmentId)) {
+                citationsByAttachment.set(attachmentId, {});
             }
-            citationsByFile.get(fileId)[key] = citation;
+            citationsByAttachment.get(attachmentId)[key] = citation;
         }
         // Verify all files in parallel
         const verificationPromises = [];
-        for (const [fileId, fileCitations] of citationsByFile) {
-            if (fileId) {
-                verificationPromises.push(this.verifyCitations(fileId, fileCitations, { outputImageFormat }));
+        for (const [attachmentId, fileCitations] of citationsByAttachment) {
+            if (attachmentId) {
+                verificationPromises.push(this.verifyCitations(attachmentId, fileCitations, { outputImageFormat }));
             }
         }
         const results = await Promise.all(verificationPromises);

package/lib/client/types.d.ts

@@ -12,8 +12,8 @@ export interface DeepCitationConfig {
  * Response from uploading a file for citation verification
  */
 export interface UploadFileResponse {
-    /** The file ID assigned by DeepCitation (custom or auto-generated) */
-    fileId: string;
+    /** 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 */
@@ -41,8 +41,8 @@ export interface UploadFileResponse {
  * Options for file upload
  */
 export interface UploadFileOptions {
-    /** Optional custom file ID to use instead of auto-generated one */
-    fileId?: string;
+    /** Optional custom attachment ID to use instead of auto-generated one */
+    attachmentId?: string;
     /** Optional custom filename (uses File.name if not provided) */
     filename?: string;
 }
@@ -72,15 +72,15 @@ export interface FileInput {
     file: File | Blob | Buffer;
     /** Optional filename */
     filename?: string;
-    /** Optional custom file ID */
-    fileId?: string;
+    /** Optional custom attachment ID */
+    attachmentId?: string;
 }
 /**
  * File reference returned from prepareFiles
  */
 export interface FileDataPart {
-    /** The file ID assigned by DeepCitation */
-    fileId: string;
+    /** 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 */
@@ -120,15 +120,15 @@ export interface ConvertFileInput {
     file?: File | Blob | Buffer;
     /** Optional custom filename for the converted PDF */
     filename?: string;
-    /** Optional custom file ID */
-    fileId?: string;
+    /** Optional custom attachment ID */
+    attachmentId?: string;
 }
 /**
  * Response from convertFile
  */
 export interface ConvertFileResponse {
-    /** The file ID assigned by DeepCitation. Pass this to prepareConvertedFile(). */
-    fileId: string;
+    /** The attachment ID assigned by DeepCitation. Pass this to prepareConvertedFile(). */
+    attachmentId: string;
     /** Metadata about the conversion */
     metadata: {
         /** Original filename before conversion */
@@ -149,6 +149,6 @@ export interface ConvertFileResponse {
  * Options for processing a converted file
  */
 export interface PrepareConvertedFileOptions {
-    /** The file ID from a previous convertFile call */
-    fileId: string;
+    /** The attachment ID from a previous convertFile call */
+    attachmentId: string;
 }

package/lib/index.d.ts

@@ -4,7 +4,7 @@
  */
 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, groupCitationsByFileId, groupCitationsByFileIdObject, } from "./parsing/parseCitation.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";

package/lib/index.js

@@ -5,7 +5,7 @@
 // Client
 export { DeepCitation } from "./client/index.js";
 // Parsing
-export { parseCitation, getCitationStatus, getAllCitationsFromLlmOutput, groupCitationsByFileId, groupCitationsByFileIdObject, } from "./parsing/parseCitation.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 { DEFAULT_OUTPUT_IMAGE_FORMAT } from "./types/citation.js";

package/lib/parsing/normalizeCitation.js

@@ -1,6 +1,6 @@
 export const removeCitations = (pageText, leaveValueBehind) => {
-    const citationRegex = /<cite\s+fileId='(\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;
-    return pageText.replace(citationRegex, (match, fileId, pageNumber, index, fullPhrase, lineIds, value) => {
+    const citationRegex = /<cite\s+(?:fileId|attachmentId)='(\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;
+    return pageText.replace(citationRegex, (match, attachmentId, pageNumber, index, fullPhrase, lineIds, value) => {
         //it is still value= so we need to remove the value=
         if (leaveValueBehind) {
             return value?.replace(/value=['"]|['"]/g, "") || "";
@@ -53,7 +53,7 @@ const normalizeCitationContent = (input) => {
             key === "start_pageKey" ||
             key === "start_page_key")
             return "start_page_key";
-        if (key === "fileID" || key === "fileId" || key === "file_id")
+        if (key === "fileID" || key === "fileId" || key === "file_id" || key === "attachmentId" || key === "attachment_id")
             return "file_id";
         if (key === "keySpan" || key === "key_span")
             return "key_span";
@@ -71,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|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;
+    const textAttributeRegex = /(fullPhrase|full_phrase|keySpan|key_span|reasoning|value)\s*=\s*(['"])([\s\S]*?)(?=\s+(?:line_ids|lineIds|timestamps|fileId|file_id|attachmentId|attachment_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

package/lib/parsing/parseCitation.d.ts

@@ -27,53 +27,53 @@ export declare const getAllCitationsFromLlmOutput: (llmOutput: any) => {
     [key: string]: Citation;
 };
 /**
- * Groups citations by their fileId for multi-file verification scenarios.
+ * 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 fileId to dictionary of citations from that file
+ * @returns Map of attachmentId to dictionary of citations from that file
  *
  * @example
  * ```typescript
  * const citations = getAllCitationsFromLlmOutput(response.content);
- * const citationsByFile = groupCitationsByFileId(citations);
+ * const citationsByAttachment = groupCitationsByAttachmentId(citations);
  *
  * // Verify citations for each file
- * for (const [fileId, fileCitations] of citationsByFile) {
- *   const verified = await dc.verifyCitations(fileId, fileCitations);
+ * for (const [attachmentId, fileCitations] of citationsByAttachment) {
+ *   const verified = await dc.verifyCitations(attachmentId, fileCitations);
  *   // Process verification results...
  * }
  * ```
  */
-export declare function groupCitationsByFileId(citations: Citation[] | {
+export declare function groupCitationsByAttachmentId(citations: Citation[] | {
     [key: string]: Citation;
 }): Map<string, {
     [key: string]: Citation;
 }>;
 /**
- * Groups citations by their fileId and returns as a plain object.
- * Alternative to groupCitationsByFileId that returns a plain object instead of a Map.
+ * 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 fileId keys mapping to citation dictionaries
+ * @returns Object with attachmentId keys mapping to citation dictionaries
  *
  * @example
  * ```typescript
  * const citations = getAllCitationsFromLlmOutput(response.content);
- * const citationsByFile = groupCitationsByFileIdObject(citations);
+ * const citationsByAttachment = groupCitationsByAttachmentIdObject(citations);
  *
  * // Verify citations for each file using Promise.all
- * const verificationPromises = Object.entries(citationsByFile).map(
- *   ([fileId, fileCitations]) => dc.verifyCitations(fileId, fileCitations)
+ * const verificationPromises = Object.entries(citationsByAttachment).map(
+ *   ([attachmentId, fileCitations]) => dc.verifyCitations(attachmentId, fileCitations)
  * );
  * const results = await Promise.all(verificationPromises);
  * ```
  */
-export declare function groupCitationsByFileIdObject(citations: Citation[] | {
+export declare function groupCitationsByAttachmentIdObject(citations: Citation[] | {
     [key: string]: Citation;
 }): {
-    [fileId: string]: {
+    [attachmentId: string]: {
         [key: string]: Citation;
     };
 };

package/lib/parsing/parseCitation.js

@@ -88,7 +88,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         : "";
     const middleCite = fragment.substring(fragment.indexOf("<cite"), fragment.indexOf("/>") + 2);
     // GROUPS:
-    // 1: fileId
+    // 1: attachmentId
     // 2: start_page number
     // 3: index number
     // 4: full_phrase content (escaped)
@@ -101,8 +101,8 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     const match = citationMatches?.[0];
     const pageNumber = match?.[2] ? parseInt(match?.[2]) : undefined;
     const pageIndex = match?.[3] ? parseInt(match?.[3]) : undefined;
-    let fileId = match?.[1];
-    let attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || fileId;
+    let rawAttachmentId = match?.[1];
+    let attachmentId = rawAttachmentId?.length === 20 ? rawAttachmentId : mdAttachmentId || rawAttachmentId;
     // Use helper to handle escaped quotes inside the phrase
     let fullPhrase = cleanAndUnescape(match?.[4]);
     let keySpan = cleanAndUnescape(match?.[5]);
@@ -128,7 +128,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
             console.error("Error parsing lineIds", e);
     }
     // GROUPS for AV:
-    // 1: fileId
+    // 1: attachmentId
     // 2: full_phrase content (escaped)
     // 3: timestamps content
     // 4: Optional Key (value|reasoning)
@@ -138,8 +138,8 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
     const avMatch = avCitationMatches?.[0];
     let timestamps;
     if (avMatch) {
-        fileId = avMatch?.[1];
-        attachmentId = fileId?.length === 20 ? fileId : mdAttachmentId || fileId;
+        rawAttachmentId = avMatch?.[1];
+        attachmentId = rawAttachmentId?.length === 20 ? rawAttachmentId : mdAttachmentId || rawAttachmentId;
         fullPhrase = cleanAndUnescape(avMatch?.[2]);
         const timestampsString = avMatch?.[3]?.replace(/timestamps=['"]|['"]/g, "");
         const [startTime, endTime] = timestampsString?.split("-") || [];
@@ -154,7 +154,7 @@ export const parseCitation = (fragment, mdAttachmentId, citationCounterRef, isVe
         timestamps = { startTime, endTime };
     }
     const citation = {
-        fileId: attachmentId,
+        attachmentId: attachmentId,
         pageNumber,
         startPageKey: `page_number_${pageNumber || 1}_index_${pageIndex || 0}`,
         fullPhrase,
@@ -188,7 +188,7 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
     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 attachmentId = jsonCitation.attachmentId ?? jsonCitation.attachment_id ?? jsonCitation.fileId ?? jsonCitation.file_id;
     const reasoning = jsonCitation.reasoning;
     const value = jsonCitation.value;
     if (!fullPhrase) {
@@ -215,7 +215,7 @@ const parseJsonCitation = (jsonCitation, citationNumber) => {
         ? [...rawLineIds].sort((a, b) => a - b)
         : undefined;
     const citation = {
-        fileId,
+        attachmentId,
         pageNumber,
         fullPhrase,
         citationNumber,
@@ -363,71 +363,71 @@ export const getAllCitationsFromLlmOutput = (llmOutput) => {
     return citations;
 };
 /**
- * Groups citations by their fileId for multi-file verification scenarios.
+ * 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 fileId to dictionary of citations from that file
+ * @returns Map of attachmentId to dictionary of citations from that file
  *
  * @example
  * ```typescript
  * const citations = getAllCitationsFromLlmOutput(response.content);
- * const citationsByFile = groupCitationsByFileId(citations);
+ * const citationsByAttachment = groupCitationsByAttachmentId(citations);
  *
  * // Verify citations for each file
- * for (const [fileId, fileCitations] of citationsByFile) {
- *   const verified = await dc.verifyCitations(fileId, fileCitations);
+ * for (const [attachmentId, fileCitations] of citationsByAttachment) {
+ *   const verified = await dc.verifyCitations(attachmentId, fileCitations);
  *   // Process verification results...
  * }
  * ```
  */
-export function groupCitationsByFileId(citations) {
+export function groupCitationsByAttachmentId(citations) {
     const grouped = new Map();
     // Normalize input to entries
     const entries = Array.isArray(citations)
         ? citations.map((c, idx) => [generateCitationKey(c) || String(idx + 1), c])
         : Object.entries(citations);
     for (const [key, citation] of entries) {
-        const fileId = citation.fileId || "";
-        if (!grouped.has(fileId)) {
-            grouped.set(fileId, {});
+        const attachmentId = citation.attachmentId || "";
+        if (!grouped.has(attachmentId)) {
+            grouped.set(attachmentId, {});
         }
-        grouped.get(fileId)[key] = citation;
+        grouped.get(attachmentId)[key] = citation;
     }
     return grouped;
 }
 /**
- * Groups citations by their fileId and returns as a plain object.
- * Alternative to groupCitationsByFileId that returns a plain object instead of a Map.
+ * 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 fileId keys mapping to citation dictionaries
+ * @returns Object with attachmentId keys mapping to citation dictionaries
  *
  * @example
  * ```typescript
  * const citations = getAllCitationsFromLlmOutput(response.content);
- * const citationsByFile = groupCitationsByFileIdObject(citations);
+ * const citationsByAttachment = groupCitationsByAttachmentIdObject(citations);
  *
  * // Verify citations for each file using Promise.all
- * const verificationPromises = Object.entries(citationsByFile).map(
- *   ([fileId, fileCitations]) => dc.verifyCitations(fileId, fileCitations)
+ * const verificationPromises = Object.entries(citationsByAttachment).map(
+ *   ([attachmentId, fileCitations]) => dc.verifyCitations(attachmentId, fileCitations)
  * );
  * const results = await Promise.all(verificationPromises);
  * ```
  */
-export function groupCitationsByFileIdObject(citations) {
+export function groupCitationsByAttachmentIdObject(citations) {
     const grouped = {};
     // Normalize input to entries
     const entries = Array.isArray(citations)
         ? citations.map((c, idx) => [generateCitationKey(c) || String(idx + 1), c])
         : Object.entries(citations);
     for (const [key, citation] of entries) {
-        const fileId = citation.fileId || "";
-        if (!grouped[fileId]) {
-            grouped[fileId] = {};
+        const attachmentId = citation.attachmentId || "";
+        if (!grouped[attachmentId]) {
+            grouped[attachmentId] = {};
         }
-        grouped[fileId][key] = citation;
+        grouped[attachmentId][key] = citation;
     }
     return grouped;
 }

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' key_span='the verbatim 1-3 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 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='attachment_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 1-3 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='attachment_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;
@@ -77,7 +77,7 @@ export declare function wrapCitationPrompt(options: WrapCitationPromptOptions):
 export declare const CITATION_JSON_OUTPUT_FORMAT: {
     type: string;
     properties: {
-        fileId: {
+        attachmentId: {
             type: string;
         };
         startPageKey: {
@@ -109,7 +109,7 @@ export declare const CITATION_JSON_OUTPUT_FORMAT: {
 export declare const CITATION_AV_BASED_JSON_OUTPUT_FORMAT: {
     type: string;
     properties: {
-        fileId: {
+        attachmentId: {
             type: string;
         };
         startPageKey: {

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' key_span='the verbatim 1-3 words within full_phrase that best support the citation' line_ids='2-6' reasoning='the terse logic used to conclude the citation' />
+<cite file_id='attachment_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 1-3 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='attachment_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.
 `;
 /**
@@ -110,7 +110,7 @@ export function wrapCitationPrompt(options) {
 export const CITATION_JSON_OUTPUT_FORMAT = {
     type: "object",
     properties: {
-        fileId: { type: "string" },
+        attachmentId: { type: "string" },
         startPageKey: {
             type: "string",
             description: 'Only return a result like "page_number_PAGE_index_INDEX" from the provided page keys (e.g. <page_number_1_index_0>) and never from the contents inside the page.',
@@ -134,7 +134,7 @@ export const CITATION_JSON_OUTPUT_FORMAT = {
         },
     },
     required: [
-        "fileId",
+        "attachmentId",
         "startPageKey",
         "reasoning",
         "fullPhrase",
@@ -145,7 +145,7 @@ export const CITATION_JSON_OUTPUT_FORMAT = {
 export const CITATION_AV_BASED_JSON_OUTPUT_FORMAT = {
     type: "object",
     properties: {
-        fileId: { type: "string" },
+        attachmentId: { type: "string" },
         startPageKey: {
             type: "string",
             description: 'Only return a result like "page_number_PAGE_index_INDEX" from the provided page keys (e.g. <page_number_1_index_0>) and never from the contents inside the page.',

package/lib/prompts/promptCompression.js

@@ -91,7 +91,7 @@ export function decompressPromptIds(compressed, prefixMap) {
         const escPrefix = prefix.replace(/[-\/\\^$*+?.()|[\]{}]/g, "\\$&");
         text = text.replace(new RegExp(escPrefix, "g"), full);
     }
-    //this is for citation fileId or file_id
+    //this is for citation attachmentId, file_id, or fileId
     if (entries.length === 1 && (text.includes("file_id='") || text.includes('file_id="'))) {
         const fullId = entries[0][1];
         text = text.replace(/file_id='[^']*'|file_id="[^"]*"/g, `file_id='${fullId}'`);
@@ -100,6 +100,10 @@ export function decompressPromptIds(compressed, prefixMap) {
         const fullId = entries[0][1];
         text = text.replace(/fileId='[^']*'|fileId="[^"]*"/g, `fileId='${fullId}'`);
     }
+    else if (entries.length === 1 && (text.includes("attachmentId='") || text.includes('attachmentId="'))) {
+        const fullId = entries[0][1];
+        text = text.replace(/attachmentId='[^']*'|attachmentId="[^"]*"/g, `attachmentId='${fullId}'`);
+    }
     const newLength = text?.length;
     const diff = originalLength - newLength;
     if (diff > 0) {

package/lib/react/styles.css

@@ -79,7 +79,8 @@
 }
 
 /* Status-specific styles */
-.dc-citation--verified .dc-citation-text {
+/* Only brackets variant gets verified blue text color */
+.dc-citation--brackets.dc-citation--verified .dc-citation-text {
   color: var(--dc-color-verified, #2563eb);
 }
 
@@ -87,7 +88,8 @@
   background-color: var(--dc-verified-hover-bg, rgba(37, 99, 235, 0.08));
 }
 
-.dc-citation--verified:hover .dc-citation-text {
+/* Only brackets variant gets verified blue text on hover */
+.dc-citation--brackets.dc-citation--verified:hover .dc-citation-text {
   text-decoration: underline;
   color: var(--dc-color-verified-hover, #1d4ed8);
 }

package/lib/react/utils.js

@@ -7,7 +7,7 @@ import { getCitationPageNumber } from "../parsing/normalizeCitation.js";
 export function generateCitationKey(citation) {
     const pageNumber = citation.pageNumber || getCitationPageNumber(citation.startPageKey);
     const keyParts = [
-        citation.fileId || "",
+        citation.attachmentId || "",
         pageNumber?.toString() || "",
         citation.fullPhrase || "",
         citation.keySpan?.toString() || "",

package/lib/types/citation.d.ts

@@ -8,7 +8,7 @@ export interface VerifyCitationResponse {
     };
 }
 export interface VerifyCitationRequest {
-    fileId: string;
+    attachmentId: string;
     citations: {
         [key: string]: Citation;
     };
@@ -16,7 +16,7 @@ export interface VerifyCitationRequest {
     apiKey?: string;
 }
 export interface Citation {
-    fileId?: string;
+    attachmentId?: string;
     fullPhrase?: string | null;
     keySpan?: string | null;
     startPageKey?: string | null;

package/lib/types/verification.d.ts

@@ -6,7 +6,7 @@ export declare const PENDING_VERIFICATION_INDEX = -2;
 export declare const BLANK_VERIFICATION: Verification;
 export declare function deterministicIdFromVerification(verification: Verification): string;
 export interface Verification {
-    fileId?: string | null;
+    attachmentId?: string | null;
     label?: string | null;
     pageNumber?: number | null;
     timestamp?: number | null;

package/lib/types/verification.js

@@ -2,12 +2,12 @@ import { sha1Hash } from "../utils/sha.js";
 export const NOT_FOUND_VERIFICATION_INDEX = -1;
 export const PENDING_VERIFICATION_INDEX = -2;
 export const BLANK_VERIFICATION = {
-    fileId: null,
+    attachmentId: null,
     pageNumber: NOT_FOUND_VERIFICATION_INDEX,
     matchSnippet: null,
     source: null,
     citation: {
-        fileId: undefined,
+        attachmentId: undefined,
         startPageKey: null,
         fullPhrase: null,
         keySpan: null,
@@ -17,5 +17,5 @@ export const BLANK_VERIFICATION = {
     },
 };
 export function deterministicIdFromVerification(verification) {
-    return sha1Hash(`${verification.label}-${verification.fileId}-${verification.pageNumber}-${verification.hitIndexWithinPage}-${verification.matchSnippet}-${verification?.hitIndexWithinPage}`);
+    return sha1Hash(`${verification.label}-${verification.attachmentId}-${verification.pageNumber}-${verification.hitIndexWithinPage}-${verification.matchSnippet}-${verification?.hitIndexWithinPage}`);
 }

package/package.json

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