@awesomate/sdk 0.7.0 → 0.9.0

package/README.md

@@ -146,6 +146,36 @@ and takes a fresh copy when it does. Up to 200 rows a list and 20 lists a connec
 `{ onRows, onError }` to hear about a list the server refused (a column that does not exist).
 Outside a browser, give it a WebSocket: `createAppClient({ publishableKey, WebSocket })`.
 
+### Staff find a customer
+
+People in an app read no contacts but their own, so by default staff cannot put a job under a
+customer. Switch it on per app for the roles that need it (`awesomate_crm_apps`,
+`customer_lookup`, never the role customers sign in with). Those roles can then search by name or
+email and point a record at any customer:
+
+```ts
+const [jo] = await app.lookupCustomers({ q: 'jo' });           // or { ids: [...] }, up to 50
+await app.write('job', { title: 'Gutters' }, { links: { customer: jo.id } });
+```
+
+Name, email and phone only, and nothing the owner marked sensitive. Anyone else is refused.
+
+An attribute can also be visible to some roles only (`awesomate_crm_kinds`, `set_visibility`, for
+example a cost only `staff` see). For everyone else it comes back `null` and a write that sets it
+is refused, whatever the app asks for.
+
+Some things a customer should do without being able to edit the record: accept their quote, say.
+Save it as a write recipe and open it to their role (`awesomate_crm_recipes`, `run_by`, Pro and
+above), then:
+
+```ts
+await app.call('accept_quote', { job: job.id });
+```
+
+The database lets them do exactly the recipe's steps: only its params take their values, every
+other value is fixed, and an existing record must be one they can already read. A recipe not
+opened to their role is "not found".
+
 The rules are kept in your own database, which applies them to every read and write, so a mistake
 in the app cannot show anyone more than their role allows. A disabled person is refused on their
 next call. Sessions are kept in `localStorage`; in a Capacitor app pass `storage` (Preferences) and

package/dist/index.d.ts

@@ -370,6 +370,13 @@ export interface AppUser {
     role: string;
     contact_id: string | null;
 }
+/** A customer as lookupCustomers() returns them. A field the owner marked sensitive is null. */
+export interface Customer {
+    id: string;
+    name: string | null;
+    email: string | null;
+    phone: string | null;
+}
 export interface AppClientOptions {
     /** The app's publishable key (pk_...). Not a secret: it belongs in browser code. */
     publishableKey: string;
@@ -485,6 +492,23 @@ export declare class AwesomateAppClient {
     /** Create a record (returns its id) or change one with options.id, inside the kind's write rule for this user. */
     write<K extends KindName>(kind: K, data: Partial<RowOf<K>> | Record<string, unknown>, options?: WriteOptions): Promise<string>;
     archive<K extends KindName>(kind: K, id: string): Promise<void>;
+    /**
+     * Run a recipe the account opened to this person's role: "accept this quote", something their
+     * write rule would not let them do by hand. Every step commits or none does; a recipe they may
+     * not run reads as not found. Never retried once sent: a write that may have landed is not safe
+     * to send twice (a refused sign-in is, and is retried after a refresh like every data call).
+     */
+    call<R extends RecipeName>(recipe: R, args?: ArgsOf<R>): Promise<RecipeResult>;
+    /**
+     * Customers by name or email (two characters or more), or by id, so staff can find one and put
+     * a record under them. Only for a role the account lets look customers up in this app; anyone
+     * else gets a forbidden error. Name, email and phone only, at most 50.
+     */
+    lookupCustomers(options: {
+        q?: string;
+        ids?: string[];
+        limit?: number;
+    }): Promise<Customer[]>;
     /**
      * A list kept current: onRows gets the whole list (up to 200 rows, the query's order) at first
      * and again whenever a row in it is added, changed, removed, or stops being one this person may

package/dist/index.js

@@ -514,6 +514,23 @@ export class AwesomateAppClient {
     async archive(kind, id) {
         await this.data('POST', '/call', { fn: 'archive_record', args: { kind, id } });
     }
+    /**
+     * Run a recipe the account opened to this person's role: "accept this quote", something their
+     * write rule would not let them do by hand. Every step commits or none does; a recipe they may
+     * not run reads as not found. Never retried once sent: a write that may have landed is not safe
+     * to send twice (a refused sign-in is, and is retried after a refresh like every data call).
+     */
+    async call(recipe, args = {}) {
+        return (await this.data('POST', '/call', { fn: recipe, args })).result;
+    }
+    /**
+     * Customers by name or email (two characters or more), or by id, so staff can find one and put
+     * a record under them. Only for a role the account lets look customers up in this app; anyone
+     * else gets a forbidden error. Name, email and phone only, at most 50.
+     */
+    async lookupCustomers(options) {
+        return (await this.data('POST', '/customers/lookup', options)).customers;
+    }
     /**
      * A list kept current: onRows gets the whole list (up to 200 rows, the query's order) at first
      * and again whenever a row in it is added, changed, removed, or stops being one this person may

package/package.json

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