@vunora/sdk
v0.2.0
Published
Official JavaScript/TypeScript SDK for Vunora, the agentic CMS. Typed read client for pages, posts, media, and localized content.
Maintainers
vimanyuReadme
@vunora/sdk
Official JavaScript/TypeScript SDK for Vunora — the agentic CMS. Read your workspace content (pages, posts, media, and more) from any frontend or server with a typed client.
npm i @vunora/sdk
# or: pnpm add @vunora/sdk / yarn add @vunora/sdkQuick start
import { createClient } from '@vunora/sdk'
const vunora = createClient({
baseUrl: 'https://your-workspace.vunora.ai', // your Vunora API base URL
publicKey: process.env.VUNORA_PUBLIC_KEY!, // a publishable key: pk_live_…
})
// List documents in a collection
const { docs, totalDocs } = await vunora.collection('posts').find({
where: { featured: { equals: true } },
sort: '-publishedAt',
limit: 10,
})
// Read one document by id or slug
const page = await vunora.collection('pages').findById('home')Keys
- Publishable key (
pk_live_…) — read-only, safe to ship in client-side code. Use it with this SDK for reads. - Secret key (
sk_live_…) — server-only, can write. Never expose it in a browser bundle.
Create keys in your Vunora dashboard under Settings → API tokens. Each key is scoped to specific collections and environments.
Reading content
collection(name).find(options)
type FindOptions = {
where?: Record<string, unknown> // Payload-style query, e.g. { status: { equals: 'published' } }
sort?: string // e.g. '-publishedAt' (prefix '-' for descending)
limit?: number // 1–100, default 10
page?: number // 1-based
depth?: number // relationship depth, 0–2
locale?: string // 'es', 'ja', … or 'all' — see Localization
}
// → { docs, totalDocs, limit, totalPages, page }collection(name).findById(id, options)
const post = await vunora.collection('posts').findById('42', { depth: 1, locale: 'es' })id accepts the document id or its slug (for pages/posts).
Localization
Sites imported into Vunora carry per-locale content. Pass locale to read a specific language; omit it for the site's default locale.
const es = await vunora.collection('pages').findById('home', { locale: 'es' })
// es.contentFields hold the Spanish valuesSurface API
surface() returns the resolved region/locale/country configuration plus content, integrations, logos, and reviews for the current site — useful for building localized, region-aware storefronts.
const surface = await vunora.surface({ region: 'eu', locale: 'de', country: 'DE' })React (optional)
The /react subpath ships a headless RegionSelector. It has no hard React dependency in the core client; react is an optional peer.
import { RegionSelector } from '@vunora/sdk/react'Local development
Set VUNORA_IS_LOCAL=true (or VITE_/PUBLIC_/NEXT_PUBLIC_ variants) to return mock data without a live API — handy for prototyping UI before your keys are ready.
Error handling
Read failures throw an Error whose message is Vunora <status>: <body>. A 401 means a missing or wrong key; a 404 from surface() resolves to null rather than throwing.
License
MIT