@lunnoa/client 2.0.0 → 2.2.0

package/README.md

@@ -27,49 +27,17 @@ npm install @lunnoa/client
 npx @lunnoa/client init my-app --url https://lunnoa.your-company.example
 ```
 
-Scaffolds the [lunnoa-starter](https://github.com/lunnoa-automate/lunnoa-starter) Next.js template (thin, Docker-deployable, both auth patterns behind `LUNNOA_AUTH_MODE`) and writes `.env`, prompting for an API key when run interactively. `--template <owner/repo[#ref]|./local-folder>` overrides the source. Then `npm install` and open the folder in Claude Code / Cursor / Codex.
+Scaffolds the [lunnoa-starter](https://github.com/lunnoa-automate/lunnoa-starter) Next.js template (thin, Docker-deployable, Lunnoa user login) and writes `.env`, prompting for an API key for CLI commands when run interactively. `--template <owner/repo[#ref]|./local-folder>` overrides the source. Then `npm install` and open the folder in Claude Code / Cursor / Codex.
 
 ## Quickstart
 
 ```typescript
-import { LunnoaClient } from '@lunnoa/client';
+import { createBrowserClient, isLoginRequires2FA } from '@lunnoa/client';
 
-const lunnoa = new LunnoaClient({
+const lunnoa = createBrowserClient({
   baseUrl: 'https://lunnoa.your-company.example',
-  apiKey: process.env.LUNNOA_API_KEY, // lna_... — server-side only
 });
 
-const { data: invoices } = await lunnoa.entities.list({
-  objectTypeSlug: 'invoice',
-  state: 'pending',
-  expansion: ['attributes'],
-});
-```
-
-A SuperAdmin creates API keys in **Adminspace → API keys**, choosing the workspace and an RBAC role for the key's service account. The role is the key's entire capability model — grant the minimum permission set, not Admin.
-
-## Two auth patterns
-
-| Pattern | Credential | Where |
-|---|---|---|
-| **A. Backend holds the key** | `apiKey: 'lna_...'` via `createServerClient` | Your server, background jobs, server-rendered pages. The key acts as a workspace-scoped service account. |
-| **B. End users are Lunnoa users** | User JWT via `createBrowserClient` + `lunnoa.auth.*` | Browser apps. Login, 2FA, refresh, and SSO discovery are wrapped; per-user permissions apply. |
-
-```typescript
-import {
-  createBrowserClient,
-  createServerClient,
-  isLoginRequires2FA,
-} from '@lunnoa/client';
-
-// Pattern A — server-side
-const server = createServerClient({
-  baseUrl,
-  apiKey: process.env.LUNNOA_API_KEY!,
-});
-
-// Pattern B — browser (tokens in localStorage by default; auto-refresh on 401)
-const lunnoa = createBrowserClient({ baseUrl });
 const result = await lunnoa.auth.login({ email, password });
 if (isLoginRequires2FA(result)) {
   await lunnoa.auth.verify2faLogin({
@@ -77,12 +45,17 @@ if (isLoginRequires2FA(result)) {
     token: totpCode,
   });
 }
-const me = await lunnoa.auth.me();
+
+const { data: invoices } = await lunnoa.entities.list({
+  objectTypeSlug: 'invoice',
+  state: 'pending',
+  expansion: ['attributes'],
+});
 ```
 
-**API keys never ship to browsers.** The SDK enforces this: constructing a client with an `lna_` key while `window` exists throws immediately. Browser apps either use Pattern B or call your own backend, which holds the key (backend-for-frontend).
+People using the app sign in as Lunnoa users (invite, SSO, or SCIM). Their permissions apply. The deployment must allow your origin via `CORS_ALLOWED_ORIGINS`.
 
-For Pattern B the deployment must allow your origin via its `CORS_ALLOWED_ORIGINS` configuration. See the Authentication guide under `guides/develop/client/auth` in Lunnoa Docs for SSO redirect constraints and token stores.
+`lna_...` API keys are for the CLI (discovery, codegen, deploy), not for the app session. A SuperAdmin creates them in **Adminspace → API keys**, with a minimal RBAC role. The SDK throws if an `lna_` key is used while `window` exists. See the Authentication guide under `guides/develop/client/auth` in Lunnoa Docs for SSO redirect constraints and token stores.
 
 ### React (optional)
 
@@ -253,10 +226,10 @@ npx @lunnoa/client codegen --url https://lunnoa.your-company.example --api-key l
 This writes `lunnoa.generated.ts`:
 
 ```typescript
-import { LunnoaClient } from '@lunnoa/client';
+import { createBrowserClient } from '@lunnoa/client';
 import { createDeploymentClient } from './lunnoa/lunnoa.generated';
 
-const lunnoa = createDeploymentClient(new LunnoaClient({ baseUrl, apiKey }));
+const lunnoa = createDeploymentClient(createBrowserClient({ baseUrl }));
 
 // Entity attributes and states are compile-time checked:
 const open = await lunnoa.entities.invoice.list({ state: 'pending' });
@@ -304,13 +277,14 @@ npx @lunnoa/client tools get http_action_send-request --json
 npx @lunnoa/client apps list --json
 npx @lunnoa/client apps get http --json
 npx @lunnoa/client connections list --app gmail --json
+npx @lunnoa/client ai-connections list --json
 npx @lunnoa/client agents list --json
 npx @lunnoa/client workflows list --json
 npx @lunnoa/client entity-types list --json
 npx @lunnoa/client features --json
 ```
 
-`tools list` is compact (`appId`, `actionId`, name, flags). `tools get` prints `inputConfig` and a `defineAction({ id, appId, input })` sketch. Auth flags and `LUNNOA_URL` / `LUNNOA_API_KEY` / `lunnoa.config` work the same as deploy. The CLI also reads `./.env` (real environment variables win).
+`tools list` is compact (`appId`, `actionId`, name, flags). `tools get` prints `inputConfig` and a `defineAction({ id, appId, input })` sketch. `ai-connections list --json` prints the model ids each AI connection accepts; use `models[].id` as `defineAgent({ model })`. Auth flags and `LUNNOA_URL` / `LUNNOA_API_KEY` / `lunnoa.config` work the same as deploy. The CLI also reads `./.env` (real environment variables win).
 
 ## Regenerating the API types
 

package/dist/cli.js

@@ -12,7 +12,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)) {
@@ -94,7 +94,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) {
@@ -472,7 +472,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 } : {}
   };
@@ -852,6 +852,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) {
@@ -2050,7 +2066,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;
@@ -2077,6 +2093,8 @@ var LunnoaClient = class {
   variables;
   scorecards;
   connections;
+  /** AI provider connections and the model ids each one accepts. */
+  aiConnections;
   workflowApps;
   discovery;
   constructor(options) {
@@ -2100,6 +2118,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);
   }
 };
@@ -2113,6 +2132,7 @@ var GROUPS_WITH_SUBCOMMAND = /* @__PURE__ */ new Set([
   "tools",
   "apps",
   "connections",
+  "ai-connections",
   "skills"
 ]);
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
@@ -2210,6 +2230,7 @@ var USAGE = `Usage:
   npx @lunnoa/client apps get <appId> [--json]
   npx @lunnoa/client connections list [--app <appId>] [--json]
   npx @lunnoa/client connections get <connectionId> [--json]
+  npx @lunnoa/client ai-connections list [--json]
   npx @lunnoa/client agents list [--json]
   npx @lunnoa/client workflows list [--json]
   npx @lunnoa/client entity-types list [--json]
@@ -2239,6 +2260,9 @@ Options:
 Environment: LUNNOA_URL, LUNNOA_API_KEY (also read from ./.env)
 Optional config file: lunnoa.config.ts | .mjs | .js | .json
 
+ai-connections list prints the model ids each AI connection accepts. Use
+models[].id as defineAgent({ model }). connections list is app connections
+(Gmail, HTTP), not model providers.
 tools get prints inputConfig and a defineAction() sketch. tools list is compact;
 run tools get for the schema. An entity-type slug is unique on the deployment
 and grants the API key's workspace when the slug is new.
@@ -2602,6 +2626,40 @@ async function runAppsGet(client, args) {
     { key: "needsConnection", header: "NEEDS_CONN" }
   ]);
 }
+async function runAiConnectionsList(client, args) {
+  const connections = await client.aiConnections.list();
+  if (args.json) {
+    printJson(connections);
+    return;
+  }
+  const rows = connections.flatMap((connection) => {
+    if (connection.models.length === 0) {
+      return [
+        {
+          name: connection.name,
+          provider: connection.provider,
+          model: "",
+          isDefault: connection.isDefault,
+          id: connection.id
+        }
+      ];
+    }
+    return connection.models.map((model) => ({
+      name: connection.name,
+      provider: connection.provider,
+      model: model.id,
+      isDefault: connection.isDefault && model.isDefault,
+      id: connection.id
+    }));
+  });
+  printTable(rows, [
+    { key: "name", header: "CONNECTION" },
+    { key: "provider", header: "PROVIDER" },
+    { key: "model", header: "MODEL" },
+    { key: "isDefault", header: "DEFAULT" },
+    { key: "id", header: "ID" }
+  ]);
+}
 async function runConnectionsList(client, args) {
   const connections = await client.connections.list({
     expansion: ["workflowAppId", "connectionId", "createdAt"]
@@ -3026,7 +3084,7 @@ function generateFactory(entityEntries, workflowEntries, agentEntries) {
  * entity types, workflows, and agents.
  *
  * \`\`\`ts
- * const lunnoa = createDeploymentClient(new LunnoaClient({ baseUrl, apiKey }));
+ * const lunnoa = createDeploymentClient(createBrowserClient({ baseUrl }));
  * const open = await lunnoa.entities.invoice.list({ state: 'pending' });
  * \`\`\`
  */
@@ -3328,7 +3386,7 @@ async function runInit(args) {
   if (process.stdin.isTTY && (!url || !apiKey)) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     url ||= (await rl.question("Lunnoa URL (e.g. https://lunnoa.your-company.example): ")).trim();
-    apiKey ||= (await rl.question("API key lna_... (server-side only; Enter to skip and sign in as a user instead): ")).trim();
+    apiKey ||= (await rl.question("API key lna_... (CLI only: discovery, codegen, deploy. Enter to skip): ")).trim();
     rl.close();
   }
   const example = await readFile(join(dest, ".env.example"), "utf8").catch(() => "");
@@ -3347,7 +3405,7 @@ Next steps:`);
   console.log(`  cd ${args.path}`);
   console.log("  npm install");
   if (!apiKey) {
-    console.log("  Add LUNNOA_API_KEY to .env, or set LUNNOA_AUTH_MODE=user to sign in with your Lunnoa account");
+    console.log("  The app signs people in as Lunnoa users. Add LUNNOA_API_KEY to .env when you want CLI discovery and deploy");
   }
   console.log("  npm run dev");
   console.log("  Open the folder in Claude Code / Cursor / Codex and describe your idea.");
@@ -3490,6 +3548,7 @@ var DISCOVERY_SUBCOMMANDS = {
   tools: ["list", "get", "search"],
   apps: ["list", "get"],
   connections: ["list", "get"],
+  "ai-connections": ["list"],
   tables: ["list", "get"],
   features: void 0
 };
@@ -3523,7 +3582,7 @@ ${USAGE}`
 }
 async function runDiscovery(args) {
   const { command, subcommand } = args;
-  if (command === "tools" || command === "apps" || command === "connections" || command === "tables") {
+  if (command === "tools" || command === "apps" || command === "connections" || command === "ai-connections" || command === "tables") {
     assertKnownDiscoveryShape(args);
   }
   if (!isDiscoveryCommand(args)) {
@@ -3558,6 +3617,10 @@ async function runDiscovery(args) {
     await runConnectionsGet(client, args);
     return true;
   }
+  if (command === "ai-connections" && subcommand === "list") {
+    await runAiConnectionsList(client, args);
+    return true;
+  }
   if (command === "agents" && subcommand === "list") {
     await runAgentsList(client, args);
     return true;

package/dist/index.cjs

@@ -8,7 +8,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)) {
@@ -90,7 +90,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) {
@@ -468,7 +468,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 } : {}
   };
@@ -894,6 +894,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) {
@@ -2092,7 +2108,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;
@@ -2119,6 +2135,8 @@ var LunnoaClient = class {
   variables;
   scorecards;
   connections;
+  /** AI provider connections and the model ids each one accepts. */
+  aiConnections;
   workflowApps;
   discovery;
   constructor(options) {
@@ -2142,6 +2160,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);
   }
 };
@@ -2223,6 +2242,7 @@ exports.ActionsResource = ActionsResource;
 exports.AgentChatClient = AgentChatClient;
 exports.AgentChatStream = AgentChatStream;
 exports.AgentsResource = AgentsResource;
+exports.AiConnectionsResource = AiConnectionsResource;
 exports.ApprovalsResource = ApprovalsResource;
 exports.AuthResource = AuthResource;
 exports.ConnectionsResource = ConnectionsResource;