@awesomate/sdk 0.6.0 → 0.8.0

package/README.md

@@ -79,6 +79,26 @@ Every failure is an `AwesomateError` with a `code`: `unauthenticated`, `forbidde
 The token is your account's hosting token. Use it in a server, a script or a scheduled job, never
 in a browser. For a browser, sign your app's own users in (below).
 
+## Your app's server: a key of its own
+
+An app's own server, or an n8n workflow, should not carry the account's token. Give it a server
+key instead: Claude makes one with `awesomate_crm_apps` (`create_key`), read or write, for every
+kind or only the ones it names. The key is shown once; put it in the server's environment.
+
+```ts
+const db = createClient({ token: process.env.AWESOMATE_APP_KEY! }); // ak_...
+const { rows } = await db.query('job', { where: { status: 'booked' } });
+await db.write('job', { status: 'done' }, { id: rows[0].id });
+await db.call('book_job', { customer, title: 'Gutter clean', status: 'booked' });
+```
+
+A key reads and writes records and runs saved queries and recipes, only for its kinds (a recipe
+that writes anything else is refused). It reads every attribute of an app kind, and the contact
+list only as Claude does. Writes need Support Plus and above. It cannot change kinds, rules,
+queries or recipes, and it never works from a browser. Revoking a key stops it at once; switching
+the app off stops all of them. From n8n, send it as `Authorization: Bearer ak_...` to
+`https://hub.awesomate.ai/api/sdk/v1/server/rows/query` (and `/call`, `/queries/<key>/run`).
+
 ## Your app's users sign in (Pro and above)
 
 Set the app up first (Claude Code: `awesomate_crm_apps`): its name, the origins it runs on, and
@@ -126,6 +146,20 @@ 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.
+
 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

@@ -22,7 +22,7 @@
  * 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.6.0";
+export declare const VERSION = "0.7.0";
 /** Augmented by the generated awesomate.d.ts, so each kind's rows are typed. */
 export interface Kinds {
 }
@@ -143,7 +143,11 @@ export declare class AwesomateError extends Error {
     serverCode?: string | undefined);
 }
 export interface ClientOptions {
-    /** The account's hosting token (amt_pat_...) with crm:read. */
+    /**
+     * The account's hosting token (amt_pat_...) with crm:read, or an app's server key (ak_...) from
+     * the account's apps. A key reads and writes records and runs saved queries and recipes, for the
+     * kinds it was made for; changing kinds, queries or recipes needs the account's token.
+     */
     token: string;
     baseUrl?: string;
     fetch?: typeof fetch;
@@ -152,6 +156,8 @@ export declare class AwesomateClient {
     private readonly opts;
     private readonly base;
     private readonly doFetch;
+    /** An app key talks to its own routes, which carry only what a key may do. */
+    private readonly appKey;
     constructor(opts: ClientOptions);
     private request;
     /** The kinds this token can read, their columns, operators and examples. */
@@ -364,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;
@@ -479,6 +492,16 @@ 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>;
+    /**
+     * 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

@@ -22,7 +22,7 @@
  * queries works on every plan; writing app data (kinds, records, saved queries, recipes) needs
  * crm:write, Support Plus and above.
  */
-export const VERSION = '0.6.0';
+export const VERSION = '0.7.0';
 const DEFAULT_BASE = 'https://hub.awesomate.ai';
 const ERROR_CODES = ['unauthenticated', 'forbidden', 'not_found', 'validation', 'consent_blocked', 'rate_limited', 'conflict', 'unavailable'];
 export class AwesomateError extends Error {
@@ -58,20 +58,37 @@ function errorCode(status, server) {
         return 'not_found';
     return 'unavailable';
 }
+const ACCOUNT = '/api/my-crm/v1';
+const KEY_ROUTES = [
+    ['GET', /^\/rows\/schema$/], ['POST', /^\/rows\/query$/], ['GET', /^\/rows\/[^/]+\/[^/?]+(\?.*)?$/], ['POST', /^\/call$/],
+    ['GET', /^\/queries$/], ['POST', /^\/queries\/[^/]+\/run$/], ['GET', /^\/recipes$/],
+];
+/** The same call on an app key's routes, or a clear refusal for what only the account may do. */
+function keyPath(method, path) {
+    const rest = path.startsWith(ACCOUNT) ? path.slice(ACCOUNT.length) : path;
+    if (KEY_ROUTES.some(([m, re]) => m === method && re.test(rest)))
+        return `/api/sdk/v1/server${rest}`;
+    throw new AwesomateError('forbidden', 'An app key reads and writes records and runs saved queries and recipes. This needs the account\'s token.', 0);
+}
 export class AwesomateClient {
     opts;
     base;
     doFetch;
+    /** An app key talks to its own routes, which carry only what a key may do. */
+    appKey;
     constructor(opts) {
         this.opts = opts;
         if (!opts?.token)
-            throw new Error('createClient needs a token (the account\'s hosting token with crm:read).');
+            throw new Error('createClient needs a token: the account\'s hosting token, or an app\'s server key (ak_...).');
+        this.appKey = opts.token.startsWith('ak_');
         this.base = (opts.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, '');
         this.doFetch = opts.fetch ?? globalThis.fetch;
         if (!this.doFetch)
             throw new Error('No fetch available: use Node 18 or later, or pass fetch.');
     }
     async request(method, path, body, retry = true) {
+        if (this.appKey)
+            path = keyPath(method, path);
         const res = await this.doFetch(`${this.base}${path}`, {
             method,
             headers: {
@@ -497,6 +514,14 @@ export class AwesomateAppClient {
     async archive(kind, id) {
         await this.data('POST', '/call', { fn: 'archive_record', args: { kind, id } });
     }
+    /**
+     * 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.6.0",
+  "version": "0.8.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",