ofpos-shared-core 1.1.0

package/dist/stores/sessionStore.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Modul penyimpanan sesi pengguna dengan deteksi idle dan re-authentication.
+ */
+import { Handler } from 'mitt';
+import { PosCore } from '../PosCore';
+import { User } from '../models/User';
+/**
+ * Tipe event untuk SessionStore.
+ */
+export type SessionEvents = {
+    /** Event update status sesi */
+    update: SessionState;
+    /** Event requirement re-authentication */
+    reauthenticate: undefined;
+};
+/**
+ * Status sesi pengguna.
+ */
+export interface SessionState {
+    /** Apakah pengguna sudah login */
+    isLoggedIn: boolean;
+    /** ID pengguna saat login, null jika tidak ada */
+    userId: string | null;
+    /** Objek user lengkap saat login, null jika tidak ada */
+    user: User | null;
+    /** Timestamp login terakhir, null jika tidak ada */
+    lastLoginAt: number | null;
+    /** Tenant context dari sesi autentikasi (SaaS), null jika tidak ada */
+    tenantId: string | null;
+}
+/**
+ * Nilai awal state sesi.
+ */
+export declare const initialSessionState: SessionState;
+/**
+ * Kelas penyimpanan sesi dengan idle timeout dan re-authentication.
+ */
+export declare class SessionStore {
+    private context;
+    private state;
+    private emitter;
+    private idleTimerId?;
+    private lastBlurAt;
+    private get idleTimeoutMs();
+    private get reauthTimeoutMs();
+    private readonly activityEvents;
+    private readonly onActivity;
+    private readonly onBlur;
+    private readonly onFocus;
+    /**
+     * Inisialisasi SessionStore.
+     * @param context Konteks PosCore aplikasi
+     */
+    constructor(context: PosCore);
+    /**
+     * Berlangganan perubahan state sesi.
+     * @param handler Handler yang dipanggil saat update
+     * @returns Fungsi untuk unsubscribe
+     */
+    subscribe(handler: Handler<SessionState>): () => void;
+    /**
+     * Berlangganan event re-authentication.
+     * @param handler Handler yang dipanggil saat reauthenticate
+     * @returns Fungsi untuk unsubscribe
+     */
+    onReauthenticate(handler: Handler<void>): () => void;
+    /**
+     * Mengambil salinan state saat ini.
+     */
+    getState(): SessionState;
+    /**
+     * Menyiapkan listener aktivitas pengguna untuk idle dan reauth.
+     */
+    private setupActivityListeners;
+    shutdown(): void;
+    /**
+     * Memulai timer idle untuk auto-logout.
+     */
+    private startIdleTimer;
+    /**
+     * Mereset ulang timer idle.
+     */
+    private resetIdleTimer;
+    /**
+     * Menghentikan timer idle.
+     */
+    private clearIdleTimer;
+    /**
+     * Menangani auto-logout saat idle.
+     */
+    private handleIdleLogout;
+    /**
+     * Melakukan login, mengubah state, dan memulai timer idle.
+     * @param user Objek user lengkap yang login
+     */
+    login(user: User & {
+        tenantId?: string | null;
+    }): void;
+    /**
+     * Melakukan logout, membersihkan token dan timer.
+     */
+    logout(): void;
+    /**
+     * Menggabungkan state baru dan menyimpan.
+     * @param patch Partial state yang akan diterapkan
+     */
+    private setState;
+}

package/dist/stores/storageAdapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Modul adapter penyimpanan abstrak.
+ */
+import { PosCore } from "../PosCore";
+/**
+ * Interface adapter penyimpanan kunci-nilai.
+ */
+export interface StorageAdapter {
+    /**
+     * Mengambil nilai berdasarkan key.
+     * @param key Kunci item
+     * @returns Promise atau nilai string|null
+     */
+    getItem(key: string): Promise<string | null> | string | null;
+    /**
+     * Menyimpan nilai dengan key tertentu.
+     * @param key Kunci item
+     * @param value Nilai string yang akan disimpan
+     */
+    setItem(key: string, value: string): Promise<void> | void;
+    /**
+     * Menghapus item berdasarkan key.
+     * @param key Kunci item yang akan dihapus
+     */
+    removeItem(key: string): Promise<void> | void;
+}
+/**
+ * Adapter penyimpanan memori untuk testing atau demo.
+ */
+export declare class MemoryStorage implements StorageAdapter {
+    private context;
+    private map;
+    /**
+     * Membuat instance MemoryStorage.
+     * @param context PosCore sebagai konteks (opsional)
+     */
+    constructor(context: PosCore);
+    /** {@inheritDoc StorageAdapter.getItem} */
+    getItem(key: string): string | null;
+    /** {@inheritDoc StorageAdapter.setItem} */
+    setItem(key: string, value: string): void;
+    /** {@inheritDoc StorageAdapter.removeItem} */
+    removeItem(key: string): void;
+}

package/dist/stores/syncService.d.ts

@@ -0,0 +1,90 @@
+import { PosCore } from '../PosCore';
+export type ConflictResolutionStrategy = 'server_wins' | 'local_wins_manual';
+/**
+ * Matriks conflict policy canonical per entitas.
+ * `server_wins`: perubahan server tetap diterapkan walau timestamp lokal lebih baru.
+ * `local_wins_manual`: perubahan lokal dipertahankan dan konflik dicatat untuk resolusi manual.
+ */
+export declare const CONFLICT_POLICY_MATRIX: Record<string, ConflictResolutionStrategy>;
+type SyncTraceContext = {
+    correlationId: string;
+    syncBatchId: string;
+};
+/**
+ * Interface dasar untuk layanan sinkronisasi.
+ */
+export interface ISyncService {
+    /**
+     * Wrapper retry dengan exponential backoff.
+     * @param fn Fungsi async yang dijalankan
+     * @param retries Jumlah maksimal percobaan ulang
+     * @param delay Delay dasar (ms) untuk backoff
+     */
+    backoff<T>(fn: () => Promise<T>, retries?: number, delay?: number): Promise<T>;
+    /**
+     * Menerapkan serangkaian perubahan (CRUD) ke adapter lokal.
+     * @param changes Daftar objek perubahan
+     */
+    applyChanges(changes: Array<{
+        table: string;
+        id: string;
+        updated_at: number;
+        [key: string]: any;
+    }>): Promise<void>;
+    /**
+     * Sinkronisasi data dasar dari ERP.
+     */
+    syncWithErp(): Promise<void>;
+    /**
+     * Loop sinkronisasi penuh: dorong, tarik, ERP, dan pembersihan.
+     */
+    syncLoop(): Promise<void>;
+}
+/**
+ * Implementasi layanan sinkronisasi.
+ */
+export declare class SyncService {
+    private context;
+    private readonly dbAdapter;
+    private readonly apiService?;
+    private readonly syncStore;
+    private debounceTimer?;
+    private periodicTimer?;
+    private unsubscribeStore?;
+    private readonly onDataChanged;
+    private lastAlertAtByCode;
+    /**
+     * Membuat instance SyncService.
+     * @param context Konteks PosCore aplikasi
+     */
+    constructor(context: PosCore);
+    private normalizeOutgoingChange;
+    private getRemoteTimestamp;
+    private getConflictResolutionStrategy;
+    private requireBranchContext;
+    /**
+     * Menjalankan fungsi dengan retry dan exponential backoff.
+     */
+    backoff<T>(fn: () => Promise<T>, retries?: number, delay?: number): Promise<T>;
+    /**
+     * Menerapkan array perubahan ke database lokal.
+     */
+    applyChanges(changes: any[], traceContext?: SyncTraceContext): Promise<void>;
+    /**
+     * Sinkronisasi data master dari ERP.
+     */
+    syncWithErp(traceContext?: SyncTraceContext): Promise<void>;
+    /**
+     * Cleanup data yang dihapus (belum diimplementasi generik).
+     */
+    private cleanupDeleted;
+    private shouldTriggerAlert;
+    private emitOperationalAlert;
+    private evaluateOperationalAlerts;
+    /**
+     * Loop sinkronisasi lengkap: push, pull, ERP, pembersihan.
+     */
+    syncLoop(): Promise<void>;
+    shutdown(): void;
+}
+export {};

package/dist/stores/syncStore.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Modul penyimpanan state sinkronisasi dengan persistensi.
+ */
+import { Handler } from 'mitt';
+import { PosCore } from '../PosCore';
+/**
+ * Event untuk SyncStore.
+ */
+export type SyncEvents = {
+    /** Event update state */
+    update: State;
+};
+/**
+ * Struktur state sinkronisasi.
+ */
+export interface State {
+    /** Status: idle, syncing, atau error */
+    status: 'idle' | 'syncing' | 'error';
+    /** Daftar perubahan antrean */
+    queue: SyncChange[];
+    /** Panjang antrean */
+    queueLength: number;
+    /** Daftar konflik terdeteksi */
+    conflicts: Array<Record<string, unknown>>;
+    /** Perubahan yang dipindahkan ke dead-letter queue setelah gagal permanen */
+    deadLetters: SyncDeadLetter[];
+    /** Metrik agregat sinkronisasi untuk observability baseline */
+    metrics: SyncMetrics;
+    /** Error terakhir jika ada */
+    lastError: Error | null;
+    /** Timestamp terakhir sinkron */
+    lastSyncAt: number | null;
+}
+/**
+ * Nilai awal state sinkronisasi.
+ */
+export declare const initialState: State;
+export type SyncChangeType = 'CREATE' | 'UPDATE' | 'DELETE';
+export interface SyncChange {
+    id: string;
+    table: string;
+    type: SyncChangeType;
+    record: Record<string, unknown>;
+    updated_at: number;
+    firstQueuedAt: number;
+    retryCount: number;
+    lastAttemptAt: number | null;
+    lastErrorMessage: string | null;
+}
+export interface SyncDeadLetter {
+    movedAt: number;
+    reason: string;
+    attempts: number;
+    errorMessage: string | null;
+    change: SyncChange;
+}
+export interface SyncMetrics {
+    totalPushAttempted: number;
+    totalPushSucceeded: number;
+    totalPushFailed: number;
+    totalPullApplied: number;
+    totalConflictsRecorded: number;
+    lastQueueLatencyMs: number;
+    lastRunDurationMs: number;
+    lastRunAt: number | null;
+}
+type SyncTraceContext = {
+    correlationId?: string;
+    syncBatchId?: string;
+};
+/**
+ * Kelas penyimpanan sinkronisasi berbasis mitt dan storage adapter.
+ */
+export declare class SyncStore {
+    private context;
+    private state;
+    private emitter;
+    private storage;
+    /**
+     * Membuat instance SyncStore.
+     * @param context Konteks PosCore aplikasi
+     */
+    constructor(context: PosCore);
+    /**
+     * Berlangganan update state.
+     * @param handler Handler dipanggil saat update
+     * @returns Fungsi unsubscribe
+     */
+    subscribe(handler: Handler<State>): () => void;
+    /**
+     * Mengambil salinan state.
+     */
+    getState(): State;
+    /**
+     * Menggabungkan patch ke state, menyimpan, dan emit update.
+     * @param patch Partial state yang akan diterapkan
+     */
+    private setState;
+    private normalizeChange;
+    /**
+     * Memulai proses sinkronisasi.
+     */
+    startSync(traceContext?: SyncTraceContext): void;
+    /**
+     * Mengatur error pada state.
+     * @param error Error yang terjadi
+     */
+    setError(error: Error, traceContext?: SyncTraceContext): void;
+    /**
+     * Membersihkan error jika sebelumnya ada.
+     */
+    clearError(): void;
+    /**
+     * Menambahkan perubahan ke antrean.
+     * @param change Objek perubahan
+     */
+    enqueueChange(change: any): void;
+    /**
+     * Mengeluarkan perubahan terdepan dari antrean.
+     */
+    dequeueChange(): void;
+    removeQueuedChange(changeId: string): void;
+    /**
+     * Menambahkan detail konflik.
+     * @param conflict Objek detail konflik
+     */
+    addConflict(conflict: any): void;
+    markRetryAttempt(changeId: string, error?: unknown): void;
+    moveToDeadLetter(changeId: string, reason: string, error?: unknown): void;
+    requeueDeadLetter(changeId: string): boolean;
+    recordSyncMetrics(patch: Partial<SyncMetrics>): void;
+    /**
+     * Menghapus semua konflik.
+     */
+    clearConflicts(): void;
+    /**
+     * Mengatur timestamp terakhir sinkron.
+     * @param timestamp Waktu dalam milidetik
+     */
+    setLastSyncAt(timestamp: number): void;
+    /**
+     * Menandai selesai sinkron dan kembali ke idle.
+     */
+    finishSync(traceContext?: SyncTraceContext): void;
+    /**
+     * Menghapus semua data antrean dan state saat logout.
+     */
+    logoutLocal(): void;
+    /**
+     * Menyimpan state ke storage.
+     */
+    private save;
+    /**
+     * Memuat state dari storage.
+     * @returns Promise State atau null
+     */
+    private load;
+    /**
+     * Shutdown emitter dan listeners.
+     */
+    shutdown(): Promise<void>;
+}
+export {};

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "ofpos-shared-core",
+  "version": "1.1.0",
+  "description": "Offline-first POS client-side core library, platform and database agnostic.",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "browser": "dist/index.browser.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    },
+    "./browser": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.browser.mjs"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc -b && node esbuild.config.js",
+    "bundle": "node esbuild.config.js",
+    "lint": "eslint \"src/**/*.{ts,js}\"",
+    "test": "jest --coverage",
+    "test:package-matrix": "bash ./scripts/verify-package-matrix.sh",
+    "verify:mode-matrix": "bash ./scripts/verify-mode-matrix.sh",
+    "build:distribution": "bash ./scripts/build-distribution-artifacts.sh",
+    "verify:distribution": "bash ./scripts/verify-distribution-artifacts.sh",
+    "verify:release-discipline": "node ./scripts/verify-release-discipline.js",
+    "verify:ofcore-spike": "node ./scripts/verify-ofcore-spike.js",
+    "verify:ofcore-bridges": "node ./scripts/verify-ofcore-bridges.js",
+    "verify:no-internal-bridge-imports": "node ./scripts/verify-no-internal-bridge-imports.js",
+    "verify:governance": "node ./scripts/verify-governance-transport.js",
+    "verify:governance:negative": "node ./scripts/verify-governance-transport-negative.js",
+    "verify:poscore-runtime-bridge": "node ./scripts/verify-poscore-runtime-bridge.js",
+    "verify:poscore-overrides": "node ./scripts/verify-poscore-overrides.js",
+    "audit:schema": "node ./scripts/schema-audit.js",
+    "docs:check-links": "bash ./scripts/check-docs-links.sh",
+    "ci:check": "npm run lint && npm test -- --runInBand && npm run build && npm run verify:release-discipline && npm run verify:ofcore-bridges && npm run verify:no-internal-bridge-imports && npm run verify:governance && npm run verify:governance:negative && npm run verify:poscore-runtime-bridge && npm run verify:poscore-overrides && npm run docs:check-links",
+    "test:watch": "jest --watch",
+    "docs": "typedoc src/index.ts --out tsdocs",
+    "prepack": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourorg/shared-core.git"
+  },
+  "author": "Agus Made <krisnaparta@gmail.com>",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ofcore": "0.1.0-alpha.0",
+    "ofauth-shared-core": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/crypto-js": "^4.2.2",
+    "@types/jest": "^30.0.0",
+    "@types/reflect-metadata": "^0.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.1",
+    "@typescript-eslint/parser": "^8.46.1",
+    "bcryptjs": "^3.0.2",
+    "crypto-js": "^4.2.0",
+    "date-fns": "^4.1.0",
+    "dotenv": "^16.0.3",
+    "esbuild": "^0.25.11",
+    "eslint": "^9.37.0",
+    "jest": "^30.2.0",
+    "jest-html-reporters": "^3.1.7",
+    "mitt": "^3.0.1",
+    "react": "^19.2.0",
+    "reflect-metadata": "^0.2.2",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.4.5",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.28.14",
+    "typescript": "^5.9.3",
+    "uuidv7": "^1.0.2"
+  }
+}