Docs

TypeScript client SDK

Build custom apps on top of Lunnoa Automate with @lunnoa/client.

@lunnoa/client is the official TypeScript SDK for the Lunnoa Automate Public API. Use it to build portals, internal tools, chat UIs, and backends that talk to your deployment's agents, workflows, entities, queues, and knowledge.

The SDK is presentation-free: no components, hooks, or widgets. You bring your own UI framework and design system; the SDK provides typed data access, SSE agent chat streaming, and deployment-specific codegen.

Requirements

Before you install, make sure you have:

  • Node.js 20 or newer (or any runtime with fetch and web streams)
  • A Lunnoa Automate deployment URL
  • Either a workspace API key (lna_…) or a user JWT

Install

Add the package to your app:

install.sh
npm install @lunnoa/client

Quickstart

Create a client against your deployment, then list entities. Expansion fields are optional extras: responses are minimal by default, so request what you plan to render.

quickstart.ts
import { LunnoaClient } from '@lunnoa/client';const lunnoa = new LunnoaClient({  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 Admin Space → API Keys, choosing the workspace and an RBAC role for the key's service account. Prefer a minimal custom role over Admin. See API authentication for key creation and security notes.

Authentication

Pick one pattern before you write UI code. Mixing them usually means a leaked key or broken permissions.

PatternCredentialWhere
A. Backend holds the keyapiKey: 'lna_…'Your server, background jobs, server-rendered pages
B. End users are Lunnoa usersaccessToken: <user JWT>Browser apps. Users log in via /api/auth or /api/sso
server.ts
const lunnoa = new LunnoaClient({  baseUrl,  apiKey: process.env.LUNNOA_API_KEY,});

Resources

Most namespaces map to the Public API surface. approvals uses the authenticated workspace API (see Approvals).

NamespacePurpose
agents / tasks / agentChatAgents, task history, SSE chat streaming
workflows / executionsTrigger workflows and poll or wait for results
entities / entityTypesObjects and their schemas / state machines
knowledgeKnowledge bases and documents
queues / queueItemsHuman-in-the-loop work items
approvalsRequest Approval inbox (workspace API)
variables / connections / projectsWorkspace configuration
workflowAppsResolve app/action IDs to labels and icons
discoveryFeature flags for the deployment's edition

List calls accept shared conventions: expansion (extra fields), filterBy, and pagination (page / pageSize). Many list resources also support async iteration (entities.iterate(...), queueItems.iterate(...)).

Browse every public operation on the API reference.

Guides in this section

GuideWhat you will do
CodegenGenerate typed accessors for your deployment
DiscoveryInspect agents, workflows, and entity schemas at runtime
EntitiesQuery, create, and change entity state
WorkflowsTrigger runs, render executionPath, resume NEEDS_INPUT
Agent chatStream SSE chat in the AI SDK UIMessage format
QueuesWork through human-in-the-loop queue items
ApprovalsList pending approvals and decide
ErrorsHandle LunnoaApiError status helpers

Checklist for a new custom UI

Use this as a short go-live list once the SDK is wired in.

  1. Choose an auth pattern

    Confirm base URL and pattern A or B. Keep lna_ keys server-side only.

  2. Run codegen

    Run npx @lunnoa/client codegen against the deployment and commit the output. See Codegen.

  3. Adapt to features

    Call discovery.enabledFeatures() and hide unsupported areas. See Discovery.

  4. Build from schemas

    Drive forms and tables from attributeSchema / customInputConfig, or from the generated types.

  5. Handle workflow UX

    Render progress from executionPath. Resume NEEDS_INPUT with submitInput. See Workflows.

  6. Wire chat carefully

    Stream via SSE, handle resume and stop, load history from the task. See Agent chat.

  7. Handle API errors

    Map 401 to re-auth, 403 to hide the capability, and 429 to back off. See Errors.

Related