@pdfvector/instance-contract 0.0.28 → 0.0.30

package/.tsc/lib/router/academic/find-citations.d.ts

@@ -9,6 +9,7 @@ export declare const findCitations: import("@orpc/contract").ContractProcedureBu
         eric: "eric";
         "europe-pmc": "europe-pmc";
         openalex: "openalex";
+        crossref: "crossref";
     }>>>;
     fields: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodEnum<{
         url: "url";

package/.tsc/lib/router/academic/find-citations.js

@@ -8,8 +8,9 @@ const providerSchema = z.enum([
     "eric",
     "europe-pmc",
     "openalex",
+    "crossref",
 ], {
-    message: "Invalid provider. Must be one of: semantic-scholar, pubmed, arxiv, google-scholar, eric, europe-pmc, openalex",
+    message: "Invalid provider. Must be one of: semantic-scholar, pubmed, arxiv, google-scholar, eric, europe-pmc, openalex, crossref",
 });
 const authorSchema = z.object({
     name: z.string(),

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

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

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

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

package/.tsc/lib/router/academic/paper-graph.d.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+export declare const paperGraph: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    id: z.ZodString;
+    citationsLimit: z.ZodDefault<z.ZodNumber>;
+    referencesLimit: z.ZodDefault<z.ZodNumber>;
+    citationsOffset: z.ZodDefault<z.ZodNumber>;
+    referencesOffset: z.ZodDefault<z.ZodNumber>;
+    fields: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodEnum<{
+        url: "url";
+        doi: "doi";
+        title: "title";
+        providerURL: "providerURL";
+        date: "date";
+        authors: "authors";
+        year: "year";
+        totalCitations: "totalCitations";
+        totalReferences: "totalReferences";
+        abstract: "abstract";
+        pdfURL: "pdfURL";
+        provider: "provider";
+        providerData: "providerData";
+    }>>>>;
+    callback: z.ZodOptional<z.ZodObject<{
+        url: z.ZodURL;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    paper: z.ZodObject<{
+        doi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authors: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalCitations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalReferences: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pdfURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>;
+    citations: z.ZodArray<z.ZodObject<{
+        doi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authors: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalCitations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalReferences: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pdfURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>;
+    references: z.ZodArray<z.ZodObject<{
+        doi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authors: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalCitations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalReferences: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pdfURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>;
+    totalCitations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    totalReferences: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    requestId: z.ZodNumber;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/academic/paper-graph.js

@@ -0,0 +1,140 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+const authorSchema = z.object({
+    name: z.string(),
+    url: z.string().nullish(),
+});
+const publicationSchema = z.object({
+    doi: z.string().nullish(),
+    title: z.string().nullish(),
+    url: z.string().nullish(),
+    providerURL: z.string().nullish(),
+    authors: z.array(authorSchema).nullish(),
+    date: z.string().nullish(),
+    year: z.number().nullish(),
+    totalCitations: z.number().nullish(),
+    totalReferences: z.number().nullish(),
+    abstract: z.string().nullish(),
+    pdfURL: z.string().nullish(),
+    provider: z.string().nullish(),
+    providerData: z.record(z.string(), z.unknown()).nullish(),
+});
+const requestExamples = {
+    "Get citations by DOI": {
+        summary: "Get citations and references for a paper by DOI",
+        value: {
+            id: "10.1038/nature12373",
+            citationsLimit: 20,
+            referencesLimit: 20,
+        },
+    },
+    "Get citations by ArXiv ID": {
+        summary: "Get citations and references for an ArXiv paper",
+        value: {
+            id: "2303.08774",
+            citationsLimit: 50,
+            referencesLimit: 50,
+        },
+    },
+    "Paginated citations": {
+        summary: "Page through a paper's citations",
+        value: {
+            id: "10.1038/nature12373",
+            citationsLimit: 20,
+            citationsOffset: 20,
+            referencesLimit: 0,
+        },
+    },
+};
+export const paperGraph = oc
+    .input(z.object({
+    id: z
+        .string({ message: "id is required and must be a string" })
+        .min(1, "id must not be empty")
+        .max(500, "id must be at most 500 characters")
+        .describe("Paper identifier. Supports DOI, Semantic Scholar ID, ArXiv ID, PubMed ID, OpenAlex ID, or URL."),
+    citationsLimit: z
+        .number({ message: "citationsLimit must be a number" })
+        .int("citationsLimit must be a whole number")
+        .min(0, "citationsLimit must be 0 or greater")
+        .max(1000, "citationsLimit must be at most 1000")
+        .default(100)
+        .describe("Maximum number of citing papers to return"),
+    referencesLimit: z
+        .number({ message: "referencesLimit must be a number" })
+        .int("referencesLimit must be a whole number")
+        .min(0, "referencesLimit must be 0 or greater")
+        .max(1000, "referencesLimit must be at most 1000")
+        .default(100)
+        .describe("Maximum number of referenced papers to return"),
+    citationsOffset: z
+        .number({ message: "citationsOffset must be a number" })
+        .int("citationsOffset must be a whole number")
+        .min(0, "citationsOffset must be 0 or greater")
+        .default(0)
+        .describe("Pagination offset for citations"),
+    referencesOffset: z
+        .number({ message: "referencesOffset must be a number" })
+        .int("referencesOffset must be a whole number")
+        .min(0, "referencesOffset must be 0 or greater")
+        .default(0)
+        .describe("Pagination offset for references"),
+    fields: z
+        .array(z.enum([
+        "doi",
+        "title",
+        "url",
+        "providerURL",
+        "authors",
+        "date",
+        "year",
+        "totalCitations",
+        "totalReferences",
+        "abstract",
+        "pdfURL",
+        "provider",
+        "providerData",
+    ]), {
+        message: "fields must be an array of valid publication field names",
+    })
+        .nullish()
+        .describe("Specific publication fields to return. If omitted, returns all fields except providerData."),
+    callback: z
+        .object({
+        url: z
+            .url()
+            .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."),
+}))
+    .output(z.object({
+    paper: publicationSchema,
+    citations: z.array(publicationSchema),
+    references: z.array(publicationSchema),
+    totalCitations: z.number().int().nullish(),
+    totalReferences: z.number().int().nullish(),
+    requestId: z.number().int(),
+}))
+    .route({
+    summary: "Get paper citations and references",
+    description: "Fetch a paper's citing papers and referenced papers as full publication objects with automatic provider detection and pagination support.",
+    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/.tsc/lib/router/academic/search-grants.d.ts

@@ -0,0 +1,78 @@
+import { z } from "zod";
+export declare const searchGrants: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    query: z.ZodString;
+    providers: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        "grants-gov": "grants-gov";
+        "nih-reporter": "nih-reporter";
+        cordis: "cordis";
+        ukri: "ukri";
+    }>>>;
+    offset: z.ZodDefault<z.ZodNumber>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    deadlineFrom: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deadlineTo: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fundingMin: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fundingMax: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    fields: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodEnum<{
+        url: "url";
+        title: "title";
+        provider: "provider";
+        providerData: "providerData";
+        description: "description";
+        sourceId: "sourceId";
+        agency: "agency";
+        program: "program";
+        eligibility: "eligibility";
+        fundingAmountMin: "fundingAmountMin";
+        fundingAmountMax: "fundingAmountMax";
+        currency: "currency";
+        deadlineDate: "deadlineDate";
+        openDate: "openDate";
+        closeDate: "closeDate";
+        grantType: "grantType";
+        region: "region";
+        keywords: "keywords";
+        piName: "piName";
+        organizationName: "organizationName";
+    }>>>>;
+    callback: z.ZodOptional<z.ZodObject<{
+        url: z.ZodURL;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    estimatedTotalResults: z.ZodNumber;
+    results: z.ZodArray<z.ZodObject<{
+        sourceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        agency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        program: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        eligibility: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fundingAmountMin: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        fundingAmountMax: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        currency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        deadlineDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        openDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        closeDate: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        grantType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        region: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        keywords: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        piName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        organizationName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            "grants-gov": "grants-gov";
+            "nih-reporter": "nih-reporter";
+            cordis: "cordis";
+            ukri: "ukri";
+        }>>>;
+        providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>;
+    errors: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        provider: z.ZodString;
+        message: z.ZodString;
+        code: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        details: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>>>;
+    requestId: z.ZodNumber;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/academic/search-grants.js

@@ -0,0 +1,170 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+const grantProviderSchema = z.enum(["grants-gov", "nih-reporter", "cordis", "ukri"], {
+    message: "Invalid provider. Must be one of: grants-gov, nih-reporter, cordis, ukri",
+});
+const grantSchema = z.object({
+    sourceId: z.string().nullish(),
+    title: z.string().nullish(),
+    url: z.string().nullish(),
+    agency: z.string().nullish(),
+    program: z.string().nullish(),
+    description: z.string().nullish(),
+    eligibility: z.string().nullish(),
+    fundingAmountMin: z.number().nullish(),
+    fundingAmountMax: z.number().nullish(),
+    currency: z.string().nullish(),
+    deadlineDate: z.string().nullish(),
+    openDate: z.string().nullish(),
+    closeDate: z.string().nullish(),
+    grantType: z.string().nullish(),
+    region: z.string().nullish(),
+    keywords: z.array(z.string()).nullish(),
+    piName: z.string().nullish(),
+    organizationName: z.string().nullish(),
+    provider: grantProviderSchema.nullish(),
+    providerData: z.record(z.string(), z.unknown()).nullish(),
+});
+const providerErrorSchema = z.object({
+    provider: z.string(),
+    message: z.string(),
+    code: z.string().nullish(),
+    details: z.record(z.string(), z.unknown()).nullish(),
+});
+const requestExamples = {
+    "Search all providers": {
+        summary: "Search grants across all funding databases",
+        value: {
+            query: "machine learning healthcare",
+        },
+    },
+    "Search with filters": {
+        summary: "Search with funding and deadline filters",
+        value: {
+            query: "climate change research",
+            providers: ["grants-gov", "cordis"],
+            fundingMin: 50000,
+            fundingMax: 500000,
+            deadlineFrom: "2026-01-01",
+            deadlineTo: "2026-12-31",
+            limit: 20,
+        },
+    },
+    "Search specific provider": {
+        summary: "Search NIH grants only",
+        value: {
+            query: "CRISPR gene therapy",
+            providers: ["nih-reporter"],
+            limit: 10,
+        },
+    },
+};
+export const searchGrants = oc
+    .input(z.object({
+    query: z
+        .string({ message: "query is required and must be a string" })
+        .min(1, "query must not be empty")
+        .max(400, "query must be at most 400 characters")
+        .describe("Search query string for grants"),
+    providers: z
+        .array(grantProviderSchema, {
+        message: "providers must be an array of valid grant provider names",
+    })
+        .default(["grants-gov", "nih-reporter", "cordis", "ukri"])
+        .describe("Grant databases to search. Defaults to all providers."),
+    offset: z
+        .number({ message: "offset must be a number" })
+        .int("offset must be a whole number")
+        .min(0, "offset must be 0 or greater")
+        .default(0)
+        .describe("Results offset for pagination"),
+    limit: z
+        .number({ message: "limit must be a number" })
+        .int("limit must be a whole number")
+        .min(1, "limit must be at least 1")
+        .max(50, "limit must be at most 50")
+        .default(10)
+        .describe("Maximum results per provider"),
+    deadlineFrom: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, "deadlineFrom must be in ISO date format (YYYY-MM-DD)")
+        .nullish()
+        .describe("Filter grants with deadlines from this date (ISO format, e.g. 2026-01-01)"),
+    deadlineTo: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/, "deadlineTo must be in ISO date format (YYYY-MM-DD)")
+        .nullish()
+        .describe("Filter grants with deadlines up to this date (ISO format, e.g. 2026-12-31)"),
+    fundingMin: z
+        .number({ message: "fundingMin must be a number" })
+        .min(0, "fundingMin must be 0 or greater")
+        .nullish()
+        .describe("Minimum funding amount filter"),
+    fundingMax: z
+        .number({ message: "fundingMax must be a number" })
+        .min(0, "fundingMax must be 0 or greater")
+        .nullish()
+        .describe("Maximum funding amount filter"),
+    fields: z
+        .array(z.enum([
+        "sourceId",
+        "title",
+        "url",
+        "agency",
+        "program",
+        "description",
+        "eligibility",
+        "fundingAmountMin",
+        "fundingAmountMax",
+        "currency",
+        "deadlineDate",
+        "openDate",
+        "closeDate",
+        "grantType",
+        "region",
+        "keywords",
+        "piName",
+        "organizationName",
+        "provider",
+        "providerData",
+    ]), {
+        message: "fields must be an array of valid grant field names",
+    })
+        .nullish()
+        .describe("Specific grant fields to return. If omitted, returns all fields except providerData."),
+    callback: z
+        .object({
+        url: z
+            .url()
+            .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."),
+}))
+    .output(z.object({
+    estimatedTotalResults: z.number(),
+    results: z.array(grantSchema),
+    errors: z.array(providerErrorSchema).nullish(),
+    requestId: z.number().int(),
+}))
+    .route({
+    summary: "Search grants",
+    description: "Search for research grants and funding opportunities across multiple databases (Grants.gov, NIH RePORTER, CORDIS, UKRI) with unified results, relevance ranking, and filtering by deadline and funding amount.",
+    tags: ["Grant"],
+    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/.tsc/lib/router/academic/search.d.ts

@@ -9,6 +9,7 @@ export declare const search: import("@orpc/contract").ContractProcedureBuilderWi
         eric: "eric";
         "europe-pmc": "europe-pmc";
         openalex: "openalex";
+        crossref: "crossref";
     }>>>;
     offset: z.ZodDefault<z.ZodNumber>;
     limit: z.ZodDefault<z.ZodNumber>;
@@ -58,6 +59,7 @@ export declare const search: import("@orpc/contract").ContractProcedureBuilderWi
             eric: "eric";
             "europe-pmc": "europe-pmc";
             openalex: "openalex";
+            crossref: "crossref";
         }>>>;
         providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
     }, z.core.$strip>>;

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

@@ -8,8 +8,9 @@ const providerSchema = z.enum([
     "eric",
     "europe-pmc",
     "openalex",
+    "crossref",
 ], {
-    message: "Invalid provider. Must be one of: semantic-scholar, pubmed, arxiv, google-scholar, eric, europe-pmc, openalex",
+    message: "Invalid provider. Must be one of: semantic-scholar, pubmed, arxiv, google-scholar, eric, europe-pmc, openalex, crossref",
 });
 const authorSchema = z.object({
     name: z.string(),

package/.tsc/lib/router/academic/similar-papers.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+export declare const similarPapers: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    id: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+    includeEdges: z.ZodDefault<z.ZodBoolean>;
+    fields: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodEnum<{
+        url: "url";
+        doi: "doi";
+        title: "title";
+        providerURL: "providerURL";
+        date: "date";
+        authors: "authors";
+        year: "year";
+        totalCitations: "totalCitations";
+        totalReferences: "totalReferences";
+        abstract: "abstract";
+        pdfURL: "pdfURL";
+        provider: "provider";
+        providerData: "providerData";
+    }>>>>;
+    callback: z.ZodOptional<z.ZodObject<{
+        url: z.ZodURL;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    seed: z.ZodObject<{
+        doi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authors: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>>;
+        date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalCitations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        totalReferences: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pdfURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>;
+    results: z.ZodArray<z.ZodObject<{
+        publication: z.ZodObject<{
+            doi: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            providerURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            authors: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            }, z.core.$strip>>>>;
+            date: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            year: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            totalCitations: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            totalReferences: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            abstract: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            pdfURL: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            provider: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            providerData: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        }, z.core.$strip>;
+        similarity: z.ZodNumber;
+        pageRank: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        distance: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        citingIds: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+        citedByIds: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    }, z.core.$strip>>;
+    requestId: z.ZodNumber;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/academic/similar-papers.js

@@ -0,0 +1,139 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+const authorSchema = z.object({
+    name: z.string(),
+    url: z.string().nullish(),
+});
+const publicationSchema = z.object({
+    doi: z.string().nullish(),
+    title: z.string().nullish(),
+    url: z.string().nullish(),
+    providerURL: z.string().nullish(),
+    authors: z.array(authorSchema).nullish(),
+    date: z.string().nullish(),
+    year: z.number().nullish(),
+    totalCitations: z.number().nullish(),
+    totalReferences: z.number().nullish(),
+    abstract: z.string().nullish(),
+    pdfURL: z.string().nullish(),
+    provider: z.string().nullish(),
+    providerData: z.record(z.string(), z.unknown()).nullish(),
+});
+const similarPaperSchema = z.object({
+    publication: publicationSchema,
+    similarity: z
+        .number()
+        .describe("Combined similarity score from citation network analysis"),
+    pageRank: z.number().nullish().describe("Citation network importance score"),
+    distance: z
+        .number()
+        .int()
+        .nullish()
+        .describe("Graph distance from seed paper"),
+    citingIds: z
+        .array(z.string())
+        .nullish()
+        .describe("OpenAlex IDs of papers in result set that cite this paper (only if includeEdges=true)"),
+    citedByIds: z
+        .array(z.string())
+        .nullish()
+        .describe("OpenAlex IDs of papers in result set cited by this paper (only if includeEdges=true)"),
+});
+const requestExamples = {
+    "Find similar papers by DOI": {
+        summary: "Find papers similar to a given paper",
+        value: {
+            id: "10.1038/nature12373",
+            limit: 20,
+        },
+    },
+    "Find similar with edges": {
+        summary: "Find similar papers with citation graph edges",
+        value: {
+            id: "10.1038/nature12373",
+            limit: 20,
+            includeEdges: true,
+        },
+    },
+    "Find similar by OpenAlex ID": {
+        summary: "Find similar papers using an OpenAlex ID",
+        value: {
+            id: "W2963403868",
+            limit: 10,
+        },
+    },
+};
+export const similarPapers = oc
+    .input(z.object({
+    id: z
+        .string({ message: "id is required and must be a string" })
+        .min(1, "id must not be empty")
+        .max(500, "id must be at most 500 characters")
+        .describe("Seed paper identifier. Supports DOI, Semantic Scholar ID, ArXiv ID, PubMed ID, OpenAlex ID, or URL."),
+    limit: z
+        .number({ message: "limit must be a number" })
+        .int("limit must be a whole number")
+        .min(1, "limit must be at least 1")
+        .max(100, "limit must be at most 100")
+        .default(30)
+        .describe("Maximum number of similar papers to return"),
+    includeEdges: z
+        .boolean({ message: "includeEdges must be a boolean" })
+        .default(false)
+        .describe("Whether to include citing/cited_by edge data for graph construction"),
+    fields: z
+        .array(z.enum([
+        "doi",
+        "title",
+        "url",
+        "providerURL",
+        "authors",
+        "date",
+        "year",
+        "totalCitations",
+        "totalReferences",
+        "abstract",
+        "pdfURL",
+        "provider",
+        "providerData",
+    ]), {
+        message: "fields must be an array of valid publication field names",
+    })
+        .nullish()
+        .describe("Specific publication fields to return. If omitted, returns all fields except providerData."),
+    callback: z
+        .object({
+        url: z
+            .url()
+            .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."),
+}))
+    .output(z.object({
+    seed: publicationSchema,
+    results: z.array(similarPaperSchema),
+    requestId: z.number().int(),
+}))
+    .route({
+    summary: "Find similar papers",
+    description: "Find papers similar to a seed paper using citation network analysis. Returns papers ranked by similarity with optional graph edge data for visualization.",
+    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.30
+### Patch Changes
+
+
+
+- [#150](https://github.com/phuctm97/pdfvector/pull/150) [`aaf8ba1`](https://github.com/phuctm97/pdfvector/commit/aaf8ba1a73c4076cc63c17fcd47e463b05d7db2a) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Add grant search API and remove unused academic providers
+
+## 0.0.29
+### Patch Changes
+
+
+
+- [#149](https://github.com/phuctm97/pdfvector/pull/149) [`bcffa28`](https://github.com/phuctm97/pdfvector/commit/bcffa2840c98af3e8ab0c971e61d580beedd3b85) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Add academic paper graph and similar papers APIs with integration tests
+
 ## 0.0.28
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/instance-contract",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "type": "module",
   "description": "API contract definitions for PDFVector instance server",
   "license": "MIT",