@awesomate/sdk 0.1.0 → 0.3.0

package/README.md

@@ -30,6 +30,30 @@ const one = await db.get('contact', rows[0].id); // null if there is none
 const byPlan = await db.aggregate({ measures: [{ column: 'people', agg: 'count' }], dimensions: ['plan'] });
 ```
 
+## Writing app data (Support Plus and above)
+
+Define the tables an app keeps, then write to them. There's no migration and no SQL; every value is
+checked against the kind (types, choices, required attributes and links).
+
+```ts
+await db.defineKind({
+  key: 'job', label: 'Job', label_plural: 'Jobs',
+  attributes: [
+    { key: 'title', type: 'text', required: true, readable_by_ai: true },
+    { key: 'status', type: 'choice', choices: ['open', 'booked', 'done'], readable_by_ai: true },
+  ],
+  links: [{ key: 'customer', to: 'contact' }],
+});
+const id = await db.write('job', { title: 'Possum in the roof', status: 'open' }, { links: { customer: contactId } });
+await db.write('job', { status: 'booked' }, { id });            // values not given stay
+const jobs = await db.query('job', { where: { customer_id: contactId } });
+await db.archive('job', id);
+```
+
+Only attributes marked `readable_by_ai` come back from `query` and `get`; a `sensitive` attribute
+can never be readable. Contacts themselves are not written this way: the contact list keeps its
+own consent rules.
+
 ## What you can read
 
 The built-in contact details (name, email, phone, company, tags, when they were added) and only

package/dist/index.d.ts

@@ -6,15 +6,37 @@
  *   const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
  *   const { rows, next } = await db.query('contact', { where: { created_at: { gte: '$YEAR_BEGIN' } }, limit: 50 });
  *
+ *   const open = await db.run('open_jobs_in', { suburb: 'Carindale' }); // a saved query, by name
+ *   await db.call('log_visit', { customer, title: 'Possum in the roof' }); // a write recipe, one transaction
+ *
  * The account's token (a hosting PAT with crm:read) is a secret: use it on a server, never in a
- * browser. End-user sign-in for browser apps comes in a later version.
+ * browser. End-user sign-in for browser apps comes in a later version. Reading and running saved
+ * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
+ * crm:write, Support Plus and above.
  */
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.3.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
 export type KindName = [keyof Kinds] extends [never] ? string : Extract<keyof Kinds, string>;
 export type RowOf<K> = K extends keyof Kinds ? Kinds[K] : Record<string, unknown>;
+/** Augmented by the generated awesomate.d.ts: each saved query's params and row. */
+export interface Queries {
+}
+/** Augmented by the generated awesomate.d.ts: each write recipe's args. */
+export interface Recipes {
+}
+export type QueryName = [keyof Queries] extends [never] ? string : Extract<keyof Queries, string>;
+export type ParamsOf<Q> = Q extends keyof Queries ? (Queries[Q] extends {
+    params: infer P;
+} ? P : never) : Record<string, unknown>;
+export type QueryRowOf<Q> = Q extends keyof Queries ? (Queries[Q] extends {
+    row: infer R;
+} ? R : never) : Record<string, unknown>;
+export type RecipeName = [keyof Recipes] extends [never] ? string : Extract<keyof Recipes, string>;
+export type ArgsOf<R> = R extends keyof Recipes ? (Recipes[R] extends {
+    args: infer A;
+} ? A : never) : Record<string, unknown>;
 type TextOps<V extends string> = {
     eq?: V | null;
     neq?: V | null;
@@ -122,7 +144,7 @@ export declare class AwesomateClient {
     private readonly base;
     private readonly doFetch;
     constructor(opts: ClientOptions);
-    private call;
+    private request;
     /** The kinds this token can read, their columns, operators and examples. */
     schema(): Promise<{
         kinds: Array<{
@@ -151,6 +173,42 @@ export declare class AwesomateClient {
     get<K extends KindName>(kind: K, id: string, options?: {
         tz?: string;
     }): Promise<RowOf<K> | null>;
+    /** The app kinds this account has defined. */
+    kinds(): Promise<KindDescription[]>;
+    /** Define an app kind (a table an app keeps). No migration: registry rows and generated views. */
+    defineKind(spec: KindSpec): Promise<KindDescription>;
+    /** Create a record (returns its id), or change one with options.id. Every value is checked against the kind. */
+    write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
+    /** Archive a record: it leaves every read and is kept for a restore. */
+    archive<K extends KindName>(kind: K, id: string): Promise<void>;
+    /** The saved queries on this account. */
+    queries(): Promise<SavedQueryDescription[]>;
+    /**
+     * Save a query by name (saving a name again replaces it). The spec is the query() grammar on one
+     * kind, with {"$param": "<name>"} where a caller's value goes; it is compiled before it is
+     * stored, so a column it cannot read is refused now rather than when it runs.
+     */
+    saveQuery(spec: SavedQuerySpec): Promise<SavedQueryDescription>;
+    archiveQuery(key: string): Promise<void>;
+    /** Run a saved query with its params. An optional param left out drops its condition. */
+    run<Q extends QueryName>(query: Q, params?: ParamsOf<Q>, options?: {
+        limit?: number;
+        after?: string;
+        tz?: string;
+    }): Promise<Page<QueryRowOf<Q>>>;
+    /** The write recipes on this account. */
+    recipes(): Promise<RecipeDescription[]>;
+    /**
+     * Save a write recipe: up to 10 write_record / archive_record steps run in one transaction.
+     * {"$param": "<name>"} takes a caller's value, {"$step": "<as>"} the id an earlier step wrote.
+     */
+    saveRecipe(spec: RecipeSpec): Promise<RecipeDescription>;
+    archiveRecipe(key: string): Promise<void>;
+    /**
+     * Run a write recipe. Every step commits or none does; a refusal names the step and the field.
+     * Never retried: a write that may have landed is not safe to send twice.
+     */
+    call<R extends RecipeName>(recipe: R, args?: ArgsOf<R>): Promise<RecipeResult>;
     /** Grouped numbers (counts, sums) in the Business Data API's shape. */
     aggregate(request: {
         measures: Array<{
@@ -178,5 +236,111 @@ export declare class AwesomateClient {
         limit?: number;
     }): Promise<Record<string, unknown>>;
 }
+export interface AttributeSpec {
+    key: string;
+    label?: string;
+    type?: 'text' | 'long_text' | 'number' | 'money' | 'date' | 'datetime' | 'duration' | 'yes_no' | 'choice' | 'choices' | 'email' | 'phone' | 'address' | 'url' | 'file';
+    choices?: string[];
+    required?: boolean;
+    sensitivity?: 'ordinary' | 'personal' | 'sensitive';
+    /** Default false. Only readable attributes reach query(), get() and the generated types. */
+    readable_by_ai?: boolean;
+}
+export interface KindSpec {
+    key: string;
+    label?: string;
+    label_plural?: string;
+    attributes: AttributeSpec[];
+    /** to is 'contact' or a kind already defined; each link reads back as <key>_id. */
+    links?: Array<{
+        key: string;
+        to: string;
+        label?: string;
+        to_label?: string;
+        required?: boolean;
+    }>;
+}
+export interface KindDescription extends Omit<KindSpec, 'attributes'> {
+    storage: 'plain' | 'tracked';
+    attributes: Array<Required<Pick<AttributeSpec, 'key' | 'label' | 'type' | 'required' | 'sensitivity' | 'readable_by_ai'>> & {
+        choices: string[] | null;
+    }>;
+    views: {
+        all: string;
+        for_agents: string;
+    };
+}
+export interface WriteOptions {
+    /** Change this record instead of creating one; values not given stay. */
+    id?: string;
+    /** Set a link by its key ('<id>'), or end it (null). */
+    links?: Record<string, string | null>;
+}
+export type ParamType = 'text' | 'number' | 'date' | 'datetime' | 'boolean' | 'uuid' | 'text_list' | 'number_list';
+export interface ParamSpec {
+    name: string;
+    /** Default text. */
+    type?: ParamType;
+    required?: boolean;
+    default?: unknown;
+    label?: string;
+}
+/** Where a caller's value goes in a saved query or a recipe. */
+export type Param = {
+    $param: string;
+};
+export interface SavedQuerySpec {
+    key: string;
+    label: string;
+    description?: string;
+    /** 'contact' or an app kind. */
+    kind: string;
+    spec: {
+        where?: Record<string, unknown>;
+        orderBy?: Array<[string, 'asc' | 'desc']>;
+        select?: string[];
+        limit?: number;
+    };
+    params?: ParamSpec[];
+}
+export interface SavedQueryDescription extends Required<Omit<SavedQuerySpec, 'description' | 'params'>> {
+    description: string | null;
+    params: ParamSpec[];
+    updated_at: string;
+}
+export type RecipeStep = {
+    op: 'write_record';
+    kind: string;
+    id?: Param | {
+        $step: string;
+    };
+    as?: string;
+    data?: Record<string, unknown>;
+    links?: Record<string, unknown>;
+} | {
+    op: 'archive_record';
+    kind: string;
+    id: Param | {
+        $step: string;
+    };
+};
+export interface RecipeSpec {
+    key: string;
+    label: string;
+    description?: string;
+    params?: ParamSpec[];
+    steps: RecipeStep[];
+}
+export interface RecipeDescription extends Required<Omit<RecipeSpec, 'description' | 'params'>> {
+    description: string | null;
+    params: ParamSpec[];
+    updated_at: string;
+}
+export interface RecipeResult {
+    /** The id each step named with `as` wrote. */
+    ids: Record<string, string>;
+    /** Every record the recipe wrote or archived, in step order. */
+    records: string[];
+}
 export declare function createClient(options: ClientOptions): AwesomateClient;
 export {};

package/dist/index.js

@@ -6,10 +6,15 @@
  *   const db = createClient({ token: process.env.AWESOMATE_TOKEN! });
  *   const { rows, next } = await db.query('contact', { where: { created_at: { gte: '$YEAR_BEGIN' } }, limit: 50 });
  *
+ *   const open = await db.run('open_jobs_in', { suburb: 'Carindale' }); // a saved query, by name
+ *   await db.call('log_visit', { customer, title: 'Possum in the roof' }); // a write recipe, one transaction
+ *
  * The account's token (a hosting PAT with crm:read) is a secret: use it on a server, never in a
- * browser. End-user sign-in for browser apps comes in a later version.
+ * browser. End-user sign-in for browser apps comes in a later version. Reading and running saved
+ * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
+ * crm:write, Support Plus and above.
  */
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 export class AwesomateError extends Error {
     code;
@@ -57,7 +62,7 @@ export class AwesomateClient {
         if (!this.doFetch)
             throw new Error('No fetch available: use Node 18 or later, or pass fetch.');
     }
-    async call(method, path, body, retry = true) {
+    async request(method, path, body, retry = true) {
         const res = await this.doFetch(`${this.base}${path}`, {
             method,
             headers: {
@@ -80,20 +85,20 @@ export class AwesomateClient {
         // The field list changed while the read ran (the view is rebuilt on every field edit): a read
         // is safe to run again, once.
         if (code === 'conflict' && retry)
-            return this.call(method, path, body, false);
+            return this.request(method, path, body, false);
         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);
     }
     /** The kinds this token can read, their columns, operators and examples. */
     schema() {
-        return this.call('GET', '/api/my-crm/v1/rows/schema');
+        return this.request('GET', '/api/my-crm/v1/rows/schema');
     }
     /** The readable kinds as a TypeScript file (what the types command writes). */
     types() {
-        return this.call('GET', '/api/my-crm/v1/rows/types');
+        return this.request('GET', '/api/my-crm/v1/rows/types');
     }
     async query(kind, options = {}) {
-        const r = await this.call('POST', '/api/my-crm/v1/rows/query', { kind, ...options });
+        const r = await this.request('POST', '/api/my-crm/v1/rows/query', { kind, ...options });
         return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, hidden: r.hidden, asAt: r.as_at };
     }
     /** Every matching row, a page at a time. maxRows guards against reading a whole list by accident. */
@@ -115,7 +120,7 @@ export class AwesomateClient {
     async get(kind, id, options = {}) {
         try {
             const qs = options.tz ? `?tz=${encodeURIComponent(options.tz)}` : '';
-            const r = await this.call('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(id)}${qs}`);
+            const r = await this.request('GET', `/api/my-crm/v1/rows/${encodeURIComponent(kind)}/${encodeURIComponent(id)}${qs}`);
             return r.row;
         }
         catch (err) {
@@ -124,9 +129,69 @@ export class AwesomateClient {
             throw err;
         }
     }
+    /** The app kinds this account has defined. */
+    async kinds() {
+        return (await this.request('GET', '/api/my-crm/v1/kinds')).kinds;
+    }
+    /** Define an app kind (a table an app keeps). No migration: registry rows and generated views. */
+    async defineKind(spec) {
+        return (await this.request('POST', '/api/my-crm/v1/kinds', spec)).kind;
+    }
+    /** Create a record (returns its id), or change one with options.id. Every value is checked against the kind. */
+    async write(kind, data, options = {}) {
+        const r = await this.request('POST', '/api/my-crm/v1/call', {
+            fn: 'write_record', args: { kind, data, links: options.links ?? {}, ...(options.id ? { id: options.id } : {}) },
+        }, false);
+        return r.result.id;
+    }
+    /** Archive a record: it leaves every read and is kept for a restore. */
+    async archive(kind, id) {
+        await this.request('POST', '/api/my-crm/v1/call', { fn: 'archive_record', args: { kind, id } }, false);
+    }
+    /** The saved queries on this account. */
+    async queries() {
+        return (await this.request('GET', '/api/my-crm/v1/queries')).queries;
+    }
+    /**
+     * Save a query by name (saving a name again replaces it). The spec is the query() grammar on one
+     * kind, with {"$param": "<name>"} where a caller's value goes; it is compiled before it is
+     * stored, so a column it cannot read is refused now rather than when it runs.
+     */
+    async saveQuery(spec) {
+        return (await this.request('POST', '/api/my-crm/v1/queries', spec, false)).query;
+    }
+    async archiveQuery(key) {
+        await this.request('DELETE', `/api/my-crm/v1/queries/${encodeURIComponent(key)}`, undefined, false);
+    }
+    /** Run a saved query with its params. An optional param left out drops its condition. */
+    async run(query, params = {}, options = {}) {
+        const r = await this.request('POST', `/api/my-crm/v1/queries/${encodeURIComponent(query)}/run`, { params, ...options });
+        return { rows: r.rows, next: r.next, count: r.count, applied: r.applied, hidden: r.hidden, asAt: r.as_at };
+    }
+    /** The write recipes on this account. */
+    async recipes() {
+        return (await this.request('GET', '/api/my-crm/v1/recipes')).recipes;
+    }
+    /**
+     * Save a write recipe: up to 10 write_record / archive_record steps run in one transaction.
+     * {"$param": "<name>"} takes a caller's value, {"$step": "<as>"} the id an earlier step wrote.
+     */
+    async saveRecipe(spec) {
+        return (await this.request('POST', '/api/my-crm/v1/recipes', spec, false)).recipe;
+    }
+    async archiveRecipe(key) {
+        await this.request('DELETE', `/api/my-crm/v1/recipes/${encodeURIComponent(key)}`, undefined, false);
+    }
+    /**
+     * Run a write recipe. Every step commits or none does; a refusal names the step and the field.
+     * Never retried: a write that may have landed is not safe to send twice.
+     */
+    async call(recipe, args = {}) {
+        return (await this.request('POST', '/api/my-crm/v1/call', { fn: recipe, args }, false)).result;
+    }
     /** Grouped numbers (counts, sums) in the Business Data API's shape. */
     aggregate(request) {
-        return this.call('POST', '/api/my-crm/v1/data/query', request);
+        return this.request('POST', '/api/my-crm/v1/data/query', request);
     }
 }
 export function createClient(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Read your own Awesomate data from Node: query and page through your contact list with types generated from your fields",
   "license": "MIT",
   "type": "module",