@propertysimple/client 0.1.0

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

@@ -0,0 +1,231 @@
+import { z } from 'zod';
+/** Additive shared contract. An absent block means an older parser, not empty source data. */
+export declare const CATALOG_FIELDS_VERSION = "catalog-fields-v2";
+export declare const SourceFieldsSchema: z.ZodObject<{
+    listhub: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strict>;
+export declare const SourceDateSchema: z.ZodObject<{
+    value: z.ZodNullable<z.ZodString>;
+    precision: z.ZodEnum<{
+        unknown: "unknown";
+        date: "date";
+        instant: "instant";
+    }>;
+}, z.core.$strict>;
+export declare const ProfessionalsSchema: z.ZodObject<{
+    agent: z.ZodObject<{
+        full_name: z.ZodNullable<z.ZodString>;
+        first_name: z.ZodNullable<z.ZodString>;
+        last_name: z.ZodNullable<z.ZodString>;
+        license: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    office: z.ZodObject<{
+        key: z.ZodNullable<z.ZodString>;
+        mls_id: z.ZodNullable<z.ZodString>;
+        name: z.ZodNullable<z.ZodString>;
+        broker_mls_id: z.ZodNullable<z.ZodString>;
+        corporate_id: z.ZodNullable<z.ZodString>;
+        main_office_id: z.ZodNullable<z.ZodString>;
+        website_url: z.ZodNullable<z.ZodURL>;
+        address: z.ZodObject<{
+            street: z.ZodNullable<z.ZodString>;
+            unit: z.ZodNullable<z.ZodString>;
+            city: z.ZodNullable<z.ZodString>;
+            region: z.ZodNullable<z.ZodString>;
+            postal_code: z.ZodNullable<z.ZodString>;
+            country: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    brokerage: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+        website_url: z.ZodNullable<z.ZodURL>;
+        logo_url: z.ZodNullable<z.ZodURL>;
+        address: z.ZodObject<{
+            street: z.ZodNullable<z.ZodString>;
+            unit: z.ZodNullable<z.ZodString>;
+            city: z.ZodNullable<z.ZodString>;
+            region: z.ZodNullable<z.ZodString>;
+            postal_code: z.ZodNullable<z.ZodString>;
+            country: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    builder: z.ZodObject<{
+        name: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    franchise: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const ProfessionalContactsSchema: z.ZodObject<{
+    agent: z.ZodObject<{
+        email: z.ZodNullable<z.ZodEmail>;
+        preferred_phone: z.ZodNullable<z.ZodString>;
+        direct_phone: z.ZodNullable<z.ZodString>;
+        office_phone: z.ZodNullable<z.ZodString>;
+        fax: z.ZodNullable<z.ZodString>;
+        website_url: z.ZodNullable<z.ZodURL>;
+    }, z.core.$strict>;
+    office: z.ZodObject<{
+        email: z.ZodNullable<z.ZodEmail>;
+        phone: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    brokerage: z.ZodObject<{
+        email: z.ZodNullable<z.ZodEmail>;
+        phone: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    builder: z.ZodObject<{
+        email: z.ZodNullable<z.ZodEmail>;
+        phone: z.ZodNullable<z.ZodString>;
+        fax: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const SharedListingFields: {
+    source_amenities: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<"source-amenities-v1">;
+        values: z.ZodRecord<z.ZodEnum<{
+            hardwood: "hardwood";
+            solar: "solar";
+            ev_charger: "ev_charger";
+            rv_parking: "rv_parking";
+            view: "view";
+        }>, z.ZodObject<{
+            value: z.ZodNullable<z.ZodBoolean>;
+            state: z.ZodEnum<{
+                supported: "supported";
+                not_stated: "not_stated";
+                conflicting: "conflicting";
+            }>;
+            source_paths: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    search_document: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<"catalog-search-text-v1">;
+        text: z.ZodString;
+    }, z.core.$strict>>;
+    content_hash: z.ZodOptional<z.ZodString>;
+    source_fields: z.ZodOptional<z.ZodObject<{
+        listhub: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    }, z.core.$strict>>;
+    source_metadata: z.ZodOptional<z.ZodObject<{
+        contract_version: z.ZodLiteral<"catalog-fields-v2">;
+        parser_version: z.ZodString;
+        exposure_version: z.ZodString;
+        source_system_id: z.ZodNullable<z.ZodString>;
+        source_system_name: z.ZodNullable<z.ZodString>;
+        originating_system_name: z.ZodNullable<z.ZodString>;
+        source_photo_count: z.ZodNullable<z.ZodNumber>;
+        supplied_paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    market_dates: z.ZodOptional<z.ZodObject<{
+        listing_contract: z.ZodObject<{
+            value: z.ZodNullable<z.ZodString>;
+            precision: z.ZodEnum<{
+                unknown: "unknown";
+                date: "date";
+                instant: "instant";
+            }>;
+        }, z.core.$strict>;
+        on_market: z.ZodObject<{
+            value: z.ZodNullable<z.ZodString>;
+            precision: z.ZodEnum<{
+                unknown: "unknown";
+                date: "date";
+                instant: "instant";
+            }>;
+        }, z.core.$strict>;
+        source_days_on_market: z.ZodNullable<z.ZodNumber>;
+        source_cumulative_days_on_market: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    taxes: z.ZodOptional<z.ZodObject<{
+        annual_amount: z.ZodNullable<z.ZodString>;
+        currency: z.ZodNullable<z.ZodString>;
+        year: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>>;
+    schools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        level: z.ZodEnum<{
+            elementary: "elementary";
+            middle: "middle";
+            high: "high";
+        }>;
+        name: z.ZodNullable<z.ZodString>;
+        district: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+    price_history: z.ZodOptional<z.ZodObject<{
+        original_amount: z.ZodNullable<z.ZodString>;
+        previous_amount: z.ZodNullable<z.ZodString>;
+        low_amount: z.ZodNullable<z.ZodString>;
+        currency: z.ZodNullable<z.ZodString>;
+        original_currency: z.ZodNullable<z.ZodString>;
+        previous_currency: z.ZodNullable<z.ZodString>;
+        low_currency: z.ZodNullable<z.ZodString>;
+        changed_at: z.ZodObject<{
+            value: z.ZodNullable<z.ZodString>;
+            precision: z.ZodEnum<{
+                unknown: "unknown";
+                date: "date";
+                instant: "instant";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    virtual_tours: z.ZodOptional<z.ZodObject<{
+        branded_url: z.ZodNullable<z.ZodURL>;
+        unbranded_url: z.ZodNullable<z.ZodURL>;
+    }, z.core.$strict>>;
+    additional_media: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodURL;
+        categories: z.ZodArray<z.ZodString>;
+        order: z.ZodNumber;
+        caption: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+    professionals: z.ZodOptional<z.ZodObject<{
+        agent: z.ZodObject<{
+            full_name: z.ZodNullable<z.ZodString>;
+            first_name: z.ZodNullable<z.ZodString>;
+            last_name: z.ZodNullable<z.ZodString>;
+            license: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        office: z.ZodObject<{
+            key: z.ZodNullable<z.ZodString>;
+            mls_id: z.ZodNullable<z.ZodString>;
+            name: z.ZodNullable<z.ZodString>;
+            broker_mls_id: z.ZodNullable<z.ZodString>;
+            corporate_id: z.ZodNullable<z.ZodString>;
+            main_office_id: z.ZodNullable<z.ZodString>;
+            website_url: z.ZodNullable<z.ZodURL>;
+            address: z.ZodObject<{
+                street: z.ZodNullable<z.ZodString>;
+                unit: z.ZodNullable<z.ZodString>;
+                city: z.ZodNullable<z.ZodString>;
+                region: z.ZodNullable<z.ZodString>;
+                postal_code: z.ZodNullable<z.ZodString>;
+                country: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        brokerage: z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+            website_url: z.ZodNullable<z.ZodURL>;
+            logo_url: z.ZodNullable<z.ZodURL>;
+            address: z.ZodObject<{
+                street: z.ZodNullable<z.ZodString>;
+                unit: z.ZodNullable<z.ZodString>;
+                city: z.ZodNullable<z.ZodString>;
+                region: z.ZodNullable<z.ZodString>;
+                postal_code: z.ZodNullable<z.ZodString>;
+                country: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        builder: z.ZodObject<{
+            name: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        franchise: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    permissions: z.ZodOptional<z.ZodObject<{
+        internet_display: z.ZodNullable<z.ZodBoolean>;
+        entire_listing_display: z.ZodNullable<z.ZodBoolean>;
+        address_display: z.ZodNullable<z.ZodBoolean>;
+        automated_valuation_display: z.ZodNullable<z.ZodBoolean>;
+        consumer_comment: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>>;
+};
+/** Unit conversions are shared by adapters. Unknown units never become square feet. */
+export declare function convertArea(value: number | null | undefined, unit: string | null | undefined, target: 'sqft' | 'acres'): number | null;
+/** Recursively remove location-bearing aliases from extensions, including old snapshots. */
+export declare function redactSourceAddress(fields: z.infer<typeof SourceFieldsSchema>): z.infer<typeof SourceFieldsSchema>;

package/contracts/src/catalog-fields.js

@@ -0,0 +1,194 @@
+import { z } from 'zod';
+/** Additive shared contract. An absent block means an older parser, not empty source data. */
+export const CATALOG_FIELDS_VERSION = 'catalog-fields-v2';
+export const SourceFieldsSchema = z.strictObject({ listhub: z.record(z.string(), z.json()) });
+const text = z.string().nullable();
+const count = z.number().nonnegative().nullable();
+const amount = z
+    .string()
+    .regex(/^\d+(?:\.\d{1,2})?$/)
+    .nullable();
+const currency = z
+    .string()
+    .regex(/^[A-Z]{3}$/)
+    .nullable();
+const httpUrl = z.url({ protocol: /^https?$/ }).nullable();
+export const SourceDateSchema = z.strictObject({
+    value: text,
+    precision: z.enum(['date', 'instant', 'unknown']),
+});
+const businessAddress = z.strictObject({
+    street: text,
+    unit: text,
+    city: text,
+    region: text,
+    postal_code: text,
+    country: text,
+});
+export const ProfessionalsSchema = z.strictObject({
+    agent: z.strictObject({
+        full_name: text,
+        first_name: text,
+        last_name: text,
+        license: text,
+    }),
+    office: z.strictObject({
+        key: text,
+        mls_id: text,
+        name: text,
+        broker_mls_id: text,
+        corporate_id: text,
+        main_office_id: text,
+        website_url: httpUrl,
+        address: businessAddress,
+    }),
+    brokerage: z.strictObject({
+        name: text,
+        website_url: httpUrl,
+        logo_url: httpUrl,
+        address: businessAddress,
+    }),
+    builder: z.strictObject({ name: text }),
+    franchise: text,
+});
+export const ProfessionalContactsSchema = z.strictObject({
+    agent: z.strictObject({
+        email: z.email().nullable(),
+        preferred_phone: text,
+        direct_phone: text,
+        office_phone: text,
+        fax: text,
+        website_url: httpUrl,
+    }),
+    office: z.strictObject({ email: z.email().nullable(), phone: text }),
+    brokerage: z.strictObject({ email: z.email().nullable(), phone: text }),
+    builder: z.strictObject({ email: z.email().nullable(), phone: text, fax: text }),
+});
+export const SharedListingFields = {
+    source_amenities: z
+        .strictObject({
+        version: z.literal('source-amenities-v1'),
+        values: z.record(z.enum(['hardwood', 'solar', 'ev_charger', 'rv_parking', 'view']), z.strictObject({
+            value: z.boolean().nullable(),
+            state: z.enum(['supported', 'not_stated', 'conflicting']),
+            source_paths: z.array(z.string()),
+        })),
+    })
+        .optional(),
+    search_document: z
+        .strictObject({ version: z.literal('catalog-search-text-v1'), text: z.string() })
+        .optional(),
+    content_hash: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/)
+        .optional(),
+    source_fields: SourceFieldsSchema.optional(),
+    source_metadata: z
+        .strictObject({
+        contract_version: z.literal(CATALOG_FIELDS_VERSION),
+        parser_version: z.string(),
+        exposure_version: z.string(),
+        source_system_id: text,
+        source_system_name: text,
+        originating_system_name: text,
+        source_photo_count: z.number().int().nonnegative().nullable(),
+        // Presence covers permitted paths only. Unreviewed names/values stay private.
+        supplied_paths: z.array(z.string()),
+    })
+        .optional(),
+    market_dates: z
+        .strictObject({
+        listing_contract: SourceDateSchema,
+        on_market: SourceDateSchema,
+        source_days_on_market: count,
+        source_cumulative_days_on_market: count,
+    })
+        .optional(),
+    taxes: z
+        .strictObject({ annual_amount: amount, currency, year: z.number().int().nullable() })
+        .optional(),
+    schools: z
+        .array(z.strictObject({
+        level: z.enum(['elementary', 'middle', 'high']),
+        name: text,
+        district: text,
+    }))
+        .optional(),
+    price_history: z
+        .strictObject({
+        original_amount: amount,
+        previous_amount: amount,
+        low_amount: amount,
+        currency,
+        original_currency: currency,
+        previous_currency: currency,
+        low_currency: currency,
+        changed_at: SourceDateSchema,
+    })
+        .optional(),
+    virtual_tours: z.strictObject({ branded_url: httpUrl, unbranded_url: httpUrl }).optional(),
+    additional_media: z
+        .array(z.strictObject({
+        url: z.url({ protocol: /^https?$/ }),
+        categories: z.array(z.string()),
+        order: z.number().int().nonnegative(),
+        caption: text,
+    }))
+        .optional(),
+    professionals: ProfessionalsSchema.optional(),
+    permissions: z
+        .strictObject({
+        internet_display: z.boolean().nullable(),
+        entire_listing_display: z.boolean().nullable(),
+        address_display: z.boolean().nullable(),
+        automated_valuation_display: z.boolean().nullable(),
+        consumer_comment: z.boolean().nullable(),
+    })
+        .optional(),
+};
+/** Unit conversions are shared by adapters. Unknown units never become square feet. */
+export function convertArea(value, unit, target) {
+    if (value == null || !Number.isFinite(value) || value < 0)
+        return null;
+    const normalized = unit?.trim().toLowerCase();
+    const sqft = normalized === 'sqft' || normalized === 'square feet'
+        ? value
+        : normalized === 'sqm' || normalized === 'square meters'
+            ? value / 0.09290304
+            : normalized === 'acres' || normalized === 'acre'
+                ? value * 43560
+                : null;
+    return sqft === null ? null : target === 'sqft' ? sqft : sqft / 43560;
+}
+/** Recursively remove location-bearing aliases from extensions, including old snapshots. */
+export function redactSourceAddress(fields) {
+    const hidden = new Set([
+        'UnparsedAddress',
+        'UnitNumber',
+        'StreetNumber',
+        'StreetNumberNumeric',
+        'StreetName',
+        'StreetDirPrefix',
+        'StreetDirSuffix',
+        'StreetSuffix',
+        'Latitude',
+        'Longitude',
+        'Location',
+        'GeocodeOptions',
+        'SubdivisionName',
+        'Directions',
+        'ParcelNumber',
+        'TaxLegalDescription',
+        'Neighborhoods',
+    ]);
+    const walk = (value) => {
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value && typeof value === 'object')
+            return Object.fromEntries(Object.entries(value)
+                .filter(([key]) => !hidden.has(key))
+                .map(([key, child]) => [key, walk(child)]));
+        return value;
+    };
+    return { listhub: walk(fields.listhub) };
+}

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

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/** Inventory progress is distinct from a completed source refresh. Processed
+ * source records include non-displayable records; they are not a search total. */
+export declare const CatalogInventoryStatusSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        partial: "partial";
+        complete: "complete";
+    }>;
+    source_observed_at: z.ZodNullable<z.ZodISODateTime>;
+    expected_source_records: z.ZodNullable<z.ZodNumber>;
+    processed_source_records: z.ZodNullable<z.ZodNumber>;
+    valid_until: z.ZodISODateTime;
+}, z.core.$strict>;
+export type CatalogInventoryStatus = z.infer<typeof CatalogInventoryStatusSchema>;

package/contracts/src/catalog-inventory.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+/** Inventory progress is distinct from a completed source refresh. Processed
+ * source records include non-displayable records; they are not a search total. */
+export const CatalogInventoryStatusSchema = z.strictObject({
+    state: z.enum(['partial', 'complete']),
+    source_observed_at: z.iso.datetime({ offset: true }).nullable(),
+    expected_source_records: z.number().int().nonnegative().nullable(),
+    processed_source_records: z.number().int().nonnegative().nullable(),
+    valid_until: z.iso.datetime({ offset: true }),
+});