@byline/core 4.0.0 → 4.1.0

package/dist/codegen/index.js

@@ -6,8 +6,8 @@
  * Copyright (c) Infonomic Company Limited
  */
 import { createHash } from 'node:crypto';
-const FORMAT_VERSION = 1;
-const HASH_DOMAIN = '@byline/core/codegen:collection-types:v1\n';
+const FORMAT_VERSION = 2;
+const HASH_DOMAIN = '@byline/core/codegen:collection-types:v2\n';
 const IMPORT_ORDER = ['JsonObject', 'JsonValue', 'RelatedDocumentValue', 'StoredFileValue'];
 function compareStrings(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
@@ -411,7 +411,38 @@ function emitBody(analysis) {
     const importLines = usedImports.length === 0
         ? []
         : ['import type {', ...usedImports.map((name) => `  ${name},`), "} from '@byline/core'", ''];
-    return `${[...importLines, ...declarations].join('\n').replace(/\n+$/, '')}\n`;
+    // Every type declaration lives inside the `@byline/generated-types`
+    // declaration-merge block, so the published stub package is the one
+    // canonical import path for app collection types
+    // (`import type { NewsFields } from '@byline/generated-types'`). The
+    // file's top-level `@byline/core` imports remain visible inside the
+    // block (module augmentation is lexically scoped).
+    const declarationLines = declarations
+        .join('\n')
+        .replace(/\n+$/, '')
+        .split('\n')
+        .map((line) => (line.length === 0 ? line : `  ${line}`));
+    // Register the app's collection registry with @byline/client (a second
+    // declaration merge). Every bare `BylineClient` in the app's program —
+    // including the `@byline/client/server` getters — then resolves to
+    // `BylineClient<CollectionFieldsByPath>`. Both `@byline/generated-types`
+    // and `@byline/client` must be resolvable in the consuming program; apps
+    // that generate types depend on both.
+    const registerLines = [
+        "declare module '@byline/client' {",
+        '  interface Register {',
+        "    collections: import('@byline/generated-types').CollectionFieldsByPath",
+        '  }',
+        '}',
+    ];
+    return `${[
+        ...importLines,
+        "declare module '@byline/generated-types' {",
+        ...declarationLines,
+        '}',
+        '',
+        ...registerLines,
+    ].join('\n')}\n`;
 }
 /**
  * Emit deterministic application collection types from evaluated runtime definitions.

package/dist/codegen/index.test.node.js

@@ -28,13 +28,31 @@ describe('emitCollectionTypes', () => {
     it('emits a versioned header, verifiable body hash, and canonical formatting', () => {
         const { source, hash } = emitCollectionTypes([collection('plain', [])]);
         const body = source.split('\n').slice(4).join('\n');
-        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 1\n\/\/ Hash: [a-f0-9]{64}\n\n/);
-        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v1\n${body}`).digest('hex'));
+        expect(source).toMatch(/^\/\/ Generated by @byline\/core\/codegen\n\/\/ Format version: 2\n\/\/ Hash: [a-f0-9]{64}\n\n/);
+        expect(hash).toBe(createHash('sha256').update(`@byline/core/codegen:collection-types:v2\n${body}`).digest('hex'));
         expect(source).toContain(`// Hash: ${hash}`);
         expect(source.endsWith('\n')).toBe(true);
         expect(source).not.toContain('\r');
         expect(source).not.toContain(';');
     });
+    it('declares every type inside the @byline/generated-types augmentation block', () => {
+        const { source } = emitCollectionTypes([collection('plain', [{ name: 'title', type: 'text' }])]);
+        expect(source).toContain("declare module '@byline/generated-types' {");
+        expect(source).toContain('  export type PlainFields = {');
+        expect(source).toContain('  export type CollectionPath = keyof CollectionFieldsByPath');
+        // No module-level type exports outside the augmentation blocks.
+        expect(source).not.toMatch(/^export /m);
+    });
+    it('emits the @byline/client Register augmentation referencing the generated registry', () => {
+        const { source } = emitCollectionTypes([collection('plain', [])]);
+        expect(source).toContain([
+            "declare module '@byline/client' {",
+            '  interface Register {',
+            "    collections: import('@byline/generated-types').CollectionFieldsByPath",
+            '  }',
+            '}',
+        ].join('\n'));
+    });
     it('sorts collections and declarations without changing field, select, or block union order', () => {
         const alpha = collection('alpha', [
             {

package/dist/host/host-request-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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
+ */
+/**
+ * The host-framework request bridge — the seam that makes the server-side
+ * client stack (`@byline/client/server`) host-agnostic.
+ *
+ * Everything request-scoped in that stack bottoms out in three
+ * primitives: "which request am I in" (identity for per-request
+ * memoization), "read a cookie", and "write a cookie" (admin session
+ * refresh rotates tokens). A host adapter implements those three over its
+ * framework's runtime and registers the bridge once at server boot;
+ * `@byline/client/server` is written against the interface and never
+ * imports a framework.
+ *
+ * Registration follows the same pattern as the config singletons in
+ * `config/config.ts`: a `Symbol.for` slot on `globalThis`, so every copy
+ * of this module (Vite SSR can resolve workspace-linked packages through
+ * different module graphs) shares the same state. Server-only by nature —
+ * hosts register from their boot path (side-effect imports guarantee
+ * registration before any request is handled), and nothing in a browser
+ * graph should ever reach for it.
+ */
+export interface HostCookieSetOptions {
+    httpOnly?: boolean;
+    sameSite?: 'lax' | 'strict' | 'none';
+    secure?: boolean;
+    path?: string;
+    maxAge?: number;
+}
+export interface HostRequestBridge {
+    /**
+     * A stable identity object for the current HTTP request, or `undefined`
+     * when running outside a request (seed scripts, background jobs, unit
+     * tests). Used purely as a WeakMap key for per-request memoization —
+     * never inspected.
+     */
+    getRequest(): object | undefined;
+    /** Read a request cookie. Returns `undefined` when not present. */
+    getCookie(name: string): string | undefined;
+    /** Write a response cookie (admin session refresh, preview toggles). */
+    setCookie(name: string, value: string, options?: HostCookieSetOptions): void;
+}
+/**
+ * Register the host adapter's bridge. Idempotent and last-write-wins —
+ * host adapters register from side-effect imports, which may evaluate
+ * more than once across module graphs.
+ */
+export declare function registerHostRequestBridge(bridge: HostRequestBridge): void;
+/** The registered bridge, or `undefined` when no host has registered one. */
+export declare function tryGetHostRequestBridge(): HostRequestBridge | undefined;
+/**
+ * The registered bridge, throwing with setup guidance when absent. Cookie
+ * reads/writes require a host; scripts and tests that have no request
+ * should pass an explicit `requestContext` to `createBylineClient`
+ * instead of using the request-bound getters.
+ */
+export declare function getHostRequestBridge(): HostRequestBridge;

package/dist/host/host-request-bridge.js

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+const BYLINE_HOST_REQUEST_BRIDGE = Symbol.for('__byline_host_request_bridge__');
+/**
+ * Register the host adapter's bridge. Idempotent and last-write-wins —
+ * host adapters register from side-effect imports, which may evaluate
+ * more than once across module graphs.
+ */
+export function registerHostRequestBridge(bridge) {
+    ;
+    globalThis[BYLINE_HOST_REQUEST_BRIDGE] = bridge;
+}
+/** The registered bridge, or `undefined` when no host has registered one. */
+export function tryGetHostRequestBridge() {
+    return globalThis[BYLINE_HOST_REQUEST_BRIDGE] ?? undefined;
+}
+/**
+ * The registered bridge, throwing with setup guidance when absent. Cookie
+ * reads/writes require a host; scripts and tests that have no request
+ * should pass an explicit `requestContext` to `createBylineClient`
+ * instead of using the request-bound getters.
+ */
+export function getHostRequestBridge() {
+    const bridge = tryGetHostRequestBridge();
+    if (!bridge) {
+        throw new Error('No HostRequestBridge registered. A host adapter (e.g. ' +
+            '@byline/host-tanstack-start) must call registerHostRequestBridge() ' +
+            'at server boot before request-bound client getters can resolve ' +
+            'cookies. Scripts and tests should pass an explicit requestContext ' +
+            'to createBylineClient instead.');
+    }
+    return bridge;
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { type BylineCore, getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
+export { getHostRequestBridge, type HostCookieSetOptions, type HostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
 export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, type ErrorReport, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { type BylineLogger, getLogger } from './lib/logger.js';

package/dist/index.js

@@ -22,6 +22,7 @@ export { validateAdminConfigs } from './config/validate-admin-configs.js';
 export { RESERVED_FIELD_NAMES } from './config/validate-collections.js';
 export { getBylineCore, initBylineCore } from './core.js';
 export * from './defaults/default-values.js';
+export { getHostRequestBridge, registerHostRequestBridge, tryGetHostRequestBridge, } from './host/host-request-bridge.js';
 export { BylineError, ERR_AUDIT_UNSUPPORTED, ERR_CONFLICT, ERR_DATABASE, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_READ_RECURSION, ERR_STORAGE, ERR_TREE_HOOK_COMMITTED, ERR_UNHANDLED, ERR_VALIDATION, ErrorCodes, TREE_HOOK_COMMITTED_MARKER, TREE_PLACEMENT_STALE_MARKER, } from './lib/errors.js';
 export { generateKeyBetween, generateNKeysBetween, validateOrderKey, } from './lib/fractional-index.js';
 export { getLogger } from './lib/logger.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -81,7 +81,7 @@
     "pino": "^10.3.1",
     "sharp": "^0.35.3",
     "zod": "^4.4.3",
-    "@byline/auth": "4.0.0"
+    "@byline/auth": "4.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",