Website builders

type AskResult = {
  url: string;
  name: string;
  description: string;
  schema_object: { image?: string };
};

/** Searches one broker's published listings. */
export async function searchBrokerListings(brokerHost: string, sentence: string): Promise<AskResult[]> {
  const params = new URLSearchParams({ query: sentence });
  const response = await fetch(`https://${brokerHost}/ask?${params}`);

  if (response.status === 429) throw new Error('Search is busy. Try again in a minute.');
  if (!response.ok) throw new Error(`Search failed with status ${response.status}.`);

  const { results } = (await response.json()) as { results: AskResult[] };
  return results;
}

// Usage:
// const results = await searchBrokerListings('alice.matchai.co', '3 bedroom condo under 600k');
// Show result.name and result.description, and link each card to result.url.

export type BrokerListing = {
  id: string;
  title: string;
  url: string;
  priceText: string | null;
  status: 'available' | 'sold' | 'rented';
  bedrooms: number | null;
  bathrooms: number | null;
  city: string | null;
  image: string | null;
  updatedAt: string;
};

/** The broker's public profile and up to 10 available listings. */
export async function currentListings(username: string): Promise<BrokerListing[]> {
  const response = await fetch('https://matchai.co/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Accept: 'application/json, text/event-stream',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: { name: 'get_professional', arguments: { username } },
    }),
  });

  const { result } = await response.json();
  if (result.isError) throw new Error(result.content[0].text);
  return result.structuredContent.listings;
}

type Known = Map<string, string>; // listing url -> the lastmod you stored

export type ListingFacts = {
  url: string;
  name: string | null;
  price: number | null;
  currency: string | null;
  availability: string | null; // for example https://schema.org/InStock or https://schema.org/SoldOut
  bedrooms: number | null;
  bathrooms: number | null;
  modified: string | null;
};

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/** Returns the listings that changed since your last sync, and the urls that are gone. */
export async function syncBroker(host: string, known: Known) {
  const xml = await (await fetch(`https://${host}/sitemap.xml`)).text();

  // Use a real XML parser in production. The home page comes first, then the listings.
  const entries = [...xml.matchAll(/<url>\s*<loc>([^<]+)<\/loc>(?:\s*<lastmod>([^<]+)<\/lastmod>)?/g)]
    .map((match) => ({ url: match[1].replaceAll('&amp;', '&'), lastmod: match[2] ?? '' }))
    .slice(1);

  const current = new Set(entries.map((entry) => entry.url));
  const removed = [...known.keys()].filter((url) => !current.has(url));
  const changed = entries.filter((entry) => known.get(entry.url) !== entry.lastmod);

  const listings: ListingFacts[] = [];
  for (const entry of changed) {
    const facts = await readListing(entry.url);
    if (facts) listings.push(facts);
    known.set(entry.url, entry.lastmod);
    await wait(1000); // keep to about one request a second for each host
  }
  for (const url of removed) known.delete(url);

  return { listings, removed };
}

async function readListing(url: string): Promise<ListingFacts | null> {
  const html = await (await fetch(url)).text();
  const script = html.match(/<script[^>]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/)?.[1];
  if (!script) return null;

  const graph: Array<Record<string, any>> = JSON.parse(script)['@graph'] ?? [];
  const listing = graph.find((node) => node['@type'] === 'RealEstateListing');
  if (!listing) return null;
  const property = graph.find((node) => node['@id'] === listing.about?.['@id']);

  return {
    url,
    name: listing.name ?? null,
    price: listing.offers?.price ?? null,
    currency: listing.offers?.priceCurrency ?? null,
    availability: listing.offers?.availability ?? null,
    bedrooms: property?.numberOfBedrooms ?? null,
    bathrooms: property?.numberOfBathroomsTotal ?? null,
    modified: listing.dateModified ?? null,
  };
}

Once per broker
  1. Broker     -> Your app:  presses "Connect with Matchai" on your site
  2. Your app   -> Matchai:   sends the broker to the Allow page (authorization code with PKCE)
  3. Broker     -> Matchai:   reads what your app may do, and who pays, then presses Allow
  4. Matchai    -> Your app:  redirects back with a code
  5. Your app   -> Matchai:   exchanges the code for tokens
  6. Your app   -> Matchai:   GET /me, GET /listings, POST /webhook-subscriptions

Listings
  Matchai       -> Your app:  listing.published, listing.updated, listing.unpublished
  Your app      -> Matchai:   GET /listings/{listing_id}   (read the current state)

Leads
  Visitor       -> Your site: fills in the contact form
  Your site     -> Matchai:   POST /enquiries              (with an Idempotency-Key)
  Matchai       -> Your app:  lead.created                 (when the person is a new lead)

Viewings
  Visitor       -> Your site: picks a day
  Your site     -> Matchai:   GET /professionals/{username}/booking-slots
  Visitor       -> Your site: picks a time
  Your site     -> Matchai:   POST /listings/{listing_id}/viewing-requests
  Matchai       -> Your app:  appointment.requested
  Broker        -> Matchai:   confirms or declines the request
  Matchai       -> Your app:  appointment.booked, or appointment.cancelled

import { createHash, randomBytes } from 'node:crypto';

const scopes = [
  'profile:read',
  'listings:read',
  'contacts:read',
  'contacts:write',
  'calendar:read',
  'calendar:write',
  'webhooks:manage',
];

/** Step 2: the address to send the broker to. Save state and verifier with the broker's record. */
export function startConnect(clientId: string, redirectUri: string) {
  const verifier = randomBytes(32).toString('base64url');
  const challenge = createHash('sha256').update(verifier).digest('base64url');
  const state = randomBytes(16).toString('base64url');

  const url = new URL('https://matchai.co/oauth/authorize');
  url.search = new URLSearchParams({
    response_type: 'code',
    client_id: clientId,
    redirect_uri: redirectUri,
    scope: scopes.join(' '),
    state,
    code_challenge: challenge,
    code_challenge_method: 'S256',
  }).toString();

  return { url: url.toString(), state, verifier };
}

/** Step 5: exchange the code for tokens, and store them for this broker only. */
export async function finishConnect(params: {
  code: string;
  verifier: string;
  clientId: string;
  clientSecret: string;
  redirectUri: string;
}) {
  const response = await fetch('https://api.matchai.co/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: params.code,
      redirect_uri: params.redirectUri,
      client_id: params.clientId,
      client_secret: params.clientSecret,
      code_verifier: params.verifier,
    }),
  });
  if (!response.ok) throw new Error(`Matchai refused the code (${response.status}).`);

  return (await response.json()) as {
    access_token: string;
    refresh_token: string;
    expires_in: number;
    scope: string;
  };
}

const api = 'https://api.matchai.co/v1';

export class MatchaiError extends Error {
  readonly status: number;
  readonly code: string;

  constructor(status: number, code: string, message: string) {
    super(message);
    this.status = status;
    this.code = code;
  }
}

/** Calls the Matchai API as one connected broker. */
export async function matchai<T>(
  path: string,
  token: string,
  init: { method?: string; body?: unknown; idempotencyKey?: string } = {},
  attempt = 0,
): Promise<T> {
  const response = await fetch(`${api}${path}`, {
    method: init.method ?? 'GET',
    headers: {
      Authorization: `Bearer ${token}`,
      ...(init.body === undefined ? {} : { 'Content-Type': 'application/json' }),
      ...(init.idempotencyKey ? { 'Idempotency-Key': init.idempotencyKey } : {}),
    },
    body: init.body === undefined ? undefined : JSON.stringify(init.body),
  });

  // Too many requests for this connection: wait as long as Matchai says, then try again.
  if (response.status === 429 && attempt < 3) {
    const seconds = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    return matchai<T>(path, token, init, attempt + 1);
  }

  if (!response.ok) {
    const { error } = await response.json();
    throw new MatchaiError(response.status, error.code, error.message);
  }
  return (await response.json()) as T;
}

import { matchai, MatchaiError } from './matchai.js';

type Page<T> = { data: T[]; next_cursor: string | null };

export type Listing = {
  id: string;
  slug: string;
  url: string | null;
  status: 'draft' | 'published' | 'archived';
  availability: 'available' | 'sold' | 'rented' | 'withdrawn';
  title: string | null;
  description: string | null;
  price: { amount: number; currency: string } | null;
  cover_image_url: string | null;
  owner: { type: 'user' | 'team'; id: string; name: string };
  updated_at: string;
};

export interface ListingStore {
  upsert(listing: Listing): void | Promise<void>;
  remove(listingId: string): void | Promise<void>;
}

/** Every listing that changed since a time, whatever its status. Leave since out for a first import. */
export async function fetchListings(
  token: string,
  options: { since?: string; locale?: 'en-US' | 'fr-CA' | 'es' } = {},
): Promise<Listing[]> {
  const all: Listing[] = [];
  let cursor: string | null = null;

  do {
    const query = new URLSearchParams({ limit: '100' });
    if (options.since) query.set('updated_since', options.since);
    if (options.locale) query.set('locale', options.locale);
    if (cursor) query.set('cursor', cursor);

    const page: Page<Listing> = await matchai<Page<Listing>>(`/listings?${query}`, token);
    all.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);

  return all;
}

/** Shows a published listing, and removes anything else. */
export async function applyListing(listing: Listing, store: ListingStore): Promise<void> {
  if (listing.status === 'published') await store.upsert(listing);
  else await store.remove(listing.id); // draft or archived: stop showing it
}

/** The handler for every listing event: read the listing again, then apply what you find. */
export async function refreshListing(listingId: string, token: string, store: ListingStore): Promise<void> {
  try {
    const listing = await matchai<Listing>(`/listings/${listingId}`, token);
    await applyListing(listing, store);
  } catch (error) {
    if (error instanceof MatchaiError && error.status === 404) await store.remove(listingId);
    else throw error;
  }
}

import { matchai, MatchaiError } from './matchai.js';

export type Enquiry = {
  first_name: string;
  last_name?: string;
  email?: string;
  phone?: string;
  message: string;
  listing_id?: string;
  page_url?: string;
  language?: 'en-US' | 'fr-CA' | 'es';
  consent_to_contact?: boolean;
};

type EnquiryResult = { contact: { id: string; type: string; display_name: string }; created: boolean };

/** Sends one form submission to the broker's contacts. submissionId is one value per submission. */
export async function sendEnquiry(token: string, submissionId: string, enquiry: Enquiry) {
  try {
    const result = await matchai<EnquiryResult>('/enquiries', token, {
      method: 'POST',
      body: enquiry,
      idempotencyKey: submissionId,
    });
    return { ok: true as const, contactId: result.contact.id, newLead: result.created };
  } catch (error) {
    // 400 and 422 carry a message that is safe to show: what happened and what to do.
    if (error instanceof MatchaiError && (error.status === 400 || error.status === 422)) {
      return { ok: false as const, message: error.message };
    }
    throw error; // anything else is yours to log and retry with the same submissionId
  }
}

import { sendEnquiry } from './enquiry.js';

export async function handleContactForm(request: Request, brokerToken: string): Promise<Response> {
  const form = await request.formData();
  const submissionId = String(form.get('submission_id') ?? '').trim();
  const email = String(form.get('email') ?? '').trim();
  const phone = String(form.get('phone') ?? '').trim();
  const firstName = String(form.get('first_name') ?? '').trim();
  const message = String(form.get('message') ?? '').trim();

  if (!submissionId || !firstName || !message || (!email && !phone)) {
    return Response.json({ message: 'Please add your name, a message, and an email or a phone number.' }, { status: 400 });
  }

  const result = await sendEnquiry(brokerToken, submissionId, {
    first_name: firstName,
    email: email || undefined,
    phone: phone || undefined,
    message,
    listing_id: String(form.get('listing_id') ?? '') || undefined,
    page_url: request.headers.get('Referer') ?? undefined,
    consent_to_contact: form.get('consent') === 'on',
  });

  if (!result.ok) return Response.json({ message: result.message }, { status: 422 });
  return Response.json({ message: 'Thank you. The broker will get back to you.' }, { status: 201 });
}

import { matchai, MatchaiError } from './matchai.js';

type Slots = {
  date: string;
  timezone: string;
  duration_minutes: number;
  slots: Array<{ starts_at: string; ends_at: string }>;
};

type Visitor = {
  first_name: string;
  last_name?: string;
  email?: string;
  phone?: string;
  language?: 'en-US' | 'fr-CA' | 'es';
};

/** The visit lengths a visitor can choose for this listing. Empty when visits cannot be booked. */
export async function visitLengths(token: string, listingId: string): Promise<number[]> {
  const settings = await matchai<{ enabled: boolean; durations_minutes: number[] }>(
    `/listings/${listingId}/availability`,
    token,
  );
  return settings.enabled ? settings.durations_minutes : [];
}

/** Free times on one day (date is YYYY-MM-DD). Slot times keep the broker's time zone offset. */
export async function bookableSlots(
  token: string,
  username: string,
  listingId: string,
  date: string,
  durationMinutes: number,
): Promise<Slots> {
  const query = new URLSearchParams({
    date,
    duration_minutes: String(durationMinutes),
    listing_id: listingId,
  });
  return matchai<Slots>(`/professionals/${username}/booking-slots?${query}`, token);
}

/** Sends the visit request. requestId is one value per request, so a retry never asks twice. */
export async function requestViewing(
  token: string,
  requestId: string,
  listingId: string,
  visitor: Visitor,
  startsAt: string,
  durationMinutes: number,
  notes?: string,
) {
  try {
    const result = await matchai<{ appointment: { id: string; status: string } }>(
      `/listings/${listingId}/viewing-requests`,
      token,
      {
        method: 'POST',
        idempotencyKey: requestId,
        body: { visitor, starts_at: startsAt, duration_minutes: durationMinutes, notes },
      },
    );
    return { ok: true as const, appointmentId: result.appointment.id, status: result.appointment.status };
  } catch (error) {
    if (error instanceof MatchaiError && error.code === 'slot_unavailable') {
      return { ok: false as const, reason: 'slot_taken' as const };
    }
    throw error;
  }
}

import { refreshListing, type ListingStore } from './listings-feed.js';

type MatchaiEvent = {
  id: string;
  type: string;
  created_at: string;
  test_mode: boolean;
  account: { user_id: string };
  data: { object: { id: string; status?: string } };
};

/** Call this after the signature is verified and after you have skipped duplicate event ids. */
export async function handlePartnerEvent(event: MatchaiEvent, brokerToken: string, store: ListingStore): Promise<void> {
  switch (event.type) {
    case 'listing.published':
    case 'listing.updated':
    case 'listing.unpublished':
    case 'listing.archived':
    case 'listing.deleted':
      await refreshListing(event.data.object.id, brokerToken, store);
      break;

    case 'appointment.requested':
    case 'appointment.booked':
    case 'appointment.rescheduled':
    case 'appointment.cancelled':
      // Update the visit request you stored, found by event.data.object.id.
      console.log('Visit', event.data.object.id, event.data.object.status);
      break;

    case 'lead.created':
      // Leads also arrive from Matchai itself. Compare the id with the contact your own form created.
      console.log('New lead', event.data.object.id);
      break;

    default:
      break; // new event types can appear at any time
  }
}