@devdash/bofrid-api-types 0.1.5

package/dist/rpc.d.ts

@@ -0,0 +1,11 @@
+/**
+ * RPC type export for Hono client consumers (apps/web).
+ *
+ * This file exists to provide a clean import path that doesn't
+ * pull in implementation files with @/ path aliases. The type is
+ * re-exported from the route chain in routes/index.ts.
+ *
+ * Usage in apps/web:
+ *   import type { AppType } from "@bofrid/api/rpc";
+ */
+export type { AppType } from "./routes/index";

package/dist/serve.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    port: number;
+    fetch: (request: Request, Env?: unknown, executionCtx?: import("hono").ExecutionContext) => Response | Promise<Response>;
+};
+export default _default;

package/dist/services/activity-feed/activity-feed.service.d.ts

@@ -0,0 +1,26 @@
+type Severity = "action_required" | "waiting" | "info" | "completed";
+type Category = "application" | "document" | "reference" | "identity" | "listing_review" | "listing_rejected" | "listing_upgraded" | "incoming_application" | "invoice" | "company_invite";
+export interface ActivityItem {
+    id: string;
+    category: Category;
+    severity: Severity;
+    title: string;
+    description?: string;
+    subtitle?: string;
+    imageUrl?: string;
+    avatarUrl?: string;
+    avatarFallback?: string;
+    href: string;
+    resourceId?: string;
+    createdAt: string;
+    completedAt?: string;
+}
+interface ActivityFeedResult {
+    items: ActivityItem[];
+    historyItems: ActivityItem[];
+    counts: Record<Category, number>;
+    total: number;
+}
+type Locale = "sv" | "en";
+export declare function getActivityFeed(profileId: string, locale: Locale, view?: "tenant" | "landlord" | "company"): Promise<ActivityFeedResult>;
+export {};

package/dist/services/applications/approval.service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Check if a tenant has the required documents for auto-approval.
+ * Returns the list of missing categories.
+ */
+export declare function checkRequiredDocs(tenantId: string): Promise<{
+    hasAll: boolean;
+    missing: string[];
+}>;
+/**
+ * Execute the full approval flow for an application:
+ * 1. Set adminApproved = true
+ * 2. Create/upgrade lead
+ * 3. Send landlord notification
+ */
+export declare function executeApprovalFlow(applicationId: string, approverProfileId: string | null): Promise<{
+    leadCreated: boolean;
+}>;

package/dist/services/auth/bankid-login.service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * BankID Login Service — handles user lookup/creation and session creation
+ * for the BankID login flow (unauthenticated users).
+ */
+interface FoundUser {
+    profileId: string;
+    authUserId: string;
+    email: string | null;
+}
+/**
+ * Find an existing active user by personnummer.
+ */
+export declare function findUserByPersonnummer(personnummer: string): Promise<FoundUser | null>;
+interface BankIDUserData {
+    personnummer: string;
+    displayName: string;
+    givenName: string;
+    surname: string;
+}
+interface CreatedUser {
+    authUserId: string;
+    profileId: string;
+    email: string;
+}
+/**
+ * Create a new user from BankID data with a deterministic placeholder email.
+ * If a BA user with the placeholder email already exists (incomplete previous flow),
+ * reuse it.
+ */
+export declare function createNewBankIDUser(bankIDData: BankIDUserData): Promise<CreatedUser>;
+/**
+ * Create a Better Auth session for a user by email.
+ * Returns a Response with Set-Cookie headers.
+ *
+ * Uses an email-keyed OTP resolver map so concurrent BankID logins on the
+ * same warm serverless instance don't clobber each other's OTP.
+ */
+export declare function createSessionForUser(email: string, requestHeaders: Headers): Promise<Response>;
+export declare function recordBankIDLogin(profileId: string, email: string | null, ipAddress: string | null, userAgent: string | null): Promise<void>;
+export {};

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

@@ -0,0 +1,2 @@
+/** Default VAT rate for Swedish domestic invoices (25%) */
+export declare const DEFAULT_VAT_RATE = 25;

package/dist/services/billing/contact-billing.service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Contact Billing Service — read-only billing view + Stripe customer queries.
+ *
+ * The pay-per-reveal charge path was removed when single-reveal checkout was
+ * retired. Listings now pay per-listing (listing upgrade) and tenants pay
+ * per-subscription (Boost); both use Stripe Checkout directly rather than
+ * the invoice-items pipeline. The functions here read historical invoice
+ * items + Stripe customer state for the billing dashboard.
+ */
+import type { ContactBillingUsage, StripeInvoiceSummary } from "./types";
+/**
+ * Get monthly usage stats for billing dashboard.
+ * Now reads from local invoice items for accurate breakdown.
+ */
+export declare function getMonthlyUsage(userId: string): Promise<ContactBillingUsage>;
+/**
+ * Check if the user's Stripe customer has a default payment method.
+ */
+export declare function checkPaymentMethod(userId: string): Promise<{
+    hasPaymentMethod: boolean;
+    brand?: string;
+    last4?: string;
+}>;
+/**
+ * List invoices — reads from local DB first, falls back to Stripe for historical.
+ */
+export declare function getInvoices(userId: string): Promise<StripeInvoiceSummary[]>;
+/**
+ * Create a Stripe Customer Portal session so the user can manage
+ * payment methods, view invoices, and download receipts.
+ */
+export declare function createPortalSession(userId: string, returnUrl: string): Promise<string>;
+/**
+ * Get the billing email from Stripe customer record.
+ * Stripe is the source of truth for invoice/billing email.
+ */
+export declare function getBillingEmail(userId: string): Promise<{
+    email: string | null;
+}>;
+/**
+ * Update the billing email on the Stripe customer record.
+ * Stripe is the source of truth — no local DB write needed.
+ */
+export declare function updateBillingEmail(userId: string, email: string): Promise<{
+    email: string;
+}>;
+/**
+ * Get Stripe receipts (from charges) for the authenticated user.
+ * Each successful Stripe Checkout creates a Charge with a receipt_url.
+ */
+export declare function getReceipts(userId: string): Promise<{
+    id: string;
+    amount: number;
+    currency: string;
+    description: string | null;
+    receiptUrl: string | null;
+    created: number;
+    paymentIntentId: string | null;
+}[]>;

package/dist/services/billing/customer.service.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Customer Service — Stripe customer management for Bofrid users.
+ */
+import type { Subscriber } from "./types";
+/**
+ * Resolve subscriber data for Stripe customer creation.
+ * Determines company vs user from businessType field.
+ */
+export declare function resolveSubscriber(userId: string): Promise<Subscriber | null>;
+/**
+ * Get or create Stripe customer for a user.
+ * Validates existing customer, adds VAT tax_id for companies.
+ */
+export declare function getOrCreateStripeCustomer(userId: string, email: string, name: string, organizationNumber?: string): Promise<string>;

package/dist/services/billing/invoice-item.service.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Invoice Item Service — read-only queries against historical invoice items.
+ *
+ * Creation of new items was retired with the single-reveal checkout flow.
+ * Listing upgrades and Boost subscriptions go straight to Stripe Checkout;
+ * the rows here are kept for the billing dashboard and historical reports.
+ */
+import type { LocalInvoiceItem } from "./types";
+/**
+ * Returns the current billing period as "YYYY-MM".
+ */
+export declare function getCurrentBillingPeriod(): string;
+/**
+ * Query pending invoice items for a customer, optionally filtered by billing period.
+ */
+export declare function getPendingItems(customerId: string, billingPeriod?: string): Promise<LocalInvoiceItem[]>;
+/**
+ * Get all invoice items for a customer in a billing period (any status).
+ */
+export declare function getItemsForPeriod(customerId: string, billingPeriod?: string): Promise<LocalInvoiceItem[]>;
+/**
+ * Void an invoice item. Sets status to "void" and attempts to delete
+ * the Stripe invoice item if it hasn't been invoiced yet.
+ */
+export declare function voidInvoiceItem(itemId: string): Promise<void>;
+/**
+ * Get usage breakdown by invoice item type for a customer in the current period.
+ */
+export declare function getUsageBreakdown(customerId: string): Promise<{
+    type: string;
+    count: number;
+    totalOre: number;
+}[]>;
+/**
+ * Get transaction history with property address info.
+ * Joins invoice items → listings → properties to enrich each item
+ * with the street/city of the listing that was revealed.
+ */
+export declare function getTransactionHistory(customerId: string, limit?: number): Promise<{
+    id: string;
+    type: string;
+    description: string;
+    totalOre: number;
+    status: string;
+    billingPeriod: string;
+    createdAt: Date;
+    propertyAddress: string | null;
+    paymentIntentId: string | null;
+}[]>;

package/dist/services/billing/invoice.service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Invoice Service — Local invoice records synced from Stripe webhooks.
+ */
+import type Stripe from "stripe";
+import type { LocalInvoiceSummary, LocalInvoiceItem } from "./types";
+/**
+ * Upsert a local invoice from Stripe webhook data.
+ * Called on invoice.finalized, invoice.paid, invoice.voided, etc.
+ */
+export declare function syncStripeInvoice(stripeInvoice: Stripe.Invoice, customerId: string, companyId?: string): Promise<string>;
+/**
+ * Query local invoices for a customer, ordered by most recent.
+ */
+export declare function getCustomerInvoices(customerId: string, limit?: number): Promise<LocalInvoiceSummary[]>;
+/**
+ * Get an invoice with its line items for detail view.
+ */
+export declare function getInvoiceWithItems(invoiceId: string, customerId: string): Promise<{
+    invoice: LocalInvoiceSummary;
+    items: LocalInvoiceItem[];
+} | null>;

package/dist/services/billing/listing-upgrade-checkout.service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Listing Upgrade Checkout Service
+ *
+ * Creates Stripe Checkout sessions for upgrading a listing (500 SEK).
+ * On webhook completion, sets `listings.upgradedAt` so all reveals are free.
+ */
+import { type UpgradeFeature } from "../../services/leads/constants";
+/** First-listing discount: 50% off */
+export declare const FIRST_LISTING_DISCOUNT_PERCENT = 50;
+/**
+ * Check if a landlord (or their company) has ever upgraded a listing before.
+ * Used to determine first-listing discount eligibility.
+ *
+ * Checks both personal properties (landlordId) and company properties (companyId)
+ * so the discount is per-customer, not per-user.
+ */
+export declare function hasAnyUpgradedListing(userId: string): Promise<boolean>;
+/**
+ * Create a Stripe Checkout session for upgrading a listing.
+ */
+export declare function createListingUpgradeCheckout(userId: string, listingId: string, returnUrl: string): Promise<{
+    alreadyUpgraded: true;
+} | {
+    checkoutUrl: string;
+}>;
+/**
+ * Complete a listing upgrade after Stripe Checkout success (webhook handler).
+ */
+export declare function completeListingUpgradeCheckout(session: {
+    id: string;
+    metadata: Record<string, string> | null;
+}): Promise<void>;
+/**
+ * Check if a listing is upgraded (all reveals free).
+ */
+export declare function isListingUpgraded(listingId: string): Promise<boolean>;
+/**
+ * Get the upgrade tier for a listing (null if not upgraded).
+ */
+export declare function getListingUpgradeTier(listingId: string): Promise<number | null>;
+/**
+ * Check if a listing has a specific upgrade feature.
+ * Returns false if not upgraded or if the tier doesn't include the feature.
+ */
+export declare function listingHasUpgradeFeature(listingId: string, feature: UpgradeFeature): Promise<boolean>;

package/dist/services/billing/purchase-receipt-email.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Purchase Receipt Email — sends a receipt after a successful Stripe Checkout.
+ *
+ * For company users, sends to the company email (or Stripe billing email)
+ * and uses the company name as recipient.
+ */
+interface SendReceiptParams {
+    userId: string;
+    productName: string;
+    amountOre: number;
+    /** VAT rate as integer percent. Defaults to DEFAULT_VAT_RATE (25%). */
+    vatRate?: number;
+}
+/**
+ * Resolve subscriber info and send a purchase receipt email.
+ *
+ * Email priority:
+ *  1. Stripe billing email (if set — source of truth for invoices/receipts)
+ *  2. Company email (for company users)
+ *  3. User profile email (fallback)
+ */
+export declare function sendPurchaseReceipt(params: SendReceiptParams): Promise<void>;
+export {};

package/dist/services/billing/reveal-allowance.service.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Reveal Allowance Service — Free monthly candidate reveals per landlord.
+ *
+ * Each landlord gets FREE_REVEALS_PER_MONTH reveals per calendar month.
+ * Admins can override this per-user via `profiles.freeRevealsPerMonth`
+ * or per-company via `companies.freeRevealsPerMonth`.
+ *
+ * Only reveals with `reveal_reason = 'quota'` consume the allowance. Reveals
+ * triggered by listing-premium, tenant-boost, or admin actions are recorded
+ * with their own reason and never count against the landlord's monthly budget.
+ */
+/** Default number of free reveals per landlord per calendar month */
+export declare const FREE_REVEALS_PER_MONTH = 2;
+/**
+ * Count how many quota-consuming reveals this landlord has used this month.
+ *
+ * A revealed (listing_id, tenant_id) pair counts at most once, even when the
+ * unlock is mirrored across both applications and leads. Only reason='quota'
+ * is counted — listing-premium / tenant-boost / admin unlocks are recorded
+ * but never charged against the monthly budget.
+ */
+export declare function countRevealsThisMonth(profileId: string): Promise<number>;
+/** Reveal allowance status for a landlord. */
+export declare function getRevealAllowance(profileId: string): Promise<{
+    used: number;
+    limit: number;
+    remaining: number;
+    resetDate: string;
+}>;
+/** Whether the landlord can spend a free reveal right now. */
+export declare function canReveal(profileId: string): Promise<boolean>;
+/** Set the per-user reveal limit override. Pass `null` to revert to global default. */
+export declare function setUserRevealLimit(profileId: string, limit: number | null): Promise<void>;

package/dist/services/billing/stripe.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Stripe Client — Lazy initialization for API layer.
+ */
+import Stripe from "stripe";
+export declare function getStripe(): Stripe;
+export declare function getWebhookSecret(): string;

package/dist/services/billing/subscription.service.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Subscription Service — Fetch Stripe subscriptions for a user.
+ */
+export interface SubscriptionSummary {
+    id: string;
+    status: string;
+    productName: string;
+    priceAmountOre: number;
+    currency: string;
+    interval: string;
+    created: number;
+    currentPeriodEnd: number | null;
+    canceledAt: number | null;
+    cancelAt: number | null;
+    endedAt: number | null;
+}
+/**
+ * List all subscriptions for a user, including canceled.
+ * Returns empty array if user has no Stripe customer.
+ */
+export declare function getSubscriptions(userId: string): Promise<SubscriptionSummary[]>;

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

@@ -0,0 +1,64 @@
+export type SubscriberType = "user" | "company";
+export interface Subscriber {
+    id: string;
+    type: SubscriberType;
+    email: string;
+    name: string;
+    companyId?: string;
+    organizationNumber?: string;
+}
+export type InvoiceItemStatus = "pending" | "invoiced" | "void";
+export type InvoiceStatus = "draft" | "open" | "paid" | "void" | "uncollectible";
+export interface LocalInvoiceItem {
+    id: string;
+    type: string;
+    description: string;
+    quantity: number;
+    unitPriceOre: number;
+    totalOre: number;
+    status: string;
+    billingPeriod: string;
+    stripeInvoiceItemId: string | null;
+    sourceType: string | null;
+    sourceId: string | null;
+    createdAt: Date;
+}
+export interface LocalInvoiceSummary {
+    id: string;
+    stripeInvoiceId: string;
+    invoiceNumber: string | null;
+    billingPeriod: string;
+    status: string;
+    subtotalOre: number;
+    vatOre: number;
+    totalOre: number;
+    currency: string;
+    hostedInvoiceUrl: string | null;
+    invoicePdf: string | null;
+    itemCount: number;
+    paidAt: Date | null;
+    createdAt: Date;
+}
+export interface BillingUsageBreakdown {
+    type: string;
+    count: number;
+    totalOre: number;
+}
+export interface ContactBillingUsage {
+    revealsThisMonth: number;
+    totalAmountThisMonth: number;
+    hasPaymentMethod: boolean;
+    breakdown: BillingUsageBreakdown[];
+    pendingItemCount: number;
+    pendingTotalOre: number;
+}
+export interface StripeInvoiceSummary {
+    id: string;
+    number: string | null;
+    status: string | null;
+    amountDue: number;
+    currency: string;
+    created: number;
+    hostedInvoiceUrl: string | null;
+    invoicePdf: string | null;
+}

package/dist/services/billing/verify-session.service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * verify-session — resolve a Stripe Checkout Session by ID and apply state.
+ *
+ * Industry-standard fulfillment pattern: client returns from Stripe with the
+ * checkout session ID in the URL, posts it here, we look it up authoritatively
+ * on Stripe and apply any state that the async webhook hasn't yet. Idempotent
+ * with the webhook handler — if the webhook already ran, this is a no-op read.
+ */
+export type CheckoutKind = "boost" | "listing_upgrade" | "unknown";
+export interface VerifySessionResult {
+    /** "complete" when checkout finished + state applied; "pending" when payment is still processing; "expired" otherwise */
+    status: "complete" | "pending" | "expired";
+    kind: CheckoutKind;
+    /** True only if this verification is allowed to be acted on by the caller (matches the requesting user) */
+    ownedByUser: boolean;
+}
+export declare function verifyCheckoutSession(sessionId: string, userId: string): Promise<VerifySessionResult>;

package/dist/services/billing/webhook.service.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Webhook Service — Handles Stripe webhook events for invoice lifecycle.
+ */
+import type Stripe from "stripe";
+/**
+ * Dispatch a Stripe webhook event to the appropriate handler.
+ */
+export declare function handleStripeWebhookEvent(event: Stripe.Event): Promise<void>;

package/dist/services/bostadsmerit/calculator.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Bostadsmerit Core Calculation — Pure Functions (No DB)
+ *
+ * SCORING SYSTEM (3 categories, 80p max):
+ *
+ * 1. DOKUMENT (30p max)
+ *    - credit_report: 5p uploaded + 5p verified = 10p
+ *    - criminal_record_extract: 5p uploaded + 5p verified = 10p
+ *    - income_doc: 5p uploaded + 5p verified = 10p
+ *
+ * 2. BOENDEHISTORIK (30p max capped)
+ *    - Import from Folkbokföringen: 5p
+ *    - Landlord signatures: 10p each (max 3 = 30p)
+ *
+ * 3. PROFIL (20p max)
+ *    - ID verification (BankID): 10p
+ *    - Profile picture: 5p
+ *    - Description: 3p
+ *    - Title: 2p
+ */
+export interface BostadsmeritInput {
+    /** Whether profile has folkbokforingRaw populated */
+    hasImportedFolkbokforing: boolean;
+    /** Whether user is ID-verified (BankID auth or approved id_doc) */
+    isIdVerified: boolean;
+    /** Whether profile has a profile picture */
+    hasProfilePicture: boolean;
+    /** Whether profile has a title set */
+    hasTitle: boolean;
+    /** Whether profile has a description set */
+    hasDescription: boolean;
+    /** Documents from bofrid_documents table */
+    documents: Array<{
+        category: string;
+        status: string | null;
+    }>;
+    /** Active housing references from bofrid_user_references table */
+    references: Array<{
+        type: string;
+        signerId: string | null;
+    }>;
+}
+export interface BostadsmeritResult {
+    total: number;
+    breakdown: {
+        housing: number;
+        documents: number;
+        profile: number;
+    };
+}
+export declare function calculateBostadsmerit(input: BostadsmeritInput): BostadsmeritResult;

package/dist/services/bostadsmerit/couple-calculator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Consolidated Couple/Group BostadsMerit Score
+ *
+ * Formula: floor(0.6 × average(scores) + 0.4 × min(scores))
+ *
+ * - Average reflects overall group quality
+ * - Minimum prevents one strong member from masking a weak one
+ * - 60/40 weighting rewards balanced couples, penalizes "carried" members
+ *
+ * Examples (couple):
+ *   Both strong: (72, 68) → floor(0.6×70 + 0.4×68) = floor(42 + 27.2) = 69
+ *   One weak:    (75, 30) → floor(0.6×52.5 + 0.4×30) = floor(31.5 + 12) = 43
+ *   Both weak:   (35, 40) → floor(0.6×37.5 + 0.4×35) = floor(22.5 + 14) = 36
+ */
+export interface ConsolidatedScoreResult {
+    /** Consolidated group score (0–80). */
+    consolidatedScore: number;
+    /** Each member's individual score. */
+    memberScores: Array<{
+        userId: string;
+        score: number;
+        breakdown: {
+            housing: number;
+            documents: number;
+            profile: number;
+        } | null;
+    }>;
+    /** ID of the member with the lowest score ("weakest link"). */
+    weakestMemberId: string | null;
+    /** Whether all members are BankID-verified. */
+    allBankIdVerified: boolean;
+}
+/**
+ * Calculate consolidated couple/group bostadsmerit from individual scores.
+ * Returns null if no scores are provided (empty group).
+ */
+export declare function calculateConsolidatedBostadsmerit(members: Array<{
+    userId: string;
+    bostadsmeritScore: number;
+    bostadsmeritBreakdown: {
+        housing: number;
+        documents: number;
+        profile: number;
+    } | null;
+    isBankIdVerified: boolean;
+}>): ConsolidatedScoreResult | null;

package/dist/services/bostadsmerit/tracker.service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Bostadsmerit Score Tracker Service
+ *
+ * Internal service (not a route) — called by other API handlers after mutations.
+ * Calculates score from DB data and persists the result on the profile.
+ */
+import { type BostadsmeritResult } from "./calculator";
+export type TrackingReason = "reference_signed" | "housing_imported" | "document_uploaded" | "document_verified" | "profile_updated";
+export interface ScoreChangeResult {
+    oldScore: number;
+    newScore: number;
+    difference: number;
+    action: string;
+    breakdown?: BostadsmeritResult["breakdown"];
+}
+/**
+ * Recalculate and persist the bostadsmerit score for a user.
+ * Returns the full result with breakdown.
+ */
+export declare function recalculateScore(profileId: string): Promise<BostadsmeritResult>;
+/**
+ * Get current cached score from the profile (no recalculation).
+ */
+export declare function getCachedScore(profileId: string): Promise<{
+    score: number;
+    breakdown: unknown;
+    updatedAt: Date | null;
+}>;
+/**
+ * Bulk recalculate scores for ALL profiles.
+ * Processes sequentially to avoid overwhelming the DB.
+ * NOTE: Will timeout on Vercel (60s limit) with large user counts.
+ * For formula changes, prefer setting bostadsmerit_updated_at = NULL
+ * so scores recalculate lazily on next GET /bostadsmerit/score.
+ */
+export declare function recalculateAllScores(): Promise<{
+    total: number;
+    updated: number;
+    errors: number;
+}>;
+/**
+ * Track a score change after a mutation. Recalculates and returns the delta.
+ * Fire-and-forget safe — catches all errors internally.
+ */
+export declare function trackBostadsmeritChange(profileId: string, action: TrackingReason): Promise<ScoreChangeResult>;