@freqhole/api-client 0.1.31 → 0.2.1

package/src/automerge/index.ts

@@ -1,14 +0,0 @@
-// automerge transport layer - iroh QUIC network adapter for automerge-repo.
-//
-// re-exports everything needed by consuming packages.
-export {
-  IrohNetworkAdapter,
-  SYNC_ALPN,
-} from "./IrohNetworkAdapter.js";
-
-export type {
-  BiStreamLike,
-  MiddenStreamNode,
-  ConnectionSummary,
-  IrohNetworkAdapterOptions,
-} from "./IrohNetworkAdapter.js";

package/src/storage/blobs.ts

@@ -1,272 +0,0 @@
-// local blob storage for images and media
-// metadata in IndexedDB, actual blob data in OPFS or Cache API
-
-import { openDB, type IDBPDatabase } from "idb";
-
-// module-local logger - no-op by default; wire up via setStorageLogger
-let logger: (scope: string, ...args: unknown[]) => void = () => {};
-
-/**
- * set the logger function used by blob storage operations.
- * call this at app startup to opt into logging.
- */
-export function setStorageLogger(
-  fn: (scope: string, ...args: unknown[]) => void,
-): void {
-  logger = fn;
-}
-
-export const BLOB_DB_NAME = "freqhole_blobs";
-const BLOB_DB_VERSION = 1;
-const STORE_BLOBS = "blobs";
-const CACHE_NAME = "freqhole-blobs";
-
-// global blob URL cache - persists for session, cleared on page reload
-const BLOB_URL_CACHE = new Map<string, string>();
-
-export type BlobStorageType = "opfs" | "cache";
-
-export interface BlobRecord {
-  blob_id: string; // sha256 hash of content (primary key)
-  storage_type: BlobStorageType;
-  storage_path: string; // opfs path or cache key
-  mime_type: string;
-  file_size: number;
-  created_at: number;
-}
-
-let blobDbInstance: IDBPDatabase | null = null;
-
-async function initBlobDB(): Promise<IDBPDatabase> {
-  if (blobDbInstance) return blobDbInstance;
-
-  blobDbInstance = await openDB(BLOB_DB_NAME, BLOB_DB_VERSION, {
-    upgrade(db) {
-      if (!db.objectStoreNames.contains(STORE_BLOBS)) {
-        db.createObjectStore(STORE_BLOBS, { keyPath: "blob_id" });
-      }
-    },
-  });
-
-  return blobDbInstance;
-}
-
-// close database connection (required before deletion)
-export function closeBlobDB(): void {
-  if (blobDbInstance) {
-    blobDbInstance.close();
-    blobDbInstance = null;
-    logger("blobs", "blob database connection closed");
-  }
-}
-
-// check if OPFS is available
-async function isOPFSAvailable(): Promise<boolean> {
-  try {
-    if (!navigator.storage?.getDirectory) return false;
-    await navigator.storage.getDirectory();
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// write blob to OPFS
-async function writeBlobToOPFS(blobId: string, data: Blob): Promise<string> {
-  const root = await navigator.storage.getDirectory();
-  const blobsDir = await root.getDirectoryHandle("blobs", { create: true });
-  const fileHandle = await blobsDir.getFileHandle(blobId, { create: true });
-  const writable = await fileHandle.createWritable();
-  await writable.write(data);
-  await writable.close();
-  return `/blobs/${blobId}`;
-}
-
-// read blob from OPFS
-async function readBlobFromOPFS(storagePath: string): Promise<Blob | null> {
-  try {
-    const root = await navigator.storage.getDirectory();
-    const blobsDir = await root.getDirectoryHandle("blobs");
-    const fileName = storagePath.split("/").pop()!;
-    const fileHandle = await blobsDir.getFileHandle(fileName);
-    const file = await fileHandle.getFile();
-    return file;
-  } catch {
-    return null;
-  }
-}
-
-// write blob to Cache API
-async function writeBlobToCache(
-  blobId: string,
-  data: Blob,
-  mimeType: string,
-): Promise<string> {
-  const cache = await caches.open(CACHE_NAME);
-  // use synthetic HTTP URL - webkitgtk (linux) rejects non-HTTP URLs in Cache API
-  const url = `https://blob.local/${blobId}`;
-  const response = new Response(data, {
-    headers: { "Content-Type": mimeType },
-  });
-  await cache.put(url, response);
-  return url;
-}
-
-// read blob from Cache API
-async function readBlobFromCache(storagePath: string): Promise<Blob | null> {
-  try {
-    const cache = await caches.open(CACHE_NAME);
-    const response = await cache.match(storagePath);
-    if (!response) return null;
-    return await response.blob();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * store a blob in local storage and return its ID (sha256 hash).
- * automatically chooses OPFS or Cache API based on availability.
- */
-export async function storeBlob(
-  data: Blob,
-  mimeType: string,
-): Promise<string> {
-  const db = await initBlobDB();
-
-  // compute sha256 hash of blob data
-  const arrayBuffer = await data.arrayBuffer();
-  const hashBuffer = await crypto.subtle.digest("SHA-256", arrayBuffer);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  const blobId = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
-
-  // check if already exists
-  const existing = await db.get(STORE_BLOBS, blobId);
-  if (existing) {
-    return blobId;
-  }
-
-  // determine storage type and write blob data
-  const useOPFS = await isOPFSAvailable();
-  const storageType: BlobStorageType = useOPFS ? "opfs" : "cache";
-  const storagePath = useOPFS
-    ? await writeBlobToOPFS(blobId, data)
-    : await writeBlobToCache(blobId, data, mimeType);
-
-  // store metadata
-  const record: BlobRecord = {
-    blob_id: blobId,
-    storage_type: storageType,
-    storage_path: storagePath,
-    mime_type: mimeType,
-    file_size: data.size,
-    created_at: Date.now(),
-  };
-
-  await db.put(STORE_BLOBS, record);
-  return blobId;
-}
-
-/**
- * get blob metadata by ID
- */
-export async function getBlobMetadata(
-  blobId: string,
-): Promise<BlobRecord | null> {
-  const db = await initBlobDB();
-  const record = await db.get(STORE_BLOBS, blobId);
-  return record || null;
-}
-
-/**
- * get blob data by ID
- */
-export async function getBlob(blobId: string): Promise<Blob | null> {
-  const metadata = await getBlobMetadata(blobId);
-  if (!metadata) return null;
-
-  if (metadata.storage_type === "opfs") {
-    return await readBlobFromOPFS(metadata.storage_path);
-  } else {
-    return await readBlobFromCache(metadata.storage_path);
-  }
-}
-
-/**
- * get blob object URL by ID, cached to avoid repeated OPFS reads and URL creations.
- * returns an object URL string usable directly in an img src.
- * URLs are cached for the session and revoked on page unload.
- */
-export async function getBlobObjectURL(
-  blobId: string,
-): Promise<string | null> {
-  if (!blobId) return null;
-
-  // check cache first
-  const cachedUrl = BLOB_URL_CACHE.get(blobId);
-  if (cachedUrl) return cachedUrl;
-
-  // fetch blob and create object URL
-  const blob = await getBlob(blobId);
-  if (!blob) return null;
-
-  const objectUrl = URL.createObjectURL(blob);
-  BLOB_URL_CACHE.set(blobId, objectUrl);
-
-  return objectUrl;
-}
-
-/**
- * synchronous blob URL cache lookup (no OPFS read).
- * returns cached object URL if available, null otherwise.
- */
-export function getCachedBlobObjectURL(blobId: string): string | null {
-  if (!blobId) return null;
-  return BLOB_URL_CACHE.get(blobId) ?? null;
-}
-
-/**
- * clear all cached blob URLs and revoke object URLs
- */
-export function clearBlobUrlCache(): void {
-  BLOB_URL_CACHE.forEach((url) => URL.revokeObjectURL(url));
-  BLOB_URL_CACHE.clear();
-}
-
-// revoke object URLs on page unload to avoid memory leaks
-if (typeof window !== "undefined") {
-  window.addEventListener("beforeunload", () => {
-    clearBlobUrlCache();
-  });
-}
-
-/**
- * delete blob by ID from both storage and metadata db
- */
-export async function deleteBlob(blobId: string): Promise<void> {
-  const metadata = await getBlobMetadata(blobId);
-  if (!metadata) return;
-
-  // delete from storage
-  if (metadata.storage_type === "opfs") {
-    try {
-      const root = await navigator.storage.getDirectory();
-      const blobsDir = await root.getDirectoryHandle("blobs");
-      const fileName = metadata.storage_path.split("/").pop()!;
-      await blobsDir.removeEntry(fileName);
-    } catch {
-      // ignore errors during cleanup
-    }
-  } else {
-    try {
-      const cache = await caches.open(CACHE_NAME);
-      await cache.delete(metadata.storage_path);
-    } catch {
-      // ignore errors during cleanup
-    }
-  }
-
-  // delete metadata
-  const db = await initBlobDB();
-  await db.delete(STORE_BLOBS, blobId);
-}

package/src/storage/identity.ts

@@ -1,190 +0,0 @@
-// p2p identity resolution with read-only access to spume's freqhole_app IndexedDB.
-//
-// policy:
-//   - never create or upgrade the "freqhole_app" database
-//   - if freqhole_app exists and has an "app_state" store, use it as the primary store
-//   - otherwise, use the injected IdentityStore (local, per-app)
-//   - when both have an identity, prefer spume's db
-
-const FREQHOLE_APP_DB = "freqhole_app";
-const APP_STATE_STORE = "app_state";
-const IDENTITY_KEY = "p2p_identity";
-
-// snake_case fields are a wire/storage compatibility contract with spume
-export interface P2PIdentity {
-  id: "p2p_identity";
-  secret_key: Uint8Array;
-  node_id: string;
-  created_at: number;
-}
-
-/** per-app fallback store - apps supply their own settings persistence */
-export interface IdentityStore {
-  get(): Promise<P2PIdentity | null>;
-  set(identity: P2PIdentity): Promise<void>;
-}
-
-/**
- * check whether freqhole_app exists without creating it.
- *
- * strategy:
- *   1. use indexedDB.databases() when available (Chrome/Firefox 126+)
- *   2. fall back to a versionless open; abort the versionchange transaction
- *      if upgrade fires (meaning the db did not exist), then close and delete.
- */
-async function freqholeAppExists(): Promise<boolean> {
-  // prefer the non-destructive databases() API
-  if (typeof indexedDB.databases === "function") {
-    try {
-      const dbs = await indexedDB.databases();
-      return dbs.some((d) => d.name === FREQHOLE_APP_DB);
-    } catch {
-      // fall through to open-based detection
-    }
-  }
-
-  // open-based detection: if upgradeneeded fires, the db did not exist -
-  // abort immediately so IDB never persists it
-  return new Promise<boolean>((resolve) => {
-    const req = indexedDB.open(FREQHOLE_APP_DB);
-    let existed = true;
-
-    req.onupgradeneeded = (event) => {
-      // upgradeneeded on a version-0 open means the db is being created now
-      existed = false;
-      // abort the versionchange transaction to prevent creation
-      (event.target as IDBOpenDBRequest).transaction?.abort();
-    };
-
-    req.onsuccess = () => {
-      req.result.close();
-      if (!existed) {
-        // clean up the empty database that was created before we could abort
-        indexedDB.deleteDatabase(FREQHOLE_APP_DB);
-      }
-      resolve(existed);
-    };
-
-    req.onerror = () => {
-      // the abort above causes an error - if existed is false this is expected
-      resolve(existed);
-    };
-  });
-}
-
-/**
- * check whether freqhole_app has the app_state object store.
- * caller must have already confirmed the db exists.
- */
-async function hasAppStateStore(): Promise<boolean> {
-  return new Promise<boolean>((resolve) => {
-    const req = indexedDB.open(FREQHOLE_APP_DB);
-
-    req.onupgradeneeded = () => {
-      // should not fire here since we know the db exists - if it does, abort
-      req.transaction?.abort();
-      resolve(false);
-    };
-
-    req.onsuccess = () => {
-      const db = req.result;
-      const has = db.objectStoreNames.contains(APP_STATE_STORE);
-      db.close();
-      resolve(has);
-    };
-
-    req.onerror = () => resolve(false);
-  });
-}
-
-/** read p2p_identity from spume's app_state store */
-function readFromFreqholeApp(): Promise<P2PIdentity | null> {
-  return new Promise<P2PIdentity | null>((resolve) => {
-    const req = indexedDB.open(FREQHOLE_APP_DB);
-
-    req.onupgradeneeded = () => {
-      req.transaction?.abort();
-      resolve(null);
-    };
-
-    req.onsuccess = () => {
-      const db = req.result;
-      const tx = db.transaction(APP_STATE_STORE, "readonly");
-      const getReq = tx.objectStore(APP_STATE_STORE).get(IDENTITY_KEY);
-
-      getReq.onsuccess = () => {
-        db.close();
-        resolve((getReq.result as P2PIdentity) ?? null);
-      };
-      getReq.onerror = () => {
-        db.close();
-        resolve(null);
-      };
-    };
-
-    req.onerror = () => resolve(null);
-  });
-}
-
-/** write p2p_identity to spume's app_state store (no version bump) */
-function writeToFreqholeApp(identity: P2PIdentity): Promise<void> {
-  return new Promise<void>((resolve, reject) => {
-    const req = indexedDB.open(FREQHOLE_APP_DB);
-
-    req.onupgradeneeded = () => {
-      req.transaction?.abort();
-      reject(new Error("freqhole_app unexpectedly absent during write"));
-    };
-
-    req.onsuccess = () => {
-      const db = req.result;
-      const tx = db.transaction(APP_STATE_STORE, "readwrite");
-      const putReq = tx.objectStore(APP_STATE_STORE).put(identity, IDENTITY_KEY);
-
-      putReq.onsuccess = () => {
-        db.close();
-        resolve();
-      };
-      putReq.onerror = () => {
-        db.close();
-        reject(putReq.error);
-      };
-    };
-
-    req.onerror = () => reject(req.error);
-  });
-}
-
-/**
- * resolve the p2p identity for this origin.
- * prefers spume's db when both sources have an identity.
- */
-export async function resolveIdentity(
-  local: IdentityStore,
-): Promise<P2PIdentity | null> {
-  const exists = await freqholeAppExists();
-  if (exists && (await hasAppStateStore())) {
-    const spumeIdentity = await readFromFreqholeApp();
-    if (spumeIdentity) return spumeIdentity;
-    // spume db exists but has no identity - fall through to local
-  }
-
-  return local.get();
-}
-
-/**
- * persist a p2p identity.
- * writes to spume's db if it exists and has app_state; otherwise uses local.
- */
-export async function persistIdentity(
-  identity: P2PIdentity,
-  local: IdentityStore,
-): Promise<void> {
-  const exists = await freqholeAppExists();
-  if (exists && (await hasAppStateStore())) {
-    await writeToFreqholeApp(identity);
-    return;
-  }
-
-  await local.set(identity);
-}

package/src/storage/index.ts

@@ -1,5 +0,0 @@
-// shared browser storage layer - re-exports all storage submodules
-
-export * from "./blobs.js";
-export * from "./identity.js";
-export * from "./webLocks.js";

package/src/storage/webLocks.ts

@@ -1,92 +0,0 @@
-// web locks leader election for the iroh node.
-// only one tab per origin runs the midden node at a time.
-
-/** lock name used for iroh node leader election */
-export const LOCK_NAME = "freqhole-iroh-node";
-
-export interface AcquireNodeLeadershipOpts {
-  /** called when this tab becomes the node leader */
-  onAcquired: () => void | Promise<void>;
-  /** called with state transitions; optional */
-  onStateChange?: (state: "leader" | "waiting" | "unsupported") => void;
-}
-
-/**
- * attempt to acquire exclusive leadership of the iroh node.
- *
- * behavior:
- *   - tries ifAvailable first; if the lock is free, holds it and calls onAcquired
- *   - if already held, reports "waiting" and queues a normal request with an AbortController
- *     so leadership transfers when the current leader tab closes
- *   - if navigator.locks is absent (e.g. non-secure context), reports "unsupported"
- *     and calls onAcquired immediately (single-tab fallback)
- *
- * returns a cancel/release function; call it to give up leadership or cancel the wait.
- */
-export function acquireNodeLeadership(
-  opts: AcquireNodeLeadershipOpts,
-): () => void {
-  const { onAcquired, onStateChange } = opts;
-
-  // single-tab fallback for environments without Web Locks
-  if (
-    typeof navigator === "undefined" ||
-    !navigator.locks
-  ) {
-    onStateChange?.("unsupported");
-    void Promise.resolve().then(() => onAcquired());
-    return () => {};
-  }
-
-  let released = false;
-  // resolving this promise releases the held lock
-  let releaseLock: (() => void) | null = null;
-  // used to cancel the waiting queue request
-  const waitAbort = new AbortController();
-
-  function cancel() {
-    released = true;
-    waitAbort.abort();
-    releaseLock?.();
-  }
-
-  // try to grab the lock immediately without queuing
-  navigator.locks.request(
-    LOCK_NAME,
-    { ifAvailable: true },
-    async (lock: Lock | null) => {
-      if (released) return;
-
-      if (lock !== null) {
-        // we are now the leader - call onAcquired, then hold the lock until released
-        onStateChange?.("leader");
-        await onAcquired();
-        await new Promise<void>((resolve) => {
-          releaseLock = resolve;
-        });
-      } else {
-        // another tab holds the lock - queue up for leadership
-        onStateChange?.("waiting");
-
-        try {
-          await navigator.locks.request(
-            LOCK_NAME,
-            { signal: waitAbort.signal },
-            async () => {
-              if (released) return;
-              onStateChange?.("leader");
-              await onAcquired();
-              await new Promise<void>((resolve) => {
-                releaseLock = resolve;
-              });
-            },
-          );
-        } catch {
-          // aborted by cancel() or context destroyed - not an error
-        }
-      }
-    },
-  );
-
-  return cancel;
-}