/**
 * Axis-C host-injected store for module code that needs host-owned data.
 * Host implements against its own schema; module code never imports host pgTable stubs.
 *
 * Scope is MODULE-WIDE (spec §3A Wave-4 extension), not `/fraud`-only: attribution
 * (`isSelfReferral`, `bindReferralOnSignup`) also consumes it for host-resident lookups
 * (`users.phone_index`, `referral_settings.fraud_config`).
 */
import type { AdapterConfig } from './types.js'

export interface UserIdentityRingFields {
  phoneIndex: string | null | undefined
  emailCanonicalIndex: string | null | undefined
}

/** isSelfReferral: one user's phone blind-index, keyed by userId (batched fetch). */
export interface PhoneBlindIndexRow {
  userId: string
  phoneBlindIndex: string | null
}

export interface LinkConversionStats {
  clicks: number
  conversions: number
}

export interface FraudHostStore {
  /** email-canonical: existing account with this canonical email index. */
  findExistingUserIdByEmailCanonical(canonical: string): Promise<string | undefined>

  /** payment-instrument: card fingerprints on file for the referrer. */
  listReferrerCardFingerprints(referrerUserId: string): Promise<Array<string | null | undefined>>

  /** EARN ctx: primary card fingerprint for a user (host payment_methods, LIMIT 1). */
  getUserCardFingerprint(userId: string): Promise<string | null | undefined>

  /** payment-instrument: distinct referrers whose referees share this card fingerprint. */
  countDistinctReferrersForRefereeCardFingerprint(
    cardFingerprint: string,
    excludeRefereeUserId: string,
  ): Promise<number>

  /** velocity-conversion: purchase creation timestamp for time-to-convert check. */
  getPurchaseCreatedAt(purchaseId: string): Promise<Date | null | undefined>

  /** identity-ring: phone + canonical email indexes for a user. */
  getUserIdentityRingFields(userId: string): Promise<UserIdentityRingFields | null>

  /** phone-required-earn: verified phone index for a user. */
  getUserPhoneIndex(userId: string): Promise<string | null | undefined>

  /** email-catchall-domain: signups with canonical email index matching domain within rolling window. */
  countSignupsByEmailDomainInWindow(domain: string, windowHours: number): Promise<number>

  /** velocity-conversion: settled trailing-window click/signup rollup for referrer's links. */
  getLinkConversionStats(
    referrerUserId: string,
    windowDays: number,
  ): Promise<LinkConversionStats>

  /**
   * isSelfReferral: phone blind-indexes for the given users (host owns `users`).
   * Batched — a single `WHERE id IN (…)`. The COMPARISON
   * (index equality) stays in the module; only the FETCH is host-coupled.
   */
  getPhoneBlindIndexes(userIds: string[]): Promise<PhoneBlindIndexRow[]>

  /**
   * bindReferralOnSignup: the host's referral fraud config (`referral_settings.fraud_config`).
   * `referral_settings` is host-resident (not affiliate-owned schema). Returns null when the
   * settings row is absent — the module decides to fail loud (ReferralSettingsNotFoundError).
   */
  getFraudConfig(): Promise<Record<string, AdapterConfig> | null>
}