Environment Differences

The SDK API is mostly the same everywhere. Setup, authentication, storage, and permissions differ.

Cloud Code

Cloud Code has a global Nimbu object. It is already initialized and authenticated for the current site or app context.

Nimbu.Cloud.get('/api/articles/:id', async (request, response) => {
  const article = await new Nimbu.Query('articles').get(request.params.id);
  response.json(article.toJSON());
});

Notes:

• Do not call Nimbu.initialize().
• Jobs and backend handlers run with server-side credentials.
• Route handlers can also receive request.customer / request.user when the storefront visitor is authenticated.
• Store ids or plain params in scheduled jobs. Fetch fresh objects inside the job.

Theme Or Browser

Browser code must initialize the SDK before making requests.

await Nimbu.initialize(siteAccessToken);

const current = Nimbu.Customer.current();

Notes:

• The SDK stores the installation id and current customer session in browser storage.
• Customer methods such as logIn, signUp, current, and logOut are meant for this environment.
• Use Nimbu.Cloud.run() for business logic that should stay server-side.

External Node Or Server

Use the package from a server process when you need an integration or automation outside Cloud Code.

import Nimbu from 'nimbu-js-sdk';

Nimbu.setAjax(async (method, url, data, headers = {}, options = {}) => {
  const requestHeaders = {
    'Content-Type': options.formPost
      ? 'application/x-www-form-urlencoded'
      : 'text/plain'
  };

  if (headers._accessToken) {
    requestHeaders['X-Nimbu-Access-Token'] = `token ${headers._accessToken}`;
  }
  if (headers._clientVersion) {
    requestHeaders['X-Nimbu-Client-Version'] = headers._clientVersion;
  }
  if (headers._installationId) {
    requestHeaders['X-Nimbu-Installation-Id'] = headers._installationId;
  }
  if (headers._sessionToken) {
    requestHeaders['X-Nimbu-Session-Token'] = headers._sessionToken;
  }

  const response = await fetch(url, {
    method,
    body: method === 'GET' || method === 'DELETE' ? undefined : data,
    headers: requestHeaders
  });

  const text = response.status === 204 ? '' : await response.text();
  const body = text ? JSON.parse(text) : '';

  if (!response.ok) {
    throw {
      responseText: JSON.stringify(body)
    };
  }

  return { body, status: response.status };
});

await Nimbu.initialize(process.env.NIMBU_ACCESS_TOKEN);

const count = await new Nimbu.Query('orders')
  .equalTo('status', 'paid')
  .count();

The SDK has a browser-oriented default network layer. In Node, set an Ajax adapter like the one above. If your runtime needs persistent session storage, set that too with Nimbu.setStorage(...).

React Native

Import the React Native entrypoint so AsyncStorage is configured:

import Nimbu from 'nimbu-js-sdk/react-native';

await Nimbu.initialize(accessToken);

ACL Behavior

Server-side contexts can see more data than public/customer contexts. Use useACL when you need a request to respect channel ACLs:

const visibleArticles = await new Nimbu.Query('articles')
  .equalTo('published', true)
  .find({ useACL: true });

To make ACL filtering the default for an initialized SDK instance:

Nimbu.useACL();

Reserved Names And forceChannel

Names such as products, orders, pages, customers, roles, coupons, and devices map to built-in endpoints. If you have a custom channel with one of those names, pass forceChannel: true.

const entry = await new Nimbu.Object('products', { id }).fetch({
  forceChannel: true
});