@awesomate/sdk 0.77.1 → 0.79.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.77.1";
+export declare const VERSION = "0.79.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -574,6 +574,34 @@ export interface TrashEntry {
     /** When it was removed, or null when the trash name does not say. */
     deleted_at: string | null;
 }
+/** One move or copy in a list: where from, and where to (a folder ending in "/" keeps the name). */
+export interface FilePair {
+    from: string;
+    to: string;
+}
+/** Each item of a moveMany() or copyMany(), answered on its own. */
+export type FileBatchItem = {
+    from: string;
+    to: string;
+    ok: true;
+    entry: FileEntry;
+}
+/** partial: a copy stopped part way and left this behind; delete it before trying again. */
+ | {
+    from: string;
+    to: string;
+    ok: false;
+    error: string;
+    code: string;
+    partial?: string;
+};
+/** What moveMany() or copyMany() did: every item, how many went (moved or copied) and how many did not. */
+export interface FilesBatchResult {
+    results: FileBatchItem[];
+    moved?: number;
+    copied?: number;
+    failed: number;
+}
 /** How much of the plan's Files space is used. */
 export interface FilesUsage {
     used_bytes: number;
@@ -761,8 +789,22 @@ export declare class AwesomateClient {
         download: (path: string) => Promise<Blob>;
         /** Make a folder, and any above it. */
         mkdir: (path: string) => Promise<FileEntry>;
-        /** Move or rename. Anything using the old path or address needs the new one. */
+        /** Move or rename. A `to` ending in "/" is a folder to move it into, keeping its name. Anything using the old path or address needs the new one. */
         move: (from: string, to: string) => Promise<FileEntry>;
+        /** Move up to 100 at once. Each is answered on its own in `results`; one that fails does not stop the rest. */
+        moveMany: (items: FilePair[]) => Promise<FilesBatchResult>;
+        /**
+         * Copy a file or a folder, leaving the original. A `to` ending in "/" keeps the name. A file already at `to` is
+         * replaced only with `{ overwrite: true }`; a folder copy never writes into a folder that is there. One call copies
+         * at most 200 files and 250 MB, within the plan's Files space.
+         */
+        copy: (from: string, to: string, opts?: {
+            overwrite?: boolean;
+        }) => Promise<FileEntry>;
+        /** Copy up to 100 at once (200 files and 250 MB in all). Each is answered on its own in `results`. */
+        copyMany: (items: FilePair[], opts?: {
+            overwrite?: boolean;
+        }) => Promise<FilesBatchResult>;
         /** Move a file from private/ or temp/ to the same place under public/, and answer its public_url. Anyone with the address can open it. */
         makePublic: (path: string) => Promise<FileEntry>;
         /** Move a file out of public/ into private/. Its public address stops serving it within seconds (a browser that already opened it may keep its own copy for a while). */
@@ -1391,6 +1433,59 @@ export declare class AwesomateClient {
         /** Where the business's Stripe account stands, with one sentence (`next`) saying what happens next. */
         status: () => Promise<PaymentsStatus>;
     };
+    /**
+     * The account's own help centre: its topics and articles, written as drafts, published to the
+     * public help pages (shown while the centre's pages are on, and sent to the business's Knowledge
+     * where the centre feeds it), unpublished or archived. Needs the account's token with help:write, a permission no plan
+     * gives by itself: the account owner switches it on for one key in the hub (Claude Code, Get my
+     * code, "Write, publish and take down your help centre articles"). Never an app key, a team
+     * member's key or a chat connection. An account with no help centre answers not_found with
+     * serverCode `no_help_centre`.
+     *
+     * An article's working copy (title, summary, body) is what you change; the public sees its
+     * published copy, so an edit is not live until you publish again. Publishing is refused while
+     * the body still has a `[CHECK:` note in it. Bodies are Markdown.
+     *
+     * @example
+     * const { topics } = await db.help.centre();
+     * const article = await db.help.articles.create({ title: 'Connect Xero', body: 'Open Settings, then Integrations.', topicId: topics[0]?.id });
+     * await db.help.articles.publish(article.id);
+     */
+    readonly help: {
+        /** The centre, its public address, the segments an article may name, and its topics. */
+        centre: () => Promise<HelpCentreView>;
+        topics: {
+            /** Every topic, in the centre's order. */
+            list: () => Promise<HelpTopic[]>;
+            /** Add a topic; its slug is made from the name unless given. */
+            create: (input: {
+                name: string;
+                slug?: string;
+                description?: string | null;
+            }) => Promise<HelpTopic>;
+        };
+        articles: {
+            /** Articles without their bodies, optionally in one status or matching words in the title. */
+            list: (options?: {
+                status?: HelpArticleStatus;
+                q?: string;
+            }) => Promise<HelpArticleSummary[]>;
+            /** One article with its working and published copies, or null when there is none. */
+            get: (id: string) => Promise<HelpArticle | null>;
+            /** A new draft. Its slug is made from the title unless given; segments default to everyone. */
+            create: (input: HelpArticleInput) => Promise<HelpArticle>;
+            /** Change a draft's (or a published article's working) copy. Fields left out are left as they are. */
+            update: (id: string, patch: Partial<HelpArticleInput>) => Promise<HelpArticle>;
+            /** Make the working copy public (and send its page to Knowledge where the centre feeds it). */
+            publish: (id: string) => Promise<HelpArticle>;
+            /** Take it off the public pages; it stays as a draft. */
+            unpublish: (id: string) => Promise<HelpArticle>;
+            /** Archive it: off the public pages and out of Knowledge. Restoring is done in the hub. */
+            archive: (id: string) => Promise<HelpArticle>;
+        };
+    };
+    /** A help centre call: the account's own token only, and a change is never sent twice. */
+    private helpRequest;
     /**
      * The account's own support desk: the help inbox for its customers, under Contacts, Inbox in
      * the hub. Read only, on purpose: every message here was written by someone outside the
@@ -5128,6 +5223,90 @@ export interface CompanyUpsertResult {
     /** How it found the company it changed: by id, abn or name; null when it made one. */
     matched_by: 'id' | 'abn' | 'name' | null;
 }
+/** An article's status in a help centre. */
+export type HelpArticleStatus = 'draft' | 'published' | 'archived';
+/** A help centre's topic, from help.topics. */
+export interface HelpTopic {
+    id: string;
+    name: string;
+    slug: string;
+    description: string | null;
+    position: number;
+    updatedAt: string;
+}
+/** The help centre, from help.centre(). */
+export interface HelpCentreView {
+    centre: {
+        handle: string;
+        title: string;
+        /** Whether its public pages are on. */
+        status: 'off' | 'on';
+        /** Its own address (help.<domain>), when it has one. */
+        customHost: string | null;
+        hostStatus: 'none' | 'pending' | 'active' | 'problem';
+    };
+    /** Where its public pages are. */
+    publicUrl: string | null;
+    /** The audiences an article may name (`all`, or plans on Awesomate's own centre). */
+    segments: string[];
+    topics: HelpTopic[];
+}
+/** What creating or changing an article takes. */
+export interface HelpArticleInput {
+    title: string;
+    /** Made from the title when left out. Fixed once the article has been published. */
+    slug?: string;
+    summary?: string | null;
+    /** Markdown. A `[CHECK: ...]` note blocks publishing until it is gone. */
+    body?: string;
+    /** Who it is for: `['all']` (the default) or names from help.centre().segments. */
+    segments?: string[];
+    topicId?: string | null;
+}
+/** An article in a list, from help.articles.list(): no bodies. */
+export interface HelpArticleSummary {
+    id: string;
+    title: string;
+    slug: string;
+    summary: string | null;
+    status: HelpArticleStatus;
+    publishedTitle: string | null;
+    publishedAt: string | null;
+    firstPublishedAt: string | null;
+    segments: string[];
+    topicId: string | null;
+    /** Publishing would change what the public sees. */
+    changed: boolean;
+    /** Where its page stands in the business's Knowledge, when it has been sent there. */
+    knowledge: {
+        action: 'add' | 'remove';
+        status: 'pending' | 'sent' | 'done' | 'failed';
+        words: string | null;
+        at: string;
+    } | null;
+    updatedAt: string;
+}
+/** One article in full, from help.articles.get() and every change. */
+export interface HelpArticle {
+    id: string;
+    title: string;
+    slug: string;
+    summary: string | null;
+    body: string;
+    status: HelpArticleStatus;
+    publishedTitle: string | null;
+    publishedSummary: string | null;
+    publishedBody: string | null;
+    publishedAt: string | null;
+    firstPublishedAt: string | null;
+    segments: string[];
+    topicId: string | null;
+    position: number;
+    staffNote: string | null;
+    createdAt: string;
+    updatedAt: string;
+    changed: boolean;
+}
 /** The account's support desk, from supportDesk.status(). */
 export interface SupportDeskStatus {
     on: boolean;

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.77.1';
+export const VERSION = '0.79.0';
 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;
@@ -367,8 +367,18 @@ export class AwesomateClient {
         download: async (path) => (await this.raw('GET', `/api/files/stream?${new URLSearchParams({ path, disposition: 'attachment' })}`)).blob(),
         /** Make a folder, and any above it. */
         mkdir: async (path) => (await this.filesCall('POST', '/api/files/mkdir', { path })).entry,
-        /** Move or rename. Anything using the old path or address needs the new one. */
+        /** Move or rename. A `to` ending in "/" is a folder to move it into, keeping its name. Anything using the old path or address needs the new one. */
         move: async (from, to) => (await this.filesCall('POST', '/api/files/move', { from, to })).entry,
+        /** Move up to 100 at once. Each is answered on its own in `results`; one that fails does not stop the rest. */
+        moveMany: async (items) => this.filesCall('POST', '/api/files/move', { items }),
+        /**
+         * Copy a file or a folder, leaving the original. A `to` ending in "/" keeps the name. A file already at `to` is
+         * replaced only with `{ overwrite: true }`; a folder copy never writes into a folder that is there. One call copies
+         * at most 200 files and 250 MB, within the plan's Files space.
+         */
+        copy: async (from, to, opts = {}) => (await this.filesCall('POST', '/api/files/copy', { from, to, ...(opts.overwrite ? { overwrite: true } : {}) })).entry,
+        /** Copy up to 100 at once (200 files and 250 MB in all). Each is answered on its own in `results`. */
+        copyMany: async (items, opts = {}) => this.filesCall('POST', '/api/files/copy', { items, ...(opts.overwrite ? { overwrite: true } : {}) }),
         /** Move a file from private/ or temp/ to the same place under public/, and answer its public_url. Anyone with the address can open it. */
         makePublic: async (path) => {
             const [top, ...rest] = path.replace(/^\/+/, '').split('/');
@@ -1076,6 +1086,79 @@ export class AwesomateClient {
         /** Where the business's Stripe account stands, with one sentence (`next`) saying what happens next. */
         status: () => this.request('GET', '/api/my-crm/v1/payments/status'),
     };
+    /**
+     * The account's own help centre: its topics and articles, written as drafts, published to the
+     * public help pages (shown while the centre's pages are on, and sent to the business's Knowledge
+     * where the centre feeds it), unpublished or archived. Needs the account's token with help:write, a permission no plan
+     * gives by itself: the account owner switches it on for one key in the hub (Claude Code, Get my
+     * code, "Write, publish and take down your help centre articles"). Never an app key, a team
+     * member's key or a chat connection. An account with no help centre answers not_found with
+     * serverCode `no_help_centre`.
+     *
+     * An article's working copy (title, summary, body) is what you change; the public sees its
+     * published copy, so an edit is not live until you publish again. Publishing is refused while
+     * the body still has a `[CHECK:` note in it. Bodies are Markdown.
+     *
+     * @example
+     * const { topics } = await db.help.centre();
+     * const article = await db.help.articles.create({ title: 'Connect Xero', body: 'Open Settings, then Integrations.', topicId: topics[0]?.id });
+     * await db.help.articles.publish(article.id);
+     */
+    help = {
+        /** 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 };
+        },
+        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. */
+            create: async (input) => (await this.helpRequest('POST', '/topics', input)).topic,
+        },
+        articles: {
+            /** Articles without their bodies, optionally in one status or matching words in the title. */
+            list: async (options = {}) => {
+                const q = new URLSearchParams();
+                if (options.status)
+                    q.set('status', options.status);
+                if (options.q)
+                    q.set('q', options.q);
+                const qs = q.toString();
+                return (await this.helpRequest('GET', `/${qs ? `?${qs}` : ''}`)).articles;
+            },
+            /** One article with its working and published copies, or null when there is none. */
+            get: async (id) => {
+                if (!RECORD_ID.test(String(id)))
+                    return null;
+                try {
+                    return (await this.helpRequest('GET', `/articles/${encodeURIComponent(String(id))}`)).article;
+                }
+                catch (err) {
+                    if (err instanceof AwesomateError && err.code === 'not_found' && err.serverCode !== 'no_help_centre')
+                        return null;
+                    throw err;
+                }
+            },
+            /** A new draft. Its slug is made from the title unless given; segments default to everyone. */
+            create: async (input) => (await this.helpRequest('POST', '/articles', input)).article,
+            /** Change a draft's (or a published article's working) copy. Fields left out are left as they are. */
+            update: async (id, patch) => (await this.helpRequest('PATCH', `/articles/${encodeURIComponent(String(id))}`, patch)).article,
+            /** Make the working copy public (and send its page to Knowledge where the centre feeds it). */
+            publish: async (id) => (await this.helpRequest('POST', `/articles/${encodeURIComponent(String(id))}/publish`)).article,
+            /** Take it off the public pages; it stays as a draft. */
+            unpublish: async (id) => (await this.helpRequest('POST', `/articles/${encodeURIComponent(String(id))}/unpublish`)).article,
+            /** Archive it: off the public pages and out of Knowledge. Restoring is done in the hub. */
+            archive: async (id) => (await this.helpRequest('POST', `/articles/${encodeURIComponent(String(id))}/archive`)).article,
+        },
+    };
+    /** A help centre call: the account's own token only, and a change is never sent twice. */
+    helpRequest(method, path, body) {
+        if (this.appKey) {
+            throw new AwesomateError('forbidden', "The help centre needs the account's token with help:write, not an app key.", 0);
+        }
+        return this.request(method, `/api/my-help/v1${path}`, body, method === 'GET');
+    }
     /**
      * The account's own support desk: the help inbox for its customers, under Contacts, Inbox in
      * the hub. Read only, on purpose: every message here was written by someone outside the

package/package.json

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