@harborclient/sdk 0.6.16 → 0.6.17

package/dist/runtime-utils.test.js

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, jest } from '@jest/globals';
-import { byteLength, randomId, truncateBody, truncateToBytes } from './runtime-utils.js';
+import { byteLength, createLogger, randomId, truncateBody, truncateToBytes } from './runtime-utils.js';
 const originalTextEncoder = globalThis.TextEncoder;
 const originalCrypto = globalThis.crypto;
 afterEach(() => {
@@ -102,3 +102,76 @@ describe('truncateBody', () => {
         });
     });
 });
+describe('createLogger', () => {
+    it('prefixes messages with [pluginId]', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const logger = createLogger('my-plugin');
+        logger.info('hello');
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'hello');
+        logSpy.mockRestore();
+    });
+    it('filters messages below the active level', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        const logger = createLogger('my-plugin', { level: 'warn' });
+        logger.debug('hidden');
+        logger.info('hidden');
+        logger.warn('visible');
+        expect(logSpy).not.toHaveBeenCalled();
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        expect(warnSpy).toHaveBeenCalledWith('[my-plugin]', 'visible');
+        logSpy.mockRestore();
+        warnSpy.mockRestore();
+    });
+    it('updates the active level via setLevel', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const logger = createLogger('my-plugin');
+        logger.info('before');
+        logger.setLevel('silent');
+        logger.info('after');
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'before');
+        logSpy.mockRestore();
+    });
+    it('suppresses all output at silent level', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const logger = createLogger('my-plugin', { level: 'silent' });
+        logger.debug('a');
+        logger.info('b');
+        logger.warn('c');
+        logger.error('d');
+        expect(logSpy).not.toHaveBeenCalled();
+        expect(errorSpy).not.toHaveBeenCalled();
+        logSpy.mockRestore();
+        errorSpy.mockRestore();
+    });
+    it('routes warn and error through console.warn and console.error when available', () => {
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const logger = createLogger('my-plugin', { level: 'debug' });
+        logger.warn('warned');
+        logger.error('failed');
+        expect(warnSpy).toHaveBeenCalledWith('[my-plugin]', 'warned');
+        expect(errorSpy).toHaveBeenCalledWith('[my-plugin]', 'failed');
+        warnSpy.mockRestore();
+        errorSpy.mockRestore();
+    });
+    it('falls back to console.log when console.warn and console.error are unavailable', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const originalWarn = console.warn;
+        const originalError = console.error;
+        // @ts-expect-error — exercise SES main-runtime fallback
+        console.warn = undefined;
+        // @ts-expect-error — exercise SES main-runtime fallback
+        console.error = undefined;
+        const logger = createLogger('my-plugin', { level: 'debug' });
+        logger.warn('warned');
+        logger.error('failed');
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'warned');
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'failed');
+        console.warn = originalWarn;
+        console.error = originalError;
+        logSpy.mockRestore();
+    });
+});

package/dist/storage/index.d.ts

@@ -1,2 +1,3 @@
 export { createCappedList, mergeById, type CreateCappedListOptions, type MergeByIdOptions } from './cappedList.js';
+export { arrayOf, asRecord, bool, isRecord, num, numArray, oneOf, recordOf, str, strArray } from './validate.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,GAAG,EACH,QAAQ,EACT,MAAM,eAAe,CAAC"}

package/dist/storage/index.js

@@ -1 +1,2 @@
 export { createCappedList, mergeById } from './cappedList.js';
+export { arrayOf, asRecord, bool, isRecord, num, numArray, oneOf, recordOf, str, strArray } from './validate.js';

package/dist/storage/validate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Returns true when a value is a plain object record (not null, not an array).
+ *
+ * @param value - Candidate value from plugin storage.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Narrows an unknown storage value to a string-keyed record, or null when invalid.
+ *
+ * @param value - Raw value from plugin storage.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/**
+ * Returns a string when the value is a string; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a string.
+ */
+export declare function str<F>(value: unknown, fallback: F): string | F;
+/**
+ * Returns a finite number when the value is a number; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a finite number.
+ */
+export declare function num<F>(value: unknown, fallback: F): number | F;
+/**
+ * Returns a boolean when the value is a boolean; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a boolean.
+ */
+export declare function bool<F>(value: unknown, fallback: F): boolean | F;
+/**
+ * Returns the candidate when it is one of the allowed string literals; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param allowed - Permitted string literals.
+ * @param fallback - Value used when the candidate is not in {@link allowed}.
+ */
+export declare function oneOf<T extends string, F>(value: unknown, allowed: readonly T[], fallback: F): T | F;
+/**
+ * Filters an array to finite numbers; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ */
+export declare function numArray(value: unknown): number[];
+/**
+ * Filters an array to non-empty strings; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ */
+export declare function strArray(value: unknown): string[];
+/**
+ * Filters an array through a type guard; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ * @param guard - Predicate that narrows each element.
+ */
+export declare function arrayOf<T>(value: unknown, guard: (entry: unknown) => entry is T): T[];
+/**
+ * Builds a string-keyed record from entries that pass a type guard.
+ *
+ * Non-record inputs (including arrays) return an empty object so callers can treat
+ * malformed storage as "no data" without throwing.
+ *
+ * @param value - Raw value from plugin storage.
+ * @param guard - Predicate that narrows each property value.
+ */
+export declare function recordOf<T>(value: unknown, guard: (entry: unknown) => entry is T): Record<string, T>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/storage/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/storage/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,GAAG,CAAC,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,GAAG,CAAC,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,GAAG,CAAC,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EACvC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,QAAQ,EAAE,CAAC,GACV,CAAC,GAAG,CAAC,CAIP;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAOjD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAKjD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAKrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAYnB"}

package/dist/storage/validate.js

@@ -0,0 +1,111 @@
+/**
+ * Returns true when a value is a plain object record (not null, not an array).
+ *
+ * @param value - Candidate value from plugin storage.
+ */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Narrows an unknown storage value to a string-keyed record, or null when invalid.
+ *
+ * @param value - Raw value from plugin storage.
+ */
+export function asRecord(value) {
+    return isRecord(value) ? value : null;
+}
+/**
+ * Returns a string when the value is a string; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a string.
+ */
+export function str(value, fallback) {
+    return typeof value === 'string' ? value : fallback;
+}
+/**
+ * Returns a finite number when the value is a number; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a finite number.
+ */
+export function num(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+/**
+ * Returns a boolean when the value is a boolean; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a boolean.
+ */
+export function bool(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+/**
+ * Returns the candidate when it is one of the allowed string literals; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param allowed - Permitted string literals.
+ * @param fallback - Value used when the candidate is not in {@link allowed}.
+ */
+export function oneOf(value, allowed, fallback) {
+    return typeof value === 'string' && allowed.includes(value)
+        ? value
+        : fallback;
+}
+/**
+ * Filters an array to finite numbers; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ */
+export function numArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === 'number' && Number.isFinite(entry));
+}
+/**
+ * Filters an array to non-empty strings; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ */
+export function strArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === 'string');
+}
+/**
+ * Filters an array through a type guard; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ * @param guard - Predicate that narrows each element.
+ */
+export function arrayOf(value, guard) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter(guard);
+}
+/**
+ * Builds a string-keyed record from entries that pass a type guard.
+ *
+ * Non-record inputs (including arrays) return an empty object so callers can treat
+ * malformed storage as "no data" without throwing.
+ *
+ * @param value - Raw value from plugin storage.
+ * @param guard - Predicate that narrows each property value.
+ */
+export function recordOf(value, guard) {
+    const record = asRecord(value);
+    if (!record) {
+        return {};
+    }
+    const result = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (guard(entry)) {
+            result[key] = entry;
+        }
+    }
+    return result;
+}

package/dist/storage/validate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validate.test.d.ts.map

package/dist/storage/validate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.test.d.ts","sourceRoot":"","sources":["../../src/storage/validate.test.ts"],"names":[],"mappings":""}

package/dist/storage/validate.test.js

@@ -0,0 +1,78 @@
+import { describe, expect, it } from '@jest/globals';
+import { arrayOf, asRecord, bool, isRecord, num, numArray, oneOf, recordOf, str, strArray } from './validate.js';
+describe('isRecord', () => {
+    it('accepts plain objects and rejects arrays and primitives', () => {
+        expect(isRecord({ a: 1 })).toBe(true);
+        expect(isRecord([])).toBe(false);
+        expect(isRecord(null)).toBe(false);
+        expect(isRecord('x')).toBe(false);
+    });
+});
+describe('asRecord', () => {
+    it('returns the record or null', () => {
+        const value = { key: 'v' };
+        expect(asRecord(value)).toBe(value);
+        expect(asRecord(null)).toBeNull();
+        expect(asRecord([1])).toBeNull();
+    });
+});
+describe('str', () => {
+    it('returns strings and falls back otherwise', () => {
+        expect(str('hello', '')).toBe('hello');
+        expect(str(42, 'fallback')).toBe('fallback');
+        expect(str(undefined, null)).toBeNull();
+    });
+});
+describe('num', () => {
+    it('returns finite numbers and falls back otherwise', () => {
+        expect(num(3, 0)).toBe(3);
+        expect(num(NaN, 0)).toBe(0);
+        expect(num(Infinity, 0)).toBe(0);
+        expect(num('3', null)).toBeNull();
+    });
+});
+describe('bool', () => {
+    it('returns booleans and falls back otherwise', () => {
+        expect(bool(true, false)).toBe(true);
+        expect(bool(false, true)).toBe(false);
+        expect(bool('true', true)).toBe(true);
+    });
+});
+describe('oneOf', () => {
+    it('accepts allowed literals and falls back otherwise', () => {
+        expect(oneOf('delay', ['interval', 'delay'], 'interval')).toBe('delay');
+        expect(oneOf('other', ['interval', 'delay'], 'interval')).toBe('interval');
+        expect(oneOf(1, ['interval', 'delay'], 'interval')).toBe('interval');
+    });
+});
+describe('numArray', () => {
+    it('filters to finite numbers', () => {
+        expect(numArray([1, NaN, 2, 'x', Infinity])).toEqual([1, 2]);
+        expect(numArray(null)).toEqual([]);
+    });
+});
+describe('strArray', () => {
+    it('filters to strings', () => {
+        expect(strArray(['a', 1, 'b'])).toEqual(['a', 'b']);
+        expect(strArray(undefined)).toEqual([]);
+    });
+});
+describe('arrayOf', () => {
+    it('filters through a guard', () => {
+        const isNum = (entry) => typeof entry === 'number' && Number.isFinite(entry);
+        expect(arrayOf([1, 'x', 2], isNum)).toEqual([1, 2]);
+        expect(arrayOf('nope', isNum)).toEqual([]);
+    });
+});
+describe('recordOf', () => {
+    it('keeps entries that pass the guard', () => {
+        const isNum = (entry) => typeof entry === 'number' && Number.isFinite(entry);
+        expect(recordOf({
+            a: 1,
+            b: 'x',
+            c: 2
+        }, isNum)).toEqual({ a: 1, c: 2 });
+        expect(recordOf([], isNum)).toEqual({});
+        expect(recordOf(null, isNum)).toEqual({});
+    });
+});

package/dist/store.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=store.test.d.ts.map

package/dist/store.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.test.d.ts","sourceRoot":"","sources":["../src/store.test.ts"],"names":[],"mappings":""}

package/dist/store.test.js

@@ -0,0 +1,248 @@
+import { afterEach, beforeEach, describe, expect, it, jest } from '@jest/globals';
+import { createExternalStore, createStorageStore, setIntervalDisposable, syncOnWindowFocus } from './runtime/store.js';
+/**
+ * Builds an in-memory storage mock for store tests.
+ *
+ * @param initial - Seed values keyed by storage key.
+ */
+function createMockStorage(initial = {}) {
+    const data = { ...initial };
+    const getMock = jest.fn(async (key) => data[key]);
+    const setMock = jest.fn(async (key, value) => {
+        data[key] = value;
+    });
+    return {
+        data,
+        get: getMock,
+        set: setMock,
+        getMock,
+        setMock
+    };
+}
+describe('createExternalStore', () => {
+    it('notifies subscribers when setState is called', () => {
+        const store = createExternalStore(0);
+        const listener = jest.fn();
+        store.subscribe(listener);
+        store.setState(1);
+        expect(listener).toHaveBeenCalledTimes(1);
+        expect(store.getSnapshot()).toBe(1);
+    });
+});
+describe('createStorageStore', () => {
+    it('starts from parse(undefined)', () => {
+        const storage = createMockStorage();
+        const store = createStorageStore({
+            storage,
+            key: 'items',
+            parse: (raw) => (Array.isArray(raw) ? raw : [])
+        });
+        expect(store.getSnapshot()).toEqual([]);
+    });
+    it('persists and updates the snapshot via set', async () => {
+        const storage = createMockStorage();
+        const store = createStorageStore({
+            storage,
+            key: 'items',
+            parse: (raw) => (Array.isArray(raw) ? raw : [])
+        });
+        const listener = jest.fn();
+        store.subscribe(listener);
+        await store.set(['a']);
+        expect(store.getSnapshot()).toEqual(['a']);
+        expect(storage.setMock).toHaveBeenCalledWith('items', ['a']);
+        expect(listener).toHaveBeenCalledTimes(1);
+    });
+    it('skips set when equals reports no change', async () => {
+        const storage = createMockStorage({ items: ['a'] });
+        const store = createStorageStore({
+            storage,
+            key: 'items',
+            parse: (raw) => (Array.isArray(raw) ? raw : [])
+        });
+        await store.reloadFromStorage();
+        const listener = jest.fn();
+        store.subscribe(listener);
+        await store.set(['a']);
+        expect(listener).not.toHaveBeenCalled();
+        expect(storage.setMock).not.toHaveBeenCalled();
+    });
+    it('reloadFromStorage applies parsed storage values', async () => {
+        const storage = createMockStorage({ count: 3 });
+        const store = createStorageStore({
+            storage,
+            key: 'count',
+            parse: (raw) => (typeof raw === 'number' ? raw : 0)
+        });
+        const listener = jest.fn();
+        store.subscribe(listener);
+        await store.reloadFromStorage();
+        expect(store.getSnapshot()).toBe(3);
+        expect(listener).toHaveBeenCalledTimes(1);
+    });
+    it('reloadFromStorage skips notify when parsed value is unchanged', async () => {
+        const storage = createMockStorage({ count: 2 });
+        const store = createStorageStore({
+            storage,
+            key: 'count',
+            parse: (raw) => (typeof raw === 'number' ? raw : 0)
+        });
+        await store.reloadFromStorage();
+        const listener = jest.fn();
+        store.subscribe(listener);
+        await store.reloadFromStorage();
+        expect(listener).not.toHaveBeenCalled();
+    });
+    it('uses a custom equals function', async () => {
+        const storage = createMockStorage();
+        const store = createStorageStore({
+            storage,
+            key: 'status',
+            parse: (raw) => raw && typeof raw === 'object' && 'running' in raw
+                ? raw
+                : { running: false },
+            equals: (a, b) => a.running === b.running
+        });
+        await store.set({ running: true });
+        const listener = jest.fn();
+        store.subscribe(listener);
+        storage.data.status = { running: true, port: 8080 };
+        await store.reloadFromStorage();
+        expect(listener).not.toHaveBeenCalled();
+        expect(store.getSnapshot()).toEqual({ running: true });
+    });
+    it('keeps the current snapshot when storage is missing and keepCurrentWhenMissing is true', async () => {
+        const storage = createMockStorage();
+        const store = createStorageStore({
+            storage,
+            key: 'status',
+            parse: () => ({ running: false }),
+            keepCurrentWhenMissing: true
+        });
+        await store.set({ running: true });
+        delete storage.data.status;
+        const listener = jest.fn();
+        store.subscribe(listener);
+        await store.reloadFromStorage();
+        expect(listener).not.toHaveBeenCalled();
+        expect(store.getSnapshot()).toEqual({ running: true });
+    });
+});
+describe('setIntervalDisposable', () => {
+    beforeEach(() => {
+        jest.useFakeTimers();
+    });
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+    it('invokes the callback on an interval until disposed', () => {
+        const callback = jest.fn();
+        const disposable = setIntervalDisposable(callback, 100);
+        jest.advanceTimersByTime(250);
+        expect(callback).toHaveBeenCalledTimes(2);
+        disposable.dispose();
+        jest.advanceTimersByTime(200);
+        expect(callback).toHaveBeenCalledTimes(2);
+    });
+});
+describe('syncOnWindowFocus', () => {
+    const focusListeners = new Set();
+    const visibilityListeners = new Set();
+    const originalWindow = globalThis.window;
+    const originalDocument = globalThis.document;
+    beforeEach(() => {
+        jest.useFakeTimers();
+        focusListeners.clear();
+        visibilityListeners.clear();
+        globalThis.window = {
+            addEventListener: (type, listener) => {
+                if (type === 'focus' && typeof listener === 'function') {
+                    focusListeners.add(listener);
+                }
+            },
+            removeEventListener: (type, listener) => {
+                if (type === 'focus' && typeof listener === 'function') {
+                    focusListeners.delete(listener);
+                }
+            },
+            dispatchEvent: (event) => {
+                if (event.type === 'focus') {
+                    for (const listener of focusListeners) {
+                        listener(event);
+                    }
+                }
+                return true;
+            }
+        };
+        globalThis.document = {
+            addEventListener: (type, listener) => {
+                if (type === 'visibilitychange' && typeof listener === 'function') {
+                    visibilityListeners.add(listener);
+                }
+            },
+            removeEventListener: (type, listener) => {
+                if (type === 'visibilitychange' && typeof listener === 'function') {
+                    visibilityListeners.delete(listener);
+                }
+            },
+            dispatchEvent: (event) => {
+                if (event.type === 'visibilitychange') {
+                    for (const listener of visibilityListeners) {
+                        listener(event);
+                    }
+                }
+                return true;
+            }
+        };
+    });
+    afterEach(() => {
+        jest.useRealTimers();
+        globalThis.window = originalWindow;
+        globalThis.document = originalDocument;
+    });
+    it('reloads stores on focus, visibility change, mount, and interval', async () => {
+        const storage = createMockStorage({ count: 1 });
+        const store = createStorageStore({
+            storage,
+            key: 'count',
+            parse: (raw) => (typeof raw === 'number' ? raw : 0)
+        });
+        const reloadSpy = jest.spyOn(store, 'reloadFromStorage');
+        const disposable = syncOnWindowFocus(store, { intervalMs: 500 });
+        expect(reloadSpy).toHaveBeenCalledTimes(1);
+        storage.data.count = 2;
+        window.dispatchEvent(new Event('focus'));
+        expect(reloadSpy).toHaveBeenCalledTimes(2);
+        storage.data.count = 3;
+        document.dispatchEvent(new Event('visibilitychange'));
+        expect(reloadSpy).toHaveBeenCalledTimes(3);
+        storage.data.count = 4;
+        jest.advanceTimersByTime(500);
+        expect(reloadSpy).toHaveBeenCalledTimes(4);
+        disposable.dispose();
+        storage.data.count = 5;
+        window.dispatchEvent(new Event('focus'));
+        jest.advanceTimersByTime(500);
+        expect(reloadSpy).toHaveBeenCalledTimes(4);
+        await store.reloadFromStorage();
+        expect(store.getSnapshot()).toBe(5);
+    });
+    it('reloads multiple stores together', async () => {
+        const storage = createMockStorage();
+        const first = createStorageStore({
+            storage,
+            key: 'first',
+            parse: (raw) => (typeof raw === 'number' ? raw : 0)
+        });
+        const second = createStorageStore({
+            storage,
+            key: 'second',
+            parse: (raw) => (typeof raw === 'number' ? raw : 0)
+        });
+        const reloadFirst = jest.spyOn(first, 'reloadFromStorage');
+        const reloadSecond = jest.spyOn(second, 'reloadFromStorage');
+        syncOnWindowFocus([first, second]).dispose();
+        expect(reloadFirst).toHaveBeenCalledTimes(1);
+        expect(reloadSecond).toHaveBeenCalledTimes(1);
+    });
+});

package/dist/types.d.ts

@@ -358,6 +358,13 @@ export interface RequestTabContext {
      * Empty variable values fall back to each variable's defaultValue (same as Send).
      */
     variables: Record<string, string>;
+    /**
+     * Stable per-request identifier for namespacing persistent plugin state.
+     *
+     * Saved requests use `req:<id>` and remain stable across edits and restarts.
+     * Unsaved tabs fall back to a best-effort `METHOD url` fingerprint.
+     */
+    requestKey: string;
 }
 /**
  * Adds a segmented tab to the request editor (alongside Params, Headers, Body, and so on).
@@ -388,6 +395,13 @@ export interface ResponseTabContext {
      * Last response, or `null` when no response exists yet.
      */
     response: HttpResponse | null;
+    /**
+     * Stable per-request identifier for namespacing persistent plugin state.
+     *
+     * Saved requests use `req:<id>` and remain stable across edits and restarts.
+     * Unsaved tabs fall back to a best-effort `METHOD url` fingerprint.
+     */
+    requestKey: string;
 }
 /**
  * Adds a tab to the response viewer (alongside Body, Headers, Tests).