`@vlozi/blog` — SDK Reference

import { VloziClient } from "@vlozi/blog";
 
const client = new VloziClient({
    apiKey: process.env.VLOZI_API_KEY!,    // pk_*; sk_* keys throw VloziSecretKeyError
    baseUrl: process.env.VLOZI_BASE_URL!,  // e.g. "https://api.vlozi.app"
    // Optional knobs:
    timeoutMs: 10_000,        // request timeout; 0 disables
    retries: 2,                // retry attempts on network/5xx/429
    retryBackoffMs: 300,       // initial backoff; doubles each attempt
    cache: undefined,          // CacheAdapter | false; default is shared InMemoryCache
    cacheTtlMs: 60_000,        // default TTL for cached GETs
    onRequest: (ctx) => {},    // hook fires before each request
    onResponse: (ctx) => {},   // hook fires after each response
    onError: (ctx) => {},      // hook fires after retries exhausted
});

interface Post {
    title: string;
    slug: string;                              // canonical React key — no `id` field exposed
    excerpt: string;
    content?: string;                          // HTML. Only on `client.blog.get()`.
    publishedAt: string;                       // ISO-8601
    seoTitle?: string;
    seoDescription?: string;
    featuredImageUrl?: string | null;
    category?: Category | null;
    tags?: Tag[];
    author?: Author | null;
    readingTime?: number;                      // computed client-side if missing
}

interface Category { name: string; slug: string; postCount?: number; }
interface Tag      { name: string; slug: string; postCount?: number; }

interface Author {
    name: string;
    slug?: string;       // for /authors/:slug pages
    avatarUrl?: string;
    bio?: string;
    url?: string;
}

interface PaginatedResponse<T> {
    data: T[];
    meta: { page: number; limit: number; total: number; totalPages: number };
}
 
interface ListParams {
    page?: number;          // default 1
    limit?: number;         // default 10
    category?: string | string[];   // OR-matched if array
    tag?: string | string[];
    search?: string;
    sort?: 'publishedAt' | 'title' | 'createdAt';
    order?: 'asc' | 'desc';
}
 
interface ArchiveGroup {
    year: number; month: number; monthName: string;
    posts: Post[]; count: number;
}
interface ArchiveResult { groups: ArchiveGroup[]; totalPosts: number; }
 
interface NeighborsResult { previous: Post | null; next: Post | null; }

VloziError                          // base — `instanceof VloziError` for catch-all
├── VloziConfigError                // missing apiKey/baseUrl on first request; .field, .hint
├── VloziApiError                   // any non-2xx HTTP response; .status, .url, .requestId, .detail
│   ├── VloziAuthError              // 401/403
│   └── VloziRateLimitError         // 429; .retryAfter (seconds)
├── VloziNetworkError               // DNS, offline, CORS — no response received; .url, .cause
├── VloziTimeoutError               // exceeded timeoutMs; .url, .timeoutMs
└── VloziSecretKeyError             // sk_* passed as apiKey; thrown at construction

Vlozi API Error (404): Not Found [GET https://api.vlozi.app/blog/public/posts/x] (requestId=req_abc123)

import { InMemoryCache, type CacheAdapter, type CacheEntry } from "@vlozi/blog";
 
// Defaults: maxEntries: 100, maxAgeMultiplier: 5 (so SWR window = ttlMs * 5)
new InMemoryCache({ maxEntries: 200, maxAgeMultiplier: 10 });
 
// Or implement your own:
class RedisCache implements CacheAdapter {
    get<T>(key: string): CacheEntry<T> | undefined { /* ... */ }
    set<T>(key: string, value: T, ttlMs: number): void { /* ... */ }
    delete(key: string): void { /* ... */ }
    invalidate(pattern: string | RegExp): void { /* ... */ }
    clear(): void { /* ... */ }
    subscribe(key: string, listener: () => void): () => void { /* ... */ }
}

import { generateRSS, generateSitemap } from "@vlozi/blog";
 
// RSS 2.0 string
const rssXml = await generateRSS({
    client,
    siteUrl: "https://example.com",
    title: "Example Blog",
    description: "Latest posts",
    postUrl: (slug) => `https://example.com/blog/${slug}`,  // optional
    language: "en-us",
    limit: 50,
    category: undefined,
});
 
// Sitemap XML
const sitemapXml = await generateSitemap({
    client,
    siteUrl: "https://example.com",
    additionalUrls: [
        { loc: "https://example.com/", priority: 1.0, changefreq: "daily" },
    ],
});

import { VloziClient } from "@vlozi/blog";
import { VloziProvider } from "@vlozi/blog/react";
import "@vlozi/blog/styles.css";   // see "CSS contract" below
 
const client = new VloziClient({ apiKey: ..., baseUrl: ... });
 
<VloziProvider
    client={client}
    config={{
        mermaidTheme: "auto",         // "default" | "dark" | "auto" | () => "default" | "dark"
        syntaxHighlighting: true,      // true emits data-vlz-syntax="default"; false omits it
        imageComponent: undefined,     // default <img>; pass Next.js Image to upgrade
    }}
>
    {children}
</VloziProvider>

const {
    data,         // PaginatedResponse<Post> | null
    loading, error,
    refetch,      // () => Promise<void>; bypasses cache
    page, totalPages, hasNextPage, hasPrevPage,
} = usePosts(params?: ListParams);
 
const { data, loading, error } = usePost(slug: string);
 
const { data, loading, error, refetch } = useCategories();
const { data, loading, error, refetch } = useTags();
 
const { data, loading, error, refetch } = useArchive({ maxPosts? });
 
const { data, loading, error } = useRelatedPosts(slug, { limit?, pool? });
const { data, loading, error } = useNeighbors(slug, { pool? });

<BlogContent
    html={post.content!}                        // required
    className?: string                           // merged with .vlz-content
    transformHtml?: (html: string) => string    // run BEFORE sanitization
    imageComponent?: VloziImageComponent         // upgrade inline <img> tags via portal
/>

<BlogPost
    slug={params.slug}                           // required
    className?: string                            // applied to <article>
    renderTitle?: Slot<[title: string]>           // default: <h1>
    showFeaturedImage?: boolean                   // default true
    imageComponent?: VloziImageComponent          // featured image only
    renderLoading?: Slot                          // default: <BlogPostSkeleton>
    renderError?: Slot<[error: Error]>            // default: same as renderNotFound
    renderNotFound?: Slot                         // shown when usePost resolves to null
/>

<BlogList
    className?: string
    limit?: number                                // default 10
    columns?: 1 | 2 | 3 | 4                       // default 3
    variant?: "grid" | "list"                     // default "grid"
    category?: string | string[]                  // OR-matched if array
    tag?: string | string[]
    showPagination?: boolean                      // default true
    renderItem?: Slot<[post: Post]>               // replaces <BlogCard>
    renderLoading?: Slot                          // default: <BlogListSkeleton>
    renderEmpty?: Slot                            // "No posts found"
    renderError?: Slot<[error: Error]>
    imageComponent?: VloziImageComponent          // forwarded to each card
    prefetchOnHover?: boolean                     // forwarded to each card
    scrollToTopOnPageChange?: boolean             // default true
    search?: string                                // controlled query (wins over searchable input)
    searchable?: boolean                           // built-in input with debounce
    searchPlaceholder?: string                     // default "Search posts..."
    searchDebounceMs?: number                      // default 300
    sortable?: boolean                             // built-in sort dropdown
/>

<BlogInfiniteList
    className?: string
    limit?: number                                // page size (default 10)
    columns?: 1 | 2 | 3 | 4                       // default 3
    category?, tag?, search?, sort?, order?       // see ListParams
    renderItem?: Slot<[post: Post]>
    renderLoading?, renderEmpty?, renderError?
    imageComponent?: VloziImageComponent
    prefetchOnHover?: boolean
    rootMargin?: string                           // IntersectionObserver; default "400px"
/>

<BlogCard
    post={post}                                   // required
    className?: string
    variant?: "default" | "featured" | "compact"  // default "default"
    renderMeta?: Slot<[post: Post]>
    footer?: ReactNode
    onClick?: (post: Post) => void
    imageComponent?: VloziImageComponent
    prefetchOnHover?: boolean                     // default false
/>

<BlogCategoryNav
    className?: string
    activeCategory?: string                       // controlled — current slug
    onSelect?: (slug: string | null) => void      // null = "All"
    variant?: "sidebar" | "tabs" | "pills"        // default "sidebar"
    showCounts?: boolean                          // default true
    renderLoading?, renderEmpty?: Slot
/>

<BlogTagNav
    className?: string
    activeTag?: string                            // controlled
    onSelect?: (slug: string | null) => void      // null = "All tags"
    variant?: "pills" | "cloud"                   // default "pills"
    showCounts?: boolean                          // default true
    renderLoading?, renderEmpty?: Slot
/>

<BlogArchive
    className?: string
    maxPosts?: number                             // default 1000
    postHref?: (post: Post) => string             // default `/blog/${slug}`
    variant?: "flat" | "grouped"                  // default "grouped"
    prefetchOnHover?: boolean                     // default false
    renderLoading?, renderError?, renderEmpty?: Slot
    renderGroup?: Slot<[group: ArchiveGroup]>     // replaces default post list
/>

<RelatedPosts
    slug={post.slug}                              // required
    className?: string
    limit?: number                                // default 3
    pool?: number                                 // default 100
    heading?: ReactNode                           // default "Related posts"; pass null to hide
    columns?: 1 | 2 | 3 | 4                       // default 3
    imageComponent?: VloziImageComponent
    prefetchOnHover?: boolean
    renderItem?: Slot<[post: Post]>
    renderLoading?, renderError?, renderEmpty?: Slot
/>

<PrevNextNav
    slug={post.slug}                              // required
    className?: string
    pool?: number                                 // default 500
    postHref?: (post: Post) => string
    renderLink?: Slot<[post: Post, direction: "previous" | "next"]>
    renderLoading?: Slot
    hideWhenEmpty?: boolean                       // default true
/>

<MermaidBlock
    source={mermaidSourceString}                  // required
    className?: string
    theme?: VloziMermaidTheme                     // override; falls back to provider, then "auto"
/>
 
<Carousel
    slides={[{ src: "/a.jpg", alt: "...", caption?: "..." }]}    // required
    className?: string
/>

import { BlogPostSkeleton, BlogCardSkeleton, BlogListSkeleton } from "@vlozi/blog/react";
 
<BlogPostSkeleton className?: string />
<BlogCardSkeleton className?: string />
<BlogListSkeleton
    columns?: 1 | 2 | 3 | 4   // default 3
    count?: number             // default columns * 2
    className?: string
/>

interface VloziImageProps {
    src: string;
    alt: string;
    className?: string;
    loading?: "lazy" | "eager";
    decoding?: "sync" | "async" | "auto";
    width?: number;        // body-image hydration only — featured paths don't pass these
    height?: number;
}
 
type VloziImageComponent = ComponentType<VloziImageProps>;

import { type Slot, resolveSlot } from "@vlozi/blog/react";   // resolveSlot is internal but exported

import { ServerBlogList, ServerBlogPost, ServerBlogCategoryList } from "@vlozi/blog/server";
import { VloziClient } from "@vlozi/blog";
 
const client = new VloziClient({ apiKey: ..., baseUrl: ... });
 
// Drop-in for app/blog/page.tsx — zero client JS, pure SSR HTML
export default async function BlogIndexPage() {
    return <ServerBlogList client={client} limit={9} />;
}

<ServerBlogList
    client={client}                               // required
    page?: number                                  // default 1
    limit?: number                                 // default 10
    category?, tag?, search?, sort?, order?       // ListParams
    postHref?: (post: Post) => string
    notFound?: ReactNode                           // empty-state JSX
    className?: string
/>

<ServerBlogPost
    client={client}                               // required
    slug={params.slug}                             // required
    notFound?: ReactNode                           // shown on 404
    render?: (post: Post) => ReactNode             // custom layout
    showFeaturedImage?: boolean                    // default true
    className?: string
/>

<ServerBlogCategoryList
    client={client}                               // required
    activeCategory?: string
    categoryHref?: (cat: Category) => string
    showCounts?: boolean
    className?: string
/>

import { generateStaticParamsForPosts, generateMetadataForPost } from "@vlozi/blog/next";
import type { GenerateStaticParamsOptions, GenerateMetadataOptions, VloziMetadata } from "@vlozi/blog/next";
 
// app/blog/[slug]/page.tsx
export const generateStaticParams = () =>
    generateStaticParamsForPosts({ client, paramKey: "slug", limit: 1000 });
 
export const generateMetadata = async ({ params }) => {
    const { slug } = await params;
    return generateMetadataForPost({
        client,
        slug,
        siteUrl: "https://example.com",        // optional; used to build canonical + og urls
    });
};

.vlz-content {
    --vlz-accent:        hsl(var(--primary));
    --vlz-muted-fg:      hsl(var(--muted-foreground));
    --vlz-border:        hsl(var(--border));
    --vlz-surface:       hsl(var(--muted) / 0.6);
    --vlz-surface-hover: hsl(var(--muted) / 0.8);
}

<pre><code class="language-typescript">
  <span class="hljs-keyword">const</span> x: <span class="hljs-keyword">string</span> = <span class="hljs-string">"hi"</span>;
</code></pre>