@awesomate/hosting-mcp 0.49.0 → 0.51.0

package/dist/index.js

@@ -41217,6 +41217,7 @@ var TITLES = {
   awesomate_crm_apps: "Set up sign-in for your own apps",
   awesomate_crm_app_users: "Manage the people who sign in to your apps",
   awesomate_crm_assistant: "Set up the AI in your app's conversations",
+  awesomate_crm_hooks: "Send record changes to your n8n",
   awesomate_crm_email: "Draft an email to a contact list"
 };
 function annotate(name, kind) {
@@ -42886,13 +42887,14 @@ server.registerTool(
   "awesomate_crm_apps",
   {
     annotations: annotate("awesomate_crm_apps", MUTATING),
-    description: "The account's own apps (a client portal, a members' app) whose users sign in by email link and then read and change only what each kind's access rules allow them (awesomate_crm_kinds set_access). Pro and above to create or change; reading is every plan. action 'list': each app with its publishable key, allowed origins, sign-up mode and default role. action 'create' {name, allowed_origins, sign_up?, default_role?}: name appears in the sign-in email; allowed_origins are the exact origins the app runs on (https://portal.example.com; http://localhost:5173 for development; capacitor://localhost for the mobile shell), with no path and no wildcard; sign_up 'invite' (default: only people added with awesomate_crm_app_users) or 'open' (anyone who uses the email link gets the default role). action 'update' {app_id, ...any of those, status?}: status 'disabled' signs everyone out of that app and stops its server keys. The publishable key (pk_...) is not a secret: it goes in the app's browser code, with @awesomate/sdk. Never put the account's own token (amt_pat_...) in browser code. Confirm origins and sign-up mode with the user: open sign-up lets strangers in under the default role. SERVER KEYS (ak_...), for the app's own server or an n8n workflow, used with @awesomate/sdk createClient({ token: <key> }) or as a Bearer token on https://hub.awesomate.ai/api/sdk/v1/server: action 'keys' {app_id} lists them (never the secrets); 'create_key' {app_id, name, access: 'read'|'write', kinds?} makes one (kinds leaves it to those kinds, 'contact' to read contacts; leave it out for every kind) and returns the key ONCE: put it straight into the app server's environment (awesomate_app_set_env for an app hosted with us, or the n8n credential) and never into browser code, a repository or a reply to the user; 'revoke_key' {app_id, key_id} stops it at once. A key reads every attribute of an app kind, contacts only as you read them, and writes need Support Plus and above. Prefer the narrowest key: read unless the server writes, and only the kinds it uses.",
+    description: "The account's own apps (a client portal, a members' app) whose users sign in by email link and then read and change only what each kind's access rules allow them (awesomate_crm_kinds set_access). Pro and above to create or change; reading is every plan. action 'list': each app with its publishable key, allowed origins, sign-up mode and default role. action 'create' {name, allowed_origins, sign_up?, default_role?}: name appears in the sign-in email; allowed_origins are the exact origins the app runs on (https://portal.example.com; http://localhost:5173 for development; capacitor://localhost for the mobile shell), with no path and no wildcard; sign_up 'invite' (default: only people added with awesomate_crm_app_users) or 'open' (anyone who uses the email link gets the default role). action 'update' {app_id, ...any of those, status?}: status 'disabled' signs everyone out of that app and stops its server keys. The publishable key (pk_...) is not a secret: it goes in the app's browser code, with @awesomate/sdk. Never put the account's own token (amt_pat_...) in browser code. Confirm origins and sign-up mode with the user: open sign-up lets strangers in under the default role. action 'customer_lookup' {app_id, roles?}: which roles in that app may look customers up (name, email and phone, by search or id, with @awesomate/sdk lookupCustomers) and so put a record under any customer, not only themselves. Without roles it reads the setting; roles ['staff'] switches it on for staff; [] switches it off. Never the app's default role (the one customers sign in with): that would show every customer to every other customer, and the hub refuses it. Off until the owner asks for it. SERVER KEYS (ak_...), for the app's own server or an n8n workflow, used with @awesomate/sdk createClient({ token: <key> }) or as a Bearer token on https://hub.awesomate.ai/api/sdk/v1/server: action 'keys' {app_id} lists them (never the secrets); 'create_key' {app_id, name, access: 'read'|'write', kinds?} makes one (kinds leaves it to those kinds, 'contact' to read contacts; leave it out for every kind) and returns the key ONCE: put it straight into the app server's environment (awesomate_app_set_env for an app hosted with us, or the n8n credential) and never into browser code, a repository or a reply to the user; 'revoke_key' {app_id, key_id} stops it at once. A key reads every attribute of an app kind, contacts only as you read them, and writes need Support Plus and above. Prefer the narrowest key: read unless the server writes, and only the kinds it uses.",
     inputSchema: {
-      action: external_exports.enum(["list", "create", "update", "keys", "create_key", "revoke_key"]),
-      app_id: external_exports.string().max(48).optional().describe("update, keys, create_key, revoke_key: the app"),
+      action: external_exports.enum(["list", "create", "update", "keys", "create_key", "revoke_key", "customer_lookup"]),
+      app_id: external_exports.string().max(48).optional().describe("update, keys, create_key, revoke_key, customer_lookup: the app"),
       access: external_exports.enum(["read", "write"]).optional().describe("create_key"),
       kinds: external_exports.array(external_exports.string().max(41)).max(50).optional().describe("create_key: only these kinds (contact to read contacts); leave out for every kind"),
       key_id: external_exports.string().max(64).optional().describe("revoke_key: from keys"),
+      roles: external_exports.array(external_exports.string().max(31)).max(10).optional().describe("customer_lookup: the roles that may look customers up; [] switches it off; leave out to read"),
       name: external_exports.string().max(80).optional(),
       allowed_origins: external_exports.array(external_exports.string().max(200)).max(10).optional(),
       sign_up: external_exports.enum(["invite", "open"]).optional(),
@@ -42900,10 +42902,15 @@ server.registerTool(
       status: external_exports.enum(["active", "disabled"]).optional().describe("update only")
     }
   },
-  async ({ action, app_id, name, allowed_origins, sign_up, default_role, status, access, kinds, key_id }) => {
+  async ({ action, app_id, name, allowed_origins, sign_up, default_role, status, access, kinds, key_id, roles }) => {
     try {
       const cfg = requireConfig();
       if (action === "list") return textResult(await hubGet(cfg, "/api/my-crm/v1/apps"));
+      if (action === "customer_lookup") {
+        if (!app_id) return errorResult(new Error("customer_lookup needs app_id, from list."));
+        const path = `/api/my-crm/v1/apps/${encodeURIComponent(app_id)}/customer-lookup`;
+        return textResult(roles === void 0 ? await hubGet(cfg, path) : await hubPut(cfg, path, { roles }));
+      }
       if (action === "keys" || action === "create_key" || action === "revoke_key") {
         if (!app_id) return errorResult(new Error(`${action} needs app_id, from list.`));
         const keys = `/api/my-crm/v1/apps/${encodeURIComponent(app_id)}/keys`;
@@ -42992,6 +42999,39 @@ server.registerTool(
     }
   }
 );
+server.registerTool(
+  "awesomate_crm_hooks",
+  {
+    annotations: annotate("awesomate_crm_hooks", MUTATING),
+    description: "Send changes to an app's records to the account's own n8n: when a record of a named kind is created, updated or archived, the hub POSTs an event to a Webhook node on THEIR n8n (no other host is accepted), in order, at least once, retrying while n8n is down. Every writer counts: the app's people, its server key, Claude, a recipe, the assistant. Use it for 'when a job is requested, draft a quote', then write the result back with an app server key (awesomate_crm_apps create_key) from the same workflow. Event body: {id (stable: drop repeats), event: created|updated|archived, kind, record_id, changed: [attributes and links that changed], by, at, record (the record as it is when sent; null once archived), app}. Pro and above to change; reading is every plan. action 'list' {app_id}: each hook with delivered/missed counts and its last error. 'create' {app_id, name, url, kinds, events?}: url is the PRODUCTION webhook URL of an active workflow on their n8n (create and activate the workflow first with the awesomate_n8n tools); returns a secret ONCE: put it straight into an n8n Header Auth credential on that Webhook node (header X-Awesomate-Webhook-Secret), never into a reply. A new hook starts from now. 'update' {app_id, hook_id, name?, url?, kinds?, events?, enabled?}: enabled true retries at once. 'remove' {app_id, hook_id}. 'test' {app_id, hook_id}: one test event now ({event: 'test'}), and what n8n answered. Confirm the kinds and what the workflow will do with the user before creating one.",
+    inputSchema: {
+      action: external_exports.enum(["list", "create", "update", "remove", "test"]),
+      app_id: external_exports.string().max(48).describe("the app, from awesomate_crm_apps list"),
+      hook_id: external_exports.string().max(64).optional().describe("update, remove, test: from list"),
+      name: external_exports.string().max(80).optional(),
+      url: external_exports.string().max(500).optional().describe("create/update: the production URL of a Webhook node on the account's own n8n"),
+      kinds: external_exports.array(external_exports.string().max(41)).max(20).optional(),
+      events: external_exports.array(external_exports.enum(["created", "updated", "archived"])).max(3).optional().describe("default all three"),
+      enabled: external_exports.boolean().optional().describe("update only")
+    }
+  },
+  async ({ action, app_id, hook_id, name, url, kinds, events, enabled }) => {
+    try {
+      const cfg = requireConfig();
+      const path = `/api/my-crm/v1/apps/${encodeURIComponent(app_id)}/hooks`;
+      if (action === "list") return textResult(await hubGet(cfg, path));
+      const fields = Object.fromEntries(Object.entries({ name, url, kinds, events }).filter(([, v]) => v !== void 0));
+      if (action === "create") return textResult(await hubPost(cfg, path, fields));
+      if (!hook_id) return errorResult(new Error(`${action} needs hook_id, from list.`));
+      const one = `${path}/${encodeURIComponent(hook_id)}`;
+      if (action === "remove") return textResult(await hubDelete(cfg, one));
+      if (action === "test") return textResult(await hubPost(cfg, `${one}/test`, {}));
+      return textResult(await hubPatch(cfg, one, { ...fields, ...enabled === void 0 ? {} : { enabled } }));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
 var crmParam = external_exports.object({
   name: external_exports.string().max(41).describe("lower_case"),
   type: external_exports.enum(["text", "number", "date", "datetime", "boolean", "uuid", "text_list", "number_list"]).optional().describe("default text"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awesomate/hosting-mcp",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases",
   "license": "UNLICENSED",
   "type": "module",

package/skill/CHANGELOG.json

@@ -1,5 +1,21 @@
 {
   "versions": [
+    {
+      "version": "0.51.0",
+      "highlights": [
+        "Your app's staff can now find a customer and put a job under them, straight from the portal. Switch it on per app for the roles that need it (awesomate_crm_apps, customer_lookup). Pro and above",
+        "They see name, email and phone only, never a field you marked sensitive, and never the role your customers sign in with: customers still see only themselves"
+      ]
+    },
+    {
+      "version": "0.50.0",
+      "highlights": [
+        "Your n8n can now hear about your app's records (awesomate_crm_hooks): when a job is requested, changed or archived, a workflow runs straight away, with the record attached",
+        "Events arrive in order and keep coming back while n8n is down, so a quiet weekend doesn't lose anything. Each has an id, so a workflow can ignore a repeat",
+        "Only your own n8n can receive them, protected by a secret your Webhook node checks. Pair it with an app server key to write the result back, such as a drafted quote",
+        "New skill, awesomate-portals: ask Claude for a customer portal and it designs the records, who sees what, sign-in by email link and the page, step by step"
+      ]
+    },
     {
       "version": "0.49.0",
       "highlights": [

package/skill/awesomate-portals/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: awesomate-portals
+description: Build a portal or members' app on the account's own data with @awesomate/sdk. Customers sign in by email link and see only their own records, staff see everything, lists update live, and optionally an AI assistant answers in conversations. Use when the user says "customer portal", "client login", "members' area", "let my customers see their jobs / bookings / orders", "staff dashboard", "chat with customers", "portal", or wants people outside the business to sign in to something of theirs. Companion to awesomate-app-builder (hosting the page), awesomate-database and awesomate-n8n: same connection, same token.
+---
+
+# Awesomate Portals: people sign in and see their own records
+
+A portal is three things the account already has, put together: **kinds** (the app's own tables,
+in the account's own database), **access rules** on each kind (who sees and changes what, enforced
+by the database itself), and an **app** (where it runs, how people sign in). The page uses
+`@awesomate/sdk` straight from the browser. There is no app server to write.
+
+Work in plain words with the owner. They describe their business ("customers request jobs, we
+quote, they see the status"), you turn that into kinds and rules, show them the design in a
+sentence or two, and only then create anything. Kinds, rules and apps are part of their data,
+not scratch space.
+
+## 0. First, every time
+
+1. `awesomate_whoami`: everything below acts on that account. Fix the connection if the slug is
+   not the one the user means.
+2. `awesomate_get_context`: check the plan. **Sign-in for an app's people is Pro and above.**
+   Creating kinds and writing data is Support Plus and above. Reading is every plan. A 403
+   carries the upgrade path: relay it honestly, never retry it.
+
+## 1. Understand who signs in and what they do
+
+Ask, one or two at a time:
+- Who signs in? Usually **customers** (role `member`) and **staff** (role `staff`).
+- What does a customer see? ("their own jobs, and the messages on them")
+- What can a customer do? ("request a job, send a message")
+- What do staff do? ("see every job, set status and quote, reply")
+- Who may sign up: only people the owner adds (`invite`, the default and the safe choice), or
+  anyone with the link (`open`, everyone gets the default role)?
+
+## 2. Design the kinds
+
+`awesomate_crm_kinds {action:'define'}`. Typical portal:
+
+| Kind | Attributes | Links |
+|---|---|---|
+| `job` | `title` (text, required), `status` (choice), `quote` (money) | `customer` to `contact` |
+| `message` | `body` (long_text, required) | `job` to `job` (required) |
+
+- **Link the thing to the customer's contact.** That link is what "their own" means.
+- Mark an attribute `readable_by_ai` only when the owner wants Claude and AI assistants to see
+  it. Never for anything sensitive. App people see every attribute of a record they may read;
+  `readable_by_ai` is only about AI.
+- Show the owner the design ("A job has a title, a status and a quote, and belongs to a
+  customer. Messages hang off a job.") and get a yes first.
+
+## 3. Set the access rules
+
+`awesomate_crm_kinds {action:'set_access'}`. Rules are per kind and per role:
+`all`, `none`, `own` (records they created), or `linked:<path ending at a contact>`.
+
+```json
+job:     {"read": {"member": "linked:customer", "staff": "all"}, "write": {"member": "linked:customer", "staff": "all"}}
+message: {"read": {"member": "linked:job.customer", "staff": "all"}, "write": {"member": "linked:job.customer", "staff": "all"}}
+```
+
+- A role with no rule gets nothing. The database applies these to every read and every write, so
+  a mistake in the page can never show anyone more than their role allows.
+- A person can only link a record to something they can see: a customer can point a job at their
+  own contact, never someone else's.
+- **Staff putting a job under a customer** needs one more switch, per app: app people read no
+  contacts but their own, so by default staff can only link to themselves. Ask the owner, then
+  `awesomate_crm_apps {action:'customer_lookup', app_id, roles:['staff']}`. Those roles can then
+  search customers (name, email, phone; never a sensitive field) and link a record to any of
+  them. Never the app's default role (the one customers sign in with); the hub refuses it.
+
+## 4. Create the app and add people
+
+1. `awesomate_crm_apps {action:'create', name, allowed_origins, sign_up}`. `allowed_origins` are
+   the exact addresses the page runs on (`https://portal.example.com.au`, plus
+   `http://localhost:5173` while building). The name appears in the sign-in email. The answer
+   has the **publishable key** (`pk_...`): it is not a secret and goes in the page.
+2. `awesomate_crm_app_users {action:'add', email, role}` for each person. A customer is matched to
+   their contact by email. Staff get `role: 'staff'`. No email is sent; they ask for a link on the
+   page.
+
+## 5. Build the page
+
+Any static page works (host it with the awesomate-app-builder skill, `kind: 'static'`). The SDK
+loads from a CDN, or from npm in a Vite app:
+
+```html
+<script type="module">
+import { createAppClient } from 'https://cdn.jsdelivr.net/npm/@awesomate/sdk@0.8/+esm';
+const app = createAppClient({ publishableKey: 'pk_...' });
+
+// The email link signs them in by itself (also when it opens in a tab already on this page).
+app.auth.onChange((user) => (user ? showPortal(user) : showSignIn()));
+app.auth.onSignInError((err) => showMessage(err.message));
+const user = await app.auth.user();
+user ? showPortal(user) : showSignIn();
+
+// Sign-in form
+await app.auth.signInWithLink(email, { redirectTo: location.href });
+
+// Data: the same calls for everyone; the rules decide what each person gets.
+const stop = app.live('job', { orderBy: ['created_at', 'desc'], limit: 100 }, (rows) => renderJobs(rows));
+await app.write('job', { title: 'Leaking tap', status: 'open' }, { links: { customer: user.contact_id } });
+await app.write('message', { body }, { links: { job: jobId } });
+
+// Staff, once customer_lookup is on for their role: find a customer, file a job for them.
+const [customer] = await app.lookupCustomers({ q: 'jo' });
+await app.write('job', { title: 'Gutters', status: 'open' }, { links: { customer: customer.id } });
+</script>
+```
+
+- Choose the view from `user.role` (`staff` sees everything and edit controls; `member` sees
+  their own records and a request form).
+- `live()` keeps a list current: anything changed anywhere (staff, Claude, n8n) shows at once.
+- To test customer and staff side by side in one browser, give the staff view its own
+  `storageKey` (for example when the address has `?staff`).
+- Serve the HTML with `Cache-Control: no-cache` (an `.htaccess` rule on Awesomate hosting), or
+  people keep an old copy of the page after you change it.
+- **Never put the account's token (`amt_pat_...`) or a server key (`ak_...`) in a page.** Only
+  the `pk_` key belongs in the browser.
+
+## 6. Optional: an AI in the conversations
+
+`awesomate_crm_assistant` adds an assistant (for example "Bree") to the message threads. Each
+conversation is Off (people only, the default), Draft (a suggested reply only staff see) or Auto
+(she replies, marked as AI, when she is sure). She reads as the customer she is answering, so
+the access rules bound her, and only `readable_by_ai` attributes reach her. The tool description
+lists the two staff-only kinds it needs (`assistant_thread`, `assistant_draft`) and the
+`from_assistant` attribute on the message kind. Give her a published, public, strict Knowledge
+agent (awesomate-knowledge skill) so she can answer questions about the business. Confirm the
+name and the default mode with the owner: switching it on lets an AI reply to their customers.
+
+## 7. Optional: automation
+
+- **Server key** (`awesomate_crm_apps {action:'create_key'}`): for the app's own server or an n8n
+  workflow to read and write records. Read or write, only the kinds it needs. Shown once: put it
+  straight into the server's environment or an n8n credential, never in a reply or a repository.
+- **Record events** (`awesomate_crm_hooks`): when a record of a kind is created, updated or
+  archived, the account's own n8n gets an event at once. Build and activate the workflow first
+  (awesomate-n8n skill), then create the hook with its production webhook URL and put the secret
+  in the Webhook node's Header Auth credential. Use `test` to check it. Example: a job is
+  requested, the workflow drafts a quote and writes it back with a write key for `job`.
+
+## 8. Check it works
+
+- Sign in as a customer and as staff (two windows). The customer must not see another
+  customer's records; try it.
+- Write as one, watch the other update live.
+- With an assistant: set one job to Draft, ask a question as the customer, see the draft as staff.
+- Tell the owner what you built in their terms, and what is not built yet.