@nexushub/client 0.8.9 → 1.1.0

package/dist/react.d.cts

@@ -1,6 +1,16 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 
+interface NexusRendererProps {
+    content: string;
+    className?: string;
+    onCommentClick?: (commentId: string) => void;
+    onImageClick?: (src: string, alt?: string) => void;
+    hydrateCharts?: boolean;
+    enableImageInteraction?: boolean;
+    documentClassName?: string;
+}
+declare function NexusRenderer({ content, className, onCommentClick, onImageClick, hydrateCharts, enableImageInteraction, documentClassName, }: NexusRendererProps): React.JSX.Element;
+
 interface MinimalNexusConfig {
     apiUrl?: string;
     analyticsUrl?: string;
@@ -14,6 +24,18 @@ interface NexusConfig extends MinimalNexusConfig {
     revalidateTime?: number | false;
     timeout?: number;
     retries?: number;
+    /** Internal/runtime version; populated automatically. */
+    sdkVersion?: string;
+    /** GN-Apex owns cache invalidation. Forever is intentional by default. */
+    cacheInvalidation?: "platform" | "manual";
+    environment?: "development" | "staging" | "production";
+    privacy?: {
+        analytics?: boolean;
+        fingerprinting?: boolean;
+        redact?: boolean;
+    };
+    autoTracking?: boolean;
+    publicKeyOnly?: boolean;
 }
 interface NexusConfig {
     projectId: string;
@@ -58,6 +80,8 @@ declare class ContentEngine {
     private abortController?;
     private isServer;
     constructor(config: NexusConfig);
+    /** Update runtime configuration without exposing internal mutation. */
+    updateConfig(config: NexusConfig): void;
     /**
      * Fetch a Single Page with full strategy pipeline
      */
@@ -79,7 +103,7 @@ declare class ContentEngine {
     }): Promise<CollectionResponse<T>>;
     private _getCollection;
     /**
-     * Fetch Global Settings with nested includes support
+     * Fetch Global Settings
      */
     getGlobals<T = any>(options?: {
         include?: string[];
@@ -108,31 +132,11 @@ declare class ContentEngine {
         total: number;
     }>;
     /**
-     * Prefetch content for better performance
+     * Prefetch content
      */
     prefetch(urls: string[]): Promise<void>;
     /**
      * Robust Real-time Subscriptions (SSE) with Auto-Reconnect
-     *
-     * ⚠️ SCOPE — READ BEFORE RELYING ON THIS FOR "instant" UPDATES:
-     * This connects from the BROWSER TAB it's called in, and on message it
-     * only clears THIS SDK INSTANCE's in-memory `memoryCache` (via
-     * invalidateCache below) in THAT browser tab's JS heap. In a typical
-     * Next.js deployment — and Cloudflare specifically, which is stateless
-     * per-request at the edge — that is a different process/isolate than the
-     * one that will render the NEXT server request for this content. So:
-     *   - ✅ Useful for: a client component that reads from `nexus.content`
-     *     directly in the browser and re-renders in place without a page
-     *     navigation (e.g. a live-updating dashboard widget).
-     *   - ❌ NOT sufficient for: "user A edits content in the CMS, user B's
-     *     already-loaded page updates" via a server-rendered page. That
-     *     requires the backend's /api/revalidate webhook (see
-     *     content.service.ts `pingNextRevalidateWebhook`) to have actually
-     *     cleared the *server's* Data Cache, so the NEXT navigation or
-     *     server request picks up fresh data. This SSE channel does not
-     *     replace that — it's a complementary, browser-local optimization.
-     * If your symptom was "stale content after editing," fix the webhook
-     * wiring first; treat this method as an enhancement layered on top.
      */
     subscribeToUpdates(callback: (data: any) => void): () => void;
     private checkCaches;
@@ -159,9 +163,13 @@ declare class ContentEngine {
     private fetchWithTimeout;
     private getHeaders;
     private isCacheValid;
+    /**
+     * 🛡️ FIX: Normalizes timeout errors (AbortError, 408, or Timeout messages)
+     * into clean, standardized "Request timeout" errors.
+     */
     private normalizeError;
     cancelRequests(): void;
-    private cleanup;
+    cleanup(): void;
 }
 
 declare class AnalyticsEngine {
@@ -209,25 +217,159 @@ declare class AnalyticsEngine {
     stop(isFinalShutdown?: boolean): void;
 }
 
+type NexusEventMap = {
+    "request:start": {
+        requestId: string;
+        url: string;
+        method: string;
+    };
+    "request:end": {
+        requestId: string;
+        url: string;
+        status: number;
+        duration: number;
+    };
+    "cache:hit": {
+        key: string;
+        stale?: boolean;
+    };
+    "cache:miss": {
+        key: string;
+    };
+    "analytics:queued": {
+        count: number;
+    };
+    "analytics:flushed": {
+        sent: number;
+        remaining: number;
+    };
+    "content:updated": {
+        type: string;
+        slug?: string;
+        collectionId?: string;
+        id?: string;
+    };
+    "error": {
+        error: unknown;
+    };
+};
+type Listener<T> = (payload: T) => void;
+declare class NexusEventBus<M extends Record<string, any> = NexusEventMap> {
+    private listeners;
+    on<K extends keyof M>(event: K, listener: Listener<M[K]>): () => void;
+    emit<K extends keyof M>(event: K, payload: M[K]): void;
+    clear(): void;
+}
+
+interface NexusRequestOptions extends RequestInit {
+    timeout?: number;
+    retries?: number;
+    next?: {
+        tags?: string[];
+        revalidate?: number | false;
+    };
+}
+declare class NexusHttpClient {
+    private config;
+    private events;
+    private readonly limiter;
+    private readonly breaker;
+    private readonly backoff;
+    constructor(config: NexusConfig, events?: NexusEventBus<NexusEventMap>);
+    updateConfig(config: NexusConfig): void;
+    request(input: string, options?: NexusRequestOptions): Promise<Response>;
+    getStats(): {
+        rateLimit: {
+            currentRequests: number;
+            limit: number;
+        };
+        circuit: string;
+    };
+}
+
+declare class FeatureFlags {
+    private values;
+    constructor(initial?: Record<string, any>);
+    set(values: Record<string, any>): void;
+    isEnabled(key: string, fallback?: boolean): boolean;
+    get<T = any>(key: string, fallback?: T): T;
+    all(): {
+        [x: string]: any;
+    };
+}
+declare class RemoteConfig {
+    private values;
+    set(values: Record<string, any>): void;
+    get<T = any>(key: string, fallback?: T): T;
+    all(): {
+        [x: string]: any;
+    };
+}
+
+/**
+ * GN-Apex client: intentionally zero-config for GN-Apex generated sites.
+ * Platform configuration is discovered automatically; explicit overrides are
+ * an escape hatch for SDK consumers, not a requirement for site developers.
+ * Cache revalidation is FALSE by default on purpose: GN-Apex/Cloudflare owns
+ * invalidation and purge, so immutable content can stay cached indefinitely.
+ */
 declare class NexusClient {
     private config;
     content: ContentEngine;
     analytics?: AnalyticsEngine;
+    readonly events: NexusEventBus;
+    readonly http: NexusHttpClient;
+    readonly flags: FeatureFlags;
+    readonly remoteConfig: RemoteConfig;
     constructor(config?: Partial<NexusConfig>);
     /**
-     * Helper alias for cleaner content fetching.
+     * Helper alias for cleaner page content fetching.
      */
     getPage<T = any>(slug: string, options?: any): Promise<T>;
     /**
-     * Returns a readonly snapshot of the current config.
+     * Returns a readonly snapshot of the active configuration.
      */
     getConfig(): Readonly<NexusConfig>;
     /**
-     * Updates specific config fields at runtime.
-     * Replaces the previous pattern of `(nexus as any).config.projectId = x`
-     * which bypassed TypeScript and mutated internal state unsafely.
+     * Updates runtime configuration dynamically without breaking active listeners.
      */
     updateConfig(updates: Partial<NexusConfig>): void;
+    /**
+     * Returns deep system diagnostics including HTTP and cache performance.
+     */
+    diagnostics(): {
+        cache: {
+            memory: {
+                size: number;
+                hits: number;
+                misses: number;
+                hitRate: number;
+            };
+            browser: {
+                size: number;
+            } | null;
+            local: {
+                loaded: boolean;
+            };
+        };
+        http: {
+            rateLimit: {
+                currentRequests: number;
+                limit: number;
+            };
+            circuit: string;
+        };
+        analyticsQueue: number | undefined;
+        version: string;
+        environment: string;
+        online: boolean;
+        userAgent?: string;
+        memory?: number;
+    };
+    /**
+     * Gracefully terminates background tasks and cleans up listeners.
+     */
+    destroy(): void;
 }
 
 interface NexusProviderProps {
@@ -263,7 +405,7 @@ interface LiveFeedContextValue {
     isConnected: boolean;
 }
 declare const useNexusLiveFeed: () => LiveFeedContextValue;
-declare const NexusProvider: ({ children, projectId, disableAnalytics, hasConsent, enableLiveFeed, onLiveEvent, autoPromptPush, }: NexusProviderProps) => react_jsx_runtime.JSX.Element;
+declare const NexusProvider: ({ children, projectId, disableAnalytics, hasConsent, enableLiveFeed, onLiveEvent, autoPromptPush, }: NexusProviderProps) => React.JSX.Element;
 declare const useNexus: () => NexusClient;
 declare const useNexusAnalytics: () => {
     track: (eventName: string, properties?: Record<string, any>) => void;
@@ -334,33 +476,36 @@ interface AuthContextType extends AuthState {
 declare const AuthProvider: ({ children, config, }: {
     children: React.ReactNode;
     config: NexusConfig;
-}) => react_jsx_runtime.JSX.Element;
+}) => React.JSX.Element;
 declare const useNexusAuth: () => AuthContextType;
 
 interface NexusRichTextProps {
     value: string;
     className?: string;
+    hydrateCharts?: boolean;
+    onCommentClick?: (commentId: string) => void;
+    onImageClick?: (src: string, alt?: string) => void;
 }
-declare function NexusRichText({ value, className }: NexusRichTextProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusRichText({ value, className, hydrateCharts, onCommentClick, onImageClick, }: NexusRichTextProps): React.JSX.Element | null;
 interface NexusLongTextProps {
     value: string;
     className?: string;
 }
-declare function NexusLongText({ value, className }: NexusLongTextProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusLongText({ value, className }: NexusLongTextProps): React.JSX.Element | null;
 interface NexusIconProps {
     name: string;
     className?: string;
     size?: number;
     strokeWidth?: number;
 }
-declare function NexusIcon({ name, className, size, strokeWidth, }: NexusIconProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusIcon({ name, className, size, strokeWidth, }: NexusIconProps): React.JSX.Element | null;
 interface NexusImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
     value: string | {
         url: string;
         alt?: string;
     } | null;
 }
-declare function NexusImage({ value, className, alt, ...props }: NexusImageProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusImage({ value, className, alt, ...props }: NexusImageProps): React.JSX.Element | null;
 interface NexusGalleryProps {
     value: Array<string | {
         url: string;
@@ -369,13 +514,13 @@ interface NexusGalleryProps {
     className?: string;
     imageClassName?: string;
 }
-declare function NexusGallery({ value, className, imageClassName, }: NexusGalleryProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusGallery({ value, className, imageClassName, }: NexusGalleryProps): React.JSX.Element | null;
 interface NexusVideoProps {
     value: string | null;
     className?: string;
     autoplay?: boolean;
 }
-declare function NexusVideo({ value, className, autoplay, }: NexusVideoProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusVideo({ value, className, autoplay, }: NexusVideoProps): React.JSX.Element | null;
 interface NexusMapProps {
     value: {
         lat: number;
@@ -384,27 +529,20 @@ interface NexusMapProps {
     } | null;
     className?: string;
 }
-declare function NexusMap({ value, className }: NexusMapProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusMap({ value, className }: NexusMapProps): React.JSX.Element | null;
 interface NexusColorProps {
     value: string | null;
     className?: string;
     showHexLabel?: boolean;
 }
-/**
- * Renders a color value as a styled swatch with optional HEX/RGB label copy-trigger.
- */
-declare function NexusColor({ value, className, showHexLabel, }: NexusColorProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusColor({ value, className, showHexLabel, }: NexusColorProps): React.JSX.Element | null;
 interface NexusGradientProps {
     value: string | null;
     children?: React.ReactNode;
     className?: string;
     asTextMask?: boolean;
 }
-/**
- * Renders a container or text utilizing a CSS background-gradient.
- * supporting text-clip masks (e.g. gradient headings).
- */
-declare function NexusGradient({ value, children, className, asTextMask, }: NexusGradientProps): react_jsx_runtime.JSX.Element;
+declare function NexusGradient({ value, children, className, asTextMask, }: NexusGradientProps): React.JSX.Element;
 interface NexusAddressProps {
     value: {
         street?: string;
@@ -415,65 +553,44 @@ interface NexusAddressProps {
     } | null;
     className?: string;
 }
-/**
- * Formats structured location address payloads into an elegant micro-card.
- */
-declare function NexusAddress({ value, className }: NexusAddressProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusAddress({ value, className }: NexusAddressProps): React.JSX.Element | null;
 interface NexusKeyValueProps {
     value: Record<string, string> | null;
     className?: string;
 }
-/**
- * Renders arbitrary specifications or metadata maps inside an elegant tabular grid.
- */
-declare function NexusKeyValue({ value, className }: NexusKeyValueProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusKeyValue({ value, className }: NexusKeyValueProps): React.JSX.Element | null;
 interface NexusTagsProps {
     value: string[] | null;
     className?: string;
     badgeClassName?: string;
 }
-/**
- * Iterates and renders arrays or tags as styled status badges.
- */
-declare function NexusTags({ value, className, badgeClassName, }: NexusTagsProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusTags({ value, className, badgeClassName, }: NexusTagsProps): React.JSX.Element | null;
 interface NexusProgressProps {
     value: number | null;
     max?: number;
     className?: string;
     color?: string;
 }
-/**
- * Renders progress fields or percent ratings inside a smooth horizontal bar.
- */
-declare function NexusProgress({ value, max, className, color, }: NexusProgressProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusProgress({ value, max, className, color, }: NexusProgressProps): React.JSX.Element | null;
 interface NexusBlendContainerProps {
     mode: string | null;
     children: React.ReactNode;
     className?: string;
 }
-/**
- * Wraps dynamic components to apply a specified mix-blend-mode container safely.
- */
-declare function NexusBlendContainer({ mode, children, className, }: NexusBlendContainerProps): react_jsx_runtime.JSX.Element;
+declare function NexusBlendContainer({ mode, children, className, }: NexusBlendContainerProps): React.JSX.Element;
 interface NexusCodeProps {
     value: string | null;
     language?: string;
     className?: string;
     showLineNumbers?: boolean;
 }
-/**
- * Renders scrollable JSON, script contents, or code files with an instant Copy button.
- */
-declare function NexusCode({ value, language, className, showLineNumbers, }: NexusCodeProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusCode({ value, language, className, showLineNumbers, }: NexusCodeProps): React.JSX.Element | null;
 interface NexusBooleanProps {
     value: boolean | null;
     className?: string;
     trueLabel?: string;
     falseLabel?: string;
 }
-/**
- * Renders toggles or boolean validations as a styled linter-safe status badge.
- */
-declare function NexusBoolean({ value, className, trueLabel, falseLabel, }: NexusBooleanProps): react_jsx_runtime.JSX.Element | null;
+declare function NexusBoolean({ value, className, trueLabel, falseLabel, }: NexusBooleanProps): React.JSX.Element | null;
 
-export { AuthProvider, type LiveAnalyticsEvent, NexusAddress, type NexusAddressProps, NexusBlendContainer, type NexusBlendContainerProps, NexusBoolean, type NexusBooleanProps, NexusCode, type NexusCodeProps, NexusColor, type NexusColorProps, NexusGallery, type NexusGalleryProps, NexusGradient, type NexusGradientProps, NexusIcon, type NexusIconProps, NexusImage, type NexusImageProps, NexusKeyValue, type NexusKeyValueProps, NexusLongText, type NexusLongTextProps, NexusMap, type NexusMapProps, NexusProgress, type NexusProgressProps, NexusProvider, type NexusProviderProps, NexusRichText, type NexusRichTextProps, NexusTags, type NexusTagsProps, NexusVideo, type NexusVideoProps, useNexus, useNexusAnalytics, useNexusAuth, useNexusLiveFeed };
+export { AuthProvider, type LiveAnalyticsEvent, NexusAddress, type NexusAddressProps, NexusBlendContainer, type NexusBlendContainerProps, NexusBoolean, type NexusBooleanProps, NexusCode, type NexusCodeProps, NexusColor, type NexusColorProps, NexusGallery, type NexusGalleryProps, NexusGradient, type NexusGradientProps, NexusIcon, type NexusIconProps, NexusImage, type NexusImageProps, NexusKeyValue, type NexusKeyValueProps, NexusLongText, type NexusLongTextProps, NexusMap, type NexusMapProps, NexusProgress, type NexusProgressProps, NexusProvider, type NexusProviderProps, NexusRenderer, NexusRichText, type NexusRichTextProps, NexusTags, type NexusTagsProps, NexusVideo, type NexusVideoProps, useNexus, useNexusAnalytics, useNexusAuth, useNexusLiveFeed };