@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/utils/versioned-storage.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Generic Versioned Storage Utility
+ *
+ * Provides a framework-agnostic way to store and retrieve versioned data
+ * with automatic migration support.
+ */
+import { z } from "zod";
+/**
+ * Versioned storage wrapper schema
+ * Used to check if data is in versioned format
+ */
+export declare const VersionedStorageSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    data: z.ZodUnknown;
+}, z.core.$strip>;
+export type VersionedStorage = z.infer<typeof VersionedStorageSchema>;
+/**
+ * Storage adapter interface - allows different storage backends
+ */
+export interface StorageAdapter {
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Version parser function - handles migration from one version to another
+ */
+export type VersionParser<T> = (data: unknown, version: number) => T[];
+/**
+ * Serializer function - converts data to JSON-serializable format
+ */
+export type Serializer<T> = (data: T) => Record<string, unknown>;
+/**
+ * What a listener learns about a write besides the data. `noRepublish` is set
+ * by a writer for a change peers must not hear about: one it folded from a
+ * peer (a bus delta, a Swarm fold), a volatile field nobody else needs, or a
+ * device-local sign-out. Another instance in the same window must not publish
+ * that write to the room (#707). Absent for a write from another window,
+ * whose origin the `storage` event cannot carry.
+ */
+export interface StorageChange {
+    noRepublish: boolean;
+}
+/** Listener for storage change events, from other windows or this one. */
+export type StorageChangeListener<T> = (data: T[], change?: StorageChange) => void;
+/**
+ * Encryption of fields inside the stored records. Sealing is asynchronous and
+ * reading storage is not, so `prime` opens what is stored into memory and
+ * `open` then reads it synchronously. What `prime` could not open, `open`
+ * treats as absent. `seal` is handed what is stored at the time of the write,
+ * so it can keep a stored record this page could not read.
+ */
+export interface RecordSealing {
+    seal(records: Record<string, unknown>[], stored: unknown): Promise<Record<string, unknown>[]>;
+    open(data: unknown): unknown;
+    prime(data: unknown): Promise<void>;
+}
+/**
+ * Options for versioned storage
+ */
+export interface VersionedStorageOptions<T> {
+    /** Storage key */
+    key: string;
+    /** Current version number */
+    currentVersion: number;
+    /** Storage adapter (e.g., localStorage) */
+    storage: StorageAdapter;
+    /** Version parsers - map of version to parser function */
+    parsers: Record<number, VersionParser<T>>;
+    /** Optional serializer for complex types */
+    serializer?: Serializer<T>;
+    /** Logger name for error messages */
+    loggerName?: string;
+    /**
+     * Seals fields of every record on write. With it, writes are asynchronous
+     * and queued per key in this window, a load reads only what `prime` opened,
+     * and listeners hear of a change once it is primed.
+     */
+    sealing?: RecordSealing;
+}
+/**
+ * LocalStorage adapter for browser environments
+ */
+export declare class LocalStorageAdapter implements StorageAdapter {
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * In-memory storage adapter (for testing or non-browser environments)
+ */
+export declare class MemoryStorageAdapter implements StorageAdapter {
+    private storage;
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Generic versioned storage manager
+ */
+export declare class VersionedStorageManager<T> {
+    private options;
+    private listeners;
+    private boundStorageHandler;
+    private boundSameWindowHandler;
+    constructor(options: VersionedStorageOptions<T>);
+    /**
+     * Subscribe to writes to this key that this instance did not make: other
+     * windows' through the browser's `storage` event, and other manager
+     * instances' in THIS window through the `swarm-id-storage-write` event that
+     * `save()` and `clear()` dispatch — the `storage` event never fires in the
+     * window that wrote. This instance's own writes are skipped.
+     *
+     * @param listener - Callback function that receives the updated data
+     * @returns Unsubscribe function to remove the listener
+     */
+    subscribe(listener: StorageChangeListener<T>): () => void;
+    /**
+     * Set up the browser storage event listener
+     * Only listens for changes to this manager's specific key
+     */
+    private setupStorageEventListener;
+    /**
+     * Clean up the storage event listener when no more subscribers
+     */
+    private cleanupStorageEventListener;
+    /**
+     * Broadcast a write to other manager instances in this window.
+     */
+    private notifySameWindow;
+    private reloadAndNotify;
+    /**
+     * Notify all listeners of data changes
+     */
+    private notifyListeners;
+    /**
+     * Load data from storage
+     */
+    load(): T[];
+    /**
+     * Parse versioned data and migrate if needed
+     */
+    private parse;
+    /**
+     * Open the sealed fields of what is stored into memory, so `load` can read
+     * them. A no-op without sealing.
+     */
+    prime(): Promise<void>;
+    /** The records as stored, still sealed, or `undefined` when there are none. */
+    private storedData;
+    /**
+     * Save data to storage. Resolves once written, which with sealing is after
+     * every earlier write to this key in this window. With sealing a write that
+     * fails rejects, so the caller can tell the person. Without it the failure
+     * is only logged.
+     */
+    save(data: T[], options?: {
+        noRepublish?: boolean;
+    }): Promise<void>;
+    /**
+     * Read, change and write back as one step: the change sees what is stored
+     * when its turn comes, after every earlier write to this key in this window.
+     * A change that returns `undefined` writes nothing. Rejects when the write
+     * fails.
+     */
+    update(mutate: (stored: T[]) => T[] | undefined, options?: {
+        noRepublish?: boolean;
+    }): Promise<void>;
+    /**
+     * Clear data from storage
+     */
+    clear(): Promise<void>;
+    private serialize;
+    private seal;
+    private write;
+    /** The returned turn rejects on failure. The queue moves on regardless. */
+    private enqueue;
+}
+/**
+ * Create a versioned storage manager with localStorage
+ */
+export declare function createLocalStorageManager<T>(options: Omit<VersionedStorageOptions<T>, "storage">): VersionedStorageManager<T>;

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@solarpunkltd/swarm-id",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.8.1",
+  "type": "module",
+  "description": "Swarm ID library for authentication and Bee API operations",
+  "main": "dist/swarm-id.esm.js",
+  "module": "dist/swarm-id.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/swarm-id.esm.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.esm.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "swarm",
+    "identity",
+    "authentication",
+    "bee",
+    "web3"
+  ],
+  "author": "Solar Punk, based on Swarm ID by snaha",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Solar-Punk-Ltd/solarpunk-id.git",
+    "directory": "lib"
+  },
+  "homepage": "https://github.com/Solar-Punk-Ltd/solarpunk-id/tree/main/lib#readme",
+  "bugs": {
+    "url": "https://github.com/Solar-Punk-Ltd/solarpunk-id/issues"
+  },
+  "dependencies": {
+    "@ethersphere/bee-js": "^13.0.0",
+    "@ethersphere/core-sdk": "^0.1.1",
+    "@noble/curves": "1.2.0",
+    "@noble/hashes": "1.3.2",
+    "cafe-utility": "34.0.0",
+    "zod": "4.1.13"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "29.0.0",
+    "@rollup/plugin-json": "6.1.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-replace": "6.0.3",
+    "@rollup/plugin-terser": "0.4.4",
+    "@rollup/plugin-typescript": "12.3.0",
+    "@types/node": "24.10.1",
+    "@typescript-eslint/eslint-plugin": "8.69.0",
+    "@typescript-eslint/parser": "8.69.0",
+    "@vitest/ui": "^4.0.16",
+    "esbuild": "^0.28.0",
+    "eslint": "10.9.1",
+    "prettier": "3.7.3",
+    "rollup": "4.53.3",
+    "tslib": "2.8.1",
+    "typescript": "5.8.3",
+    "vitest": "4.0.14",
+    "@swarm-id/signaling": "0.1.0",
+    "@swarm-id/eslint-rules": "0.0.0"
+  },
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "build:watch": "rollup -c -w",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"test/**/*.ts\"",
+    "typecheck": "tsc --noEmit -p tsconfig.check.json",
+    "check:all": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test",
+    "check:pack": "node dev/check-pack.js"
+  }
 }