@awesomate/sdk 0.23.0 → 0.24.0

package/dist/index.d.ts

@@ -24,7 +24,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.23.0";
+export declare const VERSION = "0.24.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -516,12 +516,27 @@ export declare class AwesomateClient {
      */
     business(): Promise<BusinessIdentity>;
     /**
-     * The business map: the seven divisions every business has, the jobs in each and who holds them,
-     * which agents and automations help which job and how far each may go, and what is missing, most
-     * important first. Read only: the owner changes the map in the hub. Needs the account's token
-     * (hosting:read, every plan), never an app key, and the account must have the business map.
+     * The business map: the seven departments every business has, their sub-departments, the roles in
+     * each and who holds them, which agents and automations help which role and how far each may go,
+     * and what is missing, most important first. Read only: the owner changes the map in the hub.
+     * Needs the account's token (hosting:read, every plan), never an app key, and the account must
+     * have the business map. Since 0.24.0 in the words the owner sees; businessMapV1() is the old shape.
      */
     businessMap(): Promise<BusinessMap>;
+    /** Every role on the map, one line each: slug, title, department and who holds it. */
+    businessMapRoles(): Promise<BusinessMapRoleSummary[]>;
+    /**
+     * One role by its slug, with the line each helper's instructions carry (`helpers[].instructionLine`):
+     * which role it helps, for whom, how far it may go and where its procedures are.
+     */
+    businessMapRole(slug: string): Promise<BusinessMapRoleDetail>;
+    /**
+     * The business map in its first shape, where a department is a `division`, a sub-department a
+     * `department` and a role a `job`.
+     * @deprecated Use businessMap(), which uses the words the owner sees. v1 is removed once it has
+     * gone 30 days unused, and not before 2026-11-06.
+     */
+    businessMapV1(): Promise<BusinessMapV1>;
     /** Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. */
     businessSuggestions(): Promise<BusinessSuggestion[]>;
     /** Grouped numbers (counts, sums) in the Business Data API's shape. */
@@ -592,20 +607,20 @@ export interface BusinessMapHelper {
     ref: string;
     label: string;
 }
-/** A job on the map. `slug` is its stable name for routing work: "whoever holds quotes". */
-export interface BusinessMapJob {
+/** A role on the map. `slug` is its stable name for routing work: "whoever holds quotes". */
+export interface BusinessMapRole {
     id: number;
     slug: string;
     title: string;
     mission: string | null;
     /** active: someone holds it. open: nobody does. hire_next: the owner's next hire. */
     state: 'active' | 'open' | 'hire_next';
-    isOwnerJob: boolean;
-    /** Runs its division: the division manager, above its departments, so departmentNo is null (the owner's job excepted). */
-    headsDivision: boolean;
-    /** Runs its department: the person responsible for it, and for its department-level KPIs. */
+    isOwnerRole: boolean;
+    /** Runs its department: above its sub-departments, so subDepartmentNo is null (the owner's role excepted). */
     headsDepartment: boolean;
-    departmentNo: number | null;
+    /** Runs its sub-department: the person responsible for it, and for its KPIs. */
+    headsSubDepartment: boolean;
+    subDepartmentNo: number | null;
     reportsTo: {
         id: number;
         title: string;
@@ -628,12 +643,12 @@ export interface BusinessMapJob {
         exceptions: string | null;
         minutesSavedPerRun: number | null;
     }>;
-    /** The tag this job's procedures carry in 1Brain, such as 'job:quotes'. The map keeps no procedure text. */
+    /** 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 hat, every quarter. */
+    /** Quarterly priorities on this role, every quarter. */
     priorities: BusinessMapPriority[];
 }
-/** A quarterly priority on a hat: one of the few things it must move this quarter. */
+/** A quarterly priority on a role: one of the few things it must move this quarter. */
 export interface BusinessMapPriority {
     id: number;
     /** '2026-Q4'. */
@@ -649,15 +664,15 @@ export interface BusinessMapPriority {
 export interface BusinessMapPathStep {
     position: number;
     label: string;
-    divisionNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    departmentNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
     verb: string;
-    /** The job that looks after the step, when the owner named one. */
-    job: {
+    /** The role that looks after the step, when the owner named one. */
+    role: {
         id: number;
         slug: string;
         title: string;
     } | null;
-    /** Who looks after it: the job's holder, else whoever runs the division (byDefault). */
+    /** Who looks after it: the role's holder, else whoever runs the department (byDefault). */
     owner: {
         name: string;
         byDefault: boolean;
@@ -665,8 +680,23 @@ export interface BusinessMapPathStep {
     /** Where this step hands over to the next, in the owner's words. */
     handoffRule: string | null;
 }
-/** One of the seven divisions, in board order (7 first). */
-export interface BusinessMapDivision {
+/** A sub-department and who runs it: the holder of the role that heads it, else whoever runs the department (byDefault). */
+export interface BusinessMapSubDepartment {
+    no: number;
+    name: string;
+    gloss: string;
+    runBy: {
+        name: string;
+        byDefault: boolean;
+    };
+    headRole: {
+        id: number;
+        slug: string;
+        title: string;
+    } | null;
+}
+/** One of the seven departments, in board order (7 first). */
+export interface BusinessMapDepartment {
     no: 1 | 2 | 3 | 4 | 5 | 6 | 7;
     /** Envision, Form, Promise, Balance, Fulfil, Refine, Share. */
     verb: string;
@@ -678,12 +708,230 @@ export interface BusinessMapDivision {
         name: string;
         byDefault: boolean;
     };
+    roles: BusinessMapRole[];
+    /** Helping here but not yet put on a role, with how they were placed, in words. */
+    helpers: Array<BusinessMapHelper & {
+        placedBy: string;
+    }>;
+    subDepartments: BusinessMapSubDepartment[];
+    ideas: Array<{
+        label: string;
+        what: string;
+        status: 'live' | 'library' | 'coming' | 'building' | 'planned';
+        path?: string;
+    }>;
+    numbers: Array<{
+        label: string;
+        kind: 'lead' | 'result';
+    }>;
+    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. */
+    noRoleYet: Array<{
+        id: number;
+        name: string;
+    }>;
+}
+/** The business map, as businessMap() returns it. No email addresses. */
+export interface BusinessMap {
+    version: 2;
+    business: {
+        name: string | null;
+        ownerName: string;
+    };
+    /** false: the owner has not started the map, so it is worked out from what the account runs. */
+    stored: boolean;
+    /** access: what the person may do in the hub (owner, full or view). */
+    people: Array<{
+        id: number | null;
+        name: string;
+        kind: 'owner' | 'staff' | 'contractor' | 'adviser' | null;
+        access: 'owner' | 'full' | 'view' | null;
+        location: string | null;
+        fromTeamAccess: boolean;
+    }>;
+    departments: BusinessMapDepartment[];
+    /** Helpers we could not place on a department. */
+    unplaced: Array<BusinessMapHelper & {
+        placedBy: string;
+    }>;
+    /** How a customer moves through the business. stored false: suggested for its kind of business, not set by the owner yet. */
+    path: {
+        stored: boolean;
+        template: {
+            key: string;
+            label: string;
+        } | null;
+        steps: BusinessMapPathStep[];
+    };
+    /** This quarter, '2026-Q4' (UTC): the one the map shows priorities for. */
+    quarter: string;
+    /** What is missing, most important first. */
+    gaps: Array<{
+        kind: 'procedure_first' | 'no_helper' | 'role_open' | 'path_missing' | 'path_unowned' | 'owner_everywhere' | 'unplaced';
+        department: number | null;
+        title: string;
+        detail: string;
+        action: {
+            label: string;
+            path: string;
+        } | null;
+    }>;
+    /** oneBrainCategory: the 1Brain category this business is, once linked. */
+    settings: {
+        adviser: string | null;
+        runsWeek: string | null;
+        oneBrainCategory: string | null;
+    };
+    counts: {
+        people: number;
+        helpers: number;
+        placed: number;
+        departmentsWithHelpers: number;
+        roles: number;
+    };
+    /** Sources that could not be read just now: a missing helper may simply not have been read. */
+    unavailable: string[];
+}
+/** One role in businessMapRoles(). */
+export interface BusinessMapRoleSummary {
+    slug: string;
+    title: string;
+    state: BusinessMapRole['state'];
+    department: {
+        no: number;
+        verb: string;
+        name: string;
+    };
+    /** The accountable holder, else the first; null when nobody holds it. */
+    holder: string | null;
+}
+/** One role, as businessMapRole() returns it. */
+export interface BusinessMapRoleDetail {
+    slug: string;
+    title: string;
+    mission: string | null;
+    state: BusinessMapRole['state'];
+    department: {
+        no: number;
+        verb: string;
+        name: string;
+    };
+    headsDepartment: boolean;
+    headsSubDepartment: boolean;
+    reportsTo: {
+        title: string;
+        slug: string | null;
+    } | null;
+    holder: string | null;
+    procedures: {
+        where: '1Brain';
+        tag: string;
+    };
+    /** This quarter's and next quarter's. */
+    priorities: Array<{
+        quarter: string;
+        title: string;
+        status: BusinessMapPriority['status'];
+        owner: string | null;
+        dueOn: string | null;
+    }>;
+    pathSteps: Array<{
+        position: number;
+        label: string;
+        handoffRule: string | null;
+    }>;
+    holders: Array<{
+        name: string;
+        accountable: boolean;
+        timeSharePct: number | null;
+    }>;
+    responsibilities: Array<{
+        text: string;
+        level: BusinessMapLevel;
+        levelLabel: string;
+        exceptions: string | null;
+    }>;
+    helpers: Array<{
+        kind: BusinessMapHelper['kind'];
+        ref: string;
+        label: string;
+        supervisor: string;
+        level: BusinessMapLevel | null;
+        levelLabel: string | null;
+        exceptions: string | null;
+        instructionLine: string;
+    }>;
+}
+/**
+ * A job on the v1 map (a role).
+ * @deprecated v1 shape, from businessMapV1(). Use BusinessMapRole.
+ */
+export interface BusinessMapJob {
+    id: number;
+    slug: string;
+    title: string;
+    mission: string | null;
+    state: 'active' | 'open' | 'hire_next';
+    isOwnerJob: boolean;
+    /** Runs its division (a department). */
+    headsDivision: boolean;
+    /** Runs its department (a sub-department). */
+    headsDepartment: boolean;
+    /** The sub-department. */
+    departmentNo: number | null;
+    reportsTo: {
+        id: number;
+        title: string;
+    } | null;
+    holders: BusinessMapRole['holders'];
+    responsibilities: BusinessMapRole['responsibilities'];
+    helpers: BusinessMapRole['helpers'];
+    proceduresTag: string;
+    priorities: BusinessMapPriority[];
+}
+/**
+ * One step of the customer's path on the v1 map.
+ * @deprecated v1 shape, from businessMapV1(). Use BusinessMapPathStep.
+ */
+export interface BusinessMapPathStepV1 {
+    position: number;
+    label: string;
+    /** The department. */
+    divisionNo: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    verb: string;
+    /** The role. */
+    job: {
+        id: number;
+        slug: string;
+        title: string;
+    } | null;
+    owner: {
+        name: string;
+        byDefault: boolean;
+    };
+    handoffRule: string | null;
+}
+/**
+ * A division on the v1 map (a department).
+ * @deprecated v1 shape, from businessMapV1(). Use BusinessMapDepartment.
+ */
+export interface BusinessMapDivision {
+    no: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+    verb: string;
+    name: string;
+    purpose: string;
+    stage: 'survive' | 'grow' | 'scale';
+    runBy: {
+        name: string;
+        byDefault: boolean;
+    };
     jobs: BusinessMapJob[];
-    /** Helping here but not yet put on a job, with how they were placed, in words. */
     helpers: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
-    /** Each department and who runs it: the holder of the job that heads it, else whoever runs the division (byDefault). */
+    /** The sub-departments. */
     departments: Array<{
         no: number;
         name: string;
@@ -698,33 +946,26 @@ export interface BusinessMapDivision {
             title: string;
         } | null;
     }>;
-    ideas: Array<{
-        label: string;
-        what: string;
-        status: 'live' | 'library' | 'coming' | 'building' | 'planned';
-        path?: string;
-    }>;
-    numbers: Array<{
-        label: string;
-        kind: 'lead' | 'result';
-    }>;
+    ideas: BusinessMapDepartment['ideas'];
+    numbers: BusinessMapDepartment['numbers'];
     question: string;
-    /** 1Brain departments whose procedures belong in this division. */
     oneBrainDepartments: string[];
-    /** People on the map who wear no hat yet. They sit in Form (division 1) for display; empty for every other division. */
     noHatYet: Array<{
         id: number;
         name: string;
     }>;
 }
-/** The business map, as businessMap() returns it. No email addresses. */
-export interface BusinessMap {
+/**
+ * The business map in its first shape, as businessMapV1() returns it.
+ * @deprecated Use BusinessMap, from businessMap().
+ */
+export interface BusinessMapV1 {
     business: {
         name: string | null;
         ownerName: string;
     };
-    /** false: the owner has not started the map, so it is worked out from what the account runs. */
     stored: boolean;
+    /** role: the person's access. */
     people: Array<{
         id: number | null;
         name: string;
@@ -734,22 +975,18 @@ export interface BusinessMap {
         fromTeamAccess: boolean;
     }>;
     divisions: BusinessMapDivision[];
-    /** Helpers we could not place on a division. */
     unplaced: Array<BusinessMapHelper & {
         placedBy: string;
     }>;
-    /** How a customer moves through the business. stored false: suggested for its kind of business, not set by the owner yet. */
     path: {
         stored: boolean;
         template: {
             key: string;
             label: string;
         } | null;
-        steps: BusinessMapPathStep[];
+        steps: BusinessMapPathStepV1[];
     };
-    /** This quarter, '2026-Q4' (UTC): the one the map shows priorities for. */
     quarter: string;
-    /** What is missing, most important first. */
     gaps: Array<{
         kind: 'procedure_first' | 'no_helper' | 'job_open' | 'path_missing' | 'path_unowned' | 'owner_everywhere' | 'unplaced';
         division: number | null;
@@ -763,6 +1000,7 @@ export interface BusinessMap {
     settings: {
         adviser: string | null;
         runsWeek: string | null;
+        oneBrainCategory: string | null;
     };
     counts: {
         people: number;
@@ -771,7 +1009,6 @@ export interface BusinessMap {
         divisionsWithHelpers: number;
         jobs: number;
     };
-    /** Sources that could not be read just now: a missing helper may simply not have been read. */
     unavailable: string[];
 }
 /** A detail waiting for the owner's yes. */

package/dist/index.js

@@ -24,7 +24,7 @@
  * Docs: https://hub.awesomate.ai/docs/sdk/
  */
 /** This package's version, sent to the hub with every server call. */
-export const VERSION = '0.23.0';
+export const VERSION = '0.24.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 /**
@@ -402,12 +402,33 @@ export class AwesomateClient {
         return this.request('GET', '/api/my-business/v1/identity?format=json');
     }
     /**
-     * The business map: the seven divisions every business has, the jobs in each and who holds them,
-     * which agents and automations help which job and how far each may go, and what is missing, most
-     * important first. Read only: the owner changes the map in the hub. Needs the account's token
-     * (hosting:read, every plan), never an app key, and the account must have the business map.
+     * The business map: the seven departments every business has, their sub-departments, the roles in
+     * each and who holds them, which agents and automations help which role and how far each may go,
+     * and what is missing, most important first. Read only: the owner changes the map in the hub.
+     * Needs the account's token (hosting:read, every plan), never an app key, and the account must
+     * have the business map. Since 0.24.0 in the words the owner sees; businessMapV1() is the old shape.
      */
     async businessMap() {
+        return (await this.request('GET', '/api/my-business/v2/map?format=json')).map;
+    }
+    /** Every role on the map, one line each: slug, title, department and who holds it. */
+    async businessMapRoles() {
+        return (await this.request('GET', '/api/my-business/v2/map/roles')).roles;
+    }
+    /**
+     * One role by its slug, with the line each helper's instructions carry (`helpers[].instructionLine`):
+     * which role it helps, for whom, how far it may go and where its procedures are.
+     */
+    async businessMapRole(slug) {
+        return (await this.request('GET', `/api/my-business/v2/map/roles/${encodeURIComponent(slug)}`)).role;
+    }
+    /**
+     * The business map in its first shape, where a department is a `division`, a sub-department a
+     * `department` and a role a `job`.
+     * @deprecated Use businessMap(), which uses the words the owner sees. v1 is removed once it has
+     * gone 30 days unused, and not before 2026-11-06.
+     */
+    async businessMapV1() {
         return (await this.request('GET', '/api/my-business/v1/map?format=json')).map;
     }
     /** Details waiting for the owner's yes on Your business: from the website, the account, a team member or a file. */

package/package.json

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