@freqhole/api-client 0.1.31 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freqhole/api-client",
-  "version": "0.1.31",
+  "version": "0.2.1",
   "type": "module",
   "repository": {
     "type": "git",
@@ -11,36 +11,26 @@
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./storage": "./src/storage/index.ts",
-    "./playlistz": "./src/playlistz/index.ts",
-    "./automerge": "./src/automerge/index.ts"
+    ".": "./src/index.ts"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "tsx src/test.ts",
     "test:coverage": "SKIP_INTEGRATION=true tsx src/test.ts",
     "test:integration": "tsx src/test.ts",
+    "test:unit": "vitest run",
     "auth-test": "vite --config vite.config.js"
   },
   "dependencies": {
-    "idb": "^8.0.3",
-    "zod": "^4.3.5"
-  },
-  "peerDependencies": {
-    "@automerge/automerge-repo": "^2.5.5"
-  },
-  "peerDependenciesMeta": {
-    "@automerge/automerge-repo": {
-      "optional": true
-    }
+    "zod": "^4.3.5",
+    "@freqhole/haruspex": "file:../../lib/haruspex/ts"
   },
   "devDependencies": {
-    "@automerge/automerge-repo": "^2.5.6",
     "@tauri-apps/api": "^2.10.1",
     "@types/node": "^25.0.8",
     "tsx": "^4.7.0",
+    "vitest": "^2.1.0",
     "typescript": "^5.3.0",
     "vite": "^5.4.21"
   }
-}
+}

package/src/CharnelTransport.ts

@@ -128,12 +128,12 @@ export class CharnelTransport implements Transport {
     const inv = await ensureInvoke();
 
     // intentionally no per-error debug log here: the underlying
-    // p2p_proxy_request command already traces failures on the rust
+    // p2p_api_call command already traces failures on the rust
     // side, and callers (auth-status, health-check, etc.) decide
     // whether to surface the error. logging at this layer fires once
     // per request per failed peer and drowns the console for any
     // peer that's temporarily unreachable.
-    const result = (await inv("p2p_proxy_request", {
+    const result = (await inv("p2p_api_call", {
       peerAddr: this.peerAddr,
       method,
       path,
@@ -218,7 +218,7 @@ export class CharnelTransport implements Transport {
       );
     }
 
-    // for non-music uploads, send path + metadata via proxy_request
+    // for non-music uploads, send path + metadata via api_request
     const body: Record<string, unknown> = {
       file_path: filePath,
       ...metadata,
@@ -253,7 +253,7 @@ export class CharnelTransport implements Transport {
       }
     }
 
-    // send via proxy_request — routes through offal dispatch on the remote peer
+    // send via api_request — routes through offal dispatch on the remote peer
     return this.request("POST", path, JSON.stringify(body));
   }
 
@@ -311,7 +311,7 @@ export class CharnelTransport implements Transport {
   /**
    * fetch a blob via P2P
    * if blake3 is provided, uses iroh-blobs verified streaming.
-   * for blobs without blake3 (images, waveforms, thumbnails), uses proxy_request
+   * for blobs without blake3 (images, waveforms, thumbnails), uses api_request
    * to fetch base64-encoded data from the peer's /api/blobs/{id}/data endpoint.
    */
   async fetchBlob(blobId: string, blake3?: string): Promise<BlobData> {
@@ -334,7 +334,7 @@ export class CharnelTransport implements Transport {
       };
     }
 
-    // no blake3 — try proxy_request to get blob data from database
+    // no blake3 — try api_request to get blob data from database
     // this is the primary path for images (waveforms, thumbnails) stored in the database
     try {
       const result = await this.request("GET", `/api/blobs/${blobId}/data`);
@@ -349,7 +349,7 @@ export class CharnelTransport implements Transport {
     } catch (e) {
       const errorMessage = e instanceof Error ? e.message : String(e);
       console.warn(
-        `[CharnelTransport] proxy blob data request failed, falling back to verified download: ${errorMessage}`,
+        `[CharnelTransport] api blob data request failed, falling back to verified download: ${errorMessage}`,
       );
     }
 

package/src/WasmTransport.ts

@@ -45,7 +45,7 @@ export interface BiStreamLike {
 export interface MiddenNodeLike {
   node_id(): string;
   secret_key(): Uint8Array;
-  proxy_request(
+  api_request(
     peer_addr: string,
     method: string,
     path: string,
@@ -218,7 +218,7 @@ export class WasmTransport implements Transport {
     body?: string,
   ): Promise<TransportResponse> {
     try {
-      const result = await this.node.proxy_request(
+      const result = await this.node.api_request(
         this.peerAddr,
         method,
         path,
@@ -260,7 +260,7 @@ export class WasmTransport implements Transport {
       return this.uploadViaIrohBlobs(file, formData);
     }
 
-    // fallback: base64 encode and send via proxy_request (works for image uploads)
+    // fallback: base64 encode and send via api_request (works for image uploads)
     return this.uploadViaBase64(path, file, formData);
   }
 
@@ -363,7 +363,7 @@ export class WasmTransport implements Transport {
       }
     }
 
-    // send via proxy_request — routes through offal dispatch on the remote peer
+    // send via api_request — routes through offal dispatch on the remote peer
     return this.request("POST", path, JSON.stringify(body));
   }
 
@@ -407,15 +407,15 @@ export class WasmTransport implements Transport {
           console.warn(
             `[WasmTransport] verified download failed, falling back: ${errorMessage}`,
           );
-          // fall through to proxy fetch
+          // fall through to api fetch
         }
       }
     }
 
-    // no blake3 (or verified download failed) — try proxy_request to get blob data
+    // no blake3 (or verified download failed) — try api_request to get blob data
     // this is the primary path for images (waveforms, thumbnails) stored in the database
     try {
-      const result = await this.node.proxy_request(
+      const result = await this.node.api_request(
         this.peerAddr,
         "GET",
         `/api/blobs/${blobId}/data`,
@@ -443,7 +443,7 @@ export class WasmTransport implements Transport {
     } catch (e) {
       const errorMessage = e instanceof Error ? e.message : String(e);
       console.warn(
-        `[WasmTransport] proxy blob data request failed, falling back: ${errorMessage}`,
+        `[WasmTransport] api blob data request failed, falling back: ${errorMessage}`,
       );
     }
 
@@ -653,9 +653,10 @@ export class WasmTransport implements Transport {
     }
 
     // no blake3 (or verified download failed).
-    // for audio blobs, prefer verified-by-id before proxy `/data` because
-    // `/api/blobs/{id}/data` only works for DB-backed blobs and file-backed
-    // media blobs would otherwise fail first, then fall back anyway.
+    // for audio blobs, prefer verified-by-id before the api_request `/data`
+    // fallback because `/api/blobs/{id}/data` only works for DB-backed blobs
+    // and file-backed media blobs would otherwise fail first, then fall back
+    // anyway.
     if (
       !blake3 &&
       this.node.download_verified_by_id &&
@@ -684,15 +685,15 @@ export class WasmTransport implements Transport {
       } catch (e) {
         const errorMessage = e instanceof Error ? e.message : String(e);
         console.warn(
-          `[WasmTransport] audio verified-by-id failed, falling back to proxy: ${errorMessage}`,
+          `[WasmTransport] audio verified-by-id failed, falling back to api_request: ${errorMessage}`,
         );
       }
     }
 
-    // try proxy_request to get blob data
-    let proxyFailureReason: string | null = null;
+    // try api_request to get blob data
+    let apiFailureReason: string | null = null;
     try {
-      const result = await this.node.proxy_request(
+      const result = await this.node.api_request(
         this.peerAddr,
         "GET",
         `/api/blobs/${blobId}/data`,
@@ -719,17 +720,17 @@ export class WasmTransport implements Transport {
 
           return { data, contentType };
         }
-        proxyFailureReason = `success=false in proxy response body for blob ${blobId}`;
-        console.warn(`[WasmTransport] ${proxyFailureReason}`);
+        apiFailureReason = `success=false in api response body for blob ${blobId}`;
+        console.warn(`[WasmTransport] ${apiFailureReason}`);
       } else {
-        proxyFailureReason = `proxy returned status ${result.status} for blob ${blobId}`;
-        console.warn(`[WasmTransport] ${proxyFailureReason}`);
+        apiFailureReason = `api request returned status ${result.status} for blob ${blobId}`;
+        console.warn(`[WasmTransport] ${apiFailureReason}`);
       }
     } catch (e) {
       const errorMessage = e instanceof Error ? e.message : String(e);
-      proxyFailureReason = `proxy request threw: ${errorMessage}`;
+      apiFailureReason = `api request threw: ${errorMessage}`;
       console.warn(
-        `[WasmTransport] proxy blob data request failed, falling back: ${errorMessage}`,
+        `[WasmTransport] api blob data request failed, falling back: ${errorMessage}`,
       );
     }
 
@@ -804,7 +805,7 @@ export class WasmTransport implements Transport {
     throw new Error(
       `no download method available for blob ${blobId} ` +
         `(blake3=${blake3 ? "yes" : "no"}, ` +
-        `proxy=${proxyFailureReason ?? "not attempted"}, ` +
+        `api=${apiFailureReason ?? "not attempted"}, ` +
         `legacy_fetch_blob=${this.node.fetch_blob ? "available" : "missing"})`,
     );
   }

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/permissions.ts

@@ -1,8 +1,12 @@
 // permission helpers for route authorization
 //
 // these are hand-written helpers that use the generated route auth metadata
-// to check if a user has permission to perform actions.
+// to check if a user has permission to perform actions. the core role-
+// hierarchy/route-auth evaluation logic is bound once over this package's
+// own codegen'd role hierarchy from @freqhole/haruspex/permissions - only
+// the entity-specific route lookups below are tomb-specific.
 
+import { bindRoleHierarchy, type AccessRule } from "@freqhole/haruspex/permissions";
 import {
   roleHierarchy,
   routes,
@@ -10,6 +14,8 @@ import {
   type UserRoleName,
 } from "./codegen/routes.js";
 
+const roleChecks = bindRoleHierarchy(roleHierarchy);
+
 // ============================================================================
 // core permission functions
 // ============================================================================
@@ -26,7 +32,7 @@ export function canAccessRole(
   userRole: UserRoleName,
   requiredRole: UserRoleName,
 ): boolean {
-  return roleHierarchy[userRole] <= roleHierarchy[requiredRole];
+  return roleChecks.hasAtLeastRole(userRole, requiredRole);
 }
 
 /**
@@ -45,12 +51,7 @@ export function canAccessOwnerOr(
   userRole: UserRoleName,
   requiredRole: UserRoleName,
 ): boolean {
-  // owner always has access
-  if (ownerId !== null && userId === ownerId) {
-    return true;
-  }
-  // otherwise check role
-  return canAccessRole(userRole, requiredRole);
+  return roleChecks.canAccessOwnerOr(userId, ownerId, userRole, requiredRole);
 }
 
 /**
@@ -65,7 +66,7 @@ export function canAccessOwner(
   userId: string,
   ownerId: string | null,
 ): boolean {
-  return ownerId !== null && userId === ownerId;
+  return roleChecks.isOwner(userId, ownerId);
 }
 
 /**
@@ -84,28 +85,14 @@ export function canAccessRoute(
   userId: string | null,
   ownerId: string | null,
 ): boolean {
-  switch (auth.type) {
-    case "public":
-      return true;
-
-    case "authenticated":
-      return userRole !== null;
-
-    case "role":
-      return userRole !== null && canAccessRole(userRole, auth.role);
-
-    case "owner":
-      return userId !== null && canAccessOwner(userId, ownerId);
-
-    case "owner_or":
-      return (
-        userId !== null &&
-        userRole !== null &&
-        canAccessOwnerOr(userId, ownerId, userRole, auth.role)
-      );
-  }
+  return roleChecks.canAccess(auth as AccessRule<UserRoleName>, {
+    userRole,
+    userId,
+    ownerId,
+  });
 }
 
+
 // ============================================================================
 // entity-specific permission helpers
 // ============================================================================

package/src/pollingJobEvents.test.ts

@@ -0,0 +1,192 @@
+// tests for the http polling fallback's snapshot-diffing state machine.
+//
+// pollingJobEvents synthesizes status_changed/stage events by diffing
+// consecutive snapshots against a retained baseline (`prev`). these
+// tests exist because that diffing logic previously had a real bug: a
+// transient snapshot fetch failure wiped `prev` entirely, causing every
+// still-active job to spuriously re-announce as "new" (from: null) on
+// the next successful poll even though nothing had actually changed.
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  pollingJobEvents,
+  POLL_INTERVAL_FALLBACK_MS,
+  type Transport,
+  type TransportResponse,
+} from "./transport.js";
+import type { JobStateSnapshot } from "./codegen/schema.js";
+
+function snapshot(
+  overrides: Partial<JobStateSnapshot> & Pick<JobStateSnapshot, "job_id">,
+): JobStateSnapshot {
+  return {
+    session_id: null,
+    job_type: "ScanDirectory",
+    status: "pending",
+    entity_ref: null,
+    created_by: null,
+    last_stage: null,
+    last_message: null,
+    updated_at: 0,
+    ...overrides,
+  };
+}
+
+/** a fake Transport whose `request` returns one canned snapshot list (or
+ *  throws) per call, in order. the last entry repeats for any extra calls. */
+function fakeTransport(responses: Array<JobStateSnapshot[] | Error>): Transport {
+  let call = 0;
+  const request = vi.fn(async (): Promise<TransportResponse> => {
+    const entry = responses[Math.min(call, responses.length - 1)];
+    call++;
+    if (entry instanceof Error) throw entry;
+    return { status: 200, body: JSON.stringify({ success: true, data: entry }) };
+  });
+  return {
+    request,
+    upload: vi.fn(),
+    fetchBlob: vi.fn(),
+    getBlobUrl: vi.fn(),
+  } as unknown as Transport;
+}
+
+/** advances the fake poll-interval timer `count` times in sequence,
+ *  fully draining the microtask queue between each advance. */
+async function advanceTicks(count: number): Promise<void> {
+  for (let i = 0; i < count; i++) {
+    await vi.advanceTimersByTimeAsync(POLL_INTERVAL_FALLBACK_MS);
+  }
+}
+
+describe("pollingJobEvents", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("the first tick only seeds the baseline - no event for an already-known job", async () => {
+    const transport = fakeTransport([
+      [snapshot({ job_id: "job-a", status: "running" })],
+      [snapshot({ job_id: "job-a", status: "completed" })],
+    ]);
+    const iter = pollingJobEvents(transport);
+    const nextPromise = iter.next();
+
+    await advanceTicks(1);
+    const result = await nextPromise;
+
+    expect(result.done).toBe(false);
+    expect(result.value).toMatchObject({
+      kind: "status_changed",
+      job_id: "job-a",
+      from: "running",
+      to: "completed",
+    });
+  });
+
+  it("a job appearing after the baseline yields status_changed with from: null", async () => {
+    const transport = fakeTransport([
+      [],
+      [snapshot({ job_id: "job-a", status: "running" })],
+    ]);
+    const iter = pollingJobEvents(transport);
+    const nextPromise = iter.next();
+
+    await advanceTicks(1);
+    const result = await nextPromise;
+
+    expect(result.value).toMatchObject({
+      kind: "status_changed",
+      job_id: "job-a",
+      from: null,
+      to: "running",
+    });
+  });
+
+  it("a stage/message change yields a stage event", async () => {
+    const transport = fakeTransport([
+      [snapshot({ job_id: "job-a", status: "running", last_stage: "scanning" })],
+      [
+        snapshot({
+          job_id: "job-a",
+          status: "running",
+          last_stage: "importing",
+          last_message: "42 files",
+        }),
+      ],
+    ]);
+    const iter = pollingJobEvents(transport);
+    const nextPromise = iter.next();
+
+    await advanceTicks(1);
+    const result = await nextPromise;
+
+    expect(result.value).toMatchObject({
+      kind: "stage",
+      job_id: "job-a",
+      stage: "importing",
+      message: "42 files",
+    });
+  });
+
+  it("a transient fetch failure between two ticks does not wipe tracked state (regression)", async () => {
+    const transport = fakeTransport([
+      [snapshot({ job_id: "job-a", status: "running" })], // tick 1: seed
+      new Error("network blip"), // tick 2: transient failure
+      [snapshot({ job_id: "job-a", status: "running" })], // tick 3: unchanged
+      [snapshot({ job_id: "job-a", status: "completed" })], // tick 4: the only real change
+    ]);
+    const iter = pollingJobEvents(transport);
+    const nextPromise = iter.next();
+
+    // if the failed tick wiped `prev`, job-a would look "new" again on
+    // tick 3 (an unchanged snapshot) and this promise would already have
+    // resolved with a spurious `from: null` event after just 2 advances.
+    await advanceTicks(3);
+    const result = await nextPromise;
+
+    expect(result.value).toMatchObject({
+      kind: "status_changed",
+      job_id: "job-a",
+      from: "running",
+      to: "completed",
+    });
+  });
+
+  it("a disappearing job_id is silently dropped, not yielded", async () => {
+    const transport = fakeTransport([
+      [snapshot({ job_id: "job-a", status: "completed" })],
+      [], // job-a no longer present
+      [snapshot({ job_id: "job-b", status: "running" })],
+    ]);
+    const iter = pollingJobEvents(transport);
+    const nextPromise = iter.next();
+
+    await advanceTicks(2);
+    const result = await nextPromise;
+
+    // the only event ever produced is job-b appearing - job-a's
+    // disappearance after tick 2 produced nothing.
+    expect(result.value).toMatchObject({
+      kind: "status_changed",
+      job_id: "job-b",
+      from: null,
+      to: "running",
+    });
+  });
+
+  it("stops promptly when the abort signal fires", async () => {
+    const controller = new AbortController();
+    const transport = fakeTransport([[snapshot({ job_id: "job-a", status: "running" })]]);
+    const iter = pollingJobEvents(transport, undefined, controller.signal);
+
+    const nextPromise = iter.next();
+    controller.abort();
+    await advanceTicks(1);
+    const result = await nextPromise;
+
+    expect(result.done).toBe(true);
+  });
+});