lynkow 2.1.3 → 3.0.0

package/dist/index.d.mts

@@ -1,3 +1,28 @@
+/**
+ * Cache manager for Lynkow SDK
+ * Uses memory cache on server, localStorage on browser
+ */
+/**
+ * Cache configuration
+ */
+interface CacheConfig {
+    /** Default TTL in milliseconds (default: 5 minutes) */
+    defaultTtl?: number;
+    /** Storage key prefix */
+    prefix?: string;
+}
+/**
+ * Create a cache manager
+ */
+declare function createCache(config?: CacheConfig): {
+    get: <T>(key: string) => T | null;
+    set: <T>(key: string, value: T, ttl?: number) => void;
+    remove: (key: string) => void;
+    invalidate: (pattern?: string) => void;
+    getOrSet: <T>(key: string, factory: () => Promise<T>, ttl?: number) => Promise<T>;
+};
+type Cache = ReturnType<typeof createCache>;
+
 /**
  * Normalized internal configuration
  */
@@ -6,12 +31,15 @@ interface InternalConfig {
     baseUrl: string;
     locale?: string;
     fetchOptions: RequestInit;
+    /** Optional cache manager for caching responses */
+    cache?: Cache;
 }
 /**
  * Base service that all specific services inherit from
  */
 declare abstract class BaseService {
     protected config: InternalConfig;
+    protected cache?: Cache;
     constructor(config: InternalConfig);
     /**
      * Builds the full URL for an endpoint
@@ -21,6 +49,23 @@ declare abstract class BaseService {
      * Performs a GET request
      */
     protected get<T>(path: string, query?: Record<string, unknown>, options?: BaseRequestOptions): Promise<T>;
+    /**
+     * Performs a cached GET request
+     * If cache is available and data exists, returns cached data
+     * Otherwise fetches from API and caches the result
+     *
+     * @param cacheKey - Unique cache key
+     * @param path - API endpoint path
+     * @param query - Query parameters
+     * @param options - Request options
+     * @param ttl - Cache TTL in milliseconds (default: SHORT)
+     */
+    protected getWithCache<T>(cacheKey: string, path: string, query?: Record<string, unknown>, options?: BaseRequestOptions, ttl?: number): Promise<T>;
+    /**
+     * Invalidates cache entries matching a pattern
+     * @param pattern - Pattern to match cache keys
+     */
+    protected invalidateCache(pattern?: string): void;
     /**
      * Performs a POST request
      */
@@ -69,6 +114,10 @@ declare class ContentsService extends BaseService {
      * ```
      */
     getBySlug(slug: string, options?: BaseRequestOptions): Promise<Content>;
+    /**
+     * Clear contents cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -116,6 +165,10 @@ declare class CategoriesService extends BaseService {
      * ```
      */
     getBySlug(slug: string, options?: CategoryOptions & BaseRequestOptions): Promise<CategoryDetailResponse>;
+    /**
+     * Clear categories cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -134,8 +187,19 @@ declare class TagsService extends BaseService {
      * ```
      */
     list(options?: BaseRequestOptions): Promise<TagsListResponse>;
+    /**
+     * Clear tags cache
+     */
+    clearCache(): void;
 }
 
+/**
+ * Options for listing pages
+ */
+interface PagesListOptions extends BaseRequestOptions {
+    /** Filter pages by tag (e.g., 'legal' for legal documents) */
+    tag?: string;
+}
 /**
  * Service for pages (Site Blocks of type "page")
  */
@@ -143,15 +207,19 @@ declare class PagesService extends BaseService {
     /**
      * Retrieves the list of published pages
      *
-     * @param options - Request options (locale)
+     * @param options - Request options (locale, tag filter)
      * @returns List of pages
      *
      * @example
      * ```typescript
+     * // List all pages
      * const { data } = await lynkow.pages.list()
+     *
+     * // List legal documents
+     * const { data } = await lynkow.pages.list({ tag: 'legal' })
      * ```
      */
-    list(options?: BaseRequestOptions): Promise<PagesListResponse>;
+    list(options?: PagesListOptions): Promise<PagesListResponse>;
     /**
      * Retrieves a page by its slug
      *
@@ -192,10 +260,15 @@ declare class PagesService extends BaseService {
      * ```
      */
     getJsonLd(slug: string, options?: BaseRequestOptions): Promise<Record<string, unknown>>;
+    /**
+     * Clear pages cache
+     */
+    clearCache(): void;
 }
 
 /**
  * Service for global blocks (header, footer, etc.)
+ * Also aliased as `globals` in the client
  */
 declare class BlocksService extends BaseService {
     /**
@@ -206,7 +279,7 @@ declare class BlocksService extends BaseService {
      *
      * @example
      * ```typescript
-     * const { data } = await lynkow.blocks.siteConfig()
+     * const { data } = await lynkow.globals.siteConfig()
      * const header = data.globals['header']
      * const footer = data.globals['footer']
      * ```
@@ -221,11 +294,19 @@ declare class BlocksService extends BaseService {
      *
      * @example
      * ```typescript
-     * const { data } = await lynkow.blocks.global('header')
+     * const { data } = await lynkow.globals.getBySlug('header')
      * // data.data contient les donnees du bloc
      * ```
      */
+    getBySlug(slug: string, options?: BaseRequestOptions): Promise<GlobalBlockResponse>;
+    /**
+     * @deprecated Use `getBySlug()` instead
+     */
     global(slug: string, options?: BaseRequestOptions): Promise<GlobalBlockResponse>;
+    /**
+     * Clear globals cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -270,6 +351,10 @@ declare class FormsService extends BaseService {
      * ```
      */
     submit(slug: string, data: FormSubmitData, options?: SubmitOptions & BaseRequestOptions): Promise<FormSubmitResponse>;
+    /**
+     * Clear forms cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -342,6 +427,10 @@ declare class ReviewsService extends BaseService {
      * ```
      */
     submit(data: ReviewSubmitData, options?: SubmitOptions & BaseRequestOptions): Promise<ReviewSubmitResponse>;
+    /**
+     * Clear reviews cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -360,42 +449,68 @@ declare class SiteService extends BaseService {
      * ```
      */
     getConfig(): Promise<SiteConfig>;
+    /**
+     * Clear site configuration cache
+     */
+    clearCache(): void;
 }
 
 /**
- * Service for legal documents
+ * Service for accessing legal documents (pages tagged with 'legal')
+ *
+ * @deprecated Use `pages.list({ tag: 'legal' })` and `pages.getBySlug(slug)` instead.
+ * This service will be removed in the next major version.
+ *
+ * @remarks
+ * Legal documents are now regular pages with the 'legal' tag.
+ * This service provides convenience methods to access them.
+ *
+ * @example
+ * ```typescript
+ * // Deprecated:
+ * const docs = await sdk.legal.list()
+ * const privacy = await sdk.legal.getBySlug('privacy-policy')
+ *
+ * // Recommended:
+ * const docs = await sdk.pages.list({ tag: 'legal' })
+ * const privacy = await sdk.pages.getBySlug('privacy-policy')
+ * ```
  */
 declare class LegalService extends BaseService {
     /**
-     * Retrieves the list of legal documents
+     * List all legal pages
      *
-     * @param options - Request options (locale)
-     * @returns List of available documents
+     * @deprecated Use `pages.list({ tag: 'legal' })` instead
      *
-     * @example
-     * ```typescript
-     * const { data } = await lynkow.legal.list()
-     * ```
+     * Returns all published pages that have the 'legal' tag.
+     *
+     * @param options - Request options (locale)
+     * @returns Array of legal documents
      */
-    list(options?: BaseRequestOptions): Promise<LegalListResponse>;
+    list(options?: BaseRequestOptions): Promise<LegalDocument[]>;
     /**
-     * Retrieves a legal document by its type
+     * Get a specific legal page by slug
      *
-     * @param type - Document type ('terms', 'privacy', etc.)
-     * @param options - Request options (locale)
-     * @returns Full legal document
+     * @deprecated Use `pages.getBySlug(slug)` instead
      *
-     * @example
-     * ```typescript
-     * const privacy = await lynkow.legal.getByType('privacy')
-     * // privacy.content contient le HTML
-     * ```
+     * @param slug - The page slug (e.g., 'privacy-policy', 'terms-of-service')
+     * @param options - Request options (locale)
+     * @returns The legal document
+     * @throws {LynkowError} If the document doesn't exist (404)
+     */
+    getBySlug(slug: string, options?: BaseRequestOptions): Promise<LegalDocument>;
+    /**
+     * Clear legal documents cache
      */
-    getByType(type: LegalDocumentType, options?: BaseRequestOptions): Promise<LegalDocument>;
+    clearCache(): void;
 }
 
 /**
  * Service for cookie consent
+ *
+ * @remarks
+ * This service will be expanded into the `consent` module in v3
+ * with banner UI and preferences modal support.
  */
 declare class CookiesService extends BaseService {
     /**
@@ -428,6 +543,10 @@ declare class CookiesService extends BaseService {
      * ```
      */
     logConsent(preferences: CookiePreferences, options?: BaseRequestOptions): Promise<ConsentLogResponse>;
+    /**
+     * Clear cookies configuration cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -527,6 +646,10 @@ declare class PathsService extends BaseService {
      * ```
      */
     matchRedirect(path: string, options?: BaseRequestOptions): Promise<Redirect | null>;
+    /**
+     * Clear paths cache
+     */
+    clearCache(): void;
 }
 
 /**
@@ -981,35 +1104,36 @@ interface SiteConfig {
     enabledLocales: string[];
     /** Additional settings */
     settings: Record<string, unknown>;
+    /** Show branding badge (free plan) */
+    showBranding: boolean;
 }
 
 /**
- * Legal document types
- */
-type LegalDocumentType = 'terms' | 'privacy' | 'cookies' | 'legal-notice' | 'refund' | 'shipping';
-/**
- * Legal document summary
- */
-interface LegalDocumentSummary {
-    /** Document type */
-    type: LegalDocumentType;
-    /** Title */
-    title: string;
-    /** Update date */
-    updatedAt: string;
-}
-/**
- * Full legal document
+ * A legal document (page tagged with 'legal')
+ *
+ * @remarks
+ * Legal documents are now regular pages with the 'legal' tag.
+ * This provides more flexibility in content structure and SEO.
  */
-interface LegalDocument extends LegalDocumentSummary {
-    /** HTML content */
-    content: string;
-    /** Locale */
+interface LegalDocument {
+    /** Unique identifier */
+    id: string;
+    /** URL-friendly identifier */
+    slug: string;
+    /** Display name */
+    name: string;
+    /** Locale of the document */
     locale: string;
-    /** Document version */
-    version: string;
-    /** Effective date */
-    effectiveDate: string;
+    /** Document content (schema-dependent) */
+    data: Record<string, unknown>;
+    /** SEO metadata */
+    seo?: {
+        title?: string | null;
+        description?: string | null;
+        ogImage?: string | null;
+    } | null;
+    /** Last update timestamp */
+    updatedAt: string;
 }
 
 /**
@@ -1209,12 +1333,6 @@ interface ReviewSubmitResponse {
     status: 'success' | 'pending';
     reviewId?: number;
 }
-/**
- * Legal documents list response
- */
-interface LegalListResponse {
-    data: LegalDocumentSummary[];
-}
 /**
  * Consent log response
  */
@@ -1322,63 +1440,534 @@ interface SubmitOptions {
 }
 
 /**
- * Error codes
+ * Checks if a resolution response is a content
  */
-type ErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'VALIDATION_ERROR' | 'TOO_MANY_REQUESTS' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE' | 'NETWORK_ERROR';
+declare function isContentResolve(response: ResolveResponse): response is ContentResolveResponse;
 /**
- * Error detail
+ * Checks if a resolution response is a category
  */
-interface ApiErrorDetail {
-    /** Error message */
-    message: string;
-    /** Concerned field (for validation errors) */
-    field?: string;
-    /** Specific error code */
-    code?: string;
+declare function isCategoryResolve(response: ResolveResponse): response is CategoryResolveResponse;
+
+/**
+ * Analytics module for Lynkow SDK
+ *
+ * Browser-only module that loads and wraps the Lynkow tracker.js
+ * All methods are no-op on server.
+ */
+
+/**
+ * Data for tracking pageviews
+ */
+interface PageviewData {
+    /** Page path (default: window.location.pathname) */
+    path?: string;
+    /** Page title (default: document.title) */
+    title?: string;
+    /** Referrer URL */
+    referrer?: string;
+}
+/**
+ * Data for tracking custom events
+ */
+interface EventData {
+    /** Event type */
+    type: string;
+    /** Additional event data */
+    [key: string]: unknown;
+}
+/**
+ * Funnel step data
+ */
+interface FunnelStepData {
+    /** Funnel identifier */
+    funnelId: string;
+    /** Step number (1-based) */
+    stepNumber: number;
+    /** Step name */
+    stepName: string;
+    /** Funnel name (optional) */
+    funnelName?: string;
+}
+/**
+ * LynkowAnalytics global interface (from tracker.js)
+ */
+interface LynkowAnalyticsGlobal {
+    init: (siteId: string, options?: {
+        endpoint?: string;
+    }) => void;
+    track: (event: Record<string, unknown>) => void;
+    trackFunnel: (funnelId: string, stepNumber: number, stepName: string, funnelName?: string) => void;
+}
+declare global {
+    interface Window {
+        LynkowAnalytics?: LynkowAnalyticsGlobal;
+    }
+}
+/**
+ * Analytics service that loads and wraps the Lynkow tracker.js
+ *
+ * Browser-only. All methods are no-op on server.
+ */
+declare class AnalyticsService {
+    private config;
+    private enabled;
+    private initialized;
+    private loading;
+    private loadPromise;
+    constructor(config: InternalConfig);
+    /**
+     * Get the tracker script URL
+     */
+    private getTrackerUrl;
+    /**
+     * Load the tracker.js script
+     */
+    private loadTracker;
+    /**
+     * Initialize analytics tracking
+     * Loads the tracker.js script and initializes it
+     */
+    init(): Promise<void>;
+    /**
+     * Track a custom event
+     *
+     * @example
+     * ```typescript
+     * lynkow.analytics.trackEvent({
+     *   type: 'purchase',
+     *   productId: 'abc123',
+     *   amount: 99.99
+     * })
+     * ```
+     */
+    trackEvent(event: EventData): Promise<void>;
+    /**
+     * Track a funnel step
+     *
+     * @example
+     * ```typescript
+     * lynkow.analytics.trackFunnelStep({
+     *   funnelId: 'checkout',
+     *   stepNumber: 2,
+     *   stepName: 'payment',
+     *   funnelName: 'Checkout Flow'
+     * })
+     * ```
+     */
+    trackFunnelStep(data: FunnelStepData): Promise<void>;
+    /**
+     * Track a pageview manually
+     * Note: The tracker automatically tracks pageviews, this is for SPA navigation
+     *
+     * @example
+     * ```typescript
+     * // After SPA navigation
+     * lynkow.analytics.trackPageview({ path: '/new-page' })
+     * ```
+     */
+    trackPageview(data?: PageviewData): Promise<void>;
+    /**
+     * Enable analytics tracking
+     */
+    enable(): void;
+    /**
+     * Disable analytics tracking
+     */
+    disable(): void;
+    /**
+     * Check if analytics is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if tracker is loaded and initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the underlying LynkowAnalytics global object
+     * For advanced usage when you need direct access to the tracker
+     */
+    getTracker(): LynkowAnalyticsGlobal | undefined;
+    /**
+     * Clean up resources (removes the tracker script)
+     */
+    destroy(): void;
 }
 
 /**
- * Lynkow SDK specific error
+ * Simple event emitter for Lynkow SDK
  */
-declare class LynkowError extends Error {
-    /** HTTP status code */
-    status: number;
-    /** Error code */
-    code: ErrorCode;
-    /** List of detailed errors */
-    errors: ApiErrorDetail[];
-    constructor(status: number, code: ErrorCode, message: string, errors?: ApiErrorDetail[]);
+/**
+ * Event types for the SDK
+ */
+interface LynkowEvents {
+    ready: void;
+    'locale-changed': string;
+    'consent-changed': Record<string, boolean>;
+    error: Error;
 }
+type EventName = keyof LynkowEvents;
+/**
+ * Event listener function type
+ */
+type EventListener<T> = (data: T) => void;
+/**
+ * Create an event emitter
+ */
+declare function createEventEmitter(): {
+    on: <K extends EventName>(event: K, listener: EventListener<LynkowEvents[K]>) => () => void;
+    off: <K extends EventName>(event: K, listener: EventListener<LynkowEvents[K]>) => void;
+    emit: <K extends EventName>(event: K, data: LynkowEvents[K]) => void;
+    once: <K extends EventName>(event: K, listener: EventListener<LynkowEvents[K]>) => () => void;
+    removeAllListeners: (event?: EventName) => void;
+};
+type EventEmitter = ReturnType<typeof createEventEmitter>;
 
 /**
- * Checks if a resolution response is a content
+ * Consent module for Lynkow SDK
+ *
+ * Hybrid module: API everywhere + UI browser-only
  */
-declare function isContentResolve(response: ResolveResponse): response is ContentResolveResponse;
+
 /**
- * Checks if a resolution response is a category
+ * Consent categories
  */
-declare function isCategoryResolve(response: ResolveResponse): response is CategoryResolveResponse;
+interface ConsentCategories {
+    /** Always true, not modifiable */
+    necessary: boolean;
+    /** Analytics cookies */
+    analytics: boolean;
+    /** Marketing cookies */
+    marketing: boolean;
+    /** Preference cookies */
+    preferences: boolean;
+}
 /**
- * Checks if an error is a Lynkow error
+ * Consent service for cookie consent management
+ *
+ * Provides:
+ * - API methods that work everywhere (getConfig, logConsent)
+ * - UI methods that work only in browser (show, hide, acceptAll, etc.)
+ */
+declare class ConsentService {
+    private config;
+    private events;
+    private bannerElement;
+    private preferencesElement;
+    private configCache;
+    constructor(config: InternalConfig, events: EventEmitter);
+    /**
+     * Get cookie consent configuration from API
+     */
+    getConfig(): Promise<CookieConfig>;
+    /**
+     * Log consent to server
+     */
+    logConsent(preferences: CookiePreferences): Promise<void>;
+    private getStoredConsent;
+    private saveConsent;
+    /**
+     * Show the consent banner
+     */
+    show(): void;
+    /**
+     * Hide the consent banner
+     */
+    hide(): void;
+    /**
+     * Show the preferences modal
+     */
+    showPreferences(): void;
+    /**
+     * Get current consent categories
+     */
+    getCategories(): ConsentCategories;
+    /**
+     * Check if user has already consented
+     */
+    hasConsented(): boolean;
+    /**
+     * Accept all cookies
+     */
+    acceptAll(): void;
+    /**
+     * Reject all optional cookies
+     */
+    rejectAll(): void;
+    /**
+     * Set specific consent categories
+     */
+    setCategories(categories: Partial<ConsentCategories>): void;
+    /**
+     * Reset consent and show banner again
+     */
+    reset(): void;
+    private createBannerHTML;
+    private createPreferencesHTML;
+    private attachBannerEvents;
+    private attachPreferencesEvents;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Branding module for Lynkow SDK
+ *
+ * Browser-only module. Displays "Powered by Lynkow" badge for free plan users.
+ */
+/**
+ * Branding service for "Powered by Lynkow" badge
+ *
+ * Browser-only. All methods are no-op on server.
+ */
+declare class BrandingService {
+    private badgeElement;
+    /**
+     * Inject styles into document head
+     */
+    private injectStyles;
+    /**
+     * Inject the branding badge into the page
+     */
+    inject(): void;
+    /**
+     * Remove the branding badge from the page
+     */
+    remove(): void;
+    /**
+     * Check if the badge is currently visible
+     */
+    isVisible(): boolean;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}
+
+/**
+ * Lynkow SDK Client
+ * Main entry point for the SDK
  */
-declare function isLynkowError(error: unknown): error is LynkowError;
 
 /**
- * Creates a Lynkow client instance
+ * Extended configuration for SDK v3
+ */
+interface ClientConfig extends LynkowConfig {
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Extended client interface for SDK v3
+ */
+interface Client extends LynkowClient {
+    /**
+     * Current locale
+     */
+    readonly locale: string;
+    /**
+     * Available locales from site configuration
+     */
+    readonly availableLocales: string[];
+    /**
+     * Client configuration (readonly)
+     */
+    readonly config: Readonly<{
+        siteId: string;
+        baseUrl: string;
+        debug: boolean;
+    }>;
+    /**
+     * Set the current locale
+     * @param locale - New locale to use
+     */
+    setLocale(locale: string): void;
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void;
+    /**
+     * Destroy the client and clean up resources
+     */
+    destroy(): void;
+    /**
+     * Subscribe to an event
+     * @param event - Event name
+     * @param listener - Event listener
+     * @returns Unsubscribe function
+     */
+    on<K extends EventName>(event: K, listener: (data: LynkowEvents[K]) => void): () => void;
+    /**
+     * Alias for blocks (v3 naming)
+     * @deprecated Use `globals` instead in v3
+     */
+    blocks: BlocksService;
+    /**
+     * Global blocks service (v3 naming)
+     */
+    globals: BlocksService;
+    /**
+     * Analytics service (browser-only)
+     */
+    analytics: AnalyticsService;
+    /**
+     * Consent service (cookie consent management)
+     */
+    consent: ConsentService;
+    /**
+     * Branding service (badge for free plan)
+     */
+    branding: BrandingService;
+}
+/**
+ * Creates a Lynkow client instance (SDK v3)
  *
  * @param config - Client configuration
  * @returns Client instance with all services
  *
  * @example
  * ```typescript
- * const lynkow = createLynkowClient({
+ * const lynkow = createClient({
  *   siteId: 'your-site-uuid',
- *   locale: 'fr'
+ *   locale: 'fr',
+ *   debug: true
  * })
  *
  * const posts = await lynkow.contents.list()
  * ```
  */
+declare function createClient(config: ClientConfig): Client;
+/**
+ * Creates a Lynkow client instance (legacy naming)
+ *
+ * @deprecated Use `createClient` instead
+ * @param config - Client configuration
+ * @returns Client instance with all services
+ */
 declare function createLynkowClient(config: LynkowConfig): LynkowClient;
 
-export { type Alternate, type ApiErrorDetail, type Author, type BaseRequestOptions, type CategoriesListResponse, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type ConsentLogResponse, type Content, type ContentBlock, type ContentBody, type ContentResolveResponse, type ContentSummary, type ContentsFilters, type ContentsListResponse, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, type ErrorCode, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormSettings, type FormSubmitData, type FormSubmitResponse, type GlobalBlock, type GlobalBlockResponse, type LegalDocument, type LegalDocumentSummary, type LegalDocumentType, type LegalListResponse, type LynkowClient, type LynkowConfig, LynkowError, type Page, type PageSeo, type PageSummary, type PagesListResponse, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, type SiteConfig, type SiteConfigResponse, type SortOptions, type SubmitOptions, type Tag, type TagsListResponse, createLynkowClient, isCategoryResolve, isContentResolve, isLynkowError };
+/**
+ * Error handling utilities for Lynkow SDK
+ */
+/**
+ * Error codes for Lynkow SDK errors
+ */
+type ErrorCode = 'BAD_REQUEST' | 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'RATE_LIMITED' | 'TOO_MANY_REQUESTS' | 'TIMEOUT' | 'NETWORK_ERROR' | 'INTERNAL_ERROR' | 'SERVICE_UNAVAILABLE' | 'UNKNOWN';
+/**
+ * API error detail from server response
+ */
+interface ApiErrorDetail {
+    message: string;
+    field?: string;
+    code?: string;
+}
+/**
+ * Custom error class for Lynkow SDK
+ * Provides structured error information including HTTP status codes and error details
+ */
+declare class LynkowError extends Error {
+    /**
+     * Error name (always 'LynkowError')
+     */
+    readonly name = "LynkowError";
+    /**
+     * Error code for categorization
+     */
+    readonly code: ErrorCode;
+    /**
+     * HTTP status code (if applicable)
+     */
+    readonly status?: number;
+    /**
+     * Additional error details from the API
+     */
+    readonly details?: ApiErrorDetail[];
+    /**
+     * Original error that caused this error (if any)
+     */
+    readonly cause?: Error;
+    constructor(message: string, code: ErrorCode, status?: number, details?: ApiErrorDetail[], cause?: Error);
+    /**
+     * Create a LynkowError from an HTTP response
+     */
+    static fromResponse(response: Response): Promise<LynkowError>;
+    /**
+     * Create a LynkowError from a network error
+     */
+    static fromNetworkError(error: Error): LynkowError;
+    /**
+     * Map HTTP status code to error code
+     */
+    private static statusToCode;
+    /**
+     * Convert error to a plain object for serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Type guard to check if an error is a LynkowError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await lynkow.contents.getBySlug('not-found')
+ * } catch (error) {
+ *   if (isLynkowError(error) && error.code === 'NOT_FOUND') {
+ *     // Handle 404
+ *   }
+ * }
+ * ```
+ */
+declare function isLynkowError(error: unknown): error is LynkowError;
+
+/**
+ * Environment detection utilities
+ * Determines if code is running in browser or server environment
+ */
+/**
+ * Check if running in a browser environment
+ */
+declare const isBrowser: boolean;
+/**
+ * Check if running in a server environment (Node.js, Deno, etc.)
+ */
+declare const isServer: boolean;
+/**
+ * Execute a function only in browser environment
+ * Returns the fallback value in server environment
+ *
+ * @param fn - Function to execute in browser
+ * @param fallback - Value to return in server environment
+ * @returns Result of fn() in browser, fallback in server
+ *
+ * @example
+ * ```typescript
+ * const visitorId = browserOnly(
+ *   () => localStorage.getItem('visitor_id'),
+ *   null
+ * )
+ * ```
+ */
+declare function browserOnly<T>(fn: () => T, fallback: T): T;
+/**
+ * Execute an async function only in browser environment
+ * Returns the fallback value in server environment
+ *
+ * @param fn - Async function to execute in browser
+ * @param fallback - Value to return in server environment
+ * @returns Promise resolving to result of fn() in browser, fallback in server
+ *
+ * @example
+ * ```typescript
+ * const config = await browserOnlyAsync(
+ *   () => fetchConfig(),
+ *   defaultConfig
+ * )
+ * ```
+ */
+declare function browserOnlyAsync<T>(fn: () => Promise<T>, fallback: T): Promise<T>;
+
+export { type Alternate, type ApiErrorDetail, type Author, type BaseRequestOptions, type CategoriesListResponse, type Category, type CategoryDetail, type CategoryDetailResponse, type CategoryOptions, type CategoryResolveResponse, type CategoryTreeNode, type CategoryTreeResponse, type CategoryWithCount, type Client, type ClientConfig, type ConsentCategories, type ConsentLogResponse, type Content, type ContentBlock, type ContentBody, type ContentResolveResponse, type ContentSummary, type ContentsFilters, type ContentsListResponse, type CookieCategory, type CookieConfig, type CookiePreferences, type CookieTexts, type ErrorCode, type EventData, type EventName, type Form, type FormField, type FormFieldOption, type FormFieldType, type FormFieldValidation, type FormSettings, type FormSubmitData, type FormSubmitResponse, type FunnelStepData, type GlobalBlock, type GlobalBlockResponse, type LegalDocument, type LynkowClient, type LynkowConfig, LynkowError, type LynkowEvents, type Page, type PageSeo, type PageSummary, type PagesListResponse, type PageviewData, type PaginatedResponse, type PaginationMeta, type PaginationOptions, type Path, type PathsListResponse, type Redirect, type ResolveResponse, type Review, type ReviewResponse, type ReviewSettings, type ReviewSubmitData, type ReviewSubmitResponse, type ReviewsFilters, type ReviewsListResponse, type SiteConfig, type SiteConfigResponse, type SortOptions, type SubmitOptions, type Tag, type TagsListResponse, browserOnly, browserOnlyAsync, createClient, createLynkowClient, isBrowser, isCategoryResolve, isContentResolve, isLynkowError, isServer };