Getting Started

Use the SDK through the package, the browser bundle, or the Cloud Code global.

Package Install

pnpm add nimbu-js-sdk

import Nimbu from 'nimbu-js-sdk';

await Nimbu.initialize('site-or-user-access-token');

In browsers and Cloud Code, the network layer is already available. In a plain Node process, configure Nimbu.setAjax(...) before making API requests. See External Node Or Server.

CommonJS works too:

const imported = require('nimbu-js-sdk');
const Nimbu = imported.default || imported;

await Nimbu.initialize('site-or-user-access-token');

Browser Bundle

Use the bundled global when you are not using a bundler:

<script src="/path/to/nimbu.min.js"></script>
<script>
  Nimbu.initialize('site-or-user-access-token').then(function () {
    return Nimbu.Cloud.run('calculateShipping', { country: 'BE' });
  });
</script>

Inside Nimbu themes, prefer the SDK asset provided by the platform when available:

<script src="{{ 'nimbu-js-sdk' | asset_url }}"></script>

Cloud Code

Cloud Code exposes Nimbu globally. Do not call Nimbu.initialize() there.

Nimbu.Cloud.job('publish_due_articles', async () => {
  const articles = await new Nimbu.Query('articles')
    .lessThanOrEqualTo('publish_at', new Date())
    .equalTo('status', 'scheduled')
    .findAll();

  for (const article of articles) {
    article.set('status', 'published');
    await article.save();
  }
});

Initialization

Nimbu.initialize() returns a promise. Wait for it before making SDK requests. Cloud Code is the exception: it provides an already initialized global Nimbu.

await Nimbu.initialize('access-token', 'https://api.nimbu.io', 'installation-id');

Arguments:

Argument	Required	Description
accessToken	Yes	Static access token string, or { clientId, refreshToken } for OAuth2 refresh.
endpoint	No	API endpoint. Defaults to https://api.nimbu.io.
installationId	No	Stable client installation id. If omitted, the SDK stores one.

OAuth2 refresh token setup:

await Nimbu.initialize({
  clientId: 'oauth-client-id',
  refreshToken: 'refresh-token'
});

First Query

const query = new Nimbu.Query('articles');
query.equalTo('published', true);
query.descending('published_at');
query.limit(10);

const articles = await query.find();

find() returns one page as a plain array. Use findAll() or collection().fetch() only when you intentionally want every match.

First Save

const article = new Nimbu.Object('articles', {
  title: 'SDK introduction',
  published: false
});

await article.save();

TypeScript

The package ships types. You can type channel fields with generics:

import Nimbu, { NimbuQuery } from 'nimbu-js-sdk';

type Article = {
  title: string;
  published: boolean;
};

const ArticleObject = Nimbu.Object.extend<Article>('articles');
const article = new ArticleObject({ title: 'Typed article', published: false });
const query = new NimbuQuery<Article>(ArticleObject);

query.equalTo('published', article.get('published'));