@freqhole/api-client 0.1.30 → 0.1.32

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