@onebeyond/agnostic-cms-harmonizer

Agnostic CMS Harmonizer

An agnostic library to handle communication with multiple CMS in an agnostic way.

Find the latest package version on the One Beyond NPM Registry

Quick Start

Install the library via npm:

npm i @onebeyond/agnostic-cms-harmonizer

Use the harmonized providers:

 import { ContentfulClient } from '@onebeyond/agnostic-cms-harmonizer';
 
 const client = new ContentfulClient({
   accessToken,
   space,
   environment,
 });

 await client.init();

 const entry = await client.getEntry<MyEntry>({ entryId: '123' });

 const collection = await client.getCollection<MyCollection>({ collectionId: '123' });

The library exposes a common interface for multiple CMSs and outputs harmonized data instead raw responses.

Each CMS provider exposes the getEntry and getCollection methods to request one or multiple entries accordingly.

First, supply the vendor-related configuration parameters to the constructor:

const cmsClient = new CmsClient(vendorConfigurationObject)

The client instance must call the init() method to configure the provider before attempting to request data from the CMS:

await client.init();

Now use the harmonizer methods of the cmsCLient.

 const entry = await client.getEntry<MyEntry>({ entryId: '123' });

 const collection = await client.getCollection<MyCollection>({ collectionId: '123' });

Enjoy!

Development

CLI

Install Contentful CLI or alternatively use npx contentful-cli

Environment Variables

1. You have to create a space in contentful to run the tests.
2. Follow the instructions here to create an API key.
3. Setup your .env file as follows

CONTENTFUL_ACCESS_TOKEN=your_access_token
CONTENTFUL_ENVIRONMENT=your_environment
CONTENTFUL_SPACE=your_space
CONTENTFUL_ENTRY=your_entry
CONTENTFUL_CONTENT_TYPE=your_content_type

Testing

Import Content

To run the e2e tests you need to be authenticated in your contentful account and import the dummy content into the space you created before. The content you need to import is located at __tests__/exports/contentful/agnostic-cms-harmonizer_space.json and should not be updated.

Login to Contentful and import test content with the CLI:

contentful login

contentful space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Or by using NPX:

npx contentful-cli login

npx contentful-cli space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Export Content

To update the test content you need to export the updated content from Contentful.

Export the content using the CLI

contentful space export --config ./__tests__/exports/contentful/config.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Or by using NPX:

npx contentful-cli space export --config ./__tests__/exports/contentful/config.json --space-id <your-contentful-space-id> --environment-id <your-contentful-environment-id>

Continous Integration

The pipeline is configured to use the Contentful space managed by the [e-mail] account during the E2E tests execution. If the content of these tests needs to be updated in the provider, you must have access to this vault, otherwise, you can open an issue referencing the new content exported.

Run the test suites

• Run unit tests

npm run test

• Run end to end tests

npm run test:e2e

Documentation

The project uses tsdoc to generate the technical documentation from the source code.

• Build the documentation

npm run docs:build

• Run in watch mode to look for file changes and update immediately

npm run docs:build:watch

• Serve the build output statically

npm run docs:serve

Community

• We are open to improvements in the issues section.
• Check the wiki for more context on the internal workings of this library.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Íñigo Marquínez Prado 💻 📖 👀

Àlex Serra 💻 ⚠️ 📖 👀

Matyas Angyal 👀 💻 📖 ⚠️

Ulises Gascón 👀

Roberto Hernández 💻 ⚠️ 📖 👀

This project follows the all-contributors specification. Contributions of any kind welcome!

Changelog

0.2.3 (2024-05-16)

🔧 Others

• deps-dev: bump @typescript-eslint/parser from 7.2.0 to 7.8.0 (#103) (f02a4f6)
• deps-dev: bump npm-check-updates from 16.14.15 to 16.14.20 (#97) (8cfe2fd)
• deps-dev: bump typescript from 5.4.2 to 5.4.5 (#82) (b2dbff6)
• deps: bump actions/checkout from 4.1.2 to 4.1.4 (#93) (a050739)
• deps: bump actions/checkout from 4.1.4 to 4.1.5 (#107) (538d92d)
• deps: bump amannn/action-semantic-pull-request (#99) (5a0f5df)
• deps: bump contentful from 10.10.0 to 10.11.0 (#110) (6260238)
• deps: bump contentful from 10.8.3 to 10.10.0 (#108) (c5aad26)
• deps: bump github/codeql-action from 3.24.8 to 3.25.1 (#86) (38337b7)
• deps: bump github/codeql-action from 3.25.1 to 3.25.4 (#106) (c472444)
• deps: bump JamesIves/github-pages-deploy-action from 4.5.0 to 4.6.0 (#84) (aba693e)
• deps: bump step-security/harden-runner from 2.7.0 to 2.7.1 (#102) (b3b178c)
• deps: bump tar from 6.2.0 to 6.2.1 (#81) (0e12d3a)
• wiki reference (74e5ab2)

📝 Docs

• add robertoHeCi as a contributor for code, test, and 2 more (#95) (51fbb05)

🔄 Code Refactoring

• move the index files to a folder and create a index as a root level to be able to use the library properly (#90) (4fc2f79)

☁️ CI

• create a e2e test to make sure the export works as expected (#101) (badc839)