@konso/cms-client

TypeScript client for the Konso CMS REST API.

Installation

npm install @konso/cms-client
# or
pnpm add @konso/cms-client

Setup

import { KonsoCmsClient } from "@konso/cms-client";

const client = new KonsoCmsClient({
  projectId: "your-project-id",
  apiKey: "your-api-key",
});

| Option | Default | Description | | --- | --- | --- | | projectId | — | Your Konso project ID | | apiKey | KONSO_API_KEY env | Your Konso API key | | baseUrl | KONSO_BASE_URL env → https://apis-spb.konso.io | API base URL |

Resources

Pages

// List
const { list, total } = await client.pages.list({ isPublished: true });

// Get by id or slug
const page = await client.pages.get(42);
const page = await client.pages.getBySlug("home");

// Create
const { result: id } = await client.pages.create({
  name: "home",
  slug: "home",
  title: "Home",
  pageType: PageType.Content,   // 1 = Master, 2 = Content
  isActive: true,
  publish: true,
  contents: [
    { contentType: PageContentType.Html, content: "<h1>Hello</h1>" },
  ],
});

// Update
await client.pages.update({ id, title: "New Title" });

// Delete
await client.pages.delete(id);

import { PageType, PageContentType } from "@konso/cms-client";
// PageType:        Master = 1, Content = 2
// PageContentType: Html = 2, Markdown = 6, Json = 9

Contents

const { list } = await client.contents.list({ type: 1 });

const { result: id } = await client.contents.create({
  name: "article-1",
  title: "My Article",
  body: "<p>Body</p>",
  announce: "",
  type: 1,
});

await client.contents.update({ ...existing, id, title: "Updated" });
await client.contents.delete(id);

Categories

const { list } = await client.categories.list({ section: 1 });
const category   = await client.categories.get(id);

const { result: id } = await client.categories.create({
  name: "News",
  slug: "news",
  section: 1,
});

await client.categories.update({ id, name: "Latest News" });
await client.categories.delete(id);

Menus

const { list } = await client.menus.list();
const menu      = await client.menus.get(id);
const menu      = await client.menus.getByName("Main Nav");

const { result: menuId } = await client.menus.create({
  name: "Main Nav",
  items: [
    { text: "Home", link: "/", order: 1 },
  ],
});

await client.menus.update({ id: menuId, name: "Primary Nav" });
await client.menus.delete(menuId);

Menu items

const { list } = await client.menus.listItems(menuId);

const { result: itemId } = await client.menus.createItem({
  menuId,
  text: "About",
  link: "/about",
  order: 2,
});

await client.menus.updateItem({ id: itemId, menuId, text: "About Us" });
await client.menus.deleteItem(itemId);

Tags

const { list } = await client.tags.list();
const tag      = await client.tags.get(id);
const tag      = await client.tags.getByName("typescript");

// Create accepts an array, returns an array of new ids
const { result: ids } = await client.tags.create([
  { tag: "typescript" },
  { tag: "cms" },
]);

await client.tags.update({ id, tag: "ts" });
await client.tags.delete(id);

Error handling

All API errors throw KonsoHttpError:

import { KonsoHttpError } from "@konso/cms-client";

try {
  await client.pages.get(99999);
} catch (err) {
  if (err instanceof KonsoHttpError) {
    console.error(err.status); // HTTP status code
    console.error(err.message); // "Konso API error 404: ..."
    console.error(err.body);   // raw ApiResponse body
  }
}

Requirements

Node.js 18 or later (uses native fetch).