@devdash/bofrid-api-types 0.1.5

package/dist/services/homii/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Homii posting orchestrator.
+ *
+ * Queries listing + property + images from DB, maps to Homii payload,
+ * resolves location, uploads image, and posts to Homii API.
+ *
+ * Returns a structured result with per-step status for admin visibility.
+ */
+import type { HomiiPostResult, HomiiPreviewResult } from "./types";
+export { type HomiiPostResult, type HomiiPreviewResult, type HomiiBroadcastMeta } from "./types";
+export declare function previewHomiiListing(listingId: string): Promise<HomiiPreviewResult>;
+export declare function postListingToHomii(listingId: string): Promise<HomiiPostResult>;

package/dist/services/homii/location.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Homii location resolver — resolves a city name to a Google Place ID
+ * using the Google Places Text Search API.
+ *
+ * Homii's own location-autocomplete API was deprecated (404 since 2025).
+ * Their post-listing endpoint requires a `locationGooglePlaceId` field.
+ *
+ * NOTE (2026-03-15): Only Stockholm-region listings return 204 from Homii.
+ * Göteborg, Malmö, Örebro, Borås, Uppsala all return 500 from Homii API.
+ */
+export interface LocationResult {
+    success: boolean;
+    placeId?: string;
+    region?: string;
+    error?: string;
+}
+interface ResolveLocationOpts {
+    /** Street address (e.g. "Barkarbyvägen 30C") */
+    street?: string | null;
+    /** City name (e.g. "Järfälla") */
+    city: string;
+}
+/**
+ * Resolve an address to a Google Place ID via Google Places Text Search API.
+ *
+ * Uses street + city when available to get a locality-level place ID
+ * (not just a municipality). Homii extracts `locality` from the place ID
+ * for their page title — a municipality-level ID leaves `locality` null
+ * which causes "Ledig lägenhet att hyra - null" on their site.
+ */
+export declare function resolveLocation(cityOrOpts: string | null | undefined | ResolveLocationOpts): Promise<LocationResult>;
+export {};

package/dist/services/homii/mapper.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Homii payload mapper — converts Bofrid DB rows to Homii API payload.
+ */
+import type { HomiiListingPayload } from "./types";
+export interface PropertyData {
+    propertyType: string;
+    propertySize: number;
+    totalRooms: number;
+    description: string | null;
+    furnishingStatus: string | null;
+    amenities: string[] | null;
+    includedUtilities: string[] | null;
+    baseMonthlyRent: number | null;
+    rentalStart: string | null;
+    rentalEnd: string | null;
+    extensionPossible: boolean | null;
+    street: string;
+    streetNumber: string | null;
+    postalCode: string | null;
+    city: string;
+}
+export interface ImageData {
+    url: string;
+    urls: unknown;
+    isPrimary: boolean;
+}
+export interface MapperInput {
+    property: PropertyData;
+    images: ImageData[];
+    listingId: string;
+    publicUrl?: string | null;
+}
+export interface MapperResult {
+    success: boolean;
+    payload: HomiiListingPayload | null;
+    sourceImageUrl: string | null;
+    warnings: string[];
+    errors: string[];
+}
+export declare function buildAddress(p: PropertyData): string;
+export declare function mapToHomiiPayload(input: MapperInput): MapperResult;

package/dist/services/homii/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Homii API types — payload, response, and mapping types.
+ *
+ * Homii's post-listing API is unauthenticated (device_id cookie only).
+ * Endpoint: POST https://subletting.api.homii.se/post-listing
+ */
+export type HomiiPropertyType = "APARTMENT" | "HOUSE" | "ROOM";
+export type HomiiAvailabilityType = "IMMEDIATE" | "DETERMINED";
+export type HomiiLeaseLengthType = "INDEFINITE" | "FIXED_TERM";
+export interface HomiiListingPayload {
+    listingId: string;
+    renterFirstName: string;
+    renterLastName: string;
+    renterEmailAddress: string;
+    headline: string;
+    description: string;
+    pictureUrl: string;
+    propertyType: HomiiPropertyType;
+    propertyNumberOfRooms: number;
+    propertySquareMeters: number;
+    propertyPrivateEntrance: boolean;
+    propertyPrivateBathroom: boolean;
+    propertyPrivateKitchen: boolean;
+    locationGooglePlaceId: string;
+    leasePeriodAvailabilityType: HomiiAvailabilityType;
+    leasePeriodFromDate?: string;
+    leasePeriodLengthType: HomiiLeaseLengthType;
+    leasePeriodToDate?: string;
+    leasePeriodPossibleToExtend: boolean;
+    rentSpecificationMonthlyRent: number;
+    rentSpecificationCableTvIncluded: boolean;
+    rentSpecificationInternetIncluded: boolean;
+    rentSpecificationElectricityIncluded: boolean;
+    featuresAndAmenitiesFurnished: boolean;
+    featuresAndAmenitiesBalcony: boolean;
+    featuresAndAmenitiesWasher: boolean;
+    featuresAndAmenitiesDishwasher: boolean;
+    featuresAndAmenitiesBathtub: boolean;
+    featuresAndAmenitiesParking: boolean;
+    featuresAndAmenitiesElevator: boolean;
+}
+export interface HomiiPreviewResult {
+    canPost: boolean;
+    errors: string[];
+    warnings: string[];
+    payload: HomiiListingPayload | null;
+    sourceImageUrl: string | null;
+    address: string;
+    region: string | null;
+}
+export interface HomiiStepResult {
+    success: boolean;
+    error?: string;
+    detail?: string;
+}
+export interface HomiiPostResult {
+    success: boolean;
+    homiiListingId?: string;
+    homiiUrl?: string;
+    /** Raw response from Homii API (for debugging) */
+    homiiResponse?: unknown;
+    /** The full payload sent to Homii (for debugging) */
+    payload?: HomiiListingPayload;
+    error?: string;
+    warnings: string[];
+    steps: {
+        mapping: HomiiStepResult;
+        location: HomiiStepResult;
+        image: HomiiStepResult;
+        posting: HomiiStepResult;
+    };
+}
+export interface HomiiBroadcastMeta {
+    homiiListingId?: string;
+    homiiUrl?: string;
+    homiiResponse?: unknown;
+    /** The full Homii payload that was sent (for admin debugging) */
+    payload?: HomiiListingPayload;
+    /** Who triggered the posting */
+    triggeredBy?: {
+        name: string;
+        email?: string;
+    };
+    warnings?: string[];
+    steps?: {
+        mapping: HomiiStepResult;
+        location: HomiiStepResult;
+        image: HomiiStepResult;
+        posting: HomiiStepResult;
+    };
+}

package/dist/services/leads/constants.d.ts

@@ -0,0 +1,32 @@
+import type { LeadTier } from "./types";
+export type UpgradeFeature = "unlimited_reveals" | "auto_conversations" | "bevakning_email" | "priority_visibility";
+export interface UpgradeTierDef {
+    /** Tier version (1, 2, …). Stored in DB as `upgrade_tier`. */
+    tier: number;
+    /** Price in öre at time of sale */
+    priceOre: number;
+    /** Stripe product label (Swedish) */
+    label: string;
+    /** Features included in this tier */
+    features: readonly UpgradeFeature[];
+}
+/**
+ * All tier definitions, ordered by version.
+ * RULES:
+ *  - NEVER remove or mutate an existing entry (old purchases reference it).
+ *  - To change price or add features, append a new tier and bump CURRENT_UPGRADE_TIER.
+ */
+export declare const UPGRADE_TIERS: readonly UpgradeTierDef[];
+/** The tier sold to new buyers right now. Bump this when adding a new tier. */
+export declare const CURRENT_UPGRADE_TIER = 2;
+/** Helper: get tier definition by version number */
+export declare function getUpgradeTier(tier: number): UpgradeTierDef | undefined;
+/** Helper: get the current tier definition (what new buyers get) */
+export declare function getCurrentUpgradeTier(): UpgradeTierDef;
+/** Helper: check if a tier includes a specific feature */
+export declare function tierHasFeature(tier: number | null | undefined, feature: UpgradeFeature): boolean;
+/** @deprecated Use getCurrentUpgradeTier().priceOre instead */
+export declare const LISTING_UPGRADE_PRICE_ORE = 50000;
+export declare const LEAD_TIER_SCORES: Record<LeadTier, number>;
+export declare const MIN_KEY_DOC_CATEGORIES = 2;
+export declare const KEY_DOC_CATEGORIES: readonly ["credit_report", "criminal_record_extract", "income_doc"];

package/dist/services/leads/generate-leads.service.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Lead Generation Service
+ *
+ * Generates leads by matching bevakningar to published listings.
+ * Supports both directions:
+ *   - Forward: listing publishes → find matching bevakningar → create leads
+ *   - Reverse: bevakning created → find matching published listings → create leads
+ */
+export interface GenerateLeadsForListingOpts {
+    listingId: string;
+    /** The landlord/admin user triggering this */
+    actingUserId: string;
+}
+export declare function generateLeadsForListing(opts: GenerateLeadsForListingOpts): Promise<{
+    created: number;
+    skipped: number;
+    errors: number;
+}>;
+export interface GenerateLeadsForBevakningOpts {
+    bevakningId: string;
+    userId: string;
+    filters: {
+        maxRent?: number;
+        propertyTypes?: string[];
+        minRooms?: number;
+        maxRooms?: number;
+    } | null;
+    numberOfPeople?: number | null;
+}
+/**
+ * When a new bevakning is created, find all published listings whose property
+ * coordinates fall within the bevakning's polygon and create leads.
+ */
+export declare function generateLeadsForBevakning(opts: GenerateLeadsForBevakningOpts): Promise<{
+    created: number;
+    skipped: number;
+    errors: number;
+}>;

package/dist/services/leads/matching.service.d.ts

@@ -0,0 +1,55 @@
+import type { MatchDetails } from "./types";
+export interface LocationInterest {
+    id: string;
+    userId: string;
+    active: boolean;
+    emailNotifications: boolean;
+    location: {
+        place_id?: string;
+        name?: string;
+        bounds?: {
+            southwest: {
+                lat: number;
+                lng: number;
+            };
+            northeast: {
+                lat: number;
+                lng: number;
+            };
+        };
+    };
+    numberOfPeople?: number;
+}
+export interface ListingForMatching {
+    id: string;
+    location: {
+        geoCoordinates: {
+            lat: number;
+            lon: number;
+        };
+    };
+    rules: {
+        maxOccupancy: number;
+    };
+}
+export interface BevakningForMatching extends LocationInterest {
+    filters?: {
+        maxRent?: number;
+        propertyTypes?: string[];
+        minRooms?: number;
+        maxRooms?: number;
+    };
+}
+export interface ListingForLeadMatching extends ListingForMatching {
+    pricing: {
+        baseMonthlyRent: number;
+    };
+    listing: {
+        propertyType: string;
+    };
+    dimensions: {
+        totalRooms: number;
+    };
+    landlordId: string;
+}
+export declare function matchBevakningToListing(bevakning: BevakningForMatching, listing: ListingForLeadMatching): MatchDetails | null;

package/dist/services/leads/tier.service.d.ts

@@ -0,0 +1,6 @@
+import type { LeadSource, LeadTier } from "./types";
+export declare function classifyTier(source: LeadSource, hasUploadedDocs: boolean): LeadTier;
+export declare function getTierScore(tier: LeadTier): number;
+export declare function hasKeyDocsUploaded(documents: Array<{
+    category?: string;
+}> | undefined): boolean;

package/dist/services/leads/types.d.ts

@@ -0,0 +1,27 @@
+export type LeadTier = "super_premium" | "premium" | "standard" | "basic";
+export type LeadSource = "bevakning" | "application" | "both";
+export type LeadStatus = "active" | "expired" | "converted" | "declined";
+export interface MaskedTenantData {
+    firstInitial: string;
+    age?: number;
+    bostadsmeritScore: number;
+    employmentStatus?: string;
+    hasVerifiedDocs: boolean;
+    verifiedDocCount: number;
+    uploadedDocCount: number;
+    referenceCount: number;
+    numberOfPeople?: number;
+    firstName?: string;
+    title?: string;
+    profilePictureUrl?: string;
+    email?: string;
+    phoneNumber?: string;
+    about?: string;
+}
+export interface MatchDetails {
+    geographicMatch: boolean;
+    rentInBudget: boolean;
+    propertyTypeMatch: boolean;
+    roomCountMatch: boolean;
+    overallMatchScore: number;
+}

package/dist/services/listings/seo.service.d.ts

@@ -0,0 +1,57 @@
+/**
+ * SEO URL Generation Service
+ *
+ * Generates listing SEO URLs server-side during listing creation.
+ * Uses the Bofrid Geo API (SCB polygon data) for reverse geocoding,
+ * then builds deterministic URL slugs from property data.
+ *
+ * URL Pattern (Swedish): /hyra-{type}/{län}/{kommun}/{område}/{slug}
+ * URL Pattern (English): /en/rent-{type}/sweden/{län}/{kommun}/{område}/{slug}
+ * Slug format: {street}-{rooms}-{size}kvm-{type}-{timestamp}
+ */
+interface SEOInput {
+    propertyType: string;
+    totalRooms: number;
+    propertySize: number;
+    street: string;
+    streetNumber?: string | null;
+    city?: string | null;
+    municipality?: string | null;
+    lat: number;
+    lon: number;
+    shortId: string;
+}
+interface SEOResult {
+    slug: string;
+    regionSlug: string;
+    municipalitySlug: string;
+    områdeSlug: string;
+    isCardinalFallback: boolean;
+    routePrefix: "hyra-lagenhet" | "hyra-hus";
+    fullPath: string;
+    fullPathEn: string;
+}
+export declare function generateListingSEO(input: SEOInput): Promise<SEOResult | null>;
+export declare function generateAndSaveListingSEO(listingId: string, input: SEOInput): Promise<void>;
+export declare function ensureListingSEO(listingId: string): Promise<void>;
+/** Fields that affect the SEO URL and should trigger regeneration */
+export declare const SEO_RELEVANT_FIELDS: Set<string>;
+export interface PropertyGeo {
+    geoLan: string;
+    geoKommun: string;
+    geoOmrade: string;
+    geoRoutePrefix: string;
+}
+/**
+ * Reverse geocode lat/lon and save geo columns on the property.
+ * Returns the resolved geo data, or null if reverse geocode fails.
+ */
+export declare function resolveAndSavePropertyGeo(propertyId: string, lat: number, lon: number, propertyType: string): Promise<PropertyGeo | null>;
+/**
+ * Refresh SEO URLs for all active listings of a property.
+ * Also updates the property's geo columns.
+ * Called when SEO-relevant property fields change (address, type, size, rooms).
+ * Fire-and-forget safe — logs errors but does not throw.
+ */
+export declare function refreshPropertyListingSEO(propertyId: string): Promise<void>;
+export {};

package/dist/services/listings/status.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Listing status taxonomy and visibility predicates.
+ *
+ * `bofrid_listings.status` is plain text in the schema. The valid values and
+ * the questions we ask about them ("does this still block the property slot?",
+ * "does it count against the user's quota?") live here so they live in one
+ * place instead of being re-spelled at every call site.
+ *
+ * Each `where*` helper returns a Drizzle SQL predicate suitable for
+ * `where(and(..., wherePredicate()))`. They reference `listings.status`
+ * directly, so they only work in queries where `listings` is in scope.
+ *
+ * Note: `eq(listings.status, "published")` is intentionally NOT wrapped here —
+ * call sites differ on whether they also require `publishedAt IS NOT NULL`,
+ * and unifying them is a separate question worth its own pass.
+ */
+import type { SQL } from "drizzle-orm";
+export declare const LISTING_STATUSES: readonly ["draft", "under_review", "rejected", "published", "archived", "rented", "deleted"];
+export type ListingStatus = (typeof LISTING_STATUSES)[number];
+/**
+ * Listing is not soft-deleted — safe for owner/admin reads.
+ */
+export declare const whereNotDeleted: () => SQL;
+/**
+ * Listing occupies the property's "advertised" slot — another listing on the
+ * same property cannot be created while one of these exists. Mirrors the
+ * partial unique index `uq_listings_one_active_per_property`
+ * (`status NOT IN ('archived','rented','deleted')`). Rented listings free the
+ * slot because the rental cycle is complete.
+ */
+export declare const whereOccupyingPropertySlot: () => SQL;
+/**
+ * Listing counts toward the landlord's MAX_DRAFTS quota. Wider than
+ * `whereOccupyingPropertySlot` — `rented` listings still count, since they
+ * remain on the landlord's roster until archived.
+ */
+export declare const whereCountedTowardQuota: () => SQL;

package/dist/services/mejl/client.d.ts

@@ -0,0 +1,38 @@
+/**
+ * mejl.to (MailMCP) HTTP client.
+ * Docs: https://docs.mejl.to — base URL: https://api.mejl.to
+ */
+export declare class MejlConfigError extends Error {
+}
+export declare class MejlApiError extends Error {
+    status: number;
+    body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+export declare const mejl: {
+    listInboxes: (q: {
+        limit?: number;
+        page_token?: string;
+    }) => Promise<unknown>;
+    listMessages: (inboxId: string, q: {
+        limit?: number;
+        page_token?: string;
+        labels?: string;
+        before?: string;
+        after?: string;
+        ascending?: boolean;
+        include_spam?: boolean;
+    }) => Promise<unknown>;
+    getMessage: (inboxId: string, messageId: string) => Promise<unknown>;
+    sendMessage: (inboxId: string, body: Record<string, unknown>) => Promise<unknown>;
+    sendSms: (body: {
+        to: string | string[];
+        text: string;
+        ttl?: number;
+        with_delivery_report?: boolean;
+    }) => Promise<unknown>;
+    listSmsMessages: (q: {
+        limit?: number;
+    }) => Promise<unknown>;
+    getSmsMessage: (id: string) => Promise<unknown>;
+};

package/dist/services/mrkoll/client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * mrkoll chromebox client.
+ *
+ * Talks to the chromebox /exec endpoint that drives the `mrkoll` Chromium
+ * profile. Read-only — only `search-person` and `get-person`.
+ *
+ * Profile isolation: every call passes `--account <MRKOLL_ACCOUNT>` (default
+ * "mrkoll"). The chromebox maps each account slug to its own Chromium
+ * `user_data_dir` (verify via GET /chrome/profiles), so cookies, Cloudflare
+ * clearance and IAB consent persist independently of other adapters
+ * (facebook, strato, devto, …) running on the same chromebox container.
+ * Never point MRKOLL_ACCOUNT at "default" — that's the shared profile.
+ */
+export interface MrkollSearchHit {
+    id: string;
+    person_url: string;
+    full_name: string;
+    age: number | null;
+    street_address: string | null;
+    postal_code: string | null;
+    city: string | null;
+    pnr_prefix: string | null;
+    resident_since: string | null;
+}
+export interface MrkollSearchResult {
+    ok: boolean;
+    query: string;
+    location: string | null;
+    total: number;
+    pnr_filtered_total: number;
+    pnr_filter_applied: string | null;
+    results: MrkollSearchHit[];
+    aborted_reason: string | null;
+}
+export interface MrkollPreviousAddress {
+    street: string;
+    postal_code: string | null;
+    city: string | null;
+    effective: string;
+}
+export interface MrkollHouseholdMember {
+    name: string;
+    person_url: string;
+}
+export interface MrkollPerson {
+    ok: boolean;
+    id: string;
+    person_url: string;
+    display_name: string | null;
+    calling_name: string | null;
+    middle_name: string | null;
+    last_name: string | null;
+    age: number | null;
+    gender: string | null;
+    birth_date: string | null;
+    pnr_full: string | null;
+    street_address: string | null;
+    postal_code: string | null;
+    city: string | null;
+    municipality: string | null;
+    region: string | null;
+    housing_type: string | null;
+    lives_alone: boolean | null;
+    name_day: string | null;
+    household_members: MrkollHouseholdMember[];
+    previous_addresses: MrkollPreviousAddress[];
+    name_changes?: {
+        first?: boolean;
+        middle?: boolean;
+        last_was?: string | null;
+    } | null;
+    phone: string | null;
+    vehicle_summary: string | null;
+    area_avg_income: number | null;
+    area_max_income: number | null;
+    income_indicator: number | null;
+    has_dogs: boolean | null;
+    company_engagements: string | null;
+    fetched_at: string | null;
+    aborted_reason: string | null;
+}
+export declare class MrkollClientError extends Error {
+    readonly kind: "not_configured" | "network" | "http_error" | "exec_error" | "timeout";
+    readonly status?: number | undefined;
+    constructor(message: string, kind: "not_configured" | "network" | "http_error" | "exec_error" | "timeout", status?: number | undefined);
+}
+export interface SearchPersonInput {
+    query: string;
+    pnr?: string;
+    location?: string;
+    limit?: number;
+}
+export declare function searchPerson(input: SearchPersonInput): Promise<MrkollSearchResult>;
+export declare function getPerson(id: string): Promise<MrkollPerson>;
+export declare function isMrkollConfigured(): boolean;

package/dist/services/mrkoll/import.d.ts

@@ -0,0 +1,38 @@
+import { type MrkollPerson } from "./client";
+import { type HousingHistoryInsert } from "./match";
+export type MrkollImportResult = {
+    status: "verified";
+    entries: HousingHistoryInsert[];
+    person: MrkollPerson;
+} | {
+    status: "not_found";
+} | {
+    status: "ambiguous";
+    hitCount: number;
+} | {
+    status: "pnr_mismatch";
+} | {
+    status: "rate_limited";
+} | {
+    status: "error";
+    reason: string;
+};
+export interface MrkollImportInput {
+    profileId: string;
+    fullName: string;
+    personnummer: string;
+}
+/**
+ * Resolve a Bofrid profile to its mrkoll record and produce verified
+ * housing-history rows. Read-only against mrkoll, server-side only.
+ *
+ * Match path:
+ *   1. search-person --query <fullName> --pnr <pnr>
+ *   2. on 0 hits     -> not_found
+ *   3. on 1 hit      -> get-person -> assert pnr_full
+ *   4. on 2+ hits    -> get-person on each, look for exactly one pnr_full match
+ *
+ * The 100% certainty step is `pnr_full` equality after `get-person`.
+ * `pnr_full` is consumed in-memory only and never logged or persisted.
+ */
+export declare function importMrkollFolkbokforing(input: MrkollImportInput): Promise<MrkollImportResult>;

package/dist/services/mrkoll/match.d.ts

@@ -0,0 +1,35 @@
+import type { MrkollPerson } from "./client";
+import type { housingHistory } from "@bofrid/db";
+export type HousingHistoryInsert = typeof housingHistory.$inferInsert;
+/**
+ * Parse mrkoll's Swedish "effective" string for a previous address.
+ *  - "Flyttade till denna tidigare adress 2021-06-01" -> "2021-06-01"
+ *  - "Flyttdatumet till denna tidigare adress är okänt" -> null
+ *  - anything else -> null
+ */
+export declare function parsePnrEffective(effective: string | null | undefined): {
+    moveInDate: string | null;
+};
+/**
+ * Strip non-digits from a personnummer.
+ */
+export declare function normalizeDigits(input: string | null | undefined): string;
+/**
+ * Redact a personnummer to "YYYYMMDD-XXXX" form for safe logging.
+ * Anything we can't recognise -> "redacted".
+ */
+export declare function redactPnr(input: string | null | undefined): string;
+/**
+ * Compare two personnummer for equality after normalising. Both must be
+ * 12 digits or this returns false.
+ */
+export declare function pnrMatches(expected: string, got: string | null | undefined): boolean;
+/**
+ * Map a verified mrkoll person record into housing_history insert rows.
+ * Marks rows as `verified: true, verifiedAt: now()` (verifiedBy stays null
+ * — system, not an admin).
+ *
+ * `moveOutDate` is the next-newer move-in date, mirroring the existing
+ * Nusvar logic: previous_addresses[] are sorted newest-first.
+ */
+export declare function mrkollToHousingEntries(person: MrkollPerson, profileId: string): HousingHistoryInsert[];