@bernierllc/contentful-types

TypeScript definitions and utilities for Contentful content types.

This package provides a robust and type-safe way to interact with Contentful data within TypeScript projects.

Installation

npm install @bernierllc/contentful-types

Usage

Import and use the types in your TypeScript project:

import {
  ContentfulEntry,
  ContentfulAsset,
  ContentfulSpace,
  ContentfulContentType,
  validateContentTypeName,
  isValidContentType
} from '@bernierllc/contentful-types';

// Type-safe Contentful entry
const entry: ContentfulEntry = {
  sys: {
    id: '123',
    type: 'Entry',
    contentType: { sys: { id: 'blogPost', type: 'Link', linkType: 'ContentType' } },
    createdAt: '2025-01-01T00:00:00Z',
    updatedAt: '2025-01-01T00:00:00Z',
    space: { sys: { id: 'space-id', type: 'Link', linkType: 'Space' } },
    environment: { sys: { id: 'master', type: 'Link', linkType: 'Environment' } },
    revision: 1,
    locale: 'en-US'
  },
  fields: {
    title: 'Hello World',
    content: 'This is my first post'
  },
  metadata: { tags: [] }
};

// Validate content type names
const isValid = validateContentTypeName('blogPost');
console.log(isValid); // true

API

Types

• ContentfulEntry - Base entry structure with sys and fields
• ContentfulAsset - Asset type with file metadata
• ContentfulSpace - Space configuration
• ContentfulContentType - Content type schema definition
• ContentfulLink - Link reference structure
• ContentfulSys - System metadata structure
• ContentfulLocale - Locale configuration
• ContentfulEnvironment - Environment settings
• ContentfulField - Field definition structure
• ContentfulRichText - Rich text document structure
• ContentfulQueryOptions - Query parameters for CDA/CMA
• ContentfulSyncOptions - Sync API parameters
• ContentfulGraphQLQuery - GraphQL query structure

Functions

validateContentTypeName(name: string): boolean

Validates that a content type name follows Contentful naming conventions (alphanumeric, dashes, underscores, 1-64 characters).

validateContentTypeName('blog-post'); // true
validateContentTypeName('Blog Post'); // false (spaces not allowed)

isValidContentType(contentType: any): boolean

Type guard that validates if an object matches the ContentfulContentType interface structure.

const ct = { sys: { id: 'post', type: 'ContentType' }, name: 'Post', fields: [] };
if (isValidContentType(ct)) {
  // TypeScript knows ct is ContentfulContentType
}

Integration Documentation

Logger Integration

This package does not depend on @bernierllc/logger as it is a pure types package with no runtime logging requirements. If you need logging for validation errors in your application, integrate logger at the application level.

NeverHub Integration

This package does not require NeverHub integration as it provides static TypeScript types and validation utilities. NeverHub integration should be implemented at the service layer that consumes these types.

Graceful Degradation

All validation functions provide fallback behavior:

• validateContentTypeName() returns false for invalid inputs rather than throwing
• Type guards like isValidContentType() safely return false for malformed data
• No external service dependencies required for core functionality