@baryodev/barako-client

Typed TypeScript client for the barakoCMS headless API. Framework-agnostic and isomorphic: it runs in Node, the browser, and edge runtimes on the global fetch, with no runtime dependencies. Ships ESM, CJS, and type declarations.

• Two auth modes. An API key for machine callers (SDKs, CI, integrations), or a username and password for human apps with automatic token refresh.
• Tenant aware. Sends the right X-Tenant for multi-tenant deployments, derived from the token.
• Typed. Content, content types, and results are typed; failures throw a BarakoError carrying the status and the server's message.

Compatibility

This version works with barakoCMS 4.0 through 4.4 (API contract 1 to 4, sent by the API as X-Api-Contract-Version). The client does not read that header, so check it yourself when you move to a barakoCMS release that raises the contract. Node 18 or later.

Install

npm i @baryodev/barako-client

Quick start

Machine caller with an API key (create one in the barakoBrew console under Access, then API keys):

import { createClient } from "@baryodev/barako-client";

const cms = createClient({
  baseUrl: "https://your-host/barakocms-api",
  apiKey: "bcms_...",
});

const posts = await cms.contents.list({ contentType: "post", pageSize: 10 });
const one = await cms.contents.get(posts.items[0].id);

Human app with login. Tokens are stored and refreshed for you:

import { createClient, browserStore } from "@baryodev/barako-client";

const cms = createClient({
  baseUrl: "https://your-host/barakocms-api",
  storage: browserStore(), // localStorage; defaults to in-memory
});

await cms.auth.login("username", "password");
const tenants = await cms.me.tenants();
await cms.me.switch("acme"); // swap to another tenant you belong to

API

createClient(config) returns a client with five resources.

// auth (JWT flows)
await cms.auth.login(username, password, tenant?);
await cms.auth.logout();
await cms.auth.refresh();
cms.auth.isAuthenticated;

// me
await cms.me.tenants();
await cms.me.switch(tenantSlug);

// content types
await cms.contentTypes.list();
await cms.contentTypes.create({ name, displayName, fields });

// content
await cms.contents.list({ contentType?, page?, pageSize?, status? });
await cms.contents.get(id);
await cms.contents.create({ contentType, data, status?, sensitivity? });
await cms.contents.update(id, { data, status?, version? });
await cms.contents.setStatus(id, ContentStatus.Published);
await cms.contents.history(id);

// public delivery: anonymous, published-only, for a website frontend
await cms.public.list("post", { page?, pageSize? }); // paged published entries
await cms.public.bySlug("post", "my-slug");           // one entry, or null
await cms.public.menu("main");                         // a nav menu, or null
cms.public.fileUrl(fileId);                            // a public file URL for <img src>

Public delivery

For a website frontend you don't need auth at all, just a base URL (and a tenant for a multi-tenant deployment). The public resource reads only published content and never returns drafts or sensitive fields.

const cms = createClient({ baseUrl: "https://your-cms/barakocms-api", tenant: "your-site" });

const posts = await cms.public.list("post");
const post = await cms.public.bySlug("post", params.slug); // null: render a 404
const nav = await cms.public.menu("main");

Errors

import { BarakoError } from "@baryodev/barako-client";

try {
  await cms.contents.create({ contentType: "member", data: { Email: "not-an-email" } });
} catch (e) {
  if (e instanceof BarakoError && e.isValidation) {
    console.log(e.status, e.message); // 400, "Field 'Email' expects type 'email'..."
  }
}

Config

| Option | Purpose | | --- | --- | | baseUrl | API base URL (required) | | apiKey | bcms_... key for machine auth (no login, no X-Tenant) | | token / refreshToken | Start JWT auth from existing tokens | | tenant | Force the X-Tenant for JWT auth (otherwise read from the token) | | storage | Where JWT tokens live: memoryStore() (default) or browserStore() | | fetch | Custom fetch, for interception or a runtime without a global one |

License

MIT