Docs

Entities

Query, create, and change entity state with @lunnoa/client.

Entities (Objects) are typed records defined by your deployment's entity types. Load the schema, create records with attributes keyed by field ID, then iterate or change state as needed.

Prefer codegen when you can: lunnoa.entities.invoice.create({ ... }) is compile-time checked. Without it, use the generic entities / entityTypes namespaces and discovery.

Attribute rules

By default, entity types reject unknown attribute keys on create and update. Keys must match field IDs declared on the type's attributeSchema.

KeyAllowed when
Declared field IDAlways (subject to required / type checks)
extensionsAlways, as a JSON object (intentional flexible bag)
Any other keyOnly if the type has allowUnknownAttributes: true

Admins set allowUnknownAttributes in Adminspace object type Settings, or via the CLI / defineEntityType. Schema itself is authored in Adminspace (Form or JSON) or deployed from code; the Public SDK does not invent new field definitions on write.

Query and create

entities.ts
const invoiceType = await lunnoa.entityTypes.getBySlug('invoice', {  expansion: ['attributeSchema', 'stateSchema'],});const created = await lunnoa.entities.create({  name: 'INV-2026-0042',  objectTypeId: invoiceType.id,  attributes: {    amount: 1250.5,    currency: 'CHF', // field IDs from attributeSchema    extensions: { source: 'partner-portal' }, // always allowed  },});for await (const invoice of lunnoa.entities.iterate({  objectTypeSlug: 'invoice',})) {  // pages fetched lazily}await lunnoa.entities.changeState(created.id, {  newState: 'approved',  reason: 'Matches purchase order',});

List conventions

  • One page: entities.list({ objectTypeSlug, state, search, page, pageSize, expansion }) (default page size 20, max 100)
  • Everything: entities.iterate(...) fetches pages lazily for exports or aggregations
  • State changes are validated against the type's state machine
  • Prefer entities.getStateTransitions(id) for transitions valid now, not the full schema

Deploy entity types from code

To create or update the type (schema), use defineEntityType and npx @lunnoa/client entity-types deploy. That path is workspace-scoped (no --project-id). See Define locally and CLI.

Next