@pdfvector/instance-client 0.0.40 → 0.0.41

package/.tsc/lib/index.d.ts

@@ -18,8 +18,9 @@ export interface ClientContext {
 /**
  * Custom error class for PDF Vector API errors.
  *
- * All API errors thrown by the client are instances of this class.
- * Provides structured access to error code, HTTP status, message, and additional data.
+ * All errors thrown by the client are instances of this class, including
+ * transport-layer failures (DNS, connection refused, timeouts) which surface
+ * with `code: "NETWORK_ERROR"` and `status: 0`.
  *
  * @example
  * ```typescript
@@ -27,10 +28,11 @@ export interface ClientContext {
  *   await client.document.parse({ url: "..." });
  * } catch (error) {
  *   if (error instanceof PDFVectorError) {
- *     console.error(error.code);    // "UNAUTHORIZED" | "BAD_REQUEST" | ...
- *     console.error(error.status);  // 401 | 400 | 422 | 500
- *     console.error(error.message); // "Invalid API key"
- *     console.error(error.data);    // { requestId: 1 }
+ *     console.error(error.code);      // "UNAUTHORIZED" | "BAD_REQUEST" | "NETWORK_ERROR" | ...
+ *     console.error(error.status);    // 401 | 400 | 422 | 500 | 0 (network)
+ *     console.error(error.message);   // "Invalid API key"
+ *     console.error(error.userError); // true if the error is caused by user input (illegible upload, etc.)
+ *     console.error(error.data);      // { requestId: 1, userError: true }
  *   }
  * }
  * ```
@@ -38,10 +40,16 @@ export interface ClientContext {
 export declare class PDFVectorError extends Error {
     /** Error code identifying the type of error */
     readonly code: string;
-    /** HTTP status code */
+    /** HTTP status code. `0` for transport-layer failures (see `NETWORK_ERROR`). */
     readonly status: number;
-    /** Additional error data from the server (e.g., requestId) */
+    /** Additional error data from the server (e.g., `requestId`, `userError`) */
     readonly data: unknown;
+    /**
+     * True when the server flagged this error as caused by user input
+     * (e.g. illegible uploads, empty documents) rather than a server-side
+     * failure. Mirrors `data.userError === true`.
+     */
+    readonly userError: boolean;
     constructor(options: {
         code: string;
         message: string;

package/.tsc/lib/index.js

@@ -4,8 +4,9 @@ const DEFAULT_DOMAIN = "global.pdfvector.com";
 /**
  * Custom error class for PDF Vector API errors.
  *
- * All API errors thrown by the client are instances of this class.
- * Provides structured access to error code, HTTP status, message, and additional data.
+ * All errors thrown by the client are instances of this class, including
+ * transport-layer failures (DNS, connection refused, timeouts) which surface
+ * with `code: "NETWORK_ERROR"` and `status: 0`.
  *
  * @example
  * ```typescript
@@ -13,10 +14,11 @@ const DEFAULT_DOMAIN = "global.pdfvector.com";
  *   await client.document.parse({ url: "..." });
  * } catch (error) {
  *   if (error instanceof PDFVectorError) {
- *     console.error(error.code);    // "UNAUTHORIZED" | "BAD_REQUEST" | ...
- *     console.error(error.status);  // 401 | 400 | 422 | 500
- *     console.error(error.message); // "Invalid API key"
- *     console.error(error.data);    // { requestId: 1 }
+ *     console.error(error.code);      // "UNAUTHORIZED" | "BAD_REQUEST" | "NETWORK_ERROR" | ...
+ *     console.error(error.status);    // 401 | 400 | 422 | 500 | 0 (network)
+ *     console.error(error.message);   // "Invalid API key"
+ *     console.error(error.userError); // true if the error is caused by user input (illegible upload, etc.)
+ *     console.error(error.data);      // { requestId: 1, userError: true }
  *   }
  * }
  * ```
@@ -24,16 +26,26 @@ const DEFAULT_DOMAIN = "global.pdfvector.com";
 export class PDFVectorError extends Error {
     /** Error code identifying the type of error */
     code;
-    /** HTTP status code */
+    /** HTTP status code. `0` for transport-layer failures (see `NETWORK_ERROR`). */
     status;
-    /** Additional error data from the server (e.g., requestId) */
+    /** Additional error data from the server (e.g., `requestId`, `userError`) */
     data;
+    /**
+     * True when the server flagged this error as caused by user input
+     * (e.g. illegible uploads, empty documents) rather than a server-side
+     * failure. Mirrors `data.userError === true`.
+     */
+    userError;
     constructor(options) {
         super(options.message);
         this.name = "PDFVectorError";
         this.code = options.code;
         this.status = options.status;
         this.data = options.data;
+        this.userError =
+            options.data != null &&
+                typeof options.data === "object" &&
+                options.data.userError === true;
     }
     /**
      * Type guard to check if an unknown error is a PDFVectorError.
@@ -48,6 +60,23 @@ export function _buildClient(options) {
     const isLocal = domain.startsWith("localhost") || domain.startsWith("127.0.0.1");
     const baseUrl = `${isLocal ? "http" : "https"}://${domain}`;
     const token = options?.apiKey ?? options?.secret;
+    const wrappedFetch = async (input, init) => {
+        try {
+            return await (token
+                ? fetch(input, init)
+                : fetch(input, { ...init, credentials: "include" }));
+        }
+        catch (err) {
+            throw new PDFVectorError({
+                code: "NETWORK_ERROR",
+                message: err instanceof Error
+                    ? err.message
+                    : "Network request failed before reaching the server",
+                status: 0,
+                data: { cause: err },
+            });
+        }
+    };
     const link = new RPCLink({
         url: `${baseUrl}/rpc`,
         headers: ({ context }) => {
@@ -62,11 +91,12 @@ export function _buildClient(options) {
             }
             return headers;
         },
-        fetch: token
-            ? undefined
-            : (input, init) => fetch(input, { ...init, credentials: "include" }),
+        fetch: wrappedFetch,
         interceptors: [
             onError((error) => {
+                if (error instanceof PDFVectorError) {
+                    throw error;
+                }
                 if (error instanceof ORPCError) {
                     throw new PDFVectorError({
                         code: error.code,

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @pdfvector/instance-client
 
+## 0.0.41
+### Patch Changes
+
+
+
+- [#205](https://github.com/phuctm97/pdfvector/pull/205) [`93b9624`](https://github.com/phuctm97/pdfvector/commit/93b9624333f643b143062e08c6af216eed5a859a) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Improve SDK error handling and tighten academic provider types
+
+- Updated dependencies [[`93b9624`](https://github.com/phuctm97/pdfvector/commit/93b9624333f643b143062e08c6af216eed5a859a)]:
+  - @pdfvector/instance-contract@0.0.40
+
 ## 0.0.40
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/instance-client",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "type": "module",
   "description": "Official TypeScript/JavaScript SDK for PDF Vector API - Parse PDF/Word/Image/Excel documents to clean, structured markdown format and search academic publications across multiple databases",
   "license": "MIT",
@@ -35,7 +35,7 @@
   "dependencies": {
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
-    "@pdfvector/instance-contract": "^0.0.39"
+    "@pdfvector/instance-contract": "^0.0.40"
   },
   "files": [
     ".tsc",