@pdfvector/instance-client 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.tsc/lib/errors.d.ts.map +1 -1
- package/.tsc/lib/errors.js +20 -0
- package/CHANGELOG.md +20 -0
- package/README.md +66 -9
- package/package.json +2 -2
package/.tsc/lib/errors.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../lib/errors.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAC3B,aAAa,GACb,cAAc,GACd,kBAAkB,GAClB,WAAW,GACX,mBAAmB,GACnB,UAAU,GACV,iBAAiB,GACjB,uBAAuB,GACvB,uBAAuB,CAAC;AAE3B,MAAM,MAAM,sBAAsB,GAC/B,gBAAgB,GAChB,SAAS,GACT,YAAY,GACZ,gBAAgB,GAChB,qBAAqB,GACrB,YAAY,GACZ,WAAW,GACX,UAAU,GACV,aAAa,GACb,QAAQ,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAC3C,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,KAAK,eAAe,GAAG,IAAI,CAAC,qBAAqB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC;AAEtE,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,sBAAsB,CAAC;IACjC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,wBAAwB,EAAE,OAAO,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;
|
|
1
|
+
{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../lib/errors.ts"],"names":[],"mappings":"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"}
|
package/.tsc/lib/errors.js
CHANGED
|
@@ -80,9 +80,20 @@ function inferCategory(code, message, data) {
|
|
|
80
80
|
}
|
|
81
81
|
return "document_input";
|
|
82
82
|
}
|
|
83
|
+
/** A source website refused or failed a download: neither the caller's input nor a PDF Vector bug, retry later. */
|
|
84
|
+
const upstreamReasonCodes = new Set([
|
|
85
|
+
"UPSTREAM_FETCH_FAILED",
|
|
86
|
+
"PDF_NOT_FETCHABLE",
|
|
87
|
+
]);
|
|
88
|
+
function isUpstreamFailure(data) {
|
|
89
|
+
const code = data["code"];
|
|
90
|
+
return typeof code === "string" && upstreamReasonCodes.has(code);
|
|
91
|
+
}
|
|
83
92
|
function inferOrigin(code, category, data) {
|
|
84
93
|
if (data["userError"] === true)
|
|
85
94
|
return "user";
|
|
95
|
+
if (isUpstreamFailure(data))
|
|
96
|
+
return "system";
|
|
86
97
|
if (code === "INTERNAL_SERVER_ERROR")
|
|
87
98
|
return "system";
|
|
88
99
|
if (category === "document_processing" && data["userError"] !== true)
|
|
@@ -192,6 +203,14 @@ function inferSuggestion(code, message, data) {
|
|
|
192
203
|
? `Retry the request. If it keeps failing, contact support with requestId ${requestId}.`
|
|
193
204
|
: "Retry the request. If it keeps failing, contact support with the request details.";
|
|
194
205
|
}
|
|
206
|
+
if (reasonCode === "UPSTREAM_FETCH_FAILED")
|
|
207
|
+
return "The website blocked or failed the download. Download the file yourself and send it as file or base64, or retry later.";
|
|
208
|
+
if (reasonCode === "PDF_NOT_FETCHABLE")
|
|
209
|
+
return "The paper's open-access PDF could not be downloaded right now. Retry later, upload the PDF, or pass a direct PDF URL to document.parse.";
|
|
210
|
+
if (reasonCode === "CONTENT_TYPE_MISMATCH")
|
|
211
|
+
return "Send the original file: its content does not match the declared MIME type or extension.";
|
|
212
|
+
if (reasonCode === "ARCHIVE_TOO_LARGE")
|
|
213
|
+
return "Send the document itself or a smaller archive: this one expands beyond the processing limit.";
|
|
195
214
|
if (reasonCode === "EXTRACTION_FAILED")
|
|
196
215
|
return "Simplify the extraction schema or prompt, then retry.";
|
|
197
216
|
if (reasonCode === "MODEL_OUTPUT_UNUSABLE")
|
|
@@ -264,6 +283,7 @@ export class PDFVectorError extends Error {
|
|
|
264
283
|
this.retryableWithHigherModel = hasHigherModelHint(this.message, this.data);
|
|
265
284
|
this.retryable =
|
|
266
285
|
this.retryableWithHigherModel ||
|
|
286
|
+
isUpstreamFailure(this.data) ||
|
|
267
287
|
this.code === "TOO_MANY_REQUESTS" ||
|
|
268
288
|
this.code === "INTERNAL_SERVER_ERROR";
|
|
269
289
|
this.requestedModel = readString(this.data, "requestedModel");
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# @pdfvector/instance-client
|
|
2
2
|
|
|
3
|
+
## 0.1.2
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [#564](https://github.com/phuctm97/pdfvector/pull/564) [`6dcf020`](https://github.com/phuctm97/pdfvector/commit/6dcf0205899627e57b7824d7d7a2837f4537e336) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Failed requests are never charged and our own failures are no longer reported as the caller's.
|
|
8
|
+
|
|
9
|
+
- Billing: a request that ends in an error (any class) is billed 0 credits; provider calls it made stay in provider usage as our cost (before: an error after a successful provider call, such as the nano/mini text validator or the image text pre-check, was charged).
|
|
10
|
+
- Classification: user_error only for explicit caller faults (`data.userError`: input validation, size/page limits, unreadable uploads), contract validation and rate limits; an untagged BAD_REQUEST is a system error and reaches Sentry. "Retry with a higher model" is recorded as user_error with the usage code `HIGHER_MODEL_REQUIRED` so its rate stays visible. Ask/extract keep a system parse failure (e.g. `DOCUMENT_PROCESSING_FAILED`) instead of wrapping it in "try a higher model"; mini/pro OCR outages are system errors instead of "try a higher model"; a provider page limit within the tier's own limit is a processing failure, not a user BAD_REQUEST; when one engine failed on our side and another called the input bad, the system error wins; auto PDFs over Document AI's default page cap get a chunked Document AI pass before "no text" and report a system error if an engine was skipped.
|
|
11
|
+
- URL input: browser-like headers, 90 s timeout, a streaming size cap at the tier's file limit, a retry of 403/408/429/5xx and network errors through the residential proxy (redirect hops re-checked against private addresses). A site that still refuses is `UPSTREAM_FETCH_FAILED` (BAD_REQUEST, `statusCode`, `host`; not a user error, tracked instead of sent to Sentry); 401/404/410, unresolvable hosts, private share links and expired signed links stay user errors.
|
|
12
|
+
- academic.parse tries up to three open-access copies (OpenAlex locations, arXiv, Europe PMC) and the proxy; when none downloads, `PDF_NOT_FETCHABLE` keeps NOT_FOUND but is a system error with every attempt in `data.attempts`, and each download is a `other/document_fetch` provider-health event.
|
|
13
|
+
- Input validation: uploads and URL bodies are sniffed; a different supported format is processed as such, a mismatch (an HTML page sent as PDF) is `CONTENT_TYPE_MISMATCH`. ZIP uploads and ZIP-based Office/ODF/EPUB files are bounded (20,000 entries, 1 GB expanded, 200x past 100 MB: `ARCHIVE_TOO_LARGE`). A DOCX whose text is only in headers, footers or notes is no longer rejected as empty.
|
|
14
|
+
- Sentry events are rate limited per error key (10 per hour).
|
|
15
|
+
- SDK: `UPSTREAM_FETCH_FAILED` and `PDF_NOT_FETCHABLE` are system-origin, retryable errors with their own suggestions; `CONTENT_TYPE_MISMATCH` and `ARCHIVE_TOO_LARGE` get suggestions. The README lists the reason codes.
|
|
16
|
+
|
|
17
|
+
## 0.1.1
|
|
18
|
+
|
|
19
|
+
### Patch Changes
|
|
20
|
+
|
|
21
|
+
- [#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.
|
|
22
|
+
|
|
3
23
|
## 0.1.0
|
|
4
24
|
|
|
5
25
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -14,6 +14,10 @@ pnpm add @pdfvector/instance-client
|
|
|
14
14
|
bun add @pdfvector/instance-client
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
+
> **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.
|
|
18
|
+
|
|
19
|
+
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`.
|
|
20
|
+
|
|
17
21
|
## Quick Start
|
|
18
22
|
|
|
19
23
|
```typescript
|
|
@@ -60,6 +64,7 @@ const extractResult = await client.document.extract({
|
|
|
60
64
|
console.log(extractResult.data);
|
|
61
65
|
```
|
|
62
66
|
|
|
67
|
+
|
|
63
68
|
## Authentication
|
|
64
69
|
|
|
65
70
|
Get your API key from the [PDF Vector dashboard](https://app.pdfvector.com/instances/2?tab=settings).
|
|
@@ -627,6 +632,17 @@ All API errors are thrown as `PDFVectorError` instances. The SDK maps server err
|
|
|
627
632
|
|
|
628
633
|
For `INTERNAL_SERVER_ERROR`, the API returns a safe message and keeps the original provider failure in server diagnostics. Use `requestId` when contacting support. For document processing failures, check `reasonCode` and `retryableWithHigherModel` instead of parsing the message; `EXTRACTION_FAILED` identifies unusable structured output even if message wording changes. `DOCUMENT_PROCESSING_FAILED` identifies a processing rejection that was not confirmed to be a caller-input error, so the SDK suggests retrying or contacting support rather than changing the document. Error responses do not include raw AI output.
|
|
629
634
|
|
|
635
|
+
Reason codes (`reasonCode`, from the response's `data.code`) for document input:
|
|
636
|
+
|
|
637
|
+
| `reasonCode` | Status | Meaning |
|
|
638
|
+
| --- | --- | --- |
|
|
639
|
+
| `UPSTREAM_FETCH_FAILED` | 400 (`URLFetchError`) | The website behind `url` blocked, rate limited, failed or timed out the download, even through a retry from another network. Not a caller fault: `userError` is `false`, `retryable` is `true`; `statusCode` and `data.host` say what the site answered. Download the file and send it as `file`/`base64`, or retry later. A 401/404/410, a private share link or an expired signed link stays a user error. |
|
|
640
|
+
| `PDF_NOT_FETCHABLE` | 404 (`academic.parse`) | No open-access copy of the paper could be downloaded (each copy tried is in `data.attempts`). Retryable, not a caller fault. |
|
|
641
|
+
| `CONTENT_TYPE_MISMATCH` | 400 | The uploaded bytes are not the declared format (for example an HTML page sent as a PDF). A file whose real format differs but is supported is processed as its real format instead. |
|
|
642
|
+
| `ARCHIVE_TOO_LARGE` | 400 | A ZIP upload or ZIP-based Office/EPUB/ODF file has more than 20,000 entries or expands beyond 1 GB (or 200x its size past 100 MB). |
|
|
643
|
+
|
|
644
|
+
A request that ends in an error is never charged credits.
|
|
645
|
+
|
|
630
646
|
```typescript
|
|
631
647
|
import {
|
|
632
648
|
PDFVectorError,
|
|
@@ -720,7 +736,7 @@ try {
|
|
|
720
736
|
} else if (error instanceof UnauthorizedError) {
|
|
721
737
|
console.error("Invalid API key; check your dashboard");
|
|
722
738
|
} else if (error instanceof PaymentRequiredError) {
|
|
723
|
-
console.error(
|
|
739
|
+
console.error(error.message, error.payUrl ?? error.billingUrl ?? "");
|
|
724
740
|
} else if (error instanceof TooManyRequestsError) {
|
|
725
741
|
console.error(`Rate limit ${error.limit} exceeded; resets at ${error.resetAt}`);
|
|
726
742
|
} else if (error instanceof EmptyDocumentError) {
|
|
@@ -731,6 +747,44 @@ try {
|
|
|
731
747
|
}
|
|
732
748
|
```
|
|
733
749
|
|
|
750
|
+
### Out of credits and billing holds (402)
|
|
751
|
+
|
|
752
|
+
`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.
|
|
753
|
+
|
|
754
|
+
```typescript
|
|
755
|
+
import { PaymentRequiredError } from "@pdfvector/instance-client";
|
|
756
|
+
|
|
757
|
+
try {
|
|
758
|
+
await client.document.parse({ url: "https://example.com/document.pdf" });
|
|
759
|
+
} catch (error) {
|
|
760
|
+
if (error instanceof PaymentRequiredError) {
|
|
761
|
+
if (error.isBillingHold) {
|
|
762
|
+
// Unpaid invoice, missing payment method, dispute, or account hold.
|
|
763
|
+
console.error(error.message);
|
|
764
|
+
console.error(error.payUrl ?? error.billingUrl); // where to pay or fix billing
|
|
765
|
+
console.error(error.amountDue, error.currency); // minor units, e.g. 1900 "usd"
|
|
766
|
+
} else {
|
|
767
|
+
// error.isCreditsExhausted: the monthly credits are used up.
|
|
768
|
+
console.error(`${error.remainingCredits}/${error.totalCredits} credits left, reset on ${error.resetsAt}`);
|
|
769
|
+
}
|
|
770
|
+
}
|
|
771
|
+
}
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
| Field | Type | Description |
|
|
775
|
+
|-------|------|-------------|
|
|
776
|
+
| `isCreditsExhausted` | `boolean` | The monthly credits are used up |
|
|
777
|
+
| `isBillingHold` | `boolean` | Requests are blocked by a billing problem (`reasonCode` starts with `BILLING_`) |
|
|
778
|
+
| `totalCredits` | `number \| undefined` | Monthly credits of the plan |
|
|
779
|
+
| `remainingCredits` | `number \| undefined` | Credits left in the current period |
|
|
780
|
+
| `resetsAt` | `string \| undefined` | ISO date when the credits reset |
|
|
781
|
+
| `billingReason` | `string \| undefined` | Billing hold reason from the API |
|
|
782
|
+
| `invoiceCount` | `number \| undefined` | Number of unpaid invoices |
|
|
783
|
+
| `amountDue` | `number \| undefined` | Outstanding amount in minor currency units (cents) |
|
|
784
|
+
| `currency` | `string \| undefined` | Currency of `amountDue`, such as `usd` |
|
|
785
|
+
| `billingUrl` | `string \| undefined` | Billing page to update the payment method or see invoices |
|
|
786
|
+
| `payUrl` | `string \| undefined` | Direct link to pay the outstanding invoice (absent for disputes and account holds) |
|
|
787
|
+
|
|
734
788
|
### Error Class Hierarchy
|
|
735
789
|
|
|
736
790
|
```
|
|
@@ -740,14 +794,14 @@ PDFVectorError
|
|
|
740
794
|
│ ├── PageLimitExceededError — pageCount, pageLimit, model
|
|
741
795
|
│ ├── PasswordProtectedError
|
|
742
796
|
│ ├── UnsupportedFormatError — format, supportedFormats
|
|
743
|
-
│ ├── URLFetchError — url, statusCode, statusText
|
|
797
|
+
│ ├── URLFetchError — url, statusCode, statusText (reasonCode UPSTREAM_FETCH_FAILED: the site refused)
|
|
744
798
|
│ ├── InvalidDocumentURLError
|
|
745
799
|
│ ├── InvalidBase64Error
|
|
746
800
|
│ ├── TierNotSupportedError — documentType, model, allowedTypes
|
|
747
801
|
│ ├── InvalidSchemaError — reason
|
|
748
802
|
│ └── NoInputProvidedError
|
|
749
803
|
├── UnauthorizedError (401)
|
|
750
|
-
├── PaymentRequiredError (402) — totalCredits, remainingCredits, resetsAt
|
|
804
|
+
├── PaymentRequiredError (402) — totalCredits, remainingCredits, resetsAt, payUrl, billingUrl, …
|
|
751
805
|
├── NotFoundError (404)
|
|
752
806
|
│ ├── AcademicPaperNotFoundError — input, paperErrorCode
|
|
753
807
|
│ └── NoPublicPDFError — input, paperTitle, doi, providerURL
|
|
@@ -790,7 +844,7 @@ Use `error.toAgentError()` or `JSON.stringify(error)` when you need a serializab
|
|
|
790
844
|
|------|--------|-------------|
|
|
791
845
|
| `BAD_REQUEST` | 400 | Input validation failed, including invalid URLs, unsupported formats, file size limits, page limits, invalid base64, and invalid JSON Schema |
|
|
792
846
|
| `UNAUTHORIZED` | 401 | Missing, invalid or deleted API key |
|
|
793
|
-
| `PAYMENT_REQUIRED` | 402 | The workspace has used all of its monthly credits
|
|
847
|
+
| `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) |
|
|
794
848
|
| `NOT_FOUND` | 404 | Resource not found, including academic paper IDs and papers without public PDFs |
|
|
795
849
|
| `CONFLICT` | 409 | Operation conflicts with the current state |
|
|
796
850
|
| `UNPROCESSABLE_CONTENT` | 422 | Document could not be processed, including empty documents, no readable text, and extraction failures |
|
|
@@ -853,12 +907,15 @@ import type {
|
|
|
853
907
|
} from "@pdfvector/instance-client";
|
|
854
908
|
```
|
|
855
909
|
|
|
856
|
-
|
|
910
|
+
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`.
|
|
911
|
+
|
|
912
|
+
The contract (oRPC router with zod schemas) and `pdfvectorModelSchema` are exported from the main entry:
|
|
857
913
|
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
914
|
+
```typescript
|
|
915
|
+
import { contract, pdfvectorModelSchema } from "@pdfvector/instance-client";
|
|
916
|
+
|
|
917
|
+
pdfvectorModelSchema.parse("nano"); // "nano" | "mini" | "pro" | "max"
|
|
918
|
+
```
|
|
862
919
|
|
|
863
920
|
## Support
|
|
864
921
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pdfvector/instance-client",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"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",
|
|
6
6
|
"license": "MIT",
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
},
|
|
34
34
|
"main": ".tsc/lib/index.js",
|
|
35
35
|
"dependencies": {
|
|
36
|
-
"@pdfvector/instance-contract": "^0.2.
|
|
36
|
+
"@pdfvector/instance-contract": "^0.2.27"
|
|
37
37
|
},
|
|
38
38
|
"types": ".tsc/lib/index.d.ts",
|
|
39
39
|
"files": [
|