@neevjs/client 0.0.1 → 1.0.1-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rahul7raj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { NeevClientConfig, NeevClientInterface, AuthInterface, AuthUser, ModelRecord, UseModelReturn, SyncStatus, NeevPlugin } from '@neevjs/shared';
-export { ApiMeta, ApiResponse, AuthInterface, AuthLoginResponse, AuthUser, ModelRecord, NeevClientConfig, NeevClientInterface, NeevPlugin, NeevRequest, Pagination, QueuedAction, RequestOptions, SyncStatus, UseModelReturn } from '@neevjs/shared';
-import React from 'react';
+export { ApiMeta, ApiResponse, AuthInterface, AuthLoginResponse, AuthUser, ModelRecord, NeevClientConfig, NeevClientInterface, NeevPlugin, NeevRequest, Pagination, QueuedAction, RequestOptions, SyncStatus, UseModelReturn, VERSION } from '@neevjs/shared';
+import React, { ReactNode } from 'react';
 
 declare function createClient(config?: NeevClientConfig): NeevClientInterface;
 
@@ -24,25 +24,175 @@ declare class AuthClient implements AuthInterface {
     getToken(): string | null;
 }
 
-declare function useModel<T extends ModelRecord>(name: string): UseModelReturn<T>;
+/**
+ * SecureStore — AES-256-GCM encrypted client-side storage for NeevJS.
+ *
+ * ## Security model
+ * - Data is encrypted with AES-256-GCM before being written to localStorage.
+ * - The encryption key is generated fresh every session and lives ONLY in memory.
+ * - On page refresh the key is gone, so the encrypted ciphertext in localStorage
+ *   is permanently unreadable — it is automatically discarded.
+ * - This means SecureStore does NOT persist across page refreshes by design.
+ *   If you need truly sensitive data to survive refreshes, store it on the server.
+ *
+ * ## Threat model
+ * ✅ Protects against: physical access to device / localStorage dump
+ * ✅ Protects against: another browser tab/window reading the storage
+ * ❌ Does NOT protect against: XSS (attacker JS runs in your origin and can
+ *    call SecureStore.get() directly — same as any in-memory value)
+ *
+ * ## When to use
+ * - Temporary sensitive values during a session (payment amount, masked card, OTP state)
+ * - Values that must not appear in plaintext in DevTools Application → Storage
+ *
+ * ## API
+ * ```ts
+ * await SecureStore.set('pending_payment', { amount: 4999, currency: 'INR' })
+ * const payment = await SecureStore.get<Payment>('pending_payment')
+ * SecureStore.remove('pending_payment')
+ * SecureStore.clear()  // remove all SecureStore entries
+ * ```
+ */
+declare const SecureStore: {
+    /**
+     * Encrypt and store a value in localStorage.
+     * The value cannot be read without the in-memory session key.
+     */
+    set<T>(key: string, value: T): Promise<void>;
+    /**
+     * Retrieve and decrypt a value.
+     * Returns null if the key doesn't exist or cannot be decrypted
+     * (e.g. after a page refresh when the key is gone).
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Remove a specific key from SecureStore.
+     */
+    remove(key: string): void;
+    /**
+     * Remove ALL SecureStore entries from localStorage.
+     * Call this on logout to clean up all session-bound encrypted data.
+     */
+    clear(): void;
+};
+
+interface UseModelOptions {
+    suspense?: boolean;
+    /**
+     * Query parameters appended to the request URL.
+     * The full URL (including params) is used as the cache key, so
+     * useModel('users', { params: { page: 1 } }) and
+     * useModel('users', { params: { page: 2 } }) cache independently.
+     *
+     * @example params: { page: 1, role: 'admin', search: 'rahul' }
+     */
+    params?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Override the client's default baseURL for this specific model instance.
+     * Useful for Hybrid Mode (connecting to different backends).
+     */
+    baseURL?: string;
+}
+declare function useModel<T extends ModelRecord>(name: string, options?: UseModelOptions): UseModelReturn<T>;
 
 declare function useAuth(): AuthInterface;
 
 declare function useSyncStatus(): SyncStatus;
 
+interface UseStoreOptions {
+    /**
+     * Persist value to localStorage. Survives page reloads and browser restarts.
+     *
+     * ⚠️ SECURITY: localStorage is readable by any JavaScript on the page.
+     * Do NOT use for sensitive data (passwords, payment info, PII).
+     * Use `{ session: true }` instead for semi-sensitive data.
+     *
+     * @default false
+     */
+    persist?: boolean;
+    /**
+     * Store value in sessionStorage. Survives page refresh but is:
+     * - Cleared when the browser tab closes
+     * - NOT shared across tabs
+     * - Safer than localStorage for semi-sensitive data (e.g. current user preferences)
+     *
+     * Cannot be combined with `persist: true`.
+     *
+     * @default false
+     */
+    session?: boolean;
+    /**
+     * TTL (time-to-live) in milliseconds. After this duration, the stored value
+     * expires and falls back to `initialValue`.
+     * Only applies when `persist` or `session` is true.
+     *
+     * @example ttl: 7 * 24 * 60 * 60 * 1000  // 7 days
+     */
+    ttl?: number;
+}
+/**
+ * `useStore` — Global client-side state management for NeevJS.
+ *
+ * Built on React 18's `useSyncExternalStore` for concurrent-mode safety.
+ *
+ * Security levels:
+ * - Default (in-memory only)  → Most secure. Lost on refresh.
+ * - `{ session: true }`       → sessionStorage. Safe for semi-sensitive data.
+ * - `{ persist: true }`       → localStorage. For non-sensitive preferences only.
+ *
+ * For truly sensitive data that must persist across sessions → store on the server.
+ */
+declare function useStore<T>(key: string, initialValue: T, options?: UseStoreOptions): [T, (updater: T | ((prev: T) => T)) => void];
+declare function getStore<T>(key: string): T | undefined;
+declare function setStore<T>(key: string, value: T): void;
+declare function clearPersistedStore(key: string): void;
+
 interface TableColumn<T extends ModelRecord> {
     key: keyof T & string;
     label?: string;
     render?: (value: T[keyof T], row: T) => React.ReactNode;
 }
+interface TableClassNames {
+    root?: string;
+    table?: string;
+    thead?: string;
+    tr?: string;
+    th?: string;
+    tbody?: string;
+    td?: string;
+    actions?: string;
+    editButton?: string;
+    deleteButton?: string;
+    emptyState?: string;
+    errorState?: string;
+    loadingState?: string;
+}
+interface TableStyles {
+    root?: React.CSSProperties;
+    table?: React.CSSProperties;
+    thead?: React.CSSProperties;
+    tr?: React.CSSProperties;
+    th?: React.CSSProperties;
+    tbody?: React.CSSProperties;
+    td?: React.CSSProperties;
+    actions?: React.CSSProperties;
+    editButton?: React.CSSProperties;
+    deleteButton?: React.CSSProperties;
+    emptyState?: React.CSSProperties;
+    errorState?: React.CSSProperties;
+    loadingState?: React.CSSProperties;
+}
 interface TableProps<T extends ModelRecord> {
     model: string;
     columns?: TableColumn<T>[];
     onEdit?: (row: T) => void;
     onDelete?: (row: T) => void;
     emptyMessage?: string;
+    classNames?: TableClassNames;
+    styles?: TableStyles;
+    unstyled?: boolean;
 }
-declare function Table<T extends ModelRecord>({ model, columns, onEdit, onDelete, emptyMessage, }: TableProps<T>): React.ReactElement;
+declare function Table<T extends ModelRecord>({ model, columns, onEdit, onDelete, emptyMessage, classNames, styles, unstyled, }: TableProps<T>): React.ReactElement;
 
 interface FormField {
     name: string;
@@ -55,6 +205,26 @@ interface FormField {
         value: string;
     }[];
 }
+interface FormClassNames {
+    root?: string;
+    error?: string;
+    fieldError?: string;
+    label?: string;
+    input?: string;
+    select?: string;
+    textarea?: string;
+    submitButton?: string;
+}
+interface FormStyles {
+    root?: React.CSSProperties;
+    error?: React.CSSProperties;
+    fieldError?: React.CSSProperties;
+    label?: React.CSSProperties;
+    input?: React.CSSProperties;
+    select?: React.CSSProperties;
+    textarea?: React.CSSProperties;
+    submitButton?: React.CSSProperties;
+}
 interface FormProps<T extends ModelRecord> {
     model: string;
     fields?: FormField[];
@@ -63,16 +233,44 @@ interface FormProps<T extends ModelRecord> {
     onSuccess?: () => void;
     onError?: (err: Error) => void;
     submitLabel?: string;
+    classNames?: FormClassNames;
+    styles?: FormStyles;
+    unstyled?: boolean;
+    transformPayload?: (payload: Partial<T>) => Partial<T> | Promise<Partial<T>>;
+    onSubmitOverride?: (payload: Partial<T>) => Promise<void>;
     children?: React.ReactNode;
+    /**
+     * Per-field validation errors. Keys are field names, values are error messages.
+     * Use this to display server-side validation errors next to the relevant field.
+     * @example fieldErrors={{ email: 'Email is already taken' }}
+     */
+    fieldErrors?: Record<string, string>;
+    /**
+     * Client-side validation function. Called before submission.
+     * Return an object of field errors to block submission, or undefined/null to proceed.
+     * @example validate={(values) => values.password.length < 8 ? { password: 'Min 8 characters' } : undefined}
+     */
+    validate?: (values: Partial<T>) => Record<string, string> | undefined | null;
 }
-declare function Form<T extends ModelRecord>({ model, fields, initialValues, editId, onSuccess, onError, submitLabel, children, }: FormProps<T>): React.ReactElement;
+declare function Form<T extends ModelRecord>({ model, fields, initialValues, editId, onSuccess, onError, submitLabel, classNames, styles, unstyled, transformPayload, onSubmitOverride, children, fieldErrors: externalFieldErrors, validate, }: FormProps<T>): React.ReactElement;
 
 interface ProtectedProps {
     children: React.ReactNode;
+    /** Shown while auth state is being verified. Defaults to null (invisible). */
+    loadingFallback?: React.ReactNode;
+    /** Shown when user is not authenticated or lacks the required role. */
     fallback?: React.ReactNode;
+    /** If provided, user must have this exact role string to access the content. */
     role?: string;
 }
-declare function Protected({ children, fallback, role }: ProtectedProps): React.ReactElement;
+declare function Protected({ children, loadingFallback, fallback, role }: ProtectedProps): React.ReactElement;
+
+interface NeevBoundaryProps {
+    children: ReactNode;
+    loadingFallback?: ReactNode;
+    errorFallback?: (error: Error, resetErrorBoundary: () => void) => ReactNode;
+}
+declare function NeevBoundary({ children, loadingFallback, errorFallback }: NeevBoundaryProps): React.ReactElement;
 
 declare const AuthPlugin: NeevPlugin;
 
@@ -88,4 +286,4 @@ declare const CachePlugin: NeevPlugin;
 declare function createOfflinePlugin(): NeevPlugin;
 declare const OfflinePlugin: NeevPlugin;
 
-export { AuthClient, AuthPlugin, CachePlugin, Form, LoggerPlugin, NeevContext, NeevProvider, OfflinePlugin, Protected, Table, createCachePlugin, createClient, createOfflinePlugin, useAuth, useModel, useNeevClient, useSyncStatus };
+export { AuthClient, AuthPlugin, CachePlugin, Form, LoggerPlugin, NeevBoundary, NeevContext, NeevProvider, OfflinePlugin, Protected, SecureStore, Table, clearPersistedStore, createCachePlugin, createClient, createOfflinePlugin, getStore, setStore, useAuth, useModel, useNeevClient, useStore, useSyncStatus };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { NeevClientConfig, NeevClientInterface, AuthInterface, AuthUser, ModelRecord, UseModelReturn, SyncStatus, NeevPlugin } from '@neevjs/shared';
-export { ApiMeta, ApiResponse, AuthInterface, AuthLoginResponse, AuthUser, ModelRecord, NeevClientConfig, NeevClientInterface, NeevPlugin, NeevRequest, Pagination, QueuedAction, RequestOptions, SyncStatus, UseModelReturn } from '@neevjs/shared';
-import React from 'react';
+export { ApiMeta, ApiResponse, AuthInterface, AuthLoginResponse, AuthUser, ModelRecord, NeevClientConfig, NeevClientInterface, NeevPlugin, NeevRequest, Pagination, QueuedAction, RequestOptions, SyncStatus, UseModelReturn, VERSION } from '@neevjs/shared';
+import React, { ReactNode } from 'react';
 
 declare function createClient(config?: NeevClientConfig): NeevClientInterface;
 
@@ -24,25 +24,175 @@ declare class AuthClient implements AuthInterface {
     getToken(): string | null;
 }
 
-declare function useModel<T extends ModelRecord>(name: string): UseModelReturn<T>;
+/**
+ * SecureStore — AES-256-GCM encrypted client-side storage for NeevJS.
+ *
+ * ## Security model
+ * - Data is encrypted with AES-256-GCM before being written to localStorage.
+ * - The encryption key is generated fresh every session and lives ONLY in memory.
+ * - On page refresh the key is gone, so the encrypted ciphertext in localStorage
+ *   is permanently unreadable — it is automatically discarded.
+ * - This means SecureStore does NOT persist across page refreshes by design.
+ *   If you need truly sensitive data to survive refreshes, store it on the server.
+ *
+ * ## Threat model
+ * ✅ Protects against: physical access to device / localStorage dump
+ * ✅ Protects against: another browser tab/window reading the storage
+ * ❌ Does NOT protect against: XSS (attacker JS runs in your origin and can
+ *    call SecureStore.get() directly — same as any in-memory value)
+ *
+ * ## When to use
+ * - Temporary sensitive values during a session (payment amount, masked card, OTP state)
+ * - Values that must not appear in plaintext in DevTools Application → Storage
+ *
+ * ## API
+ * ```ts
+ * await SecureStore.set('pending_payment', { amount: 4999, currency: 'INR' })
+ * const payment = await SecureStore.get<Payment>('pending_payment')
+ * SecureStore.remove('pending_payment')
+ * SecureStore.clear()  // remove all SecureStore entries
+ * ```
+ */
+declare const SecureStore: {
+    /**
+     * Encrypt and store a value in localStorage.
+     * The value cannot be read without the in-memory session key.
+     */
+    set<T>(key: string, value: T): Promise<void>;
+    /**
+     * Retrieve and decrypt a value.
+     * Returns null if the key doesn't exist or cannot be decrypted
+     * (e.g. after a page refresh when the key is gone).
+     */
+    get<T>(key: string): Promise<T | null>;
+    /**
+     * Remove a specific key from SecureStore.
+     */
+    remove(key: string): void;
+    /**
+     * Remove ALL SecureStore entries from localStorage.
+     * Call this on logout to clean up all session-bound encrypted data.
+     */
+    clear(): void;
+};
+
+interface UseModelOptions {
+    suspense?: boolean;
+    /**
+     * Query parameters appended to the request URL.
+     * The full URL (including params) is used as the cache key, so
+     * useModel('users', { params: { page: 1 } }) and
+     * useModel('users', { params: { page: 2 } }) cache independently.
+     *
+     * @example params: { page: 1, role: 'admin', search: 'rahul' }
+     */
+    params?: Record<string, string | number | boolean | undefined>;
+    /**
+     * Override the client's default baseURL for this specific model instance.
+     * Useful for Hybrid Mode (connecting to different backends).
+     */
+    baseURL?: string;
+}
+declare function useModel<T extends ModelRecord>(name: string, options?: UseModelOptions): UseModelReturn<T>;
 
 declare function useAuth(): AuthInterface;
 
 declare function useSyncStatus(): SyncStatus;
 
+interface UseStoreOptions {
+    /**
+     * Persist value to localStorage. Survives page reloads and browser restarts.
+     *
+     * ⚠️ SECURITY: localStorage is readable by any JavaScript on the page.
+     * Do NOT use for sensitive data (passwords, payment info, PII).
+     * Use `{ session: true }` instead for semi-sensitive data.
+     *
+     * @default false
+     */
+    persist?: boolean;
+    /**
+     * Store value in sessionStorage. Survives page refresh but is:
+     * - Cleared when the browser tab closes
+     * - NOT shared across tabs
+     * - Safer than localStorage for semi-sensitive data (e.g. current user preferences)
+     *
+     * Cannot be combined with `persist: true`.
+     *
+     * @default false
+     */
+    session?: boolean;
+    /**
+     * TTL (time-to-live) in milliseconds. After this duration, the stored value
+     * expires and falls back to `initialValue`.
+     * Only applies when `persist` or `session` is true.
+     *
+     * @example ttl: 7 * 24 * 60 * 60 * 1000  // 7 days
+     */
+    ttl?: number;
+}
+/**
+ * `useStore` — Global client-side state management for NeevJS.
+ *
+ * Built on React 18's `useSyncExternalStore` for concurrent-mode safety.
+ *
+ * Security levels:
+ * - Default (in-memory only)  → Most secure. Lost on refresh.
+ * - `{ session: true }`       → sessionStorage. Safe for semi-sensitive data.
+ * - `{ persist: true }`       → localStorage. For non-sensitive preferences only.
+ *
+ * For truly sensitive data that must persist across sessions → store on the server.
+ */
+declare function useStore<T>(key: string, initialValue: T, options?: UseStoreOptions): [T, (updater: T | ((prev: T) => T)) => void];
+declare function getStore<T>(key: string): T | undefined;
+declare function setStore<T>(key: string, value: T): void;
+declare function clearPersistedStore(key: string): void;
+
 interface TableColumn<T extends ModelRecord> {
     key: keyof T & string;
     label?: string;
     render?: (value: T[keyof T], row: T) => React.ReactNode;
 }
+interface TableClassNames {
+    root?: string;
+    table?: string;
+    thead?: string;
+    tr?: string;
+    th?: string;
+    tbody?: string;
+    td?: string;
+    actions?: string;
+    editButton?: string;
+    deleteButton?: string;
+    emptyState?: string;
+    errorState?: string;
+    loadingState?: string;
+}
+interface TableStyles {
+    root?: React.CSSProperties;
+    table?: React.CSSProperties;
+    thead?: React.CSSProperties;
+    tr?: React.CSSProperties;
+    th?: React.CSSProperties;
+    tbody?: React.CSSProperties;
+    td?: React.CSSProperties;
+    actions?: React.CSSProperties;
+    editButton?: React.CSSProperties;
+    deleteButton?: React.CSSProperties;
+    emptyState?: React.CSSProperties;
+    errorState?: React.CSSProperties;
+    loadingState?: React.CSSProperties;
+}
 interface TableProps<T extends ModelRecord> {
     model: string;
     columns?: TableColumn<T>[];
     onEdit?: (row: T) => void;
     onDelete?: (row: T) => void;
     emptyMessage?: string;
+    classNames?: TableClassNames;
+    styles?: TableStyles;
+    unstyled?: boolean;
 }
-declare function Table<T extends ModelRecord>({ model, columns, onEdit, onDelete, emptyMessage, }: TableProps<T>): React.ReactElement;
+declare function Table<T extends ModelRecord>({ model, columns, onEdit, onDelete, emptyMessage, classNames, styles, unstyled, }: TableProps<T>): React.ReactElement;
 
 interface FormField {
     name: string;
@@ -55,6 +205,26 @@ interface FormField {
         value: string;
     }[];
 }
+interface FormClassNames {
+    root?: string;
+    error?: string;
+    fieldError?: string;
+    label?: string;
+    input?: string;
+    select?: string;
+    textarea?: string;
+    submitButton?: string;
+}
+interface FormStyles {
+    root?: React.CSSProperties;
+    error?: React.CSSProperties;
+    fieldError?: React.CSSProperties;
+    label?: React.CSSProperties;
+    input?: React.CSSProperties;
+    select?: React.CSSProperties;
+    textarea?: React.CSSProperties;
+    submitButton?: React.CSSProperties;
+}
 interface FormProps<T extends ModelRecord> {
     model: string;
     fields?: FormField[];
@@ -63,16 +233,44 @@ interface FormProps<T extends ModelRecord> {
     onSuccess?: () => void;
     onError?: (err: Error) => void;
     submitLabel?: string;
+    classNames?: FormClassNames;
+    styles?: FormStyles;
+    unstyled?: boolean;
+    transformPayload?: (payload: Partial<T>) => Partial<T> | Promise<Partial<T>>;
+    onSubmitOverride?: (payload: Partial<T>) => Promise<void>;
     children?: React.ReactNode;
+    /**
+     * Per-field validation errors. Keys are field names, values are error messages.
+     * Use this to display server-side validation errors next to the relevant field.
+     * @example fieldErrors={{ email: 'Email is already taken' }}
+     */
+    fieldErrors?: Record<string, string>;
+    /**
+     * Client-side validation function. Called before submission.
+     * Return an object of field errors to block submission, or undefined/null to proceed.
+     * @example validate={(values) => values.password.length < 8 ? { password: 'Min 8 characters' } : undefined}
+     */
+    validate?: (values: Partial<T>) => Record<string, string> | undefined | null;
 }
-declare function Form<T extends ModelRecord>({ model, fields, initialValues, editId, onSuccess, onError, submitLabel, children, }: FormProps<T>): React.ReactElement;
+declare function Form<T extends ModelRecord>({ model, fields, initialValues, editId, onSuccess, onError, submitLabel, classNames, styles, unstyled, transformPayload, onSubmitOverride, children, fieldErrors: externalFieldErrors, validate, }: FormProps<T>): React.ReactElement;
 
 interface ProtectedProps {
     children: React.ReactNode;
+    /** Shown while auth state is being verified. Defaults to null (invisible). */
+    loadingFallback?: React.ReactNode;
+    /** Shown when user is not authenticated or lacks the required role. */
     fallback?: React.ReactNode;
+    /** If provided, user must have this exact role string to access the content. */
     role?: string;
 }
-declare function Protected({ children, fallback, role }: ProtectedProps): React.ReactElement;
+declare function Protected({ children, loadingFallback, fallback, role }: ProtectedProps): React.ReactElement;
+
+interface NeevBoundaryProps {
+    children: ReactNode;
+    loadingFallback?: ReactNode;
+    errorFallback?: (error: Error, resetErrorBoundary: () => void) => ReactNode;
+}
+declare function NeevBoundary({ children, loadingFallback, errorFallback }: NeevBoundaryProps): React.ReactElement;
 
 declare const AuthPlugin: NeevPlugin;
 
@@ -88,4 +286,4 @@ declare const CachePlugin: NeevPlugin;
 declare function createOfflinePlugin(): NeevPlugin;
 declare const OfflinePlugin: NeevPlugin;
 
-export { AuthClient, AuthPlugin, CachePlugin, Form, LoggerPlugin, NeevContext, NeevProvider, OfflinePlugin, Protected, Table, createCachePlugin, createClient, createOfflinePlugin, useAuth, useModel, useNeevClient, useSyncStatus };
+export { AuthClient, AuthPlugin, CachePlugin, Form, LoggerPlugin, NeevBoundary, NeevContext, NeevProvider, OfflinePlugin, Protected, SecureStore, Table, clearPersistedStore, createCachePlugin, createClient, createOfflinePlugin, getStore, setStore, useAuth, useModel, useNeevClient, useStore, useSyncStatus };