Postack CMS SDK

Official SDK for Postack CMS - A modern headless content management system.

Features

• 🚀 Easy Integration - Simple setup with API key authentication
• 📝 Posts API - Full CRUD operations for blog posts
• ⚛️ React Components - Ready-to-use components for displaying content
• 🔧 TypeScript Support - Full type definitions included
• 🎨 Customizable - Flexible styling and layout options
• 📱 Responsive - Mobile-first design patterns

Installation

npm install postack-cms-sdk

Quick Start

1. Initialize with CLI

npx postack-cms init

This will:

• Check if your CMS server is running
• Validate your API key
• Generate starter files
• Add the SDK to your project

2. Basic Usage

import { PostackCMS } from 'postack-cms-sdk';

const cms = new PostackCMS({
  baseUrl: 'http://localhost:3002',
  apiKey: 'your-api-key'
});

// Get all published posts
const posts = await cms.getPosts({ published: true });

// Get featured posts
const featured = await cms.getFeaturedPosts(3);

// Get single post
const post = await cms.getPost('post-slug');

3. React Components

import { BlogList, FeaturedPosts } from 'postack-cms-sdk';

const config = {
  baseUrl: 'http://localhost:3002',
  apiKey: 'your-api-key'
};

function MyBlog() {
  return (
    <div>
      {/* Featured Posts */}
      <FeaturedPosts 
        config={config}
        limit={3}
        onPostClick={(post) => console.log('Clicked:', post)}
      />

      {/* All Posts */}
      <BlogList 
        config={config}
        options={{
          postsPerPage: 10,
          layout: 'grid',
          showImages: true,
          showExcerpt: true
        }}
      />
    </div>
  );
}

API Reference

PostackCMS Client

Constructor

new PostackCMS(config, options)

Config:

• baseUrl (string) - Your CMS server URL
• apiKey (string) - Your API key for authentication

Options:

• timeout (number) - Request timeout in milliseconds (default: 30000)
• headers (object) - Additional headers to send with requests

Methods

Posts

// Get posts with filters
await cms.getPosts({
  published: true,
  featured: false,
  limit: 10,
  page: 1,
  category: 'tech',
  tag: 'javascript',
  author: 'user-id'
});

// Get featured posts
await cms.getFeaturedPosts(limit = 3);

// Get posts by category
await cms.getPostsByCategory('tech', { limit: 5 });

// Get posts by tag
await cms.getPostsByTag('javascript', { limit: 5 });

// Get posts by author
await cms.getPostsByAuthor('user-id', { limit: 5 });

// Get single post
await cms.getPost('post-slug');

Authentication

// Validate API key
await cms.validateApiKey('your-api-key');

// Login (if using email/password)
await cms.login('email@example.com', 'password');

// Logout
await cms.logout();

Content (Legacy)

// Get content
await cms.getContent('content-id');

// Create content
await cms.createContent({ title: 'New Content', body: 'Content body' });

// Update content
await cms.updateContent('content-id', { title: 'Updated Title' });

// Delete content
await cms.deleteContent('content-id');

React Components

BlogList

Display a list of blog posts with customizable options.

<BlogList 
  config={config}
  options={{
    postsPerPage: 10,
    showFeatured: false,
    layout: 'grid', // 'grid' | 'list'
    showImages: true,
    showExcerpt: true,
    showAuthor: true,
    showDate: true,
    showTags: true,
    className: 'custom-class'
  }}
  onPostClick={(post) => handlePostClick(post)}
/>

FeaturedPosts

Display featured posts in a grid layout.

<FeaturedPosts 
  config={config}
  limit={3}
  className="custom-class"
  onPostClick={(post) => handlePostClick(post)}
/>

Data Types

Post

interface Post {
  id: string;
  title: string;
  slug: string;
  content: string;
  excerpt?: string;
  image?: string;
  featured: boolean;
  published: boolean;
  createdAt: string;
  updatedAt: string;
  author?: {
    id: string;
    name: string;
    email: string;
  };
  category?: {
    id: string;
    name: string;
    slug: string;
  };
  tags?: Array<{
    id: string;
    name: string;
    slug: string;
  }>;
}

PostsResponse

interface PostsResponse {
  posts: Post[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

Examples

Custom Blog Layout

import { BlogList } from 'postack-cms-sdk';

function CustomBlog() {
  return (
    <div className="max-w-6xl mx-auto px-4">
      <h1 className="text-3xl font-bold mb-8">My Blog</h1>

      <BlogList 
        config={config}
        options={{
          postsPerPage: 12,
          layout: 'grid',
          showImages: true,
          showExcerpt: true,
          showAuthor: true,
          showDate: true,
          showTags: true
        }}
        onPostClick={(post) => {
          // Navigate to post page
          window.location.href = `/blog/${post.slug}`;
        }}
      />
    </div>
  );
}

Featured Posts Section

import { FeaturedPosts } from 'postack-cms-sdk';

function HomePage() {
  return (
    <div>
      <section className="py-12 bg-gray-50">
        <div className="max-w-6xl mx-auto px-4">
          <h2 className="text-2xl font-bold mb-8">Featured Articles</h2>
          <FeaturedPosts 
            config={config}
            limit={3}
            onPostClick={(post) => {
              // Handle post click
              console.log('Featured post clicked:', post);
            }}
          />
        </div>
      </section>
    </div>
  );
}

Programmatic Usage

import { PostackCMS } from 'postack-cms-sdk';

async function loadBlogData() {
  const cms = new PostackCMS({
    baseUrl: 'http://localhost:3002',
    apiKey: 'your-api-key'
  });

  try {
    // Get featured posts for homepage
    const featured = await cms.getFeaturedPosts(3);

    // Get latest posts for blog page
    const latest = await cms.getPosts({ 
      published: true, 
      limit: 10 
    });

    // Get posts by category
    const techPosts = await cms.getPostsByCategory('technology', { 
      limit: 5 
    });

    return { featured, latest, techPosts };
  } catch (error) {
    console.error('Error loading blog data:', error);
    return { featured: [], latest: [], techPosts: [] };
  }
}

Configuration

postack.config.js

The CLI generates a configuration file:

module.exports = {
  baseUrl: 'http://localhost:3002',
  apiKey: 'your-api-key',
  // Optional: Customize component styling
  theme: {
    primaryColor: '#3B82F6',
    borderRadius: '0.5rem',
    fontFamily: 'Inter, sans-serif'
  }
};

Error Handling

The SDK provides comprehensive error handling:

try {
  const posts = await cms.getPosts({ published: true });
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Invalid API key');
  } else if (error.response?.status === 404) {
    console.error('Posts not found');
  } else {
    console.error('Network error:', error.message);
  }
}

Support

• 📚 Documentation
• 💬 Support
• 🐛 Issues

License

MIT License - see LICENSE for details.