@voltro/plugin-search 0.32.0 → 0.34.0

package/dist/rpc-BQBNr0OU.js

@@ -0,0 +1,61 @@
+import { Schema as e } from "effect";
+import { defineAction as t } from "@voltro/protocol";
+//#region src/errors.ts
+var n = class extends e.TaggedError()("SearchIndexNotFound", { index: e.String }) {}, r = class extends e.TaggedError()("SearchFieldRejected", {
+	field: e.String,
+	where: e.Literal("filter", "facet", "highlight"),
+	reason: e.Literal("not-an-identifier", "not-queryable")
+}) {}, i = e.Union(e.String, e.Number, e.Boolean), a = e.Struct({
+	field: e.String,
+	op: e.Literal("eq", "neq", "gt", "gte", "lt", "lte", "in", "nin"),
+	value: e.Union(i, e.Array(i))
+}), o = e.Struct({
+	fields: e.optional(e.Array(e.String)),
+	preTag: e.optional(e.String),
+	postTag: e.optional(e.String)
+}), s = e.Struct({
+	doc: e.Record({
+		key: e.String,
+		value: e.Unknown
+	}),
+	highlights: e.optional(e.Record({
+		key: e.String,
+		value: e.String
+	}))
+}), c = t({
+	name: "search.query",
+	input: e.Struct({
+		index: e.String,
+		q: e.String,
+		limit: e.optional(e.Number),
+		offset: e.optional(e.Number),
+		filters: e.optional(e.Array(a)),
+		facets: e.optional(e.Array(e.String)),
+		highlight: e.optional(o),
+		fuzziness: e.optional(e.Union(e.Number, e.Literal("auto"))),
+		engineParams: e.optional(e.Record({
+			key: e.String,
+			value: e.Unknown
+		}))
+	}),
+	output: e.Struct({
+		hits: e.Array(s),
+		facets: e.Record({
+			key: e.String,
+			value: e.Record({
+				key: e.String,
+				value: e.Number
+			})
+		})
+	}),
+	error: e.Union(n, r)
+}), l = [{
+	tag: "search.query",
+	kind: "action",
+	import: {
+		module: "@voltro/plugin-search/rpc",
+		name: "queryDescriptor"
+	}
+}];
+//#endregion
+export { n as a, r as i, c as n, l as r, a as t };

package/dist/rpc.d.ts

@@ -3,12 +3,19 @@ import { PluginRpcClientDescriptor } from '@voltro/protocol';
 import { Schema } from 'effect';
 
 export declare const queryDescriptor: ActionProcedureDescriptor<"search.query", Schema.Struct<{
+    /** One of the indexes the app declared. An unregistered name is refused
+     *  (`SearchIndexNotFound`) — it has no spec, so it has no tenant field to
+     *  scope by, and answering it would query an unscoped collection. */
     index: typeof Schema.String;
     q: typeof Schema.String;
     limit: Schema.optional<typeof Schema.Number>;
     offset: Schema.optional<typeof Schema.Number>;
     /** Clauses ANDed together — equality, range, negation, set membership. */
     filters: Schema.optional<Schema.Array$<Schema.Struct<{
+        /** A doc field path. Validated server-side against the index's declared
+         *  `queryableFields` (or a plain-identifier pattern) before it is spliced
+         *  into the engine's filter DSL — a mismatch is a typed
+         *  `SearchFieldRejected`, not a query. */
         field: typeof Schema.String;
         op: Schema.Literal<["eq", "neq", "gt", "gte", "lt", "lte", "in", "nin"]>;
         value: Schema.Union<[Schema.Union<[typeof Schema.String, typeof Schema.Number, typeof Schema.Boolean]>, Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number, typeof Schema.Boolean]>>]>;
@@ -23,7 +30,10 @@ export declare const queryDescriptor: ActionProcedureDescriptor<"search.query",
     }>>;
     /** Typo tolerance — a max edit distance (0 = exact) or `'auto'`. */
     fuzziness: Schema.optional<Schema.Union<[typeof Schema.Number, Schema.Literal<["auto"]>]>>;
-    /** Escape hatch — forwarded verbatim to the underlying engine's search call. */
+    /** Escape hatch — the engine's presentation-only params (paging, ordering,
+     *  typo tolerance, highlight shaping). Anything that could select a
+     *  different document set is dropped server-side and logged; express a
+     *  filter as a `filters[]` clause instead. */
     engineParams: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>, Schema.Struct<{
     hits: Schema.Array$<Schema.Struct<{
@@ -32,14 +42,60 @@ export declare const queryDescriptor: ActionProcedureDescriptor<"search.query",
     }>>;
     /** field → (value → count) for the requested facets. */
     facets: Schema.Record$<typeof Schema.String, Schema.Record$<typeof Schema.String, typeof Schema.Number>>;
-}>, typeof Schema.Never>;
+}>, Schema.Union<[typeof SearchIndexNotFound, typeof SearchFieldRejected]>>;
+
+/**
+ * A field name the caller supplied — in `filters[].field`, `facets[]` or
+ * `highlight.fields[]` — was refused before it could reach the engine.
+ *
+ * `reason: 'not-an-identifier'` — the name is not a plain field path
+ * (`^[A-Za-z_][A-Za-z0-9_.]*$`). Every vendor adapter interpolates the name
+ * into that engine's filter DSL, so anything else is a control-plane injection
+ * (a Typesense `filter_by` is ONE flat string with `||`, so a crafted name
+ * re-groups the boolean tree around the appended tenant clause).
+ *
+ * `reason: 'not-queryable'` — the name is well-formed but not in the index's
+ * declared `queryableFields` allowlist.
+ */
+declare class SearchFieldRejected extends SearchFieldRejected_base {
+}
+
+declare const SearchFieldRejected_base: Schema.TaggedErrorClass<SearchFieldRejected, "SearchFieldRejected", {
+    readonly _tag: Schema.tag<"SearchFieldRejected">;
+} & {
+    field: typeof Schema.String;
+    where: Schema.Literal<["filter", "facet", "highlight"]>;
+    reason: Schema.Literal<["not-an-identifier", "not-queryable"]>;
+}>;
 
 export declare const SearchFilterSchema: Schema.Struct<{
+    /** A doc field path. Validated server-side against the index's declared
+     *  `queryableFields` (or a plain-identifier pattern) before it is spliced
+     *  into the engine's filter DSL — a mismatch is a typed
+     *  `SearchFieldRejected`, not a query. */
     field: typeof Schema.String;
     op: Schema.Literal<["eq", "neq", "gt", "gte", "lt", "lte", "in", "nin"]>;
     value: Schema.Union<[Schema.Union<[typeof Schema.String, typeof Schema.Number, typeof Schema.Boolean]>, Schema.Array$<Schema.Union<[typeof Schema.String, typeof Schema.Number, typeof Schema.Boolean]>>]>;
 }>;
 
+/**
+ * The queried index is not one the app declared in `searchPlugin({ indexes })`.
+ *
+ * This is a REFUSAL, not an empty result, and the distinction is the whole
+ * point: an unknown index has no `IndexSpec`, therefore no `tenantField`,
+ * therefore no tenant clause — so answering it would run an unfiltered query
+ * against whatever collection of that name exists on the (usually shared)
+ * engine. Fail instead of querying something we cannot scope.
+ */
+declare class SearchIndexNotFound extends SearchIndexNotFound_base {
+}
+
+declare const SearchIndexNotFound_base: Schema.TaggedErrorClass<SearchIndexNotFound, "SearchIndexNotFound", {
+    readonly _tag: Schema.tag<"SearchIndexNotFound">;
+} & {
+    index: typeof Schema.String;
+}>;
+
 /** Declared for the codegen (`VoltroPlugin.rpcClientDescriptors`) so each tag is
  *  emitted into the generated client group. Kept in lockstep with the exports. */
 export declare const searchRpcClientImports: ReadonlyArray<PluginRpcClientDescriptor>;

package/dist/rpc.js

@@ -1,56 +1,2 @@
-import { Schema as e } from "effect";
-import { defineAction as t } from "@voltro/protocol";
-//#region src/rpc.ts
-var n = e.Union(e.String, e.Number, e.Boolean), r = e.Struct({
-	field: e.String,
-	op: e.Literal("eq", "neq", "gt", "gte", "lt", "lte", "in", "nin"),
-	value: e.Union(n, e.Array(n))
-}), i = e.Struct({
-	fields: e.optional(e.Array(e.String)),
-	preTag: e.optional(e.String),
-	postTag: e.optional(e.String)
-}), a = e.Struct({
-	doc: e.Record({
-		key: e.String,
-		value: e.Unknown
-	}),
-	highlights: e.optional(e.Record({
-		key: e.String,
-		value: e.String
-	}))
-}), o = t({
-	name: "search.query",
-	input: e.Struct({
-		index: e.String,
-		q: e.String,
-		limit: e.optional(e.Number),
-		offset: e.optional(e.Number),
-		filters: e.optional(e.Array(r)),
-		facets: e.optional(e.Array(e.String)),
-		highlight: e.optional(i),
-		fuzziness: e.optional(e.Union(e.Number, e.Literal("auto"))),
-		engineParams: e.optional(e.Record({
-			key: e.String,
-			value: e.Unknown
-		}))
-	}),
-	output: e.Struct({
-		hits: e.Array(a),
-		facets: e.Record({
-			key: e.String,
-			value: e.Record({
-				key: e.String,
-				value: e.Number
-			})
-		})
-	})
-}), s = [{
-	tag: "search.query",
-	kind: "action",
-	import: {
-		module: "@voltro/plugin-search/rpc",
-		name: "queryDescriptor"
-	}
-}];
-//#endregion
-export { r as SearchFilterSchema, o as queryDescriptor, s as searchRpcClientImports };
+import { n as e, r as t, t as n } from "./rpc-BQBNr0OU.js";
+export { n as SearchFilterSchema, e as queryDescriptor, t as searchRpcClientImports };

package/dist/web.d.ts

@@ -13,11 +13,14 @@ export declare interface SearchHitOut<Doc> {
 export declare interface SearchOptions {
     readonly limit?: number;
     readonly offset?: number;
-    /** Clauses ANDed together — equality, range, negation, set. */
+    /** Clauses ANDed together — equality, range, negation, set. Each `field` is
+     *  validated server-side (index allowlist, else a plain-identifier pattern);
+     *  a mismatch is a typed `SearchFieldRejected`. */
     readonly filters?: ReadonlyArray<SearchFilterInput>;
-    /** Facet-count fields (returned in `facets`). */
+    /** Facet-count fields (returned in `facets`). Validated like `filters[].field`. */
     readonly facets?: ReadonlyArray<string>;
-    /** Matched-term highlighting (returned per-hit). */
+    /** Matched-term highlighting (returned per-hit). `fields` is validated like
+     *  `filters[].field`. */
     readonly highlight?: {
         readonly fields?: ReadonlyArray<string>;
         readonly preTag?: string;
@@ -25,7 +28,10 @@ export declare interface SearchOptions {
     };
     /** Typo tolerance — a max edit distance (0 = exact) or `'auto'`. */
     readonly fuzziness?: number | 'auto';
-    /** Escape hatch — forwarded verbatim to the underlying engine. */
+    /** Escape hatch, narrowed to the engine's presentation-only params (paging,
+     *  ordering, typo tolerance, highlight shaping). Keys that could select a
+     *  different document set are dropped server-side — express a filter as a
+     *  `filters[]` clause, which is ANDed with the tenant scope. */
     readonly engineParams?: Record<string, unknown>;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/plugin-search",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "Keep an external search index (Typesense / Meilisearch / Algolia) in sync with framework tables via the post-commit ChangeEvent tap, then query it — tenant-scoped, with a backfill path and a useSearch() hook.",
   "keywords": [
     "voltro",
@@ -32,7 +32,8 @@
       "types": "./dist/rpc.d.ts",
       "import": "./dist/rpc.js",
       "default": "./dist/rpc.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -42,9 +43,9 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@voltro/client": "0.32.0",
-    "@voltro/database": "0.32.0",
-    "@voltro/protocol": "0.32.0"
+    "@voltro/client": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/protocol": "0.34.0"
   },
   "optionalDependencies": {
     "algoliasearch": "^5.56.0",