@propertysimple/client 0.1.0

package/contracts/src/directory-identity.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { DirectoryKind } from './directory.js';
+import { ListingSchema, MarketStatus, CatalogSourceFreshnessSchema } from './schemas.js';
+const Id = z.string().min(1).max(256);
+const Revision = z.string().regex(/^\d+$/);
+export const DirectoryIdentityMemberSchema = z.strictObject({
+    entity_id: Id,
+    source_namespace: Id,
+});
+/** A feed resource is anchored to an immutable source ID; hidden source members are omitted. */
+export const DirectoryIdentityResolutionSchema = z
+    .strictObject({
+    id: Id,
+    source_namespace: Id,
+    kind: DirectoryKind,
+    revision: Revision,
+    canonical_id: Id.nullable(),
+    state: z.enum(['source_identity', 'canonical']),
+    members: z.array(DirectoryIdentityMemberSchema).min(1).max(200),
+})
+    .superRefine((value, context) => {
+    const anchor = value.members.find((member) => member.entity_id === value.id);
+    if (!anchor ||
+        anchor.source_namespace !== value.source_namespace ||
+        new Set(value.members.map((member) => member.entity_id)).size !== value.members.length)
+        context.addIssue({
+            code: 'custom',
+            message: 'Identity members must be unique and include the source anchor.',
+            path: ['members'],
+        });
+    if (value.state === 'source_identity'
+        ? value.canonical_id !== null || value.members.length !== 1
+        : value.canonical_id === null)
+        context.addIssue({
+            code: 'custom',
+            message: 'Canonical state and membership must agree.',
+            path: ['canonical_id'],
+        });
+});
+export const DirectoryCanonicalIdentitySchema = z.strictObject({
+    requested_id: Id,
+    state: z.enum(['source_identity', 'canonical', 'redirected', 'split']),
+    canonical_id: Id.nullable(),
+    kind: DirectoryKind,
+    // Scope-dependent content hash, never the count/revision of hidden evidence.
+    revision: z.string(),
+    members: z.array(DirectoryIdentityMemberSchema).max(200),
+    alternatives: z
+        .array(z.strictObject({
+        canonical_id: Id,
+        members: z.array(DirectoryIdentityMemberSchema).min(1).max(200),
+    }))
+        .max(200),
+    bindings: z
+        .array(z.strictObject({
+        entity_id: Id,
+        canonical_id: Id.nullable(),
+        revision: Revision,
+    }))
+        .max(200),
+});
+export const DirectoryCanonicalQuery = z.strictObject({ id: Id, dataset_id: Id.optional() });
+const ExpectedBinding = z.strictObject({
+    entity_id: Id,
+    canonical_id: Id.nullable(),
+    revision: Revision,
+});
+const Mutation = z.strictObject({
+    dataset_id: Id.optional(),
+    producer_id: Id,
+    request_id: Id,
+    reason: z.string().min(10).max(2000),
+    evidence_ref: Id,
+    expected_bindings: z.array(ExpectedBinding).min(2).max(200),
+});
+export const DirectoryMergeIdentities = Mutation;
+export const DirectorySplitIdentity = Mutation.extend({
+    canonical_id: Id,
+    partitions: z.array(z.array(Id).min(1).max(199)).min(2).max(200),
+});
+export const DirectoryIdentityMutationResult = z.strictObject({
+    operation_id: Id,
+    identity_ids: z.array(Id).min(1).max(200),
+});
+export const DirectoryInventoryQuery = z.strictObject({
+    id: Id,
+    dataset_id: Id.optional(),
+    inventory_basis: z.enum(['listing_representation', 'current_roster']),
+    rollup: z.enum(['none', 'verified_corporate']).default('none'),
+    cursor: z.string().max(4096).optional(),
+    limit: z.coerce.number().int().min(1).max(200).default(100),
+    market_status: z.lazy(() => MarketStatus).optional(),
+    transaction_type: z.enum(['for_sale', 'for_rent']).optional(),
+    include_counts: z.enum(['true', 'false']).default('false'),
+});
+export const DirectoryInventoryPage = z.strictObject({
+    data: z.array(z.lazy(() => ListingSchema)),
+    next_cursor: z.string().nullable(),
+    has_more: z.boolean(),
+    meta: z.strictObject({
+        dataset_id: Id,
+        inventory_basis: z.enum(['listing_representation', 'current_roster']),
+        rollup: z.enum(['none', 'verified_corporate']),
+        source_namespaces: z.array(Id),
+        coverage: z.literal('authorized_published_listings'),
+        calculated_at: z.iso.datetime({ offset: true }),
+        source_freshness: z.array(z.lazy(() => CatalogSourceFreshnessSchema)),
+        definition_version: z.literal('verified-inventory-v1'),
+        rollup_policy: z.literal('verified-current-effective-operates-v1'),
+        listing_count: z.number().int().nonnegative().optional(),
+        active_listing_count: z.number().int().nonnegative().optional(),
+        relationship_fingerprint: z.string(),
+    }),
+});
+export const directoryIdentityOperations = {
+    directoryGetCanonicalIdentity: {
+        input: DirectoryCanonicalQuery,
+        output: DirectoryCanonicalIdentitySchema,
+    },
+    directoryMergeIdentities: {
+        input: DirectoryMergeIdentities,
+        output: DirectoryIdentityMutationResult,
+    },
+    directorySplitIdentity: {
+        input: DirectorySplitIdentity,
+        output: DirectoryIdentityMutationResult,
+    },
+    directoryListInventory: { input: DirectoryInventoryQuery, output: DirectoryInventoryPage },
+};

package/contracts/src/directory-sales.d.ts

@@ -0,0 +1,333 @@
+import { z } from 'zod';
+export declare const DirectorySalesContextSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<"directory-sales-v1">;
+    product_id: z.ZodString;
+    adoption_status: z.ZodEnum<{
+        unknown: "unknown";
+        active: "active";
+        prospect: "prospect";
+        trial: "trial";
+        paused: "paused";
+        churned: "churned";
+    }>;
+    account_id: z.ZodNullable<z.ZodString>;
+    verified_account_binding_id: z.ZodNullable<z.ZodString>;
+    last_activity_at: z.ZodNullable<z.ZodISODateTime>;
+    last_contacted_at: z.ZodNullable<z.ZodISODateTime>;
+    suppressed: z.ZodBoolean;
+    unsubscribed: z.ZodBoolean;
+    snoozed_until: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type DirectorySalesContext = z.infer<typeof DirectorySalesContextSchema>;
+export declare const DirectorySalesProfilePolicySchema: z.ZodObject<{
+    reviewed: z.ZodBoolean;
+    required_context: z.ZodArray<z.ZodString>;
+    max_context_age_minutes: z.ZodNumber;
+    max_source_age_minutes: z.ZodNumber;
+    allowed_audience_ids: z.ZodArray<z.ZodString>;
+    allowed_subject_kinds: z.ZodArray<z.ZodEnum<{
+        office: "office";
+        professional: "professional";
+        organization: "organization";
+    }>>;
+    eligible_adoption_states: z.ZodArray<z.ZodEnum<{
+        active: "active";
+        prospect: "prospect";
+        trial: "trial";
+        paused: "paused";
+        churned: "churned";
+    }>>;
+    minimum_active_listings: z.ZodNumber;
+    contact_cooldown_hours: z.ZodNumber;
+    validity_minutes: z.ZodNumber;
+    purpose_family: z.ZodString;
+    intent: z.ZodEnum<{
+        adoption_outreach: "adoption_outreach";
+        expansion_review: "expansion_review";
+        reactivation_review: "reactivation_review";
+    }>;
+}, z.core.$strict>;
+export declare const DirectorySalesPlanRequest: z.ZodObject<{
+    dataset_id: z.ZodString;
+    profile_id: z.ZodString;
+    audience_id: z.ZodString;
+    subject_ids: z.ZodArray<z.ZodString>;
+    target_count: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const DirectorySalesRecommendationSchema: z.ZodObject<{
+    intent_id: z.ZodString;
+    subject: z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            office: "office";
+            professional: "professional";
+            organization: "organization";
+        }>;
+        revision: z.ZodString;
+    }, z.core.$strict>;
+    target_product_id: z.ZodString;
+    intent: z.ZodEnum<{
+        adoption_outreach: "adoption_outreach";
+        expansion_review: "expansion_review";
+        reactivation_review: "reactivation_review";
+    }>;
+    authority: z.ZodLiteral<"recommendation_only">;
+    reasons: z.ZodArray<z.ZodString>;
+    metrics: z.ZodObject<{
+        active_listing_count: z.ZodNumber;
+        represented_listing_count: z.ZodNumber;
+        definition_version: z.ZodLiteral<"directory-sales-inventory-v1">;
+        coverage: z.ZodLiteral<"authorized_observed_listings">;
+    }, z.core.$strict>;
+    context_fingerprint: z.ZodString;
+    adoption_status: z.ZodEnum<{
+        unknown: "unknown";
+        active: "active";
+        prospect: "prospect";
+        trial: "trial";
+        paused: "paused";
+        churned: "churned";
+    }>;
+    account_id: z.ZodNullable<z.ZodString>;
+    verified_account_binding_id: z.ZodNullable<z.ZodString>;
+    contact_resolution: z.ZodObject<{
+        entity_id: z.ZodString;
+        operation: z.ZodLiteral<"directoryGetContacts">;
+        purpose: z.ZodEnum<{
+            office: "office";
+            professional: "professional";
+            organization: "organization";
+        }>;
+        requires_current_authorization: z.ZodLiteral<true>;
+    }, z.core.$strict>;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const DirectorySalesPlanSchema: z.ZodObject<{
+    id: z.ZodString;
+    profile_id: z.ZodString;
+    policy_revision: z.ZodString;
+    dataset_id: z.ZodString;
+    audience_id: z.ZodString;
+    status: z.ZodEnum<{
+        stale: "stale";
+        expired: "expired";
+        blocked: "blocked";
+        ready: "ready";
+    }>;
+    authority: z.ZodLiteral<"recommendation_only">;
+    requested_count: z.ZodNumber;
+    examined_count: z.ZodNumber;
+    selected_count: z.ZodNumber;
+    shortfall: z.ZodNumber;
+    selection_scope: z.ZodLiteral<"explicit_bounded_subject_set">;
+    data: z.ZodArray<z.ZodObject<{
+        intent_id: z.ZodString;
+        subject: z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<{
+                office: "office";
+                professional: "professional";
+                organization: "organization";
+            }>;
+            revision: z.ZodString;
+        }, z.core.$strict>;
+        target_product_id: z.ZodString;
+        intent: z.ZodEnum<{
+            adoption_outreach: "adoption_outreach";
+            expansion_review: "expansion_review";
+            reactivation_review: "reactivation_review";
+        }>;
+        authority: z.ZodLiteral<"recommendation_only">;
+        reasons: z.ZodArray<z.ZodString>;
+        metrics: z.ZodObject<{
+            active_listing_count: z.ZodNumber;
+            represented_listing_count: z.ZodNumber;
+            definition_version: z.ZodLiteral<"directory-sales-inventory-v1">;
+            coverage: z.ZodLiteral<"authorized_observed_listings">;
+        }, z.core.$strict>;
+        context_fingerprint: z.ZodString;
+        adoption_status: z.ZodEnum<{
+            unknown: "unknown";
+            active: "active";
+            prospect: "prospect";
+            trial: "trial";
+            paused: "paused";
+            churned: "churned";
+        }>;
+        account_id: z.ZodNullable<z.ZodString>;
+        verified_account_binding_id: z.ZodNullable<z.ZodString>;
+        contact_resolution: z.ZodObject<{
+            entity_id: z.ZodString;
+            operation: z.ZodLiteral<"directoryGetContacts">;
+            purpose: z.ZodEnum<{
+                office: "office";
+                professional: "professional";
+                organization: "organization";
+            }>;
+            requires_current_authorization: z.ZodLiteral<true>;
+        }, z.core.$strict>;
+        expires_at: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    exclusions: z.ZodRecord<z.ZodString, z.ZodNumber>;
+    created_at: z.ZodISODateTime;
+    expires_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export declare const directorySalesOperations: {
+    readonly createDirectorySalesPlan: {
+        readonly input: z.ZodObject<{
+            dataset_id: z.ZodString;
+            profile_id: z.ZodString;
+            audience_id: z.ZodString;
+            subject_ids: z.ZodArray<z.ZodString>;
+            target_count: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly output: z.ZodObject<{
+            id: z.ZodString;
+            profile_id: z.ZodString;
+            policy_revision: z.ZodString;
+            dataset_id: z.ZodString;
+            audience_id: z.ZodString;
+            status: z.ZodEnum<{
+                stale: "stale";
+                expired: "expired";
+                blocked: "blocked";
+                ready: "ready";
+            }>;
+            authority: z.ZodLiteral<"recommendation_only">;
+            requested_count: z.ZodNumber;
+            examined_count: z.ZodNumber;
+            selected_count: z.ZodNumber;
+            shortfall: z.ZodNumber;
+            selection_scope: z.ZodLiteral<"explicit_bounded_subject_set">;
+            data: z.ZodArray<z.ZodObject<{
+                intent_id: z.ZodString;
+                subject: z.ZodObject<{
+                    id: z.ZodString;
+                    kind: z.ZodEnum<{
+                        office: "office";
+                        professional: "professional";
+                        organization: "organization";
+                    }>;
+                    revision: z.ZodString;
+                }, z.core.$strict>;
+                target_product_id: z.ZodString;
+                intent: z.ZodEnum<{
+                    adoption_outreach: "adoption_outreach";
+                    expansion_review: "expansion_review";
+                    reactivation_review: "reactivation_review";
+                }>;
+                authority: z.ZodLiteral<"recommendation_only">;
+                reasons: z.ZodArray<z.ZodString>;
+                metrics: z.ZodObject<{
+                    active_listing_count: z.ZodNumber;
+                    represented_listing_count: z.ZodNumber;
+                    definition_version: z.ZodLiteral<"directory-sales-inventory-v1">;
+                    coverage: z.ZodLiteral<"authorized_observed_listings">;
+                }, z.core.$strict>;
+                context_fingerprint: z.ZodString;
+                adoption_status: z.ZodEnum<{
+                    unknown: "unknown";
+                    active: "active";
+                    prospect: "prospect";
+                    trial: "trial";
+                    paused: "paused";
+                    churned: "churned";
+                }>;
+                account_id: z.ZodNullable<z.ZodString>;
+                verified_account_binding_id: z.ZodNullable<z.ZodString>;
+                contact_resolution: z.ZodObject<{
+                    entity_id: z.ZodString;
+                    operation: z.ZodLiteral<"directoryGetContacts">;
+                    purpose: z.ZodEnum<{
+                        office: "office";
+                        professional: "professional";
+                        organization: "organization";
+                    }>;
+                    requires_current_authorization: z.ZodLiteral<true>;
+                }, z.core.$strict>;
+                expires_at: z.ZodISODateTime;
+            }, z.core.$strict>>;
+            exclusions: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            created_at: z.ZodISODateTime;
+            expires_at: z.ZodISODateTime;
+        }, z.core.$strict>;
+    };
+    readonly getDirectorySalesPlan: {
+        readonly input: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strict>;
+        readonly output: z.ZodObject<{
+            id: z.ZodString;
+            profile_id: z.ZodString;
+            policy_revision: z.ZodString;
+            dataset_id: z.ZodString;
+            audience_id: z.ZodString;
+            status: z.ZodEnum<{
+                stale: "stale";
+                expired: "expired";
+                blocked: "blocked";
+                ready: "ready";
+            }>;
+            authority: z.ZodLiteral<"recommendation_only">;
+            requested_count: z.ZodNumber;
+            examined_count: z.ZodNumber;
+            selected_count: z.ZodNumber;
+            shortfall: z.ZodNumber;
+            selection_scope: z.ZodLiteral<"explicit_bounded_subject_set">;
+            data: z.ZodArray<z.ZodObject<{
+                intent_id: z.ZodString;
+                subject: z.ZodObject<{
+                    id: z.ZodString;
+                    kind: z.ZodEnum<{
+                        office: "office";
+                        professional: "professional";
+                        organization: "organization";
+                    }>;
+                    revision: z.ZodString;
+                }, z.core.$strict>;
+                target_product_id: z.ZodString;
+                intent: z.ZodEnum<{
+                    adoption_outreach: "adoption_outreach";
+                    expansion_review: "expansion_review";
+                    reactivation_review: "reactivation_review";
+                }>;
+                authority: z.ZodLiteral<"recommendation_only">;
+                reasons: z.ZodArray<z.ZodString>;
+                metrics: z.ZodObject<{
+                    active_listing_count: z.ZodNumber;
+                    represented_listing_count: z.ZodNumber;
+                    definition_version: z.ZodLiteral<"directory-sales-inventory-v1">;
+                    coverage: z.ZodLiteral<"authorized_observed_listings">;
+                }, z.core.$strict>;
+                context_fingerprint: z.ZodString;
+                adoption_status: z.ZodEnum<{
+                    unknown: "unknown";
+                    active: "active";
+                    prospect: "prospect";
+                    trial: "trial";
+                    paused: "paused";
+                    churned: "churned";
+                }>;
+                account_id: z.ZodNullable<z.ZodString>;
+                verified_account_binding_id: z.ZodNullable<z.ZodString>;
+                contact_resolution: z.ZodObject<{
+                    entity_id: z.ZodString;
+                    operation: z.ZodLiteral<"directoryGetContacts">;
+                    purpose: z.ZodEnum<{
+                        office: "office";
+                        professional: "professional";
+                        organization: "organization";
+                    }>;
+                    requires_current_authorization: z.ZodLiteral<true>;
+                }, z.core.$strict>;
+                expires_at: z.ZodISODateTime;
+            }, z.core.$strict>>;
+            exclusions: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            created_at: z.ZodISODateTime;
+            expires_at: z.ZodISODateTime;
+        }, z.core.$strict>;
+    };
+};
+export type DirectorySalesPlanInput = z.output<typeof DirectorySalesPlanRequest>;
+export type DirectorySalesPlan = z.infer<typeof DirectorySalesPlanSchema>;
+export type DirectorySalesRecommendation = z.infer<typeof DirectorySalesRecommendationSchema>;

package/contracts/src/directory-sales.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+const Id = z.string().min(1).max(256), Time = z.iso.datetime({ offset: true });
+export const DirectorySalesContextSchema = z
+    .strictObject({
+    schema_version: z.literal('directory-sales-v1'),
+    product_id: Id,
+    adoption_status: z.enum(['prospect', 'trial', 'active', 'paused', 'churned', 'unknown']),
+    account_id: Id.nullable(),
+    verified_account_binding_id: Id.nullable(),
+    last_activity_at: Time.nullable(),
+    last_contacted_at: Time.nullable(),
+    suppressed: z.boolean(),
+    unsubscribed: z.boolean(),
+    snoozed_until: Time.nullable(),
+})
+    .refine((value) => (value.account_id === null) === (value.verified_account_binding_id === null), {
+    message: 'Account and verified binding must be supplied together',
+});
+export const DirectorySalesProfilePolicySchema = z.strictObject({
+    reviewed: z.boolean(),
+    required_context: z.array(Id).min(1).max(10),
+    max_context_age_minutes: z.number().int().min(1).max(1440),
+    max_source_age_minutes: z.number().int().min(1).max(720),
+    allowed_audience_ids: z.array(Id).min(1).max(100),
+    allowed_subject_kinds: z
+        .array(z.enum(['professional', 'office', 'organization']))
+        .min(1)
+        .max(3),
+    eligible_adoption_states: z
+        .array(z.enum(['prospect', 'trial', 'active', 'paused', 'churned']))
+        .min(1)
+        .max(5),
+    minimum_active_listings: z.number().int().min(1).max(1000000),
+    contact_cooldown_hours: z.number().int().min(0).max(8760),
+    validity_minutes: z.number().int().min(1).max(1440),
+    purpose_family: Id,
+    intent: z.enum(['adoption_outreach', 'expansion_review', 'reactivation_review']),
+});
+export const DirectorySalesPlanRequest = z.strictObject({
+    dataset_id: Id,
+    profile_id: Id,
+    audience_id: Id,
+    subject_ids: z
+        .array(Id)
+        .min(1)
+        .max(500)
+        .refine((values) => new Set(values).size === values.length, {
+        message: 'Duplicate subjects are not allowed',
+    }),
+    target_count: z.number().int().min(1).max(500).default(100),
+});
+export const DirectorySalesRecommendationSchema = z.strictObject({
+    intent_id: Id,
+    subject: z.strictObject({
+        id: Id,
+        kind: z.enum(['professional', 'office', 'organization']),
+        revision: z.string(),
+    }),
+    target_product_id: Id,
+    intent: z.enum(['adoption_outreach', 'expansion_review', 'reactivation_review']),
+    authority: z.literal('recommendation_only'),
+    reasons: z.array(z.string()),
+    metrics: z.strictObject({
+        active_listing_count: z.number().int().nonnegative(),
+        represented_listing_count: z.number().int().nonnegative(),
+        definition_version: z.literal('directory-sales-inventory-v1'),
+        coverage: z.literal('authorized_observed_listings'),
+    }),
+    context_fingerprint: z.string(),
+    adoption_status: DirectorySalesContextSchema.shape.adoption_status,
+    account_id: Id.nullable(),
+    verified_account_binding_id: Id.nullable(),
+    contact_resolution: z.strictObject({
+        entity_id: Id,
+        operation: z.literal('directoryGetContacts'),
+        purpose: z.enum(['professional', 'office', 'organization']),
+        requires_current_authorization: z.literal(true),
+    }),
+    expires_at: Time,
+});
+export const DirectorySalesPlanSchema = z.strictObject({
+    id: Id,
+    profile_id: Id,
+    policy_revision: z.string(),
+    dataset_id: Id,
+    audience_id: Id,
+    status: z.enum(['ready', 'blocked', 'stale', 'expired']),
+    authority: z.literal('recommendation_only'),
+    requested_count: z.number().int(),
+    examined_count: z.number().int(),
+    selected_count: z.number().int(),
+    shortfall: z.number().int(),
+    selection_scope: z.literal('explicit_bounded_subject_set'),
+    data: z.array(DirectorySalesRecommendationSchema),
+    exclusions: z.record(z.string(), z.number().int().nonnegative()),
+    created_at: Time,
+    expires_at: Time,
+});
+export const directorySalesOperations = {
+    createDirectorySalesPlan: { input: DirectorySalesPlanRequest, output: DirectorySalesPlanSchema },
+    getDirectorySalesPlan: { input: z.strictObject({ id: Id }), output: DirectorySalesPlanSchema },
+};