lynkow 3.6.0 → 3.6.2

package/README.md

@@ -65,18 +65,63 @@ interface ClientConfig {
 }
 ```
 
-### Next.js App Router Example
+### Next.js App Router Caching
+
+> **Important**: By default, Next.js App Router caches all `fetch()` requests **indefinitely**. This means content updates in Lynkow won't appear until you redeploy or clear the cache.
+
+You must configure `fetchOptions` to control caching behavior:
+
+#### Option 1: No Cache (Always Fresh)
+
+Best for frequently updated content or during development:
+
+```typescript
+const lynkow = createClient({
+  siteId: process.env.LYNKOW_SITE_ID!,
+  fetchOptions: {
+    cache: 'no-store', // Disable Next.js fetch cache entirely
+  },
+})
+```
+
+#### Option 2: Time-based Revalidation (ISR)
+
+Best for production with occasional updates:
+
+```typescript
+const lynkow = createClient({
+  siteId: process.env.LYNKOW_SITE_ID!,
+  fetchOptions: {
+    next: { revalidate: 60 }, // Revalidate every 60 seconds
+  },
+})
+```
+
+#### Option 3: On-Demand Revalidation
+
+For precise cache control, use Next.js [on-demand revalidation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation):
 
 ```typescript
+// lib/lynkow.ts
 const lynkow = createClient({
   siteId: process.env.LYNKOW_SITE_ID!,
-  locale: 'fr',
   fetchOptions: {
-    next: { revalidate: 60 }, // ISR: revalidate every 60 seconds
+    next: { tags: ['lynkow'] }, // Tag all requests
   },
 })
+
+// app/api/revalidate/route.ts
+import { revalidateTag } from 'next/cache'
+
+export async function POST(request: Request) {
+  // Verify webhook secret here
+  revalidateTag('lynkow')
+  return Response.json({ revalidated: true })
+}
 ```
 
+Then configure a webhook in Lynkow to call your revalidate endpoint when content changes.
+
 ## Browser vs Server
 
 The SDK is isomorphic and works on both browser and server environments. Some features are browser-only:
@@ -522,13 +567,328 @@ console.log(lynkow.locale) // 'fr'
 // Get available locales
 console.log(lynkow.availableLocales) // ['fr', 'en', 'es']
 
-// Change locale
+// Change locale (browser-only)
 lynkow.setLocale('en')
 
 // Locale detection (browser-only)
 // Priority: localStorage > URL path > HTML lang > default
 ```
 
+## Next.js App Router Integration
+
+The SDK works seamlessly with Next.js App Router, but there are important patterns to follow for Server Components and internationalization.
+
+### Basic Setup
+
+```typescript
+// lib/lynkow.ts
+import { createClient } from 'lynkow'
+
+export const lynkow = createClient({
+  siteId: process.env.NEXT_PUBLIC_LYNKOW_SITE_ID!,
+})
+```
+
+### Server Components
+
+In Server Components, you can fetch data directly:
+
+```typescript
+// app/page.tsx
+import { lynkow } from '@/lib/lynkow'
+
+export default async function HomePage() {
+  const page = await lynkow.pages.getByPath('/')
+
+  return (
+    <main>
+      <h1>{page.data.title}</h1>
+    </main>
+  )
+}
+```
+
+### Internationalization (i18n)
+
+The SDK supports multi-language content via the `locale` option. There are two main approaches:
+
+#### Approach 1: Cookie-based Locale (Recommended)
+
+This approach uses a cookie to store the user's language preference. The locale is managed entirely via cookie, not URL.
+
+**1. Read the cookie in Server Components:**
+
+```typescript
+// app/page.tsx
+import { cookies } from 'next/headers'
+import { lynkow } from '@/lib/lynkow'
+
+export default async function HomePage() {
+  // Read locale from cookie
+  const cookieStore = await cookies()
+  const localeCookie = cookieStore.get('_lkw_lang')
+
+  // Get site config for default locale and i18n settings
+  const siteConfig = await lynkow.site.getConfig()
+  const locale = localeCookie?.value || siteConfig.defaultLocale || 'fr'
+
+  // Fetch content with the correct locale
+  const page = await lynkow.pages.getByPath('/', { locale })
+
+  return (
+    <main>
+      <h1>{page.data.title}</h1>
+      <LanguageSwitcher
+        i18n={siteConfig.i18n}
+        currentLocale={locale}
+      />
+    </main>
+  )
+}
+```
+
+**2. Create a Language Switcher component:**
+
+```typescript
+// components/LanguageSwitcher.tsx
+'use client'
+
+import Cookies from 'js-cookie'
+import type { I18nConfig } from 'lynkow'
+
+interface LanguageSwitcherProps {
+  i18n: I18nConfig
+  currentLocale: string
+}
+
+export function LanguageSwitcher({ i18n, currentLocale }: LanguageSwitcherProps) {
+  // Don't render if only one locale
+  if (!i18n.switcher || i18n.locales.length <= 1) {
+    return null
+  }
+
+  const handleLocaleChange = (localeCode: string) => {
+    if (localeCode === currentLocale) return
+
+    // Set cookie with locale preference
+    Cookies.set(i18n.detection.cookieName, localeCode, {
+      expires: i18n.detection.cookieMaxAge,
+      sameSite: 'lax',
+    })
+
+    // Reload page to fetch content in new locale
+    window.location.reload()
+  }
+
+  const currentLocaleInfo = i18n.locales.find(l => l.code === currentLocale)
+
+  return (
+    <select
+      value={currentLocale}
+      onChange={(e) => handleLocaleChange(e.target.value)}
+    >
+      {i18n.locales.map((locale) => (
+        <option key={locale.code} value={locale.code}>
+          {locale.flag} {locale.name}
+        </option>
+      ))}
+    </select>
+  )
+}
+```
+
+**3. Install js-cookie for client-side cookie management:**
+
+```bash
+npm install js-cookie
+npm install -D @types/js-cookie
+```
+
+#### Approach 2: URL-based Locale (with Next.js i18n)
+
+For URL-based routing like `/en/about`, `/fr/about`, use Next.js built-in i18n:
+
+```typescript
+// next.config.js
+module.exports = {
+  i18n: {
+    locales: ['fr', 'en', 'es'],
+    defaultLocale: 'fr',
+  },
+}
+```
+
+Then access locale from params:
+
+```typescript
+// app/[locale]/page.tsx
+import { lynkow } from '@/lib/lynkow'
+
+interface Props {
+  params: { locale: string }
+}
+
+export default async function HomePage({ params }: Props) {
+  const page = await lynkow.pages.getByPath('/', { locale: params.locale })
+
+  return <h1>{page.data.title}</h1>
+}
+```
+
+### Site Configuration & i18n Data
+
+The `site.getConfig()` method returns all i18n information needed for language switching:
+
+```typescript
+const config = await lynkow.site.getConfig()
+
+// Flat fields for simple usage
+console.log(config.defaultLocale)   // 'fr'
+console.log(config.enabledLocales)  // ['fr', 'en']
+
+// Rich i18n config for building UI
+console.log(config.i18n)
+// {
+//   enabled: true,
+//   default: 'fr',
+//   locales: [
+//     { code: 'fr', name: 'Français', flag: '🇫🇷' },
+//     { code: 'en', name: 'English', flag: '🇬🇧' }
+//   ],
+//   switcher: true,
+//   detection: {
+//     enabled: true,
+//     order: ['cookie', 'browser'],
+//     cookieName: '_lkw_lang',
+//     cookieMaxAge: 365
+//   }
+// }
+```
+
+### Complete Example: Internationalized Page
+
+Here's a complete example of a multi-language page with language switcher:
+
+```typescript
+// app/page.tsx
+import { cookies } from 'next/headers'
+import { lynkow } from '@/lib/lynkow'
+import { LanguageSwitcher } from '@/components/LanguageSwitcher'
+import { HomeContent } from './HomeContent'
+
+// Default content as fallback
+const defaultContent = {
+  title: 'Welcome',
+  description: 'Default description',
+}
+
+const defaultI18n = {
+  enabled: false,
+  default: 'en',
+  locales: [{ code: 'en', name: 'English', flag: '🇬🇧' }],
+  switcher: false,
+  detection: {
+    enabled: false,
+    order: [] as string[],
+    cookieName: '_lkw_lang',
+    cookieMaxAge: 365
+  },
+}
+
+export default async function HomePage() {
+  let content = defaultContent
+  let i18n = defaultI18n
+  let currentLocale = 'en'
+
+  // Read locale preference from cookie
+  const cookieStore = await cookies()
+  const localeCookie = cookieStore.get('_lkw_lang')
+
+  try {
+    // 1. Get site config (includes i18n settings)
+    const siteConfig = await lynkow.site.getConfig()
+    if (siteConfig?.i18n) {
+      i18n = siteConfig.i18n
+      currentLocale = localeCookie?.value || siteConfig.defaultLocale || 'en'
+    }
+
+    // 2. Fetch page content with locale
+    const page = await lynkow.pages.getByPath('/', { locale: currentLocale })
+    if (page?.data) {
+      content = {
+        title: page.data.title as string || defaultContent.title,
+        description: page.data.description as string || defaultContent.description,
+      }
+    }
+
+    // Update locale from actual page response
+    if (page?.locale) {
+      currentLocale = page.locale
+    }
+  } catch (error) {
+    console.error('Failed to fetch content:', error)
+  }
+
+  return (
+    <div>
+      <header>
+        <LanguageSwitcher i18n={i18n} currentLocale={currentLocale} />
+      </header>
+      <main>
+        <HomeContent content={content} />
+      </main>
+    </div>
+  )
+}
+```
+
+### Important Notes
+
+1. **Server Components are stateless**: The SDK client doesn't maintain state between requests. Always pass `{ locale }` explicitly to API calls.
+
+2. **Cookie reading requires `cookies()`**: Use `next/headers` to read cookies in Server Components. This automatically makes the route dynamic.
+
+3. **Client-side locale changes**: When the user changes language, set the cookie and reload the page. The server will read the new cookie value.
+
+4. **No automatic locale detection on server**: The SDK's `setLocale()` and locale detection only work in the browser. On the server, you must read the locale from cookies/URL and pass it to API calls.
+
+5. **Page alternates**: Each page response includes `alternates` with links to other language versions:
+   ```typescript
+   const page = await lynkow.pages.getByPath('/')
+   console.log(page.alternates)
+   // [
+   //   { locale: 'fr', path: '/', current: true },
+   //   { locale: 'en', path: '/', current: false }
+   // ]
+   ```
+
+### TypeScript Types for i18n
+
+```typescript
+import type { I18nConfig, LocaleInfo, SiteConfig } from 'lynkow'
+
+// LocaleInfo
+interface LocaleInfo {
+  code: string   // 'fr', 'en'
+  name: string   // 'Français', 'English'
+  flag: string   // '🇫🇷', '🇬🇧'
+}
+
+// I18nConfig
+interface I18nConfig {
+  enabled: boolean
+  default: string
+  locales: LocaleInfo[]
+  switcher: boolean
+  detection: {
+    enabled: boolean
+    order: string[]
+    cookieName: string
+    cookieMaxAge: number
+  }
+}
+```
+
 ## Cache Management
 
 The SDK caches API responses automatically.
@@ -652,6 +1012,12 @@ import type {
 - **Content enhancements**: Code block copy buttons, text alignment CSS fixes
 - Automatic binding with MutationObserver for dynamic content
 
+### New in v3.6
+
+- **i18n types**: Added `I18nConfig` and `LocaleInfo` types for building language switchers
+- **Site config alignment**: API now returns both flat fields (`defaultLocale`, `enabledLocales`) and rich `i18n` object
+- **Next.js App Router documentation**: Comprehensive guide for Server Components and cookie-based i18n
+
 ### Upgrade Steps
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lynkow",
-  "version": "3.6.0",
+  "version": "3.6.2",
   "description": "Official SDK for Lynkow Headless",
   "author": "Lynkow",
   "license": "SEE LICENSE IN LICENSE",