search.service.ts

search.service.tsapps/api/src/modules/search/search.service.tsraw ← search23,807 B← Back to the app
1/**
2 * Search service — TASK-0097 S3.
3 *
4 * The API's search module is now a thin, permission-scoped facade over the
5 * single tested core, `@factory/search` (`SearchClient`): one index (alias
6 * `factory-content`), one query shape, one permission filter. The Phase-0
7 * hand-rolled 3-index client (`opensearch.ts`) and its Postgres-ILIKE
8 * fallback are GONE (recorded decision, phase-08-search.md "Phase 8 Notes":
9 * no Postgres-ILIKE fallback — OpenSearch down ⇒ 503 `SEARCH_UNAVAILABLE`).
10 *
11 * Security model (TASK-0097 §5 + Security): every query runs a FAIL-CLOSED
12 * caller-scope resolver (userId → `ViewerContext { userId, workspaceIds,
13 * teamIds }`) and the tenant clause is mandatory — the client never runs an
14 * unfiltered query:
15 *   - explicit `workspaceId` the caller is NOT a member of → 404 NOT_FOUND
16 *     (no existence leak; consistent with the pages API),
17 *   - "all workspaces" with zero memberships → empty result set (no query).
18 *
19 * Response shapes (TASK-0097 S3, recorded — the live web client pins these):
20 *   - POST /search          → envelope { data, nextCursor, tookMs }
21 *   - GET  /search/query    → BARE array of results (command palette client)
22 *   - GET  /search/suggest  → BARE array of { id, type, title } (the old
23 *     `{ data: string[] }` shape already mismatched the web typing; pinned
24 *     to objects the suggest UI needs)
25 *   - GET/PUT/DELETE /search/recent → { data: string[] } (Redis-backed, kept
26 *     as-is: key `search:recent:{userId}`, cap 20, newest first)
27 */
28import { createHash } from "node:crypto";
29import { Inject, Injectable } from "@nestjs/common";
30import { z } from "zod";
31// `SearchClient` is a VALUE here (the service constructs it lazily from
32// env); `SearchType`/`ViewerContext` are types. Root import only — the API
33// resolves under node10 (no subpaths), and the root re-exports the client.
34import { SearchClient, type SearchSort, type SearchType, type ViewerContext } from "@factory/search";
35import { m } from "@factory/observability";
36import { loadEnv } from "../../config/env.js";
37import { ActorContext } from "../../common/actor-context.js";
38import { ApiError } from "../../common/errors.js";
39import { logger } from "../../common/logger.js";
40import { PrismaService } from "../../common/prisma.service.js";
41import { RedisService } from "../../common/redis.service.js";
42import { CacheService } from "../../common/cache.js";
43 
44const RECENT_KEY = (userId: string) => `search:recent:${userId}`;
45const RECENT_MAX = 20;
46/** TASK-0097 §7: structured log per request — never more than this of the raw query. */
47const LOG_QUERY_PREFIX_CHARS = 64;
48/** TASK-0098 §5: per-user rate limit on recent-search writes (30/min). */
49const RECENT_WRITE_LIMIT = 30;
50const RECENT_WRITE_WINDOW_MS = 60_000;
51/** Suggest page size (the client defaults to 8; keep the server cap small). */
52const SUGGEST_DEFAULT_SIZE = 8;
53/** Suggest server cap (buildPrefixBody size guard). */
54const SUGGEST_MAX_SIZE = 20;
55 
56export interface SearchInput {
57  q: string;
58  types?: SearchType[];
59  workspaceId?: string;
60  teamId?: string;
61  createdBy?: string;
62  updatedAfter?: string;
63  updatedBefore?: string;
64  /** T-155: result ordering (undefined/"relevance" = the default `_score` path). */
65  sortBy?: SearchSort;
66  cursor?: string;
67  limit?: number;
68}
69 
70export interface SearchEnvelope {
71  data: import("@factory/search").SearchResult[];
72  nextCursor: string | null;
73  tookMs: number;
74}
75 
76export interface Suggestion {
77  id: string;
78  type: string;
79  title: string;
80}
81 
82/** The fail-closed caller scope (TASK-0097 Security). */
83interface CallerScope {
84  /** Every non-deleted workspace the user is a member of. */
85  workspaceIds: string[];
86  /** Team ids the user belongs to, within those workspaces. */
87  teamIds: string[];
88}
89 
90type SearchResult = import("@factory/search").SearchResult;
91 
92/**
93 * TASK-0135: search results are cached for 5 s, keyed by
94 * { workspaceId, query-hash, filters-hash, principalId } — permission
95 * relevant, so the principal is part of the key (two viewers never share an
96 * entry). The zod schema below matches the JSON shape of the LIVE envelope
97 * `{ data: SearchResult[], nextCursor, tookMs }` so a corrupt entry is a
98 * cache MISS, never a 500.
99 */
100const SEARCH_RESULT_CACHE = z.object({
101  docId: z.string(),
102  type: z.string(),
103  id: z.string(),
104  title: z.string(),
105  snippet: z.string().optional(),
106  url: z.string(),
107  icon: z.string().optional(),
108  createdByName: z.string().optional(),
109  updatedAt: z.string(),
110  pageId: z.string().optional(),
111  blockId: z.string().optional(),
112  databaseId: z.string().optional(),
113  recordId: z.string().optional(),
114  workspaceId: z.string(),
115  score: z.number(),
116  source: z.string()
117});
118const SEARCH_ENVELOPE_CACHE = z.object({
119  data: z.array(SEARCH_RESULT_CACHE),
120  nextCursor: z.string().nullable(),
121  tookMs: z.number()
122});
123 
124@Injectable()
125export class SearchService {
126  /**
127   * The single `SearchClient` for the module (TASK-0097: built lazily so
128   * unit tests can swap the instance via {@link setClientForTesting}).
129   */
130  private clientOverride: SearchClient | null = null;
131  private lazyClient: SearchClient | null = null;
132 
133  constructor(
134    @Inject(PrismaService) private readonly prisma: PrismaService,
135    @Inject(RedisService) private readonly redis: RedisService,
136    @Inject(CacheService) private readonly cache: CacheService,
137  ) {}
138 
139  /** Test seam: swap the client instance (a fake/fetch-backed `SearchClient`). */
140  setClientForTesting(client: SearchClient | null): void {
141    this.clientOverride = client;
142    this.lazyClient = null;
143  }
144 
145  private client(): SearchClient {
146    if (this.clientOverride) return this.clientOverride;
147    if (!this.lazyClient) {
148      const env = loadEnv();
149      this.lazyClient = new SearchClient({
150        baseUrl: env.SEARCH_URL,
151        ...(env.SEARCH_PASSWORD
152          ? { auth: { username: env.SEARCH_USERNAME, password: env.SEARCH_PASSWORD } }
153          : {}),
154      });
155    }
156    return this.lazyClient;
157  }
158 
159  /**
160   * TASK-0125 — public access to the underlying client for the AI RAG query
161   * path (it needs the raw client's `_mget` for full chunk context beyond the
162   * 160-char snippet the search API surfaces). The client is the SAME
163   * singleton the search API uses (config + test-override aware).
164   */
165  searchClient(): SearchClient {
166    return this.client();
167  }
168 
169  /**
170   * Resolve the caller's scope (fail-closed, TASK-0097 Security):
171   * workspaceIds = the user's non-deleted workspace memberships;
172   * teamIds = `teamMember` rows joined through `team.workspaceId IN workspaceIds`.
173   */
174  async resolveScope(userId: string): Promise<CallerScope> {
175    // TASK-0127: API keys are scoped to their OWN workspace (docs §7) —
176    // never the creator's memberships. The key sees the whole workspace
177    // (including team-scoped content — it acts as the workspace), so
178    // teamIds = ALL teams of that workspace (a `teamId` filter then works).
179    const actor = ActorContext.get();
180    if (actor?.kind === "api" && actor.workspaceId) {
181      const active = await this.filterActiveWorkspaces([actor.workspaceId]);
182      let teamIds: string[] = [];
183      if (active.length > 0) {
184        const teamRows = await this.prisma.team.findMany({
185          where: { workspaceId: actor.workspaceId },
186          select: { id: true },
187        });
188        teamIds = teamRows.map((t) => t.id);
189      }
190      return { workspaceIds: active, teamIds };
191    }
192    const members = await this.prisma.workspaceMember.findMany({
193      where: { userId },
194      select: { workspaceId: true },
195    });
196    const workspaceIds = await this.filterActiveWorkspaces(members.map((m) => m.workspaceId));
197    let teamIds: string[] = [];
198    if (workspaceIds.length > 0) {
199      const teamRows = await this.prisma.teamMember.findMany({
200        where: { userId, team: { workspaceId: { in: workspaceIds } } },
201        select: { teamId: true },
202      });
203      teamIds = [...new Set(teamRows.map((t) => t.teamId))];
204    }
205    return { workspaceIds, teamIds };
206  }
207 
208  /**
209   * TASK-0125 — public viewer resolution for the AI RAG query path (the RAG
210   * service lives in the AI module; it must not reach into the search
211   * service's private plumbing). Same fail-closed rules as the search API:
212   * non-member workspace → 404; zero memberships → null (empty result, no
213   * query sent).
214   */
215  async viewerForWorkspace(userId: string, workspaceId: string): Promise<ViewerContext | null> {
216    const scope = await this.resolveScope(userId);
217    return this.viewerFor(userId, scope, workspaceId);
218  }
219 
220  /** Drop workspaces that no longer exist (deleted rows) — non-member ≠ member. */
221  private async filterActiveWorkspaces(ids: string[]): Promise<string[]> {
222    if (ids.length === 0) return [];
223    const rows = await this.prisma.workspace.findMany({
224      where: { id: { in: ids }, deletedAt: null },
225      select: { id: true },
226    });
227    return rows.map((w) => w.id);
228  }
229 
230  /**
231   * The viewer context for a request, enforcing the fail-closed rules:
232   *   - explicit `workspaceId` + not a member → 404 NOT_FOUND (no leak),
233   *   - no `workspaceId` + zero memberships  → null (caller returns empty;
234   *     the query is never sent — "nothing the caller can see").
235   */
236  private async viewerFor(
237    userId: string,
238    scope: CallerScope,
239    workspaceId?: string,
240  ): Promise<ViewerContext | null> {
241    const actor = ActorContext.get();
242    const isKey = actor?.kind === "api";
243    let workspaceIds: string[];
244    if (isKey) {
245      // TASK-0127: a key can ONLY search its own workspace, explicitly.
246      // No `workspaceId` (or a different one) → 404, never a cross-tenant
247      // query over "all of the key's workspaces" (the key has exactly one).
248      if (!workspaceId || workspaceId !== actor.workspaceId) {
249        throw ApiError.notFound("Resource not found.");
250      }
251      workspaceIds = [workspaceId];
252    } else if (workspaceId) {
253      if (!scope.workspaceIds.includes(workspaceId)) {
254        // 404 (NOT 403): consistent with the pages API; a workspace the
255        // caller is not a member of simply does not exist for them.
256        throw ApiError.notFound("Resource not found.");
257      }
258      workspaceIds = [workspaceId];
259    } else {
260      workspaceIds = scope.workspaceIds;
261      if (workspaceIds.length === 0) return null;
262    }
263    // TASK-0127: for a key the viewer identity is SYNTHETIC — a real user
264    // id (the creator's) in `grants.users` would surface the creator's
265    // personal grants. The key acts as the workspace: the
266    // `grants.workspace` + team clauses (all workspace teams) are its access.
267    return {
268      userId: isKey ? `apikey-${actor!.apiKeyId ?? "unknown"}` : userId,
269      workspaceIds,
270      teamIds: scope.teamIds,
271    };
272  }
273 
274  /**
275   * Full-text search (POST /search). TASK-0135: the result envelope is
276   * cached for 5 s, keyed by { workspaceId, query-hash, filters-hash,
277   * principalId } — permission relevant, so the principal (userId) is part of
278   * the key and two viewers never share an entry. On a cache hit the scope +
279   * viewer + OpenSearch round-trip are skipped entirely.
280   */
281  async search(userId: string, input: SearchInput): Promise<SearchEnvelope> {
282    const cacheKeyInput = {
283      q: input.q.trim(),
284      types: input.types,
285      workspaceId: input.workspaceId,
286      teamId: input.teamId,
287      createdBy: input.createdBy,
288      updatedAfter: input.updatedAfter,
289      updatedBefore: input.updatedBefore,
290      // T-155: a different ordering is a different result — part of the key so
291      // a sortBy=createdAt query never returns a cached relevance envelope.
292      sortBy: input.sortBy,
293      cursor: input.cursor,
294      limit: input.limit
295    };
296    const { data } = await this.cache.getSearch(
297      input.workspaceId,
298      userId,
299      cacheKeyInput,
300      () => this.searchLive(userId, input),
301      SEARCH_ENVELOPE_CACHE
302    );
303    return data as SearchEnvelope;
304  }
305 
306  /** The live (un-cached) search — the loader the 5 s cache calls. */
307  private async searchLive(userId: string, input: SearchInput): Promise<SearchEnvelope> {
308    const q = input.q.trim();
309    const scope = await this.resolveScope(userId);
310    const viewer = await this.viewerFor(userId, scope, input.workspaceId);
311    if (!viewer) {
312      // Fail-closed: zero visible workspaces → nothing can match. No query sent.
313      this.logSearch(userId, { q, types: input.types, workspaceId: input.workspaceId }, 0, 0);
314      return { data: [], nextCursor: null, tookMs: 0 };
315    }
316 
317    // Clamp OUTSIDE tryClient: an out-of-range `limit` must surface as
318    // 400 VALIDATION_ERROR, not 503 — tryClient's catch maps ANY non-
319    // SEARCH_UNAVAILABLE throw to 503 SEARCH_UNAVAILABLE (mapSharedError),
320    // which would swallow the 400 (recorded S3 contract, UI depends on it).
321    const pageSize = clampLimit(input.limit);
322    const started = Date.now();
323    const res = await this.tryClient(() =>
324      this.client().search(
325        {
326          q,
327          ...(input.types && input.types.length > 0 ? { types: input.types } : {}),
328          // T-155: additive date sort — undefined/"relevance" keeps the default.
329          ...(input.sortBy && input.sortBy !== "relevance" ? { sortBy: input.sortBy } : {}),
330          filters: {
331            ...(input.teamId ? { teams: [input.teamId] } : {}),
332            ...(input.createdBy ? { createdBy: input.createdBy } : {}),
333            ...(input.updatedAfter ? { updatedAfter: input.updatedAfter } : {}),
334            ...(input.updatedBefore ? { updatedBefore: input.updatedBefore } : {}),
335          },
336          page: input.cursor,
337          pageSize,
338        },
339        viewer,
340      ),
341    );
342    const tookMs = Date.now() - started;
343    // TASK-0135: the spec's search_query_duration_seconds (type bm25 — the
344    // live engine is BM25; kNN would be a second call site when/if hybrid
345    // lands). The cache-HIT path (search()) never reaches here — cached
346    // results are not "search queries" for the duration catalog.
347    m.search.record({ type: "bm25" }, tookMs / 1000);
348    this.logSearch(
349      userId,
350      { q, types: input.types, workspaceId: input.workspaceId },
351      res.total,
352      tookMs,
353    );
354    return { data: res.results, nextCursor: res.cursor ?? null, tookMs };
355  }
356 
357  /**
358   * Command-palette query (GET /search/query): same engine, BARE array
359   * response (the web client types it `Promise<SearchResult[]>` and does
360   * `searchApi.query(...).then(setResults)` — a record shape would break the
361   * palette; envelope-vs-array is the recorded S3 decision).
362   */
363  async query(userId: string, input: SearchInput): Promise<SearchResult[]> {
364    const q = input.q.trim();
365    const scope = await this.resolveScope(userId);
366    const viewer = await this.viewerFor(userId, scope, input.workspaceId);
367    if (!viewer) return [];
368 
369    // Clamp outside tryClient (400 VALIDATION_ERROR, not 503 — see search()).
370    const pageSize = clampLimit(input.limit);
371    const res = await this.tryClient(() =>
372      this.client().search(
373        {
374          q,
375          ...(input.types && input.types.length > 0 ? { types: input.types } : {}),
376          // T-155: additive date sort — undefined/"relevance" keeps the default.
377          ...(input.sortBy && input.sortBy !== "relevance" ? { sortBy: input.sortBy } : {}),
378          filters: {
379            ...(input.teamId ? { teams: [input.teamId] } : {}),
380            ...(input.createdBy ? { createdBy: input.createdBy } : {}),
381            ...(input.updatedAfter ? { updatedAfter: input.updatedAfter } : {}),
382            ...(input.updatedBefore ? { updatedBefore: input.updatedBefore } : {}),
383          },
384          page: input.cursor,
385          pageSize,
386        },
387        viewer,
388      ),
389    );
390    // TASK-0135: search_query_duration_seconds — the command-palette path
391    // (GET /search/query) is the same BM25 engine.
392    m.search.record({ type: "bm25" }, res.latencyMs / 1000);
393    this.logSearch(
394      userId,
395      { q, types: input.types, workspaceId: input.workspaceId },
396      res.total,
397      res.latencyMs,
398    );
399    return res.results;
400  }
401 
402  /**
403   * Suggestions (GET /search/suggest): prefix match via the client's
404   * `suggest()` (`buildPrefixBody` over the SAME permission filters). BARE
405   * array of `{ id, type, title }` (recorded S3 decision: the old
406   * `{ data: string[] }` mismatched the web typing `SearchResult[]`;
407   * objects are what the suggest UI needs).
408   */
409  async suggest(userId: string, q: string, limit?: number): Promise<Suggestion[]> {
410    const scope = await this.resolveScope(userId);
411    const viewer = await this.viewerFor(userId, scope);
412    if (!viewer) return [];
413    // Clamp outside tryClient (400 VALIDATION_ERROR, not 503 — see search()).
414    const size = clampSuggest(limit);
415    const started = Date.now();
416    const items = await this.tryClient(() => this.client().suggest(q, viewer, size));
417    this.logSearch(userId, { q, suggest: true }, items.length, Date.now() - started);
418    return items;
419  }
420 
421  /** Run a client call, mapping the shared `ApiError` (see mapSharedError). */
422  private async tryClient<T>(fn: () => Promise<T>): Promise<T> {
423    try {
424      return await fn();
425    } catch (err) {
426      this.mapSharedError(err);
427    }
428  }
429 
430  /**
431   * Map the SHARED `@factory/shared/errors` ApiError thrown by `SearchClient`
432   * onto the API-local `ApiError` the global exception filter understands.
433   *
434   * WHY: the filter's `instanceof ApiError` check is against the API-LOCAL
435   * class (common/errors.ts); the shared class is a DIFFERENT class, so an
436   * unmapped shared error would fall through every structural check to the
437   * 500 INTERNAL_ERROR catch-all. The shared `SEARCH_UNAVAILABLE` (503)
438   * therefore becomes the API-local `ApiError("SEARCH_UNAVAILABLE", 503, …)`
439   * with a GENERIC message — backend details (host, path, upstream status)
440   * are logged here and never returned (TASK-0097 §8: "do not leak
441   * backend details").
442   */
443  private mapSharedError(err: unknown): never {
444    const code: unknown = (err as { code?: unknown })?.code;
445    const status: unknown = (err as { status?: unknown })?.status;
446    const msg = err instanceof Error ? err.message : "search request failed";
447    if (code === "SEARCH_UNAVAILABLE") {
448      logger.warn("opensearch unavailable", { code, status, message: msg });
449      throw new ApiError(
450        "SEARCH_UNAVAILABLE",
451        typeof status === "number" ? status : 503,
452        "Search is temporarily unavailable.",
453      );
454    }
455    // Unknown shared error codes (e.g. AI_ERROR from a mis-configured hybrid)
456    // and non-ApiError throws (should not happen): 503 keeps the contract
457    // "search down ⇒ 503 SEARCH_UNAVAILABLE" (TASK-0097 §8).
458    logger.warn("search backend error", {
459      code: code ?? null,
460      status: status ?? null,
461      message: msg,
462    });
463    throw new ApiError("SEARCH_UNAVAILABLE", 503, "Search is temporarily unavailable.");
464  }
465 
466  /** TASK-0097 §7 structured log: types, tookMs, total + query hash. */
467  private logSearch(
468    userId: string,
469    meta: { q: string; types?: SearchType[]; workspaceId?: string; suggest?: boolean },
470    total: number,
471    tookMs: number,
472  ): void {
473    // Never more than 64 raw chars in the log; the rest is a hash.
474    const prefix = meta.q.slice(0, LOG_QUERY_PREFIX_CHARS);
475    const hash = createHash("sha256").update(meta.q, "utf8").digest("hex").slice(0, 16);
476    logger.info(meta.suggest ? "search:suggest" : "search:query", {
477      userId,
478      types: meta.types ?? null,
479      workspaceId: meta.workspaceId ?? null,
480      tookMs,
481      total,
482      queryPrefix: prefix,
483      queryHash: hash,
484    });
485  }
486 
487  // ---------------------------------------------------------------------
488  // Recent searches (Redis, kept as-is from the Phase-0 module: key
489  // `search:recent:{userId}`, cap 20, newest first). The e2e spec pins the
490  // `search-recent` / `search-recent-item` UI testids against these routes.
491  // ---------------------------------------------------------------------
492 
493  /** Record a query (dedupe: lrem + lpush, cap 20, newest first). Best-effort. */
494  async trackRecent(userId: string, q: string): Promise<void> {
495    try {
496      const key = RECENT_KEY(userId);
497      const redis = this.redis.getRedis();
498      await redis.lrem(key, 1, q);
499      await redis.lpush(key, q);
500      await redis.ltrim(key, 0, RECENT_MAX - 1);
501    } catch (err) {
502      logger.warn(`recent-search tracking failed: ${(err as Error).message}`);
503    }
504  }
505 
506  async recent(userId: string): Promise<{ data: string[] }> {
507    try {
508      const items = await this.redis.getRedis().lrange(RECENT_KEY(userId), 0, RECENT_MAX - 1);
509      return { data: items };
510    } catch {
511      return { data: [] };
512    }
513  }
514 
515  /**
516   * PUT /search/recent (TASK-0098 §5, recorded in docs/api/search.md):
517   * upsert a query into the user's list (dedupe, cap 20, newest first) and
518   * return the updated list. Reuses `trackRecent` (same Redis list); the
519   * 30/min per-user write rate limit (TASK-0098 §5) is a small inline
520   * sliding window on the SAME Redis — no new infra (recorded S3 decision:
521   * the global RateLimitGuard is per-route-class, not per-action, and
522   * building dedicated infra is out of scope for this slice).
523   */
524  async addRecent(userId: string, q: string): Promise<{ data: string[] }> {
525    const raw = q.trim();
526    if (raw.length === 0)
527      throw ApiError.validation("q is required.", [{ field: "q", issue: "required" }]);
528    await this.enforceRecentWriteLimit(userId);
529    await this.trackRecent(userId, raw);
530    return this.recent(userId);
531  }
532 
533  private async enforceRecentWriteLimit(userId: string): Promise<void> {
534    try {
535      const key = `search:recent:rl:${userId}`;
536      const now = Date.now();
537      const pipe = this.redis.getRedis().pipeline();
538      pipe.zremrangebyscore(key, 0, now - RECENT_WRITE_WINDOW_MS);
539      pipe.zadd(key, now, `${now}:${Math.random().toString(36).slice(2)}`);
540      pipe.zcard(key);
541      pipe.pexpire(key, RECENT_WRITE_WINDOW_MS);
542      const results = await pipe.exec();
543      const card = results?.[2]?.[1];
544      const count = typeof card === "number" ? card : 1;
545      if (count > RECENT_WRITE_LIMIT) {
546        throw new ApiError("RATE_LIMITED", 429, "Too many recent-search writes.", [
547          { retryAfterSeconds: Math.ceil(RECENT_WRITE_WINDOW_MS / 1000) },
548        ]);
549      }
550    } catch (err) {
551      // Degrade OPEN like the global guard (availability over strictness);
552      // a 429 thrown above is re-thrown as-is.
553      if (err instanceof ApiError) throw err;
554      logger.warn(
555        `recent-write rate limit degraded (redis unavailable): ${(err as Error).message}`,
556      );
557    }
558  }
559 
560  async clearRecent(userId: string): Promise<{ cleared: boolean }> {
561    try {
562      await this.redis.getRedis().del(RECENT_KEY(userId));
563      return { cleared: true };
564    } catch {
565      return { cleared: false };
566    }
567  }
568}
569 
570/** limit: 1..50 (TASK-0097 §2; LIMITS.MAX_SEARCH_LIMIT = 50), default 20. */
571function clampLimit(limit: number | undefined): number {
572  if (limit === undefined) return 20;
573  if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
574    throw ApiError.validation("limit must be an integer between 1 and 50.", [
575      { field: "limit", issue: "1..50", received: String(limit) },
576    ]);
577  }
578  return limit;
579}
580 
581function clampSuggest(limit: number | undefined): number {
582  if (limit === undefined) return SUGGEST_DEFAULT_SIZE;
583  if (!Number.isInteger(limit) || limit < 1) {
584    throw ApiError.validation("limit must be an integer between 1 and 20.", [
585      { field: "limit", issue: "1..20", received: String(limit) },
586    ]);
587  }
588  return Math.min(limit, SUGGEST_MAX_SIZE);
589}
590