yoastseo package: define serializable PaperDTO schema and conversion function

apps/content-analysis-api/helpers/paper-from-request.js

@@ -0,0 +1,22 @@
+const { toPaper } = require( "yoastseo/contract" );
+
+/**
+ * Builds a Paper from the request body via the PaperDTO contract (`yoastseo/contract`).
+ *
+ * On a structurally invalid body (wrong types, unknown keys, missing `text`) it responds with a 400 and
+ * returns null, so callers should bail when the result is falsy.
+ *
+ * @param {Object} request  The Express request.
+ * @param {Object} response The Express response.
+ * @returns {Object|null} The constructed Paper, or null when the body was rejected.
+ */
+const paperFromRequest = ( request, response ) => {
+	try {
+		return toPaper( request.body || {} );
+	} catch ( error ) {
+		response.status( 400 ).json( { error: "Invalid request body", details: error.issues || String( error ) } );
+		return null;
+	}
+};
+
+module.exports = { paperFromRequest };

apps/content-analysis-api/routes/analyze.js

@@ -1,5 +1,6 @@
-const { Paper, assessments, assessors, interpreters } = require( "yoastseo" );
+const { assessments, assessors, interpreters } = require( "yoastseo" );
 const { getResearcher } = require( "../helpers/get-researcher" );
+const { paperFromRequest } = require( "../helpers/paper-from-request" );
 
 const express = require( "express" ), app = express();
 
@@ -32,9 +33,13 @@ const resultToVM = ( result ) => {
 
 module.exports = function( app ) {
 	app.get( "/analyze", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
+
 		// Fetch the Researcher and set the morphology data for the given language (yes, this is a bit hacky)
 		const language = request.body.locale || "en";
-
 		const researcher = getResearcher( language );
 
 		const seoAssessor = new SEOAssessor( researcher );
@@ -46,11 +51,6 @@ module.exports = function( app ) {
 		const relatedKeywordAssessor = new RelatedKeywordAssessor( researcher );
 		const inclusiveLanguageAssessor = new InclusiveLanguageAssessor( researcher );
 
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
-
 		seoAssessor.assess( paper );
 		contentAssessor.assess( paper );
 		relatedKeywordAssessor.assess( paper );
@@ -65,116 +65,121 @@ module.exports = function( app ) {
 	} );
 
 	app.get( "/analyze/seo", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new SEOAssessor( researcher );
 		assessor.addAssessment( "keyphraseDistribution", new KeyphraseDistributionAssessment() );
 		assessor.addAssessment( "TextTitleAssessment", new TextTitleAssessment() );
 
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/readability", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new ContentAssessor( researcher );
 		assessor.addAssessment( "wordComplexity", new WordComplexityAssessment() );
 		assessor.addAssessment( "textAlignment", new TextAlignmentAssessment() );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
+
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/related-keyphrase", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new RelatedKeywordAssessor( researcher );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
+
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/inclusive-language", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new InclusiveLanguageAssessor( researcher );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
+
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/meta-description", ( request, response ) => {
-		if (! request.body.description) {
+		if ( ! request.body.description ) {
 			return response.status( 400 ).json( { error: "Description is required" } );
 		}
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new MetaDescriptionAssessor( researcher );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/seo-title", ( request, response ) => {
-		if (! request.body.title) {
+		if ( ! request.body.title ) {
 			return response.status( 400 ).json( { error: "Title is required" } );
 		}
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new SeoTitleAssessor( researcher );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/keyphrase", ( request, response ) => {
-		if (! request.body.keyword) {
-			return response.status( 400 ).json( { error: "Keyword is required" } );
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
+		// This endpoint is keyphrase analysis, so a keyphrase is required (the contract leaves it optional).
+		if ( ! paper.hasKeyword() ) {
+			return response.status( 400 ).json( { error: "A keyphrase is required" } );
 		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new KeyphraseAssessor( researcher );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );
 
 	app.get( "/analyze/keyphrase-use", ( request, response ) => {
-		if (! request.body.keyword) {
-			return response.status( 400 ).json( { error: "Keyword is required" } );
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
+		// This endpoint is keyphrase analysis, so a keyphrase is required (the contract leaves it optional).
+		if ( ! paper.hasKeyword() ) {
+			return response.status( 400 ).json( { error: "A keyphrase is required" } );
 		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
 		const assessor = new KeyphraseUseAssessor( researcher );
 		assessor.addAssessment( "keyphraseDistribution", new KeyphraseDistributionAssessment() );
 
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		assessor.assess( paper );
 		response.json( assessor.getValidResults().map( resultToVM ) );
 	} );

apps/content-analysis-api/routes/research.js

@@ -1,52 +1,52 @@
-const { Paper } = require( "yoastseo" );
 const { build } = require( "yoastseo/build/parse/build" );
 const { LanguageProcessor } = require( "yoastseo/build/parse/language" );
 const { getResearcher } = require( "../helpers/get-researcher" );
+const { paperFromRequest } = require( "../helpers/paper-from-request" );
 
 module.exports = function( app ) {
 	app.get( "/research/estimated-reading-time", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		researcher.setPaper( paper );
 		const estimatedReadingTime = researcher.getResearch( "readingTime" );
 		response.json( { time: estimatedReadingTime } );
 	} );
 
 	app.get( "/research/flesch-reading-ease", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		researcher.setPaper( paper );
 		const fleschReadingEaseScore = researcher.getResearch( "getFleschReadingScore" );
 		response.json( { score: fleschReadingEaseScore.score, difficulty: fleschReadingEaseScore.difficulty } );
 	} );
 
 	app.get( "/research/word-count", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		researcher.setPaper( paper );
 		const wordCount = researcher.getResearch( "wordCountInText" );
 		response.json( { count: wordCount.count, unit: wordCount.unit } );
 	} );
 
 	app.get( "/research/sentence-count", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		paper.setTree( build( paper, new LanguageProcessor( researcher ), paper._attributes && paper._attributes.shortcodes ) );
 		researcher.setPaper( paper );
 		const sentenceLengths = researcher.getResearch( "countSentencesFromText" );
@@ -56,12 +56,12 @@ module.exports = function( app ) {
 	} );
 
 	app.get( "/research/paragraph-count", ( request, response ) => {
+		const paper = paperFromRequest( request, response );
+		if ( ! paper ) {
+			return;
+		}
 		const language = request.body.locale || "en";
 		const researcher = getResearcher( language );
-		const paper = new Paper(
-			request.body.text || "",
-			request.body || {}
-		);
 		paper.setTree( build( paper, new LanguageProcessor( researcher ), paper._attributes && paper._attributes.shortcodes ) );
 		researcher.setPaper( paper );
 		const paragraphLengths = researcher.getResearch( "getParagraphLength" );

apps/content-analysis-webworker/src/index.js

@@ -1,4 +1,5 @@
-import { AnalysisWorkerWrapper, Paper, interpreters } from "yoastseo";
+import { AnalysisWorkerWrapper, interpreters } from "yoastseo";
+import { toPaper } from "yoastseo/contract";
 
 const loadWebWorker = ( language ) => {
 	const workerUnwrapped = new Worker( new URL("./worker.js", import.meta.url) );
@@ -40,9 +41,8 @@ document.addEventListener("DOMContentLoaded", function(event) {
 			logLevel: "TRACE", // Optional, see https://github.com/pimterry/loglevel#documentation
 		} ).then( () => {
 			// The worker has been configured, we can now analyze a Paper.
-			const paper = new Paper( paperText, {
-				keyword: keyphrase,
-			} );
+			// Build the Paper through the serializable input contract (`yoastseo/contract`).
+			const paper = toPaper( { text: paperText, keyphrase } );
 
 			return worker.analyze( paper );
 		} ).then( ( results ) => {

packages/yoastseo/GLOSSARY.md

@@ -27,6 +27,28 @@ const paper = new Paper("<p>This is the <strong>main</strong> content<p>", {
 });
 ```
 
+### <a name="paperdto"></a>PaperDTO
+A documented, serializable **input contract** for the engine (neutral core + a few optional, deprecated WordPress-transitional fields), exposed via the opt-in `yoastseo/contract` entry. A non-WordPress consumer sends a `PaperDTO` (plain JSON) and the `toPaper` boundary validates it and constructs an internal [Paper](#paper). It is the *external* counterpart of `Paper`: where `Paper` is the engine's internal value object, `PaperDTO` is the stable shape consumers send.
+
+Key differences from `Paper`:
+- Uses the canonical name **`keyphrase`** (mapped to the engine's `keyword`); `keyword` is accepted as a deprecated alias.
+- Carries the WordPress-transitional fields (`wpBlocks`, `shortcodes`, `isFrontPage`) as **optional, deprecated** — they are real analysis inputs that change WordPress scores, so a remote/API analysis needs them for result parity.
+- Authored in [zod](https://zod.dev); validates structure (wrong types / unknown keys throw) while leaving per-assessment fields optional (omitting one just skips that assessment).
+- Consumers that register their own analysis (e.g., assessments) pass those inputs through the opaque `customData` object, whose contents are not validated.
+
+**Example:**
+```javascript
+import { toPaper } from "yoastseo/contract";
+
+const paper = toPaper({
+    text: "<p>This is the <strong>main</strong> content</p>",
+    keyphrase: "example",
+    description: "This is a meta description",
+    slug: "example-page",
+    locale: "en_US"
+});
+```
+
 ### <a name="assessment"></a>Assessment
 A single analysis unit that evaluates one specific aspect of content. Each assessment:
 - Has a specific purpose (e.g., the _keyword density_ assessment evaluates the number of keywords used in the content)
@@ -59,7 +81,7 @@ Types of assessors include:
 - ReadabilityAssessor: Analyzes text readability
 - CornerStoneAssessor: Applies stricter rules for important content
 
-The diagram below shows an example hierarchy of assessors and assessments. 
+The diagram below shows an example hierarchy of assessors and assessments.
 
 ```mermaid
 graph TD
@@ -179,4 +201,4 @@ Alternative words or phrases with similar meaning to the keyphrase. Used to:
 ```
 Keyphrase: "car"
 Synonyms: "automobile", "vehicle", "motor vehicle"
-``` 
+```