feat: enable timeline preview [TOL-3117] (#2525)

Author: 2wce

README.md

@@ -11,10 +11,10 @@
 <h3 align="center">Javascript</h3>
 
 <p align="center">
-  <a href="README.md">Readme</a> · 
-  <a href="MIGRATION.md">Migration</a> · 
-  <a href="ADVANCED.md">Advanced</a> · 
-  <a href="TYPESCRIPT.md">TypeScript</a> · 
+  <a href="README.md">Readme</a> ·
+  <a href="MIGRATION.md">Migration</a> ·
+  <a href="ADVANCED.md">Advanced</a> ·
+  <a href="TYPESCRIPT.md">TypeScript</a> ·
   <a href="CONTRIBUTING.md">Contributing</a>
 </p>
 
@@ -70,8 +70,8 @@ JavaScript library for the Contentful [Content Delivery API](https://www.content
   - [Authentication](#authentication)
 - [Documentation \& References](#documentation--references)
   - [Configuration](#configuration)
-      - [Request configuration options](#request-configuration-options)
-      - [Response configuration options](#response-configuration-options)
+    - [Request configuration options](#request-configuration-options)
+    - [Response configuration options](#response-configuration-options)
   - [Client chain modifiers](#client-chain-modifiers)
     - [Entries](#entries)
       - [Example](#example)
@@ -186,7 +186,7 @@ Check the [releases](https://github.com/contentful/contentful.js/releases) page
 The following code snippet is the most basic one you can use to get some content from Contentful with this library:
 
 ```js
-import * as contentful from "contentful"
+import * as contentful from 'contentful'
 const client = contentful.createClient({
   // This is the space ID. A space is like a project folder in Contentful terms
   space: 'developer_bookshelf',
@@ -207,7 +207,7 @@ Check out this [JSFiddle](https://jsfiddle.net/contentful/kefaj4s8/) version of
 This library can also be used with the Preview API. In order to do so, you need to use the Preview API Access token, available on the same page where you get the Delivery API token, and specify the host of the preview API, such as:
 
 ```js
-import * as contentful from "contentful"
+import * as contentful from 'contentful'
 const client = contentful.createClient({
   space: 'developer_bookshelf',
   accessToken: 'preview_0b7f6x59a0',
@@ -279,6 +279,28 @@ The configuration options belong to two categories: request config and response
 
 > :warning: **Response config options** have been **removed** in `v10.0.0` in favor of the new [client chain modifiers](#client-chain-modifiers) approach.
 
+### Timeline Preview
+
+The Timeline Preview API provides the ability to query content by future date or specific release
+
+##### Example
+
+```js
+import * as contentful from 'contentful'
+const client = contentful.createClient({
+  space: 'developer_bookshelf',
+  accessToken: 'preview_0b7f6x59a0',
+  host: 'preview.contentful.com',
+  // either release or timestamp or both can be passed as a valid config
+  alphaFeatures: {
+    timelinePreview: {
+      release: { lte: 'black-friday' },
+      timestamp: { lte: '2025-11-29T08:46:15Z' },
+    },
+  },
+})
+```
+
 ### Client chain modifiers
 
 > Introduced in `v10.0.0`.
@@ -332,24 +354,18 @@ const localizedData = {
     {
       metadata: { tags: [] },
       sys: {
-        space: {
-          sys: { type: 'Link', linkType: 'Space', id: 'my-space-id' },
-        },
+        space: { sys: { type: 'Link', linkType: 'Space', id: 'my-space-id' } },
         id: 'my-zoo',
         type: 'Entry',
         createdAt: '2020-01-01T00:00:00.000Z',
         updatedAt: '2020-01-01T00:00:00.000Z',
-        environment: {
-          sys: { id: 'master', type: 'Link', linkType: 'Environment' },
-        },
+        environment: { sys: { id: 'master', type: 'Link', linkType: 'Environment' } },
         revision: 1,
         contentType: { sys: { type: 'Link', linkType: 'ContentType', id: 'zoo' } },
         locale: 'en-US',
       },
       fields: {
-        animal: {
-          'en-US': { sys: { type: 'Link', linkType: 'Entry', id: 'oink' } },
-        },
+        animal: { 'en-US': { sys: { type: 'Link', linkType: 'Entry', id: 'oink' } } },
         anotheranimal: {
           'en-US': { sys: { type: 'Link', linkType: 'Entry', id: 'middle-parrot' } },
         },
@@ -361,28 +377,19 @@ const localizedData = {
       {
         metadata: { tags: [] },
         sys: {
-          space: {
-            sys: { type: 'Link', linkType: 'Space', id: 'my-space-id' },
-          },
+          space: { sys: { type: 'Link', linkType: 'Space', id: 'my-space-id' } },
           id: 'oink',
           type: 'Entry',
           createdAt: '2020-01-01T00:00:00.000Z',
           updatedAt: '2020-02-01T00:00:00.000Z',
-          environment: {
-            sys: { id: 'master', type: 'Link', linkType: 'Environment' },
-          },
+          environment: { sys: { id: 'master', type: 'Link', linkType: 'Environment' } },
           revision: 2,
           contentType: { sys: { type: 'Link', linkType: 'ContentType', id: 'animal' } },
           locale: 'en-US',
         },
         fields: {
-          name: {
-            'en-US': 'Pig',
-            de: 'Schwein',
-          },
-          friend: {
-            'en-US': { sys: { type: 'Link', linkType: 'Entry', id: 'groundhog' } },
-          },
+          name: { 'en-US': 'Pig', de: 'Schwein' },
+          friend: { 'en-US': { sys: { type: 'Link', linkType: 'Entry', id: 'groundhog' } } },
         },
       },
     ],

lib/contentful.ts

@@ -14,6 +14,7 @@ import {
   validateResolveLinksParam,
 } from './utils/validate-params.js'
 import type { ContentfulClientApi } from './types/client.js'
+import type { TimelinePreview } from './types/timeline-preview.js'
 
 /**
  * @category Client
@@ -119,6 +120,7 @@ export interface CreateClientParams {
    * This feature is only available when using the Content Preview API.
    */
   includeContentSourceMaps?: boolean
+
   /**
    * Enable alpha features.
    */
@@ -127,6 +129,13 @@ export interface CreateClientParams {
      * @deprecated Use the `includeContentSourceMaps` option directly instead.
      */
     includeContentSourceMaps?: boolean
+
+    /**
+     * Enable Timeline Preview.
+     * @remarks
+     * This feature is only available in private beta when using the Content Preview API.
+     */
+    timelinePreview?: TimelinePreview
   }
 }
 

lib/create-contentful-api.ts

@@ -43,6 +43,7 @@ import {
   validateResolveLinksParam,
 } from './utils/validate-params.js'
 import validateSearchParameters from './utils/validate-search-parameters.js'
+import { getTimelinePreviewParams } from './utils/timeline-preview-helpers.js'
 
 const ASSET_KEY_MAX_LIFETIME = 48 * 60 * 60
 
@@ -130,6 +131,27 @@ export default function createContentfulApi<OptionType extends ChainOptions>(
     return query
   }
 
+  function maybeEnableTimelinePreview(path: string): string {
+    const { enabled } = getTimelinePreviewParams(http.httpClientParams as CreateClientParams)
+    return enabled ? `timeline/${path}` : path
+  }
+
+  function maybeAddTimelinePreviewConfigToQuery(query: Record<string, any>) {
+    const { enabled, timelinePreview } = getTimelinePreviewParams(
+      http.httpClientParams as CreateClientParams,
+    )
+    if (enabled) {
+      if (timelinePreview?.release) {
+        query.release = timelinePreview.release
+      }
+      if (timelinePreview?.timestamp) {
+        query.timestamp = timelinePreview.timestamp
+      }
+    }
+
+    return query
+  }
+
   function maybeEncodeCPAResponse(data: any, config: Record<string, any>): any {
     const includeContentSourceMaps = config?.params?.includeContentSourceMaps as boolean
 
@@ -260,6 +282,13 @@ export default function createContentfulApi<OptionType extends ChainOptions>(
     )
   }
 
+  function prepareQuery(query: Record<string, any>): Record<string, any> {
+    // First, add timeline preview config if enabled
+    const withTimelinePreview = maybeAddTimelinePreviewConfigToQuery({ ...query })
+    // Then, apply source maps and other normalizations
+    return maybeEnableSourceMaps(normalizeSearchParameters(normalizeSelect(withTimelinePreview)))
+  }
+
   async function internalGetEntries<
     EntrySkeleton extends EntrySkeletonType,
     Locales extends LocaleCode,
@@ -269,13 +298,12 @@ export default function createContentfulApi<OptionType extends ChainOptions>(
     options: Options,
   ): Promise<EntryCollection<EntrySkeleton, ModifiersFromOptions<Options>, Locales>> {
     const { withoutLinkResolution, withoutUnresolvableLinks } = options
-
     try {
       const entries = await get({
         context: 'environment',
-        path: 'entries',
+        path: maybeEnableTimelinePreview('entries'),
         config: createRequestConfig({
-          query: maybeEnableSourceMaps(normalizeSearchParameters(normalizeSelect(query))),
+          query: prepareQuery(query),
         }),
       })
 
@@ -321,8 +349,8 @@ export default function createContentfulApi<OptionType extends ChainOptions>(
     try {
       return get({
         context: 'environment',
-        path: `assets/${id}`,
-        config: createRequestConfig({ query: maybeEnableSourceMaps(normalizeSelect(query)) }),
+        path: maybeEnableTimelinePreview(`assets/${id}`),
+        config: createRequestConfig({ query: prepareQuery(query) }),
       })
     } catch (error) {
       errorHandler(error)
@@ -354,9 +382,9 @@ export default function createContentfulApi<OptionType extends ChainOptions>(
     try {
       return get({
         context: 'environment',
-        path: 'assets',
+        path: maybeEnableTimelinePreview('assets'),
         config: createRequestConfig({
-          query: maybeEnableSourceMaps(normalizeSearchParameters(normalizeSelect(query))),
+          query: prepareQuery(query),
         }),
       })
     } catch (error) {

lib/types/timeline-preview.ts

@@ -0,0 +1,4 @@
+export type TimelinePreview = {
+  release?: { lte: string }
+  timestamp?: { lte: string | Date }
+} & ({ release: { lte: string } } | { timestamp: { lte: string | Date } })

lib/utils/timeline-preview-helpers.ts

@@ -0,0 +1,48 @@
+import type { CreateClientParams } from '../contentful'
+import type { TimelinePreview } from '../types/timeline-preview'
+import { checkEnableTimelinePreviewIsAllowed } from './validate-params'
+import { ValidationError } from './validation-error'
+
+function isValidRelease(release: TimelinePreview['release']): boolean {
+  return !!(release && typeof release === 'object' && typeof release.lte === 'string')
+}
+
+function isValidTimestamp(timestamp: TimelinePreview['timestamp']): boolean {
+  return !!(
+    timestamp &&
+    typeof timestamp === 'object' &&
+    (typeof timestamp.lte === 'string' || timestamp.lte instanceof Date)
+  )
+}
+
+export const isValidTimelinePreviewConfig = (timelinePreview: TimelinePreview) => {
+  if (
+    typeof timelinePreview !== 'object' ||
+    timelinePreview === null ||
+    Array.isArray(timelinePreview)
+  ) {
+    throw new ValidationError(
+      'timelinePreview',
+      `The 'timelinePreview' parameter must be an object.`,
+    )
+  }
+
+  const hasRelease = isValidRelease(timelinePreview.release)
+  const hasTimestamp = isValidTimestamp(timelinePreview.timestamp)
+
+  if (!hasRelease && !hasTimestamp) {
+    throw new ValidationError(
+      'timelinePreview',
+      `The 'timelinePreview' object must have at least one of 'release' or 'timestamp' with a valid 'lte' property.`,
+    )
+  }
+
+  return hasRelease || hasTimestamp
+}
+
+export const getTimelinePreviewParams = (params: CreateClientParams) => {
+  const host = params?.host as string
+  const timelinePreview = params?.alphaFeatures?.timelinePreview as TimelinePreview
+  const enabled = checkEnableTimelinePreviewIsAllowed(host, timelinePreview)
+  return { enabled, timelinePreview }
+}

lib/utils/validate-params.ts

@@ -1,3 +1,5 @@
+import type { TimelinePreview } from '../types/timeline-preview.js'
+import { isValidTimelinePreviewConfig } from './timeline-preview-helpers.js'
 import { ValidationError } from './validation-error.js'
 
 function checkLocaleParamIsAll(query) {
@@ -74,3 +76,26 @@ export function checkIncludeContentSourceMapsParamIsAllowed(
 
   return includeContentSourceMaps as boolean
 }
+
+export function checkEnableTimelinePreviewIsAllowed(
+  host: string,
+  timelinePreview?: TimelinePreview,
+) {
+  if (timelinePreview === undefined) {
+    return false
+  }
+
+  const isValidConfig = isValidTimelinePreviewConfig(timelinePreview)
+
+  const isValidHost = typeof host === 'string' && host.startsWith('preview')
+
+  if (isValidConfig && !isValidHost) {
+    throw new ValidationError(
+      'timelinePreview',
+      `The 'timelinePreview' parameter can only be used with the CPA. Please set host to 'preview.contentful.com' to enable Timeline Preview.
+      `,
+    )
+  }
+
+  return true
+}

test/integration/getEntry.test.ts

@@ -353,3 +353,18 @@ test('Gets entry with attached metadata and field called "metadata" on preview',
   expect(response.fields.metadata).toBeDefined()
   expect(response.metadata).toBeDefined()
 })
+
+test('can make calls to TimelinePreview API on preview', async () => {
+  const timelinePreviewClient = contentful.createClient({
+    ...previewParamsWithCSM,
+    alphaFeatures: {
+      timelinePreview: { release: { lte: 'black-friday' } },
+    },
+  })
+
+  const entryWithMetadataFieldAndMetadata = '1NnAC4eF9IRMpHtFB1NleW'
+
+  await expect(timelinePreviewClient.getEntry(entryWithMetadataFieldAndMetadata)).rejects.toThrow(
+    /spaces\/ezs1swce23xe\/environments\/master\/timeline\/entries/,
+  )
+})