@financial-times/cp-content-pipeline-schema 0.2.1

package/src/helpers/metadata.ts

@@ -0,0 +1,88 @@
+import type { InternalContent, Annotation } from '../types/internal-content.js'
+
+import conceptIds from '@financial-times/n-concept-ids'
+
+export function uuidFromUrl(url: string): string {
+  const match = url.match(/(........-....-....-....-............)/)
+
+  if (match === null) {
+    return ''
+  }
+
+  return match[1] || ''
+}
+
+export function isOpinion(content: InternalContent): boolean {
+  return content.annotations.some((annotation) =>
+    annotation.id.endsWith(conceptIds.genre.opinion)
+  )
+}
+
+function isAuthor(annotation: Annotation) {
+  return (
+    annotation.predicate === 'http://www.ft.com/ontology/annotation/hasAuthor'
+  )
+}
+
+function createStreamLink(streamUuid: string) {
+  return `https://www.ft.com/stream/uuid/${streamUuid}`
+}
+
+export function getAuthorUrlMapping(annotations: Annotation[]) {
+  const authorAnnotations = getAuthorAnnotations(annotations)
+  return authorAnnotations.reduce((mapping, author) => {
+    if (author.prefLabel) {
+      const uuid = uuidFromUrl(author.id)
+      mapping.set(author.prefLabel, createStreamLink(uuid))
+    }
+    return mapping
+  }, new Map<string, string>)
+}
+
+function getAuthorAnnotations(annotations: Annotation[]) {
+  return annotations.filter(isAuthor)
+}
+
+export function getAuthor(content: InternalContent): Annotation | undefined {
+  return content.annotations.find((annotation) => isAuthor(annotation))
+}
+
+export function isColumn(content: InternalContent): boolean {
+  return isOpinion(content) && !!getAuthor(content)
+}
+
+export function getDisplayConcept(
+  content: InternalContent
+): Annotation | undefined {
+  return content.annotations.find(
+    (annotation) =>
+      annotation.predicate === 'http://www.ft.com/ontology/hasDisplayTag'
+  )
+}
+
+export function getBrandConcept(
+  content: InternalContent
+): Annotation | undefined {
+  return content.annotations.find(
+    (annotation) =>
+      annotation.predicate ===
+        'http://www.ft.com/ontology/classification/isClassifiedBy' &&
+      annotation.directType === 'http://www.ft.com/ontology/product/Brand'
+  )
+}
+
+export function isPodcast(content: InternalContent): boolean {
+  return content.types.includes('http://www.ft.com/ontology/content/Audio')
+}
+
+export function isEditorsChoice(content: InternalContent): boolean {
+  return !!content.standout?.editorsChoice
+}
+
+export function isExclusive(content: InternalContent): boolean {
+  return !!content.standout?.exclusive
+}
+
+export function isScoop(content: InternalContent): boolean {
+  return !!content.standout?.scoop
+}

package/src/helpers/syntaxTree.ts

@@ -0,0 +1,26 @@
+export function buildUrlTree(
+  urlMapping: Map<string, string>,
+  parts: string[]
+) {
+  const children = parts.map((part) => {
+    const url = urlMapping.get(part)
+
+    if (url) {
+      return {
+        type: 'element',
+        tagName: 'Link',
+        properties: { href: url },
+        children: [{ type: 'text', value: part }],
+      }
+    } else {
+      return {
+        type: 'text',
+        value: part,
+      }
+    }
+  })
+
+  return {
+    tree: { type: 'root', children },
+  }
+}

package/src/image.test.ts

@@ -0,0 +1,339 @@
+import { resolvers, ImageType } from './image.js'
+import type { ImageSourceArgs, DisplayWidthArgs } from './image.js'
+import type { Image } from './types/internal-content.js'
+import { jest } from '@jest/globals'
+import { IObjectTypeResolver } from '@graphql-tools/utils'
+
+//TODO:AG:20220908 Replace this with generated schema types
+type ImageSource = {
+  url: string
+  width?: number
+  dpr?: number
+}
+
+describe('Image', () => {
+  const image = {
+    id: 'https://api.ft.com/content/00000000-0000-0000-0000-000000000001',
+    type: ImageType.Image,
+    title: 'title',
+    description: 'description',
+    binaryUrl: 'cloudfront.com/image',
+  }
+
+  const graphic = {
+    ...image,
+    type: ImageType.Graphic,
+  }
+
+  const getImageMetadata = jest.fn()
+
+  const context = {
+    dataSources: {
+      origami: {
+        getImageMetadata: getImageMetadata,
+      },
+      capi: {},
+    },
+  }
+
+  beforeEach(() => {
+    getImageMetadata.mockReset()
+  })
+
+  describe('sources resolver', () => {
+    type ResolverType = (
+      root: Image,
+      args: ImageSourceArgs,
+      context: unknown
+    ) => Promise<ImageSource[]>
+
+    const sourcesResolver = (resolvers.Image as IObjectTypeResolver)
+      .sources as ResolverType
+
+    describe('An image that is provided with a high resolution', () => {
+      let sources: ImageSource[]
+
+      beforeAll(async () => {
+        getImageMetadata.mockReturnValue({ width: 5000, height: 1000 })
+        sources = await sourcesResolver(
+          image,
+          {
+            width: 1000,
+          },
+          context
+        )
+      })
+
+      it('transforms the URL to use the Origami Image Service', () => {
+        expect(
+          sources.every((source) =>
+            source.url.startsWith(
+              'https://www.ft.com/__origami/service/image/v2'
+            )
+          )
+        ).toBeTruthy()
+      })
+
+      it('resizes the image to the requested width', () => {
+        expect(
+          sources.every(
+            (source) =>
+              source.width === 1000 && source.url.includes('width=1000')
+          )
+        ).toBeTruthy()
+      })
+
+      it('includes sources for all the possible resolutions we can display the image at, given the requested width and the original source width', () => {
+        expect(sources.length).toEqual(5)
+        expect(sources[0].dpr).toEqual(1)
+        expect(sources[0].url).toMatch(/dpr=1/)
+        expect(sources[4].dpr).toEqual(5)
+        expect(sources[4].url).toMatch(/dpr=5/)
+      })
+    })
+
+    describe("An image that that isn't wide enough to generate high-resolution sources for", () => {
+      it('returns an array with a single resolution iamge service UR', async () => {
+        getImageMetadata.mockReturnValue({ width: 1500, height: 500 })
+        const sources = await sourcesResolver(
+          image,
+          {
+            width: 1000,
+          },
+          context
+        )
+        expect(sources.length).toEqual(1)
+        expect(sources[0]).toEqual({
+          dpr: 1,
+          url: 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3A00000000-0000-0000-0000-000000000001?source=undefined&fit=scale-down&quality=highest&width=1000&dpr=1',
+          width: 1000,
+        })
+      })
+    })
+
+    describe('An image that that is smaller than the width that was requested', () => {
+      it('returns the image at the same width as the original', async () => {
+        getImageMetadata.mockReturnValue({ width: 500, height: 500 })
+        const sources = await sourcesResolver(
+          image,
+          {
+            width: 1000,
+          },
+          context
+        )
+        expect(sources.length).toEqual(1)
+        expect(sources[0]).toEqual({
+          dpr: 1,
+          url: 'https://www.ft.com/__origami/service/image/v2/images/raw/ftcms%3A00000000-0000-0000-0000-000000000001?source=undefined&fit=scale-down&quality=highest&width=500&dpr=1',
+          width: 500,
+        })
+      })
+    })
+
+    describe('A large image with the maxDpr argumet passed', () => {
+      it('only returns sources up to and including the maxDpr', async () => {
+        getImageMetadata.mockReturnValue({ width: 5000, height: 500 })
+        const sources = await sourcesResolver(
+          image,
+          {
+            width: 1000,
+            maxDpr: 2,
+          },
+          context
+        )
+        expect(sources.length).toEqual(2)
+        expect(sources[0].dpr).toEqual(1)
+        expect(sources[1].dpr).toEqual(2)
+      })
+    })
+
+    describe('An invalid image object', () => {
+      it('throws an error', async () => {
+        const invalidImage = {
+          type: ImageType.Image,
+          id: 'not-a-uuid',
+          title: '',
+          description: '',
+          binaryUrl: '',
+        }
+        await expect(
+          sourcesResolver(
+            invalidImage,
+            {
+              width: 1000,
+              maxDpr: 2,
+            },
+            context
+          )
+        ).rejects.toThrow('not-a-uuid is not a valid Content API Image ID')
+        expect(getImageMetadata).not.toHaveBeenCalled()
+      })
+    })
+
+    describe('When the image service fails to return metadata', () => {
+      let sources: ImageSource[]
+      beforeEach(async () => {
+        getImageMetadata.mockRejectedValue(null)
+
+        sources = await sourcesResolver(
+          image,
+          {
+            width: 3000,
+          },
+          context
+        )
+      })
+      it('passes the requested width to the image service', async () => {
+        expect(sources.length).toEqual(1)
+        expect(sources[0].width).toEqual(3000)
+        expect(sources[0].url).toMatch(/width=3000/)
+      })
+      it('falls back to a single DPR source', async () => {
+        expect(sources.length).toEqual(1)
+        expect(sources[0].dpr).toEqual(1)
+        expect(sources[0].url).toMatch(/dpr=1/)
+      })
+    })
+  })
+
+  describe('originalWidth/originalHeight resolvers', () => {
+    type ResolverType = (
+      root: Image,
+      args: undefined,
+      context: unknown
+    ) => Promise<number | null>
+
+    const originalWidthResolver = (resolvers.Image as IObjectTypeResolver)
+      .originalWidth as ResolverType
+    const originalHeightResolver = (resolvers.Image as IObjectTypeResolver)
+      .originalHeight as ResolverType
+
+    it('returns the original width and height from the image service metadata', async () => {
+      getImageMetadata.mockReturnValue({ width: 100, height: 200 })
+      const width = await originalWidthResolver(image, undefined, context)
+      const height = await originalHeightResolver(image, undefined, context)
+      expect(width).toEqual(100)
+      expect(height).toEqual(200)
+    })
+
+    it('returns null if the image service metadata call fails', async () => {
+      getImageMetadata.mockRejectedValue(null)
+      const width = await originalWidthResolver(image, undefined, context)
+      const height = await originalHeightResolver(image, undefined, context)
+      expect(width).toEqual(null)
+      expect(height).toEqual(null)
+    })
+  })
+
+  describe('minDisplayWidth/maxDisplayWidth resolvers', () => {
+    type ResolverType = (
+      root: Image,
+      args?: DisplayWidthArgs
+    ) => Promise<number | null>
+
+    const minDisplayWidthResolver = (resolvers.Image as IObjectTypeResolver)
+      .minDisplayWidth as ResolverType
+    const maxDisplayWidthResolver = (resolvers.Image as IObjectTypeResolver)
+      .maxDisplayWidth as ResolverType
+
+    it('uses the argument value if supplied, so consumers can control when an image should be displayed', () => {
+      const imageWithDisplayWidth = {
+        ...image,
+        minDisplayWidth: '980px',
+      }
+      const minDisplayWidth = minDisplayWidthResolver(imageWithDisplayWidth, {
+        width: 500,
+      })
+      const maxDisplayWidth = maxDisplayWidthResolver(imageWithDisplayWidth, {
+        width: 900,
+      })
+      expect(minDisplayWidth).toEqual('500px')
+      expect(maxDisplayWidth).toEqual('900px')
+    })
+
+    it('uses the values from the content API if no overrides supplied', () => {
+      const imageWithDisplayWidth = {
+        ...image,
+        minDisplayWidth: '490px',
+        maxDisplayWidth: '980px',
+      }
+      const minDisplayWidth = minDisplayWidthResolver(imageWithDisplayWidth, {})
+      const maxDisplayWidth = maxDisplayWidthResolver(imageWithDisplayWidth, {})
+      expect(minDisplayWidth).toEqual('490px')
+      expect(maxDisplayWidth).toEqual('980px')
+    })
+
+    it('returns undefined if no values supplied or in content API response ', () => {
+      const minDisplayWidth = minDisplayWidthResolver(image, {})
+      const maxDisplayWidth = maxDisplayWidthResolver(image, {})
+      expect(minDisplayWidth).toBeUndefined()
+      expect(maxDisplayWidth).toBeUndefined()
+    })
+  })
+
+  describe('caption resolver', () => {
+    type ResolverType = (root: Image) => Promise<string | null>
+
+    const captionResolver = (resolvers.Image as IObjectTypeResolver)
+      .caption as ResolverType
+
+    it('combines the caption and copyright together', () => {
+      const imageWithCopyright = { ...image, copyright: { notice: '© credit' } }
+      const caption = captionResolver(imageWithCopyright)
+      expect(caption).toBe('title © credit')
+    })
+
+    it('returns just the caption if there is no copright', () => {
+      const caption = captionResolver(image)
+      expect(caption).toBe('title')
+    })
+  })
+
+  describe('copyright resolver', () => {
+    type ResolverType = (root: Image) => Promise<string | null>
+
+    const copyrightResolver = (resolvers.Image as IObjectTypeResolver)
+      .copyright as ResolverType
+
+    it('returns the copyright notice if it exists', () => {
+      const imageWithCopyright = { ...image, copyright: { notice: '© credit' } }
+      const copyright = copyrightResolver(imageWithCopyright)
+      expect(copyright).toBe('© credit')
+    })
+
+    it('returns undefined if no copyright', () => {
+      const copyright = copyrightResolver(image)
+      expect(copyright).toBe(undefined)
+    })
+  })
+
+  describe('alt resolver', () => {
+    type ResolverType = (root: Image) => Promise<string | null>
+
+    const altResolver = (resolvers.Image as IObjectTypeResolver)
+      .alt as ResolverType
+
+    it('uses the description if it exists', () => {
+      const alt = altResolver(image)
+      expect(alt).toBe('description')
+    })
+
+    it('escapes double quotes', () => {
+      const alt = altResolver({
+        ...image,
+        description: 'This is a "quoted" description',
+      })
+      expect(alt).toBe('This is a &quot;quoted&quot; description')
+    })
+
+    it("returns an empty string for images with no description, so screen readers don't read out the URL", () => {
+      const alt = altResolver({ ...image, description: '' })
+      expect(alt).toBe('')
+    })
+
+    it('returns an default alt text for graphics with no description, as they are not considered presentational', () => {
+      const alt = altResolver({ ...graphic, description: '' })
+      expect(alt).toBe('A graphic with no description')
+    })
+  })
+})

package/src/image.ts

@@ -0,0 +1,154 @@
+import { gql } from 'graphql-tag'
+import { IResolvers } from '@graphql-tools/utils'
+import imageServiceUrl from './helpers/imageService.js'
+import type { DataSources } from './datasources/index.js'
+import { uuidFromUrl } from './helpers/metadata.js'
+import type { Image } from './types/internal-content.js'
+
+type ImageDimensions = {
+  width: number
+  height: number
+}
+
+export type ImageSourceArgs = {
+  width: number
+  maxDpr?: number
+}
+
+export type DisplayWidthArgs = {
+  width?: number
+}
+
+export const ImageType = {
+  Image: 'http://www.ft.com/ontology/content/Image',
+  Graphic: 'http://www.ft.com/ontology/content/Graphic',
+} as const
+
+export const typeDef = gql`
+  enum ImageType {
+    Image
+    Graphic
+  }
+
+  type ImageSource {
+    url: String!
+    width: Int
+    dpr: Int
+  }
+
+  type Image {
+    type: ImageType
+    sources(width: Int, maxDpr: Int): [ImageSource!]!
+    binaryUrl: String
+    originalWidth: Int
+    originalHeight: Int
+    copyright: String
+    minDisplayWidth(
+      """
+      min-width (in pixels) for this image to be displayed.
+      Overrides any value coming from the Content API
+      """
+      width: Int
+    ): String
+    maxDisplayWidth(width: Int): String
+    caption: String!
+    alt: String!
+  }
+`
+
+export async function getImageDimensions(
+  image: Image,
+  dataSources: DataSources
+): Promise<ImageDimensions> {
+  if (image.pixelWidth && image.pixelHeight) {
+    return { width: image.pixelWidth, height: image.pixelHeight }
+  }
+  const binaryUrl = image.binaryUrl
+  const imageMetadata = await dataSources.origami.getImageMetadata(binaryUrl)
+  return imageMetadata
+}
+
+export const resolvers: IResolvers<
+  unknown,
+  { systemCode: string; dataSources: DataSources },
+  never
+> = {
+  Image: {
+    async sources(parent: Image, args: ImageSourceArgs, context) {
+      const id = uuidFromUrl(parent.id)
+      if (!id) {
+        throw new Error(`${parent.id} is not a valid Content API Image ID`)
+      }
+      const requestedWidth = args.width || 700
+      let maxAllowedWidth = requestedWidth
+      let maxDpr = 1
+      try {
+        const dimensions = await getImageDimensions(parent, context.dataSources)
+        maxAllowedWidth = Math.min(requestedWidth, dimensions.width)
+        maxDpr = Math.min(
+          args.maxDpr || Infinity,
+          Math.floor(dimensions.width / maxAllowedWidth)
+        )
+      } catch (err) {
+        //TODO: log error
+      }
+      const resolutions = [...Array(maxDpr + 1).keys()].slice(1)
+
+      return resolutions.map((dpr) => ({
+        url: imageServiceUrl({
+          id,
+          url: parent.binaryUrl,
+          systemCode: context.systemCode,
+          width: maxAllowedWidth,
+          dpr,
+        }),
+        width: maxAllowedWidth,
+        dpr,
+      }))
+    },
+    async originalWidth(parent: Image, args, context) {
+      try {
+        const dimensions = await getImageDimensions(parent, context.dataSources)
+        return dimensions.width
+      } catch (err) {
+        //TODO: log error
+        return null
+      }
+    },
+    async originalHeight(parent: Image, args, context) {
+      try {
+        const dimensions = await getImageDimensions(parent, context.dataSources)
+        return dimensions.height
+      } catch (err) {
+        //TODO: log error
+        return null
+      }
+    },
+
+    copyright(parent: Image) {
+      return parent.copyright?.notice
+    },
+
+    minDisplayWidth(parent: Image, args: DisplayWidthArgs) {
+      return args.width ? `${args.width}px` : parent.minDisplayWidth
+    },
+    maxDisplayWidth(parent: Image, args: DisplayWidthArgs) {
+      return args.width ? `${args.width}px` : parent.maxDisplayWidth
+    },
+
+    caption(parent: Image) {
+      const elements = [parent.title, parent.copyright?.notice].filter(Boolean)
+      return elements.length && elements.join(' ')
+    },
+
+    alt(parent: Image) {
+      const fallback =
+        parent.type === ImageType.Graphic ? 'A graphic with no description' : ''
+      return (parent.description || fallback).replace(/"/g, '&quot;')
+    },
+  },
+  ImageType: {
+    Image: ImageType.Image,
+    Graphic: ImageType.Graphic,
+  },
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+import type { IResolvers } from '@graphql-tools/utils'
+import { DocumentNode } from 'graphql'
+import { gql } from 'graphql-tag'
+
+import { dataSources, DataSources } from './datasources/index.js'
+
+import { typeDef as Content, resolvers as contentResolvers } from './content.js'
+import { typeDef as Concept, resolvers as conceptResolvers } from './concept.js'
+import { typeDef as Picture, resolvers as pictureResolvers } from './picture.js'
+import { typeDef as Image, resolvers as imageResolvers } from './image.js'
+import { typeDef as Topper, resolvers as topperResolvers } from './topper.js'
+import {
+  typeDef as RichText,
+  resolvers as richTextResolvers,
+} from './richText.js'
+
+import tags from './tags.js'
+
+const tagEntries = Object.entries(tags)
+const tagsWithReferences = tagEntries.filter(([_key, tag]) => tag.typeDef)
+const tagTypeDefs = tagsWithReferences.flatMap(
+  ([_key, tag]) => tag.typeDef as DocumentNode
+)
+const Reference = gql`union Reference = ${tagsWithReferences
+  .flatMap(([key]) => key)
+  .join(' | ')}`
+
+const tagResolvers = Object.fromEntries(
+  tagEntries.flatMap(([key, tag]) => (tag.resolve ? [[key, tag.resolve]] : []))
+)
+
+// A schema is a collection of type definitions (hence "typeDefs")
+// that together define the "shape" of queries that are executed against
+// your data.
+const coreTypeDefs = gql`
+  # Comments in GraphQL strings (such as this one) start with the hash (#) symbol.
+
+  scalar JSON
+
+  # The "Query" type is special: it lists all of the available queries that
+  # clients can execute, along with the return type for each. In this
+  # case, the "books" query returns an array of zero or more Books (defined above).
+  type Query {
+    content(uuid: String!): Content!
+    contentFromJSON(content: JSON!): Content!
+  }
+`
+// Resolvers define the technique for fetching the types defined in the
+// schema. This resolver retrieves books from the "books" array above.
+export const resolvers: IResolvers<unknown, { dataSources: DataSources }> = {
+  Query: {
+    async content(parent, args, context) {
+      return context.dataSources.capi.getContent(args.uuid)
+    },
+    contentFromJSON(_, { content }) {
+      return content
+    },
+  },
+
+  Reference: {
+    __resolveType(obj: { constructor: { name: string } }) {
+      return obj.constructor.name
+    },
+  },
+
+  ...conceptResolvers,
+  ...contentResolvers,
+  ...pictureResolvers,
+  ...imageResolvers,
+  ...tagResolvers,
+  ...topperResolvers,
+  ...richTextResolvers,
+}
+
+export const typeDefs = [
+  Content,
+  Concept,
+  Picture,
+  Image,
+  Topper,
+  RichText,
+  Reference,
+  tagTypeDefs,
+  coreTypeDefs,
+]
+
+export { dataSources, DataSources, typeDefs as schema }