@awesomate/sdk 0.6.0 → 0.7.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

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. */

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: {

package/package.json

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