@freqhole/api-client 0.1.30 → 0.1.31

package/README.md

@@ -0,0 +1,49 @@
+# @freqhole/api-client
+
+type-safe TypeScript client for freqhole APIs.
+
+this package wraps generated route + schema metadata with a small runtime client so requests are validated and typed on both input and output.
+
+## install
+
+```bash
+npm i @freqhole/api-client
+```
+
+for local monorepo usage, this repo usually links it by file path.
+
+## quick start
+
+```ts
+import { createHttpClient } from "@freqhole/api-client";
+
+const api = createHttpClient({
+  baseUrl: "http://localhost:4315",
+});
+
+const songs = await api.music.listSongs({
+  query: { limit: 25, offset: 0 },
+});
+
+if (songs.success) {
+  console.log(songs.data.songs.length);
+}
+```
+
+## package structure
+
+- `src/codegen/schema.ts`: generated zod schemas
+- `src/codegen/routes.ts`: generated route metadata
+- `src/*.ts`: hand-written helpers and client adapters
+
+avoid editing files under `src/codegen/` directly.
+
+## development notes
+
+if you are working in this repo and need to regenerate types/routes, run codegen from `client-codegen/`.
+
+the full generator workflow and architecture docs live in `client-codegen/README.md`.
+
+---
+
+made with 💖 in NYC

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@freqhole/api-client",
-  "version": "0.1.30",
+  "version": "0.1.31",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/freqhole/tomb"
+  },
   "main": "./src/index.ts",
   "publishConfig": {
     "access": "public"

package/src/playlistz/convert.ts

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

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

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

@@ -1,222 +0,0 @@
-// 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);
-}

package/src/playlistz/schema.ts

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

@@ -1,76 +0,0 @@
-// 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)}`;
-}