iChiba Contentful SDK

A TypeScript SDK for accessing iChiba marketplace content from Contentful CMS. This SDK provides type-safe methods to retrieve banners, blog posts, documentation articles, and other content types with market and language filtering support.

Features

• 🔒 Type-safe: Full TypeScript support with auto-generated types from Contentful schemas
• 🌐 Multi-market: Built-in filtering by market and language
• 📝 Content Types: Support for banners, blog posts, documentation, and more
• 🚀 Easy to use: Simple API with intuitive method names
• 🎯 Selective queries: Optimized queries with field selection
• ⚡ Performance: Built on top of the official Contentful SDK

Installation

# Using npm
npm install @janbox/contentful-marketplace-sdk

# Using yarn
yarn add @janbox/contentful-marketplace-sdk

# Using pnpm
pnpm add @janbox/contentful-marketplace-sdk

Quick Start

1. Configure the SDK

import { ContentfulSDK } from '@janbox/contentful-marketplace-sdk';

// Initialize the SDK with your Contentful credentials
ContentfulSDK.configure({
  space: 'your-space-id',
  accessToken: 'your-access-token',
  environment: 'master', // optional, defaults to 'master'
});

2. Fetch Content

import { 
  listBannerEntries, 
  listBlogPostEntries, 
  findBlogPostEntry,
  listDocCategoryEntries,
  listDocArticleEntries 
} from '@janbox/contentful-marketplace-sdk';

// Get banners for a specific market and language
const banners = await listBannerEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.platform[in]': 'WEB',
    limit: 10
  }
});

// Get blog posts
const blogPosts = await listBlogPostEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    order: '-sys.createdAt',
    limit: 5
  }
});

// Find a specific blog post by slug
const blogPost = await findBlogPostEntry({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.slug': 'how-to-shop-online'
  }
});

// Get documentation categories
const docCategories = await listDocCategoryEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    order: 'fields.order'
  }
});

Supported Content Types

🎯 Banners

• Type: banner
• Methods: listBannerEntries()
• Fields: name, image, redirectUrl, market, language, platform
• Platforms: MOBILE, WEB

📝 Blog Posts

• Type: blogPost
• Methods: listBlogPostEntries(), findBlogPostEntry()
• Fields: title, slug, author, featuredImage, content, category, shortDescription, seo
• Features: Related posts, categories, SEO metadata

📚 Documentation

• Types: documentationCategory, documentationArticle
• Methods: listDocCategoryEntries(), findDocCategoryEntry(), listDocArticleEntries(), findDocArticleEntry()
• Features: Hierarchical categories, searchable articles, SVG icons

👤 Authors

• Type: author
• Fields: name, avatar

🏷️ Categories

• Types: blogCategory, documentationCategory
• Features: SEO support, hierarchical organization

🔍 SEO Metadata

• Type: seo
• Fields: metaTitle, metaDescription, metaKeywords, metaRobots

API Reference

Configuration

ContentfulSDK.configure(params)

Configure the SDK with Contentful credentials.

ContentfulSDK.configure({
  space: string,           // Your Contentful space ID
  accessToken: string,     // Your Contentful access token
  environment?: string,    // Environment (default: 'master')
  host?: string,          // Custom host (optional)
  // ... other Contentful client options
});

Banner Methods

listBannerEntries(options)

Retrieve multiple banner entries.

const banners = await listBannerEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.platform[in]': 'WEB,MOBILE',
    limit: 10,
    order: '-sys.createdAt'
  }
});

Blog Methods

listBlogPostEntries(options)

Retrieve multiple blog post entries with basic fields.

const posts = await listBlogPostEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.category.sys.id': 'category-id',
    limit: 10,
    skip: 0
  }
});

findBlogPostEntry(options)

Retrieve a single blog post with full content.

const post = await findBlogPostEntry({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.slug': 'my-blog-post'
  }
});

Documentation Methods

listDocCategoryEntries(options)

Retrieve documentation categories.

const categories = await listDocCategoryEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    order: 'fields.order'
  }
});

findDocCategoryEntry(options)

Find a specific documentation category.

const category = await findDocCategoryEntry({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.slug': 'getting-started'
  }
});

listDocArticleEntries(options)

Retrieve documentation articles.

const articles = await listDocArticleEntries({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.category.sys.id': 'category-id',
    order: '-sys.updatedAt'
  }
});

findDocArticleEntry(options)

Find a specific documentation article.

const article = await findDocArticleEntry({
  marketId: 'vn',
  language: 'vi',
  query: {
    'fields.slug': 'payment-methods'
  }
});

Error Handling

The SDK includes built-in error handling for common scenarios:

import { NotFoundResponse } from '@janbox/contentful-marketplace-sdk';

try {
  const post = await findBlogPostEntry({
    marketId: 'vn',
    language: 'vi',
    query: { 'fields.slug': 'non-existent-post' }
  });
} catch (error) {
  if (error instanceof NotFoundResponse) {
    console.log('Blog post not found');
  }
}

Type Definitions

The SDK exports comprehensive TypeScript types for all content:

import type {
  // Entry Types
  BannerEntry,
  BlogPostEntry,
  DocCategoryEntry,
  DocArticleEntry,
  
  // Skeleton Types
  TypeBannerSkeleton,
  TypeBlogPostSkeleton,
  TypeDocumentationCategorySkeleton,
  TypeDocumentationArticleSkeleton,
  
  // Field Types
  TypeBannerFields,
  TypeBlogPostFields,
  // ... and many more
} from '@janbox/contentful-marketplace-sdk';

Query Options

All list methods accept Contentful's standard query parameters:

• limit: Number of entries to return (max 1000)
• skip: Number of entries to skip
• order: Sort order (e.g., '-sys.createdAt', 'fields.title')
• fields.*: Filter by field values
• sys.*: Filter by system properties
• include: Include linked entries (0-10)
• select: Choose specific fields to return

Development

Prerequisites

• Node.js 18+
• pnpm 8+

Setup

# Clone the repository
git clone https://github.com/your-org/ichiba-contentful-sdk.git

# Install dependencies
pnpm install

# Build the SDK
pnpm build:packages

Project Structure

ichiba-contentful-sdk/
├── packages/
│   └── marketplace-sdk/
│       ├── src/
│       │   ├── client/         # SDK client configuration
│       │   ├── entries/        # Content type methods
│       │   ├── http-responses/ # Custom error responses
│       │   ├── types/          # TypeScript type definitions
│       │   └── index.ts        # Main export file
│       ├── dist/               # Built files
│       └── package.json
├── examples/                   # Usage examples
└── package.json

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support, please contact the iChiba development team or create an issue in the repository.

Built with ❤️ by the iChiba team