@byline/client 2.7.0 → 3.0.1

package/dist/collection-handle.js

@@ -57,6 +57,7 @@ export class CollectionHandle {
             pageSize,
             fields: select,
             readMode,
+            onMissingLocale: options.onMissingLocale ?? 'fallback',
         });
         await this.populateIfRequested(collectionId, result.documents, locale, readMode, requestContext, {
             ...options,
@@ -96,6 +97,7 @@ export class CollectionHandle {
             populate: options.populate,
             depth: options.depth,
             status: options.status,
+            onMissingLocale: options.onMissingLocale,
             _readContext: options._readContext,
             _bypassBeforeRead: options._bypassBeforeRead,
         });
@@ -119,6 +121,7 @@ export class CollectionHandle {
             readMode,
             filters,
             lenient: options.lenient,
+            onMissingLocale: options.onMissingLocale ?? 'fallback',
         });
         if (raw == null)
             return null;
@@ -158,6 +161,7 @@ export class CollectionHandle {
             reconstruct: true,
             readMode,
             filters,
+            onMissingLocale: options.onMissingLocale ?? 'fallback',
         });
         if (raw == null)
             return null;
@@ -202,6 +206,7 @@ export class CollectionHandle {
             locale: options.locale,
             status: options.status,
             path: options.path,
+            availableLocales: options.availableLocales,
         });
     }
     /**
@@ -216,6 +221,7 @@ export class CollectionHandle {
             data,
             locale: options.locale,
             path: options.path,
+            availableLocales: options.availableLocales,
         });
     }
     /**

package/dist/response.js

@@ -35,6 +35,25 @@ export function shapeDocument(raw) {
     if (Array.isArray(raw.restoreWarnings) && raw.restoreWarnings.length > 0) {
         shaped._restoreWarnings = raw.restoreWarnings;
     }
+    // The per-document content source locale (storage key `source_locale`).
+    if (typeof raw.source_locale === 'string') {
+        shaped.sourceLocale = raw.source_locale;
+    }
+    // Locale advertising + availability metadata. Present on
+    // find / findById / findByPath; absent on version/history reads.
+    // 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/I18N.md.
+    if (Array.isArray(raw.availableLocales)) {
+        shaped.availableLocales = raw.availableLocales;
+    }
+    if (Array.isArray(raw._availableVersionLocales)) {
+        shaped._availableVersionLocales = raw._availableVersionLocales;
+    }
+    if (typeof raw._localeAgnostic === 'boolean') {
+        shaped._localeAgnostic = raw._localeAgnostic;
+    }
     return shaped;
 }
 /**

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, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
 export type { FilterOperators, PredicateValue, QueryPredicate, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
@@ -138,6 +138,31 @@ interface PopulateControls {
 interface StatusControls {
     status?: ReadMode;
 }
+/**
+ * What a read does when the requested content locale is missing. Shared by
+ * every read method. `@byline/client` defaults this to `'fallback'`.
+ *
+ *   - `'fallback'` (client default) — always return content. A document
+ *     requested in a locale it has not been translated into falls back through
+ *     the locale chain to the default content locale: a detail read still
+ *     returns the document (rendered in the default locale); a list read still
+ *     includes it.
+ *   - `'empty'` — restore the requested locale exactly, leaving untranslated
+ *     localized fields empty (the raw per-locale view; what the admin editor
+ *     uses). The document is still returned.
+ *   - `'omit'` — only surface documents available in the requested locale. A
+ *     detail read returns `null` (so callers can 404); a list read excludes
+ *     untranslated documents (filtered at the SQL layer, so the page count and
+ *     `total` stay correct). A document with no localized content is available
+ *     in every locale.
+ *
+ * Availability is the version-grain ledger described in
+ * `docs/I18N.md`. Relationship population always behaves
+ * as `'fallback'` so a populated tree never has holes.
+ */
+interface MissingLocaleControls {
+    onMissingLocale?: MissingLocalePolicy;
+}
 /**
  * Read-side access-control escape hatch shared by every read method.
  *
@@ -153,7 +178,7 @@ interface StatusControls {
 interface BeforeReadControls {
     _bypassBeforeRead?: true;
 }
-export interface FindOptions<F = Record<string, any>> extends PopulateControls, StatusControls, BeforeReadControls {
+export interface FindOptions<F = Record<string, any>> extends PopulateControls, StatusControls, MissingLocaleControls, BeforeReadControls {
     /** Filter documents. Keys are field names or reserved names (status, path). */
     where?: WhereClause;
     /** Return only these fields. Omit for all fields. */
@@ -167,12 +192,12 @@ export interface FindOptions<F = Record<string, any>> extends PopulateControls,
     /** Documents per page. Defaults to 20. */
     pageSize?: number;
 }
-export interface FindOneOptions<F = Record<string, any>> extends PopulateControls, StatusControls, BeforeReadControls {
+export interface FindOneOptions<F = Record<string, any>> extends PopulateControls, StatusControls, MissingLocaleControls, BeforeReadControls {
     where?: WhereClause;
     select?: (keyof F & string)[] | string[];
     locale?: string;
 }
-export interface FindByIdOptions<F = Record<string, any>> extends PopulateControls, StatusControls, BeforeReadControls {
+export interface FindByIdOptions<F = Record<string, any>> extends PopulateControls, StatusControls, MissingLocaleControls, BeforeReadControls {
     select?: (keyof F & string)[] | string[];
     locale?: string;
     /**
@@ -185,7 +210,7 @@ export interface FindByIdOptions<F = Record<string, any>> extends PopulateContro
      */
     lenient?: boolean;
 }
-export interface FindByPathOptions<F = Record<string, any>> extends PopulateControls, StatusControls, BeforeReadControls {
+export interface FindByPathOptions<F = Record<string, any>> extends PopulateControls, StatusControls, MissingLocaleControls, BeforeReadControls {
     select?: (keyof F & string)[] | string[];
     locale?: string;
 }
@@ -228,6 +253,13 @@ export interface CreateOptions {
      * derives a path from `definition.useAsPath` (or falls back to a UUID).
      */
     path?: string;
+    /**
+     * 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/I18N.md`.
+     */
+    availableLocales?: string[];
 }
 export interface UpdateOptions {
     /** Locale for field value resolution. Defaults to the client's `defaultLocale`. */
@@ -237,6 +269,13 @@ export interface UpdateOptions {
      * carries forward unchanged (sticky).
      */
     path?: string;
+    /**
+     * 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/I18N.md`.
+     */
+    availableLocales?: string[];
 }
 /**
  * A where clause maps field names (or reserved document-level names like
@@ -292,6 +331,15 @@ export interface ClientDocument<F = Record<string, any>> {
     path: string;
     /** Workflow status (e.g. 'draft', 'published'). */
     status: string;
+    /**
+     * The document's content **source locale** — the locale it was authored in,
+     * and its per-document anchor (fallback floor, path locale, completeness
+     * 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/I18N.md`.
+     */
+    sourceLocale?: string;
     /** When this version was created. */
     createdAt: Date;
     /** When this version was last updated. */
@@ -307,6 +355,33 @@ export interface ClientDocument<F = Record<string, any>> {
      * normal reads.
      */
     _restoreWarnings?: string[];
+    /**
+     * The editorial *advertised* locale set — the content locales the editor
+     * has deliberately elected to promote for this document. Document-grain and
+     * stored (in `byline_document_available_locales`), sticky across versions —
+     * not derived. The deliberate counterpart to the structural
+     * `_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/I18N.md`.
+     */
+    availableLocales?: string[];
+    /**
+     * Content locales this document's resolved version is *structurally*
+     * available in — path-coverage against the default content locale, from the
+     * version-grain `byline_document_version_locales` ledger. Computed, read-only.
+     * 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/I18N.md`.
+     */
+    _availableVersionLocales?: string[];
+    /**
+     * `true` when the document has no localized content — it renders identically
+     * in every locale and `_availableVersionLocales` is empty. A per-document
+     * language affordance should render nothing in this case.
+     */
+    _localeAgnostic?: boolean;
 }
 export interface FindResult<F = Record<string, any>> {
     docs: ClientDocument<F>[];

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "2.7.0",
+  "version": "3.0.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -38,8 +38,8 @@
   ],
   "dependencies": {
     "npm-run-all": "^4.1.5",
-    "@byline/auth": "2.7.0",
-    "@byline/core": "2.7.0"
+    "@byline/auth": "3.0.1",
+    "@byline/core": "3.0.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
@@ -51,7 +51,7 @@
     "tsx": "^4.22.3",
     "typescript": "6.0.3",
     "vitest": "^4.1.7",
-    "@byline/db-postgres": "2.7.0"
+    "@byline/db-postgres": "3.0.1"
   },
   "publishConfig": {
     "access": "public",