@pdfvector/client 0.0.20 → 0.0.21

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @pdfvector/client
 
+## 0.0.21
+### 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-client@0.0.41
+
 ## 0.0.20
 ### Patch Changes
 

package/README.md

@@ -580,7 +580,9 @@ console.log(resultB.documentId); // "doc-b"
 
 ## Error Handling
 
-All API errors are thrown as `PDFVectorError` instances with structured error information:
+All errors thrown by the client are `PDFVectorError` instances — including
+transport-layer failures (DNS, connection refused, timeouts), which surface
+with `code: "NETWORK_ERROR"` and `status: 0`.
 
 ```typescript
 import { createClient, PDFVectorError } from "@pdfvector/client";
@@ -598,6 +600,7 @@ try {
   if (error instanceof PDFVectorError) {
     console.error(`API Error [${error.code}]: ${error.message}`);
     console.error(`HTTP Status: ${error.status}`);
+    console.error(`User error: ${error.userError}`);
     console.error(`Error Data:`, error.data);
   } else {
     console.error("Unexpected Error:", error);
@@ -619,6 +622,16 @@ try {
       case "BAD_REQUEST":
         console.error("Validation error:", error.message);
         break;
+      case "UNPROCESSABLE_CONTENT":
+        if (error.userError) {
+          console.error("The upload is unreadable or empty — please check the document.");
+        } else {
+          console.error("The server failed to process the document:", error.message);
+        }
+        break;
+      case "NETWORK_ERROR":
+        console.error("Could not reach the server. Check your network connection.");
+        break;
       case "INTERNAL_SERVER_ERROR":
         console.error("Server error:", error.message);
         break;
@@ -633,9 +646,22 @@ try {
 |------|--------|-------------|
 | `BAD_REQUEST` | 400 | Input validation failed (e.g., missing fields, invalid URL, question too short) |
 | `UNAUTHORIZED` | 401 | Missing or invalid API key |
-| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed by the requested model tier |
+| `NOT_FOUND` | 404 | Requested resource does not exist |
+| `CONFLICT` | 409 | Request conflicts with current state (e.g., duplicate operation) |
+| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed. When `error.userError === true`, the upload itself is unreadable or empty; otherwise it's a server-side parse failure. |
 | `TOO_MANY_REQUESTS` | 429 | Rate limit exceeded |
+| `NOT_IMPLEMENTED` | 501 | Endpoint is not supported on this instance |
 | `INTERNAL_SERVER_ERROR` | 500 | Server-side failure |
+| `NETWORK_ERROR` | 0 | Transport-layer failure — the request never reached the server (DNS, connection refused, timeout, etc.). `error.data.cause` holds the underlying error. |
+
+### User vs. system errors
+
+Document-family endpoints (`document.*`, `invoice.*`, `identity.*`,
+`bankStatement.*`) surface `error.userError === true` when the failure is
+caused by the uploaded document itself (e.g. empty file, illegible image,
+password-protected, unsupported content type). Use this flag to decide whether
+to show the end user an actionable message or report a backend issue. The same
+information is also available as `error.data.userError`.
 
 ## TypeScript Support
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/client",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "description": "Official TypeScript/JavaScript SDK for PDF Vector API",
   "license": "MIT",
@@ -23,7 +23,7 @@
   },
   "main": ".tsc/lib/index.js",
   "dependencies": {
-    "@pdfvector/instance-client": "^0.0.40"
+    "@pdfvector/instance-client": "^0.0.41"
   },
   "files": [
     ".tsc",