@awesomate/hosting-mcp 0.49.0 → 0.50.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) {
@@ -42992,6 +42993,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.50.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,14 @@
 {
   "versions": [
+    {
+      "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,144 @@
+---
+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.
+- **Known gap:** staff cannot yet put a job under a customer from the portal (they can only link
+  to contacts they can see, and app people do not read the contact list). Until that lands, the
+  owner creates or reassigns jobs for customers through Claude (`awesomate_crm_write`).
+
+## 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.6/+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 } });
+</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.