@nexushub/client 0.9.0 → 1.1.1

package/dist/index.d.cts

@@ -8,12 +8,33 @@ interface MinimalNexusConfig {
 }
 declare const DEFAULT_API_URL = "https://api.gnapex.com";
 declare const DEFAULT_ANALYTICS_URL = "https://sentry.gnapex.com";
+declare const SDK_VERSION = "1.1.0";
 declare const LOCAL_NEST_URL = "https://api.gnapex.com";
 declare const LOCAL_RUST_URL = "https://sentry.gnapex.com";
+/**
+ * Automatically discovers runtime configuration across:
+ * 1. Window Global (__GNAPEX__ or __NEXUS__)
+ * 2. HTML Meta Tags (<meta name="gnapex-project"> / <meta name="nexus-project">)
+ * 3. Next.js Public Environment Variables (NEXT_PUBLIC_GNAPEX_* / NEXT_PUBLIC_NEXUS_*)
+ * 4. Node.js Standard Process Variables (GNAPEX_* / NEXUS_*)
+ */
 declare const getEnvConfig: () => MinimalNexusConfig;
+/**
+ * Merges discovered configuration with manual constructor overrides
+ */
 declare const mergeConfigs: (base: MinimalNexusConfig, override: Partial<MinimalNexusConfig>) => MinimalNexusConfig;
+/**
+ * Returns complete resolved configuration snapshot
+ */
 declare const getFullConfig: (partialConfig?: Partial<MinimalNexusConfig>) => MinimalNexusConfig;
+/**
+ * Validates configuration integrity
+ */
 declare const validateConfig: (config: MinimalNexusConfig) => string[];
+/**
+ * Helper to check if required keys exist
+ */
+declare const hasRequiredConfig: (config: MinimalNexusConfig) => boolean;
 
 interface NexusConfig extends MinimalNexusConfig {
     debug?: boolean;
@@ -21,6 +42,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;
@@ -92,6 +125,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
      */
@@ -113,7 +148,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[];
@@ -142,31 +177,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;
@@ -193,9 +208,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 {
@@ -243,28 +262,184 @@ 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;
 }
 declare const nexus: NexusClient;
-declare const createNexusClient: (config: Partial<NexusConfig>) => NexusClient;
+declare const createNexusClient: (config?: Partial<NexusConfig>) => NexusClient;
+
+type NexusErrorCode = "CONFIGURATION_ERROR" | "NETWORK_ERROR" | "TIMEOUT" | "ABORTED" | "HTTP_ERROR" | "RATE_LIMITED" | "CIRCUIT_OPEN" | "NOT_FOUND" | "VALIDATION_ERROR" | "STORAGE_ERROR" | "UNKNOWN";
+declare class NexusError extends Error {
+    readonly code: NexusErrorCode;
+    readonly status?: number | undefined;
+    readonly requestId?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly retryable: boolean;
+    readonly cause?: unknown | undefined;
+    readonly name = "NexusError";
+    constructor(message: string, code?: NexusErrorCode, status?: number | undefined, requestId?: string | undefined, details?: unknown | undefined, retryable?: boolean, cause?: unknown | undefined);
+}
+declare const isNexusError: (e: unknown) => e is NexusError;
+
+interface NexusDiagnostics {
+    version: string;
+    environment: string;
+    online: boolean;
+    userAgent?: string;
+    memory?: number;
+}
+declare const getDiagnostics: (version: string, environment: string) => NexusDiagnostics;
 
 interface SiteUser {
     id: string;
@@ -319,8 +494,9 @@ interface AuthContextType extends AuthState {
 interface CacheOptions {
     maxSize?: number;
     ttl?: number;
+    /** false means platform-controlled immutable cache. */
+    revalidate?: number | false;
     tags?: string[];
-    revalidate?: number;
 }
 interface CacheStats {
     size: number;
@@ -385,6 +561,19 @@ declare class LocalCacheProxy implements ILocalCache {
     getAllData(): Promise<any>;
 }
 
-declare const VERSION = "0.0.1";
+declare class NexusPushClient {
+    private config;
+    constructor(config: NexusConfig);
+    /**
+     * Helper to convert Base64 VAPID key to Uint8Array for WebPush security
+     */
+    private urlBase64ToUint8Array;
+    /**
+     * Requests browser notification permissions and registers the WebPush subscription
+     */
+    requestSubscription(serviceWorkerPath?: string): Promise<boolean>;
+}
+
+declare const VERSION = "1.1.0";
 
-export { AnalyticsEngine, type AuthContextType, type AuthError, type AuthState, BrowserCache, type CacheEntry, type CacheMetadata, CacheTags, type CollectionQuery, type CollectionResponse, ContentEngine, type ContentResponse, DEFAULT_ANALYTICS_URL, DEFAULT_API_URL, type ErrorResponse, LOCAL_NEST_URL, LOCAL_RUST_URL, LocalCacheProxy as LocalCache, type LoginCredentials, MemoryCache, type MinimalNexusConfig, NexusClient, type NexusConfig, type RegisterCredentials, type SiteUser, VERSION, createNexusClient, getEnvConfig, getFullConfig, mergeConfigs, nexus, validateConfig };
+export { AnalyticsEngine, type AuthContextType, type AuthError, type AuthState, BrowserCache, type CacheEntry, type CacheMetadata, CacheTags, type CollectionQuery, type CollectionResponse, ContentEngine, type ContentResponse, DEFAULT_ANALYTICS_URL, DEFAULT_API_URL, type ErrorResponse, FeatureFlags, LOCAL_NEST_URL, LOCAL_RUST_URL, LocalCacheProxy as LocalCache, type LoginCredentials, MemoryCache, type MinimalNexusConfig, NexusClient, type NexusConfig, type NexusDiagnostics, NexusError, type NexusErrorCode, NexusEventBus, type NexusEventMap, NexusHttpClient, NexusPushClient, type NexusRequestOptions, type RegisterCredentials, RemoteConfig, SDK_VERSION, type SiteUser, VERSION, createNexusClient, getDiagnostics, getEnvConfig, getFullConfig, hasRequiredConfig, isNexusError, mergeConfigs, nexus, validateConfig };

package/dist/index.d.ts

@@ -8,12 +8,33 @@ interface MinimalNexusConfig {
 }
 declare const DEFAULT_API_URL = "https://api.gnapex.com";
 declare const DEFAULT_ANALYTICS_URL = "https://sentry.gnapex.com";
+declare const SDK_VERSION = "1.1.0";
 declare const LOCAL_NEST_URL = "https://api.gnapex.com";
 declare const LOCAL_RUST_URL = "https://sentry.gnapex.com";
+/**
+ * Automatically discovers runtime configuration across:
+ * 1. Window Global (__GNAPEX__ or __NEXUS__)
+ * 2. HTML Meta Tags (<meta name="gnapex-project"> / <meta name="nexus-project">)
+ * 3. Next.js Public Environment Variables (NEXT_PUBLIC_GNAPEX_* / NEXT_PUBLIC_NEXUS_*)
+ * 4. Node.js Standard Process Variables (GNAPEX_* / NEXUS_*)
+ */
 declare const getEnvConfig: () => MinimalNexusConfig;
+/**
+ * Merges discovered configuration with manual constructor overrides
+ */
 declare const mergeConfigs: (base: MinimalNexusConfig, override: Partial<MinimalNexusConfig>) => MinimalNexusConfig;
+/**
+ * Returns complete resolved configuration snapshot
+ */
 declare const getFullConfig: (partialConfig?: Partial<MinimalNexusConfig>) => MinimalNexusConfig;
+/**
+ * Validates configuration integrity
+ */
 declare const validateConfig: (config: MinimalNexusConfig) => string[];
+/**
+ * Helper to check if required keys exist
+ */
+declare const hasRequiredConfig: (config: MinimalNexusConfig) => boolean;
 
 interface NexusConfig extends MinimalNexusConfig {
     debug?: boolean;
@@ -21,6 +42,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;
@@ -92,6 +125,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
      */
@@ -113,7 +148,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[];
@@ -142,31 +177,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;
@@ -193,9 +208,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 {
@@ -243,28 +262,184 @@ 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;
 }
 declare const nexus: NexusClient;
-declare const createNexusClient: (config: Partial<NexusConfig>) => NexusClient;
+declare const createNexusClient: (config?: Partial<NexusConfig>) => NexusClient;
+
+type NexusErrorCode = "CONFIGURATION_ERROR" | "NETWORK_ERROR" | "TIMEOUT" | "ABORTED" | "HTTP_ERROR" | "RATE_LIMITED" | "CIRCUIT_OPEN" | "NOT_FOUND" | "VALIDATION_ERROR" | "STORAGE_ERROR" | "UNKNOWN";
+declare class NexusError extends Error {
+    readonly code: NexusErrorCode;
+    readonly status?: number | undefined;
+    readonly requestId?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly retryable: boolean;
+    readonly cause?: unknown | undefined;
+    readonly name = "NexusError";
+    constructor(message: string, code?: NexusErrorCode, status?: number | undefined, requestId?: string | undefined, details?: unknown | undefined, retryable?: boolean, cause?: unknown | undefined);
+}
+declare const isNexusError: (e: unknown) => e is NexusError;
+
+interface NexusDiagnostics {
+    version: string;
+    environment: string;
+    online: boolean;
+    userAgent?: string;
+    memory?: number;
+}
+declare const getDiagnostics: (version: string, environment: string) => NexusDiagnostics;
 
 interface SiteUser {
     id: string;
@@ -319,8 +494,9 @@ interface AuthContextType extends AuthState {
 interface CacheOptions {
     maxSize?: number;
     ttl?: number;
+    /** false means platform-controlled immutable cache. */
+    revalidate?: number | false;
     tags?: string[];
-    revalidate?: number;
 }
 interface CacheStats {
     size: number;
@@ -385,6 +561,19 @@ declare class LocalCacheProxy implements ILocalCache {
     getAllData(): Promise<any>;
 }
 
-declare const VERSION = "0.0.1";
+declare class NexusPushClient {
+    private config;
+    constructor(config: NexusConfig);
+    /**
+     * Helper to convert Base64 VAPID key to Uint8Array for WebPush security
+     */
+    private urlBase64ToUint8Array;
+    /**
+     * Requests browser notification permissions and registers the WebPush subscription
+     */
+    requestSubscription(serviceWorkerPath?: string): Promise<boolean>;
+}
+
+declare const VERSION = "1.1.0";
 
-export { AnalyticsEngine, type AuthContextType, type AuthError, type AuthState, BrowserCache, type CacheEntry, type CacheMetadata, CacheTags, type CollectionQuery, type CollectionResponse, ContentEngine, type ContentResponse, DEFAULT_ANALYTICS_URL, DEFAULT_API_URL, type ErrorResponse, LOCAL_NEST_URL, LOCAL_RUST_URL, LocalCacheProxy as LocalCache, type LoginCredentials, MemoryCache, type MinimalNexusConfig, NexusClient, type NexusConfig, type RegisterCredentials, type SiteUser, VERSION, createNexusClient, getEnvConfig, getFullConfig, mergeConfigs, nexus, validateConfig };
+export { AnalyticsEngine, type AuthContextType, type AuthError, type AuthState, BrowserCache, type CacheEntry, type CacheMetadata, CacheTags, type CollectionQuery, type CollectionResponse, ContentEngine, type ContentResponse, DEFAULT_ANALYTICS_URL, DEFAULT_API_URL, type ErrorResponse, FeatureFlags, LOCAL_NEST_URL, LOCAL_RUST_URL, LocalCacheProxy as LocalCache, type LoginCredentials, MemoryCache, type MinimalNexusConfig, NexusClient, type NexusConfig, type NexusDiagnostics, NexusError, type NexusErrorCode, NexusEventBus, type NexusEventMap, NexusHttpClient, NexusPushClient, type NexusRequestOptions, type RegisterCredentials, RemoteConfig, SDK_VERSION, type SiteUser, VERSION, createNexusClient, getDiagnostics, getEnvConfig, getFullConfig, hasRequiredConfig, isNexusError, mergeConfigs, nexus, validateConfig };