@propertysimple/client 0.1.0

package/contracts/src/intelligence.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+const Key = z.string().regex(/^[a-zA-Z0-9_-]{1,80}$/);
+const Text = z.string().min(1).max(4000);
+const Span = z.strictObject({ id: Key, text: Text });
+const Spans = z.array(Span).min(1).max(20);
+const Timestamp = z.iso.datetime({ offset: true });
+export const JudgmentTask = z.enum([
+    'claim_verification',
+    'meaningful_text_change',
+    'marketing_angle',
+    'preference_relevance',
+    'intent_routing',
+    'operational_triage',
+]);
+export const JudgmentRequest = z.discriminatedUnion('task', [
+    z.strictObject({
+        task: z.literal('claim_verification'),
+        claims: z.array(Span).min(1).max(10),
+        source_spans: Spans,
+    }),
+    z.strictObject({ task: z.literal('meaningful_text_change'), before: Text, after: Text }),
+    z.strictObject({
+        task: z.literal('marketing_angle'),
+        product_brief: z.string().min(1).max(1000),
+        candidates: z.array(Span).min(1).max(10),
+        source_spans: Spans,
+        previous_messages: z.array(Span).max(20),
+    }),
+    z.strictObject({
+        task: z.literal('preference_relevance'),
+        preferences: z
+            .array(z.strictObject({
+            id: Key,
+            text: z.string().min(1).max(1000),
+            importance: z.enum(['required', 'preferred']),
+        }))
+            .min(1)
+            .max(10),
+        candidates: z.array(Span).min(1).max(20),
+    }),
+    z.strictObject({ task: z.literal('intent_routing'), text: Text }),
+    z.strictObject({
+        task: z.literal('operational_triage'),
+        component: z.enum(['api', 'worker', 'source', 'model', 'database', 'unknown']),
+        sanitized_logs: z.array(Span).min(1).max(20),
+    }),
+]);
+const Verdict = z.enum(['supported', 'contradicted', 'not_established', 'conflicting']);
+const Intent = z.enum([
+    'billing',
+    'listing_correction',
+    'access_issue',
+    'marketing_question',
+    'technical_issue',
+    'tour_request',
+    'property_details',
+    'agent_help',
+    'unsubscribe',
+    'other',
+    'unknown',
+]);
+export const JudgmentDecision = z.discriminatedUnion('task', [
+    z.strictObject({
+        task: z.literal('claim_verification'),
+        claims: z
+            .array(z.strictObject({
+            id: Key,
+            verdict: Verdict,
+            evidence_refs: z.array(Key),
+            review_required: z.boolean(),
+        }))
+            .max(10),
+    }),
+    z.strictObject({
+        task: z.literal('meaningful_text_change'),
+        change: z.enum(['material', 'editorial', 'unchanged', 'uncertain']),
+        review_required: z.boolean(),
+    }),
+    z.strictObject({
+        task: z.literal('marketing_angle'),
+        selected_candidate_id: Key.nullable(),
+        repeat_status: z.enum(['novel', 'repetition', 'unknown']),
+        evidence_refs: z.array(Key),
+        review_required: z.boolean(),
+    }),
+    z.strictObject({
+        task: z.literal('preference_relevance'),
+        ranked: z
+            .array(z.strictObject({
+            candidate_id: Key,
+            score: z.number().min(0).max(3).nullable(),
+            relevance: z.enum(['relevant', 'not_relevant', 'unknown']),
+        }))
+            .max(20),
+        review_required: z.boolean(),
+    }),
+    z.strictObject({
+        task: z.literal('intent_routing'),
+        intent: Intent,
+        urgent: z.boolean().nullable(),
+        review_required: z.boolean(),
+    }),
+    z.strictObject({
+        task: z.literal('operational_triage'),
+        category: z.enum(['auth', 'source_format', 'rate_limit', 'transient_dependency', 'unknown']),
+        severity: z.enum(['informational', 'degraded', 'blocking', 'critical', 'unknown']),
+        recommended_check: z.enum([
+            'credential_configuration',
+            'source_contract',
+            'retry_budget',
+            'dependency_health',
+            'manual_review',
+        ]),
+        review_required: z.boolean(),
+    }),
+]);
+export const JudgmentProvenance = z.strictObject({
+    provider: z.enum(['openrouter', 'vercel_gateway', 'fixture', 'disabled']),
+    requested_model: z.string(),
+    resolved_model: z.string().nullable(),
+    model_policy: z.enum(['pinned', 'rolling_alias', 'fixture']),
+    policy_revision: z.string(),
+    adapter_version: z.string(),
+    /** A code-owned result retains the requested route but did not invoke it. */
+    execution: z.literal('deterministic_exact_comparison').optional(),
+});
+export const JudgmentSchema = z.strictObject({
+    id: z.string(),
+    task: JudgmentTask,
+    task_version: z.string(),
+    state: z.enum(['running', 'succeeded', 'failed', 'expired']),
+    input_fingerprint: z.string(),
+    source_trust: z.literal('caller_supplied'),
+    provenance: JudgmentProvenance,
+    result: JudgmentDecision.nullable(),
+    error_code: z.string().nullable(),
+    created_at: Timestamp,
+    completed_at: Timestamp.nullable(),
+    valid_until: Timestamp,
+    cached: z.boolean(),
+});
+export const IntelligenceCapabilitySchema = z.strictObject({
+    id: z.string(),
+    description: z.string(),
+    status: z.enum(['implemented', 'not_implemented']),
+    task_version: z.string().nullable(),
+    task_id: JudgmentTask.nullable(),
+    input_kind: z.string(),
+    limitations: z.array(z.string()),
+});
+export const IntelligenceCapabilitiesSchema = z.strictObject({
+    data: z.array(IntelligenceCapabilitySchema),
+    provider: JudgmentProvenance,
+    effects_enabled: z.boolean(),
+    catalog_model: z.string(),
+    taxonomy_version: z.string(),
+});

package/contracts/src/location-serving.d.ts

@@ -0,0 +1,13 @@
+import type { Listing } from './schemas.js';
+import type { ListingLocation } from './location.js';
+/** A withheld address is still a listing. Apply this to historical payloads too:
+ * absent source fields must never preserve an older public or geocoded location. */
+export declare function redactListingAddress<T extends Listing>(listing: T): T;
+export declare function emptyLocation(policyVersion: string, state: ListingLocation['state'], issue?: ListingLocation['issue']): ListingLocation;
+/** The catalog still owns visibility. Enrichment may never undo a source display restriction. */
+export declare function applyLocationProjection<T extends Listing>(listing: T, projection: ListingLocation): T & {
+    location: ListingLocation;
+};
+/** Direct reads and managed consumers must apply expiry even before the next
+ * publication sweep. Source points remain valid when only their appends expire. */
+export declare function freshLocationProjection<T extends Listing>(listing: T, at: Date): T;

package/contracts/src/location-serving.js

@@ -0,0 +1,89 @@
+import { redactSourceAddress } from './catalog-fields.js';
+import { catalogSearchDocument } from './catalog-derived.js';
+/** A withheld address is still a listing. Apply this to historical payloads too:
+ * absent source fields must never preserve an older public or geocoded location. */
+export function redactListingAddress(listing) {
+    if (listing.display.address_allowed)
+        return listing;
+    const redacted = {
+        ...listing,
+        address: { ...listing.address, street: null, unit: null },
+        ...(listing.source_fields ? { source_fields: redactSourceAddress(listing.source_fields) } : {}),
+        ...(listing.source_metadata
+            ? {
+                source_metadata: {
+                    ...listing.source_metadata,
+                    supplied_paths: listing.source_metadata.supplied_paths.filter((path) => !/(^|\.)(UnparsedAddress|UnitNumber|Street\w*|Latitude|Longitude|Location|GeocodeOptions|SubdivisionName|Directions|ParcelNumber|TaxLegalDescription|Neighborhoods)(\.|\[|$)/.test(path)),
+                },
+            }
+            : {}),
+        ...(listing.property_details
+            ? { property_details: { ...listing.property_details, subdivision: null } }
+            : {}),
+        latitude: null,
+        longitude: null,
+        ...(listing.location
+            ? {
+                location: emptyLocation(listing.location.policy_version, 'suppressed', 'display_restricted'),
+            }
+            : {}),
+    };
+    if (redacted.search_document)
+        redacted.search_document = catalogSearchDocument(redacted);
+    return redacted;
+}
+export function emptyLocation(policyVersion, state, issue = null) {
+    return {
+        state,
+        origin: null,
+        precision: 'unknown',
+        map_eligible: false,
+        coordinates: null,
+        accuracy_score: null,
+        accuracy_type: null,
+        match_type: null,
+        provider: null,
+        provider_version: null,
+        policy_version: policyVersion,
+        source: null,
+        resolved_at: null,
+        valid_until: null,
+        country_code: null,
+        region_code: null,
+        timezone: null,
+        enrichment: null,
+        geography: null,
+        issue,
+    };
+}
+/** The catalog still owns visibility. Enrichment may never undo a source display restriction. */
+export function applyLocationProjection(listing, projection) {
+    const location = listing.display.address_allowed
+        ? projection
+        : emptyLocation(projection.policy_version, 'suppressed', 'display_restricted');
+    return {
+        ...redactListingAddress(listing),
+        latitude: location.map_eligible ? (location.coordinates?.latitude ?? null) : null,
+        longitude: location.map_eligible ? (location.coordinates?.longitude ?? null) : null,
+        location,
+    };
+}
+/** Direct reads and managed consumers must apply expiry even before the next
+ * publication sweep. Source points remain valid when only their appends expire. */
+export function freshLocationProjection(listing, at) {
+    listing = redactListingAddress(listing);
+    const location = listing.location;
+    if (!location)
+        return listing;
+    if (!listing.display.address_allowed)
+        return applyLocationProjection(listing, location);
+    if (location.origin === 'geocoded' &&
+        (!location.valid_until || Date.parse(location.valid_until) <= at.getTime()))
+        return applyLocationProjection(listing, emptyLocation(location.policy_version, 'stale', 'expired'));
+    if (location.enrichment && Date.parse(location.enrichment.valid_until) <= at.getTime())
+        return {
+            ...listing,
+            location: { ...location, timezone: null, geography: null, enrichment: null },
+        };
+    return listing;
+}

package/contracts/src/location.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+/** Accuracy describes the evidence available; a match score is not a distance error bound. */
+export declare const LocationSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        source: "source";
+        pending: "pending";
+        resolved: "resolved";
+        coarse: "coarse";
+        unavailable: "unavailable";
+        stale: "stale";
+        suppressed: "suppressed";
+    }>;
+    origin: z.ZodNullable<z.ZodEnum<{
+        source: "source";
+        geocoded: "geocoded";
+    }>>;
+    precision: z.ZodEnum<{
+        source_unknown: "source_unknown";
+        parcel: "parcel";
+        street: "street";
+        area: "area";
+        unknown: "unknown";
+    }>;
+    map_eligible: z.ZodBoolean;
+    coordinates: z.ZodNullable<z.ZodObject<{
+        latitude: z.ZodNumber;
+        longitude: z.ZodNumber;
+    }, z.core.$strip>>;
+    accuracy_score: z.ZodNullable<z.ZodNumber>;
+    accuracy_type: z.ZodNullable<z.ZodString>;
+    match_type: z.ZodNullable<z.ZodString>;
+    provider: z.ZodNullable<z.ZodString>;
+    provider_version: z.ZodNullable<z.ZodString>;
+    policy_version: z.ZodString;
+    source: z.ZodNullable<z.ZodString>;
+    resolved_at: z.ZodNullable<z.ZodISODateTime>;
+    valid_until: z.ZodNullable<z.ZodISODateTime>;
+    country_code: z.ZodNullable<z.ZodString>;
+    region_code: z.ZodNullable<z.ZodString>;
+    timezone: z.ZodNullable<z.ZodString>;
+    enrichment: z.ZodNullable<z.ZodObject<{
+        provider: z.ZodString;
+        provider_version: z.ZodString;
+        resolved_at: z.ZodISODateTime;
+        valid_until: z.ZodISODateTime;
+        fields: z.ZodArray<z.ZodEnum<{
+            timezone: "timezone";
+            census2025: "census2025";
+        }>>;
+    }, z.core.$strip>>;
+    geography: z.ZodNullable<z.ZodObject<{
+        census_year: z.ZodNumber;
+        state_fips: z.ZodNullable<z.ZodString>;
+        county_fips: z.ZodNullable<z.ZodString>;
+        tract_geoid: z.ZodNullable<z.ZodString>;
+        block_geoid: z.ZodNullable<z.ZodString>;
+        place_fips: z.ZodNullable<z.ZodString>;
+        cbsa_code: z.ZodNullable<z.ZodString>;
+        source: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    issue: z.ZodNullable<z.ZodEnum<{
+        pending: "pending";
+        invalid_source_point: "invalid_source_point";
+        insufficient_address: "insufficient_address";
+        unsupported_country: "unsupported_country";
+        no_match: "no_match";
+        low_quality: "low_quality";
+        provider_failure: "provider_failure";
+        expired: "expired";
+        display_restricted: "display_restricted";
+    }>>;
+}, z.core.$strip>;
+export type ListingLocation = z.infer<typeof LocationSchema>;

package/contracts/src/location.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/** Accuracy describes the evidence available; a match score is not a distance error bound. */
+export const LocationSchema = z.object({
+    state: z.enum(['source', 'pending', 'resolved', 'coarse', 'unavailable', 'stale', 'suppressed']),
+    origin: z.enum(['source', 'geocoded']).nullable(),
+    precision: z.enum(['source_unknown', 'parcel', 'street', 'area', 'unknown']),
+    map_eligible: z.boolean(),
+    coordinates: z
+        .object({ latitude: z.number().min(-90).max(90), longitude: z.number().min(-180).max(180) })
+        .nullable(),
+    accuracy_score: z.number().min(0).max(1).nullable(),
+    accuracy_type: z.string().nullable(),
+    match_type: z.string().nullable(),
+    provider: z.string().nullable(),
+    provider_version: z.string().nullable(),
+    policy_version: z.string(),
+    source: z.string().nullable(),
+    resolved_at: z.iso.datetime().nullable(),
+    valid_until: z.iso.datetime().nullable(),
+    country_code: z.string().nullable(),
+    region_code: z.string().nullable(),
+    timezone: z.string().nullable(),
+    enrichment: z
+        .object({
+        provider: z.string(),
+        provider_version: z.string(),
+        resolved_at: z.iso.datetime(),
+        valid_until: z.iso.datetime(),
+        fields: z.array(z.enum(['timezone', 'census2025'])),
+    })
+        .nullable(),
+    geography: z
+        .object({
+        census_year: z.number().int(),
+        state_fips: z
+            .string()
+            .regex(/^\d{2}$/)
+            .nullable(),
+        county_fips: z
+            .string()
+            .regex(/^\d{5}$/)
+            .nullable(),
+        tract_geoid: z
+            .string()
+            .regex(/^\d{11}$/)
+            .nullable(),
+        block_geoid: z
+            .string()
+            .regex(/^\d{15}$/)
+            .nullable(),
+        place_fips: z
+            .string()
+            .regex(/^\d{7}$/)
+            .nullable(),
+        cbsa_code: z
+            .string()
+            .regex(/^\d{5}$/)
+            .nullable(),
+        source: z.string().nullable(),
+    })
+        .nullable(),
+    issue: z
+        .enum([
+        'invalid_source_point',
+        'insufficient_address',
+        'unsupported_country',
+        'no_match',
+        'low_quality',
+        'provider_failure',
+        'pending',
+        'expired',
+        'display_restricted',
+    ])
+        .nullable(),
+});

package/contracts/src/openapi.d.ts

@@ -0,0 +1,22 @@
+/** Generate at runtime/build from the same validators used at both ends of the wire. */
+export declare function createOpenApiDocument(): {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description: string;
+    };
+    servers: {
+        url: string;
+    }[];
+    paths: Record<string, Record<string, unknown>>;
+    components: {
+        securitySchemes: {
+            bearerAuth: {
+                type: string;
+                scheme: string;
+            };
+        };
+        schemas: Record<string, unknown>;
+    };
+};

package/contracts/src/openapi.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { operations } from './operations.js';
+import { ProblemSchema } from './schemas.js';
+import { routes } from './routes.js';
+/** Generate at runtime/build from the same validators used at both ends of the wire. */
+export function createOpenApiDocument() {
+    const paths = {};
+    const schemas = {};
+    const register = (name, schema) => {
+        // Zod's recursive JSON values use local refs. Once embedded in OpenAPI they must
+        // point at this component, not at an unrelated $defs at the document root.
+        const rewrite = (value) => {
+            if (Array.isArray(value))
+                return value.map(rewrite);
+            if (value && typeof value === 'object')
+                return Object.fromEntries(Object.entries(value)
+                    .filter(([key]) => key !== '$schema')
+                    .map(([key, child]) => [
+                    key,
+                    key === '$ref' && typeof child === 'string' && child.startsWith('#')
+                        ? `#/components/schemas/${name}${child.slice(1)}`
+                        : rewrite(child),
+                ]));
+            return value;
+        };
+        schemas[name] = rewrite(schema);
+        return { $ref: `#/components/schemas/${name}` };
+    };
+    const problem = register('Problem', z.toJSONSchema(ProblemSchema));
+    for (const route of routes) {
+        const contract = operations[route.operation];
+        const input = z.toJSONSchema(contract.input, { io: 'input' });
+        const pathNames = [...route.path.matchAll(/\{([^}]+)\}/g)].map((match) => match[1]);
+        const properties = (input.properties ?? {});
+        const parameters = pathNames.map((name) => ({
+            name,
+            in: 'path',
+            required: true,
+            schema: properties[name],
+        }));
+        let requestBody;
+        if (route.method === 'GET') {
+            for (const [name, schema] of Object.entries(properties)) {
+                if (!pathNames.includes(name))
+                    parameters.push({
+                        name,
+                        in: 'query',
+                        required: input.required?.includes(name) ?? false,
+                        schema,
+                        ...(schema && typeof schema === 'object' && 'type' in schema && schema.type === 'array'
+                            ? { style: 'form', explode: false }
+                            : {}),
+                    });
+            }
+        }
+        else {
+            if (!('readOnly' in route && route.readOnly))
+                parameters.push({
+                    name: 'Idempotency-Key',
+                    in: 'header',
+                    required: true,
+                    schema: { type: 'string', minLength: 1, maxLength: 200 },
+                });
+            // Path identity is never accepted a second time in JSON, where it could disagree.
+            const bodyProperties = Object.fromEntries(Object.entries(properties).filter(([name]) => !pathNames.includes(name)));
+            const body = register(`${route.operation}Request`, {
+                ...input,
+                properties: bodyProperties,
+                required: input.required?.filter((name) => !pathNames.includes(name)),
+            });
+            requestBody = { required: true, content: { 'application/json': { schema: body } } };
+        }
+        const status = 'status' in route ? route.status : 200;
+        paths[route.path] ??= {};
+        paths[route.path][route.method.toLowerCase()] = {
+            operationId: route.operation,
+            summary: route.summary,
+            security: [{ bearerAuth: [] }],
+            parameters,
+            ...('scope' in route ? { 'x-required-scope': route.scope } : {}),
+            ...(requestBody ? { requestBody } : {}),
+            responses: {
+                [status]: {
+                    description: 'Validated response',
+                    content: {
+                        'application/json': {
+                            schema: register(`${route.operation}Response`, z.toJSONSchema(contract.output)),
+                        },
+                    },
+                },
+                default: {
+                    description: 'Problem details; code is stable across message changes.',
+                    content: { 'application/problem+json': { schema: problem } },
+                },
+            },
+        };
+    }
+    return {
+        openapi: '3.1.1',
+        info: {
+            title: 'Listings Intelligence API',
+            version: '1.0.0',
+            description: 'Current classified catalog and persisted, authorized opportunity selections. Creating a plan does not send a message.',
+        },
+        servers: [{ url: '/' }],
+        paths,
+        components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } }, schemas },
+    };
+}