fix: add correct amb filter types (#134)

Author: JannikStreek

AGENTS.md

@@ -64,7 +64,7 @@ All adapters implement `SourceAdapter` from `oer-adapter-core` and normalize res
 | `NODE_ENV` | `development` | `development`, `production`, `test` |
 | `ENABLED_ADAPTERS` | `''` | Comma-separated adapter IDs |
 | `ADAPTER_TIMEOUT_MS` | `3000` | Per-adapter request timeout |
-| `NOSTR_AMB_RELAY_URL` | `''` | WebSocket URL for AMB relay |
+| `NOSTR_AMB_RELAY_URL` | `''` | Comma-separated WebSocket URL(s) for AMB relay(s) |
 | `RPI_VIRTUELL_API_URL` | `''` | Optional override for RPI-Virtuell |
 | `IMGPROXY_BASE_URL` | `''` | Enables imgproxy when set |
 | `IMGPROXY_KEY` | `''` | Hex key for signed URLs |

docs/client-packages.md

@@ -460,7 +460,7 @@ interface SourceConfig {
 
 | Source ID | Description | `baseUrl` |
 |-----------|-------------|-----------|
-| `nostr-amb-relay` | Nostr AMB Relay | Required (e.g., `'wss://amb-relay.edufeed.org'`) |
+| `nostr-amb-relay` | Nostr AMB Relay | Required. WebSocket URL(s) — supports comma-separated values for multiple relays (e.g., `'wss://relay1.example.com, wss://relay2.example.com'`) |
 | `openverse` | Openverse | Not needed |
 | `arasaac` | ARASAAC | Not needed |
 | `wikimedia` | Wikimedia Commons | Not needed |
@@ -515,6 +515,34 @@ searchElement.sources = [
 ];
 ```
 
+#### Nostr AMB Relay Adapter
+
+The `nostr-amb-relay` adapter connects to one or more [AMB relay](https://github.com/edufeed-org/amb-relay) instances via WebSocket to search educational metadata using the Nostr protocol (kind 30142 events).
+
+**Key features:**
+- Fan-out queries to multiple relays concurrently with result merging and deduplication
+- Supports all resource types, license filtering, and educational level filtering
+- Uses `learningResourceType` (HCRT vocabulary) for type filtering
+
+**Configuration:** Set `baseUrl` in the `SourceConfig` to one or more WebSocket URLs. For multiple relays, separate URLs with commas:
+
+```javascript
+// Single relay
+{ id: 'nostr-amb-relay', label: 'AMB Relay', baseUrl: 'wss://amb-relay.edufeed.org' }
+
+// Multiple relays (fan-out: queries all relays, merges and deduplicates results)
+{ id: 'nostr-amb-relay', label: 'AMB Relay', baseUrl: 'wss://relay1.example.com, wss://relay2.example.com' }
+```
+
+In direct client mode, you must register the adapter before the first search:
+
+```javascript
+import { registerNostrAmbRelayAdapter } from '@edufeed-org/oer-finder-plugin/adapter/nostr-amb-relay';
+registerNostrAmbRelayAdapter();
+```
+
+In server-proxy mode, relay URLs are configured server-side via the `NOSTR_AMB_RELAY_URL` environment variable (also comma-separated for multiple relays) — no adapter registration is needed on the client.
+
 ### Advanced Features
 
 #### Customizing Page Size

nak-data/publish-demo-events.sh

@@ -66,7 +66,7 @@ for i in $(seq 1 2); do
     -t "d=https://example.edu/images/photosynthesis${i}.png" \
     -t "e=${KIND_1063_EVENT_ID};${RELAY_URL};" \
     -t "type=LearningResource" \
-    -t "type=Image" \
+    -t "type=ImageObject" \
     -t "name=Photosynthesis Process Diagram ${i}" \
     -t "description=Detailed diagram illustrating the photosynthesis process in plant cells" \
     -t "dateCreated=2025-01-15" \

packages/oer-adapter-nostr-amb-relay/src/nostr-amb-relay.adapter.ts

@@ -23,13 +23,62 @@ import { mapNostrAmbEventToExternalOerItem } from './mappers/nostr-amb-to-extern
 /** Default timeout for relay requests */
 const DEFAULT_TIMEOUT_MS = 10000;
 
+/** Maximum number of relay URLs allowed to prevent resource exhaustion */
+const MAX_RELAY_COUNT = 10;
+
+/**
+ * Maps UI resource types to HCRT (Hochschulcurriculare Ressourcentypen) vocabulary entries.
+ *
+ * The relay groups filter tokens by base field name (before the first dot) and
+ * OR's values within the same group. Using `learningResourceType.id` and
+ * `learningResourceType.prefLabel.en` ensures they share the `learningResourceType`
+ * group and are OR'd together, matching resources tagged with either the HCRT URI
+ * or the English label.
+ *
+ * @see https://w3id.org/kim/hcrt/scheme
+ */
+interface TypeFilterTokens {
+  readonly hcrtId: string;
+  readonly hcrtPrefLabelEn: string;
+}
+
+const TYPE_FILTER_CONFIG: Readonly<Record<string, TypeFilterTokens>> = {
+  image: {
+    hcrtId: 'https://w3id.org/kim/hcrt/image',
+    hcrtPrefLabelEn: 'Image',
+  },
+  video: {
+    hcrtId: 'https://w3id.org/kim/hcrt/video',
+    hcrtPrefLabelEn: 'Video',
+  },
+  audio: {
+    hcrtId: 'https://w3id.org/kim/hcrt/audio',
+    hcrtPrefLabelEn: 'Audio',
+  },
+  text: {
+    hcrtId: 'https://w3id.org/kim/hcrt/text',
+    hcrtPrefLabelEn: 'Text',
+  },
+  'application/pdf': {
+    hcrtId: 'https://w3id.org/kim/hcrt/text',
+    hcrtPrefLabelEn: 'Text',
+  },
+};
+
+interface RelayQueryResults {
+  readonly events: readonly Event[];
+  readonly errors: readonly Error[];
+}
+
 /**
  * Nostr AMB Relay adapter for searching educational metadata.
  *
  * The amb-relay is a specialized search relay for educational metadata
  * built on the AMB (Allgemeines Metadatenprofil für Bildungsressourcen) standard.
  * It combines Typesense full-text search with the Nostr protocol.
  *
+ * Supports multiple relay URLs for fan-out queries with result merging and deduplication.
+ *
  * @see https://github.com/edufeed-org/amb-relay
  */
 export class NostrAmbRelayAdapter implements SourceAdapter {
@@ -41,26 +90,36 @@ export class NostrAmbRelayAdapter implements SourceAdapter {
     supportsEducationalLevelFilter: true,
   };
 
-  private readonly relayUrl: string;
+  private readonly relayUrls: readonly string[];
   private readonly timeoutMs: number;
 
   constructor(config: NostrAmbRelayConfig) {
-    this.relayUrl = config.relayUrl;
+    if (config.relayUrls.length === 0) {
+      throw new Error('At least one relay URL must be provided');
+    }
+    if (config.relayUrls.length > MAX_RELAY_COUNT) {
+      throw new Error(
+        `Too many relay URLs (${config.relayUrls.length}). Maximum is ${MAX_RELAY_COUNT}.`,
+      );
+    }
+    const validatedUrls = config.relayUrls.map((url) => {
+      if (!url.startsWith('ws://') && !url.startsWith('wss://')) {
+        throw new Error(
+          `Invalid relay URL scheme: ${url}. Must use ws:// or wss://`,
+        );
+      }
+      return url;
+    });
+    this.relayUrls = validatedUrls;
     this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
 
   /**
    * Search for educational resources matching the query.
    *
-   * The amb-relay supports full-text search through the Nostr protocol
-   * using the 'search' filter parameter.
-   *
-   * Supported filters:
-   * - search: Full-text search across all AMB metadata fields
-   * - limit: Number of results to return (maps to pageSize)
-   *
-   * Field-specific queries can be performed using the format:
-   * "field.subfield:value" (e.g., "publisher.name:example")
+   * Fans out to all configured relays concurrently. Results are merged and
+   * deduplicated by event ID. Partial results are returned if some relays fail;
+   * an error is thrown only when all relays fail.
    */
   async search(
     query: AdapterSearchQuery,
@@ -70,28 +129,46 @@ export class NostrAmbRelayAdapter implements SourceAdapter {
       return EMPTY_RESULT;
     }
 
-    let relay: Relay | null = null;
+    const filter = this.buildFilter(query);
+    const { events, errors } = await this.queryAllRelays(
+      filter,
+      options?.signal,
+    );
 
-    try {
-      relay = await Relay.connect(this.relayUrl);
+    if (events.length === 0 && errors.length > 0) {
+      throw this.wrapError(errors[0]);
+    }
 
-      const filter = this.buildFilter(query);
-      const events = await this.subscribeToEvents(
-        relay,
-        filter,
-        options?.signal,
-      );
-      const items = this.mapEventsToItems(events);
-      const paginatedItems = paginateItems(items, query.page, query.pageSize);
+    const deduplicatedEvents = deduplicateEvents(events);
+    const items = this.mapEventsToItems(deduplicatedEvents);
+    const paginatedItems = paginateItems(items, query.page, query.pageSize);
 
-      return {
-        items: paginatedItems,
-        total: events.length,
-      };
-    } catch (error) {
-      throw this.wrapError(error);
+    return {
+      items: paginatedItems,
+      total: deduplicatedEvents.length,
+    };
+  }
+
+  private async queryAllRelays(
+    filter: Filter,
+    signal?: AbortSignal,
+  ): Promise<RelayQueryResults> {
+    const settled = await Promise.allSettled(
+      this.relayUrls.map((url) => this.queryRelay(url, filter, signal)),
+    );
+    return collectResults(settled);
+  }
+
+  private async queryRelay(
+    url: string,
+    filter: Filter,
+    signal?: AbortSignal,
+  ): Promise<Event[]> {
+    const relay = await Relay.connect(url);
+    try {
+      return await this.subscribeToEvents(relay, filter, signal);
     } finally {
-      relay?.close();
+      relay.close();
     }
   }
 
@@ -102,9 +179,7 @@ export class NostrAmbRelayAdapter implements SourceAdapter {
    * and converts them to Typesense filter_by expressions. This allows
    * filtering by language, license, and type without protocol-level changes.
    */
-  private buildFilter(
-    query: AdapterSearchQuery,
-  ): Filter & { search?: string } {
+  private buildFilter(query: AdapterSearchQuery): Filter & { search?: string } {
     const searchParts: string[] = [query.keywords?.trim() ?? ''];
 
     if (query.language) {
@@ -116,7 +191,13 @@ export class NostrAmbRelayAdapter implements SourceAdapter {
     }
 
     if (query.type) {
-      searchParts.push(`type:${query.type}`);
+      const config = TYPE_FILTER_CONFIG[query.type];
+      if (config) {
+        searchParts.push(`learningResourceType.id:${config.hcrtId}`);
+        searchParts.push(
+          `learningResourceType.prefLabel.en:${config.hcrtPrefLabelEn}`,
+        );
+      }
     }
 
     if (query.educationalLevel) {
@@ -138,22 +219,33 @@ export class NostrAmbRelayAdapter implements SourceAdapter {
     const events: Event[] = [];
 
     await new Promise<void>((resolve, reject) => {
+      let sub: { close: () => void } | undefined;
+
+      const cleanup = () => {
+        sub?.close();
+      };
+
       const timeoutId = setTimeout(() => {
+        cleanup();
         reject(new Error(`Relay request timed out after ${this.timeoutMs}ms`));
       }, this.timeoutMs);
 
-      signal?.addEventListener('abort', () => {
+      const onAbort = () => {
         clearTimeout(timeoutId);
+        cleanup();
         reject(new Error('Request aborted'));
-      });
+      };
+
+      signal?.addEventListener('abort', onAbort, { once: true });
 
-      const sub = relay.subscribe([filter], {
+      sub = relay.subscribe([filter], {
         onevent: (event: Event) => {
           events.push(event);
         },
         oneose: () => {
           clearTimeout(timeoutId);
-          sub.close();
+          signal?.removeEventListener('abort', onAbort);
+          sub?.close();
           resolve();
         },
       });
@@ -183,6 +275,35 @@ export class NostrAmbRelayAdapter implements SourceAdapter {
   }
 }
 
+function deduplicateEvents(events: readonly Event[]): Event[] {
+  return Array.from(
+    events
+      .reduce(
+        (seen, event) => (seen.has(event.id) ? seen : seen.set(event.id, event)),
+        new Map<string, Event>(),
+      )
+      .values(),
+  );
+}
+
+function collectResults(
+  settled: readonly PromiseSettledResult<Event[]>[],
+): RelayQueryResults {
+  const fulfilled = settled.filter(
+    (r): r is PromiseFulfilledResult<Event[]> => r.status === 'fulfilled',
+  );
+  const rejected = settled.filter(
+    (r): r is PromiseRejectedResult => r.status === 'rejected',
+  );
+
+  return {
+    events: fulfilled.flatMap((r) => r.value),
+    errors: rejected.map((r) =>
+      r.reason instanceof Error ? r.reason : new Error(String(r.reason)),
+    ),
+  };
+}
+
 /**
  * Factory function to create a NostrAmbRelayAdapter.
  *

packages/oer-adapter-nostr-amb-relay/src/nostr-amb-relay.types.ts

@@ -52,8 +52,8 @@ export function parseNostrAmbEvent(data: unknown): NostrAmbEvent {
  * Configuration options for the Nostr AMB Relay adapter
  */
 export interface NostrAmbRelayConfig {
-  /** WebSocket URL of the amb-relay (e.g., 'wss://relay.example.com') */
-  relayUrl: string;
+  /** WebSocket URLs of the amb-relay(s) — supports multiple relays for fan-out queries */
+  relayUrls: readonly string[];
   /** Timeout for relay requests in milliseconds (default: 10000) */
   timeoutMs?: number;
 }

packages/oer-adapter-nostr-amb-relay/src/utils/tag-parser.util.ts

@@ -9,10 +9,7 @@
  */
 
 /** Checks whether a value already exists at a nested path. */
-function hasNestedValue(
-  obj: Record<string, unknown>,
-  path: string[],
-): boolean {
+function hasNestedValue(obj: Record<string, unknown>, path: string[]): boolean {
   let current: unknown = obj;
   for (const segment of path) {
     if (typeof current !== 'object' || current === null) return false;