@awesomate/sdk 0.34.0 → 0.51.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.34.0";
+export declare const VERSION = "0.51.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -135,7 +135,7 @@ export interface QueryOptions<T, S extends keyof T = keyof T> {
      * 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. */
+    /** IANA zone for dates and time variables. Default: the business's time zone from Your business, Sydney if none is set. */
     tz?: string;
 }
 /** What the hub assumed for a query (order, limit, time zone, what each time variable meant), so it can be said back. */
@@ -243,6 +243,28 @@ export interface TaskCard {
         canDrop: boolean;
         canEdit: boolean;
     } | null;
+    /**
+     * Set for a task given to a role on the business map rather than a person (an agent's or a
+     * stage's): everyone in the role sees it until one of them takes it. `queued` while nobody has;
+     * `takenBy` once someone has; `mayTake` when this token's owner may take it with take(). Null or
+     * absent for every other card.
+     */
+    role?: {
+        jobId: number;
+        slug: string | null;
+        title: string | null;
+        queued: boolean;
+        takenBy: TaskPerson | null;
+        /** Nobody took it in 4 business hours, so it went to the person responsible for the role. */
+        unclaimed?: boolean;
+        /** While it waits: when it goes to the person responsible if nobody takes it, and that as a sentence. */
+        goesTo?: {
+            at: string;
+            words: string;
+        } | null;
+        inRole: boolean;
+        mayTake: boolean;
+    } | null;
 }
 /** A card's one-tap action, by name (the hub page behind the card runs it). */
 export type TaskCardAction = {
@@ -258,6 +280,11 @@ export type TaskCardAction = {
 } | {
     name: 'finish_task';
     taskId: number;
+}
+/** A role's task nobody has taken yet: take() makes it yours. */
+ | {
+    name: 'take_task';
+    taskId: number;
 } | {
     name: 'approve_public_reply';
     taskId: number;
@@ -337,6 +364,16 @@ export interface DecisionCard {
         kind: 'person' | 'owners';
         label: string;
     };
+    /**
+     * A role's decision within the role's limits: anyone in `role` who can decide it may answer it, and
+     * the first answer decides it. `people` is how many may answer it now; `line` is the sentence the
+     * hub shows ("Any of you in Bookkeeping can answer."). Null or absent when only `decider` can.
+     */
+    shared?: {
+        role: string;
+        people: number;
+        line: string;
+    } | null;
     /** Work waits behind it: a yes lets it carry on. */
     holdsWork: boolean;
     /** What may be pressed now. Always empty for an account token: deciding is a person's tap in the hub. */
@@ -459,15 +496,49 @@ export interface TaskRecord {
         handoffs: number;
     };
 }
-/** A task to give: to someone on the account by email, or to the owner when `forEmail` is left out. */
+/**
+ * A task to give: to someone on the account by email, to a role on the business map by its key, or
+ * to the owner when both are left out. Send `forEmail` or `role`, never both.
+ */
 export interface GiveTask {
     title: string;
     detail?: string;
     forEmail?: string;
+    /**
+     * A role on the business map, by its key (`slug` in `businessMap()`'s roles), instead of a person.
+     * Everyone in the role sees it until one of them takes it; a role with nobody in it who can act
+     * sends it to the owner. A role not on the map is refused (`serverCode: 'unknown_role'`, with the
+     * map's roles in the error's `roles`). Needs the business map (`business_map`).
+     */
+    role?: string;
     /** ISO time it is due. */
     dueAt?: string;
     /** A hub path the task points at, e.g. /contacts/people/... */
     linkPath?: string;
+    /**
+     * Something that can't wait: a hot lead, a fault, a staff alert. It goes to the person's linked
+     * chats straight away, past their daily limit, and in their quiet hours only to the chat they chose
+     * to be woken in (or not until morning, if they chose none). At most five a day per person; urgent
+     * wears off a day after it is given. Leave it out for anything else.
+     */
+    urgent?: boolean;
+}
+/** What `db.tasks.give()` answers. */
+export interface GivenTask {
+    key: string;
+    id: number;
+    /** Who has it now: null only for a role's task still waiting for someone in the role to take it. */
+    holder: TaskPerson | null;
+    /** Whether the person it went to was emailed (the role's responsible person, for a role's task). */
+    emailed: boolean;
+    urgent: boolean;
+    /** Set when it was given to a role: `queued` while it waits in the role, false when the role had nobody and it went to the owner. */
+    role?: {
+        slug: string;
+        title: string;
+        queued: boolean;
+    };
+    note?: string;
 }
 /** A file or folder in the account's Files (the folders on its automation account: public/, private/, temp/). */
 export interface FileEntry {
@@ -555,6 +626,11 @@ export interface AwesomateErrorDetails {
      * unavailable when the hub said (serverCode crm_maintenance: the account's Contacts is being moved).
      */
     retryAfter?: number;
+    /** With unknown_role (giving a task to a role not on the business map): the map's roles, by key and name. */
+    roles?: Array<{
+        slug: string;
+        title: string;
+    }>;
 }
 /**
  * Every failure from the hub. `message` is for you, the developer; `personMessage`, when the hub
@@ -592,6 +668,11 @@ export declare class AwesomateError extends Error {
      * being moved). Wait at least that long, then try once more; retrying at once only meets the same answer.
      */
     readonly retryAfter?: number;
+    /** With serverCode unknown_role (`tasks.give({ role })` naming a role not on the business map): the map's roles, by key and name. */
+    readonly roles?: Array<{
+        slug: string;
+        title: string;
+    }>;
     constructor(
     /** Why it failed. */
     code: ErrorCode, message: string, 
@@ -722,6 +803,7 @@ export declare class AwesomateClient {
      *
      * @example
      * await db.tasks.give({ title: 'Call Sam back about the leak', forEmail: 'jo@brightwater.example', dueAt: '2026-10-06T09:00:00+11:00' });
+     * await db.tasks.give({ title: 'Hot lead: Sam wants a quote today', forEmail: 'jo@brightwater.example', urgent: true });
      */
     readonly tasks: {
         /** The board: waiting now, put off, with someone else, recently decided. `all` shows everyone's, not only yours. hosting:read. */
@@ -745,15 +827,27 @@ export declare class AwesomateClient {
         decisionRecord: (taskId: number | string) => Promise<TaskRecord & {
             kind: "decision";
         }>;
-        /** Give a task. The person gets it on their board, and an email when they are not the one giving it. hosting:manage. */
-        give: (task: GiveTask) => Promise<{
-            key: string;
-            id: number;
-            holder: TaskPerson;
-            emailed: boolean;
-        }>;
-        /** Change a given task: whoever wrote it, or the owner. hosting:manage. */
-        update: (id: number | string, patch: Partial<Omit<GiveTask, "forEmail">>) => Promise<void>;
+        /**
+         * Give a task. The person gets it on their board, an email when they are not the one giving it,
+         * and a card in any chat they linked, within their quiet hours and daily limit (`urgent` goes
+         * straight away). `urgent` in the result says whether it went as urgent: a person's sixth urgent
+         * task in a day goes as an ordinary one, and `note` says so. hosting:manage.
+         */
+        give: (task: GiveTask) => Promise<GivenTask>;
+        /**
+         * Change a given task: whoever wrote it, or the owner. `urgent: false` takes urgent off; a task can
+         * only be marked urgent when it is given. hosting:manage.
+         */
+        update: (id: number | string, patch: Partial<Omit<GiveTask, "forEmail" | "urgent">> & {
+            urgent?: false;
+        }) => Promise<void>;
+        /**
+         * Take a role's task (a card with `role.mayTake`): it becomes the owner's, and everyone else in
+         * the role sees who took it. Only someone in the role can take it, so this works for the owner
+         * only when they are in that role (serverCode `not_in_role` otherwise). Someone who got there
+         * first answers `taken`, with their name in the message. hosting:manage.
+         */
+        take: (id: number | string) => Promise<void>;
         /** Mark a given task done: the person who has it, whoever wrote it, or the owner. hosting:manage. */
         done: (id: number | string) => Promise<void>;
         /** Take a given task off the board without doing it: whoever wrote it, or the owner. hosting:manage. */
@@ -1022,6 +1116,27 @@ export declare class AwesomateClient {
         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>;
+        /**
+         * Record that the person asked to stop getting email, by reply, phone, in person or in writing
+         * (`how`), at the time they asked (`askedAt`, default now, at most 30 days back). With no `list`
+         * it stops every email, booking confirmations and other service emails included; with a list's
+         * key, that list only. Recorded as the person's own withdrawal, so a later import never puts
+         * them back. Answers `changed: false` when it was already recorded. The law gives 5 business
+         * days from when they asked. A person with no email address is refused (validation).
+         */
+        unsubscribe: (id: string, options: {
+            how: ContactStopHow;
+            list?: string;
+            askedAt?: Date | string;
+        }) => Promise<ContactUnsubscribeResult>;
+        /**
+         * Prepare an erasure, for when someone asks for their details to be deleted. Answers what
+         * erasing the person would take (`counts`) and `finishInHub`, the hub link where an Owner of the
+         * business finishes it, signed in as themselves, by typing the person's email address. Nothing
+         * is erased here: no token can erase anyone, because an erasure can't be undone. Only an Owner's
+         * token may prepare one (403 `owner_only`). Null when there is no such person.
+         */
+        erasurePreview: (id: string) => Promise<ContactErasurePreview | null>;
         /**
          * 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,
@@ -1151,6 +1266,18 @@ export declare class AwesomateClient {
     get<K extends KindName>(kind: K, id: string, options?: {
         tz?: string;
     }): Promise<RowOf<K> | null>;
+    /**
+     * What points at one row: for each link from another kind (a job's customer, a memo's job), how
+     * many rows point here and the newest of them (`limit`, default 20, at most 100), read as query()
+     * reads that kind. Null when there is no such row. The account's token, crm:read.
+     *
+     * @example
+     * const related = await db.related('contact', contactId);
+     * for (const r of related ?? []) console.log(r.kind, r.link, r.count);
+     */
+    related(kind: KindName, id: string, options?: {
+        limit?: number;
+    }): Promise<RelatedRows[] | null>;
     /** The app kinds this account has defined. The account's token, crm:read, every plan; never an app key. */
     kinds(): Promise<KindDescription[]>;
     /**
@@ -1210,6 +1337,18 @@ export declare class AwesomateClient {
     write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
     /** Archive a record: it leaves every read and is kept for a restore. Needs what write() needs. */
     archive<K extends KindName>(kind: K, id: string): Promise<void>;
+    /**
+     * Create or change the record that mirrors one in another system, found by that system's name and
+     * its id there (`ref.system`, lower case like `xero`; `ref.externalId`), so a sync run twice changes
+     * the record instead of making a second one. The same checks as write(). A record with that id that
+     * was archived is refused (`conflict`): a sync never undoes an archive or makes a second copy. Companies
+     * are refused here: use companies.upsert(), which matches by ABN and name. The account's token only
+     * (never an app key), crm:write, Support Plus and above.
+     *
+     * @example
+     * const { id, created } = await db.upsertByRef('job', { system: 'servicem8', externalId: 'JOB-0042' }, { title: 'Possum in the roof' }, { links: { customer: contactId } });
+     */
+    upsertByRef<K extends KindName>(kind: K, ref: RecordRef, data?: Partial<RowOf<K>> | Record<string, unknown>, options?: Omit<WriteOptions, 'id'>): Promise<UpsertByRefResult>;
     /** The saved queries on this account. crm:read, every plan: the account's token or an app key. */
     queries(): Promise<SavedQueryDescription[]>;
     /**
@@ -1266,6 +1405,26 @@ export declare class AwesomateClient {
      * the business map on the account.
      */
     businessMapRole(slug: string): Promise<BusinessMapRoleDetail>;
+    /**
+     * The business's KPIs: each a number with a target and someone responsible for it, with where it
+     * sits, who answers for it, its light against the target for the last complete period, the period
+     * so far, a trend of up to 12 periods and where its figure comes from. A person's own key reads only the KPIs
+     * they would see in the hub. `period` reads every KPI by the week, month or quarter (never finer than
+     * its own period); left out, each by its own. hosting:read, every plan; `available` is false, with a
+     * `reason`, where the account has no KPIs to read.
+     */
+    businessKpis(opts?: {
+        period?: 'week' | 'month' | 'quarter';
+    }): Promise<BusinessKpis>;
+    /**
+     * Add figures for the business's KPIs from your own tool or script: totals per day, week or month,
+     * into the business's own Your numbers, where a KPI reads them by name. Up to 100 a call; a figure
+     * sent again for the same period replaces the one before. Each figure name belongs to the first
+     * source that sends it (`serverCode: 'figure_owned'` for another). Totals only: a label that looks
+     * like an email address, phone number or web address is refused. knowledge:write, Support Plus and
+     * above (`feature_unavailable` below that), and Your numbers switched on for the business.
+     */
+    addFigures(input: AddFigures): Promise<FiguresAdded>;
     /**
      * The business map in its first shape, where a department is a `division`, a sub-department a
      * `department` and a role a `job`. hosting:read, the business map on the account.
@@ -1420,6 +1579,7 @@ export interface BusinessMapRole {
     headsDepartment: boolean;
     /** Runs its sub-department: the person responsible for it, and for its KPIs. */
     headsSubDepartment: boolean;
+    /** The sub-department's key (see BusinessMapSubDepartment.no): match it there for the name, never show it. */
     subDepartmentNo: number | null;
     reportsTo: {
         id: number;
@@ -1436,17 +1596,91 @@ export interface BusinessMapRole {
         level: BusinessMapLevel;
         exceptions: string | null;
     }>;
+    /**
+     * Its helpers. `look` says what the hub draws: an Awesomate agent's picture URL, a full link to the
+     * hub (null: the hub draws its initials; always null when the account does not have Agents) and
+     * whether it is on (null when that could not be read), an n8n agent's icon, an automation's bolt.
+     */
     helpers: Array<BusinessMapHelper & {
         id: number;
         supervisor: string;
         level: BusinessMapLevel | null;
         exceptions: string | null;
         minutesSavedPerRun: number | null;
+        look: {
+            kind: 'awesomate' | 'n8n' | 'automation' | 'external';
+            picture: string | null;
+            state: 'on' | 'off' | null;
+        };
     }>;
     /** The tag this role's procedures carry in 1Brain, such as 'job:quotes'. The map keeps no procedure text. */
     proceduresTag: string;
     /** Quarterly priorities on this role, every quarter. */
     priorities: BusinessMapPriority[];
+    /** Its responsibilities as processes, in the same order: what writes each down and who does it. */
+    processes: BusinessMapProcess[];
+    /** How many processes it has, how many are written down, how many automated. */
+    progress: {
+        processes: number;
+        written: number;
+        automated: number;
+    };
+    /** Ready to hand over: the owner is still responsible for it and every process is written down or automated. */
+    ready: boolean;
+    /** The one line the map shows for it ("Booking reminders failed twice this week"), or null. */
+    flag: string | null;
+}
+/** The one next step the map suggests, with its button's words and what the button does. */
+export interface BusinessMapNextStep {
+    title: string;
+    detail: string;
+    button: string;
+    action: {
+        kind: 'hand_over';
+        roleId: number;
+        roleSlug: string;
+        membershipId: number | null;
+    } | {
+        kind: 'open_role';
+        roleId: number;
+        roleSlug: string;
+    } | {
+        kind: 'link';
+        path: string;
+    } | {
+        kind: 'add_role';
+        departmentNo: number;
+    } | {
+        kind: 'edit_path';
+    } | {
+        kind: 'place_helpers';
+    };
+}
+/**
+ * One of a role's processes (a responsibility). Written down: a 1Brain page on the role's own list of
+ * 1Brain systems is linked to it. Automated: an agent or automation on the role does it, at any level.
+ */
+export interface BusinessMapProcess {
+    text: string;
+    level: BusinessMapLevel;
+    /** The 1Brain page that writes it down, by its ids and title; null when it is not written down yet. */
+    procedure: {
+        accountId: number;
+        itemId: number;
+        title: string;
+    } | null;
+    /** Who does it: the role's holder, or a helper on the role. */
+    doneBy: {
+        kind: 'holder';
+        name: string | null;
+    } | {
+        kind: 'helper';
+        helperId: number;
+        label: string;
+        helperKind: BusinessMapHelper['kind'];
+    };
+    /** How far whoever does it goes alone, in words: a helper's level, else the role's limits, else "A person". */
+    mayActAlone: string;
 }
 /** A quarterly priority on a role: one of the few things it must move this quarter. */
 export interface BusinessMapPriority {
@@ -1465,6 +1699,8 @@ export interface BusinessMapPathStep {
     position: number;
     label: string;
     departmentNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    /** The department's plain name ("Sales"): what people read. */
+    name: string;
     verb: string;
     /** The role that looks after the step, when the owner named one. */
     role: {
@@ -1480,11 +1716,25 @@ export interface BusinessMapPathStep {
     /** Where this step hands over to the next, in the owner's words. */
     handoffRule: string | null;
 }
-/** A sub-department and who runs it: the holder of the role that heads it, else whoever runs the department (byDefault). */
+/**
+ * A sub-department and who runs it: the holder of the role that heads it, else whoever runs the
+ * department (byDefault). Each business names, orders and adds its own, so they come in the
+ * business's order and by its names.
+ */
 export interface BusinessMapSubDepartment {
+    /**
+     * A key, never shown to people: 1 to 21 for a standard sub-department, 1001 and up for one the
+     * owner added. A role's subDepartmentNo is this key.
+     */
     no: number;
+    /** The business's name for it: show this. */
     name: string;
-    gloss: string;
+    /** The standard name, or null for one the owner added. Differs from name when the owner renamed it. */
+    standardName: string | null;
+    /** The owner added it. */
+    custom: boolean;
+    /** What a standard one covers; null for one the owner added. */
+    gloss: string | null;
     runBy: {
         name: string;
         byDefault: boolean;
@@ -1513,6 +1763,7 @@ export interface BusinessMapDepartment {
     helpers: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
+    /** In the business's order, by its names. */
     subDepartments: BusinessMapSubDepartment[];
     ideas: Array<{
         label: string;
@@ -1527,12 +1778,160 @@ export interface BusinessMapDepartment {
     question: string;
     /** 1Brain Departments whose procedures belong in this department. */
     oneBrainDepartments: string[];
-    /** People on the map who hold no role yet. They sit in Form (department 1) for display; empty for every other department. */
+    /** People on the map who hold no role yet. They sit in Team and systems (department 1) for display; empty for every other department. */
     noRoleYet: Array<{
         id: number;
         name: string;
     }>;
 }
+/**
+ * A KPI's light. Say its word beside any colour: Act now, Watch, On track, Late, Not a KPI yet.
+ * `not_due` is no light at all: the KPI is new and its first figure is not due yet, so it is never Late
+ * before then; `lightWord` says when ("First figure due Mon 19 Oct") and `firstDue` what brings it.
+ */
+export type KpiLight = 'act_now' | 'watch' | 'on_track' | 'late' | 'no_target' | 'not_due';
+/** One period of a KPI's figures: first and last day (YYYY-MM-DD), a short label, its figure and target. */
+export interface KpiPeriodFigure {
+    from: string;
+    to: string;
+    label: string;
+    /** null: no figure for that period. */
+    figure: number | null;
+    target: number | null;
+}
+/** One KPI, as businessKpis() returns it. */
+export interface BusinessKpi {
+    id: string;
+    /** The hub's own KPIs only: fixed when it is added. */
+    slug?: string;
+    name: string;
+    /** false: it points at a place the map no longer has. */
+    onMap: boolean;
+    place: {
+        level: 'department' | 'sub_department' | 'role' | null;
+        department: number | null;
+        subDepartment: number | null;
+        role: string | null;
+        roleTitle: string | null;
+    };
+    /** Who answers for it now; forNow: nobody holds it, so it falls to whoever runs the department. */
+    responsible: {
+        name: string;
+        forNow: boolean;
+    } | null;
+    light: KpiLight;
+    lightWord: string;
+    /** The judged period's figure and target (the last complete period). */
+    figure: number | null;
+    target: number | null;
+    period: {
+        from: string;
+        to: string;
+    } | null;
+    kind: 'lead' | 'result' | null;
+    critical: boolean;
+    format: string | null;
+    /** The rest is on the hub's own KPIs, not on those kept in Reports. */
+    frequency?: 'daily' | 'weekly' | 'monthly';
+    direction?: 'up' | 'down';
+    aggregation?: 'sum' | 'mean' | 'last';
+    /** The target per its own period, as typed: 40 for "40 a week". null: not a KPI yet. */
+    targetPerPeriod?: number | null;
+    targetWords?: string | null;
+    watchPct?: number;
+    source?: 'contacts' | 'collected' | 'entered' | 'other';
+    /** "Entered weekly by Dave, from a task". */
+    sourceLine?: string;
+    sharedEveryone?: boolean;
+    /** Why the reader sees it, in words. */
+    because?: string[];
+    /** The period so far: its figure and the target to date. Never lit. */
+    soFar?: {
+        period: {
+            start: string;
+            end: string;
+        };
+        value: number | null;
+        targetToDate: number | null;
+    };
+    /** Up to 12 complete periods before this one, oldest first, starting where tracking began: shorter, or empty, for a new KPI. */
+    trend?: KpiPeriodFigure[];
+    /** "No figure since 6 Oct", "No figure yet", or null. */
+    figureNote?: string | null;
+    /** Set when the light is Late: since when, and what it needs in a sentence. */
+    late?: {
+        since: string | null;
+        needs: string;
+        task: null;
+    } | null;
+    /** Before last period's figure is due: when it is due. */
+    dueNote?: string | null;
+    /**
+     * Set while the light is `not_due`: the day its first figure is due (YYYY-MM-DD), the words to show
+     * ("First figure due Mon 19 Oct"), and what brings the figure ("No figure yet. Dave enters it each week,
+     * from a task."). `arrived`: a figure for its first period is in already (entered before that period
+     * ended), so `day` is the day it lights up, `words` read "Lights up Mon 19 Oct" and `note` says so.
+     */
+    firstDue?: {
+        day: string;
+        words: string;
+        note: string;
+        arrived: boolean;
+    } | null;
+}
+/** One figure for addFigures(): a total for a period, under a named figure a KPI can read. */
+export interface Figure {
+    /** The named figure, two to four dotted parts in lower case: `xero.cash_received`. */
+    key: string;
+    /** Its name for people, when the key's last part does not say it well. */
+    label?: string;
+    unit: 'count' | 'money' | 'quantity';
+    /** With money: a three-letter code, `AUD`. */
+    currency?: string;
+    /** How periods combine into a longer one: `sum` (the default), `mean`, or `last` for a balance or a rating. */
+    aggregation?: 'sum' | 'mean' | 'last';
+    grain: 'day' | 'week' | 'month';
+    /** Any date in the period (`2026-10-08`), or an ISO time, read in the business's own time zone. Weeks start Monday. */
+    period: string;
+    value: number;
+}
+/** What addFigures() sends: where the figures come from, and the figures. */
+export interface AddFigures {
+    /** The tool or script the figures come from, in a few plain words: `Xero`. */
+    source: {
+        name: string;
+    };
+    figures: Figure[];
+}
+/** What addFigures() answers: how many were added, and the Your numbers tables they went to. */
+export interface FiguresAdded {
+    added: number;
+    source: {
+        name: string;
+        slug: string;
+    };
+    /** One table per source and grain, `collected-<source>-<grain>`. */
+    tables: Array<{
+        slug: string;
+        grain: 'day' | 'week' | 'month';
+        figures: number;
+        periods: number;
+    }>;
+}
+/** The business's KPIs, as businessKpis() returns them. */
+export type BusinessKpis = {
+    available: false;
+    reason: 'not_connected' | 'no_reports' | 'unreadable';
+} | {
+    available: true;
+    /** Where they are kept: the hub's own until the account links Reports, then Reports'. */
+    store: 'hub' | 'buddzee';
+    truncated: boolean;
+    period?: 'week' | 'month' | 'quarter' | null;
+    /** The hub's own: whether figures could be read from Your numbers. */
+    figures?: 'ok' | 'off' | 'no_workspace' | 'not_configured' | 'unreadable';
+    kpis: BusinessKpi[];
+};
 /** The business map, as businessMap() returns it. No email addresses. */
 export interface BusinessMap {
     version: 2;
@@ -1591,6 +1990,26 @@ export interface BusinessMap {
         departmentsWithHelpers: number;
         roles: number;
     };
+    /**
+     * How far the business has got: the roles the owner is still responsible for (their own included) of
+     * every role, and the processes written down and automated, each of every process.
+     */
+    progress: {
+        rolesYouHold: {
+            held: number;
+            of: number;
+        };
+        written: {
+            done: number;
+            of: number;
+        };
+        automated: {
+            done: number;
+            of: number;
+        };
+    };
+    /** The one next step: a ready role to hand over first, else the most important gap; null when there is none. */
+    nextStep: BusinessMapNextStep | null;
     /** Sources that could not be read just now: a missing helper may simply not have been read. */
     unavailable: string[];
 }
@@ -1653,7 +2072,12 @@ export interface BusinessMapRoleDetail {
         levelLabel: string;
         exceptions: string | null;
     }>;
+    /** Each responsibility as a process, in the same order. */
+    processes: BusinessMapProcess[];
+    progress: BusinessMapRole['progress'];
+    /** `id` is what a process's `doneBy.helperId` and a proposal's `doneByHelperId` name. */
     helpers: Array<{
+        id: number;
         kind: BusinessMapHelper['kind'];
         ref: string;
         label: string;
@@ -1662,6 +2086,7 @@ export interface BusinessMapRoleDetail {
         levelLabel: string | null;
         exceptions: string | null;
         instructionLine: string;
+        look: BusinessMapRole['helpers'][number]['look'];
     }>;
 }
 /**
@@ -1731,11 +2156,13 @@ export interface BusinessMapDivision {
     helpers: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
-    /** The sub-departments. */
+    /** The sub-departments, in the business's order: standardName and custom as on BusinessMapSubDepartment. */
     departments: Array<{
         no: number;
         name: string;
-        gloss: string;
+        standardName?: string | null;
+        custom?: boolean;
+        gloss: string | null;
         runBy: {
             name: string;
             byDefault: boolean;
@@ -1930,6 +2357,19 @@ export interface WriteOptions {
     /** Set a link by its key ('<id>'), or end it (null). */
     links?: Record<string, string | null>;
 }
+/** Which record in another system a record mirrors, for upsertByRef(). */
+export interface RecordRef {
+    /** That system's name, lower case: letters, digits, `_`, `.` or `-`, at most 40 characters (`xero`, `shopify`). */
+    system: string;
+    /** The record's id in that system, 1 to 200 characters. */
+    externalId: string;
+}
+/** What upsertByRef() did. */
+export interface UpsertByRefResult {
+    id: string;
+    /** True when the record was made; false when the one with that id changed. */
+    created: boolean;
+}
 /** The type of a saved query's or recipe's parameter. */
 export type ParamType = 'text' | 'number' | 'date' | 'datetime' | 'boolean' | 'uuid' | 'text_list' | 'number_list';
 /** One parameter of a saved query or recipe. */
@@ -2101,7 +2541,7 @@ export interface Schema {
         max_limit: number;
         statement_timeout_ms: number;
     };
-    /** With the account's token: the time zone dates are read in unless a query says otherwise. */
+    /** With the account's token: the time zone dates are read in unless a query says otherwise (the business's own, Sydney if none is set). */
     default_timezone?: string;
     /** With an app key: whether it can only read or can also write. */
     access?: 'read' | 'write';
@@ -2351,6 +2791,118 @@ export interface ContactTagsResult {
     /** Tags taken off them. */
     removed: number;
 }
+/** One link pointing at a row, from related(). */
+export interface RelatedRows {
+    /** The kind the link starts from. */
+    kind: string;
+    /** That kind's name as the owner wrote it, plural ("Jobs"): show this beside the label. */
+    kind_label: string;
+    /** The link's key on that kind (its rows carry <link>_id). A company's people come as kind contact, link company. */
+    link: string;
+    /** What the link is called from this side, as its maker named it ("has" when they did not). */
+    label: string;
+    /** True when this link could not be read just now: count and rows are empty, never zero. */
+    unavailable?: boolean;
+    /** Fields and sections of this kind your role cannot see, when any were left out. */
+    not_shown_to_you?: NotShownToYou;
+    /** How many rows point here, up to 10,000 (count_capped past it). */
+    count: number;
+    count_capped: boolean;
+    /** The newest of them, only columns query() would show. */
+    rows: Array<Record<string, unknown>>;
+    /** Pass to query() with where { <link>_id: id } and after, for more. */
+    next: string | null;
+}
+/** How a person asked to stop getting email, for contacts.unsubscribe(). */
+export type ContactStopHow = 'reply' | 'phone' | 'in_person' | 'in_writing' | 'other';
+/** What contacts.unsubscribe() recorded. */
+export interface ContactUnsubscribeResult {
+    id: string;
+    /** False when it was already recorded. */
+    changed: boolean;
+    /** Whether email reaches them now. */
+    email_status: ContactEmailStatus;
+    /** The list they left, or null for every email. */
+    list: string | null;
+    how: ContactStopHow;
+    /** When they asked, ISO 8601. */
+    asked_at: string;
+}
+/** What erasing a person would take, from contacts.erasurePreview(): counts only, never values. */
+export interface ContactErasureCounts {
+    /** Their email addresses and phone numbers. */
+    email_addresses: number;
+    phone_numbers: number;
+    /** Of their numbers, those someone else also holds: texts to them stop for that person too. */
+    phone_numbers_shared: number;
+    /** Details on their page with a value: name, company, phone, time zone and the owner's fields. */
+    fields: number;
+    tags: number;
+    /** Email lists they are on. */
+    lists: number;
+    /** Their consent records with an IP address or browser: the records stay as proof, those details go. */
+    consent_ip_details: number;
+    /** Emails sent to them, and their opens and clicks. */
+    emails_sent: number;
+    opens_and_clicks: number;
+    series_runs: number;
+    /** Calls with them, and calls from their numbers that named nobody (a shared line's among them). */
+    calls: number;
+    calls_shared_number: number;
+    /** What the agent remembered about them (0 or 1). */
+    call_memory: number;
+    /** Bookings: the answers they gave go, the times stay. */
+    bookings: number;
+    /** Support tickets that are theirs, and how each was found (a ticket can be found more than one way). */
+    tickets: number;
+    tickets_by_link: number;
+    tickets_by_email: number;
+    tickets_by_number: number;
+    /** Someone else's tickets that carry their address or number: only that comes off. */
+    tickets_of_someone_else: number;
+    /** Tickets from a number someone else also holds: left alone. */
+    tickets_shared_number: number;
+    /** Their tickets that someone else raised: that person's own address, number and name stay. */
+    tickets_customer_kept: number;
+    /** Messages they wrote, their attachments, emails from them held as suspect, and stored raw copies. */
+    messages: number;
+    /** Customers' messages on their tickets that are someone else's, or that can't be told to be theirs: they stay. */
+    messages_not_theirs: number;
+    attachments: number;
+    quarantined_emails: number;
+    raw_emails: number;
+    /** Stored emails also filed on someone else's record: kept for it. */
+    raw_emails_shared: number;
+    /** Other records linked to them, by kind; the links end and the records keep their own fields. */
+    linked_records: Array<{
+        kind: string;
+        label: string;
+        records: number;
+        required: number;
+    }>;
+    /** Of those, records that must have a person and will need a new one before their next change. */
+    linked_required: number;
+    /** Their sign-in to the account's apps, and sign-in links sent to them. */
+    app_sign_ins: number;
+    /** Other sign-in addresses linked to them, blocked with theirs. */
+    app_addresses_blocked: number;
+    sign_in_links: number;
+    /** Their rows in past imports. */
+    import_rows: number;
+}
+/** What contacts.erasurePreview() answers. Nothing has been erased. */
+export interface ContactErasurePreview {
+    /** The person's id, and whether they were removed from Contacts. Never their name or address: the Owner sees who it is in the hub. */
+    contact: {
+        id: string;
+        removed: boolean;
+    };
+    counts: ContactErasureCounts;
+    /** Where an Owner finishes it in the hub, signed in as themselves. Null when it can't be finished there on this account yet: pass on `note`. */
+    finishInHub: string | null;
+    /** What happens next, in a sentence to pass on. */
+    note: string;
+}
 /** 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. */

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.34.0';
+export const VERSION = '0.51.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;
@@ -62,6 +62,8 @@ export class AwesomateError extends Error {
      * being moved). Wait at least that long, then try once more; retrying at once only meets the same answer.
      */
     retryAfter;
+    /** With serverCode unknown_role (`tasks.give({ role })` naming a role not on the business map): the map's roles, by key and name. */
+    roles;
     constructor(
     /** Why it failed. */
     code, message, 
@@ -94,6 +96,8 @@ export class AwesomateError extends Error {
             this.requiredPlan = details.requiredPlan;
         if (details.retryAfter !== undefined)
             this.retryAfter = details.retryAfter;
+        if (details.roles !== undefined)
+            this.roles = details.roles;
     }
 }
 /** Every code the hub uses for "the account has switched this off in its privacy settings". */
@@ -153,6 +157,12 @@ function refusal(status, json) {
         ?? (Array.isArray(json.requiredPlans) ? nonEmpty(json.requiredPlans[0]) : undefined);
     if (required)
         details.requiredPlan = required;
+    if (Array.isArray(json.roles)) {
+        details.roles = json.roles
+            .filter((r) => Boolean(r) && typeof r === 'object')
+            .map((r) => ({ slug: String(r.slug ?? ''), title: String(r.title ?? '') }))
+            .filter((r) => r.slug !== '');
+    }
     return {
         code: errorCode(status, serverCode, json),
         message: (codeInError ? sentence : error ?? sentence) ?? `The hub answered ${status}.`,
@@ -414,6 +424,7 @@ export class AwesomateClient {
      *
      * @example
      * await db.tasks.give({ title: 'Call Sam back about the leak', forEmail: 'jo@brightwater.example', dueAt: '2026-10-06T09:00:00+11:00' });
+     * await db.tasks.give({ title: 'Hot lead: Sam wants a quote today', forEmail: 'jo@brightwater.example', urgent: true });
      */
     tasks = {
         /** The board: waiting now, put off, with someone else, recently decided. `all` shows everyone's, not only yours. hosting:read. */
@@ -431,15 +442,32 @@ export class AwesomateClient {
          * token may not see reads as not found (serverCode `gone`). hosting:read.
          */
         decisionRecord: (taskId) => this.tasksCall('GET', `/api/my-tasks/decisions/${encodeURIComponent(String(taskId))}/record`),
-        /** Give a task. The person gets it on their board, and an email when they are not the one giving it. hosting:manage. */
+        /**
+         * Give a task. The person gets it on their board, an email when they are not the one giving it,
+         * and a card in any chat they linked, within their quiet hours and daily limit (`urgent` goes
+         * straight away). `urgent` in the result says whether it went as urgent: a person's sixth urgent
+         * task in a day goes as an ordinary one, and `note` says so. hosting:manage.
+         */
         give: async (task) => {
             const r = await this.tasksCall('POST', '/api/my-tasks/tasks', task);
-            return { key: r.key, id: r.id, holder: r.holder, emailed: r.emailed };
+            return { key: r.key, id: r.id, holder: r.holder, emailed: r.emailed, urgent: r.urgent === true, ...(r.role ? { role: r.role } : {}), ...(r.note ? { note: r.note } : {}) };
         },
-        /** Change a given task: whoever wrote it, or the owner. hosting:manage. */
+        /**
+         * Change a given task: whoever wrote it, or the owner. `urgent: false` takes urgent off; a task can
+         * only be marked urgent when it is given. hosting:manage.
+         */
         update: async (id, patch) => {
             await this.tasksCall('PATCH', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}`, patch);
         },
+        /**
+         * Take a role's task (a card with `role.mayTake`): it becomes the owner's, and everyone else in
+         * the role sees who took it. Only someone in the role can take it, so this works for the owner
+         * only when they are in that role (serverCode `not_in_role` otherwise). Someone who got there
+         * first answers `taken`, with their name in the message. hosting:manage.
+         */
+        take: async (id) => {
+            await this.tasksCall('POST', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/take`);
+        },
         /** Mark a given task done: the person who has it, whoever wrote it, or the owner. hosting:manage. */
         done: async (id) => {
             await this.tasksCall('POST', `/api/my-tasks/tasks/${encodeURIComponent(String(id))}/done`);
@@ -786,6 +814,37 @@ export class AwesomateClient {
         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 }),
+        /**
+         * Record that the person asked to stop getting email, by reply, phone, in person or in writing
+         * (`how`), at the time they asked (`askedAt`, default now, at most 30 days back). With no `list`
+         * it stops every email, booking confirmations and other service emails included; with a list's
+         * key, that list only. Recorded as the person's own withdrawal, so a later import never puts
+         * them back. Answers `changed: false` when it was already recorded. The law gives 5 business
+         * days from when they asked. A person with no email address is refused (validation).
+         */
+        unsubscribe: async (id, options) => {
+            const askedAt = options.askedAt instanceof Date ? options.askedAt.toISOString() : options.askedAt;
+            return this.contactsWrite('POST', `/${contactIdOf(id)}/unsubscribe`, {
+                how: options.how, ...(options.list !== undefined ? { list: options.list } : {}), ...(askedAt !== undefined ? { asked_at: askedAt } : {}),
+            });
+        },
+        /**
+         * Prepare an erasure, for when someone asks for their details to be deleted. Answers what
+         * erasing the person would take (`counts`) and `finishInHub`, the hub link where an Owner of the
+         * business finishes it, signed in as themselves, by typing the person's email address. Nothing
+         * is erased here: no token can erase anyone, because an erasure can't be undone. Only an Owner's
+         * token may prepare one (403 `owner_only`). Null when there is no such person.
+         */
+        erasurePreview: async (id) => {
+            if (this.appKey)
+                throw contactsNeedAccount();
+            if (!RECORD_ID.test(String(id)))
+                return null;
+            const r = await nullIfMissing(this.request('GET', `/api/my-crm/v1/contacts/${encodeURIComponent(String(id))}/erasure`));
+            if (!r)
+                return null;
+            return { contact: r.contact, counts: r.counts, finishInHub: r.finish_in_hub, note: r.note };
+        },
         /**
          * 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,
@@ -1010,6 +1069,22 @@ export class AwesomateClient {
             throw err;
         }
     }
+    /**
+     * What points at one row: for each link from another kind (a job's customer, a memo's job), how
+     * many rows point here and the newest of them (`limit`, default 20, at most 100), read as query()
+     * reads that kind. Null when there is no such row. The account's token, crm:read.
+     *
+     * @example
+     * const related = await db.related('contact', contactId);
+     * for (const r of related ?? []) console.log(r.kind, r.link, r.count);
+     */
+    async related(kind, id, options = {}) {
+        if (!RECORD_ID.test(String(id)))
+            return null;
+        const qs = options.limit ? `?limit=${options.limit}` : '';
+        const r = await nullIfMissing(this.request('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(String(id))}/related${qs}`));
+        return r ? r.related : null;
+    }
     /** The app kinds this account has defined. The account's token, crm:read, every plan; never an app key. */
     async kinds() {
         return (await this.request('GET', '/api/my-crm/v1/kinds')).kinds;
@@ -1087,6 +1162,25 @@ export class AwesomateClient {
     async archive(kind, id) {
         await this.request('POST', '/api/my-crm/v1/call', { fn: 'archive_record', args: { kind, id } }, false);
     }
+    /**
+     * Create or change the record that mirrors one in another system, found by that system's name and
+     * its id there (`ref.system`, lower case like `xero`; `ref.externalId`), so a sync run twice changes
+     * the record instead of making a second one. The same checks as write(). A record with that id that
+     * was archived is refused (`conflict`): a sync never undoes an archive or makes a second copy. Companies
+     * are refused here: use companies.upsert(), which matches by ABN and name. The account's token only
+     * (never an app key), crm:write, Support Plus and above.
+     *
+     * @example
+     * const { id, created } = await db.upsertByRef('job', { system: 'servicem8', externalId: 'JOB-0042' }, { title: 'Possum in the roof' }, { links: { customer: contactId } });
+     */
+    async upsertByRef(kind, ref, data = {}, options = {}) {
+        if (this.appKey)
+            throw new AwesomateError('forbidden', "upsertByRef needs the account's token (amt_pat_...). An app key writes records with write().", 0);
+        const r = await this.request('POST', `/api/my-crm/v1/records/${encodeURIComponent(kind)}/by-ref`, {
+            system: ref.system, external_id: ref.externalId, data, links: options.links ?? {},
+        }, false);
+        return r.result;
+    }
     /** The saved queries on this account. crm:read, every plan: the account's token or an app key. */
     async queries() {
         return (await this.request('GET', '/api/my-crm/v1/queries')).queries;
@@ -1164,6 +1258,29 @@ export class AwesomateClient {
     async businessMapRole(slug) {
         return (await this.request('GET', `/api/my-business/v2/map/roles/${encodeURIComponent(slug)}`)).role;
     }
+    /**
+     * The business's KPIs: each a number with a target and someone responsible for it, with where it
+     * sits, who answers for it, its light against the target for the last complete period, the period
+     * so far, a trend of up to 12 periods and where its figure comes from. A person's own key reads only the KPIs
+     * they would see in the hub. `period` reads every KPI by the week, month or quarter (never finer than
+     * its own period); left out, each by its own. hosting:read, every plan; `available` is false, with a
+     * `reason`, where the account has no KPIs to read.
+     */
+    async businessKpis(opts = {}) {
+        return this.request('GET', `/api/my-business/v2/map/kpis${opts.period ? `?period=${opts.period}` : ''}`);
+    }
+    /**
+     * Add figures for the business's KPIs from your own tool or script: totals per day, week or month,
+     * into the business's own Your numbers, where a KPI reads them by name. Up to 100 a call; a figure
+     * sent again for the same period replaces the one before. Each figure name belongs to the first
+     * source that sends it (`serverCode: 'figure_owned'` for another). Totals only: a label that looks
+     * like an email address, phone number or web address is refused. knowledge:write, Support Plus and
+     * above (`feature_unavailable` below that), and Your numbers switched on for the business.
+     */
+    async addFigures(input) {
+        const r = await this.request('POST', '/api/my-business/v2/figures', input);
+        return { added: r.added, source: r.source, tables: r.tables };
+    }
     /**
      * The business map in its first shape, where a department is a `division`, a sub-department a
      * `department` and a role a `job`. hosting:read, the business map on the account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.34.0",
+  "version": "0.51.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",