@awesomate/sdk 0.81.2 → 0.81.4

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.81.2";
+export declare const VERSION = "0.81.4";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -1490,11 +1490,18 @@ export declare class AwesomateClient {
         topics: {
             /** Every topic, in the centre's order. */
             list: () => Promise<HelpTopic[]>;
-            /** Add a topic; its slug is made from the name unless given. */
+            /** Add a topic; its slug is made from the name unless given. `icon` is one of HELP_ICON_NAMES. */
             create: (input: {
                 name: string;
                 slug?: string;
                 description?: string | null;
+                icon?: HelpIconName | null;
+            }) => Promise<HelpTopic>;
+            /** Rename a topic, or change its description or icon (one of HELP_ICON_NAMES, or null for the default). Its slug is changed in the hub. */
+            update: (id: string, patch: {
+                name?: string;
+                description?: string | null;
+                icon?: HelpIconName | null;
             }) => Promise<HelpTopic>;
         };
         articles: {
@@ -4305,7 +4312,7 @@ export interface ContactFindResult {
     zone: string | null;
 }
 /** The groups contacts.activity() can keep, as its `types` option takes them. */
-export type ContactActivityGroup = 'contact' | 'lists' | 'forms' | 'events' | 'emails' | 'series' | 'bookings' | 'conversations';
+export type ContactActivityGroup = 'contact' | 'lists' | 'forms' | 'events' | 'emails' | 'series' | 'bookings' | 'conversations' | 'changes';
 /** One thing that happened with a person, from contacts.activity(). */
 export interface ContactActivityRow {
     /** What happened: contact_added, list_joined, tag_added, email, service_email, series_came_off, booking_completed, ticket, call and so on. */
@@ -5370,9 +5377,15 @@ export interface HelpTopic {
     name: string;
     slug: string;
     description: string | null;
+    /** Its icon's name, one of HELP_ICON_NAMES, or null for the default. */
+    icon: HelpIconName | null;
     position: number;
     updatedAt: string;
 }
+/** The icons a help topic may use, by name (the help pages draw each one inline). */
+export declare const HELP_ICON_NAMES: readonly ["rocket", "settings", "account", "billing", "receipt", "website", "email", "chat", "automation", "ai", "knowledge", "learn", "help", "security", "lock", "troubleshoot", "cloud", "data", "code", "phone", "calendar", "people", "marketing", "shop", "reports", "integrations", "document", "star"];
+/** One of HELP_ICON_NAMES. */
+export type HelpIconName = (typeof HELP_ICON_NAMES)[number];
 /** The help centre, from help.centre(). */
 export interface HelpCentreView {
     centre: {
@@ -5389,6 +5402,10 @@ export interface HelpCentreView {
     /** The audiences an article may name (`all`, or plans on Awesomate's own centre). */
     segments: string[];
     topics: HelpTopic[];
+    /** The public help API's address for this centre (createHelpClient). */
+    publicApi: string | null;
+    /** Whether the new design is on for this centre: the public help API answers only then. */
+    v2: boolean;
 }
 /** What creating or changing an article takes. */
 export interface HelpArticleInput {
@@ -6332,4 +6349,199 @@ export declare class AwesomateBookingsClient {
  * ```
  */
 export declare function createBookingsClient(options: BookingsClientOptions): AwesomateBookingsClient;
+/** Options for createHelpClient(). */
+export interface HelpClientOptions {
+    /** The help centre's handle (awesomate), or its own address once that is switched on (help.yourbusiness.com.au). */
+    centre: string;
+    /** Default https://hub.awesomate.ai. */
+    baseUrl?: string;
+    /** Your own fetch. Default: the global one. */
+    fetch?: typeof fetch;
+}
+/** A help centre's topic, from the public help API: only topics with something published in them. */
+export interface PublicHelpTopic {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    icon: HelpIconName | null;
+    /** The icon as inline SVG, drawn in `currentColor`: no third-party request. */
+    iconSvg: string;
+    articleCount: number;
+}
+/** A published article in a list, from the public help API. */
+export interface PublicHelpArticleSummary {
+    id: string;
+    slug: string;
+    title: string;
+    summary: string | null;
+    topicId: string | null;
+    updatedAt: string | null;
+    /** The article's page on the help centre. */
+    url: string;
+}
+/** One published article, from help.article(). */
+export interface PublicHelpArticle extends PublicHelpArticleSummary {
+    markdown: string;
+    /** The article as safe HTML: no scripts, only https images and the help pages' own players. */
+    html: string;
+    /** Its headings, for a contents list (`text` is already HTML-safe). */
+    headings: Array<{
+        depth: number;
+        id: string;
+        text: string;
+    }>;
+    firstPublishedAt: string | null;
+    topic: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+}
+/** The help centre, from help.centre(). */
+export interface PublicHelpCentre {
+    handle: string;
+    title: string;
+    /** Where its own pages are. */
+    url: string;
+    /** The business's website, for "Go to website". */
+    website: string | null;
+    privacyUrl: string | null;
+    brand: {
+        name: string;
+        logo: {
+            src: string;
+            alt: string;
+        } | null;
+        colours: Record<string, string>;
+        fontStack: string;
+    };
+    topics: PublicHelpTopic[];
+    /** What the centre offers: answers (ask), messages (contact) and, with messages, questions about the business's services. */
+    features: {
+        ask: boolean;
+        contact: boolean;
+        enquiries: boolean;
+    };
+}
+/** An answer from help.ask(). */
+export interface PublicHelpAnswer {
+    /** answered; none (the articles do not say); unavailable (try the articles, or later). An empty or too long question is refused with `validation`. */
+    status: 'answered' | 'none' | 'unavailable';
+    /** The answer as markdown, with [n] markers for its citations. Null unless answered. */
+    answer: string | null;
+    html: string | null;
+    citations: Array<{
+        n: number;
+        title: string;
+        url: string | null;
+    }>;
+    /** Carry it into help.contact.start({ attempt }) so the team sees this answer with the message. */
+    feedbackToken: string | null;
+}
+/** Where a message to the team is up to, from help.contact. */
+export type PublicHelpContactStep = {
+    step: 'form';
+    problems: Array<{
+        field: 'name' | 'email' | 'question' | 'kind';
+        message: string;
+    }>;
+    message?: string;
+    code?: string;
+} | {
+    step: 'code';
+    flow: string;
+    email: string;
+    message: string;
+    code?: string;
+} | {
+    step: 'done';
+    email: string;
+    deskAddress: string | null;
+};
+/**
+ * The help client, from createHelpClient(): a business's published help centre for pages it builds
+ * itself, for visitors who are not signed in. Reading needs no key and works from any website.
+ * Asking, rating and messages work only from the centre's own address and the websites its owner
+ * listed, in the visitor's browser: limits are per visitor address, so a server relaying for many
+ * people shares one allowance.
+ */
+export declare class AwesomateHelpClient {
+    private readonly base;
+    private readonly doFetch;
+    constructor(opts: HelpClientOptions);
+    private request;
+    /** The centre: its title, address, brand, website, topics and what it offers. */
+    centre(): Promise<PublicHelpCentre>;
+    /** Topics with something published in them, each with its icon and count. */
+    topics(): Promise<PublicHelpTopic[]>;
+    /** Published articles, 20 a page unless told otherwise (at most 50), optionally in one topic (by its slug). */
+    articles(options?: {
+        topic?: string;
+        page?: number;
+        perPage?: number;
+    }): Promise<{
+        articles: PublicHelpArticleSummary[];
+        page: number;
+        perPage: number;
+        total: number;
+    }>;
+    /** One published article with its HTML, markdown and headings, or null when there is none by that slug. */
+    article(slug: string): Promise<PublicHelpArticle | null>;
+    /** The six most read articles, the owner's pinned ones first. */
+    popular(): Promise<PublicHelpArticleSummary[]>;
+    /** Articles matching a search (spelling slips and close words included). The words are never kept. */
+    search(q: string): Promise<PublicHelpArticleSummary[]>;
+    /**
+     * The notice to show beside an ask box, and its token. Pass the token to ask() once you have shown
+     * the notice: only then can a question the articles do not answer reach the owner's Questions inbox.
+     */
+    askNotice(): Promise<{
+        notice: string | null;
+        noticeToken: string | null;
+    }>;
+    /**
+     * Ask the centre's assistant (one of the business's Knowledge answers; the same question again within
+     * a day costs nothing). From the centre's own address and the owner's listed websites only.
+     */
+    ask(question: string, options?: {
+        noticeToken?: string | null;
+    }): Promise<PublicHelpAnswer>;
+    /** "Was this helpful?" on an article. Counted once a day per visitor. */
+    helpful(slug: string, yes: boolean): Promise<void>;
+    /**
+     * A message to the business's team. start() checks the form and emails the visitor a 6-digit code;
+     * confirm() takes the code and sends the message, as a ticket with the assistant's answer beside it
+     * when `attempt` carried one. Problems and a wrong code come back as steps, not errors.
+     */
+    readonly contact: {
+        /** Check the form and send the code. `kind: 'enquiry'` only where features.enquiries is on. */
+        start: (input: {
+            name: string;
+            email: string;
+            question: string;
+            kind?: "help" | "enquiry";
+            attempt?: string | null;
+        }) => Promise<PublicHelpContactStep>;
+        /** The code from the email: the message is sent (`done`), or the code page again with why. */
+        confirm: (flow: string, code: string) => Promise<PublicHelpContactStep>;
+        /** Send a new code for the same message. */
+        resend: (flow: string) => Promise<PublicHelpContactStep>;
+    };
+}
+/**
+ * The client for help pages a business builds itself, for visitors who are not signed in. Reading
+ * works from anywhere with no key; asking, rating and messages from the centre's own address and the
+ * websites its owner lists. The help centre must have the new design on.
+ *
+ * @example
+ * ```ts
+ * import { createHelpClient } from '@awesomate/sdk';
+ *
+ * const help = createHelpClient({ centre: 'awesomate' });
+ * const { topics } = await help.centre();
+ * const found = await help.search('reset my password');
+ * ```
+ */
+export declare function createHelpClient(options: HelpClientOptions): AwesomateHelpClient;
 export {};

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.81.2';
+export const VERSION = '0.81.4';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 /** The one check for a platform `watch_url` (mirrored in the hub's awesomate-knowledge.ts and its MCP). */
 const WATCH_URL = /^https:\/\/[^\s"'<>]+$/i;
@@ -1128,13 +1128,15 @@ export class AwesomateClient {
         /** The centre, its public address, the segments an article may name, and its topics. */
         centre: async () => {
             const r = await this.helpRequest('GET', '/?articles=0');
-            return { centre: r.centre, publicUrl: r.publicUrl, segments: r.segments, topics: r.topics };
+            return { centre: r.centre, publicUrl: r.publicUrl, segments: r.segments, topics: r.topics, publicApi: r.publicApi ?? null, v2: r.v2 === true };
         },
         topics: {
             /** Every topic, in the centre's order. */
             list: async () => (await this.helpRequest('GET', '/?articles=0')).topics,
-            /** Add a topic; its slug is made from the name unless given. */
+            /** Add a topic; its slug is made from the name unless given. `icon` is one of HELP_ICON_NAMES. */
             create: async (input) => (await this.helpRequest('POST', '/topics', input)).topic,
+            /** Rename a topic, or change its description or icon (one of HELP_ICON_NAMES, or null for the default). Its slug is changed in the hub. */
+            update: async (id, patch) => (await this.helpRequest('PATCH', `/topics/${encodeURIComponent(String(id))}`, patch)).topic,
         },
         articles: {
             /** Articles without their bodies, optionally in one status or matching words in the title. */
@@ -2187,6 +2189,12 @@ function briefFromWire(r) {
     const { session_id, job_id, ...rest } = r;
     return { ...rest, ...(session_id ? { sessionId: session_id } : {}), ...(job_id ? { jobId: job_id } : {}) };
 }
+/** The icons a help topic may use, by name (the help pages draw each one inline). */
+export const HELP_ICON_NAMES = [
+    'rocket', 'settings', 'account', 'billing', 'receipt', 'website', 'email', 'chat', 'automation', 'ai', 'knowledge', 'learn', 'help',
+    'security', 'lock', 'troubleshoot', 'cloud', 'data', 'code', 'phone', 'calendar', 'people', 'marketing', 'shop', 'reports',
+    'integrations', 'document', 'star',
+];
 function memoryStorage() {
     const m = new Map();
     return { getItem: (k) => m.get(k) ?? null, setItem: (k, v) => { m.set(k, v); }, removeItem: (k) => { m.delete(k); } };
@@ -3441,3 +3449,131 @@ export class AwesomateBookingsClient {
 export function createBookingsClient(options) {
     return new AwesomateBookingsClient(options);
 }
+/**
+ * The help client, from createHelpClient(): a business's published help centre for pages it builds
+ * itself, for visitors who are not signed in. Reading needs no key and works from any website.
+ * Asking, rating and messages work only from the centre's own address and the websites its owner
+ * listed, in the visitor's browser: limits are per visitor address, so a server relaying for many
+ * people shares one allowance.
+ */
+export class AwesomateHelpClient {
+    base;
+    doFetch;
+    constructor(opts) {
+        const centre = String(opts?.centre ?? '').trim().toLowerCase();
+        if (!/^[a-z0-9][a-z0-9.-]{0,252}$/.test(centre))
+            throw new Error('createHelpClient needs the help centre\'s handle, or its own address (help.yourbusiness.com.au).');
+        this.base = `${(opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, '')}/api/public/help/v1/${encodeURIComponent(centre)}`;
+        const f = opts.fetch ?? globalThis.fetch?.bind(globalThis);
+        if (!f)
+            throw new Error('No fetch available.');
+        this.doFetch = f;
+    }
+    async request(method, path, body, steps = false) {
+        let res;
+        try {
+            res = await this.doFetch(`${this.base}${path}`, {
+                method,
+                headers: body === undefined ? {} : { 'content-type': 'application/json' },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            throw new AwesomateError('unavailable', `The hub could not be reached: ${err.message}`, 0);
+        }
+        const data = (await res.json().catch(() => ({})));
+        // A message's own steps (the form's problems, a wrong code) are answers, not failures.
+        if (!res.ok && !(steps && typeof data.step === 'string')) {
+            const err = hubError(res, data);
+            throw new AwesomateError(err.code, err.message, err.status, err.field, err.serverCode, err.message, err);
+        }
+        return data;
+    }
+    /** The centre: its title, address, brand, website, topics and what it offers. */
+    centre() {
+        return this.request('GET', '/centre');
+    }
+    /** Topics with something published in them, each with its icon and count. */
+    async topics() {
+        return (await this.request('GET', '/topics')).topics;
+    }
+    /** Published articles, 20 a page unless told otherwise (at most 50), optionally in one topic (by its slug). */
+    articles(options = {}) {
+        const q = new URLSearchParams();
+        if (options.topic)
+            q.set('topic', options.topic);
+        if (options.page)
+            q.set('page', String(options.page));
+        if (options.perPage)
+            q.set('per_page', String(options.perPage));
+        const qs = q.toString();
+        return this.request('GET', `/articles${qs ? `?${qs}` : ''}`);
+    }
+    /** One published article with its HTML, markdown and headings, or null when there is none by that slug. */
+    async article(slug) {
+        try {
+            return await this.request('GET', `/articles/${encodeURIComponent(slug)}`);
+        }
+        catch (err) {
+            if (err instanceof AwesomateError && err.code === 'not_found')
+                return null;
+            throw err;
+        }
+    }
+    /** The six most read articles, the owner's pinned ones first. */
+    async popular() {
+        return (await this.request('GET', '/popular')).articles;
+    }
+    /** Articles matching a search (spelling slips and close words included). The words are never kept. */
+    async search(q) {
+        return (await this.request('GET', `/search?q=${encodeURIComponent(q)}`)).articles;
+    }
+    /**
+     * The notice to show beside an ask box, and its token. Pass the token to ask() once you have shown
+     * the notice: only then can a question the articles do not answer reach the owner's Questions inbox.
+     */
+    askNotice() {
+        return this.request('GET', '/ask/notice');
+    }
+    /**
+     * Ask the centre's assistant (one of the business's Knowledge answers; the same question again within
+     * a day costs nothing). From the centre's own address and the owner's listed websites only.
+     */
+    ask(question, options = {}) {
+        return this.request('POST', '/ask', { question, ...(options.noticeToken ? { noticeToken: options.noticeToken } : {}) });
+    }
+    /** "Was this helpful?" on an article. Counted once a day per visitor. */
+    async helpful(slug, yes) {
+        await this.request('POST', `/articles/${encodeURIComponent(slug)}/helpful`, { answer: yes ? 'yes' : 'no' });
+    }
+    /**
+     * A message to the business's team. start() checks the form and emails the visitor a 6-digit code;
+     * confirm() takes the code and sends the message, as a ticket with the assistant's answer beside it
+     * when `attempt` carried one. Problems and a wrong code come back as steps, not errors.
+     */
+    contact = {
+        /** Check the form and send the code. `kind: 'enquiry'` only where features.enquiries is on. */
+        start: (input) => this.request('POST', '/contact/start', input, true),
+        /** The code from the email: the message is sent (`done`), or the code page again with why. */
+        confirm: (flow, code) => this.request('POST', '/contact/confirm', { flow, code }, true),
+        /** Send a new code for the same message. */
+        resend: (flow) => this.request('POST', '/contact/confirm', { flow, resend: true }, true),
+    };
+}
+/**
+ * The client for help pages a business builds itself, for visitors who are not signed in. Reading
+ * works from anywhere with no key; asking, rating and messages from the centre's own address and the
+ * websites its owner lists. The help centre must have the new design on.
+ *
+ * @example
+ * ```ts
+ * import { createHelpClient } from '@awesomate/sdk';
+ *
+ * const help = createHelpClient({ centre: 'awesomate' });
+ * const { topics } = await help.centre();
+ * const found = await help.search('reset my password');
+ * ```
+ */
+export function createHelpClient(options) {
+    return new AwesomateHelpClient(options);
+}

package/package.json

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