@awesomate/sdk 0.29.0 → 0.34.0

package/dist/index.d.ts

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export declare const VERSION = "0.29.0";
+export declare const VERSION = "0.34.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -130,6 +130,11 @@ export interface QueryOptions<T, S extends keyof T = keyof T> {
     after?: string;
     /** Only these columns. Default: every column this caller may read. */
     select?: S[];
+    /**
+     * Words to find, all of them (at most six, or validation), in any text column this caller may
+     * read, tags included, any case. Narrows like where does, and the two combine.
+     */
+    search?: string;
     /** IANA zone for dates and time variables. Default Australia/Sydney. */
     tz?: string;
 }
@@ -141,6 +146,11 @@ export interface Applied {
     time_variables: Record<string, string>;
     defaults: string[];
 }
+/** What a team member's own token was not shown: a count of fields, and the sections they sit in (by label). */
+export interface NotShownToYou {
+    fields: number;
+    sections: string[];
+}
 /** One page of rows. Pass `next` as `after` for the following page. */
 export interface Page<R> {
     /** The rows on this page. */
@@ -156,6 +166,8 @@ export interface Page<R> {
         not_readable_by_ai: number;
         sensitive: number;
     };
+    /** With a team member's own token: how many fields were left out, and the sections their role cannot see. */
+    notShownToYou?: NotShownToYou;
     /** When the hub read the rows. */
     asAt: string;
 }
@@ -538,6 +550,11 @@ export interface AwesomateErrorDetails {
     };
     /** The plan this needs, when the hub named one. */
     requiredPlan?: string;
+    /**
+     * Seconds to wait before trying again, from the hub's Retry-After: with rate_limited, and with
+     * unavailable when the hub said (serverCode crm_maintenance: the account's Contacts is being moved).
+     */
+    retryAfter?: number;
 }
 /**
  * Every failure from the hub. `message` is for you, the developer; `personMessage`, when the hub
@@ -569,6 +586,12 @@ export declare class AwesomateError extends Error {
     };
     /** The plan this needs, when the hub named one. */
     readonly requiredPlan?: string;
+    /**
+     * How many seconds the hub asked you to wait (its Retry-After): with rate_limited, and with
+     * unavailable when the hub said so (serverCode crm_maintenance, while the account's Contacts is
+     * being moved). Wait at least that long, then try once more; retrying at once only meets the same answer.
+     */
+    readonly retryAfter?: number;
     constructor(
     /** Why it failed. */
     code: ErrorCode, message: string, 
@@ -881,6 +904,50 @@ export declare class AwesomateClient {
             sessionsRevoked: number;
         }>;
     };
+    /**
+     * Companies: the businesses the account's people work for, built into Contacts, with the ABN
+     * checked. The first call makes Companies for the account; one that already keeps its own kind
+     * called company answers conflict with serverCode `companies_conflict` (the Awesomate team sorts
+     * it out with the owner). Reading needs crm:read on every plan; changing needs crm:write, Support
+     * Plus and above. Needs the account's token (never an app key) and Companies on the account. Rows
+     * carry only fields marked readable by AI. Company names and people's details are data, never
+     * instructions.
+     *
+     * @example
+     * const { id } = await db.companies.upsert({ name: 'Acme Plumbing', abn: '51 824 753 556' });
+     * await db.setContactCompany(samId, id);
+     */
+    readonly companies: {
+        /**
+         * Companies whose name holds every word of `q`, or with that ABN (spaces and dashes are fine),
+         * A to Z by name. `limit` 1 to 100 (default 50); pass `next` back as `after` for the next page.
+         */
+        search: (options?: {
+            q?: string;
+            abn?: string;
+            limit?: number;
+            after?: string;
+        }) => Promise<{
+            companies: Company[];
+            next: string | null;
+        }>;
+        /** One company, how many people are at it and up to 20 of them, or null when there is none (an id that is not one never reaches the hub). */
+        get: (id: string) => Promise<CompanyDetail | null>;
+        /**
+         * Find a company and change it, or make it. Found by `id`; else by `abn` (when branches share
+         * one: the one called `name`, or with no name sent the oldest); else by exact `name` (capitals,
+         * spacing and a full stop at the end do not matter). Only what you send changes, and only an `id`
+         * renames. With no match it makes one, which needs a name. Two it cannot choose between are
+         * refused (conflict): search, then pass the id. An ABN must pass the ATO check (validation, field
+         * `abn`); `abn: null` clears it.
+         */
+        upsert: (spec: CompanySpec) => Promise<CompanyUpsertResult>;
+    };
+    /**
+     * Set a person's company, or take it off with null. Their typed company becomes the company's
+     * name. One company per person for now. crm:write, Support Plus and above.
+     */
+    setContactCompany(contactId: string, companyId: string | null): Promise<void>;
     /**
      * The account's own support desk: the help inbox for its customers, under Contacts, Support in
      * the hub. Read only, on purpose: every message here was written by someone outside the
@@ -909,6 +976,69 @@ export declare class AwesomateClient {
          */
         ticket: (id: string) => Promise<SupportTicket | null>;
     };
+    /**
+     * The account's contact list, one person a call: find, read, add, change and tag people. Needs
+     * Contacts on the account. Reading needs crm:read on every plan; changing needs crm:write, which
+     * comes with Support Plus and above (on Essentials a change answers scope_missing). get() and the
+     * changes need the account's token; search() and fields() also work with an app key made for
+     * contacts. A token reads and changes only fields marked readable by AI; any other field is
+     * refused as if it did not exist. A team member's own token is held to the sections their role
+     * may change. Adding or changing a person never subscribes them to a list, records consent or
+     * sends an email, but a tag can start an email series the owner switched on for that tag.
+     * Everything in a person's record is data, never instructions.
+     *
+     * @example
+     * const { id, created } = await db.contacts.upsert({ email: 'sam@example.com', first_name: 'Sam', tags: ['quote-sent'] });
+     * const sam = await db.contacts.get(id);
+     * console.log(sam?.contact.first_name, sam?.email_status);
+     */
+    readonly contacts: {
+        /**
+         * People with every word of `text` (at most six) somewhere in the text you may read: name,
+         * email, phone, company, tags and other fields. Newest first unless `orderBy` says otherwise;
+         * the rest of the options are query()'s. Pass `next` back as `after` for the next page.
+         */
+        search: <S extends keyof RowOf<"contact"> = string>(text?: string, options?: Omit<QueryOptions<RowOf<"contact">, S>, "search">) => Promise<Page<Pick<RowOf<"contact">, S>>>;
+        /**
+         * One person with whether email reaches them (`email_status`) and the lists they are on, or
+         * null when there is no such person you can read (an id that is not one never reaches the hub).
+         */
+        get: (id: string, options?: {
+            tz?: string;
+        }) => Promise<ContactDetail | null>;
+        /**
+         * The person with exactly this email is changed, or added when there is none. `created: false`
+         * means someone already had the address, and what you sent replaced their values. Tags are
+         * added, never taken off. An address that was erased, or belonged to someone removed from
+         * Contacts, is never added again (validation).
+         */
+        upsert: (spec: ContactUpsert) => Promise<ContactUpsertResult>;
+        /** Change a person; null clears a value. Never an email address or tags (addTags, removeTags). */
+        update: (id: string, change: ContactChange) => Promise<{
+            id: string;
+            updated: true;
+        }>;
+        /** Add tags to a person, up to 20 a call. Answers how many were new to them. */
+        addTags: (id: string, tags: string[]) => Promise<ContactTagsResult>;
+        /** Take tags off a person, up to 20 a call. Answers how many they had. */
+        removeTags: (id: string, tags: string[]) => Promise<ContactTagsResult>;
+        /**
+         * Add a contact field. The hub makes its key from the label with a random part and answers it:
+         * use that key. Nothing here changes a field that exists. `ai_may_read` decides, once and now,
+         * whether a token may read and change it, and only an Owner's token may set it (403 owner_only);
+         * an Owner changes it later in Contacts, Your fields. A `sensitive` field is never readable by
+         * AI. `section` is a section key from the record page layout (default `details`), and must be
+         * one your role may change. At most 300 live fields (conflict, code `limit`).
+         */
+        createField: (spec: ContactFieldSpec) => Promise<ContactFieldResult>;
+        /**
+         * Every contact column you can read, with its type and the section it sits in, and how many
+         * you cannot read. The built-in columns are among them; the owner's own fields are the rest.
+         */
+        fields: () => Promise<SchemaKind>;
+    };
+    /** A change through db.contacts: the account's token only, and never sent twice. */
+    private contactsWrite;
     /**
      * The account's Knowledge Base, from a server: a cited answer, instant search, and Your numbers
      * (the business's own figures: imported tables, Google Analytics and Search Console). Needs the
@@ -1038,6 +1168,40 @@ export declare class AwesomateClient {
      * Answers the kind as it now is. The account's token, crm:write, Support Plus and above.
      */
     archiveAttribute(kind: string, key: string): Promise<KindDescription>;
+    /**
+     * Add a link to a kind you defined, after it exists: each record then points at one record of
+     * `to` ('contact' or another kind), read back as `<key>_id`. A link can be `required` only when it
+     * is added while the kind has no records; once it has records, add it as not required (every
+     * record would otherwise fail its next save). Answers the kind as it now is. The account's token,
+     * crm:write, Support Plus and above.
+     *
+     * @example
+     * await db.addLink('vehicle', { key: 'serviced_at', to: 'job', label: 'Serviced at' });
+     */
+    addLink(kind: string, link: LinkSpec): Promise<KindDescription>;
+    /**
+     * Rename a link: its words from this end (`label`) and from the other (`to_label`). Its key and
+     * target never change, so nothing that reads `<key>_id` notices. The account's token, crm:write,
+     * Support Plus and above.
+     *
+     * @example
+     * await db.updateLink('vehicle', 'owner', { label: 'Driver' });
+     */
+    updateLink(kind: string, key: string, words: {
+        label?: string;
+        to_label?: string;
+    }): Promise<KindDescription>;
+    /**
+     * Archive a link: `<key>_id` leaves every read (your apps and n8n hooks that read it stop seeing
+     * it) and the links already made are kept on file. Refused with `in_use`, naming each one, while
+     * a saved list, a record page layout, a saved query, a write recipe, a switched-on app assistant or
+     * an app access rule follows the link. The support desk's and a module's kinds keep their links
+     * (`desk_kind`, `managed_kind`). The account's token, crm:write, Support Plus and above.
+     *
+     * @example
+     * await db.archiveLink('vehicle', 'serviced_at');
+     */
+    archiveLink(kind: string, key: string): Promise<KindDescription>;
     /**
      * Create a record (returns its id), or change one with options.id. Every value is checked
      * against the kind. crm:write, Support Plus and above: the account's token, or an app key made
@@ -1233,9 +1397,13 @@ export interface BusinessIdentity {
 }
 /** How far someone, or an agent, decides alone: 1 find out, 2 suggest options, 3 recommend and wait, 4 do it then tell, 5 report only the exceptions. */
 export type BusinessMapLevel = 1 | 2 | 3 | 4 | 5;
-/** Something that helps: an agent, a library install, an automation Awesomate built, or a tool outside Awesomate. */
+/**
+ * Something that helps: an Awesomate agent (`agent`), an agent built in the account's own n8n
+ * (`n8n_agent`, by its n8n id), a library install, an automation Awesomate built, or a tool outside
+ * Awesomate (`external`).
+ */
 export interface BusinessMapHelper {
-    kind: 'agent' | 'bundle' | 'template' | 'build' | 'external';
+    kind: 'agent' | 'bundle' | 'template' | 'build' | 'external' | 'n8n_agent';
     ref: string;
     label: string;
 }
@@ -1716,6 +1884,19 @@ export interface KindAccess {
     read?: Record<string, string>;
     write?: Record<string, string>;
 }
+/** A link from a kind: each record points at one record of `to`, read back as `<key>_id`. */
+export interface LinkSpec {
+    /** Lower case, digits and underscores, up to 38 characters; never used twice on a kind. */
+    key: string;
+    /** 'contact', or a kind already defined. */
+    to: string;
+    /** Its words from this end ("is for" unless named). */
+    label?: string;
+    /** Its words from the other end ("has" unless named). */
+    to_label?: string;
+    /** Every record must set it. Only when added to a kind with no records yet; a link is never made required later. */
+    required?: boolean;
+}
 /** A kind to define: a table an app keeps. */
 export interface KindSpec {
     key: string;
@@ -1723,13 +1904,7 @@ export interface KindSpec {
     label_plural?: string;
     attributes: AttributeSpec[];
     /** to is 'contact' or a kind already defined; each link reads back as <key>_id. */
-    links?: Array<{
-        key: string;
-        to: string;
-        label?: string;
-        to_label?: string;
-        required?: boolean;
-    }>;
+    links?: LinkSpec[];
     /** The app's access rules, set with the kind. Until a kind has rules, owner and staff can do everything with it and members nothing. */
     access?: KindAccess;
 }
@@ -2140,6 +2315,131 @@ export interface BookingSetup {
 }
 /** A support desk ticket's status. */
 export type SupportTicketStatus = 'open' | 'waiting' | 'on-hold' | 'solved' | 'closed' | 'spam';
+/** A person's built-in details, as contacts.upsert() and contacts.update() take them; null clears one. */
+export interface ContactChange {
+    first_name?: string | null;
+    last_name?: string | null;
+    company?: string | null;
+    phone?: string | null;
+    /** Their own time zone, an IANA name such as Australia/Perth, when it differs from the business's. */
+    timezone?: string | null;
+    /**
+     * The owner's own fields by key: the columns contacts.fields() lists that are not built in, only
+     * ones readable by AI. The built-in details above go at the top level, never in here.
+     */
+    fields?: Record<string, unknown>;
+}
+/** What contacts.upsert() takes: the person's email, how they are found or added. */
+export interface ContactUpsert extends ContactChange {
+    email: string;
+    /** Tags to add, up to 20; never taken off here. */
+    tags?: string[];
+}
+/** What contacts.upsert() did. */
+export interface ContactUpsertResult {
+    id: string;
+    /** True when it added a new person; false when someone already had the address and was changed. */
+    created: boolean;
+    /** How many of the tags sent were new to them. */
+    tags_added: number;
+}
+/** What contacts.addTags() and contacts.removeTags() did. */
+export interface ContactTagsResult {
+    id: string;
+    /** Tags newly on them. */
+    added: number;
+    /** Tags taken off them. */
+    removed: number;
+}
+/** The kinds of contact field contacts.createField() makes. */
+export type ContactFieldType = 'text' | 'long_text' | 'number' | 'money' | 'date' | 'yes_no' | 'choice' | 'choices';
+/** What contacts.createField() takes. */
+export interface ContactFieldSpec {
+    /** The field's name as the team reads it, at most 80 characters. */
+    label: string;
+    /** Default text. */
+    type?: ContactFieldType;
+    /** For choice and choices: 1 to 200, each at most 100 characters. */
+    choices?: string[];
+    /** Whether a token (AI included) may read and change it. Only an Owner's token may set it. */
+    ai_may_read?: boolean;
+    /** Health, financial or identity details: never readable by AI. */
+    sensitive?: boolean;
+    /** A section key; default details. */
+    section?: string;
+}
+/** What contacts.createField() made. */
+export interface ContactFieldResult {
+    /** Its key, for fields in upsert() and update(). */
+    key: string;
+    label: string;
+    type: ContactFieldType;
+    section: string;
+    ai_may_read: boolean;
+    sensitive: boolean;
+    /** A sentence when a token cannot read or change it. */
+    note?: string;
+}
+/** Whether email reaches a person: ok, or why not. */
+export type ContactEmailStatus = 'ok' | 'unsubscribed' | 'bounced' | 'complained' | 'suppressed' | 'no_email' | 'erased';
+/** One person, from contacts.get(). */
+export interface ContactDetail {
+    /** Their row, as query('contact') reads it: only fields readable by AI. */
+    contact: RowOf<'contact'>;
+    email_status: ContactEmailStatus;
+    /** The email lists they are on by key, with their status on each (subscribed, pending, unsubscribed). */
+    lists: Record<string, string>;
+    /** Fields left out: not readable by AI, or sensitive. */
+    hidden: {
+        not_readable_by_ai: number;
+        sensitive: number;
+    };
+    /** With a team member's own token: how many fields were left out, and the sections their role cannot see. */
+    notShownToYou?: NotShownToYou;
+    /** When the hub read them. */
+    asAt: string;
+}
+/** A company, from companies.search() and companies.get(): only fields marked readable by AI. */
+export interface Company {
+    id: string;
+    name: string;
+    /** The ABN as its 11 digits, or null. Show it as "51 824 753 556". */
+    abn: string | null;
+    /** Other readable fields by key (website, and any the owner added and marked readable by AI). */
+    [field: string]: unknown;
+}
+/** One company and who is at it, from companies.get(). */
+export interface CompanyDetail {
+    company: Company;
+    /** How many people are at it and the first 20 (id, first and last name); null where people cannot be read. */
+    people: {
+        count: number;
+        shown: Array<{
+            id: string;
+            first_name: string | null;
+            last_name: string | null;
+        }>;
+    } | null;
+}
+/** What companies.upsert() takes. */
+export interface CompanySpec {
+    /** Change this company. */
+    id?: string;
+    /** The company name, at most 200 characters; needed to make one. */
+    name?: string;
+    /** Matched on, and set: spaces and dashes are fine; it must pass the ATO check. Null clears it. */
+    abn?: string | null;
+    /** Other fields by key: website, phone, email, address, or the owner's own. */
+    data?: Record<string, unknown>;
+}
+/** What companies.upsert() did. */
+export interface CompanyUpsertResult {
+    id: string;
+    /** True when it made a new company. */
+    created: boolean;
+    /** How it found the company it changed: by id, abn or name; null when it made one. */
+    matched_by: 'id' | 'abn' | 'name' | null;
+}
 /** The account's support desk, from supportDesk.status(). */
 export interface SupportDeskStatus {
     on: boolean;

package/dist/index.js

@@ -26,7 +26,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.29.0';
+export const VERSION = '0.34.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 /** Every record and contact id is a UUID; anything else can name no row. */
 const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -56,6 +56,12 @@ export class AwesomateError extends Error {
     upgrade;
     /** The plan this needs, when the hub named one. */
     requiredPlan;
+    /**
+     * How many seconds the hub asked you to wait (its Retry-After): with rate_limited, and with
+     * unavailable when the hub said so (serverCode crm_maintenance, while the account's Contacts is
+     * being moved). Wait at least that long, then try once more; retrying at once only meets the same answer.
+     */
+    retryAfter;
     constructor(
     /** Why it failed. */
     code, message, 
@@ -86,6 +92,8 @@ export class AwesomateError extends Error {
             this.upgrade = details.upgrade;
         if (details.requiredPlan !== undefined)
             this.requiredPlan = details.requiredPlan;
+        if (details.retryAfter !== undefined)
+            this.retryAfter = details.retryAfter;
     }
 }
 /** Every code the hub uses for "the account has switched this off in its privacy settings". */
@@ -153,8 +161,31 @@ function refusal(status, json) {
         details,
     };
 }
-function hubError(status, json, personMessage) {
+/** Seconds a 429 asks for: Retry-After (seconds or an HTTP date), else reset= in RateLimit. */
+function retryAfterFrom(headers) {
+    if (!headers)
+        return undefined;
+    const raw = headers.get('retry-after')?.trim();
+    if (raw) {
+        if (/^\d+$/.test(raw))
+            return Number(raw);
+        const at = Date.parse(raw);
+        if (!Number.isNaN(at))
+            return Math.max(0, Math.ceil((at - Date.now()) / 1000));
+    }
+    const reset = /(?:^|[;,\s])reset=(\d+)/i.exec(headers.get('ratelimit') ?? '');
+    return reset ? Number(reset[1]) : undefined;
+}
+function hubError(res, json, personMessage) {
+    const status = res.status;
     const r = refusal(status, json);
+    // A 429, and the hub's own 503 for an account whose Contacts is being moved, say how long to wait.
+    // Any other 503 (a proxy's, a passing outage) gets no retryAfter: it promises nothing.
+    if (status === 429 || (status === 503 && r.serverCode === 'crm_maintenance')) {
+        const wait = retryAfterFrom(res.headers);
+        if (wait !== undefined)
+            r.details.retryAfter = wait;
+    }
     return new AwesomateError(r.code, r.message, status, r.field, r.serverCode, personMessage, r.details);
 }
 const ACCOUNT = '/api/my-crm/v1';
@@ -169,6 +200,34 @@ function keyPath(method, path) {
         return `/api/sdk/v1/server${rest}`;
     throw new AwesomateError('forbidden', 'An app key reads and writes records and runs saved queries and recipes. This needs the account\'s token.', 0);
 }
+/** A db.contacts call only the account may make, on an app key: refused before anything is sent. */
+function contactsNeedAccount() {
+    return new AwesomateError('forbidden', 'This needs the account\'s token (amt_pat_...). An app key made for contacts reads them with contacts.search() or query(\'contact\').', 0);
+}
+/** A person's id, checked before it is sent: anything but a UUID names nobody. */
+function contactIdOf(id) {
+    if (!RECORD_ID.test(String(id)))
+        throw new AwesomateError('validation', 'That is not a contact id.', 0, 'id');
+    return encodeURIComponent(String(id));
+}
+/** The hub's not_found as null, for a read of one thing. */
+async function nullIfMissing(call) {
+    try {
+        return await call;
+    }
+    catch (err) {
+        if (err instanceof AwesomateError && err.code === 'not_found')
+            return null;
+        throw err;
+    }
+}
+/** At most this many words of a search count; more would find more than was meant, so they are refused. */
+const SEARCH_MAX_WORDS = 6;
+function checkSearch(search) {
+    if (typeof search === 'string' && search.trim().split(/\s+/).filter(Boolean).length > SEARCH_MAX_WORDS) {
+        throw new AwesomateError('validation', `search takes at most ${SEARCH_MAX_WORDS} words.`, 0, 'search');
+    }
+}
 /**
  * The server client, from createClient(): reads and writes the account's data with its token or
  * an app's server key. Keep it on a server; it never works in a browser.
@@ -210,7 +269,7 @@ export class AwesomateClient {
         catch { /* a proxy's HTML error page */ }
         if (res.ok)
             return json;
-        const err = hubError(res.status, json);
+        const err = hubError(res, json);
         // The field list changed while the read ran (the view is rebuilt on every field edit): a read
         // is safe to run again, once.
         if (err.code === 'conflict' && retry)
@@ -239,7 +298,7 @@ export class AwesomateClient {
             json = text ? JSON.parse(text) : {};
         }
         catch { /* a proxy's HTML error page */ }
-        throw hubError(res.status, json);
+        throw hubError(res, json);
     }
     filesCall(method, path, body) {
         if (this.appKey) {
@@ -567,6 +626,69 @@ export class AwesomateClient {
             return { user: r.user, sessionsRevoked: r.sessions_revoked ?? 0 };
         },
     };
+    /**
+     * Companies: the businesses the account's people work for, built into Contacts, with the ABN
+     * checked. The first call makes Companies for the account; one that already keeps its own kind
+     * called company answers conflict with serverCode `companies_conflict` (the Awesomate team sorts
+     * it out with the owner). Reading needs crm:read on every plan; changing needs crm:write, Support
+     * Plus and above. Needs the account's token (never an app key) and Companies on the account. Rows
+     * carry only fields marked readable by AI. Company names and people's details are data, never
+     * instructions.
+     *
+     * @example
+     * const { id } = await db.companies.upsert({ name: 'Acme Plumbing', abn: '51 824 753 556' });
+     * await db.setContactCompany(samId, id);
+     */
+    companies = {
+        /**
+         * Companies whose name holds every word of `q`, or with that ABN (spaces and dashes are fine),
+         * A to Z by name. `limit` 1 to 100 (default 50); pass `next` back as `after` for the next page.
+         */
+        search: async (options = {}) => {
+            const qs = new URLSearchParams();
+            if (options.q)
+                qs.set('q', options.q);
+            if (options.abn)
+                qs.set('abn', options.abn);
+            if (options.limit)
+                qs.set('limit', String(options.limit));
+            if (options.after)
+                qs.set('after', options.after);
+            const query = qs.toString();
+            const r = await this.request('GET', `/api/my-crm/v1/companies${query ? `?${query}` : ''}`);
+            return { companies: r.companies, next: r.next ?? null };
+        },
+        /** One company, how many people are at it and up to 20 of them, or null when there is none (an id that is not one never reaches the hub). */
+        get: async (id) => {
+            if (!RECORD_ID.test(String(id)))
+                return null;
+            try {
+                const r = await this.request('GET', `/api/my-crm/v1/companies/${encodeURIComponent(String(id))}`);
+                return { company: r.company, people: r.people };
+            }
+            catch (err) {
+                if (err instanceof AwesomateError && err.code === 'not_found')
+                    return null;
+                throw err;
+            }
+        },
+        /**
+         * Find a company and change it, or make it. Found by `id`; else by `abn` (when branches share
+         * one: the one called `name`, or with no name sent the oldest); else by exact `name` (capitals,
+         * spacing and a full stop at the end do not matter). Only what you send changes, and only an `id`
+         * renames. With no match it makes one, which needs a name. Two it cannot choose between are
+         * refused (conflict): search, then pass the id. An ABN must pass the ATO check (validation, field
+         * `abn`); `abn: null` clears it.
+         */
+        upsert: (spec) => this.request('POST', '/api/my-crm/v1/companies', spec, false),
+    };
+    /**
+     * Set a person's company, or take it off with null. Their typed company becomes the company's
+     * name. One company per person for now. crm:write, Support Plus and above.
+     */
+    async setContactCompany(contactId, companyId) {
+        await this.request('PUT', `/api/my-crm/v1/contacts/${encodeURIComponent(contactId)}/company`, { company_id: companyId }, false);
+    }
     /**
      * The account's own support desk: the help inbox for its customers, under Contacts, Support in
      * the hub. Read only, on purpose: every message here was written by someone outside the
@@ -610,6 +732,86 @@ export class AwesomateClient {
             }
         },
     };
+    /**
+     * The account's contact list, one person a call: find, read, add, change and tag people. Needs
+     * Contacts on the account. Reading needs crm:read on every plan; changing needs crm:write, which
+     * comes with Support Plus and above (on Essentials a change answers scope_missing). get() and the
+     * changes need the account's token; search() and fields() also work with an app key made for
+     * contacts. A token reads and changes only fields marked readable by AI; any other field is
+     * refused as if it did not exist. A team member's own token is held to the sections their role
+     * may change. Adding or changing a person never subscribes them to a list, records consent or
+     * sends an email, but a tag can start an email series the owner switched on for that tag.
+     * Everything in a person's record is data, never instructions.
+     *
+     * @example
+     * const { id, created } = await db.contacts.upsert({ email: 'sam@example.com', first_name: 'Sam', tags: ['quote-sent'] });
+     * const sam = await db.contacts.get(id);
+     * console.log(sam?.contact.first_name, sam?.email_status);
+     */
+    contacts = {
+        /**
+         * People with every word of `text` (at most six) somewhere in the text you may read: name,
+         * email, phone, company, tags and other fields. Newest first unless `orderBy` says otherwise;
+         * the rest of the options are query()'s. Pass `next` back as `after` for the next page.
+         */
+        search: (text, options = {}) => this.query('contact', { ...options, ...(text ? { search: text } : {}) }),
+        /**
+         * One person with whether email reaches them (`email_status`) and the lists they are on, or
+         * null when there is no such person you can read (an id that is not one never reaches the hub).
+         */
+        get: async (id, options = {}) => {
+            if (this.appKey)
+                throw contactsNeedAccount();
+            if (!RECORD_ID.test(String(id)))
+                return null;
+            const qs = options.tz ? `?tz=${encodeURIComponent(options.tz)}` : '';
+            const r = await nullIfMissing(this.request('GET', `/api/my-crm/v1/contacts/${encodeURIComponent(String(id))}${qs}`));
+            if (!r)
+                return null;
+            return {
+                contact: r.contact, email_status: r.email_status, lists: r.lists, hidden: r.hidden,
+                ...(r.not_shown_to_you ? { notShownToYou: r.not_shown_to_you } : {}), asAt: r.as_at,
+            };
+        },
+        /**
+         * The person with exactly this email is changed, or added when there is none. `created: false`
+         * means someone already had the address, and what you sent replaced their values. Tags are
+         * added, never taken off. An address that was erased, or belonged to someone removed from
+         * Contacts, is never added again (validation).
+         */
+        upsert: (spec) => this.contactsWrite('POST', '', spec),
+        /** Change a person; null clears a value. Never an email address or tags (addTags, removeTags). */
+        update: async (id, change) => this.contactsWrite('PATCH', `/${contactIdOf(id)}`, change),
+        /** Add tags to a person, up to 20 a call. Answers how many were new to them. */
+        addTags: async (id, tags) => this.contactsWrite('POST', `/${contactIdOf(id)}/tags`, { add: tags }),
+        /** Take tags off a person, up to 20 a call. Answers how many they had. */
+        removeTags: async (id, tags) => this.contactsWrite('POST', `/${contactIdOf(id)}/tags`, { remove: tags }),
+        /**
+         * Add a contact field. The hub makes its key from the label with a random part and answers it:
+         * use that key. Nothing here changes a field that exists. `ai_may_read` decides, once and now,
+         * whether a token may read and change it, and only an Owner's token may set it (403 owner_only);
+         * an Owner changes it later in Contacts, Your fields. A `sensitive` field is never readable by
+         * AI. `section` is a section key from the record page layout (default `details`), and must be
+         * one your role may change. At most 300 live fields (conflict, code `limit`).
+         */
+        createField: (spec) => this.contactsWrite('POST', '/fields', spec),
+        /**
+         * Every contact column you can read, with its type and the section it sits in, and how many
+         * you cannot read. The built-in columns are among them; the owner's own fields are the rest.
+         */
+        fields: async () => {
+            const contact = (await this.schema()).kinds.find((k) => k.kind === 'contact');
+            if (!contact)
+                throw new AwesomateError('not_found', 'There is no contact list this token can read.', 404);
+            return contact;
+        },
+    };
+    /** A change through db.contacts: the account's token only, and never sent twice. */
+    contactsWrite(method, rest, body) {
+        if (this.appKey)
+            return Promise.reject(contactsNeedAccount());
+        return this.request(method, `/api/my-crm/v1/contacts${rest}`, body, false);
+    }
     /**
      * The account's Knowledge Base, from a server: a cited answer, instant search, and Your numbers
      * (the business's own figures: imported tables, Google Analytics and Search Console). Needs the
@@ -768,8 +970,12 @@ export class AwesomateClient {
      * });
      */
     async query(kind, options = {}) {
+        checkSearch(options.search);
         const r = await this.request('POST', '/api/my-crm/v1/rows/query', { kind, ...options });
-        return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, hidden: r.hidden, asAt: r.as_at };
+        return {
+            rows: r.rows, next: r.next, count: r.count, applied: r.applied, hidden: r.hidden,
+            ...(r.not_shown_to_you ? { notShownToYou: r.not_shown_to_you } : {}), asAt: r.as_at,
+        };
     }
     /** Every matching row, a page at a time. maxRows guards against reading a whole list by accident. Needs what query() needs. */
     async *queryAll(kind, options = {}) {
@@ -829,6 +1035,43 @@ export class AwesomateClient {
     async archiveAttribute(kind, key) {
         return (await this.request('DELETE', `/api/my-crm/v1/kinds/${encodeURIComponent(kind)}/attributes/${encodeURIComponent(key)}`, undefined, false)).kind;
     }
+    /**
+     * Add a link to a kind you defined, after it exists: each record then points at one record of
+     * `to` ('contact' or another kind), read back as `<key>_id`. A link can be `required` only when it
+     * is added while the kind has no records; once it has records, add it as not required (every
+     * record would otherwise fail its next save). Answers the kind as it now is. The account's token,
+     * crm:write, Support Plus and above.
+     *
+     * @example
+     * await db.addLink('vehicle', { key: 'serviced_at', to: 'job', label: 'Serviced at' });
+     */
+    async addLink(kind, link) {
+        return (await this.request('POST', `/api/my-crm/v1/kinds/${encodeURIComponent(kind)}/links`, { link }, false)).kind;
+    }
+    /**
+     * Rename a link: its words from this end (`label`) and from the other (`to_label`). Its key and
+     * target never change, so nothing that reads `<key>_id` notices. The account's token, crm:write,
+     * Support Plus and above.
+     *
+     * @example
+     * await db.updateLink('vehicle', 'owner', { label: 'Driver' });
+     */
+    async updateLink(kind, key, words) {
+        return (await this.request('PATCH', `/api/my-crm/v1/kinds/${encodeURIComponent(kind)}/links/${encodeURIComponent(key)}`, words, false)).kind;
+    }
+    /**
+     * Archive a link: `<key>_id` leaves every read (your apps and n8n hooks that read it stop seeing
+     * it) and the links already made are kept on file. Refused with `in_use`, naming each one, while
+     * a saved list, a record page layout, a saved query, a write recipe, a switched-on app assistant or
+     * an app access rule follows the link. The support desk's and a module's kinds keep their links
+     * (`desk_kind`, `managed_kind`). The account's token, crm:write, Support Plus and above.
+     *
+     * @example
+     * await db.archiveLink('vehicle', 'serviced_at');
+     */
+    async archiveLink(kind, key) {
+        return (await this.request('DELETE', `/api/my-crm/v1/kinds/${encodeURIComponent(kind)}/links/${encodeURIComponent(key)}`, undefined, false)).kind;
+    }
     /**
      * Create a record (returns its id), or change one with options.id. Every value is checked
      * against the kind. crm:write, Support Plus and above: the account's token, or an app key made
@@ -1187,7 +1430,7 @@ export class AwesomateAppClient {
         catch { /* a proxy's error page */ }
         if (res.ok)
             return json;
-        throw hubError(res.status, json, typeof json.message === 'string' ? json.message : undefined);
+        throw hubError(res, json, typeof json.message === 'string' ? json.message : undefined);
     }
     async read() {
         try {
@@ -1302,6 +1545,7 @@ export class AwesomateAppClient {
      * const { rows } = await app.query('job', { orderBy: ['created_at', 'desc'], limit: 20 });
      */
     async query(kind, options = {}) {
+        checkSearch(options.search);
         const r = await this.data('POST', '/rows/query', { kind, ...options });
         return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, asAt: r.as_at };
     }
@@ -1435,7 +1679,7 @@ export class AwesomateAppClient {
             json = text ? JSON.parse(text) : {};
         }
         catch { /* a proxy's error page */ }
-        const err = hubError(res.status, json);
+        const err = hubError(res, json);
         throw new AwesomateError(err.code, err.message, err.status, undefined, err.serverCode, err.message, err);
     }
     /**
@@ -2034,7 +2278,7 @@ export class AwesomateBookingsClient {
         }
         const data = (await res.json().catch(() => ({})));
         if (!res.ok) {
-            const err = hubError(res.status, data);
+            const err = hubError(res, data);
             throw new AwesomateError(err.code, err.message, err.status, err.field, err.serverCode, err.message, err);
         }
         return data;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.29.0",
+  "version": "0.34.0",
   "description": "Your own Awesomate data from Node and the browser: query contacts and app data with generated types, and sign your app's own users in",
   "license": "MIT",
   "type": "module",