storyblok-ts-client v4.7.0

Storyblok Management API Typescript Client

typescript library for working with Storyblok management API.

Description

• consists of:

  • a basic CRUD client "Storyblok" with throttling and failure-retry
  • a wrapper library over the CRUD client "ApiClient"
  • typescript conversion of the original storyblok-js-client - "StoryblokTS"
  • abstraction classes with limited functionalities:
    • Space
    • Component
    • Story
      • FolderIndex
      • Content
      • Folder
        • RootFolder
        • Subfolder
    • Asset
    • AssetFolder

• ApiClient methods are categorized into the following:

  • assetFolders
  • assets
  • components
  • spaces
  • stories

• API requests are throttled

• images are compressed and resized using sharp

• jest is setup for testing (not fully tested)

• the management API is not fully implemented

Installation

npm install --save storyblok-ts-client

Usage

// Basic CRUD client
const {Storyblok} = require('storyblok-ts-client')
const storyblok = new Storyblok('fake_api_token')
return storyblok.get('/12345')
  .then(res => console.log('space id:', res.data.id))
  // => space id: 12345

// Management API wrapper
const {ApiClient} = require('storyblok-ts-client')
const apiClient = new ApiClient('fake_api_token', 12345)
return apiClient.spaces.get()
  .then(space => console.log('space id:', space.id))
  // => space id: 12345

// StoryblokTS
const {StoryblokTS} = require('storyblok-ts-client')
let storyblokTS = new StoryblokTS({oauthToken: 'YOUR_OAUTH_TOKEN'})
const spaceId = 12345
storyblokTS.post(`spaces/${spaceId}/stories`, {story: {name: 'xy', slug: 'xy'}})
storyblokTS.put(`spaces/${spaceId}/stories/1`, {story: {name: 'xy', slug: 'xy'}})
storyblokTS.delete(`spaces/${spaceId}/stories/1`, null)

CLI Scripts

# development and testing
npm run dev       # runs typescript transpiler in watch mode
npm start         # runs any executable code in the index.js

# test - remember to update .env file with a test Storyblok account api token and test space id
npm run dev:test  # runs jest in watch mode
npm test          # runs jest
npm run coverage  # runs jest and check code coverage stat

# build
npm run build

# tslint
npm run lint

# prettier
npm run format

API Reference - generated with jsdoc2md

Classes

Functions

ApiClient

Kind: global class
Implements: IStoryblokClass
Export:

• ApiClient
  • new ApiClient(apiToken, spaceId)
  • .assetFolders
    • .create ⇒ Promise
    • .delete ⇒ Promise
    • .deleteExisting ⇒ Promise
    • .get ⇒ Promise
    • .getByName ⇒ Promise
    • .getExisting ⇒ Promise
  • .assets
    • .count ⇒ Promise
    • .createFromImage ⇒ Promise
    • .delete ⇒ Promise
    • .deleteExisting ⇒ Promise
    • .get ⇒ Promise
    • .getByPage ⇒ Promise.<Array.<IAsset>>
    • .getByUrl ⇒ Promise
    • .getExisting ⇒ Promise
    • .register ⇒ Promise
    • .upload ⇒ Promise
  • .components
    • .create ⇒ Promise
    • .delete ⇒ Promise
    • .deleteExisting ⇒ Promise
    • .get ⇒ Promise
    • .getExisting ⇒ Promise
    • .update ⇒ Promise
    • .create ⇒ Promise
  • .spaces
    • .get ⇒ Promise
  • .stories
    • .count ⇒ Promise
    • .countPages ⇒ Promise
    • .create ⇒ Promise
    • .delete ⇒ Promise
    • .deleteExisting ⇒ Promise
    • .get ⇒ Promise
    • .getByPage ⇒ Promise
    • .getExisting ⇒ Promise
    • .publish ⇒ Promise
    • .publishPendings ⇒ Promise
    • .reorder ⇒ Promise
    • .update ⇒ Promise
    • .publishPendings ⇒ Promise
  • .countAssets ⇒ Promise
  • .countStories ⇒ Promise
  • .countStoryPages ⇒ Promise
  • .createAssetFolder ⇒ Promise
  • .createAssetFromImage ⇒ Promise
  • .createStory ⇒ Promise
  • .deleteAsset ⇒ Promise
  • .deleteAssetFolder ⇒ Promise
  • .deleteComponent ⇒ Promise
  • .deleteStory ⇒ Promise
  • .deleteExistingAssetFolders ⇒ Promise
  • .deleteExistingAssets ⇒ Promise
  • .deleteExistingComponents ⇒ Promise
  • .deleteExistingStories ⇒ Promise
  • .getAsset ⇒ Promise
  • .getAssetByUrl ⇒ Promise
  • .getAssetFolder ⇒ Promise
  • .getAssetFolderByName ⇒ Promise
  • .getComponent ⇒ Promise
  • .getExistingAssets ⇒ Promise
  • .getExistingComponents ⇒ Promise
  • .getExistingAssetFolders ⇒ Promise
  • .getExistingStories ⇒ Promise
  • .getSpace ⇒ Promise
  • .getStoriesByPage ⇒ Promise
  • .publishStory ⇒ Promise
  • .registerAsset ⇒ Promise
  • .reorderStory ⇒ Promise
  • .updateComponent ⇒ Promise
  • .updateStory ⇒ Promise
  • .uploadAsset ⇒ Promise
  • .getAssetsByPage([page], [perPage]) ⇒ Promise.<Array.<IAsset>>

new ApiClient(apiToken, spaceId)

Example

const {ApiClient} = require('storyblok-ts-client')
const apiClient = new ApiClient('fake_api_token', 12345)

apiClient.assetFolders

Kind: instance property of ApiClient
Read only: true

• .assetFolders
  • .create ⇒ Promise
  • .delete ⇒ Promise
  • .deleteExisting ⇒ Promise
  • .get ⇒ Promise
  • .getByName ⇒ Promise
  • .getExisting ⇒ Promise

assetFolders.create ⇒ Promise

Kind: instance property of assetFolders
Fulfil: IAssetFolder Details of the asset folder created.
Reject: AxiosError Axios error.

assetFolders.delete ⇒ Promise

Kind: instance property of assetFolders
Fulfil: void
Reject: AxiosError Axios error.

assetFolders.deleteExisting ⇒ Promise

Kind: instance property of assetFolders
Fulfil: void[]
Reject: AxiosError Axios error.

assetFolders.get ⇒ Promise

Kind: instance property of assetFolders
Fulfil: IAssetFolder Asset folder information.
Reject: AxiosError Axios error.

assetFolders.getByName ⇒ Promise

Kind: instance property of assetFolders
Fulfil: IAssetFolder[] List of matched asset folders.
Reject: AxiosError Axios error.

assetFolders.getExisting ⇒ Promise

Kind: instance property of assetFolders
Fulfil: IAssetFolder[] List of existing asset folders.
Reject: AxiosError Axios error.

apiClient.assets

Kind: instance property of ApiClient
Read only: true

• .assets
  • .count ⇒ Promise
  • .createFromImage ⇒ Promise
  • .delete ⇒ Promise
  • .deleteExisting ⇒ Promise
  • .get ⇒ Promise
  • .getByPage ⇒ Promise.<Array.<IAsset>>
  • .getByUrl ⇒ Promise
  • .getExisting ⇒ Promise
  • .register ⇒ Promise
  • .upload ⇒ Promise

assets.count ⇒ Promise

Kind: instance property of assets
Fulfil: number A count of existing assets.
Reject: AxiosError Axios error.

assets.createFromImage ⇒ Promise

Kind: instance property of assets
Fulfil: string public access url of the new asset.
Reject: AxiosError Axios error.

assets.delete ⇒ Promise

Kind: instance property of assets
Fulfil: IAsset Information of the deleted asset.
Reject: AxiosError Axios error.

assets.deleteExisting ⇒ Promise

Kind: instance property of assets
Fulfil: IAsset[] Information on the deleted assets.
Reject: AxiosError Axios error.

assets.get ⇒ Promise

Kind: instance property of assets
Fulfil: IAsset Details of the asset.
Reject: AxiosError Axios error.

assets.getByPage ⇒ Promise.<Array.<IAsset>>

Kind: instance property of assets
Fulfil: IAsset[] Assets on the pagination page.
Reject: AxiosError Axios error.

assets.getByUrl ⇒ Promise

Kind: instance property of assets
Fulfil: IAsset Matched asset.
Reject: AxiosError Axios error.

assets.getExisting ⇒ Promise

Kind: instance property of assets
Fulfil: IAsset[] A list of existing assets.
Reject: AxiosError Axios error.

assets.register ⇒ Promise

Kind: instance property of assets
Fulfil: IRegistration Asset registration info (used for uploading).
Reject: AxiosError Axios error.

assets.upload ⇒ Promise

Kind: instance property of assets
Fulfil: string Access url of the uploaded asset.
Reject: AxiosError Axios error.

apiClient.components

Kind: instance property of ApiClient
Read only: true

• .components
  • .create ⇒ Promise
  • .delete ⇒ Promise
  • .deleteExisting ⇒ Promise
  • .get ⇒ Promise
  • .getExisting ⇒ Promise
  • .update ⇒ Promise
  • .create ⇒ Promise

components.create ⇒ Promise

Kind: instance property of components
Fulfil: IComponent Details of the component that was created.
Reject: AxiosError Axios error.

components.delete ⇒ Promise

Kind: instance property of components
Fulfil: IComponent Details of the deleted component.
Reject: AxiosError Axios error.

components.deleteExisting ⇒ Promise

Kind: instance property of components
Fulfil: IComponent[] A list of deleted components details.
Reject: AxiosError Axios error.

components.get ⇒ Promise

Kind: instance property of components
Fulfil: IComponent Details of the component definition.
Reject: AxiosError Axios error.

components.getExisting ⇒ Promise

Kind: instance property of components
Fulfil: IComponent[] A list of component definitions.
Reject: AxiosError Axios error.

components.update ⇒ Promise

Kind: instance property of components
Fulfil: IComponent Details of component that was updated.
Reject: AxiosError Axios error.

components.create ⇒ Promise

Kind: instance property of components
Fulfil: IComponent Details of the component that was created.
Reject: AxiosError Axios error.

apiClient.spaces

Kind: instance property of ApiClient
Read only: true

spaces.get ⇒ Promise

Kind: instance property of spaces
Fulfil: ISpace Working space information.
Reject: AxiosError Axios error.

apiClient.stories

Kind: instance property of ApiClient
Read only: true

• .stories
  • .count ⇒ Promise
  • .countPages ⇒ Promise
  • .create ⇒ Promise
  • .delete ⇒ Promise
  • .deleteExisting ⇒ Promise
  • .get ⇒ Promise
  • .getByPage ⇒ Promise
  • .getExisting ⇒ Promise
  • .publish ⇒ Promise
  • .publishPendings ⇒ Promise
  • .reorder ⇒ Promise
  • .update ⇒ Promise
  • .publishPendings ⇒ Promise

stories.count ⇒ Promise

Kind: instance property of stories
Fulfil: number A count of existing stories.
Reject: AxiosError Axios error.

stories.countPages ⇒ Promise

Kind: instance property of stories
Fulfil: number Total story pagination page count.
Reject: AxiosError Axios error.

stories.create ⇒ Promise

Kind: instance property of stories
Fulfil: IStory Details of story that was created.
Reject: AxiosError Axios error.

stories.delete ⇒ Promise

Kind: instance property of stories
Fulfil: IStory Details of the story that was deleted.
Reject: AxiosError Axios error.

stories.deleteExisting ⇒ Promise

Kind: instance property of stories
Fulfil: IStory[] A list of deleted stories details.
Reject: AxiosError Axios error.

stories.get ⇒ Promise

Kind: instance property of stories
Fulfil: IStory Details of content story.
Reject: AxiosError Axios error.

stories.getByPage ⇒ Promise

Kind: instance property of stories
Fulfil: IStory[] A page of stories.
Reject: AxiosError Axios error.

stories.getExisting ⇒ Promise

Kind: instance property of stories
Fulfil: IStory[] A list of existing content stories.
Reject: AxiosError Axios error.

stories.publish ⇒ Promise

Kind: instance property of stories
Fulfil: IStory Details of the published story
Reject: AxiosError Axios error.

stories.publishPendings ⇒ Promise

Kind: instance property of stories
Fulfil: IStory[] List of published stories.
Reject: AxiosError Axios error.

stories.reorder ⇒ Promise

Kind: instance property of stories
Fulfil: IStory Details of the moved story.
Reject: AxiosError Axios error.

stories.update ⇒ Promise

Kind: instance property of stories
Fulfil: IStory Details of story that was updated.
Reject: AxiosError Axios error.

stories.publishPendings ⇒ Promise

Kind: instance property of stories
Fulfil: IStory[] List of published stories.
Reject: AxiosError Axios error.

apiClient.countAssets ⇒ Promise

Kind: instance property of ApiClient
Fulfil: number A count of existing assets.
Reject: AxiosError Axios error.

apiClient.countStories ⇒ Promise

Kind: instance property of ApiClient
Fulfil: number A count of existing stories.
Reject: AxiosError Axios error.

apiClient.countStoryPages ⇒ Promise

Kind: instance property of ApiClient
Fulfil: number Total story pagination page count.
Reject: AxiosError Axios error.

apiClient.createAssetFolder ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAssetFolder Details of the asset folder created.
Reject: AxiosError Axios error.

apiClient.createAssetFromImage ⇒ Promise

Kind: instance property of ApiClient
Fulfil: string Public access url of the new asset.
Reject: AxiosError Axios error.

apiClient.createStory ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory Details of story that was created.
Reject: AxiosError Axios error.

apiClient.deleteAsset ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAsset Information of the deleted asset.
Reject: AxiosError Axios error.

apiClient.deleteAssetFolder ⇒ Promise

Kind: instance property of ApiClient
Fulfil: void
Reject: AxiosError Axios error.

apiClient.deleteComponent ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IComponent Details of the deleted component.
Reject: AxiosError Axios error.

apiClient.deleteStory ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory Details of the story that was deleted.
Reject: AxiosError Axios error.

apiClient.deleteExistingAssetFolders ⇒ Promise

Kind: instance property of ApiClient
Fulfil: void[]
Reject: AxiosError Axios error.

apiClient.deleteExistingAssets ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAsset[] Information on the deleted assets.
Reject: AxiosError Axios error.

apiClient.deleteExistingComponents ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IComponent[] A list of deleted components details.
Reject: AxiosError Axios error.

apiClient.deleteExistingStories ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory[] A list of deleted stories details.
Reject: AxiosError Axios error.

apiClient.getAsset ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAsset Details of the asset.
Reject: AxiosError Axios error.

apiClient.getAssetByUrl ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAsset Matched asset.
Reject: AxiosError Axios error.

apiClient.getAssetFolder ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAssetFolder Asset folder information.
Reject: AxiosError Axios error.

apiClient.getAssetFolderByName ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAssetFolder[] List of matched asset folders.
Reject: AxiosError Axios error.

apiClient.getComponent ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IComponent Details of the component definition.
Reject: AxiosError Axios error.

apiClient.getExistingAssets ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAsset[] A list of existing assets.
Reject: AxiosError Axios error.

apiClient.getExistingComponents ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IComponent[] A list of component definitions.
Reject: AxiosError Axios error.

apiClient.getExistingAssetFolders ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IAssetFolder[] List of existing asset folders.
Reject: AxiosError Axios error.

apiClient.getExistingStories ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory[] A list of existing content stories.
Reject: AxiosError Axios error.

apiClient.getSpace ⇒ Promise

Kind: instance property of ApiClient
Fulfil: ISpace Working space information.
Reject: AxiosError Axios error.

apiClient.getStoriesByPage ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory[] A page of stories.
Reject: AxiosError Axios error.

apiClient.publishStory ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory Details of the published story
Reject: AxiosError Axios error.

apiClient.registerAsset ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IRegistration Asset registration info (used for uploading).
Reject: AxiosError Axios error.

apiClient.reorderStory ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory Details of the moved story.
Reject: AxiosError Axios error.

apiClient.updateComponent ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IComponent Details of component that was updated.
Reject: AxiosError Axios error.

apiClient.updateStory ⇒ Promise

Kind: instance property of ApiClient
Fulfil: IStory Details of story that was updated.
Reject: AxiosError Axios error.

apiClient.uploadAsset ⇒ Promise

Kind: instance property of ApiClient
Fulfil: string Access url of the uploaded asset.
Reject: AxiosError Axios error.

apiClient.getAssetsByPage(page, perPage) ⇒ Promise.<Array.<IAsset>>

Kind: instance method of ApiClient
Fulfil: IAsset[] Assets on the pagination page.
Reject: AxiosError Axios error.

Storyblok

Kind: global class
Implements: IStoryblokClass
Export:

• Storyblok
  • new Storyblok(apiToken)
  • .delete ⇒ Promise.<any>
  • .get ⇒ Promise.<any>
  • .post ⇒ Promise.<any>
  • .put ⇒ Promise.<any>

new Storyblok(apiToken)

Example

const {Storyblok} = require('storyblok-ts-client')
const storyblok = new Storyblok('fake_api_token')

storyblok.delete ⇒ Promise.<any>

Kind: instance property of Storyblok

Example

const {Storyblok} = require('storyblok-ts-client')
const storyblok = new Storyblok('fake_api_token')
const spaceId = 12345
const storyId = 123456
const url = `/${spaceId}/stories/${storyId}`
storyblok.delete(url, {retries: 3, retryDelay: 1000})
  .then(res => console.log('deleted story id:', res.story.id))
// => deleted story id: 123456

storyblok.get ⇒ Promise.<any>

Kind: instance property of Storyblok

Example

const {Storyblok} = require('storyblok-ts-client')
const storyblok = new Storyblok('fake_api_token')
const spaceId = 12345
const url = `/${spaceId}`
storyblok.get(url, {retries: 3, retryDelay: 1000})
  .then(res => console.log('space id:', res.space.id))
// => space id: 12345

storyblok.post ⇒ Promise.<any>

Kind: instance property of Storyblok

Example

const {Storyblok} = require('storyblok-ts-client')
const storyblok = new Storyblok('fake_api_token')
const spaceId = 12345
const url = `/${spaceId}/stories`
const story = {
  name: 'test',
  slug: 'test',
}
storyblok.post(url, {story}, {retries: 3, retryDelay: 1000})
  .then(res => console.log('new story id:', res.story.id))
// => new story id: 123456

storyblok.put ⇒ Promise.<any>

Kind: instance property of Storyblok

Example

const {Storyblok} = require('storyblok-ts-client')
const storyblok = new Storyblok('fake_api_token')
const spaceId = 12345
const url = `/${spaceId}/stories`
const story = {name: 'test', slug: 'test'}
storyblok.post(url, {story}, {retries: 3, retryDelay: 1000})
  .then(res => {
    const newStoryId = res.story.id
    console.log('new story id:', newStoryId)
    console.log('new story name:', res.story.name)
    const updateContent = {name: 'new test', slug: 'test'}
    return storyblok.put(
      url + `/${newStoryId}`,
      {story: updateContent},
      {retries: 3, retryDelay: 1000}
    )
  })
  .then(res => console.log('updated story name:', res.story.name))
  .catch(e => console.log(e.config))
// => new story id: 123456
// => new story name: test
// => updated story name: new test

StoryblokTS

Kind: global class
Export:

new StoryblokTS(config, rateLimit, endpoint)

Example

// Example for using the content delivery api
// 1. Require the Storyblok client
const {StoryblokTS} = require('storyblok-ts-client')
// 2. Initialize the client with the preview
//    token from your space dashboard at
//    https://app.storyblok.com
let Storyblok = new StoryblokClient({
  accessToken: 'your_access_token'
})

// Example for using the content management api
// 1. Require the Storyblok client
const {StoryblokTS} = require('storyblok-ts-client')
const spaceId = 12345
// 2. Initialize the client with the oauth token
//    from the my account area at
//    https://app.storyblok.com
let Storyblok = new StoryblokClient({
  oauthToken: 'YOUR_OAUTH_TOKEN'
})
Storyblok.post(`spaces/${spaceId}/stories`, {story: {name: 'xy', slug: 'xy'}})
Storyblok.put(`spaces/${spaceId}/stories/1`, {story: {name: 'xy', slug: 'xy'}})
Storyblok.delete(`spaces/${spaceId}/stories/1`, null)

imageToBuffer(filePath, compress, sizeLimit, forceFormat) ⇒ Promise

Kind: global function
Fulfil: Buffer Buffered image data.
Reject: Error Error value.

resizeImage(image, sizeLimit) ⇒ Promise

Kind: global function
Fulfil: Sharp Resized sharp object.
Reject: Error Error value.

© 2018 juniorCitizen