@freqhole/api-client 0.1.30

package/src/playlistz/schema.ts

@@ -0,0 +1,138 @@
+// zod schemas for the playlistz automerge document model.
+// plain objects + zod only - no automerge imports.
+import * as z from "zod";
+
+// the set of blob types a stored binary can represent
+export const BlobKindSchema = z.union([
+  z.literal("original"),
+  z.literal("thumbnail"),
+  z.literal("waveform"),
+  z.literal("preview"),
+]);
+export type BlobKind = z.infer<typeof BlobKindSchema>;
+
+// a reference to a binary stored in the blob store, keyed by sha256
+export const ImageRefSchema = z.object({
+  blobId: z.string(),
+  isPrimary: z.boolean(),
+  blobType: BlobKindSchema,
+});
+export type ImageRef = z.infer<typeof ImageRefSchema>;
+
+// a named url associated with a playlist or song
+export const EntityUrlSchema = z.object({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  url: z.string(),
+});
+export type EntityUrl = z.infer<typeof EntityUrlSchema>;
+
+// a single song as stored in the playlist doc
+export const SongEntrySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  artist: z.string(),
+  album: z.string(),
+  duration: z.number(),
+  mimeType: z.string(),
+  fileSize: z.number(),
+  sha256: z.string(),
+  blake3: z.string().optional(),
+  images: z.array(ImageRefSchema).default([]),
+  urls: z.array(EntityUrlSchema).default([]),
+  lyrics: z.string().optional(),
+});
+export type SongEntry = z.infer<typeof SongEntrySchema>;
+
+// the top-level automerge document for a playlist.
+// all fields have defaults so schema.parse({}) succeeds for graceful degradation.
+export const PlaylistDocSchema = z.object({
+  version: z.literal(1).default(1),
+  title: z.string().default(""),
+  description: z.string().default(""),
+  createdAt: z.string().default(() => new Date().toISOString()),
+  lastModified: z.string().default(() => new Date().toISOString()),
+  lastModifiedBy: z.string().default(""),
+  images: z.array(ImageRefSchema).default([]),
+  urls: z.array(EntityUrlSchema).default([]),
+  songs: z.record(z.string(), SongEntrySchema).default({}),
+  order: z.array(z.string()).default([]),
+  peers: z
+    .record(
+      z.string(),
+      z.object({
+        nodeId: z.string(),
+        joinedAt: z.string(),
+        lastSeenAt: z.string().optional(),
+      }),
+    )
+    .default({}),
+  acl: z
+    .record(
+      z.string(),
+      z.object({
+        role: z.union([
+          z.literal("owner"),
+          z.literal("editor"),
+          z.literal("viewer"),
+        ]),
+      }),
+    )
+    .optional(),
+  deleted: z.boolean().optional(),
+  // per-playlist sharing mode. unset = private (not shared).
+  sharingMode: z.union([z.literal("public"), z.literal("knock")]).optional(),
+  // display filter settings for the playlist background and cover
+  bgFilterEnabled: z.boolean().optional(),
+  bgFilterBlur: z.number().optional(),
+  bgFilterContrast: z.number().optional(),
+  bgFilterBrightness: z.number().optional(),
+  coverFilterEnabled: z.boolean().optional(),
+  coverFilterBlur: z.number().optional(),
+  // background image layout
+  bgSize: z.string().optional(),     // css background-size, default: "cover"
+  bgPosition: z.string().optional(), // css background-position, default: "top"
+  bgRepeat: z.string().optional(),   // css background-repeat, default: "no-repeat"
+});
+export type PlaylistDoc = z.infer<typeof PlaylistDocSchema>;
+
+// recursively copy an object keeping only string-keyed enumerable props.
+// automerge doc proxies carry symbol keys (_am_objectId, _am_datatype_) that
+// zod records reject, so raw docs are plainified before parsing.
+function plainify(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(plainify);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value)) {
+      out[key] = plainify((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+// parse raw unknown data into a PlaylistDoc.
+// on failure, logs a warning and returns schema defaults (graceful degradation).
+export function parsePlaylistDoc(raw: unknown): PlaylistDoc {
+  try {
+    return PlaylistDocSchema.parse(plainify(raw ?? {}));
+  } catch (err) {
+    console.warn(
+      "[playlistz:schema] parse failed - falling back to defaults. error:",
+      err instanceof z.ZodError ? err.issues : err,
+      "raw keys:",
+      raw && typeof raw === "object" ? Object.keys(raw) : "null",
+    );
+    return PlaylistDocSchema.parse({});
+  }
+}
+
+// create an empty PlaylistDoc, optionally merged with caller-supplied fields.
+export function emptyPlaylistDoc(init?: Partial<PlaylistDoc>): PlaylistDoc {
+  const now = new Date().toISOString();
+  return PlaylistDocSchema.parse({
+    createdAt: now,
+    lastModified: now,
+    ...init,
+  });
+}

package/src/playlistz/shareLink.ts

@@ -0,0 +1,76 @@
+// share token encoding/decoding for playlistz p2p sharing.
+// versioned base64url payload, no padding.
+// format: base64url({ v: 1, n: nodeId, d: docId, t?: titleHint })
+// url fragment: #share/<token>
+import * as z from "zod";
+
+// v1 share payload: node id, doc id, optional title hint, optional mode hint
+const SharePayloadV1Schema = z.object({
+  v: z.literal(1),
+  n: z.string().min(1),
+  d: z.string().min(1),
+  t: z.string().optional(),
+  m: z.enum(["public", "knock"]).optional(), // sharing mode at link-creation time
+});
+export type SharePayloadV1 = z.infer<typeof SharePayloadV1Schema>;
+
+// convert standard base64 to base64url (no padding)
+function toBase64Url(b64: string): string {
+  return b64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+
+// normalize base64url back to standard base64 for decoding
+function fromBase64Url(b64url: string): string {
+  let s = b64url.replace(/-/g, "+").replace(/_/g, "/");
+  // re-add padding
+  while (s.length % 4 !== 0) {
+    s += "=";
+  }
+  return s;
+}
+
+// encode a share payload to a base64url token (no padding)
+export function encodeShareToken(payload: SharePayloadV1): string {
+  const json = JSON.stringify(payload);
+  const b64 = btoa(json);
+  return toBase64Url(b64);
+}
+
+// decode a share token back to a SharePayloadV1.
+// forgiving: strips whitespace, full urls, "#share/" and "share/" prefixes.
+// accepts both base64 and base64url.
+// returns null on anything invalid.
+export function decodeShareToken(input: string): SharePayloadV1 | null {
+  try {
+    let raw = input.trim();
+
+    // strip full url up to and including the #share/ fragment
+    const hashIdx = raw.indexOf("#share/");
+    if (hashIdx !== -1) {
+      raw = raw.slice(hashIdx + 7);
+    } else if (raw.startsWith("share/")) {
+      raw = raw.slice(6);
+    }
+
+    // strip any trailing fragment or query that may have been appended
+    const ampIdx = raw.indexOf("&");
+    if (ampIdx !== -1) raw = raw.slice(0, ampIdx);
+
+    if (!raw) return null;
+
+    const b64 = fromBase64Url(raw);
+    const json = atob(b64);
+    const parsed: unknown = JSON.parse(json);
+
+    const result = SharePayloadV1Schema.safeParse(parsed);
+    if (!result.success) return null;
+    return result.data;
+  } catch {
+    return null;
+  }
+}
+
+// build a url fragment for embedding in window.location.hash
+export function shareFragment(payload: SharePayloadV1): string {
+  return `#share/${encodeShareToken(payload)}`;
+}

package/src/storage/blobs.ts

@@ -0,0 +1,272 @@
+// 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

@@ -0,0 +1,190 @@
+// 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

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