kakasete-js-sdk

JavaScript/TypeScript SDK for KAKASETE Headless CMS API.

Features

• TypeScript-first with full type safety
• Zero runtime dependencies (uses native fetch)
• Universal - works in Browser, Node.js, and Edge runtimes
• ESM and CommonJS support
• Comprehensive error handling

Installation

npm install kakasete-js-sdk
# or
yarn add kakasete-js-sdk
# or
pnpm add kakasete-js-sdk

Quick Start

import { createClient } from 'kakasete-js-sdk';

const client = createClient({
  siteSlug: 'your-site-slug',
  apiKey: 'your-api-key',
});

// Fetch articles
const { items, totalCount } = await client.articles.getList();

// Fetch single article
const article = await client.articles.getDetail({ id: 1 });

// Fetch with filters
const filtered = await client.articles.getList({
  queries: {
    category: 'news',
    page: 1,
    pageSize: 10,
  },
});

API Reference

createClient(config)

Creates a new KAKASETE client instance.

Config Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | siteSlug | string | Yes | Your site slug | | apiKey | string | Yes | API key for authentication | | baseUrl | string | No | Custom API base URL | | customFetch | function | No | Custom fetch implementation | | timeout | number | No | Request timeout in milliseconds (default: 10000) |

Articles

// Get paginated list of articles
const response = await client.articles.getList({
  queries: {
    page: 1,
    pageSize: 10,
    category: 'news',      // Filter by category slug
    articleType: 'blog',   // Filter by article type slug
    tag: 'featured',       // Filter by tag
    search: 'keyword',     // Search query
    sort: 'publishedAt:desc', // Sort order
  },
});

// Get single article by ID
const article = await client.articles.getDetail({ id: 1 });

// Get all articles (handles pagination automatically)
const allArticles = await client.articles.getAllContents();

// Get all article IDs
const ids = await client.articles.getAllIds();

Categories

// Get paginated list of categories
const response = await client.categories.getList();

// Get single category by ID
const category = await client.categories.getDetail({ id: 1 });

// Get all categories
const allCategories = await client.categories.getAllContents();

Tags

// Get paginated list of tags
const response = await client.tags.getList();

// Get single tag by ID
const tag = await client.tags.getDetail({ id: 1 });

// Get all tags
const allTags = await client.tags.getAllContents();

Article Types

// Get paginated list of article types
const response = await client.articleTypes.getList();

// Get single article type by ID
const articleType = await client.articleTypes.getDetail({ id: 1 });

// Get all article types
const allTypes = await client.articleTypes.getAllContents();

Response Types

ListResponse

All getList methods return a paginated response:

interface ListResponse<T> {
  items: T[];
  page: number;
  pageSize: number;
  totalCount: number;
  totalPages: number;
  hasMore: boolean;
}

Article

interface Article {
  id: number;
  slug?: string;
  title: string;
  content: string;
  excerpt?: string;
  imageUrl?: string;
  videoUrl?: string;
  category?: string;
  categorySlug?: string;
  articleType?: string;
  articleTypeSlug?: string;
  author?: string;
  isPublished: boolean;
  publishedAt?: string;
  updatedAt?: string;
  tags?: string[];
}

Error Handling

import {
  createClient,
  KakaseteApiError,
  KakaseteNetworkError,
  KakaseteConfigError,
} from 'kakasete-js-sdk';

try {
  const articles = await client.articles.getList();
} catch (error) {
  if (error instanceof KakaseteApiError) {
    // API returned an error response
    console.error(`API Error: ${error.message} (${error.statusCode})`);
    console.error('Response:', error.response);
  } else if (error instanceof KakaseteNetworkError) {
    // Network request failed
    console.error(`Network Error: ${error.message}`);
    console.error('Cause:', error.cause);
  } else if (error instanceof KakaseteConfigError) {
    // Invalid client configuration
    console.error(`Config Error: ${error.message}`);
  }
}

Framework Integration

Next.js (App Router)

// app/articles/page.tsx
import { createClient } from 'kakasete-js-sdk';

const client = createClient({
  siteSlug: process.env.KAKASETE_SITE_SLUG!,
  apiKey: process.env.KAKASETE_API_KEY!,
});

export default async function ArticlesPage() {
  const { items } = await client.articles.getList();

  return (
    <ul>
      {items.map((article) => (
        <li key={article.id}>{article.title}</li>
      ))}
    </ul>
  );
}

Next.js (Pages Router)

// pages/articles/index.tsx
import { createClient } from 'kakasete-js-sdk';
import type { GetStaticProps } from 'next';
import type { Article } from 'kakasete-js-sdk';

const client = createClient({
  siteSlug: process.env.KAKASETE_SITE_SLUG!,
  apiKey: process.env.KAKASETE_API_KEY!,
});

export const getStaticProps: GetStaticProps = async () => {
  const { items } = await client.articles.getList();

  return {
    props: { articles: items },
    revalidate: 60,
  };
};

export default function ArticlesPage({ articles }: { articles: Article[] }) {
  return (
    <ul>
      {articles.map((article) => (
        <li key={article.id}>{article.title}</li>
      ))}
    </ul>
  );
}

Cloudflare Workers

import { createClient } from 'kakasete-js-sdk';

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const client = createClient({
      siteSlug: env.KAKASETE_SITE_SLUG,
      apiKey: env.KAKASETE_API_KEY,
    });

    const { items } = await client.articles.getList();
    return Response.json(items);
  },
};

React (Client-side)

import { useEffect, useState } from 'react';
import { createClient, type Article } from 'kakasete-js-sdk';

const client = createClient({
  siteSlug: 'your-site-slug',
  apiKey: 'your-api-key',
});

function ArticleList() {
  const [articles, setArticles] = useState<Article[]>([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    client.articles.getList()
      .then(({ items }) => setArticles(items))
      .finally(() => setLoading(false));
  }, []);

  if (loading) return <p>Loading...</p>;

  return (
    <ul>
      {articles.map((article) => (
        <li key={article.id}>{article.title}</li>
      ))}
    </ul>
  );
}

Custom Fetch

For environments that require a custom fetch implementation:

import { createClient } from 'kakasete-js-sdk';

// Example: Using undici for Node.js
import { fetch as undiciFetch } from 'undici';

const client = createClient({
  siteSlug: 'your-site-slug',
  apiKey: 'your-api-key',
  customFetch: undiciFetch,
});

TypeScript Support

All types are exported for use in your application:

import type {
  Article,
  Category,
  Tag,
  ArticleType,
  ListResponse,
  ArticleListParams,
  GetListRequest,
  GetDetailRequest,
  GetAllContentsRequest,
  KakaseteClient,
  KakaseteClientConfig,
} from 'kakasete-js-sdk';

License

Apache-2.0