newt-client-js

JavaScript SDK for Newt's API

JavaScript client for Newt. Works in Node.js and modern browsers.

Supported browsers and Node.js versions

• Chrome (>= 90)
• Firefox (>= 90)
• Edge (>= 90)
• Safari (>= 13)
• Node.js (>= 14)

Other browsers should also work, but Newt Client requires ES6 Promise.

Getting Started

Installation

Install the package with:

npm install newt-client-js

# or

yarn add newt-client-js

Using it directly in the browser:

<script src="https://cdn.jsdelivr.net/npm/newt-client-js@latest/dist/umd/newtClient.js"></script>

Your first request

The following code snippet is the most basic one you can use to get some content from Newt with this library:

const { createClient } = require('newt-client-js');
const client = createClient({
  spaceUid: 'YOUR_SPACE_UID',
  token: 'YOUR_CDN_API_TOKEN',
  apiType: 'cdn' // You can specify "cdn" or "api".
});

client
  .getContent({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    contentId: 'YOUR_CONTENT_ID'
  })
  .then((content) => console.log(content))
  .catch((err) => console.log(err));

Documentation & References

Please refer to the following documents.

• ガイド: SDK
• ガイド: 利用可能なクエリ
• チュートリアル: NewtのAPIで利用できるクエリパラメータを理解して、様々なクエリを実行する
• REST API reference

Configuration

The createClient method supports several options you may set to achieve the expected behavior:

Options

Name	Default	Description
spaceUid		Required. Your space uid.
token		Required. Your Newt CDN API token or Newt API token.
apiType	cdn	You can specify cdn or api. Please specify cdn to send a request to the Newt CDN API, or api to send a request to the Newt API.
adapter	undefined	Custom adapter to handle making the requests. Find further information in the axios request config documentation. https://github.com/mzabriskie/axios#request-config
retryOnError	true	By default, this client will retry if the response status is 429 too many requests or 500 server error. To turn off this behavior, set this to false.
retryLimit	3	The number of times to retry before failure. Please specify a value less than or equal to 10.
fetch	undefined	You can specify a custom fetch function for the HTTP request like globalThis.fetch or node-fetch. Note that if you use the fetch option, the adapter option will be ignored and no retry will be performed.

You can choose to use axios or fetch for your request, whichever you prefer.

If you do not specify the fetch option, the request will be made with axios, in which case the values specified for the options adapter, retryOnError, and retryLimit will be taken into account.

If you set a value for the fetch option, the request will be made using fetch instead of axios. Note that in that case, the adapter option will not be taken into account and retries will not be performed.

Get contents

client
  .getContents({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    query: {
      '_sys.createdAt': { gt: '2021-09-01' },
      category: 'news'
    }
  })
  .then((contents) => console.log(contents))
  .catch((err) => console.log(err));

client
  .getContents({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    query: {
      or: [
        { title: { match: 'update' } },
        { title: { match: 'アップデート' } }
      ],
      body: { fmt: 'text' },
      limit: 10
    }
  })
  .then((contents) => console.log(contents))
  .catch((err) => console.log(err));

Get a content

client
  .getContent({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    contentId: 'YOUR_CONTENT_ID'
  })
  .then((content) => console.log(content))
  .catch((err) => console.log(err));

client
  .getContent({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    contentId: 'YOUR_CONTENT_ID',
    query: { select: ['title', 'body'] }
  })
  .then((content) => console.log(content))
  .catch((err) => console.log(err));

Get first content

The getFirstContent method will return the first content that matches the condition specified in query. You can set the parameters available for getContents except for limit.

client
  .getFirstContent({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    query: {
      slug: 'hello-world'
    }
  })
  .then((content) => console.log(content))
  .catch((err) => console.log(err));

Get an app

client
  .getApp({
    appUid: 'YOUR_APP_UID'
  })
  .then((app) => console.log(app))
  .catch((err) => console.log(err));

Usage with TypeScript

Type definition

By using the type Content, you can easily define the type.

// Suppose you have defined a model named Post in the admin page.

// Type definition
/**
 * Content type
 *
 * {
 *   _id: string;
 *   _sys: {
 *     createdAt: string;
 *     updatedAt: string;
 *     customOrder: number;
 *     raw: {
 *       createdAt: string;
 *       updatedAt: string;
 *       firstPublishedAt: string;
 *       publishedAt: string;
 *     };
 *   };
 * }
 */
const { Content } = require('newt-client-js');
interface Post extends Content {
  title: string
  body: string
}

Request and Response

The type of the content you want to get can be passed as a parameter.

/**
 * getContents response type
 *
 * {
 *   skip: number;
 *   limit: number;
 *   total: number;
 *   items: Array<Post>; // an array of content defined by you
 * }
 */
client.getContents<Post>({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
  })
  .then((posts) => console.log(posts))
  .catch((err) => console.log(err));

/**
 * getContent response type
 *
 * {
 *   _id: string;
 *   _sys: {
 *     createdAt: string;
 *     updatedAt: string;
 *     customOrder: number;
 *     raw: {
 *       createdAt: string;
 *       updatedAt: string;
 *       firstPublishedAt: string;
 *       publishedAt: string;
 *     };
 *   };
 *   title: string; // field defined by you
 *   body: string; // field defined by you
 * }
 */
client
  .getContent<Post>({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
    contentId: 'YOUR_CONTENT_ID'
  })
  .then((post) => console.log(post))
  .catch((err) => console.log(err));

/**
 * getFirstContent response type
 *
 * {
 *   _id: string;
 *   _sys: {
 *     createdAt: string;
 *     updatedAt: string;
 *     customOrder: number;
 *     raw: {
 *       createdAt: string;
 *       updatedAt: string;
 *       firstPublishedAt: string;
 *       publishedAt: string;
 *     };
 *   };
 *   title: string; // field defined by you
 *   body: string; // field defined by you
 * }
 */
client
  .getFirstContent<Post>({
    appUid: 'YOUR_APP_UID',
    modelUid: 'YOUR_MODEL_UID',
  })
  .then((post) => console.log(post))
  .catch((err) => console.log(err));

Query Fields

All fields are optional.

Field	Type	Description
YOUR_FIELD	-	You can define a query for a field that you define
select	string[]
order	string[]
limit	number
skip	number
depth	number
or	Array	Connects each element in the array as an "or" condition.
and	Array	Connects each element in the array as an "and" condition.

Query Operators

Operator	Type
ne	string / number / boolean
match	string
in	string[] / number[]
nin	string[] / number[]
all	string[] / number[]
exists	boolean
lt	string / number
lte	string / number
gt	string / number
gte	string / number
fmt	'text'

License

This repository is published under the MIT License.