Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/onebeyond/agnostic-cms-harmonizer
Library to manage the communication with any CMS agnostic to the user
https://github.com/onebeyond/agnostic-cms-harmonizer
agnostic cms nodejs npm package
Last synced: 3 months ago
JSON representation
Library to manage the communication with any CMS agnostic to the user
- Host: GitHub
- URL: https://github.com/onebeyond/agnostic-cms-harmonizer
- Owner: onebeyond
- License: mit
- Created: 2024-02-07T10:08:34.000Z (almost 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-12T11:56:32.000Z (6 months ago)
- Last Synced: 2024-09-19T02:27:34.046Z (5 months ago)
- Topics: agnostic, cms, nodejs, npm, package
- Language: TypeScript
- Homepage: https://onebeyond.github.io/agnostic-cms-harmonizer/
- Size: 1.12 MB
- Stars: 2
- Watchers: 12
- Forks: 1
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Agnostic CMS Harmonizer
An agnostic library to handle communication with multiple CMS in an agnostic way.
[](https://codeclimate.com/github/onebeyond/agnostic-cms-harmonizer/maintainability)
[](https://socket.dev/npm/package/@onebeyond/agnostic-cms-harmonizer)
Find the latest package version on the One Beyond NPM Registry
## Quick Start
Install the library via `npm`:
```sh
npm i @onebeyond/agnostic-cms-harmonizer
```
Use the harmonized providers:
```ts
import { ContentfulClient } from '@onebeyond/agnostic-cms-harmonizer';
const client = new ContentfulClient({
accessToken,
space,
environment,
});
await client.init();
const entry = await client.getEntry({ entryId: '123' });
const collection = await client.getCollection({ collectionId: '123' });
```
The library exposes a common interface for multiple CMSs and outputs [harmonized data](https://onebeyond.github.io/agnostic-cms-harmonizer/types/_types_output.HarmonizedOutput.html) instead raw responses.
Each CMS [provider](https://onebeyond.github.io/agnostic-cms-harmonizer/classes/index_abstract.AbstractProvider.html) exposes the [`getEntry`](https://onebeyond.github.io/agnostic-cms-harmonizer/classes/index_abstract.AbstractProvider.html#getEntry) and [`getCollection`](https://onebeyond.github.io/agnostic-cms-harmonizer/classes/index_abstract.AbstractProvider.html#getCollection) methods to request one or multiple entries accordingly.
First, supply the vendor-related configuration parameters to the constructor:
```ts
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:
```ts
await client.init();
```
Now use the harmonizer methods of the `cmsCLient`.
```ts
const entry = await client.getEntry({ entryId: '123' });
const collection = await client.getCollection({ collectionId: '123' });
```
Enjoy!
## Development
### CLI
Install [Contentful CLI](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#requirements) 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](https://www.contentful.com/developers/docs/references/authentication/#the-content-delivery-and-preview-api) 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](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#importing-content) 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:
```bash
contentful login
contentful space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id --environment-id
```
Or by using NPX:
```bash
npx contentful-cli login
npx contentful-cli space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id --environment-id
```
#### Export Content
To update the test content you need to [export](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#exporting-content) the updated content from Contentful.
Export the content using the CLI
```bash
contentful space export --config ./__tests__/exports/contentful/config.json --space-id --environment-id
```
Or by using NPX:
```bash
npx contentful-cli space export --config ./__tests__/exports/contentful/config.json --space-id --environment-id
```
#### Continous Integration
The pipeline is configured to use the Contentful space managed by the _**[email protected]**_ 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](https://beyondsecure.onebeyond.cloud/vaults/OB-BpuUbMukgIKDSxGqmypk/secrets), otherwise, you can open an issue referencing the new content exported.
#### Run the test suites
- Run unit tests
```sh
npm run test
```
- Run end to end tests
```sh
npm run test:e2e
```
### Documentation
The project uses `tsdoc` to generate the technical documentation from the source code.
- Build the documentation
```sh
npm run docs:build
```
- Run in _watch mode_ to look for file changes and update immediately
```sh
npm run docs:build:watch
```
- Serve the build output statically
```sh
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](https://allcontributors.org/docs/en/emoji-key)):
Íñigo Marquínez Prado
💻 📖 👀
Àlex Serra
💻 ⚠️ 📖 👀
Matyas Angyal
👀 💻 📖 ⚠️
Ulises Gascón
👀
Roberto Hernández
💻 ⚠️ 📖 👀
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!