@pdfvector/instance-client 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pdfvector/instance-client
 
+## 0.1.1
+
+### Patch Changes
+
+- [#515](https://github.com/phuctm97/pdfvector/pull/515) [`6f8ae23`](https://github.com/phuctm97/pdfvector/commit/6f8ae23349c1a386fb5c3fc4985b6a8f95f98616) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Correct the README: this package is ESM only and exports the contract from its main entry; point most users to @pdfvector/client.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -14,6 +14,10 @@ pnpm add @pdfvector/instance-client
 bun add @pdfvector/instance-client
 ```
 
+> **Most users should install [`@pdfvector/client`](https://www.npmjs.com/package/@pdfvector/client)** (same API, plus a CommonJS build, smaller bundles and no environment access). `@pdfvector/instance-client` is the lower-level ESM-only package `@pdfvector/client` is built from.
+
+This package is ESM only (`import`; Node.js 20.19+/22.12+ can also `require()` it) and ships type definitions. It works in Node.js, Bun, Cloudflare Workers, and browsers; Deno needs `--allow-env`.
+
 ## Quick Start
 
 ```typescript
@@ -60,6 +64,7 @@ const extractResult = await client.document.extract({
 console.log(extractResult.data);
 ```
 
+
 ## Authentication
 
 Get your API key from the [PDF Vector dashboard](https://app.pdfvector.com/instances/2?tab=settings).
@@ -720,7 +725,7 @@ try {
   } else if (error instanceof UnauthorizedError) {
     console.error("Invalid API key; check your dashboard");
   } else if (error instanceof PaymentRequiredError) {
-    console.error(`${error.message} (${error.suggestion})`);
+    console.error(error.message, error.payUrl ?? error.billingUrl ?? "");
   } else if (error instanceof TooManyRequestsError) {
     console.error(`Rate limit ${error.limit} exceeded; resets at ${error.resetAt}`);
   } else if (error instanceof EmptyDocumentError) {
@@ -731,6 +736,44 @@ try {
 }
 ```
 
+### Out of credits and billing holds (402)
+
+`PaymentRequiredError` covers two cases. `reasonCode` holds the stable machine code from the API (`CREDITS_EXHAUSTED`, or a `BILLING_*` code such as `BILLING_UNPAID_INVOICE`, `BILLING_PAYMENT_METHOD_REQUIRED`, `BILLING_DISPUTE`, `BILLING_LINKED_UNPAID_BALANCE`, `BILLING_ACCOUNT_HOLD`). Show `message` to the user as-is.
+
+```typescript
+import { PaymentRequiredError } from "@pdfvector/instance-client";
+
+try {
+  await client.document.parse({ url: "https://example.com/document.pdf" });
+} catch (error) {
+  if (error instanceof PaymentRequiredError) {
+    if (error.isBillingHold) {
+      // Unpaid invoice, missing payment method, dispute, or account hold.
+      console.error(error.message);
+      console.error(error.payUrl ?? error.billingUrl); // where to pay or fix billing
+      console.error(error.amountDue, error.currency); // minor units, e.g. 1900 "usd"
+    } else {
+      // error.isCreditsExhausted: the monthly credits are used up.
+      console.error(`${error.remainingCredits}/${error.totalCredits} credits left, reset on ${error.resetsAt}`);
+    }
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `isCreditsExhausted` | `boolean` | The monthly credits are used up |
+| `isBillingHold` | `boolean` | Requests are blocked by a billing problem (`reasonCode` starts with `BILLING_`) |
+| `totalCredits` | `number \| undefined` | Monthly credits of the plan |
+| `remainingCredits` | `number \| undefined` | Credits left in the current period |
+| `resetsAt` | `string \| undefined` | ISO date when the credits reset |
+| `billingReason` | `string \| undefined` | Billing hold reason from the API |
+| `invoiceCount` | `number \| undefined` | Number of unpaid invoices |
+| `amountDue` | `number \| undefined` | Outstanding amount in minor currency units (cents) |
+| `currency` | `string \| undefined` | Currency of `amountDue`, such as `usd` |
+| `billingUrl` | `string \| undefined` | Billing page to update the payment method or see invoices |
+| `payUrl` | `string \| undefined` | Direct link to pay the outstanding invoice (absent for disputes and account holds) |
+
 ### Error Class Hierarchy
 
 ```
@@ -747,7 +790,7 @@ PDFVectorError
 │   ├── InvalidSchemaError                — reason
 │   └── NoInputProvidedError
 ├── UnauthorizedError               (401)
-├── PaymentRequiredError            (402) — totalCredits, remainingCredits, resetsAt
+├── PaymentRequiredError            (402) — totalCredits, remainingCredits, resetsAt, payUrl, billingUrl, …
 ├── NotFoundError                   (404)
 │   ├── AcademicPaperNotFoundError        — input, paperErrorCode
 │   └── NoPublicPDFError                  — input, paperTitle, doi, providerURL
@@ -790,7 +833,7 @@ Use `error.toAgentError()` or `JSON.stringify(error)` when you need a serializab
 |------|--------|-------------|
 | `BAD_REQUEST` | 400 | Input validation failed, including invalid URLs, unsupported formats, file size limits, page limits, invalid base64, and invalid JSON Schema |
 | `UNAUTHORIZED` | 401 | Missing, invalid or deleted API key |
-| `PAYMENT_REQUIRED` | 402 | The workspace has used all of its monthly credits; the message says when they reset and links to the plan page |
+| `PAYMENT_REQUIRED` | 402 | The workspace has used all of its monthly credits, or requests are on a billing hold (for example an unpaid invoice); see [Out of credits and billing holds](#out-of-credits-and-billing-holds-402) |
 | `NOT_FOUND` | 404 | Resource not found, including academic paper IDs and papers without public PDFs |
 | `CONFLICT` | 409 | Operation conflicts with the current state |
 | `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed, including empty documents, no readable text, and extraction failures |
@@ -853,12 +896,15 @@ import type {
 } from "@pdfvector/instance-client";
 ```
 
-## Runtime Support
+Request and response types are inferred from the API contract, so `client.document.parse(...)` is fully typed without extra imports. With `skipLibCheck: false`, also install `@opentelemetry/api` (an optional type dependency of oRPC), or use `@pdfvector/client`. They reference the standard `fetch` types (`Blob`, `ReadableStream`, `AbortSignal`), so include the `dom` lib or `@types/node`.
+
+The contract (oRPC router with zod schemas) and `pdfvectorModelSchema` are exported from the main entry:
 
-- **Node.js**: 20+
-- **Bun**: 1.0+
-- **ESM only** (CommonJS is not supported)
-- Uses standard `fetch` API
+```typescript
+import { contract, pdfvectorModelSchema } from "@pdfvector/instance-client";
+
+pdfvectorModelSchema.parse("nano"); // "nano" | "mini" | "pro" | "max"
+```
 
 ## Support
 

package/package.json

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