@propertysimple/client 0.1.0

package/client/src/index.js

@@ -0,0 +1,285 @@
+import { operations, opportunityObservation, ProblemSchema, routes, } from '../../contracts/src/index.js';
+export const DEFAULT_BASE_URL = 'https://api.propertysimple.ai';
+export class ApiError extends Error {
+    status;
+    code;
+    problem;
+    constructor(status, code, message, problem) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.problem = problem;
+        this.name = 'ApiError';
+    }
+}
+export class ContractError extends Error {
+    operation;
+    constructor(message, operation) {
+        super(message);
+        this.operation = operation;
+        this.name = 'ContractError';
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', abort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', abort, { once: true });
+    });
+}
+/** Each instance owns its credential; there is no mutable process-global tenant configuration. */
+export class ListingsClient {
+    options;
+    constructor(options) {
+        if (typeof window !== 'undefined')
+            throw new Error('Service credentials belong on the product backend, not in browser bundles.');
+        const base = new URL(options.baseUrl ?? DEFAULT_BASE_URL);
+        if (base.username || base.password || base.search || base.hash)
+            throw new Error('baseUrl must not contain credentials, query parameters or fragments.');
+        if (base.protocol !== 'https:' &&
+            !(base.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname)))
+            throw new Error('Use HTTPS except for a loopback development server.');
+        if (!options.apiKey || /[\r\n]/.test(options.apiKey))
+            throw new Error('A valid service API key is required.');
+        this.options = {
+            ...options,
+            baseUrl: base.toString(),
+            fetch: options.fetch ?? fetch,
+            timeoutMs: options.timeoutMs ?? 15000,
+            maxRetries: options.maxRetries ?? 2,
+        };
+        if (!Number.isSafeInteger(this.options.timeoutMs) ||
+            this.options.timeoutMs < 1 ||
+            !Number.isInteger(this.options.maxRetries) ||
+            this.options.maxRetries < 0 ||
+            this.options.maxRetries > 5)
+            throw new Error('Invalid timeout or retry limit.');
+    }
+    async call(operation, input, options = {}) {
+        const route = routes.find((candidate) => candidate.operation === operation);
+        const parsed = operations[operation].input.safeParse(input);
+        if (!parsed.success)
+            throw new ContractError(`Invalid input for ${operation}: ${parsed.error.issues.map((issue) => issue.path.join('.')).join(', ')}`, operation);
+        const values = { ...parsed.data };
+        let path = route.path;
+        path = path.replace(/\{([^}]+)\}/g, (_, name) => {
+            const value = values[name];
+            delete values[name];
+            return encodeURIComponent(String(value));
+        });
+        const url = new URL(path, this.options.baseUrl);
+        if (route.method === 'GET')
+            for (const [key, value] of Object.entries(values))
+                if (value !== undefined)
+                    url.searchParams.set(key, Array.isArray(value) ? value.join(',') : String(value));
+        if (route.method === 'POST' &&
+            !('readOnly' in route && route.readOnly) &&
+            !options.idempotencyKey)
+            throw new ContractError(`An idempotencyKey is required for ${operation}.`, operation);
+        const headers = {
+            authorization: `Bearer ${this.options.apiKey}`,
+            accept: 'application/json',
+        };
+        if (route.method === 'POST') {
+            headers['content-type'] = 'application/json';
+            if (options.idempotencyKey)
+                headers['idempotency-key'] = options.idempotencyKey;
+        }
+        const body = route.method === 'POST' ? JSON.stringify(values) : undefined;
+        for (let attempt = 0;; attempt++) {
+            const timeout = AbortSignal.timeout(this.options.timeoutMs);
+            const signal = options.signal ? AbortSignal.any([timeout, options.signal]) : timeout;
+            let response;
+            try {
+                response = await this.options.fetch(url, {
+                    method: route.method,
+                    headers,
+                    body,
+                    signal,
+                    redirect: 'error',
+                });
+            }
+            catch (error) {
+                if (options.signal?.aborted || attempt >= this.options.maxRetries)
+                    throw error;
+                // Every mutation above has the same idempotency identity on every attempt.
+                await sleep(Math.min(250 * 2 ** attempt, 2000), options.signal);
+                continue;
+            }
+            if ([429, 503].includes(response.status) && attempt < this.options.maxRetries) {
+                const retryHeader = response.headers.get('retry-after');
+                const seconds = retryHeader ? Number(retryHeader) : NaN;
+                const delay = Number.isFinite(seconds)
+                    ? seconds * 1000
+                    : retryHeader
+                        ? Date.parse(retryHeader) - Date.now()
+                        : 250 * 2 ** attempt;
+                await response.body?.cancel();
+                await sleep(Math.min(Math.max(Number.isFinite(delay) ? delay : 250, 0), 30000), options.signal);
+                continue;
+            }
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch {
+                // A gateway can deny access before the API emits a problem document. Preserve that
+                // status so a replica still hides revoked inventory instead of treating it as bad JSON.
+                if (!response.ok)
+                    throw new ApiError(response.status, 'INVALID_ERROR_RESPONSE', `API request failed (HTTP ${response.status}).`);
+                throw new ContractError(`Non-JSON response from ${operation} (HTTP ${response.status}).`, operation);
+            }
+            if (!response.ok) {
+                const problem = ProblemSchema.safeParse(value);
+                if (problem.success)
+                    throw new ApiError(response.status, problem.data.code, problem.data.detail, problem.data);
+                throw new ApiError(response.status, 'INVALID_ERROR_RESPONSE', `API request failed (HTTP ${response.status}).`);
+            }
+            const validated = operations[operation].output.safeParse(value);
+            if (!validated.success)
+                throw new ContractError(`Response from ${operation} does not match the public contract.`, operation);
+            return validated.data;
+        }
+    }
+    /** Product backends share one search contract and never handle Typesense keys. */
+    search = {
+        features: (options) => this.call('searchFeatures', {}, options),
+        listings: (input = {}, options) => this.call('searchListings', input, options),
+        facets: (input, options) => this.call('searchFacets', input, options),
+        map: (input, options) => this.call('searchMap', input, options),
+        suggest: (input, options) => this.call('searchSuggest', input, options),
+        interpret: (input, options) => this.call('searchInterpret', input, options),
+    };
+    listings = {
+        list: (input = {}, options) => this.call('listListings', input, options),
+        get: (id, options) => this.call('getListing', {
+            id,
+            ...(options?.profile ? { profile: options.profile } : {}),
+            ...(options?.dataset_id ? { dataset_id: options.dataset_id } : {}),
+        }, options),
+        map: (input, options) => this.call('listListingMap', input, options),
+        similar: (input, options) => this.call('listSimilarListings', input, options),
+        contacts: (id, options) => this.call('getListingContacts', { id, ...(options?.dataset_id ? { dataset_id: options.dataset_id } : {}) }, options),
+        resolveIdentity: (input, options) => this.call('resolveListingIdentity', input, options),
+    };
+    agents = {
+        resolveIdentity: (input, options) => this.call('resolveAgentIdentity', input, options),
+        get: (id, options) => this.call('getAgent', { id }, options),
+        listings: (id, input = {}, options) => this.call('listAgentListings', { ...input, id }, options),
+    };
+    publications = {
+        report: (input, options) => this.call('reportPublication', input, options),
+        destination: (input, options) => this.call('resolveDestination', input, options),
+    };
+    judgments = {
+        evaluate: (input, options) => this.call('evaluateJudgment', input, options),
+        get: (id, options) => this.call('getJudgment', { id }, options),
+        capabilities: (options) => this.call('intelligenceCapabilities', {}, options),
+    };
+    catalog = {
+        health: (datasetId, options) => this.call('getCatalogHealth', { dataset_id: datasetId }, options),
+        createSnapshot: (input, options) => this.call('createSnapshot', input, options),
+        snapshot: (id, options) => this.call('getSnapshot', { id }, options),
+        snapshotItems: (id, input = {}, options) => this.call('listSnapshotItems', { ...input, id }, options),
+        changes: (input = {}, options) => this.call('listCatalogChanges', input, options),
+        events: (input = {}, options) => this.call('listEvents', input, options),
+        opportunityObservations: async (input = {}, options) => {
+            const page = await this.call('listEvents', input, options);
+            try {
+                return {
+                    ...page,
+                    data: page.data
+                        .map(opportunityObservation)
+                        .filter((event) => event !== null),
+                };
+            }
+            catch {
+                throw new ContractError('Invalid opportunity observation evidence.', 'listEvents');
+            }
+        },
+    };
+    directory = {
+        canonicalIdentity: (input, options) => this.call('directoryGetCanonicalIdentity', input, options),
+        mergeIdentities: (input, options) => this.call('directoryMergeIdentities', input, options),
+        splitIdentity: (input, options) => this.call('directorySplitIdentity', input, options),
+        inventory: (input, options) => this.call('directoryListInventory', input, options),
+        salesCandidates: (input, options) => this.call('discoverDirectorySalesCandidates', input, options),
+        recordProfile: (input, options) => this.call('directoryRecordProfile', input, options),
+        recordRelationship: (input, options) => this.call('directoryRecordRelationship', input, options),
+        professionals: (input = {}, options) => this.call('directoryListProfessionals', input, options),
+        offices: (input = {}, options) => this.call('directoryListOffices', input, options),
+        organizations: (input = {}, options) => this.call('directoryListOrganizations', input, options),
+        teams: (input = {}, options) => this.call('directoryListTeams', input, options),
+        get: (input, options) => this.call('directoryGetEntity', input, options),
+        agent: (input, options) => this.call('directoryResolveAgent', input, options),
+        identity: (input, options) => this.call('directoryResolveIdentity', input, options),
+        relationships: (input, options) => this.call('directoryListRelationships', input, options),
+        contacts: (input, options) => this.call('directoryGetContacts', input, options),
+        metrics: (input, options) => this.call('directoryGetMetrics', input, options),
+        assess: (input, options) => this.call('requestDirectoryAssessment', input, options),
+        assessment: (id, options) => this.call('getDirectoryAssessment', { id }, options),
+        latestAssessment: (input, options) => this.call('latestDirectoryAssessment', input, options),
+        createSalesPlan: (input, options) => this.call('createDirectorySalesPlan', input, options),
+        salesPlan: (id, options) => this.call('getDirectorySalesPlan', { id }, options),
+        createSnapshot: (input, options) => this.call('createDirectorySnapshot', input, options),
+        snapshot: (id, options) => this.call('getDirectorySnapshot', { id }, options),
+        snapshotItems: (id, input = {}, options) => this.call('listDirectorySnapshotItems', { ...input, id }, options),
+        changes: (input, options) => this.call('listDirectoryChanges', input, options),
+    };
+    directoryActions = {
+        claim: (input, options) => this.call('claimDirectoryActions', input, options),
+        startAttempt: (input, options) => this.call('startDirectoryAttempt', input, options),
+        get: (id, options) => this.call('getDirectoryAction', { id }, options),
+        outcomes: (input, options) => this.call('recordDirectoryActionOutcomes', input, options),
+    };
+    opportunityPlans = {
+        create: (input, options) => this.call('createPlan', input, options),
+        get: (id, options) => this.call('getPlan', { id }, options),
+        items: (id, input = {}, options) => this.call('listPlanItems', { ...input, id }, options),
+        claimDispatchBatch: (input, options) => this.call('claimDispatchBatch', input, options),
+        waitUntilReady: async (id, options = {}) => {
+            const deadline = Date.now() + (options.maxWaitMs ?? 60000);
+            for (;;) {
+                const plan = await this.call('getPlan', { id }, options);
+                if (!['queued', 'building'].includes(plan.status))
+                    return plan;
+                if (Date.now() >= deadline)
+                    throw new ApiError(408, 'PLAN_WAIT_TIMEOUT', 'Plan is still building; its ID remains usable.');
+                await sleep(Math.min(1000, deadline - Date.now()), options.signal);
+            }
+        },
+    };
+    actions = {
+        startAttempt: (id, input, options) => this.call('startAttempt', { ...input, id }, options),
+        outcomes: (input, options) => this.call('recordActionOutcomes', input, options),
+    };
+    /** Live browsing only. Use catalog snapshots for a complete, consistent inventory replica. */
+    async *iterateListings(input = {}, options) {
+        let cursor = input.cursor;
+        const seen = new Set();
+        for (;;) {
+            const result = await this.call('listListings', { ...input, ...(cursor ? { cursor } : {}) }, options);
+            for (const listing of result.data)
+                yield listing;
+            if (!result.has_more)
+                return;
+            if (!result.next_cursor || seen.has(result.next_cursor))
+                throw new ContractError('Listing pagination did not advance.', 'listListings');
+            seen.add(result.next_cursor);
+            cursor = result.next_cursor;
+        }
+    }
+}
+// Both names refer to the same instance-based client; branding adds no global
+// configuration or second transport implementation for existing callers.
+export { ListingsClient as PropertySimple, ListingsClient as default };

package/client/src/managed-sync.d.ts

@@ -0,0 +1,129 @@
+import { CatalogSourceFreshnessSchema, type Listing } from '../../contracts/src/index.js';
+import { type ListingsClient } from './index.js';
+/** Structurally compatible with the platform Database and a consumer's transaction wrapper. */
+export interface TargetSql {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+        rowCount: number;
+    }>;
+}
+export interface TargetDatabase extends TargetSql {
+    transaction<T>(fn: (tx: TargetSql) => Promise<T>): Promise<T>;
+}
+export interface CatalogProjectionProfile {
+    /** Change this version whenever eligibility semantics change; an existing stream rejects drift. */
+    id: string;
+    eligible(listing: Listing): boolean;
+}
+export declare const portalActiveProfile: CatalogProjectionProfile;
+export declare const allVisibleProfile: CatalogProjectionProfile;
+export interface SyncConfiguration {
+    streamId: string;
+    datasetId: string;
+    /** Stable identity for the API environment + tenant/product/entitlement scope, never a secret. */
+    sourceNamespace: string;
+    profile: CatalogProjectionProfile;
+}
+interface Checkpoint {
+    phase: 'create' | 'waiting' | 'snapshot' | 'replay' | 'blocked';
+    generation: string;
+    snapshotId?: string;
+    snapshotCursor?: string;
+    replayCursor?: string;
+    lastSequence: string;
+    stagedCount: number;
+    expectedCount?: number;
+    sourceFreshness?: Array<ReturnType<typeof CatalogSourceFreshnessSchema.parse>>;
+}
+export interface ProjectionReadOptions {
+    /** Time since the consumer last drained its replay to the published boundary. */
+    maxStalenessMs: number;
+    /** Optional independent source-contact bound; missing coverage information fails closed. */
+    maxSourceStalenessMs?: number;
+    /** Full source enumeration is needed to discover records that disappeared. */
+    maxFullEnumerationStalenessMs?: number;
+}
+export interface SyncState {
+    version: string;
+    checkpoint: Checkpoint;
+    active_generation: string | null;
+    synchronized_at: string | null;
+}
+export interface CatalogProjection {
+    listing_id: string;
+    local_id: string;
+    listing: Listing;
+}
+export interface CatalogRecord {
+    listing_id: string;
+    local_id: string;
+    eligible: boolean;
+    listing: Listing | null;
+}
+export interface CatalogInvalidation {
+    id: string;
+    stream_id: string;
+    generation: string;
+    kind: 'reset' | 'upsert' | 'remove';
+    listing_id: string | null;
+    local_id: string | null;
+    lease_token: string;
+}
+export declare class ProjectionUnavailableError extends Error {
+    constructor(message?: string);
+}
+/**
+ * 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 declare class PostgresCatalogTarget {
+    private readonly db;
+    readonly configuration: SyncConfiguration;
+    constructor(db: TargetDatabase, configuration: SyncConfiguration);
+    /** Explicit schema installation. Run only against an approved consumer database. */
+    initialize(): Promise<void>;
+    state(): Promise<SyncState>;
+    /** Adopt an existing product UUID before importing it; never rewrite an established mapping. */
+    mapExistingIdentity(listingId: string, localId: string): Promise<void>;
+    /** Readers never see staging generations. A caller must choose an explicit freshness budget. */
+    list(options: ProjectionReadOptions & {
+        limit?: number;
+        after?: string;
+    }): Promise<CatalogProjection[]>;
+    /** Status consumers may inspect a noneligible upsert; a source tombstone has a null payload. */
+    get(listingId: string, options: ProjectionReadOptions): Promise<CatalogRecord | null>;
+    private assertReadable;
+    commit(expected: SyncState, next: Checkpoint, mutate: (tx: TargetSql) => Promise<void>, synchronized?: boolean): Promise<boolean>;
+    write(tx: TargetSql, generation: string, listing: Listing | null, listingId: string, invalidate: boolean, snapshot?: boolean): Promise<void>;
+    activate(tx: TargetSql, generation: string): Promise<void>;
+    private invalidate;
+    reset(expected: SyncState, blocked?: boolean): Promise<boolean>;
+    /** Explicit operator recovery after correcting denied credentials/scope. Does not change scope. */
+    resume(): Promise<void>;
+    claimInvalidations(limit?: number, leaseSeconds?: number): Promise<CatalogInvalidation[]>;
+    acknowledgeInvalidation(id: string, leaseToken: string): Promise<boolean>;
+    /** Bounded retention removes obsolete listing payloads, preserving identities and product data. */
+    pruneObsolete(limit?: number): Promise<number>;
+}
+type CatalogSource = Pick<ListingsClient, 'catalog'>;
+export type SyncStep = {
+    status: 'progress' | 'idle' | 'waiting' | 'conflict' | 'reset' | 'blocked';
+    phase: Checkpoint['phase'];
+    applied: number;
+};
+/** One step makes at most one network request and commits at most one bounded page. */
+export declare class CatalogSyncWorker {
+    private readonly source;
+    private readonly target;
+    private readonly pageSize;
+    constructor(source: CatalogSource, target: PostgresCatalogTarget, pageSize?: number);
+    step(options?: {
+        signal?: AbortSignal;
+    }): Promise<SyncStep>;
+    private validateChanges;
+    run(options: {
+        maxSteps: number;
+        signal?: AbortSignal;
+    }): Promise<SyncStep[]>;
+}
+export {};