Guides

Kinds and records

Define the tables an app keeps, write records with the server client, and choose which fields Claude, agents and the account's token may read.

A kind is a table your app keeps: jobs, quotes, bookings, messages. Defining one takes no migration and no SQL. Defining kinds and writing records needs the Support Plus plan or above.

#Define a kind

Ask Claude Code (awesomate_crm_kinds), or use the server client with the account's token:

await db.defineKind({
  key: 'job',
  label: 'Job',
  label_plural: 'Jobs',
  attributes: [
    { key: 'title', type: 'text', required: true, readable_by_ai: true },
    { key: 'status', type: 'choice', choices: ['open', 'quoted', 'booked', 'done'], readable_by_ai: true },
    { key: 'quote', type: 'money', readable_by_ai: true },
  ],
  links: [{ key: 'customer', to: 'contact', label: 'is for' }],
});

• Attribute types: text, long_text, number, money, date, datetime, duration, yes_no, choice, choices, email, phone, address, url, file.
• A link points at contact or a kind you already made, and reads back as <key>_id.
• sensitivity is ordinary (default), personal or sensitive. A sensitive attribute is never readable by AI.

#Write and archive

const id = await db.write('job', { title: 'Possum in the roof', status: 'open' }, { links: { customer: contactId } });
await db.write('job', { status: 'booked' }, { id }); // values you don't give stay as they are
await db.archive('job', id);                         // leaves every read; kept, and can be restored

Every value is checked against the kind: types, choices, required attributes and links. A refusal is a validation error whose field names the attribute. Set a link to null to end it.

The app client writes the same way, as the signed-in person, inside their write rule.

#Readable by AI

readable_by_ai decides what Claude, your agents and the account's token see. With the account's token, query() and get() return only readable attributes, and hidden on each page counts the rest. Mark an attribute readable when the owner wants Claude and agents to use it, never for anything sensitive.

An app's own people read every attribute their rules allow, and an app server key reads every attribute of its kinds: they are your app, not a model.

#Fields only some roles see

Some fields belong on a record a customer can read but are not for them, such as a cost or a note for your team. Ask Claude to make one visible only to staff (awesomate_crm_kinds, set_visibility). Other roles read it as null and cannot write it.

#Change a kind

A kind you defined from code can gain an attribute, or lose one, from code:

await db.addAttribute('job', { key: 'notes', label: 'Notes', type: 'long_text', readable_by_ai: true });
await db.archiveAttribute('job', 'notes'); // leaves every read; its values are kept

Records already there have no value for a new attribute. Both answer the kind as it now is, and need the account's token with crm:write, Support Plus and above. Run npx @awesomate/sdk types again afterwards so your types match.

#Your contacts

Contacts are not written this way: the contact list keeps its own consent rules. Read them with query('contact', ...) on the server client.