@content-streamline/nextjs 0.0.8 → 0.0.10

package/README.md

@@ -6,7 +6,8 @@ Next.js library for Content Streamline API with reusable, responsive components.
 
 - 🚀 **Easy Setup** - Configure via environment variables
 - 📦 **Reusable Components** - Pre-built React components for posts
-- 💾 **Smart Caching** - Automatic file-based caching with refresh control
+- 💾 **Next.js Native Caching** - Uses `fetch()` with `revalidate` for ISR support
+- 🔄 **On-Demand Revalidation** - Cache tags for targeted refresh via `revalidateTag()`
 - 🎨 **Customizable** - Responsive components with configurable props
 - 📱 **Mobile-Friendly** - Built-in responsive design
 - 🔧 **TypeScript** - Full TypeScript support
@@ -55,7 +56,7 @@ import '@content-streamline/nextjs/components/styles.css';
 import { getAllPosts } from '@content-streamline/nextjs/server';
 import { LatestPosts, PostsList } from '@content-streamline/nextjs/components';
 
-export const revalidate = 3600; // Revalidate every hour (ISR)
+export const revalidate = 300; // Revalidate every 5 minutes (ISR)
 
 export default async function BlogPage() {
   const posts = await getAllPosts({ platform: 'blog' });
@@ -133,7 +134,7 @@ export const getStaticProps: GetStaticProps = async () => {
   
   return {
     props: { posts },
-    revalidate: 3600, // Revalidate every hour
+    revalidate: 300, // Revalidate every 5 minutes
   };
 };
 
@@ -182,7 +183,7 @@ export const getStaticProps: GetStaticProps = async ({ params }) => {
   
   return {
     props: { post },
-    revalidate: 3600,
+    revalidate: 300,
   };
 };
 
@@ -197,15 +198,16 @@ export default function PostPage({ post }: { post: PostDetailResponse }) {
 
 #### `getAllPosts(options?)`
 
-Get all posts with automatic caching.
+Get all posts with Next.js caching (ISR-compatible).
 
 ```tsx
 import { getAllPosts } from '@content-streamline/nextjs/server';
 
 const posts = await getAllPosts({
   platform: 'blog',       // Filter by platform (default: undefined = all)
-  maxCacheAge: 60,        // Cache age in minutes (default: 60)
-  forceRefresh: false,    // Force API fetch (default: false)
+  revalidate: 300,        // Cache TTL in seconds (default: 300 = 5 min)
+  forceRefresh: false,    // Bypass cache (default: false)
+  tags: ['custom-tag'],   // Additional cache tags for revalidateTag()
 });
 ```
 
@@ -221,8 +223,9 @@ import { getPost } from '@content-streamline/nextjs/server';
 const post = await getPost(123, {
   language: 'en',
   contentFormat: 'markdown', // or 'html'
-  maxCacheAge: 60,
+  revalidate: 300,           // Cache TTL in seconds (default: 300)
   forceRefresh: false,
+  tags: ['custom-tag'],
 });
 ```
 
@@ -237,11 +240,24 @@ const post = await getPostBySlug('my-post-slug', {
   language: 'en',
   contentFormat: 'markdown',
   platform: 'blog',
-  maxCacheAge: 60,
+  revalidate: 300,
   forceRefresh: false,
 });
 ```
 
+#### `getCacheTags()`
+
+Get cache tag names for use with `revalidateTag()`.
+
+```tsx
+import { getCacheTags } from '@content-streamline/nextjs/server';
+
+const tags = getCacheTags();
+// tags.all        → 'content-streamline' (all content)
+// tags.postsList  → 'posts-list' (post listings)
+// tags.post(123)  → 'post-123' (specific post)
+```
+
 ### Components
 
 #### `<LatestPosts />`
@@ -443,17 +459,81 @@ import { PostDetail } from '@content-streamline/nextjs/components';
 
 ## Caching
 
-The library automatically caches posts in `.next/content-streamline-cache/`. 
+The library uses **Next.js native fetch caching** for optimal performance with ISR (Incremental Static Regeneration).
+
+### How It Works
+
+- **Default TTL**: 5 minutes (300 seconds)
+- **Automatic revalidation**: Next.js refreshes cache in background after TTL expires
+- **Cache tags**: Each request is tagged for targeted invalidation
+- **Works with static generation**: Pages can be statically generated at build time
+
+### Cache Tags
 
-- **Default cache age**: 60 minutes
-- **Cache location**: `.next/content-streamline-cache/`
-- **Automatic refresh**: When cache is older than `maxCacheAge`
+Every request is tagged for granular cache control:
+
+| Tag | Description |
+|-----|-------------|
+| `content-streamline` | All content from this library |
+| `posts-list` | Post listing requests |
+| `post-{id}` | Individual post by ID (e.g., `post-123`) |
+
+### Automatic Revalidation (Time-Based)
+
+Cache automatically refreshes after the TTL expires:
 
-To force refresh:
 ```tsx
+// 5 minute cache (default)
+const posts = await getAllPosts();
+
+// 1 minute cache
+const posts = await getAllPosts({ revalidate: 60 });
+
+// 1 hour cache
+const posts = await getAllPosts({ revalidate: 3600 });
+
+// No caching (always fresh)
 const posts = await getAllPosts({ forceRefresh: true });
 ```
 
+### On-Demand Revalidation
+
+Invalidate cache instantly when content changes (e.g., from a webhook):
+
+```tsx
+// app/api/revalidate/route.ts
+import { revalidateTag } from 'next/cache';
+import { getCacheTags } from '@content-streamline/nextjs';
+
+export async function POST(request: Request) {
+  const { postId } = await request.json();
+  
+  // Revalidate specific post
+  if (postId) {
+    revalidateTag(getCacheTags().post(postId));
+  }
+  
+  // Or revalidate all posts
+  revalidateTag(getCacheTags().postsList);
+  
+  return Response.json({ revalidated: true });
+}
+```
+
+### Static Generation with ISR
+
+For fully static pages with background revalidation:
+
+```tsx
+// app/blog/page.tsx
+export const revalidate = 300; // Revalidate page every 5 minutes
+
+export default async function BlogPage() {
+  const posts = await getAllPosts({ platform: 'blog' });
+  return <PostsList posts={posts} />;
+}
+```
+
 ## TypeScript
 
 Full TypeScript support is included:
@@ -462,6 +542,9 @@ Full TypeScript support is included:
 import type { 
   Post, 
   PostDetailResponse,
+  GetAllPostsOptions,
+  GetPostOptions,
+  CacheOptions,
   PostsListProps,
   LatestPostsProps,
   PostDetailProps,

package/dist/api/client.d.ts

@@ -1,25 +1,35 @@
 /**
  * Content Streamline Public API Client
+ * Uses Next.js fetch caching for optimal performance
  */
 import type { Post, PostDetailResponse, PostsResponse } from '../types/index.js';
+export interface CacheOptions {
+    /** Revalidation time in seconds (default: 300 = 5 minutes) */
+    revalidate?: number;
+    /** Cache tags for on-demand revalidation */
+    tags?: string[];
+    /** Force fresh data, bypassing cache */
+    forceRefresh?: boolean;
+}
 declare class ContentStreamlineAPI {
     private baseUrl;
     private accessToken;
-    constructor(baseUrl: string, accessToken: string);
+    private defaultRevalidate;
+    constructor(baseUrl: string, accessToken: string, defaultRevalidate?: number);
     private fetch;
     /**
      * List all posts with pagination
      */
-    listPosts(page?: number, platform?: string): Promise<PostsResponse>;
+    listPosts(page?: number, platform?: string, cacheOptions?: CacheOptions): Promise<PostsResponse>;
     /**
      * Get all posts by fetching all pages
      */
-    getAllPosts(platform?: string): Promise<Post[]>;
+    getAllPosts(platform?: string, cacheOptions?: CacheOptions): Promise<Post[]>;
     /**
      * Get a single post by ID
      */
-    getPost(id: number, contentFormat?: 'markdown' | 'html'): Promise<PostDetailResponse>;
+    getPost(id: number, contentFormat?: 'markdown' | 'html', cacheOptions?: CacheOptions): Promise<PostDetailResponse>;
 }
-export declare function createAPIClient(baseUrl: string, accessToken: string): ContentStreamlineAPI;
+export declare function createAPIClient(baseUrl: string, accessToken: string, defaultRevalidate?: number): ContentStreamlineAPI;
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,kBAAkB,EAClB,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B,cAAM,oBAAoB;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;YAKlC,KAAK;IAsDnB;;OAEG;IACG,SAAS,CAAC,IAAI,GAAE,MAAU,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAS5E;;OAEG;IACG,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IA4BrD;;OAEG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,GAAE,UAAU,GAAG,MAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAIxG;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,oBAAoB,CAE1F"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,kBAAkB,EAClB,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,wCAAwC;IACxC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,cAAM,oBAAoB;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,GAAE,MAAY;YAMnE,KAAK;IAwEnB;;OAEG;IACG,SAAS,CACb,IAAI,GAAE,MAAU,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,YAAY,GAAE,YAAiB,GAC9B,OAAO,CAAC,aAAa,CAAC;IAezB;;OAEG;IACG,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,YAAY,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IA4BtF;;OAEG;IACG,OAAO,CACX,EAAE,EAAE,MAAM,EACV,aAAa,GAAE,UAAU,GAAG,MAAmB,EAC/C,YAAY,GAAE,YAAiB,GAC9B,OAAO,CAAC,kBAAkB,CAAC;CAS/B;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,iBAAiB,GAAE,MAAY,GAC9B,oBAAoB,CAEtB"}

package/dist/api/client.js

@@ -1,23 +1,37 @@
 /**
  * Content Streamline Public API Client
+ * Uses Next.js fetch caching for optimal performance
  */
 class ContentStreamlineAPI {
-    constructor(baseUrl, accessToken) {
+    constructor(baseUrl, accessToken, defaultRevalidate = 300) {
         this.baseUrl = baseUrl.replace(/\/$/, ''); // Remove trailing slash
         this.accessToken = accessToken;
+        this.defaultRevalidate = defaultRevalidate;
     }
-    async fetch(endpoint, options = {}) {
+    async fetch(endpoint, options = {}, cacheOptions = {}) {
         const url = `${this.baseUrl}${endpoint}`;
         const headers = {
             'Authorization': `Bearer ${this.accessToken}`,
             'Content-Type': 'application/json',
             ...options.headers,
         };
+        const { revalidate = this.defaultRevalidate, tags, forceRefresh } = cacheOptions;
+        // Build Next.js cache options
+        const nextOptions = {};
+        if (!forceRefresh) {
+            nextOptions.revalidate = revalidate;
+        }
+        if (tags && tags.length > 0) {
+            nextOptions.tags = tags;
+        }
         let response;
         try {
             response = await fetch(url, {
                 ...options,
                 headers,
+                // Next.js cache configuration
+                cache: forceRefresh ? 'no-store' : undefined,
+                next: Object.keys(nextOptions).length > 0 ? nextOptions : undefined,
             });
         }
         catch (error) {
@@ -61,23 +75,24 @@ class ContentStreamlineAPI {
     /**
      * List all posts with pagination
      */
-    async listPosts(page = 1, platform) {
+    async listPosts(page = 1, platform, cacheOptions = {}) {
         const params = new URLSearchParams();
         params.set('page', page.toString());
         if (platform) {
             params.set('platform', platform);
         }
-        return this.fetch(`/public/v1/posts?${params.toString()}`);
+        const tags = cacheOptions.tags || ['content-streamline', 'posts-list'];
+        return this.fetch(`/public/v1/posts?${params.toString()}`, {}, { ...cacheOptions, tags });
     }
     /**
      * Get all posts by fetching all pages
      */
-    async getAllPosts(platform) {
+    async getAllPosts(platform, cacheOptions = {}) {
         const allPosts = [];
         let currentPage = 1;
         let hasMore = true;
         while (hasMore) {
-            const response = await this.listPosts(currentPage, platform);
+            const response = await this.listPosts(currentPage, platform, cacheOptions);
             // Validate response structure
             if (!response || !Array.isArray(response.data)) {
                 throw new Error(`Invalid API response: expected PostsResponse with data array, got ${typeof response}`);
@@ -96,11 +111,12 @@ class ContentStreamlineAPI {
     /**
      * Get a single post by ID
      */
-    async getPost(id, contentFormat = 'markdown') {
+    async getPost(id, contentFormat = 'markdown', cacheOptions = {}) {
         const format = contentFormat === 'html' ? 'html' : 'markdown';
-        return this.fetch(`/public/v1/posts/${id}?content_format=${format}`);
+        const tags = cacheOptions.tags || ['content-streamline', `post-${id}`];
+        return this.fetch(`/public/v1/posts/${id}?content_format=${format}`, {}, { ...cacheOptions, tags });
     }
 }
-export function createAPIClient(baseUrl, accessToken) {
-    return new ContentStreamlineAPI(baseUrl, accessToken);
+export function createAPIClient(baseUrl, accessToken, defaultRevalidate = 300) {
+    return new ContentStreamlineAPI(baseUrl, accessToken, defaultRevalidate);
 }

package/dist/index.d.ts

@@ -1,9 +1,16 @@
 /**
  * Content Streamline Next.js Library
  * Main entry point
+ *
+ * Features:
+ * - Next.js native caching with automatic revalidation
+ * - Cache tags for on-demand revalidation via revalidateTag()
+ * - Static page generation with ISR support
+ * - Default 5-minute cache TTL (configurable)
  */
 export type { Post, PostDetailResponse, PostTranslation, PostImage, PostsResponse, Pagination, CacheMetadata, } from './types/index.js';
-export { getAllPosts, getPost, getPostBySlug, } from './server/index.js';
+export { getAllPosts, getPost, getPostBySlug, getCacheTags, } from './server/index.js';
+export type { GetAllPostsOptions, GetPostOptions, CacheOptions, } from './server/index.js';
 export { clearCache, isAPIConfigured, } from './cache/file-cache.js';
 export { PostsList, PostDetail, LatestPosts, } from './components/index.js';
 export type { PostsListProps, PostDetailProps, LatestPostsProps, } from './components/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,IAAI,EACJ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,aAAa,EACb,UAAU,EACV,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,OAAO,EACP,aAAa,GACd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,UAAU,EACV,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,YAAY,EACV,IAAI,EACJ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,aAAa,EACb,UAAU,EACV,aAAa,GACd,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,OAAO,EACP,aAAa,EACb,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,YAAY,GACb,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,UAAU,EACV,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,GACZ,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -1,10 +1,16 @@
 /**
  * Content Streamline Next.js Library
  * Main entry point
+ *
+ * Features:
+ * - Next.js native caching with automatic revalidation
+ * - Cache tags for on-demand revalidation via revalidateTag()
+ * - Static page generation with ISR support
+ * - Default 5-minute cache TTL (configurable)
  */
-// Export server functions
-export { getAllPosts, getPost, getPostBySlug, } from './server/index.js';
-// Export cache utilities
+// Export server functions with Next.js caching
+export { getAllPosts, getPost, getPostBySlug, getCacheTags, } from './server/index.js';
+// Export legacy cache utilities (optional, for advanced use)
 export { clearCache, isAPIConfigured, } from './cache/file-cache.js';
 // Export components
 export { PostsList, PostDetail, LatestPosts, } from './components/index.js';

package/dist/server/index.d.ts

@@ -1,44 +1,115 @@
 /**
  * Server-side functions for Next.js
- * Use these in Server Components, API Routes, or getServerSideProps
- */
-import type { Post, PostDetailResponse } from '../types/index.js';
-/**
- * Get all posts (with automatic cache refresh)
- * Use this in Server Components or API Routes
  *
- * Note: Only successful API responses are cached. Failed API calls
- * (network errors, auth failures, etc.) will NOT be cached, allowing
- * subsequent calls to retry the API.
+ * Uses Next.js native caching via fetch() with revalidate options.
+ * This enables:
+ * - Static page generation with ISR (Incremental Static Regeneration)
+ * - Automatic cache revalidation (default: 5 minutes)
+ * - Cache tags for on-demand revalidation via revalidateTag()
+ *
+ * Cache tags used:
+ * - 'content-streamline': All content from this library
+ * - 'posts-list': Post listings
+ * - 'post-{id}': Individual post by ID
  */
-export declare function getAllPosts(options?: {
-    maxCacheAge?: number;
+import type { Post, PostDetailResponse } from '../types/index.js';
+export interface GetAllPostsOptions {
+    /**
+     * Revalidation time in seconds (default: 300 = 5 minutes)
+     * Set to 0 for no caching, or false for infinite cache
+     */
+    revalidate?: number | false;
+    /** Force fresh data, bypassing cache */
     forceRefresh?: boolean;
+    /** Filter by platform: 'x', 'linkedin', 'blog', 'facebook', 'instagram', 'other' */
     platform?: string;
-}): Promise<Post[]>;
+    /** Additional cache tags for on-demand revalidation */
+    tags?: string[];
+}
 /**
- * Get a single post by ID
- * Use this in Server Components or API Routes
+ * Get all posts with Next.js caching
+ *
+ * Uses Next.js fetch caching with automatic revalidation.
+ * Perfect for static page generation with ISR.
  *
- * Note: Only successful API responses are cached. Failed API calls
- * will NOT be cached, allowing subsequent calls to retry the API.
+ * @example
+ * // In a Server Component or page.tsx
+ * const posts = await getAllPosts({ revalidate: 300 }); // 5 min cache
+ *
+ * @example
+ * // Force fresh data
+ * const posts = await getAllPosts({ forceRefresh: true });
+ *
+ * @example
+ * // Revalidate on-demand in an API route
+ * import { revalidateTag } from 'next/cache';
+ * revalidateTag('posts-list');
  */
-export declare function getPost(id: number, options?: {
+export declare function getAllPosts(options?: GetAllPostsOptions): Promise<Post[]>;
+export interface GetPostOptions {
+    /** Language for translation lookup (default: 'en') */
     language?: string;
+    /** Content format: 'markdown' or 'html' (default: 'markdown') */
     contentFormat?: 'markdown' | 'html';
-    maxCacheAge?: number;
+    /**
+     * Revalidation time in seconds (default: 300 = 5 minutes)
+     * Set to 0 for no caching, or false for infinite cache
+     */
+    revalidate?: number | false;
+    /** Force fresh data, bypassing cache */
     forceRefresh?: boolean;
-}): Promise<PostDetailResponse | null>;
+    /** Additional cache tags for on-demand revalidation */
+    tags?: string[];
+}
+/**
+ * Get a single post by ID with Next.js caching
+ *
+ * Uses Next.js fetch caching with automatic revalidation.
+ * Each post has its own cache tag for targeted revalidation.
+ *
+ * @example
+ * // In a Server Component
+ * const post = await getPost(123, { contentFormat: 'html' });
+ *
+ * @example
+ * // Revalidate specific post on-demand
+ * import { revalidateTag } from 'next/cache';
+ * revalidateTag('post-123');
+ */
+export declare function getPost(id: number, options?: GetPostOptions): Promise<PostDetailResponse | null>;
 /**
- * Get post by slug
- * Use this in Server Components or API Routes
+ * Get post by slug with Next.js caching
+ *
+ * Finds a post by its URL slug across all posts.
+ *
+ * @example
+ * // In a dynamic route [slug]/page.tsx
+ * const post = await getPostBySlug(params.slug);
  */
-export declare function getPostBySlug(slug: string, options?: {
-    language?: string;
-    contentFormat?: 'markdown' | 'html';
-    maxCacheAge?: number;
-    forceRefresh?: boolean;
+export declare function getPostBySlug(slug: string, options?: GetPostOptions & {
     platform?: string;
 }): Promise<PostDetailResponse | null>;
+/**
+ * Get cache tags for use with revalidateTag()
+ *
+ * @example
+ * // Revalidate all content
+ * revalidateTag(getCacheTags().all);
+ *
+ * // Revalidate posts list
+ * revalidateTag(getCacheTags().postsList);
+ *
+ * // Revalidate specific post
+ * revalidateTag(getCacheTags().post(123));
+ */
+export declare function getCacheTags(): {
+    /** Tag for all content-streamline data */
+    all: string;
+    /** Tag for posts list */
+    postsList: string;
+    /** Get tag for a specific post by ID */
+    post: (id: number) => string;
+};
 export type { Post, PostDetailResponse, PostTranslation, PostImage, PostsResponse, Pagination, } from '../types/index.js';
+export type { CacheOptions } from '../api/client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,OAAO,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AA+BlE;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,CAAC,EAAE;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAyGlB;AAED;;;;;;GAMG;AACH,wBAAsB,OAAO,CAC3B,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GACA,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAoDpC;AAED;;;GAGG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA2BpC;AAGD,YAAY,EACV,IAAI,EACJ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,aAAa,EACb,UAAU,GACX,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAoBlE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5B,wCAAwC;IACxC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CA2C/E;AAED,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,aAAa,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC5B,wCAAwC;IACxC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAC3B,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAoCpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,cAAc,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CA4BpC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY;IAExB,0CAA0C;;IAE1C,yBAAyB;;IAEzB,wCAAwC;eAC7B,MAAM;EAEpB;AAGD,YAAY,EACV,IAAI,EACJ,kBAAkB,EAClB,eAAe,EACf,SAAS,EACT,aAAa,EACb,UAAU,GACX,MAAM,mBAAmB,CAAC;AAG3B,YAAY,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/server/index.js

@@ -1,9 +1,20 @@
 /**
  * Server-side functions for Next.js
- * Use these in Server Components, API Routes, or getServerSideProps
+ *
+ * Uses Next.js native caching via fetch() with revalidate options.
+ * This enables:
+ * - Static page generation with ISR (Incremental Static Regeneration)
+ * - Automatic cache revalidation (default: 5 minutes)
+ * - Cache tags for on-demand revalidation via revalidateTag()
+ *
+ * Cache tags used:
+ * - 'content-streamline': All content from this library
+ * - 'posts-list': Post listings
+ * - 'post-{id}': Individual post by ID
  */
 import { createAPIClient } from '../api/client.js';
-import { getAllCachedPosts, getCachedPost, cachePost, updatePostsIndex, shouldRefreshCache, } from '../cache/file-cache.js';
+/** Default revalidation time: 5 minutes */
+const DEFAULT_REVALIDATE_SECONDS = 300;
 /**
  * Get API configuration from environment variables
  * Returns null if not configured (instead of throwing)
@@ -17,170 +28,103 @@ function getAPIConfig() {
     return { baseUrl, accessToken };
 }
 /**
- * Get API configuration, throwing if not configured
- * Use this when API is required
- */
-function requireAPIConfig() {
-    const config = getAPIConfig();
-    if (!config) {
-        throw new Error('Missing API configuration. Set CONTENT_STREAMLINE_API_BASE_URL and CONTENT_STREAMLINE_API_ACCESS_TOKEN environment variables.');
-    }
-    return config;
-}
-/**
- * Get all posts (with automatic cache refresh)
- * Use this in Server Components or API Routes
+ * Get all posts with Next.js caching
+ *
+ * Uses Next.js fetch caching with automatic revalidation.
+ * Perfect for static page generation with ISR.
+ *
+ * @example
+ * // In a Server Component or page.tsx
+ * const posts = await getAllPosts({ revalidate: 300 }); // 5 min cache
  *
- * Note: Only successful API responses are cached. Failed API calls
- * (network errors, auth failures, etc.) will NOT be cached, allowing
- * subsequent calls to retry the API.
+ * @example
+ * // Force fresh data
+ * const posts = await getAllPosts({ forceRefresh: true });
+ *
+ * @example
+ * // Revalidate on-demand in an API route
+ * import { revalidateTag } from 'next/cache';
+ * revalidateTag('posts-list');
  */
 export async function getAllPosts(options) {
-    const { maxCacheAge = 15, forceRefresh = false, platform } = options || {};
-    // Check if API is configured
+    const { revalidate = DEFAULT_REVALIDATE_SECONDS, forceRefresh = false, platform, tags = [] } = options || {};
     const apiConfig = getAPIConfig();
-    // Check cache freshness (this also validates cache metadata)
-    if (!forceRefresh) {
-        const needsRefresh = await shouldRefreshCache(maxCacheAge);
-        if (!needsRefresh) {
-            const cached = await getAllCachedPosts();
-            if (cached.length > 0) {
-                // Filter cached posts by platform if specified
-                if (platform) {
-                    const filtered = cached.filter(post => post.platform.toLowerCase() === platform.toLowerCase());
-                    if (filtered.length > 0) {
-                        return filtered;
-                    }
-                }
-                else {
-                    return cached;
-                }
-            }
-        }
-    }
-    // If API is not configured, return empty array but DON'T cache it
     if (!apiConfig) {
         console.warn('Content Streamline: API not configured. Set CONTENT_STREAMLINE_API_BASE_URL and CONTENT_STREAMLINE_API_ACCESS_TOKEN environment variables.');
         return [];
     }
-    // Fetch from API
-    let posts;
+    const cacheOptions = {
+        revalidate: typeof revalidate === 'number' ? revalidate : undefined,
+        forceRefresh,
+        tags: ['content-streamline', 'posts-list', ...tags],
+    };
     try {
-        const api = createAPIClient(apiConfig.baseUrl, apiConfig.accessToken);
-        console.log(`Content Streamline: Fetching posts from API (forceRefresh: ${forceRefresh}, platform: ${platform || 'all'})`);
-        posts = await api.getAllPosts(platform);
-        console.log(`Content Streamline: Successfully fetched ${posts.length} posts from API`);
+        const api = createAPIClient(apiConfig.baseUrl, apiConfig.accessToken, typeof revalidate === 'number' ? revalidate : DEFAULT_REVALIDATE_SECONDS);
+        const posts = await api.getAllPosts(platform, cacheOptions);
+        if (!Array.isArray(posts)) {
+            console.error('Content Streamline: API returned invalid response (not an array)');
+            return [];
+        }
+        return posts;
     }
     catch (error) {
-        // API call failed - DON'T cache the error, just return empty
-        // This allows subsequent calls to retry the API
         const errorMessage = error instanceof Error ? error.message : String(error);
-        console.error('Content Streamline: Failed to fetch posts from API:', errorMessage);
-        if (error instanceof Error && error.stack) {
-            console.error('Content Streamline: Error stack:', error.stack);
-        }
-        // Try to return stale cache if available (better than nothing)
-        const staleCached = await getAllCachedPosts();
-        if (staleCached.length > 0) {
-            console.warn(`Content Streamline: Returning ${staleCached.length} stale cached posts due to API error`);
-            if (platform) {
-                const filtered = staleCached.filter(post => post.platform.toLowerCase() === platform.toLowerCase());
-                return filtered;
-            }
-            return staleCached;
-        }
-        console.warn('Content Streamline: No cached data available, returning empty array');
-        return [];
-    }
-    // Validate that we got posts
-    if (!Array.isArray(posts)) {
-        console.error('Content Streamline: API returned invalid response (not an array):', typeof posts);
+        console.error('Content Streamline: Failed to fetch posts:', errorMessage);
         return [];
     }
-    // API call succeeded - cache the results with success metadata
-    // Note: We cache individual post details, but failures here don't prevent returning the posts
-    let cachedCount = 0;
-    for (const post of posts) {
-        try {
-            const api = createAPIClient(apiConfig.baseUrl, apiConfig.accessToken);
-            const fullPost = await api.getPost(post.id, 'markdown');
-            await cachePost(fullPost);
-            cachedCount++;
-        }
-        catch (error) {
-            // Log but don't fail - we still want to return the posts
-            console.warn(`Content Streamline: Failed to cache full details for post ${post.id}:`, error instanceof Error ? error.message : String(error));
-        }
-    }
-    if (cachedCount > 0) {
-        console.log(`Content Streamline: Cached ${cachedCount} of ${posts.length} posts`);
-    }
-    // Update index with success metadata
-    try {
-        await updatePostsIndex(posts, true);
-    }
-    catch (error) {
-        console.warn('Content Streamline: Failed to update posts index cache (non-fatal):', error instanceof Error ? error.message : String(error));
-    }
-    console.log(`Content Streamline: Returning ${posts.length} posts`);
-    return posts;
 }
 /**
- * Get a single post by ID
- * Use this in Server Components or API Routes
+ * Get a single post by ID with Next.js caching
  *
- * Note: Only successful API responses are cached. Failed API calls
- * will NOT be cached, allowing subsequent calls to retry the API.
+ * Uses Next.js fetch caching with automatic revalidation.
+ * Each post has its own cache tag for targeted revalidation.
+ *
+ * @example
+ * // In a Server Component
+ * const post = await getPost(123, { contentFormat: 'html' });
+ *
+ * @example
+ * // Revalidate specific post on-demand
+ * import { revalidateTag } from 'next/cache';
+ * revalidateTag('post-123');
  */
 export async function getPost(id, options) {
-    const { language = 'en', contentFormat = 'markdown', maxCacheAge = 15, forceRefresh = false, } = options || {};
-    // Check if API is configured
+    const { contentFormat = 'markdown', revalidate = DEFAULT_REVALIDATE_SECONDS, forceRefresh = false, tags = [], } = options || {};
     const apiConfig = getAPIConfig();
-    // Try cache first (cache validation includes metadata checks)
-    if (!forceRefresh) {
-        const needsRefresh = await shouldRefreshCache(maxCacheAge);
-        if (!needsRefresh) {
-            const cached = await getCachedPost(id, language);
-            if (cached) {
-                return cached;
-            }
-        }
-    }
-    // If API is not configured, return null but DON'T cache it
     if (!apiConfig) {
         console.warn('Content Streamline: API not configured. Set CONTENT_STREAMLINE_API_BASE_URL and CONTENT_STREAMLINE_API_ACCESS_TOKEN environment variables.');
         return null;
     }
-    // Fetch from API
+    const cacheOptions = {
+        revalidate: typeof revalidate === 'number' ? revalidate : undefined,
+        forceRefresh,
+        tags: ['content-streamline', `post-${id}`, ...tags],
+    };
     try {
-        const api = createAPIClient(apiConfig.baseUrl, apiConfig.accessToken);
-        const post = await api.getPost(id, contentFormat);
-        // API call succeeded - cache it
-        await cachePost(post);
-        return post;
+        const api = createAPIClient(apiConfig.baseUrl, apiConfig.accessToken, typeof revalidate === 'number' ? revalidate : DEFAULT_REVALIDATE_SECONDS);
+        return await api.getPost(id, contentFormat, cacheOptions);
     }
     catch (error) {
-        // API call failed - DON'T cache the error
-        // Try to return stale cache if available
-        console.error(`Content Streamline: Failed to fetch post ${id}:`, error);
-        const staleCached = await getCachedPost(id, language);
-        if (staleCached) {
-            console.warn(`Content Streamline: Returning stale cached data for post ${id} due to API error`);
-            return staleCached;
-        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.error(`Content Streamline: Failed to fetch post ${id}:`, errorMessage);
         return null;
     }
 }
 /**
- * Get post by slug
- * Use this in Server Components or API Routes
+ * Get post by slug with Next.js caching
+ *
+ * Finds a post by its URL slug across all posts.
+ *
+ * @example
+ * // In a dynamic route [slug]/page.tsx
+ * const post = await getPostBySlug(params.slug);
  */
 export async function getPostBySlug(slug, options) {
-    // First, get all posts to find the one with matching slug
     const posts = await getAllPosts({
-        maxCacheAge: options?.maxCacheAge,
+        revalidate: options?.revalidate,
         forceRefresh: options?.forceRefresh,
         platform: options?.platform,
+        tags: options?.tags,
     });
     const language = options?.language || 'en';
     // Find post with matching slug
@@ -190,10 +134,34 @@ export async function getPostBySlug(slug, options) {
             return getPost(post.id, {
                 language,
                 contentFormat: options?.contentFormat,
-                maxCacheAge: options?.maxCacheAge,
+                revalidate: options?.revalidate,
                 forceRefresh: options?.forceRefresh,
+                tags: options?.tags,
             });
         }
     }
     return null;
 }
+/**
+ * Get cache tags for use with revalidateTag()
+ *
+ * @example
+ * // Revalidate all content
+ * revalidateTag(getCacheTags().all);
+ *
+ * // Revalidate posts list
+ * revalidateTag(getCacheTags().postsList);
+ *
+ * // Revalidate specific post
+ * revalidateTag(getCacheTags().post(123));
+ */
+export function getCacheTags() {
+    return {
+        /** Tag for all content-streamline data */
+        all: 'content-streamline',
+        /** Tag for posts list */
+        postsList: 'posts-list',
+        /** Get tag for a specific post by ID */
+        post: (id) => `post-${id}`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@content-streamline/nextjs",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Next.js library for Content Streamline API with reusable components",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,8 +33,8 @@
   "author": "",
   "license": "MIT",
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "next": "^14.0.0 || ^15.0.0"
+    "next": "^14.0.0 || ^15.0.0",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",