@freqhole/api-client 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freqhole/api-client",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "type": "module",
   "repository": {
     "type": "git",

package/src/WasmTransport.ts

@@ -975,6 +975,71 @@ export class WasmTransport implements Transport {
     return url;
   }
 
+  /**
+   * stream a blob's bytes straight to a caller-supplied sink, without ever
+   * assembling the whole blob in one buffer here - see the `Transport`
+   * interface doc comment for why this exists (docs/blob-transfer-opfs-
+   * and-sha256-refactor-plan.md phase 2). only the verified iroh-blobs
+   * path (blake3 required) is supported - callers without a blake3 should
+   * use `getBlobUrlWithProgress`/`fetchBlob` instead, same as before.
+   */
+  async streamBlobToSink(
+    blobId: string,
+    onChunk: (chunk: Uint8Array, offset: number) => void | Promise<void>,
+    onProgress: (received: number, total: number) => void,
+    blake3?: string,
+    totalBytes?: number,
+    mimeType?: string,
+  ): Promise<{ contentType: string; totalBytes: number }> {
+    if (!blake3) {
+      throw new TransportError(
+        `streamBlobToSink requires a blake3 hash for verified streaming (blob ${blobId})`,
+      );
+    }
+    const streamingFn =
+      this.node.download_verified_streaming_with_ensure ?? this.node.download_verified_streaming;
+    if (!streamingFn) {
+      throw new TransportError(
+        `streamBlobToSink: node has no streaming download method (blob ${blobId})`,
+      );
+    }
+
+    let totalReceived = 0;
+    // chunk delivery is fire-and-forget from the wasm side (see
+    // download_verified_streaming_with_ensure's own doc comment) - queue
+    // each onChunk call after the previous one finishes so a slow sink
+    // (e.g. an OPFS write) applies real backpressure instead of racing
+    // ahead of disk writes.
+    let writeChain: Promise<void> = Promise.resolve();
+
+    await streamingFn.call(
+      this.node,
+      this.peerAddr,
+      blake3,
+      totalBytes ?? 0,
+      (chunk: Uint8Array, offset: number) => {
+        // chunk is a wasm-owned Uint8Array view - copy to detach before
+        // it's handed off across the write chain / a later tick.
+        const owned = new Uint8Array(chunk.length);
+        owned.set(chunk);
+        totalReceived += owned.length;
+        writeChain = writeChain.then(() => onChunk(owned, offset));
+        if (!totalBytes || totalBytes <= 0) {
+          onProgress(totalReceived, totalReceived);
+        }
+      },
+      (fraction: number) => {
+        if (totalBytes && totalBytes > 0) {
+          const received = Math.min(totalBytes, Math.floor(fraction * totalBytes));
+          onProgress(received, totalBytes);
+        }
+      },
+    );
+    await writeChain;
+
+    return { contentType: mimeType ?? "application/octet-stream", totalBytes: totalReceived };
+  }
+
   /**
    * revoke a blob URL to free memory
    */

package/src/codegen/routes.ts

@@ -40,6 +40,7 @@ export const routes = {
     radio_public_blob_thumbnail: { method: 'GET', path: '/api/radio/stations/{station_id}/blobs/{blob_id}/thumb/{size}', req: null, resp: null, auth: { type: 'public' } as const },
     radio_public_timeline: { method: 'GET', path: '/api/radio/stations/{station_id}/timeline', req: null, resp: s.PublicTimelineManifestSchema, auth: { type: 'public' } as const },
     radio_stations: { method: 'GET', path: '/api/radio/stations', req: null, resp: s.RadioStationsResponseSchema, auth: { type: 'public' } as const },
+    radio_stations_full: { method: 'GET', path: '/api/radio/stations/full', req: null, resp: s.RadioStationsResponseSchema, auth: { type: 'authenticated' } as const },
     server_info: { method: 'GET', path: '/api/hello', req: null, resp: s.ServerInfoResponseSchema, auth: { type: 'public' } as const },
   },
   auth: {

package/src/codegen/schema.ts

@@ -1508,7 +1508,8 @@ export const CreateStationRequestSchema = z.object({
   encode_args: z.string().nullish(),
   codec: z.string().nullish(),
   play_mode: z.string().nullish(),
-  timeline_only_mode: z.boolean().nullish()
+  timeline_only_mode: z.boolean().nullish(),
+  content_mode: z.string().nullish()
 });
 export type CreateStationRequest = z.infer<typeof CreateStationRequestSchema>;
 
@@ -5190,6 +5191,7 @@ export const PublicAssetRefSchema = z.object({
 export type PublicAssetRef = z.infer<typeof PublicAssetRefSchema>;
 
 export const PublicNowPlayingSchema = z.object({
+  kind: z.string(),
   song_id: z.string(),
   title: z.string(),
   artist: z.string().nullish(),
@@ -5210,7 +5212,9 @@ export const PublicStationSchema = z.object({
   listener_count: z.number(),
   is_default: z.boolean(),
   is_public: z.boolean(),
+  is_running: z.boolean(),
   now_playing: z.object({
+  kind: z.string(),
   song_id: z.string(),
   title: z.string(),
   artist: z.string().nullish(),
@@ -5391,7 +5395,8 @@ export type QueryVideosRequest = z.infer<typeof QueryVideosRequestSchema>;
 export const RadioBumperSchema = z.object({
   id: z.string(),
   station_id: z.string(),
-  song_id: z.string(),
+  song_id: z.string().nullish(),
+  video_id: z.string().nullish(),
   label: z.string(),
   weight: z.number(),
   created_at: z.number()
@@ -5400,7 +5405,8 @@ export type RadioBumper = z.infer<typeof RadioBumperSchema>;
 
 export const RadioBumpersAddRequestSchema = z.object({
   station_id: z.string(),
-  song_id: z.string(),
+  song_id: z.string().nullish(),
+  video_id: z.string().nullish(),
   label: z.string(),
   weight: z.number().nullish()
 });
@@ -5424,8 +5430,12 @@ export type RadioBumpersSetFrequencyRequest = z.infer<typeof RadioBumpersSetFreq
 
 export const RadioConfigPayloadSchema = z.object({
   enabled: z.boolean(),
-  encode_args: z.string(),
-  ffmpeg_available: z.boolean()
+  encode_args: z.string().nullish(),
+  video_encode_args: z.string().nullish(),
+  video_codec: z.string().nullish(),
+  ffmpeg_available: z.boolean(),
+  max_concurrent_audio_streams: z.number(),
+  max_concurrent_video_streams: z.number()
 });
 export type RadioConfigPayload = z.infer<typeof RadioConfigPayloadSchema>;
 
@@ -5451,7 +5461,9 @@ export const RadioInfoResponseSchema = z.object({
   listener_count: z.number(),
   is_default: z.boolean(),
   is_public: z.boolean(),
+  is_running: z.boolean(),
   now_playing: z.object({
+  kind: z.string(),
   song_id: z.string(),
   title: z.string(),
   artist: z.string().nullish(),
@@ -5493,6 +5505,8 @@ export const RadioStationSchema = z.object({
   codec: z.string(),
   play_mode: z.string(),
   timeline_only_mode: z.number(),
+  content_mode: z.string(),
+  bumper_frequency_seconds: z.number().nullish(),
   created_at: z.number(),
   updated_at: z.number()
 });
@@ -5530,7 +5544,9 @@ export const RadioStationsResponseSchema = z.object({
   listener_count: z.number(),
   is_default: z.boolean(),
   is_public: z.boolean(),
+  is_running: z.boolean(),
   now_playing: z.object({
+  kind: z.string(),
   song_id: z.string(),
   title: z.string(),
   artist: z.string().nullish(),
@@ -7631,7 +7647,8 @@ export const UpdateStationRequestSchema = z.object({
   encode_args: z.string().nullish(),
   codec: z.string().nullish(),
   play_mode: z.string().nullish(),
-  timeline_only_mode: z.boolean().nullish()
+  timeline_only_mode: z.boolean().nullish(),
+  content_mode: z.string().nullish()
 });
 export type UpdateStationRequest = z.infer<typeof UpdateStationRequestSchema>;
 

package/src/domains/app.ts

@@ -7,7 +7,8 @@ export function createAppMethods(call: CallFn) {
   return {
     healthCheck: () => {
       return call(
-        "app", "health_check",
+        "app",
+        "health_check",
         routes.app.health_check.resp,
         routes.app.health_check.req,
         routes.app.health_check.method,
@@ -17,7 +18,8 @@ export function createAppMethods(call: CallFn) {
 
     serverInfo: () => {
       return call(
-        "app", "server_info",
+        "app",
+        "server_info",
         routes.app.server_info.resp,
         routes.app.server_info.req,
         routes.app.server_info.method,
@@ -27,7 +29,8 @@ export function createAppMethods(call: CallFn) {
 
     radioInfo: () => {
       return call(
-        "app", "radio_info",
+        "app",
+        "radio_info",
         routes.app.radio_info.resp,
         routes.app.radio_info.req,
         routes.app.radio_info.method,
@@ -37,7 +40,8 @@ export function createAppMethods(call: CallFn) {
 
     radioStations: () => {
       return call(
-        "app", "radio_stations",
+        "app",
+        "radio_stations",
         routes.app.radio_stations.resp,
         routes.app.radio_stations.req,
         routes.app.radio_stations.method,
@@ -45,10 +49,25 @@ export function createAppMethods(call: CallFn) {
       );
     },
 
+    // authenticated counterpart of radioStations() - includes non-public
+    // stations too, for a caller who actually resolved (real session or
+    // known iroh peer). see offal::music::radio's doc comment.
+    radioStationsFull: () => {
+      return call(
+        "app",
+        "radio_stations_full",
+        routes.app.radio_stations_full.resp,
+        routes.app.radio_stations_full.req,
+        routes.app.radio_stations_full.method,
+        routes.app.radio_stations_full.path,
+      );
+    },
+
     // get blob metadata for a station blob
     radioPublicBlob: (params: { station_id: string; blob_id: string }) => {
       return call(
-        "app", "radio_public_blob",
+        "app",
+        "radio_public_blob",
         routes.app.radio_public_blob.resp,
         routes.app.radio_public_blob.req,
         routes.app.radio_public_blob.method,
@@ -60,7 +79,8 @@ export function createAppMethods(call: CallFn) {
     // stream the binary data for a station blob
     radioPublicBlobData: (params: { station_id: string; blob_id: string }) => {
       return call(
-        "app", "radio_public_blob_data",
+        "app",
+        "radio_public_blob_data",
         routes.app.radio_public_blob_data.resp,
         routes.app.radio_public_blob_data.req,
         routes.app.radio_public_blob_data.method,
@@ -72,7 +92,8 @@ export function createAppMethods(call: CallFn) {
     // get a thumbnail for a station blob at a given size
     radioPublicBlobThumbnail: (params: { station_id: string; blob_id: string; size: string }) => {
       return call(
-        "app", "radio_public_blob_thumbnail",
+        "app",
+        "radio_public_blob_thumbnail",
         routes.app.radio_public_blob_thumbnail.resp,
         routes.app.radio_public_blob_thumbnail.req,
         routes.app.radio_public_blob_thumbnail.method,
@@ -84,7 +105,8 @@ export function createAppMethods(call: CallFn) {
     // get the public timeline manifest for a station
     radioPublicTimeline: (params: { station_id: string }) => {
       return call(
-        "app", "radio_public_timeline",
+        "app",
+        "radio_public_timeline",
         routes.app.radio_public_timeline.resp,
         routes.app.radio_public_timeline.req,
         routes.app.radio_public_timeline.method,

package/src/transport.ts

@@ -137,6 +137,34 @@ export interface Transport {
     opts?: BlobFetchOptions,
   ): Promise<string>;
 
+  /**
+   * stream a blob's bytes to a caller-supplied sink, chunk by chunk,
+   * instead of assembling the whole blob in memory first (optional).
+   * only implemented by WasmTransport - HTTP callers should stream
+   * directly from `fetch()`'s own `response.body` reader instead (see
+   * `streamVideoToOPFSWithResume`), and CharnelLocalTransport's sync-to-
+   * local path never goes through JS at all (grimoire's own disk-backed
+   * pull). intended for a caller writing straight to OPFS (or anywhere
+   * else) without ever holding the full blob in one buffer - see
+   * docs/blob-transfer-opfs-and-sha256-refactor-plan.md phase 2.
+   * @param blobId - the blob ID to fetch
+   * @param onChunk - called with each chunk as it arrives, in order
+   * @param onProgress - callback with (received, total) bytes
+   * @param blake3 - optional blake3 hash for verified streaming via iroh-blobs
+   * @param totalBytes - optional known total size in bytes
+   * @param mimeType - optional content type (midden's streaming path doesn't
+   *   surface the source mime)
+   * @returns the content type and total bytes actually streamed
+   */
+  streamBlobToSink?(
+    blobId: string,
+    onChunk: (chunk: Uint8Array, offset: number) => void | Promise<void>,
+    onProgress: (received: number, total: number) => void,
+    blake3?: string,
+    totalBytes?: number,
+    mimeType?: string,
+  ): Promise<{ contentType: string; totalBytes: number }>;
+
   /**
    * fetch server image (public, no auth required)
    * used during "add remote" flow before user is authenticated