@pdfvector/instance-contract 0.0.17 → 0.0.19

package/.tsc/lib/router/bankStatement/ask.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const ask: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    question: z.ZodString;
+    model: z.ZodDefault<z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    markdown: z.ZodString;
+    model: z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/bankStatement/ask.js

@@ -0,0 +1,70 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedModelSchema = z
+    .enum(["auto", ...pdfvectorModelSchema.options])
+    .default("auto");
+const askInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the bank statement file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Bank statement file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded bank statement file content"),
+    question: z
+        .string()
+        .min(4)
+        .describe("The question to answer about the bank statement"),
+    model: specializedModelSchema.describe("Model tier for answering the question. " +
+        "'auto' (default): Automatically selects the best tier. " +
+        "'nano': Uses lightweight models. " +
+        "'mini': Uses mid-range models. " +
+        "'pro': Uses capable models. " +
+        "'max': Uses the most powerful models."),
+});
+const askOutputSchema = z.object({
+    markdown: z.string().describe("The answer to the question"),
+    model: pdfvectorModelSchema.describe("Model tier used to answer the question"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Ask from URL": {
+        summary: "Ask from URL",
+        value: {
+            url: "https://example.com/bank-statement.pdf",
+            question: "What is the ending balance?",
+        },
+    },
+};
+export const ask = oc
+    .route({
+    summary: "Ask a question about a bank statement",
+    description: "Parse a bank statement and answer a question about its content using AI. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Bank Statement"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(askInputSchema)
+    .output(askOutputSchema);

package/.tsc/lib/router/bankStatement/extract.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const extract: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    schema: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodPipe<z.ZodString, z.ZodTransform<Record<string, unknown>, string>>]>;
+    model: z.ZodDefault<z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodUnknown;
+    model: z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/bankStatement/extract.js

@@ -0,0 +1,117 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedModelSchema = z
+    .enum(["auto", ...pdfvectorModelSchema.options])
+    .default("auto");
+const extractInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the bank statement file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Bank statement file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded bank statement file content"),
+    prompt: z
+        .string()
+        .min(4)
+        .describe("The prompt instructing the AI how to extract data from the bank statement"),
+    schema: z
+        .union([
+        z.record(z.string(), z.unknown()),
+        z.string().transform((str, ctx) => {
+            try {
+                const trimmed = str.startsWith('"') && str.endsWith('"') ? str.slice(1, -1) : str;
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed !== "object" || parsed === null) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: "Schema must be a JSON object",
+                    });
+                    return z.NEVER;
+                }
+                return parsed;
+            }
+            catch {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "Invalid JSON string for schema",
+                });
+                return z.NEVER;
+            }
+        }),
+    ])
+        .describe("JSON Schema describing the structure of the data to extract from the bank statement. Can be a JSON object or a JSON string."),
+    model: specializedModelSchema.describe("Model tier for extracting structured data. " +
+        "'auto' (default): Automatically selects the best tier. " +
+        "'nano': Uses lightweight models. " +
+        "'mini': Uses mid-range models. " +
+        "'pro': Uses capable models. " +
+        "'max': Uses the most powerful models."),
+});
+const extractOutputSchema = z.object({
+    data: z
+        .unknown()
+        .describe("Extracted structured data matching the provided JSON Schema"),
+    model: pdfvectorModelSchema.describe("Model tier used to extract the data"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Extract from URL": {
+        summary: "Extract from URL",
+        value: {
+            url: "https://example.com/bank-statement.pdf",
+            prompt: "Extract the account number, statement period, and transactions",
+            schema: JSON.stringify({
+                type: "object",
+                properties: {
+                    accountNumber: { type: "string" },
+                    statementPeriod: { type: "string" },
+                    transactions: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                date: { type: "string" },
+                                description: { type: "string" },
+                                amount: { type: "number" },
+                            },
+                        },
+                    },
+                },
+                required: ["accountNumber", "statementPeriod"],
+            }),
+        },
+    },
+};
+export const extract = oc
+    .route({
+    summary: "Extract structured data from a bank statement",
+    description: "Parse a bank statement and extract structured data matching a provided JSON Schema using AI. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Bank Statement"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(extractInputSchema)
+    .output(extractOutputSchema);

package/.tsc/lib/router/bankStatement/get-default-spec.d.ts

@@ -0,0 +1 @@
+export declare function getDefaultSpec(op: Record<string, unknown>, requestExamples: Record<string, unknown>): Record<string, unknown>;

package/.tsc/lib/router/bankStatement/get-default-spec.js

@@ -0,0 +1,19 @@
+export function getDefaultSpec(op, requestExamples) {
+    op.security = [{ bearerAuth: [] }];
+    const params = (op.parameters ?? []);
+    params.push({
+        name: "x-pdfvector-document-id",
+        in: "header",
+        required: false,
+        schema: { type: "string", default: "my-doc-123" },
+        description: "Optional document ID to associate with this request. Returned in the response and saved for usage tracking.",
+    });
+    op.parameters = params;
+    const reqBody = op.requestBody;
+    if (reqBody?.content) {
+        for (const mediaType of Object.values(reqBody.content)) {
+            mediaType.examples = requestExamples;
+        }
+    }
+    return op;
+}

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

@@ -0,0 +1,3 @@
+export * from "./ask";
+export * from "./extract";
+export * from "./parse";

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

@@ -0,0 +1,3 @@
+export * from "./ask";
+export * from "./extract";
+export * from "./parse";

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const parse: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    model: z.ZodDefault<z.ZodEnum<{
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    markdown: z.ZodString;
+    pageCount: z.ZodNumber;
+    model: z.ZodEnum<{
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    html: z.ZodOptional<z.ZodString>;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

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

@@ -0,0 +1,84 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedParseModelSchema = z
+    .enum(["pro", "max", "auto"])
+    .default("auto");
+const parseInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the bank statement file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Bank statement file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded bank statement file content"),
+    model: specializedParseModelSchema.describe("Model tier for parsing. " +
+        "'auto' (default): Automatically selects the best parsing strategy with intelligent fallback. " +
+        "'pro': Extracts structured bank statement fields with standard accuracy. " +
+        "'max': Extracts structured bank statement fields with highest accuracy and fallback."),
+});
+const parseOutputSchema = z.object({
+    markdown: z
+        .string()
+        .describe("Extracted text content from the bank statement"),
+    pageCount: z.number().int().describe("Total number of pages in the document"),
+    model: z
+        .enum(["pro", "max"])
+        .describe("Model tier used to parse the bank statement"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    html: z
+        .string()
+        .optional()
+        .describe("Full HTML representation of the document content. Only available when using the 'max' model. " +
+        "Preserves rich formatting, tables, selection marks, and visual layout that cannot be fully represented in markdown."),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Parse from URL": {
+        summary: "Parse from URL",
+        value: {
+            url: "https://example.com/bank-statement.pdf",
+        },
+    },
+    "Parse from base64": {
+        summary: "Parse from base64",
+        value: {
+            base64: "JVBERi0xLjAKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqIDIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iaiAzIDAgb2JqPDwvVHlwZS9QYWdlL01lZGlhQm94WzAgMCAzIDNdL1BhcmVudCAyIDAgUj4+ZW5kb2JqCnhyZWYKMCA0CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNC9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjE5MAolJUVPRg==",
+        },
+    },
+    "Parse from file upload": {
+        summary: "Parse from file upload",
+        value: {
+            file: "(binary)",
+        },
+    },
+};
+export const parse = oc
+    .route({
+    summary: "Parse a bank statement",
+    description: "Extract text and structured data from a bank statement. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Bank Statement"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(parseInputSchema)
+    .output(parseOutputSchema);

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

@@ -20,5 +20,6 @@ export declare const parse: import("@orpc/contract").ContractProcedureBuilderWit
         max: "max";
     }>;
     requestId: z.ZodNumber;
+    html: z.ZodOptional<z.ZodString>;
     documentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, Record<never, never>, Record<never, never>>;

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

@@ -47,6 +47,11 @@ const parseOutputSchema = z.object({
         .number()
         .int()
         .describe("Unique request identifier for this API call"),
+    html: z
+        .string()
+        .optional()
+        .describe("Full HTML representation of the document content. Only available when using the 'max' model. " +
+        "Preserves rich formatting, tables, selection marks, and visual layout that cannot be fully represented in markdown."),
     documentId: z
         .string()
         .optional()

package/.tsc/lib/router/identity/ask.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const ask: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    question: z.ZodString;
+    model: z.ZodDefault<z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    markdown: z.ZodString;
+    model: z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/identity/ask.js

@@ -0,0 +1,77 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedModelSchema = z
+    .enum(["auto", ...pdfvectorModelSchema.options])
+    .default("auto");
+const askInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the identity document file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Identity document file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded identity document file content"),
+    question: z
+        .string()
+        .min(4)
+        .describe("The question to answer about the identity document"),
+    model: specializedModelSchema.describe("Model tier for answering the question. " +
+        "'auto' (default): Automatically selects the best tier. " +
+        "'nano': Uses lightweight models. " +
+        "'mini': Uses mid-range models. " +
+        "'pro': Uses capable models. " +
+        "'max': Uses the most powerful models."),
+});
+const askOutputSchema = z.object({
+    markdown: z.string().describe("The answer to the question"),
+    model: pdfvectorModelSchema.describe("Model tier used to answer the question"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Ask from URL": {
+        summary: "Ask from URL",
+        value: {
+            url: "https://example.com/identity-document.pdf",
+            question: "What is the name on this identity document?",
+        },
+    },
+    "Ask from base64": {
+        summary: "Ask from base64",
+        value: {
+            base64: "JVBERi0xLjAKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqIDIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iaiAzIDAgb2JqPDwvVHlwZS9QYWdlL01lZGlhQm94WzAgMCAzIDNdL1BhcmVudCAyIDAgUj4+ZW5kb2JqCnhyZWYKMCA0CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNC9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjE5MAolJUVPRg==",
+            question: "What is the document number?",
+        },
+    },
+};
+export const ask = oc
+    .route({
+    summary: "Ask a question about an identity document",
+    description: "Parse an identity document and answer a question about its content using AI. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Identity"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(askInputSchema)
+    .output(askOutputSchema);

package/.tsc/lib/router/identity/extract.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const extract: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    schema: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodPipe<z.ZodString, z.ZodTransform<Record<string, unknown>, string>>]>;
+    model: z.ZodDefault<z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodUnknown;
+    model: z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/identity/extract.js

@@ -0,0 +1,107 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedModelSchema = z
+    .enum(["auto", ...pdfvectorModelSchema.options])
+    .default("auto");
+const extractInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the identity document file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Identity document file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded identity document file content"),
+    prompt: z
+        .string()
+        .min(4)
+        .describe("The prompt instructing the AI how to extract data from the identity document"),
+    schema: z
+        .union([
+        z.record(z.string(), z.unknown()),
+        z.string().transform((str, ctx) => {
+            try {
+                const trimmed = str.startsWith('"') && str.endsWith('"') ? str.slice(1, -1) : str;
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed !== "object" || parsed === null) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: "Schema must be a JSON object",
+                    });
+                    return z.NEVER;
+                }
+                return parsed;
+            }
+            catch {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "Invalid JSON string for schema",
+                });
+                return z.NEVER;
+            }
+        }),
+    ])
+        .describe("JSON Schema describing the structure of the data to extract from the identity document. Can be a JSON object or a JSON string."),
+    model: specializedModelSchema.describe("Model tier for extracting structured data. " +
+        "'auto' (default): Automatically selects the best tier. " +
+        "'nano': Uses lightweight models. " +
+        "'mini': Uses mid-range models. " +
+        "'pro': Uses capable models. " +
+        "'max': Uses the most powerful models."),
+});
+const extractOutputSchema = z.object({
+    data: z
+        .unknown()
+        .describe("Extracted structured data matching the provided JSON Schema"),
+    model: pdfvectorModelSchema.describe("Model tier used to extract the data"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Extract from URL": {
+        summary: "Extract from URL",
+        value: {
+            url: "https://example.com/identity-document.pdf",
+            prompt: "Extract the name, date of birth, and document number",
+            schema: JSON.stringify({
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    dateOfBirth: { type: "string" },
+                    documentNumber: { type: "string" },
+                },
+                required: ["name", "dateOfBirth", "documentNumber"],
+            }),
+        },
+    },
+};
+export const extract = oc
+    .route({
+    summary: "Extract structured data from an identity document",
+    description: "Parse an identity document and extract structured data matching a provided JSON Schema using AI. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Identity"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(extractInputSchema)
+    .output(extractOutputSchema);

package/.tsc/lib/router/identity/get-default-spec.d.ts

@@ -0,0 +1 @@
+export declare function getDefaultSpec(op: Record<string, unknown>, requestExamples: Record<string, unknown>): Record<string, unknown>;

package/.tsc/lib/router/identity/get-default-spec.js

@@ -0,0 +1,19 @@
+export function getDefaultSpec(op, requestExamples) {
+    op.security = [{ bearerAuth: [] }];
+    const params = (op.parameters ?? []);
+    params.push({
+        name: "x-pdfvector-document-id",
+        in: "header",
+        required: false,
+        schema: { type: "string", default: "my-doc-123" },
+        description: "Optional document ID to associate with this request. Returned in the response and saved for usage tracking.",
+    });
+    op.parameters = params;
+    const reqBody = op.requestBody;
+    if (reqBody?.content) {
+        for (const mediaType of Object.values(reqBody.content)) {
+            mediaType.examples = requestExamples;
+        }
+    }
+    return op;
+}

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

@@ -0,0 +1,3 @@
+export * from "./ask";
+export * from "./extract";
+export * from "./parse";

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

@@ -0,0 +1,3 @@
+export * from "./ask";
+export * from "./extract";
+export * from "./parse";

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

@@ -0,0 +1,22 @@
+import { z } from "zod";
+export declare const parse: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    model: z.ZodDefault<z.ZodEnum<{
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    markdown: z.ZodString;
+    pageCount: z.ZodNumber;
+    model: z.ZodEnum<{
+        pro: "pro";
+        max: "max";
+    }>;
+    documentType: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

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

@@ -0,0 +1,88 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedParseModelSchema = z
+    .enum(["pro", "max", "auto"])
+    .default("auto");
+const parseInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the identity document file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Identity document file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z
+        .string()
+        .optional()
+        .describe("Base64-encoded identity document file content"),
+    model: specializedParseModelSchema.describe("Model tier for parsing. " +
+        "'auto' (default): Automatically selects the best parsing strategy with intelligent fallback. " +
+        "'pro': Extracts structured identity document fields with standard accuracy. " +
+        "'max': Extracts structured identity document fields with highest accuracy."),
+});
+const parseOutputSchema = z.object({
+    markdown: z
+        .string()
+        .describe("Extracted text content from the identity document"),
+    pageCount: z.number().int().describe("Total number of pages in the document"),
+    model: z
+        .enum(["pro", "max"])
+        .describe("Model tier used to parse the identity document"),
+    documentType: z
+        .string()
+        .optional()
+        .describe("Detected identity document type (e.g., passport, driver's license)"),
+    html: z
+        .string()
+        .optional()
+        .describe("Full HTML representation of the document content. Only available when using the 'max' model. " +
+        "Preserves rich formatting, tables, selection marks, and visual layout that cannot be fully represented in markdown."),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Parse from URL": {
+        summary: "Parse from URL",
+        value: {
+            url: "https://example.com/identity-document.pdf",
+        },
+    },
+    "Parse from base64": {
+        summary: "Parse from base64",
+        value: {
+            base64: "JVBERi0xLjAKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqIDIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iaiAzIDAgb2JqPDwvVHlwZS9QYWdlL01lZGlhQm94WzAgMCAzIDNdL1BhcmVudCAyIDAgUj4+ZW5kb2JqCnhyZWYKMCA0CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNC9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjE5MAolJUVPRg==",
+        },
+    },
+    "Parse from file upload": {
+        summary: "Parse from file upload",
+        value: {
+            file: "(binary)",
+        },
+    },
+};
+export const parse = oc
+    .route({
+    summary: "Parse an identity document",
+    description: "Extract text and structured data from an identity document. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Identity"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(parseInputSchema)
+    .output(parseOutputSchema);

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

@@ -1,3 +1,6 @@
 export * as admin from "./admin";
 export * as authenticate from "./authenticate";
+export * as bankStatement from "./bankStatement";
 export * as document from "./document";
+export * as identity from "./identity";
+export * as invoice from "./invoice";

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

@@ -1,3 +1,6 @@
 export * as admin from "./admin";
 export * as authenticate from "./authenticate";
+export * as bankStatement from "./bankStatement";
 export * as document from "./document";
+export * as identity from "./identity";
+export * as invoice from "./invoice";

package/.tsc/lib/router/invoice/ask.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+export declare const ask: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    question: z.ZodString;
+    model: z.ZodDefault<z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    markdown: z.ZodString;
+    model: z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/invoice/ask.js

@@ -0,0 +1,67 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedModelSchema = z
+    .enum(["auto", ...pdfvectorModelSchema.options])
+    .default("auto");
+const askInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the invoice file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Invoice file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z.string().optional().describe("Base64-encoded invoice file content"),
+    question: z
+        .string()
+        .min(4)
+        .describe("The question to answer about the invoice"),
+    model: specializedModelSchema.describe("Model tier for answering the question. " +
+        "'auto' (default): Automatically selects the best tier. " +
+        "'nano': Uses lightweight models. " +
+        "'mini': Uses mid-range models. " +
+        "'pro': Uses capable models. " +
+        "'max': Uses the most powerful models."),
+});
+const askOutputSchema = z.object({
+    markdown: z.string().describe("The answer to the question"),
+    model: pdfvectorModelSchema.describe("Model tier used to answer the question"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Ask from URL": {
+        summary: "Ask from URL",
+        value: {
+            url: "https://example.com/invoice.pdf",
+            question: "What is the total amount on this invoice?",
+        },
+    },
+};
+export const ask = oc
+    .route({
+    summary: "Ask a question about an invoice",
+    description: "Parse an invoice and answer a question about its content using AI. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Invoice"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(askInputSchema)
+    .output(askOutputSchema);

package/.tsc/lib/router/invoice/extract.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+export declare const extract: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    schema: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodPipe<z.ZodString, z.ZodTransform<Record<string, unknown>, string>>]>;
+    model: z.ZodDefault<z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    data: z.ZodUnknown;
+    model: z.ZodEnum<{
+        nano: "nano";
+        mini: "mini";
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/.tsc/lib/router/invoice/extract.js

@@ -0,0 +1,113 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { pdfvectorModelSchema } from "../../pdfvector-model-schema";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedModelSchema = z
+    .enum(["auto", ...pdfvectorModelSchema.options])
+    .default("auto");
+const extractInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the invoice file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Invoice file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z.string().optional().describe("Base64-encoded invoice file content"),
+    prompt: z
+        .string()
+        .min(4)
+        .describe("The prompt instructing the AI how to extract data from the invoice"),
+    schema: z
+        .union([
+        z.record(z.string(), z.unknown()),
+        z.string().transform((str, ctx) => {
+            try {
+                const trimmed = str.startsWith('"') && str.endsWith('"') ? str.slice(1, -1) : str;
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed !== "object" || parsed === null) {
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        message: "Schema must be a JSON object",
+                    });
+                    return z.NEVER;
+                }
+                return parsed;
+            }
+            catch {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "Invalid JSON string for schema",
+                });
+                return z.NEVER;
+            }
+        }),
+    ])
+        .describe("JSON Schema describing the structure of the data to extract from the invoice. Can be a JSON object or a JSON string."),
+    model: specializedModelSchema.describe("Model tier for extracting structured data. " +
+        "'auto' (default): Automatically selects the best tier. " +
+        "'nano': Uses lightweight models. " +
+        "'mini': Uses mid-range models. " +
+        "'pro': Uses capable models. " +
+        "'max': Uses the most powerful models."),
+});
+const extractOutputSchema = z.object({
+    data: z
+        .unknown()
+        .describe("Extracted structured data matching the provided JSON Schema"),
+    model: pdfvectorModelSchema.describe("Model tier used to extract the data"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Extract from URL": {
+        summary: "Extract from URL",
+        value: {
+            url: "https://example.com/invoice.pdf",
+            prompt: "Extract the vendor name, total amount, and line items",
+            schema: JSON.stringify({
+                type: "object",
+                properties: {
+                    vendorName: { type: "string" },
+                    totalAmount: { type: "number" },
+                    lineItems: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: {
+                                description: { type: "string" },
+                                amount: { type: "number" },
+                            },
+                        },
+                    },
+                },
+                required: ["vendorName", "totalAmount"],
+            }),
+        },
+    },
+};
+export const extract = oc
+    .route({
+    summary: "Extract structured data from an invoice",
+    description: "Parse an invoice and extract structured data matching a provided JSON Schema using AI. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Invoice"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(extractInputSchema)
+    .output(extractOutputSchema);

package/.tsc/lib/router/invoice/get-default-spec.d.ts

@@ -0,0 +1 @@
+export declare function getDefaultSpec(op: Record<string, unknown>, requestExamples: Record<string, unknown>): Record<string, unknown>;

package/.tsc/lib/router/invoice/get-default-spec.js

@@ -0,0 +1,19 @@
+export function getDefaultSpec(op, requestExamples) {
+    op.security = [{ bearerAuth: [] }];
+    const params = (op.parameters ?? []);
+    params.push({
+        name: "x-pdfvector-document-id",
+        in: "header",
+        required: false,
+        schema: { type: "string", default: "my-doc-123" },
+        description: "Optional document ID to associate with this request. Returned in the response and saved for usage tracking.",
+    });
+    op.parameters = params;
+    const reqBody = op.requestBody;
+    if (reqBody?.content) {
+        for (const mediaType of Object.values(reqBody.content)) {
+            mediaType.examples = requestExamples;
+        }
+    }
+    return op;
+}

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

@@ -0,0 +1,3 @@
+export * from "./ask";
+export * from "./extract";
+export * from "./parse";

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

@@ -0,0 +1,3 @@
+export * from "./ask";
+export * from "./extract";
+export * from "./parse";

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

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const parse: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
+    url: z.ZodOptional<z.ZodURL>;
+    file: z.ZodOptional<z.ZodFile>;
+    base64: z.ZodOptional<z.ZodString>;
+    model: z.ZodDefault<z.ZodEnum<{
+        pro: "pro";
+        max: "max";
+        auto: "auto";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    markdown: z.ZodString;
+    pageCount: z.ZodNumber;
+    model: z.ZodEnum<{
+        pro: "pro";
+        max: "max";
+    }>;
+    requestId: z.ZodNumber;
+    html: z.ZodOptional<z.ZodString>;
+    documentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, Record<never, never>, Record<never, never>>;

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

@@ -0,0 +1,79 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import { getDefaultSpec } from "./get-default-spec";
+const specializedParseModelSchema = z
+    .enum(["pro", "max", "auto"])
+    .default("auto");
+const parseInputSchema = z.object({
+    url: z
+        .url()
+        .optional()
+        .describe("URL of the invoice file to fetch and parse"),
+    file: z
+        .file()
+        .mime([
+        "application/pdf",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        "text/csv",
+        "application/csv",
+        "image/png",
+        "image/jpeg",
+    ])
+        .optional()
+        .describe("Invoice file upload via multipart form-data (PDF, DOCX, XLSX, CSV, PNG, JPG)"),
+    base64: z.string().optional().describe("Base64-encoded invoice file content"),
+    model: specializedParseModelSchema.describe("Model tier for parsing. " +
+        "'auto' (default): Automatically selects the best parsing strategy with intelligent fallback. " +
+        "'pro': Extracts structured invoice fields with standard accuracy. " +
+        "'max': Extracts structured invoice fields with highest accuracy and fallback."),
+});
+const parseOutputSchema = z.object({
+    markdown: z.string().describe("Extracted text content from the invoice"),
+    pageCount: z.number().int().describe("Total number of pages in the document"),
+    model: z
+        .enum(["pro", "max"])
+        .describe("Model tier used to parse the invoice"),
+    requestId: z
+        .number()
+        .int()
+        .describe("Unique request identifier for this API call"),
+    html: z
+        .string()
+        .optional()
+        .describe("Full HTML representation of the document content. Only available when using the 'max' model. " +
+        "Preserves rich formatting, tables, selection marks, and visual layout that cannot be fully represented in markdown."),
+    documentId: z
+        .string()
+        .optional()
+        .describe("Document ID if provided via x-pdfvector-document-id header"),
+});
+const requestExamples = {
+    "Parse from URL": {
+        summary: "Parse from URL",
+        value: {
+            url: "https://example.com/invoice.pdf",
+        },
+    },
+    "Parse from base64": {
+        summary: "Parse from base64",
+        value: {
+            base64: "JVBERi0xLjAKMSAwIG9iajw8L1R5cGUvQ2F0YWxvZy9QYWdlcyAyIDAgUj4+ZW5kb2JqIDIgMCBvYmo8PC9UeXBlL1BhZ2VzL0tpZHNbMyAwIFJdL0NvdW50IDE+PmVuZG9iaiAzIDAgb2JqPDwvVHlwZS9QYWdlL01lZGlhQm94WzAgMCAzIDNdL1BhcmVudCAyIDAgUj4+ZW5kb2JqCnhyZWYKMCA0CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAwOSAwMDAwMCBuIAowMDAwMDAwMDU4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKdHJhaWxlcjw8L1NpemUgNC9Sb290IDEgMCBSPj4Kc3RhcnR4cmVmCjE5MAolJUVPRg==",
+        },
+    },
+    "Parse from file upload": {
+        summary: "Parse from file upload",
+        value: {
+            file: "(binary)",
+        },
+    },
+};
+export const parse = oc
+    .route({
+    summary: "Parse an invoice",
+    description: "Extract text and structured data from an invoice. Supports PDF, Word (.docx), Excel (.xlsx), CSV, and Image (.png, .jpg) files. Provide the document via file upload, a public URL, or a base64-encoded string.",
+    tags: ["Invoice"],
+    spec: (op) => getDefaultSpec(op, requestExamples),
+})
+    .input(parseInputSchema)
+    .output(parseOutputSchema);

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @pdfvector/instance-contract
 
+## 0.0.19
+### Patch Changes
+
+
+
+- [#116](https://github.com/phuctm97/pdfvector/pull/116) [`c9bf7f0`](https://github.com/phuctm97/pdfvector/commit/c9bf7f05be2be778818306010cf1b484e4233702) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Add HTML field to parse response and rename Identity Document tag to Identity
+
+## 0.0.18
+### Patch Changes
+
+
+
+- [#115](https://github.com/phuctm97/pdfvector/pull/115) [`f726901`](https://github.com/phuctm97/pdfvector/commit/f7269017780da691cf7fc3c9463a28050ad8453f) Thanks [@khanhduyvt0101](https://github.com/khanhduyvt0101)! - Add identity, invoice, and bank statement parse/ask/extract APIs
+
 ## 0.0.17
 ### Patch Changes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pdfvector/instance-contract",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "main": ".tsc/lib/index.js",
   "dependencies": {