@alexkroman1/aai-ui 0.12.3 → 0.13.0

package/dist/internal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `@alexkroman1/aai-ui/internal` — the plumbing `mountClient()` and the default
+ * client install for themselves, NOT part of the public client API and not
+ * covered by semver. A `client.tsx` should never import from here; everything
+ * an author writes a page or a custom chrome against lives on the root export
+ * and the documented subpaths.
+ *
+ * These names used to ride on the root barrel, tagged `@internal` and nothing
+ * else, which meant they were in a client author's autocomplete beside
+ * `mountClient()`, `<Form>`, `useAgentState` and `useWorkflowRun` — eight symbols an
+ * author is invited to reach for and no capability contract covers. Keeping
+ * them on their own subpath keeps the root importable surface the same shape as
+ * the promise: what is on it is contracted.
+ *
+ * A release tag cannot do this from the barrel. API Extractor reads `@internal`
+ * at the DECLARATION site, so a tag written on a re-export clause member is
+ * silently ignored and the name stays `@public` in the report — and the
+ * contract exemption in `contracts/internal-surface.json` is per SUBPATH, so a
+ * tag on the root barrel buys an entry on that ratchet rather than removing
+ * one. A subpath is the mechanism, the same one `@alexkroman1/aai` and
+ * `@alexkroman1/aai-runtime` already use, and `NON_AUTHORING_SUBPATHS` in
+ * `scripts/_api-contracts-tree.mjs` carries the matching entry so a name
+ * arriving here joins no capability contract.
+ *
+ * The corollary is the rule for adding to this file, and it runs the other way
+ * too: a name that WANTS to be public gets its `@internal` tag removed and
+ * joins a capability contract — it does not stay on the barrel wearing a tag.
+ * That is what happened to `fetchClientConfig`, which the SDK's own `@public`
+ * prose told a workflow-app author to call while the export excluded it.
+ *
+ * Named re-exports rather than `export *`: the wildcard form needs a
+ * `noReExportAll` suppression, and the escape-hatch ratchet only moves down.
+ *
+ * @module internal
+ */
+export { buildAgentUrl, loadClientConfig } from "./client-config.ts";
+export { ToolConfigContext } from "./components/tool-config-context.ts";
+export { ApiUrlChip, SessionUrlChips, UiUrlChip } from "./components/url-chips.tsx";
+export { SessionProvider, ThemeProvider } from "./context.ts";
+export { VOICE_CAPTURE_CONSTRAINTS } from "./types.ts";
+export { TRANSCRIBING_PLACEHOLDER } from "./use-user-transcript.ts";
+export { DEFAULT_PROGRESS_POLL_MS } from "./use-workflow-progress.ts";
+export { DEFAULT_WORKFLOW_POLL_MS, MAX_MISSING_READS } from "./use-workflow-run.ts";

package/dist/internal.js

@@ -0,0 +1,8 @@
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-C7fQrioM.js";
+import { SessionProvider, ThemeProvider } from "./context.js";
+import { n as SessionUrlChips, r as UiUrlChip, t as ApiUrlChip } from "./url-chips-oyy_Eiqh.js";
+import { t as TRANSCRIBING_PLACEHOLDER } from "./use-user-transcript-uyHhzy4d.js";
+import { t as ToolConfigContext } from "./tool-config-context-Es4YUzV2.js";
+import { i as DEFAULT_PROGRESS_POLL_MS, n as MAX_MISSING_READS, t as DEFAULT_WORKFLOW_POLL_MS } from "./use-workflow-run-DdhWmbx-.js";
+import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
+export { ApiUrlChip, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, MAX_MISSING_READS, SessionProvider, SessionUrlChips, TRANSCRIBING_PLACEHOLDER, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, loadClientConfig };

package/dist/linked-client.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `createLinkedClient` — which client this page IS: a device it was linked to
+ * (by a spoken code, a QR scan, a pairing flow of the app's own), else this
+ * browser's own `browserClientId()`.
+ *
+ * A page linked to a speaker becomes the speaker's twin: it sends the
+ * speaker's id as `?client=`, so its sessions join the speaker's durable
+ * conversation and its inbox takes the speaker's reminders. Every such page
+ * kept the link in `localStorage` and wrote the same read-validate-fallback;
+ * the part worth having once is the VALIDATION — a stored id that is not a
+ * client id (letters, digits, `-`, `_`, at most 64) is treated as no link, so
+ * a corrupted entry falls back to the browser's own id rather than being sent
+ * and ignored by the server (a session with no client at all).
+ *
+ * @module
+ */
+/**
+ * Options for {@link createLinkedClient}.
+ *
+ * @public
+ */
+export type LinkedClientOptions = {
+    /** The `localStorage` key the link is kept under, used as given — choose one that is yours. */
+    key: string;
+    /**
+     * This browser's own id, used while unlinked. Default: {@link browserClientId}
+     * for the page's agent — pass your own to carry over an id minted before.
+     */
+    fallback?: (() => string) | undefined;
+};
+/**
+ * Which client a page is — see {@link createLinkedClient}.
+ *
+ * @public
+ */
+export type LinkedClient = {
+    /** The client this page is now: the linked one, else this browser's own. */
+    id(): string;
+    /** The linked client, or `undefined` while unlinked. */
+    linked(): string | undefined;
+    /** This browser's own id, linked or not — what it asks for a link code AS. */
+    own(): string;
+    /**
+     * Link to `id` (`undefined` unlinks). An invalid id unlinks too. Takes effect
+     * on the next read — a mounted session's next connection attempt, since
+     * `mountClient({ client })` asks per attempt; reload to move the inbox too.
+     */
+    set(id: string | undefined): void;
+    /** Unlink: back to this browser's own id. */
+    clear(): void;
+};
+/**
+ * A page's client id with a link on top — see this module's doc.
+ *
+ * @example A page that can be linked to a speaker
+ * ```ts
+ * import { createLinkedClient, mountClient } from "@alexkroman1/aai-ui";
+ *
+ * const client = createLinkedClient({ key: "my-speaker:linked" });
+ *
+ * mountClient({ client: client.id });
+ * // …after the speaker reads out its id: client.set(spokenId); location.reload();
+ * ```
+ *
+ * @param options - Where the link is kept, and the unlinked id; see {@link LinkedClientOptions}.
+ * @returns The handle; see {@link LinkedClient}.
+ *
+ * @public
+ */
+export declare function createLinkedClient(options: LinkedClientOptions): LinkedClient;