@propertysimple/client 0.1.0 → 0.2.0

package/contracts/src/schemas.js

@@ -4,7 +4,6 @@ import { LocationSchema } from './location.js';
 import { redactListingAddress } from './location-serving.js';
 import { SharedListingFields, SourceFieldsSchema, ProfessionalContactsSchema, } from './catalog-fields.js';
 export * from './catalog-fields.js';
-export * from './intelligence.js';
 /** Wire types are intentionally independent of database rows and provider payloads. */
 export const Id = z.string().min(1).max(256);
 export const Timestamp = z.iso.datetime({ offset: true });
@@ -313,8 +312,6 @@ const ListingQueryFields = DatasetPageQuery.extend({
     address_q: z.string().trim().min(2).max(500).optional(),
     market_status: MarketStatus.optional(),
     agent_id: Id.optional(),
-    party_id: Id.optional(),
-    inventory_basis: z.literal('listing_representation').optional(),
     mls_number: z.string().max(128).optional(),
     modified_since: Timestamp.optional(),
     source_modified_since: Timestamp.optional(),
@@ -327,7 +324,6 @@ const ListingQueryFields = DatasetPageQuery.extend({
         .regex(/^\d+(?:\.\d{1,2})?$/)
         .optional(),
     min_bedrooms: z.coerce.number().min(0).max(100).optional(),
-    features: z.array(z.string().min(1).max(80)).max(20).optional(),
     bbox: z
         .string()
         .max(128)
@@ -346,11 +342,7 @@ const ListingQueryFields = DatasetPageQuery.extend({
     }, 'Use west,south,east,north within geographic bounds, without crossing the antimeridian.')
         .optional(),
 });
-const explicitPartyInventory = (query) => Boolean(query.party_id) === Boolean(query.inventory_basis);
-const partyInventoryMessage = {
-    message: 'party_id and inventory_basis=listing_representation must be supplied together.',
-};
-export const ListingQuery = ListingQueryFields.refine(explicitPartyInventory, partyInventoryMessage);
+export const ListingQuery = ListingQueryFields;
 export const IdentityQuery = z.strictObject({ source: Id, key: Id });
 export const IdentitySchema = z.strictObject({
     source: Id,
@@ -358,7 +350,40 @@ export const IdentitySchema = z.strictObject({
     listing_id: Id,
     episode_id: Id,
 });
+/** /v1/listing-changes. Without a cursor, `start` picks where the stream begins:
+ * `now` (from this moment) or `all` (every listing first, then changes). */
+export const ListingChangeQuery = DatasetPageQuery.extend({
+    start: z.enum(['now', 'all']).default('now'),
+    include_contacts: z.union([z.boolean(), z.enum(['true', 'false'])]).optional(),
+});
+/** One listing's current state. `visible` carries the listing as /v1/listings
+ * renders it; `hidden` (present but not displayable) and `removed` (absent from a
+ * complete enumeration) carry only the identity. Contacts follow the
+ * /contacts rule and appear only when requested with contacts:read. */
+export const ListingChangeSchema = z.strictObject({
+    listing_id: Id,
+    episode_id: Id,
+    revision: z.string(),
+    source_identities: z.array(z.strictObject({ source: Id, key: Id })),
+    status: z.enum(['visible', 'hidden', 'removed']),
+    listing: ListingSchema.nullable(),
+    contacts: ListingContactsSchema.nullable().optional(),
+});
 export const AgentIdentitySchema = z.strictObject({ source: Id, key: Id, agent_id: Id });
+/** Suppression evidence only; never consent, identity matching or contact freshness. */
+export const AgentEmailSharingSchema = z
+    .strictObject({
+    source: Id,
+    key: Id,
+    agent_id: Id,
+    email: z.email().max(320).nullable(),
+    sharing_count: z.number().int().min(1).max(10_000_000).nullable(),
+    observed_at: Timestamp,
+    basis: z.literal('stored_source_agent_email'),
+    coverage: z.literal('known_source_agents'),
+    matching: z.literal('exact_stored_email'),
+})
+    .refine((value) => (value.email === null) === (value.sharing_count === null));
 export function page(item) {
     return z.strictObject({
         data: z.array(item),
@@ -367,11 +392,19 @@ export function page(item) {
         meta: z.record(z.string(), Json),
     });
 }
-/** Operational source health is live metadata; immutable listing snapshots keep their original observation times. */
+/** Operational source health is live metadata; immutable listing snapshots keep their original observation times.
+ * Each time is the capture start of a completed, non-dry import run. */
 export const CatalogSourceFreshnessSchema = z.strictObject({
     source: Id,
+    /** The newest completed run of any kind: change-scan freshness. */
     last_completed_enumeration_at: Timestamp.nullable(),
+    /** Withdrawal coverage: the newest completed nightly full or removal sweep. Both are
+     * complete key enumerations that resolve absence, so a listing present now was in
+     * that key list or was seen after it. */
     last_full_enumeration_at: Timestamp.nullable(),
+    /** The newest completed nightly full, which also re-fetches every listing. Sweeps do
+     * not move it, so a failed full stays visible here while sweeps keep coverage. */
+    last_full_refresh_at: Timestamp.nullable().optional(),
     state: z.enum(['fresh', 'stale', 'never_completed']),
     freshness_window_seconds: z.number().int().positive(),
     /** Continuous sources separate change-scan freshness from withdrawal coverage. */
@@ -406,12 +439,10 @@ export const ListingMapQuery = ListingQueryFields.omit({
     limit: true,
     sort: true,
     include_total: true,
-})
-    .extend({
+}).extend({
     bbox: ListingQueryFields.shape.bbox.unwrap(),
     limit: z.coerce.number().int().min(1).max(1000).default(500),
-})
-    .refine(explicitPartyInventory, partyInventoryMessage);
+});
 export const ListingMapSchema = z.strictObject({
     data: z.array(z.strictObject({
         id: Id,
@@ -441,27 +472,6 @@ export const SimilarListingsSchema = z.strictObject({
     candidate_count: z.number().int().nonnegative(),
     candidates_truncated: z.boolean(),
 });
-export const SnapshotRequest = z.strictObject({ dataset_id: Id });
-export const SnapshotSchema = z.strictObject({
-    id: Id,
-    dataset_id: Id,
-    status: z.enum(['building', 'ready', 'failed', 'expired']),
-    schema_version: z.string(),
-    snapshot_sequence: z.string(),
-    replay_cursor: z.string(),
-    created_at: Timestamp,
-    expires_at: Timestamp,
-    count: z.number().int().nonnegative().optional(),
-});
-export const CatalogChangeSchema = z.strictObject({
-    id: Id,
-    sequence: z.string(),
-    listing_id: Id,
-    revision: z.string(),
-    operation: z.enum(['upsert', 'remove']),
-    listing: ListingSchema.nullable(),
-    published_at: Timestamp,
-});
 export const DomainEventSchema = z.strictObject({
     id: Id,
     sequence: z.string(),
@@ -472,194 +482,6 @@ export const DomainEventSchema = z.strictObject({
     observed_at: Timestamp,
     evidence: z.record(z.string(), Json),
 });
-export const ClassificationDefinitionSchema = z.strictObject({
-    taxonomy_version: z.string(),
-    attributes: z.array(z.strictObject({
-        id: Id,
-        description: z.string(),
-        type: z.enum(['boolean', 'string', 'number']),
-        values: z.array(z.string()).optional(),
-    })),
-});
-export const ActionProfileSchema = z.strictObject({
-    id: Id,
-    family: Id,
-    purpose: z.string(),
-    owner_product: Id,
-    channel: z.enum(['email', 'social', 'ads']),
-    target_unit: z.enum(['contact_actions', 'content_actions', 'ad_candidates']),
-    timezone: z.string(),
-    policy_revision: z.string(),
-    required_context: z.array(z.string()),
-    enabled: z.boolean(),
-});
-export const OpportunityQuery = PageQuery.extend({
-    profile_id: Id,
-    account_id: Id.optional(),
-    agent_id: Id.optional(),
-});
-export const OpportunitySchema = z.strictObject({
-    id: Id,
-    profile_id: Id,
-    listing_id: Id,
-    episode_id: Id,
-    recipient_id: Id,
-    intent_id: Id,
-    primary_angle: z.string(),
-    trigger_event_ids: z.array(Id),
-    supporting_evidence_refs: z.array(z.string()),
-    reason_codes: z.array(z.string()),
-    priority_index: z.number(),
-    valid_until: Timestamp,
-    decision_revision: z.string(),
-});
-export const PlanRequest = z.strictObject({
-    profile_id: Id,
-    business_date: DateOnly,
-    audience_id: Id,
-    target: z.strictObject({
-        count: z.number().int().min(1).max(100000),
-        unit: z.enum(['contact_actions', 'content_actions', 'ad_candidates']),
-    }),
-    run_slot: z
-        .string()
-        .min(1)
-        .max(64)
-        .regex(/^[a-z0-9_-]+$/),
-});
-export const PlanSchema = z.strictObject({
-    id: Id,
-    profile_id: Id,
-    business_date: DateOnly,
-    timezone: z.string(),
-    status: z.enum(['queued', 'building', 'ready', 'failed', 'cancelled', 'expired']),
-    requested_count: z.number().int().nonnegative(),
-    selected_count: z.number().int().nonnegative(),
-    unique_recipients: z.number().int().nonnegative(),
-    reserve_count: z.number().int().nonnegative(),
-    shortfall: z.number().int().nonnegative(),
-    completeness: z.enum(['pending', 'complete', 'partial']),
-    decision_mode: z.enum(['jev', 'cached_jev', 'fixture']),
-    created_at: Timestamp,
-    expires_at: Timestamp,
-    policy_revision: z.string(),
-    exclusions: z.record(z.string(), z.number().int().nonnegative()),
-    cutoffs: z.record(z.string(), z.string()),
-    execution_counts: z.record(z.string(), z.number().int().nonnegative()).optional(),
-});
-export const ActionState = z.enum([
-    'unclaimed',
-    'reserved',
-    'dispatching',
-    'accepted',
-    'delivered',
-    'rejected',
-    'invalidated',
-    'unknown',
-]);
-export const PlanItemReplacementSchema = z.strictObject({
-    item_id: Id,
-    opportunity_id: Id,
-    listing_id: Id,
-    recipient_id: Id,
-    reason: z.string(),
-    replaced_at: Timestamp,
-});
-export const PlanItemSchema = z.strictObject({
-    id: Id,
-    slot: z.number().int(),
-    rank: z.number().int(),
-    opportunity_id: Id,
-    listing_id: Id,
-    episode_id: Id,
-    recipient_id: Id,
-    primary_angle: z.string(),
-    trigger_event_ids: z.array(Id),
-    supporting_evidence_refs: z.array(z.string()),
-    reason_codes: z.array(z.string()),
-    valid_until: Timestamp,
-    execution_state: ActionState,
-    action_id: Id.nullable(),
-    // Selection facts remain the original snapshot; this names the reserve executing its logical slot.
-    replacement: PlanItemReplacementSchema.optional(),
-});
-export const DispatchRequest = z.strictObject({
-    plan_id: Id,
-    limit: z.number().int().min(1).max(100),
-    worker_id: Id,
-});
-export const DispatchActionSchema = z.strictObject({
-    id: Id,
-    plan_item_id: Id,
-    listing_id: Id,
-    recipient_id: Id,
-    action_kind: z.string(),
-    lease_token: z.string(),
-    lease_expires_at: Timestamp,
-    endpoint: z.string(),
-    payload: z.record(z.string(), Json),
-});
-export const DispatchBatchSchema = z.strictObject({
-    id: Id,
-    plan_id: Id,
-    actions: z.array(DispatchActionSchema),
-    exhausted: z.boolean(),
-});
-export const AttemptRequest = z.strictObject({ id: Id, lease_token: z.string().min(1).max(1024) });
-export const AttemptSchema = z.strictObject({
-    id: Id,
-    action_id: Id,
-    provider_idempotency_key: z.string(),
-    state: z.literal('dispatching'),
-    started_at: Timestamp,
-    replayed: z.boolean(),
-});
-export const ActionOutcomeSchema = z.strictObject({
-    event_id: Id,
-    action_id: Id,
-    attempt_id: Id,
-    provider: Id,
-    provider_event_id: Id,
-    outcome: z.enum(['accepted', 'delivered', 'rejected', 'unknown', 'bounced', 'complained']),
-    occurred_at: Timestamp,
-    details: z.record(z.string(), Json).optional(),
-});
-export const OutcomesRequest = z.strictObject({
-    outcomes: z.array(ActionOutcomeSchema).min(1).max(100),
-});
-export const ProductContextEventSchema = z.strictObject({
-    event_id: Id,
-    producer_id: Id,
-    stream_epoch: Id,
-    coverage_id: Id,
-    subject_id: Id,
-    subject_type: Id,
-    subject_version: z.number().int().nonnegative(),
-    stream_sequence: z.number().int().nonnegative(),
-    type: z.string().min(1).max(128),
-    occurred_at: Timestamp,
-    payload: z.record(z.string(), Json),
-});
-export const ContextEventsRequest = z.strictObject({
-    events: z.array(ProductContextEventSchema).min(1).max(100),
-});
-export const BatchResultSchema = z.strictObject({
-    results: z.array(z.strictObject({
-        event_id: Id,
-        status: z.enum(['accepted', 'duplicate', 'rejected']),
-        code: z.string().nullable(),
-    })),
-});
-export const WebhookRequest = z.strictObject({
-    url: z.url(),
-    dataset_id: Id,
-    event_types: z.array(z.string()).min(1).max(20),
-});
-export const WebhookSchema = z.strictObject({
-    id: Id,
-    url: z.string(),
-    status: z.enum(['pending_verification', 'active', 'disabled']),
-});
 export const CapabilitiesSchema = z.strictObject({
     api_version: z.literal('v1'),
     dataset_ids: z.array(Id),