BlockMind SDK

SDK for BlockMind CMS data, services and CLI.

Documentation for Coding Agents

For detailed API response documentation, see agents.md. This file contains comprehensive information about backend response structures for Next.js frontend development.

Important Chapters

• Introduction - Overview of the documentation and its purpose
• Response Structure Patterns - Understanding single item responses, list responses, and error handling
• API Responses - Complete documentation for all APIs:
  • Pages API - Fetching pages and page content blocks
  • Collections API - Working with collection items
  • Menus API - Navigation menus
  • Widgets API - Reusable widget components
  • Forms API - Form definitions and submissions
  • Site Settings API - Site-wide settings (logos, favicon, scripts, etc.)
• Common Types - Shared data structures:
  • Block - Dynamic content blocks (no predefined structure)
  • MetaTag - Complete SEO metadata structure
  • Media/Image Objects - Image and media file structures
  • Element/Button Objects - Button and link structures
• Building Pages: A Complete Workflow - Step-by-step guide for building pages:
  • The Story of Building a Page - Complete workflow from fetching page structure to rendering widgets, forms, and collections
  • Key Takeaways - Important points to remember
  • Important Notes - Critical information about block handling
• Usage Examples - Code examples for common operations
• Notes - Important implementation details and best practices

Install

npm i @appropriate-team/blockmind-sdk

Quick start

• Client components (no Node APIs):

import { submitPublicForm } from '@appropriate-team/blockmind-sdk/client';

await submitPublicForm('contactUs', [
  { apiName: 'email', value: '[email protected]' },
], 'turnstile-token-here');

• Server code (Node environment):

import { pagesApi, collectionsApi, menusApi, widgetsApi, formsApi, siteSettingsApi } from '@appropriate-team/blockmind-sdk';

const page = pagesApi.getBySlug('home');
const posts = collectionsApi.getByCollectionTypeApiName('blog');
const mainNav = menusApi.getByApiName('main-navigation');
const logos = siteSettingsApi.getLogos();

Next.js rendering modes

• SSG / ISR: Import from @appropriate-team/blockmind-sdk inside generateStaticParams, generateMetadata, getStaticProps, etc. All services make API calls, so they work during build or in Route Handlers.
• SSR / Server Components: safe to import from @appropriate-team/blockmind-sdk because execution stays on the server. Ideal for app/ router loaders, API routes, and edge/serverless functions with Node APIs enabled.
• Client Components: import from @appropriate-team/blockmind-sdk/client only. That entry strips Node dependencies and exposes submitPublicForm, initSanctum, and future browser-safe helpers.

Services

• pagesApi: getAll, getBySlug
• collectionsApi: getAll, getByCollectionTypeAndSlug, getByCollectionTypeApiName
• menusApi: getAll, getByApiName
• widgetsApi: getAll, getByApiName
• formsApi: getAll, getByApiName, submitPublicForm(slug, formData, turnstileToken)
• siteSettingsApi: getAll, getFavicon, getCookies, getLogos, getSiteLinks, getScripts, getScriptsByLocation, getScriptsForPage

Note: submitPublicForm can be imported directly from @appropriate-team/blockmind-sdk/client for client components, or accessed via formsApi.submitPublicForm() for server code. The turnstileToken parameter is required for Cloudflare Turnstile verification.

Types

Types are re-exported from src/index.d.ts.

Notes

• Import from @appropriate-team/blockmind-sdk/client in Client Components to avoid Node modules.

Tests

npm run test