@financial-times/cp-content-pipeline-schema 2.15.0 → 3.0.0

package/src/model/CapiResponse.ts

@@ -3,7 +3,7 @@ import type {
   ContentTypeSchemas,
   MainImage,
   ClipSet,
-} from '../types/internal-content'
+} from './schemas/capi/internal-content'
 import conceptIds from '@financial-times/n-concept-ids'
 import metadata from '@financial-times/n-display-metadata'
 import cloneDeep from 'clone-deep'
@@ -13,7 +13,7 @@ import type { QueryContext } from '..'
 import sortBy from 'lodash.sortby'
 
 import { CAPIImage } from './Image'
-import { Concept } from './Concept'
+import { Concept, predicates } from './Concept'
 import { Person } from './Person'
 import isError from '../helpers/isError'
 import { uuidFromUrl } from '../helpers/metadata'
@@ -30,6 +30,7 @@ import {
 } from '../resolvers/literal-union'
 
 import {
+  ContentAnnotationsArgs,
   ContentPackageContainsArgs,
   ContentUrlArgs,
   Media,
@@ -161,18 +162,21 @@ export class CapiResponse {
       packageContainer
     )
   }
+
   body() {
     if (this.type() === 'Video' && 'transcript' in this.capiData) {
       return new RichText('transcript', this.capiData.transcript ?? null, this)
     }
     return new RichText('bodyXML', this.bodyXML(), this)
   }
+
   bodyXML(): string | null {
     if ('bodyXML' in this.capiData) {
       return this.capiData.bodyXML
     }
     return null
   }
+
   embeds(): (ImageSet | ClipSet)[] {
     if ('embeds' in this.capiData && this.capiData.embeds)
       return this.capiData.embeds
@@ -184,41 +188,43 @@ export class CapiResponse {
     return null
   }
 
-  byline({ vanity }: Partial<ContentUrlArgs>) {
-    const bylineText = this.rawByline()
-
-    if (!bylineText) return null
-    const authorUrlMapping = this.getAuthorUrlMapping()
+  async byline({ vanity }: Partial<ContentUrlArgs>) {
+    if (!this.capiData.byline) return null
 
-    return new Byline(
-      bylineText,
+    const byline = new Byline(
+      this.capiData.byline,
       Boolean(vanity),
-      authorUrlMapping,
-      this.context
-    ).buildBylineTree()
-  }
-  rawByline(): string | null {
-    if ('byline' in this.capiData && this.capiData.byline) {
-      return this.capiData.byline
-    }
+      this.annotations({ byPredicate: predicates.hasAuthor }),
+      this
+    )
 
-    return null
+    return byline.buildBylineTree()
   }
+
   #rawAnnotations() {
     return this.capiData.annotations
   }
 
-  annotations(): Concept[] {
-    return sortBy(this.#rawAnnotations(), ['predicate', 'id']).map(
+  annotations({ byPredicate }: ContentAnnotationsArgs = {}): Concept[] {
+    const concepts = sortBy(this.#rawAnnotations(), ['predicate', 'id']).map(
       (concept) => new Concept(concept, this.context)
     )
+
+    if (byPredicate) {
+      return concepts.filter((concept) => concept.predicate() === byPredicate)
+    }
+
+    return concepts
   }
+
   types() {
     return this.capiData.types
   }
+
   url({ relative, vanity }: Partial<ContentUrlArgs>) {
     return relative ? this.relativeUrl(vanity) : this.absoluteUrl(vanity)
   }
+
   async absoluteUrl(vanity?: boolean | null) {
     const url =
       this.capiData.webUrl ??
@@ -243,43 +249,65 @@ export class CapiResponse {
     }
     return url
   }
+
   leadImages() {
     if ('leadImages' in this.capiData) return this.capiData.leadImages
     return []
   }
+
   topper() {
     if ('topper' in this.capiData) return this.capiData.topper
     return null
   }
-  authors(): Person[] | null {
-    const authors = this.getAuthors()
-    return authors.length === 0
-      ? null
-      : authors.map((author: Concept) => new Person(author, this, this.context))
+
+  async authors(): Promise<Person[]> {
+    const authors = this.annotations({ byPredicate: predicates.hasAuthor })
+
+    return Promise.all(
+      authors.map((author) =>
+        this.context.dataSources.capi.getPerson(author.uuid())
+      )
+    )
+  }
+
+  async primaryAuthor(): Promise<Person | null> {
+    const primaryAuthor = this.annotations({
+      byPredicate: predicates.hasAuthor,
+    })[0]
+
+    if (primaryAuthor) {
+      return this.context.dataSources.capi.getPerson(primaryAuthor.uuid())
+    }
+
+    return null
   }
+
   accessLevel(): LiteralUnionScalarValues<typeof AccessLevel> {
     return this.capiData.accessLevel ?? 'subscribed'
   }
+
   editorialDesk() {
     return this.capiData.editorialDesk ?? null
   }
+
   canBeSyndicated(): LiteralUnionScalarValues<typeof CanBeSyndicated> {
     return this.capiData.canBeSyndicated
   }
+
   instantAlertConcept() {
-    const authors = this.getAuthors()
-    const authorConcept = authors.length === 1 ? authors[0] : null
+    const authors = this.annotations({ byPredicate: predicates.hasAuthor })
     const displayConcept = this.getDisplayConcept()
 
-    if ((this.isOpinion() || this.isAlphaville()) && authorConcept) {
-      return authorConcept
+    if ((this.isColumn() || this.isAlphaville()) && authors[0]) {
+      return authors[0]
     } else if (displayConcept?.isOrganisation()) {
       return displayConcept
     }
 
     return null
   }
-  originatingParty(): string | null {
+
+  originatingParty() {
     return this.capiData.canBeDistributed === 'no' &&
       this.annotations().some((annotation) => {
         annotation.id() ===
@@ -288,10 +316,12 @@ export class CapiResponse {
       ? 'Reuters'
       : 'FT'
   }
+
   summary() {
     if ('summary' in this.capiData) return this.capiData.summary
     return null
   }
+
   title() {
     // CI-2038 HACK to remove "Comment:" prefix from live blog post titles
     // as this is as the sole indicator that this is an opinion post
@@ -303,9 +333,11 @@ export class CapiResponse {
     }
     return this.capiData.title
   }
+
   id() {
     return uuidFromUrl(this.capiData.id)
   }
+
   standfirst(): string | null {
     if ('standfirst' in this.capiData && this.capiData.standfirst) {
       return this.capiData.standfirst
@@ -313,18 +345,33 @@ export class CapiResponse {
 
     return null
   }
+
   publishedDate() {
+    // WARNING:20240815:RB: "publishedDate" is only updated for editorial
+    // publishes where they explictly check a box to update it. If you need
+    // all editorial changes you may be after "lastModified" instead.
     return this.capiData.publishedDate
   }
+
   publishedTimestamp() {
+    // WARNING:20240815:RB: "publishedTimestamp" is only updated for editorial
+    // publishes where they explictly check a box to update it. If you need
+    // all editorial changes you may be after "modifiedTimestamp" instead.
     return new Date(this.capiData.publishedDate).getTime()
   }
+
   firstPublishedDate() {
     return this.capiData.firstPublishedDate || this.capiData.publishedDate
   }
+
+  modifiedTimestamp() {
+    return new Date(this.capiData.lastModified).getTime()
+  }
+
   publishReference() {
-    return this.capiData.publishReference
+    return this.capiData.publishReference ?? null
   }
+
   alternativeTitle() {
     return this.capiData.alternativeTitles ?? null
   }
@@ -417,7 +464,7 @@ export class CapiResponse {
 
   async metaPrefixText() {
     const meta = await this.#teaserMetadata()
-    return meta.prefixText
+    return meta.prefixText ?? null
   }
 
   teaser() {
@@ -493,23 +540,6 @@ export class CapiResponse {
     return cloneDeep(this.capiData)
   }
 
-  #createStreamLink(streamUuid: string) {
-    return `https://www.ft.com/stream/${streamUuid}`
-  }
-  getAuthorUrlMapping() {
-    const authorAnnotations = this.getAuthors()
-    return authorAnnotations.reduce((mapping, author: Concept) => {
-      if (author.prefLabel()) {
-        const nameWithCurlyApostrophes = author.prefLabel().replace("'", '’')
-        mapping.set(
-          nameWithCurlyApostrophes,
-          this.#createStreamLink(author.uuid())
-        )
-      }
-      return mapping
-    }, new Map<string, string>())
-  }
-
   getBrandConcept() {
     return this.annotations().find((annotation: Concept) =>
       annotation.isBrand()
@@ -546,14 +576,11 @@ export class CapiResponse {
     )
   }
 
-  getAuthors() {
-    return this.annotations().filter((annotation: Concept) =>
-      annotation.isAuthor()
-    )
-  }
-
   isColumn() {
-    return this.isOpinion() && this.getAuthors().length === 1
+    return (
+      this.isOpinion() &&
+      this.annotations({ byPredicate: predicates.hasAuthor }).length === 1
+    )
   }
 
   isOpinion() {

package/src/model/Clip.ts

@@ -1,5 +1,5 @@
 import { uuidFromUrl } from '../helpers/metadata'
-import { Clip as ClipMetadata } from '../types/internal-content'
+import { Clip as ClipMetadata } from './schemas/capi/internal-content'
 import {
   LiteralUnionScalarValues,
   validLiteralUnionValue,

package/src/model/Concept.ts

@@ -1,4 +1,4 @@
-import type { Annotation } from '../types/internal-content'
+import type { Annotation } from './schemas/capi/internal-content'
 import type { QueryContext } from '..'
 import { uuidFromUrl } from '../helpers/metadata'
 import isError from '../helpers/isError'
@@ -6,7 +6,6 @@ import conceptIds from '@financial-times/n-concept-ids'
 
 const CAPI_ID_PREFIX = /^https?:\/\/(?:www|api)\.ft\.com\/things?\//
 const BASE_URL = 'https://www.ft.com/stream/'
-const FT_URL = 'https://www.ft.com'
 
 type URLArguments = {
   vanity?: boolean | null
@@ -163,8 +162,9 @@ export class Concept {
     }
 
     if (args?.relative) {
-      url = url.replace(FT_URL, '')
+      return new URL(url).pathname
     }
+
     return url
   }
 }

package/src/model/FlourishSource.ts

@@ -37,7 +37,7 @@ export class FlourishSource {
   }
 
   format() {
-    return 'standard'
+    return 'standard' as const
   }
 
   flourishUrl() {

package/src/model/Image.test.ts

@@ -1,7 +1,7 @@
 import { CAPIImage } from './Image'
 import { jest } from '@jest/globals'
 import type { QueryContext } from '..'
-import { Image } from '../types/internal-content'
+import { Image } from './schemas/capi/internal-content'
 import { OrigamiImageDataSource } from '../datasources/origami-image'
 import { MAX_IMAGE_WIDTH } from '../helpers/imageService'
 import type { ImageSource } from '../generated'

package/src/model/Image.ts

@@ -4,7 +4,7 @@ import type { DataSources } from '../datasources'
 import type {
   Image as InternalContentImage,
   LeadImage,
-} from '../types/internal-content'
+} from './schemas/capi/internal-content'
 import type { QueryContext } from '..'
 import {
   LiteralUnionScalarValues,

package/src/model/LeadFlourish.test.ts

@@ -28,6 +28,7 @@ describe('LeadFlourish', () => {
     clonedBase.topper = {
       layout: 'flourish',
       layoutWidth: 'full-width',
+      backgroundColour: 'paper',
     }
     const capiResponse = new CapiResponse(clonedBase, context)
     leadFlourish = new LeadFlourish(capiResponse, context)

package/src/model/Person.test.ts

@@ -1,14 +1,11 @@
 import { Person } from './Person'
 import { jest } from '@jest/globals'
 import type { QueryContext } from '..'
-import { Concept } from './Concept'
-import { CapiResponse } from './CapiResponse'
-import { baseCapiObject } from '../fixtures/capiObject'
 import { capiPerson } from '../fixtures/capiPerson'
-import cloneDeep from 'clone-deep'
 import { URLManagementDataSource } from '../datasources/url-management'
 import { CapiDataSource } from '../datasources/capi'
 import { Logger } from '@dotcom-reliability-kit/logger'
+import { CapiPerson } from './schemas/capi/internal-content'
 
 const vanityMock = jest.fn<URLManagementDataSource['get']>()
 const getPersonMock = jest.fn<CapiDataSource['getPerson']>()
@@ -22,86 +19,38 @@ const context = {
   logger: new Logger(),
 } as unknown as QueryContext
 
-const topic = {
-  apiUrl: 'http://api.ft.com/things/6b32f2c1-da43-4e19-80b9-8aef4ab640d7',
-  directType: 'http://www.ft.com/ontology/Topic',
-  id: 'http://api.ft.com/things/6b32f2c1-da43-4e19-80b9-8aef4ab640d7',
-  predicate: 'http://www.ft.com/ontology/annotation/about',
-  prefLabel: 'Technology sector',
-  type: 'TOPIC',
-  types: [
-    'http://www.ft.com/ontology/core/Thing',
-    'http://www.ft.com/ontology/concept/Concept',
-    'http://www.ft.com/ontology/Topic',
-  ],
-}
-
-const author = {
-  apiUrl: 'http://api.ft.com/people/4076f4fd-723b-4ce5-9934-fb29416554fa',
-  directType: 'http://www.ft.com/ontology/person/Person',
-  id: 'http://api.ft.com/things/4076f4fd-723b-4ce5-9934-fb29416554fa',
-  predicate: 'http://www.ft.com/ontology/annotation/hasAuthor',
-  prefLabel: 'Robert Shrimsley',
-  type: 'PERSON',
-  types: [
-    'http://www.ft.com/ontology/core/Thing',
-    'http://www.ft.com/ontology/concept/Concept',
-    'http://www.ft.com/ontology/person/Person',
-  ],
-}
 describe('Person model', () => {
-  let clonedBase: typeof baseCapiObject
-  let capiResponse: CapiResponse
-  let topicConcept: Concept
-  let authorConcept: Concept
-
   beforeEach(() => {
     jest.resetAllMocks()
-
-    clonedBase = cloneDeep(baseCapiObject)
-    capiResponse = new CapiResponse(clonedBase, context)
-    topicConcept = new Concept(topic, context)
-    authorConcept = new Concept(author, context)
   })
 
-  describe('headshot()', () => {
-    it('returns null if the concept is not for an author', async () => {
-      const model = new Person(topicConcept, capiResponse, context)
-      expect(await model.headshot()).toEqual(null)
-    })
-
+  describe('headshot', () => {
     it('returns the headshot for an author', async () => {
-      getPersonMock.mockResolvedValue(capiPerson)
-      const model = new Person(authorConcept, capiResponse, context)
-      expect(await model.headshot()).toEqual(
+      const model = new Person(capiPerson as CapiPerson, context)
+      expect(await model.headshot({})).toEqual(
         'https://www.ft.com/__origami/service/image/v2/images/raw/https%3A%2F%2Fd1e00ek4ebabms.cloudfront.net%2Fproduction%2Fuploaded-files%2Ffthead-v1_robert-shrimsley-cc467908-15d6-474d-94d8-171594ceabb9.png?source=image-test&fit=scale-down&quality=highest&width=150&dpr=1'
       )
     })
 
     it('can resize headshot and provide high resolution version', async () => {
-      getPersonMock.mockResolvedValue(capiPerson)
-      const model = new Person(authorConcept, capiResponse, context)
+      const model = new Person(capiPerson as CapiPerson, context)
       expect(await model.headshot({ width: 300, dpr: 2 })).toEqual(
         'https://www.ft.com/__origami/service/image/v2/images/raw/https%3A%2F%2Fd1e00ek4ebabms.cloudfront.net%2Fproduction%2Fuploaded-files%2Ffthead-v1_robert-shrimsley-cc467908-15d6-474d-94d8-171594ceabb9.png?source=image-test&fit=scale-down&quality=highest&width=300&dpr=2'
       )
     })
 
-    it('returns null if there is an error getting the person data', async () => {
-      getPersonMock.mockRejectedValue(new Error('error getting person'))
-      const model = new Person(authorConcept, capiResponse, context)
-      expect(await model.headshot({ width: 300, dpr: 2 })).toEqual(null)
-    })
-
     it("returns null if the author doesn't have a headshot", async () => {
-      getPersonMock.mockResolvedValue({ ...capiPerson, _imageUrl: undefined })
-      const model = new Person(authorConcept, capiResponse, context)
-      expect(await model.headshot()).toEqual(null)
+      const model = new Person(
+        { ...capiPerson, _imageUrl: undefined } as CapiPerson,
+        context
+      )
+      expect(await model.headshot({})).toEqual(null)
     })
   })
 
   describe('streamPage()', () => {
     it('returns the stream URL', () => {
-      const model = new Person(authorConcept, capiResponse, context)
+      const model = new Person(capiPerson as CapiPerson, context)
       expect(model.streamPage()).toEqual(
         'https://www.ft.com/stream/4076f4fd-723b-4ce5-9934-fb29416554fa'
       )

package/src/model/Person.ts

@@ -1,37 +1,54 @@
 import type { QueryContext } from '..'
-import { Concept } from './Concept'
-import { CapiResponse } from './CapiResponse'
 import imageServiceUrl from '../helpers/imageService'
-import isError from '../helpers/isError'
-import decorateHeadshotUrl, { UUID_REGEX } from '../helpers/decorateHeadshotUrl'
+import decorateHeadshotUrl from '../helpers/decorateHeadshotUrl'
 import { OperationalError } from '@dotcom-reliability-kit/errors'
-
-type HeadshotArguments = {
-  width?: number | null
-  dpr?: number | null
-}
-
-const predicates = {
-  hasAuthor: 'http://www.ft.com/ontology/annotation/hasAuthor',
-} as const
+import { CapiPerson as CapiPersonSchema } from './schemas/capi/base-schema'
+import { CapiPerson } from './schemas/capi/internal-content'
+import flattenFormattedZodIssues from '../helpers/flatten-formatted-zod-errors'
+import { PersonHeadshotArgs } from '../generated'
+import { uuidFromUrl } from '../helpers/metadata'
 
 export class Person {
   #systemCode: string
 
-  constructor(
-    private concept: Concept,
-    private capiResponse: CapiResponse,
-    private context: QueryContext
-  ) {
+  static fromJson(data: unknown, context: QueryContext): Person {
+    const result = CapiPersonSchema.safeParse(data)
+    if (!result.success) {
+      context.logger.warn({
+        event: 'RECOVERABLE_ERROR',
+        error: new OperationalError({
+          message:
+            'The data received from the CAPI data source does not match our data source schema. It is likely that our schema will require updating to handle all possible responses from CAPI.',
+          code: 'CAPI_SCHEMA_VALIDATION_FAILURE',
+          schemaError: flattenFormattedZodIssues(result.error.format(), data),
+          contentId: (data as { id?: string }).id,
+          contentType: 'Person',
+        }),
+      })
+      context.metrics?.count(
+        `graphql.datasource.CapiDataSource.Person.validation.failure.count`,
+        1
+      )
+    } else {
+      context.metrics?.count(
+        `graphql.datasource.CapiDataSource.Person.validation.success.count`,
+        1
+      )
+    }
+
+    return new Person(data as CapiPerson, context)
+  }
+
+  constructor(private person: CapiPerson, private context: QueryContext) {
     this.#systemCode = context.systemCode ?? 'cp-content-pipeline'
   }
 
   prefLabel() {
-    return this.concept.prefLabel()
+    return this.person.prefLabel
   }
 
   uuid() {
-    return this.concept.uuid()
+    return uuidFromUrl(this.person.id)
   }
 
   streamPage() {
@@ -40,40 +57,19 @@ export class Person {
   }
 
   apiUrl() {
-    return this.concept.apiUrl()
+    return this.person.apiUrl
   }
 
-  isAuthor() {
-    return this.concept.predicate() === predicates.hasAuthor
-  }
+  headshot(args: PersonHeadshotArgs) {
+    const url = decorateHeadshotUrl(this.person)
 
-  async headshot(args?: HeadshotArguments) {
-    try {
-      const uuid = this.apiUrl().match(UUID_REGEX)?.[0]
-      if (!this.isAuthor() || !uuid || !this.capiResponse) return null
-      const person = await this.context.dataSources.capi.getPerson(uuid)
-      const url = decorateHeadshotUrl(person)
-
-      return url
-        ? imageServiceUrl({
-            url,
-            systemCode: this.#systemCode,
-            width: args?.width || 150,
-            dpr: args?.dpr ?? undefined,
-          })
-        : null
-    } catch (error) {
-      if (isError(error)) {
-        this.context.logger.warn({
-          event: 'RECOVERABLE_ERROR',
-          error: new OperationalError({
-            message: `Error fetching CAPI Person for headshot URL for ${this.prefLabel()}`,
-            code: 'HEADSHOT_PERSON_FETCH_ERROR',
-            cause: error,
-          }),
+    return url
+      ? imageServiceUrl({
+          url,
+          systemCode: this.#systemCode,
+          width: args.width || 150,
+          dpr: args.dpr ?? undefined,
         })
-      }
-      return null
-    }
+      : null
   }
 }

package/src/model/Picture.test.ts

@@ -1,5 +1,5 @@
 import { QueryContext } from '..'
-import { ImageSet } from '../types/internal-content'
+import { ImageSet } from './schemas/capi/internal-content'
 import { Picture } from './Picture'
 
 const isLiveBlog = false

package/src/model/Picture.ts

@@ -1,5 +1,5 @@
 import { QueryContext } from '..'
-import { ImageSet } from '../types/internal-content'
+import { ImageSet } from './schemas/capi/internal-content'
 import { CAPIImage, Image } from './Image'
 import assert from 'assert'