@deepcitation/deepcitation-js 1.0.5 → 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
 ```
 
 ---
@@ -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.
      *
@@ -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.
@@ -150,75 +146,42 @@ export class DeepCitation {
      * ```
      */
     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;
     }
     /**
@@ -242,7 +205,6 @@ export class DeepCitation {
      * ```
      */
     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.`);
@@ -259,18 +221,9 @@ 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.
@@ -377,9 +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());
     }
@@ -414,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 || "";
@@ -423,35 +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;
@@ -94,7 +94,7 @@ export interface PrepareFilesResult {
 /**
  * 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,7 +3,7 @@
  * @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";

package/package.json

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