@byline/client 4.8.0 → 4.9.0

package/dist/collection-handle.d.ts

@@ -186,7 +186,7 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      */
     history<F = TFields>(documentId: string, options?: HistoryOptions): Promise<FindResult<F>>;
     /**
-     * Fetch the document-grain audit log for a single document (docs/06-auth-and-security/02-auditability.md —
+     * Fetch the document-grain audit log for a single document (docs/07-auth-and-security/02-auditability.md —
      * Workstream 3): the non-versioned system-field writes (path,
      * available-locales), in-place status transitions, and the deletion event
      * the immutable version stream deliberately does not record an actor for.

package/dist/collection-handle.js

@@ -8,7 +8,7 @@
 import { applyAfterRead, assertActorCanPerform, buildSearchDocument, changeDocumentStatus, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, ERR_VALIDATION, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
 import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
-import { finalizeSearchHits } from './search.js';
+import { assertSearchQueryLength, finalizeSearchHits } from './search.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -130,6 +130,7 @@ export class CollectionHandle {
      * Throws `ERR_VALIDATION` when no provider is registered.
      */
     async search(options) {
+        assertSearchQueryLength(options.query);
         const readMode = resolveReadMode(options.status);
         const readCtx = createReadContext();
         const requestContext = await this.resolveAndAssertRead(readMode, readCtx);
@@ -144,6 +145,7 @@ export class CollectionHandle {
         }
         const results = await provider.search({
             query: options.query,
+            matching: options.matching,
             collectionPath: this.definition.path,
             locale: options.locale ?? this.client.defaultLocale,
             status: readMode,
@@ -240,7 +242,7 @@ export class CollectionHandle {
         if (provider == null || this.definition.search == null)
             return result;
         // Clear the slice so deleted documents don't leave orphan rows.
-        await provider.reindex?.({ collectionPath: this.definition.path });
+        await provider.reindex({ collectionPath: this.definition.path });
         const pageSize = 100;
         let page = 1;
         for (;;) {
@@ -524,7 +526,7 @@ export class CollectionHandle {
         };
     }
     /**
-     * Fetch the document-grain audit log for a single document (docs/06-auth-and-security/02-auditability.md —
+     * Fetch the document-grain audit log for a single document (docs/07-auth-and-security/02-auditability.md —
      * Workstream 3): the non-versioned system-field writes (path,
      * available-locales), in-place status transitions, and the deletion event
      * the immutable version stream deliberately does not record an actor for.

package/dist/response.js

@@ -43,7 +43,7 @@ export function shapeDocument(raw) {
     // `created_by` / `event_type`).
     // `created_by` is NULL on rows written before audit wiring or by
     // internal tooling without a request context — omitted here, rendered as
-    // "unknown" by consumers. See docs/06-auth-and-security/02-auditability.md — Workstream 1.
+    // "unknown" by consumers. See docs/07-auth-and-security/02-auditability.md — Workstream 1.
     if (typeof raw.created_by === 'string') {
         shaped.createdBy = raw.created_by;
     }
@@ -55,7 +55,7 @@ export function shapeDocument(raw) {
     // Storage raw keys already match the surface names (passthrough) —
     // `availableLocales` is the editorial advertised set (document-grain,
     // stored), `_availableVersionLocales` is the structural ledger fact
-    // (version-grain, computed). See docs/07-internationalization/index.md.
+    // (version-grain, computed). See docs/08-internationalization/index.md.
     if (Array.isArray(raw.availableLocales)) {
         shaped.availableLocales = raw.availableLocales;
     }

package/dist/search.d.ts

@@ -58,3 +58,4 @@ export declare function finalizeSearchHits(params: FinalizeSearchHitsParams): Pr
  * ability error only when the actor can read none of the members.
  */
 export declare function zoneSearch(client: BylineClient<any>, options: ZoneSearchOptions): Promise<ClientSearchResults>;
+export declare function assertSearchQueryLength(query: string): void;

package/dist/search.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
+import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, MAX_SEARCH_QUERY_LENGTH, resolveItemViewColumns, resolveSearchZones, } from '@byline/core';
 import { resolveReadRequestContext, resolveReadSecurityFilters } from './read-context.js';
 /**
  * Authorise (and optionally hydrate) provider hits, per collection:
@@ -127,6 +127,7 @@ export async function finalizeSearchHits(params) {
  * ability error only when the actor can read none of the members.
  */
 export async function zoneSearch(client, options) {
+    assertSearchQueryLength(options.query);
     const provider = client.searchProvider;
     if (provider == null) {
         throw ERR_VALIDATION({
@@ -175,6 +176,7 @@ export async function zoneSearch(client, options) {
     }
     const results = await provider.search({
         query: options.query,
+        matching: options.matching,
         zone: options.zone,
         locale: options.locale ?? client.defaultLocale,
         status: readMode,
@@ -199,3 +201,14 @@ export async function zoneSearch(client, options) {
         ? { hits, total: hits.length }
         : { hits, total: results.total, facets: results.facets };
 }
+export function assertSearchQueryLength(query) {
+    if (query.length <= MAX_SEARCH_QUERY_LENGTH)
+        return;
+    throw ERR_VALIDATION({
+        message: `Search query exceeds the maximum length of ${MAX_SEARCH_QUERY_LENGTH} UTF-16 code units.`,
+        details: {
+            maximumLength: MAX_SEARCH_QUERY_LENGTH,
+            actualLength: query.length,
+        },
+    });
+}

package/dist/search.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/search.test.node.js

@@ -0,0 +1,22 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { MAX_SEARCH_QUERY_LENGTH } from '@byline/core';
+import { describe, expect, it } from 'vitest';
+import { assertSearchQueryLength } from './search.js';
+describe('search query validation', () => {
+    it('accepts the portable query limit and rejects longer input', () => {
+        expect(() => assertSearchQueryLength('a'.repeat(MAX_SEARCH_QUERY_LENGTH))).not.toThrow();
+        expect(() => assertSearchQueryLength('a'.repeat(MAX_SEARCH_QUERY_LENGTH + 1))).toThrowError(expect.objectContaining({
+            code: 'ERR_VALIDATION',
+            details: {
+                maximumLength: MAX_SEARCH_QUERY_LENGTH,
+                actualLength: MAX_SEARCH_QUERY_LENGTH + 1,
+            },
+        }));
+    });
+});

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
 export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
@@ -183,6 +183,8 @@ interface StatusControls {
 export interface CollectionSearchOptions extends BeforeReadControls {
     /** Free-text query string. */
     query: string;
+    /** Provider-neutral term and phrase matching semantics. */
+    matching?: SearchMatching;
     /** Restrict to a single content locale (defaults to the client default). */
     locale?: string;
     /** Read mode — `'published'` (default) or `'any'`. */
@@ -215,6 +217,8 @@ export interface CollectionSearchOptions extends BeforeReadControls {
 export interface ZoneSearchOptions extends BeforeReadControls {
     /** Free-text query string. */
     query: string;
+    /** Provider-neutral term and phrase matching semantics. */
+    matching?: SearchMatching;
     /** The zone (named cross-collection scope) to search. */
     zone: string;
     /** Restrict to a single content locale (defaults to the client default). */
@@ -253,7 +257,10 @@ export interface ReindexResult {
     collectionPath: string;
     /** Number of published documents walked. */
     documents: number;
-    /** Number of `(document, locale)` index rows upserted. */
+    /**
+     * Currently mirrors `documents` — the provider upserts are the source of
+     * truth for how many `(document, locale)` rows were written.
+     */
     indexed: number;
 }
 /**
@@ -275,7 +282,7 @@ export interface ReindexResult {
  *     in every locale.
  *
  * Availability is the version-grain ledger described in
- * `docs/07-internationalization/index.md`. Relationship population always behaves
+ * `docs/08-internationalization/index.md`. Relationship population always behaves
  * as `'fallback'` so a populated tree never has holes.
  */
 interface MissingLocaleControls {
@@ -349,7 +356,7 @@ export interface HistoryOptions extends BeforeReadControls {
 }
 /**
  * Options for `CollectionHandle.auditLog(documentId, options)`. The
- * document-grain audit log (docs/06-auth-and-security/02-auditability.md — Workstream 3) records the
+ * document-grain audit log (docs/07-auth-and-security/02-auditability.md — Workstream 3) records the
  * non-versioned changes the immutable version stream does not capture an
  * actor for: system-field writes (path, available-locales), in-place status
  * transitions, and the deletion event. Entries are newest-first and paged;
@@ -390,7 +397,7 @@ export interface CreateOptions {
      * The editorial advertised-locale set, stored document-grain in
      * `byline_document_available_locales`. When omitted, a new document starts
      * with an empty set; an explicit array (empty included) is stored verbatim.
-     * Surfaced on reads as `availableLocales`. See `docs/07-internationalization/index.md`.
+     * Surfaced on reads as `availableLocales`. See `docs/08-internationalization/index.md`.
      */
     availableLocales?: string[];
 }
@@ -406,7 +413,7 @@ export interface UpdateOptions {
      * The editorial advertised-locale set. When omitted, the existing set
      * carries forward unchanged (sticky — document-grain, like `path`); an
      * explicit array (empty included) replaces it wholesale. Surfaced on reads
-     * as `availableLocales`. See `docs/07-internationalization/index.md`.
+     * as `availableLocales`. See `docs/08-internationalization/index.md`.
      */
     availableLocales?: string[];
 }
@@ -552,7 +559,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * yardstick). Stable, document-grain. Surfaced so consumers / the admin can
      * indicate a document whose primary language differs from the system default.
      * Present on `find` / `findById` / `findByPath`. See
-     * `docs/07-internationalization/index.md`.
+     * `docs/08-internationalization/index.md`.
      */
     sourceLocale?: string;
     /** When this version was created. */
@@ -565,7 +572,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * the creator of the current version is also "who last updated the
      * document". Absent on rows written before audit wiring or by
      * internal tooling without a request context. Raw id only — display-name
-     * resolution is an admin-realm concern (see docs/06-auth-and-security/02-auditability.md — Workstream 1).
+     * resolution is an admin-realm concern (see docs/07-auth-and-security/02-auditability.md — Workstream 1).
      */
     createdBy?: string;
     /**
@@ -593,7 +600,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * `_availableVersionLocales` fact below; the public advertised set is their
      * intersection (`availableLocales ∩ _availableVersionLocales`), which the
      * host composes for hreflang / sitemap / "Also available in…" menus.
-     * Present on `find` / `findById` / `findByPath`. See `docs/07-internationalization/index.md`.
+     * Present on `find` / `findById` / `findByPath`. See `docs/08-internationalization/index.md`.
      */
     availableLocales?: string[];
     /**
@@ -603,7 +610,7 @@ export interface ClientDocument<F = Record<string, any>> {
      * Present on `find` / `findById` / `findByPath` (absent on version/history
      * reads); the published-available set on a normal (published) read. The
      * structural fact reconciled against the editorial `availableLocales` above.
-     * See `docs/07-internationalization/index.md`.
+     * See `docs/08-internationalization/index.md`.
      */
     _availableVersionLocales?: string[];
     /**

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,8 +44,8 @@
   ],
   "dependencies": {
     "uuid": "^14.0.1",
-    "@byline/auth": "4.8.0",
-    "@byline/core": "4.8.0"
+    "@byline/auth": "4.9.0",
+    "@byline/core": "4.9.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.4",
@@ -58,8 +58,8 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@byline/search-postgres": "4.8.0",
-    "@byline/db-postgres": "4.8.0"
+    "@byline/db-postgres": "4.9.0",
+    "@byline/search-postgres": "4.9.0"
   },
   "publishConfig": {
     "access": "public",