@lunnoa/client 0.0.0-development

package/dist/index.cjs

@@ -0,0 +1,2141 @@
+'use strict';
+
+// src/core/auth.ts
+var API_KEY_PREFIX = "lna_";
+function isBrowserEnvironment() {
+  return typeof window !== "undefined";
+}
+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`."
+    );
+  }
+  if (!apiKey.startsWith(API_KEY_PREFIX)) {
+    throw new Error(
+      `Invalid Lunnoa API key: expected it to start with "${API_KEY_PREFIX}". If you are passing a user JWT, use the \`accessToken\` option instead of \`apiKey\`.`
+    );
+  }
+}
+
+// src/core/errors.ts
+var LunnoaApiError = class extends Error {
+  /** HTTP status code of the failed response. */
+  status;
+  /** Parsed JSON error body when the server returned one, otherwise the raw text. */
+  body;
+  /** HTTP method of the failed request. */
+  method;
+  /** Path of the failed request (without the base URL). */
+  path;
+  constructor(args) {
+    const detail = extractMessage(args.body);
+    super(
+      `Lunnoa API request failed: ${args.method} ${args.path} \u2192 ${args.status}${detail ? ` (${detail})` : ""}`
+    );
+    this.name = "LunnoaApiError";
+    this.status = args.status;
+    this.body = args.body;
+    this.method = args.method;
+    this.path = args.path;
+  }
+  /** True for 401 responses (missing, revoked, or expired credential). */
+  get isUnauthorized() {
+    return this.status === 401;
+  }
+  /** True for 403 responses (missing permission or feature not licensed). */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** True for 404 responses. */
+  get isNotFound() {
+    return this.status === 404;
+  }
+  /** True for 429 responses (rate limited). */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+function extractMessage(body) {
+  if (body && typeof body === "object") {
+    const record = body;
+    const candidate = record.message ?? record.error;
+    if (typeof candidate === "string") {
+      return candidate;
+    }
+    if (Array.isArray(candidate)) {
+      return candidate.filter((m) => typeof m === "string").join("; ");
+    }
+  }
+  if (typeof body === "string" && body.length > 0 && body.length < 300) {
+    return body;
+  }
+  return void 0;
+}
+
+// src/core/http.ts
+var HttpClient = class {
+  baseUrl;
+  tokenStore;
+  /** Underlying fetch (shared with AI SDK transports when needed). */
+  fetch;
+  apiKey;
+  accessToken;
+  autoRefresh;
+  defaultHeaders;
+  refreshInFlight = null;
+  constructor(options) {
+    if (!options.baseUrl) {
+      throw new Error("LunnoaClient requires a baseUrl.");
+    }
+    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)."
+      );
+    }
+    if (options.apiKey) {
+      assertApiKeyAllowedInEnvironment(options.apiKey);
+    }
+    if (typeof options.accessToken === "string" && options.accessToken.startsWith(API_KEY_PREFIX)) {
+      throw new Error(
+        "The accessToken option received an lna_ API key. API keys must be passed as `apiKey` (and never in a browser); accessToken is for user JWTs only."
+      );
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.accessToken = options.accessToken;
+    this.tokenStore = options.tokenStore;
+    this.autoRefresh = options.autoRefresh ?? Boolean(options.tokenStore && !options.apiKey);
+    this.fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.defaultHeaders = options.headers ?? {};
+  }
+  async resolveAuthHeader() {
+    if (this.apiKey) {
+      return `Bearer ${this.apiKey}`;
+    }
+    if (this.tokenStore) {
+      const fromStore = await this.tokenStore.getAccessToken();
+      if (!fromStore) {
+        throw new Error(
+          "No access token in the token store. Call lunnoa.auth.login(...) first, or seed the store with setTokens / createMemoryTokenStore({ accessToken })."
+        );
+      }
+      return `Bearer ${fromStore}`;
+    }
+    const token = typeof this.accessToken === "function" ? await this.accessToken() : this.accessToken;
+    if (!token) {
+      throw new Error("accessToken resolved to an empty value.");
+    }
+    return `Bearer ${token}`;
+  }
+  buildUrl(path, query) {
+    const url = new URL(this.baseUrl + path);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const headers = {
+      ...this.defaultHeaders,
+      ...options.headers
+    };
+    if (!options.skipAuth) {
+      headers.Authorization = await this.resolveAuthHeader();
+    }
+    const init = { method, headers, signal: options.signal };
+    if (options.body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(options.body);
+    }
+    const response = await this.fetch(url, init);
+    if (!response.ok && response.status === 401 && !options.skipAuth && !options._retriedAfterRefresh && this.autoRefresh && this.tokenStore && !this.apiKey) {
+      const refreshed = await this.tryRefreshAccessToken();
+      if (refreshed) {
+        return this.request(method, path, {
+          ...options,
+          _retriedAfterRefresh: true
+        });
+      }
+    }
+    if (!response.ok) {
+      const body = await parseBodySafely(response);
+      throw new LunnoaApiError({
+        status: response.status,
+        body,
+        method,
+        path
+      });
+    }
+    if (options.raw) {
+      return response;
+    }
+    if (response.status === 204) {
+      return void 0;
+    }
+    return await parseBodySafely(response);
+  }
+  get(path, options) {
+    return this.request("GET", path, options);
+  }
+  post(path, options) {
+    return this.request("POST", path, options);
+  }
+  patch(path, options) {
+    return this.request("PATCH", path, options);
+  }
+  put(path, options) {
+    return this.request("PUT", path, options);
+  }
+  delete(path, options) {
+    return this.request("DELETE", path, options);
+  }
+  /**
+   * Single-flight refresh using the token store. Returns false when refresh
+   * is impossible or fails (store is cleared on failure).
+   */
+  async tryRefreshAccessToken() {
+    if (!this.tokenStore) {
+      return false;
+    }
+    if (!this.refreshInFlight) {
+      this.refreshInFlight = this.performRefresh().finally(() => {
+        this.refreshInFlight = null;
+      });
+    }
+    return this.refreshInFlight;
+  }
+  async performRefresh() {
+    const refreshToken = await this.tokenStore.getRefreshToken();
+    if (!refreshToken) {
+      return false;
+    }
+    try {
+      const url = this.buildUrl("/api/auth/refresh-token");
+      const response = await this.fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refreshToken })
+      });
+      if (!response.ok) {
+        await this.tokenStore.clear();
+        return false;
+      }
+      const body = await parseBodySafely(response);
+      if (!body?.access_token) {
+        await this.tokenStore.clear();
+        return false;
+      }
+      await this.tokenStore.setTokens({ accessToken: body.access_token });
+      return true;
+    } catch {
+      await this.tokenStore.clear();
+      return false;
+    }
+  }
+};
+async function parseBodySafely(response) {
+  const text = await response.text();
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+// src/streaming/sse.ts
+async function* parseSseStream(stream) {
+  for await (const event of parseSseEvents(stream)) {
+    if (event.data !== null) {
+      yield event.data;
+    }
+  }
+}
+async function* parseSseEvents(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: false });
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      buffer = buffer.replace(/\r\n/g, "\n");
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const rawEvent = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        boundary = buffer.indexOf("\n\n");
+        const parsed = extractEvent(rawEvent);
+        if (parsed.data !== null || parsed.event !== "message") {
+          yield parsed;
+        }
+      }
+    }
+    const remaining = buffer.trim();
+    if (remaining) {
+      const parsed = extractEvent(remaining);
+      if (parsed.data !== null || parsed.event !== "message") {
+        yield parsed;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function extractEvent(rawEvent) {
+  const dataLines = [];
+  let eventName = "message";
+  for (const line of rawEvent.split("\n")) {
+    if (line.startsWith(":")) {
+      continue;
+    }
+    if (line.startsWith("event:")) {
+      let value = line.slice("event:".length);
+      if (value.startsWith(" ")) {
+        value = value.slice(1);
+      }
+      if (value) {
+        eventName = value;
+      }
+      continue;
+    }
+    if (line.startsWith("data:")) {
+      let value = line.slice("data:".length);
+      if (value.startsWith(" ")) {
+        value = value.slice(1);
+      }
+      dataLines.push(value);
+    }
+  }
+  return {
+    event: eventName,
+    data: dataLines.length === 0 ? null : dataLines.join("\n")
+  };
+}
+
+// src/streaming/agent-chat.ts
+var AgentChatStream = class {
+  constructor(response, options) {
+    this.response = response;
+    this.options = options;
+    this.runId = response.headers.get("X-Task-Run-Id");
+  }
+  response;
+  options;
+  /**
+   * Server run id of this turn (`X-Task-Run-Id` response header), when
+   * provided. Useful for diagnostics.
+   */
+  runId;
+  consumed = false;
+  [Symbol.asyncIterator]() {
+    return this.chunks();
+  }
+  async *chunks() {
+    if (this.consumed) {
+      throw new Error("This AgentChatStream has already been consumed.");
+    }
+    this.consumed = true;
+    const body = this.response.body;
+    if (!body) {
+      return;
+    }
+    for await (const data of parseSseStream(body)) {
+      if (this.options?.signal?.aborted) {
+        return;
+      }
+      if (data === "[DONE]") {
+        return;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(data);
+      } catch {
+        continue;
+      }
+      if (parsed && typeof parsed === "object" && "type" in parsed) {
+        yield parsed;
+      }
+    }
+  }
+  /**
+   * The same chunks as a web `ReadableStream`, ready for the AI SDK's
+   * `readUIMessageStream({ stream })` to assemble into `UIMessage` snapshots.
+   */
+  toUIMessageStream() {
+    const iterator = this.chunks();
+    return new ReadableStream({
+      async pull(controller) {
+        const { done, value } = await iterator.next();
+        if (done) {
+          controller.close();
+        } else {
+          controller.enqueue(value);
+        }
+      },
+      async cancel() {
+        await iterator.return();
+      }
+    });
+  }
+  /** Collects the full text of the turn (concatenated `text-delta` chunks). */
+  async text() {
+    let text = "";
+    for await (const chunk of this.chunks()) {
+      if (chunk.type === "text-delta" && typeof chunk.delta === "string") {
+        text += chunk.delta;
+      }
+    }
+    return text;
+  }
+};
+var AgentChatClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Sends a user message to an agent task and streams the assistant turn.
+   * Creates the task row when `taskId` does not exist yet (client-generated
+   * UUIDs are supported, mirroring the bundled UI).
+   *
+   * `message` may be a plain string (wrapped into a UIMessage) or a full AI
+   * SDK `UIMessage`.
+   */
+  async streamMessage(agentId, taskId, message, options = {}) {
+    const uiMessage = typeof message === "string" ? {
+      id: generateMessageId(),
+      role: "user",
+      parts: [{ type: "text", text: message }]
+    } : message;
+    const response = await this.http.request(
+      "POST",
+      `/api/agents/${agentId}/tasks/${taskId}/stream-message`,
+      {
+        raw: true,
+        signal: options.signal,
+        headers: { Accept: "text/event-stream" },
+        body: {
+          messages: [uiMessage],
+          ...options.chatMode ? { chatMode: options.chatMode } : {}
+        }
+      }
+    );
+    return new AgentChatStream(response, { signal: options.signal });
+  }
+  /**
+   * Reattaches to an in-flight agent turn after a disconnect (the resumable
+   * stream replays from the beginning of the turn). Returns `null` when
+   * there is no active stream to resume (server responds 204).
+   */
+  async resumeStream(agentId, taskId, options = {}) {
+    const response = await this.http.request(
+      "GET",
+      `/api/agents/${agentId}/tasks/${taskId}/stream-message`,
+      {
+        raw: true,
+        signal: options.signal,
+        headers: { Accept: "text/event-stream" }
+      }
+    );
+    if (response.status === 204) {
+      return null;
+    }
+    return new AgentChatStream(response, { signal: options.signal });
+  }
+  /**
+   * Requests cancellation of the active agent turn for a task. Idempotent:
+   * succeeds even when no stream is active. Optionally persists the partial
+   * assistant message received so far.
+   */
+  async stop(agentId, taskId, options = {}) {
+    return this.http.post(
+      `/api/agents/${agentId}/tasks/${taskId}/stream-message/stop`,
+      {
+        body: options.assistantMessage ? { assistantMessage: options.assistantMessage } : {}
+      }
+    );
+  }
+};
+function generateMessageId() {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj?.randomUUID) {
+    return cryptoObj.randomUUID();
+  }
+  return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/resources/actions.ts
+var ActionsResource = class {
+  constructor(http, executions) {
+    this.http = http;
+    this.executions = executions;
+  }
+  http;
+  executions;
+  /**
+   * Run a single catalogue action as a one-step ad-hoc Execution (`source: SDK`).
+   *
+   * The platform runs the action synchronously and returns the execution id
+   * plus status/output/executionPath. You can also poll
+   * {@link ExecutionsResource.get} / {@link ExecutionsResource.waitUntilFinished}
+   * with the returned id.
+   *
+   * Discover `appId` / `actionId` / `inputConfig` via `workflowApps.list()`.
+   */
+  run(options) {
+    return this.http.post("/api/actions/run", {
+      body: options
+    });
+  }
+  /**
+   * Convenience: run the action and wait until the Execution reaches a
+   * terminal status (or pauses in `NEEDS_INPUT`). Prefer {@link run} when the
+   * synchronous response is enough.
+   */
+  async runAndWait(options, waitOptions) {
+    const { id } = await this.run(options);
+    return this.executions.waitUntilFinished(id, {
+      ...waitOptions,
+      expansion: [
+        "executionPath",
+        "source",
+        ...waitOptions?.expansion ?? []
+      ]
+    });
+  }
+  /**
+   * Thin discovery helper: find one action definition from `workflowApps.list()`.
+   * Prefer calling `workflowApps.list()` once and caching when looking up many
+   * actions.
+   */
+  async get(appId, actionId) {
+    const apps = await this.http.get("/api/workflow-apps");
+    const app = apps.find((a) => a.id === appId);
+    return app?.actions?.find((action) => action.id === actionId);
+  }
+};
+
+// src/define/index.ts
+var DEFINE_KINDS = {
+  connection: "connection",
+  aiConnection: "aiConnection",
+  action: "action",
+  workflow: "workflow",
+  agent: "agent"
+};
+function defineConnection(config = {}) {
+  return { kind: DEFINE_KINDS.connection, ...config };
+}
+function defineAiConnection(config = {}) {
+  return { kind: DEFINE_KINDS.aiConnection, ...config };
+}
+function defineAction(config) {
+  if (!config.id?.trim()) {
+    throw new Error("defineAction requires id (catalogue action id)");
+  }
+  return { kind: DEFINE_KINDS.action, ...config };
+}
+function defineWorkflow(config) {
+  if (!config.slug?.trim()) {
+    throw new Error("defineWorkflow requires slug");
+  }
+  if (!config.steps?.length) {
+    throw new Error("defineWorkflow requires at least one step");
+  }
+  return { kind: DEFINE_KINDS.workflow, ...config };
+}
+function defineAgent(config) {
+  if (!config.slug?.trim()) {
+    throw new Error("defineAgent requires slug");
+  }
+  if (!config.model?.trim()) {
+    throw new Error("defineAgent requires model");
+  }
+  if (config.instructions == null) {
+    throw new Error("defineAgent requires instructions");
+  }
+  return { kind: DEFINE_KINDS.agent, ...config };
+}
+function resolveActionAppId(action) {
+  if (action.appId?.trim()) {
+    return action.appId.trim();
+  }
+  const id = action.id.trim();
+  const actionMarker = "_action_";
+  const markerIndex = id.indexOf(actionMarker);
+  if (markerIndex > 0) {
+    return id.slice(0, markerIndex);
+  }
+  const dot = id.indexOf(".");
+  if (dot > 0) {
+    return id.slice(0, dot);
+  }
+  throw new Error(
+    `Cannot infer appId for action "${id}". Pass appId explicitly.`
+  );
+}
+function resolveActionId(action) {
+  const id = action.id.trim();
+  const appId = action.appId?.trim();
+  if (appId && id.startsWith(`${appId}.`)) {
+    return id.slice(appId.length + 1);
+  }
+  const marker = "_action_";
+  if (id.includes(marker)) {
+    return id;
+  }
+  const dot = id.indexOf(".");
+  if (dot > 0) {
+    return id.slice(dot + 1);
+  }
+  return id;
+}
+
+// src/resources/common.ts
+function serializeListQuery(options = {}) {
+  return {
+    expansion: serializeCsv(options.expansion),
+    filterBy: serializeFilterBy(options.filterBy),
+    includeType: serializeCsv(options.includeType)
+  };
+}
+function serializeCsv(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return Array.isArray(value) ? value.join(",") : value;
+}
+function serializeFilterBy(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return Object.entries(value).map(([key, filterValue]) => `${key}:${filterValue}`).join(",");
+}
+
+// src/resources/agents.ts
+function unwrapTool(tool) {
+  if ("use" in tool && tool.use) {
+    return tool.use;
+  }
+  return tool;
+}
+function agentDefinitionToUpsert(def, options) {
+  const tools = [];
+  const workflowIds = [...options?.workflowIds ?? []];
+  for (const tool of def.tools ?? []) {
+    const unwrapped = unwrapTool(tool);
+    if (unwrapped.kind === DEFINE_KINDS.workflow) {
+      continue;
+    }
+    if (unwrapped.kind === DEFINE_KINDS.action) {
+      tools.push({
+        appId: resolveActionAppId(unwrapped),
+        actionId: resolveActionId(unwrapped),
+        connectionId: unwrapped.connection?.id,
+        name: unwrapped.name,
+        description: unwrapped.description,
+        input: unwrapped.input
+      });
+    }
+  }
+  return {
+    slug: def.slug,
+    name: def.name,
+    description: def.description,
+    instructions: def.instructions,
+    model: def.model,
+    aiConnectionId: def.aiConnection?.id,
+    connectionIds: def.connections?.map((c) => c.id).filter((id) => Boolean(id)),
+    workflowIds: workflowIds.length ? workflowIds : void 0,
+    tools,
+    managedByCode: true
+  };
+}
+var AgentsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists agents visible to the caller in the current workspace. */
+  list(options) {
+    return this.http.get("/api/agents", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single agent. */
+  get(agentId, options) {
+    return this.http.get(`/api/agents/${agentId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Upsert an agent by project-scoped slug.
+   * Prefer the CLI (`npx @lunnoa/client agents deploy`) for happy-path deploy.
+   */
+  upsertBySlug(projectId, body, options) {
+    const payload = "kind" in body && body.kind === "agent" ? agentDefinitionToUpsert(body, options) : body;
+    return this.http.post(`/api/projects/${projectId}/agents/upsert`, {
+      body: payload
+    });
+  }
+};
+
+// src/auth/types.ts
+function isLoginRequires2FA(result) {
+  return "requires2FA" in result && result.requires2FA === true;
+}
+function mapWireTokens(wire) {
+  return {
+    accessToken: wire.access_token,
+    ...wire.refresh_token !== void 0 ? { refreshToken: wire.refresh_token } : {}
+  };
+}
+function mapLoginWire(wire) {
+  if ("requires2FA" in wire && wire.requires2FA) {
+    return {
+      requires2FA: true,
+      sessionToken: wire.sessionToken
+    };
+  }
+  const tokens = wire;
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token
+  };
+}
+
+// src/resources/auth.ts
+var AuthResource = class {
+  constructor(http, tokenStore) {
+    this.http = http;
+    this.tokenStore = tokenStore;
+    this.sso = new SsoAuthResource(http);
+  }
+  http;
+  tokenStore;
+  sso;
+  /**
+   * `POST /api/auth/login`
+   *
+   * On success without 2FA, tokens are written to the token store (when set).
+   * When 2FA is required, returns `{ requires2FA, sessionToken }` and does not
+   * store tokens until {@link verify2faLogin} succeeds.
+   */
+  async login(input) {
+    const wire = await this.http.post("/api/auth/login", {
+      body: { email: input.email, password: input.password },
+      skipAuth: true
+    });
+    const result = mapLoginWire(wire);
+    if (!isLoginRequires2FA(result)) {
+      await this.persistTokens(result);
+    }
+    return result;
+  }
+  /**
+   * `POST /api/auth/2fa/verify-login`
+   *
+   * Completes password login after TOTP or backup-code verification.
+   */
+  async verify2faLogin(input) {
+    const wire = await this.http.post(
+      "/api/auth/2fa/verify-login",
+      {
+        body: {
+          sessionToken: input.sessionToken,
+          token: input.token
+        },
+        skipAuth: true
+      }
+    );
+    const result = mapLoginWire(wire);
+    if (isLoginRequires2FA(result)) {
+      throw new Error(
+        "Unexpected 2FA challenge after verify2faLogin; expected access and refresh tokens."
+      );
+    }
+    await this.persistTokens(result);
+    return result;
+  }
+  /**
+   * `POST /api/auth/login-with-token`
+   *
+   * Exchanges a short-lived hidden JWT (SSO callback or email verification)
+   * for access and refresh tokens.
+   */
+  async loginWithToken(input) {
+    const wire = await this.http.post("/api/auth/login-with-token", {
+      body: { token: input.token },
+      skipAuth: true
+    });
+    const tokens = {
+      accessToken: wire.access_token,
+      refreshToken: wire.refresh_token
+    };
+    await this.persistTokens(tokens);
+    return tokens;
+  }
+  /**
+   * `POST /api/auth/refresh-token`
+   *
+   * Returns a new access token. The refresh token itself is not rotated.
+   * When a token store is configured and `refreshToken` is omitted, the
+   * stored refresh token is used.
+   */
+  async refresh(input) {
+    const refreshToken = input?.refreshToken ?? await this.tokenStore?.getRefreshToken() ?? null;
+    if (!refreshToken) {
+      throw new Error(
+        "auth.refresh requires a refreshToken argument or a token store that holds one."
+      );
+    }
+    const wire = await this.http.post(
+      "/api/auth/refresh-token",
+      {
+        body: { refreshToken },
+        skipAuth: true
+      }
+    );
+    const mapped = mapWireTokens(wire);
+    if (this.tokenStore) {
+      await this.tokenStore.setTokens({
+        accessToken: mapped.accessToken,
+        // Keep existing refresh token; refresh responses omit it.
+        refreshToken: mapped.refreshToken
+      });
+    }
+    return { accessToken: mapped.accessToken };
+  }
+  /**
+   * `GET /api/users/me` — current user profile for the active JWT.
+   */
+  me() {
+    return this.http.get("/api/users/me");
+  }
+  /**
+   * Clears tokens from the token store.
+   * There is no server-side logout endpoint; access tokens remain valid until expiry
+   * (or until the user's `tokensValidFrom` watermark invalidates them).
+   */
+  async logout() {
+    await this.tokenStore?.clear();
+  }
+  /** True when the token store has an access token (sync stores only wait on Promise). */
+  async hasSession() {
+    const token = await this.tokenStore?.getAccessToken();
+    return Boolean(token);
+  }
+  async persistTokens(tokens) {
+    if (!this.tokenStore) {
+      return;
+    }
+    await this.tokenStore.setTokens({
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken
+    });
+  }
+};
+var SsoAuthResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** `GET /api/auth/sso/providers` (public). */
+  listProviders() {
+    return this.http.get("/api/auth/sso/providers", {
+      skipAuth: true
+    });
+  }
+  /**
+   * Absolute URL for `GET /api/auth/sso/:providerId/login`.
+   * Navigate the browser here to start the OIDC redirect.
+   */
+  getLoginUrl(providerId) {
+    if (!providerId) {
+      throw new Error("sso.getLoginUrl requires a providerId.");
+    }
+    return this.http.buildUrl(
+      `/api/auth/sso/${encodeURIComponent(providerId)}/login`
+    );
+  }
+};
+
+// src/resources/connections.ts
+var ConnectionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists connections in the workspace. */
+  list(options) {
+    return this.http.get("/api/connections", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single connection (secrets are never included). */
+  get(connectionId, options) {
+    return this.http.get(`/api/connections/${connectionId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+};
+
+// src/resources/discovery.ts
+var DiscoveryResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Returns the deployment's feature flags (storage, vector database, email,
+   * SSO, edition gating), letting a custom UI adapt to what is enabled.
+   */
+  enabledFeatures() {
+    return this.http.get("/api/discovery/enabled-features");
+  }
+};
+
+// src/core/pagination.ts
+async function* iteratePages(fetchPage) {
+  let page = 1;
+  while (true) {
+    const { data, pagination } = await fetchPage(page);
+    for (const item of data) {
+      yield item;
+    }
+    if (page >= pagination.totalPages || data.length === 0) {
+      return;
+    }
+    page += 1;
+  }
+}
+async function* iterateOffset(fetchBatch) {
+  let offset = 0;
+  while (true) {
+    const { items, pagination } = await fetchBatch(offset);
+    for (const item of items) {
+      yield item;
+    }
+    offset += items.length;
+    const exhausted = items.length === 0 || (pagination.hasMore !== void 0 ? !pagination.hasMore : offset >= pagination.total);
+    if (exhausted) {
+      return;
+    }
+  }
+}
+
+// src/resources/entities.ts
+var EntitiesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Returns one page of entities matching the filter. */
+  list(options = {}) {
+    return this.http.get("/api/objects", {
+      query: this.serializeListOptions(options)
+    });
+  }
+  /**
+   * Async-iterates every entity matching the filter, fetching pages lazily.
+   *
+   * ```ts
+   * for await (const invoice of client.entities.iterate({ objectTypeSlug: 'invoice' })) { ... }
+   * ```
+   */
+  iterate(options = {}) {
+    return iteratePages(async (page) => {
+      const result = await this.list({ ...options, page });
+      return { data: result.data ?? [], pagination: result.pagination };
+    });
+  }
+  /** Returns a single entity. Request `expansion: ['attributes']` for field values. */
+  get(entityId, options = {}) {
+    return this.http.get(`/api/objects/${entityId}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Creates an entity. `attributes` are keyed by field ID. */
+  create(data, options = {}) {
+    return this.http.post("/api/objects", {
+      body: data,
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Partially updates an entity; supplied attributes are merged. */
+  update(entityId, data, options = {}) {
+    return this.http.patch(`/api/objects/${entityId}`, {
+      body: data,
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Soft-deletes an entity. */
+  delete(entityId) {
+    return this.http.delete(`/api/objects/${entityId}`);
+  }
+  /** Moves an entity to a new state (validated against the type's state machine). */
+  changeState(entityId, data) {
+    return this.http.post(
+      `/api/objects/${entityId}/state`,
+      { body: data }
+    );
+  }
+  /** Returns the entity's state changes, newest first. */
+  getStateHistory(entityId, options = {}) {
+    return this.http.get(
+      `/api/objects/${entityId}/state/history`,
+      { query: { limit: options.limit } }
+    );
+  }
+  /** Returns the current state and the transitions allowed from it. */
+  getStateTransitions(entityId) {
+    return this.http.get(
+      `/api/objects/${entityId}/state/transitions`
+    );
+  }
+  /** Imports pre-parsed rows into an entity type (SuperAdmin only). */
+  import(data) {
+    return this.http.post("/api/objects/import", {
+      body: data
+    });
+  }
+  /** Exports entities of a type as flat JSON rows. */
+  export(data) {
+    return this.http.post(
+      "/api/objects/export",
+      { body: data }
+    );
+  }
+  /** Returns the column headers and a sample row for importing (SuperAdmin only). */
+  getImportTemplate(entityTypeId) {
+    return this.http.get(
+      `/api/objects/import/template/${entityTypeId}`
+    );
+  }
+  serializeListOptions(options) {
+    return {
+      objectTypeId: options.objectTypeId,
+      objectTypeSlug: options.objectTypeSlug,
+      state: options.state,
+      states: options.states?.join(","),
+      ownerId: options.ownerId,
+      search: options.search,
+      sortBy: options.sortBy,
+      sortOrder: options.sortOrder,
+      page: options.page,
+      pageSize: options.pageSize,
+      expansion: serializeCsv(options.expansion)
+    };
+  }
+};
+
+// src/resources/entity-types.ts
+var EntityTypesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * Lists entity types in the workspace. Request
+   * `expansion: ['attributeSchema', 'stateSchema']` for the field and state
+   * machine definitions the codegen CLI builds types from.
+   */
+  list(options = {}) {
+    return this.http.get("/api/object-types", {
+      query: {
+        includeDisabled: options.includeDisabled,
+        expansion: serializeCsv(options.expansion)
+      }
+    });
+  }
+  /** Returns a single entity type by ID. */
+  get(id, options = {}) {
+    return this.http.get(`/api/object-types/${id}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Returns a single entity type by its URL-safe slug. */
+  getBySlug(slug, options = {}) {
+    return this.http.get(`/api/object-types/slug/${slug}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+};
+
+// src/resources/approvals.ts
+var ApprovalsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /**
+   * @param options.status `pending` (default) for actionable items, or `done` for history.
+   */
+  async inbox(options) {
+    return this.http.get("/api/approvals/inbox", {
+      query: { status: options?.status ?? "pending" }
+    });
+  }
+  async decide(approvalId, body) {
+    return this.http.post(`/api/approvals/${approvalId}/decide`, { body });
+  }
+};
+
+// src/streaming/execution-progress.ts
+var ExecutionProgressStream = class {
+  constructor(response, options) {
+    this.response = response;
+    this.options = options;
+  }
+  response;
+  options;
+  consumed = false;
+  [Symbol.asyncIterator]() {
+    return this.events();
+  }
+  async *events() {
+    if (this.consumed) {
+      throw new Error("This ExecutionProgressStream has already been consumed.");
+    }
+    this.consumed = true;
+    const body = this.response.body;
+    if (!body) {
+      return;
+    }
+    for await (const frame of parseSseEvents(body)) {
+      if (this.options?.signal?.aborted) {
+        return;
+      }
+      if (frame.data === null) {
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(frame.data);
+      } catch {
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object") {
+        continue;
+      }
+      yield {
+        event: frame.event,
+        data: parsed
+      };
+      if (frame.event === "execution.finished" || frame.event === "execution.error") {
+        return;
+      }
+    }
+  }
+};
+async function openExecutionStream(http, executionId, options) {
+  const response = await http.request("GET", `/api/executions/${executionId}/stream`, {
+    raw: true,
+    signal: options?.signal
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => void 0);
+    let parsed = body;
+    try {
+      parsed = body ? JSON.parse(body) : void 0;
+    } catch {
+    }
+    throw new LunnoaApiError({
+      status: response.status,
+      body: parsed,
+      method: "GET",
+      path: `/api/executions/${executionId}/stream`
+    });
+  }
+  return new ExecutionProgressStream(response, options);
+}
+
+// src/resources/executions.ts
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "SUCCESS",
+  "FAILED",
+  "CANCELLED"
+]);
+var ExecutionTimeoutError = class extends Error {
+  constructor(executionId, timeoutMs) {
+    super(
+      `Execution ${executionId} did not finish within ${timeoutMs}ms. It is still running server-side; keep polling executions.get() or increase timeoutMs.`
+    );
+    this.executionId = executionId;
+    this.timeoutMs = timeoutMs;
+    this.name = "ExecutionTimeoutError";
+  }
+  executionId;
+  timeoutMs;
+};
+var ExecutionsResource = class {
+  constructor(http, workflowApps) {
+    this.http = http;
+    this.workflowApps = workflowApps;
+  }
+  http;
+  workflowApps;
+  catalogCache = null;
+  /**
+   * Starts a new execution of a workflow. Only the execution ID is returned;
+   * use {@link waitUntilFinished} or `get` to track progress.
+   */
+  execute(workflowId, inputData) {
+    return this.http.post(
+      `/api/executions/workflows/${workflowId}/execute`,
+      { body: { inputData: inputData ?? {} } }
+    );
+  }
+  /** Lists executions in the current workspace, most recently started first. */
+  list(options) {
+    return this.http.get("/api/executions", {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Returns a single execution. Request `expansion: ['status', 'executionPath']`
+   * for the business-readable step list custom UIs render progress from.
+   */
+  get(executionId, options) {
+    return this.http.get(`/api/executions/${executionId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Timeline-ready progress: `executionPath` plus catalogue icons/logos.
+   * Use this for a custom status bar / step list (not raw nodes/edges).
+   */
+  async getProgress(executionId) {
+    const execution = await this.get(executionId, {
+      expansion: [
+        "status",
+        "statusMessage",
+        "executionPath",
+        "pendingInput",
+        "source",
+        "name",
+        "startedAt",
+        "stoppedAt",
+        "output"
+      ]
+    });
+    return this.#toProgress(execution);
+  }
+  /**
+   * Opens the Public API SSE stream (`GET /executions/:id/stream`).
+   * Yields `execution.progress`, `loop.progress`, `execution.finished`, etc.
+   * For a simple timeline, prefer {@link watchProgress}.
+   */
+  stream(executionId, options) {
+    return openExecutionStream(this.http, executionId, options);
+  }
+  /**
+   * Live progress snapshots for a custom timeline UI.
+   * Subscribes to SSE `execution.progress` events (and enriches steps with icons).
+   * Completes when the execution reaches a terminal status or the signal aborts.
+   */
+  async *watchProgress(executionId, options) {
+    const stream = await this.stream(executionId, options);
+    for await (const frame of stream) {
+      if (frame.event === "execution.progress") {
+        const payload = frame.data;
+        yield await this.#progressFromPayload(payload);
+      } else if (frame.event === "execution.finished") {
+        yield await this.getProgress(executionId);
+        return;
+      } else if (frame.event === "execution.error") {
+        throw new Error(
+          typeof frame.data.message === "string" ? frame.data.message : `Execution stream error for ${executionId}`
+        );
+      }
+    }
+  }
+  /**
+   * Polls an execution with exponential backoff until it reaches a terminal
+   * status (`SUCCESS`, `FAILED`, `CANCELLED`) — or pauses in `NEEDS_INPUT`
+   * (unless `stopOnNeedsInput: false`). Resolves with the final execution
+   * including `status`, `statusMessage`, and `output`.
+   */
+  async waitUntilFinished(executionId, options = {}) {
+    const {
+      timeoutMs = 10 * 60 * 1e3,
+      initialDelayMs = 500,
+      maxDelayMs = 5e3,
+      backoffFactor = 1.5,
+      stopOnNeedsInput = true,
+      expansion = [],
+      signal,
+      sleep = defaultSleep
+    } = options;
+    const pollExpansion = Array.from(
+      /* @__PURE__ */ new Set(["status", "statusMessage", "output", ...expansion])
+    );
+    const startedAt = Date.now();
+    let waitedMs = 0;
+    let delay = initialDelayMs;
+    while (true) {
+      signal?.throwIfAborted();
+      const execution = await this.get(executionId, {
+        expansion: pollExpansion
+      });
+      const status = execution.status;
+      if (status && TERMINAL_STATUSES.has(status)) {
+        return execution;
+      }
+      if (stopOnNeedsInput && status === "NEEDS_INPUT") {
+        return execution;
+      }
+      const elapsed = Math.max(Date.now() - startedAt, waitedMs);
+      if (elapsed + delay > timeoutMs) {
+        throw new ExecutionTimeoutError(executionId, timeoutMs);
+      }
+      await sleep(delay);
+      waitedMs += delay;
+      delay = Math.min(delay * backoffFactor, maxDelayMs);
+    }
+  }
+  /**
+   * Resumes an execution paused in `NEEDS_INPUT` by submitting values for the
+   * waiting node. Identify the waiting node and its field schema via
+   * `expansion: ['pendingInput', 'executionPath']` (prefer `pendingInput` for
+   * the form contract; `executionPath` steps with status `NEEDS_INPUT` also
+   * carry the `nodeId`). Required fields from the schema must be present.
+   * The server acknowledges immediately and resumes asynchronously — follow
+   * up with {@link waitUntilFinished}.
+   */
+  async submitInput(executionId, nodeId, values) {
+    await this.http.post(
+      `/api/webhooks/executions/${executionId}/nodes/${nodeId}/input`,
+      { body: values }
+    );
+  }
+  /**
+   * Submit an approve/reject decision for a Request Approval node.
+   * Uses the authenticated Approvals API (not the public input webhook).
+   * Partial approvals keep the execution paused; terminal decisions resume it.
+   */
+  async submitApproval(executionId, nodeId, body) {
+    return this.http.post(
+      `/api/executions/${executionId}/nodes/${nodeId}/approvals`,
+      { body }
+    );
+  }
+  async #toProgress(execution) {
+    const path = execution.executionPath ?? [];
+    const steps = await this.#enrichSteps(path);
+    return {
+      executionId: execution.id,
+      status: execution.status,
+      statusMessage: execution.statusMessage ?? null,
+      name: execution.name ?? null,
+      source: execution.source ?? null,
+      startedAt: execution.startedAt,
+      stoppedAt: execution.stoppedAt ?? null,
+      steps,
+      pendingInput: execution.pendingInput,
+      output: execution.output,
+      activeStepIndex: findActiveStepIndex(steps)
+    };
+  }
+  async #progressFromPayload(payload) {
+    const steps = await this.#enrichSteps(payload.executionPath ?? []);
+    return {
+      executionId: payload.executionId,
+      status: payload.status ?? void 0,
+      statusMessage: payload.statusMessage,
+      name: payload.name,
+      source: payload.source,
+      startedAt: payload.startedAt,
+      stoppedAt: payload.stoppedAt,
+      steps,
+      pendingInput: payload.pendingInput,
+      output: payload.output,
+      activeStepIndex: findActiveStepIndex(steps)
+    };
+  }
+  async #enrichSteps(path) {
+    const catalog = await this.#loadCatalog();
+    return path.map((step) => {
+      const app = catalog?.find((a) => a.id === step.appId);
+      const action = step.actionId && Array.isArray(app?.actions) ? app.actions.find(
+        (a) => a && typeof a === "object" && a.id === step.actionId
+      ) : void 0;
+      const trigger = step.triggerId && Array.isArray(app?.triggers) ? app.triggers.find(
+        (t) => t && typeof t === "object" && t.id === step.triggerId
+      ) : void 0;
+      const iconUrl = typeof action?.iconUrl === "string" && action.iconUrl || typeof trigger?.iconUrl === "string" && trigger.iconUrl || null;
+      const durationMs = computeDurationMs(step.startTime, step.endTime);
+      return {
+        ...step,
+        appLogoUrl: app?.logoUrl ?? null,
+        iconUrl,
+        durationMs
+      };
+    });
+  }
+  async #loadCatalog() {
+    if (!this.workflowApps) {
+      return null;
+    }
+    if (!this.catalogCache) {
+      try {
+        this.catalogCache = await this.workflowApps.list();
+      } catch {
+        return null;
+      }
+    }
+    return this.catalogCache;
+  }
+};
+function findActiveStepIndex(steps) {
+  const idx = steps.findIndex(
+    (s) => s.status === "RUNNING" || s.status === "NEEDS_INPUT" || s.status === "RETRYING" || s.status === "WAITING" || s.status === "SCHEDULED"
+  );
+  return idx;
+}
+function computeDurationMs(start, end) {
+  if (!start || !end) return null;
+  const a = Date.parse(start);
+  const b = Date.parse(end);
+  if (Number.isNaN(a) || Number.isNaN(b) || b < a) return null;
+  return b - a;
+}
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/resources/knowledge.ts
+var KnowledgeResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists knowledge notebooks in the workspace. */
+  list(options = {}) {
+    return this.http.get("/api/knowledge", {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Returns a single knowledge notebook. */
+  get(knowledgeId, options = {}) {
+    return this.http.get(`/api/knowledge/${knowledgeId}`, {
+      query: { expansion: serializeCsv(options.expansion) }
+    });
+  }
+  /** Creates a knowledge notebook. Subject to the deployment's storage/vector infrastructure. */
+  create(data) {
+    return this.http.post("/api/knowledge", { body: data });
+  }
+  /** Updates a knowledge notebook. */
+  update(knowledgeId, data) {
+    return this.http.patch(`/api/knowledge/${knowledgeId}`, {
+      body: data
+    });
+  }
+  /** Deletes a knowledge notebook. */
+  delete(knowledgeId) {
+    return this.http.delete(`/api/knowledge/${knowledgeId}`);
+  }
+  /** Saves raw text into the notebook (chunked, embedded, and indexed server-side). */
+  saveUploadedText(knowledgeId, data) {
+    return this.http.post(
+      `/api/knowledge/${knowledgeId}/saveUploadedText`,
+      { body: data }
+    );
+  }
+  /** Lists the documents stored in a notebook. */
+  listDocuments(knowledgeId) {
+    return this.http.get(
+      `/api/knowledge/${knowledgeId}/documents`
+    );
+  }
+  /** Returns one document group (an uploaded document and its chunks). */
+  getDocumentGroup(knowledgeId, groupId) {
+    return this.http.get(
+      `/api/knowledge/${knowledgeId}/documents/${groupId}`
+    );
+  }
+  /** Deletes one document group from the notebook. */
+  deleteDocumentGroup(knowledgeId, groupId) {
+    return this.http.delete(
+      `/api/knowledge/${knowledgeId}/documents/${groupId}`
+    );
+  }
+};
+
+// src/resources/projects.ts
+var ProjectsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists projects in the workspace, most recently updated first. */
+  list(options) {
+    return this.http.get("/api/projects", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single project. */
+  get(projectId, options) {
+    return this.http.get(`/api/projects/${projectId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a project. */
+  create(data) {
+    return this.http.post("/api/projects", { body: data });
+  }
+};
+
+// src/resources/queue-items.ts
+var QueueItemsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Returns one page of items in a queue (offset-based pagination). */
+  list(queueId, options = {}) {
+    return this.http.get(`/api/queues/${queueId}/items`, {
+      query: {
+        limit: options.limit,
+        offset: options.offset,
+        expansion: serializeCsv(options.expansion),
+        filterBy: serializeFilterBy(options.filterBy)
+      }
+    });
+  }
+  /** Async-iterates every item in a queue, fetching batches lazily. */
+  iterate(queueId, options = {}) {
+    return iterateOffset(async (offset) => {
+      const result = await this.list(queueId, { ...options, offset });
+      return {
+        items: result.items ?? [],
+        pagination: result.pagination
+      };
+    });
+  }
+  /** Returns a single queue item. */
+  get(queueId, itemId) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/${itemId}`
+    );
+  }
+  /** Adds an item to a queue. */
+  create(queueId, data) {
+    return this.http.post(`/api/queues/${queueId}/items`, {
+      body: data
+    });
+  }
+  /** Adds many items to a queue in one call. */
+  bulkCreate(queueId, data) {
+    return this.http.post(
+      `/api/queues/${queueId}/items/bulk`,
+      { body: data }
+    );
+  }
+  /** Updates a queue item. */
+  update(queueId, itemId, data) {
+    return this.http.patch(
+      `/api/queues/${queueId}/items/${itemId}`,
+      { body: data }
+    );
+  }
+  /** Deletes a queue item. */
+  delete(queueId, itemId) {
+    return this.http.delete(
+      `/api/queues/${queueId}/items/${itemId}`
+    );
+  }
+  /** Returns items that are ready to be processed. */
+  listReady(queueId, options = {}) {
+    return this.http.get(`/api/queues/${queueId}/items/ready`, {
+      query: { limit: options.limit }
+    });
+  }
+  /** Returns items eligible for retry. */
+  listRetryable(queueId) {
+    return this.http.get(`/api/queues/${queueId}/items/retry`);
+  }
+  /** Returns items with the given status. */
+  listByStatus(queueId, status) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/status/${status}`
+    );
+  }
+  /** Looks an item up by the external ID your system supplied. */
+  getByExternalId(queueId, externalId) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/external/${externalId}`
+    );
+  }
+  /** Searches items in the queue. */
+  search(queueId, query) {
+    return this.http.get(`/api/queues/${queueId}/items/search`, {
+      query: { q: query }
+    });
+  }
+  /** Returns per-status and per-priority counts for the queue. */
+  stats(queueId) {
+    return this.http.get(`/api/queues/${queueId}/items/stats`);
+  }
+  /** Returns the recorded processing errors of an item. */
+  listErrors(queueId, itemId) {
+    return this.http.get(
+      `/api/queues/${queueId}/items/${itemId}/errors`
+    );
+  }
+  /** Updates the processing status of an item. */
+  updateStatus(queueId, itemId, status) {
+    return this.http.patch(
+      `/api/queues/${queueId}/items/${itemId}/status`,
+      { body: { status } }
+    );
+  }
+  /** Links an item to the workflow execution that processed it. */
+  linkExecution(queueId, itemId, executionId) {
+    return this.http.patch(
+      `/api/queues/${queueId}/items/${itemId}/link-execution`,
+      { body: { executionId } }
+    );
+  }
+  /** Queues the item for another processing attempt. */
+  retry(queueId, itemId) {
+    return this.http.post(
+      `/api/queues/${queueId}/items/${itemId}/retry`
+    );
+  }
+  /** Records a processing error on the item. */
+  addError(queueId, itemId, error) {
+    return this.http.post(
+      `/api/queues/${queueId}/items/${itemId}/error`,
+      { body: error }
+    );
+  }
+};
+
+// src/resources/queues.ts
+var QueuesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists queues in the workspace, ordered by priority then creation date. */
+  list(options) {
+    return this.http.get("/api/queues", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single queue. */
+  get(queueId, options) {
+    return this.http.get(`/api/queues/${queueId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a queue. */
+  create(data) {
+    return this.http.post("/api/queues", { body: data });
+  }
+  /** Updates a queue. */
+  update(queueId, data) {
+    return this.http.patch(`/api/queues/${queueId}`, { body: data });
+  }
+  /** Deletes a queue. */
+  delete(queueId) {
+    return this.http.delete(`/api/queues/${queueId}`);
+  }
+  /** Returns aggregate statistics for a queue. */
+  stats(queueId) {
+    return this.http.get(`/api/queues/${queueId}/stats`);
+  }
+  /** Activates a queue. */
+  activate(queueId) {
+    return this.http.patch(`/api/queues/${queueId}/activate`);
+  }
+  /** Deactivates a queue. */
+  deactivate(queueId) {
+    return this.http.patch(`/api/queues/${queueId}/deactivate`);
+  }
+};
+
+// src/resources/runs.ts
+function isWorkflowDefinition(value) {
+  return typeof value === "object" && value !== null && value.kind === "workflow";
+}
+function isActionDefinition(value) {
+  return typeof value === "object" && value !== null && value.kind === "action";
+}
+function stepFromDefinition(step) {
+  if ("appId" in step && "actionId" in step && !("use" in step) && !("kind" in step)) {
+    return step;
+  }
+  if (isActionDefinition(step)) {
+    return {
+      appId: resolveActionAppId(step),
+      actionId: resolveActionId(step),
+      ...step.connection?.id ? { connectionId: step.connection.id } : {},
+      ...step.input ? { input: step.input } : {},
+      ...step.name ? { name: step.name } : {}
+    };
+  }
+  const use = step.use;
+  const input = {
+    ...use.input ?? {},
+    ...step.input ?? {}
+  };
+  return {
+    appId: resolveActionAppId(use),
+    actionId: resolveActionId(use),
+    ...use.connection?.id ? { connectionId: use.connection.id } : {},
+    ...Object.keys(input).length ? { input } : {},
+    ...step.name ?? use.name ? { name: step.name ?? use.name } : {}
+  };
+}
+function normalizeStartRunInput(input) {
+  if (isWorkflowDefinition(input)) {
+    return {
+      steps: input.steps.map(stepFromDefinition),
+      name: input.name ?? input.slug
+    };
+  }
+  if (Array.isArray(input)) {
+    return { steps: input.map((s) => stepFromDefinition(s)) };
+  }
+  return input;
+}
+var RunsResource = class {
+  constructor(http, executions) {
+    this.http = http;
+    this.executions = executions;
+  }
+  http;
+  executions;
+  /**
+   * Start a linear multi-step ad-hoc Execution.
+   *
+   * Accepts a `defineWorkflow` result, a step array, or an explicit
+   * `{ steps, projectId?, name? }` payload.
+   */
+  start(input) {
+    const options = normalizeStartRunInput(input);
+    if (!options.steps?.length) {
+      throw new Error("runs.start requires at least one step");
+    }
+    return this.http.post("/api/runs", {
+      body: options
+    });
+  }
+  /** Convenience: start and wait until terminal / NEEDS_INPUT. */
+  async startAndWait(input, waitOptions) {
+    const { id } = await this.start(input);
+    return this.executions.waitUntilFinished(id, {
+      ...waitOptions,
+      expansion: [
+        "executionPath",
+        "source",
+        ...waitOptions?.expansion ?? []
+      ]
+    });
+  }
+};
+
+// src/resources/tasks.ts
+var TasksResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists tasks (conversation threads) visible to the caller, most recently updated first. */
+  list(options) {
+    return this.http.get("/api/tasks", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single task. Request `expansion: ['messages']` for the conversation history. */
+  get(taskId, options) {
+    return this.http.get(`/api/tasks/${taskId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a task (conversation thread) for an agent. */
+  create(agentId, data, options) {
+    return this.http.post(`/api/agents/${agentId}/tasks`, {
+      body: data,
+      query: serializeListQuery(options)
+    });
+  }
+  /** Updates the task name or description. */
+  update(taskId, data, options) {
+    return this.http.patch(`/api/tasks/${taskId}`, {
+      body: data,
+      query: serializeListQuery(options)
+    });
+  }
+  /** Permanently deletes a task and its messages. */
+  delete(taskId) {
+    return this.http.delete(`/api/tasks/${taskId}`);
+  }
+  /**
+   * Sends a message to an agent task and waits for the full agent turn to
+   * finish (non-streaming). Returns either a plain string or the assistant
+   * messages in AI SDK UIMessage format. For token-by-token output use
+   * `client.agentChat.streamMessage` instead.
+   */
+  message(agentId, taskId, message, options = {}) {
+    const uiMessage = typeof message === "string" ? {
+      id: generateMessageId2(),
+      role: "user",
+      parts: [{ type: "text", text: message }]
+    } : message;
+    return this.http.post(
+      `/api/agents/${agentId}/tasks/${taskId}/message`,
+      {
+        body: {
+          messages: [uiMessage],
+          ...options.chatMode ? { chatMode: options.chatMode } : {}
+        }
+      }
+    );
+  }
+};
+function generateMessageId2() {
+  const cryptoObj = globalThis.crypto;
+  if (cryptoObj?.randomUUID) {
+    return cryptoObj.randomUUID();
+  }
+  return `msg_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/resources/variables.ts
+var VariablesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists variables in the workspace. */
+  list(options) {
+    return this.http.get("/api/variables", {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Returns a single variable. */
+  get(variableId, options) {
+    return this.http.get(`/api/variables/${variableId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /** Creates a variable. */
+  create(data) {
+    return this.http.post("/api/variables", { body: data });
+  }
+  /** Updates a variable. */
+  update(variableId, data) {
+    return this.http.patch(`/api/variables/${variableId}`, {
+      body: data
+    });
+  }
+  /** Deletes a variable. */
+  delete(variableId) {
+    return this.http.delete(`/api/variables/${variableId}`);
+  }
+};
+
+// src/resources/workflow-apps.ts
+var WorkflowAppsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Lists all workflow apps installed on the deployment. */
+  list() {
+    return this.http.get("/api/workflow-apps");
+  }
+  /**
+   * Creates a connection for an app where the connection type is
+   * non-interactive (API key, basic auth). OAuth connections require the
+   * browser flow inside the bundled UI and cannot be created here.
+   */
+  connect(appId, connectionId, value) {
+    return this.http.post(
+      `/api/workflow-apps/${appId}/connections/${connectionId}/connect`,
+      { body: value }
+    );
+  }
+};
+
+// src/resources/workflows.ts
+function stepToUpsertInput(step) {
+  const use = step.use;
+  return {
+    appId: resolveActionAppId(use),
+    actionId: resolveActionId(use),
+    connectionId: use.connection?.id,
+    input: {
+      ...use.input ?? {},
+      ...step.input ?? {}
+    },
+    name: step.name ?? use.name,
+    description: use.description
+  };
+}
+function workflowDefinitionToUpsert(def) {
+  return {
+    slug: def.slug,
+    name: def.name,
+    description: def.description,
+    isActive: def.isActive,
+    managedByCode: true,
+    steps: def.steps.map(stepToUpsertInput)
+  };
+}
+var WorkflowsResource = class {
+  constructor(http, executions) {
+    this.http = http;
+    this.executions = executions;
+  }
+  http;
+  executions;
+  /** Lists workflows in the current workspace. */
+  list(options) {
+    return this.http.get("/api/workflows", {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Returns a single workflow. Request `expansion: ['triggerNode']` to read
+   * the manual trigger's custom input field definitions.
+   */
+  get(workflowId, options) {
+    return this.http.get(`/api/workflows/${workflowId}`, {
+      query: serializeListQuery(options)
+    });
+  }
+  /**
+   * Upsert a workflow by project-scoped slug from a linear step list.
+   * Prefer the CLI (`npx @lunnoa/client workflows deploy`) for happy-path deploy.
+   */
+  upsertBySlug(projectId, body) {
+    const payload = "kind" in body && body.kind === "workflow" ? workflowDefinitionToUpsert(body) : body;
+    return this.http.post(
+      `/api/projects/${projectId}/workflows/upsert`,
+      { body: payload }
+    );
+  }
+  /**
+   * Starts a new execution of the workflow with the given trigger inputs.
+   * Returns immediately with the execution ID.
+   */
+  execute(workflowId, inputs) {
+    return this.executions.execute(workflowId, inputs);
+  }
+  /**
+   * Convenience: execute the workflow and wait (poll with backoff) until it
+   * reaches a terminal status or pauses in `NEEDS_INPUT`.
+   */
+  async executeAndWait(workflowId, inputs, waitOptions) {
+    const { id } = await this.executions.execute(workflowId, inputs);
+    return this.executions.waitUntilFinished(id, waitOptions);
+  }
+  /**
+   * Triggers a workflow through its unauthenticated custom webhook endpoint
+   * (`POST /api/webhooks/workflows/:workflowId`). Only works for workflows
+   * with a webhook trigger. Returns the synchronous trigger output when the
+   * workflow responds synchronously.
+   */
+  triggerWebhook(workflowId, payload) {
+    return this.http.post(
+      `/api/webhooks/workflows/${workflowId}`,
+      { body: payload ?? {} }
+    );
+  }
+};
+
+// src/client.ts
+var LunnoaClient = class {
+  /** The underlying HTTP layer, exposed for advanced/escape-hatch requests. */
+  http;
+  /** Login, refresh, SSO discovery, and session helpers (Pattern B). */
+  auth;
+  agents;
+  tasks;
+  /** Hand-written SSE streaming client for agent chat (AI SDK UIMessage chunks). */
+  agentChat;
+  workflows;
+  executions;
+  /** Run catalogue actions as one-step ad-hoc Executions (`source: SDK`). */
+  actions;
+  /**
+   * Multi-step ad-hoc Executions (`source: SDK`) via `POST /api/runs`.
+   * Prefer `defineWorkflow` + `runs.start` for local linear chains.
+   */
+  runs;
+  /** Authenticated Approvals inbox (workspace API). */
+  approvals;
+  entities;
+  entityTypes;
+  knowledge;
+  queues;
+  queueItems;
+  variables;
+  connections;
+  projects;
+  workflowApps;
+  discovery;
+  constructor(options) {
+    this.http = new HttpClient(options);
+    this.auth = new AuthResource(this.http, this.http.tokenStore);
+    this.agents = new AgentsResource(this.http);
+    this.tasks = new TasksResource(this.http);
+    this.agentChat = new AgentChatClient(this.http);
+    this.workflowApps = new WorkflowAppsResource(this.http);
+    this.executions = new ExecutionsResource(this.http, this.workflowApps);
+    this.actions = new ActionsResource(this.http, this.executions);
+    this.runs = new RunsResource(this.http, this.executions);
+    this.approvals = new ApprovalsResource(this.http);
+    this.workflows = new WorkflowsResource(this.http, this.executions);
+    this.entities = new EntitiesResource(this.http);
+    this.entityTypes = new EntityTypesResource(this.http);
+    this.knowledge = new KnowledgeResource(this.http);
+    this.queues = new QueuesResource(this.http);
+    this.queueItems = new QueueItemsResource(this.http);
+    this.variables = new VariablesResource(this.http);
+    this.connections = new ConnectionsResource(this.http);
+    this.projects = new ProjectsResource(this.http);
+    this.discovery = new DiscoveryResource(this.http);
+  }
+};
+
+// src/auth/token-store.ts
+function createMemoryTokenStore(initial) {
+  let accessToken = initial?.accessToken ?? null;
+  let refreshToken = initial?.refreshToken ?? null;
+  return {
+    getAccessToken: () => accessToken,
+    getRefreshToken: () => refreshToken,
+    setTokens: (tokens) => {
+      accessToken = tokens.accessToken;
+      if (tokens.refreshToken !== void 0) {
+        refreshToken = tokens.refreshToken;
+      }
+    },
+    clear: () => {
+      accessToken = null;
+      refreshToken = null;
+    }
+  };
+}
+function createLocalStorageTokenStore(options = {}) {
+  const accessTokenKey = options.accessTokenKey ?? "accessToken";
+  const refreshTokenKey = options.refreshTokenKey ?? "refreshToken";
+  const storage = options.storage ?? (typeof globalThis !== "undefined" ? globalThis.localStorage : void 0);
+  if (!storage) {
+    throw new Error(
+      "createLocalStorageTokenStore requires localStorage (or a custom storage option). On the server, use createMemoryTokenStore or pass accessToken / apiKey instead."
+    );
+  }
+  return {
+    getAccessToken: () => storage.getItem(accessTokenKey),
+    getRefreshToken: () => storage.getItem(refreshTokenKey),
+    setTokens: (tokens) => {
+      storage.setItem(accessTokenKey, tokens.accessToken);
+      if (tokens.refreshToken !== void 0) {
+        storage.setItem(refreshTokenKey, tokens.refreshToken);
+      }
+    },
+    clear: () => {
+      storage.removeItem(accessTokenKey);
+      storage.removeItem(refreshTokenKey);
+    }
+  };
+}
+
+// src/auth/create-client.ts
+function createBrowserClient(options) {
+  const tokenStore = options.tokenStore ?? createLocalStorageTokenStore();
+  return new LunnoaClient({
+    baseUrl: options.baseUrl,
+    tokenStore,
+    autoRefresh: options.autoRefresh ?? true,
+    fetch: options.fetch,
+    headers: options.headers
+  });
+}
+function createServerClient(options) {
+  if (!options.apiKey && !options.accessToken && !options.tokenStore) {
+    throw new Error(
+      "createServerClient requires apiKey, accessToken, or tokenStore."
+    );
+  }
+  return new LunnoaClient({
+    baseUrl: options.baseUrl,
+    apiKey: options.apiKey,
+    accessToken: options.accessToken,
+    tokenStore: options.tokenStore,
+    autoRefresh: options.autoRefresh,
+    fetch: options.fetch,
+    headers: options.headers
+  });
+}
+
+exports.API_KEY_PREFIX = API_KEY_PREFIX;
+exports.ActionsResource = ActionsResource;
+exports.AgentChatClient = AgentChatClient;
+exports.AgentChatStream = AgentChatStream;
+exports.AgentsResource = AgentsResource;
+exports.ApprovalsResource = ApprovalsResource;
+exports.AuthResource = AuthResource;
+exports.ConnectionsResource = ConnectionsResource;
+exports.DEFINE_KINDS = DEFINE_KINDS;
+exports.DiscoveryResource = DiscoveryResource;
+exports.EntitiesResource = EntitiesResource;
+exports.EntityTypesResource = EntityTypesResource;
+exports.ExecutionProgressStream = ExecutionProgressStream;
+exports.ExecutionTimeoutError = ExecutionTimeoutError;
+exports.ExecutionsResource = ExecutionsResource;
+exports.HttpClient = HttpClient;
+exports.KnowledgeResource = KnowledgeResource;
+exports.LunnoaApiError = LunnoaApiError;
+exports.LunnoaClient = LunnoaClient;
+exports.ProjectsResource = ProjectsResource;
+exports.QueueItemsResource = QueueItemsResource;
+exports.QueuesResource = QueuesResource;
+exports.RunsResource = RunsResource;
+exports.SsoAuthResource = SsoAuthResource;
+exports.TasksResource = TasksResource;
+exports.VariablesResource = VariablesResource;
+exports.WorkflowAppsResource = WorkflowAppsResource;
+exports.WorkflowsResource = WorkflowsResource;
+exports.assertApiKeyAllowedInEnvironment = assertApiKeyAllowedInEnvironment;
+exports.createBrowserClient = createBrowserClient;
+exports.createLocalStorageTokenStore = createLocalStorageTokenStore;
+exports.createMemoryTokenStore = createMemoryTokenStore;
+exports.createServerClient = createServerClient;
+exports.defineAction = defineAction;
+exports.defineAgent = defineAgent;
+exports.defineAiConnection = defineAiConnection;
+exports.defineConnection = defineConnection;
+exports.defineWorkflow = defineWorkflow;
+exports.isBrowserEnvironment = isBrowserEnvironment;
+exports.isLoginRequires2FA = isLoginRequires2FA;
+exports.iterateOffset = iterateOffset;
+exports.iteratePages = iteratePages;
+exports.parseSseEvents = parseSseEvents;
+exports.parseSseStream = parseSseStream;
+exports.resolveActionAppId = resolveActionAppId;
+exports.resolveActionId = resolveActionId;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map