{"id":14991061,"url":"https://github.com/nascentdigital/contentfully","last_synced_at":"2026-03-05T16:04:19.557Z","repository":{"id":33086336,"uuid":"144057772","full_name":"nascentdigital/contentfully","owner":"nascentdigital","description":"A simple but performant REST client for Contentful.","archived":false,"fork":false,"pushed_at":"2025-09-30T21:11:23.000Z","size":1103,"stargazers_count":18,"open_issues_count":12,"forks_count":7,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-10-18T22:39:26.019Z","etag":null,"topics":["contentful","fast","javascript","library","linking","nodejs","react-native","simple","typescript"],"latest_commit_sha":null,"homepage":null,"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/nascentdigital.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2018-08-08T19:17:52.000Z","updated_at":"2025-03-11T15:12:23.000Z","dependencies_parsed_at":"2024-05-02T15:58:07.736Z","dependency_job_id":"75789977-122f-441d-95e8-33517c48b2b1","html_url":"https://github.com/nascentdigital/contentfully","commit_stats":{"total_commits":114,"total_committers":10,"mean_commits":11.4,"dds":"0.42105263157894735","last_synced_commit":"ecbf62ef0d2ef9ce2caa52de8c5444545ab34bb6"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/nascentdigital/contentfully","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nascentdigital%2Fcontentfully","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nascentdigital%2Fcontentfully/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nascentdigital%2Fcontentfully/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nascentdigital%2Fcontentfully/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nascentdigital","download_url":"https://codeload.github.com/nascentdigital/contentfully/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nascentdigital%2Fcontentfully/sbom","scorecard":{"id":674825,"data":{"date":"2025-08-11","repo":{"name":"github.com/nascentdigital/contentfully","commit":"c433b0aa184485a3e8dfa5ef8acac21a91837b4d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.2,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":1,"reason":"Found 4/26 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 9 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-968p-4wvh-cqc8","Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw","Warn: Project is vulnerable to: GHSA-fjxv-7rqg-78g4"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-21T21:09:05.473Z","repository_id":33086336,"created_at":"2025-08-21T21:09:05.474Z","updated_at":"2025-08-21T21:09:05.474Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30134588,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T15:35:27.018Z","status":"ssl_error","status_checked_at":"2026-03-05T15:35:23.768Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["contentful","fast","javascript","library","linking","nodejs","react-native","simple","typescript"],"created_at":"2024-09-24T14:21:24.062Z","updated_at":"2026-03-05T16:04:19.545Z","avatar_url":"https://github.com/nascentdigital.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contentfully\n\u003e A simple but fast API client for Contentful that lets developers focus on data instead of Contentful metadata and REST structure.\n\n[![NPM version](https://img.shields.io/npm/v/contentfully.svg)](https://www.npmjs.com/package/contentfully)\n[![downloads](https://img.shields.io/npm/dm/contentfully.svg)](http://npm-stat.com/charts.html?package=contentfully\u0026from=2018-01-01)\n[![Node version](https://img.shields.io/node/v/contentfully.svg)](http://nodejs.org/download/)\n[![Build Status](https://travis-ci.com/nascentdigital/contentfully.svg?branch=master)](https://travis-ci.com/nascentdigital/contentfully.svg?branch=master)\n[![Code Coverage](https://img.shields.io/codecov/c/github/nascentdigital/contentfully.svg)](https://codecov.io/github/nascentdigital/contentfully)\n[![Known Vulnerabilities](https://snyk.io/test/github/nascentdigital/contentfully/badge.svg)](https://snyk.io/test/github/nascentdigital/contentfully)\n\n\n## Table of Contents\n1. [Features](#features)\n2. [Installation](#installation)\n3. [Prerequisites](#prerequisites)\n4. [Basic Usage](#basic-usage)\n5. [Migration Guide](#migration-guide)\n\n\n## Features\n- Transforms Contentful responses into simple / flat JavaScript objects.\n- Stripping of metadata, retaining the basics that you need (e.g. ID, contentType, and fields).\n- Recursive folding of linked entries and assets without cloning (i.e. an Entry\n  / Asset that is reference multiple times is only created once).\n- Supports custom transforms of assets URLs to allow caching or rewrites.\n- Supports full [Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters),\n  including custom environments and preview servers.\n- Typescript 5 support.\n- React Native support.\n\n\n## Installation\n\nCurrent stable release (`4.x`)\n\n```sh\n$ npm i -s contentfully\n```\n\n\n## Prerequisites\n\nYou'll need the **Space ID** and **API key** for the space that you wish to access.\nYou can get these by doing the following after logging into the\n[Contentful Web App](https://be.contentful.com/login):\n\n1. Navigate to your *Organization / Space* (usually from the upper-left space\n   selector in the top toolbar).\n2. Select *Settings \u0026rarr; General Settings* to find your `Space ID`.\n3. Select *Settings \u0026rarr; API keys* to see your generated API keys (you will\n   need to have the correct permissions on the space to do this).  Create a new\n   `API key` if you need to.\n\n\n## Basic Usage\n\nContentfully takes the same parameters as the Contentful client ([`CreateClientParams`](https://github.com/contentful/contentful.js/blob/a39c783e9db0b725d2109d5016b9e33ac01a2312/lib/contentful.ts#L23)). The following are the most used parameters:\n\n| Option             | Type     | Required? | Default            |\n|--------------------|----------|-----------|--------------------|\n| accessToken        | string   | YES       |                    |\n| space              | string   | YES       |                    |\n| environment        | string   | NO        | master             |\n| host               | string   | NO        | cdn.contentful.com |\n\nCreate an instance of `Contentfully`:\n\n```typescript\nimport {Contentfully} from 'contentfully'\n\n// create a Contentfully instance\nconst contentfully = new Contentfully({\n  accessToken: 'YOUR_API_KEY',\n  space: 'YOUR_SPACE_ID'\n})\n```\n\nNext, we can now query Contentful using Contenfully's `getEntries()` method.\nThe first argument to `getEntries()` is a query object that takes the same query\nparameters as a direct [Content Delivery API](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters)\ncall.\n\n```typescript\n// get the 3rd page of my model objects\n// can also pass in optional type for the models getting fetched\nconst data = await contentfully.getEntries\u003cMyModel\u003e({\n    content_type: 'myModel',\n    skip: 20,\n    limit: 10\n})\n\n// print the result\nconsole.log(data)\n```\n\nContentfully will execute the query, recursively linking any assets or embedded\ncontent models, returning a basic JavaScript object without the Contentful\nmetadata that you don't need.\n\nIt should look something like this:\n\n```javascript\n{\n    total: 10,\n    skip: 20,\n    limit: 10,\n    items: [\n        {\n            _id: \"5nZHNlP6zCESgGuMGKG2Q8\",\n            _type: \"myModel\",\n            field1: \"value1\",\n            field2: \"value2\",\n            field3: false,\n            field5: {\n                _id: \"m972ick1jqhi\",\n                _type: \"myModelDependency\",\n                field1: \"foo\",\n                field2: \"bar\",\n                field3: true,\n            },\n            field6: [\n                1, 4, 10, 20\n            ]\n        },\n        ...\n    ]\n}\n\n```\n\n### Localization\nJust as with the Content Delivery API, you can query entries to retrieve a single locale or all localized versions of an entry.\n\n```typescript\n// single entry with specific locale\nconst modelWithAllLocales = await contentfully.getEntry('myModel_id', {locale: 'en-US'})\n\n// mutliple entries with specific locale\nconst modelsWithAllLocales = await contentfully.getEntries({\n    content_type: 'myModel',\n    skip: 20,\n    limit: 10,\n    locale: 'en-US'\n})\n\n// single entry with all locales\nconst modelWithAllLocales = await contentfully.getEntry('myModel_id', {allLocales: true})\n\n// mutliple entries with all locales\nconst modelsWithAllLocales = await contentfully.getEntries({\n    content_type: 'myModel',\n    skip: 20,\n    limit: 10\n}, {allLocales: true})\n```\n\nBy default locales will be lifted to top level objects so each locale can be used holistically. Please refer to the example response below. The default locale from the space will be used to for values not defined in any locale. Fallback locales are implemented for lifted responses following Contentful's \"Considerations on fallback locales\" documentation. Flattening can be disabled for a query by passing the `{flatten: false}`\n\n```typescript\n// disable locale flattening for single entry\nawait contentfully.getEntry('myModel_id', {allLocales: true, flatten: false})\n\n// disable locale flattening for multiple locales\nawait contentfully.getEntries({query}, {allLocales: true, flatten: false})\n```\n\nExample output with (from `getEntries`) flattened locales:\n```javascript\n{\n    total: 10,\n    skip: 20,\n    limit: 10,\n    items: {\n      \"en-CA\": [\n        {\n          _id: \"5nZHNlP6zCESgGuMGKG2Q8\",\n          _type: \"myModel\",\n          field1: \"Hello\",\n          field2: \"\",\n          field3: \"foo\",\n          field4: true,\n          field5: {\n              _id: \"m972ick1jqhi\",\n              _type: \"myModelDependency\",\n              field1: \"foo\",\n              field2: \"bar\",\n              field3: true\n          },\n          field6: [1, 4, 10, 20],\n          image: {\n            _id: \"m12mkd123fdr4\",\n            url: \"foo.png\",\n            title: \"title\",\n            dimensions: {\n              width: 1,\n              height: 1\n            },\n            size: 44335\n          }\n        }\n      ],\n      \"fr-CA\": [\n        {\n          _id: \"5nZHNlP6zCESgGuMGKG2Q8\",\n          _type: \"myModel\",\n          field1: \"Bonjour\",\n          field2: \"Comment vas-tu\",\n          field3: \"foo\",\n          field3: false,\n          field5: {\n              _id: \"m972ick1jqhi\",\n              _type: \"myModelDependency\",\n              field1: \"foo\",\n              field2: \"bar\",\n              field3: true\n          },\n          field6: [2, 8, 20, 40],\n          image: {\n            _id: \"m12mkd123fdr4\",\n            url: \"bar.jpg\",\n            title: \"french title\",\n            dimensions: {\n              width: 2,\n              height: 2\n            },\n            size: 123124\n          }\n        }\n      ]\n    }\n}\n```\n\n## Migration Guide\n\nThis guide goes over migrating from `v2.x` to `v3.x`.\n\n### Initializing\n\nInitializing Contentfully in `v2.x` was:\n```typescript\n// create the contentful client\nconst contentfulClient = new ContentfulClient({\n\n  // credentials for the space\n  accessToken: \"YOUR_API_KEY\",\n  spaceId:     \"YOUR_SPACE_ID\",\n\n  // setup a handler to auto-retry when a rate-limit error occurs\n  onRateLimitError: ExponentialBackoffHandler.create()\n});\n\n// create a Contentfully instance\nconst contentfully = new Contentfully(contentfulClient);\n```\n\nIn `v3.x` settings are passed directly\n\n\u003e [!NOTE]\n\u003e Also note that keys no longer have `Id`. For example `spaceId` is now `space`.\n\n```typescript\n// Contentful settings passed directly into contentfully\nconst contentfully = new Contentfully({\n  accessToken: \"YOUR_API_KEY\",\n  space: \"YOUR_SPACE_ID\"\n})\n```\n\n`onRateLimitError` is no longer supported however by default, on error, the request is tried again up to 5 times. This behaviour can be changed by passing in options `retryOnError` and `retryLimit`.\n\nIn `v3.x` experimental behaviour is now the default behaviour.\n\n### Localization\n\nGet single locale for entry:\n```typescript\n// v2.x\nconst model = await contentfully.getEntry('myModel_id', 'en-US')\n\n// v3.x\nconst model = await contentfully.getEntry('myModel_id', {locale: 'en-US'})\n```\n\nGet all locales for entry:\n```typescript\n// v2.x\nconst model = await contentfully.getEntry('myModel_id', '*')\n\n// v3.x\nconst model = await contentfully.getEntry('myModel_id', {allLocales: true})\n```\n\nGet all locales for entries:\n```typescript\n// v2.x\nconst model = await contentfully.getEntries({locale: '*'})\n\n// v3.x\nconst model = await contentfully.getEntries({query}, {allLocales: true})\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnascentdigital%2Fcontentfully","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnascentdigital%2Fcontentfully","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnascentdigital%2Fcontentfully/lists"}