@pdfvector/instance-client 0.0.41 → 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

@@ -1,69 +1,14 @@
-import type { ContractRouterClient } from "@orpc/contract";
-import type { contract } from "@pdfvector/instance-contract";
+import { type ContractRouterClient, type contract } from "@pdfvector/instance-contract";
 export interface CreateClientOptions {
-    /** Domain of the PDF Vector instance server (e.g., "your-instance.pdfvector.com"). Defaults to "global.pdfvector.com". */
+    /** Defaults to "global.pdfvector.com". */
     domain?: string;
-    /** API key for Bearer token authentication */
     apiKey?: string;
-    /** @internal Server secret */
-    secret?: string;
-    /** @internal Additional headers merged into every outgoing request (e.g. forwarded IP) */
-    forwardedHeaders?: Record<string, string>;
 }
-/** Per-request context passed as the second argument to any API call. */
 export interface ClientContext {
-    /** Document ID for usage tracking. Returned in response for document, identity, invoice, and bank statement endpoints. */
+    /** Optional ID echoed back in responses, used for per-document usage tracking. */
     documentId?: string;
 }
-/**
- * Custom error class for PDF Vector API errors.
- *
- * 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
- * try {
- *   await client.document.parse({ url: "..." });
- * } catch (error) {
- *   if (error instanceof PDFVectorError) {
- *     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 }
- *   }
- * }
- * ```
- */
-export declare class PDFVectorError extends Error {
-    /** Error code identifying the type of error */
-    readonly code: string;
-    /** HTTP status code. `0` for transport-layer failures (see `NETWORK_ERROR`). */
-    readonly status: number;
-    /** 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;
-        status: number;
-        data?: unknown;
-    });
-    /**
-     * Type guard to check if an unknown error is a PDFVectorError.
-     */
-    static is(error: unknown): error is PDFVectorError;
-}
-/** @internal */
-export declare function _buildClient(options?: CreateClientOptions): Client;
-export declare function createClient(options?: CreateClientOptions): PublicClient;
-type Client = ContractRouterClient<typeof contract, ClientContext>;
-export type PublicClient = Omit<ContractRouterClient<typeof contract, ClientContext>, "admin" | "free">;
-export type { ContractInputs, ContractOutputs, PDFVectorModel, } from "@pdfvector/instance-contract";
+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,115 +1,53 @@
-import { createORPCClient, ORPCError, onError } from "@orpc/client";
-import { RPCLink } from "@orpc/client/fetch";
+import { createORPCClient, RPCLink, } from "@pdfvector/instance-contract";
+import { fromORPCError } from "./errors";
 const DEFAULT_DOMAIN = "global.pdfvector.com";
-/**
- * Custom error class for PDF Vector API errors.
- *
- * 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
- * try {
- *   await client.document.parse({ url: "..." });
- * } catch (error) {
- *   if (error instanceof PDFVectorError) {
- *     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 }
- *   }
- * }
- * ```
- */
-export class PDFVectorError extends Error {
-    /** Error code identifying the type of error */
-    code;
-    /** HTTP status code. `0` for transport-layer failures (see `NETWORK_ERROR`). */
-    status;
-    /** 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.
-     */
-    static is(error) {
-        return error instanceof PDFVectorError;
-    }
+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;
+        },
+    });
 }
-/** @internal */
-export function _buildClient(options) {
+export function createClient(options) {
     const domain = options?.domain ?? DEFAULT_DOMAIN;
     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 token = options?.apiKey;
     const link = new RPCLink({
         url: `${baseUrl}/rpc`,
         headers: ({ context }) => {
-            const headers = {
-                ...options?.forwardedHeaders,
-            };
-            if (token) {
+            const headers = {};
+            if (token)
                 headers.authorization = `Bearer ${token}`;
-            }
-            if (context?.documentId) {
+            if (context?.documentId)
                 headers["x-pdfvector-document-id"] = context.documentId;
-            }
             return headers;
         },
-        fetch: wrappedFetch,
-        interceptors: [
-            onError((error) => {
-                if (error instanceof PDFVectorError) {
-                    throw error;
-                }
-                if (error instanceof ORPCError) {
-                    throw new PDFVectorError({
-                        code: error.code,
-                        message: error.message,
-                        status: error.status,
-                        data: error.data,
-                    });
-                }
-            }),
-        ],
+        fetch: (input, init) => fetch(input, token ? init : { ...init, credentials: "include" }),
     });
-    return createORPCClient(link);
-}
-export function createClient(options) {
-    return _buildClient(options);
+    const raw = createORPCClient(link);
+    return wrapWithErrorMapping(raw);
 }
+export * from "@pdfvector/instance-contract";
+export * from "./errors";

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @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
+
+
+
+- [#214](https://github.com/phuctm97/pdfvector/pull/214) [`3a1c66b`](https://github.com/phuctm97/pdfvector/commit/3a1c66bcdfade057be5f1b9170f8ed64934bf2a9) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Fix PDFVECTOR-INSTANCE-T and slim instance-client SDK
+
+- Updated dependencies [[`3a1c66b`](https://github.com/phuctm97/pdfvector/commit/3a1c66bcdfade057be5f1b9170f8ed64934bf2a9)]:
+  - @pdfvector/instance-contract@0.0.41
+
 ## 0.0.41
 ### Patch Changes
 

package/README.md

@@ -580,14 +580,12 @@ console.log(resultB.documentId); // "doc-b"
 
 ## Error Handling
 
-All API errors are thrown as `PDFVectorError` instances with structured error information:
+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/instance-client";
 
-const client = createClient({
-  apiKey: "your-api-key",
-});
+const client = createClient({ apiKey: "your-api-key" });
 
 try {
   const result = await client.document.parse({
@@ -598,20 +596,72 @@ try {
   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);
   }
 }
 ```
 
-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/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 (PDFVectorError.is(error)) {
+  if (error instanceof PDFVectorError) {
     switch (error.code) {
       case "UNAUTHORIZED":
         console.error("Invalid API key");
@@ -619,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
 
@@ -644,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/instance-client";
 
 import type {
@@ -654,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.41",
+  "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",
@@ -33,12 +33,11 @@
   },
   "main": ".tsc/lib/index.js",
   "dependencies": {
-    "@orpc/client": "^1.13.14",
-    "@orpc/contract": "^1.13.14",
-    "@pdfvector/instance-contract": "^0.0.40"
+    "@pdfvector/instance-contract": "^0.0.41"
   },
   "files": [
     ".tsc",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "README.md"
   ]
 }

package/.tsc/lib/internal.d.ts

@@ -1,5 +0,0 @@
-import type { ContractRouterClient } from "@orpc/contract";
-import type { contract } from "@pdfvector/instance-contract";
-import { type ClientContext, type CreateClientOptions } from ".";
-export type Client = ContractRouterClient<typeof contract, ClientContext>;
-export declare function createInternalClient(options?: CreateClientOptions): Client;

package/.tsc/lib/internal.js

@@ -1,4 +0,0 @@
-import { _buildClient } from ".";
-export function createInternalClient(options) {
-    return _buildClient(options);
-}