@b10cks/client 1.8.0 → 1.10.0

package/dist/index.d.ts

@@ -240,6 +240,21 @@ export declare class B10cksDataApi {
     getCollection<T>(endpoint: Endpoint, params?: ApiQueryParams, options?: CollectionFetchOptions): Promise<T[]>;
     getContent<T = Record<string, unknown>>(fullSlug: string, params?: Omit<IBContentQueryParams, 'token' | 'full_slug'>): Promise<IBContent<T>>;
     getContents<T = Record<string, unknown>>(params?: IBGetContentsParams, options?: CollectionFetchOptions): Promise<IBContent<T>[]>;
+    /**
+     * The ancestor trail of an entry, ordered from the tree root down to the
+     * entry itself. Addressed by full slug or by content id.
+     *
+     * Unpublished ancestors are omitted rather than blanked, so the position in
+     * the trail is not the position in the tree — read `depth` for that, and pass
+     * `ancestors: 'all'` when structural levels are never published by design.
+     */
+    getBreadcrumb<T = Record<string, unknown>>(slug: string, params?: IBBreadcrumbParams): Promise<IBBreadcrumbLevel<T>[]>;
+    /**
+     * Like {@link getBreadcrumb}, but keeps the response's `meta` block — the
+     * resolved language, its fallback, the space's i18n mode, and the root and
+     * current ids.
+     */
+    getBreadcrumbResponse<T = Record<string, unknown>>(slug: string, params?: IBBreadcrumbParams): Promise<IBBreadcrumbResponse<T>>;
     getBlock(blockId: string, params?: ApiQueryParams): Promise<IBBlock>;
     getBlocks(params?: IBGetBlocksParams, options?: CollectionFetchOptions): Promise<IBBlock[]>;
     search<T = Record<string, unknown>>(params: IBSearchParams): Promise<IBSearchResponse<T>>;
@@ -250,7 +265,7 @@ export declare class B10cksDataApi {
      * separate one for news. Unknown names respond with 404.
      */
     getNamedSitemap(name: string, params?: Omit<IBContentQueryParams, 'token'>, options?: CollectionFetchOptions): Promise<IBSitemapEntry[]>;
-    getDataEntries(source: string, params?: ApiQueryParams, options?: CollectionFetchOptions): Promise<IBDataEntry[]>;
+    getDataEntries(source: string, params?: IBDataEntryParams, options?: CollectionFetchOptions): Promise<IBDataEntry[]>;
     getDataSources(params?: ApiQueryParams, options?: CollectionFetchOptions): Promise<IBDataSource[]>;
     getSpace(params?: ApiQueryParams): Promise<IBSpace>;
     lookupRedirect(source: string): Promise<IBRedirectLookupResult | false>;
@@ -302,6 +317,35 @@ export declare interface B10cksLinkResolved {
  */
 export declare function bindPreviewStore<T>(store: PreviewStore<T>): () => void;
 
+/**
+ * Renders a trail as a schema.org `BreadcrumbList`, ready to be serialized into
+ * an `application/ld+json` script tag.
+ *
+ * `position` numbers the emitted items consecutively — unlike a level's `depth`,
+ * which is its position in the content tree and may skip a dropped ancestor.
+ */
+export declare function breadcrumbJsonLd<T>(levels: IBBreadcrumbLevel<T>[], options?: BreadcrumbJsonLdOptions): BreadcrumbListJsonLd;
+
+export declare interface BreadcrumbJsonLdOptions {
+    /** Absolute base URL. Without it, `item` carries the relative path. */
+    siteUrl?: string;
+    /** Drop the current entry from the list. Defaults to `false` — Google expects it. */
+    excludeCurrent?: boolean;
+}
+
+export declare interface BreadcrumbListItem {
+    '@type': 'ListItem';
+    position: number;
+    name: string;
+    item: string;
+}
+
+export declare interface BreadcrumbListJsonLd {
+    '@context': 'https://schema.org';
+    '@type': 'BreadcrumbList';
+    itemListElement: BreadcrumbListItem[];
+}
+
 export declare type BridgeEvent = {
     type: EventType;
     payload: EventPayloadMap[EventType];
@@ -369,7 +413,7 @@ export declare type DateFilter = string | {
 
 export declare type EditableFieldMode = 'inline' | 'select';
 
-export declare type Endpoint = 'blocks' | `blocks/${string}` | 'contents' | `contents/${string}` | `datasources/${string}/entries` | 'datasources' | 'redirects' | 'search' | 'sitemap' | `sitemaps/${string}` | 'spaces/me';
+export declare type Endpoint = 'blocks' | `blocks/${string}` | `breadcrumbs/${string}` | 'contents' | `contents/${string}` | `datasources/${string}/entries` | 'datasources' | 'redirects' | 'search' | 'sitemap' | `sitemaps/${string}` | 'spaces/me';
 
 /**
  * Inject the preview outline styles once. Selected/hovered blocks get an
@@ -422,11 +466,18 @@ export declare type FieldUpdateEvent = {
  */
 export declare function filterSitemapEntries(entries: IBSitemapEntry[], options?: SitemapFilterOptions): IBSitemapEntry[];
 
+/**
+ * Depth-first search for the path to the node carrying `id`. The root node
+ * itself is not considered a match — callers handle the root explicitly.
+ */
+export declare function findPathById(root: unknown, id: string): FieldPath | null;
+
 /** Read the value at `path` within `target`, or undefined if absent. */
 export declare function getAtPath(target: unknown, path: FieldPath): unknown;
 
 export declare interface GetConfigOptions extends Omit<IBContentQueryParams, 'token' | 'full_slug'> {
     slug?: string;
+    /** @deprecated Use `language_iso`, matching every other content param. */
     language?: string;
     bypassCache?: boolean;
 }
@@ -434,6 +485,12 @@ export declare interface GetConfigOptions extends Omit<IBContentQueryParams, 'to
 export declare interface IBBaseQueryParams extends IBPaginationParams, IBSortParams {
     vid?: string;
     version?: string;
+    /**
+     * Content revision to read at. Defaults to the client's current revision;
+     * pass it explicitly to pin a request (or `Date.now()` to bypass the
+     * delivery cache from a server route).
+     */
+    rv?: string | number;
     token: string;
 }
 
@@ -458,6 +515,98 @@ export declare interface IBBlockFilter {
     updated_at?: DateFilter;
 }
 
+/**
+ * One level of a breadcrumb trail.
+ *
+ * A level is resolved through its own i18n family, so an untranslated ancestor
+ * is served from the fallback language and flagged (`is_fallback`) rather than
+ * dropped.
+ */
+export declare interface IBBreadcrumbLevel<Content = IBContentBlock<string> & {
+    [index: string]: unknown;
+}> {
+    id: string;
+    external_id: string | null;
+    name: string;
+    slug: string;
+    /** Stored path of this level, without a locale segment. */
+    full_slug: string;
+    /** Delivery path, with the *requested* language's locale segment applied. */
+    path: string;
+    /** Slug of the assigned block definition. */
+    block: string | null;
+    parent_id: string | null;
+    position: number;
+    /**
+     * Depth in the content tree, 0 for the root — not the index in the trail. A
+     * gap in the sequence is where an unpublished ancestor was dropped.
+     */
+    depth: number;
+    is_root: boolean;
+    /** True for the entry the trail was requested for. */
+    is_current: boolean;
+    /** The requested language. */
+    language_iso: string;
+    /** The language this level was actually served from. */
+    resolved_language_iso: string;
+    is_fallback: boolean;
+    is_published: boolean;
+    published_at: string | null;
+    updated_at: string | null;
+    /** Only present when requested with `include_content`. */
+    content?: Content;
+    /** Only present when requested with `translations`. */
+    translations?: IBBreadcrumbTranslation[];
+}
+
+export declare interface IBBreadcrumbMeta {
+    language_iso: string;
+    fallback_language_iso: string | null;
+    i18n_mode: 'overlay' | 'independent';
+    levels: number;
+    root_id: string | null;
+    current_id: string | null;
+}
+
+export declare interface IBBreadcrumbParams {
+    /** Language every level is resolved for. Unknown values fall back to the space default. */
+    language?: string;
+    language_iso?: string;
+    /** A version id is not accepted here — every level is a different entry. */
+    vid?: 'published' | 'draft';
+    /** Include the requested entry as the last level. Defaults to `true`. */
+    include_self?: boolean;
+    /** `all` keeps unpublished ancestors, which are dropped by default. */
+    ancestors?: 'published' | 'all';
+    /** Add published sibling translations to every level. */
+    translations?: boolean;
+    /** Add the resolved `content` payload to every level; honors `take`/`except`. */
+    include_content?: boolean;
+    /** Comma-separated field whitelist for `include_content`. */
+    take?: string;
+    /** Comma-separated field blacklist for `include_content`. */
+    except?: string;
+}
+
+export declare interface IBBreadcrumbResponse<Content = IBContentBlock<string> & {
+    [index: string]: unknown;
+}> {
+    /** The trail, ordered from the tree root down to the requested entry. */
+    breadcrumb: IBBreadcrumbLevel<Content>[];
+    meta: IBBreadcrumbMeta;
+    rv?: string | number;
+}
+
+/** A published sibling translation of a breadcrumb level. */
+export declare interface IBBreadcrumbTranslation {
+    language_iso: string;
+    name: string | null;
+    /** Stored path of the translation, without a locale segment. */
+    full_slug: string;
+    /** Delivery path of the translation, with its own locale segment applied. */
+    path: string;
+}
+
 export declare interface IBCollectionResponse<T> {
     data: T[];
     rv?: string | number;
@@ -532,6 +681,14 @@ export declare interface IBDataEntry {
     updated_at: string;
 }
 
+export declare type IBDataEntryParams = Omit<IBBaseQueryParams, 'token'> & {
+    /**
+     * Serves the entries mutated for this dimension (usually a locale), falling
+     * back to the stored base value for keys the dimension does not override.
+     */
+    dimension?: string;
+};
+
 export declare interface IBDataSource {
     id: string;
     name: string;
@@ -665,6 +822,26 @@ export declare type IdFilter = string | {
 
 declare type Listener = () => void;
 
+/**
+ * Merge a `CONTENT_UPDATE` payload into an existing content tree.
+ *
+ * The editor sends updates scoped to the edited item — the payload is the block
+ * that changed, carrying its own `id` — and only sends the whole tree when the
+ * root block itself is edited (as `{ id: entryId, ...entryContent }`). Blindly
+ * assigning the payload as the new root therefore collapses the page to the
+ * edited block, so the payload is instead matched by `id`:
+ *
+ * - payload without an `id` → treated as the whole tree (legacy/whole-tree push)
+ * - payload id equal to the root's id → replaces the root
+ * - payload id found in the tree → replaces that node in place, immutably
+ * - payload id found nowhere → ignored (an update for a block not rendered here)
+ *
+ * When the root is rendered without its entry id (`entry.content` alone, so the
+ * root has no `id` to match) an update that matches nothing nested but has the
+ * same `block` type as the root is taken as the root.
+ */
+export declare function mergeContentUpdate<T>(root: T, update: Record<string, unknown>): T;
+
 export declare function normalizePathSegment(value: string | null | undefined): string;
 
 export declare class PreviewBridge {
@@ -706,7 +883,7 @@ export declare interface PreviewBridgeInitOptions {
 
 /**
  * A framework-agnostic, reactive holder for the content tree shown in the
- * preview. The editor pushes whole-tree (`CONTENT_UPDATE`) or granular
+ * preview. The editor pushes block-scoped (`CONTENT_UPDATE`) or granular
  * (`CONTENT_PATCH`) changes; subscribers re-render from the new snapshot.
  */
 export declare class PreviewStore<T = Record<string, unknown>> {
@@ -716,6 +893,12 @@ export declare class PreviewStore<T = Record<string, unknown>> {
     subscribe: (listener: Listener) => (() => void);
     getSnapshot: () => T;
     setContent(next: T): void;
+    /**
+     * Apply an editor `CONTENT_UPDATE` payload. See {@link mergeContentUpdate}:
+     * scoped payloads are merged by `id` instead of replacing the whole tree.
+     * Unknown ids are ignored and do not notify subscribers.
+     */
+    applyContentUpdate(update: Record<string, unknown>): void;
     patch(path: FieldPath, value: unknown): void;
     private emit;
 }
@@ -737,8 +920,11 @@ export declare function renderSitemapIndex(paths: string[], siteUrl?: string): s
 /**
  * Renders `IBSitemapEntry[]` as a `<urlset>` XML string.
  * Pass `siteUrl` to emit absolute `<loc>` values; without it, relative paths are used.
+ *
+ * Locale prefixing follows {@link SitemapPathOptions.localePrefix}, which
+ * defaults to `auto` — a mono-lingual entry set is emitted unprefixed.
  */
-export declare function renderSitemapXml(entries: IBSitemapEntry[], siteUrl?: string): string;
+export declare function renderSitemapXml(entries: IBSitemapEntry[], siteUrl?: string, options?: SitemapPathOptions): string;
 
 /**
  * Resolves a B10cksLink value to a plain { href, target } object.
@@ -751,6 +937,11 @@ export declare function renderSitemapXml(entries: IBSitemapEntry[], siteUrl?: st
  */
 export declare function resolveB10cksLink(link: B10cksLink | undefined | null): B10cksLinkResolved | undefined;
 
+export declare type RootBlock<T> = T & {
+    id: string;
+    block: string;
+};
+
 export declare type SelectUpdateEvent = {
     selectedItem: string;
 };
@@ -767,13 +958,34 @@ export declare function setAtPath<T>(target: T, path: FieldPath, value: unknown)
  */
 export declare function setPreviewScrollOffset(offset: number | string): void;
 
-export declare interface SitemapFilterOptions {
+export declare interface SitemapFilterOptions extends SitemapPathOptions {
     /** Absolute base URL used for deduplication. Without it, paths are compared as strings. */
     siteUrl?: string;
     /** Only include entries for this locale (ISO code). */
     locale?: string;
 }
 
+/**
+ * How a locale segment is applied to an entry's stored `full_slug`. The SDK
+ * cannot infer the consuming app's routing, so this mirrors the usual i18n
+ * strategies.
+ *
+ * - `auto` (default) prefixes only when the entries span more than one
+ *   `language_iso`. A mono-lingual space is served at `/about`, not `/en/about`,
+ *   even though its entries still carry a language.
+ * - `always` prefixes every entry.
+ * - `never` uses paths as stored, for an app that routes the locale some other
+ *   way (a route param, a domain).
+ * - `except-default` prefixes every locale but {@link SitemapPathOptions.defaultLocale}.
+ */
+export declare type SitemapLocalePrefix = 'auto' | 'always' | 'never' | 'except-default';
+
+export declare interface SitemapPathOptions {
+    localePrefix?: SitemapLocalePrefix;
+    /** The unprefixed locale under `localePrefix: 'except-default'`. */
+    defaultLocale?: string;
+}
+
 export declare type StringFilter = string | {
     eq: string;
 } | {
@@ -789,13 +1001,30 @@ export declare type StringFilter = string | {
 } | {
     '^like': string;
 } | {
-    'like$': string;
+    like$: string;
 } | {
     null: true;
 } | {
     '!null': true;
 };
 
+/**
+ * Flatten a content entry into a renderable root block.
+ *
+ * An entry's `content` object carries `block` but not `id` — the id lives on the
+ * entry. Rendering `entry.content` directly therefore yields a root block the
+ * visual editor cannot address: `v-editable` no-ops on it, and the editor's
+ * root-level `CONTENT_UPDATE` (sent as `{ id: entryId, … }`) matches nothing.
+ * Use this helper to carry the entry id into the tree:
+ *
+ * ```ts
+ * const block = toRootBlock(entry) // { ...entry.content, id, block }
+ * ```
+ */
+export declare function toRootBlock<T extends Record<string, unknown>>(entry: IBContent<T>): RootBlock<T>;
+
+export declare function toRootBlock<T extends Record<string, unknown>>(entry: IBContent<T> | null | undefined): RootBlock<T> | null;
+
 export declare namespace types {
     export {
         FetchClient,
@@ -809,7 +1038,13 @@ export declare namespace types {
         IBContentRelation,
         IBContent,
         IBContentBlock,
+        IBBreadcrumbTranslation,
+        IBBreadcrumbLevel,
+        IBBreadcrumbMeta,
+        IBBreadcrumbResponse,
+        IBBreadcrumbParams,
         IBDataEntry,
+        IBDataEntryParams,
         IBPaginationParams,
         IBSortParams,
         IBBaseQueryParams,