/**
 * This Source Code is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
 *
 * Copyright (c) Infonomic Company Limited
 */

/**
 * `AdminUsersRepository` — the DB-adapter-facing contract for the
 * `byline_admin_users` table.
 *
 * The interface deliberately takes **pre-hashed** password strings
 * (`password_hash`) rather than plaintext. Argon2 / bcrypt hashing is a
 * service-layer concern that depends on `@byline/admin/auth` primitives;
 * keeping it out of the repository means the adapter stays unaware of
 * password policy and the hashing library of the day.
 *
 * **Optimistic concurrency.** Content-shaped writes (`update`,
 * `setPasswordHash`, `delete`) take an `expectedVid` and bump the stored
 * `vid` on success. If the stored `vid` does not match `expectedVid` the
 * adapter throws `AdminUsersError(VERSION_CONFLICT)`, signalling a stale
 * client. Admin-intent writes that do not depend on current state
 * (`setEnabled`, login counters) are vid-less — last-writer-wins is the
 * right semantic for those.
 *
 * Adapters (e.g. `@byline/db-postgres`) implement this interface; admin
 * services (`seed-super-admin`, admin-user commands) consume it. No
 * caller should ever construct `AdminUsersRepository` instances directly
 * outside the adapter — use the `AdminStore` bundle passed at
 * `initBylineCore()` time.
 */

/**
 * Public-facing admin-user row — the `password_hash` column is
 * deliberately omitted. Only `getByEmailForSignIn` returns the hash, and
 * only so the session provider can verify it.
 */
export interface AdminUserRow {
  id: string
  vid: number
  given_name: string | null
  family_name: string | null
  username: string | null
  email: string
  remember_me: boolean
  last_login: Date | null
  last_login_ip: string | null
  failed_login_attempts: number
  is_super_admin: boolean
  is_enabled: boolean
  is_email_verified: boolean
  /**
   * Admin interface locale preference. `null` means "use the detection
   * cascade" (cookie → Accept-Language → defaultLocale). Stored as a
   * BCP 47 code; validated at the command layer against the host's
   * `i18n.admin.locales`.
   */
  preferred_locale: string | null
  created_at: Date
  updated_at: Date
}

/**
 * Admin-user row including the PHC password hash. Returned only by
 * `getByEmailForSignIn` — callers must treat it with care (never log,
 * never return to clients).
 */
export interface AdminUserWithPasswordRow extends AdminUserRow {
  password_hash: string
  /** Native session generation, independent of edit revisions. */
  session_version: number
}

export interface CreateAdminUserInput {
  email: string
  /** Pre-hashed PHC string. Service layer hashes plaintext before calling. */
  password_hash: string
  given_name?: string | null
  family_name?: string | null
  username?: string | null
  is_super_admin?: boolean
  is_enabled?: boolean
  is_email_verified?: boolean
  /** Initial locale preference. `null` defers to the detection cascade. */
  preferred_locale?: string | null
}

export interface UpdateAdminUserInput {
  given_name?: string | null
  family_name?: string | null
  username?: string | null
  email?: string
  is_super_admin?: boolean
  is_enabled?: boolean
  is_email_verified?: boolean
  remember_me?: boolean
  /** Pass `null` to clear and fall back to the detection cascade. */
  preferred_locale?: string | null
}

export type AdminUserListOrder =
  | 'given_name'
  | 'family_name'
  | 'email'
  | 'username'
  | 'created_at'
  | 'updated_at'

export interface ListAdminUsersOptions {
  /** 1-based page number. */
  page: number
  /** Page size. Reasonable ceiling applied at the command layer. */
  pageSize: number
  /** Free-text search across email, given_name, family_name, username. */
  query?: string
  /** Column to sort by. */
  order: AdminUserListOrder
  /** True for DESC, false for ASC. */
  desc: boolean
}

export interface CountAdminUsersOptions {
  /** Free-text search — same semantics as `list`. */
  query?: string
}

export interface AdminUsersRepository {
  create(input: CreateAdminUserInput): Promise<AdminUserRow>
  getById(id: string): Promise<AdminUserRow | null>
  /**
   * Bulk lookup for audit actor-label resolution (the `actors`
   * map on admin document reads — see docs/07-auth-and-security/02-auditability.md, Workstream 1). Ids
   * with no matching row are simply absent from the result; callers
   * render a tombstone label for them.
   */
  getByIds(ids: string[]): Promise<AdminUserRow[]>
  getByEmail(email: string): Promise<AdminUserRow | null>
  getByUsername(username: string): Promise<AdminUserRow | null>
  /**
   * Sign-in-only lookup. Returns the PHC hash alongside the public row so
   * the session provider can verify. Callers **must not** persist or echo
   * the `password_hash` field.
   */
  getByEmailForSignIn(email: string): Promise<AdminUserWithPasswordRow | null>
  /**
   * Authenticated-verification lookup. Same shape as
   * `getByEmailForSignIn` but keyed by id — used by the self-service
   * change-password flow, where the actor is already authenticated and
   * we need to verify the *current* password before swapping in a new
   * one. Same handling rules apply: callers **must not** persist or
   * echo the `password_hash` field.
   */
  getByIdForSignIn(id: string): Promise<AdminUserWithPasswordRow | null>
  /** Paginated, filtered, sorted list. */
  list(options: ListAdminUsersOptions): Promise<AdminUserRow[]>
  /** Total row count matching the same filter (for pager `total_pages`). */
  count(options?: CountAdminUsersOptions): Promise<number>
  /**
   * Content update with optimistic concurrency. Throws
   * `AdminUsersError(VERSION_CONFLICT)` if the stored `vid` differs from
   * `expectedVid`. Bumps `vid` on success and returns the fresh row.
   * A false `is_enabled` patch must atomically advance the native session
   * generation and revoke refresh sessions, under the account row lock.
   */
  update(id: string, expectedVid: number, patch: UpdateAdminUserInput): Promise<AdminUserRow>
  /**
   * Replace the stored password hash with optimistic concurrency.
   * Version-gated on `expectedVid`. Caller supplies a pre-hashed PHC string.
   * Atomically advance the native session generation and revoke every refresh
   * session in the same transaction. Lock the account before refresh rows.
   * Returns the updated row so callers holding the edit form can refresh
   * their cached `vid` without a second round-trip.
   */
  setPasswordHash(id: string, expectedVid: number, passwordHash: string): Promise<AdminUserRow>
  /**
   * Toggle enabled state. Disable must atomically advance the native session
   * generation and revoke refresh sessions. Enable never resets the generation.
   */
  setEnabled(id: string, enabled: boolean): Promise<void>
  /**
   * Set the admin interface locale preference. Vid-less — user preference
   * is independent of content state. Pass `null` to clear and fall back
   * to the detection cascade (cookie → Accept-Language → defaultLocale).
   */
  setPreferredLocale(id: string, locale: string | null): Promise<void>
  recordLoginSuccess(id: string, ip: string | null): Promise<void>
  recordLoginFailure(id: string): Promise<void>
  /**
   * Delete with optimistic concurrency. Version-gated on `expectedVid` to
   * prevent races against a concurrent update.
   */
  delete(id: string, expectedVid: number): Promise<void>
}