@pdfvector/instance-contract 0.0.46 → 0.0.48

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

@@ -1,6 +1,7 @@
 export * from "./fetch.js";
 export * from "./find-citations.js";
 export * from "./paper-graph.js";
+export * from "./parse.js";
 export * from "./search.js";
 export * from "./search-grants.js";
 export * from "./similar-papers.js";

package/.tsc/lib/router/academic/index.js

@@ -1,6 +1,7 @@
 export * from "./fetch.js";
 export * from "./find-citations.js";
 export * from "./paper-graph.js";
+export * from "./parse.js";
 export * from "./search.js";
 export * from "./search-grants.js";
 export * from "./similar-papers.js";

package/.tsc/lib/router/academic/parse.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const parse: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodURL>;
+    model: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        pro: "pro";
+        nano: "nano";
+        mini: "mini";
+        max: "max";
+        auto: "auto";
+    }>>>;
+    callback: z.ZodOptional<z.ZodObject<{
+        url: z.ZodURL;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    doi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    providerURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    pdfURL: z.ZodString;
+    detectedProvider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        "semantic-scholar": "semantic-scholar";
+        pubmed: "pubmed";
+        arxiv: "arxiv";
+        "google-scholar": "google-scholar";
+        eric: "eric";
+        "europe-pmc": "europe-pmc";
+        openalex: "openalex";
+        crossref: "crossref";
+    }>>>;
+    markdown: z.ZodString;
+    pageCount: z.ZodNumber;
+    model: z.ZodEnum<{
+        pro: "pro";
+        nano: "nano";
+        mini: "mini";
+        max: "max";
+    }>;
+    credits: z.ZodNumber;
+    requestId: z.ZodNumber;
+    html: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/academic/parse.js

@@ -0,0 +1,126 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { fetchableUrlSchema } from "../../fetchable-url-schema.js";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema.js";
+import { documentParseModelDescription, outputModelDescription, } from "../../supported-mimes.js";
+import { providerSchema } from "./provider.js";
+const callbackSchema = z
+    .object({
+    url: fetchableUrlSchema.describe("Webhook URL where results will be POSTed when processing completes"),
+    type: z
+        .string()
+        .optional()
+        .describe("Callback type identifier (e.g. 'zapier')"),
+})
+    .optional()
+    .describe("Optional webhook callback for async processing. " +
+    "When provided, the server returns 202 immediately and POSTs the full response payload to the callback URL when processing completes. " +
+    "On error, the callback receives a POST with X-Pdfvector-Callback-Failed: true header and error details in the body. " +
+    "Useful for long-running operations that may exceed client timeout limits.");
+const parseInputSchema = z
+    .object({
+    id: z
+        .string({ message: "id must be a string" })
+        .trim()
+        .min(1, "id must be a non-empty string")
+        .optional()
+        .describe("Publication identifier to resolve and parse. Supports DOI, PubMed ID, ArXiv ID, Semantic Scholar ID, ERIC ID, Europe PMC ID, OpenAlex ID."),
+    url: fetchableUrlSchema
+        .optional()
+        .describe("Publication URL to resolve and parse. Supports known provider URLs such as DOI, ArXiv, PubMed, Semantic Scholar, ERIC, Europe PMC, OpenAlex, Springer, Nature, bioRxiv, and medRxiv."),
+    model: z
+        .enum(["auto", ...pdfvectorModelSchema.options])
+        .optional()
+        .default("auto")
+        .describe(documentParseModelDescription),
+    callback: callbackSchema,
+})
+    .superRefine((input, ctx) => {
+    const hasId = typeof input.id === "string" && input.id.length > 0;
+    const hasUrl = typeof input.url === "string" && input.url.length > 0;
+    if (hasId === hasUrl) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["id"],
+            message: "Provide exactly one of id or url",
+        });
+    }
+});
+const parseOutputSchema = z.object({
+    id: z.string().describe("Original input identifier or URL"),
+    title: z.string().nullish().describe("Publication title, if available"),
+    doi: z.string().nullish().describe("Publication DOI, if available"),
+    url: z
+        .string()
+        .nullish()
+        .describe("PDF Vector publication URL, if available"),
+    providerURL: z
+        .string()
+        .nullish()
+        .describe("Provider publication page URL, if available"),
+    pdfURL: z.string().describe("Resolved public PDF URL used for parsing"),
+    detectedProvider: providerSchema
+        .nullish()
+        .describe("Provider detected from the input identifier or URL"),
+    markdown: z
+        .string()
+        .describe("Extracted markdown content from the paper PDF"),
+    pageCount: z
+        .number()
+        .int()
+        .describe("Total number of pages in the paper PDF"),
+    model: pdfvectorModelSchema.describe(outputModelDescription),
+    credits: z
+        .number()
+        .int()
+        .describe("Number of credits consumed by this API call. Cost per page: nano=1, mini=2, pro=4, max=8."),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    html: z
+        .string()
+        .optional()
+        .describe("Full HTML representation of the paper content. Only available when using the 'max' model."),
+});
+const requestExamples = {
+    "Parse ArXiv paper by ID": {
+        summary: "Parse ArXiv paper by ID",
+        value: {
+            id: "1706.03762",
+            model: "auto",
+        },
+    },
+    "Parse paper by DOI URL": {
+        summary: "Parse paper by DOI URL",
+        value: {
+            url: "https://doi.org/10.1038/nature12373",
+            model: "pro",
+        },
+    },
+    "Parse PubMed paper by ID": {
+        summary: "Parse PubMed paper by ID",
+        value: {
+            id: "33116299",
+            model: "auto",
+        },
+    },
+};
+export const parse = oc
+    .input(parseInputSchema)
+    .output(parseOutputSchema)
+    .route({
+    summary: "Parse an academic paper to markdown",
+    description: "Resolve an academic paper URL or identifier to a public PDF URL, parse the PDF, and return markdown using the same model tiers as document.parse. Returns NOT_FOUND when the paper cannot be found or no public PDF is available.",
+    tags: ["Academic"],
+    spec: (op) => {
+        op.security = [{ bearerAuth: [] }];
+        const reqBody = op.requestBody;
+        if (reqBody?.content) {
+            for (const mediaType of Object.values(reqBody.content)) {
+                mediaType.examples = requestExamples;
+            }
+        }
+        return op;
+    },
+});

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @pdfvector/instance-contract
 
+## 0.0.48
+### Patch Changes
+
+
+
+- [#250](https://github.com/phuctm97/pdfvector/pull/250) [`a2e6883`](https://github.com/phuctm97/pdfvector/commit/a2e68833d9f0dd6b38ea5b4b2a91aefb9f13aaf8) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Upgrade workspace dependencies and adapt SPA navigation state typing for React Router 7.15.1.
+
+## 0.0.47
+### Patch Changes
+
+
+
+- [#240](https://github.com/phuctm97/pdfvector/pull/240) [`2c8691c`](https://github.com/phuctm97/pdfvector/commit/2c8691c9bbd251ff7b7a153fd4254d9360c11c08) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Add academic.parse to resolve academic paper IDs or provider URLs to public PDFs and parse them to markdown.
+
 ## 0.0.46
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/instance-contract",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "type": "module",
   "description": "API contract definitions for PDF Vector instance server",
   "license": "MIT",
@@ -20,8 +20,8 @@
   },
   "main": ".tsc/lib/index.js",
   "dependencies": {
-    "@orpc/client": "^1.14.2",
-    "@orpc/contract": "^1.14.2",
+    "@orpc/client": "^1.14.3",
+    "@orpc/contract": "^1.14.3",
     "@pdfvector/util": "0.0.22"
   },
   "peerDependencies": {