@lunnoa/client 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { UIMessage, UIMessageChunk } from 'ai';
 export { 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 {
@@ -46,20 +46,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;
@@ -5477,7 +5477,7 @@ interface operations {
             query?: {
                 /** @description Comma-separated inclusion flags. Available: all, internal. Pass internal to include executions of internal workflows, which are excluded by default. */
                 includeType?: string;
-                /** @description Comma-separated key:value filters. Available: projectId, workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
+                /** @description Comma-separated key:value filters. Available: workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
                 filterBy?: string;
                 /** @description Comma-separated fields to expand. Available: createdAt, updatedAt, startedAt, stoppedAt, executionNumber, nodes, edges, status, statusMessage, continueExecutionAt, workflow, project, workspace, output, orientation, executionVariables, source, name. The executionPath expansion is only honoured on GET /executions/{executionId}. Example: expansion=status,startedAt,workflow,source */
                 expansion?: string;
@@ -6721,7 +6721,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.
@@ -7379,28 +7379,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;
@@ -7463,11 +7456,10 @@ declare const API_KEY_PREFIX = "lna_";
 /** Returns true when running inside a browser (or browser-like) environment. */
 declare function isBrowserEnvironment(): boolean;
 /**
- * API keys are server-to-server credentials. Shipping one to a browser exposes
- * the whole workspace the key is scoped to, so the SDK refuses outright.
+ * API keys are operator credentials (CLI, codegen, deploy). Shipping one to a
+ * browser exposes the whole workspace the key is scoped to, so the SDK refuses.
  *
- * Browser apps must authenticate end users with a Lunnoa user JWT (Pattern B)
- * or proxy through their own backend which holds the key (Pattern A / BFF).
+ * Apps authenticate end users with a Lunnoa user JWT.
  */
 declare function assertApiKeyAllowedInEnvironment(apiKey: string): void;
 
@@ -7540,7 +7532,7 @@ interface CreateBrowserClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern B helper: browser (or isomorphic) client with JWT storage,
+ * Browser (or isomorphic) client with JWT storage,
  * `lunnoa.auth.login` / refresh, and optional auto-refresh on 401.
  *
  * Never pass an `lna_` API key here.
@@ -7550,13 +7542,13 @@ interface CreateServerClientOptions {
     /** Base URL of the Lunnoa Automate deployment. */
     baseUrl: string;
     /**
-     * Workspace API key (`lna_...`). Preferred for Pattern A backends / BFFs.
+     * Workspace API key (`lna_...`) for operator scripts and the CLI.
+     * Not an app login: people using an app authenticate as Lunnoa users.
      * Mutually exclusive with `accessToken` / `tokenStore`.
      */
     apiKey?: string;
     /**
-     * User JWT (or getter) when the server acts on behalf of a logged-in user.
-     * Prefer this over embedding tokens in the browser when you own the session.
+     * User JWT (or getter) when the server already holds a signed-in Lunnoa user's token.
      */
     accessToken?: string | (() => string | Promise<string>);
     /** Optional store when the server holds both access and refresh tokens. */
@@ -7566,10 +7558,9 @@ interface CreateServerClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern A (or server-side Pattern B) helper for Node / BFF / route handlers.
- *
- * Provide `apiKey` for a service account, or `accessToken` / `tokenStore` for a
- * user JWT held on the server. Throws if used with an API key in a browser.
+ * Node helper for a Lunnoa user JWT held on the server, or an `lna_` key for
+ * operator scripts. App login uses {@link createBrowserClient}. Throws if
+ * used with an API key in a browser.
  */
 declare function createServerClient(options: CreateServerClientOptions): LunnoaClient;
 

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { UIMessage, UIMessageChunk } from 'ai';
 export { 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 {
@@ -46,20 +46,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;
@@ -5477,7 +5477,7 @@ interface operations {
             query?: {
                 /** @description Comma-separated inclusion flags. Available: all, internal. Pass internal to include executions of internal workflows, which are excluded by default. */
                 includeType?: string;
-                /** @description Comma-separated key:value filters. Available: projectId, workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
+                /** @description Comma-separated key:value filters. Available: workflowId, source (WORKFLOW|SDK), objectId. Example: filterBy=workflowId:wf_123 or filterBy=objectId:<uuid> */
                 filterBy?: string;
                 /** @description Comma-separated fields to expand. Available: createdAt, updatedAt, startedAt, stoppedAt, executionNumber, nodes, edges, status, statusMessage, continueExecutionAt, workflow, project, workspace, output, orientation, executionVariables, source, name. The executionPath expansion is only honoured on GET /executions/{executionId}. Example: expansion=status,startedAt,workflow,source */
                 expansion?: string;
@@ -6721,7 +6721,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.
@@ -7379,28 +7379,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;
@@ -7463,11 +7456,10 @@ declare const API_KEY_PREFIX = "lna_";
 /** Returns true when running inside a browser (or browser-like) environment. */
 declare function isBrowserEnvironment(): boolean;
 /**
- * API keys are server-to-server credentials. Shipping one to a browser exposes
- * the whole workspace the key is scoped to, so the SDK refuses outright.
+ * API keys are operator credentials (CLI, codegen, deploy). Shipping one to a
+ * browser exposes the whole workspace the key is scoped to, so the SDK refuses.
  *
- * Browser apps must authenticate end users with a Lunnoa user JWT (Pattern B)
- * or proxy through their own backend which holds the key (Pattern A / BFF).
+ * Apps authenticate end users with a Lunnoa user JWT.
  */
 declare function assertApiKeyAllowedInEnvironment(apiKey: string): void;
 
@@ -7540,7 +7532,7 @@ interface CreateBrowserClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern B helper: browser (or isomorphic) client with JWT storage,
+ * Browser (or isomorphic) client with JWT storage,
  * `lunnoa.auth.login` / refresh, and optional auto-refresh on 401.
  *
  * Never pass an `lna_` API key here.
@@ -7550,13 +7542,13 @@ interface CreateServerClientOptions {
     /** Base URL of the Lunnoa Automate deployment. */
     baseUrl: string;
     /**
-     * Workspace API key (`lna_...`). Preferred for Pattern A backends / BFFs.
+     * Workspace API key (`lna_...`) for operator scripts and the CLI.
+     * Not an app login: people using an app authenticate as Lunnoa users.
      * Mutually exclusive with `accessToken` / `tokenStore`.
      */
     apiKey?: string;
     /**
-     * User JWT (or getter) when the server acts on behalf of a logged-in user.
-     * Prefer this over embedding tokens in the browser when you own the session.
+     * User JWT (or getter) when the server already holds a signed-in Lunnoa user's token.
      */
     accessToken?: string | (() => string | Promise<string>);
     /** Optional store when the server holds both access and refresh tokens. */
@@ -7566,10 +7558,9 @@ interface CreateServerClientOptions {
     headers?: Record<string, string>;
 }
 /**
- * Pattern A (or server-side Pattern B) helper for Node / BFF / route handlers.
- *
- * Provide `apiKey` for a service account, or `accessToken` / `tokenStore` for a
- * user JWT held on the server. Throws if used with an API key in a browser.
+ * Node helper for a Lunnoa user JWT held on the server, or an `lna_` key for
+ * operator scripts. App login uses {@link createBrowserClient}. Throws if
+ * used with an API key in a browser.
  */
 declare function createServerClient(options: CreateServerClientOptions): LunnoaClient;
 

package/dist/index.js

@@ -6,7 +6,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)) {
@@ -88,7 +88,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) {
@@ -2090,7 +2090,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;