@123toto/ai-app-assistant-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 123toto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @123toto/ai-app-assistant-client
+
+Framework-neutral browser client and optional UI for `@123toto/ai-app-assistant-server`.
+
+```bash
+npm install @123toto/ai-app-assistant-client
+```
+
+## Web Component
+
+```ts
+import "@123toto/ai-app-assistant-client/web-component";
+```
+
+```html
+<ai-docs-assistant
+  endpoint="/api/ai-docs/ask"
+  stream-endpoint="/api/ai-docs/ask/stream"
+></ai-docs-assistant>
+```
+
+The component handles page capture, DOM element selection, streaming, retry, cancellation and conversation state. It can be used from plain HTML, React, Vue, Svelte or Angular.
+
+Runtime headers and visual labels can be configured programmatically:
+
+```ts
+document.querySelector("ai-docs-assistant")?.configure({
+  endpoint: "/api/ai-docs/ask",
+  headers: () => ({ authorization: `Bearer ${auth.token()}` }),
+  assistantName: "Application assistant"
+});
+```
+
+## Headless client
+
+Import `createAiDocsClient`, `AiDocsAssistantController`, `capturePage` or `pickElement` from `@123toto/ai-app-assistant-client` when the application owns the complete UI.
+
+## Angular connector
+
+```ts
+import { AiDocsAssistantComponent, provideAiDocs } from "@123toto/ai-app-assistant-client/angular";
+
+bootstrapApplication(AppComponent, {
+  providers: [provideAiDocs({
+    endpoint: "/api/ai-docs/ask",
+    streamEndpoint: "/api/ai-docs/ask/stream",
+    managedEndpoint: "/api/ai-docs"
+  })]
+});
+```
+
+Angular and RxJS are optional peer dependencies. The main package and Web Components do not load Angular.
+
+## Settings
+
+The optional `@123toto/ai-app-assistant-client/settings-web-component` entry point registers a generic administration screen. Applications with their own UI can use `@123toto/ai-app-assistant-client/settings` instead.
+
+## Capture privacy
+
+Form values and `[data-sensitive]` subtrees are removed by default. Additional application-specific selectors can be provided through `redactSelectors`. Authentication and final privacy enforcement remain backend responsibilities.
+
+Full documentation: [github.com/123toto/ai-docs-asker](https://github.com/123toto/ai-docs-asker)

package/dist/angular.d.ts

@@ -0,0 +1,185 @@
+import { type EnvironmentProviders, type OnDestroy, type OnInit } from "@angular/core";
+import type { AiDocsAccessView, AskDocumentationResponse } from "@123toto/ai-app-assistant-contracts";
+import { type AiDocsClient } from "./client.js";
+import { type AiDocsControllerConfig, type AiDocsControllerMessage, type AiDocsControllerState } from "./controller.js";
+import { type AiDocsSettingsClient } from "./settings.js";
+import { type AiDocsSettingsTheme } from "./settings-web-component.js";
+import * as i0 from "@angular/core";
+/** Configuration for the Angular connector and its ready-to-use assistant. */
+export interface AiDocsAngularConfig extends AiDocsControllerConfig {
+    endpoint: string;
+    streamEndpoint?: string;
+    /** Enables access discovery and the optional administration screen. */
+    managedEndpoint?: string;
+    headers?: () => HeadersInit | Promise<HeadersInit>;
+    assistantName?: string;
+    launcherLabel?: string;
+    subtitle?: string;
+    /**
+     * Visual tokens consumed by the generic assistant. CSS variables are valid,
+     * which lets a host application follow its own live theme without coupling
+     * this connector to a particular design system.
+     */
+    theme?: Partial<AiDocsTheme>;
+    /** @deprecated Prefer `theme.accent`. */
+    accentColor?: string;
+    mascot?: string;
+    /** Optional copy overrides; defaults follow the document language (French or English). */
+    labels?: Partial<AiDocsUiLabels>;
+    settings?: AiDocsAngularSettingsConfig;
+}
+export interface AiDocsAngularSettingsConfig {
+    title?: string;
+    /** Defaults to document.body. Useful when theme variables live on an application shell. */
+    container?: () => HTMLElement | null;
+    confirmRevoke?: () => boolean | Promise<boolean>;
+    theme?: Partial<AiDocsSettingsTheme>;
+}
+/** Small provider-neutral palette used by the ready-to-use assistant. */
+export interface AiDocsTheme {
+    accent: string;
+    accentContrast: string;
+    header: string;
+    headerText: string;
+    launcher: string;
+    launcherText: string;
+    surface: string;
+    surfaceMuted: string;
+    text: string;
+    textMuted: string;
+    border: string;
+    selection: string;
+    selectionText: string;
+    danger: string;
+}
+export interface AiDocsUiLabels {
+    selectionInstruction: string;
+    cancel: string;
+    newConversation: string;
+    detach: string;
+    dock: string;
+    minimize: string;
+    welcomeTitle: string;
+    welcomeBody: string;
+    reliability: string;
+    retrying: string;
+    reading: string;
+    thinking: string;
+    writing: string;
+    finalizing: string;
+    stop: string;
+    errorTitle: string;
+    retry: string;
+    placeholder: string;
+    select: string;
+    elementSelected: string;
+    mediumConfidence: string;
+    lowConfidence: string;
+    insufficientConfidence: string;
+    conversationLimitReached: string;
+    send: string;
+}
+/** Registers the generic client while preserving Angular HTTP interceptors. */
+export declare function provideAiDocs(config: AiDocsAngularConfig): EnvironmentProviders;
+export type AiDocsState = AiDocsControllerState;
+export type AiDocsConversationMessage = AiDocsControllerMessage;
+/** Angular state, conversation and cancellable DOM-selection facade. */
+export declare class AiDocsService {
+    #private;
+    readonly settingsClient?: AiDocsSettingsClient | undefined;
+    readonly state: import("@angular/core").Signal<AiDocsControllerState>;
+    readonly messages: import("@angular/core").Signal<AiDocsControllerMessage[]>;
+    readonly selecting: import("@angular/core").Signal<boolean>;
+    readonly loading: import("@angular/core").Signal<boolean>;
+    readonly selectedElementLabel: import("@angular/core").Signal<string | undefined>;
+    readonly maxConversationTurns: import("@angular/core").Signal<number>;
+    readonly conversationTurns: import("@angular/core").Signal<number>;
+    readonly conversationLimitReached: import("@angular/core").Signal<boolean>;
+    readonly available: import("@angular/core").Signal<boolean>;
+    readonly config: Readonly<AiDocsAngularConfig>;
+    constructor(config: AiDocsAngularConfig, client: AiDocsClient, settingsClient?: AiDocsSettingsClient | undefined);
+    /** Refreshes launcher visibility and the server-defined conversation limit. */
+    refreshAccess(): Promise<AiDocsAccessView | undefined>;
+    /** Captures the page and asks without application-specific DOM annotations. */
+    ask(options?: {
+        question?: string;
+        selectedElement?: Element;
+    }): Promise<AskDocumentationResponse>;
+    /** Starts selection only. Asking remains a separate user action. */
+    selectElement(): Promise<Element>;
+    /** Backward-compatible shortcut; prefer selectElement followed by ask. */
+    selectAndAsk(question: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<AskDocumentationResponse>;
+    cancelElementSelection(): void;
+    clearSelectedElement(): void;
+    /** Aborts the active provider call without erasing the conversation. */
+    stop(): void;
+    /** Replays the last prompt after automatic retries have been exhausted. */
+    retry(): Promise<AskDocumentationResponse>;
+    /** Explicitly clears conversation and selection; minimizing does not. */
+    newConversation(): void;
+    /** Resets automatically when the application's page URL changes. */
+    syncPage(key?: string): boolean;
+    reset(): void;
+    /** Applies a host-provided runtime limit without recreating the assistant. */
+    setMaxConversationTurns(value: number): void;
+}
+/** Opens the framework-neutral settings UI with Angular's authenticated HttpClient. */
+export declare class AiDocsSettingsService {
+    #private;
+    readonly config: AiDocsAngularConfig;
+    readonly client: AiDocsSettingsClient | undefined;
+    readonly assistant: AiDocsService;
+    constructor(config: AiDocsAngularConfig, client: AiDocsSettingsClient | undefined, assistant: AiDocsService);
+    /** Lazily creates and opens the generic settings element. */
+    open(): void;
+    close(): void;
+    /** Creates one shared element and refreshes launcher access after changes. */
+    private element;
+}
+/** Complete standalone UI. Add `<ai-docs-assistant />` near the app root. */
+export declare class AiDocsAssistantComponent implements OnInit, OnDestroy {
+    readonly service: AiDocsService;
+    readonly open: import("@angular/core").WritableSignal<boolean>;
+    readonly docked: import("@angular/core").WritableSignal<boolean>;
+    readonly left: import("@angular/core").WritableSignal<number | null>;
+    readonly top: import("@angular/core").WritableSignal<number | null>;
+    readonly question: import("@angular/core").WritableSignal<string>;
+    readonly assistantName: import("@angular/core").Signal<string>;
+    readonly launcherLabel: import("@angular/core").Signal<string>;
+    readonly subtitle: import("@angular/core").Signal<string>;
+    readonly mascot: import("@angular/core").Signal<string>;
+    readonly theme: import("@angular/core").Signal<Partial<AiDocsTheme>>;
+    readonly labels: import("@angular/core").Signal<AiDocsUiLabels>;
+    private readonly conversationContent;
+    private routeTimer;
+    private dragCleanup;
+    private scrollFrame;
+    private scrollKey;
+    /** Keeps the latest question and the start of its answer in view. */
+    private readonly keepLatestTurnVisible;
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    show(): void;
+    newConversation(): void;
+    toggleDock(): void;
+    confidencePercent(response: AskDocumentationResponse): number;
+    confidenceClass(response: AskDocumentationResponse): string;
+    confidenceNotice(response: AskDocumentationResponse): string | undefined;
+    progressLabel(phase: "preparing" | "thinking" | "writing" | "finalizing"): string;
+    visibleLimitations(response: AskDocumentationResponse): string[];
+    updateQuestion(event: Event): void;
+    composerKeydown(event: KeyboardEvent): void;
+    submit(event?: Event): Promise<void>;
+    beginSelection(): Promise<void>;
+    cancelSelection(): void;
+    clearSelection(): void;
+    retry(): Promise<void>;
+    /** Relocates each sparkle between cycles; movement is hidden while transparent. */
+    randomizeStar(event: AnimationEvent): void;
+    startDrag(event: PointerEvent): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AiDocsAssistantComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<AiDocsAssistantComponent, "ai-docs-assistant", never, {}, {}, never, never, true, never>;
+}
+//# sourceMappingURL=angular.d.ts.map

package/dist/angular.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"angular.d.ts","sourceRoot":"","sources":["../src/angular.ts"],"names":[],"mappings":"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"}