@awesomate/sdk 0.34.0 → 0.45.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.45.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. */
@@ -468,6 +505,13 @@ export interface GiveTask {
     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;
 }
 /** A file or folder in the account's Files (the folders on its automation account: public/, private/, temp/). */
 export interface FileEntry {
@@ -722,6 +766,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 +790,34 @@ 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 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<{
             key: string;
             id: number;
             holder: TaskPerson;
             emailed: boolean;
+            urgent: boolean;
+            note?: string;
         }>;
-        /** Change a given task: whoever wrote it, or the owner. hosting:manage. */
-        update: (id: number | string, patch: Partial<Omit<GiveTask, "forEmail">>) => Promise<void>;
+        /**
+         * 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 +1086,19 @@ 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>;
         /**
          * 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 +1228,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 +1299,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[]>;
     /**
@@ -1420,6 +1521,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 +1538,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 +1641,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 +1658,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 +1705,7 @@ export interface BusinessMapDepartment {
     helpers: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
+    /** In the business's order, by its names. */
     subDepartments: BusinessMapSubDepartment[];
     ideas: Array<{
         label: string;
@@ -1527,7 +1720,7 @@ 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;
@@ -1591,6 +1784,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 +1866,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 +1880,7 @@ export interface BusinessMapRoleDetail {
         levelLabel: string | null;
         exceptions: string | null;
         instructionLine: string;
+        look: BusinessMapRole['helpers'][number]['look'];
     }>;
 }
 /**
@@ -1731,11 +1950,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 +2151,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 +2335,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 +2585,43 @@ 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;
+}
 /** 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.45.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;
@@ -414,6 +414,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 +432,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.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 +804,20 @@ 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 } : {}),
+            });
+        },
         /**
          * 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 +1042,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 +1135,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;

package/package.json

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