contentful 9.1.13 → 10.0.0-beta-v10.2

package/ADVANCED.md

@@ -0,0 +1,244 @@
+<!-- shared header  START --> 
+
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/">
+    <img alt="Contentful Logo" title="Contentful" src="images/contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align='center'>Content Delivery API</h1>
+
+<h3 align="center">Advanced Concepts & Tips</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="CONTRIBUTING.md">Contributing</a>
+</p>
+
+<p align="center">
+  <a href="https://www.contentful.com/slack/">
+    <img src="https://img.shields.io/badge/-Join%20Community%20Slack-2AB27B.svg?logo=slack&maxAge=31557600" alt="Join Contentful Community Slack">
+  </a>
+</p>
+
+<!-- shared header  END --> 
+
+
+> Find helpful concepts and tips about how to use this library.
+
+- [Using ES6 import](#using-es6-import)
+- [Framework specifics](#framework-specifics)
+- [Link resolution](#link-resolution)
+  - [Note: link resolution for versions older than 10.0.0](#note:-link-resolution-for-versions-older-than-10.0.0)
+  - [Note: link resolution for versions older than 7.0.0](#note:-link-resolution-for-versions-older-than-7.0.0)
+- [Sync](#sync)
+  - [Sync without pagination](#sync-without-pagination)
+- [Querying & Search parameters](#querying--search-parameters)
+
+## Using ES6 import
+
+You can use the es6 import with the SDK as follow
+
+```js
+import { createClient } from "contentful";
+const client = createClient({...});
+```
+
+OR
+
+```js
+import * as contentful from "contentful";
+const client = contentful.createClient({...});
+```
+
+## Framework specifics
+
+### React Native & Server Side Rendering
+
+This library is able to handle Server Side Rendering and React Native. Depending on your implementation, you may need to explicitly require the `browser` or `node` variant of the library. (webpack usually is able to handle this on its own)
+
+```js
+const contentful = require("contentful");
+// will become the following to enforce the browser version
+const contentful = require("contentful/dist/contentful.browser.min.js");
+```
+
+### Angular Universal
+
+This library is able to handle Server Side Rendering with Angular Universal. To use it, you will have to provide a custom [Axios adapter](https://github.com/axios/axios/tree/master/lib/adapters), one example for Angular would be the [ngx-axios-adapter](https://github.com/patrickhousley/ngx-axios-adapter).
+
+## Link resolution
+
+In Contentful, you can create content that references other content. We call them "linked" or "referenced" entries. In contrast to a simple REST call, this library can render the content of a linked entry in place, using
+the [contentful-resolve-response](https://github.com/contentful/contentful-resolve-response) package. This enables what we call link resolution.
+
+**Example entry response without link resolution:**
+
+```
+{
+  "sys": { ... },
+  "metadata": { ... },
+  "fields": {
+    "referencedEntry": {
+      "type": "Link",
+      "linkType": "Entry",
+      "id": "<referenced-entry-id>"
+    }
+  }
+}
+```
+
+**Example entry response with link resolution:**
+
+```
+{
+  "sys": { ... },
+  "metadata": { ... },
+  "fields": {
+    "referencedEntry": {
+      "sys": { ... },
+      "metadata": { ... },
+      fields {
+        ...
+      }
+    }
+  }
+}
+```
+
+This makes parsing the response easier, and you don't need to manually extract every linked entry from the response object.
+
+The link resolution is applied to one level deep by default. If you need it to be applied deeper, you may specify the `include` parameter when fetching your entries as follows `client.getEntries( {include: <value> })`. The `include` parameter can be set to a number up to 10, which would represent a ten layers deep link resolution.
+
+**We resolve links by default**. If this behaviour is not what you want, you can use the chain modifier `withoutLinkResolution` on the Contentful client to keep the link objects instead of the inlined entries in your response object. See [Chained Clients](README.md#chained-clients)
+
+
+**Links which could not get resolved will be kept by default**. If you want to completely remove fields which could not be resolved, you can use the chain modifier `withoutUnresolvableLinks.`
+
+Please see the notes below for link resolution prior to v.10.0.0 and v.7.0.0.
+
+#### Note: link resolution for versions older than 10.0.0
+
+Please note that for versions older than 10.0.0, disabling link resolution needs to be done via [configuration options](README.md#response-configuration-options) during client creation.
+To disable it, set `resolveLinks` to `false` when creating the Contentful client. Like so:
+
+```js
+const contentful = require("contentful");
+const client = contentful.createClient({
+  accessToken: "<you-access-token>",
+  space: "<your-space-id>",
+  resolveLinks: false
+});
+```
+
+If you want to completely remove fields which could not be resolved, set `removeUnresolved` to `true` in the configuration options.
+
+
+#### Note: link resolution for versions older than 7.0.0
+
+Please note that for versions older than 7.0.0, link resolution is only possible when requesting records from the collection endpoint using `client.getEntries()` or by performing an initial sync `client.sync({initial: true})`. In case you want to request one entry and benefit from the link resolution you can use the collection end point with the following query parameter `'sys.id': '<your-entry-id>'`.
+
+**e.g.** assuming that you have a Content Type `post` that has a reference field `author`
+
+```js
+const contentful = require("contentful");
+const client = contentful.createClient({
+  accessToken: "<you-access-token>",
+  space: "<your-space-id>"
+});
+// getting a specific Post
+client
+  .getEntries({ "sys.id": "<entry-id>" })
+  .then(response => {
+    // output the author name
+    console.log(response.items[0].fields.author.fields.name);
+  })
+  .catch(err => console.log(err));
+```
+
+
+## Sync
+
+The Sync API allows you to keep a local copy of all content in a space up-to-date via delta updates, meaning only changes that occurred since last sync call.
+Whenever you perform a sync operation the endpoint will send back a `syncToken` which you can use in a subsequent sync to only retrieve data which changed since the last call.
+**e.g.**
+
+```js
+const contentful = require("contentful");
+const client = contentful.createClient({
+  accessToken: "<you-access-token>",
+  space: "<your-space-id>"
+});
+// first time you are syncing make sure to specify `initial: true`
+client
+  .sync({ initial: true })
+  .then(response => {
+    // You should save the `nextSyncToken` to use in the following sync
+    console.log(response.nextSyncToken);
+  })
+  .catch(err => console.log(err));
+```
+
+The SDK will go through all the pages for you and gives you back a response object with the full data so you don't need to handle pagination.
+
+### Sync without pagination
+
+You may use syncing without pagination if you want to handle it on your own. To do this, you have to pass `paginate: false` as option when calling sync. You manually have to take care to pass `nextPageToken` or `nextSyncToken` to your subsequent calls. The logic follows our [sync API docs](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization/pagination-and-subsequent-syncs) while you pass tokens instead of full urls.
+
+```js
+const contentful = require("contentful");
+const client = contentful.createClient({
+  accessToken: "<you-access-token>",
+  space: "<your-space-id>"
+});
+
+function customPaginatedSync(query) {
+  // Call sync, make sure you set paginate to false for every call
+  return client.sync(query, { paginate: false }).then(response => {
+    // Do something with the respond. For example save result to disk.
+    console.log("Result of current sync page:", response.items);
+
+    // Sync finished when `nextSyncToken` is available
+    if (response.nextSyncToken) {
+      console.log(
+        "Syncing done. Start a new sync via " + response.nextSyncToken
+      );
+      return;
+    }
+
+    // Otherwise, just continue to next page of the current sync run
+    return customPaginatedSync({ nextPageToken: response.nextPageToken });
+  });
+}
+
+customPaginatedSync({ initial: true }).then(() => console.log("Sync done"));
+```
+
+## Querying & Search parameters
+
+You can pass your query parameters as `key: value` pairs in the query object whenever request a resource. For example:
+
+```js
+const contentful = require("contentful");
+const client = contentful.createClient({
+  accessToken: "<you-access-token>",
+  space: "<your-space-id>"
+});
+
+// getting a specific Post
+client
+  .getEntries({ "sys.id": "<entry-id>" })
+  .then(response => {
+    // output the author name
+    console.log(response.items[0].fields.author.fields.name);
+  })
+  .catch(err => console.log(err));
+
+// You can pass a query when requesting a single entity
+client.getEntry("<entry-id>", { key: value });
+```
+
+For more information about the search parameters, check the [documentation](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters).

package/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+<!-- shared header  START --> 
+
+<p align="center">
+  <a href="https://www.contentful.com/developers/docs/references/content-delivery-api/">
+    <img alt="Contentful Logo" title="Contentful" src="images/contentful-icon.png" width="150">
+  </a>
+</p>
+
+<h1 align='center'>Content Delivery API</h1>
+
+<h3 align="center">Contributing</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="CONTRIBUTING.md">Contributing</a>
+</p>
+
+<p align="center">
+  <a href="https://www.contentful.com/slack/">
+    <img src="https://img.shields.io/badge/-Join%20Community%20Slack-2AB27B.svg?logo=slack&maxAge=31557600" alt="Join Contentful Community Slack">
+  </a>
+</p>
+
+<!-- shared header  END --> 
+
+
+<p align="center">
+  <a href="http://makeapullrequest.com">
+    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?maxAge=31557600" alt="PRs Welcome">
+  </a>
+  &nbsp;
+  <a href="http://makeapullrequest.com">
+    <img src="https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?maxAge=31557600" alt="Semantic Release">
+  </a>
+  &nbsp;
+  <a href="http://standardjs.com/">
+    <img src="https://img.shields.io/badge/code%20style-standard-brightgreen.svg?maxAge=31557600" alt="JS Standard Style">
+  </a>
+</p>
+
+We appreciate any community contributions to this project, whether in the form of issues or pull requests.
+
+This document outlines what we'd like you to follow in terms of commit messages and code style.
+
+It also explains what to do in case you want to setup the project locally and run tests.
+
+**Working on your first Pull Request?** You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
+
+## Setup
+
+This project is written in ES2015 and transpiled to ES5 using Babel, to the `dist` directory. This should generally only happen at publishing time, or for testing purposes only.
+
+Run `npm install` to install all necessary dependencies. When running `npm install` locally, `dist` is not compiled.
+
+All necessary dependencies are installed under `node_modules` and any necessary tools can be accessed via npm scripts. There is no need to install anything globally.
+
+When importing local, in develoment code, via `index.js`, this file checks if `dist` exists and uses that. Otherwise, it uses the code from `lib`.
+
+If you have a `dist` directory, run `npm run clean`.
+
+Axios, one of the main dependencies is vendored. This generally shouldn't matter, but if you'd like to understand why, check [SETUP.md](SETUP.md)
+
+## Useful npm scripts
+
+- `npm run clean` removes any built files
+- `npm run build` builds vendored files, node package and browser version
+- `npm run build:dist` builds ES5 sources from ES6 ones
+- `npm run build:standalone` builds unminified and minified sources for browsers
+
+## Running tests
+
+This project has unit and integration tests. Both of these run on both Node.js and Browser environments.
+
+Both of these test environments are setup to deal with Babel and code transpiling, so there's no need to worry about that
+
+- `npm test` runs all three kinds of tests and generates a coverage report
+- `npm run test:only` runs Node.js unit tests without coverage. `npm run test:cover` to run Node.js unit tests with coverage. `npm run test:debug` runs babel-node in debug mode (same as running `node debug`).
+- `npm run test:integration` runs the integration tests against the Contentful CDA API
+- `npm run test:browser-local` runs both the unit and integration tests using Karma against local browsers.
+- `npm run test:ci` runs tests in CI
+- `npm run test:browser-remote` runs both the unit and integration tests using Karma against Sauce Labs. This is only usable in the CI environment, as it expects the credentials and connection tunnel to be present.
+
+## Documentation
+
+Code is documented using JSDoc 3, and reference documentation is published automatically with each new version.
+
+- `npm run docs:watch` watches code directory, and rebuilds documentation when anything changes. Useful for documentation writing and development.
+- `npm run docs:dev` builds code and builds docs afterwards. Used by `npm run docs:watch`. Code building is required as the documentation is generated from the unminified ES5 compiled sources, rather than the original ES6 sources. You should then open the generated `out/contentful/index.html` in your browser.
+- `npm run docs:build` builds documentation.
+- `npm run docs:publish` builds documentation and publishes it to github pages.
+
+## Code style
+
+This project uses [standard](https://github.com/feross/standard). Install a relevant editor plugin if you'd like.
+
+Everywhere where it isn't applicable, follow a style similar to the existing code.
+
+## Commit messages and issues
+
+This project uses the [Angular JS Commit Message Conventions](https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y/edit), via semantic-release. See the semantic-release [Default Commit Message Format](https://github.com/semantic-release/semantic-release#default-commit-message-format) section for more details.
+
+## Versioning
+
+This project strictly follows [Semantic Versioning](http://semver.org/) by use of [semantic-release](https://github.com/semantic-release/semantic-release).
+
+This means that new versions are released automatically as fixes, features or breaking changes are released.
+
+You can check the changelog on the [releases](https://github.com/contentful/contentful.js/releases) page.