Skip to content

Newt-Inc/newt-client-js

Repository files navigation

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.

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.