brickwise 0.1.0

package/src/lib/pf/transactions.ts

@@ -0,0 +1,85 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { fetchPfPage } from "./client";
+import { extractPageProps } from "./parse";
+import { getDb, now } from "../db";
+import { PfTransaction } from "../types";
+
+const BASE = "https://www.propertyfinder.ae";
+const MAX_TX_PAGES = 10;
+const SYNC_TTL_MS = 7 * 24 * 3600 * 1000;
+
+async function scrapeTransactionPages(
+  citySlug: string,
+  towerSlug: string,
+  kind: "buy" | "rent"
+): Promise<PfTransaction[]> {
+  const all: PfTransaction[] = [];
+  let pageCount = 1;
+  for (let page = 1; page <= Math.min(pageCount, MAX_TX_PAGES); page++) {
+    const url = `${BASE}/en/transactions/${kind}/${citySlug}/${towerSlug}${page > 1 ? `?page=${page}` : ""}`;
+    let pp: any;
+    try {
+      pp = extractPageProps(await fetchPfPage(url));
+    } catch {
+      break; // tower without transaction page
+    }
+    const list = pp.list;
+    if (!list?.transactionList) break;
+    all.push(...list.transactionList);
+    pageCount = list.totalPageCount ?? 1;
+  }
+  return all;
+}
+
+/** Scrape buy+rent transaction history for a tower into SQLite (7-day TTL). */
+export async function syncTransactions(citySlug: string, towerSlug: string): Promise<void> {
+  const db = getDb();
+  const insert = db.prepare(
+    `INSERT OR REPLACE INTO transactions (id, tower_slug, kind, date, amount, size_sqft, price_per_sqft, bedrooms, unit, scraped_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  );
+  const getSync = db.prepare(`SELECT synced_at FROM tx_sync WHERE tower_slug = ? AND kind = ?`);
+  const setSync = db.prepare(`INSERT OR REPLACE INTO tx_sync (tower_slug, kind, synced_at) VALUES (?, ?, ?)`);
+
+  for (const kind of ["buy", "rent"] as const) {
+    const sync = getSync.get(towerSlug, kind) as { synced_at: string } | undefined;
+    if (sync && Date.now() - Date.parse(sync.synced_at) < SYNC_TTL_MS) continue;
+    const txs = await scrapeTransactionPages(citySlug, towerSlug, kind);
+    const ts = now();
+    const write = db.transaction(() => {
+      for (const t of txs) {
+        insert.run(
+          t.id,
+          towerSlug,
+          kind,
+          kind === "rent" ? (t.contractStartDate || t.transactionDate) : t.transactionDate,
+          t.price,
+          t.propertySize || null,
+          t.pricePerSqft || null,
+          typeof t.bedrooms === "number" ? t.bedrooms : parseInt(String(t.bedrooms)) || null,
+          t.propertyNumber || null,
+          ts
+        );
+      }
+      setSync.run(towerSlug, kind, ts);
+    });
+    write();
+  }
+}
+
+export interface TxRow {
+  id: string;
+  kind: "buy" | "rent";
+  date: string;
+  amount: number;
+  size_sqft: number | null;
+  price_per_sqft: number | null;
+  bedrooms: number | null;
+  unit: string | null;
+}
+
+export function getTransactions(towerSlug: string, kind: "buy" | "rent"): TxRow[] {
+  return getDb()
+    .prepare(`SELECT * FROM transactions WHERE tower_slug = ? AND kind = ? ORDER BY date DESC`)
+    .all(towerSlug, kind) as TxRow[];
+}

package/src/lib/store.ts

@@ -0,0 +1,182 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { getDb, now } from "./db";
+import { AnalysisRow, ListingRow, PfProperty, YieldResult } from "./types";
+
+function sizeSqft(p: PfProperty): number | null {
+  const s: any = p.size;
+  if (s == null) return null;
+  if (typeof s === "number") return s;
+  const parsed = parseFloat(String(s.value ?? s));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** Coerce PF values that may come as number, numeric string, {value} or {price} object. */
+function toNum(v: unknown): number | null {
+  if (v == null) return null;
+  if (typeof v === "object") {
+    const o = v as { value?: unknown; price?: unknown };
+    return toNum(o.value ?? o.price);
+  }
+  const n = typeof v === "number" ? v : parseFloat(String(v));
+  return Number.isFinite(n) ? n : null;
+}
+
+/** Search pages: images is an array; detail pages: {property: [...]} with other size keys. */
+function normalizeImages(p: PfProperty): { small: string; medium: string }[] {
+  const raw: any = p.images;
+  const arr: any[] = Array.isArray(raw) ? raw : raw?.property || [];
+  return arr
+    .map((i) => ({ small: i.small || i.thumbnail || i.medium || "", medium: i.medium || i.full || i.small || "" }))
+    .filter((i) => i.medium);
+}
+
+function toInt(v: unknown): number | null {
+  if (v == null) return null;
+  if (typeof v === "number") return v;
+  const s = String(v).toLowerCase();
+  if (s === "studio") return 0;
+  const n = parseInt(s, 10);
+  return Number.isFinite(n) ? n : null;
+}
+
+/** The tower node (or deepest location) the transactions history is keyed on. */
+function towerNode(p: PfProperty) {
+  const tree = p.location_tree;
+  if (tree?.length) {
+    const tower = [...tree].reverse().find((l) => l.type === "TOWER");
+    return tower || tree[tree.length - 1];
+  }
+  return p.location;
+}
+
+export function upsertListing(p: PfProperty, citySlug = "dubai"): ListingRow {
+  const db = getDb();
+  const tower = towerNode(p);
+  const size = sizeSqft(p);
+  const price = p.price?.value ?? 0;
+  const ts = now();
+  const existing = db
+    .prepare(`SELECT first_seen_at, amenities_json, description, images_json FROM listings WHERE id = ?`)
+    .get(p.id) as
+    | { first_seen_at: string; amenities_json: string; description: string | null; images_json: string }
+    | undefined;
+  const amenities = p.amenity_names?.length
+    ? JSON.stringify(p.amenity_names)
+    : existing?.amenities_json ?? "[]";
+  // Search cards only carry ~3 images; never let them clobber a richer detail-page set.
+  let images = normalizeImages(p);
+  if (existing) {
+    try {
+      const prev = JSON.parse(existing.images_json);
+      if (Array.isArray(prev) && prev.length > images.length) images = prev;
+    } catch {}
+  }
+
+  db.prepare(
+    `INSERT OR REPLACE INTO listings
+     (id, url, title, price, size_sqft, bedrooms, bathrooms, property_type, tower_id, tower_slug, tower_name,
+      city_slug, lat, lon, images_json, amenities_json, agent_json, price_per_sqft, description, first_seen_at, last_scraped_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    String(p.id),
+    p.share_url || `https://www.propertyfinder.ae${p.details_path || ""}`,
+    p.title || "",
+    price,
+    size,
+    toInt(p.bedrooms),
+    toInt(p.bathrooms),
+    p.property_type || "",
+    tower?.id != null ? String(tower.id) : null,
+    tower?.slug ?? null,
+    tower?.name ?? null,
+    citySlug,
+    toNum(p.location?.coordinates?.lat),
+    toNum(p.location?.coordinates?.lon),
+    JSON.stringify(images),
+    amenities,
+    JSON.stringify({ agent: p.agent?.name ?? null, broker: p.broker?.name ?? null }),
+    toNum(p.price_per_area) ?? (size && price ? price / size : null),
+    p.description ?? existing?.description ?? null,
+    existing?.first_seen_at ?? ts,
+    ts
+  );
+  return getListing(p.id)!;
+}
+
+export function getListing(id: string): ListingRow | null {
+  return (getDb().prepare(`SELECT * FROM listings WHERE id = ?`).get(id) as ListingRow) ?? null;
+}
+
+export function saveAnalysis(listingId: string, y: YieldResult, gym: { gym_name: string | null; distance_m: number | null }) {
+  getDb()
+    .prepare(
+      `INSERT OR REPLACE INTO analyses
+       (listing_id, gross_yield, asking_yield, median_rent, median_sale_price,
+        rent_n, buy_n, gym_distance_m, gym_name, computed_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+    )
+    .run(
+      listingId,
+      y.gross_yield,
+      y.asking_yield,
+      y.median_rent,
+      y.median_sale_price,
+      y.rent_n,
+      y.buy_n,
+      gym.distance_m,
+      gym.gym_name,
+      now()
+    );
+}
+
+export function getAnalysis(listingId: string): AnalysisRow | null {
+  return (getDb().prepare(`SELECT * FROM analyses WHERE listing_id = ?`).get(listingId) as AnalysisRow) ?? null;
+}
+
+export interface AnalyzedListing extends ListingRow, Omit<AnalysisRow, "listing_id" | "computed_at"> {
+  computed_at: string | null;
+}
+
+export function addFavorite(listingId: string) {
+  getDb()
+    .prepare(`INSERT OR IGNORE INTO favorites (listing_id, notes, added_at) VALUES (?, '', ?)`)
+    .run(listingId, now());
+}
+
+export function removeFavorite(listingId: string) {
+  getDb().prepare(`DELETE FROM favorites WHERE listing_id = ?`).run(listingId);
+}
+
+export function setFavoriteNotes(listingId: string, notes: string) {
+  getDb().prepare(`UPDATE favorites SET notes = ? WHERE listing_id = ?`).run(notes, listingId);
+}
+
+export interface FavoriteListing extends AnalyzedListing {
+  notes: string;
+  added_at: string;
+}
+
+export function listFavorites(): FavoriteListing[] {
+  return getDb()
+    .prepare(
+      `SELECT l.*, a.gross_yield, a.asking_yield, a.median_rent, a.median_sale_price,
+              a.rent_n, a.buy_n, a.gym_distance_m, a.gym_name, a.computed_at,
+              f.notes, f.added_at
+       FROM favorites f
+       JOIN listings l ON l.id = f.listing_id
+       LEFT JOIN analyses a ON a.listing_id = f.listing_id
+       ORDER BY a.gross_yield DESC NULLS LAST`
+    )
+    .all() as FavoriteListing[];
+}
+
+export function listAnalyzed(): AnalyzedListing[] {
+  return getDb()
+    .prepare(
+      `SELECT l.*, a.gross_yield, a.asking_yield, a.median_rent, a.median_sale_price,
+              a.rent_n, a.buy_n, a.gym_distance_m, a.gym_name, a.computed_at
+       FROM listings l JOIN analyses a ON a.listing_id = l.id
+       ORDER BY a.gross_yield DESC NULLS LAST`
+    )
+    .all() as AnalyzedListing[];
+}

package/src/lib/types.ts

@@ -0,0 +1,122 @@
+export interface PfImage {
+  small: string;
+  medium: string;
+}
+
+export interface PfLocation {
+  id: string;
+  full_name: string;
+  coordinates?: { lat: number; lon: number };
+  slug: string;
+  path: string;
+  type: string;
+  name: string;
+  path_name: string;
+}
+
+export interface PfProperty {
+  id: string;
+  title: string;
+  price: { value: number; currency: string; period: string };
+  size?: { value: number; unit: string } | number;
+  bedrooms?: number | string;
+  bathrooms?: number | string;
+  property_type: string;
+  images: PfImage[];
+  share_url: string;
+  details_path: string;
+  location: PfLocation;
+  location_tree?: PfLocation[];
+  amenity_names?: string[];
+  amenities?: string[];
+  price_per_area?: number;
+  description?: string;
+  listed_date?: string;
+  broker?: { name?: string };
+  agent?: { name?: string };
+  similar_price_transactions?: {
+    buy: SimilarTransaction[];
+    rent: SimilarTransaction[];
+  };
+}
+
+export interface SimilarTransaction {
+  date: string;
+  amount: string;
+  size: number;
+}
+
+export interface PfTransaction {
+  id: string;
+  transactionDate: string;
+  price: number;
+  propertySize: number;
+  pricePerSqft: number;
+  bedrooms: number | string;
+  propertyNumber: string;
+  propertyType: string;
+  locationName: string;
+  contractStartDate?: string;
+  contractEndDate?: string;
+}
+
+export interface SearchFilters {
+  locationId?: string;
+  locationLabel?: string;
+  minPrice?: number;
+  maxPrice?: number;
+  minArea?: number;
+  maxArea?: number;
+  bedrooms?: string[];
+  bathrooms?: string[];
+  propertyTypeId?: string;
+  amenities?: string[];
+  maxGymDistanceM?: number;
+  maxPages?: number;
+}
+
+export interface ListingRow {
+  id: string;
+  url: string;
+  title: string;
+  price: number;
+  size_sqft: number | null;
+  bedrooms: number | null;
+  bathrooms: number | null;
+  property_type: string;
+  tower_id: string | null;
+  tower_slug: string | null;
+  tower_name: string | null;
+  city_slug: string | null;
+  lat: number | null;
+  lon: number | null;
+  images_json: string;
+  amenities_json: string;
+  agent_json: string;
+  price_per_sqft: number | null;
+  description: string | null;
+  first_seen_at: string;
+  last_scraped_at: string;
+}
+
+export interface AnalysisRow {
+  listing_id: string;
+  gross_yield: number | null;
+  asking_yield: number | null;
+  median_rent: number | null;
+  median_sale_price: number | null;
+  rent_n: number;
+  buy_n: number;
+  gym_distance_m: number | null;
+  gym_name: string | null;
+  computed_at: string;
+}
+
+export interface YieldResult {
+  gross_yield: number | null;
+  asking_yield: number | null;
+  median_rent: number | null;
+  median_sale_price: number | null;
+  rent_n: number;
+  buy_n: number;
+}

package/src/lib/yield.ts

@@ -0,0 +1,80 @@
+import { TxRow } from "./pf/transactions";
+import { SimilarTransaction, YieldResult } from "./types";
+
+const WINDOW_MS = 24 * 30.44 * 24 * 3600 * 1000; // ~24 months
+const MIN_SAMPLES = 3;
+const SIZE_TOLERANCE = 0.2;
+
+function median(xs: number[]): number | null {
+  if (xs.length === 0) return null;
+  const s = [...xs].sort((a, b) => a - b);
+  const m = Math.floor(s.length / 2);
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+
+/**
+ * Comparable units only: same bedrooms + similar size when possible, relaxing to
+ * same bedrooms, then similar size. Never falls back to "every transaction in the
+ * building" — mixing unit types is what produces bogus yields.
+ */
+function pickSample(txs: TxRow[], bedrooms: number | null, sizeSqft: number | null): TxRow[] {
+  const cutoff = Date.now() - WINDOW_MS;
+  const recent = txs.filter((t) => Date.parse(t.date) >= cutoff);
+  const sameBdr = (t: TxRow) => bedrooms != null && t.bedrooms === bedrooms;
+  const sameSize = (t: TxRow) =>
+    sizeSqft != null && t.size_sqft != null && Math.abs(t.size_sqft - sizeSqft) / sizeSqft <= SIZE_TOLERANCE;
+
+  const byBoth = recent.filter((t) => sameBdr(t) && sameSize(t));
+  if (byBoth.length >= MIN_SAMPLES) return byBoth;
+  const byBdr = recent.filter(sameBdr);
+  if (byBdr.length >= MIN_SAMPLES) return byBdr;
+  const bySize = recent.filter(sameSize);
+  if (bySize.length >= MIN_SAMPLES) return bySize;
+  // Below MIN_SAMPLES everywhere: use the best comparable set we have, even if tiny.
+  if (byBoth.length) return byBoth;
+  if (byBdr.length) return byBdr;
+  return bySize;
+}
+
+/**
+ * Annual rental yield from the building's real transactions:
+ *   gross_yield  = median annual rent of comparable units / median sale price of comparable units
+ *   asking_yield = median annual rent of comparable units / asking price of this listing
+ * No appreciation / revaluation metrics.
+ */
+export function computeYield(
+  price: number,
+  sizeSqft: number | null,
+  bedrooms: number | null,
+  buyTxs: TxRow[],
+  rentTxs: TxRow[]
+): YieldResult {
+  const buySample = pickSample(buyTxs, bedrooms, sizeSqft);
+  const rentSample = pickSample(rentTxs, bedrooms, sizeSqft);
+
+  const medianRent = median(rentSample.map((t) => t.amount));
+  const medianSalePrice = median(buySample.map((t) => t.amount));
+
+  return {
+    gross_yield: medianRent != null && medianSalePrice ? medianRent / medianSalePrice : null,
+    asking_yield: medianRent != null && price > 0 ? medianRent / price : null,
+    median_rent: medianRent,
+    median_sale_price: medianSalePrice,
+    rent_n: rentSample.length,
+    buy_n: buySample.length,
+  };
+}
+
+/** Fallback: the 5+5 size-matched transactions embedded in the listing detail page. */
+export function similarToTxRows(sims: SimilarTransaction[], kind: "buy" | "rent"): TxRow[] {
+  return sims.map((s, i) => ({
+    id: `sim-${kind}-${i}-${s.date}`,
+    kind,
+    date: s.date,
+    amount: parseFloat(s.amount),
+    size_sqft: s.size ?? null,
+    price_per_sqft: s.size ? parseFloat(s.amount) / s.size : null,
+    bedrooms: null,
+    unit: null,
+  }));
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}