@noodleseed/assistant 1.0.0 → 1.1.0

package/README.md

@@ -12,22 +12,54 @@ Never pass an embed client secret, model key, MCP token, or raw application sess
 component. Exchange the already-authenticated user from the customer backend and return only the short-lived
 assistant session.
 
+The model configuration and SaaS integration credentials have different owners:
+
+| Owner | Configuration | Destination |
+| --- | --- | --- |
+| Noodle deployment | `ASSISTANT_MODEL_BASE_URL`, `ASSISTANT_MODEL`, `ASSISTANT_MODEL_API_KEY` | Managed with `noodle variables set` / `noodle secrets set` |
+| Customer backend | `NOODLE_SERVICE_URL`, `NOODLE_ASSISTANT_CLIENT_ID`, `NOODLE_ASSISTANT_CLIENT_SECRET` | Backend environment or secret manager only |
+
+`allowedOrigins` accepts exact origins. Production origins must be HTTPS; plain HTTP is accepted only for
+loopback development origins such as `http://localhost:3000`. Local MCP authoring remains available without
+login, but an external browser embed needs an active deployment before its deployment-bound client can be
+created.
+
+Runtime requirements: Node.js 20+ for the server helper; the package ships ESM and CommonJS with full
+export conditions, so bundlers and plain Node resolve it without aliases or type shims.
+
+The full, always-current integration guide (access modes, session response contract, framework notes, and
+troubleshooting) lives at <https://docs.noodleseed.dev/guides/embedded-assistant>. Authoring and deploying
+the server itself is `@noodleseed/one` (`npm install -g @noodleseed/one`).
+
 ## Quick start
 
-Install the package in the customer web application:
+Install the package in the customer web application with that application's existing package manager. For
+example:
+
+```bash
+npm install @noodleseed/assistant
+```
+
+Configure the model through Noodle managed config, validate, and deploy the assistant-enabled server before
+creating the embed client:
 
 ```bash
-pnpm add @noodleseed/assistant
+noodle variables set ASSISTANT_MODEL_BASE_URL --scope env --org acme --app support --env prod --value https://model.example/v1
+noodle variables set ASSISTANT_MODEL --scope env --org acme --app support --env prod --value your-model
+noodle secrets set ASSISTANT_MODEL_API_KEY --scope env --org acme --app support --env prod --from-env ASSISTANT_MODEL_API_KEY
+noodle check --target embedded-assistant
+noodle deploy --org acme --app support --env prod
 ```
 
-Create an embed client after deploying an assistant-enabled server:
+Then create the deployment-bound client:
 
 ```bash
 noodle assistant clients create --name web --org acme --app support --env prod
 ```
 
 The command saves `{ clientId, clientSecret }` to a mode-`0600` file and prints its path, never the secret.
-Load that file only in your backend. A framework route can exchange the current signed-in user like this:
+Move those values to the customer backend's secret manager without printing or committing them. A framework
+route can exchange the current signed-in user like this:
 
 ```ts
 import { createAssistantSession } from '@noodleseed/assistant/server';
@@ -65,6 +97,21 @@ import { NoodleAssistant } from '@noodleseed/assistant/react';
 <NoodleAssistant sessionEndpoint="/api/assistant/session" theme="auto" />;
 ```
 
+Assistant text renders as provider deltas arrive. If a turn finds an expired session, the component calls
+the same authenticated session endpoint and retries that unprocessed message once. Confirmations never
+replay across sessions. React applications may observe recovery and structured failures:
+
+```tsx
+<NoodleAssistant
+  sessionEndpoint="/api/assistant/session"
+  onSessionExpired={() => reportAssistantRecovery()}
+  onError={({ code, status, retryable }) => reportAssistantError({ code, status, retryable })}
+/>;
+```
+
+`createAssistantSession` returns the opaque token, expiry, resolved non-secret configuration, and explicit
+`endpoints.turns` / `endpoints.toolConfirmations` URLs. Forward that response unchanged to the component.
+
 The MCP server's top-level `branding` block provides the shared identity and theme for widgets and the
 assistant. Set semantic CSS variables only for application-level integration overrides:
 

package/dist/appearance-KDbtkt2G.d.cts

@@ -0,0 +1,88 @@
+type AssistantThemeMode = 'auto' | 'light' | 'dark';
+type AssistantLayoutMode = 'floating' | 'inline' | 'drawer';
+type AssistantPosition = 'bottom-left' | 'bottom-right';
+interface AssistantConfiguration {
+    readonly branding?: {
+        readonly name?: string;
+        readonly accent?: string;
+        readonly surface?: string;
+        readonly surfaceDark?: string;
+        readonly logo?: AssistantBrandAsset;
+        readonly mark?: AssistantBrandAsset;
+        readonly avatar?: AssistantBrandAsset;
+        readonly theme?: {
+            readonly light?: BrandThemeOverrides;
+            readonly dark?: BrandThemeOverrides;
+        };
+        readonly radius?: 'none' | 'sm' | 'md' | 'lg';
+        readonly density?: 'compact' | 'comfortable';
+        readonly typography?: 'system' | 'serif' | 'mono';
+        readonly colorScheme?: AssistantThemeMode;
+    };
+    readonly assistant?: AssistantUiConfiguration;
+}
+interface AssistantBrandAsset {
+    readonly uri: string;
+    readonly darkUri?: string;
+    readonly alt: string;
+}
+interface BrandThemeOverrides {
+    readonly surface?: string;
+    readonly surfaceRaised?: string;
+    readonly surfaceMuted?: string;
+    readonly text?: string;
+    readonly textMuted?: string;
+    readonly accent?: string;
+    readonly accentText?: string;
+    readonly link?: string;
+    readonly border?: string;
+    readonly borderStrong?: string;
+    readonly focus?: string;
+    readonly success?: string;
+    readonly warning?: string;
+    readonly danger?: string;
+    readonly code?: string;
+}
+interface AssistantUiConfiguration {
+    readonly layout?: {
+        readonly mode?: AssistantLayoutMode;
+        readonly position?: AssistantPosition;
+        readonly panelWidth?: number;
+        readonly panelMinHeight?: number;
+        readonly panelMaxHeight?: number;
+        readonly zIndex?: number;
+        readonly density?: 'compact' | 'comfortable';
+        readonly mobileFullscreen?: boolean;
+    };
+    readonly behavior?: {
+        readonly startOpen?: boolean;
+        readonly closeOnEscape?: boolean;
+        readonly closeOnOutsideClick?: boolean;
+        readonly showLauncher?: boolean;
+        readonly showHeader?: boolean;
+        readonly showAvatars?: boolean;
+        readonly showTimestamps?: boolean;
+    };
+    readonly labels?: Partial<AssistantLabels>;
+    readonly suggestedPrompts?: readonly string[];
+    readonly privacyUrl?: string;
+    readonly termsUrl?: string;
+    readonly locale?: string;
+    readonly direction?: 'ltr' | 'rtl' | 'auto';
+}
+interface AssistantLabels {
+    readonly welcomeHeading: string;
+    readonly welcomeMessage: string;
+    readonly composerPlaceholder: string;
+    readonly send: string;
+    readonly stop: string;
+    readonly close: string;
+    readonly open: string;
+    readonly confirm: string;
+    readonly cancel: string;
+    readonly retry: string;
+    readonly unavailable: string;
+    readonly sessionExpired: string;
+}
+
+export type { AssistantThemeMode as A, AssistantConfiguration as a };

package/dist/appearance-KDbtkt2G.d.ts

@@ -0,0 +1,88 @@
+type AssistantThemeMode = 'auto' | 'light' | 'dark';
+type AssistantLayoutMode = 'floating' | 'inline' | 'drawer';
+type AssistantPosition = 'bottom-left' | 'bottom-right';
+interface AssistantConfiguration {
+    readonly branding?: {
+        readonly name?: string;
+        readonly accent?: string;
+        readonly surface?: string;
+        readonly surfaceDark?: string;
+        readonly logo?: AssistantBrandAsset;
+        readonly mark?: AssistantBrandAsset;
+        readonly avatar?: AssistantBrandAsset;
+        readonly theme?: {
+            readonly light?: BrandThemeOverrides;
+            readonly dark?: BrandThemeOverrides;
+        };
+        readonly radius?: 'none' | 'sm' | 'md' | 'lg';
+        readonly density?: 'compact' | 'comfortable';
+        readonly typography?: 'system' | 'serif' | 'mono';
+        readonly colorScheme?: AssistantThemeMode;
+    };
+    readonly assistant?: AssistantUiConfiguration;
+}
+interface AssistantBrandAsset {
+    readonly uri: string;
+    readonly darkUri?: string;
+    readonly alt: string;
+}
+interface BrandThemeOverrides {
+    readonly surface?: string;
+    readonly surfaceRaised?: string;
+    readonly surfaceMuted?: string;
+    readonly text?: string;
+    readonly textMuted?: string;
+    readonly accent?: string;
+    readonly accentText?: string;
+    readonly link?: string;
+    readonly border?: string;
+    readonly borderStrong?: string;
+    readonly focus?: string;
+    readonly success?: string;
+    readonly warning?: string;
+    readonly danger?: string;
+    readonly code?: string;
+}
+interface AssistantUiConfiguration {
+    readonly layout?: {
+        readonly mode?: AssistantLayoutMode;
+        readonly position?: AssistantPosition;
+        readonly panelWidth?: number;
+        readonly panelMinHeight?: number;
+        readonly panelMaxHeight?: number;
+        readonly zIndex?: number;
+        readonly density?: 'compact' | 'comfortable';
+        readonly mobileFullscreen?: boolean;
+    };
+    readonly behavior?: {
+        readonly startOpen?: boolean;
+        readonly closeOnEscape?: boolean;
+        readonly closeOnOutsideClick?: boolean;
+        readonly showLauncher?: boolean;
+        readonly showHeader?: boolean;
+        readonly showAvatars?: boolean;
+        readonly showTimestamps?: boolean;
+    };
+    readonly labels?: Partial<AssistantLabels>;
+    readonly suggestedPrompts?: readonly string[];
+    readonly privacyUrl?: string;
+    readonly termsUrl?: string;
+    readonly locale?: string;
+    readonly direction?: 'ltr' | 'rtl' | 'auto';
+}
+interface AssistantLabels {
+    readonly welcomeHeading: string;
+    readonly welcomeMessage: string;
+    readonly composerPlaceholder: string;
+    readonly send: string;
+    readonly stop: string;
+    readonly close: string;
+    readonly open: string;
+    readonly confirm: string;
+    readonly cancel: string;
+    readonly retry: string;
+    readonly unavailable: string;
+    readonly sessionExpired: string;
+}
+
+export type { AssistantThemeMode as A, AssistantConfiguration as a };