Javascript SDK

The Caasy Javascript SDK is a simple and lightweight (<10kb) wrapper for the public Caasy API. It helps you fetching all your public content such as blog posts and pages. The SDK is continuously evolving. Make sure to check this site regularly for updates and changes.

Install

Install the SDK with npm i --save @caasy/sdk-js and import it with the import or require keyword. The SDK works in the browser as well as in NodeJS. You can use it with all frameworks and libraries such as NextJS and Gatsby.

const caasy = require('@caasy/sdk-js');
// or
import caasy from '@caasy/sdk-js';

Configuration

Before you use the SDK, it needs to be initialized with the init method. All you need to provide is the site ID, which you can find in the overview of all the sites you have access to. You only need to call the init function once in your app. We recommend doing it at the top of your entire app.

caasy.init({ siteId: '<site ID>' });

Internationalization

Certain data of elements are multi-language content and is therefore structured as an object with the language codes as property.

Example:

description: {
en_US: "Some english text"
}

Blog Posts

The SDK exposes several methods to fetch public blog posts conveniently.

Get All

To fetch all published blog posts, use the getAll function. The response is paginated, starting on page 1. You can pass the desired page as a number to the function. Keep in mind that this function only fetches the basic data of a blog post and no details such as its elements.

const allPosts = await caasy.posts.getAll(1);

Example Response:

{
totalItems: 1,
items: 1,
page: 1,
itemsPerPage: 25,
data: [
{
id: '5f11a482b37775863c3243a8',
title: [Object],
description: [Object],
authorId: '5f05b66d985d5565e1826921',
author: [Object],
siteId: '5f05b799985d5565e1826922',
previewImageName: '5f05b799985d5565e1826922-484EEEA10A-image.jpg',
previewImageUrls: [Object],
updatedById: '5f05b66d985d5565e1826921',
updatedBy: [Object],
isPublished: true,
updatedAt: '2020-07-20T16:03:52.334Z',
createdAt: '2020-07-17T13:15:46.248Z'
}
]
}

Get one by ID

If you want to fetch a single blog post with all its elements, use the getById function.

const post = await caasy.posts.getById('5f11a482b37775863c3243a8');

Example Response:

{
id: '5f11a482b37775863c3243a8',
title: { en_US: 'My second blog post' },
description: {
en_US: "Some description"
},
authorId: '5f05b66d985d5565e1826921',
author: {
id: '5f05b66d985d5565e1826921',
firstName: 'Caasy',
lastName: 'Admin'
},
siteId: '5f05b799985d5565e1826922',
elements: [
{
customId: '',
id: '1594210663665-t4dtb',
subtitle: [Object],
title: [Object],
type: 'headline'
},
{
customId: '',
id: '1595254341146-vm1ni',
text: [Object],
type: 'markdown'
}
],
previewImageName: '5f05b799985d5565e1826922-484EEEA10A-image.jpg',
previewImageUrls: {
original: 'https://storage.googleapis.com/caasy-media/5f05b799985d5565e1826922-484EEEA10A-image.jpg',
large: 'https://storage.googleapis.com/caasy-media-thumbnails/1500x1500_5f05b799985d5565e1826922-484EEEA10A-image.jpg',
larger: 'https://storage.googleapis.com/caasy-media-thumbnails/1200x1200_5f05b799985d5565e1826922-484EEEA10A-image.jpg',
medium: 'https://storage.googleapis.com/caasy-media-thumbnails/800x800_5f05b799985d5565e1826922-484EEEA10A-image.jpg',
smaller: 'https://storage.googleapis.com/caasy-media-thumbnails/400x400_5f05b799985d5565e1826922-484EEEA10A-image.jpg'
},
updatedById: '5f05b66d985d5565e1826921',
isPublished: true,
updatedAt: '2020-07-20T16:03:52.334Z',
createdAt: '2020-07-17T13:15:46.248Z'
}

Get all IDs

If you are planning to use a static site generator, you might need to have a list of all blog post IDs to define, which routes are available on your site. In this scenario, you can use the getAllIds function.

const allPostIds = await caasy.posts.getAllIds();

Example Response:

[ '5f11a473b37775863c3243a7', '5f11a482b37775863c3243a8' ]

Get all Authors

Use the getAllAuthors function, if you want to fetch all the authors, that have published a blog post on the site. The response is paginated. Pass the desired page as a number to the function.

const allAuthors = await caasy.posts.getAllAuthors(1);

Example Response:

{
totalItems: 1,
items: 1,
page: 1,
itemsPerPage: 25,
data: [
{
id: '5f05b66d985d5565e1826921',
firstName: 'Caasy',
lastName: 'Admin'
}
]
}

Get by Author

The getAllByAuthor function allows you to fetch all published blog posts by an author. The first argument is the author ID and the second one the page of posts you want to fetch.

const postsByAuthor = await caasy.posts.getAllByAuthor('5f05b66d985d5565e1826921', 1);

Example Response:

{
totalItems: 1,
items: 1,
page: 1,
itemsPerPage: 25,
data: [
{
id: '5f11a482b37775863c3243a8',
title: [Object],
description: [Object],
authorId: '5f05b66d985d5565e1826921',
author: [Object],
siteId: '5f05b799985d5565e1826922',
previewImageName: '5f05b799985d5565e1826922-484EEEA10A-asoggetti-rSFxBGpnluw-unsplash-(1).jpg',
previewImageUrls: [Object],
updatedById: '5f05b66d985d5565e1826921',
updatedBy: [Object],
isPublished: true,
updatedAt: '2020-07-20T16:03:52.334Z',
createdAt: '2020-07-17T13:15:46.248Z'
}
]
}

Pages

The SDK offers also methods to fetch published pages.

Get All

Fetches all published pages. The response is paginated, starting on page 1. You can pass the desired page as a number to the function. Keep in mind that the function only fetches the basic data of a page and no details such as its elements.

const allPages = await caasy.pages.getAll();

Example Response:

{
totalItems: 1,
items: 1,
page: 1,
itemsPerPage: 25,
data: [
{
id: '5f1ebb1d36b222ac09bd3400',
authorId: '5f05b66d985d5565e1826921',
author: [Object],
siteId: '5f1eba3c36b222ac09bd33f1',
title: [Object],
updatedById: '5f05b66d985d5565e1826921',
updatedBy: [Object],
isPublished: true,
updatedAt: '2020-07-29T11:27:46.388Z',
createdAt: '2020-07-27T11:31:41.637Z'
}
]
}

Get one by ID

Fetches a page with all its elements for a given page ID.

const pageById = await caasy.pages.getById('5f1ebb1d36b222ac09bd3400');

Example Response:

{
id: '5f1ebb1d36b222ac09bd3400',
authorId: '5f05b66d985d5565e1826921',
author: {
id: '5f05b66d985d5565e1826921',
firstName: 'Caasy',
lastName: 'Admin',
avatar: '22'
},
siteId: '5f1eba3c36b222ac09bd33f1',
title: { en_US: 'Landing Page' },
elements: [
{
customId: 'about-section',
elements: [Array],
id: '1595856051255-1fxlo',
type: 'container'
}
],
updatedById: '5f05b66d985d5565e1826921',
isPublished: true,
updatedAt: '2020-07-29T11:27:46.388Z',
createdAt: '2020-07-27T11:31:41.637Z'
}

Helpers

In addition, there are several helper functions that are handy when working with a blog post's or page's data.

Filter Elements by Custom ID

Filters an array of Caasy elements by a given custom element ID. The function returns an array that contains all elements that have the given custom ID.

const pageById = await caasy.pages.getById('5f1ebb1d36b222ac09bd3400');
const headlines = caasy.helpers.filterElementsByCustomId(pageById.elements, 'top-level-headline');

Get Element by ID

Searches for one element with a given element ID in an array of Caasy elements. If no element was found, it will return null.

const blogPost = await caasy.posts.getById('5f11a482b37775863c3243a8');
const slider = caasy.helpers.getElementById(blogPost.elements, '1595849396752-1warb');

Get Element by Custom ID

Searches for one element with a given custom element ID in an array of Caasy elements. If no element was found, it will return null.

const blogPost = await caasy.posts.getById('5f11a482b37775863c3243a8');
const aboutHeadline = caasy.helpers.getElementByCustomId(blogPost.elements, 'about-headline');
Edit this page