@rubytech/create-realagent-code 0.1.24 → 0.1.27

package/payload/platform/plugins/loop/mcp/src/lib/neo4j.ts

@@ -0,0 +1,51 @@
+import neo4j, { Driver, Session } from "neo4j-driver";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+let driver: Driver | null = null;
+
+function readPassword(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+
+  const passwordFile = resolve(
+    process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../.."),
+    "config/.neo4j-password"
+  );
+
+  try {
+    return readFileSync(passwordFile, "utf-8").trim();
+  } catch {
+    throw new Error(
+      `Neo4j password not found. Expected at ${passwordFile} or in NEO4J_PASSWORD env var.`
+    );
+  }
+}
+
+export function getDriver(): Driver {
+  if (!driver) {
+    // Task 580: NEO4J_URI must be explicit. Silent default to :7687 was the
+    // vector for Task 577's orphan data in Maxy's DB from a realagent install.
+    const uri = process.env.NEO4J_URI;
+    if (!uri) {
+      throw new Error(
+        "[loop] NEO4J_URI unset — refusing to default to bolt://localhost:7687 (Task 580)"
+      );
+    }
+    const user = process.env.NEO4J_USER ?? "neo4j";
+    const password = readPassword();
+    console.error(`[loop] resolved neo4j_uri=${uri}`);
+    driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+  }
+  return driver;
+}
+
+export function getSession(): Session {
+  return getDriver().session();
+}
+
+export async function closeDriver(): Promise<void> {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+}

package/payload/platform/plugins/loop/mcp/src/tools/customer-preferences.ts

@@ -0,0 +1,66 @@
+import { loopGet, loopPost, withTeamKey } from "../lib/loop-api.js";
+
+type PreferencesAction = "read" | "write";
+
+// ─── Loop API V2: /customer/preferences/{personCode} ───────────
+// Uses personCode (encoded), NOT raw personId from /people.
+// personCode is obtained from marketing context (auto-responder,
+// matching), not from standard /people endpoints.
+// GET returns preferences object; POST updates it.
+// ────────────────────────────────────────────────────────────────
+interface LoopCustomerPreferences {
+  personCode?: number;
+  preferences?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+interface LoopBooleanResponse {
+  success?: boolean;
+  [key: string]: unknown;
+}
+
+export async function customerPreferences(params: {
+  accountId: string;
+  teamName: string;
+  personCode: number;
+  action: PreferencesAction;
+  preferences?: Record<string, unknown>;
+}): Promise<string> {
+  const { accountId, teamName, personCode, action } = params;
+
+  if (action === "read") {
+    const result = await withTeamKey<LoopCustomerPreferences>(
+      accountId, teamName, "customer", "loop-customer-preferences",
+      async (apiKey) => {
+        return loopGet<LoopCustomerPreferences>(
+          apiKey, `/customer/preferences/${personCode}`,
+          "loop-customer-preferences", teamName
+        );
+      }
+    );
+
+    if (!result || (Array.isArray(result) && result.length === 0)) {
+      return `No preferences found for person ${personCode} via team "${teamName}".`;
+    }
+    return JSON.stringify(result, null, 2);
+  }
+
+  if (action === "write") {
+    if (!params.preferences) {
+      throw new Error("preferences object is required when action is 'write'.");
+    }
+
+    await withTeamKey<LoopBooleanResponse>(
+      accountId, teamName, "customer", "loop-customer-preferences",
+      async (apiKey) => {
+        return loopPost<LoopBooleanResponse>(
+          apiKey, `/customer/preferences/${personCode}`,
+          params.preferences!, "loop-customer-preferences", teamName
+        );
+      }
+    );
+    return `Preferences updated for person ${personCode} via team "${teamName}".`;
+  }
+
+  throw new Error(`Unknown action: ${action}. Use "read" or "write".`);
+}

package/payload/platform/plugins/loop/mcp/src/tools/feedback.ts

@@ -0,0 +1,86 @@
+import {
+  loopGet,
+  loopPost,
+  withTeamKey,
+} from "../lib/loop-api.js";
+
+type Department = "sales" | "lettings";
+
+// ─── Loop API V2: /feedback/residential/{dept}/viewings/{id} ───
+// Returns null when no feedback has been submitted. Exact schema
+// not verified — endpoint returned null for all test viewings.
+// Fields below are the documented schema; the [key: string]: unknown
+// catch-all ensures any actual response fields are accessible.
+// ────────────────────────────────────────────────────────────────
+interface LoopViewingFeedback {
+  viewingId?: number;
+  propertyAddress?: string;
+  date?: string;
+  attendeeName?: string;
+  feedback?: string;
+  rating?: number;
+  status?: string;
+  [key: string]: unknown;
+}
+
+interface LoopBooleanResponse {
+  success?: boolean;
+  [key: string]: unknown;
+}
+
+export async function feedbackGet(params: {
+  accountId: string;
+  teamName: string;
+  viewingId: number;
+  department: Department;
+}): Promise<string> {
+  const { accountId, teamName, viewingId, department } = params;
+
+  const result = await withTeamKey<LoopViewingFeedback>(
+    accountId,
+    teamName,
+    "feedback",
+    "loop-feedback-get",
+    async (apiKey) => {
+      const path = `/feedback/residential/${department}/viewings/${viewingId}`;
+      return loopGet<LoopViewingFeedback>(apiKey, path, "loop-feedback-get", teamName);
+    }
+  );
+
+  if (!result || (Array.isArray(result) && result.length === 0)) {
+    return `No feedback found for viewing ${viewingId} (${department}) via team "${teamName}".`;
+  }
+
+  const f = result;
+  const lines = [`**Feedback for viewing ${viewingId}**`];
+  if (f.propertyAddress) lines.push(`Property: ${f.propertyAddress}`);
+  if (f.date) lines.push(`Date: ${f.date}`);
+  if (f.attendeeName) lines.push(`Attendee: ${f.attendeeName}`);
+  if (f.rating != null) lines.push(`Rating: ★${f.rating}`);
+  if (f.status) lines.push(`Status: ${f.status}`);
+  if (f.feedback) lines.push(`Feedback: ${f.feedback}`);
+  return lines.join("\n");
+}
+
+export async function feedbackSubmit(params: {
+  accountId: string;
+  teamName: string;
+  viewingId: number;
+  department: Department;
+  feedback: string;
+}): Promise<string> {
+  const { accountId, teamName, viewingId, department, feedback } = params;
+
+  await withTeamKey<LoopBooleanResponse>(
+    accountId,
+    teamName,
+    "feedback",
+    "loop-feedback-submit",
+    async (apiKey) => {
+      const path = `/feedback/residential/${department}/viewings/${viewingId}/feedback`;
+      return loopPost<LoopBooleanResponse>(apiKey, path, { result: feedback }, "loop-feedback-submit", teamName);
+    }
+  );
+
+  return `Feedback submitted for viewing ${viewingId} (${department}) via team "${teamName}".`;
+}

package/payload/platform/plugins/loop/mcp/src/tools/key-deregister.ts

@@ -0,0 +1,27 @@
+import { getSession } from "../lib/neo4j.js";
+
+export async function keyDeregister(params: {
+  teamName: string;
+  accountId: string;
+}): Promise<void> {
+  const { teamName, accountId } = params;
+
+  const session = getSession();
+  try {
+    const result = await session.run(
+      `MATCH (k:LoopTeamKey {teamName: $teamName, accountId: $accountId})
+       DELETE k
+       RETURN count(k) AS deleted`,
+      { teamName, accountId }
+    );
+
+    const deleted = result.records[0]?.get("deleted")?.toNumber?.() ?? 0;
+    if (deleted === 0) {
+      throw new Error(`Team "${teamName}" not found.`);
+    }
+  } finally {
+    await session.close();
+  }
+
+  console.error(`[loop] key-deregister team=${teamName} account=${accountId}`);
+}

package/payload/platform/plugins/loop/mcp/src/tools/key-list.ts

@@ -0,0 +1,19 @@
+import { loadTeamKeys } from "../lib/loop-api.js";
+
+export async function keyList(params: {
+  accountId: string;
+}): Promise<string> {
+  const keys = await loadTeamKeys(params.accountId);
+
+  if (keys.length === 0) {
+    return "No Loop teams registered. Use loop-key-register to add team API keys.";
+  }
+
+  const lines = keys.map((k) => {
+    const perms = k.permissions.join(", ");
+    const addr = k.teamAddress ? ` — ${k.teamAddress}` : "";
+    return `- **${k.teamName}**${addr} (permissions: ${perms}, registered: ${k.createdAt})`;
+  });
+
+  return `${keys.length} Loop team(s) registered:\n\n${lines.join("\n")}`;
+}

package/payload/platform/plugins/loop/mcp/src/tools/key-register.ts

@@ -0,0 +1,95 @@
+import { getSession } from "../lib/neo4j.js";
+import { encrypt } from "../lib/crypto.js";
+import { loopGet, LoopApiError } from "../lib/loop-api.js";
+
+interface LoopTeamResponse {
+  id?: string;
+  name?: string;
+  address?: string;
+  agentId?: string;
+  [key: string]: unknown;
+}
+
+const ALL_PERMISSIONS = ["properties", "people", "viewings", "feedback", "team", "marketing", "customer", "supplier"];
+
+export async function keyRegister(params: {
+  teamName: string;
+  apiKey: string;
+  accountId: string;
+  permissions?: string[];
+}): Promise<{ warning?: string }> {
+  const { teamName, apiKey, accountId } = params;
+  const permissions = params.permissions ?? ALL_PERMISSIONS;
+
+  // Validate key against Loop API — try /team endpoint
+  let teamAddress = "";
+  let agentId = "";
+  let warning: string | undefined;
+
+  try {
+    const teamData = await loopGet<LoopTeamResponse>(
+      apiKey,
+      "/team",
+      "loop-key-register",
+      teamName
+    );
+
+    if (Array.isArray(teamData) && teamData.length === 0) {
+      // 204 was converted to empty array — ambiguous scope
+      warning =
+        "Key accepted but Loop returned no team data (204). " +
+        "Verify the key's scope in Loop's dashboard.";
+    } else if (teamData && typeof teamData === "object") {
+      teamAddress = String(teamData.address ?? "");
+      agentId = String(teamData.agentId ?? teamData.id ?? "");
+    }
+  } catch (err) {
+    if (err instanceof LoopApiError && err.status === 401) {
+      throw new Error(
+        `Loop API rejected the key for team "${teamName}" (HTTP 401). ` +
+        `Check that the key is valid and not expired.`
+      );
+    }
+    // Network/timeout errors — still reject, key is unverified
+    throw new Error(
+      `Could not validate key against Loop API: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+
+  // Encrypt and store
+  const encryptedKey = encrypt(apiKey);
+  const now = new Date().toISOString();
+
+  const writeSession = getSession();
+  try {
+    await writeSession.run(
+      `CREATE INDEX loop_team_key_account_team IF NOT EXISTS
+       FOR (k:LoopTeamKey) ON (k.accountId, k.teamName)`,
+      {}
+    );
+
+    const mergeResult = await writeSession.run(
+      `MERGE (k:LoopTeamKey {teamName: $teamName, accountId: $accountId})
+       ON CREATE SET
+         k.encryptedKey = $encryptedKey,
+         k.teamAddress = $teamAddress,
+         k.agentId = $agentId,
+         k.permissions = $permissions,
+         k.createdAt = $now,
+         k.updatedAt = $now
+       RETURN k.createdAt = $now AS created`,
+      { teamName, encryptedKey, teamAddress, agentId, accountId, permissions, now }
+    );
+
+    const created = mergeResult.records[0]?.get("created");
+    if (!created) {
+      throw new Error(`Team "${teamName}" is already registered for this account.`);
+    }
+  } finally {
+    await writeSession.close();
+  }
+
+  console.error(`[loop] key-register team=${teamName} account=${accountId}`);
+
+  return { warning };
+}

package/payload/platform/plugins/loop/mcp/src/tools/marketing-enquiry.ts

@@ -0,0 +1,113 @@
+import { loopGet, loopPost, loopPut, withTeamKey } from "../lib/loop-api.js";
+
+type EnquiryAction = "seller-enquiry" | "autoresponder-get" | "autoresponder-answers" | "autoresponder-details" | "autoresponder-refer";
+
+// ─── Loop API V2: Marketing Enquiry Endpoints ──────────────────
+// POST /marketing/enquiries/seller — submit seller enquiry
+// GET /marketing/enquiries/auto-responder/{id}/{key} — read enquiry
+// PUT .../auto-responder/{id}/answers/{key} — submit answers
+// PUT .../auto-responder/{id}/details/{key} — update details
+// PUT .../auto-responder/{id}/refer/{key} — refer enquiry
+// Note: auto-responder uses personCode + key (UUID), not personId
+// ────────────────────────────────────────────────────────────────
+interface LoopBooleanResponse {
+  success?: boolean;
+  [key: string]: unknown;
+}
+
+interface LoopAutoResponderDetails {
+  id?: number;
+  questions?: unknown[];
+  enquiryDetails?: unknown;
+  [key: string]: unknown;
+}
+
+export async function marketingEnquiry(params: {
+  accountId: string;
+  teamName: string;
+  action: EnquiryAction;
+  // For seller-enquiry
+  sellerEnquiryData?: Record<string, unknown>;
+  // For autoresponder actions
+  autoResponderId?: number;
+  autoResponderKey?: string;
+  // For autoresponder-answers
+  answers?: unknown[];
+  // For autoresponder-details
+  details?: Record<string, unknown>;
+}): Promise<string> {
+  const { accountId, teamName, action } = params;
+
+  if (action === "seller-enquiry") {
+    await withTeamKey<LoopBooleanResponse>(
+      accountId, teamName, "marketing", "loop-marketing-enquiry",
+      async (apiKey) => {
+        return loopPost<LoopBooleanResponse>(
+          apiKey, "/marketing/enquiries/seller",
+          params.sellerEnquiryData ?? {}, "loop-marketing-enquiry", teamName
+        );
+      }
+    );
+    return `Seller enquiry submitted via team "${teamName}".`;
+  }
+
+  if (!params.autoResponderId || !params.autoResponderKey) {
+    throw new Error("autoResponderId and autoResponderKey are required for autoresponder actions.");
+  }
+  const id = params.autoResponderId;
+  const key = params.autoResponderKey;
+
+  if (action === "autoresponder-get") {
+    const result = await withTeamKey<LoopAutoResponderDetails>(
+      accountId, teamName, "marketing", "loop-marketing-enquiry",
+      async (apiKey) => {
+        return loopGet<LoopAutoResponderDetails>(
+          apiKey, `/marketing/enquiries/auto-responder/${id}/${key}`,
+          "loop-marketing-enquiry", teamName
+        );
+      }
+    );
+    return JSON.stringify(result, null, 2);
+  }
+
+  if (action === "autoresponder-answers") {
+    await withTeamKey<LoopBooleanResponse>(
+      accountId, teamName, "marketing", "loop-marketing-enquiry",
+      async (apiKey) => {
+        return loopPut<LoopBooleanResponse>(
+          apiKey, `/marketing/enquiries/auto-responder/${id}/answers/${key}`,
+          params.answers ?? [], "loop-marketing-enquiry", teamName
+        );
+      }
+    );
+    return `Auto-responder answers submitted for enquiry ${id} via team "${teamName}".`;
+  }
+
+  if (action === "autoresponder-details") {
+    await withTeamKey<LoopBooleanResponse>(
+      accountId, teamName, "marketing", "loop-marketing-enquiry",
+      async (apiKey) => {
+        return loopPut<LoopBooleanResponse>(
+          apiKey, `/marketing/enquiries/auto-responder/${id}/details/${key}`,
+          params.details ?? {}, "loop-marketing-enquiry", teamName
+        );
+      }
+    );
+    return `Auto-responder details updated for enquiry ${id} via team "${teamName}".`;
+  }
+
+  if (action === "autoresponder-refer") {
+    await withTeamKey<LoopBooleanResponse>(
+      accountId, teamName, "marketing", "loop-marketing-enquiry",
+      async (apiKey) => {
+        return loopPut<LoopBooleanResponse>(
+          apiKey, `/marketing/enquiries/auto-responder/${id}/refer/${key}`,
+          {}, "loop-marketing-enquiry", teamName
+        );
+      }
+    );
+    return `Enquiry ${id} referred via team "${teamName}".`;
+  }
+
+  throw new Error(`Unknown action: ${action}`);
+}

package/payload/platform/plugins/loop/mcp/src/tools/marketing-match-batch.ts

@@ -0,0 +1,53 @@
+import {
+  aggregateAcrossTeams,
+  formatAggregationResult,
+  loopPut,
+} from "../lib/loop-api.js";
+
+// ─── Loop API V2: PUT /marketing/matching/other-matches ─────────
+// Request body: array of property IDs
+// Response: array of matching property summaries
+// Schema not verified via curl (depends on matching state)
+// ────────────────────────────────────────────────────────────────
+interface LoopMatchingSummary {
+  id?: number;
+  address?: string;
+  price?: number;
+  type?: string;
+  bedrooms?: number;
+  [key: string]: unknown;
+}
+
+type Department = "sales" | "lettings";
+
+export async function marketingMatchBatch(params: {
+  accountId: string;
+  propertyIds: number[];
+  department: Department;
+  teamName?: string;
+}): Promise<string> {
+  const { accountId, propertyIds, department, teamName } = params;
+
+  const result = await aggregateAcrossTeams<LoopMatchingSummary>(
+    accountId,
+    "marketing",
+    "loop-marketing-match-batch",
+    async (apiKey, team) => {
+      const prefix = department === "lettings" ? "/marketing/rentals" : "/marketing";
+      const path = `${prefix}/matching/other-matches`;
+      const data = await loopPut<LoopMatchingSummary[]>(apiKey, path, propertyIds, "loop-marketing-match-batch", team);
+      return Array.isArray(data) ? data : [];
+    },
+    { teamName }
+  );
+
+  return formatAggregationResult(
+    result,
+    (p) => {
+      const price = p.price ? ` — £${p.price.toLocaleString("en-GB")}` : "";
+      const beds = p.bedrooms ? ` ${p.bedrooms}bed` : "";
+      return `- ${p.address ?? "Unknown"}${price}${beds}`;
+    },
+    "matching properties"
+  );
+}

package/payload/platform/plugins/loop/mcp/src/tools/marketing-match-request.ts

@@ -0,0 +1,42 @@
+import { loopPost, withTeamKey } from "../lib/loop-api.js";
+
+type Department = "sales" | "lettings";
+type MatchAction = "viewing" | "information" | "callback";
+
+// ─── Loop API V2: POST /marketing/matching/{id}/{action} ────────
+// Actions: viewing, information, callback
+// Request body: { name?, email?, phone?, message? }
+// Response: boolean success
+// ────────────────────────────────────────────────────────────────
+interface LoopBooleanResponse {
+  success?: boolean;
+  [key: string]: unknown;
+}
+
+export async function marketingMatchRequest(params: {
+  accountId: string;
+  teamName: string;
+  propertyId: number;
+  department: Department;
+  action: MatchAction;
+  name?: string;
+  email?: string;
+  phone?: string;
+  message?: string;
+}): Promise<string> {
+  const { accountId, teamName, propertyId, department, action, ...body } = params;
+
+  await withTeamKey<LoopBooleanResponse>(
+    accountId,
+    teamName,
+    "marketing",
+    "loop-marketing-match-request",
+    async (apiKey) => {
+      const prefix = department === "lettings" ? "/marketing/rentals" : "/marketing";
+      const path = `${prefix}/matching/${propertyId}/${action}`;
+      return loopPost<LoopBooleanResponse>(apiKey, path, body, "loop-marketing-match-request", teamName);
+    }
+  );
+
+  return `${action} request submitted for matching property ${propertyId} (${department}) via team "${teamName}".`;
+}

package/payload/platform/plugins/loop/mcp/src/tools/marketing-match.ts

@@ -0,0 +1,84 @@
+import {
+  aggregateAcrossTeams,
+  formatAggregationResult,
+  loopGet,
+} from "../lib/loop-api.js";
+
+// ─── Loop API V2: /marketing/matching/{id} ─────────────────────
+// Returned HTTP 500 for test property 895155 — may require
+// publishedToMatching: true. Exact response schema not verified.
+// Fields below are from Swagger docs; [key: string]: unknown
+// ensures any actual response fields are accessible.
+// ────────────────────────────────────────────────────────────────
+interface LoopMatchingProperty {
+  id?: number;
+  address?: string;
+  price?: number;
+  type?: string;
+  bedrooms?: number;
+  status?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
+interface LoopMatchingTeamProfile {
+  name?: string;
+  address?: string;
+  phone?: string;
+  email?: string;
+  logoUrl?: string;
+  [key: string]: unknown;
+}
+
+type Department = "sales" | "lettings";
+
+export async function marketingMatchDetail(params: {
+  accountId: string;
+  propertyId: number;
+  department: Department;
+  includeTeamProfile?: boolean;
+  teamName?: string;
+}): Promise<string> {
+  const { accountId, propertyId, department, includeTeamProfile = false, teamName } = params;
+
+  const result = await aggregateAcrossTeams<LoopMatchingProperty>(
+    accountId,
+    "marketing",
+    "loop-marketing-match",
+    async (apiKey, team) => {
+      const prefix = department === "lettings" ? "/marketing/rentals" : "/marketing";
+      const path = `${prefix}/matching/${propertyId}`;
+      const data = await loopGet<LoopMatchingProperty>(apiKey, path, "loop-marketing-match", team);
+      if (data && typeof data === "object" && !Array.isArray(data)) {
+        if (includeTeamProfile) {
+          const profilePath = `${prefix}/matching/${propertyId}/team-profile`;
+          const profile = await loopGet<LoopMatchingTeamProfile>(apiKey, profilePath, "loop-marketing-match", team).catch(() => null);
+          if (profile) {
+            (data as Record<string, unknown>)._teamProfile = profile;
+          }
+        }
+        return [data];
+      }
+      return [];
+    },
+    { teamName }
+  );
+
+  return formatAggregationResult(
+    result,
+    (p) => {
+      const lines = [`**${p.address ?? "Unknown address"}**`];
+      if (p.price) lines.push(`Price: £${p.price.toLocaleString("en-GB")}`);
+      if (p.type) lines.push(`Type: ${p.type}`);
+      if (p.bedrooms) lines.push(`Bedrooms: ${p.bedrooms}`);
+      if (p.status) lines.push(`Status: ${p.status}`);
+      if (p.description) lines.push(`\n${p.description}`);
+      const profile = (p as Record<string, unknown>)._teamProfile as LoopMatchingTeamProfile | undefined;
+      if (profile) {
+        lines.push(`\n**Team:** ${profile.name ?? ""} — ${profile.address ?? ""} | ${profile.phone ?? ""} | ${profile.email ?? ""}`);
+      }
+      return lines.join("\n");
+    },
+    "matching property details"
+  );
+}