@awesomate/sdk 0.15.0 → 0.16.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.15.0";
+export declare const VERSION = "0.16.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -157,6 +157,38 @@ export interface Page<R> {
     /** When the hub read the rows. */
     asAt: 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. */
+    path: string;
+    name: string;
+    type: 'file' | 'dir';
+    /** Bytes; 0 for a folder. */
+    size: number;
+    /** ISO time it last changed. */
+    modified: string;
+    /** For a file in public/: the address anyone with it can open, with no login. Otherwise null. */
+    public_url: string | null;
+}
+/** How much of the plan's Files space is used. */
+export interface FilesUsage {
+    used_bytes: number;
+    limit_bytes: number;
+    files: number;
+    /** The measure stopped early on a very large tree: used_bytes is at least this much. */
+    partial: boolean;
+    measured_at: string;
+}
+/** A file uploaded from an app. Keep `handle` in a record (a kind's file attribute); it opens the file again. */
+export interface AppFile {
+    handle: string;
+    name: string;
+    size: number;
+    /** Only when the app's uploads are public. */
+    public_url: string | null;
+}
+/** What a file can be sent as. */
+export type FileBody = Blob | ArrayBuffer | Uint8Array | string;
 declare const ERROR_CODES: readonly ["unauthenticated", "forbidden", "not_found", "validation", "consent_blocked", "rate_limited", "conflict", "unavailable"];
 /**
  * Why a call failed, one of a fixed list: unauthenticated, forbidden, not_found, validation,
@@ -215,6 +247,56 @@ export declare class AwesomateClient {
     private readonly appKey;
     constructor(opts: ClientOptions);
     private request;
+    /** A call whose body or answer is a file, not JSON. Answers the Response when it succeeded. */
+    private raw;
+    private filesCall;
+    /**
+     * The account's Files: the folders on its automation account that its n8n workflows read and
+     * write (public/, private/, temp/). A file in public/ has a public_url anyone with it can open;
+     * the others never do. Needs the account's token with files:read (reading) or files:write
+     * (changing), on a plan with Files, after the owner has switched on "Open your automation
+     * account's file folders" in Settings, Privacy.
+     *
+     * @example
+     * const logo = await db.files.upload('public/brand/logo.png', await readFile('logo.png'));
+     * console.log(logo.public_url);
+     */
+    readonly files: {
+        /** One folder; '' (the default) lists the top folders. */
+        list: (path?: string) => Promise<FileEntry[]>;
+        /** Files by part of their name (* and ? are wildcards), across the folders or in one. At most 200: `truncated` says there were more. */
+        search: (options?: {
+            q?: string;
+            top?: "public" | "private" | "temp";
+            extensions?: string[];
+        }) => Promise<{
+            results: FileEntry[];
+            truncated: boolean;
+        }>;
+        /** Space used against the plan's Files space. Measured, and up to ten minutes old. */
+        usage: () => Promise<FilesUsage>;
+        /**
+         * Write a file (up to 50 MB). Refuses to replace one already there unless `overwrite`. A full
+         * Files space answers serverCode files_storage_full.
+         */
+        upload: (path: string, data: FileBody, options?: {
+            overwrite?: boolean;
+        }) => Promise<FileEntry>;
+        /** A file's contents. */
+        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: (from: string, to: string) => Promise<FileEntry>;
+        /** 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, though Cloudflare can keep showing the last copy for up to 4 hours. */
+        makePrivate: (path: string) => Promise<FileEntry>;
+        /** Move to the trash. Not erased, and no longer counted toward the Files space. */
+        remove: (path: string) => Promise<{
+            trashPath: string;
+        }>;
+    };
     /** The kinds this token can read, their columns, operators and examples. */
     schema(): Promise<{
         kinds: Array<{
@@ -871,6 +953,34 @@ export declare class AwesomateAppClient {
         ids?: string[];
         limit?: number;
     }): Promise<Customer[]>;
+    /** Runs a call with the current access token, refreshing it once when the hub says it expired. */
+    private authed;
+    private rawData;
+    /**
+     * Files people attach in this app, such as a photo of a job or a signed form, kept in the
+     * account's Files. Off until the account switches it on for the app (private, or public with a
+     * public address per file): check mode() before showing an upload button. Keep the handle an
+     * upload answers in a record's file attribute; anyone signed in to this app who can read that
+     * record can open the file with download().
+     *
+     * @example
+     * const file = await app.files.upload(input.files[0]);
+     * await app.write('message', { body: 'Photo of the leak', attachment: file.handle }, { links: { job: jobId } });
+     */
+    readonly files: {
+        /** Whether this app takes uploads: 'off', 'private' or 'public'. */
+        mode: () => Promise<"off" | "private" | "public">;
+        /**
+         * Upload one file, up to 10 MB. The name comes from a File, or pass one. A refusal's
+         * serverCode says why: uploads_off, too_large, type_not_allowed (public uploads take no web
+         * pages or scripts), files_storage_full; personMessage is the sentence to show.
+         */
+        upload: (file: Blob, options?: {
+            name?: string;
+        }) => Promise<AppFile>;
+        /** The file a handle names, for someone signed in to this app. */
+        download: (handle: string) => Promise<Blob>;
+    };
     /**
      * The agent this app talks with by voice, or null when the account has not picked one. Pass it
      * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.

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.15.0';
+export const VERSION = '0.16.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 /**
@@ -57,13 +57,17 @@ export class AwesomateError extends Error {
         this.name = 'AwesomateError';
     }
 }
+const CONSENT_CODES = new Set(['consent_blocked', 'consent_denied', 'files_consent_off']);
 function errorCode(status, server) {
     if (server === 'validation' || server === 'invalid' || status === 422)
         return 'validation';
+    // A file the hub will not take as sent: too big, no length, or a type it refuses.
+    if (status === 411 || status === 413 || status === 415)
+        return 'validation';
     if (status === 401)
         return 'unauthenticated';
     if (status === 403)
-        return server === 'consent_blocked' ? 'consent_blocked' : 'forbidden';
+        return server && CONSENT_CODES.has(server) ? 'consent_blocked' : 'forbidden';
     if (status === 429)
         return 'rate_limited';
     if (server === 'conflict')
@@ -133,6 +137,99 @@ export class AwesomateClient {
         const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
         throw new AwesomateError(code, message, res.status, typeof json.field === 'string' ? json.field : undefined, server);
     }
+    /** A call whose body or answer is a file, not JSON. Answers the Response when it succeeded. */
+    async raw(method, path, body) {
+        if (this.appKey) {
+            throw new AwesomateError('forbidden', 'Files needs the account\'s token (amt_pat_... with files:read or files:write), not an app key.', 0);
+        }
+        const res = await this.doFetch(`${this.base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.opts.token}`,
+                'user-agent': `@awesomate/sdk/${VERSION}`,
+                ...(body === undefined ? {} : { 'content-type': 'application/octet-stream' }),
+            },
+            body: body,
+        });
+        if (res.ok)
+            return res;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* a proxy's HTML error page */ }
+        const server = typeof json.code === 'string' ? json.code : undefined;
+        const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
+        throw new AwesomateError(errorCode(res.status, server), message, res.status, undefined, server);
+    }
+    filesCall(method, path, body) {
+        if (this.appKey) {
+            return Promise.reject(new AwesomateError('forbidden', 'Files needs the account\'s token (amt_pat_... with files:read or files:write), not an app key.', 0));
+        }
+        return this.request(method, path, body, false);
+    }
+    /**
+     * The account's Files: the folders on its automation account that its n8n workflows read and
+     * write (public/, private/, temp/). A file in public/ has a public_url anyone with it can open;
+     * the others never do. Needs the account's token with files:read (reading) or files:write
+     * (changing), on a plan with Files, after the owner has switched on "Open your automation
+     * account's file folders" in Settings, Privacy.
+     *
+     * @example
+     * const logo = await db.files.upload('public/brand/logo.png', await readFile('logo.png'));
+     * console.log(logo.public_url);
+     */
+    files = {
+        /** One folder; '' (the default) lists the top folders. */
+        list: async (path = '') => (await this.filesCall('GET', `/api/files?path=${encodeURIComponent(path)}`)).entries,
+        /** Files by part of their name (* and ? are wildcards), across the folders or in one. At most 200: `truncated` says there were more. */
+        search: async (options = {}) => {
+            const qs = new URLSearchParams({ q: options.q ?? '' });
+            if (options.top)
+                qs.set('top', options.top);
+            if (options.extensions?.length)
+                qs.set('exts', options.extensions.join(','));
+            const r = await this.filesCall('GET', `/api/files/search?${qs}`);
+            return { results: r.results, truncated: r.truncated };
+        },
+        /** Space used against the plan's Files space. Measured, and up to ten minutes old. */
+        usage: () => this.filesCall('GET', '/api/files/usage'),
+        /**
+         * Write a file (up to 50 MB). Refuses to replace one already there unless `overwrite`. A full
+         * Files space answers serverCode files_storage_full.
+         */
+        upload: async (path, data, options = {}) => {
+            const qs = new URLSearchParams({ path });
+            if (options.overwrite)
+                qs.set('overwrite', '1');
+            return (await (await this.raw('POST', `/api/files?${qs}`, data)).json()).entry;
+        },
+        /** A file's contents. */
+        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: async (from, to) => (await this.filesCall('POST', '/api/files/move', { from, to })).entry,
+        /** 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('/');
+            if (top === 'public')
+                throw new AwesomateError('validation', `${path} is already public.`, 0, 'path');
+            if (!rest.length)
+                throw new AwesomateError('validation', 'Name a file inside the folder.', 0, 'path');
+            return this.files.move(path, `public/${rest.join('/')}`);
+        },
+        /** Move a file out of public/ into private/. Its public address stops serving it, though Cloudflare can keep showing the last copy for up to 4 hours. */
+        makePrivate: async (path) => {
+            const [top, ...rest] = path.replace(/^\/+/, '').split('/');
+            if (top !== 'public' || !rest.length)
+                throw new AwesomateError('validation', `${path} is not a file in public/.`, 0, 'path');
+            return this.files.move(path, `private/${rest.join('/')}`);
+        },
+        /** Move to the trash. Not erased, and no longer counted toward the Files space. */
+        remove: async (path) => this.filesCall('DELETE', `/api/files?path=${encodeURIComponent(path)}`),
+    };
     /** The kinds this token can read, their columns, operators and examples. */
     schema() {
         return this.request('GET', '/api/my-crm/v1/rows/schema');
@@ -597,6 +694,71 @@ export class AwesomateAppClient {
     async lookupCustomers(options) {
         return (await this.data('POST', '/customers/lookup', options)).customers;
     }
+    /** Runs a call with the current access token, refreshing it once when the hub says it expired. */
+    async authed(fn) {
+        let s = await this.current();
+        if (!s)
+            throw new AwesomateError('unauthenticated', 'Sign in first.', 401);
+        try {
+            return await fn(s.access_token);
+        }
+        catch (err) {
+            if (!(err instanceof AwesomateError) || err.code !== 'unauthenticated')
+                throw err;
+            s = await this.refresh(s);
+            if (!s)
+                throw err;
+            return fn(s.access_token);
+        }
+    }
+    async rawData(method, path, token, body) {
+        const res = await this.doFetch(`${this.base}/api/sdk/v1${path}`, {
+            method,
+            headers: {
+                'x-awesomate-key': this.opts.publishableKey,
+                authorization: `Bearer ${token}`,
+                ...(body === undefined ? {} : { 'content-type': 'application/octet-stream' }),
+            },
+            body: body,
+        });
+        if (res.ok)
+            return res;
+        const text = await res.text();
+        let json = {};
+        try {
+            json = text ? JSON.parse(text) : {};
+        }
+        catch { /* a proxy's error page */ }
+        const server = typeof json.code === 'string' ? json.code : undefined;
+        const message = typeof json.error === 'string' ? json.error : `The hub answered ${res.status}.`;
+        throw new AwesomateError(errorCode(res.status, server), message, res.status, undefined, server, message);
+    }
+    /**
+     * Files people attach in this app, such as a photo of a job or a signed form, kept in the
+     * account's Files. Off until the account switches it on for the app (private, or public with a
+     * public address per file): check mode() before showing an upload button. Keep the handle an
+     * upload answers in a record's file attribute; anyone signed in to this app who can read that
+     * record can open the file with download().
+     *
+     * @example
+     * const file = await app.files.upload(input.files[0]);
+     * await app.write('message', { body: 'Photo of the leak', attachment: file.handle }, { links: { job: jobId } });
+     */
+    files = {
+        /** Whether this app takes uploads: 'off', 'private' or 'public'. */
+        mode: async () => (await this.data('GET', '/me')).app.file_uploads ?? 'off',
+        /**
+         * Upload one file, up to 10 MB. The name comes from a File, or pass one. A refusal's
+         * serverCode says why: uploads_off, too_large, type_not_allowed (public uploads take no web
+         * pages or scripts), files_storage_full; personMessage is the sentence to show.
+         */
+        upload: async (file, options = {}) => {
+            const name = options.name ?? file.name ?? 'file';
+            return this.authed(async (token) => (await (await this.rawData('POST', `/files?name=${encodeURIComponent(name)}`, token, file)).json()).file);
+        },
+        /** The file a handle names, for someone signed in to this app. */
+        download: async (handle) => this.authed(async (token) => (await this.rawData('GET', `/files/${encodeURIComponent(handle)}`, token)).blob()),
+    };
     /**
      * The agent this app talks with by voice, or null when the account has not picked one. Pass it
      * to AwesomateAgent.mount as agentId; the hub decides which agent answers, never the page.

package/package.json

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