inventra

TypeScript SDK for the Inventra CMS API. Framework-agnostic core with optional React and Next.js integrations.

Installation

npm install inventra
# or
bun add inventra

Quick Start

import { Inventra } from 'inventra';

const inventra = new Inventra({
  apiKey: process.env.INVENTRA_API_KEY!,
  orgId: process.env.INVENTRA_ORG_ID!,
});

// List published contents
const posts = await inventra.contents.list();

// Get a single post
const post = await inventra.contents.getBySlug('my-post');

// List categories
const categories = await inventra.categories.list();

// Submit a contact form
await inventra.contacts.submit({
  fullName: 'John Doe',
  phoneNumber: '+5511999999999',
  email: '[email protected]',
  subject: 'Inquiry',
  message: 'Hello!',
});

// Get organization info
const org = await inventra.organizations.get();

// Get sitemap entries
const entries = await inventra.sitemaps.listEntries();

// List all published blocks
const blocks = await inventra.blocks.list();

// List blocks for a specific page
const homeBlocks = await inventra.blocks.list({ pages: 'home' });
// or
const homeBlocks2 = await inventra.blocks.listForPage('home');

// Fetch a single block by its key (slug)
const hero = await inventra.blocks.getBySlug('homepage-hero');

Blocks

Blocks are reusable, structured content pieces you configure in the Inventra admin (hero sections, about sections, CTAs, etc.). Each block has a slug (the "key") and a fields array with typed values (text, richtext, image, video).

import { Inventra, Blocks } from 'inventra-sdk';

const inventra = new Inventra({ apiKey, orgId });

const hero = await inventra.blocks.getBySlug('homepage-hero');
if (hero) {
  const headline = Blocks.getText(hero, 'headline');
  const bio = Blocks.getText(hero, 'bio'); // markdown string for richtext
  const bg = Blocks.getImage(hero, 'background'); // { url, alt } | null
  const demo = Blocks.getVideo(hero, 'demo-reel'); // { url, status } | null
}

Render markdown-typed fields (richtext) with the Markdown component:

import { Markdown } from 'inventra-sdk/react';

<Markdown content={Blocks.getText(block, 'bio')} />

Entry Points

| Import | Description | Dependencies | |--------|-------------|--------------| | inventra-sdk | Core client, types, utilities | None | | inventra-sdk/schema | JSON-LD schema builders | None | | inventra-sdk/llms | LLM-friendly content generation | Core | | inventra-sdk/react | React components (JsonLd, Markdown, AutoBreadcrumbSchema) | react, react-markdown, remark-gfm, rehype-sanitize | | inventra-sdk/next | Next.js helpers (sitemap, route handlers, ISR) | next | | inventra-sdk/og | Branded OpenGraph image generation (Satori templates, theme config, metadata builders) | next, react, sharp + date-fns (bundled) |

Configuration

const inventra = new Inventra({
  apiKey: 'your-api-key',   // Required
  orgId: 'your-org-id',     // Required
  apiUrl: 'http://localhost:3000', // Optional, defaults to 'https://inventra.sh'
  fetch: customFetch,       // Optional, override global fetch
});

The /api suffix is appended automatically to apiUrl.

Next.js Integration

import { withISR } from 'inventra-sdk/next';

// ISR caching
const posts = await inventra.contents.list(withISR(60));

// app/sitemap.ts
import { createSitemapGenerator } from 'inventra-sdk/next';

export default createSitemapGenerator(inventra, {
  baseUrl: 'https://example.com',
  staticRoutes: [
    { path: '/', priority: 1 },
    { path: '/blog', changeFrequency: 'daily', priority: 0.8 },
  ],
});

// app/api/contents/route.ts
import { createContentsHandler } from 'inventra-sdk/next';
export const GET = createContentsHandler(inventra);

Schema Builders

import { buildArticleSchema, buildBreadcrumbSchema } from 'inventra-sdk/schema';

const schema = buildArticleSchema({
  siteUrl: 'https://example.com',
  professional: { name: 'Dr. Jane', jobTitle: 'Therapist', description: '...' },
  title: post.title,
  slug: post.slug,
  // ...
});

React Components

import { JsonLd, Markdown, AutoBreadcrumbSchema } from 'inventra-sdk/react';

<JsonLd data={schema} />
<Markdown content={post.content} />
<AutoBreadcrumbSchema siteUrl="https://example.com" routeLabels={{ blog: 'Blog' }} />

LLMs Service

import { createLlmsService } from 'inventra-sdk/llms';

const llms = createLlmsService({
  client: inventra,
  siteName: 'My Site',
  siteDescription: 'About my site',
  baseUrl: 'https://example.com',
  pages: { /* page providers */ },
});

const index = await llms.generateIndex();
const page = await llms.generatePageContent(['blog', 'my-post']);

Full Documentation

See llms.txt for comprehensive API documentation including all types, parameters, and examples.

License

MIT