@mihe-dev/js 0.0.0-stage → 0.1.0

package/dist/mihe.d.ts

@@ -0,0 +1,343 @@
+/**
+ * `Mihe` — the assistant without a framework (doc 08).
+ *
+ * The wiring between the store, the client and whatever UI draws it. It owns
+ * three responsibilities and nothing else:
+ *
+ * 1. Publish the screen context whenever the app's declaration changes.
+ * 2. Execute commands the runtime sends, and ack every one of them.
+ * 3. Hold the conversation the UI renders.
+ *
+ * State is an immutable snapshot, replaced on every change, so React's
+ * `useSyncExternalStore` reads it with no adapter: the React provider is a
+ * thin wrapper over this class, and the two cannot disagree about what a
+ * proposal or a voice event does.
+ */
+import type { KnowledgeSourceRef, ProposalStatus, WidgetSettings } from "@mihe-dev/protocol";
+import { type ConnectionState, type ProposalPayload } from "./client.js";
+import { type AssistantChart, type AssistantTable, type AssistantTabs } from "./declarations.js";
+import { AssistantStore, type ActionHandler, type ComponentDeclaration, type ScreenDeclaration } from "./store.js";
+import { type VoiceState } from "./voice.js";
+export declare const SDK_VERSION = "0.1.0";
+/**
+ * DOM id of the assistant panel, so a custom trigger can point
+ * `aria-controls` at it.
+ */
+export declare const ASSISTANT_PANEL_ID = "mihe-panel";
+export interface ChatMessage {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    /** True while the assistant is still streaming into this message. */
+    streaming?: boolean;
+    /**
+     * Documentation this answer drew on, if any.
+     *
+     * Worth surfacing rather than keeping for debugging: an answer a user can
+     * trace to a named section of their own handbook is one they can check, and
+     * "where did that come from?" is the first question anyone asks of an
+     * assistant that suddenly knows their internal policy.
+     */
+    sources?: KnowledgeSourceRef[];
+}
+/**
+ * The voice session, as the UI sees it.
+ *
+ * `available` is answered by the runtime rather than assumed: voice is a
+ * per-app setting with a real price attached, so a microphone button that
+ * appears and then fails on the first press is worse than no button. It stays
+ * false until the runtime has actually issued a permit.
+ */
+export interface VoiceControls {
+    available: boolean;
+    state: VoiceState;
+    /** True while the session is hands-free rather than push-to-talk. */
+    handsFree: boolean;
+    /** The line currently being spoken, either side. Empty between utterances. */
+    caption: string;
+    /**
+     * Something about the session worth saying that is not a failure — the
+     * ceiling approaching, or a session that has just reached it.
+     *
+     * Separate from `lastError` so a host app's own UI can draw the two
+     * differently, which is the whole point: a session ending on time is the
+     * ordinary case, and putting it in the same red box as a dead provider tells
+     * the user their conversation broke when it did not.
+     */
+    notice: string | null;
+    /**
+     * Open the socket and the microphone. Must be called from a user gesture —
+     * both the permission prompt and iOS Safari's audio unlock require one.
+     *
+     * `handsFree` leaves the microphone open and lets the provider decide where
+     * utterances begin and end, so the user can interrupt mid-reply. The cost is
+     * that the assistant can hear itself; see `VoiceSessionOptions`.
+     */
+    start: (options?: {
+        handsFree?: boolean;
+        /**
+         * Open the conversation panel as the session starts, so what is said
+         * appears there as the session goes. True by default. The orb passes false, because it
+         * shows voice in itself and the point of it is that the page stays visible.
+         */
+        openPanel?: boolean;
+    }) => void;
+    stop: () => void;
+    /**
+     * Push-to-talk: press and release.
+     *
+     * `press({ hold: true })` captures without sending until `confirm()`, and
+     * `discard()` drops it: for a control where a press may turn into a drag.
+     * Releasing a held press confirms it.
+     */
+    press: (options?: {
+        hold?: boolean;
+    }) => void;
+    release: () => void;
+    confirm: () => void;
+    discard: () => void;
+    /**
+     * Follow how loud each side is, 0 to 1, as it happens. Returns the
+     * unsubscribe. Outside the state snapshot on purpose: it fires tens of
+     * times a second, and a listener should move an element directly, not
+     * re-render.
+     */
+    onLevel: (listener: (source: "user" | "assistant", level: number) => void) => () => void;
+}
+/** Everything a UI draws, as one immutable snapshot. */
+export interface MiheState {
+    connection: ConnectionState;
+    messages: ChatMessage[];
+    /** Confirmation cards awaiting a decision. */
+    proposals: ProposalPayload[];
+    /** True from the moment a turn starts until it completes or fails. */
+    busy: boolean;
+    lastError: string | null;
+    /**
+     * Whether the assistant UI is showing.
+     *
+     * Held here rather than inside the widget so that anything in the host
+     * app — a nav button, a command palette, a keyboard shortcut, a plain div —
+     * can open the assistant.
+     */
+    isOpen: boolean;
+    /**
+     * What the assistant calls itself, from the app's settings in the dashboard.
+     * `null` until the handshake answers; a title passed in code still wins.
+     */
+    assistantName: string | null;
+    /**
+     * The customer's launcher icon, uploaded in the dashboard (amendment 58).
+     * `null` means draw the Mihe mark.
+     */
+    launcherIconUrl: string | null;
+    /**
+     * How the widget presents itself, from the app's settings in the dashboard
+     * (amendment 61). `null` until the handshake answers.
+     */
+    widgetSettings: WidgetSettings | null;
+    /** Realtime voice (doc 03). */
+    voice: VoiceControls;
+}
+export interface MiheOptions {
+    /** Runtime WebSocket URL. */
+    url: string;
+    /** The app's public key. Safe to ship in a browser bundle. */
+    publicKey: string;
+    /**
+     * Fetches a signed user token from the host app's own backend.
+     *
+     * This is the app's authority, not the browser's: the runtime reads the
+     * user's id and permissions from this token's verified claims and from
+     * nothing else, so a user cannot grant themselves access by editing
+     * anything on this side.
+     */
+    getUserToken: () => Promise<string>;
+    /**
+     * Route change handler. Wire this to your router — the default is a full
+     * page load, which works but throws away app state.
+     */
+    navigate?: (route: string) => void;
+    /**
+     * Open a registered dialog. Return `false` when the key is not one this
+     * app can open, so the assistant is told rather than reporting success for
+     * a form that never appeared.
+     */
+    openModal?: (modalKey: string) => void | boolean;
+    /**
+     * Called when a confirmed action finishes, whatever the outcome.
+     *
+     * Exists because the assistant changes data the host app is already
+     * displaying, and an app with a client-side cache has no way to know. The
+     * usual implementation is one line — refetch what the page shows — and
+     * without it a user watches an action succeed while the page goes on
+     * showing what was true before it.
+     */
+    onActionComplete?: (action: {
+        actionName: string;
+        status: ProposalStatus;
+        result?: unknown;
+    }) => void;
+    /**
+     * Log what each screen costs to the console: how many tokens one answer
+     * re-sends, and which tools make up most of it (amendment 67). Turn it on
+     * while building an integration; leave it off in production.
+     */
+    debug?: boolean;
+}
+/** Create the assistant and connect it. */
+export declare function createMihe(options: MiheOptions): Mihe;
+export declare class Mihe {
+    /** The app's declaration of itself. */
+    readonly store: AssistantStore;
+    private readonly highlighter;
+    private options;
+    private state;
+    private readonly listeners;
+    private client;
+    private voiceSession;
+    /**
+     * Set while the user is waiting on a permit they asked for.
+     *
+     * A token arriving with this false is one the runtime issued for a probe at
+     * connect time, and starting a session on it would turn the microphone on
+     * without anyone having asked.
+     */
+    private voiceRequested;
+    /** The mode asked for, read when the permit comes back. */
+    private requestedHandsFree;
+    /** Whether the session being requested should open the panel. */
+    private requestedOpenPanel;
+    private readonly levelListeners;
+    /** The route of the last screen context actually sent to the runtime. */
+    private publishedRoute;
+    /** The last screen context actually sent, for acks that check a view. */
+    private publishedScreen;
+    /** Whether that screen had finished loading its data when it was sent. */
+    private publishedSettled;
+    /** Navigate and set_view acks waiting for the screen to report in. */
+    private readonly screenWaiters;
+    private publishTimer;
+    private unsubscribeStore;
+    private readonly tabs;
+    private readonly tables;
+    private readonly charts;
+    private readonly actions;
+    private lastScreen;
+    constructor(options: MiheOptions);
+    /** The current state. The same object until something changes. */
+    getState: () => MiheState;
+    /** Called after every change of state. Returns the unsubscribe. */
+    subscribe: (listener: () => void) => (() => void);
+    /** Voice controls and state; the same as `getState().voice`. */
+    get voice(): VoiceControls;
+    private setState;
+    private setVoice;
+    private setMessages;
+    /**
+     * Replace options. Callbacks take effect at once; a new `url`, `publicKey`
+     * or `debug` reconnects, since each belongs to the session.
+     */
+    update(options: Partial<MiheOptions>): void;
+    /** Open the session. Called by `createMihe`; does nothing if connected. */
+    connect(): void;
+    /**
+     * Close the session, the voice session and any highlight. The
+     * conversation and the declarations stay, for a later `connect()`.
+     */
+    disconnect(): void;
+    /** Disconnect and drop every listener. The instance is done after this. */
+    destroy(): void;
+    send: (text: string) => void;
+    respondToProposal: (proposalId: string, confirmed: boolean) => void;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    /**
+     * A one-tap "ask this", for suggestion chips and help links:
+     * `chip.onclick = mihe.prompt("How do I add a product?")`.
+     */
+    prompt(text: string): () => void;
+    /**
+     * Declare the screen the user is on. Call it again when what the screen
+     * shows changes; call the returned function when the user leaves it.
+     *
+     * `visibleData` is what makes answers concrete — "you have 7 low-stock
+     * products" rather than "check your stock levels" — so include the summary
+     * values already on screen, and only those.
+     */
+    setScreen(screen: ScreenDeclaration): () => void;
+    /**
+     * Declare a component the assistant can talk about or point at. Marks
+     * `element` so it can be found; pass `null` for one that is described but
+     * cannot be highlighted.
+     */
+    registerComponent(element: Element | null, componentKey: string, meta: ComponentDeclaration): () => void;
+    /**
+     * Supply the code for an action the assistant may run in the browser.
+     *
+     * The action itself — its risk tier, permissions, and whether it needs
+     * confirmation — is configured in the dashboard, not here. Whatever the
+     * handler returns becomes the tool result the model sees, so return
+     * something descriptive. Throwing reports the failure honestly.
+     */
+    registerAction(name: string, handler: ActionHandler["handler"]): () => void;
+    private undoAction;
+    /**
+     * Let the assistant see which tab is open and switch to another. Pass the
+     * tab that is really showing as `value`, and call this again when it
+     * changes: a switch is not reported done until `value` matches.
+     */
+    registerTabs(tabs: AssistantTabs): () => void;
+    /**
+     * Let the assistant read a table. The rows are not sent with the screen;
+     * the model reads them when a question needs them, and only the declared
+     * columns ever leave the browser (amendment 67). Call it again when the
+     * rows change.
+     */
+    registerTable<Row>(table: AssistantTable<Row>): () => void;
+    /**
+     * Let the assistant explain a chart. Each series is summarised here, in
+     * the browser; the points are read when an exact value is wanted. Call it
+     * again when the data changes.
+     */
+    registerChart<Datum>(chart: AssistantChart<Datum>): () => void;
+    /**
+     * Add figures to the screen's `visibleData` under `key`: the stat cards
+     * inside a tab, a summary panel. Dropped when the screen changes.
+     */
+    setValues(key: string, values: Record<string, unknown>): () => void;
+    /**
+     * One declaration kind's register-update-undo, shared so tabs, tables and
+     * charts behave the same. The store's entry is re-registered only when the
+     * signature changes, or when the store no longer holds it because the
+     * screen changed underneath.
+     */
+    private declare;
+    /**
+     * Make an element open and close the assistant, keyboard and screen
+     * reader included: a `div` with only a click handler is invisible to both,
+     * and that is the most common way a custom trigger ships broken.
+     */
+    bindTrigger(element: HTMLElement): () => void;
+    private handleEvent;
+    private publish;
+    /**
+     * A navigate command cannot be acked until the destination has published
+     * its context, or the runtime's next step would still be reasoning about
+     * the screen the user just left. See `CommandContext.screenPublished`.
+     */
+    private awaitScreenPublished;
+    /**
+     * A set_view ack waits the same way, for the tab the app was asked to show
+     * to be the one the published screen reports. An app whose `onChange` did
+     * nothing is reported as a failure rather than a switch that did not
+     * happen.
+     */
+    private awaitViewPublished;
+    private startVoiceRequest;
+    private stopVoice;
+    private startVoice;
+    private handleVoiceEvent;
+}
+//# sourceMappingURL=mihe.d.ts.map

package/dist/mihe.d.ts.map

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