OpenResume Parser

OpenResume Parser converts text-based resume PDFs into structured ATS-friendly JSON. It runs locally and does not upload resume data.

Usage

import { parseResumeFromPdf } from "open-resume";

const result = await parseResumeFromPdf("resume.pdf");

if (result.ok) {
  console.log(JSON.stringify(result.resume, null, 2));
} else {
  console.error(result.error.code, result.error.message);
}

React Native usage

React Native applications should import the platform-neutral entry:

import { parseResumeFromTextItems } from "open-resume/native";

const result = parseResumeFromTextItems(nativeTextItems);

The native entry does not import PDF.js or Node-specific APIs. Your Android or iOS PDF text extraction library must map each extracted text fragment to the TextItem contract:

interface TextItem {
  text: string;
  x: number;
  y: number;
  width: number;
  height: number;
  fontName: string;
  hasEOL: boolean;
  pageNumber: number;
  sourceIndex: number;
}

sourceIndex must be a stable, zero-based index across the document and pageNumber must start at 1. Coordinates should use a consistent PDF-style coordinate system. The parser validates these values and returns INVALID_TEXT_ITEMS instead of silently parsing malformed native data.

The platform-specific PDF extraction layer remains outside this package. This keeps PDF.js out of the React Native bundle and allows Android and iOS to use their preferred native PDF text extraction implementation.

Build the package with npm run build, validate it with npm test, then publish it with npm publish.

The parser returns:

{
  "contact": {
    "name": "",
    "email": "",
    "phone": "",
    "location": "",
    "url": ""
  },
  "summary": "",
  "experience": [],
  "education": [],
  "projects": [],
  "skills": [],
  "certifications": [],
  "languages": []
}

Scanned/image-only PDFs can use the optional OCR.Space fallback. The API key must be supplied by the application and is never stored or embedded by this package:

const result = await parseResumeFromPdf("resume.pdf", {
  ocr: { apiKey: process.env.OCR_SPACE_API_KEY! },
});

The fallback uploads the PDF to OCR.Space, so do not enable it for documents that must remain local. Configure endpoint, language, or timeoutMs in the same ocr object when needed. Without ocr.apiKey, image-only PDFs still return PDF_HAS_NO_TEXT.

Current parsing contract

The parser expects a text-based PDF and is optimized for English resumes with conventional section headings. It reconstructs coordinate-based lines and conservatively detects clear two-column layouts, but it does not guarantee correct reading order for table-heavy, highly decorated, or ambiguous layouts.

On success, every field in ParsedResume is present. Fields that are not found are returned as empty strings or arrays. The parser does not infer values that are not present in the source document.

The current fatal error codes are:

• PDF_HAS_NO_TEXT: the PDF has no extractable text and may require OCR.
• PDF_PARSE_FAILED: the PDF could not be read or processed.
• OCR_FAILED: the configured OCR.Space fallback could not process the PDF.

The parser preserves the public result shape while layout reconstruction and field extraction are improved. New diagnostics should be added as optional metadata so existing consumers can continue to use result.ok and result.resume without migration.

Successful results now also include optional diagnostics metadata with detected sections, page and column estimates, domain confidence values, and recoverable warnings. Fatal PDF errors remain represented by ok: false.

The package exports ParsedResume, ParseResumeResult, ParseDiagnostics, ParseWarning, ParseWarningCode, and ParseErrorCode for typed consumers.

Release checklist

Before publishing:

1. Run npm test.
2. Confirm generated ESM, CommonJS, and declaration outputs are created in dist/.
3. Confirm only the intended package files are included by the files list in package.json.
4. Review parser warnings and regression output for representative resumes.
5. Confirm no temporary files, local fixtures, credentials, or generated archives are added to the package.

OCR.Space is an optional remote fallback; text extraction remains local by default.

Validation

Run the build and dependency-free Node regression suite with:

npm test

The regression suite validates the sample PDF output shape, diagnostics, deterministic repeated parsing, and explicit handling of an unreadable PDF.