@byline/client 4.16.0 → 4.18.0

package/dist/client.d.ts

@@ -8,14 +8,15 @@
 import { type RequestContext } from '@byline/auth';
 import type { BylineLogger, CollectionDefinition, CollectionRegistry, IDbAdapter, IStorageProvider, RichTextPopulateFn, RichTextToTextFn, SearchProvider, SlugifierFn } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
-import type { RegisteredCollections } from './register.js';
+import { SingletonHandle } from './singleton-handle.js';
+import type { RegisteredCollections, RegisteredSingletons } from './register.js';
 import type { BylineClientConfig, ClientSearchResults, ZoneSearchOptions } from './types.js';
 /**
  * The main Byline client instance. Holds the database adapter, collection
  * definitions, and optional storage provider. Use `collection(path)` to get
  * a scoped handle for querying and mutating documents.
  */
-export declare class BylineClient<TRegistry extends CollectionRegistry = RegisteredCollections> {
+export declare class BylineClient<TCollections extends CollectionRegistry = RegisteredCollections, TSingletons extends CollectionRegistry = RegisteredSingletons> {
     readonly db: IDbAdapter;
     readonly collections: readonly CollectionDefinition[];
     readonly storage: IStorageProvider | undefined;
@@ -55,7 +56,9 @@ export declare class BylineClient<TRegistry extends CollectionRegistry = Registe
      * Get a handle scoped to a single collection. All subsequent read/write
      * operations on the handle are performed against this collection.
      */
-    collection<TPath extends keyof TRegistry & string>(path: TPath): CollectionHandle<TRegistry[TPath]>;
+    collection<TPath extends keyof TCollections & string>(path: TPath): CollectionHandle<TCollections[TPath]>;
+    /** Get the deliberately narrow, document-ID-free handle for a singleton slot. */
+    singleton<TPath extends keyof TSingletons & string>(path: TPath): SingletonHandle<TSingletons[TPath]>;
     /**
      * Resolve a collection path to its database row id and current schema
      * version. Cached for the lifetime of this client instance. The version
@@ -72,8 +75,8 @@ export declare class BylineClient<TRegistry extends CollectionRegistry = Registe
     resolveCollectionId(path: string): Promise<string>;
 }
 /**
- * Create a new Byline client instance. The registry generic defaults to
- * `RegisteredCollections`, so in an app whose generated types augment
- * `Register` the returned client is fully typed with no explicit generic.
+ * Create a new Byline client instance. Both registry generics default through
+ * `Register`, so an app's generated collection and singleton types make the
+ * returned client fully typed with no explicit generic.
  */
-export declare function createBylineClient<TRegistry extends CollectionRegistry = RegisteredCollections>(config: BylineClientConfig): BylineClient<TRegistry>;
+export declare function createBylineClient<TCollections extends CollectionRegistry = RegisteredCollections, TSingletons extends CollectionRegistry = RegisteredSingletons>(config: BylineClientConfig): BylineClient<TCollections, TSingletons>;

package/dist/client.js

@@ -6,9 +6,10 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { ERR_UNAUTHENTICATED } from '@byline/auth';
-import { ERR_NOT_FOUND, getLogger } from '@byline/core';
+import { ERR_NOT_FOUND, ERR_VALIDATION, getLogger, isSingleton } from '@byline/core';
 import { CollectionHandle } from './collection-handle.js';
 import { zoneSearch } from './search.js';
+import { SingletonHandle } from './singleton-handle.js';
 /**
  * Resolve a logger for the client in priority order:
  *   1. explicit `config.logger`
@@ -138,12 +139,40 @@ export class BylineClient {
                 message: `Collection not found: '${path}'`,
                 details: {
                     collectionPath: path,
-                    available: this.collections.map((c) => c.path),
+                    available: this.collections
+                        .filter((definition) => !isSingleton(definition))
+                        .map((c) => c.path),
                 },
             });
         }
+        if (isSingleton(definition)) {
+            throw ERR_VALIDATION({
+                message: `'${path}' is a singleton; use client.singleton('${path}')`,
+                details: { path, actualKind: 'singleton', expectedKind: 'collection' },
+            });
+        }
         return new CollectionHandle(this, definition);
     }
+    /** Get the deliberately narrow, document-ID-free handle for a singleton slot. */
+    singleton(path) {
+        const definition = this.collections.find((c) => c.path === path);
+        if (!definition) {
+            throw ERR_NOT_FOUND({
+                message: `Singleton not found: '${path}'`,
+                details: {
+                    singletonPath: path,
+                    available: this.collections.filter(isSingleton).map((c) => c.path),
+                },
+            });
+        }
+        if (!isSingleton(definition)) {
+            throw ERR_VALIDATION({
+                message: `'${path}' is a collection; use client.collection('${path}')`,
+                details: { path, actualKind: 'collection', expectedKind: 'singleton' },
+            });
+        }
+        return new SingletonHandle(this, definition);
+    }
     /**
      * Resolve a collection path to its database row id and current schema
      * version. Cached for the lifetime of this client instance. The version
@@ -174,9 +203,9 @@ export class BylineClient {
     }
 }
 /**
- * Create a new Byline client instance. The registry generic defaults to
- * `RegisteredCollections`, so in an app whose generated types augment
- * `Register` the returned client is fully typed with no explicit generic.
+ * Create a new Byline client instance. Both registry generics default through
+ * `Register`, so an app's generated collection and singleton types make the
+ * returned client fully typed with no explicit generic.
  */
 export function createBylineClient(config) {
     return new BylineClient(config);

package/dist/collection-handle.js

@@ -7,8 +7,9 @@
  */
 import { applyAfterRead, assertActorCanPerform, buildSearchDocument, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, ERR_VALIDATION, getDocumentScheduledPublish, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, } from '@byline/core';
 import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
+import { expectedDocumentId } from './read-internals.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
-import { assertSearchQueryLength, finalizeSearchHits } from './search.js';
+import { assertSearchFieldScope, assertSearchQueryLength, finalizeSearchHits } from './search.js';
 function toScheduleInfo(schedule) {
     const { executionToken: _executionToken, executionExpiresAt: _executionExpiresAt, ...info } = schedule;
     return info;
@@ -147,8 +148,10 @@ export class CollectionHandle {
                     'see `@byline/search-postgres` → `postgresSearch()` for the built-in driver.',
             });
         }
+        assertSearchFieldScope(provider, options.fieldScope);
         const results = await provider.search({
             query: options.query,
+            fieldScope: options.fieldScope,
             matching: options.matching,
             collectionPath: this.definition.path,
             locale: options.locale ?? this.client.defaultLocale,
@@ -240,7 +243,7 @@ export class CollectionHandle {
      */
     async reindex() {
         const requestContext = await this.client.resolveRequestContext();
-        assertActorCanPerform(requestContext, this.definition.path, 'reindex');
+        assertActorCanPerform(requestContext, this.definition, 'reindex');
         const provider = this.client.searchProvider;
         const result = { collectionPath: this.definition.path, documents: 0, indexed: 0 };
         if (provider == null || this.definition.search == null)
@@ -612,6 +615,7 @@ export class CollectionHandle {
      * `null` without revealing ownership.
      */
     async findByVersion(versionId, options = {}) {
+        const boundOptions = options;
         const readCtx = options._readContext ?? createReadContext();
         const requestContext = await this.resolveAndAssertRead('any', readCtx);
         const filters = await this.resolveBeforeReadFilters(requestContext, readCtx, options._bypassBeforeRead);
@@ -619,6 +623,7 @@ export class CollectionHandle {
         const locale = options.locale ?? this.client.defaultLocale;
         const raw = await this.client.db.queries.documents.getDocumentByVersion({
             document_version_id: versionId,
+            document_id: boundOptions[expectedDocumentId],
             locale,
             collection_id: collectionId,
             filters,
@@ -824,7 +829,7 @@ export class CollectionHandle {
      */
     async resolveAndAssertRead(readMode, readContext) {
         const requestContext = await resolveReadRequestContext(this.client, readContext, readMode);
-        assertActorCanPerform(requestContext, this.definition.path, 'read');
+        assertActorCanPerform(requestContext, this.definition, 'read');
         return requestContext;
     }
     /**

package/dist/index.d.ts

@@ -5,8 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
+export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type SingletonSaveResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
-export type { Register, RegisteredCollections } from './register.js';
-export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';
+export { SingletonHandle } from './singleton-handle.js';
+export type { Register, RegisteredCollections, RegisteredSingletons } from './register.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSingletonOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, SearchFacetBucket, SearchHit, SearchResults, SingletonDocument, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, UpdateSingletonOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';

package/dist/index.js

@@ -8,3 +8,4 @@
 export { createReadContext, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
+export { SingletonHandle } from './singleton-handle.js';

package/dist/read-internals.d.ts

@@ -0,0 +1,5 @@
+/** Internal ownership constraint for singleton historical reads. */
+export declare const expectedDocumentId: unique symbol;
+export interface DocumentBoundFindByVersionOptions {
+    [expectedDocumentId]?: string;
+}

package/dist/read-internals.js

@@ -0,0 +1,2 @@
+/** Internal ownership constraint for singleton historical reads. */
+export const expectedDocumentId = Symbol('byline.expectedDocumentId');

package/dist/register.d.ts

@@ -15,14 +15,16 @@ import type { CollectionRegistry } from '@byline/core';
  * declare module '@byline/client' {
  *   interface Register {
  *     collections: CollectionFieldsByPath
+ *     singletons: SingletonFieldsByPath
  *   }
  * }
  * ```
  *
  * Once merged, every bare `BylineClient` in the app's program — including
  * the getters on `@byline/client/server` — resolves to
- * `BylineClient<CollectionFieldsByPath>`, so `client.collection('news')`
- * autocompletes collection paths and returns the generated field shapes
+ * `BylineClient<CollectionFieldsByPath, SingletonFieldsByPath>`, so
+ * `client.collection('news')` and `client.singleton('site-settings')`
+ * autocomplete their respective paths and return the generated field shapes
  * with no per-call generics and no type assertions.
  *
  * Exactly one application per TypeScript program can augment this
@@ -42,3 +44,12 @@ export interface Register {
 export type RegisteredCollections = Register extends {
     collections: infer TCollections extends CollectionRegistry;
 } ? TCollections : CollectionRegistry;
+/**
+ * The app's registered singleton registry, or the same loose
+ * `CollectionRegistry` fallback used by collections when no augmentation is
+ * present. Keeping this as a conditional lookup preserves the deliberately
+ * empty declaration-merge target above.
+ */
+export type RegisteredSingletons = Register extends {
+    singletons: infer TSingletons extends CollectionRegistry;
+} ? TSingletons : CollectionRegistry;

package/dist/register.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/register.test.node.js

@@ -0,0 +1,16 @@
+/**
+ * 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 { describe, expectTypeOf, it } from 'vitest';
+describe('unaugmented client registration fallback', () => {
+    it('keeps both path registries loose outside an application program', () => {
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+        expectTypeOf().toEqualTypeOf();
+    });
+});

package/dist/search.d.ts

@@ -17,9 +17,11 @@
  * into shaped `ClientDocument`s in the same query.
  */
 import type { RequestContext } from '@byline/auth';
-import type { ReadContext, ReadMode, SearchHit } from '@byline/core';
+import type { ReadContext, ReadMode, SearchHit, SearchProvider } from '@byline/core';
 import type { BylineClient } from './client.js';
 import type { ClientSearchResults, HydratedSearchHit, ZoneSearchOptions } from './types.js';
+/** Validate the optional logical body-field scope before calling a provider. */
+export declare function assertSearchFieldScope(provider: SearchProvider, fieldScope: string[] | undefined): void;
 export interface FinalizeSearchHitsParams {
     client: BylineClient<any>;
     requestContext: RequestContext;

package/dist/search.js

@@ -7,6 +7,20 @@
  */
 import { assertActorCanPerform, createReadContext, ERR_VALIDATION, getCollectionAdminConfig, MAX_SEARCH_QUERY_LENGTH, resolveSearchZones, } from '@byline/core';
 import { resolveReadRequestContext, resolveReadSecurityFilters } from './read-context.js';
+/** Validate the optional logical body-field scope before calling a provider. */
+export function assertSearchFieldScope(provider, fieldScope) {
+    if (fieldScope == null)
+        return;
+    if (fieldScope.length === 0 ||
+        fieldScope.some((field) => typeof field !== 'string' || field.trim().length === 0)) {
+        throw ERR_VALIDATION({ message: 'Search fieldScope must contain one or more field names.' });
+    }
+    if (!provider.capabilities.fullText.fieldScope) {
+        throw ERR_VALIDATION({
+            message: 'The registered search provider does not support field-scoped full-text queries.',
+        });
+    }
+}
 /**
  * Authorise (and optionally hydrate) provider hits, per collection:
  *
@@ -152,7 +166,7 @@ export async function zoneSearch(client, options) {
     let firstAbilityError;
     for (const member of members) {
         try {
-            assertActorCanPerform(requestContext, member.path, 'read');
+            assertActorCanPerform(requestContext, member, 'read');
             readable.add(member.path);
         }
         catch (err) {
@@ -163,6 +177,7 @@ export async function zoneSearch(client, options) {
     if (readable.size === 0) {
         throw firstAbilityError;
     }
+    assertSearchFieldScope(provider, options.fieldScope);
     let aggregateRestricted = readable.size !== members.length;
     if (!options._bypassBeforeRead) {
         for (const member of members) {
@@ -176,6 +191,7 @@ export async function zoneSearch(client, options) {
     }
     const results = await provider.search({
         query: options.query,
+        fieldScope: options.fieldScope,
         matching: options.matching,
         zone: options.zone,
         locale: options.locale ?? client.defaultLocale,

package/dist/singleton-handle.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 type { ChangeStatusResult, SingletonDefinition, SingletonSaveResult, UnpublishResult } from '@byline/core';
+import type { BylineClient } from './client.js';
+import type { ClientDocument, ConfirmScheduledPublishOptions, DocumentPublishScheduleInfo, FindByVersionOptions, FindResult, GetSingletonOptions, HistoryOptions, SchedulePublishOptions, SingletonDocument, UpdateSingletonOptions } from './types.js';
+/**
+ * A document-ID-free handle for one registered singleton slot.
+ *
+ * Reads deliberately delegate to the collection document reader only after
+ * the singleton read ability and slot mapping have been resolved in that
+ * order. This keeps reconstruction, hooks, populate, and response shaping
+ * identical without exposing collection-only operations on this handle.
+ */
+export declare class SingletonHandle<TFields extends Record<string, any> = Record<string, any>> {
+    private readonly client;
+    private readonly definition;
+    private readonly reader;
+    constructor(client: BylineClient<any, any>, definition: SingletonDefinition);
+    get(options?: GetSingletonOptions<TFields>): Promise<SingletonDocument<TFields> | null>;
+    update(data: TFields, options?: UpdateSingletonOptions): Promise<SingletonSaveResult>;
+    changeStatus(nextStatus: string): Promise<ChangeStatusResult>;
+    unpublish(): Promise<UnpublishResult>;
+    schedulePublish(options: SchedulePublishOptions): Promise<DocumentPublishScheduleInfo>;
+    confirmScheduledPublish(options: ConfirmScheduledPublishOptions): Promise<DocumentPublishScheduleInfo>;
+    cancelScheduledPublish(): Promise<DocumentPublishScheduleInfo | null>;
+    getScheduledPublish(): Promise<DocumentPublishScheduleInfo | null>;
+    history<F = TFields>(options?: HistoryOptions): Promise<FindResult<F>>;
+    findByVersion<F = TFields>(versionId: string, options?: FindByVersionOptions<F>): Promise<ClientDocument<F> | null>;
+    restoreVersion(sourceVersionId: string): Promise<SingletonSaveResult>;
+    copyToLocale(args: {
+        sourceLocale: string;
+        targetLocale: string;
+        overwrite?: boolean;
+    }): Promise<SingletonSaveResult>;
+    private authorizeRead;
+    private buildAuthorizedLifecycleContext;
+    private resolveMappedDocumentId;
+    private resolveRequiredDocument;
+}

package/dist/singleton-handle.js

@@ -0,0 +1,155 @@
+/**
+ * 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 { assertActorCanPerform, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, copySingletonToLocale, createReadContext, ERR_NOT_FOUND, getDocumentScheduledPublish, resolveSingletonDocumentId, restoreSingletonVersion, scheduleDocumentPublish, unpublishDocument, updateSingleton, } from '@byline/core';
+import { CollectionHandle } from './collection-handle.js';
+import { resolveReadRequestContext } from './read-context.js';
+import { expectedDocumentId } from './read-internals.js';
+function toScheduleInfo(schedule) {
+    const { executionToken: _executionToken, executionExpiresAt: _executionExpiresAt, ...info } = schedule;
+    return info;
+}
+/**
+ * A document-ID-free handle for one registered singleton slot.
+ *
+ * Reads deliberately delegate to the collection document reader only after
+ * the singleton read ability and slot mapping have been resolved in that
+ * order. This keeps reconstruction, hooks, populate, and response shaping
+ * identical without exposing collection-only operations on this handle.
+ */
+export class SingletonHandle {
+    client;
+    definition;
+    reader;
+    constructor(client, definition) {
+        this.client = client;
+        this.definition = definition;
+        this.reader = new CollectionHandle(client, definition);
+    }
+    async get(options = {}) {
+        const readContext = options._readContext ?? createReadContext();
+        await this.authorizeRead(options.status ?? 'published', readContext);
+        const documentId = await this.resolveMappedDocumentId();
+        if (documentId == null)
+            return null;
+        const document = await this.reader.findById(documentId, {
+            ...options,
+            _readContext: readContext,
+        });
+        if (document == null)
+            return null;
+        const { path: _path, ...singleton } = document;
+        return singleton;
+    }
+    async update(data, options = {}) {
+        const ctx = await this.buildAuthorizedLifecycleContext(['update']);
+        return updateSingleton(ctx, { data, ...options });
+    }
+    async changeStatus(nextStatus) {
+        const abilities = ['changeStatus'];
+        if (nextStatus === 'published')
+            abilities.push('publish');
+        const { ctx, documentId } = await this.resolveRequiredDocument(abilities);
+        return changeDocumentStatus(ctx, { documentId, nextStatus });
+    }
+    async unpublish() {
+        const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus']);
+        return unpublishDocument(ctx, { documentId });
+    }
+    async schedulePublish(options) {
+        const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus', 'publish']);
+        return toScheduleInfo(await scheduleDocumentPublish(ctx, { documentId, ...options }));
+    }
+    async confirmScheduledPublish(options) {
+        const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus', 'publish']);
+        return toScheduleInfo(await confirmDocumentScheduledPublish(ctx, { documentId, ...options }));
+    }
+    async cancelScheduledPublish() {
+        const { ctx, documentId } = await this.resolveRequiredDocument(['changeStatus', 'publish']);
+        const schedule = await cancelDocumentScheduledPublish(ctx, { documentId });
+        return schedule == null ? null : toScheduleInfo(schedule);
+    }
+    async getScheduledPublish() {
+        const ctx = await this.buildAuthorizedLifecycleContext(['changeStatus', 'publish']);
+        const documentId = await resolveSingletonDocumentId(ctx);
+        if (documentId == null)
+            return null;
+        const schedule = await getDocumentScheduledPublish(ctx, { documentId });
+        return schedule == null ? null : toScheduleInfo(schedule);
+    }
+    async history(options = {}) {
+        const readContext = options._readContext ?? createReadContext();
+        await this.authorizeRead('any', readContext);
+        const documentId = await this.resolveMappedDocumentId();
+        if (documentId == null) {
+            const page = options.page ?? 1;
+            const pageSize = options.pageSize ?? 20;
+            return { docs: [], meta: { total: 0, page, pageSize, totalPages: 0 } };
+        }
+        return this.reader.history(documentId, { ...options, _readContext: readContext });
+    }
+    async findByVersion(versionId, options = {}) {
+        const readContext = options._readContext ?? createReadContext();
+        await this.authorizeRead('any', readContext);
+        const documentId = await this.resolveMappedDocumentId();
+        if (documentId == null)
+            return null;
+        const boundOptions = {
+            ...options,
+            _readContext: readContext,
+            [expectedDocumentId]: documentId,
+        };
+        return this.reader.findByVersion(versionId, boundOptions);
+    }
+    async restoreVersion(sourceVersionId) {
+        const ctx = await this.buildAuthorizedLifecycleContext(['update']);
+        return restoreSingletonVersion(ctx, { sourceVersionId });
+    }
+    async copyToLocale(args) {
+        const ctx = await this.buildAuthorizedLifecycleContext(['update']);
+        return copySingletonToLocale(ctx, { ...args, overwrite: args.overwrite ?? false });
+    }
+    async authorizeRead(readMode, readContext) {
+        const requestContext = await resolveReadRequestContext(this.client, readContext, readMode);
+        assertActorCanPerform(requestContext, this.definition, 'read');
+        return requestContext;
+    }
+    async buildAuthorizedLifecycleContext(abilities) {
+        const requestContext = await this.client.resolveRequestContext();
+        for (const ability of abilities) {
+            assertActorCanPerform(requestContext, this.definition, ability);
+        }
+        const { id: collectionId, version: collectionVersion } = await this.client.resolveCollectionRecord(this.definition.path);
+        return {
+            db: this.client.db,
+            definition: this.definition,
+            collectionId,
+            collectionVersion,
+            collectionPath: this.definition.path,
+            storage: this.client.storage,
+            logger: this.client.logger,
+            defaultLocale: this.client.defaultLocale,
+            slugifier: this.client.slugifier,
+            requestContext,
+        };
+    }
+    async resolveMappedDocumentId() {
+        const collectionId = await this.client.resolveCollectionId(this.definition.path);
+        return this.client.db.queries.singletons.getMappedDocumentId(collectionId);
+    }
+    async resolveRequiredDocument(abilities) {
+        const ctx = await this.buildAuthorizedLifecycleContext(abilities);
+        const documentId = await resolveSingletonDocumentId(ctx);
+        if (documentId == null) {
+            throw ERR_NOT_FOUND({
+                message: `singleton '${this.definition.path}' has not been saved`,
+                details: { singletonPath: this.definition.path },
+            });
+        }
+        return { ctx, documentId };
+    }
+}

package/dist/types.d.ts

@@ -183,6 +183,8 @@ interface StatusControls {
 export interface CollectionSearchOptions extends BeforeReadControls {
     /** Free-text query string. */
     query: string;
+    /** Restrict full-text matching to named fields from the collection's `search.body`. */
+    fieldScope?: string[];
     /** Provider-neutral term and phrase matching semantics. */
     matching?: SearchMatching;
     /** Restrict to a single content locale (defaults to the client default). */
@@ -217,6 +219,8 @@ export interface CollectionSearchOptions extends BeforeReadControls {
 export interface ZoneSearchOptions extends BeforeReadControls {
     /** Free-text query string. */
     query: string;
+    /** Restrict full-text matching to body-field names shared by participating collections. */
+    fieldScope?: string[];
     /** Provider-neutral term and phrase matching semantics. */
     matching?: SearchMatching;
     /** The zone (named cross-collection scope) to search. */
@@ -335,6 +339,8 @@ export interface FindByIdOptions<F = Record<string, any>> extends PopulateContro
      */
     lenient?: boolean;
 }
+/** Read controls for `SingletonHandle.get()`. */
+export type GetSingletonOptions<F = Record<string, any>> = FindByIdOptions<F>;
 export interface FindByPathOptions<F = Record<string, any>> extends PopulateControls, StatusControls, MissingLocaleControls, BeforeReadControls {
     select?: (keyof F & string)[] | string[];
     locale?: string;
@@ -417,6 +423,13 @@ export interface UpdateOptions {
      */
     availableLocales?: string[];
 }
+/** Write controls for `SingletonHandle.update()`. */
+export interface UpdateSingletonOptions {
+    /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
+    locale?: string;
+    /** Reject the save when this is not the slot's current version id. */
+    expectedVersionId?: string;
+}
 /** Optimistic, absolute-time input for `CollectionHandle.schedulePublish()`. */
 export interface SchedulePublishOptions {
     /** ISO instant carrying an explicit UTC offset or `Z`. */
@@ -637,6 +650,8 @@ export interface ClientDocument<F = Record<string, any>> {
      */
     _localeAgnostic?: boolean;
 }
+/** A singleton read envelope. Singleton documents have no public URL path. */
+export type SingletonDocument<F = Record<string, any>> = Omit<ClientDocument<F>, 'path'>;
 export interface FindResult<F = Record<string, any>> {
     docs: ClientDocument<F>[];
     meta: {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.16.0",
+  "version": "4.18.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,22 +44,21 @@
   ],
   "dependencies": {
     "uuid": "^14.0.2",
-    "@byline/auth": "4.16.0",
-    "@byline/core": "4.16.0"
+    "@byline/auth": "4.18.0",
+    "@byline/core": "4.18.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.5.9",
-    "@types/node": "^26.2.0",
+    "@biomejs/biome": "2.5.10",
+    "@types/node": "^26.4.0",
     "chokidar": "^5.0.0",
     "chokidar-cli": "^3.0.0",
     "dotenv": "^17.4.2",
     "npm-run-all": "^4.1.5",
     "tsc-alias": "^1.9.2",
-    "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "@byline/db-postgres": "4.16.0",
-    "@byline/search-postgres": "4.16.0"
+    "@byline/search-postgres": "4.18.0",
+    "@byline/db-postgres": "4.18.0"
   },
   "publishConfig": {
     "access": "public",