@awesomate/sdk 0.45.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.45.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 {
 }
@@ -496,11 +496,21 @@ 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/... */
@@ -513,6 +523,23 @@ export interface GiveTask {
      */
     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 {
     /** Relative to the files folder, starting with its top folder: public/images/logo.png. */
@@ -599,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
@@ -636,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, 
@@ -796,14 +833,7 @@ export declare class AwesomateClient {
          * 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;
-        }>;
+        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.
@@ -1099,6 +1129,14 @@ export declare class AwesomateClient {
             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,
@@ -1367,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.
@@ -1726,6 +1784,154 @@ export interface BusinessMapDepartment {
         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;
@@ -2622,6 +2828,81 @@ export interface ContactUnsubscribeResult {
     /** 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.45.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}.`,
@@ -440,7 +450,7 @@ export class AwesomateClient {
          */
         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, urgent: r.urgent === true, ...(r.note ? { note: r.note } : {}) };
+            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. `urgent: false` takes urgent off; a task can
@@ -818,6 +828,23 @@ export class AwesomateClient {
                 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,
@@ -1231,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.45.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",