@burgantech/context-store 0.1.0

package/dist/context-store.d.ts

@@ -0,0 +1,101 @@
+import { Boundary, Storage, Envelope, ContextStoreOptions, Observable, IContextStore } from './types';
+export declare class ContextStore implements IContextStore {
+    private _activeDevice;
+    private _activeUser;
+    private _activeSubject;
+    private memoryStore;
+    private encryptionKey;
+    private timeManager;
+    private log;
+    private appName;
+    private appVersion;
+    private listeners;
+    private subjectsByStorageKey;
+    private constructor();
+    static create(options: ContextStoreOptions): ContextStore;
+    get activeDevice(): string | null;
+    get activeUser(): string | null;
+    set activeUser(value: string | null);
+    get activeSubject(): string | null;
+    set activeSubject(value: string | null);
+    getServerTime(): Promise<Date>;
+    setEncryptionKey(key: string): void;
+    get isEncryptionKeySet(): boolean;
+    revokeEncryptionKey(): void;
+    setData(boundary: Boundary, key: string, value: any, options?: {
+        storage?: Storage;
+        ttl?: number;
+        dataPath?: string;
+    }): void;
+    getData<T = any>(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): T | undefined;
+    getDataMetadata(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+    }): Envelope | undefined;
+    deleteData(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): void;
+    batchSet(operations: Array<{
+        boundary: Boundary;
+        key: string;
+        value: any;
+        storage?: Storage;
+        ttl?: number;
+    }>): void;
+    batchGet(operations: Array<{
+        boundary: Boundary;
+        key: string;
+        storage?: Storage;
+    }>): Array<{
+        boundary: Boundary;
+        key: string;
+        value: any;
+    }>;
+    observeData(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): Observable<any>;
+    addListener(listenerId: string, boundary: Boundary, key: string, callback: (value: any) => void, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): void;
+    removeListener(listenerId: string): void;
+    clearAllListeners(): void;
+    findKeys(boundary: Boundary, partialKey: string, options?: {
+        storage?: Storage;
+    }): string[];
+    clearData(boundary: Boundary, options?: {
+        storage?: Storage;
+        partialKey?: string;
+    }): void;
+    exportData(boundary: Boundary, options?: {
+        storage?: Storage;
+        partialKey?: string;
+    }): Record<string, any>;
+    importData(boundary: Boundary, data: Record<string, any>, options?: {
+        storage?: Storage;
+        overwrite?: boolean;
+    }): void;
+    cleanup(options?: {
+        boundary?: Boundary;
+        storage?: Storage;
+    }): void;
+    private buildStorageKey;
+    private buildKeyPrefix;
+    private identityScope;
+    private readRaw;
+    private writeRaw;
+    private deleteRaw;
+    private allKeysIn;
+    private readEnvelope;
+    private makeEnvelope;
+    private touchEnvelope;
+    private emit;
+    private isPemOrDer;
+    private initDeviceId;
+    private detectAppName;
+    private detectAppVersion;
+}

package/dist/context-store.js

@@ -0,0 +1,555 @@
+import { Boundary, Storage, } from './types';
+import { ServerTimeManager } from './server-time';
+import { encrypt, decrypt } from './crypto';
+const SDK_VERSION = '0.1.0';
+const KEY_PREFIX = 'cs';
+// ---------------------------------------------------------------------------
+// Internal Subject (minimal pub-sub)
+// ---------------------------------------------------------------------------
+class Subject {
+    subs = new Set();
+    next(v) {
+        for (const cb of this.subs) {
+            try {
+                cb(v);
+            }
+            catch {
+                /* subscriber errors must not propagate */
+            }
+        }
+    }
+    subscribe(cb) {
+        this.subs.add(cb);
+        return { unsubscribe: () => this.subs.delete(cb) };
+    }
+    clear() {
+        this.subs.clear();
+    }
+}
+// ---------------------------------------------------------------------------
+// ContextStore
+// ---------------------------------------------------------------------------
+export class ContextStore {
+    // Identity
+    _activeDevice = null;
+    _activeUser = null;
+    _activeSubject = null;
+    // Storage
+    memoryStore = new Map();
+    encryptionKey = null;
+    // Time
+    timeManager;
+    // Metadata
+    log;
+    appName;
+    appVersion;
+    // Reactivity
+    listeners = new Map();
+    subjectsByStorageKey = new Map();
+    // ---------------------------------------------------------------------------
+    // Construction
+    // ---------------------------------------------------------------------------
+    constructor(options) {
+        this.timeManager = new ServerTimeManager(options);
+        this.log = options.onLog;
+        this.appName = options.appName ?? this.detectAppName();
+        this.appVersion = options.appVersion ?? this.detectAppVersion();
+        this._activeDevice = this.initDeviceId();
+    }
+    static create(options) {
+        return new ContextStore(options);
+    }
+    // ---------------------------------------------------------------------------
+    // Properties
+    // ---------------------------------------------------------------------------
+    get activeDevice() {
+        return this._activeDevice;
+    }
+    get activeUser() {
+        return this._activeUser;
+    }
+    set activeUser(value) {
+        this._activeUser = value;
+    }
+    get activeSubject() {
+        return this._activeSubject;
+    }
+    set activeSubject(value) {
+        this._activeSubject = value;
+    }
+    async getServerTime() {
+        return this.timeManager.getServerTime();
+    }
+    // ---------------------------------------------------------------------------
+    // Encryption Key
+    // ---------------------------------------------------------------------------
+    setEncryptionKey(key) {
+        this.encryptionKey = key;
+    }
+    get isEncryptionKeySet() {
+        return this.encryptionKey !== null;
+    }
+    revokeEncryptionKey() {
+        this.encryptionKey = null;
+    }
+    // ---------------------------------------------------------------------------
+    // CRUD
+    // ---------------------------------------------------------------------------
+    setData(boundary, key, value, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const storageKey = this.buildStorageKey(storage, boundary, key);
+        if (!storageKey) {
+            this.log?.('warn', 'Cannot resolve storage key — identity not set', undefined, { boundary, key });
+            return;
+        }
+        // PEM/DER bypass
+        if (this.isPemOrDer(value)) {
+            this.writeRaw(storage, storageKey, typeof value === 'string' ? value : JSON.stringify(value));
+            this.emit(storageKey, value);
+            return;
+        }
+        const now = this.timeManager.getNow();
+        const existing = this.readEnvelope(storage, storageKey);
+        let targetValue = value;
+        if (options?.dataPath && existing) {
+            const obj = structuredClone(existing.data);
+            setNested(obj, options.dataPath, value);
+            targetValue = obj;
+        }
+        const envelope = existing
+            ? this.touchEnvelope(existing, targetValue, now, options?.ttl)
+            : this.makeEnvelope(targetValue, now, options?.ttl);
+        this.writeRaw(storage, storageKey, JSON.stringify(envelope));
+        this.emit(storageKey, envelope.data);
+    }
+    getData(boundary, key, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const storageKey = this.buildStorageKey(storage, boundary, key);
+        if (!storageKey)
+            return undefined;
+        const raw = this.readRaw(storage, storageKey);
+        if (raw === null)
+            return undefined;
+        if (raw.trimStart().startsWith('-----BEGIN')) {
+            return raw;
+        }
+        let envelope;
+        try {
+            envelope = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+        if (!envelope.createdAt)
+            return raw;
+        const now = this.timeManager.getNow();
+        if (envelope.expiry && now >= new Date(envelope.expiry)) {
+            this.deleteRaw(storage, storageKey);
+            this.log?.('debug', 'Lazy cleanup: expired entry removed', undefined, { boundary, key });
+            return undefined;
+        }
+        const data = envelope.data;
+        return options?.dataPath ? getNested(data, options.dataPath) : data;
+    }
+    getDataMetadata(boundary, key, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const storageKey = this.buildStorageKey(storage, boundary, key);
+        if (!storageKey)
+            return undefined;
+        return this.readEnvelope(storage, storageKey) ?? undefined;
+    }
+    deleteData(boundary, key, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const storageKey = this.buildStorageKey(storage, boundary, key);
+        if (!storageKey)
+            return;
+        if (options?.dataPath) {
+            const envelope = this.readEnvelope(storage, storageKey);
+            if (envelope) {
+                const obj = structuredClone(envelope.data);
+                deleteNested(obj, options.dataPath);
+                const updated = this.touchEnvelope(envelope, obj, this.timeManager.getNow());
+                this.writeRaw(storage, storageKey, JSON.stringify(updated));
+                this.emit(storageKey, obj);
+            }
+            return;
+        }
+        this.deleteRaw(storage, storageKey);
+        this.emit(storageKey, undefined);
+    }
+    // ---------------------------------------------------------------------------
+    // Batch
+    // ---------------------------------------------------------------------------
+    batchSet(operations) {
+        for (const op of operations) {
+            this.setData(op.boundary, op.key, op.value, { storage: op.storage, ttl: op.ttl });
+        }
+    }
+    batchGet(operations) {
+        return operations.map((op) => ({
+            boundary: op.boundary,
+            key: op.key,
+            value: this.getData(op.boundary, op.key, { storage: op.storage }),
+        }));
+    }
+    // ---------------------------------------------------------------------------
+    // Observe / Listen
+    // ---------------------------------------------------------------------------
+    observeData(boundary, key, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const storageKey = this.buildStorageKey(storage, boundary, key);
+        const subject = new Subject();
+        if (storageKey) {
+            const list = this.subjectsByStorageKey.get(storageKey) ?? [];
+            list.push(subject);
+            this.subjectsByStorageKey.set(storageKey, list);
+        }
+        return {
+            subscribe: (callback) => {
+                const inner = subject.subscribe((value) => {
+                    callback(options?.dataPath ? getNested(value, options.dataPath) : value);
+                });
+                return {
+                    unsubscribe: () => {
+                        inner.unsubscribe();
+                        if (storageKey) {
+                            const arr = this.subjectsByStorageKey.get(storageKey);
+                            if (arr) {
+                                const idx = arr.indexOf(subject);
+                                if (idx !== -1)
+                                    arr.splice(idx, 1);
+                                if (arr.length === 0)
+                                    this.subjectsByStorageKey.delete(storageKey);
+                            }
+                        }
+                    },
+                };
+            },
+        };
+    }
+    addListener(listenerId, boundary, key, callback, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        this.listeners.set(listenerId, { id: listenerId, boundary, key, storage, dataPath: options?.dataPath, callback });
+    }
+    removeListener(listenerId) {
+        this.listeners.delete(listenerId);
+    }
+    clearAllListeners() {
+        this.listeners.clear();
+        for (const list of this.subjectsByStorageKey.values()) {
+            for (const s of list)
+                s.clear();
+        }
+        this.subjectsByStorageKey.clear();
+    }
+    // ---------------------------------------------------------------------------
+    // Query
+    // ---------------------------------------------------------------------------
+    findKeys(boundary, partialKey, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const prefix = this.buildKeyPrefix(storage, boundary);
+        if (!prefix)
+            return [];
+        const needle = partialKey ? `${prefix}:${partialKey}` : `${prefix}:`;
+        return this.allKeysIn(storage)
+            .filter((k) => k.startsWith(needle))
+            .map((k) => k.slice(prefix.length + 1));
+    }
+    clearData(boundary, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const prefix = this.buildKeyPrefix(storage, boundary);
+        if (!prefix)
+            return;
+        const needle = options?.partialKey ? `${prefix}:${options.partialKey}` : `${prefix}:`;
+        for (const k of this.allKeysIn(storage)) {
+            if (k.startsWith(needle))
+                this.deleteRaw(storage, k);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Export / Import
+    // ---------------------------------------------------------------------------
+    exportData(boundary, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const prefix = this.buildKeyPrefix(storage, boundary);
+        if (!prefix)
+            return {};
+        const needle = options?.partialKey ? `${prefix}:${options.partialKey}` : `${prefix}:`;
+        const result = {};
+        for (const k of this.allKeysIn(storage)) {
+            if (!k.startsWith(needle))
+                continue;
+            const raw = this.readRaw(storage, k);
+            if (raw === null)
+                continue;
+            const userKey = k.slice(prefix.length + 1);
+            try {
+                result[userKey] = JSON.parse(raw);
+            }
+            catch {
+                result[userKey] = raw;
+            }
+        }
+        return result;
+    }
+    importData(boundary, data, options) {
+        const storage = options?.storage ?? Storage.secureStorage;
+        const overwrite = options?.overwrite ?? false;
+        for (const [key, value] of Object.entries(data)) {
+            const storageKey = this.buildStorageKey(storage, boundary, key);
+            if (!storageKey)
+                continue;
+            if (!overwrite && this.readRaw(storage, storageKey) !== null)
+                continue;
+            this.writeRaw(storage, storageKey, JSON.stringify(value));
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Cleanup
+    // ---------------------------------------------------------------------------
+    cleanup(options) {
+        const boundaries = options?.boundary ? [options.boundary] : [Boundary.device, Boundary.user, Boundary.subject];
+        const storages = options?.storage
+            ? [options.storage]
+            : [Storage.secureStorage, Storage.secureStorageEncrypted, Storage.memory, Storage.localStorage];
+        const now = this.timeManager.getNow();
+        let cleaned = 0;
+        for (const storage of storages) {
+            for (const boundary of boundaries) {
+                const prefix = this.buildKeyPrefix(storage, boundary);
+                if (!prefix)
+                    continue;
+                for (const k of this.allKeysIn(storage)) {
+                    if (!k.startsWith(`${prefix}:`))
+                        continue;
+                    const raw = this.readRaw(storage, k);
+                    if (raw === null)
+                        continue;
+                    try {
+                        const env = JSON.parse(raw);
+                        if (env.expiry && now >= new Date(env.expiry)) {
+                            this.deleteRaw(storage, k);
+                            cleaned++;
+                        }
+                    }
+                    catch {
+                        /* not an envelope — skip */
+                    }
+                }
+            }
+        }
+        this.log?.('info', `Cleanup completed: ${cleaned} expired entries removed`);
+    }
+    // ===========================================================================
+    // Private — storage plumbing
+    // ===========================================================================
+    buildStorageKey(storage, boundary, key) {
+        const prefix = this.buildKeyPrefix(storage, boundary);
+        return prefix ? `${prefix}:${key}` : null;
+    }
+    buildKeyPrefix(storage, boundary) {
+        const identity = this.identityScope(boundary);
+        return identity ? `${KEY_PREFIX}:${storage}:${boundary}:${identity}` : null;
+    }
+    identityScope(boundary) {
+        const d = this._activeDevice;
+        if (!d)
+            return null;
+        switch (boundary) {
+            case Boundary.device:
+                return d;
+            case Boundary.user:
+                return this._activeUser ? `${d}:${this._activeUser}` : null;
+            case Boundary.subject:
+                return this._activeUser && this._activeSubject
+                    ? `${d}:${this._activeUser}:${this._activeSubject}`
+                    : null;
+        }
+    }
+    readRaw(storage, key) {
+        this.log?.('debug', `readRaw [${storage}] ${key}`);
+        if (storage === Storage.memory)
+            return this.memoryStore.get(key) ?? null;
+        if (storage === Storage.secureStorageEncrypted) {
+            if (!this.encryptionKey) {
+                this.log?.('warn', 'Encryption key not set — cannot read encrypted storage');
+                return null;
+            }
+            const cipher = globalThis.localStorage.getItem(key);
+            if (!cipher)
+                return null;
+            try {
+                const plain = decrypt(cipher, this.encryptionKey);
+                this.log?.('debug', 'Encrypted read OK');
+                return plain;
+            }
+            catch (err) {
+                this.log?.('error', 'Decryption failed — wrong encryption key', err);
+                return null;
+            }
+        }
+        return globalThis.localStorage.getItem(key);
+    }
+    writeRaw(storage, key, value) {
+        this.log?.('debug', `writeRaw [${storage}] ${key}`);
+        if (storage === Storage.memory) {
+            this.memoryStore.set(key, value);
+            return;
+        }
+        if (storage === Storage.secureStorageEncrypted) {
+            if (!this.encryptionKey) {
+                this.log?.('warn', 'Encryption key not set — cannot write to encrypted storage');
+                return;
+            }
+            try {
+                globalThis.localStorage.setItem(key, encrypt(value, this.encryptionKey));
+            }
+            catch (err) {
+                this.log?.('error', 'Encryption / storage write failed', err);
+            }
+            return;
+        }
+        try {
+            globalThis.localStorage.setItem(key, value);
+        }
+        catch (err) {
+            this.log?.('error', 'Storage write failed', err);
+        }
+    }
+    deleteRaw(storage, key) {
+        if (storage === Storage.memory) {
+            this.memoryStore.delete(key);
+            return;
+        }
+        globalThis.localStorage.removeItem(key);
+    }
+    allKeysIn(storage) {
+        if (storage === Storage.memory)
+            return [...this.memoryStore.keys()];
+        const keys = [];
+        for (let i = 0; i < globalThis.localStorage.length; i++) {
+            const k = globalThis.localStorage.key(i);
+            if (k?.startsWith(KEY_PREFIX))
+                keys.push(k);
+        }
+        return keys;
+    }
+    // ===========================================================================
+    // Private — envelope helpers
+    // ===========================================================================
+    readEnvelope(storage, storageKey) {
+        const raw = this.readRaw(storage, storageKey);
+        if (!raw)
+            return null;
+        try {
+            const obj = JSON.parse(raw);
+            return obj.createdAt ? obj : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    makeEnvelope(data, now, ttl) {
+        const iso = now.toISOString();
+        return {
+            data,
+            expiry: ttl ? new Date(now.getTime() + ttl).toISOString() : null,
+            createdAt: iso,
+            updatedAt: iso,
+            appName: this.appName,
+            appVersion: this.appVersion,
+            sdkVersion: SDK_VERSION,
+        };
+    }
+    touchEnvelope(existing, data, now, ttl) {
+        return {
+            ...existing,
+            data,
+            updatedAt: now.toISOString(),
+            expiry: ttl ? new Date(now.getTime() + ttl).toISOString() : existing.expiry,
+            appName: this.appName,
+            appVersion: this.appVersion,
+            sdkVersion: SDK_VERSION,
+        };
+    }
+    // ===========================================================================
+    // Private — reactivity
+    // ===========================================================================
+    emit(storageKey, value) {
+        for (const l of this.listeners.values()) {
+            const lk = this.buildStorageKey(l.storage, l.boundary, l.key);
+            if (lk !== storageKey)
+                continue;
+            const v = l.dataPath ? getNested(value, l.dataPath) : value;
+            try {
+                l.callback(v);
+            }
+            catch {
+                /* listener errors must not propagate */
+            }
+        }
+        const subs = this.subjectsByStorageKey.get(storageKey);
+        if (subs)
+            for (const s of subs)
+                s.next(value);
+    }
+    // ===========================================================================
+    // Private — platform detection
+    // ===========================================================================
+    isPemOrDer(value) {
+        if (typeof value === 'string')
+            return value.trimStart().startsWith('-----BEGIN');
+        if (value instanceof Uint8Array || value instanceof ArrayBuffer)
+            return true;
+        return false;
+    }
+    initDeviceId() {
+        const SESSION_KEY = 'cs:deviceId';
+        let id = globalThis.sessionStorage?.getItem(SESSION_KEY);
+        if (!id) {
+            id = globalThis.crypto.randomUUID();
+            globalThis.sessionStorage?.setItem(SESSION_KEY, id);
+        }
+        return id;
+    }
+    detectAppName() {
+        try {
+            return globalThis.document?.title || 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    detectAppVersion() {
+        try {
+            const meta = globalThis.document?.querySelector('meta[name="version"]');
+            return meta?.getAttribute('content') ?? '0.0.0';
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+}
+// ===========================================================================
+// Utility — nested property access
+// ===========================================================================
+function getNested(obj, path) {
+    return path.split('.').reduce((o, k) => o?.[k], obj);
+}
+function setNested(obj, path, value) {
+    const parts = path.split('.');
+    const last = parts.pop();
+    const target = parts.reduce((o, k) => {
+        if (o[k] == null)
+            o[k] = {};
+        return o[k];
+    }, obj);
+    target[last] = value;
+}
+function deleteNested(obj, path) {
+    const parts = path.split('.');
+    const last = parts.pop();
+    const target = parts.reduce((o, k) => o?.[k], obj);
+    if (target)
+        delete target[last];
+}

package/dist/crypto.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sync encryption for web runtime.
+ * Production implementations MUST use AES-256-GCM via platform crypto APIs
+ * (Web Crypto SubtleCrypto, CryptoKit, javax.crypto).
+ *
+ * This module uses XOR + key-derived pad as a synchronous placeholder
+ * so that the public API (setData / getData) stays synchronous per spec.
+ *
+ * AUTH_TAG simulates AES-GCM's authentication: a known prefix is encrypted
+ * alongside the plaintext. On decrypt, if the prefix doesn't match,
+ * the key is wrong and an error is thrown.
+ */
+export declare function encrypt(plaintext: string, key: string): string;
+export declare function decrypt(base64: string, key: string): string;

package/dist/crypto.js

@@ -0,0 +1,43 @@
+/**
+ * Sync encryption for web runtime.
+ * Production implementations MUST use AES-256-GCM via platform crypto APIs
+ * (Web Crypto SubtleCrypto, CryptoKit, javax.crypto).
+ *
+ * This module uses XOR + key-derived pad as a synchronous placeholder
+ * so that the public API (setData / getData) stays synchronous per spec.
+ *
+ * AUTH_TAG simulates AES-GCM's authentication: a known prefix is encrypted
+ * alongside the plaintext. On decrypt, if the prefix doesn't match,
+ * the key is wrong and an error is thrown.
+ */
+const AUTH_TAG = 'CS\x00\x01';
+function deriveKeyBytes(key) {
+    const raw = new TextEncoder().encode(key);
+    const pad = new Uint8Array(256);
+    for (let i = 0; i < pad.length; i++) {
+        pad[i] = raw[i % raw.length] ^ ((i * 31 + 17) & 0xff);
+    }
+    return pad;
+}
+function xor(src, pad) {
+    const out = new Uint8Array(src.length);
+    for (let i = 0; i < src.length; i++) {
+        out[i] = src[i] ^ pad[i % pad.length];
+    }
+    return out;
+}
+export function encrypt(plaintext, key) {
+    const pad = deriveKeyBytes(key);
+    const src = new TextEncoder().encode(AUTH_TAG + plaintext);
+    const out = xor(src, pad);
+    return btoa(String.fromCharCode(...out));
+}
+export function decrypt(base64, key) {
+    const pad = deriveKeyBytes(key);
+    const src = Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+    const result = new TextDecoder().decode(xor(src, pad));
+    if (!result.startsWith(AUTH_TAG)) {
+        throw new Error('Decryption failed: invalid encryption key');
+    }
+    return result.slice(AUTH_TAG.length);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { ContextStore } from './context-store';
+export { Boundary, Storage } from './types';
+export type { Envelope, ContextStoreOptions, Observable, Subscription, IContextStore, LogLevel, } from './types';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ContextStore } from './context-store';
+export { Boundary, Storage } from './types';

package/dist/server-time.d.ts

@@ -0,0 +1,18 @@
+import type { ContextStoreOptions } from './types';
+export declare class ServerTimeManager {
+    private cachedTime;
+    private cachedAt;
+    private ttl;
+    private urls;
+    private timeout;
+    private delegate;
+    private log;
+    private fetchPromise;
+    constructor(options: ContextStoreOptions);
+    getServerTime(): Promise<Date>;
+    /** Synchronous best-effort: cached time or device time. Used internally for envelope timestamps. */
+    getNow(): Date;
+    private isCacheExpired;
+    private offsetFromCache;
+    private fetchFromServers;
+}

package/dist/server-time.js

@@ -0,0 +1,61 @@
+export class ServerTimeManager {
+    cachedTime = null;
+    cachedAt = 0;
+    ttl;
+    urls;
+    timeout;
+    delegate;
+    log;
+    fetchPromise = null;
+    constructor(options) {
+        this.ttl = options.serverTimeTtl ?? 30 * 60 * 1000;
+        this.urls = options.timeServerUrls;
+        this.timeout = options.requestServerTimeTimeout ?? 5000;
+        this.delegate = options.onRequestServerTime;
+        this.log = options.onLog;
+    }
+    async getServerTime() {
+        if (this.cachedTime && !this.isCacheExpired()) {
+            return this.offsetFromCache();
+        }
+        try {
+            if (!this.fetchPromise) {
+                this.fetchPromise = this.fetchFromServers();
+            }
+            const time = await this.fetchPromise;
+            this.fetchPromise = null;
+            return time;
+        }
+        catch (err) {
+            this.fetchPromise = null;
+            this.log?.('error', 'Server time fetch failed, falling back to device time', err);
+            return new Date();
+        }
+    }
+    /** Synchronous best-effort: cached time or device time. Used internally for envelope timestamps. */
+    getNow() {
+        if (this.cachedTime && !this.isCacheExpired()) {
+            return this.offsetFromCache();
+        }
+        return new Date();
+    }
+    isCacheExpired() {
+        return performance.now() - this.cachedAt > this.ttl;
+    }
+    offsetFromCache() {
+        const elapsed = performance.now() - this.cachedAt;
+        return new Date(this.cachedTime.getTime() + elapsed);
+    }
+    async fetchFromServers() {
+        const results = await Promise.allSettled(this.urls.map((url) => this.delegate(url, this.timeout)));
+        for (const r of results) {
+            if (r.status === 'fulfilled' && r.value) {
+                this.cachedTime = r.value;
+                this.cachedAt = performance.now();
+                this.log?.('debug', 'Server time synced', undefined, { time: r.value.toISOString() });
+                return r.value;
+            }
+        }
+        throw new Error('All server time requests failed');
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+export declare enum Boundary {
+    device = "device",
+    user = "user",
+    subject = "subject"
+}
+export declare enum Storage {
+    secureStorage = "secureStorage",
+    secureStorageEncrypted = "secureStorageEncrypted",
+    memory = "memory",
+    localStorage = "localStorage"
+}
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type Subscription = {
+    unsubscribe(): void;
+};
+export type Observable<T> = {
+    subscribe(callback: (value: T) => void): Subscription;
+};
+export type Envelope = {
+    data: any;
+    expiry: string | null;
+    createdAt: string;
+    updatedAt: string;
+    appName: string;
+    appVersion: string;
+    sdkVersion: string;
+};
+export type ContextStoreOptions = {
+    onRequestServerTime: (url: string, timeout: number) => Promise<Date | null>;
+    timeServerUrls: string[];
+    serverTimeTtl?: number;
+    requestServerTimeTimeout?: number;
+    onLog?: (level: LogLevel, message: string, error?: any, context?: Record<string, any>) => void;
+    appName?: string;
+    appVersion?: string;
+};
+export interface IContextStore {
+    readonly activeDevice: string | null;
+    activeUser: string | null;
+    activeSubject: string | null;
+    getServerTime(): Promise<Date>;
+    setEncryptionKey(key: string): void;
+    get isEncryptionKeySet(): boolean;
+    revokeEncryptionKey(): void;
+    setData(boundary: Boundary, key: string, value: any, options?: {
+        storage?: Storage;
+        ttl?: number;
+        dataPath?: string;
+    }): void;
+    getData<T = any>(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): T | undefined;
+    getDataMetadata(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+    }): Envelope | undefined;
+    deleteData(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): void;
+    batchSet(operations: Array<{
+        boundary: Boundary;
+        key: string;
+        value: any;
+        storage?: Storage;
+        ttl?: number;
+    }>): void;
+    batchGet(operations: Array<{
+        boundary: Boundary;
+        key: string;
+        storage?: Storage;
+    }>): Array<{
+        boundary: Boundary;
+        key: string;
+        value: any;
+    }>;
+    observeData(boundary: Boundary, key: string, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): Observable<any>;
+    addListener(listenerId: string, boundary: Boundary, key: string, callback: (value: any) => void, options?: {
+        storage?: Storage;
+        dataPath?: string;
+    }): void;
+    removeListener(listenerId: string): void;
+    clearAllListeners(): void;
+    findKeys(boundary: Boundary, partialKey: string, options?: {
+        storage?: Storage;
+    }): string[];
+    clearData(boundary: Boundary, options?: {
+        storage?: Storage;
+        partialKey?: string;
+    }): void;
+    exportData(boundary: Boundary, options?: {
+        storage?: Storage;
+        partialKey?: string;
+    }): Record<string, any>;
+    importData(boundary: Boundary, data: Record<string, any>, options?: {
+        storage?: Storage;
+        overwrite?: boolean;
+    }): void;
+    cleanup(options?: {
+        boundary?: Boundary;
+        storage?: Storage;
+    }): void;
+}

package/dist/types.js

@@ -0,0 +1,13 @@
+export var Boundary;
+(function (Boundary) {
+    Boundary["device"] = "device";
+    Boundary["user"] = "user";
+    Boundary["subject"] = "subject";
+})(Boundary || (Boundary = {}));
+export var Storage;
+(function (Storage) {
+    Storage["secureStorage"] = "secureStorage";
+    Storage["secureStorageEncrypted"] = "secureStorageEncrypted";
+    Storage["memory"] = "memory";
+    Storage["localStorage"] = "localStorage";
+})(Storage || (Storage = {}));

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@burgantech/context-store",
+  "version": "0.1.0",
+  "description": "Centralized state store SDK — boundary-based, encrypted, observable",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/burgan-tech/vnext-client-data-manager.git",
+    "directory": "core/ts-context-store"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "happy-dom": "^20.8.4",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  }
+}