Products

Products manages the agent’s product catalog: free-form JSON products keyed by an id you choose, listed with pagination and a Lua Query filter, or found by semantic search. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. A product goes into a basket by its id. Verified against lua-cli 3.33.0.

import { Products } from 'lua-cli';

Quick example

import { Products } from 'lua-cli';

const product = await Products.create({ id: 'MBP-14', name: 'MacBook Pro 14', price: 1999, inStock: true });
const hits = await Products.search('laptop for video editing');
console.log(product.name, hits.map((p) => p.name));

Methods

get()

Returns one page of products, optionally filtered.

Products.get(page?: number, limit?: number): Promise<ProductPaginationInstance>
Products.get(options?: { page?: number; limit?: number; filter?: LuaQuery }): Promise<ProductPaginationInstance>

number

default:1

Page number, starting at 1.

number

default:10

Products per page.

LuaQuery

Matches product fields; see Lua Query. Options form only.

Returns

ProductPaginationInstance

An iterable page. It has no data property.

Show properties

ProductInstance[]

The page’s products.

object

currentPage, totalPages, totalCount, limit, hasNextPage, hasPrevPage, nextPage, and prevPage.

number

Products on this page.

function

Array helpers over products; the instance is also iterable with for...of.

() => Promise<ProductPaginationInstance>

Fetch the adjacent page with the same limit. Throw No next page and No previous page at the ends.

Example

import { Products } from 'lua-cli';

const page = await Products.get({ page: 1, limit: 20, filter: { inStock: true, price: { $lte: 500 } } });
for (const product of page) {
  console.log(product.name, product.price);
}
if (page.pagination.hasNextPage) {
  const next = await page.nextPage();
  console.log(next.length);
}

Errors — Failed to get products; No next page and No previous page from the paging helpers.

create()

Creates a product, or updates the product that already has the same id.

Products.create(product: Product): Promise<ProductInstance>

{ id: string; [key: string]: any }

required

id is your identifier (a SKU, a catalog id, a UUID you mint) and the only required field. Everything else is free-form.

Returns — the product as a ProductInstance. Example

import { Products } from 'lua-cli';

const mouse = await Products.create({
  id: 'MOUSE-001',
  name: 'Wireless mouse',
  price: 29.99,
  category: 'Electronics',
  inStock: true,
});
console.log(mouse.id, mouse.price);

Errors — Failed to create product when the platform rejects the write.

delete()

Deletes a product by id.

Products.delete(id: string): Promise<DeleteProductResponse>

Returns

boolean

true when the product was removed.

Example

import { Products } from 'lua-cli';

const { deleted } = await Products.delete('MOUSE-001');

Errors — Failed to delete product when no product has that id.

search()

Returns up to five products semantically closest to a query.

Products.search(query: string): Promise<ProductSearchInstance>

string

required

Natural-language query.

Returns

ProductSearchInstance

An iterable result set with products, length, and the same array helpers as a page. No pagination, no data, and no limit argument: the platform returns at most five matches.

Example

import { Products } from 'lua-cli';

const results = await Products.search('wireless headphones');
const affordable = results.filter((p) => p.price < 100);
console.log(results.length, affordable.map((p) => p.name));

Errors — Failed to search products.

getById()

Returns one product by id.

Products.getById(id: string): Promise<ProductInstance>

Returns — the product as a ProductInstance. There is no null return: an unknown id throws. Example

import { Products } from 'lua-cli';

let product;
try {
  product = await Products.getById('MBP-14');
} catch {
  throw new Error('Product not found: MBP-14');
}
console.log(product.name);

Errors — Failed to get product when no product has that id.

ProductInstance

The object create(), getById(), and the page and search results hold. Product fields are readable and writable directly (product.price) and through product.data; direct assignments stay local until save().

Product

The product object, including id.

update()

Merges fields into the product on the server and locally.

product.update(data: Record<string, any>): Promise<Product>

Returns — the updated product. Errors — Failed to update product when the platform reports no update.

delete()

Deletes the product and empties the local data.

product.delete(): Promise<Product>

Returns — the emptied product object.

save()

Writes the whole local data to the server.

product.save(): Promise<boolean>

Returns — true. Example

import { Products } from 'lua-cli';

const product = await Products.getById('MBP-14');
product.price = 1799;
product.inStock = false;
await product.save();

Errors — Failed to save product data.

toJSON()

Returns data, which is what JSON.stringify(product) and console.log(product) print.

Types

ProductInstance is exported. Product ({ id: string; [key: string]: any }), ProductFilterOptions, ProductPaginationInstance, and ProductSearchInstance are not; name them from the method that returns them.

import { Products } from 'lua-cli';
import type { ProductInstance } from 'lua-cli';

type ProductPage = Awaited<ReturnType<typeof Products.get>>;
type ProductSearch = Awaited<ReturnType<typeof Products.search>>;

export function cheapest(page: ProductPage | ProductSearch): ProductInstance | undefined {
  return page.reduce<ProductInstance | undefined>(
    (best, p) => (best === undefined || p.price < best.price ? p : best),
    undefined,
  );
}

SDK

CLI

REST API

Quick example

Methods

get()

create()

delete()

search()

getById()

ProductInstance

update()

delete()

save()

toJSON()

Types

See also

​Quick example

​Methods

​get()

​create()

​delete()

​search()

​getById()

​ProductInstance

​update()

​delete()

​save()

​toJSON()

​Types

​See also

Quick example

Methods

get()

create()

delete()

search()

getById()

ProductInstance

update()

delete()

save()

toJSON()

Types

See also