@propertysimple/client 0.1.0

package/API.md

@@ -0,0 +1,79 @@
+# PropertySimple client API reference
+
+Generated from the shared route registry. Run `npm run sdk:docs` in the platform repository to update it.
+
+Every operation below is available through `ps.call(operation, input, options)`, with inferred input and response types. The [quickstart](README.md) documents convenient namespace helpers such as `ps.listings.get(id)` and `ps.search.listings(query)`. Request fields use the API's snake_case names. Supply `{ idempotencyKey: 'stable-request-id' }` in options for mutating POST requests; search POSTs are read-only.
+
+This reference describes the SDK contract, not a claim that every feature is enabled or accepted in production. Credential scopes, dataset grants, source freshness and index readiness still govern access. Legacy `/api/*`, admin pages, public health/OpenAPI routes and internal jobs are outside this versioned SDK registry. The package also includes `openapi.json` with full input/output schemas.
+
+| Operation for `ps.call`            | HTTP endpoint                                  | Required scope             | Purpose                                                                               |
+| ---------------------------------- | ---------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------- |
+| `searchFeatures`                   | `GET /v1/search/features`                      | `catalog:read`             | Read typed feature definitions and supported search operators.                        |
+| `searchListings`                   | `POST /v1/search/listings`                     | `catalog:read`             | Search current inventory with typed hard constraints and evidence.                    |
+| `searchFacets`                     | `POST /v1/search/facets`                       | `catalog:read`             | Read authorized refinement counts for the same normalized search.                     |
+| `searchMap`                        | `POST /v1/search/map`                          | `catalog:read`             | Read bounded map points and clusters with matching search semantics.                  |
+| `searchSuggest`                    | `GET /v1/search/suggest`                       | `catalog:read`             | Suggest registered features and permitted listing locations.                          |
+| `searchInterpret`                  | `POST /v1/search/interpret`                    | `catalog:read`             | Interpret a bounded search vocabulary into editable filters and unresolved text.      |
+| `directoryGetCanonicalIdentity`    | `GET /v1/directory/canonical-identities/{id}`  | `directory:read`           | Resolve reviewed identity links using only permitted source members.                  |
+| `directoryMergeIdentities`         | `POST /v1/directory/identity-merges`           | `directory:identity:write` | Record an audited identity merge with expected source bindings.                       |
+| `directorySplitIdentity`           | `POST /v1/directory/identity-splits`           | `directory:identity:write` | Split a reviewed identity without moving account or action history.                   |
+| `directoryListInventory`           | `GET /v1/directory/entities/{id}/inventory`    | `directory:read`           | Read represented or current-roster inventory with optional verified corporate rollup. |
+| `discoverDirectorySalesCandidates` | `GET /v1/directory/sales-candidates`           | `directory:sales`          | Discover a bounded authorized page of subjects for sales-plan evaluation.             |
+| `claimDirectoryActions`            | `POST /v1/directory/action-claims`             | `directory:execute`        | Reserve directory recommendations under a separately reviewed execution policy.       |
+| `startDirectoryAttempt`            | `POST /v1/directory/actions/{id}/attempts`     | `directory:execute`        | Recheck authority and start one attempt, or return reconciliation-only replay.        |
+| `getDirectoryAction`               | `GET /v1/directory/actions/{id}`               | `directory:execute`        | Read a product-scoped directory action and its execution state.                       |
+| `recordDirectoryActionOutcomes`    | `POST /v1/directory/action-outcomes`           | `directory:execute`        | Record authenticated provider receipts without retrying ambiguous effects.            |
+| `directoryRecordProfile`           | `POST /v1/directory/profile-observations`      | `directory:write`          | Record a trusted producer’s scoped profile evidence.                                  |
+| `directoryRecordRelationship`      | `POST /v1/directory/relationship-observations` | `directory:write`          | Record a trusted producer’s evidenced relationship.                                   |
+| `directoryListProfessionals`       | `GET /v1/directory/professionals`              | `directory:read`           | Read permitted source-backed professionals.                                           |
+| `directoryListOffices`             | `GET /v1/directory/offices`                    | `directory:read`           | Read permitted source offices.                                                        |
+| `directoryListOrganizations`       | `GET /v1/directory/organizations`              | `directory:read`           | Read evidenced business and brand observations.                                       |
+| `directoryListTeams`               | `GET /v1/directory/teams`                      | `directory:read`           | Read evidenced teams.                                                                 |
+| `directoryGetEntity`               | `GET /v1/directory/entities/{id}`              | `directory:read`           | Read a scoped professional, office, organization or team.                             |
+| `directoryResolveAgent`            | `GET /v1/directory/legacy-agents/{id}`         | `directory:read`           | Resolve a listing agent ID to its permitted public directory identity.                |
+| `directoryResolveIdentity`         | `GET /v1/directory/identities`                 | `directory:read`           | Resolve a typed directory source identity.                                            |
+| `directoryListRelationships`       | `GET /v1/directory/relationships`              | `directory:read`           | Read bounded evidenced relationships.                                                 |
+| `directoryGetContacts`             | `GET /v1/directory/entities/{id}/contacts`     | `directory:contacts`       | Read purpose-permitted directory contact endpoints.                                   |
+| `directoryGetMetrics`              | `GET /v1/directory/entities/{id}/metrics`      | `directory:read`           | Read authorized observed inventory metrics.                                           |
+| `createDirectorySnapshot`          | `POST /v1/directory/snapshots`                 | `directory:sync`           | Capture a directory or combined feed boundary.                                        |
+| `getDirectorySnapshot`             | `GET /v1/directory/snapshots/{id}`             | `directory:sync`           | Read snapshot scope, boundary and expiry.                                             |
+| `listDirectorySnapshotItems`       | `GET /v1/directory/snapshots/{id}/items`       | `directory:sync`           | Page immutable typed snapshot resources.                                              |
+| `listDirectoryChanges`             | `GET /v1/directory/changes`                    | `directory:sync`           | Replay typed changes with complete commit-group boundaries.                           |
+| `createDirectorySalesPlan`         | `POST /v1/directory/sales-plans`               | `directory:sales`          | Prepare bounded professional or organization sales recommendations.                   |
+| `getDirectorySalesPlan`            | `GET /v1/directory/sales-plans/{id}`           | `directory:sales`          | Read a scoped recommendation-only directory sales plan.                               |
+| `requestDirectoryAssessment`       | `POST /v1/directory/assessments`               | `intelligence:judge`       | Queue a canonical-evidence directory assessment.                                      |
+| `latestDirectoryAssessment`        | `GET /v1/directory/assessments/latest`         | `intelligence:read`        | Read prepared directory intelligence with current evidence checks.                    |
+| `getDirectoryAssessment`           | `GET /v1/directory/assessments/{id}`           | `intelligence:read`        | Read a purpose-scoped directory assessment.                                           |
+| `reportPublication`                | `POST /v1/publications`                        | `publications:write`       | Acknowledge this product’s current listing publication.                               |
+| `resolveDestination`               | `GET /v1/listings/{id}/destination`            | `catalog:read`             | Resolve a current product-reported destination.                                       |
+| `evaluateJudgment`                 | `POST /v1/judgments`                           | `intelligence:judge`       | Evaluate a bounded versioned task against caller-supplied evidence.                   |
+| `getJudgment`                      | `GET /v1/judgments/{id}`                       | `intelligence:read`        | Read this credential subject’s durable judgment audit.                                |
+| `intelligenceCapabilities`         | `GET /v1/intelligence-capabilities`            | `intelligence:read`        | Read implemented judgment tasks and explicit unsupported capabilities.                |
+| `capabilities`                     | `GET /v1/capabilities`                         | Authenticated caller       | Read this caller’s supported capabilities.                                            |
+| `getCatalogHealth`                 | `GET /v1/catalog-health`                       | `catalog:read`             | Read authorized source freshness independently of catalog changes.                    |
+| `listListings`                     | `GET /v1/listings`                             | `catalog:read`             | Search the current authorized catalog.                                                |
+| `listListingMap`                   | `GET /v1/listings/map`                         | `catalog:read`             | Read bounded map markers within a required geographic box.                            |
+| `listSimilarListings`              | `GET /v1/listings/{id}/similar`                | `catalog:read`             | Rank a bounded local shortlist using transparent fact similarity.                     |
+| `getListing`                       | `GET /v1/listings/{id}`                        | `catalog:read`             | Read a current listing.                                                               |
+| `getListingContacts`               | `GET /v1/listings/{id}/contacts`               | `contacts:read`            | Read protected source contact routing for a current active listing.                   |
+| `resolveListingIdentity`           | `GET /v1/listing-identities`                   | `catalog:read`             | Resolve a namespaced source alias.                                                    |
+| `resolveAgentIdentity`             | `GET /v1/agent-identities`                     | `agents:read`              | Resolve a namespaced agent source alias.                                              |
+| `getAgent`                         | `GET /v1/agents/{id}`                          | `agents:read`              | Read permitted agent attribution.                                                     |
+| `listAgentListings`                | `GET /v1/agents/{id}/listings`                 | `catalog:read`             | Read an agent’s authorized inventory.                                                 |
+| `classificationSchema`             | `GET /v1/classification-schema`                | `catalog:read`             | Read the current classification vocabulary.                                           |
+| `createSnapshot`                   | `POST /v1/catalog-snapshots`                   | `catalog:sync`             | Create a consistent snapshot with its replay cursor.                                  |
+| `getSnapshot`                      | `GET /v1/catalog-snapshots/{id}`               | `catalog:sync`             | Read snapshot readiness and expiry.                                                   |
+| `listSnapshotItems`                | `GET /v1/catalog-snapshots/{id}/items`         | `catalog:sync`             | Page an immutable snapshot.                                                           |
+| `listCatalogChanges`               | `GET /v1/catalog-changes`                      | `catalog:sync`             | Replay authorized projection changes and removals.                                    |
+| `listEvents`                       | `GET /v1/events`                               | `catalog:sync`             | Replay committed domain occurrences.                                                  |
+| `listActionProfiles`               | `GET /v1/action-profiles`                      | `opportunities:read`       | Read published action profiles.                                                       |
+| `listOpportunities`                | `GET /v1/opportunities`                        | `opportunities:read`       | Read current candidates without reserving actions.                                    |
+| `createPlan`                       | `POST /v1/opportunity-plans`                   | `plans:create`             | Create or reuse an actual persisted selection.                                        |
+| `getPlan`                          | `GET /v1/opportunity-plans/{id}`               | `opportunities:read`       | Read plan progress, coverage and execution counts.                                    |
+| `listPlanItems`                    | `GET /v1/opportunity-plans/{id}/items`         | `opportunities:read`       | Read stable selection pages.                                                          |
+| `claimDispatchBatch`               | `POST /v1/dispatch-batches`                    | `actions:dispatch`         | Reserve executable actions after critical revalidation.                               |
+| `startAttempt`                     | `POST /v1/actions/{id}/attempts`               | `actions:dispatch`         | Fence and record dispatch before an external effect.                                  |
+| `recordActionOutcomes`             | `POST /v1/action-outcomes`                     | `actions:dispatch`         | Record idempotent sender receipts with per-item results.                              |
+| `recordProductContextEvents`       | `POST /v1/product-context-events`              | `product-events:write`     | Ingest owned product context snapshots and deltas.                                    |
+| `createWebhookSubscription`        | `POST /v1/webhook-subscriptions`               | `webhooks:manage`          | Register a subscription only where delivery support is configured.                    |
+| `readiness`                        | `GET /v1/operations/readiness`                 | `operations:read`          | Inspect configured operational dependencies.                                          |

package/README.md

@@ -0,0 +1,348 @@
+# @propertysimple/client
+
+The typed **server-side PropertySimple SDK** for listing details, property search,
+agents, catalog synchronization, directory data and the platform's other public
+API operations. Configure one client in your backend, then use `ps.listings`,
+`ps.search`, `ps.agents` and `ps.catalog` throughout your application.
+
+This package is distributed publicly for **authenticated PropertySimple API
+integrations**. An API key is required to access data; no credentials or listing
+data are included in the package. The existing `@propertysimple/listings` package
+is separate and unchanged.
+
+**Service readiness:** SDK availability and API feature readiness are separate.
+Start direct catalog integrations with `ps.listings` and `ps.agents`. Managed
+search uses `ps.search` and requires a ready, authorized index on the API server.
+At the initial 0.1.0 release, full production search acceptance is still pending;
+do not treat this package release as approval to switch search traffic. Installing
+the SDK does not activate imports, indexing, synchronization schedules, Jev,
+geocoding or outbound actions.
+
+## Installation
+
+Requires **Node.js 24** and ESM (`"type": "module"` in your application's
+`package.json`). JavaScript and TypeScript are supported; declarations are
+included. TypeScript applications should use their normal `@types/node` setup.
+CommonJS and browser clients are not supported by this release.
+
+```sh
+npm install @propertysimple/client
+```
+
+The archive contains compiled JavaScript, TypeScript declarations, the shared
+contracts, this guide, [the complete operation reference](API.md) and
+`openapi.json`. Its only external runtime dependency is Zod. Consumers do not need
+`@ps/client`, `@ps/contracts`, the platform source tree or a TypeScript runtime loader.
+Commit your application's lockfile so deployments use the version you tested.
+
+## Configure once
+
+Create a backend-only module such as `src/lib/ps.ts`. The environment variable
+names below are application conventions; the SDK reads only the supplied options.
+Do not use browser-exposed environment variables for service credentials.
+
+<!-- sdk-example: ps.ts -->
+
+```ts
+import PropertySimple from '@propertysimple/client';
+
+const apiKey = process.env.PROPERTYSIMPLE_API_KEY;
+if (!apiKey) throw new Error('Set PROPERTYSIMPLE_API_KEY on the server.');
+
+const ps = new PropertySimple({
+  apiKey,
+});
+
+export default ps;
+```
+
+The default base URL is `https://api.propertysimple.ai`. Supply a scoped service
+key issued for your application; you do not need Typesense, ListHub or database
+credentials. For staging or local development, explicitly pass `baseUrl` when
+constructing the client, for example `baseUrl: 'http://127.0.0.1:3100'`. Each instance owns its credentials; multiple
+instances can coexist without changing another tenant's configuration.
+
+Request a service key and dataset ID from your PropertySimple platform
+administrator. Keys grant specific datasets and operations: catalog reads use
+`catalog:read`, agent profiles use `agents:read`, and protected contacts need their
+own scope. Choose the minimum permissions your integration needs. A dataset ID is
+an authorization boundary, not an MLS number or a value to guess.
+
+Keep the key in your backend's secret manager or an ignored local `.env` file.
+Never put it in a browser bundle, mobile app, public repository, URL, or a
+`NEXT_PUBLIC_`/`VITE_` environment variable. The SDK sends it as an HTTPS Bearer
+credential. Browser and mobile clients should call your own authenticated backend;
+that backend owns the `ps` instance and validates end-user access.
+
+In application code, import this configured instance. Adjust the relative path
+or use your application's `@/lib/ps` alias:
+
+<!-- sdk-example: listings.ts -->
+
+```ts
+import ps from './ps.js';
+
+const datasetId = 'your-authorized-dataset';
+
+const page = await ps.listings.list({
+  dataset_id: datasetId,
+  mls_number: 'EXAMPLE-123',
+  limit: 25,
+});
+
+const listing = await ps.listings.get('your-listing-id', {
+  dataset_id: datasetId,
+  profile: 'portal_active',
+});
+
+const identity = await ps.listings.resolveIdentity({
+  source: 'listhub',
+  key: 'your-source-listing-key',
+});
+
+const agent = await ps.agents.get('your-agent-id');
+```
+
+`listings.get` includes the full gallery. `profile: 'portal_active'` requires
+currently eligible active portal inventory; generic catalog reads can retain
+meaningful pending/sold status. A missing or removed listing is not evidence that
+it sold. A source key and a canonical listing ID are different identities: resolve
+existing source keys instead of treating addresses as unique IDs.
+
+For a first connectivity check, use `await ps.call('capabilities', {})`, then
+`await ps.catalog.health(datasetId)` and a small `ps.listings.list` request.
+Capabilities describe the caller's API support; health describes source freshness.
+Neither response establishes that a Typesense generation is ready.
+
+The examples use ESM imports. Run plain JavaScript in a `.mjs` file, or set
+`"type": "module"`; for local environment files Node 24 supports
+`node --env-file=.env your-script.mjs`. TypeScript examples should be compiled by
+your application's normal build. In a server-rendered framework, keep this module
+in server routes/services and use a Node.js runtime.
+
+## Search
+
+<!-- sdk-example: search.ts -->
+
+```ts
+import ps from './ps.js';
+
+const results = await ps.search.listings({
+  dataset_id: 'your-authorized-dataset',
+  q: '123 Main Street',
+  filters: {
+    transaction_type: 'for_sale',
+    currency: 'USD',
+    price: { max: '900000.00' },
+    bedrooms: { min: 3 },
+  },
+  sort: 'relevance',
+  limit: 24,
+});
+```
+
+Search responses include compact listing cards with a cover photo, `photo_count`,
+match reasons and index/freshness metadata. Use `ps.listings.get(id, options)` for
+complete details. The SDK calls the shared API; it never exposes Typesense keys.
+Source facts can be searched without Jev; interpreted features require their own
+current evidence. Missing evidence is not a negative match.
+
+The map helper takes `{ query, viewport, zoom, limit }`. Use the same applied
+query for listings, facets and maps, and honor generation/checkpoint, coverage,
+truncation and expiry metadata. Search readiness or stale-index errors must not
+silently become empty inventory or a broader query with filters removed.
+
+## Methods and complete API coverage
+
+| Namespace                            | Common methods                                                                                                          |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| `ps.listings`                        | `list`, `get`, `resolveIdentity`, `contacts`, `map`, `similar`                                                          |
+| `ps.search`                          | `listings`, `suggest`, `facets`, `map`, `features`, `interpret`                                                         |
+| `ps.agents`                          | `get`, `resolveIdentity`, `listings`                                                                                    |
+| `ps.catalog`                         | `health`, `createSnapshot`, `snapshot`, `snapshotItems`, `changes`, `events`, `opportunityObservations`                 |
+| `ps.directory`                       | `professionals`, `offices`, `organizations`, `teams`, `get`, `inventory`, identity, contact and synchronization helpers |
+| `ps.publications`                    | `report`, `destination`                                                                                                 |
+| `ps.judgments`                       | `capabilities`, `evaluate`, `get`                                                                                       |
+| `ps.opportunityPlans`                | `create`, `get`, `items`, `claimDispatchBatch`, `waitUntilReady`                                                        |
+| `ps.actions` / `ps.directoryActions` | Explicit action claims, attempts and outcomes                                                                           |
+
+All 69 registered versioned public operations are available through
+`ps.call(operation, input, options)`, including operations without a shortcut.
+Input and output types are inferred from the operation name. Input fields use the
+API's snake_case names; helpers use camelCase. For example:
+
+<!-- sdk-example: operations.ts -->
+
+```ts
+import ps from './ps.js';
+
+const capabilities = await ps.call('capabilities', {});
+const health = await ps.catalog.health('your-authorized-dataset');
+const listing = await ps.call('getListing', {
+  id: 'your-listing-id',
+  dataset_id: 'your-authorized-dataset',
+});
+```
+
+See [API.md](API.md) for every operation, HTTP route and required scope. Legacy
+`/api/*` adapters, admin pages, `/health/live`, `/openapi.json` and internal worker
+routes are not versioned SDK operations. Having a method does not grant its scope
+or enable an optional feature in production.
+The reference and OpenAPI document also ship at
+`node_modules/@propertysimple/client/API.md` and
+`node_modules/@propertysimple/client/openapi.json`, so integrations can inspect
+them without repository access. The repository guides linked below require
+access to the PropertySimple source repository.
+
+## Pagination and synchronization
+
+Continue a listing page with its `next_cursor` and the original query. Honor
+`has_more`, including when an authorized feed page is empty. Do not increase an
+offset to page a large dataset. `ps.iterateListings(query)` is convenient for live
+browsing, but concurrent updates can move records between pages.
+
+<!-- sdk-example: pagination.ts -->
+
+```ts
+import ps from './ps.js';
+
+const query = { dataset_id: 'your-authorized-dataset', limit: 25 };
+const firstPage = await ps.listings.list(query);
+
+if (firstPage.has_more && firstPage.next_cursor) {
+  const nextPage = await ps.listings.list({
+    ...query,
+    cursor: firstPage.next_cursor,
+  });
+  console.log(nextPage.data.map((listing) => listing.id));
+}
+```
+
+For a consistent replica, create a catalog snapshot, read its immutable pages,
+then replay `ps.catalog.changes` from the supplied cursor. Persist the checkpoint
+atomically with applied updates/removals. An expired cursor requires a new
+snapshot; resuming from an invented timestamp loses removals.
+
+The optional `@propertysimple/client/managed-sync` export supplies
+`CatalogSyncWorker` and `PostgresCatalogTarget`. The
+`@propertysimple/client/directory-sync` export supplies `DirectorySyncWorker`
+and `PostgresDirectoryTarget` for directory or combined feeds. They use an
+explicitly supplied database adapter and a separate consumer-owned schema;
+installation does not create tables, overwrite product data or install a schedule.
+Keep the database wrappers, checkpoints and cache invalidation handling required
+by the [managed synchronization guide](https://github.com/PropertySimple/ps-listings-platform/blob/main/docs/managed-sync.md).
+
+## Errors, requests and retries
+
+`ApiError` contains the HTTP `status`, stable `code` and validated `problem`
+(including the request ID when provided). `ContractError` means an input or a
+successful response failed the shared contract; never treat it as empty inventory.
+
+<!-- sdk-example: errors.ts -->
+
+```ts
+import { ApiError, ContractError } from '@propertysimple/client';
+import ps from './ps.js';
+
+try {
+  await ps.listings.get('your-listing-id');
+} catch (error) {
+  if (error instanceof ApiError) {
+    console.error(error.status, error.code, error.problem?.request_id);
+  } else if (error instanceof ContractError) {
+    console.error('API contract mismatch', error.operation);
+  }
+  throw error;
+}
+```
+
+Client options include the optional `baseUrl` override, `timeoutMs` (default 15,000 milliseconds per attempt),
+`maxRetries` (default two; allowed zero through five) and an optional `fetch`
+implementation. Requests accept an abort `signal`. Network failures and HTTP
+429/503 can retry within those limits; authorization errors do not retry.
+Use an abort signal for a total deadline across attempts. Redirects are rejected;
+HTTPS is required except for loopback development.
+
+For an integration timeout spanning retries, pass
+`{ signal: AbortSignal.timeout(30_000) }` as the request options. Log the operation,
+HTTP status, problem code and request ID; exclude API keys, contact details and
+complete response bodies from ordinary logs. In particular:
+
+| Result                                               | Integration behavior                                                                                                |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| HTTP 401/403                                         | Check the service key, dataset grant and operation scope; do not retry with broader credentials automatically.      |
+| HTTP 404                                             | Handle the unavailable resource explicitly; do not infer that a listing sold.                                       |
+| HTTP 429/503                                         | Honor the SDK's bounded retry behavior and surface persistent unavailability.                                       |
+| `SEARCH_INDEX_NOT_READY` / `SEARCH_SNAPSHOT_TOO_OLD` | Keep search unavailable until a valid generation is ready; do not show an empty inventory as a successful response. |
+| `ContractError`                                      | Check API/SDK compatibility and report the contract mismatch.                                                       |
+
+Mutating POST operations require a caller-supplied
+`{ idempotencyKey: 'stable-request-id' }` request option. Retries keep the same key
+and body. Search POSTs are read-only and need no key. An action attempt with
+`replayed: true` is an existing attempt to reconcile, not permission to send again.
+The SDK does not call email, advertising or payment providers. A plan does not
+constitute permission to contact someone or make a purchase.
+
+## Types, validation and compatibility
+
+The default export, named `PropertySimple` and named `ListingsClient` refer to the
+same class. Existing instance-based code can retain `ListingsClient`; there is no
+process-global `Listings.init()` configuration.
+
+The root exports the `DEFAULT_BASE_URL` constant and `Listing`, `InputRequest`, `Output`, `Operation`, `Principal`,
+`ClientOptions` and `RequestOptions` types. Full schemas and types are available
+from `@propertysimple/client/contracts`; location expiry/privacy projection helpers
+are available from `@propertysimple/client/location-serving`.
+
+Keep API and SDK contract versions compatible. Responses are validated strictly;
+coordinate additive schema changes before deployment when older consumers would
+reject new fields. Source freshness, dataset grants, contacts permissions and
+current address privacy still apply. Private-address listings can remain in
+nonspatial results, but their street/unit/subdivision and coordinates must be
+cleared from consumer copies and caches. Do not restore an old geocode or contact.
+
+## Migrating existing applications
+
+This package is separate from `@propertysimple/listings`, not a drop-in package
+rename. Start one configured `ps` instance, map legacy source IDs to canonical IDs,
+use cursors, and verify actual fields, status/privacy behavior and application
+relationships before switching traffic. Keep the old integration available during
+a reviewed migration. The server's authenticated `/api/*` compatibility adapters
+remain available for existing retrieval callers; new code should use `/v1` methods.
+Those adapters are not the public-portal serving contract.
+
+Read the [retrieval replacement guide](https://github.com/PropertySimple/ps-listings-platform/blob/main/docs/listings-api-replacement.md)
+and [product integration guide](https://github.com/PropertySimple/ps-listings-platform/blob/main/docs/product-integration.md)
+for the five existing retrieval mappings, source freshness and cutover checks.
+Installing this package does not modify or switch an existing consumer application.
+
+## Maintainer checks
+
+The source workspace retains the internal `@ps/client` name so existing platform
+imports continue working. `package.release.json` defines the distribution named
+`@propertysimple/client`; `sdk:build` compiles the SDK and its reachable shared
+contracts together, then replaces private workspace imports with local imports.
+The version comes from this workspace's `package.json`.
+
+```sh
+npm run sdk:docs -- --check
+npm run sdk:test
+npm run sdk:pack
+```
+
+For local integration testing, install the archive from
+`packages/client/dist/propertysimple-client-0.1.0.tgz` into a separate application.
+Publish the exact inspected archive to avoid including workspace configuration:
+
+```sh
+npm publish ./packages/client/dist/propertysimple-client-0.1.0.tgz --access public --registry https://registry.npmjs.org/ --ignore-scripts
+```
+
+`npm run sdk:test` builds and packs the release, installs it in a temporary project
+with local dependency archives and network access disabled for npm, checks every
+public export and the README examples' TypeScript types, and exercises synthetic
+requests. It performs no live API/provider work. Build output and archives stay
+ignored under `packages/client/dist`. Inspect the archive's file list and scan it
+for credentials before publication. Publishing requires npm organization access
+and any two-factor authentication required by that account. Registry versions are
+immutable; bump the client workspace version and rebuild for later releases.

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

@@ -0,0 +1,123 @@
+import { SmartFeedSelectorSchema, type SmartFeedResource, type Output } from '../../contracts/src/index.js';
+import { type ListingsClient } from './index.js';
+import { type TargetDatabase, type TargetSql, type ProjectionReadOptions } from './managed-sync.js';
+type ResourceType = SmartFeedResource['resource_type'];
+type Selector = ReturnType<typeof SmartFeedSelectorSchema.parse>;
+type Group = {
+    id: string;
+    end: string;
+    size: number;
+    next: number;
+    start: string;
+};
+interface Checkpoint {
+    phase: 'create' | 'snapshot' | 'replay' | 'blocked';
+    generation: string;
+    snapshotId?: string;
+    snapshotCursor?: string;
+    replayCursor?: string;
+    lastSequence: string;
+    visibleSequence: string;
+    snapshotSequence?: string;
+    group?: Group;
+    sourceFreshness?: Output<'listDirectoryChanges'>['meta']['source_freshness'];
+}
+export interface DirectorySyncState {
+    version: string;
+    checkpoint: Checkpoint;
+    active_generation: string | null;
+    visible_seq: string;
+    synchronized_at: string | null;
+}
+export interface DirectorySyncConfiguration {
+    streamId: string;
+    datasetId: string;
+    /** Nonsecret stable identity for environment + credential scope. Change streams on scope changes. */
+    sourceNamespace: string;
+    selector?: {
+        mode?: 'directory' | 'combined';
+        party_id?: string;
+        inventory_basis?: 'listing_representation';
+    };
+}
+export interface DirectoryInvalidation {
+    id: string;
+    kind: 'reset' | 'group';
+    generation: string;
+    from_sequence: string;
+    through_sequence: string;
+    lease_token: string;
+}
+/**
+ * A consumer-owned typed projection. Versions received for an incomplete group are durable but
+ * invisible. Completing a group changes one visibility pointer rather than applying an unbounded
+ * mutation transaction. Product-owned users, leads, slugs and billing never enter this schema.
+ */
+export declare class PostgresDirectoryTarget {
+    private readonly db;
+    readonly configuration: DirectorySyncConfiguration;
+    readonly selector: Selector;
+    private readonly fingerprint;
+    constructor(db: TargetDatabase, configuration: DirectorySyncConfiguration);
+    /**
+     * Explicit approved install/upgrade. v2 keeps resource_type as text, adds version metadata,
+     * and invalidates every v1 checkpoint so identity bindings enter through a complete snapshot.
+     * Stable local UUID mappings and old versions remain for product-owned recovery/pruning.
+     * Quiesce old SDK workers before invoking this; initialization is not a request-time action.
+     */
+    initialize(): Promise<void>;
+    state(): Promise<DirectorySyncState>;
+    commit(expected: DirectorySyncState, next: Checkpoint, write: (tx: TargetSql) => Promise<void>, options?: {
+        activate?: boolean;
+        synchronized?: boolean;
+    }): Promise<boolean>;
+    /** Two set-based writes per page, independent of page size. Checkpoint commits in the caller. */
+    writePage(tx: TargetSql, generation: string, items: Array<{
+        resource_type: ResourceType;
+        resource_id: string;
+        sequence: string;
+        resource: SmartFeedResource | null;
+    }>): Promise<void>;
+    invalidate(tx: TargetSql, generation: string, kind: 'reset' | 'group', from: string, through: string): Promise<void>;
+    reset(expected: DirectorySyncState, blocked?: boolean): Promise<boolean>;
+    resume(): Promise<void>;
+    mapExistingIdentity(resourceType: ResourceType, resourceId: string, localId: string): Promise<void>;
+    private readable;
+    list(options: ProjectionReadOptions & {
+        resourceType?: ResourceType;
+        after?: string;
+        limit?: number;
+    }): Promise<Array<{
+        resource: SmartFeedResource;
+        local_id: string;
+    }>>;
+    get(resourceType: ResourceType, resourceId: string, options: ProjectionReadOptions): Promise<SmartFeedResource | null>;
+    claimInvalidations(limit?: number, leaseSeconds?: number): Promise<DirectoryInvalidation[]>;
+    /** Page every affected key before acknowledging a group; resolve current state for cache effects. */
+    invalidationItems(event: DirectoryInvalidation, after?: string, limit?: number): Promise<Array<{
+        resource_type: ResourceType;
+        resource_id: string;
+    }>>;
+    acknowledgeInvalidation(event: Pick<DirectoryInvalidation, 'id' | 'lease_token'>): Promise<boolean>;
+    /** Preserve staged groups and unacknowledged invalidations while reclaiming bounded history. */
+    pruneObsolete(limit?: number): Promise<number>;
+}
+type FeedSource = Pick<ListingsClient, 'directory'>;
+export declare class DirectorySyncWorker {
+    private readonly source;
+    private readonly target;
+    private readonly pageSize;
+    constructor(source: FeedSource, target: PostgresDirectoryTarget, pageSize?: number);
+    step(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        status: 'progress' | 'idle' | 'conflict' | 'reset' | 'blocked';
+        applied: number;
+    }>;
+    private validateChange;
+    run(options: {
+        maxSteps: number;
+        signal?: AbortSignal;
+    }): Promise<Array<Awaited<ReturnType<DirectorySyncWorker['step']>>>>;
+}
+export {};