@se-studio/contentful-rest-api 0.1.0

package/README.md

@@ -0,0 +1,467 @@
+# @se-studio/contentful-rest-api
+
+Type-safe Contentful REST API client with caching, rate limiting, and extensible converters for Next.js applications.
+
+## Features
+
+- 🎯 **Type-safe** - Full TypeScript support with generated types from your Contentful space
+- 🔄 **Dual API Support** - Content Delivery API (CDA) and Content Preview API (CPA)
+- ⚡ **Next.js Optimized** - Built-in support for Next.js App Router cache tags and revalidation
+- 🔁 **Retry Logic** - Automatic retry with exponential backoff for failed requests
+- 🚦 **Rate Limiting** - Respect Contentful API rate limits with built-in rate limiter
+- 🧩 **Extensible Converters** - Functional composition pattern for customizing content transformations
+- 🛡️ **Error Handling** - Custom error types for different failure scenarios
+
+## Installation
+
+```bash
+pnpm add @se-studio/contentful-rest-api @se-studio/core-data-types contentful
+```
+
+## Quick Start
+
+### Basic Usage
+
+```typescript
+import { contentfulPageRest } from '@se-studio/contentful-rest-api';
+
+// Fetch a page by slug
+const page = await contentfulPageRest(
+  {
+    spaceId: process.env.CONTENTFUL_SPACE_ID!,
+    accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+    environment: 'master'
+  },
+  'home',
+  {
+    locale: 'en-US',
+    cache: {
+      tags: ['home-page'],
+      revalidate: 3600 // 1 hour
+    }
+  }
+);
+```
+
+### Preview Mode
+
+```typescript
+import { contentfulPageRest } from '@se-studio/contentful-rest-api';
+
+// Use preview API for draft content
+const page = await contentfulPageRest(
+  {
+    spaceId: process.env.CONTENTFUL_SPACE_ID!,
+    accessToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!,
+  },
+  'home',
+  {
+    preview: true, // Uses Preview API
+    cache: { cache: 'no-store' } // Don't cache preview content
+  }
+);
+```
+
+## API Reference
+
+### Client Functions
+
+#### `createContentfulClient(config)`
+
+Creates a Contentful Content Delivery API (CDA) client.
+
+```typescript
+import { createContentfulClient } from '@se-studio/contentful-rest-api';
+
+const client = createContentfulClient({
+  spaceId: process.env.CONTENTFUL_SPACE_ID!,
+  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+  environment: 'master'
+});
+```
+
+#### `createContentfulPreviewClient(config)`
+
+Creates a Contentful Content Preview API (CPA) client.
+
+```typescript
+import { createContentfulPreviewClient } from '@se-studio/contentful-rest-api';
+
+const previewClient = createContentfulPreviewClient({
+  spaceId: process.env.CONTENTFUL_SPACE_ID!,
+  accessToken: process.env.CONTENTFUL_PREVIEW_ACCESS_TOKEN!,
+});
+```
+
+### Content Fetching Functions
+
+#### `contentfulPageRest(config, slug, options?, converter?)`
+
+Fetches a page by slug.
+
+**Parameters:**
+- `config`: ContentfulConfig - Contentful client configuration
+- `slug`: string - Page slug to fetch
+- `options?`: FetchOptions - Optional fetch options (locale, preview, cache, retry)
+- `converter?`: Converter - Optional custom converter function
+
+**Returns:** `Promise<IPage | null>`
+
+```typescript
+const page = await contentfulPageRest(
+  config,
+  'about-us',
+  {
+    locale: 'en-US',
+    include: 10,
+    cache: { tags: ['about-page'], revalidate: 3600 }
+  }
+);
+```
+
+#### `contentfulPageByIdRest(config, id, options?, converter?)`
+
+Fetches a page by entry ID.
+
+**Parameters:**
+- `config`: ContentfulConfig
+- `id`: string - Entry ID
+- `options?`: FetchOptions
+- `converter?`: Converter
+
+**Returns:** `Promise<IPage>`
+
+**Throws:** `EntryNotFoundError` if entry doesn't exist
+
+```typescript
+const page = await contentfulPageByIdRest(
+  config,
+  '5nZHNlP9rZhWvKx4w2Z8zB'
+);
+```
+
+#### `contentfulAllPagesRest(config, options?, converter?)`
+
+Fetches all pages from Contentful.
+
+**Parameters:**
+- `config`: ContentfulConfig
+- `options?`: FetchOptions
+- `converter?`: Converter
+
+**Returns:** `Promise<IPage[]>`
+
+```typescript
+const pages = await contentfulAllPagesRest(
+  config,
+  {
+    locale: 'en-US',
+    cache: { tags: ['all-pages'], revalidate: 3600 }
+  }
+);
+```
+
+#### `contentfulEntryRest<TEntry, TResult>(config, id, converter, options?)`
+
+Generic function to fetch any entry type with a custom converter.
+
+```typescript
+const article = await contentfulEntryRest(
+  config,
+  'articleId123',
+  myArticleConverter,
+  { locale: 'en-US' }
+);
+```
+
+## Converter Pattern
+
+The package uses a functional composition pattern for converting Contentful entries to your domain types.
+
+### Base Converter
+
+```typescript
+import { basePageConverter } from '@se-studio/contentful-rest-api';
+
+// Use the base converter
+const page = basePageConverter(contentfulEntry);
+```
+
+### Enhancers
+
+Enhancers are functions that wrap converters to add additional functionality:
+
+```typescript
+import {
+  basePageConverter,
+  withSEO,
+  withSections,
+  withTags,
+  compose
+} from '@se-studio/contentful-rest-api';
+
+// Compose multiple enhancers
+const myConverter = compose(
+  withSEO,
+  withSections,
+  withTags
+)(basePageConverter);
+
+// Use with API functions
+const page = await contentfulPageRest(config, 'home', {}, myConverter);
+```
+
+### Custom Converters
+
+Create your own converter enhancers:
+
+```typescript
+import type { Converter, PageEntrySkeleton } from '@se-studio/contentful-rest-api';
+import type { IPage } from '@se-studio/core-data-types';
+
+function withCustomField(
+  converter: Converter<PageEntrySkeleton, IPage>
+): Converter<PageEntrySkeleton, IPage> {
+  return (entry) => {
+    const page = converter(entry);
+
+    // Add custom logic
+    return {
+      ...page,
+      customField: entry.fields.customField || 'default'
+    };
+  };
+}
+
+// Use it
+const converter = withCustomField(basePageConverter);
+```
+
+## Caching
+
+### Cache Tags
+
+The package provides utilities for generating cache tags for Next.js:
+
+```typescript
+import { generateCacheTags, getPageCacheTags } from '@se-studio/contentful-rest-api';
+
+// Generate tags for a content type
+const tags = generateCacheTags('page', 'entry-id');
+// Returns: ['contentful', 'contentful:page', 'contentful:page:entry-id']
+
+// Get page-specific cache tags
+const pageTags = getPageCacheTags('home', 'en-US');
+```
+
+### Cache Revalidation
+
+Revalidate cache tags in Server Actions or Route Handlers:
+
+```typescript
+'use server'
+
+import { revalidateTags } from '@se-studio/contentful-rest-api';
+
+export async function revalidateHomePage() {
+  await revalidateTags(['contentful:page:home']);
+}
+```
+
+## Error Handling
+
+The package provides custom error types for different scenarios:
+
+```typescript
+import {
+  ContentfulError,
+  RateLimitError,
+  EntryNotFoundError,
+  AuthenticationError,
+  ValidationError,
+  isRetryableError
+} from '@se-studio/contentful-rest-api';
+
+try {
+  const page = await contentfulPageByIdRest(config, 'invalid-id');
+} catch (error) {
+  if (error instanceof EntryNotFoundError) {
+    console.log('Entry not found:', error.entryId);
+  } else if (error instanceof RateLimitError) {
+    console.log('Rate limited, retry after:', error.retryAfter);
+  } else if (isRetryableError(error)) {
+    // Handle retryable errors
+  }
+}
+```
+
+## Retry Configuration
+
+Configure retry behavior for resilient API calls:
+
+```typescript
+const page = await contentfulPageRest(
+  config,
+  'home',
+  {
+    retry: {
+      maxRetries: 3,
+      initialDelay: 1000,
+      maxDelay: 30000,
+      backoffMultiplier: 2
+    }
+  }
+);
+```
+
+## Rate Limiting
+
+Use the built-in rate limiter to control request rates:
+
+```typescript
+import { RateLimiter } from '@se-studio/contentful-rest-api';
+
+// Create a rate limiter (5 requests per second)
+const limiter = new RateLimiter(5, 1);
+
+// Consume a token before making a request
+await limiter.consume();
+const page = await contentfulPageRest(config, 'home');
+```
+
+## Type Generation
+
+Generate TypeScript types from your Contentful space:
+
+### 1. Configure Environment Variables
+
+Create a `.env.local` file:
+
+```env
+CONTENTFUL_SPACE_ID=your-space-id
+CONTENTFUL_MANAGEMENT_TOKEN=your-management-token
+CONTENTFUL_ENVIRONMENT_NAME=master
+```
+
+### 2. Generate Types
+
+```bash
+pnpm --filter @se-studio/contentful-rest-api generate:types
+```
+
+This creates `src/generated/contentful-types.ts` with types matching your Contentful content model.
+
+### 3. Use Generated Types
+
+```typescript
+import type { TypePageSkeleton } from './generated/contentful-types';
+import { contentfulEntryRest } from '@se-studio/contentful-rest-api';
+
+const page = await client.getEntry<TypePageSkeleton>('entry-id');
+```
+
+## Configuration Options
+
+### ContentfulConfig
+
+```typescript
+interface ContentfulConfig {
+  spaceId: string;
+  accessToken: string;
+  environment?: string; // defaults to 'master'
+  host?: string; // for proxies or custom endpoints
+  options?: Partial<CreateClientParams>;
+}
+```
+
+### FetchOptions
+
+```typescript
+interface FetchOptions {
+  locale?: string;
+  preview?: boolean;
+  include?: number; // include depth for linked entries (default: 10)
+  cache?: CacheConfig;
+  retry?: RetryConfig;
+}
+```
+
+### CacheConfig
+
+```typescript
+interface CacheConfig {
+  tags?: string[]; // Next.js cache tags
+  revalidate?: number | false; // ISR revalidation time in seconds
+  cache?: 'force-cache' | 'no-store';
+}
+```
+
+### RetryConfig
+
+```typescript
+interface RetryConfig {
+  maxRetries?: number; // default: 3
+  initialDelay?: number; // default: 1000ms
+  maxDelay?: number; // default: 30000ms
+  backoffMultiplier?: number; // default: 2
+}
+```
+
+## Next.js App Router Integration
+
+Example usage in a Next.js Server Component:
+
+```typescript
+// app/[slug]/page.tsx
+import { contentfulPageRest } from '@se-studio/contentful-rest-api';
+
+interface PageProps {
+  params: { slug: string };
+}
+
+export default async function Page({ params }: PageProps) {
+  const page = await contentfulPageRest(
+    {
+      spaceId: process.env.CONTENTFUL_SPACE_ID!,
+      accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+    },
+    params.slug,
+    {
+      cache: {
+        tags: [`page:${params.slug}`],
+        revalidate: 3600
+      }
+    }
+  );
+
+  if (!page) {
+    notFound();
+  }
+
+  return (
+    <div>
+      <h1>{page.title}</h1>
+      <p>{page.description}</p>
+    </div>
+  );
+}
+
+export async function generateStaticParams() {
+  const pages = await contentfulAllPagesRest({
+    spaceId: process.env.CONTENTFUL_SPACE_ID!,
+    accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
+  });
+
+  return pages.map((page) => ({
+    slug: page.slug,
+  }));
+}
+```
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/Something-Else-Studio/se-core-product