@nice2dev/erp-adapter 0.1.0 → 1.0.3

package/dist/middleware.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ErpMiddleware — composable request/response interceptor pipeline.
+ *
+ * Middleware functions wrap `fetch` calls, enabling logging, retry,
+ * header injection, metrics, caching, etc. without modifying adapters.
+ *
+ * Usage:
+ *   const pipeline = createMiddlewarePipeline([
+ *     loggingMiddleware(),
+ *     retryMiddleware({ maxRetries: 3 }),
+ *   ]);
+ *   const adapter = new ErpDataAdapter({ baseUrl: '/api/products', fetch: pipeline(fetch) });
+ */
+/** Request context available to middleware. */
+export interface ErpRequestContext {
+    url: string;
+    init: RequestInit;
+    /** Custom metadata bag — middleware can attach/read arbitrary keys. */
+    meta: Record<string, unknown>;
+}
+/** A middleware function: receives context + next handler, returns Response. */
+export type ErpMiddleware = (ctx: ErpRequestContext, next: (ctx: ErpRequestContext) => Promise<Response>) => Promise<Response>;
+/**
+ * Compose an array of middleware into a single `fetch`-compatible function.
+ *
+ * Middleware executes in order: first in the array wraps outermost.
+ * The innermost call delegates to the real `fetch`.
+ */
+export declare function createMiddlewarePipeline(middlewares: ErpMiddleware[]): (baseFetch?: typeof fetch) => typeof fetch;
+/** Logging middleware — logs request/response timing to console. */
+export declare function loggingMiddleware(): ErpMiddleware;
+export interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3). */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 500). */
+    baseDelay?: number;
+    /** HTTP status codes that trigger retry (default: [408, 429, 500, 502, 503, 504]). */
+    retryOn?: number[];
+}
+/** Retry middleware with exponential backoff for transient failures. */
+export declare function retryMiddleware(opts?: RetryOptions): ErpMiddleware;
+/** Header injection middleware — merges extra headers into every request. */
+export declare function headerMiddleware(headers: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>)): ErpMiddleware;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,WAAW,CAAC;IAClB,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,CACxB,GAAG,EAAE,iBAAiB,EACtB,IAAI,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,QAAQ,CAAC,KAClD,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEvB;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACpC,WAAW,EAAE,aAAa,EAAE,GAC7B,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,KAAK,OAAO,KAAK,CAwB5C;AAID,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,aAAa,CAejD;AAED,MAAM,WAAW,YAAY;IACzB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,aAAa,CAyBlE;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GACnG,aAAa,CAMf"}

package/dist/useCollaborativeDataGrid.d.ts

@@ -0,0 +1,132 @@
+import { ErpSignalRAdapter, SignalRStatus } from './ErpSignalRAdapter';
+import { UseSignalRLiveDataOptions } from './useSignalRLiveData';
+import { PresenceUser, EntityPresenceInfo, EntityPresenceStatus } from './useEntityPresence';
+/** Cell position in the grid. */
+export interface CellPosition {
+    rowKey: unknown;
+    field: string;
+}
+/** Range of cells. */
+export interface CellRange {
+    startRowKey: unknown;
+    endRowKey: unknown;
+    startField: string;
+    endField: string;
+}
+/** Pending cell edit. */
+export interface PendingEdit<T = unknown> {
+    cell: CellPosition;
+    originalValue: T;
+    newValue: T;
+    timestamp: number;
+}
+/** Conflict resolution strategy. */
+export type ConflictStrategy = "last-write-wins" | "first-write-wins" | "merge" | "ask-user" | "reject";
+/** Edit conflict information. */
+export interface EditConflict<T = unknown> {
+    cell: CellPosition;
+    localValue: T;
+    remoteValue: T;
+    localUser: PresenceUser;
+    remoteUser: PresenceUser;
+    localTimestamp: number;
+    remoteTimestamp: number;
+}
+/** User cursor/selection in the grid. */
+export interface UserSelection {
+    user: PresenceUser;
+    selectedCells: CellPosition[];
+    selectedRows: unknown[];
+    focusedCell: CellPosition | null;
+    editingCell: CellPosition | null;
+    color: string;
+}
+/** Configuration for useCollaborativeDataGrid hook. */
+export interface UseCollaborativeDataGridOptions<T> {
+    /** The SignalR adapter instance. */
+    adapter: ErpSignalRAdapter;
+    /** Entity type name (e.g., "orders"). */
+    entityType: string;
+    /** Primary key field name. */
+    keyField: keyof T & string;
+    /** Current user information. */
+    currentUser: PresenceUser;
+    /** Initial data array. */
+    initialData?: T[];
+    /** Conflict resolution strategy. Default: "last-write-wins". */
+    conflictStrategy?: ConflictStrategy;
+    /** Custom merge function for "merge" strategy. */
+    mergeFunction?: (local: T, remote: T, field: string) => T;
+    /** Called when a conflict needs user resolution (for "ask-user" strategy). */
+    onConflict?: (conflict: EditConflict<any>) => Promise<"local" | "remote" | "merge">;
+    /** Called before a cell edit is committed. Return false to cancel. */
+    onBeforeCommit?: (cell: CellPosition, oldValue: any, newValue: any) => boolean | Promise<boolean>;
+    /** Called after a cell edit is committed. */
+    onAfterCommit?: (cell: CellPosition, newValue: any) => void;
+    /** Enable cell-level locking. Default: true. */
+    enableCellLocking?: boolean;
+    /** Lock timeout in ms. Default: 60000 (1 min). */
+    lockTimeout?: number;
+    /** Enable cursor sharing. Default: true. */
+    enableCursorSharing?: boolean;
+    /** Cursor update debounce in ms. Default: 50. */
+    cursorDebounce?: number;
+    /** Enable optimistic updates. Default: true. */
+    optimisticUpdates?: boolean;
+    /** Flash updated rows. Default: true. */
+    flashChanges?: boolean;
+    /** Flash duration in ms. Default: 500. */
+    flashDuration?: number;
+    /** Additional options for SignalR live data. */
+    liveDataOptions?: Partial<UseSignalRLiveDataOptions<T>>;
+}
+/** State returned by useCollaborativeDataGrid hook. */
+export interface CollaborativeDataGridState<T> {
+    /** Current data array with real-time updates. */
+    data: T[];
+    /** All user presence information. */
+    presence: EntityPresenceInfo[];
+    /** Other users' selections and cursors. */
+    userSelections: UserSelection[];
+    /** Current user's selection. */
+    mySelection: UserSelection;
+    /** Set of row keys that were recently changed (for flash animation). */
+    flashedKeys: Set<unknown>;
+    /** Pending local edits. */
+    pendingEdits: Map<string, PendingEdit>;
+    /** Connection status. */
+    connectionStatus: SignalRStatus;
+    /** Current user's presence status. */
+    myPresenceStatus: EntityPresenceStatus;
+    /** Set focused cell. */
+    setFocusedCell: (cell: CellPosition | null) => void;
+    /** Set selected cells. */
+    setSelectedCells: (cells: CellPosition[]) => void;
+    /** Set selected rows. */
+    setSelectedRows: (rowKeys: unknown[]) => void;
+    /** Start editing a cell. Returns false if locked by another user. */
+    startCellEdit: (cell: CellPosition) => boolean;
+    /** Commit a cell edit. */
+    commitCellEdit: (cell: CellPosition, newValue: any) => Promise<boolean>;
+    /** Cancel a cell edit. */
+    cancelCellEdit: (cell: CellPosition) => void;
+    /** Check if a cell is locked by another user. */
+    isCellLocked: (cell: CellPosition) => boolean;
+    /** Get the user editing a cell (if any). */
+    getCellEditor: (cell: CellPosition) => PresenceUser | null;
+    /** Get the user's cursor color. */
+    getUserColor: (userId: string) => string;
+    /** Insert a new row. */
+    insertRow: (data: Partial<T>) => Promise<void>;
+    /** Update a row. */
+    updateRow: (key: unknown, changes: Partial<T>) => Promise<void>;
+    /** Delete a row. */
+    deleteRow: (key: unknown) => Promise<void>;
+    /** Resolve a pending conflict. */
+    resolveConflict: (cell: CellPosition, resolution: "local" | "remote" | "merge") => void;
+    /** Get current conflicts. */
+    conflicts: EditConflict[];
+}
+export declare function useCollaborativeDataGrid<T extends Record<string, any>>(options: UseCollaborativeDataGridOptions<T>): CollaborativeDataGridState<T>;
+export default useCollaborativeDataGrid;
+//# sourceMappingURL=useCollaborativeDataGrid.d.ts.map

package/dist/useCollaborativeDataGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCollaborativeDataGrid.d.ts","sourceRoot":"","sources":["../src/useCollaborativeDataGrid.ts"],"names":[],"mappings":"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"}

package/dist/useEntityPresence.d.ts

@@ -0,0 +1,136 @@
+import { ErpSignalRAdapter, SignalRStatus } from './ErpSignalRAdapter';
+/** User presence status for entity tracking. */
+export type EntityPresenceStatus = "viewing" | "editing" | "idle" | "away";
+/** User information for presence display. */
+export interface PresenceUser {
+    /** User ID. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Avatar URL (optional). */
+    avatarUrl?: string;
+    /** User's email (optional). */
+    email?: string;
+    /** Custom color for cursor/indicator. */
+    color?: string;
+}
+/** Presence data for a single user on an entity. */
+export interface EntityPresenceInfo {
+    /** The user. */
+    user: PresenceUser;
+    /** Current presence status. */
+    status: EntityPresenceStatus;
+    /** When they joined this entity view. */
+    joinedAt: string;
+    /** Last activity timestamp. */
+    lastActivityAt: string;
+    /** Field being edited (if editing). */
+    editingField?: string;
+    /** Cursor position (for text fields). */
+    cursorPosition?: {
+        start: number;
+        end: number;
+    };
+    /** Selection range (for grids). */
+    selectedRange?: {
+        startRow: number;
+        endRow: number;
+        startCol: number;
+        endCol: number;
+    };
+}
+/** Configuration for useEntityPresence hook. */
+export interface UseEntityPresenceOptions {
+    /** The SignalR adapter instance. */
+    adapter: ErpSignalRAdapter;
+    /** Entity type name (e.g., "orders", "employees"). */
+    entityType: string;
+    /** Entity ID being viewed/edited. Can be array for bulk selection. */
+    entityId: string | string[];
+    /** Current user information. */
+    currentUser: PresenceUser;
+    /** Initial presence status. Default: "viewing". */
+    initialStatus?: EntityPresenceStatus;
+    /** Heartbeat interval in ms. Default: 30000. */
+    heartbeatInterval?: number;
+    /** Idle timeout in ms. Default: 60000 (1 min). */
+    idleTimeout?: number;
+    /** Away timeout in ms. Default: 300000 (5 min). */
+    awayTimeout?: number;
+    /** Hub method for joining. Default: "JoinEntityView". */
+    joinMethod?: string;
+    /** Hub method for leaving. Default: "LeaveEntityView". */
+    leaveMethod?: string;
+    /** Hub method for status update. Default: "UpdateEntityPresence". */
+    updateMethod?: string;
+    /** Hub event for presence changes. Default: "EntityPresenceChanged". */
+    presenceEventName?: string;
+    /** Hub event for user joined. Default: "EntityUserJoined". */
+    joinedEventName?: string;
+    /** Hub event for user left. Default: "EntityUserLeft". */
+    leftEventName?: string;
+    /** Called when presence list changes. */
+    onPresenceChange?: (presence: EntityPresenceInfo[]) => void;
+    /** Called when a conflict is detected. */
+    onEditConflict?: (editor: PresenceUser, field?: string) => void;
+}
+/** State returned by useEntityPresence hook. */
+export interface EntityPresenceState {
+    /** All users currently present on this entity. */
+    presence: EntityPresenceInfo[];
+    /** Users only viewing (not editing). */
+    viewers: PresenceUser[];
+    /** Users currently editing. */
+    editors: PresenceUser[];
+    /** Current user's status. */
+    myStatus: EntityPresenceStatus;
+    /** Set current user's status. */
+    setMyStatus: (status: EntityPresenceStatus, editingField?: string) => void;
+    /** Start editing a field. */
+    startEditing: (field: string) => void;
+    /** Stop editing. */
+    stopEditing: () => void;
+    /** Update cursor/selection position. */
+    updateSelection: (selection: EntityPresenceInfo["selectedRange"] | EntityPresenceInfo["cursorPosition"]) => void;
+    /** SignalR connection status. */
+    connectionStatus: SignalRStatus;
+    /** Check if another user is editing a specific field. */
+    isFieldLocked: (field: string) => PresenceUser | null;
+    /** Check if there are any active editors (conflict potential). */
+    hasActiveEditors: boolean;
+    /** Get the user editing a field (if any). */
+    getFieldEditor: (field: string) => PresenceUser | null;
+    /** Force refresh presence list. */
+    refresh: () => Promise<void>;
+}
+export declare function useEntityPresence(options: UseEntityPresenceOptions): EntityPresenceState;
+/** Generate a consistent color for a user (based on ID hash). */
+export declare function generateUserColor(userId: string): string;
+/** Format presence status for display. */
+export declare function formatPresenceStatus(status: EntityPresenceStatus): string;
+export interface MultiEntityPresenceOptions {
+    /** The SignalR adapter instance. */
+    adapter: ErpSignalRAdapter;
+    /** Entity type name. */
+    entityType: string;
+    /** Current user information. */
+    currentUser: PresenceUser;
+    /** Hub event name for batch presence updates. Default: "BatchPresenceUpdate". */
+    batchEventName?: string;
+}
+export interface MultiEntityPresenceState {
+    /** Map of entity ID to presence info array. */
+    presenceByEntity: Map<string, EntityPresenceInfo[]>;
+    /** Get presence for a specific entity. */
+    getPresence: (entityId: string) => EntityPresenceInfo[];
+    /** Check if any user is editing an entity. */
+    isEntityBeingEdited: (entityId: string) => boolean;
+    /** Get editors for an entity. */
+    getEntityEditors: (entityId: string) => PresenceUser[];
+}
+/**
+ * Hook for tracking presence across multiple entities at once.
+ * Useful for DataGrid row-level presence indicators.
+ */
+export declare function useMultiEntityPresence(options: MultiEntityPresenceOptions): MultiEntityPresenceState;
+//# sourceMappingURL=useEntityPresence.d.ts.map

package/dist/useEntityPresence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useEntityPresence.d.ts","sourceRoot":"","sources":["../src/useEntityPresence.ts"],"names":[],"mappings":"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"}

package/dist/useSignalRLiveData.d.ts

@@ -0,0 +1,121 @@
+import { ErpSignalRAdapter, SignalRStatus } from './ErpSignalRAdapter';
+/** Type of real-time data operation. */
+export type LiveDataOperation = "insert" | "update" | "delete";
+/** A single real-time data change event. */
+export interface LiveDataChange<T = unknown> {
+    /** Operation type: insert, update, or delete. */
+    operation: LiveDataOperation;
+    /** Entity type name (e.g., "employees", "orders"). */
+    entityName: string;
+    /** Primary key of the affected row. */
+    key: unknown;
+    /** Full data for insert/update; undefined for delete. */
+    data?: T;
+    /** Partial changes for update (fields that changed). */
+    changes?: Partial<T>;
+    /** Server timestamp of the change. */
+    timestamp?: string;
+    /** User ID who made the change. */
+    changedBy?: string;
+}
+/** Configuration for useSignalRLiveData hook. */
+export interface UseSignalRLiveDataOptions<T> {
+    /** The SignalR adapter instance. */
+    adapter: ErpSignalRAdapter;
+    /** Entity name to subscribe to (e.g., "employees"). */
+    entityName: string;
+    /** Primary key field name. */
+    keyField: keyof T & string;
+    /** Initial data array. */
+    initialData?: T[];
+    /** Called when a remote change is received. Return false to reject the update. */
+    onBeforeChange?: (change: LiveDataChange<T>) => boolean | Promise<boolean>;
+    /** Called after a change has been applied locally. */
+    onAfterChange?: (change: LiveDataChange<T>, data: T[]) => void;
+    /** Called when there's a conflict (local pending edit vs remote update). */
+    onConflict?: (local: T, remote: T, change: LiveDataChange<T>) => T | "local" | "remote" | "merge";
+    /** Hub method name for subscribing. Default: "SubscribeToEntity". */
+    subscribeMethod?: string;
+    /** Hub method name for unsubscribing. Default: "UnsubscribeFromEntity". */
+    unsubscribeMethod?: string;
+    /** Hub event name for data changes. Default: "EntityChanged". */
+    changeEventName?: string;
+    /** Enable flash animation for changed rows. */
+    flashChanges?: boolean;
+    /** Duration of flash animation in ms. Default: 500. */
+    flashDuration?: number;
+    /** Enable optimistic UI updates. Default: true. */
+    optimisticUpdates?: boolean;
+}
+/** State returned by useSignalRLiveData hook. */
+export interface SignalRLiveDataState<T> {
+    /** Current data array with real-time updates applied. */
+    data: T[];
+    /** SignalR connection status. */
+    status: SignalRStatus;
+    /** Set of row keys that were recently changed (for flash animation). */
+    flashedKeys: Set<unknown>;
+    /** Set of row keys with pending local changes. */
+    pendingKeys: Set<unknown>;
+    /** Last error if any. */
+    error: Error | null;
+    /** Manually apply a remote update (for testing or custom handling). */
+    applyRemoteUpdate: (change: LiveDataChange<T>) => void;
+    /** Register a local pending change (for optimistic UI). */
+    registerPendingChange: (key: unknown, change: Partial<T>) => void;
+    /** Confirm a pending change was saved server-side. */
+    confirmPendingChange: (key: unknown) => void;
+    /** Rollback a pending change (server rejected). */
+    rollbackPendingChange: (key: unknown) => void;
+    /** Force re-subscribe to the entity. */
+    resubscribe: () => Promise<void>;
+}
+export declare function useSignalRLiveData<T extends Record<string, any>>(options: UseSignalRLiveDataOptions<T>): SignalRLiveDataState<T>;
+export interface SignalRDataSourceConfig<T> {
+    /** The SignalR adapter instance. */
+    adapter: ErpSignalRAdapter;
+    /** Entity name for subscriptions. */
+    entityName: string;
+    /** Primary key field. */
+    keyField: keyof T & string;
+    /** Hub method name to fetch initial data. Default: "GetEntities". */
+    fetchMethod?: string;
+    /** Hub method name to insert. Default: "InsertEntity". */
+    insertMethod?: string;
+    /** Hub method name to update. Default: "UpdateEntity". */
+    updateMethod?: string;
+    /** Hub method name to delete. Default: "DeleteEntity". */
+    deleteMethod?: string;
+}
+/**
+ * Create callbacks for CRUD operations via SignalR.
+ * Use with useSignalRLiveData for a complete real-time data solution.
+ */
+export declare function createSignalRDataOperations<T extends Record<string, any>>(config: SignalRDataSourceConfig<T>): {
+    /** Fetch all entities from the hub. */
+    fetchAll(options?: {
+        skip?: number;
+        take?: number;
+        filter?: unknown;
+    }): Promise<T[]>;
+    /** Insert a new entity via the hub. */
+    insert(data: Partial<T>): Promise<T>;
+    /** Update an existing entity via the hub. */
+    update(key: unknown, changes: Partial<T>): Promise<T>;
+    /** Delete an entity via the hub. */
+    remove(key: unknown): Promise<void>;
+    /** Get the key field name. */
+    getKeyField(): keyof T & string;
+};
+export interface BatchChange<T> {
+    operation: LiveDataOperation;
+    key: unknown;
+    data?: T;
+    changes?: Partial<T>;
+}
+/**
+ * Apply multiple changes to a data array efficiently.
+ * Useful for initial sync or batch operations.
+ */
+export declare function applyBatchChanges<T extends Record<string, any>>(data: T[], changes: BatchChange<T>[], keyField: keyof T & string): T[];
+//# sourceMappingURL=useSignalRLiveData.d.ts.map

package/dist/useSignalRLiveData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSignalRLiveData.d.ts","sourceRoot":"","sources":["../src/useSignalRLiveData.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice2dev/erp-adapter",
-  "version": "0.1.0",
+  "version": "1.0.3",
   "description": "Adapter layer connecting OmniVerk .NET backend with @nice2dev/* React components",
   "type": "module",
   "main": "dist/index.cjs",
@@ -50,6 +50,7 @@
     "react-dom": "^18.2.0",
     "typescript": "^5.3.3",
     "vite": "^6.2.0",
-    "vite-plugin-dts": "^4.5.0"
+    "vite-plugin-dts": "^4.5.0",
+    "vitest": "^4.1.0"
   }
 }