{"id":20348493,"url":"https://github.com/onebeyond/agnostic-cms-harmonizer","last_synced_at":"2025-04-12T01:15:08.761Z","repository":{"id":221323525,"uuid":"754055415","full_name":"onebeyond/agnostic-cms-harmonizer","owner":"onebeyond","description":"Library to manage the communication with any CMS agnostic to the user","archived":false,"fork":false,"pushed_at":"2024-08-12T11:56:32.000Z","size":1172,"stargazers_count":2,"open_issues_count":12,"forks_count":1,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-12T01:15:02.080Z","etag":null,"topics":["agnostic","cms","nodejs","npm","package"],"latest_commit_sha":null,"homepage":"https://onebeyond.github.io/agnostic-cms-harmonizer/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onebeyond.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-07T10:08:34.000Z","updated_at":"2024-05-16T15:14:00.000Z","dependencies_parsed_at":"2024-02-26T08:31:50.684Z","dependency_job_id":"8d884d44-cb0e-49a8-ab80-5e745bb51c76","html_url":"https://github.com/onebeyond/agnostic-cms-harmonizer","commit_stats":null,"previous_names":["onebeyond/agnostic-cms-harmonizer"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fagnostic-cms-harmonizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fagnostic-cms-harmonizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fagnostic-cms-harmonizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onebeyond%2Fagnostic-cms-harmonizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onebeyond","download_url":"https://codeload.github.com/onebeyond/agnostic-cms-harmonizer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248501861,"owners_count":21114684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agnostic","cms","nodejs","npm","package"],"created_at":"2024-11-14T22:20:49.213Z","updated_at":"2025-04-12T01:15:08.738Z","avatar_url":"https://github.com/onebeyond.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agnostic CMS Harmonizer\n\nAn agnostic library to handle communication with multiple CMS in an agnostic way.\n\n![NPM Version](https://img.shields.io/npm/v/%40onebeyond%2Fagnostic-cms-harmonizer)\n![GitHub Release Date](https://img.shields.io/github/release-date/onebeyond/agnostic-cms-harmonizer)\n[![maintainability](https://api.codeclimate.com/v1/badges/9c8389517a18ceabc76d/maintainability)](https://codeclimate.com/github/onebeyond/agnostic-cms-harmonizer/maintainability)\n[![Socket](https://socket.dev/api/badge/npm/package/@onebeyond/agnostic-cms-harmonizer)](https://socket.dev/npm/package/@onebeyond/agnostic-cms-harmonizer)\n\n![NPM Downloads](https://img.shields.io/npm/dt/%40onebeyond%2Fagnostic-cms-harmonizer)\n![all contributors](https://img.shields.io/github/all-contributors/onebeyond/agnostic-cms-harmonizer?color=ee8449\u0026style=flat-square)\n![LICENSE](https://img.shields.io/npm/l/%40onebeyond%2Fagnostic-cms-harmonizer)\n![dependencies](https://img.shields.io/librariesio/github/onebeyond/agnostic-cms-harmonizer)\n![NPM Unpacked Size](https://img.shields.io/npm/unpacked-size/%40onebeyond%2Fagnostic-cms-harmonizer)\n\nFind the latest package version on the \u003cem\u003eOne Beyond \u003ca target=\"_blank\" href=\"https://www.npmjs.com/package/@onebeyond/agnostic-cms-harmonizer\"\u003eNPM Registry\u003c/a\u003e\u003c/em\u003e\n\n\n## Quick Start\n\nInstall the library via `npm`:\n\n```sh\nnpm i @onebeyond/agnostic-cms-harmonizer\n```\n\nUse the harmonized providers:\n\n```ts\n import { ContentfulClient } from '@onebeyond/agnostic-cms-harmonizer';\n \n const client = new ContentfulClient({\n   accessToken,\n   space,\n   environment,\n });\n\n await client.init();\n\n const entry = await client.getEntry\u003cMyEntry\u003e({ entryId: '123' });\n\n const collection = await client.getCollection\u003cMyCollection\u003e({ collectionId: '123' });\n```\n\nThe 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.\n\nEach 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.\n\nFirst, supply the vendor-related configuration parameters to the constructor:\n\n```ts\nconst cmsClient = new CmsClient(vendorConfigurationObject)\n```\n\nThe client instance _must_ call the `init()` method to configure the provider before attempting to request data from the CMS:\n\n```ts\nawait client.init();\n```\n\nNow use the harmonizer methods of the `cmsCLient`.\n\n```ts\n const entry = await client.getEntry\u003cMyEntry\u003e({ entryId: '123' });\n\n const collection = await client.getCollection\u003cMyCollection\u003e({ collectionId: '123' });\n```\n\nEnjoy!\n\n## Development\n\n### CLI\nInstall [Contentful CLI](https://www.contentful.com/developers/docs/tutorials/cli/import-and-export/#requirements) or alternatively use `npx contentful-cli`\n\n### Environment Variables\n\n 1. You have to create a space in contentful to run the tests.\n 2. Follow the instructions [here](https://www.contentful.com/developers/docs/references/authentication/#the-content-delivery-and-preview-api) to create an API key.\n 3. Setup your `.env` file as follows\n\n ```\n CONTENTFUL_ACCESS_TOKEN=your_access_token\n CONTENTFUL_ENVIRONMENT=your_environment\n CONTENTFUL_SPACE=your_space\n CONTENTFUL_ENTRY=your_entry\n CONTENTFUL_CONTENT_TYPE=your_content_type\n ```\n\n### Testing\n\n#### Import Content\n\nTo 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.\n\nLogin to Contentful and import test content with the CLI:\n\n```bash\ncontentful login\n\ncontentful space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id \u003cyour-contentful-space-id\u003e --environment-id \u003cyour-contentful-environment-id\u003e\n```\n\nOr by using NPX:\n\n```bash\nnpx contentful-cli login\n\nnpx contentful-cli space import --content-file __tests__/exports/contentful/agnostic-cms-harmonizer_space.json --space-id \u003cyour-contentful-space-id\u003e --environment-id \u003cyour-contentful-environment-id\u003e\n```\n\n#### Export Content\n\nTo 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. \n\nExport the content using the CLI\n```bash\ncontentful space export --config ./__tests__/exports/contentful/config.json --space-id \u003cyour-contentful-space-id\u003e --environment-id \u003cyour-contentful-environment-id\u003e\n```\n\nOr by using NPX:\n\n```bash\nnpx contentful-cli space export --config ./__tests__/exports/contentful/config.json --space-id \u003cyour-contentful-space-id\u003e --environment-id \u003cyour-contentful-environment-id\u003e\n```\n\n#### Continous Integration\nThe pipeline is configured to use the Contentful space managed by the _**agnostic.cms.harmonizer@proton.me**_ 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.\n\n#### Run the test suites\n\n- Run unit tests\n\n```sh\nnpm run test\n```\n\n- Run end to end tests\n\n```sh\nnpm run test:e2e\n```\n\n### Documentation\n\nThe project uses `tsdoc` to generate the technical documentation from the source code.\n\n- Build the documentation\n```sh\nnpm run docs:build\n```\n\n- Run in _watch mode_ to look for file changes and update immediately\n```sh\nnpm run docs:build:watch\n```\n\n- Serve the build output statically\n```sh\nnpm run docs:serve\n```\n\n## Community\n\n- We are open to improvements in the \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/issues\"\u003eissues\u003c/a\u003e section.\n- Check the \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/wiki\"\u003ewiki\u003c/a\u003e for more context on the internal workings of this library.\n\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/inigomarquinez\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/25435858?v=4?s=100\" width=\"100px;\" alt=\"Íñigo Marquínez Prado\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eÍñigo Marquínez Prado\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=inigomarquinez\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=inigomarquinez\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/pulls?q=is%3Apr+reviewed-by%3Ainigomarquinez\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/Bounteous17\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/16175933?v=4?s=100\" width=\"100px;\" alt=\"Àlex Serra\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eÀlex Serra\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=Bounteous17\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=Bounteous17\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=Bounteous17\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/pulls?q=is%3Apr+reviewed-by%3ABounteous17\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://www.one-beyond.com\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/88377077?v=4?s=100\" width=\"100px;\" alt=\"Matyas Angyal\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eMatyas Angyal\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/pulls?q=is%3Apr+reviewed-by%3Amatyasjay\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=matyasjay\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=matyasjay\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=matyasjay\" title=\"Tests\"\u003e⚠️\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://ulisesgascon.com/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/5110813?v=4?s=100\" width=\"100px;\" alt=\"Ulises Gascón\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eUlises Gascón\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/pulls?q=is%3Apr+reviewed-by%3AUlisesGascon\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/robertoHeCi\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/58053533?v=4?s=100\" width=\"100px;\" alt=\"Roberto Hernández\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eRoberto Hernández\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=robertoHeCi\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=robertoHeCi\" title=\"Tests\"\u003e⚠️\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/commits?author=robertoHeCi\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"https://github.com/onebeyond/agnostic-cms-harmonizer/pulls?q=is%3Apr+reviewed-by%3ArobertoHeCi\" title=\"Reviewed Pull Requests\"\u003e👀\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonebeyond%2Fagnostic-cms-harmonizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonebeyond%2Fagnostic-cms-harmonizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonebeyond%2Fagnostic-cms-harmonizer/lists"}