lynkow 2.1.3 → 3.0.0

package/README.md

@@ -8,6 +8,9 @@ Official TypeScript SDK for [Lynkow](https://lynkow.com) Headless CMS.
 - **Type-safe** - Full TypeScript support with comprehensive types
 - **Framework-agnostic** - Works with Next.js, Nuxt, Astro, SvelteKit, etc.
 - **Tree-shakeable** - Only import what you need
+- **Isomorphic** - Works on both browser and server (Node.js, Deno, Bun)
+- **Built-in Analytics** - Page views, events, and funnel tracking
+- **Cookie Consent** - GDPR-compliant consent banner with preferences
 - **Spam protection** - Built-in honeypot fields for form submissions
 
 ## Installation
@@ -23,9 +26,9 @@ pnpm add lynkow
 ## Quick Start
 
 ```typescript
-import { createLynkowClient } from 'lynkow'
+import { createClient } from 'lynkow'
 
-const lynkow = createLynkowClient({
+const lynkow = createClient({
   siteId: 'your-site-uuid',
   locale: 'fr', // optional default locale
 })
@@ -44,7 +47,7 @@ const post = await lynkow.contents.getBySlug('my-article')
 ## Configuration
 
 ```typescript
-interface LynkowConfig {
+interface ClientConfig {
   // Required: Your site UUID
   siteId: string
 
@@ -56,13 +59,16 @@ interface LynkowConfig {
 
   // Optional: Custom fetch options (for Next.js cache, etc.)
   fetchOptions?: RequestInit
+
+  // Optional: Enable debug logging
+  debug?: boolean
 }
 ```
 
 ### Next.js App Router Example
 
 ```typescript
-const lynkow = createLynkowClient({
+const lynkow = createClient({
   siteId: process.env.LYNKOW_SITE_ID!,
   locale: 'fr',
   fetchOptions: {
@@ -71,6 +77,20 @@ const lynkow = createLynkowClient({
 })
 ```
 
+## Browser vs Server
+
+The SDK is isomorphic and works on both browser and server environments. Some features are browser-only:
+
+| Feature | Browser | Server |
+|---------|---------|--------|
+| Contents, Categories, Pages... | ✅ | ✅ |
+| Forms, Reviews | ✅ | ✅ |
+| Analytics tracking | ✅ | ❌ (no-op) |
+| Consent banner | ✅ | ❌ (no-op) |
+| Branding badge | ✅ | ❌ (no-op) |
+| Locale detection | ✅ | ✅ (returns default) |
+| Cache | localStorage | In-memory |
+
 ## Services
 
 ### Contents (Blog Posts)
@@ -133,12 +153,12 @@ const jsonLd = await lynkow.pages.getJsonLd('about')
 
 ```typescript
 // Get site config with all global blocks
-const { data } = await lynkow.blocks.siteConfig()
+const { data } = await lynkow.globals.siteConfig()
 const header = data.globals['header']
 const footer = data.globals['footer']
 
 // Get a specific global block
-const { data: header } = await lynkow.blocks.global('header')
+const { data: header } = await lynkow.globals.global('header')
 ```
 
 ### Forms
@@ -192,16 +212,25 @@ console.log(config.defaultLocale) // 'fr'
 
 ### Legal Documents
 
+Legal documents are pages tagged with `legal`. Use the legal service to retrieve them.
+
 ```typescript
-// List all legal documents
-const { data } = await lynkow.legal.list()
+// List all legal documents (pages with 'legal' tag)
+const docs = await lynkow.legal.list()
+docs.forEach(doc => console.log(doc.slug, doc.name))
 
-// Get specific document
-const privacy = await lynkow.legal.getByType('privacy')
-const terms = await lynkow.legal.getByType('terms')
+// Get specific document by slug
+const privacy = await lynkow.legal.getBySlug('privacy-policy')
+const terms = await lynkow.legal.getBySlug('terms-of-service')
+
+// Access document content and SEO
+console.log(privacy.data.content) // Rich text content
+console.log(privacy.seo?.title)   // SEO meta title
 ```
 
-### Cookie Consent
+### Cookie Consent (Low-level)
+
+For programmatic access to cookie configuration:
 
 ```typescript
 // Get cookie banner config
@@ -246,6 +275,175 @@ if (redirect) {
 }
 ```
 
+## Analytics (Browser-only)
+
+The SDK includes built-in analytics that loads the Lynkow tracker automatically.
+
+```typescript
+// Initialize analytics (called automatically on client creation)
+await lynkow.analytics.init()
+
+// Track page views
+await lynkow.analytics.trackPageview()
+
+// Track with custom data
+await lynkow.analytics.trackPageview({
+  path: '/custom-path',
+  title: 'Custom Title',
+  referrer: 'https://google.com',
+})
+
+// Track custom events
+await lynkow.analytics.trackEvent({
+  type: 'purchase',
+  amount: 99.99,
+  currency: 'EUR',
+})
+
+// Track funnel steps
+await lynkow.analytics.trackFunnelStep({
+  funnelId: 'checkout',
+  funnelName: 'Checkout Flow',
+  stepNumber: 2,
+  stepName: 'payment',
+})
+
+// Enable/disable tracking
+lynkow.analytics.disable()
+lynkow.analytics.enable()
+
+// Check status
+lynkow.analytics.isEnabled()    // true/false
+lynkow.analytics.isInitialized() // true/false
+
+// Access underlying tracker
+const tracker = lynkow.analytics.getTracker()
+```
+
+## Consent Management (Browser-only)
+
+GDPR-compliant cookie consent banner with full UI.
+
+```typescript
+// Show consent banner
+lynkow.consent.show()
+
+// Hide consent banner
+lynkow.consent.hide()
+
+// Show preferences modal (for "Manage cookies" link)
+lynkow.consent.showPreferences()
+
+// Accept all cookies
+lynkow.consent.acceptAll()
+
+// Reject all optional cookies
+lynkow.consent.rejectAll()
+
+// Set specific categories
+lynkow.consent.setCategories({
+  analytics: true,
+  marketing: false,
+  preferences: true,
+})
+
+// Check consent status
+lynkow.consent.hasConsented()  // true if user made a choice
+lynkow.consent.getCategories() // { necessary: true, analytics: true, ... }
+
+// Get consent configuration from API
+const config = await lynkow.consent.getConfig()
+
+// Reset consent (clear stored preferences)
+lynkow.consent.reset()
+```
+
+### Consent Categories
+
+| Category | Description | Can be disabled |
+|----------|-------------|-----------------|
+| `necessary` | Essential cookies | ❌ Always true |
+| `analytics` | Analytics & tracking | ✅ |
+| `marketing` | Advertising cookies | ✅ |
+| `preferences` | User preferences | ✅ |
+
+### Listening to Consent Changes
+
+```typescript
+lynkow.on('consent-changed', (categories) => {
+  console.log('Consent updated:', categories)
+
+  if (categories.analytics) {
+    // Initialize analytics tools
+  }
+})
+```
+
+## Branding (Browser-only)
+
+For sites on the free plan, a "Powered by Lynkow" badge is displayed.
+
+```typescript
+// Manually inject badge (auto-injected if required by plan)
+lynkow.branding.inject()
+
+// Remove badge
+lynkow.branding.remove()
+
+// Check if badge is visible
+lynkow.branding.isVisible() // true/false
+```
+
+## Events
+
+Subscribe to SDK events for reactive updates.
+
+```typescript
+// Subscribe to an event
+const unsubscribe = lynkow.on('consent-changed', (categories) => {
+  console.log('Consent changed:', categories)
+})
+
+// Unsubscribe when done
+unsubscribe()
+```
+
+### Available Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `consent-changed` | `ConsentCategories` | User consent preferences changed |
+| `locale-changed` | `{ locale: string }` | Locale was changed |
+| `ready` | `SiteConfig` | Client fully initialized |
+
+## Locale Management
+
+```typescript
+// Get current locale
+console.log(lynkow.locale) // 'fr'
+
+// Get available locales
+console.log(lynkow.availableLocales) // ['fr', 'en', 'es']
+
+// Change locale
+lynkow.setLocale('en')
+
+// Locale detection (browser-only)
+// Priority: localStorage > URL path > HTML lang > default
+```
+
+## Cache Management
+
+The SDK caches API responses automatically.
+
+```typescript
+// Clear all cached data
+lynkow.clearCache()
+
+// Destroy client and cleanup resources
+lynkow.destroy()
+```
+
 ## Error Handling
 
 ```typescript
@@ -297,18 +495,77 @@ All types are exported for your convenience:
 
 ```typescript
 import type {
+  // Entities
   Content,
   ContentSummary,
   Category,
   Page,
   Form,
   Review,
+  Tag,
+
+  // Config
   LynkowConfig,
+  ClientConfig,
+  SiteConfig,
+
+  // Filters
   ContentsFilters,
-  // ... and many more
+  ReviewsFilters,
+  PaginationOptions,
+
+  // Responses
+  PaginatedResponse,
+  PaginationMeta,
+
+  // Analytics
+  PageviewData,
+  EventData,
+  FunnelStepData,
+
+  // Consent
+  ConsentCategories,
+  CookieConfig,
+
+  // Events
+  EventName,
+  LynkowEvents,
 } from 'lynkow'
 ```
 
+## Migration from v2.x
+
+### Breaking Changes
+
+1. **Factory function renamed**: `createLynkowClient` → `createClient` (alias still available)
+2. **Blocks service renamed**: `blocks` → `globals` (alias still available)
+3. **New browser-only modules**: `analytics`, `consent`, `branding`
+
+### New Features in v3
+
+- Analytics tracking with automatic tracker.js loading
+- GDPR consent banner with preferences UI
+- Event system for reactive updates
+- Locale detection and management
+- Built-in caching (localStorage in browser, memory on server)
+- Debug logging option
+
+### Upgrade Steps
+
+```typescript
+// v2.x
+import { createLynkowClient } from 'lynkow'
+const lynkow = createLynkowClient({ siteId: '...' })
+
+// v3.x (recommended)
+import { createClient } from 'lynkow'
+const lynkow = createClient({ siteId: '...', debug: true })
+
+// v3.x also supports the old name for backward compatibility
+import { createLynkowClient } from 'lynkow'
+const lynkow = createLynkowClient({ siteId: '...' })
+```
+
 ## License
 
 Proprietary - See [LICENSE](./LICENSE) for details.