@byline/client 3.21.0 → 4.1.0

package/dist/server/request-scope.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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
+ */
+/**
+ * Resolve `factory` at most once per HTTP request for a given `key`. The
+ * returned promise is memoized on the current request — rejections
+ * included, since a request's cookies cannot change mid-flight and retrying
+ * a failed refresh would burn a second rotation on an already-rotated
+ * token. Outside a request (seed scripts, unit tests, background jobs) —
+ * or before a host bridge is registered — there is no request to key on
+ * and the factory runs unmemoized.
+ */
+export declare function oncePerRequest<T>(key: string, factory: () => Promise<T>): Promise<T>;

package/dist/server/request-scope.js

@@ -0,0 +1,50 @@
+/**
+ * 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
+ */
+/**
+ * Per-request memoization for `RequestContext` factories.
+ *
+ * `RequestContext.requestId` is documented as "per logical request", and
+ * the read-authorization layer binds every `ReadContext` to one immutable
+ * request authority whose token includes that id. A factory that mints a
+ * fresh context per call breaks both contracts as soon as two reads share
+ * a `ReadContext` (the admin tree view, hook-threaded nested reads):
+ * the second bind sees a different authority token and throws
+ * 'ReadContext cannot be reused across request authorities'.
+ *
+ * Memoizing on the current request (via the registered
+ * `HostRequestBridge`) makes every context factory request-stable. It
+ * also means at most one session verification — and at most one
+ * refresh-token rotation — per request, instead of one per call.
+ */
+import { tryGetHostRequestBridge } from '@byline/core';
+const requestScopes = new WeakMap();
+/**
+ * Resolve `factory` at most once per HTTP request for a given `key`. The
+ * returned promise is memoized on the current request — rejections
+ * included, since a request's cookies cannot change mid-flight and retrying
+ * a failed refresh would burn a second rotation on an already-rotated
+ * token. Outside a request (seed scripts, unit tests, background jobs) —
+ * or before a host bridge is registered — there is no request to key on
+ * and the factory runs unmemoized.
+ */
+export function oncePerRequest(key, factory) {
+    const request = tryGetHostRequestBridge()?.getRequest();
+    if (!request)
+        return factory();
+    let scope = requestScopes.get(request);
+    if (!scope) {
+        scope = new Map();
+        requestScopes.set(request, scope);
+    }
+    const existing = scope.get(key);
+    if (existing)
+        return existing;
+    const pending = factory();
+    scope.set(key, pending);
+    return pending;
+}

package/dist/server/request-scope.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/server/request-scope.test.node.js

@@ -0,0 +1,89 @@
+/**
+ * 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
+ */
+/**
+ * Unit coverage for per-request memoization. Registers a fake
+ * `HostRequestBridge` so "which request am I in" can be simulated: a
+ * stable object per request, or `undefined` when running outside a
+ * request.
+ */
+import { registerHostRequestBridge } from '@byline/core';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { oncePerRequest } from './request-scope.js';
+const BRIDGE_SLOT = Symbol.for('__byline_host_request_bridge__');
+const previousBridge = globalThis[BRIDGE_SLOT];
+const bridge = {
+    getRequest: vi.fn(),
+    getCookie: vi.fn(),
+    setCookie: vi.fn(),
+};
+describe('oncePerRequest', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        registerHostRequestBridge(bridge);
+        // Default: no request in scope, so every call resolves fresh.
+        bridge.getRequest.mockReturnValue(undefined);
+    });
+    afterEach(() => {
+        ;
+        globalThis[BRIDGE_SLOT] = previousBridge;
+    });
+    it('resolves the factory once per request per key', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        const first = await oncePerRequest('ctx', factory);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).toBe(first);
+        expect(factory).toHaveBeenCalledTimes(1);
+    });
+    it('keys memoization by request identity', async () => {
+        const requestA = { id: 'a' };
+        const requestB = { id: 'b' };
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        bridge.getRequest.mockReturnValue(requestA);
+        const first = await oncePerRequest('ctx', factory);
+        bridge.getRequest.mockReturnValue(requestB);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).not.toBe(first);
+        expect(factory).toHaveBeenCalledTimes(2);
+    });
+    it('isolates entries by key within one request', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const admin = vi.fn(async () => 'admin-context');
+        const publicCtx = vi.fn(async () => 'public-context');
+        await expect(oncePerRequest('admin', admin)).resolves.toBe('admin-context');
+        await expect(oncePerRequest('public', publicCtx)).resolves.toBe('public-context');
+        await expect(oncePerRequest('admin', admin)).resolves.toBe('admin-context');
+        expect(admin).toHaveBeenCalledTimes(1);
+        expect(publicCtx).toHaveBeenCalledTimes(1);
+    });
+    it('memoizes rejections for the remainder of the request', async () => {
+        bridge.getRequest.mockReturnValue({ id: 'request-a' });
+        const factory = vi.fn(async () => {
+            throw new Error('no admin session');
+        });
+        await expect(oncePerRequest('ctx', factory)).rejects.toThrow('no admin session');
+        await expect(oncePerRequest('ctx', factory)).rejects.toThrow('no admin session');
+        expect(factory).toHaveBeenCalledTimes(1);
+    });
+    it('runs unmemoized outside a request', async () => {
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        const first = await oncePerRequest('ctx', factory);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).not.toBe(first);
+        expect(factory).toHaveBeenCalledTimes(2);
+    });
+    it('runs unmemoized when no host bridge is registered', async () => {
+        ;
+        globalThis[BRIDGE_SLOT] = undefined;
+        const factory = vi.fn(async () => ({ token: Math.random() }));
+        const first = await oncePerRequest('ctx', factory);
+        const second = await oncePerRequest('ctx', factory);
+        expect(second).not.toBe(first);
+        expect(factory).toHaveBeenCalledTimes(2);
+    });
+});

package/dist/server/session-cookies.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 declare const ACCESS_TOKEN_COOKIE = "byline_access_token";
+export declare const REFRESH_TOKEN_COOKIE = "byline_refresh_token";
+/** Read the access-token cookie. Returns undefined when not present. */
+export declare function readAccessTokenCookie(): string | undefined;
+/** Read the refresh-token cookie. Returns undefined when not present. */
+export declare function readRefreshTokenCookie(): string | undefined;
+export interface SessionCookieTokens {
+    accessToken: string;
+    refreshToken: string;
+    accessTokenExpiresAt: Date;
+    refreshTokenExpiresAt: Date;
+}
+/**
+ * Write both access and refresh cookies. Called after sign-in and after
+ * every transparent refresh in `getAdminRequestContext()`.
+ *
+ * `maxAge` is derived from each token's own expiry claim so the browser
+ * drops the cookies at the same moment the server would reject them —
+ * saves round trips when the refresh token has fully expired.
+ */
+export declare function setSessionCookies(tokens: SessionCookieTokens): void;
+/**
+ * Clear both session cookies. Called on sign-out and on any auth failure
+ * during `getAdminRequestContext()` (ensures the browser does not keep
+ * trying a token that the server has already rejected).
+ */
+export declare function clearSessionCookies(): void;

package/dist/server/session-cookies.js

@@ -0,0 +1,95 @@
+/**
+ * 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
+ */
+/**
+ * Cookie helpers for admin session management.
+ *
+ * Two separate httpOnly cookies, one for each token half:
+ *
+ *   - `byline_access_token`  — short-lived JWT; sent on every request.
+ *   - `byline_refresh_token` — long-lived opaque string; sent back only
+ *                              when the access cookie is missing or
+ *                              expired, to mint a new access token.
+ *
+ * Presenting "one session" to the user is a function of the middleware —
+ * `getAdminRequestContext()` transparently refreshes the access cookie
+ * using the refresh cookie, so the UI layer doesn't have to care.
+ *
+ * All cookies set here use:
+ *   - `httpOnly: true`   — inaccessible to JavaScript (XSS-hardened).
+ *   - `sameSite: 'lax'`  — sent on top-level navigations but not
+ *                          cross-origin subrequests (reasonable default
+ *                          for an admin SSR app).
+ *   - `secure: true` in production — https-only; dev keeps it off so
+ *                          cookies work on http://localhost.
+ *   - `path: '/'`        — available everywhere in the app.
+ *
+ * Cookie transport goes through the registered `HostRequestBridge`, so
+ * this module is host-framework agnostic.
+ */
+import { getHostRequestBridge } from '@byline/core';
+export const ACCESS_TOKEN_COOKIE = 'byline_access_token';
+export const REFRESH_TOKEN_COOKIE = 'byline_refresh_token';
+const IS_PROD = process.env.NODE_ENV === 'production';
+/** Read the access-token cookie. Returns undefined when not present. */
+export function readAccessTokenCookie() {
+    return getHostRequestBridge().getCookie(ACCESS_TOKEN_COOKIE);
+}
+/** Read the refresh-token cookie. Returns undefined when not present. */
+export function readRefreshTokenCookie() {
+    return getHostRequestBridge().getCookie(REFRESH_TOKEN_COOKIE);
+}
+/**
+ * Write both access and refresh cookies. Called after sign-in and after
+ * every transparent refresh in `getAdminRequestContext()`.
+ *
+ * `maxAge` is derived from each token's own expiry claim so the browser
+ * drops the cookies at the same moment the server would reject them —
+ * saves round trips when the refresh token has fully expired.
+ */
+export function setSessionCookies(tokens) {
+    const bridge = getHostRequestBridge();
+    const now = Date.now();
+    const accessMaxAgeSeconds = Math.max(0, Math.floor((tokens.accessTokenExpiresAt.getTime() - now) / 1000));
+    const refreshMaxAgeSeconds = Math.max(0, Math.floor((tokens.refreshTokenExpiresAt.getTime() - now) / 1000));
+    bridge.setCookie(ACCESS_TOKEN_COOKIE, tokens.accessToken, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: accessMaxAgeSeconds,
+    });
+    bridge.setCookie(REFRESH_TOKEN_COOKIE, tokens.refreshToken, {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: refreshMaxAgeSeconds,
+    });
+}
+/**
+ * Clear both session cookies. Called on sign-out and on any auth failure
+ * during `getAdminRequestContext()` (ensures the browser does not keep
+ * trying a token that the server has already rejected).
+ */
+export function clearSessionCookies() {
+    const bridge = getHostRequestBridge();
+    bridge.setCookie(ACCESS_TOKEN_COOKIE, '', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: 0,
+    });
+    bridge.setCookie(REFRESH_TOKEN_COOKIE, '', {
+        httpOnly: true,
+        sameSite: 'lax',
+        secure: IS_PROD,
+        path: '/',
+        maxAge: 0,
+    });
+}

package/dist/types.d.ts

@@ -97,9 +97,18 @@ export interface BylineClientConfig {
      *   - a static `RequestContext` — convenient for long-lived processes
      *     that authenticate once (seeds, migrations, CLI tooling); or
      *   - a factory `() => RequestContext | Promise<RequestContext>` —
-     *     resolved per-call so each operation picks up the current
-     *     authenticated request (the pattern Phase 5's admin webapp will
-     *     use to thread middleware-derived actors).
+     *     invoked per operation so each one picks up the current
+     *     authenticated request (the pattern the admin webapp uses to
+     *     thread middleware-derived actors).
+     *
+     * **Factory contract — request-stable resolution.** Within one logical
+     * request the factory must return the same context instance (same
+     * `requestId`) on every call. Reads that share a `ReadContext` bind an
+     * immutable request authority whose token includes `requestId`, so a
+     * factory that mints a fresh context per call makes the second such
+     * read throw `ERR_VALIDATION` ('ReadContext cannot be reused across
+     * request authorities'). Host adapters should memoize resolution per
+     * request — see `oncePerRequest` in `@byline/host-tanstack-start`.
      *
      * When omitted, calls fail closed with `ERR_UNAUTHENTICATED`. Scripts
      * and tests pass `createSuperAdminContext()` from `@byline/auth`.
@@ -112,12 +121,10 @@ export interface BylineClientConfig {
  * documents; `depth` caps the traversal (default 1 when populate is set,
  * 0 otherwise). Clamped to the request's internal `ReadContext.maxDepth`.
  */
-interface PopulateControls {
-    populate?: PopulateSpec;
-    depth?: number;
+interface ReadContextControls {
     /**
      * Escape hatch for read-side hook re-entry. Carries the visited set,
-     * depth clamp, and `afterReadFired` set across nested reads so the
+     * depth clamp, and `afterRead` recursion/object state across nested reads so the
      * A→B→A recursion guard stays intact.
      *
      * Threading rules:
@@ -138,6 +145,10 @@ interface PopulateControls {
      */
     _readContext?: ReadContext;
 }
+interface PopulateControls extends ReadContextControls {
+    populate?: PopulateSpec;
+    depth?: number;
+}
 /**
  * Read-mode selector shared by every read method.
  *
@@ -227,9 +238,9 @@ export interface HydratedSearchHit extends SearchHit {
 }
 /**
  * The client-side search result envelope — `SearchResults` with the hits
- * widened to carry an optional hydrated document. `total` (and facet
- * counts) are the provider's pre-authorization numbers: approximate when
- * row scoping or hydration drops hits, exact otherwise.
+ * widened to carry an optional hydrated document. When authorization removes
+ * collections or applies row predicates, `total` is conservatively reduced to
+ * the authorized hits in this page and facets are omitted.
  */
 export interface ClientSearchResults {
     hits: HydratedSearchHit[];
@@ -324,8 +335,8 @@ export interface FindByPathOptions<F = Record<string, any>> extends PopulateCont
 /**
  * Options for `CollectionHandle.history(documentId, options)`. The history
  * endpoint is paginated; `order` / `desc` mirror the storage adapter's
- * version-row sort axes. `_bypassBeforeRead` skips the `findById` access
- * gate for admin tooling.
+ * version-row sort axes. `_bypassBeforeRead` skips per-version row scoping
+ * for admin tooling.
  */
 export interface HistoryOptions extends BeforeReadControls {
     locale?: string;
@@ -353,12 +364,11 @@ export interface AuditLogOptions extends BeforeReadControls {
     _readContext?: ReadContext;
 }
 /**
- * Options for `CollectionHandle.findByVersion(versionId, options)`. No
- * `BeforeReadControls` — `findByVersion` is a low-level pass-through
- * intended for admin diff views; row-level scoping is the caller's
- * responsibility (typically by gating with a prior `findById` call).
+ * Options for `CollectionHandle.findByVersion(versionId, options)`. Historical
+ * reads are collection-bound and apply the same `beforeRead` predicate as
+ * current reads.
  */
-export interface FindByVersionOptions<F = Record<string, any>> {
+export interface FindByVersionOptions<F = Record<string, any>> extends BeforeReadControls, ReadContextControls {
     select?: (keyof F & string)[] | string[];
     locale?: string;
 }
@@ -418,6 +428,13 @@ export interface PlaceTreeNodeOptions {
     beforeDocumentId?: string | null;
     /** Right neighbour — the node lands immediately before it. */
     afterDocumentId?: string | null;
+    /** Re-run `afterTreeChange` when this exact placement is already current. */
+    reconcile?: boolean;
+}
+/** Options for an idempotent tree removal or post-commit hook retry. */
+export interface RemoveFromTreeOptions {
+    /** Re-run `afterTreeChange` when the document is already unplaced. */
+    reconcile?: boolean;
 }
 /**
  * Options for `CollectionHandle.getSubtree(options)`. Reads a node's subtree as
@@ -426,8 +443,10 @@ export interface PlaceTreeNodeOptions {
  * at (and including) that node. `depth` bounds the descent (0-based; the root is
  * depth 0). `status` follows the usual published/any selector — in `'published'`
  * mode an unpublished node hides its entire subtree (the spine breaks).
+ * `beforeRead`-hidden nodes use the same edge semantics. `_bypassBeforeRead`
+ * is reserved for internal tooling.
  */
-export interface GetSubtreeOptions<F = Record<string, any>> extends StatusControls {
+export interface GetSubtreeOptions<F = Record<string, any>> extends StatusControls, BeforeReadControls, ReadContextControls {
     rootDocumentId?: string | null;
     depth?: number;
     /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
@@ -439,14 +458,30 @@ export interface GetSubtreeOptions<F = Record<string, any>> extends StatusContro
  * Options for `CollectionHandle.getAncestors(documentId, options)`. Walks the
  * node's ancestor chain upward, returning the ancestors **root-first** (the
  * breadcrumb trail, excluding the node itself). In `'published'` mode only
- * ancestors with a published version are returned.
+ * ancestors with a published version are returned. The walk also stops at the
+ * first ancestor excluded by `beforeRead`.
  */
-export interface GetAncestorsOptions<F = Record<string, any>> extends StatusControls {
+export interface GetAncestorsOptions<F = Record<string, any>> extends StatusControls, BeforeReadControls, ReadContextControls {
     /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
     locale?: string;
     /** Return only these fields on each ancestor. Omit for all fields. */
     select?: (keyof F & string)[] | string[];
 }
+/**
+ * Options for `CollectionHandle.getTreeParent(documentId, options)`. A hidden
+ * queried node is indistinguishable from an unplaced node. When only the parent
+ * is hidden, placement remains true but its id is redacted to `null`.
+ */
+export interface GetTreeParentOptions extends StatusControls, BeforeReadControls, ReadContextControls {
+    /** Locale used to evaluate localized `beforeRead` field predicates. */
+    locale?: string;
+}
+export interface TreeParentResult {
+    placed: boolean;
+    parentDocumentId: string | null;
+    /** Distinguishes a true root/unplaced node from a hidden parent id. */
+    parentVisibility: 'none' | 'visible' | 'redacted';
+}
 /**
  * A node in a hydrated document tree. `document` is the fully-shaped
  * `ClientDocument`; `depth` is 0-based from the subtree root; `children` are the
@@ -598,16 +633,18 @@ export interface PopulatedRelation<T> {
     document?: ClientDocument<T>;
 }
 /**
- * Re-type one key of a schema-inferred fields type as a populated relation.
+ * Re-type one key of a generated fields type as a populated relation.
  * Use to overlay populate's per-call enrichment on top of the unpopulated
- * shape that `CollectionFieldData<typeof X>` derives from the schema.
+ * shape emitted for the configured collection.
  *
  * Homomorphic mapped form preserves the optionality of the underlying key —
  * an optional relation field stays optional after populate is layered on.
  *
  * ```ts
+ * import type { MediaFields, NewsCategoriesFields, NewsFields } from './byline/generated/collection-types.js'
+ *
  * type NewsPopulated = WithPopulated<
- *   WithPopulated<NewsFields, 'category', NewsCategoryFields>,
+ *   WithPopulated<NewsFields, 'category', NewsCategoriesFields>,
  *   'featureImage', MediaFields
  * >
  * client.collection('news').find<NewsPopulated>({ populate: { category: '*', featureImage: '*' } })

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.21.0",
+  "version": "4.1.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -31,14 +31,21 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "browser": "./dist/server/browser.js",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@byline/auth": "3.21.0",
-    "@byline/core": "3.21.0"
+    "uuid": "^14.0.1",
+    "@byline/auth": "4.1.0",
+    "@byline/core": "4.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
@@ -51,8 +58,8 @@
     "tsx": "^4.23.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10",
-    "@byline/db-postgres": "3.21.0",
-    "@byline/search-postgres": "3.21.0"
+    "@byline/search-postgres": "4.1.0",
+    "@byline/db-postgres": "4.1.0"
   },
   "publishConfig": {
     "access": "public",