@freqhole/api-client 0.1.30 → 0.1.32

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.32",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/freqhole/tomb"
+  },
   "main": "./src/index.ts",
   "publishConfig": {
     "access": "public"
@@ -9,7 +13,6 @@
   "exports": {
     ".": "./src/index.ts",
     "./storage": "./src/storage/index.ts",
-    "./playlistz": "./src/playlistz/index.ts",
     "./automerge": "./src/automerge/index.ts"
   },
   "scripts": {

package/src/automerge/IrohNetworkAdapter.ts

@@ -77,6 +77,8 @@ export interface BiStreamLike {
  */
 export interface MiddenStreamNode {
   node_id(): string;
+  /** full serialized endpoint addr (node id + relay url) for deterministic dialing. */
+  node_addr?(): string;
   open_bi(peer_addr: string, alpn: string): Promise<BiStreamLike>;
   accept(): Promise<BiStreamLike | null>;
 }
@@ -153,6 +155,14 @@ export class IrohNetworkAdapter extends NetworkAdapter {
     { attempt: number; timer: ReturnType<typeof setTimeout> | null }
   >();
 
+  /**
+   * optional per-peer dial address hint keyed by node id. when present the
+   * adapter dials this full endpoint addr instead of the bare node id, which
+   * skips discovery (pkarr/dns) lookup. empty in normal operation; populated
+   * by callers that already know a peer's reachable addr.
+   */
+  private peerDialAddr = new Map<string, string>();
+
   /** listeners for connection state changes. */
   private connectionStateListeners: Array<() => void> = [];
 
@@ -248,6 +258,7 @@ export class IrohNetworkAdapter extends NetworkAdapter {
     this.readLoops.clear();
     this.intendedPeers.clear();
     this.failedPeers.clear();
+    this.peerDialAddr.clear();
     this.alpnHandlers.clear();
 
     // cancel all pending reconnection timers
@@ -278,7 +289,7 @@ export class IrohNetworkAdapter extends NetworkAdapter {
    * ALPN, starts a read loop, and emits a peer-candidate event so
    * automerge-repo begins syncing with this peer.
    */
-  async addPeer(nodeId: string): Promise<void> {
+  async addPeer(nodeId: string, dialAddr?: string): Promise<void> {
     if (this._disconnected) {
       throw new Error("adapter is disconnected");
     }
@@ -286,6 +297,11 @@ export class IrohNetworkAdapter extends NetworkAdapter {
     // track this peer as one we intend to stay connected to
     this.intendedPeers.add(nodeId);
     this.failedPeers.delete(nodeId);
+    // remember an explicit dial addr hint so dials (and reconnects) can skip
+    // discovery. keyed by node id; everything else stays keyed by node id too.
+    if (dialAddr) {
+      this.peerDialAddr.set(nodeId, dialAddr);
+    }
     this.emitConnectionStateChange();
 
     // clear any pending reconnection state - this is a fresh attempt
@@ -298,9 +314,22 @@ export class IrohNetworkAdapter extends NetworkAdapter {
     }
 
     const midden = await this.ensureMidden();
-    const stream = await midden.open_bi(nodeId, this.syncAlpn);
-
-    this.registerStream(nodeId, stream);
+    const target = this.peerDialAddr.get(nodeId) ?? nodeId;
+    try {
+      const stream = await midden.open_bi(target, this.syncAlpn);
+      this.registerStream(nodeId, stream);
+    } catch (err) {
+      // the initial dial can fail when the peer is not yet discoverable. hand
+      // off to the background reconnect loop with backoff instead of forcing
+      // every caller to implement its own retry.
+      console.warn(
+        TAG,
+        "initial dial failed, scheduling reconnect:",
+        nodeId.slice(0, 16) + "...",
+        err
+      );
+      this.scheduleReconnect(nodeId);
+    }
   }
 
   /**
@@ -313,6 +342,7 @@ export class IrohNetworkAdapter extends NetworkAdapter {
     // remove from intended set first so removePeer() won't schedule a reconnect
     this.intendedPeers.delete(nodeId);
     this.failedPeers.delete(nodeId);
+    this.peerDialAddr.delete(nodeId);
     this.clearReconnectState(nodeId);
     // delegate stream cleanup and peer-disconnected emission to removePeer
     this.removePeer(nodeId);
@@ -643,6 +673,7 @@ export class IrohNetworkAdapter extends NetworkAdapter {
       );
       this.intendedPeers.delete(peerId);
       this.failedPeers.add(peerId);
+      this.peerDialAddr.delete(peerId);
       this.clearReconnectState(peerId);
       this.emitConnectionStateChange();
       return;
@@ -696,7 +727,8 @@ export class IrohNetworkAdapter extends NetworkAdapter {
 
     try {
       const midden = await this.ensureMidden();
-      const stream = await midden.open_bi(peerId, this.syncAlpn);
+      const target = this.peerDialAddr.get(peerId) ?? peerId;
+      const stream = await midden.open_bi(target, this.syncAlpn);
       console.log(TAG, "reconnected to peer:", peerId.slice(0, 16) + "...");
       this.registerStream(peerId, stream);
       // registerStream calls clearReconnectState, so no need to do it here

package/src/domains/admin.ts

@@ -93,5 +93,28 @@ export function createAdminMethods(call: CallFn) {
         routes.admin.get_knock_status_public.path,
       );
     },
+
+    // internal service callbacks
+    deviceLinkedCallback: (params: s.DeviceLinkedCallbackRequest) => {
+      return call(
+        "admin", "device_linked_callback",
+        routes.admin.device_linked_callback.resp,
+        routes.admin.device_linked_callback.req,
+        routes.admin.device_linked_callback.method,
+        routes.admin.device_linked_callback.path,
+        params,
+      );
+    },
+
+    knockAcceptedCallback: (params: s.KnockAcceptedCallbackRequest) => {
+      return call(
+        "admin", "knock_accepted_callback",
+        routes.admin.knock_accepted_callback.resp,
+        routes.admin.knock_accepted_callback.req,
+        routes.admin.knock_accepted_callback.method,
+        routes.admin.knock_accepted_callback.path,
+        params,
+      );
+    },
   };
 }

package/src/test.ts

@@ -2,7 +2,6 @@
 import { validateWrapperCoverage } from "./test/coverage.js";
 import { runIntegrationTests } from "./test/integration.js";
 import { runStatefulTests } from "./test/stateful.js";
-import { runPlaylistzTests } from "./test/playlistz.js";
 import { runAutomergeTests } from "./test/automerge.js";
 import { runStorageTests } from "./test/storage.js";
 
@@ -22,14 +21,6 @@ async function main() {
   console.log("=".repeat(50));
   console.log("");
 
-  // always run playlistz domain tests (pure - no server needed)
-  const playlistzResults = await runPlaylistzTests();
-  totalPassed += playlistzResults.passed;
-  totalFailed += playlistzResults.failed;
-
-  console.log("=".repeat(50));
-  console.log("");
-
   // automerge adapter unit tests (no server required)
   const automergeResults = await runAutomergeTests();
   totalPassed += automergeResults.passed;

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);
-}