@mhbdev/unicms

Typed SDK for the UniCMS public API (/api/public/v1/*).

Install

pnpm add @mhbdev/unicms

Create client

import { createUniCmsClient } from '@mhbdev/unicms'

const cms = createUniCmsClient({
  baseUrl: 'https://cms.example.com',
  tenant: { slug: 'acme' },
})

Use domain-based tenant scope instead:

const cms = createUniCmsClient({
  baseUrl: 'https://cms.example.com',
  tenant: { domain: 'acme.example.com' },
})

Optional auth headers (private tenants)

const cms = createUniCmsClient({
  baseUrl: 'https://cms.example.com',
  tenant: { slug: 'acme' },
  headers: async () => ({
    Authorization: `Bearer ${await getToken()}`,
  }),
})

API

await cms.getSiteSettings()
await cms.getPageBySlug('home')
await cms.getPageBySlug('pricing', { includeRawContent: true })

await cms.listPosts({ page: 1, limit: 10, q: 'cms', categorySlug: 'news', tagSlug: 'payload' })
await cms.getPostBySlug('hello-world')
await cms.getPostBySlug('hello-world', { includeRawContent: true })

await cms.listFaqs()
await cms.listFaqs({ includeRawContent: true })

await cms.listCategories()
await cms.listTags()

Error handling

SDK methods throw UniCmsError:

import { UniCmsError } from '@mhbdev/unicms'

try {
  await cms.getPageBySlug('missing-page')
} catch (error) {
  if (error instanceof UniCmsError) {
    console.error(error.code, error.status, error.message, error.details)
  }
}

Error codes:

• BAD_REQUEST
• UNAUTHORIZED
• FORBIDDEN
• NOT_FOUND
• VALIDATION_ERROR
• NETWORK_ERROR
• PARSE_ERROR
• UNKNOWN

Pagination

listPosts returns:

type Paginated<T> = {
  docs: T[]
  pagination: {
    page: number
    limit: number
    totalDocs: number
    totalPages: number
    hasNextPage: boolean
    hasPrevPage: boolean
    nextPage: number | null
    prevPage: number | null
  }
}

Defaults: page=1, limit=10, max limit=50.

Compatibility

• SDK targets UniCMS public API v1.
• Endpoints are expected at /api/public/v1/*.
• v1 returns published content only.

Release notes

• 0.1.x: Initial v1 contract-first release.