@pdfvector/instance-client 0.0.42 → 0.0.44

package/.tsc/lib/errors.d.ts

@@ -0,0 +1,93 @@
+export type PDFVectorErrorCode = "BAD_REQUEST" | "UNAUTHORIZED" | "NOT_FOUND" | "TOO_MANY_REQUESTS" | "CONFLICT" | "NOT_IMPLEMENTED" | "UNPROCESSABLE_CONTENT" | "INTERNAL_SERVER_ERROR";
+export interface PDFVectorErrorOptions {
+    code: PDFVectorErrorCode;
+    status: number;
+    message: string;
+    data?: Record<string, unknown> | undefined;
+    cause?: unknown;
+}
+type SubclassOptions = Omit<PDFVectorErrorOptions, "code" | "status">;
+export declare class PDFVectorError extends Error {
+    readonly code: PDFVectorErrorCode;
+    readonly status: number;
+    readonly data: Record<string, unknown>;
+    readonly requestId?: number;
+    readonly documentId?: string;
+    readonly userError: boolean;
+    constructor(options: PDFVectorErrorOptions);
+}
+export declare class BadRequestError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class UnauthorizedError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class NotFoundError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class TooManyRequestsError extends PDFVectorError {
+    readonly limit?: number;
+    readonly resetAt?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class ConflictError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class NotImplementedError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class UnprocessableContentError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class InternalServerError extends PDFVectorError {
+    constructor(options: SubclassOptions);
+}
+export declare class FileTooLargeError extends BadRequestError {
+    readonly fileSizeMB?: number;
+    readonly limitMB?: number;
+    readonly model?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class PageLimitExceededError extends BadRequestError {
+    readonly pageCount?: number;
+    readonly pageLimit?: number;
+    readonly model?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class PasswordProtectedError extends BadRequestError {
+}
+export declare class UnsupportedFormatError extends BadRequestError {
+    readonly format?: string;
+    readonly supportedFormats?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class URLFetchError extends BadRequestError {
+    readonly url?: string;
+    readonly statusCode?: number;
+    readonly statusText?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class TierNotSupportedError extends BadRequestError {
+    readonly documentType?: string;
+    readonly model?: string;
+    readonly allowedTypes?: string[];
+    constructor(options: SubclassOptions);
+}
+export declare class InvalidSchemaError extends BadRequestError {
+    readonly reason?: string;
+    constructor(options: SubclassOptions);
+}
+export declare class NoInputProvidedError extends BadRequestError {
+}
+export declare class EmptyDocumentError extends UnprocessableContentError {
+}
+export declare class NoTextDetectedError extends UnprocessableContentError {
+}
+export declare class ExtractionFailedError extends UnprocessableContentError {
+    readonly hint?: string;
+    readonly rawText?: string;
+    constructor(options: SubclassOptions);
+}
+export declare function fromORPCError(error: unknown): PDFVectorError | undefined;
+export declare function isPDFVectorError(error: unknown): error is PDFVectorError;
+export {};

package/.tsc/lib/errors.js

@@ -0,0 +1,229 @@
+import { ORPCError } from "@pdfvector/instance-contract";
+function readNumber(data, key) {
+    const value = data?.[key];
+    return typeof value === "number" ? value : undefined;
+}
+function readString(data, key) {
+    const value = data?.[key];
+    return typeof value === "string" ? value : undefined;
+}
+function readStringArray(data, key) {
+    const value = data?.[key];
+    if (!Array.isArray(value))
+        return undefined;
+    const strings = value.filter((v) => typeof v === "string");
+    return strings.length === value.length ? strings : undefined;
+}
+export class PDFVectorError extends Error {
+    code;
+    status;
+    data;
+    requestId;
+    documentId;
+    userError;
+    constructor(options) {
+        super(options.message, options.cause ? { cause: options.cause } : undefined);
+        this.name = new.target.name;
+        this.code = options.code;
+        this.status = options.status;
+        this.data = options.data ?? {};
+        this.requestId = readNumber(this.data, "requestId");
+        this.documentId = readString(this.data, "documentId");
+        this.userError = this.data.userError === true;
+    }
+}
+export class BadRequestError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "BAD_REQUEST", status: 400 });
+    }
+}
+export class UnauthorizedError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "UNAUTHORIZED", status: 401 });
+    }
+}
+export class NotFoundError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "NOT_FOUND", status: 404 });
+    }
+}
+export class TooManyRequestsError extends PDFVectorError {
+    limit;
+    resetAt;
+    constructor(options) {
+        super({ ...options, code: "TOO_MANY_REQUESTS", status: 429 });
+        this.limit = readNumber(options.data, "limit");
+        this.resetAt = readString(options.data, "resetAt");
+    }
+}
+export class ConflictError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "CONFLICT", status: 409 });
+    }
+}
+export class NotImplementedError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "NOT_IMPLEMENTED", status: 501 });
+    }
+}
+export class UnprocessableContentError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "UNPROCESSABLE_CONTENT", status: 422 });
+    }
+}
+export class InternalServerError extends PDFVectorError {
+    constructor(options) {
+        super({ ...options, code: "INTERNAL_SERVER_ERROR", status: 500 });
+    }
+}
+export class FileTooLargeError extends BadRequestError {
+    fileSizeMB;
+    limitMB;
+    model;
+    constructor(options) {
+        super(options);
+        this.fileSizeMB = readNumber(options.data, "fileSizeMB");
+        this.limitMB = readNumber(options.data, "limitMB");
+        this.model = readString(options.data, "model");
+    }
+}
+export class PageLimitExceededError extends BadRequestError {
+    pageCount;
+    pageLimit;
+    model;
+    constructor(options) {
+        super(options);
+        this.pageCount = readNumber(options.data, "pageCount");
+        this.pageLimit = readNumber(options.data, "pageLimit");
+        this.model = readString(options.data, "model");
+    }
+}
+export class PasswordProtectedError extends BadRequestError {
+}
+export class UnsupportedFormatError extends BadRequestError {
+    format;
+    supportedFormats;
+    constructor(options) {
+        super(options);
+        this.format = readString(options.data, "format");
+        this.supportedFormats = readString(options.data, "supportedFormats");
+    }
+}
+export class URLFetchError extends BadRequestError {
+    url;
+    statusCode;
+    statusText;
+    constructor(options) {
+        super(options);
+        this.url = readString(options.data, "url");
+        this.statusCode = readNumber(options.data, "statusCode");
+        this.statusText = readString(options.data, "statusText");
+    }
+}
+export class TierNotSupportedError extends BadRequestError {
+    documentType;
+    model;
+    allowedTypes;
+    constructor(options) {
+        super(options);
+        this.documentType = readString(options.data, "documentType");
+        this.model = readString(options.data, "model");
+        this.allowedTypes = readStringArray(options.data, "allowedTypes");
+    }
+}
+export class InvalidSchemaError extends BadRequestError {
+    reason;
+    constructor(options) {
+        super(options);
+        this.reason = readString(options.data, "reason");
+    }
+}
+export class NoInputProvidedError extends BadRequestError {
+}
+export class EmptyDocumentError extends UnprocessableContentError {
+}
+export class NoTextDetectedError extends UnprocessableContentError {
+}
+export class ExtractionFailedError extends UnprocessableContentError {
+    hint;
+    rawText;
+    constructor(options) {
+        super(options);
+        this.hint = readString(options.data, "hint");
+        this.rawText = readString(options.data, "rawText");
+    }
+}
+const ORPC_CODE_TO_CLASS = {
+    BAD_REQUEST: BadRequestError,
+    UNAUTHORIZED: UnauthorizedError,
+    NOT_FOUND: NotFoundError,
+    TOO_MANY_REQUESTS: TooManyRequestsError,
+    CONFLICT: ConflictError,
+    NOT_IMPLEMENTED: NotImplementedError,
+    UNPROCESSABLE_CONTENT: UnprocessableContentError,
+    INTERNAL_SERVER_ERROR: InternalServerError,
+};
+function isPDFVectorErrorCode(code) {
+    return code in ORPC_CODE_TO_CLASS;
+}
+function selectSpecializedClass(code, message, data) {
+    const lower = message.toLowerCase();
+    if (code === "BAD_REQUEST") {
+        if (lower.includes("password-protected"))
+            return PasswordProtectedError;
+        if (lower.startsWith("file too large"))
+            return FileTooLargeError;
+        if (lower.startsWith("document has") &&
+            lower.includes("page") &&
+            lower.includes("limit"))
+            return PageLimitExceededError;
+        if (lower.startsWith("file type") &&
+            lower.includes("not supported for the"))
+            return TierNotSupportedError;
+        if (lower.startsWith("invalid json schema"))
+            return InvalidSchemaError;
+        if (lower.includes("unsupported format") ||
+            lower.includes("does not contain any supported document files"))
+            return UnsupportedFormatError;
+        if (lower.startsWith("failed to fetch document from url") ||
+            lower.startsWith("url did not return a supported document") ||
+            lower.includes("returned an html page instead of a document"))
+            return URLFetchError;
+        if (lower.startsWith("no input provided") ||
+            lower.startsWith("empty document content"))
+            return NoInputProvidedError;
+    }
+    if (code === "UNPROCESSABLE_CONTENT") {
+        if (lower.includes("does not appear to contain any readable text") ||
+            lower.includes("does not appear to contain any text"))
+            return NoTextDetectedError;
+        if (lower.includes("no text content detected") ||
+            lower.includes("document appears to be empty"))
+            return EmptyDocumentError;
+        if (lower.startsWith("failed to extract structured data"))
+            return ExtractionFailedError;
+        if (data.hint !== undefined || data.rawText !== undefined)
+            return ExtractionFailedError;
+    }
+    return ORPC_CODE_TO_CLASS[code];
+}
+export function fromORPCError(error) {
+    if (error instanceof PDFVectorError)
+        return error;
+    if (!(error instanceof ORPCError))
+        return undefined;
+    if (!isPDFVectorErrorCode(error.code))
+        return undefined;
+    const data = error.data != null && typeof error.data === "object"
+        ? error.data
+        : {};
+    const ErrorClass = selectSpecializedClass(error.code, error.message, data);
+    return new ErrorClass({
+        message: error.message,
+        data,
+        cause: error,
+    });
+}
+export function isPDFVectorError(error) {
+    return error instanceof PDFVectorError;
+}

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

@@ -11,3 +11,4 @@ export interface ClientContext {
 export type Client = Omit<ContractRouterClient<typeof contract, ClientContext>, "admin" | "free">;
 export declare function createClient(options?: CreateClientOptions): Client;
 export * from "@pdfvector/instance-contract";
+export * from "./errors";

package/.tsc/lib/index.js

@@ -1,5 +1,34 @@
 import { createORPCClient, RPCLink, } from "@pdfvector/instance-contract";
+import { fromORPCError } from "./errors";
 const DEFAULT_DOMAIN = "global.pdfvector.com";
+function wrapWithErrorMapping(target) {
+    return new Proxy(target, {
+        apply(obj, thisArg, args) {
+            try {
+                const result = Reflect.apply(obj, thisArg, args);
+                if (result instanceof Promise) {
+                    return result.catch((err) => {
+                        const mapped = fromORPCError(err);
+                        throw mapped ?? err;
+                    });
+                }
+                return result;
+            }
+            catch (err) {
+                const mapped = fromORPCError(err);
+                throw mapped ?? err;
+            }
+        },
+        get(obj, prop, receiver) {
+            const value = Reflect.get(obj, prop, receiver);
+            if (value !== null &&
+                (typeof value === "object" || typeof value === "function")) {
+                return wrapWithErrorMapping(value);
+            }
+            return value;
+        },
+    });
+}
 export function createClient(options) {
     const domain = options?.domain ?? DEFAULT_DOMAIN;
     const isLocal = domain.startsWith("localhost") || domain.startsWith("127.0.0.1");
@@ -17,6 +46,8 @@ export function createClient(options) {
         },
         fetch: (input, init) => fetch(input, token ? init : { ...init, credentials: "include" }),
     });
-    return createORPCClient(link);
+    const raw = createORPCClient(link);
+    return wrapWithErrorMapping(raw);
 }
 export * from "@pdfvector/instance-contract";
+export * from "./errors";

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @pdfvector/instance-client
 
+## 0.0.44
+### 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)
+
+## 0.0.43
+### 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
+
 ## 0.0.42
 ### Patch Changes
 

package/README.md

@@ -580,14 +580,12 @@ console.log(resultB.documentId); // "doc-b"
 
 ## Error Handling
 
-All API errors are thrown as `ORPCError` instances with structured error information matching the server's error response shape:
+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, ORPCError } from "@pdfvector/instance-client";
+import { createClient, PDFVectorError } from "@pdfvector/instance-client";
 
-const client = createClient({
-  apiKey: "your-api-key",
-});
+const client = createClient({ apiKey: "your-api-key" });
 
 try {
   const result = await client.document.parse({
@@ -595,10 +593,12 @@ try {
   });
   console.log(result.markdown);
 } catch (error) {
-  if (error instanceof ORPCError) {
+  if (error instanceof PDFVectorError) {
     console.error(`API Error [${error.code}]: ${error.message}`);
     console.error(`HTTP Status: ${error.status}`);
-    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);
@@ -606,13 +606,62 @@ try {
 }
 ```
 
-You can branch on the error code:
+### 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/instance-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 (error instanceof ORPCError) {
+  if (error instanceof PDFVectorError) {
     switch (error.code) {
       case "UNAUTHORIZED":
         console.error("Invalid API key");
@@ -620,23 +669,83 @@ try {
       case "BAD_REQUEST":
         console.error("Validation error:", error.message);
         break;
+      case "UNPROCESSABLE_CONTENT":
+        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/instance-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 |
-| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed by the requested model tier |
+| `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 |
-| `INTERNAL_SERVER_ERROR` | 500 | Server-side failure |
+| `INTERNAL_SERVER_ERROR` | 500 | Server-side failure — capture the `requestId` for support |
+| `NOT_IMPLEMENTED` | 501 | Endpoint not available on this instance |
 
 ## TypeScript Support
 
@@ -645,6 +754,31 @@ 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/instance-client";
 
@@ -655,6 +789,7 @@ import type {
   ContractInputs,
   ContractOutputs,
   PDFVectorModel,
+  PDFVectorErrorCode,
 } from "@pdfvector/instance-client";
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/instance-client",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "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",