@byline/client 3.21.0 → 4.1.0

package/dist/client.d.ts

@@ -8,13 +8,14 @@
 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 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 = CollectionRegistry> {
+export declare class BylineClient<TRegistry extends CollectionRegistry = RegisteredCollections> {
     readonly db: IDbAdapter;
     readonly collections: readonly CollectionDefinition[];
     readonly storage: IStorageProvider | undefined;
@@ -71,6 +72,8 @@ export declare class BylineClient<TRegistry extends CollectionRegistry = Collect
     resolveCollectionId(path: string): Promise<string>;
 }
 /**
- * Create a new Byline client instance.
+ * 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.
  */
-export declare function createBylineClient<TRegistry extends CollectionRegistry = CollectionRegistry>(config: BylineClientConfig): BylineClient<TRegistry>;
+export declare function createBylineClient<TRegistry extends CollectionRegistry = RegisteredCollections>(config: BylineClientConfig): BylineClient<TRegistry>;

package/dist/client.js

@@ -174,7 +174,9 @@ export class BylineClient {
     }
 }
 /**
- * Create a new Byline client instance.
+ * 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.
  */
 export function createBylineClient(config) {
     return new BylineClient(config);

package/dist/collection-handle.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, TreeNode, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, RemoveFromTreeOptions, TreeNode, TreeParentResult, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -55,8 +55,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * comes free) and attaches them as `hit.document`. Two consequences to be
      * aware of:
      *
-     *   - `total` (and facet counts) remain the provider's pre-authorization
-     *     numbers — approximate under row scoping, exact without it.
+     *   - under row scoping, `total` is the authorized hit count for this page
+     *     and facets are omitted rather than leaking provider-wide aggregates.
      *   - a page of hits can come back shorter than `limit` when candidates
      *     are dropped; paginate on `offset`, not on received length.
      *
@@ -150,8 +150,10 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      */
     delete(documentId: string): Promise<DeleteDocumentResult>;
     /**
-     * Count documents visible to the current actor, optionally filtered by
-     * status.
+     * Sum the current-version workflow status buckets visible to the actor,
+     * optionally selecting one exact status. This is an editorial status-count
+     * API, not an ordinary published-view document count; it therefore
+     * authorizes as `readMode: 'any'` and rejects anonymous callers.
      *
      * Applies the collection's `beforeRead` predicate so the count reflects
      * only the rows the actor can see (multi-tenant scoping, owner-only
@@ -163,7 +165,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
     }): Promise<number>;
     /**
      * Per-status document counts for this collection. Used by admin status
-     * bars / dashboards. Applies `beforeRead` so per-status counts reflect
+     * bars / dashboards. This always reads current versions across statuses,
+     * authorizes as `readMode: 'any'`, and applies `beforeRead` so counts reflect
      * only the actor's visible rows.
      */
     countByStatus(options?: {
@@ -174,9 +177,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
     }>>;
     /**
      * Fetch the version history for a single document. Applies `beforeRead`
-     * as an access gate via `findById` — if the actor can't see the
-     * document at all, history returns an empty result rather than
-     * leaking version metadata.
+     * independently to every immutable version before pagination and counting,
+     * so ownership changes cannot expose hidden version content or metadata.
      *
      * Each version in the response is a shaped `ClientDocument`. Pagination
      * mirrors the storage adapter's `{ documents, meta }` shape, then is
@@ -189,9 +191,9 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * available-locales), in-place status transitions, and the deletion event
      * the immutable version stream deliberately does not record an actor for.
      *
-     * Applies `beforeRead` as an access gate via `findById` — exactly as
-     * `history()` does — so an actor who cannot see the document at all gets an
-     * empty log rather than leaking change metadata. Entries are newest-first.
+     * Applies `beforeRead` as a current-document access gate via `findById`, so
+     * an actor who cannot see the document at all gets an empty log rather than
+     * leaking change metadata. Entries are newest-first.
      * Actor *ids* are returned raw; resolving them to display labels is an
      * admin-realm concern handled above the SDK.
      *
@@ -203,12 +205,10 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * Fetch a specific version of a document by its `documentVersionId`.
      * Used by admin diff views.
      *
-     * Pass-through to `getDocumentByVersion`; access enforcement falls back
-     * to the collection-level `read` ability (asserted at the top of every
-     * read entry point). Row-level `beforeRead` does **not** apply here —
-     * version-by-id is a history-viewing primitive and the caller is
-     * expected to have already passed an access check on the parent
-     * document. Use `history()` instead if you want the access gate.
+     * The adapter query is constrained to this handle's collection and applies
+     * the collection's strict `beforeRead` predicate directly to the historical
+     * version. Unknown, cross-collection, and row-scoped version ids all return
+     * `null` without revealing ownership.
      */
     findByVersion<F = TFields>(versionId: string, options?: FindByVersionOptions<F>): Promise<ClientDocument<F> | null>;
     /**
@@ -227,14 +227,15 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * in the collection, but not in any table of contents). Distinct from
      * deleting the document. No-op when already unplaced.
      */
-    removeFromTree(documentId: string): Promise<void>;
+    removeFromTree(documentId: string, options?: RemoveFromTreeOptions): Promise<void>;
     /**
      * Read a node's subtree as a nested {@link TreeNode} forest, hydrated to
      * `ClientDocument`s. `rootDocumentId: null` (default) returns the whole tree
      * from the collection roots; a value returns the subtree rooted at (and
      * including) that node. Children are ordered per-parent. `status` defaults to
      * `'published'` (the client default) — an unpublished node hides its whole
-     * subtree in that mode.
+     * subtree in that mode. `beforeRead` visibility follows the same edge rule:
+     * a hidden node and its descendants are omitted, never promoted.
      */
     getSubtree<F = TFields>(options?: GetSubtreeOptions<F>): Promise<TreeNode<F>[]>;
     /**
@@ -243,7 +244,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * to `ClientDocument`s. In `'published'` mode (the client default) the walk
      * applies status-at-edge: it stops at the first unpublished ancestor (a
      * truncated chain), so a broken spine surfaces as a short chain the caller can
-     * detect rather than a silently-compacted one.
+     * detect rather than a silently-compacted one. A `beforeRead`-hidden ancestor
+     * breaks the edge identically.
      */
     getAncestors<F = TFields>(documentId: string, options?: GetAncestorsOptions<F>): Promise<ClientDocument<F>[]>;
     /**
@@ -251,12 +253,11 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * `getAncestors` cannot express (it returns `[]` for both a root and an
      * unplaced node). Returns `{ placed, parentDocumentId }`: `placed: false` is
      * *unplaced* (no edge row), `placed: true` with a null parent is a *root*, and
-     * a non-null parent is a *child*. Structure-only — no document hydration.
+     * a non-null parent is a *child*. A hidden queried node reports unplaced; a
+     * visible child of a hidden parent remains placed but the parent id is
+     * redacted to null. Structure-only — no document hydration.
      */
-    getTreeParent(documentId: string): Promise<{
-        placed: boolean;
-        parentDocumentId: string | null;
-    }>;
+    getTreeParent(documentId: string, options?: GetTreeParentOptions): Promise<TreeParentResult>;
     /**
      * Build a fresh `DocumentLifecycleContext` for a write call. Pulls the
      * resolved collection id, inherits the client-wide logger and storage
@@ -283,8 +284,8 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * Batch-hydrate a set of tree node document ids into shaped
      * `ClientDocument`s, keyed by document id. Reuses the populate batch read
      * (`getDocumentsByDocumentIds`) under the requested `readMode` — the tree's
-     * own status-at-edge filtering already happened structurally, so a node
-     * absent here in `'published'` mode simply has no published version. Fires
+     * own status/beforeRead edge filtering already happened structurally, and the
+     * same filters are applied again to close the structure/hydration race. Fires
      * `afterRead` per node (deduped within one shared `ReadContext`) to stay
      * consistent with the other client read paths.
      */
@@ -309,17 +310,11 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * is registered.
      */
     private richTextPopulateSources;
+    /** Complete the common post-reconstruction pipeline in security order. */
+    private finishReadDocuments;
     /**
-     * Resolve and cache the `beforeRead` hook predicate for this collection
-     * inside the current `ReadContext`. Honours `_bypassBeforeRead` (admin
-     * tooling, seeds, migrations).
-     */
-    private resolveBeforeReadPredicate;
-    /**
-     * Like `resolveBeforeReadPredicate`, but parses the predicate to the
-     * adapter-facing `DocumentFilter[]` shape used by `getDocumentById` /
-     * `getDocumentByPath`. Returns `undefined` (not `[]`) when there is no
-     * scoping, so the adapter can skip the loop entirely.
+     * Resolve the cached strict security filters used by every read shape.
+     * Returns `undefined` when no scoping applies.
      */
     private resolveBeforeReadFilters;
     /**