@pdfvector/client 0.0.21 → 0.0.24

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @pdfvector/client
 
+## 0.0.24
+### Patch Changes
+
+
+
+- [#222](https://github.com/phuctm97/pdfvector/pull/222) [`3b78122`](https://github.com/phuctm97/pdfvector/commit/3b78122a35206b85be4ac61813ad1691ad57b866) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Re-trigger releases for client, instance-client, and gateway-server (previous attempt failed at frozen-lockfile install before publish)
+
+- Updated dependencies [[`3b78122`](https://github.com/phuctm97/pdfvector/commit/3b78122a35206b85be4ac61813ad1691ad57b866)]:
+  - @pdfvector/instance-client@0.0.44
+
+## 0.0.23
+### Patch Changes
+
+
+
+- [#221](https://github.com/phuctm97/pdfvector/pull/221) [`84b9c58`](https://github.com/phuctm97/pdfvector/commit/84b9c58ce1a4f920e163f1666f738c83b3faa5c2) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Add typed PDFVectorError class hierarchy to instance-client SDK
+
+- Updated dependencies [[`84b9c58`](https://github.com/phuctm97/pdfvector/commit/84b9c58ce1a4f920e163f1666f738c83b3faa5c2)]:
+  - @pdfvector/instance-client@0.0.43
+
+## 0.0.22
+### Patch Changes
+
+- Updated dependencies [[`3a1c66b`](https://github.com/phuctm97/pdfvector/commit/3a1c66bcdfade057be5f1b9170f8ed64934bf2a9)]:
+  - @pdfvector/instance-client@0.0.42
+
 ## 0.0.21
 ### Patch Changes
 

package/README.md

@@ -580,16 +580,12 @@ console.log(resultB.documentId); // "doc-b"
 
 ## Error Handling
 
-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`.
+All API errors are thrown as `PDFVectorError` instances. The SDK transparently maps every server error into the most specific subclass it can, so you can branch on the type using `instanceof` and read typed metadata fields directly.
 
 ```typescript
 import { createClient, PDFVectorError } from "@pdfvector/client";
 
-const client = createClient({
-  apiKey: "your-api-key",
-});
+const client = createClient({ apiKey: "your-api-key" });
 
 try {
   const result = await client.document.parse({
@@ -600,21 +596,72 @@ 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);
+    console.error(`Request ID: ${error.requestId}`);   // server-assigned, useful for support
+    console.error(`Document ID: ${error.documentId}`); // echoed back if you set one
+    console.error(`User error: ${error.userError}`);   // true if caused by your input
   } else {
+    // Network errors (DNS, connection refused, timeout) bubble up as TypeError.
     console.error("Unexpected Error:", error);
   }
 }
 ```
 
-You can also use the static type guard:
+### Branching on specific error types
+
+Every error class extends `PDFVectorError`, so you can use `instanceof` to handle specific cases. Specialized subclasses expose typed fields pulled from the error's `data` payload:
+
+```typescript
+import {
+  createClient,
+  FileTooLargeError,
+  PageLimitExceededError,
+  PasswordProtectedError,
+  URLFetchError,
+  UnauthorizedError,
+  TooManyRequestsError,
+  EmptyDocumentError,
+  ExtractionFailedError,
+  PDFVectorError,
+} from "@pdfvector/client";
+
+try {
+  await client.document.parse({ url: "...", model: "nano" });
+} catch (error) {
+  if (error instanceof FileTooLargeError) {
+    console.error(
+      `File ${error.fileSizeMB}MB exceeds ${error.limitMB}MB limit for the '${error.model}' model`,
+    );
+  } else if (error instanceof PageLimitExceededError) {
+    console.error(
+      `Document has ${error.pageCount} pages — ${error.model} only supports up to ${error.pageLimit}`,
+    );
+  } else if (error instanceof PasswordProtectedError) {
+    console.error("Remove the password from the file and try again");
+  } else if (error instanceof URLFetchError) {
+    console.error(`Could not fetch ${error.url}: ${error.statusCode} ${error.statusText}`);
+  } else if (error instanceof UnauthorizedError) {
+    console.error("Invalid API key — check your dashboard");
+  } else if (error instanceof TooManyRequestsError) {
+    console.error(`Rate limit ${error.limit} exceeded; resets at ${error.resetAt}`);
+  } else if (error instanceof EmptyDocumentError) {
+    console.error("The document has no readable content");
+  } else if (error instanceof ExtractionFailedError) {
+    console.error(`Extraction failed. Hint: ${error.hint}`);
+    if (error.rawText) console.error(`Model output sample: ${error.rawText}`);
+  } else if (error instanceof PDFVectorError) {
+    // Catch-all for any error code not specifically handled
+    console.error(`API Error [${error.code}]: ${error.message}`);
+  }
+}
+```
+
+You can also branch on the error code if you prefer:
 
 ```typescript
 try {
   await client.document.parse({ url: "..." });
 } catch (error) {
-  if (PDFVectorError.is(error)) {
+  if (error instanceof PDFVectorError) {
     switch (error.code) {
       case "UNAUTHORIZED":
         console.error("Invalid API key");
@@ -623,45 +670,82 @@ try {
         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.");
+        console.error("Could not process document:", error.message);
         break;
       case "INTERNAL_SERVER_ERROR":
-        console.error("Server error:", error.message);
+        console.error(`Server error (requestId: ${error.requestId}):`, error.message);
         break;
     }
   }
 }
 ```
 
+### Error Class Hierarchy
+
+```
+PDFVectorError
+├── BadRequestError                 (400)
+│   ├── FileTooLargeError                 — fileSizeMB, limitMB, model
+│   ├── PageLimitExceededError            — pageCount, pageLimit, model
+│   ├── PasswordProtectedError
+│   ├── UnsupportedFormatError            — format, supportedFormats
+│   ├── URLFetchError                     — url, statusCode, statusText
+│   ├── TierNotSupportedError             — documentType, model, allowedTypes
+│   ├── InvalidSchemaError                — reason
+│   └── NoInputProvidedError
+├── UnauthorizedError               (401)
+├── NotFoundError                   (404)
+├── ConflictError                   (409)
+├── TooManyRequestsError            (429) — limit, resetAt
+├── UnprocessableContentError       (422)
+│   ├── EmptyDocumentError
+│   ├── NoTextDetectedError
+│   └── ExtractionFailedError             — hint, rawText
+├── InternalServerError             (500)
+└── NotImplementedError             (501)
+```
+
+### Common fields on every `PDFVectorError`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `code` | `string` | The ORPC error code (`BAD_REQUEST`, `UNAUTHORIZED`, etc.) |
+| `status` | `number` | HTTP status code (400, 401, 404, 409, 422, 429, 500, 501) |
+| `message` | `string` | Human-readable error message |
+| `data` | `Record<string, unknown>` | Raw error payload from the server |
+| `requestId` | `number \| undefined` | Server-assigned request ID — include in support tickets |
+| `documentId` | `string \| undefined` | Echoed back if you passed `context.documentId` |
+| `userError` | `boolean` | `true` if the failure was caused by your input (vs. a server-side issue) |
+| `cause` | `unknown` | Original error (the underlying `ORPCError` from the wire) |
+
+### Type guard
+
+If you'd rather not import `PDFVectorError` just to do an `instanceof` check, use the `isPDFVectorError` guard:
+
+```typescript
+import { isPDFVectorError } from "@pdfvector/client";
+
+try {
+  await client.document.parse({ url: "..." });
+} catch (error) {
+  if (isPDFVectorError(error)) {
+    console.error(error.code, error.message, error.requestId);
+  }
+}
+```
+
 ### Error Codes
 
 | Code | Status | Description |
 |------|--------|-------------|
-| `BAD_REQUEST` | 400 | Input validation failed (e.g., missing fields, invalid URL, question too short) |
+| `BAD_REQUEST` | 400 | Input validation failed (e.g., missing fields, invalid URL, file too large, page limit exceeded, invalid JSON Schema) |
 | `UNAUTHORIZED` | 401 | Missing or invalid API key |
-| `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. |
+| `NOT_FOUND` | 404 | Resource not found (e.g., academic paper ID, version) |
+| `CONFLICT` | 409 | Operation conflicts with the current state |
+| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed (empty, no readable text, extraction failed) |
 | `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`.
+| `INTERNAL_SERVER_ERROR` | 500 | Server-side failure — capture the `requestId` for support |
+| `NOT_IMPLEMENTED` | 501 | Endpoint not available on this instance |
 
 ## TypeScript Support
 
@@ -670,7 +754,32 @@ The SDK is written in TypeScript and includes full type definitions:
 ```typescript
 import {
   createClient,
+  isPDFVectorError,
+  // Base error class — all errors inherit from this
   PDFVectorError,
+  // HTTP-aligned error categories
+  BadRequestError,
+  UnauthorizedError,
+  NotFoundError,
+  ConflictError,
+  TooManyRequestsError,
+  UnprocessableContentError,
+  InternalServerError,
+  NotImplementedError,
+  // Specialized error subclasses with typed metadata
+  FileTooLargeError,
+  PageLimitExceededError,
+  PasswordProtectedError,
+  UnsupportedFormatError,
+  URLFetchError,
+  TierNotSupportedError,
+  InvalidSchemaError,
+  NoInputProvidedError,
+  EmptyDocumentError,
+  NoTextDetectedError,
+  ExtractionFailedError,
+  // Underlying ORPC error — re-exported for advanced use cases
+  ORPCError,
 } from "@pdfvector/client";
 
 import type {
@@ -680,6 +789,7 @@ import type {
   ContractInputs,
   ContractOutputs,
   PDFVectorModel,
+  PDFVectorErrorCode,
 } from "@pdfvector/client";
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/client",
-  "version": "0.0.21",
+  "version": "0.0.24",
   "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.41"
+    "@pdfvector/instance-client": "^0.0.44"
   },
   "files": [
     ".tsc",