@lunnoa/client 2.0.0 → 2.1.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' });

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) {
@@ -2050,7 +2050,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;
@@ -3026,7 +3026,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 +3328,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 +3347,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.");

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) {
@@ -2092,7 +2092,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;