Skip to content
Menu

Records module

Keeps typed business records and moves them through the stages you define, checking each move against your rules.

On this page

What it is for

Keeps typed business records and moves them through the stages you define, checking each move against your rules.

  • You track items such as invoices, bookings, cases or stock through fixed stages.
  • You want the bot to refuse a step that skips a stage or lacks required details.
  • You want a list of records that match a stage or a value.

Ask your bot

You do not type commands. Ask in plain words and the bot runs the module for you.

You ask
A new booking came in. Record it, then show me every booking that is still waiting for confirmation.
What you get back
The bot creates the record and lists the records in that stage. If a step would skip a stage or lacks a required detail, it tells you which rule stopped it.

What the bot does with it

  • The bot defines a record type for the things you track, with the fields and stages you describe.
  • It creates and updates records as work comes in.
  • It moves a record forward only along a move you declared, after the required fields have values.
  • It answers questions such as which records are in a given stage, straight from the module's query results.
  • Every write carries a retry key, so repeating a request does not create a duplicate.

What it stores

Record types, records and a history of every change live in one SQLite file, records/records.sqlite, in the bot's Ambitious folder (/workspace/ambitious by default).

The module has no screens of its own. It reads JSON, writes JSON, and keeps its data under /workspace/ambitious on the bot's computer. It never sends data anywhere.

Command reference

For the technically curious. You will rarely type these yourself; the bot runs them. Every command answers with the same envelope: whether it worked, which module and command ran, the data, and a list of errors with a hint for each. Open an example to see the command and its output.

ExampleAsk which stages a record can move to next. Here the move to sent still needs a due date.

Command

echo '{"id":"rec_2be28b99264f0c251ab9f6dd1379b5835084320e9385661ddf52a173c0324957"}' | ambitious-records allowed --json

Output

{
  "ok": true,
  "schemaVersion": 1,
  "module": "records",
  "command": "allowed",
  "data": {
    "allowed": [
      { "to": "sent", "missing": ["due"] },
      { "to": "void", "missing": [] }
    ]
  },
  "errors": [],
  "meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}
ExampleMove the record to the sent stage after the due date was filled in. The module returns the updated record.

Command

echo '{"id":"rec_2be28b99264f0c251ab9f6dd1379b5835084320e9385661ddf52a173c0324957","to":"sent","idem_key":"send-march-invoice"}' | ambitious-records move --json

Output

{
  "ok": true,
  "schemaVersion": 1,
  "module": "records",
  "command": "move",
  "data": {
    "record": {
      "id": "rec_2be28b99264f0c251ab9f6dd1379b5835084320e9385661ddf52a173c0324957",
      "type": "invoice",
      "type_version": 1,
      "stage": "sent",
      "fields": { "amount": "1250", "customer": "Example customer", "due": "2026-03-31", "number": "MARCH-001" },
      "created_at": "2026-03-01T10:00:00.000Z",
      "updated_at": "2026-03-02T09:00:00.000Z"
    }
  },
  "errors": [],
  "meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}
Show every command
commandsLists every command the module offers.
selfcheckChecks the installed file and the database, applies pending database updates and lists any problems in plain words.
type defineDefines a record type with its fields, stages and allowed moves, or adds a compatible new version.
type listLists every record type and version.
type getReturns one record type, the latest version unless another is named.
createCreates a record in the first stage of its type.
updateChanges or removes field values on a record.
moveMoves a record to another stage if that move is allowed and its required fields are filled in.
allowedLists the stages a record can move to next and the fields still missing for each.
queryFinds records of one type by stage and field values, with sorting and a limit.
historyReturns the ordered list of changes made to one record.

Source and releases

The module is open source under the Apache license. Each release carries one bundled file and its checksums; the bot installs it for you.