@propertysimple/client 0.1.0

package/client/src/managed-sync.js

@@ -0,0 +1,410 @@
+import { randomUUID } from 'node:crypto';
+import { CatalogSourceFreshnessSchema, ListingSchema, operations, } from '../../contracts/src/index.js';
+import { ApiError } from './index.js';
+import { freshLocationProjection } from '../../contracts/src/location-serving.js';
+export const portalActiveProfile = {
+    id: 'portal-active-v1',
+    eligible: (listing) => listing.display_eligibility &&
+        listing.source_availability === 'present' &&
+        listing.market_status === 'active',
+};
+export const allVisibleProfile = {
+    id: 'all-visible-v1',
+    eligible: (listing) => listing.display_eligibility && listing.source_availability === 'present',
+};
+export class ProjectionUnavailableError extends Error {
+    constructor(message = 'Catalog projection is initializing, blocked, or outside its freshness budget.') {
+        super(message);
+        this.name = 'ProjectionUnavailableError';
+    }
+}
+const newCheckpoint = () => ({
+    phase: 'create',
+    generation: randomUUID(),
+    lastSequence: '0',
+    stagedCount: 0,
+});
+const sequence = (value) => {
+    if (!/^\d+$/.test(value))
+        throw new Error('Catalog sequence must be a nonnegative integer.');
+    return BigInt(value);
+};
+/**
+ * An isolated consumer-owned projection. Product users, saved homes and canonical URLs stay in
+ * product tables, joined using local_id. Never point this adapter at a product's listings table.
+ */
+export class PostgresCatalogTarget {
+    db;
+    configuration;
+    constructor(db, configuration) {
+        this.db = db;
+        this.configuration = configuration;
+        for (const value of [
+            configuration.streamId,
+            configuration.datasetId,
+            configuration.sourceNamespace,
+            configuration.profile.id,
+        ])
+            if (!value || value.length > 256)
+                throw new Error('Sync identities must contain 1–256 characters.');
+    }
+    /** Explicit schema installation. Run only against an approved consumer database. */
+    async initialize() {
+        await this.db.query(`
+      create schema if not exists consumer_sync;
+      create table if not exists consumer_sync.streams (
+        id text primary key, dataset_id text not null, source_namespace text not null,
+        profile_id text not null, version bigint not null default 0, checkpoint jsonb not null,
+        active_generation text, synchronized_at timestamptz
+      );
+      create table if not exists consumer_sync.identities (
+        stream_id text not null references consumer_sync.streams(id), listing_id text not null,
+        local_id uuid not null, primary key(stream_id,listing_id), unique(stream_id,local_id)
+      );
+      create table if not exists consumer_sync.projections (
+        stream_id text not null references consumer_sync.streams(id), generation text not null,
+        listing_id text not null, payload jsonb, eligible boolean not null,
+        primary key(stream_id,generation,listing_id)
+      );
+      create table if not exists consumer_sync.invalidations (
+        id uuid primary key, stream_id text not null references consumer_sync.streams(id),
+        generation text not null, kind text not null check(kind in ('reset','upsert','remove')),
+        listing_id text, local_id uuid, created_at timestamptz not null default now(),
+        lease_token uuid, lease_until timestamptz, acknowledged_at timestamptz
+      );
+      create index if not exists consumer_sync_invalidations_pending
+        on consumer_sync.invalidations(stream_id,created_at) where acknowledged_at is null;
+      alter table consumer_sync.streams enable row level security;
+      alter table consumer_sync.identities enable row level security;
+      alter table consumer_sync.projections enable row level security;
+      alter table consumer_sync.invalidations enable row level security;
+      revoke all on schema consumer_sync from public;
+      revoke all on consumer_sync.streams,consumer_sync.identities,
+        consumer_sync.projections,consumer_sync.invalidations from public;
+    `);
+        await this.db.query(`insert into consumer_sync.streams(id,dataset_id,source_namespace,profile_id,checkpoint)
+       values($1,$2,$3,$4,$5::jsonb) on conflict(id) do nothing`, [
+            this.configuration.streamId,
+            this.configuration.datasetId,
+            this.configuration.sourceNamespace,
+            this.configuration.profile.id,
+            JSON.stringify(newCheckpoint()),
+        ]);
+        await this.state();
+    }
+    async state() {
+        const row = (await this.db.query(`select *,version::text from consumer_sync.streams where id=$1`, [
+            this.configuration.streamId,
+        ])).rows[0];
+        if (!row)
+            throw new Error('Initialize the consumer projection before synchronization.');
+        if (row.dataset_id !== this.configuration.datasetId ||
+            row.source_namespace !== this.configuration.sourceNamespace ||
+            row.profile_id !== this.configuration.profile.id)
+            throw new Error('Sync scope/profile changed. Use a new stream and an explicit product cutover.');
+        return row;
+    }
+    /** Adopt an existing product UUID before importing it; never rewrite an established mapping. */
+    async mapExistingIdentity(listingId, localId) {
+        await this.db.transaction(async (tx) => {
+            await tx.query(`insert into consumer_sync.identities(stream_id,listing_id,local_id) values($1,$2,$3::uuid) on conflict(stream_id,listing_id) do nothing`, [this.configuration.streamId, listingId, localId]);
+            const saved = (await tx.query(`select local_id from consumer_sync.identities where stream_id=$1 and listing_id=$2`, [this.configuration.streamId, listingId])).rows[0];
+            if (saved.local_id !== localId.toLowerCase())
+                throw new Error('An existing listing identity cannot be remapped.');
+        });
+    }
+    /** Readers never see staging generations. A caller must choose an explicit freshness budget. */
+    async list(options) {
+        const limit = options.limit ?? 100;
+        if (!Number.isInteger(limit) ||
+            limit < 1 ||
+            limit > 200 ||
+            !Number.isFinite(options.maxStalenessMs) ||
+            options.maxStalenessMs <= 0)
+            throw new Error('Use a page of 1–200 rows and a positive freshness budget.');
+        return this.db.transaction(async (tx) => {
+            const at = await this.assertReadable(tx, options);
+            return (await tx.query(`select p.listing_id,i.local_id,p.payload as listing from consumer_sync.streams s
+       join consumer_sync.projections p on p.stream_id=s.id and p.generation=s.active_generation
+       join consumer_sync.identities i on i.stream_id=p.stream_id and i.listing_id=p.listing_id
+       where s.id=$1 and p.eligible and p.listing_id>$2 and s.synchronized_at>=now()-($3::double precision * interval '1 millisecond')
+       order by p.listing_id limit $4`, [this.configuration.streamId, options.after ?? '', options.maxStalenessMs, limit])).rows.map((row) => ({ ...row, listing: freshLocationProjection(row.listing, at) }));
+        });
+    }
+    /** Status consumers may inspect a noneligible upsert; a source tombstone has a null payload. */
+    async get(listingId, options) {
+        if (!Number.isFinite(options.maxStalenessMs) || options.maxStalenessMs <= 0)
+            throw new Error('Choose a positive freshness budget.');
+        return this.db.transaction(async (tx) => {
+            const at = await this.assertReadable(tx, options);
+            const row = (await tx.query(`select p.listing_id,i.local_id,p.eligible,p.payload as listing from consumer_sync.streams s
+         join consumer_sync.projections p on p.stream_id=s.id and p.generation=s.active_generation
+         join consumer_sync.identities i on i.stream_id=p.stream_id and i.listing_id=p.listing_id
+         where s.id=$1 and p.listing_id=$2`, [this.configuration.streamId, listingId])).rows[0] ?? null;
+            return row?.listing ? { ...row, listing: freshLocationProjection(row.listing, at) } : row;
+        });
+    }
+    async assertReadable(tx, options) {
+        for (const bound of [
+            options.maxStalenessMs,
+            options.maxSourceStalenessMs,
+            options.maxFullEnumerationStalenessMs,
+        ])
+            if (bound !== undefined && (!Number.isFinite(bound) || bound <= 0))
+                throw new Error('Freshness bounds must be positive.');
+        const row = (await tx.query(`select active_generation is not null and synchronized_at>=now()-($2::double precision * interval '1 millisecond') as ready,checkpoint,now() as now_at from consumer_sync.streams where id=$1 for share`, [this.configuration.streamId, options.maxStalenessMs])).rows[0];
+        if (!row?.ready)
+            throw new ProjectionUnavailableError();
+        const sourceBounds = [
+            ['last_completed_enumeration_at', options.maxSourceStalenessMs],
+            ['last_full_enumeration_at', options.maxFullEnumerationStalenessMs],
+        ];
+        const now = new Date(row.now_at).getTime();
+        for (const [field, bound] of sourceBounds) {
+            if (bound === undefined)
+                continue;
+            if (!row.checkpoint.sourceFreshness?.length ||
+                row.checkpoint.sourceFreshness.some((source) => {
+                    const at = source[field] ? Date.parse(source[field]) : NaN;
+                    return !Number.isFinite(at) || now - at > bound || at > now + 60_000;
+                }))
+                throw new ProjectionUnavailableError(`Source coverage is unknown or outside the ${field} freshness budget.`);
+        }
+        return new Date(row.now_at);
+    }
+    async commit(expected, next, mutate, synchronized = false) {
+        return this.db.transaction(async (tx) => {
+            // The checkpoint version fences workers that fetched the same page concurrently. Provider
+            // HTTP happens before this lock; a losing worker commits neither rows nor a stale cursor.
+            const locked = (await tx.query(`select version::text from consumer_sync.streams where id=$1 for update`, [this.configuration.streamId])).rows[0];
+            if (locked.version !== expected.version)
+                return false;
+            await mutate(tx);
+            await tx.query(`update consumer_sync.streams set checkpoint=$2::jsonb,version=version+1,synchronized_at=case when $3 then now() else synchronized_at end where id=$1`, [this.configuration.streamId, JSON.stringify(next), synchronized]);
+            return true;
+        });
+    }
+    async write(tx, generation, listing, listingId, invalidate, snapshot = false) {
+        if (listing && listing.id !== listingId)
+            throw new Error('Catalog listing identity mismatch.');
+        await tx.query(`insert into consumer_sync.identities(stream_id,listing_id,local_id) values($1,$2,$3::uuid) on conflict(stream_id,listing_id) do nothing`, [this.configuration.streamId, listingId, randomUUID()]);
+        const eligible = listing !== null && this.configuration.profile.eligible(listing);
+        // Noneligible upserts are removals from this projection. Do not leave a previously active
+        // property visible merely because the upstream change used the word "upsert".
+        await tx.query(`insert into consumer_sync.projections(stream_id,generation,listing_id,payload,eligible) values($1,$2,$3,$4::jsonb,$5) ${snapshot ? '' : 'on conflict(stream_id,generation,listing_id) do update set payload=excluded.payload,eligible=excluded.eligible'}`, [
+            this.configuration.streamId,
+            generation,
+            listingId,
+            listing ? JSON.stringify(listing) : null,
+            eligible,
+        ]);
+        if (invalidate)
+            await this.invalidate(tx, generation, eligible ? 'upsert' : 'remove', listingId);
+    }
+    async activate(tx, generation) {
+        // A pointer swap keeps million-row bootstrap completion constant-sized. Consumers of the
+        // outbox must treat reset as a whole-catalog cache/index refresh, including old missing IDs.
+        await tx.query(`update consumer_sync.streams set active_generation=$2 where id=$1`, [
+            this.configuration.streamId,
+            generation,
+        ]);
+        await this.invalidate(tx, generation, 'reset');
+    }
+    async invalidate(tx, generation, kind, listingId) {
+        await tx.query(`insert into consumer_sync.invalidations(id,stream_id,generation,kind,listing_id,local_id) values($1::uuid,$2,$3,$4,$5,(select local_id from consumer_sync.identities where stream_id=$2 and listing_id=$5))`, [randomUUID(), this.configuration.streamId, generation, kind, listingId ?? null]);
+    }
+    async reset(expected, blocked = false) {
+        const next = newCheckpoint();
+        if (blocked)
+            next.phase = 'blocked';
+        return this.commit(expected, next, async (tx) => {
+            // An expired scope might remove access. Hide the old projection immediately instead of
+            // serving data that the new snapshot may no longer authorize.
+            await tx.query(`update consumer_sync.streams set active_generation=null,synchronized_at=null where id=$1`, [this.configuration.streamId]);
+            await this.invalidate(tx, next.generation, 'reset');
+        });
+    }
+    /** Explicit operator recovery after correcting denied credentials/scope. Does not change scope. */
+    async resume() {
+        const state = await this.state();
+        if (state.checkpoint.phase !== 'blocked')
+            throw new Error('Only a blocked stream needs resume.');
+        if (!(await this.reset(state)))
+            throw new Error('Stream changed concurrently; inspect before retry.');
+    }
+    async claimInvalidations(limit = 100, leaseSeconds = 60) {
+        if (!Number.isInteger(limit) ||
+            limit < 1 ||
+            limit > 200 ||
+            !Number.isInteger(leaseSeconds) ||
+            leaseSeconds < 1 ||
+            leaseSeconds > 3600)
+            throw new Error('Invalid outbox page/lease bound.');
+        const token = randomUUID();
+        return (await this.db.query(`with picked as (
+      select id from consumer_sync.invalidations where stream_id=$1 and acknowledged_at is null
+      and (lease_until is null or lease_until<now()) order by created_at,id for update skip locked limit $2
+    ) update consumer_sync.invalidations o set lease_token=$3::uuid,lease_until=now()+($4::integer*interval '1 second')
+      from picked where o.id=picked.id returning o.*`, [this.configuration.streamId, limit, token, leaseSeconds])).rows;
+    }
+    async acknowledgeInvalidation(id, leaseToken) {
+        return ((await this.db.query(`update consumer_sync.invalidations set acknowledged_at=now() where id=$1::uuid and stream_id=$2 and lease_token=$3::uuid and acknowledged_at is null and lease_until>=now()`, [id, this.configuration.streamId, leaseToken])).rowCount === 1);
+    }
+    /** Bounded retention removes obsolete listing payloads, preserving identities and product data. */
+    async pruneObsolete(limit = 200) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error('Invalid cleanup bound.');
+        return this.db.transaction(async (tx) => {
+            await tx.query(`select id from consumer_sync.streams where id=$1 for update`, [
+                this.configuration.streamId,
+            ]);
+            return (await tx.query(`delete from consumer_sync.projections where (stream_id,generation,listing_id) in (
+        select p.stream_id,p.generation,p.listing_id from consumer_sync.projections p join consumer_sync.streams s on s.id=p.stream_id
+        where s.id=$1 and p.generation is distinct from s.active_generation and p.generation<>s.checkpoint->>'generation' limit $2
+      )`, [this.configuration.streamId, limit])).rowCount;
+        });
+    }
+}
+/** One step makes at most one network request and commits at most one bounded page. */
+export class CatalogSyncWorker {
+    source;
+    target;
+    pageSize;
+    constructor(source, target, pageSize = 100) {
+        this.source = source;
+        this.target = target;
+        this.pageSize = pageSize;
+        if (!Number.isInteger(pageSize) || pageSize < 1 || pageSize > 200)
+            throw new Error('Page size must be 1–200.');
+    }
+    async step(options = {}) {
+        const state = await this.target.state();
+        const checkpoint = state.checkpoint;
+        const result = (status, applied = 0) => ({
+            status,
+            phase: checkpoint.phase,
+            applied,
+        });
+        if (checkpoint.phase === 'blocked')
+            return result('blocked');
+        try {
+            if (checkpoint.phase === 'create' || checkpoint.phase === 'waiting') {
+                const snapshot = operations.getSnapshot.output.parse(checkpoint.phase === 'create'
+                    ? await this.source.catalog.createSnapshot({ dataset_id: this.target.configuration.datasetId }, { ...options, idempotencyKey: `consumer-snapshot-${checkpoint.generation}` })
+                    : await this.source.catalog.snapshot(checkpoint.snapshotId, options));
+                if (snapshot.dataset_id !== this.target.configuration.datasetId)
+                    throw new Error('Snapshot dataset mismatch.');
+                if (snapshot.status === 'expired')
+                    return result((await this.target.reset(state)) ? 'reset' : 'conflict');
+                if (snapshot.status === 'failed')
+                    throw new Error('Catalog snapshot failed; inspect source health.');
+                sequence(snapshot.snapshot_sequence);
+                const next = {
+                    ...checkpoint,
+                    phase: snapshot.status === 'ready' ? 'snapshot' : 'waiting',
+                    snapshotId: snapshot.id,
+                    replayCursor: snapshot.replay_cursor,
+                    lastSequence: snapshot.snapshot_sequence,
+                    ...(snapshot.count === undefined ? {} : { expectedCount: snapshot.count }),
+                };
+                const saved = await this.target.commit(state, next, async () => { });
+                return result(saved ? (snapshot.status === 'ready' ? 'progress' : 'waiting') : 'conflict');
+            }
+            if (checkpoint.phase === 'snapshot') {
+                const page = operations.listSnapshotItems.output.parse(await this.source.catalog.snapshotItems(checkpoint.snapshotId, {
+                    limit: this.pageSize,
+                    ...(checkpoint.snapshotCursor ? { cursor: checkpoint.snapshotCursor } : {}),
+                }, options));
+                if (page.data.length > this.pageSize ||
+                    (page.has_more &&
+                        (!page.next_cursor ||
+                            page.next_cursor === checkpoint.snapshotCursor ||
+                            page.data.length === 0)))
+                    throw new Error('Snapshot pagination did not advance within bounds.');
+                if (new Set(page.data.map((listing) => listing.id)).size !== page.data.length)
+                    throw new Error('Snapshot page repeats a listing identity.');
+                const count = checkpoint.stagedCount + page.data.length;
+                if (!page.has_more &&
+                    checkpoint.expectedCount !== undefined &&
+                    count !== checkpoint.expectedCount)
+                    throw new Error('Snapshot count did not match its declaration.');
+                const next = {
+                    ...checkpoint,
+                    stagedCount: count,
+                    phase: page.has_more ? 'snapshot' : 'replay',
+                    ...(page.has_more ? { snapshotCursor: page.next_cursor } : {}),
+                };
+                const saved = await this.target.commit(state, next, async (tx) => {
+                    for (const listing of page.data)
+                        await this.target.write(tx, checkpoint.generation, ListingSchema.parse(listing), listing.id, false, true);
+                });
+                return result(saved ? 'progress' : 'conflict', saved ? page.data.length : 0);
+            }
+            const page = operations.listCatalogChanges.output.parse(await this.source.catalog.changes({
+                dataset_id: this.target.configuration.datasetId,
+                cursor: checkpoint.replayCursor,
+                limit: this.pageSize,
+            }, options));
+            this.validateChanges(page, checkpoint);
+            const next = {
+                ...checkpoint,
+                replayCursor: page.next_cursor,
+                lastSequence: page.data.at(-1)?.sequence ?? checkpoint.lastSequence,
+                sourceFreshness: page.meta.source_freshness === undefined
+                    ? []
+                    : CatalogSourceFreshnessSchema.array().parse(page.meta.source_freshness),
+            };
+            const saved = await this.target.commit(state, next, async (tx) => {
+                for (const change of page.data)
+                    await this.target.write(tx, checkpoint.generation, change.listing, change.listing_id, state.active_generation === checkpoint.generation);
+                // Catch up changes before revealing a new snapshot, so a property removed while the
+                // snapshot was downloading does not briefly reappear at bootstrap completion.
+                if (!page.has_more && state.active_generation !== checkpoint.generation)
+                    await this.target.activate(tx, checkpoint.generation);
+            }, !page.has_more);
+            return result(saved ? (page.has_more || page.data.length ? 'progress' : 'idle') : 'conflict', saved ? page.data.length : 0);
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 410)
+                return result((await this.target.reset(state)) ? 'reset' : 'conflict');
+            if (error instanceof ApiError && [401, 403].includes(error.status)) {
+                await this.target.reset(state, true);
+            }
+            throw error;
+        }
+    }
+    validateChanges(page, checkpoint) {
+        if (!page.next_cursor ||
+            page.data.length > this.pageSize ||
+            (page.has_more && page.data.length === 0) ||
+            (page.data.length > 0 && page.next_cursor === checkpoint.replayCursor))
+            throw new Error('Change pagination did not advance within bounds.');
+        let previous = sequence(checkpoint.lastSequence);
+        for (const change of page.data) {
+            const current = sequence(change.sequence);
+            if (current <= previous)
+                throw new Error('Catalog changes must advance in publication order.');
+            if (change.operation === 'upsert' &&
+                (!change.listing ||
+                    change.listing.id !== change.listing_id ||
+                    change.listing.revision !== change.revision))
+                throw new Error('Invalid catalog upsert identity/revision.');
+            if (change.operation === 'remove' && change.listing !== null)
+                throw new Error('Catalog removal cannot contain a listing payload.');
+            previous = current;
+        }
+    }
+    async run(options) {
+        if (!Number.isInteger(options.maxSteps) || options.maxSteps < 1 || options.maxSteps > 1000)
+            throw new Error('Choose 1–1000 steps per invocation.');
+        const results = [];
+        for (let i = 0; i < options.maxSteps; i++) {
+            options.signal?.throwIfAborted();
+            const result = await this.step(options);
+            results.push(result);
+            if (['idle', 'waiting', 'blocked', 'conflict'].includes(result.status))
+                break;
+        }
+        return results;
+    }
+}

package/contracts/src/catalog-derived.d.ts

@@ -0,0 +1,7 @@
+import type { Listing } from './schemas.js';
+/** Deterministic source vocabulary only. In particular, EV-ready is not an
+ * installed charger, boat parking is not RV parking, and silence is not false. */
+export declare function sourceAmenities(listing: Listing): NonNullable<Listing['source_amenities']>;
+/** Rebuild from the permitted record, including on historical privacy redaction.
+ * This is input text for search/embeddings, not generated marketing content. */
+export declare function catalogSearchDocument(listing: Listing): NonNullable<Listing['search_document']>;

package/contracts/src/catalog-derived.js

@@ -0,0 +1,78 @@
+/** Deterministic source vocabulary only. In particular, EV-ready is not an
+ * installed charger, boat parking is not RV parking, and silence is not false. */
+export function sourceAmenities(listing) {
+    const features = listing.property_details?.features ?? {};
+    const rules = {
+        hardwood: { fields: ['Flooring'], values: /^(hardwood|hard wood|solid hardwood)$/i },
+        solar: {
+            fields: [
+                'GreenEnergyGeneration',
+                'Roof',
+                'Utilities',
+                'ExteriorFeatures',
+                'InteriorFeatures',
+            ],
+            values: /^(solar|solar panels|solar photovoltaic|solar electric|photovoltaics)$/i,
+        },
+        ev_charger: {
+            fields: ['ParkingFeatures', 'Utilities', 'GreenEnergyEfficient'],
+            values: /^(ev charger|electric vehicle charging station\(s\)|electric vehicle charging|electric vehicle charger|ev charging)$/i,
+        },
+        rv_parking: {
+            fields: ['ParkingFeatures'],
+            values: /^(rv parking|rv access\/parking|rv garage|recreational vehicle parking)$/i,
+        },
+        view: {
+            fields: ['View'],
+            values: /^(city|city lights|mountain\(s\)|mountain|ocean|water|lake|river|panoramic|park\/greenbelt|golf course|valley|trees\/woods)$/i,
+        },
+    };
+    return {
+        version: 'source-amenities-v1',
+        values: Object.fromEntries(Object.entries(rules).map(([key, rule]) => {
+            const positive = rule.fields.filter((field) => features[field]?.some((value) => rule.values.test(value.trim())));
+            const negative = rule.fields.filter((field) => features[field]?.some((value) => new RegExp(`^no ${key.replaceAll('_', ' ')}$`, 'i').test(value.trim()) ||
+                (key === 'view' && value.trim().toLowerCase() === 'none')));
+            const conflict = positive.length > 0 && negative.length > 0;
+            return [
+                key,
+                {
+                    value: conflict ? null : positive.length ? true : negative.length ? false : null,
+                    state: conflict
+                        ? 'conflicting'
+                        : positive.length || negative.length
+                            ? 'supported'
+                            : 'not_stated',
+                    source_paths: [...new Set([...positive, ...negative])].map((field) => `property_details.features.${field}`),
+                },
+            ];
+        })),
+    };
+}
+/** Rebuild from the permitted record, including on historical privacy redaction.
+ * This is input text for search/embeddings, not generated marketing content. */
+export function catalogSearchDocument(listing) {
+    const pieces = [
+        listing.property_details?.category,
+        listing.property_details?.sub_type,
+        listing.address.city,
+        listing.address.region,
+        listing.property_details?.subdivision,
+        listing.bedrooms === null ? null : `${listing.bedrooms} bedrooms`,
+        listing.bathrooms === null ? null : `${listing.bathrooms} bathrooms`,
+        listing.living_area !== null && listing.living_area_unit
+            ? `${listing.living_area} ${listing.living_area_unit}`
+            : null,
+        listing.year_built == null ? null : `built ${listing.year_built}`,
+        listing.price
+            ? `${listing.price.amount} ${listing.price.currency}${listing.price.period ? ` per ${listing.price.period}` : ''}`
+            : null,
+        ...Object.entries(listing.property_details?.source_flags ?? {}).map(([key, value]) => `${key}: ${value}`),
+        ...Object.entries(listing.property_details?.features ?? {}).map(([key, values]) => `${key}: ${values.join(', ')}`),
+        listing.description,
+    ];
+    return {
+        version: 'catalog-search-text-v1',
+        text: pieces.filter((value) => value != null && value !== '').join('. '),
+    };
+}