@lunnoa/client 2.0.0 → 2.2.0

package/dist/react.d.cts

@@ -3,7 +3,7 @@ import { ReactNode } from 'react';
 import { UIMessage, UIMessageChunk } from 'ai';
 
 /**
- * Pluggable storage for Pattern B JWTs.
+ * Pluggable storage for Lunnoa user JWTs.
  * The SDK never uses httpOnly cookies: Automate auth is bearer JWT based.
  */
 interface TokenStore {
@@ -24,20 +24,20 @@ interface LunnoaClientOptions {
      */
     baseUrl: string;
     /**
-     * Server-side machine credential (`lna_...`). Never usable in browsers —
-     * the constructor throws if one is supplied while `window` exists.
+     * Machine credential (`lna_...`) for the CLI and operator scripts, not for app login.
+     * Never usable in browsers: the constructor throws if one is supplied while `window` exists.
      */
     apiKey?: string;
     /**
      * User JWT obtained from login / SSO. The supported credential for browser
      * applications. May be a function so refreshed tokens are picked up per request.
      *
-     * Prefer {@link tokenStore} for Pattern B so login/refresh can persist tokens
+     * Prefer {@link tokenStore} so login/refresh can persist tokens
      * and optionally auto-refresh on 401.
      */
     accessToken?: string | (() => string | Promise<string>);
     /**
-     * Optional JWT store for Pattern B. When set, authenticated requests read
+     * Optional JWT store for a signed-in Lunnoa user. When set, authenticated requests read
      * the access token from the store. Login / refresh helpers write back into it.
      */
     tokenStore?: TokenStore;
@@ -107,7 +107,10 @@ declare class HttpClient {
 
 type ChatMode = 'builder' | 'preview';
 interface StreamMessageOptions {
-    /** Agent chat mode; defaults to the server default (`builder`). */
+    /**
+     * Agent chat mode. Defaults to `preview` (10 model rounds, a normal agent run).
+     * `builder` is the agent-editor interview and stops after 4 rounds.
+     */
     chatMode?: ChatMode;
     /** Optional image attachment forwarded with this turn. */
     data?: {
@@ -937,7 +940,7 @@ interface components {
             description?: string;
             /** @description System instructions / prompt for the agent. */
             instructions: string;
-            /** @description Selected model id on the AI provider connection (e.g. `gpt-4o`). */
+            /** @description Catalogue model id enabled on the AI connection. Example: `deepseek-ai/DeepSeek-V4-Pro`. Discover ids with GET /api/ai-connections. */
             model: string;
             /** @description AiProviderConnection UUID. When omitted, platform AI defaults apply. */
             aiConnectionId?: string;
@@ -2074,6 +2077,32 @@ interface components {
             /** Format: date-time */
             updatedAt: string;
         };
+        PublicAiModelResponseDto: {
+            /** @description Catalogue model id passed to agent deploy as `model`. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
+            id: string;
+            /** @description Display name. */
+            name: string;
+            /** @description True when this is the model used if an agent deploy omits `model` on this connection. */
+            isDefault: boolean;
+            /** @description Whether the model can call tools. */
+            supportsTools: boolean;
+            /** @description Whether the model accepts image input. */
+            supportsVision: boolean;
+            /** @description Whether the model exposes a reasoning mode. */
+            supportsReasoning: boolean;
+        };
+        PublicAiConnectionResponseDto: {
+            /** @description AiProviderConnection UUID. Pass as `aiConnectionId` / `defineAiConnection({ id })` when this connection is not the default. */
+            id: string;
+            /** @description Connection display name. Example: `Lunnoa LLMs`. */
+            name: string;
+            /** @description Provider slug. Example: `featherless` or `openai`. */
+            provider: string;
+            /** @description True for the connection used when an agent deploy omits `aiConnectionId`. */
+            isDefault: boolean;
+            /** @description Models this connection accepts. Inactive models are omitted. */
+            models: components["schemas"]["PublicAiModelResponseDto"][];
+        };
         ConnectionWorkspaceDto: {
             /** @description Workspace ID. */
             id: string;
@@ -2682,7 +2711,10 @@ interface AgentDefinition {
     slug: string;
     name?: string;
     description?: string;
-    /** Selected model id on the AI provider connection. */
+    /**
+     * Catalogue model id from `ai-connections list` (`models[].id`).
+     * Example on Lunnoa LLMs: `deepseek-ai/DeepSeek-V4-Pro`.
+     */
     model: string;
     instructions: string;
     aiConnection?: AiConnectionDefinition;
@@ -2796,7 +2828,7 @@ interface CurrentUser {
 }
 
 /**
- * Login, refresh, SSO discovery, and session helpers for Pattern B.
+ * Login, refresh, SSO discovery, and session helpers for Lunnoa users.
  *
  * Password login, token exchange, refresh, and SSO provider listing are
  * **public** endpoints (no Bearer). `me()` requires a user JWT.
@@ -2885,6 +2917,36 @@ declare class SsoAuthResource {
     getLoginUrl(providerId: string): string;
 }
 
+interface AiConnectionModel {
+    /** Catalogue id for `defineAgent({ model })`. */
+    id: string;
+    name: string;
+    isDefault: boolean;
+    supportsTools: boolean;
+    supportsVision: boolean;
+    supportsReasoning: boolean;
+}
+interface AiConnection {
+    /** AiProviderConnection UUID for `defineAiConnection({ id })`. */
+    id: string;
+    name: string;
+    /** Provider slug, for example `featherless` or `openai`. */
+    provider: string;
+    /** True when agent deploy uses this connection if `aiConnection` is omitted. */
+    isDefault: boolean;
+    models: AiConnectionModel[];
+}
+declare class AiConnectionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Lists AI connections the caller can assign to an agent, with the model
+     * ids each connection accepts. Credentials are never included.
+     * Requires `agents:create` (the same permission as agent deploy).
+     */
+    list(): Promise<AiConnection[]>;
+}
+
 declare class ConnectionsResource {
     private readonly http;
     constructor(http: HttpClient);
@@ -3453,28 +3515,21 @@ declare class WorkflowsResource {
 /**
  * Typed client for the Lunnoa Automate Public API.
  *
- * Server-side (Pattern A — the backend holds the key):
- * ```ts
- * const lunnoa = new LunnoaClient({
- *   baseUrl: 'https://lunnoa.acme.example',
- *   apiKey: process.env.LUNNOA_API_KEY, // lna_...
- * });
- * ```
- *
- * Browser (Pattern B — the end user is a Lunnoa user):
+ * Apps sign people in as Lunnoa users:
  * ```ts
  * import { createBrowserClient } from '@lunnoa/client';
  * const lunnoa = createBrowserClient({ baseUrl: 'https://lunnoa.acme.example' });
  * await lunnoa.auth.login({ email, password });
  * ```
  *
- * Passing an `lna_` API key in a browser throws immediately: API keys are
- * workspace-wide server credentials and must never ship to browsers.
+ * `apiKey` (`lna_...`) is for the CLI and operator scripts (codegen, discovery,
+ * deploy). It is not an app login. Passing one while `window` exists throws:
+ * a leaked key acts as that service account across its whole workspace.
  */
 declare class LunnoaClient {
     /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
     readonly http: HttpClient;
-    /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+    /** Login, refresh, SSO discovery, and session helpers for Lunnoa users. */
     readonly auth: AuthResource;
     readonly agents: AgentsResource;
     readonly tasks: TasksResource;
@@ -3501,6 +3556,8 @@ declare class LunnoaClient {
     readonly variables: VariablesResource;
     readonly scorecards: ScorecardsResource;
     readonly connections: ConnectionsResource;
+    /** AI provider connections and the model ids each one accepts. */
+    readonly aiConnections: AiConnectionsResource;
     readonly workflowApps: WorkflowAppsResource;
     readonly discovery: DiscoveryResource;
     constructor(options: LunnoaClientOptions);
@@ -3525,7 +3582,7 @@ interface CreateBrowserClientOptions {
 
 type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
 interface LunnoaAuthContextValue {
-    /** Shared Lunnoa client (Pattern B token store). */
+    /** Shared Lunnoa client (user JWT token store). */
     client: LunnoaClient;
     /** Current user from `GET /api/users/me`, or null when signed out. */
     user: CurrentUser | null;
@@ -3567,7 +3624,7 @@ interface LunnoaAuthContextValue {
     getAccessToken: () => Promise<string | null>;
 }
 type LunnoaAuthProviderProps = {
-    /** Existing Pattern B client (from `createBrowserClient`). */
+    /** Existing browser client (from `createBrowserClient`). */
     client: LunnoaClient;
     children: ReactNode;
 } | (CreateBrowserClientOptions & {
@@ -3575,7 +3632,7 @@ type LunnoaAuthProviderProps = {
     children: ReactNode;
 });
 /**
- * Provides a Pattern B Lunnoa client and session helpers to React trees.
+ * Provides a Lunnoa user client and session helpers to React trees.
  *
  * ```tsx
  * <LunnoaAuthProvider baseUrl={import.meta.env.VITE_LUNNOA_URL}>
@@ -3584,7 +3641,7 @@ type LunnoaAuthProviderProps = {
  * ```
  */
 declare function LunnoaAuthProvider(props: LunnoaAuthProviderProps): react.FunctionComponentElement<react.ProviderProps<LunnoaAuthContextValue | null>>;
-/** Full auth session API for Pattern B React apps. */
+/** Full auth session API for React apps whose users sign in to Lunnoa. */
 declare function useLunnoaAuth(): LunnoaAuthContextValue;
 /** The Lunnoa client from the nearest {@link LunnoaAuthProvider}. */
 declare function useLunnoaClient(): LunnoaClient;
@@ -3652,7 +3709,10 @@ interface UseNeedsInputResult {
 declare function useNeedsInput(source: NeedsInputSource, options?: UseNeedsInputOptions): UseNeedsInputResult;
 
 interface UseAgentChatOptions {
-    /** Agent chat mode forwarded in the request body. */
+    /**
+     * Agent chat mode forwarded in the request body.
+     * Defaults to `preview` (10 model rounds). `builder` stops after 4 rounds.
+     */
     chatMode?: 'builder' | 'preview';
 }
 interface UseAgentChatResult {

package/dist/react.d.ts

@@ -3,7 +3,7 @@ import { ReactNode } from 'react';
 import { UIMessage, UIMessageChunk } from 'ai';
 
 /**
- * Pluggable storage for Pattern B JWTs.
+ * Pluggable storage for Lunnoa user JWTs.
  * The SDK never uses httpOnly cookies: Automate auth is bearer JWT based.
  */
 interface TokenStore {
@@ -24,20 +24,20 @@ interface LunnoaClientOptions {
      */
     baseUrl: string;
     /**
-     * Server-side machine credential (`lna_...`). Never usable in browsers —
-     * the constructor throws if one is supplied while `window` exists.
+     * Machine credential (`lna_...`) for the CLI and operator scripts, not for app login.
+     * Never usable in browsers: the constructor throws if one is supplied while `window` exists.
      */
     apiKey?: string;
     /**
      * User JWT obtained from login / SSO. The supported credential for browser
      * applications. May be a function so refreshed tokens are picked up per request.
      *
-     * Prefer {@link tokenStore} for Pattern B so login/refresh can persist tokens
+     * Prefer {@link tokenStore} so login/refresh can persist tokens
      * and optionally auto-refresh on 401.
      */
     accessToken?: string | (() => string | Promise<string>);
     /**
-     * Optional JWT store for Pattern B. When set, authenticated requests read
+     * Optional JWT store for a signed-in Lunnoa user. When set, authenticated requests read
      * the access token from the store. Login / refresh helpers write back into it.
      */
     tokenStore?: TokenStore;
@@ -107,7 +107,10 @@ declare class HttpClient {
 
 type ChatMode = 'builder' | 'preview';
 interface StreamMessageOptions {
-    /** Agent chat mode; defaults to the server default (`builder`). */
+    /**
+     * Agent chat mode. Defaults to `preview` (10 model rounds, a normal agent run).
+     * `builder` is the agent-editor interview and stops after 4 rounds.
+     */
     chatMode?: ChatMode;
     /** Optional image attachment forwarded with this turn. */
     data?: {
@@ -937,7 +940,7 @@ interface components {
             description?: string;
             /** @description System instructions / prompt for the agent. */
             instructions: string;
-            /** @description Selected model id on the AI provider connection (e.g. `gpt-4o`). */
+            /** @description Catalogue model id enabled on the AI connection. Example: `deepseek-ai/DeepSeek-V4-Pro`. Discover ids with GET /api/ai-connections. */
             model: string;
             /** @description AiProviderConnection UUID. When omitted, platform AI defaults apply. */
             aiConnectionId?: string;
@@ -2074,6 +2077,32 @@ interface components {
             /** Format: date-time */
             updatedAt: string;
         };
+        PublicAiModelResponseDto: {
+            /** @description Catalogue model id passed to agent deploy as `model`. Example: `deepseek-ai/DeepSeek-V4-Pro`. */
+            id: string;
+            /** @description Display name. */
+            name: string;
+            /** @description True when this is the model used if an agent deploy omits `model` on this connection. */
+            isDefault: boolean;
+            /** @description Whether the model can call tools. */
+            supportsTools: boolean;
+            /** @description Whether the model accepts image input. */
+            supportsVision: boolean;
+            /** @description Whether the model exposes a reasoning mode. */
+            supportsReasoning: boolean;
+        };
+        PublicAiConnectionResponseDto: {
+            /** @description AiProviderConnection UUID. Pass as `aiConnectionId` / `defineAiConnection({ id })` when this connection is not the default. */
+            id: string;
+            /** @description Connection display name. Example: `Lunnoa LLMs`. */
+            name: string;
+            /** @description Provider slug. Example: `featherless` or `openai`. */
+            provider: string;
+            /** @description True for the connection used when an agent deploy omits `aiConnectionId`. */
+            isDefault: boolean;
+            /** @description Models this connection accepts. Inactive models are omitted. */
+            models: components["schemas"]["PublicAiModelResponseDto"][];
+        };
         ConnectionWorkspaceDto: {
             /** @description Workspace ID. */
             id: string;
@@ -2682,7 +2711,10 @@ interface AgentDefinition {
     slug: string;
     name?: string;
     description?: string;
-    /** Selected model id on the AI provider connection. */
+    /**
+     * Catalogue model id from `ai-connections list` (`models[].id`).
+     * Example on Lunnoa LLMs: `deepseek-ai/DeepSeek-V4-Pro`.
+     */
     model: string;
     instructions: string;
     aiConnection?: AiConnectionDefinition;
@@ -2796,7 +2828,7 @@ interface CurrentUser {
 }
 
 /**
- * Login, refresh, SSO discovery, and session helpers for Pattern B.
+ * Login, refresh, SSO discovery, and session helpers for Lunnoa users.
  *
  * Password login, token exchange, refresh, and SSO provider listing are
  * **public** endpoints (no Bearer). `me()` requires a user JWT.
@@ -2885,6 +2917,36 @@ declare class SsoAuthResource {
     getLoginUrl(providerId: string): string;
 }
 
+interface AiConnectionModel {
+    /** Catalogue id for `defineAgent({ model })`. */
+    id: string;
+    name: string;
+    isDefault: boolean;
+    supportsTools: boolean;
+    supportsVision: boolean;
+    supportsReasoning: boolean;
+}
+interface AiConnection {
+    /** AiProviderConnection UUID for `defineAiConnection({ id })`. */
+    id: string;
+    name: string;
+    /** Provider slug, for example `featherless` or `openai`. */
+    provider: string;
+    /** True when agent deploy uses this connection if `aiConnection` is omitted. */
+    isDefault: boolean;
+    models: AiConnectionModel[];
+}
+declare class AiConnectionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Lists AI connections the caller can assign to an agent, with the model
+     * ids each connection accepts. Credentials are never included.
+     * Requires `agents:create` (the same permission as agent deploy).
+     */
+    list(): Promise<AiConnection[]>;
+}
+
 declare class ConnectionsResource {
     private readonly http;
     constructor(http: HttpClient);
@@ -3453,28 +3515,21 @@ declare class WorkflowsResource {
 /**
  * Typed client for the Lunnoa Automate Public API.
  *
- * Server-side (Pattern A — the backend holds the key):
- * ```ts
- * const lunnoa = new LunnoaClient({
- *   baseUrl: 'https://lunnoa.acme.example',
- *   apiKey: process.env.LUNNOA_API_KEY, // lna_...
- * });
- * ```
- *
- * Browser (Pattern B — the end user is a Lunnoa user):
+ * Apps sign people in as Lunnoa users:
  * ```ts
  * import { createBrowserClient } from '@lunnoa/client';
  * const lunnoa = createBrowserClient({ baseUrl: 'https://lunnoa.acme.example' });
  * await lunnoa.auth.login({ email, password });
  * ```
  *
- * Passing an `lna_` API key in a browser throws immediately: API keys are
- * workspace-wide server credentials and must never ship to browsers.
+ * `apiKey` (`lna_...`) is for the CLI and operator scripts (codegen, discovery,
+ * deploy). It is not an app login. Passing one while `window` exists throws:
+ * a leaked key acts as that service account across its whole workspace.
  */
 declare class LunnoaClient {
     /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
     readonly http: HttpClient;
-    /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+    /** Login, refresh, SSO discovery, and session helpers for Lunnoa users. */
     readonly auth: AuthResource;
     readonly agents: AgentsResource;
     readonly tasks: TasksResource;
@@ -3501,6 +3556,8 @@ declare class LunnoaClient {
     readonly variables: VariablesResource;
     readonly scorecards: ScorecardsResource;
     readonly connections: ConnectionsResource;
+    /** AI provider connections and the model ids each one accepts. */
+    readonly aiConnections: AiConnectionsResource;
     readonly workflowApps: WorkflowAppsResource;
     readonly discovery: DiscoveryResource;
     constructor(options: LunnoaClientOptions);
@@ -3525,7 +3582,7 @@ interface CreateBrowserClientOptions {
 
 type AuthStatus = 'loading' | 'authenticated' | 'unauthenticated';
 interface LunnoaAuthContextValue {
-    /** Shared Lunnoa client (Pattern B token store). */
+    /** Shared Lunnoa client (user JWT token store). */
     client: LunnoaClient;
     /** Current user from `GET /api/users/me`, or null when signed out. */
     user: CurrentUser | null;
@@ -3567,7 +3624,7 @@ interface LunnoaAuthContextValue {
     getAccessToken: () => Promise<string | null>;
 }
 type LunnoaAuthProviderProps = {
-    /** Existing Pattern B client (from `createBrowserClient`). */
+    /** Existing browser client (from `createBrowserClient`). */
     client: LunnoaClient;
     children: ReactNode;
 } | (CreateBrowserClientOptions & {
@@ -3575,7 +3632,7 @@ type LunnoaAuthProviderProps = {
     children: ReactNode;
 });
 /**
- * Provides a Pattern B Lunnoa client and session helpers to React trees.
+ * Provides a Lunnoa user client and session helpers to React trees.
  *
  * ```tsx
  * <LunnoaAuthProvider baseUrl={import.meta.env.VITE_LUNNOA_URL}>
@@ -3584,7 +3641,7 @@ type LunnoaAuthProviderProps = {
  * ```
  */
 declare function LunnoaAuthProvider(props: LunnoaAuthProviderProps): react.FunctionComponentElement<react.ProviderProps<LunnoaAuthContextValue | null>>;
-/** Full auth session API for Pattern B React apps. */
+/** Full auth session API for React apps whose users sign in to Lunnoa. */
 declare function useLunnoaAuth(): LunnoaAuthContextValue;
 /** The Lunnoa client from the nearest {@link LunnoaAuthProvider}. */
 declare function useLunnoaClient(): LunnoaClient;
@@ -3652,7 +3709,10 @@ interface UseNeedsInputResult {
 declare function useNeedsInput(source: NeedsInputSource, options?: UseNeedsInputOptions): UseNeedsInputResult;
 
 interface UseAgentChatOptions {
-    /** Agent chat mode forwarded in the request body. */
+    /**
+     * Agent chat mode forwarded in the request body.
+     * Defaults to `preview` (10 model rounds). `builder` stops after 4 rounds.
+     */
     chatMode?: 'builder' | 'preview';
 }
 interface UseAgentChatResult {

package/dist/react.js

@@ -56,7 +56,7 @@ function isBrowserEnvironment() {
 function assertApiKeyAllowedInEnvironment(apiKey) {
   if (isBrowserEnvironment()) {
     throw new Error(
-      "Refusing to use a Lunnoa API key (lna_...) in a browser environment. API keys are server-side credentials: anyone opening dev tools could read the key and act as the service account across its whole workspace. Either call the Lunnoa API from your own backend which holds the key (backend-for-frontend pattern), or authenticate the end user with a Lunnoa user JWT and pass it as `accessToken`."
+      "Refusing to use a Lunnoa API key (lna_...) in a browser environment. API keys are for the CLI and operator scripts, not for app login. Anyone opening dev tools could read the key and act as the service account across its whole workspace. Sign the end user in with lunnoa.auth.login and pass their JWT as `accessToken`."
     );
   }
   if (!apiKey.startsWith(API_KEY_PREFIX)) {
@@ -138,7 +138,7 @@ var HttpClient = class {
     }
     if (!options.apiKey && !options.accessToken && !options.tokenStore) {
       throw new Error(
-        "LunnoaClient requires an apiKey (server-side), an accessToken (user JWT), or a tokenStore (Pattern B)."
+        "LunnoaClient requires an accessToken or tokenStore (Lunnoa user JWT), or an apiKey for operator scripts."
       );
     }
     if (options.apiKey) {
@@ -516,7 +516,7 @@ var AgentChatClient = class {
 function messageTaskBody(message, options = {}) {
   return {
     messages: [message],
-    ...options.chatMode ? { chatMode: options.chatMode } : {},
+    chatMode: options.chatMode ?? "preview",
     ...options.data ? { data: options.data } : {},
     ...options.piiResolution ? { piiResolution: options.piiResolution } : {}
   };
@@ -891,6 +891,22 @@ var SsoAuthResource = class {
   }
 };
 
+// src/resources/ai-connections.ts
+var AiConnectionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Lists AI connections the caller can assign to an agent, with the model
+   * ids each connection accepts. Credentials are never included.
+   * Requires `agents:create` (the same permission as agent deploy).
+   */
+  list() {
+    return this.http.get("/api/ai-connections");
+  }
+};
+
 // src/resources/connections.ts
 var ConnectionsResource = class {
   constructor(http) {
@@ -2089,7 +2105,7 @@ var WorkflowsResource = class {
 var LunnoaClient = class {
   /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
   http;
-  /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+  /** Login, refresh, SSO discovery, and session helpers for Lunnoa users. */
   auth;
   agents;
   tasks;
@@ -2116,6 +2132,8 @@ var LunnoaClient = class {
   variables;
   scorecards;
   connections;
+  /** AI provider connections and the model ids each one accepts. */
+  aiConnections;
   workflowApps;
   discovery;
   constructor(options) {
@@ -2139,6 +2157,7 @@ var LunnoaClient = class {
     this.variables = new VariablesResource(this.http);
     this.scorecards = new ScorecardsResource(this.http);
     this.connections = new ConnectionsResource(this.http);
+    this.aiConnections = new AiConnectionsResource(this.http);
     this.discovery = new DiscoveryResource(this.http);
   }
 };
@@ -2540,7 +2559,7 @@ function useAgentChat(agentId, taskId, options = {}) {
         if (!token) return {};
         return { Authorization: `Bearer ${token}` };
       },
-      body: chatMode ? { chatMode } : void 0,
+      body: { chatMode: chatMode ?? "preview" },
       prepareReconnectToStreamRequest: ({ headers, credentials }) => ({
         api,
         headers,