@freqhole/api-client 0.1.30

package/src/domains/types.ts

@@ -0,0 +1,19 @@
+// shared types for domain method factories
+
+import { z } from "zod";
+
+// result types
+type SafeParseSuccess<T> = { success: true; data: T };
+type SafeParseError = { success: false; error: z.ZodError };
+export type SafeParseResult<T> = SafeParseSuccess<T> | SafeParseError;
+
+// the call function signature used by domain methods
+export type CallFn = <Resp>(
+  domain: string,
+  routeName: string,
+  respSchema: z.ZodType<Resp> | null,
+  reqSchema: z.ZodTypeAny | null,
+  method: string,
+  path: string,
+  params?: any,
+) => Promise<SafeParseResult<Resp>>;

package/src/domains/upload.ts

@@ -0,0 +1,214 @@
+// upload domain methods for FreqholeClient
+// uses transport.upload() for FormData handling
+
+import { z } from "zod";
+import type * as s from "../codegen/schema.js";
+import {
+  ImageUploadResponseSchema,
+  MusicImportResponseSchema,
+  MusicUploadResponseSchema,
+} from "../codegen/schema.js";
+import type { Transport } from "../transport.js";
+import type { SafeParseResult } from "./types.js";
+
+// helper to parse response and validate with schema
+function parseResponse<T>(
+  responseBody: string,
+  status: number,
+  schema: z.ZodType<T>,
+): SafeParseResult<T> {
+  if (status >= 400) {
+    let errorMessage = `HTTP ${status}`;
+    try {
+      const errorBody = JSON.parse(responseBody);
+      if (errorBody?.error) {
+        errorMessage = `HTTP ${status}: ${errorBody.error}`;
+      }
+    } catch {
+      // body wasn't JSON
+    }
+    return {
+      success: false,
+      error: new z.ZodError([
+        { code: "custom", path: [], message: errorMessage },
+      ]),
+    };
+  }
+
+  try {
+    const json = JSON.parse(responseBody);
+    const data = json.data ?? json;
+    const result = schema.safeParse(data);
+    if (result.success) {
+      return { success: true, data: result.data };
+    } else {
+      return { success: false, error: result.error };
+    }
+  } catch (err) {
+    return {
+      success: false,
+      error: new z.ZodError([
+        {
+          code: "custom",
+          path: [],
+          message: err instanceof Error ? err.message : "parse error",
+        },
+      ]),
+    };
+  }
+}
+
+export type UploadImageOptions = {
+  /** optionally associate the image with an entity (album, playlist, song, artist, etc.) */
+  associate?: s.AssociationHint;
+};
+
+export function createUploadMethods(transport: Transport) {
+  return {
+    /**
+     * upload a music file
+     * returns job information for async processing
+     */
+    music: async (
+      file: File | Blob,
+    ): Promise<SafeParseResult<s.MusicUploadResponse>> => {
+      const formData = new FormData();
+      formData.append("file", file);
+
+      const response = await transport.upload("/api/upload/music", formData);
+      return parseResponse(
+        response.body,
+        response.status,
+        MusicUploadResponseSchema,
+      );
+    },
+
+    /**
+     * upload a music file by filesystem path (tauri P2P only).
+     * imports the file into the local iroh-blobs store, then tells the remote
+     * peer to pull it via verified streaming.
+     * requires transport.uploadByPath to be implemented (CharnelTransport).
+     */
+    musicByPath: async (
+      filePath: string,
+    ): Promise<SafeParseResult<s.MusicUploadResponse>> => {
+      if (!transport.uploadByPath) {
+        return {
+          success: false,
+          error: new z.ZodError([
+            {
+              code: "custom",
+              path: [],
+              message: "uploadByPath not supported by this transport",
+            },
+          ]),
+        };
+      }
+
+      const response = await transport.uploadByPath(
+        "/api/upload/music",
+        filePath,
+      );
+      return parseResponse(
+        response.body,
+        response.status,
+        MusicUploadResponseSchema,
+      );
+    },
+
+    /**
+     * upload an image file
+     * optionally associate with an entity (album, playlist, song, artist)
+     */
+    image: async (
+      file: File | Blob,
+      options?: UploadImageOptions,
+    ): Promise<SafeParseResult<s.ImageUploadResponse>> => {
+      const formData = new FormData();
+      formData.append("file", file);
+
+      if (options?.associate) {
+        formData.append("associate_with", JSON.stringify(options.associate));
+      }
+
+      const response = await transport.upload("/api/upload/image", formData);
+      return parseResponse(
+        response.body,
+        response.status,
+        ImageUploadResponseSchema,
+      );
+    },
+
+    /**
+     * upload an image by filesystem path (tauri-local only)
+     * bypasses base64 encoding by passing path directly to backend
+     * requires transport.uploadByPath to be implemented
+     */
+    imageByPath: async (
+      filePath: string,
+      options?: UploadImageOptions,
+    ): Promise<SafeParseResult<s.ImageUploadResponse>> => {
+      if (!transport.uploadByPath) {
+        return {
+          success: false,
+          error: new z.ZodError([
+            {
+              code: "custom",
+              path: [],
+              message: "uploadByPath not supported by this transport",
+            },
+          ]),
+        };
+      }
+
+      const metadata: Record<string, unknown> = {};
+      if (options?.associate) {
+        metadata.associate_with = options.associate;
+      }
+
+      const response = await transport.uploadByPath(
+        "/api/upload/image",
+        filePath,
+        metadata,
+      );
+      return parseResponse(
+        response.body,
+        response.status,
+        ImageUploadResponseSchema,
+      );
+    },
+
+    /**
+     * import music files by filesystem paths (tauri-local only)
+     * accepts file paths or directory paths (directories are scanned recursively)
+     * bypasses file transfer since files are already local
+     * requires transport.request to be implemented (uses POST with JSON body)
+     *
+     * @param paths - array of file or directory paths to import
+     * @param options - optional settings
+     * @param options.waitForCompletion - if true, wait for all jobs to complete (up to 5 min)
+     */
+    musicByPaths: async (
+      paths: string[],
+      options?: { waitForCompletion?: boolean },
+    ): Promise<SafeParseResult<s.MusicImportResponse>> => {
+      const body = {
+        paths,
+        wait_for_completion: options?.waitForCompletion ?? false,
+      };
+
+      const response = await transport.request(
+        "POST",
+        "/api/upload/music-paths",
+        JSON.stringify(body),
+      );
+      return parseResponse(
+        response.body,
+        response.status,
+        MusicImportResponseSchema,
+      );
+    },
+  };
+}
+
+export type UploadMethods = ReturnType<typeof createUploadMethods>;

package/src/index.ts

@@ -0,0 +1,48 @@
+// freqhole api client - main exports
+
+// instance-based client
+export { FreqholeClient, createClient, createHttpClient, isAuthError, isNetworkError } from "./FreqholeClient.js";
+export type { SafeParseResult } from "./FreqholeClient.js";
+
+// transport abstraction
+export { HttpTransport, pollingJobEvents, snapshotJobEventsViaRequest, POLL_INTERVAL_FALLBACK_MS } from "./transport.js";
+export { WasmTransport } from "./WasmTransport.js";
+export { CharnelTransport, createCharnelTransport, getCharnelTransport, getCharnelNodeId, isCharnelAvailable, isCharnelP2PAvailable } from "./CharnelTransport.js";
+export { CharnelLocalTransport, createCharnelLocalTransport, JobEventsStreamClosed } from "./CharnelLocalTransport.js";
+export type { MiddenNodeLike, BlobResultLike, BlobProgressCallback, RadioHandleLike } from "./WasmTransport.js";
+export type { Transport, TransportResponse, BlobData } from "./transport.js";
+
+// export utilities (url helpers, uploads, etc)
+export * as utils from "./utils.js";
+
+// export webauthn helpers
+export * as webauthn from "./webauthn.js";
+
+// export permission helpers
+export * as permissions from "./permissions.js";
+
+// export hand-rolled favorites types (codegen doesn't handle discriminated unions)
+export type { FavoriteItem, ListFavoritesResponse } from "./domains/favorites.types.js";
+
+// export schemas and types
+export type * from "./codegen/schema.js";
+export * as schema from "./codegen/schema.js";
+
+// export route auth types
+export type { RouteAuth, RouteAuthType, UserRoleName } from "./codegen/routes.js";
+export { roleHierarchy } from "./codegen/routes.js";
+
+// export admin client (freqhole-admin/1 ALPN)
+export {
+  AdminClient,
+  AdminCommandError,
+  AdminRequestValidationError,
+  AdminResponseValidationError,
+} from "./AdminClient.js";
+export type {
+  AdminTransport,
+  AdminResponse,
+  AdminErrorDetail,
+} from "./AdminClient.js";
+export { adminCommands } from "./codegen/admin_commands.js";
+export type { AdminCommandName, AdminAuth, AdminAuthType } from "./codegen/admin_commands.js";