@freqhole/api-client 0.1.30

package/src/playlistz/convert.ts

@@ -0,0 +1,267 @@
+// converters between external record shapes and PlaylistDoc.
+// all converters are total: missing optional source fields become schema defaults.
+// never throw on extra fields.
+import type { Playlist as FreqholePlaylist, Song as FreqholeSong } from "../codegen/schema.js";
+import {
+  emptyPlaylistDoc,
+  type ImageRef,
+  type PlaylistDoc,
+  type SongEntry,
+  type EntityUrl,
+} from "./schema.js";
+
+// ---- shared helpers ----
+
+function tsToIso(ts: number): string {
+  return new Date(ts).toISOString();
+}
+
+function mapEntityUrls(
+  urls?: Array<{ id?: string | null; name?: string | null; url: string }> | null,
+): EntityUrl[] {
+  if (!urls) return [];
+  return urls.map((u) => ({
+    url: u.url,
+    ...(u.id != null ? { id: u.id } : {}),
+    ...(u.name != null ? { name: u.name } : {}),
+  }));
+}
+
+// ---- legacy playlistz types ----
+// (removed: playlistz has no deployed users, so there is no legacy idb data
+// to convert - new playlists are created directly as docs)
+
+// ---- spume idb types (inline - do not import from spume source) ----
+// field shapes from tomb/client/spume/src/music/services/storage/types.ts
+
+interface SpumeImageMetadata {
+  local_blob_id?: string;
+  remote_blob_id?: string;
+  is_primary: boolean;
+  blob_type: "thumbnail" | "waveform" | "original" | "preview";
+}
+
+interface SpumePlaylist {
+  playlist_id: string;
+  title: string;
+  description?: string | null;
+  is_public?: boolean;
+  images?: SpumeImageMetadata[];
+  urls?: Array<{ id?: string; name?: string; url: string }>;
+  created_at?: number;
+  updated_at?: number;
+}
+
+interface SpumeSong {
+  id: string;
+  sha256: string;
+  title: string;
+  artist_name?: string;
+  album_title?: string;
+  duration_seconds?: number;
+  mime_type?: string | null;
+  file_size?: number | null;
+  blake3?: string | null;
+  lyrics?: string | null;
+  images?: SpumeImageMetadata[];
+  urls?: Array<{ id?: string; name?: string; url: string }>;
+}
+
+// map SpumeImageMetadata -> ImageRef, skipping entries with no blob id
+function mapSpumeImages(images?: SpumeImageMetadata[]): ImageRef[] {
+  if (!images) return [];
+  const result: ImageRef[] = [];
+  for (const img of images) {
+    const blobId = img.local_blob_id ?? img.remote_blob_id;
+    if (!blobId) continue;
+    result.push({
+      blobId,
+      isPrimary: img.is_primary,
+      blobType: img.blob_type,
+    });
+  }
+  return result;
+}
+
+// map freqhole wire image (is_primary as 0/1 number) -> ImageRef
+function mapFreqholeImages(
+  images?: Array<{
+    blob_id: string;
+    is_primary: number;
+    blob_type: "original" | "thumbnail" | "waveform" | "preview";
+  }> | null,
+): ImageRef[] {
+  if (!images) return [];
+  return images.map((img) => ({
+    blobId: img.blob_id,
+    isPrimary: img.is_primary !== 0,
+    blobType: img.blob_type,
+  }));
+}
+
+// ---- converters ----
+
+// convert a freqhole wire Playlist + Song[] to a PlaylistDoc.
+// maps snake_case fields and is_primary number (0/1) -> boolean.
+// note: the freqhole Song wire type does not carry album_title; that field defaults to "".
+// media_blob_id is used as sha256 (it is the server's short blob id, not a true content hash).
+export function freqholePlaylistToDoc(
+  playlist: FreqholePlaylist,
+  songs: FreqholeSong[],
+): PlaylistDoc {
+  const createdAt = tsToIso(playlist.created_at);
+  const lastModified = tsToIso(playlist.updated_at);
+
+  const songEntries: Record<string, SongEntry> = {};
+  const order: string[] = [];
+
+  for (const song of songs) {
+    const entry: SongEntry = {
+      id: song.id,
+      title: song.title ?? "",
+      artist: song.track_artist ?? "",
+      album: "",
+      duration: song.duration ?? 0,
+      mimeType: "",
+      fileSize: 0,
+      sha256: song.media_blob_id,
+      images: mapFreqholeImages(song.images),
+      urls: mapEntityUrls(song.urls),
+      ...(song.lyrics != null ? { lyrics: song.lyrics } : {}),
+    };
+    songEntries[song.id] = entry;
+    order.push(song.id);
+  }
+
+  return emptyPlaylistDoc({
+    title: playlist.title ?? "",
+    description: playlist.description ?? "",
+    createdAt,
+    lastModified,
+    images: mapFreqholeImages(playlist.images),
+    urls: mapEntityUrls(playlist.urls),
+    songs: songEntries,
+    order,
+  });
+}
+
+// convert a spume idb Playlist + Song[] to a PlaylistDoc.
+// maps spume's ImageMetadata (local_blob_id/remote_blob_id) to ImageRef.
+// spume Song fields: sha256, artist_name, album_title, duration_seconds, mime_type, file_size, blake3.
+export function spumePlaylistToDoc(
+  playlist: SpumePlaylist,
+  songs: SpumeSong[],
+): PlaylistDoc {
+  const now = new Date().toISOString();
+  const createdAt = playlist.created_at ? tsToIso(playlist.created_at) : now;
+  const lastModified = playlist.updated_at ? tsToIso(playlist.updated_at) : now;
+
+  const songEntries: Record<string, SongEntry> = {};
+  const order: string[] = [];
+
+  for (const song of songs) {
+    const entry: SongEntry = {
+      id: song.id,
+      title: song.title ?? "",
+      artist: song.artist_name ?? "",
+      album: song.album_title ?? "",
+      duration: song.duration_seconds ?? 0,
+      mimeType: song.mime_type ?? "",
+      fileSize: song.file_size ?? 0,
+      sha256: song.sha256,
+      images: mapSpumeImages(song.images),
+      urls: mapEntityUrls(song.urls),
+      ...(song.blake3 != null ? { blake3: song.blake3 } : {}),
+      ...(song.lyrics != null ? { lyrics: song.lyrics } : {}),
+    };
+    songEntries[song.id] = entry;
+    order.push(song.id);
+  }
+
+  return emptyPlaylistDoc({
+    title: playlist.title ?? "",
+    description: playlist.description ?? "",
+    createdAt,
+    lastModified,
+    images: mapSpumeImages(playlist.images),
+    urls: mapEntityUrls(playlist.urls),
+    songs: songEntries,
+    order,
+  });
+}
+
+// convert a PlaylistDoc back to the freqhole wire format where lossless.
+// id is not stored in the doc - defaults to "". caller must supply the real
+// playlist id if needed (e.g. from the docIndex entry).
+// note: album_title, mime_type, file_size are not in the freqhole Song wire type
+// and are dropped. sha256 is mapped back to media_blob_id.
+export function docToFreqholePlaylist(
+  doc: PlaylistDoc,
+): { playlist: FreqholePlaylist; songs: FreqholeSong[] } {
+  const createdAt = doc.createdAt ? new Date(doc.createdAt).getTime() : 0;
+  const updatedAt = doc.lastModified ? new Date(doc.lastModified).getTime() : 0;
+
+  const playlist: FreqholePlaylist = {
+    id: "",
+    title: doc.title,
+    description: doc.description || null,
+    is_public: 0,
+    images: doc.images.map((img) => ({
+      blob_id: img.blobId,
+      is_primary: img.isPrimary ? 1 : 0,
+      blob_type: img.blobType,
+    })),
+    urls: doc.urls.map((u) => ({
+      url: u.url,
+      id: u.id ?? null,
+      name: u.name ?? null,
+    })),
+    created_by_id: null,
+    created_at: createdAt,
+    updated_at: updatedAt,
+    deleted_at: null,
+    deleted_by: null,
+    created_by: null,
+    updated_by: null,
+    song_count: doc.order.length,
+  };
+
+  const songs: FreqholeSong[] = doc.order
+    .map((id) => doc.songs[id])
+    .filter((s): s is SongEntry => s != null)
+    .map((s) => {
+      return {
+        id: s.id,
+        media_blob_id: s.sha256,
+        title: s.title,
+        track_number: 1,
+        disc_number: 1,
+        duration: s.duration,
+        track_artist: s.artist || null,
+        images: s.images.map((img) => ({
+          blob_id: img.blobId,
+          is_primary: img.isPrimary ? 1 : 0,
+          blob_type: img.blobType,
+        })),
+        urls: s.urls.map((u) => ({
+          url: u.url,
+          id: u.id ?? null,
+          name: u.name ?? null,
+        })),
+        metadata: null,
+        lyrics: s.lyrics ?? null,
+        created_at: createdAt,
+        updated_at: updatedAt,
+        deleted_at: null,
+        deleted_by: null,
+        created_by: null,
+        updated_by: null,
+        created_by_username: null,
+        updated_by_username: null,
+        bpm: null,
+        play_count: null,
+      };
+    });
+
+  return { playlist, songs };
+}

package/src/playlistz/index.ts

@@ -0,0 +1,6 @@
+// public exports for the playlistz domain package
+export * from "./schema.js";
+export * from "./mutations.js";
+export * from "./convert.js";
+export * from "./shareLink.js";
+export * from "./protocol.js";

package/src/playlistz/mutations.ts

@@ -0,0 +1,181 @@
+// pure mutation helpers for PlaylistDoc.
+// each function mutates the doc draft in place - safe to call inside handle.change().
+// no automerge imports: these are plain object mutations over plain objects.
+import type { PlaylistDoc, SongEntry, ImageRef } from "./schema.js";
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+// bump lastModified to now, optionally setting lastModifiedBy
+function bumpModified(doc: PlaylistDoc, by?: string): void {
+  doc.lastModified = nowIso();
+  if (by !== undefined) {
+    doc.lastModifiedBy = by;
+  }
+}
+
+// insert or replace a song in the doc, appending its id to order if not already present
+export function upsertSong(doc: PlaylistDoc, song: SongEntry, by?: string): void {
+  doc.songs[song.id] = song;
+  if (!doc.order.includes(song.id)) {
+    doc.order.push(song.id);
+  }
+  bumpModified(doc, by);
+}
+
+// remove a song from songs and order
+export function removeSong(doc: PlaylistDoc, songId: string, by?: string): void {
+  delete doc.songs[songId];
+  const idx = doc.order.indexOf(songId);
+  if (idx !== -1) {
+    doc.order.splice(idx, 1);
+  }
+  bumpModified(doc, by);
+}
+
+// move a single song to a target index within order.
+// single-item splice keeps automerge merge semantics sane.
+export function reorderSongs(
+  doc: PlaylistDoc,
+  songId: string,
+  toIndex: number,
+  by?: string,
+): void {
+  const fromIdx = doc.order.indexOf(songId);
+  if (fromIdx === -1) return;
+  doc.order.splice(fromIdx, 1);
+  const clamped = Math.max(0, Math.min(toIndex, doc.order.length));
+  doc.order.splice(clamped, 0, songId);
+  bumpModified(doc, by);
+}
+
+// playlist metadata fields settable via setMetadata
+type MetadataFields = Partial<
+  Pick<
+    PlaylistDoc,
+    | "title"
+    | "description"
+    | "bgFilterEnabled"
+    | "bgFilterBlur"
+    | "bgFilterContrast"
+    | "bgFilterBrightness"
+    | "coverFilterEnabled"
+    | "coverFilterBlur"
+    | "bgSize"
+    | "bgPosition"
+    | "bgRepeat"
+  >
+>;
+
+// update playlist-level metadata fields
+export function setMetadata(
+  doc: PlaylistDoc,
+  fields: MetadataFields,
+  by?: string,
+): void {
+  if (fields.title !== undefined) doc.title = fields.title;
+  if (fields.description !== undefined) doc.description = fields.description;
+  for (const key of [
+    "bgFilterEnabled",
+    "bgFilterBlur",
+    "bgFilterContrast",
+    "bgFilterBrightness",
+    "coverFilterEnabled",
+    "coverFilterBlur",
+    "bgSize",
+    "bgPosition",
+    "bgRepeat",
+  ] as const) {
+    if (fields[key] !== undefined) {
+      // assignment is type-safe per key; typescript can't narrow the loop var
+      (doc as Record<string, unknown>)[key] = fields[key];
+    }
+  }
+  bumpModified(doc, by);
+}
+
+// add an image ref to the playlist or to a specific song.
+// if ref.isPrimary is true, clears isPrimary on all sibling images first.
+export function addImage(
+  doc: PlaylistDoc,
+  ref: ImageRef,
+  target?: { songId?: string },
+  by?: string,
+): void {
+  const images =
+    target?.songId != null
+      ? doc.songs[target.songId]?.images
+      : doc.images;
+
+  if (!images) return;
+
+  if (ref.isPrimary) {
+    for (const img of images) {
+      img.isPrimary = false;
+    }
+  }
+  images.push(ref);
+  bumpModified(doc, by);
+}
+
+// set the primary image by blobId, clearing isPrimary on all others.
+// operates on playlist images or a specific song's images.
+export function setPrimaryImage(
+  doc: PlaylistDoc,
+  blobId: string,
+  target?: { songId?: string },
+  by?: string,
+): void {
+  const images =
+    target?.songId != null
+      ? doc.songs[target.songId]?.images
+      : doc.images;
+
+  if (!images) return;
+
+  for (const img of images) {
+    img.isPrimary = img.blobId === blobId;
+  }
+  bumpModified(doc, by);
+}
+
+// record a peer joining this doc. idempotent - no-op if peer is already present.
+// does not bump lastModified (peer bookkeeping is not a content edit).
+export function addPeer(doc: PlaylistDoc, nodeId: string): void {
+  if (doc.peers[nodeId]) return;
+  doc.peers[nodeId] = {
+    nodeId,
+    joinedAt: nowIso(),
+  };
+}
+
+// update lastSeenAt for an existing peer entry.
+// does not bump lastModified (ephemeral presence, not a content edit).
+export function stampLastSeen(doc: PlaylistDoc, nodeId: string): void {
+  const peer = doc.peers[nodeId];
+  if (peer) {
+    peer.lastSeenAt = nowIso();
+  }
+}
+
+// set or update the access role for a node in the acl
+export function setAclRole(
+  doc: PlaylistDoc,
+  nodeId: string,
+  role: "owner" | "editor" | "viewer",
+  by?: string,
+): void {
+  if (!doc.acl) {
+    doc.acl = {};
+  }
+  doc.acl[nodeId] = { role };
+  bumpModified(doc, by);
+}
+
+// mark this playlist as deleted (tombstone).
+// the doc remains in the repo; consumers check deleted before rendering.
+export function tombstone(doc: PlaylistDoc, by?: string): void {
+  doc.deleted = true;
+  bumpModified(doc, by);
+}

package/src/playlistz/protocol.ts

@@ -0,0 +1,222 @@
+// freqhole-playlistz/1 discovery and knock protocol.
+// zod-validated message envelopes + BiStream encode/decode helpers.
+// no midden or automerge imports.
+import * as z from "zod";
+
+// ALPN strings used when registering iroh endpoints
+export const PLAYLISTZ_ALPN = "freqhole-playlistz/1";
+export const AUTOMERGE_ALPN = "iroh/automerge-repo/1";
+
+// ---- message schemas ----
+
+const HelloSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("hello"),
+  nodeId: z.string(),
+  name: z.string().optional(),
+  avatarBlobId: z.string().optional(),
+});
+
+const HelloOkSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("hello_ok"),
+  nodeId: z.string(),
+  name: z.string().optional(),
+  avatarDataUrl: z.string().optional(),
+  public: z.boolean(),
+});
+
+const ListPlaylistsSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("list_playlists"),
+});
+
+const PlaylistItemSchema = z.object({
+  docId: z.string(),
+  title: z.string(),
+  songCount: z.number(),
+});
+
+const PlaylistsSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("playlists"),
+  items: z.array(PlaylistItemSchema),
+});
+
+const KnockSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("knock"),
+  nodeId: z.string(),
+  name: z.string().optional(),
+  message: z.string().optional(),
+  knockType: z.enum(["browse", "doc_access"]).optional(), // default: "browse"
+  docId: z.string().optional(), // present when knockType is "doc_access"
+});
+
+const KnockStatusSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("knock_status"),
+  status: z.union([
+    z.literal("pending"),
+    z.literal("accepted"),
+    z.literal("denied"),
+  ]),
+  grantedDocIds: z.array(z.string()).optional(),
+});
+
+// ask a peer to make a blob available for iroh-blobs verified download.
+// sha256 is the blob store key carried in playlist docs.
+const BlobRequestSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("blob_request"),
+  sha256: z.string(),
+});
+
+// reply: the peer imported the blob into its iroh-blobs store.
+// blake3 + size are what download_verified_streaming needs.
+const BlobReadySchema = z.object({
+  v: z.literal(1),
+  type: z.literal("blob_ready"),
+  sha256: z.string(),
+  blake3: z.string(),
+  size: z.number(),
+});
+
+const ErrorSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("error"),
+  code: z.string(),
+  message: z.string(),
+});
+
+// proactive acceptance notification: owner opens a stream to the peer and
+// sends this after accepting their knock, so the peer doesn't have to poll.
+const KnockNotifySchema = z.object({
+  v: z.literal(1),
+  type: z.literal("knock_notify"),
+  status: z.literal("accepted"),
+  docIds: z.array(z.string()),
+  ownerNodeId: z.string(),
+});
+
+// proactive identity update: a peer broadcasts their current name/avatar
+// to all peers they have established connections with.
+const IdentityUpdateSchema = z.object({
+  v: z.literal(1),
+  type: z.literal("identity_update"),
+  name: z.string().optional(),
+  avatarDataUrl: z.string().optional(),
+});
+
+// discriminated union of all protocol messages
+export const MessageSchema = z.discriminatedUnion("type", [
+  HelloSchema,
+  HelloOkSchema,
+  ListPlaylistsSchema,
+  PlaylistsSchema,
+  KnockSchema,
+  KnockStatusSchema,
+  BlobRequestSchema,
+  BlobReadySchema,
+  ErrorSchema,
+  KnockNotifySchema,
+  IdentityUpdateSchema,
+]);
+export type Message = z.infer<typeof MessageSchema>;
+
+// convenience inferred types per message kind
+export type HelloMessage = z.infer<typeof HelloSchema>;
+export type HelloOkMessage = z.infer<typeof HelloOkSchema>;
+export type ListPlaylistsMessage = z.infer<typeof ListPlaylistsSchema>;
+export type PlaylistsMessage = z.infer<typeof PlaylistsSchema>;
+export type KnockMessage = z.infer<typeof KnockSchema>;
+export type KnockStatusMessage = z.infer<typeof KnockStatusSchema>;
+export type BlobRequestMessage = z.infer<typeof BlobRequestSchema>;
+export type BlobReadyMessage = z.infer<typeof BlobReadySchema>;
+export type ErrorMessage = z.infer<typeof ErrorSchema>;
+export type KnockNotifyMessage = z.infer<typeof KnockNotifySchema>;
+
+// ---- BiStream structural interface ----
+// matches the shape provided by midden without importing it
+
+export interface BiStreamLike {
+  write_message(data: Uint8Array): Promise<void>;
+  read_message(): Promise<Uint8Array | null>;
+  close(): void;
+  peer_node_id(): string;
+  alpn(): string;
+}
+
+// ---- codec ----
+
+// error thrown when decoding an invalid or unrecognized message
+export class ProtocolError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "ProtocolError";
+    this.code = code;
+  }
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+// serialize a message to utf-8 JSON bytes
+export function encodeMessage(msg: Message): Uint8Array {
+  return encoder.encode(JSON.stringify(msg));
+}
+
+// parse utf-8 JSON bytes back to a Message.
+// throws ProtocolError with a descriptive code on invalid input.
+export function decodeMessage(bytes: Uint8Array): Message {
+  let json: string;
+  try {
+    json = decoder.decode(bytes);
+  } catch (err) {
+    throw new ProtocolError(
+      "decode_error",
+      `failed to decode utf-8: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(json);
+  } catch (err) {
+    throw new ProtocolError(
+      "parse_error",
+      `failed to parse json: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const result = MessageSchema.safeParse(raw);
+  if (!result.success) {
+    const firstIssue = result.error.issues[0];
+    throw new ProtocolError(
+      "schema_error",
+      `invalid message: ${firstIssue?.message ?? "unknown"}`,
+    );
+  }
+  return result.data;
+}
+
+// write a message to a BiStream
+export async function sendMessage(
+  stream: BiStreamLike,
+  msg: Message,
+): Promise<void> {
+  await stream.write_message(encodeMessage(msg));
+}
+
+// read the next message from a BiStream.
+// returns null on clean EOF (read_message returned null).
+// throws ProtocolError on invalid data.
+export async function readMessage(
+  stream: BiStreamLike,
+): Promise<Message | null> {
+  const bytes = await stream.read_message();
+  if (bytes === null) return null;
+  return decodeMessage(bytes);
+}