@carlonicora/nextjs-jsonapi 3.12.0 → 3.14.0

package/dist/core/index.d.mts

@@ -8,28 +8,28 @@ import { A as AbstractService, N as NextRef, P as PreviousRef } from '../Abstrac
 export { H as HttpMethod, S as SelfRef, T as TotalRef, b as clearLastApiMeta, c as clearLastApiTotal, d as getGlobalErrorHandler, a as getLastApiMeta, g as getLastApiTotal, s as setGlobalErrorHandler } from '../AbstractService-B0T7h8fX.mjs';
 import { M as ModuleWithPermissions, g as PermissionUser, A as Action, f as PermissionModule, a as ModuleFactory } from '../types-Bq_UA8Lg.mjs';
 export { d as ModuleDefinition, c as ModulePermissionDefinition, P as PageUrl, b as PermissionCheck, e as PermissionConfig } from '../types-Bq_UA8Lg.mjs';
-import { a as HowToInterface, H as HowToInput, d as AssistantMessageInterface, A as AssistantMessageRole, e as ChunkInterface, C as ChunkRelationshipMeta, b as AssistantMessageType, c as AssistantMessageInput } from '../AssistantMessageInterface-ddyG114R.mjs';
-export { B as BreadcrumbItemData } from '../AssistantMessageInterface-ddyG114R.mjs';
+import { a as HowToInterface, H as HowToInput, d as AssistantMessageInterface, A as AssistantMessageRole, e as ChunkInterface, C as ChunkRelationshipMeta, b as AssistantMessageType, c as AssistantMessageInput } from '../AssistantMessageInterface-Du3ShThp.mjs';
+export { B as BreadcrumbItemData } from '../AssistantMessageInterface-Du3ShThp.mjs';
 export { C as ContentFields, D as D3Link, a as D3Node, R as RoleFields, U as UserFields } from '../content.fields-1AlHDtDb.mjs';
 import { ClassValue } from 'clsx';
 export { ClassValue } from 'clsx';
 import * as React from 'react';
 import { ReactElement, ReactNode, JSXElementConstructor } from 'react';
 import { z } from 'zod';
-import { T as TotpAuthenticatorInterface, P as PasskeyInterface } from '../ai-connection.module-28f-hux0.mjs';
-export { h as AiConnection, l as AiConnectionEnvDefaults, i as AiConnectionFields, n as AiConnectionInput, m as AiConnectionInterface, p as AiConnectionModule, o as AiConnectionService, j as AiProviderFieldDescriptor, k as AiProviderRegistry, A as AuthComponent, b as getIcon, a as getIconByModule, c as getIconByModuleName, g as getInitials, d as getLucideIcon, e as getLucideIconByModule, f as getLucideIconByModuleName } from '../ai-connection.module-28f-hux0.mjs';
+import { T as TotpAuthenticatorInterface, P as PasskeyInterface, H as HandbookPageInterface, q as HandbookSectionInterface } from '../HandbookSectionInterface-BOxIdBdd.mjs';
+export { h as AiConnection, l as AiConnectionEnvDefaults, i as AiConnectionFields, n as AiConnectionInput, m as AiConnectionInterface, p as AiConnectionModule, o as AiConnectionService, j as AiProviderFieldDescriptor, k as AiProviderRegistry, A as AuthComponent, b as getIcon, a as getIconByModule, c as getIconByModuleName, g as getInitials, d as getLucideIcon, e as getLucideIconByModule, f as getLucideIconByModuleName } from '../HandbookSectionInterface-BOxIdBdd.mjs';
 import { PartialBlock } from '@blocknote/core';
 import { ExternalToast } from 'sonner';
-import { e as RoleInterface, R as RoleInput, U as UserInterface, c as CompanyInterface, f as UserInput, b as CompanyInput, C as ContentInterface, a as ContentInput, N as NotificationInterface, d as NotificationInput } from '../notification.interface-BWOCvKRP.mjs';
-import { b as AuthInterface, A as AuthInput } from '../auth.interface-jYD8Gc4P.mjs';
-export { a as AuthQuery } from '../auth.interface-jYD8Gc4P.mjs';
-import { T as TwoFactorChallengeInterface, c as S3Interface, b as S3Input } from '../s3.service-D_dswjgz.mjs';
-export { A as AuthService, C as CompanyService, a as ContentService, F as FeatureService, N as NotificationService, P as PushService, R as RoleService, S as S3Service, U as UserService } from '../s3.service-D_dswjgz.mjs';
+import { e as RoleInterface, R as RoleInput, U as UserInterface, c as CompanyInterface, f as UserInput, b as CompanyInput, C as ContentInterface, a as ContentInput, N as NotificationInterface, d as NotificationInput } from '../notification.interface-MnRt1Tjm.mjs';
+import { b as AuthInterface, A as AuthInput } from '../auth.interface-dR2-6gPM.mjs';
+export { a as AuthQuery } from '../auth.interface-dR2-6gPM.mjs';
+import { T as TwoFactorChallengeInterface, c as S3Interface, b as S3Input } from '../s3.service-C0Yq2Sx3.mjs';
+export { A as AuthService, C as CompanyService, a as ContentService, F as FeatureService, N as NotificationService, P as PushService, R as RoleService, S as S3Service, U as UserService } from '../s3.service-C0Yq2Sx3.mjs';
 import { PublicKeyCredentialCreationOptionsJSON, RegistrationResponseJSON, PublicKeyCredentialRequestOptionsJSON, AuthenticationResponseJSON } from '@simplewebauthn/browser';
 import { M as MeterInterface, o as MeterSummaryInterface, P as PaymentMethodInterface, S as StripeCustomerInterface, a as StripeInvoiceInterface, j as StripeSubscriptionInterface, I as InvoiceStatus, g as StripeProductInterface, d as StripePriceInterface, h as StripeProductInput, e as PriceRecurring, f as StripePriceInput, i as SubscriptionStatus, k as StripeSubscriptionInput, m as StripeSubscriptionCreateResponse, b as ProrationPreviewInterface, n as StripeUsageInterface, R as ReportUsageInput, U as UsageSummaryInterface, q as PromotionCodeValidationResult } from '../stripe-promotion-code.interface-ClZ7DxS9.mjs';
 export { c as ProrationLineItem, l as StripeSubscriptionCreateMeta, p as UsageRecordInterface } from '../stripe-promotion-code.interface-ClZ7DxS9.mjs';
 import { M as ModuleInterface, F as FeatureInterface } from '../feature.interface-CXb1-vNq.mjs';
-import { a as AssistantInterface, A as AssistantInput } from '../AssistantInterface-DMh-zApr.mjs';
+import { a as AssistantInterface, A as AssistantInput } from '../AssistantInterface-jL56dyNc.mjs';
 import { O as OAuthClientInterface, a as OAuthClientInput, b as OAuthClientCreateRequest, c as OAuthClientCreateResponse, d as OAuthConsentRequest, f as OAuthConsentInfo } from '../oauth.interface-DRE3NAKc.mjs';
 export { A as AVAILABLE_OAUTH_SCOPES, D as DEFAULT_GRANT_TYPES, g as OAUTH_SCOPE_DISPLAY, e as OAuthScopeInfo } from '../oauth.interface-DRE3NAKc.mjs';
 export { b as TokenUsageAdminBreakdownModule, T as TokenUsageAdminSummaryModule, a as TokenUsageAdminTimelineModule, c as configureTokenUsage, g as getTokenUsageCurrency, t as tokenUsageModules } from '../config-n-ZpPmOL.mjs';
@@ -259,6 +259,10 @@ interface FoundationModuleDefinitions {
     Module: ModuleWithPermissions;
     Content: ModuleWithPermissions;
     HowTo: ModuleWithPermissions;
+    HandbookPage: ModuleWithPermissions;
+    HandbookSection: ModuleWithPermissions;
+    HandbookThread: ModuleWithPermissions;
+    HandbookThreadMessage: ModuleWithPermissions;
     Assistant: ModuleWithPermissions;
     AssistantMessage: ModuleWithPermissions;
     AssistantAction: ModuleWithPermissions;
@@ -1917,6 +1921,12 @@ declare class HowToService extends AbstractService {
     static delete(params: {
         howToId: string;
     }): Promise<void>;
+    /**
+     * POST /howtos/reindex — re-queues every guide for chunking. Replies 204.
+     * Chunking otherwise only happens on create and update, so a guide that was
+     * never chunked stays invisible to help-mode retrieval with no way back.
+     */
+    static reindex(): Promise<void>;
     static findPublished(params?: {
         howToType?: string;
     }): Promise<HowToInterface[]>;
@@ -1938,6 +1948,452 @@ declare class HowToService extends AbstractService {
     }): Promise<void>;
 }
 
+declare const HandbookPageModule: (factory: ModuleFactory) => ModuleWithPermissions;
+
+/**
+ * One top-level directory of the documentation tree. Like the thread message,
+ * it has no `pageUrl` — a section has no page of its own; it is a heading on
+ * the contents surface and nothing more.
+ */
+declare const HandbookSectionModule: (factory: ModuleFactory) => ModuleWithPermissions;
+
+/**
+ * One turn of a handbook conversation. Like the thread, it has no `pageUrl` —
+ * a message is only ever read as part of its thread.
+ */
+declare const HandbookThreadMessageModule: (factory: ModuleFactory) => ModuleWithPermissions;
+
+/**
+ * A persisted handbook conversation.
+ *
+ * It carries no `pageUrl`: a thread is selected inside the ask surface
+ * (`/administration/handbook/chat`), never routed to on its own, and a
+ * `pageUrl` here would add a phantom entry to the RBAC path map.
+ *
+ * `lists` deliberately narrows to the title — the sidebar renders nothing else,
+ * and side-loading every message of every thread into the list payload is what
+ * the single-resource endpoint is for.
+ */
+declare const HandbookThreadModule: (factory: ModuleFactory) => ModuleWithPermissions;
+
+/**
+ * The handbook is INDEXED in English and SHOWN translated.
+ *
+ * A page's translation lives on the same node as its English original — matched
+ * by `path` at ingest time — and arrives as ordinary attributes beside it.
+ * There is no second id, no locale in any URL and no second resource, so
+ * nothing about ordering, grouping or section membership changes: `path`,
+ * `order` and `section` stay English and are still what every sort reads. Only
+ * the rendered words are resolved here.
+ *
+ * These five functions are the ONE place that resolution happens. A component
+ * reaching for `page.title` directly renders English to an Italian reader, and
+ * a per-component `??` would be five copies of the same rule to keep in step.
+ *
+ * Each parameter is a `Pick` of the interface rather than the whole of it, so a
+ * caller holding a projection — a row from a sparse fieldset, a spec fixture —
+ * passes it without a cast, while a rename on either interface still breaks
+ * this file rather than drifting from it.
+ */
+/** The page title to render: the translation when there is one, else English. */
+declare function handbookPageTitle(page: Pick<HandbookPageInterface, "title" | "displayTitle">): string;
+/** The page's one-line description, translated when the ingest matched one. */
+declare function handbookPageSummary(page: Pick<HandbookPageInterface, "summary" | "displaySummary">): string | undefined;
+/**
+ * The markdown body to render. Detail-only, exactly as `content` is:
+ * `displayContent` is the whole file and is absent from every list payload, so
+ * this is never called on a row that came out of a list read.
+ */
+declare function handbookPageContent(page: Pick<HandbookPageInterface, "content" | "displayContent">): string;
+/** The section heading to render, translated when the ingest matched one. */
+declare function handbookSectionTitle(section: Pick<HandbookSectionInterface, "title" | "displayTitle">): string;
+/** The section blurb to render, translated when the ingest matched one. */
+declare function handbookSectionSummary(section: Pick<HandbookSectionInterface, "summary" | "displaySummary">): string | undefined;
+
+/**
+ * Handbook pages are created by the backend ingest from files, never by a
+ * client. The input therefore carries identity only — it exists so the model
+ * satisfies AbstractApiData's contract, not because anything writes attributes.
+ */
+type HandbookPageInput = {
+    id: string;
+};
+
+declare class HandbookPage extends AbstractApiData implements HandbookPageInterface {
+    private _path?;
+    private _title?;
+    private _content?;
+    private _contentHash?;
+    private _wordCount?;
+    private _aiStatus?;
+    private _section?;
+    private _order?;
+    private _summary?;
+    private _displayTitle?;
+    private _displaySummary?;
+    private _displayContent?;
+    get path(): string;
+    get title(): string;
+    get content(): string;
+    get contentHash(): string;
+    get wordCount(): number;
+    get aiStatus(): string | undefined;
+    get section(): string;
+    get order(): string;
+    get summary(): string | undefined;
+    get displayTitle(): string | undefined;
+    get displaySummary(): string | undefined;
+    get displayContent(): string | undefined;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: HandbookPageInput): any;
+}
+
+/**
+ * An ENUM, not a string array: `ContentListTable` indexes its column map by
+ * these members and `useDataListRetriever` keys rows by the id member, exactly
+ * as HowToFields does.
+ *
+ * `content` and `contentHash` are deliberately absent: they are detail-only,
+ * and a list of a thousand markdown files must not carry their bodies.
+ * `displayContent` — the same body in the reader's language — carries the same
+ * caveat: it names the field for the detail read and is deliberately NOT in the
+ * module's list inclusion.
+ *
+ * `section`, `order` and `summary` are list-safe for the opposite reason: they
+ * are the index fields the contents page groups, orders and describes pages by,
+ * so a list that omitted them could not render a table of contents at all.
+ * `displayTitle` and `displaySummary` travel with them: the manual is indexed
+ * in English and shown translated, so the contents page needs both halves.
+ */
+declare enum HandbookPageFields {
+    handbookPageId = "handbookPageId",
+    path = "path",
+    title = "title",
+    displayTitle = "displayTitle",
+    section = "section",
+    order = "order",
+    summary = "summary",
+    displaySummary = "displaySummary",
+    displayContent = "displayContent",
+    wordCount = "wordCount",
+    aiStatus = "aiStatus"
+}
+
+declare class HandbookPageService extends AbstractService {
+    /**
+     * `next` / `prev` are not optional extras: `useDataListRetriever` drives
+     * pagination by handing the cursor back here, so a findMany that drops them
+     * renders exactly one page and no navigation, however many rows exist.
+     * Mirrors HowToService.findMany.
+     */
+    static findMany(params?: {
+        search?: string;
+        fetchAll?: boolean;
+        next?: NextRef;
+        prev?: PreviousRef;
+    }): Promise<HandbookPageInterface[]>;
+    static findOne(params: {
+        id: string;
+    }): Promise<HandbookPageInterface>;
+    /** POST /handbookpages/sync — replies 204; the caller refetches the list. */
+    static sync(): Promise<void>;
+    static delete(params: {
+        id: string;
+    }): Promise<void>;
+}
+
+/**
+ * Handbook sections are written only by the backend ingest, which replaces
+ * every one of them on each sync. No client ever posts one; this type exists so
+ * the model can satisfy AbstractApiData's `createJsonApi()` contract.
+ */
+type HandbookSectionInput = {
+    id: string;
+    key: string;
+    title: string;
+    summary?: string;
+    order: string;
+};
+
+declare class HandbookSection extends AbstractApiData implements HandbookSectionInterface {
+    private _key?;
+    private _title?;
+    private _summary?;
+    private _order?;
+    private _displayTitle?;
+    private _displaySummary?;
+    get key(): string;
+    get title(): string;
+    get summary(): string | undefined;
+    get order(): string;
+    get displayTitle(): string | undefined;
+    get displaySummary(): string | undefined;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    /**
+     * Nothing calls this: sections are read-only over HTTP and written only by
+     * the ingest. It exists because every model implements `createJsonApi()`, and
+     * a model that throws on serialisation is a trap for the next writer.
+     */
+    createJsonApi(data: HandbookSectionInput): any;
+}
+
+declare class HandbookSectionService extends AbstractService {
+    /**
+     * Every section in one read, always.
+     *
+     * There are as many sections as an application has documentation directories
+     * — ten or so — so this takes no `fetchAll` argument and no cursor: unlike
+     * the page list, nothing here is ever a second page, and a caller that could
+     * ask for one page of sections would only be able to get it wrong.
+     */
+    static findMany(): Promise<HandbookSectionInterface[]>;
+}
+
+/**
+ * One turn of a persisted handbook conversation.
+ *
+ * It extends `AssistantMessageInterface` rather than restating it: the shared
+ * chat components (`AssistantThread` → `MessageList` → `MessageItem`) are typed
+ * against that interface and take their data as plain props, so a handbook
+ * message that satisfies the same structural contract renders through them with
+ * no adapter. Everything the handbook has no concept of — token counts,
+ * references, citations, approval actions — is answered with the empty value.
+ *
+ * `sources` is the handbook's own addition: repo-relative page paths, in the
+ * order retrieval returned them.
+ */
+interface HandbookThreadMessageInterface extends AssistantMessageInterface {
+    get sources(): string[];
+}
+/**
+ * The payload of one question appended to an existing thread. `id` is the
+ * client-generated identity every model input in this framework carries; the
+ * append endpoint derives role and position server-side, so the envelope the
+ * model builds sends only `question`.
+ */
+type HandbookThreadMessageInput = {
+    id: string;
+    question: string;
+    /**
+     * Scopes retrieval to one handbook page. Set only by the reader's ask sheet,
+     * when the reader turns the "this page only" chip on; absent everywhere else,
+     * and the agent then searches the whole manual.
+     */
+    handbookPageId?: string;
+};
+
+/**
+ * A persisted handbook conversation.
+ *
+ * It extends `AssistantInterface` so the shared chat chrome —
+ * `AssistantSidebar`, `AssistantThreadHeader`, `groupThreadsByBucket` — accepts
+ * it verbatim. It is NOT an Assistant: an Assistant is company scoped and a
+ * platform administrator has no company, so the handbook owns its own threads
+ * and answers `engine` / `boundContentType` / `boundContentId` with `undefined`.
+ */
+interface HandbookThreadInterface extends AssistantInterface {
+    /** Side-loaded by `GET /handbookthreads/:id`; empty on the list endpoint. */
+    get messages(): HandbookThreadMessageInterface[];
+}
+/**
+ * The payload that opens a thread: the first question. The server derives the
+ * title from it, so nothing else is sent.
+ */
+type HandbookThreadInput = {
+    id: string;
+    question: string;
+    /**
+     * Scopes retrieval to one handbook page. Set only by the reader's ask sheet,
+     * when the reader turns the "this page only" chip on; absent everywhere else,
+     * and the agent then searches the whole manual.
+     */
+    handbookPageId?: string;
+};
+
+declare class HandbookThread extends AbstractApiData implements HandbookThreadInterface {
+    private _title?;
+    private _messageCount?;
+    private _messages?;
+    get title(): string;
+    get messageCount(): number;
+    /**
+     * The handbook runs one agent and has no engine choice, so nothing routes on
+     * this. It exists because `AssistantInterface` declares it, which is what
+     * lets the shared chat chrome take a handbook thread unchanged.
+     */
+    get engine(): string | undefined;
+    /** A handbook thread is never bound to a product resource. */
+    get boundContentType(): string | undefined;
+    get boundContentId(): string | undefined;
+    get messages(): HandbookThreadMessageInterface[];
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    /**
+     * The envelope `POST /handbookthreads` accepts: the opening question. The
+     * server derives the title from it, so no title is sent and no client id —
+     * the thread's identity is the server's to mint.
+     *
+     * `handbookPageId` rides the same way `question` does, through this method
+     * and never through `overridesJsonApiCreation`. It is written only when the
+     * caller supplied it: the DTO takes it as optional, and sending an explicit
+     * `null` would fail validation rather than mean "the whole manual".
+     */
+    createJsonApi(data: HandbookThreadInput): {
+        data: {
+            type: string;
+            attributes: {
+                handbookPageId?: string | undefined;
+                question: string;
+            };
+        };
+        included: never[];
+    };
+    /**
+     * The envelope `PATCH /handbookthreads/:id` accepts. A dedicated method
+     * rather than a branch inside `createJsonApi`: the rename sends the title and
+     * nothing else, while a create sends the question and nothing else, and the
+     * service must never hand-build either.
+     */
+    createRenameJsonApi(params: {
+        id: string;
+        title: string;
+    }): {
+        data: {
+            type: string;
+            id: string;
+            attributes: {
+                title: string;
+            };
+        };
+        included: never[];
+    };
+}
+
+/**
+ * One persisted handbook turn.
+ *
+ * The getters below are the structural contract `AssistantMessageInterface`
+ * asks for, which is what lets `AssistantThread` render handbook messages with
+ * no adapter. The handbook has no token accounting, no entity references, no
+ * chunk citations and no approval actions, so those answer `undefined` / `[]`
+ * rather than being faked.
+ */
+declare class HandbookThreadMessage extends AbstractApiData implements HandbookThreadMessageInterface {
+    private _role?;
+    private _content?;
+    private _position?;
+    private _sources?;
+    private _isOptimistic;
+    get role(): AssistantMessageRole;
+    get content(): string;
+    get position(): number;
+    get sources(): string[];
+    /** The handbook agent returns no follow-ups. */
+    get suggestedQuestions(): string[];
+    /** Token accounting is not billed against a handbook thread. */
+    get inputTokens(): number | undefined;
+    get outputTokens(): number | undefined;
+    /** The handbook answers from pages, never from product entities. */
+    get references(): ApiDataInterface[];
+    /** Cited pages travel in `sources`, not as Chunk resources. */
+    get citations(): (ChunkInterface & ChunkRelationshipMeta)[];
+    /** Set only by `buildLocal`; a rehydrated message is always real. */
+    get isOptimistic(): boolean;
+    /** There is no operator engine behind the handbook, so never an approval request. */
+    get messageType(): AssistantMessageType;
+    get actionId(): string | undefined;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    /**
+     * The envelope `POST /handbookthreads/:id/handbookthreadmessages` accepts:
+     * only the question. Role and position are derived server-side from the
+     * thread, and there is no client-chosen id for the pair of messages the turn
+     * creates.
+     *
+     * `handbookPageId` rides the same way `question` does, through this method
+     * and never through `overridesJsonApiCreation`. It is written only when the
+     * caller supplied it: the DTO takes it as optional, and sending an explicit
+     * `null` would fail validation rather than mean "the whole manual".
+     */
+    createJsonApi(data: HandbookThreadMessageInput): {
+        data: {
+            type: string;
+            attributes: {
+                handbookPageId?: string | undefined;
+                question: string;
+            };
+        };
+        included: never[];
+    };
+    /**
+     * A message that exists only on the client: the optimistic user turn while
+     * the agent runs, and the failure notice when it does not answer. Mirrors
+     * `AssistantMessage.buildLocal`, which the stateless handbook surface used
+     * before threads existed.
+     */
+    static buildLocal(params: {
+        role: AssistantMessageRole;
+        content: string;
+        position: number;
+        isOptimistic?: boolean;
+    }): HandbookThreadMessage;
+}
+
+declare class HandbookThreadMessageService extends AbstractService {
+    /**
+     * Appends one question to an existing thread and runs the agent turn.
+     *
+     * It returns nothing on purpose: the caller reads the turn back with
+     * `HandbookThreadService.findOne`, which is the one endpoint the contract
+     * guarantees side-loads the full message list. That keeps a single code path
+     * for "load the thread after a mutation" — the same one the sidebar's select
+     * uses — instead of two ways of arriving at the transcript.
+     *
+     * The API answers 400 when the installation has no usable AI configuration
+     * and 403 for a non-administrator; both reach the caller as a thrown error.
+     */
+    static ask(params: HandbookThreadMessageInput & {
+        threadId: string;
+    }): Promise<void>;
+}
+
+declare class HandbookThreadService extends AbstractService {
+    /**
+     * `next` / `prev` are not optional extras: `useDataListRetriever` drives
+     * pagination by handing the cursor back here, so a findMany that drops them
+     * renders exactly one page and no navigation, however many rows exist.
+     * Mirrors HowToService.findMany.
+     */
+    static findMany(params?: {
+        search?: string;
+        fetchAll?: boolean;
+        next?: NextRef;
+        prev?: PreviousRef;
+    }): Promise<HandbookThreadInterface[]>;
+    /** Returns the thread with its messages side-loaded — the sidebar's select. */
+    static findOne(params: {
+        id: string;
+    }): Promise<HandbookThreadInterface>;
+    /**
+     * Opens a thread with its first question. The response is the thread (title
+     * included); the messages are read back with `findOne`, because only the
+     * single-resource endpoint side-loads them.
+     *
+     * The API answers 400 when the installation has no usable AI configuration
+     * and 403 for a non-administrator; both reach the caller as a thrown error.
+     *
+     * `HandbookThreadInput.handbookPageId` scopes retrieval to one page. It rides
+     * through the model's `createJsonApi()`, exactly as `question` does — there is
+     * no `overridesJsonApiCreation` on this path.
+     */
+    static create(params: HandbookThreadInput): Promise<HandbookThreadInterface>;
+    static rename(params: {
+        id: string;
+        title: string;
+    }): Promise<void>;
+    static delete(params: {
+        id: string;
+    }): Promise<void>;
+}
+
 declare const AssistantModule: (factory: ModuleFactory) => ModuleWithPermissions;
 
 declare class Assistant extends AbstractApiData implements AssistantInterface {
@@ -1964,6 +2420,8 @@ declare class Assistant extends AbstractApiData implements AssistantInterface {
             } | undefined;
             type: string;
             attributes: {
+                limitToHandbookPageId?: string | undefined;
+                handbookMode?: boolean | undefined;
                 limitToHowToId?: string | undefined;
                 howToMode?: boolean | undefined;
                 title?: string | undefined;
@@ -2008,6 +2466,8 @@ declare class AssistantService extends AbstractService {
         content: string;
         howToMode?: boolean;
         limitToHowToId?: string;
+        handbookMode?: boolean;
+        limitToHandbookPageId?: string;
         /** BlockNote document. Serialised by the model into `content`; never its own attribute. */
         contentBlocks?: unknown[];
     }): Promise<AssistantMessageInterface[]>;
@@ -2088,11 +2548,15 @@ declare class AssistantMessage extends AbstractApiData implements AssistantMessa
         content: string;
         howToMode?: boolean;
         limitToHowToId?: string;
+        handbookMode?: boolean;
+        limitToHandbookPageId?: string;
         contentBlocks?: unknown[];
     }): {
         data: {
             type: string;
             attributes: {
+                limitToHandbookPageId?: string | undefined;
+                handbookMode?: boolean | undefined;
                 limitToHowToId?: string | undefined;
                 howToMode?: boolean | undefined;
                 content: string;
@@ -2104,6 +2568,22 @@ declare class AssistantMessage extends AbstractApiData implements AssistantMessa
         position: number;
         assistantId?: string;
     }): AssistantMessage;
+    /**
+     * A message that exists only on the client, for a surface that renders the
+     * chat presentation without persisting a thread.
+     *
+     * `buildOptimistic` is the user-turn case and delegates here. The handbook
+     * ask surface is the other caller: it has no Assistant and no stored
+     * messages, but it renders through MessageList/MessageItem like every other
+     * chat in the product, so it needs both roles.
+     */
+    static buildLocal(params: {
+        role: AssistantMessageRole;
+        content: string;
+        position: number;
+        assistantId?: string;
+        isOptimistic?: boolean;
+    }): AssistantMessage;
 }
 
 declare class AssistantMessageService extends AbstractService {
@@ -2599,4 +3079,4 @@ declare class AuditLogService extends AbstractService {
 
 declare const AuditLogModule: (factory: ModuleFactory) => ModuleWithPermissions;
 
-export { AbstractApiData, AbstractService, Action, ApiData, ApiDataInterface, ApiRequestDataTypeInterface, ApiResponseInterface, type AppModuleDefinitions, Assistant, AssistantAction, type AssistantActionInput, type AssistantActionInterface, AssistantActionModule, AssistantActionService, type AssistantActionStatus, AssistantInput, AssistantInterface, AssistantMessage, AssistantMessageInput, AssistantMessageInterface, AssistantMessageModule, AssistantMessageRole, AssistantMessageService, AssistantMessageType, AssistantModule, AssistantService, AuditLog, type AuditLogInterface, AuditLogModule, AuditLogService, Auth, AuthInput, AuthInterface, AuthModule, AuthorModule, BackupCodeVerify, type BackupCodeVerifyInput, BackupCodeVerifyModule, Billing, BillingModule, BillingService, type BlockDiffOptions, BlockNoteDiffUtil, BlockNoteWordDiffRendererUtil, CURRENT_USER_STORAGE_KEY, Chunk, type ChunkInput, ChunkInterface, ChunkModule, ChunkRelationshipMeta, ClientAbstractService, ClientHttpMethod, type ClientNextRef, type ClientPreviousRef, type ClientSelfRef, type ClientTotalRef, type CodiceFiscaleValidationOptions, Company, CompanyFields, CompanyInput, CompanyInterface, CompanyModule, Content, ContentInput, ContentInterface, ContentModule, DataClassRegistry as DataClass, DataClassRegistry, type DiffBlock, type DiffResult, ENV, EndpointCreator, type EndpointQuery, EntityAiStatus, type EntityObject, Feature, FeatureInterface, FeatureModule, FieldSelector, type FormatOption, type FoundationModuleDefinitions, HowTo, HowToFields, HowToInput, HowToInterface, HowToModule, HowToService, type InviteValidation, InvoiceStatus, JsonApiDataFactory, JsonApiHydratedDataInterface, MOBILE_BREAKPOINT, MeterInterface, MeterSummaryInterface, Module, type ModuleDefinitions, ModuleFactory, ModuleInterface, ModuleModule, ModulePathsModule, ModuleRegistrar, ModuleRegistry, ModuleWithPermissions, Modules, NextRef, Notification, NotificationFields, NotificationInput, NotificationInterface, NotificationModule, OAuthClient, OAuthClientCreateRequest, OAuthClientCreateResponse, OAuthClientInput, OAuthClientInterface, OAuthConsentInfo, OAuthConsentRequest, OAuthModule, OAuthService, Passkey, PasskeyAuthenticationOptions, type PasskeyAuthenticationOptionsInput, type PasskeyAuthenticationOptionsInterface, PasskeyAuthenticationOptionsModule, PasskeyInterface, PasskeyModule, PasskeyRegistrationOptions, type PasskeyRegistrationOptionsInput, type PasskeyRegistrationOptionsInterface, PasskeyRegistrationOptionsModule, PasskeyRegistrationVerify, type PasskeyRegistrationVerifyInput, PasskeyRegistrationVerifyModule, PasskeyRename, type PasskeyRenameInput, PasskeyRenameModule, PasskeyVerifyLogin, type PasskeyVerifyLoginInput, PasskeyVerifyLoginModule, PaymentMethod, PaymentMethodInterface, PermissionMappingModule, PermissionModule, PermissionUser, PreviousRef, PriceRecurring, PromotionCodeValidationResult, ProrationPreviewInterface, Push, type PushInput, type PushInterface, PushModule, RbacMatrixModule, ReferralModule, ReferralService, ReferralStats, ReferralStatsModule, RehydrationFactory, ReportUsageInput, Role, RoleInput, RoleInterface, RoleModule, S3, S3Input, S3Interface, S3Module, type SearchResultInterface, StripeCustomer, StripeCustomerInterface, StripeCustomerModule, StripeCustomerService, StripeInvoice, StripeInvoiceInterface, StripeInvoiceModule, StripeInvoiceService, StripePaymentMethodModule, StripePrice, StripePriceFields, StripePriceInput, StripePriceInterface, StripePriceModule, StripePriceService, StripeProduct, StripeProductFields, StripeProductInput, StripeProductInterface, StripeProductModule, StripeProductService, StripePromotionCode, StripePromotionCodeModule, StripePromotionCodeService, StripeSubscription, StripeSubscriptionCreateResponse, StripeSubscriptionInput, StripeSubscriptionInterface, StripeSubscriptionModule, StripeSubscriptionService, StripeUsage, StripeUsageInterface, StripeUsageModule, StripeUsageService, SubscriptionStatus, TableOptions, type ToastOptions, TotpAuthenticator, TotpAuthenticatorInterface, TotpAuthenticatorModule, TotpSetup, type TotpSetupInput, type TotpSetupInterface, TotpSetupModule, TotpVerify, type TotpVerifyInput, TotpVerifyLogin, type TotpVerifyLoginInput, TotpVerifyLoginModule, TotpVerifyModule, TwoFactorChallenge, type TwoFactorChallengeInput, TwoFactorChallengeInterface, TwoFactorChallengeModule, TwoFactorEnable, type TwoFactorEnableInput, TwoFactorEnableModule, TwoFactorService, TwoFactorStatus, type TwoFactorStatusInterface, TwoFactorStatusModule, UsageSummaryInterface, User, UserInput, UserInterface, UserModule, type UserObject, VIEWPORT_COOKIE_NAME, Waitlist, type WaitlistInput, type WaitlistInterface, WaitlistModule, WaitlistService, WaitlistStats, type WaitlistStatsInterface, WaitlistStatsModule, type WaitlistStatus, type WordDiff, checkPermissions, checkPermissionsFromServer, cn, composeRefs, dismissToast, entityObjectSchema, exists, formatCodiceFiscale, formatDate, formatLocalDate, formatPartitaIva, getBootstrapper, getClientGlobalErrorHandler, getTableComponents, getTableOptions, getValueFromPath, hasBootstrapper, isRemoteImageSrc, rehydrate, rehydrateList, resetBootstrapStore, setBootstrapper, setClientGlobalErrorHandler, showCustomToast, showError, showToast, translateData, translateResponse, tryBootstrap, useComposedRefs, useIsMobile, userObjectSchema, validateCodiceFiscale, validateItalianTaxCode, validatePartitaIva };
+export { AbstractApiData, AbstractService, Action, ApiData, ApiDataInterface, ApiRequestDataTypeInterface, ApiResponseInterface, type AppModuleDefinitions, Assistant, AssistantAction, type AssistantActionInput, type AssistantActionInterface, AssistantActionModule, AssistantActionService, type AssistantActionStatus, AssistantInput, AssistantInterface, AssistantMessage, AssistantMessageInput, AssistantMessageInterface, AssistantMessageModule, AssistantMessageRole, AssistantMessageService, AssistantMessageType, AssistantModule, AssistantService, AuditLog, type AuditLogInterface, AuditLogModule, AuditLogService, Auth, AuthInput, AuthInterface, AuthModule, AuthorModule, BackupCodeVerify, type BackupCodeVerifyInput, BackupCodeVerifyModule, Billing, BillingModule, BillingService, type BlockDiffOptions, BlockNoteDiffUtil, BlockNoteWordDiffRendererUtil, CURRENT_USER_STORAGE_KEY, Chunk, type ChunkInput, ChunkInterface, ChunkModule, ChunkRelationshipMeta, ClientAbstractService, ClientHttpMethod, type ClientNextRef, type ClientPreviousRef, type ClientSelfRef, type ClientTotalRef, type CodiceFiscaleValidationOptions, Company, CompanyFields, CompanyInput, CompanyInterface, CompanyModule, Content, ContentInput, ContentInterface, ContentModule, DataClassRegistry as DataClass, DataClassRegistry, type DiffBlock, type DiffResult, ENV, EndpointCreator, type EndpointQuery, EntityAiStatus, type EntityObject, Feature, FeatureInterface, FeatureModule, FieldSelector, type FormatOption, type FoundationModuleDefinitions, HandbookPage, HandbookPageFields, type HandbookPageInput, HandbookPageInterface, HandbookPageModule, HandbookPageService, HandbookSection, type HandbookSectionInput, HandbookSectionInterface, HandbookSectionModule, HandbookSectionService, HandbookThread, type HandbookThreadInput, type HandbookThreadInterface, HandbookThreadMessage, type HandbookThreadMessageInput, type HandbookThreadMessageInterface, HandbookThreadMessageModule, HandbookThreadMessageService, HandbookThreadModule, HandbookThreadService, HowTo, HowToFields, HowToInput, HowToInterface, HowToModule, HowToService, type InviteValidation, InvoiceStatus, JsonApiDataFactory, JsonApiHydratedDataInterface, MOBILE_BREAKPOINT, MeterInterface, MeterSummaryInterface, Module, type ModuleDefinitions, ModuleFactory, ModuleInterface, ModuleModule, ModulePathsModule, ModuleRegistrar, ModuleRegistry, ModuleWithPermissions, Modules, NextRef, Notification, NotificationFields, NotificationInput, NotificationInterface, NotificationModule, OAuthClient, OAuthClientCreateRequest, OAuthClientCreateResponse, OAuthClientInput, OAuthClientInterface, OAuthConsentInfo, OAuthConsentRequest, OAuthModule, OAuthService, Passkey, PasskeyAuthenticationOptions, type PasskeyAuthenticationOptionsInput, type PasskeyAuthenticationOptionsInterface, PasskeyAuthenticationOptionsModule, PasskeyInterface, PasskeyModule, PasskeyRegistrationOptions, type PasskeyRegistrationOptionsInput, type PasskeyRegistrationOptionsInterface, PasskeyRegistrationOptionsModule, PasskeyRegistrationVerify, type PasskeyRegistrationVerifyInput, PasskeyRegistrationVerifyModule, PasskeyRename, type PasskeyRenameInput, PasskeyRenameModule, PasskeyVerifyLogin, type PasskeyVerifyLoginInput, PasskeyVerifyLoginModule, PaymentMethod, PaymentMethodInterface, PermissionMappingModule, PermissionModule, PermissionUser, PreviousRef, PriceRecurring, PromotionCodeValidationResult, ProrationPreviewInterface, Push, type PushInput, type PushInterface, PushModule, RbacMatrixModule, ReferralModule, ReferralService, ReferralStats, ReferralStatsModule, RehydrationFactory, ReportUsageInput, Role, RoleInput, RoleInterface, RoleModule, S3, S3Input, S3Interface, S3Module, type SearchResultInterface, StripeCustomer, StripeCustomerInterface, StripeCustomerModule, StripeCustomerService, StripeInvoice, StripeInvoiceInterface, StripeInvoiceModule, StripeInvoiceService, StripePaymentMethodModule, StripePrice, StripePriceFields, StripePriceInput, StripePriceInterface, StripePriceModule, StripePriceService, StripeProduct, StripeProductFields, StripeProductInput, StripeProductInterface, StripeProductModule, StripeProductService, StripePromotionCode, StripePromotionCodeModule, StripePromotionCodeService, StripeSubscription, StripeSubscriptionCreateResponse, StripeSubscriptionInput, StripeSubscriptionInterface, StripeSubscriptionModule, StripeSubscriptionService, StripeUsage, StripeUsageInterface, StripeUsageModule, StripeUsageService, SubscriptionStatus, TableOptions, type ToastOptions, TotpAuthenticator, TotpAuthenticatorInterface, TotpAuthenticatorModule, TotpSetup, type TotpSetupInput, type TotpSetupInterface, TotpSetupModule, TotpVerify, type TotpVerifyInput, TotpVerifyLogin, type TotpVerifyLoginInput, TotpVerifyLoginModule, TotpVerifyModule, TwoFactorChallenge, type TwoFactorChallengeInput, TwoFactorChallengeInterface, TwoFactorChallengeModule, TwoFactorEnable, type TwoFactorEnableInput, TwoFactorEnableModule, TwoFactorService, TwoFactorStatus, type TwoFactorStatusInterface, TwoFactorStatusModule, UsageSummaryInterface, User, UserInput, UserInterface, UserModule, type UserObject, VIEWPORT_COOKIE_NAME, Waitlist, type WaitlistInput, type WaitlistInterface, WaitlistModule, WaitlistService, WaitlistStats, type WaitlistStatsInterface, WaitlistStatsModule, type WaitlistStatus, type WordDiff, checkPermissions, checkPermissionsFromServer, cn, composeRefs, dismissToast, entityObjectSchema, exists, formatCodiceFiscale, formatDate, formatLocalDate, formatPartitaIva, getBootstrapper, getClientGlobalErrorHandler, getTableComponents, getTableOptions, getValueFromPath, handbookPageContent, handbookPageSummary, handbookPageTitle, handbookSectionSummary, handbookSectionTitle, hasBootstrapper, isRemoteImageSrc, rehydrate, rehydrateList, resetBootstrapStore, setBootstrapper, setClientGlobalErrorHandler, showCustomToast, showError, showToast, translateData, translateResponse, tryBootstrap, useComposedRefs, useIsMobile, userObjectSchema, validateCodiceFiscale, validateItalianTaxCode, validatePartitaIva };