@richardmcquiston01/chat-and-react-core 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,238 @@
+type AnswerMap = Record<string, string | string[]>;
+type ChatInputType = 'text' | 'textarea' | 'dropdown' | 'radio' | 'checkbox';
+type JsonLogicRule = Record<string, unknown>;
+interface ChatConditionRef {
+    ref: string;
+}
+interface ChatQuestion {
+    id: string;
+    type: 'string' | 'array';
+    'x-chat-input': ChatInputType;
+    title: string;
+    'x-chat-placeholder'?: string;
+    'x-chat-condition'?: JsonLogicRule | ChatConditionRef;
+    enum?: string[];
+    items?: {
+        enum: string[];
+    };
+}
+interface BranchingAlways {
+    type: 'always';
+    destination_id: string;
+}
+interface BranchingIf {
+    type: 'if';
+    form_element: string;
+    value: string;
+    destination_id: string;
+}
+type BranchingRule = BranchingAlways | BranchingIf;
+interface ChatPage {
+    id: string;
+    title: string;
+    questions: ChatQuestion[];
+    branching: BranchingRule[];
+}
+interface ChatOptions {
+    userResumable: boolean;
+    localStorage: boolean;
+    autoComplete: boolean;
+}
+interface ChatSchema {
+    '$schema'?: string;
+    'x-chat-version': '1';
+    'x-chat-options'?: Partial<ChatOptions>;
+    'x-chat-pages': ChatPage[];
+    'x-chat-rules'?: Record<string, JsonLogicRule>;
+}
+interface PageSubmitEvent {
+    type: 'page:submit';
+    sessionId: string;
+    pageId: string;
+    visitIndex: number;
+    answers: AnswerMap;
+}
+interface FormCompleteEvent {
+    type: 'form:complete';
+    sessionId: string;
+    allAnswers: AnswerMap;
+}
+type ChatEvent = PageSubmitEvent | FormCompleteEvent;
+type ChatErrorCode = 'SCHEMA_INVALID' | 'RULE_EVAL_FAILED' | 'ADAPTER_ERROR' | 'STORAGE_UNAVAILABLE';
+interface ChatError {
+    code: ChatErrorCode;
+    message: string;
+    cause?: unknown;
+}
+interface InputAdapter {
+    transform(raw: unknown): unknown;
+}
+interface OutputAdapter {
+    emit(event: ChatEvent): void;
+}
+interface ErrorLogAdapter {
+    log(error: ChatError): void;
+}
+interface ChatControllerConfig {
+    schema: unknown;
+    inputAdapter?: InputAdapter;
+    outputAdapter?: OutputAdapter;
+    errorAdapter?: ErrorLogAdapter;
+}
+
+/**
+ * Parses and validates an unknown input as a {@link ChatSchema}.
+ *
+ * @param raw - The raw input to validate.
+ * @returns The typed {@link ChatSchema} if valid.
+ * @throws `{ code: 'SCHEMA_INVALID', message: string }` on any validation failure.
+ */
+declare function parseSchema(raw: unknown): ChatSchema;
+
+/**
+ * Evaluates JSON Logic rules against provided answers.
+ * Wraps json-logic-js to provide type-safe rule evaluation.
+ */
+declare class RuleEngine {
+    /**
+     * Evaluates a JSON Logic rule against an answer map.
+     * @param rule The JSON Logic rule to evaluate
+     * @param answers The answer map to evaluate the rule against
+     * @returns The boolean result of the rule evaluation
+     * @throws {{ code: 'RULE_EVAL_FAILED', message: string, cause: unknown }} if rule evaluation fails
+     */
+    evaluate(rule: JsonLogicRule, answers: AnswerMap): boolean;
+}
+
+interface StorageBackend {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    key(index: number): string | null;
+    readonly length: number;
+}
+interface SessionProgress {
+    currentPageId: string;
+    answers: AnswerMap;
+}
+declare class SessionManager {
+    private readonly storage;
+    private readonly sessionId;
+    private readonly available;
+    constructor(storage?: StorageBackend);
+    getSessionId(): string;
+    get isStorageAvailable(): boolean;
+    saveProgress(currentPageId: string, answers: AnswerMap): void;
+    loadProgress(): SessionProgress | null;
+    saveInput(questionId: string, value: string | string[]): void;
+    loadInput(questionId: string): string | string[] | null;
+    clearAll(): void;
+    private loadOrCreateSessionId;
+    private checkStorage;
+}
+
+type EventName = 'page:submit' | 'form:complete';
+type Listener = (event: ChatEvent) => void;
+/**
+ * Central orchestrator for the chat-and-react form flow.
+ * Drives page navigation, branching, session persistence, and event emission.
+ */
+declare class ChatController {
+    private schema;
+    private options;
+    private readonly config;
+    private readonly session;
+    private readonly ruleEngine;
+    private currentPage;
+    private allAnswers;
+    private visitIndex;
+    private readonly listeners;
+    /**
+     * @param config - Controller configuration including schema and optional adapters.
+     * @param sessionManager - Optional session manager for test injection.
+     */
+    constructor(config: ChatControllerConfig, sessionManager?: SessionManager);
+    /**
+     * Initialises the controller: parses the schema, resolves options,
+     * restores any saved session, and positions to the first page.
+     */
+    start(): void;
+    /**
+     * Returns the page currently being presented to the user, or null if complete.
+     */
+    getCurrentPage(): ChatPage | null;
+    /**
+     * Returns the subset of questions on the current page that pass their
+     * `x-chat-condition` rule (if any). Questions without a condition are always visible.
+     */
+    getVisibleQuestions(): ChatQuestion[];
+    /**
+     * Returns the resolved options for the current session (schema options merged with defaults).
+     */
+    getOptions(): ChatOptions;
+    /**
+     * Submits the answers for the current page and advances the session.
+     * - Accumulates answers into `allAnswers`.
+     * - Emits `page:submit` (suppressed when `userResumable` is false).
+     * - Resolves branching to find the next page.
+     * - Emits `form:complete` and clears session when `**FORM_COMPLETED**` is reached.
+     *
+     * @param pageAnswers - Answers collected for the current page.
+     */
+    submitPage(pageAnswers: AnswerMap): void;
+    /**
+     * Registers an event listener for the given event type.
+     *
+     * @param event - The event to listen for.
+     * @param listener - The callback to invoke when the event fires.
+     */
+    on(event: EventName, listener: Listener): void;
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param event - The event type to deregister from.
+     * @param listener - The specific listener to remove.
+     */
+    off(event: EventName, listener: Listener): void;
+    /**
+     * Tears down the controller: removes all listeners and nulls internal state.
+     */
+    destroy(): void;
+    /**
+     * Evaluates whether a question should be shown based on its `x-chat-condition`.
+     * Returns true when no condition is present. On evaluation failure, logs and returns false.
+     */
+    private isQuestionVisible;
+    /**
+     * Walks the branching rules top-to-bottom. Returns the first match's destination_id.
+     * Falls back to `**FORM_COMPLETED**` if nothing matches (should not happen with valid schemas).
+     */
+    private resolveBranching;
+    /**
+     * Calls `outputAdapter.emit()` and swallows adapter errors (logging them instead).
+     */
+    private safeEmit;
+    /**
+     * Notifies all registered listeners for the given event.
+     */
+    private emit;
+    /**
+     * Logs the error via the error adapter and then throws it.
+     * Used for unrecoverable errors (schema invalid, adapter failure on start).
+     */
+    private handleFatal;
+}
+
+declare class IdentityInputAdapter implements InputAdapter {
+    transform(raw: unknown): unknown;
+}
+
+declare class BrowserEventAdapter implements OutputAdapter {
+    emit(event: ChatEvent): void;
+}
+
+declare class ConsoleErrorAdapter implements ErrorLogAdapter {
+    log(error: ChatError): void;
+}
+
+export { type AnswerMap, type BranchingAlways, type BranchingIf, type BranchingRule, BrowserEventAdapter, type ChatConditionRef, ChatController, type ChatControllerConfig, type ChatError, type ChatErrorCode, type ChatEvent, type ChatInputType, type ChatOptions, type ChatPage, type ChatQuestion, type ChatSchema, ConsoleErrorAdapter, type ErrorLogAdapter, type FormCompleteEvent, IdentityInputAdapter, type InputAdapter, type JsonLogicRule, type OutputAdapter, type PageSubmitEvent, RuleEngine, SessionManager, type SessionProgress, type StorageBackend, parseSchema };

package/dist/index.d.ts

@@ -0,0 +1,238 @@
+type AnswerMap = Record<string, string | string[]>;
+type ChatInputType = 'text' | 'textarea' | 'dropdown' | 'radio' | 'checkbox';
+type JsonLogicRule = Record<string, unknown>;
+interface ChatConditionRef {
+    ref: string;
+}
+interface ChatQuestion {
+    id: string;
+    type: 'string' | 'array';
+    'x-chat-input': ChatInputType;
+    title: string;
+    'x-chat-placeholder'?: string;
+    'x-chat-condition'?: JsonLogicRule | ChatConditionRef;
+    enum?: string[];
+    items?: {
+        enum: string[];
+    };
+}
+interface BranchingAlways {
+    type: 'always';
+    destination_id: string;
+}
+interface BranchingIf {
+    type: 'if';
+    form_element: string;
+    value: string;
+    destination_id: string;
+}
+type BranchingRule = BranchingAlways | BranchingIf;
+interface ChatPage {
+    id: string;
+    title: string;
+    questions: ChatQuestion[];
+    branching: BranchingRule[];
+}
+interface ChatOptions {
+    userResumable: boolean;
+    localStorage: boolean;
+    autoComplete: boolean;
+}
+interface ChatSchema {
+    '$schema'?: string;
+    'x-chat-version': '1';
+    'x-chat-options'?: Partial<ChatOptions>;
+    'x-chat-pages': ChatPage[];
+    'x-chat-rules'?: Record<string, JsonLogicRule>;
+}
+interface PageSubmitEvent {
+    type: 'page:submit';
+    sessionId: string;
+    pageId: string;
+    visitIndex: number;
+    answers: AnswerMap;
+}
+interface FormCompleteEvent {
+    type: 'form:complete';
+    sessionId: string;
+    allAnswers: AnswerMap;
+}
+type ChatEvent = PageSubmitEvent | FormCompleteEvent;
+type ChatErrorCode = 'SCHEMA_INVALID' | 'RULE_EVAL_FAILED' | 'ADAPTER_ERROR' | 'STORAGE_UNAVAILABLE';
+interface ChatError {
+    code: ChatErrorCode;
+    message: string;
+    cause?: unknown;
+}
+interface InputAdapter {
+    transform(raw: unknown): unknown;
+}
+interface OutputAdapter {
+    emit(event: ChatEvent): void;
+}
+interface ErrorLogAdapter {
+    log(error: ChatError): void;
+}
+interface ChatControllerConfig {
+    schema: unknown;
+    inputAdapter?: InputAdapter;
+    outputAdapter?: OutputAdapter;
+    errorAdapter?: ErrorLogAdapter;
+}
+
+/**
+ * Parses and validates an unknown input as a {@link ChatSchema}.
+ *
+ * @param raw - The raw input to validate.
+ * @returns The typed {@link ChatSchema} if valid.
+ * @throws `{ code: 'SCHEMA_INVALID', message: string }` on any validation failure.
+ */
+declare function parseSchema(raw: unknown): ChatSchema;
+
+/**
+ * Evaluates JSON Logic rules against provided answers.
+ * Wraps json-logic-js to provide type-safe rule evaluation.
+ */
+declare class RuleEngine {
+    /**
+     * Evaluates a JSON Logic rule against an answer map.
+     * @param rule The JSON Logic rule to evaluate
+     * @param answers The answer map to evaluate the rule against
+     * @returns The boolean result of the rule evaluation
+     * @throws {{ code: 'RULE_EVAL_FAILED', message: string, cause: unknown }} if rule evaluation fails
+     */
+    evaluate(rule: JsonLogicRule, answers: AnswerMap): boolean;
+}
+
+interface StorageBackend {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    key(index: number): string | null;
+    readonly length: number;
+}
+interface SessionProgress {
+    currentPageId: string;
+    answers: AnswerMap;
+}
+declare class SessionManager {
+    private readonly storage;
+    private readonly sessionId;
+    private readonly available;
+    constructor(storage?: StorageBackend);
+    getSessionId(): string;
+    get isStorageAvailable(): boolean;
+    saveProgress(currentPageId: string, answers: AnswerMap): void;
+    loadProgress(): SessionProgress | null;
+    saveInput(questionId: string, value: string | string[]): void;
+    loadInput(questionId: string): string | string[] | null;
+    clearAll(): void;
+    private loadOrCreateSessionId;
+    private checkStorage;
+}
+
+type EventName = 'page:submit' | 'form:complete';
+type Listener = (event: ChatEvent) => void;
+/**
+ * Central orchestrator for the chat-and-react form flow.
+ * Drives page navigation, branching, session persistence, and event emission.
+ */
+declare class ChatController {
+    private schema;
+    private options;
+    private readonly config;
+    private readonly session;
+    private readonly ruleEngine;
+    private currentPage;
+    private allAnswers;
+    private visitIndex;
+    private readonly listeners;
+    /**
+     * @param config - Controller configuration including schema and optional adapters.
+     * @param sessionManager - Optional session manager for test injection.
+     */
+    constructor(config: ChatControllerConfig, sessionManager?: SessionManager);
+    /**
+     * Initialises the controller: parses the schema, resolves options,
+     * restores any saved session, and positions to the first page.
+     */
+    start(): void;
+    /**
+     * Returns the page currently being presented to the user, or null if complete.
+     */
+    getCurrentPage(): ChatPage | null;
+    /**
+     * Returns the subset of questions on the current page that pass their
+     * `x-chat-condition` rule (if any). Questions without a condition are always visible.
+     */
+    getVisibleQuestions(): ChatQuestion[];
+    /**
+     * Returns the resolved options for the current session (schema options merged with defaults).
+     */
+    getOptions(): ChatOptions;
+    /**
+     * Submits the answers for the current page and advances the session.
+     * - Accumulates answers into `allAnswers`.
+     * - Emits `page:submit` (suppressed when `userResumable` is false).
+     * - Resolves branching to find the next page.
+     * - Emits `form:complete` and clears session when `**FORM_COMPLETED**` is reached.
+     *
+     * @param pageAnswers - Answers collected for the current page.
+     */
+    submitPage(pageAnswers: AnswerMap): void;
+    /**
+     * Registers an event listener for the given event type.
+     *
+     * @param event - The event to listen for.
+     * @param listener - The callback to invoke when the event fires.
+     */
+    on(event: EventName, listener: Listener): void;
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param event - The event type to deregister from.
+     * @param listener - The specific listener to remove.
+     */
+    off(event: EventName, listener: Listener): void;
+    /**
+     * Tears down the controller: removes all listeners and nulls internal state.
+     */
+    destroy(): void;
+    /**
+     * Evaluates whether a question should be shown based on its `x-chat-condition`.
+     * Returns true when no condition is present. On evaluation failure, logs and returns false.
+     */
+    private isQuestionVisible;
+    /**
+     * Walks the branching rules top-to-bottom. Returns the first match's destination_id.
+     * Falls back to `**FORM_COMPLETED**` if nothing matches (should not happen with valid schemas).
+     */
+    private resolveBranching;
+    /**
+     * Calls `outputAdapter.emit()` and swallows adapter errors (logging them instead).
+     */
+    private safeEmit;
+    /**
+     * Notifies all registered listeners for the given event.
+     */
+    private emit;
+    /**
+     * Logs the error via the error adapter and then throws it.
+     * Used for unrecoverable errors (schema invalid, adapter failure on start).
+     */
+    private handleFatal;
+}
+
+declare class IdentityInputAdapter implements InputAdapter {
+    transform(raw: unknown): unknown;
+}
+
+declare class BrowserEventAdapter implements OutputAdapter {
+    emit(event: ChatEvent): void;
+}
+
+declare class ConsoleErrorAdapter implements ErrorLogAdapter {
+    log(error: ChatError): void;
+}
+
+export { type AnswerMap, type BranchingAlways, type BranchingIf, type BranchingRule, BrowserEventAdapter, type ChatConditionRef, ChatController, type ChatControllerConfig, type ChatError, type ChatErrorCode, type ChatEvent, type ChatInputType, type ChatOptions, type ChatPage, type ChatQuestion, type ChatSchema, ConsoleErrorAdapter, type ErrorLogAdapter, type FormCompleteEvent, IdentityInputAdapter, type InputAdapter, type JsonLogicRule, type OutputAdapter, type PageSubmitEvent, RuleEngine, SessionManager, type SessionProgress, type StorageBackend, parseSchema };