Global Sanctions Screening API

// Package v1 defines the public REST API contract for Noble.
// This file is the source of truth for the v1 API.
// Update this file first, then implement handlers in server.go.
//
// # API versioning
//
// The wire API has two version axes. The major axis is the URL path (/v1) —
// reserved for a wholesale redesign and changed almost never. The minor axis is
// the dated Noble-Version request header (see version.go), which is how routine
// breaking changes to response shapes are managed:
//
//   - Clients pin a version: `Noble-Version: 2026-06-01` (a release date, not a
//     SemVer — SemVer is for the installable noble CLI/SDK artifacts, not the
//     wire). Version dates are the breaking-change dates from the changelog
//     (GET /v1/changelog); additive changelog entries do not mint a version.
//     The resolved version is echoed in the response header and recorded in the
//     audit trail.
//   - No header pins to the latest version, so existing callers keep working.
//     An unrecognized version is rejected: 400 invalid_version.
//   - Backward-compatibility policy: additive changes (new response fields, new
//     endpoints, new optional request fields) do NOT bump the version. Only a
//     change that alters or removes existing response shape mints a new dated
//     version; clients pinned to an older date continue to receive the old
//     shape via a response transform applied at that point.
//
// Today exactly one version exists (VersionLatest), so no transform layer is
// built yet — the header, validation, and contract are in place so the first
// breaking change has a home.
package v1

import (
	"encoding/json"
	"errors"
	"fmt"
	"strings"
	"time"
)

// =============================================================================
// POST /v1/screen - Screen a name against sanctions lists
// =============================================================================

// ScreenRequest is the input for screening a name against sanctions lists.
type ScreenRequest struct {
	// Name to screen against sanctions lists. Required unless at least one
	// identifier (IDNumber or IDs) is supplied — an identifier-only request
	// (e.g. a digital-currency wallet address) is screened by exact ID match
	// with no name. A name that is itself an identifier (a pasted wallet
	// address) is additionally exact-matched, so it is caught even when not
	// labelled as an id. Whitespace is trimmed; a whitespace-only name is
	// rejected. When neither a name nor an identifier is present the request
	// is rejected with code query_required.
	Name string `json:"name"`

	// Maximum number of matches to return (default: 10, max: 100)
	Limit *int `json:"limit,omitempty"`

	// DeepScreen enables real-time AI expansion of the search input.
	// When true, the server calls Gemini to generate spelling/cultural
	// variations of the input name and screens each one. Adds ~1-3s latency.
	DeepScreen bool `json:"deep_screen,omitempty"`

	// EntityType of the subject being screened: "individual", "entity", "vessel", "aircraft".
	// When provided, matches against a different entity type are flagged with a dismissal reason.
	EntityType string `json:"entity_type,omitempty"`

	// DateOfBirth of the person being screened, in YYYY-MM-DD format.
	// When provided, matches are penalized if the OFAC entity's DOB
	// differs significantly.
	DateOfBirth string `json:"date_of_birth,omitempty"`

	// Country of residence (ISO 3166-1 alpha-2, e.g., "US", "RU", "CN").
	// When provided, matches are penalized if the OFAC entity's nationality
	// does not match.
	Country string `json:"country,omitempty"`

	// Address of the subject being screened (street, city, postal code).
	// When provided, surfaced alongside the SDN's address data for manual comparison.
	Address string `json:"address,omitempty"`

	// IDNumber is any identifier published on a sanctions list: a government ID
	// (passport, tax ID, cedula, national ID), a financial routing code
	// (SWIFT/BIC), a corporate registration number, a digital currency (crypto
	// wallet) address, or a vessel IMO number. When provided, actively matched
	// against the ID tables of every list in scope (OFAC, UK, EU, France,
	// Belgium, UN, Canada, Australia) using exact match after normalization —
	// both the input and the stored value are uppercased with spaces, dashes,
	// dots, and slashes stripped, so formatting differences never cause a miss.
	// A vessel IMO number matches whether written "IMO 9102198" (OFAC's
	// published form) or as the bare number "9102198".
	IDNumber string `json:"id_number,omitempty"`

	// IDType filters ID matching to a single sanctions-list ID category.
	// Optional; when omitted, the IDNumber is searched against every type.
	//
	// Common values (use the exact string as published by the source list):
	//
	//   Government IDs:
	//     "Passport", "National ID", "Tax ID", "Cedula No.", "Driver's License",
	//     "Birth Certificate Number"
	//
	//   Financial routing:
	//     "SWIFT/BIC"            — bank/financial institution identifier
	//
	//   Corporate:
	//     "Business Registration Number", "Certificate of Incorporation Number"
	//
	//   Digital currency (OFAC SDN):
	//     "Digital Currency Address - XBT"    (Bitcoin)
	//     "Digital Currency Address - ETH"    (Ethereum)
	//     "Digital Currency Address - USDT"   (Tether)
	//     "Digital Currency Address - USDC"   (USD Coin)
	//     "Digital Currency Address - XMR"    (Monero)
	//     "Digital Currency Address - SOL"    (Solana)
	//     "Digital Currency Address - TRX"    (Tron)
	//     "Digital Currency Address - XRP"    (Ripple)
	//     "Digital Currency Address - LTC"    (Litecoin)
	//     "Digital Currency Address - BCH"    (Bitcoin Cash)
	//     plus ARB, BSC, BSV, BTG, DASH, ETC, XVG, ZEC.
	//
	// The full list of in-use idType strings is the union of every <idType>
	// element across the publishers' source files (e.g., OFAC's sdn.xml and
	// consolidated.xml).
	IDType string `json:"id_type,omitempty"`

	// IDs is an additional set of identifiers to screen alongside IDNumber.
	// A single person or entity often carries several — passport plus tax ID
	// plus a crypto wallet plus a SWIFT/BIC. Submitting them in one request
	// avoids one round-trip per identifier and produces a single merged
	// response with one audit row.
	//
	// Each entry is screened independently. The result set is the union of
	// every ID's hits, deduplicated by sanctions-list UID; on hit, the
	// corresponding ScreenMatch.MatchedVia field names which submitted
	// IDs triggered the match.
	//
	// IDNumber/IDType (singular) and IDs (plural) compose — if both are
	// present, the singular is screened in addition to every entry in IDs.
	// Capped at MaxIDsPerRequest entries; entries with an empty Number are
	// rejected with code "invalid_parameter".
	IDs []IDInput `json:"ids,omitempty"`

	// Lists restricts screening to the specified sanctions lists.
	// Valid values: "ofac", "uk", "eu", "france", "belgium", "netherlands", "un", "canada", "australia".
	// When omitted or empty, all lists are screened (default behavior).
	Lists []string `json:"lists,omitempty"`

	// Include opts into response fields that are excluded by default.
	// Reserved for future per-field opt-ins. Unknown values are ignored —
	// additive evolution without breaking clients. The value "summary" is
	// accepted for backwards compatibility but is now a no-op: ScreenSummary
	// is populated by default on every response.
	Include []string `json:"include,omitempty"`

	// DeepSummary, when true, generates the summary text with an LLM (Gemini)
	// instead of the deterministic template. The verdict bucket itself
	// remains deterministic — the LLM only writes prose. Requires Standard
	// tier or higher. Adds ~1s latency.
	DeepSummary bool `json:"deep_summary,omitempty"`

	// AsOf runs the screening against the sanctions lists as they stood at a
	// historical instant — point-in-time screening for audit and examination
	// support ("what would this name have returned on date X?"). Accepts an
	// RFC 3339 timestamp ("2026-07-01T15:04:05Z") for an exact instant, or a
	// bare date ("2026-07-01"), which means end of that day UTC — "the list
	// as it stood on July 1" includes July 1's updates. Today's date is
	// accepted and resolves to the current instant. Anything later is a 400
	// invalid_parameter: as_of must not be in the future.
	//
	// An as-of screening is an inquiry into historical list state, not a
	// present-day compliance decision: it is persisted to the audit trail
	// (with as_of recorded in the stored request) but never creates an alert,
	// never enrolls the name in portfolio monitoring, and never dispatches a
	// webhook. The response's ListVersions reports the snapshots that were
	// active at the requested instant, and ScreenedAsOf echoes the resolved
	// instant. A list with no data imported by the as-of instant is omitted
	// from ListsScreened/ListVersions, exactly as a not-yet-ingested list is
	// today.
	//
	// Known fidelity boundary: OFAC's secondary tables (aliases, addresses,
	// identifiers, DOB/POB) are maintained at current state only, so the
	// OFAC-pathway alias/ID matching and match detail reflect today's child
	// records even under as_of; OFAC primary names and all other lists'
	// records (including their aliases and identifiers) are fully historical.
	// The authoritative historical record of OFAC child data is the changelog
	// (GET /v1/changelog) and the archived list snapshots.
	AsOf string `json:"as_of,omitempty"`
}

// IDInput is a single identifier in ScreenRequest.IDs. Type is optional and
// follows the same string-set documented on ScreenRequest.IDType (Passport,
// SWIFT/BIC, "Digital Currency Address - XBT", etc.). When Type is empty,
// the Number is matched against every ID type the publisher recorded.
type IDInput struct {
	// Number is the identifier to screen for (e.g., passport number, SWIFT/BIC,
	// crypto wallet address). Required. Same normalization as IDNumber:
	// uppercased with spaces, dashes, dots, and slashes stripped before
	// comparison.
	Number string `json:"number"`

	// Type restricts matching to a single sanctions-list ID category.
	// Optional; when omitted, Number is searched against every type.
	Type string `json:"type,omitempty"`
}

// ScreenResponse is the response from a screening request.
type ScreenResponse struct {
	// TraceID is the audit key this screening is persisted under. It echoes the
	// caller's X-Trace-ID, or a server-generated value when none was supplied —
	// the screening is always retrievable. Feed it straight into
	// GET /v1/export?trace_id= to pull the full audit record. Also returned in
	// the X-Trace-ID response header.
	TraceID string `json:"trace_id"`

	// RequestID is the per-call HTTP request ID for this screening — the same
	// value carried in the X-Request-Id response header and in the request_id
	// field of error bodies. Distinct from TraceID: a trace can span many
	// calls, each with its own RequestID. Persisted alongside TraceID so an
	// operator can pivot between the two; see GET /v1/export?request_id=.
	RequestID string `json:"request_id,omitempty"`

	// Unique screening record ID for audit cross-referencing
	ScreeningID int64 `json:"screening_id,omitempty"`

	// Alert ID created for this screening, if the highest match score exceeded
	// the tenant's alert threshold. Zero/omitted means no alert was generated.
	// When a recent duplicate alert already exists, its ID is returned instead
	// of creating a new one (idempotent behavior).
	AlertID int64 `json:"alert_id,omitempty"`

	// OwnershipAlertID is the alert created because this screening's
	// ownership determination came back "blocked" (see Ownership). Distinct
	// from AlertID: a name-match alert and an ownership alert are separate
	// compliance events, and either can fire without the other. Ownership
	// alerts are not gated on the tenant's score threshold — a 50 Percent
	// Rule determination is categorical, not a fuzzy-match score. Dedup is
	// idempotent like AlertID.
	OwnershipAlertID int64 `json:"ownership_alert_id,omitempty"`

	// DeepScreenFallbackReason is populated only when the caller requested
	// deep_screen and the AI variation expansion could not run in full — the
	// response then falls short of the enhanced recall that was requested. A
	// paid feature never degrades silently (same honesty contract as
	// ScreenSummary.FallbackReason); value is one of the FallbackReason*
	// constants: llm_failure means the expansion did not run at all and the
	// results are standard recall; variation_screening_failure means the
	// expansion ran but covered only some generated variations — see
	// DeepScreenCoverage for the exact counts. A deployment with deep_screen
	// entirely unconfigured rejects the request with 503
	// deep_screen_unavailable instead — see CodeDeepScreenUnavailable.
	DeepScreenFallbackReason string `json:"deep_screen_fallback_reason,omitempty"`

	// DeepScreenCoverage reports how much of the requested AI variation
	// expansion actually ran. Present whenever deep_screen was requested and
	// the variation generation succeeded (including when zero variations were
	// generated); nil when deep_screen was not requested or the generation
	// call itself failed (DeepScreenFallbackReason: llm_failure).
	//
	// Invariant: on a deep_screen=true response, either DeepScreenCoverage
	// shows VariationsScreened == VariationsGenerated or
	// DeepScreenFallbackReason is non-empty. Callers can rely on this to
	// detect partial enhanced-recall delivery without parsing logs.
	DeepScreenCoverage *DeepScreenCoverage `json:"deep_screen_coverage,omitempty"`

	// The name that was screened
	ScreenedName string `json:"screened_name"`

	// When this screening was performed (RFC 3339)
	ScreenedAt string `json:"screened_at"`

	// ScreenedAsOf is the historical instant this screening was evaluated
	// against (RFC 3339), present only when the request carried as_of. The
	// matches and list_versions then reflect the sanctions lists as they
	// stood at this instant, not at ScreenedAt.
	ScreenedAsOf string `json:"screened_as_of,omitempty"`

	// Number of matches returned
	MatchCount int `json:"match_count"`

	// Mean score across all matches in this screening (0-100).
	// Useful for portfolio risk assessment. Zero when no matches.
	AverageScore float64 `json:"average_score"`

	// ListsScreened reports which sanctions lists were included in this screening.
	// Always populated, even when the caller did not specify a lists filter.
	ListsScreened []string `json:"lists_screened"`

	// Matched sanctions entries, ranked by score
	Matches []ScreenMatch `json:"matches"`

	// ListVersions reports the publisher snapshot active at screening time
	// for every list named in ListsScreened — one entry per list with
	// imported data. Examiners use this to pin a screening decision to the
	// exact list snapshots that produced it.
	ListVersions []ListVersion `json:"list_versions,omitempty"`

	// OFACListVersion is the OFAC entry from ListVersions, retained as a
	// convenience field.
	//
	// Deprecated: use ListVersions for full multi-list coverage. New
	// integrations should read ListVersions and filter for List == "ofac".
	// Removal scheduled after the 90-day deprecation window.
	OFACListVersion *OFACListInfo `json:"ofac_list_version,omitempty"`

	// Summary is an executive synthesis of the screening result: verdict
	// bucket, top match, distinct lists, strong-match count, and a one-line
	// prose synthesis. Populated by default on every response — the
	// deterministic path is pure-function with no I/O cost. Callers that
	// want LLM-rewritten prose pass DeepSummary=true (paid tier).
	Summary *ScreenSummary `json:"summary,omitempty"`

	// JurisdictionRisk is present when the request's country field places the
	// subject in a jurisdiction under a comprehensive OFAC embargo — Cuba,
	// Iran, North Korea, or an embargoed region of Ukraine (Crimea,
	// Sevastopol, and the so-called DNR/LNR covered regions). This is nexus
	// detection, not list matching: it fires even when matches is empty,
	// because the request itself disclosed the embargo nexus. Absent for all
	// other countries and when no country was supplied. The jurisdiction set
	// tracks current OFAC programs: Syria was removed when its comprehensive
	// program was revoked effective July 1, 2025 (E.O. 14312).
	JurisdictionRisk *JurisdictionRisk `json:"jurisdiction_risk,omitempty"`

	// Ownership is the OFAC 50 Percent Rule determination for the screened
	// name: whether the ownership graph shows it to be 50%-or-more owned by
	// sanctioned parties, with the full evidence chains (see OwnershipMatch).
	// This is how a company that appears on no sanctions list — but is owned
	// by listed parties — surfaces in a screening. Present whenever a name
	// was screened live on a deployment with ownership screening enabled;
	// absent on identifier-only requests and as_of screenings. Advisory
	// plus alerting: a "blocked" determination raises an alert (see
	// OwnershipAlertID) but never alters match scores or the summary verdict.
	Ownership *OwnershipMatch `json:"ownership,omitempty"`

	// Response metadata including legal disclaimer
	Meta ResponseMeta `json:"meta"`
}

// DeepScreenCoverage quantifies a deep_screen expansion: how many AI name
// variations were generated and how many of them were actually screened
// against the sanctions lists. VariationsScreened < VariationsGenerated means
// the enhanced recall is incomplete — the response also carries
// deep_screen_fallback_reason: variation_screening_failure so the shortfall
// is never silent. Equal counts confirm the full expansion was delivered.
type DeepScreenCoverage struct {
	// VariationsGenerated is the number of name variations the LLM produced
	// for this request.
	VariationsGenerated int `json:"variations_generated"`

	// VariationsScreened is the number of generated variations that were
	// screened against the sanctions lists.
	VariationsScreened int `json:"variations_screened"`
}

// JurisdictionRisk is an advisory signal that the screened subject's
// geographic input touches a comprehensive OFAC embargo. It is deliberately
// advisory — enhanced due diligence, never an auto-block: the licensing and
// exemption determination belongs to the institution's compliance program.
// It does not alter match scores or the summary verdict.
//
// Detection accepts ISO 3166-1 alpha-2 codes (the documented country
// format), ISO 3166-2 Ukrainian region codes ("UA-43" Crimea, "UA-40"
// Sevastopol, "UA-14" Donetsk, "UA-09" Luhansk), and common English
// jurisdiction names. Ukraine ("UA") and Russia ("RU") themselves never
// fire — only the embargoed regions do.
//
// Identical detection runs on /v1/screen and per-item on /v1/batch, and the
// signal is persisted in the screening's audit record.
type JurisdictionRisk struct {
	// Jurisdiction is the canonical identifier: ISO 3166-1 alpha-2 for
	// countries ("CU", "IR", "KP"), ISO 3166-2 for the Ukrainian
	// regions ("UA-43", "UA-40", "UA-14", "UA-09").
	Jurisdiction string `json:"jurisdiction"`

	// Name is the human-readable jurisdiction name.
	Name string `json:"name"`

	// Program is the OFAC sanctions program establishing the embargo.
	Program string `json:"program"`

	// Authority is the regulatory citation (e.g. "31 CFR Part 560").
	Authority string `json:"authority"`

	// Level is always "comprehensive_embargo" today (see
	// JurisdictionLevelComprehensiveEmbargo). An enum rather than a bool so
	// lesser program levels can be added without a contract break.
	Level string `json:"level"`

	// Guidance is fixed EDD advisory text explaining what the signal means
	// and that it does not block the subject.
	Guidance string `json:"guidance"`
}

// JurisdictionLevelComprehensiveEmbargo is the only JurisdictionRisk.Level
// value emitted today: the jurisdiction is under a comprehensive OFAC
// embargo (country program or embargoed region).
const JurisdictionLevelComprehensiveEmbargo = "comprehensive_embargo"

// OwnershipMatch reports what Noble's ownership graph knows about the
// screened name under OFAC's 50 Percent Rule: an entity owned 50% or more
// in the aggregate, directly or indirectly, by one or more blocked persons
// is itself blocked — even though it appears on no sanctions list (OFAC
// FAQs 398/401; "Entities Owned by Blocked Persons", August 13, 2014).
//
// The determination is precomputed from the ownership graph (sanctions-list
// ownership assertions corroborated by GLEIF corporate-relationship data)
// and looked up by name at screening time — it adds no meaningful latency
// and never alters match scores or the summary verdict.
//
// Present on every live /v1/screen response that screened a name, on
// deployments with ownership screening enabled. Absent on identifier-only
// requests and on as_of (point-in-time) screenings — the ownership graph
// reflects current data only, and attaching today's ownership to a
// historical inquiry would misstate the record.
type OwnershipMatch struct {
	// Status is the ownership determination for the screened name:
	//
	//   "blocked" — sanctioned parties hold >= 50% in the aggregate, from
	//               edges with explicit percentages. The entity is a blocked
	//               person under the 50 Percent Rule; treat it as an SDN hit.
	//   "review"  — an ownership or control relationship to a sanctioned
	//               party exists, but no source discloses a percentage
	//               (e.g. a GLEIF consolidation parent, or an OFAC
	//               "Linked To" designation pointer). The relationship is
	//               real; the stake is unknown. A compliance officer must
	//               investigate. Not a blocked state.
	//   "clean"   — the entity is in the ownership graph and was traversed;
	//               no sanctioned ownership was found.
	//   "unknown" — the name is not in the ownership graph. Absence of a
	//               finding is not a finding: the graph covers entities
	//               named by sanctions lists and GLEIF-registered
	//               relationships, not the universe of companies.
	Status string `json:"status"`

	// EntityName is the name the screened input resolved to in the
	// ownership graph: the entity's primary name when an ownership
	// determination exists, otherwise the indexed name that matched (in
	// normalized, lowercase form). Compare it against the screened input —
	// name resolution is fuzzy, and this field shows exactly which entity
	// the determination is about. Empty when Status is "unknown".
	EntityName string `json:"entity_name,omitempty"`

	// NameSimilarity is the trigram similarity (0-100) between the
	// normalized screened name and the graph name it resolved to. 100 is an
	// exact normalized match. Omitted when Status is "unknown".
	NameSimilarity float64 `json:"name_similarity,omitempty"`

	// CumulativePercent is the aggregate percentage of the entity held by
	// sanctioned parties, summed across all ownership chains with explicit
	// percentages. Populated only when Status is "blocked" (>= 50 by
	// definition). Review-status relationships carry no percentage.
	CumulativePercent float64 `json:"cumulative_percent,omitempty"`

	// BlockedByLists names the sanctions lists whose designated entities
	// appear in Chains (e.g. ["ofac", "uk"]).
	BlockedByLists []string `json:"blocked_by_lists,omitempty"`

	// Chains are the discrete ownership paths from the screened entity up
	// to its sanctioned owners — the examiner-grade evidence behind Status.
	// Ordered by first-hop stake, descending.
	Chains []OwnershipPath `json:"chains,omitempty"`

	// AsOf is the date (YYYY-MM-DD) of the ownership computation this
	// determination came from.
	AsOf string `json:"as_of,omitempty"`

	// SourcePublishIDs pins the snapshot of every data source that
	// contributed to the ownership computation (source name -> snapshot
	// identifier), so the determination is reproducible for audit.
	SourcePublishIDs map[string]string `json:"source_publish_ids,omitempty"`
}

// OwnershipPath is one ownership chain from the screened entity up to a
// sanctioned owner. Hops[0] is the direct owner of the screened entity;
// the last hop is the sanctioned party the chain terminates at.
type OwnershipPath struct {
	// Percent is the stake the chain's first hop holds in the screened
	// entity — this chain's contribution to the >= 50% aggregate. Per OFAC
	// FAQ 401, indirect ownership propagates only through links that are
	// themselves >= 50%, so a chain's contribution is its first-hop stake,
	// never a product of percentages along the path. Zero on review-status
	// chains (percentage undisclosed).
	Percent float64 `json:"percent"`

	// Hops are the ownership steps, ordered from the screened entity's
	// direct owner upward.
	Hops []OwnershipHop `json:"hops"`
}

// OwnershipHop is one ownership step: an owner, and its stake in the
// entity one step below it in the chain.
type OwnershipHop struct {
	// EntityKey is the owner's canonical key in the ownership graph
	// (e.g. "sdn:36419", "lei:5493001KJTIIGC8Y1R12").
	EntityKey string `json:"entity_key"`

	// EntityName is the owner's primary name.
	EntityName string `json:"entity_name"`

	// PercentOwned is this owner's stake in the entity one step below it.
	// Omitted when the source discloses no percentage.
	PercentOwned float64 `json:"percent_owned,omitempty"`

	// IsSanctioned reports whether this owner is itself designated on a
	// sanctions list.
	IsSanctioned bool `json:"is_sanctioned"`

	// SanctionedList names the designating list(s) when IsSanctioned,
	// comma-separated (e.g. "ofac", "ofac,uk").
	SanctionedList string `json:"sanctioned_list,omitempty"`

	// Source identifies the data source that asserted this ownership step:
	// "gleif" (GLEIF corporate-relationship data), "ofac_linked_to" (an
	// OFAC "(Linked To:)" designation pointer), or "list_text:<list>" (an
	// ownership statement extracted from that list's published narrative
	// text, retained verbatim in Noble's audit store).
	Source string `json:"source"`

	// Confidence grades the source assertion: "high" (explicit percentage
	// from an authoritative source), "medium" (GLEIF consolidation
	// relationship), or "low" (designation linkage without an ownership
	// assertion).
	Confidence string `json:"confidence"`
}

// OwnershipMatch.Status values.
const (
	OwnershipStatusBlocked = "blocked"
	OwnershipStatusReview  = "review"
	OwnershipStatusClean   = "clean"
	OwnershipStatusUnknown = "unknown"
)

// SummaryVerdict is a deterministic classification of screening results,
// computed from match scores. The verdict is reproducible from the structured
// response alone — it is never decided by an LLM.
type SummaryVerdict string

// Verdict buckets driven by the top match score.
const (
	VerdictConfirmedMatch     SummaryVerdict = "confirmed_match"      // top_score >= 95
	VerdictStrongMatch        SummaryVerdict = "strong_match"         // top_score >= 80
	VerdictPossibleMatch      SummaryVerdict = "possible_match"       // top_score >= 65
	VerdictWeakMatch          SummaryVerdict = "weak_match"           // top_score >= 50
	VerdictNoSignificantMatch SummaryVerdict = "no_significant_match" // < 50 or no matches
)

// Prohibition type constants classify the regulatory action an OFAC hit
// carries, per OFAC's BLOCK vs. REJECT vs. restricted-dealings framework
// (Introduction to OFAC, June 2026, pp. 7-8). Surfaced on ScreenMatch.ProhibitionType.
const (
	ProhibitionBlocking       = "blocking"        // SDN and 50%-Rule entities: freeze property, file a blocking report
	ProhibitionCMICInvestment = "cmic_investment" // NS-CMIC (E.O. 13959): securities investment ban; NOT blocked, 50% Rule does not apply
	ProhibitionSSISectoral    = "ssi_sectoral"    // SSI (E.O. 13662 Directives): restricted new debt/equity/services; NOT blocked
	ProhibitionFSEReject      = "fse_reject"      // FSE (E.O. 13608): reject the transaction
	ProhibitionPLCReject      = "plc_reject"      // NS-PLC: reject the transaction
	ProhibitionCAPTA          = "capta"           // CAPTA: correspondent/payable-through-account restriction
)

// ScreenSummary is an executive synthesis of a screening result. Populated
// on every screening response — the deterministic path is pure-function and
// emits a verdict bucket, top match, distinct lists, strong-match count, and
// a one-line prose synthesis at no I/O cost. Callers that want LLM-rewritten
// prose pass DeepSummary=true (paid tier).
//
// Verdict is always deterministic — even in LLM mode, the bucket is computed
// from scores and the LLM only rewrites the prose. This keeps the audit trail
// reproducible from structured data alone.
type ScreenSummary struct {
	// Verdict is a coarse classification of the screening result, computed
	// from the top match score (see Verdict* constants).
	Verdict SummaryVerdict `json:"verdict"`

	// Text is a one-line human-readable synthesis. Up to ~280 characters.
	Text string `json:"text"`

	// TopMatch identifies the single highest-scoring match. Absent (omitted from
	// JSON) when no matches were returned. Lets callers act on the winning hit
	// without reparsing the full Matches array.
	TopMatch *SummaryTopMatch `json:"top_match,omitempty"`

	// StrongMatches counts matches with score >= 80.
	StrongMatches int `json:"strong_matches"`

	// DistinctLists names the unique source labels present in matches
	// (e.g., ["OFAC SDN", "UK", "France"]).
	DistinctLists []string `json:"distinct_lists"`

	// GeneratedBy identifies how Text was produced:
	// "deterministic" or "llm:<model-id>" (e.g., "llm:gemini-flash-latest";
	// the id is the exact serving model when the API reports one).
	GeneratedBy string `json:"generated_by"`

	// ModelVersion is the exact model identifier when GeneratedBy starts with
	// "llm:" (empty for deterministic).
	ModelVersion string `json:"model_version,omitempty"`

	// FallbackReason is populated only when the caller requested
	// deep_summary=true but the LLM path did not execute and the response
	// fell back to deterministic prose. Empty when deep_summary was not
	// requested or when the LLM successfully produced the text. See the
	// FallbackReason* constants for the documented values. Surfacing this
	// prevents silent paid-feature non-delivery.
	//
	// Invariant: on a deep_summary=true response, either GeneratedBy starts
	// with "llm:" or FallbackReason is non-empty. Callers can rely on this
	// to detect silent paid-feature degradation without parsing prose.
	FallbackReason string `json:"fallback_reason,omitempty"`
}

// Fallback reason codes for ScreenSummary.FallbackReason and
// ScreenResponse.DeepScreenFallbackReason.
const (
	// FallbackReasonLLMUnavailable indicates the server is not configured to
	// call an LLM (e.g., GEMINI_API_KEY is unset). Operator action required.
	FallbackReasonLLMUnavailable = "llm_unavailable"

	// FallbackReasonLLMFailure indicates the LLM call returned an error
	// (network failure, timeout, rate limit, invalid response). The
	// deterministic summary is returned instead.
	FallbackReasonLLMFailure = "llm_failure"

	// FallbackReasonVariationScreeningFailure (deep_screen only) indicates
	// the LLM produced name variations but one or more of them could not be
	// screened against the sanctions lists. The response carries every match
	// that was found, but the enhanced recall is incomplete —
	// ScreenResponse.DeepScreenCoverage reports exactly how many variations
	// were screened out of how many were generated. Retry the request to
	// re-attempt full coverage.
	FallbackReasonVariationScreeningFailure = "variation_screening_failure"
)

// SummaryTopMatch identifies the single highest-scoring match within a
// screening result and carries OFAC FAQ 1591's 5-step validation set for that
// entity: name, date of birth, place of birth, nationality, ID, and address.
// Exposing these on the summary lets AI agents and compliance officers
// confirm or dismiss the top hit without a second round-trip into Matches.
//
// All fields refer to the same entity — drawn from whichever ScreenMatch in
// the response carries the maximum Score. SummaryTopMatch is a pointer field
// on ScreenSummary so it is omitted from JSON entirely when no matches were
// returned.
type SummaryTopMatch struct {
	// Score is the highest combined match score across all matches (0-100).
	Score float64 `json:"score"`

	// UID is the source-list record identifier of the top match
	// (e.g., the OFAC UID). This is the list pointer, not a government ID
	// — see IDs for passports, tax IDs, and cedulas.
	UID string `json:"uid,omitempty"`

	// Name is the rendered display name of the top match
	// ("Last, First" for individuals, otherwise the last/full-name field).
	Name string `json:"name,omitempty"`

	// Source is the sanctions list that produced the top match
	// (e.g., "OFAC SDN", "UK", "France").
	Source string `json:"source,omitempty"`

	// DateOfBirth from the sanctions list, in the publisher's original format
	// (commonly YYYY-MM-DD or a free-form string). Empty when not provided
	// by the source list.
	DateOfBirth string `json:"date_of_birth,omitempty"`

	// PlaceOfBirth from the sanctions list (free-form city/region/country).
	PlaceOfBirth string `json:"place_of_birth,omitempty"`

	// Nationalities lists every nationality the source has on file for the
	// entity. OFAC and other publishers sometimes record multiple — all are
	// retained verbatim.
	Nationalities []string `json:"nationalities,omitempty"`

	// IDs are government identifiers (passport, tax ID, national ID, cedula)
	// for the entity. Used in OFAC 5-step validation step 3 (ID match).
	IDs []MatchID `json:"ids,omitempty"`

	// Addresses associated with the entity on the sanctions list. Used in
	// OFAC 5-step validation step 5 (address match).
	Addresses []MatchAddress `json:"addresses,omitempty"`
}

// ScreenMatch represents a single matched sanctions entry.
// Includes all secondary identifiers from the source list so compliance officers
// can perform OFAC's 5-step validation (FAQ 1591) without a separate lookup.
type ScreenMatch struct {
	// UID is the unique identifier from the source list (e.g., OFAC UID).
	UID string `json:"uid"`

	// First name of the sanctioned entity (if individual)
	FirstName *string `json:"first_name,omitempty"`

	// Last name or full name of the sanctioned entity
	LastName *string `json:"last_name,omitempty"`

	// Type of entry: Individual, Entity, Vessel, Aircraft
	SdnType *string `json:"sdn_type,omitempty"`

	// Combined match score (0-100), higher is stronger match.
	// When secondary attributes (DOB, country) are provided in the request,
	// this score is adjusted downward for mismatches.
	Score float64 `json:"score"`

	// Additional remarks from the source list
	Remarks *string `json:"remarks,omitempty"`

	// Source of the match (e.g., "OFAC SDN", "OFAC CONS", "UK", "EU")
	Source string `json:"source,omitempty"`

	// Sanctions programs this entity is listed under (e.g., "SDGT", "IRAN", "UKRAINE-EO13662").
	// Essential for determining which regulations apply and which general licenses may be relevant.
	Programs []string `json:"programs,omitempty"`

	// ProhibitionType is the regulatory action this OFAC hit carries — which is
	// NOT the same for every designation, and drives whether a transaction is
	// blocked, rejected, or merely restricted. A full SDN listing (and a
	// 50%-Rule entity) is "blocking" — freeze the property and file a blocking
	// report. A CMIC listing (E.O. 13959) is a securities "cmic_investment" ban
	// with no blocking. An SSI listing (E.O. 13662) is "ssi_sectoral" restricted
	// dealings, not blocked. FSE and NS-PLC are reject actions; CAPTA restricts
	// correspondent/payable-through accounts. Derived from Programs. Populated
	// for OFAC matches only — the taxonomy is OFAC-specific; empty for other
	// lists, which follow their own action frameworks. One of the Prohibition*
	// constants.
	ProhibitionType string `json:"prohibition_type,omitempty"`

	// WeakAliasOnly is true when every pathway that produced this match fired
	// via a weak OFAC AKA — no primary name, strong alias, variation, ID, or
	// other list corroborates it. OFAC does not expect a weak-AKA-only hit to
	// be treated like a strong-name match (FAQ 122-124), so this is the
	// primary false-positive control: callers may deprioritize or auto-dismiss
	// these. Per-pathway detail is on MatchSource.AliasQuality. Absent (false)
	// when any corroborating pathway is present.
	WeakAliasOnly bool `json:"weak_alias_only,omitempty"`

	// Per-source scoring breakdown showing how and why this entity matched
	MatchSources []MatchSource `json:"match_sources"`

	// DismissalReasons explains why the score was adjusted downward.
	// Only present when secondary attributes (DOB, country, entity_type) were provided
	// and a mismatch was detected.
	//
	// Deprecated: free-text reasons cannot be filtered, aggregated, or
	// audit-mapped. Use DismissalSignals for the structured form. Both
	// fields are populated in parallel during a 90-day deprecation window
	// and are guaranteed to have equal length and ordered correspondence.
	DismissalReasons []string `json:"dismissal_reasons,omitempty"`

	// DismissalSignals is the structured form of DismissalReasons: stable
	// reason codes, severity tiers, the conflicting request/target values,
	// and the exact point reduction each signal applied to the score.
	//
	// Always emitted — empty array means "no penalties applied," never
	// "we forgot." See the Dismissal* constants for the stable code set.
	// Each signal's position in this array corresponds 1:1 with the
	// position of its free-text form in DismissalReasons.
	DismissalSignals []DismissalSignal `json:"dismissal_signals"`

	// MatchedVia names which submitted identifier(s) triggered this match,
	// when the hit came from ID-based screening (ScreenRequest.IDNumber or
	// any entry in ScreenRequest.IDs). Empty when the match came only from
	// name-based screening. A single match may carry multiple entries when
	// several submitted IDs all resolve to the same sanctioned entity.
	MatchedVia []IDInput `json:"matched_via,omitempty"`

	// Secondary identifiers from the sanctions list for OFAC 5-step validation.
	// These enable compliance officers to compare against transaction data.
	Addresses     []MatchAddress `json:"addresses,omitempty"`
	IDs           []MatchID      `json:"ids,omitempty"`
	DateOfBirth   string         `json:"date_of_birth,omitempty"`
	PlaceOfBirth  string         `json:"place_of_birth,omitempty"`
	Nationalities []string       `json:"nationalities,omitempty"`
	Citizenships  []string       `json:"citizenships,omitempty"`
}

// MatchAddress is an address associated with a sanctioned entity.
type MatchAddress struct {
	Address1        string `json:"address1,omitempty"`
	Address2        string `json:"address2,omitempty"`
	City            string `json:"city,omitempty"`
	StateOrProvince string `json:"state_or_province,omitempty"`
	PostalCode      string `json:"postal_code,omitempty"`
	Country         string `json:"country,omitempty"`
}

// MatchID is a government identifier (passport, tax ID, cedula) for a sanctioned entity.
type MatchID struct {
	IDType  string `json:"id_type"`
	Number  string `json:"number"`
	Country string `json:"country,omitempty"`
}

// MatchSource provides scoring details for a single match pathway.
// An entity may match via multiple sources (e.g., both direct SDN and AI variation).
type MatchSource struct {
	// How the match was found: "ofac_sdn", "ofac_aka", "ofac_ai_variation",
	// "ofac_id", "uk_designation", "uk_alias", "uk_id", "deep_screen",
	// or "internal_watchlist"
	Source string `json:"source"`

	// Raw trigram similarity score (0-100) for this source
	TrigramScore float64 `json:"trigram_score"`

	// Whether the last name matched phonetically via Soundex
	SoundexMatch bool `json:"soundex_match"`

	// The AI-generated variation that matched (only for source="ofac_ai_variation" or "deep_screen")
	Variation string `json:"variation,omitempty"`

	// Why Gemini generated this variation (only for source="ofac_ai_variation" or "deep_screen")
	Reason string `json:"reason,omitempty"`

	// MatchedText is the source-list string that produced this pathway's
	// trigram score — the actual primary name, alias, or variation text
	// the comparison fired against. Lets consumers distinguish "matched
	// primary name 'Vladimir Putin'" from "matched 4-character alias
	// 'JOHN'" and is the foundation for length- and quality-aware
	// reweighting (and the calibration corpus those depend on).
	MatchedText string `json:"matched_text,omitempty"`

	// MatchedLength is the rune count of MatchedText. Pre-computed so
	// aggregations like "fraction of dismissed alerts with matched_length
	// <= 5" can run server-side without scanning every match.
	MatchedLength int `json:"matched_length,omitempty"`

	// AliasQuality is OFAC's alias-strength classification — "weak" or
	// "strong" — when this pathway fired via an OFAC AKA (source "ofac_aka" or
	// "ofac_cons_aka"); empty for primary-name, variation, ID, and non-OFAC
	// pathways. OFAC flags weak AKAs because they are a dominant false-positive
	// source and does not expect a weak-AKA-only hit to be treated like a
	// strong-name match (FAQ 122-124). Use it to deprioritize or suppress hits
	// driven solely by a weak alias — see ScreenMatch.WeakAliasOnly.
	AliasQuality string `json:"alias_quality,omitempty"`
}

// =============================================================================
// Dismissal Signals
// =============================================================================
//
// Structured replacement for the legacy ScreenMatch.DismissalReasons []string
// field. Every penalty applied during attribute comparison emits a
// DismissalSignal carrying the canonical reason code, severity, conflicting
// request/target values, and the score impact.
//
// Reason codes are stable identifiers — consumers filter, aggregate, and
// audit-map on them. They are grounded in OFAC FAQ 5 ("How do I determine
// if I have a valid OFAC match?") where applicable: Step 2 (entity-type
// sanity), Step 3 (single-token name match), and Step 4 (full-entry
// comparison covering DOB, country, and the broader identity set).

// DismissalSignal is a structured reason a match's score was reduced.
type DismissalSignal struct {
	// Field that drove the signal: "date_of_birth", "country",
	// "entity_type", or "name".
	Field string `json:"field"`

	// ReasonCode is one of the Dismissal* constants below. Stable across
	// releases — clients depend on these strings.
	ReasonCode string `json:"reason_code"`

	// Severity is the strength tier of this signal. High signals are
	// safe-to-auto-dismiss; low signals are advisory.
	Severity DismissalSeverity `json:"severity"`

	// RequestValue is the value the request supplied, rendered as text.
	RequestValue string `json:"request_value,omitempty"`

	// TargetValue is the value the source list carries, rendered as text.
	TargetValue string `json:"target_value,omitempty"`

	// ImpactOnScore is the point reduction this signal applied to the
	// match score (negative, on the same 0-100 scale as Score).
	ImpactOnScore float64 `json:"impact_on_score"`
}

// DismissalSeverity is the strength tier of a DismissalSignal. Derived
// from penalty depth — locked in code, not data, so the mapping is
// reproducible from the response alone.
type DismissalSeverity string

const (
	SeverityLow    DismissalSeverity = "low"
	SeverityMedium DismissalSeverity = "medium"
	SeverityHigh   DismissalSeverity = "high"
)

// Dismissal reason codes. Stable identifiers — clients filter on these.
//
//   - DismissalEntityTypeMismatch and DismissalPartialNameMatchSingleToken
//     are OFAC FAQ 5 Steps 2 and 3 respectively (not-a-valid-match
//     conditions).
//   - The DOB and country codes are OFAC FAQ 5 Step 4 (full-entry
//     comparison). The "_far" suffix splits today's overloaded
//     dob_year_mismatch and dob_mismatch into distinct codes per
//     penalty depth.
const (
	DismissalEntityTypeMismatch          = "entity_type_mismatch"
	DismissalPartialNameMatchSingleToken = "partial_name_match_single_token"
	DismissalDOBYearNearMiss             = "dob_year_near_miss"
	DismissalDOBYearMismatch             = "dob_year_mismatch"
	DismissalDOBYearMismatchFar          = "dob_year_mismatch_far"
	DismissalDOBNearMiss                 = "dob_near_miss"
	DismissalDOBMismatch                 = "dob_mismatch"
	DismissalDOBMismatchFar              = "dob_mismatch_far"
	DismissalCountryMismatch             = "country_mismatch"
)

// =============================================================================
// Sanctions List Selection
// =============================================================================

// List constants for selective screening.
const (
	ListOFAC        = "ofac"
	ListUK          = "uk"
	ListEU          = "eu"
	ListFrance      = "france"
	ListBelgium     = "belgium"
	ListNetherlands = "netherlands"
	ListUN          = "un"
	ListCanada      = "canada"
	ListAustralia   = "australia"
)

// AllLists is the complete set of supported sanctions lists.
var AllLists = []string{ListOFAC, ListUK, ListEU, ListFrance, ListBelgium, ListNetherlands, ListUN, ListCanada, ListAustralia}

// validLists is the lookup set for O(1) validation.
var validLists = map[string]bool{
	ListOFAC: true, ListUK: true, ListEU: true,
	ListFrance: true, ListBelgium: true, ListNetherlands: true,
	ListUN: true, ListCanada: true, ListAustralia: true,
}

// ValidateListNames returns an error message for the first invalid list name, or "".
func ValidateListNames(lists []string) string {
	for _, l := range lists {
		if !validLists[l] {
			return fmt.Sprintf("unknown list %q; valid values: %s", l, strings.Join(AllLists, ", "))
		}
	}
	return ""
}

// DeduplicateLists removes duplicate list names, preserving order.
func DeduplicateLists(lists []string) []string {
	seen := make(map[string]bool, len(lists))
	out := make([]string, 0, len(lists))
	for _, l := range lists {
		if !seen[l] {
			seen[l] = true
			out = append(out, l)
		}
	}
	return out
}

// =============================================================================
// Common Types
// =============================================================================

// Error type categories for machine-readable error handling.
const (
	ErrTypeInvalidRequest  = "invalid_request_error"
	ErrTypeAuthentication  = "authentication_error"
	ErrTypeForbidden       = "forbidden_error"
	ErrTypeRateLimit       = "rate_limit_error"
	ErrTypeAPI             = "api_error"
	ErrTypeNotFound        = "not_found_error"
	ErrTypeConflict        = "conflict_error"
	ErrTypeComplianceRule  = "compliance_rule_error"
	ErrTypePaymentRequired = "payment_required"
)

// Error code constants for machine-readable error handling.
const (
	CodeInvalidBody              = "invalid_request_body"
	CodeNameRequired             = "name_required"
	CodeQueryRequired            = "query_required"
	CodeNameTooLong              = "name_too_long"
	CodeMissingParameter         = "missing_parameter"
	CodeInvalidParameter         = "invalid_parameter"
	CodeKeyRequired              = "api_key_required"
	CodeKeyInvalid               = "api_key_invalid"
	CodeTenantNotProvisioned     = "tenant_not_provisioned"
	CodeTierInsufficient         = "tier_insufficient"
	CodeRateLimitExceeded        = "rate_limit_exceeded"
	CodeBatchTooLarge            = "batch_too_large"
	CodeTooManyIDs               = "too_many_ids"
	CodeNotFound                 = "not_found"
	CodeInvalidTransition        = "invalid_status_transition"
	CodeInvalidReason            = "invalid_reason_code"
	CodeInvalidDisposition       = "invalid_disposition"
	CodeDispositionRequired      = "disposition_required"
	CodeGLCitationRequired       = "gl_citation_required"
	CodeFourEyesViolation        = "four_eyes_violation"
	CodeConcurrentModification   = "concurrent_modification"
	CodeInvalidAssignee          = "invalid_assignee"
	CodeNoteEmpty                = "note_empty"
	CodeNoteTooLong              = "note_too_long"
	CodeInternalError            = "internal_error"
	CodeKeyRevoked               = "encryption_key_revoked"
	CodeConfirmationRequired     = "confirmation_required"
	CodeMethodNotAllowed         = "method_not_allowed"
	CodeWebhookURLInvalid        = "webhook_url_invalid"
	CodeWebhookSecretTooShort    = "webhook_secret_too_short"
	CodeWebhookNotFound          = "webhook_not_found"
	CodeWebhookLimitExceeded     = "webhook_limit_exceeded"
	CodeWebhookSignatureInvalid  = "webhook_signature_invalid"
	CodeTrialExpired             = "trial_expired"
	CodeSignupClosed             = "signup_closed"
	CodeInviteRequired           = "invite_code_required"
	CodeInviteInvalid            = "invite_code_invalid"
	CodeInviteExpired            = "invite_code_expired"
	CodeInviteExhausted          = "invite_code_exhausted"
	CodeInviteRevoked            = "invite_code_revoked"
	CodeIdempotencyMismatch      = "idempotency_key_mismatch"
	CodeIdempotencyInProgress    = "idempotency_in_progress"
	CodeIdempotencyKeyTooLong    = "idempotency_key_too_long"
	CodeScopeRequired            = "scope_required"
	CodeScopeNoChange            = "scope_no_change"
	CodeReplayUnsupportedChannel = "replay_unsupported_channel"
	CodeInvalidVersion           = "invalid_version"
)

// Error is the standard error response following Stripe's error model.
type Error struct {
	// Error category: invalid_request_error, authentication_error, rate_limit_error, api_error
	Type string `json:"type"`

	// Machine-readable error code for programmatic handling
	Code string `json:"code"`

	// Human-readable error message
	Message string `json:"message"`

	// Which request parameter caused the error (if applicable)
	Param string `json:"param,omitempty"`

	// Server-generated request ID for debugging and audit correlation
	RequestID string `json:"request_id"`
}

// ResponseMeta contains metadata included in every API response.
type ResponseMeta struct {
	// Legal disclaimer bounding Noble Sight's liability
	Disclaimer string `json:"disclaimer"`
}

// Disclaimer is the standard legal disclaimer included in all screening API responses.
// This text is a material part of Noble Sight's liability boundary and must not be
// modified without legal review.
const Disclaimer = "Noble Sight provides sanctions screening results for informational purposes only. " +
	"This service is not a substitute for a comprehensive sanctions compliance program. " +
	"Noble Sight does not provide legal, regulatory, or compliance advice. " +
	"Screening results reflect data available at the time of the request and may not capture all " +
	"sanctions designations, aliases, or name variations. " +
	"Final screening decisions, risk assessments, and compliance obligations remain the sole " +
	"responsibility of the subscribing institution. " +
	"Use of this service does not satisfy or replace any obligation under OFAC regulations, " +
	"the Bank Secrecy Act, or any other applicable law."

// =============================================================================
// Pagination — the uniform contract for every collection endpoint
// =============================================================================
//
// Every list endpoint (alerts, portfolio, watchlist, audit export, case
// activity) returns the same envelope and paginates the same way. This section
// is the contract; handlers must not deviate.
//
// # Envelope
//
// A list response is always:
//
//	{ "data": [ ... ], "has_more": true, "meta": { "disclaimer": "..." } }
//
// `data` is the page of items (the array key is ALWAYS "data" — never "alerts",
// "entities", "records", etc.). `has_more` is true when at least one more item
// exists past this page. There is no other top-level shape.
//
// # Cursor pagination only — never offset
//
// Pagination is keyset (cursor) based:
//
//	GET /v1/portfolio?after=<id>&limit=<n>
//
//   - `after` — exclusive cursor: return items with id > after. Omit (or 0) for
//     the first page. The cursor is the `id` of the last item in the previous
//     page's `data`. Results are ordered by `id` ascending (chronological and
//     stable, since id is a monotonic BIGSERIAL). A descending/`before` cursor
//     may be ADDED later without breaking this contract.
//   - `limit` — page size; defaults to DefaultPageLimit, hard-capped at
//     MaxPageLimit. Values above the cap are clamped, not rejected.
//
// Offset/page pagination (`?offset=`, `?page=`) is PROHIBITED. It is O(n) at
// depth — the database scans and discards `offset` rows on every request — and
// it returns duplicate or skipped rows when items are inserted concurrently,
// which is unacceptable for an append-only audit system. The scale that forces
// this: a portfolio-monitoring customer (e.g. a top-tier bank) may enroll tens
// of millions of entities; offset page 500,000 would scan ~50M rows per call,
// while a keyset cursor stays O(log n + limit) at any depth.
//
// # No `total` in list responses — counts live in a /stats companion
//
// List responses do NOT carry a row count. COUNT(*) over a large, filtered, or
// date-ranged set adds latency and lock contention to every page fetch and is
// racy under concurrent writes. Counts are instead a first-class, cheap read on
// a dedicated companion endpoint, uniformly: a collection at `/v1/<name>`
// exposes its counts at `/v1/<name>/stats`. Every stats response carries at
// least a `total`; most add a small, cheap breakdown (by_status, by_score_band,
// by_action, …). A stats endpoint honors the SAME filters as its list sibling,
// so the count matches the page the caller is browsing.
//
//	/v1/alerts          → /v1/alerts/stats           (AlertStatsResponse)
//	/v1/portfolio       → /v1/portfolio/stats        (PortfolioStatsResponse)
//	/v1/webhooks        → /v1/webhooks/stats          (WebhookStatsResponse)
//	/v1/alerts/activity → /v1/alerts/activity/stats   (ActivityStatsResponse)
//
// # Full extraction is not pagination
//
// Paging through millions of rows via GET is for browsing/triage, not bulk
// extraction. A customer who needs their entire portfolio or audit history
// pulls it via the async export/batch job, which is built for volume.
//
// # Per-endpoint application
//
//	/v1/alerts          cursor + filters (already the reference implementation)
//	/v1/portfolio       cursor (requires a (tenant_id, id) index — see migrations)
//	/v1/watchlist       cursor
//	/v1/export/bulk     cursor + hard limit; large pulls use the export job
//	/v1/alerts/activity cursor + hard limit
//	/v1/webhooks        NO pagination — capped at a handful per tenant; returns
//	                    the {data} envelope with every webhook, no cursor params.

// List is the uniform envelope returned by every collection endpoint. The
// generic parameter is the item type (e.g. List[AlertResponse]). The "data"
// key and "has_more" flag are invariant across all list endpoints; meta is
// injected by the response writer.
type List[T any] struct {
	// Data is the page of items, ordered by id ascending.
	Data []T `json:"data"`
	// HasMore reports whether at least one item exists past this page. When
	// true, request the next page with ?after=<id of the last item in Data>.
	HasMore bool `json:"has_more"`
}

// Pagination bounds for list endpoints.
const (
	DefaultPageLimit = 50  // page size when ?limit is omitted
	MaxPageLimit     = 100 // hard cap; larger ?limit values are clamped to this
)

// PageParams is the parsed cursor-pagination query shared by list handlers.
// Produced by parsePageParams; never construct it from offset/page inputs.
type PageParams struct {
	// After is the exclusive id cursor: return items with id > After.
	// Zero means start from the beginning.
	After int64
	// Limit is the clamped page size, in [1, MaxPageLimit].
	Limit int
}

// =============================================================================
// Changelog
// =============================================================================
//
// GET /v1/changelog returns the API's release notes as structured JSON so that
// customers — banks, AI compliance agents, MCP clients — can surface "what's
// new" inside their own dashboards without scraping HTML. The endpoint is
// public (no API key required) so prospects and discovery tools can read it.
//
// The source of truth is a checked-in Go slice (api/v1/changelog.go); new
// entries ship with the binary version and are reviewed in PRs.

// Changelog categories. Follows the Keep-a-Changelog convention
// (https://keepachangelog.com).
const (
	ChangeAdded      = "added"
	ChangeChanged    = "changed"
	ChangeDeprecated = "deprecated"
	ChangeRemoved    = "removed"
	ChangeFixed      = "fixed"
	ChangeSecurity   = "security"
)

// ChangelogEntry is one published API change.
type ChangelogEntry struct {
	// Release date in YYYY-MM-DD (UTC).
	Date string `json:"date"`

	// One of ChangeAdded, ChangeChanged, ChangeDeprecated, ChangeRemoved,
	// ChangeFixed, ChangeSecurity.
	Category string `json:"category"`

	// Single-line headline. Required.
	Summary string `json:"summary"`

	// Optional longer body. Plain text; no HTML.
	Details string `json:"details,omitempty"`

	// Optional endpoint the change scopes to (e.g. "/v1/screen").
	Endpoint string `json:"endpoint,omitempty"`

	// Breaking marks this entry as an API version boundary: a change that
	// altered or removed existing response shape, minting a new dated
	// Noble-Version equal to Date. The set of supported API versions is derived
	// from exactly the Breaking entries (see version.go), so the changelog is
	// the single source of truth and the two cannot drift. Additive entries
	// leave this false and never mint a version.
	Breaking bool `json:"breaking,omitempty"`

	// Verification is a customer-runnable proof the change behaves as
	// described — Steps a caller executes against the live API with their own
	// key, an Expect assertion, and how to replay it for audit. Required on
	// every fix/feature/breaking entry dated on or after the verification
	// cutover (see changelog.go): a compliance vendor's changes must be
	// independently provable by the customer, not asserted. Optional (nil) on
	// historical entries that predate the policy.
	Verification *ChangelogVerification `json:"verification,omitempty"`
}

// ChangelogVerification is a self-contained, customer-runnable check that a
// changelog entry's change works as described. It carries no privileged steps:
// every command runs against the public API with the caller's own key.
type ChangelogVerification struct {
	// Steps are exact, copy-pasteable requests that exercise the change.
	Steps []string `json:"steps"`

	// Expect is the precise pass assertion (e.g. a field == value condition).
	Expect string `json:"expect"`

	// Audit is how to independently replay or prove the result after the fact
	// (trace id, export, list_versions). Optional.
	Audit string `json:"audit,omitempty"`

	// Regression links the test(s) that lock the change. Optional.
	Regression string `json:"regression,omitempty"`
}

// ChangelogResponse is returned by GET /v1/changelog.
type ChangelogResponse struct {
	// Entries are ordered newest first.
	Entries []ChangelogEntry `json:"entries"`
	Meta    ResponseMeta     `json:"meta"`
}

// =============================================================================
// Sanctions list versions
// =============================================================================
//
// GET /v1/lists returns the active publisher snapshot for every sanctions list
// Noble screens against. Public — no API key required — so customers and AI
// compliance agents can answer "are you screening against the latest OFAC?"
// without spending screening quota. The same per-list version info is also
// embedded in every /v1/screen response's list_versions field; this endpoint
// is the standalone fetch path used by status dashboards and the
// noble://sanctions-lists MCP resource.
//
// One entry per list. Lists that have never been imported into this Noble
// deployment are omitted (rather than emitting a sentinel row) so consumers
// don't need to special-case missing data.

// SanctionsListVersion describes the active publisher snapshot for a single
// sanctions list.
type SanctionsListVersion struct {
	// List is the canonical short identifier matching the values accepted in
	// ScreenRequest.Lists: "ofac", "uk", "eu", "france", "belgium",
	// "netherlands", "un", "canada", "australia".
	List string `json:"list"`

	// DisplayName is the human-readable name surfaced in dashboards
	// (e.g., "OFAC SDN", "UK OFSI Consolidated", "EU Financial Sanctions").
	DisplayName string `json:"display_name"`

	// PublishID is the publish_info row identifier — the audit pointer back
	// to the imported source file.
	PublishID int `json:"publish_id"`

	// PublishDate is the date the publisher released this version (YYYY-MM-DD),
	// taken verbatim from the source list.
	PublishDate string `json:"publish_date"`

	// RecordCount is the number of entries in this version.
	RecordCount int `json:"record_count"`

	// ImportedAt is when Noble ingested this version (RFC 3339, UTC).
	// Compare against PublishDate to see how stale the imported snapshot is.
	ImportedAt string `json:"imported_at"`

	// LastChecked is when Noble last polled the upstream publisher for this
	// list (RFC 3339, UTC) — the ingestion heartbeat. Unlike ImportedAt, it
	// advances on every poll even when the source is unchanged, so a recent
	// LastChecked is the proof that ingestion is live and you are on the
	// current published version. A LastChecked far in the past means the
	// watcher is not running, regardless of how healthy ImportedAt looks.
	// For OFAC (which polls the SDN and Consolidated files separately) this
	// is the oldest of the two checks, so a single dead watcher surfaces here.
	LastChecked string `json:"last_checked"`

	// LastImport is when the upstream content last actually changed and was
	// loaded (RFC 3339, UTC). Empty if the content has not changed since this
	// deployment began watching. For OFAC it is the most recent change across
	// both source files.
	LastImport string `json:"last_import"`

	// Status is the ingestion-freshness verdict for this list:
	//   "ok"    — LastChecked is within the freshness window (24h); the
	//             watcher is polling and this snapshot is trustworthy.
	//   "stale" — LastChecked is older than 24h or unknown; treat ingestion
	//             as potentially broken and investigate before relying on
	//             screening results for this list.
	// The verdict is intentionally fail-closed: when in doubt it reports
	// "stale" rather than implying freshness it cannot prove.
	Status string `json:"status"`
}

// Sanctions list ingestion-freshness verdicts (SanctionsListVersion.Status).
const (
	// ListStatusOK means the list was polled within the freshness window.
	ListStatusOK = "ok"
	// ListStatusStale means the list has not been polled within the freshness
	// window (or the last-poll time is unknown). Fail-closed default.
	ListStatusStale = "stale"
)

// ListFreshThreshold is the maximum age of SanctionsListVersion.LastChecked
// before a list's Status flips from "ok" to "stale". Noble commits to polling
// every list at least daily, so a gap beyond this points to a stalled watcher.
const ListFreshThreshold = 24 * time.Hour

// ListsResponse is returned by GET /v1/lists.
type ListsResponse struct {
	// Lists ordered by canonical short identifier (alphabetical).
	Lists []SanctionsListVersion `json:"lists"`
	Meta  ResponseMeta           `json:"meta"`
}

// =============================================================================
// Idempotency
// =============================================================================
//
// All state-mutating POST endpoints accept an optional Idempotency-Key request
// header. Noble caches the response for 24 hours under (scope, method, path,
// key); a retry with the same body returns the cached response and produces
// zero new side effects (no second screening_result row, no duplicate webhook
// delivery, no second alert activity row).
//
//   Idempotency-Key: <string>   (1-255 chars; UUID v4 recommended)
//
// Scope:
//   - Authenticated endpoints: the key is namespaced by tenant_id.
//   - POST /v1/keys (unauthenticated signup): the key is namespaced by the
//     client's source IP, so a customer whose first signup attempt's response
//     was lost mid-flight can retry and receive the original plaintext key.
//
// Behavior on a second request with the same (scope, method, path, key):
//
//   Same request body hash, first request completed
//     → Replay cached status + body + headers (X-Request-Id, X-RateLimit-*,
//       Content-Type). Replays do not consume rate-limit quota.
//
//   Same request body hash, first request still in flight (< 60s)
//     → 409 with code=idempotency_in_progress and Retry-After: 1.
//
//   Same request body hash, first request abandoned (>= 60s, no completion)
//     → Treat as new — claim the slot and re-process.
//
//   Different request body hash
//     → 400 with code=idempotency_key_mismatch. To retry with a different
//       body, generate a fresh Idempotency-Key.
//
//   Key longer than 255 characters
//     → 400 with code=idempotency_key_too_long.
//
// Caching policy:
//   - 2xx and 4xx responses ARE cached (4xx is deterministic from the request).
//   - 5xx responses are NOT cached (transient errors should be retryable).
//   - Replays do not re-trigger webhooks, do not insert new audit rows, and
//     do not consume rate-limit quota.
//
// Endpoints that honor Idempotency-Key:
//   POST /v1/screen, /v1/batch, /v1/portfolio, /v1/watchlist, /v1/webhooks,
//   /v1/alerts/{id}/resolve, /v1/alerts/{id}/assign, /v1/alerts/{id}/review,
//   /v1/alerts/{id}/escalate, /v1/alerts/{id}/notes,
//   /v1/alerts/bulk/resolve, /v1/alerts/bulk/assign,
//   /v1/account/checkout, /v1/keys.
//
// Endpoints that ignore Idempotency-Key (header is silently dropped):
//   GET and DELETE methods (idempotent by HTTP semantics), and /v1/admin/*
//   (operator-driven, Phase 1 only — revisit when IAP gating lands).

// MaxIdempotencyKeyLength caps the Idempotency-Key header at the Stripe-
// compatible 255-character limit. Longer keys return 400 idempotency_key_too_long.
const MaxIdempotencyKeyLength = 255

// IdempotencyRetentionHours is how long cached responses live before the
// hourly cleanup goroutine deletes them.
const IdempotencyRetentionHours = 24

// IdempotencyInProgressTimeoutSeconds is how long an in-progress row is
// considered live. After this window, the row is treated as abandoned and a
// retry may claim its slot. Matched to the server's WriteTimeout (60s) — any
// handler still in_progress past that point has already been killed by the
// timeout, so its row is safely reclaimable.
const IdempotencyInProgressTimeoutSeconds = 60

// =============================================================================
// POST /v1/batch - Submit a batch screening job
// =============================================================================

// BatchRequest is the input for batch screening.
type BatchRequest struct {
	// Names to screen (required, max 10,000 per batch)
	Names []BatchNameInput `json:"names"`

	// Lists restricts screening to the specified sanctions lists (batch-level).
	// Same values as ScreenRequest.Lists. Applied to all names in the batch.
	Lists []string `json:"lists,omitempty"`
}

// BatchNameInput is a single name entry in a batch request.
type BatchNameInput struct {
	// Full name to screen (required)
	FullName string `json:"full_name"`

	// Date of birth in YYYY-MM-DD format (optional)
	DateOfBirth string `json:"date_of_birth,omitempty"`

	// Country code ISO 3166-1 alpha-2 (optional)
	Country string `json:"country,omitempty"`

	// EntityType of the subject: "individual", "entity", "vessel", "aircraft"
	// (optional). Applied identically to ScreenRequest.EntityType — a genuine
	// type mismatch against the matched record reduces the score (OFAC FAQ 5
	// Step 2). Omitted means no entity-type penalty, matching /v1/screen.
	EntityType string `json:"entity_type,omitempty"`

	// IDNumber is a passport, tax ID, or other government identifier (optional).
	// When provided, actively matched against OFAC and UK sanctions ID tables.
	IDNumber string `json:"id_number,omitempty"`

	// IDType filters ID matching by type (e.g., "Passport") (optional).
	IDType string `json:"id_type,omitempty"`
}

// BatchResponse is the response after creating a batch job.
type BatchResponse struct {
	// Batch job ID for status polling
	ID int64 `json:"id"`

	// Current status: pending, processing, completed, failed.
	// A job that encounters an unrecoverable error is marked "failed" with an error_message.
	Status string `json:"status"`

	// Total names submitted
	TotalNames int `json:"total_names"`

	// Names processed so far
	ProcessedNames int `json:"processed_names"`

	// Names that had at least one match
	MatchCount int `json:"match_count"`

	// Detailed results per name (populated as items are screened; complete when status=completed)
	Items []BatchItemResponse `json:"items,omitempty"`
}

// BatchItemResponse is a single name result within a batch.
type BatchItemResponse struct {
	// Name that was screened
	FullName string `json:"full_name"`

	// Status: pending, screened, error
	Status string `json:"status"`

	// Number of sanctions matches found
	MatchCount int `json:"match_count"`

	// Highest match score (0-100)
	HighestScore float64 `json:"highest_score"`

	// Alert ID created for this name, if the highest score exceeded the tenant's
	// alert threshold. Zero/omitted means no alert was generated.
	AlertID int64 `json:"alert_id,omitempty"`

	// JurisdictionRisk is present when this item's country field places the
	// subject under a comprehensive OFAC embargo — identical detection to
	// ScreenResponse.JurisdictionRisk, so batch and single-screen can never
	// disagree about the same input.
	JurisdictionRisk *JurisdictionRisk `json:"jurisdiction_risk,omitempty"`
}

// =============================================================================
// GET /v1/portfolio - List monitored entities
// =============================================================================
//
// Returns List[PortfolioEntityResponse], cursor-paginated by entity id
// (?after=&limit=), ordered id ascending — see the "Pagination" contract.
// Optional filters: q (name substring), min_score, max_score. Full extraction
// of a large portfolio belongs to the async export/batch job, not GET paging.

// PortfolioEntityResponse is a single entity in the portfolio.
type PortfolioEntityResponse struct {
	// Entity ID
	ID int64 `json:"id"`

	// Full name being monitored
	FullName string `json:"full_name"`

	// Date of birth (YYYY-MM-DD) if known
	DateOfBirth string `json:"date_of_birth,omitempty"`

	// Country code (ISO 3166-1 alpha-2) if known
	Country string `json:"country,omitempty"`

	// Entity type: individual or entity
	EntityType string `json:"entity_type"`

	// Highest match score from last screening
	HighestScore float64 `json:"highest_score"`

	// Mean match score from last screening
	AverageScore float64 `json:"average_score"`

	// When this entity was last screened
	LastScreenedAt string `json:"last_screened_at"`

	// When this entity was first enrolled
	CreatedAt string `json:"created_at"`
}

// PortfolioAddRequest is the input for adding or updating a portfolio entity.
type PortfolioAddRequest struct {
	// Full name to monitor (required)
	FullName string `json:"full_name"`

	// Date of birth in YYYY-MM-DD format (optional)
	DateOfBirth string `json:"date_of_birth,omitempty"`

	// Country code ISO 3166-1 alpha-2 (optional)
	Country string `json:"country,omitempty"`
}

// PortfolioStatsResponse is the count companion to GET /v1/portfolio. Answers
// "how many entities am I monitoring, and how many are high-risk?" without
// paging the whole portfolio. Honors the same q/min_score/max_score filters as
// the list endpoint, so the count matches the filtered view.
type PortfolioStatsResponse struct {
	// Total active entities matching the (optional) filters.
	Total int `json:"total"`

	// ByScoreBand counts entities by highest match score (0–100):
	// "95-100", "90-94", "80-89", "below-80".
	ByScoreBand map[string]int `json:"by_score_band"`
}

// =============================================================================
// GET /v1/export - Compliance export of screening decisions
// =============================================================================

// ExportRecord is a single screening decision for compliance export.
// It contains the complete request, response, and metadata for regulatory
// audit trails, across ALL screening channels (see Channel).
type ExportRecord struct {
	// Row ID
	ID int64 `json:"id"`

	// Trace ID from the original screening request
	TraceID string `json:"trace_id"`

	// RequestID is the per-call HTTP request ID of the original screening,
	// stored alongside TraceID. Lets an operator pivot from a request_id to
	// this record. Empty outside the api channel and for screenings persisted
	// before this field existed.
	RequestID string `json:"request_id,omitempty"`

	// Client that owns this record
	ClientID string `json:"client_id"`

	// Channel is the screening pathway that produced this record: "api"
	// (POST /v1/screen), "batch" (POST /v1/batch items), or "monitoring"
	// (a sanctions-list change reverse-screened against the portfolio).
	// Records persisted before channels existed report "api".
	Channel string `json:"channel"`

	// ScreenedName is the name that was screened, surfaced first-class so
	// exports can be filtered by entity. For monitoring records the
	// direction is inverted: this is the changed sanctions-list name that
	// was screened against your portfolio.
	ScreenedName string `json:"screened_name,omitempty"`

	// Request is the verbatim audit payload of the screening inputs. Its
	// shape is channel-dependent: for "api" it is a ScreenRequest; for
	// "batch" it carries the item's fields under the same JSON keys (name,
	// date_of_birth, country, entity_type, id_number, id_type, lists); for
	// "monitoring" it describes the list change (source, uid, name,
	// change_type, publish_id, job_id).
	Request json.RawMessage `json:"request"`

	// Response is the verbatim audit payload of the screening outcome. For
	// "api" it is a ScreenResponse (incl. list_versions); for "batch" it
	// carries matches, match_count, highest_score, average_score, and
	// list_versions; for "monitoring" it carries the matched portfolio
	// entities (PII blanked for Confidential Portfolio rows), match_count,
	// highest_score, publish_id, and source.
	Response json.RawMessage `json:"response"`

	// OFAC list version active at screening time
	OFACListVersion *OFACListInfo `json:"ofac_list_version,omitempty"`

	// When the screening occurred (RFC 3339)
	ScreenedAt string `json:"screened_at"`
}

// OFACListInfo identifies the OFAC sanctions list version.
//
// Deprecated: prefer ListVersion, which carries the same data plus the
// canonical list identifier. Retained while ScreenResponse.OFACListVersion
// is being phased out.
type OFACListInfo struct {
	ID          int    `json:"id"`
	PublishDate string `json:"publish_date"`
	RecordCount int    `json:"record_count"`
}

// ListVersion identifies the publisher snapshot active at screening time for
// a single sanctions list. ScreenResponse.ListVersions surfaces one entry
// per list named in ListsScreened so examiners can pin a screening decision
// to the exact list snapshots that produced it.
type ListVersion struct {
	// List is the canonical identifier matching the values accepted in
	// ScreenRequest.Lists (e.g., "ofac", "uk", "eu", "france", "belgium",
	// "netherlands", "un", "canada", "australia").
	List string `json:"list"`

	// PublishID is the source-list publish_info row identifier — the audit
	// pointer back to the imported file in <list>.publish_info.
	PublishID int `json:"publish_id"`

	// PublishDate is the date the publisher released this version
	// (YYYY-MM-DD), taken verbatim from the source list.
	PublishDate string `json:"publish_date"`

	// RecordCount is the number of entries in this version.
	RecordCount int `json:"record_count"`
}

// GET /v1/export/bulk returns List[ExportRecord], cursor-paginated by screening
// row id (?after=&limit=) within a required from/to (YYYY-MM-DD) date range,
// ordered id ascending — see the "Pagination" contract. Optional filters:
// ?name= restricts to records whose screened_name matches case-insensitively
// (entity-centric audit: one customer's screening history across every
// channel), and ?channel= restricts to one of api|batch|monitoring. limit is hard-capped at
// MaxPageLimit; a full audit pull belongs to the async export job. There is no
// total. Requires Standard tier or higher; client isolation enforced.
//
// Output format: the audit/export endpoints — GET /v1/export, GET
// /v1/export/bulk, and GET /v1/alerts/activity — accept ?format=json (default)
// or ?format=csv. CSV is a flat, examiner-friendly table, one row per record,
// with a header row; an unrecognized format value is a 400 invalid_parameter.
// Because a CSV body cannot carry the JSON meta.disclaimer, CSV responses
// surface the liability disclaimer in the X-Noble-Disclaimer response header
// and set Content-Disposition so the download is saved as a named .csv file.
// The full nested match detail is JSON-only; the CSV columns summarize each
// decision (top match, list version, request attributes).

// =============================================================================
// POST /v1/export/replay - Recompute a stored screening against its historical
// list snapshot and compare
// =============================================================================
//
// Replay is the examiner-grade proof that the system reproduces a recorded
// decision: it loads a stored screening by trace_id (or request_id), re-runs
// the screening engine pinned to the sanctions-list state at the original
// screening instant (as_of = the record's screened_at), and reports a
// field-by-field comparison. Requires Standard tier or higher; client
// isolation enforced (you can only replay your own records).
//
// Scope: channel "api" records only — batch and monitoring records store
// channel-specific payload shapes and are rejected with
// replay_unsupported_channel. The comparison deliberately excludes what
// cannot be deterministically reproduced, and names each exclusion in
// caveats rather than hiding it:
//
//   - internal watchlist matches (WL- UIDs): the tenant watchlist is mutable
//     tenant data with no version history; stored watchlist matches are
//     excluded from comparison and the replay does not re-screen it.
//   - deep_screen influence: LLM variation expansion is non-deterministic;
//     when the stored request used deep_screen, the replay runs the
//     deterministic engine only. Per-match scores are not compared, and
//     match identity is compared asymmetrically: stored matches absent from
//     the replay are attributed to variation expansion (caveat, not drift),
//     while replay-only matches are still reported as differences.
//   - volatile identifiers: trace_id, request_id, screened_at, screening_id,
//     alert_id, and LLM summary prose are never compared.
//   - OFAC child detail: see ScreenRequest.AsOf's fidelity boundary.

// ReplayRequest selects the stored screening to replay. Exactly one of
// TraceID or RequestID is required; TraceID wins when both are present.
type ReplayRequest struct {
	// TraceID of the stored screening (ScreenResponse.TraceID).
	TraceID string `json:"trace_id,omitempty"`

	// RequestID of the stored screening (ScreenResponse.RequestID).
	RequestID string `json:"request_id,omitempty"`
}

// ReplayVerdict is the outcome of a replay comparison.
type ReplayVerdict string

const (
	// ReplayVerdictMatch: every compared field reproduced exactly.
	ReplayVerdictMatch ReplayVerdict = "match"

	// ReplayVerdictMismatch: at least one compared field differed — see
	// Differences. A mismatch is a finding to investigate (list data
	// mutated outside the import path, or an engine behavior change), not
	// necessarily an error in the stored record.
	ReplayVerdictMismatch ReplayVerdict = "mismatch"
)

// ReplayDifference is one compared field that did not reproduce.
type ReplayDifference struct {
	// Field is a dotted path identifying what differed, e.g.
	// "list_versions.ofac.publish_id", "matches.uids",
	// "matches.12345.score", "summary.verdict", "match_count".
	Field string `json:"field"`

	// Stored is the value in the audit record.
	Stored string `json:"stored"`

	// Replayed is the value the re-run produced.
	Replayed string `json:"replayed"`
}

// ReplayResponse reports a point-in-time replay of a stored screening.
type ReplayResponse struct {
	// TraceID of the replayed record.
	TraceID string `json:"trace_id"`

	// ScreeningID is the stored audit row id.
	ScreeningID int64 `json:"screening_id"`

	// ScreenedAt is when the original screening ran (RFC 3339). The replay
	// pins the engine to the sanctions-list state at exactly this instant.
	ScreenedAt string `json:"screened_at"`

	// Verdict is the comparison outcome across every compared field.
	Verdict ReplayVerdict `json:"verdict"`

	// Differences lists each compared field that failed to reproduce.
	// Empty when Verdict is "match".
	Differences []ReplayDifference `json:"differences,omitempty"`

	// Caveats names each comparison exclusion that applied to this record
	// (Caveat* constants), so the verdict's scope is explicit.
	Caveats []string `json:"caveats,omitempty"`

	// Stored is the verbatim audit response payload of the original
	// screening (a ScreenResponse).
	Stored json.RawMessage `json:"stored"`

	// Replayed is the full re-computed screening response. Its own volatile
	// fields (trace_id, screened_at, ...) describe the replay run, not the
	// original.
	Replayed *ScreenResponse `json:"replayed"`

	Meta ResponseMeta `json:"meta"`
}

// Replay comparison caveats (ReplayResponse.Caveats).
const (
	// CaveatWatchlistExcluded: the stored screening contained internal
	// watchlist matches; they were excluded from comparison.
	CaveatWatchlistExcluded = "watchlist_matches_excluded"

	// CaveatDeepScreenScoresNotCompared: the stored request used deep_screen;
	// match identity was compared but per-match scores, average_score, and
	// summary.verdict were not.
	CaveatDeepScreenScoresNotCompared = "deep_screen_scores_not_compared"

	// CaveatDeepScreenMatchesNotReproduced: the stored deep_screen run
	// contains matches absent from the deterministic replay. They are
	// attributed to LLM variation expansion — which can discover matches the
	// deterministic engine cannot find from the original name — and excluded
	// from the identity comparison rather than reported as drift. Matches
	// found only by the replay are still reported as a difference.
	CaveatDeepScreenMatchesNotReproduced = "deep_screen_matches_not_reproduced"

	// CaveatOFACChildDetailCurrent: the record contains OFAC matches, whose
	// alias/address/identifier child data replays at current state (see
	// ScreenRequest.AsOf).
	CaveatOFACChildDetailCurrent = "ofac_child_detail_current_state"
)

// =============================================================================
// POST /v1/keys - Provision a new API key
// =============================================================================
//
// Behavior depends on the server's signup_mode:
//
//   open         - anyone may create a free-tier key; invite_code is optional
//                  and, when supplied, overrides the tier per the invite row.
//   invite_only  - invite_code is required; tier comes from the invite row.
//   closed       - all signups return 403 with code=signup_closed.
//
// signup_mode is a server configuration value (SIGNUP_MODE env var). It is
// not part of the request — clients discover the current mode through the
// 403 (signup_closed) or 400 (invite_code_required) error responses.

// TermsVersion is the current version of Noble Sight's Terms of Service.
// Bump this when terms change to require re-acceptance on new key creation.
const TermsVersion = "1.0"

// CodeTermsNotAccepted is the error code when accept_terms is not true.
const CodeTermsNotAccepted = "terms_not_accepted"

// Signup mode constants. These govern whether POST /v1/keys is reachable and
// whether it requires an invite code. The value is set via SIGNUP_MODE env var.
const (
	SignupModeOpen       = "open"
	SignupModeInviteOnly = "invite_only"
	SignupModeClosed     = "closed"
)

// ValidSignupModes is the immutable set of accepted signup_mode values.
// Used at startup to validate the SIGNUP_MODE config and fail loud on typos.
var ValidSignupModes = map[string]bool{
	SignupModeOpen:       true,
	SignupModeInviteOnly: true,
	SignupModeClosed:     true,
}

// CreateKeyRequest is the input for provisioning a new API key.
type CreateKeyRequest struct {
	// Unique identifier for the client organization (required, 1-100 chars)
	ClientID string `json:"client_id"`

	// Human-readable label for the key (optional, max 255 chars)
	Name string `json:"name,omitempty"`

	// Must be true to create a key. Indicates acceptance of Noble Sight's
	// Terms of Service (https://noblesight.io/terms) and acknowledgment that
	// screening results are informational only and do not constitute legal
	// or compliance advice.
	AcceptTerms bool `json:"accept_terms"`

	// InviteCode redeems an invite issued by Noble Sight. Required when the
	// server is in signup_mode=invite_only. Optional in signup_mode=open
	// (when supplied, the tier and scopes on the invite override the free-tier
	// defaults — used for promo codes, design-partner trials, and sales-led
	// trials). Format: noble_inv_ + 20 hex characters.
	InviteCode string `json:"invite_code,omitempty"`
}

// CreateKeyResponse is returned after successfully creating an API key.
type CreateKeyResponse struct {
	// Plaintext API key (shown once — store securely)
	Key string `json:"key"`

	// First 16 characters of the key for identification
	KeyPrefix string `json:"key_prefix"`

	// Tier assigned to this key
	Tier string `json:"tier"`

	// Daily rate limit (free tier)
	RateLimitPerDay int `json:"rate_limit_per_day"`

	// Version of the Terms of Service accepted
	TermsVersion string `json:"terms_version"`
}

// =============================================================================
// POST /v1/admin/keys — Mint a comped or trial API key (internal admin only)
// =============================================================================
//
// Reserved for internal admin tooling (provisioning design-partner trials,
// pilot comps, event comps). Reachable in Phase 1 only via the localhost
// interface of the noble-server pod — `kubectl port-forward` from an
// operator who already has GKE IAM access. Phase 2 will gate `/v1/admin/*`
// via Google IAP and override `granted_by` from the IAP-verified JWT email
// so callers cannot misrepresent themselves; the request/response shapes
// below remain unchanged.

// AdminCreateKeyRequest mints a comped/trial API key for a customer.
type AdminCreateKeyRequest struct {
	// Customer identifier (required, 1-100 chars)
	ClientID string `json:"client_id"`

	// Human-readable label for the key (optional, max 255 chars)
	Name string `json:"name,omitempty"`

	// Tier: free, standard, premium, enterprise. Trials are typically enterprise.
	Tier string `json:"tier"`

	// Trial duration in whole days. Zero/omitted means no expiry.
	// 30 = 30-day trial, 180 = 6-month trial, 365 = year-long comp.
	TrialDays int `json:"trial_days,omitempty"`

	// Comp category for cohort analysis: design_partner, pilot, evaluation, event.
	// Required when trial_days > 0.
	CompCategory string `json:"comp_category,omitempty"`

	// Free-text justification for the comp (required). Surfaced in audit logs
	// and the eventual admin-key list endpoint.
	CompReason string `json:"comp_reason"`

	// Operator identity for the audit trail (e.g., gcloud account email).
	// Required in Phase 1; overridden by IAP-verified email in Phase 2.
	GrantedBy string `json:"granted_by"`

	// Contact email — recorded in slog audit only, not the api_key row.
	Email string `json:"email,omitempty"`
}

// AdminCreateKeyResponse echoes the audit metadata and returns the plaintext
// key ONCE. Operators copy the key from this response; it is not retrievable
// later (only the SHA-256 hash is stored).
type AdminCreateKeyResponse struct {
	// Plaintext API key — shown once, store securely.
	Key string `json:"key"`

	// First 16 characters of the key for identification.
	KeyPrefix string `json:"key_prefix"`

	// Customer identifier this key was minted for.
	ClientID string `json:"client_id"`

	// Tier assigned to this key.
	Tier string `json:"tier"`

	// When the trial expires (RFC 3339). Empty when no trial.
	TrialEndsAt string `json:"trial_ends_at,omitempty"`

	// Comp category recorded for this key.
	CompCategory string `json:"comp_category,omitempty"`

	// Free-text justification recorded for this key.
	CompReason string `json:"comp_reason"`

	// Operator identity recorded for this key.
	CompGrantedBy string `json:"comp_granted_by"`
}

// Error codes for admin endpoints.
const (
	CodeReasonRequired        = "comp_reason_required"
	CodeCategoryRequired      = "comp_category_required"
	CodeGrantedByRequired     = "granted_by_required"
	CodeInvalidTrialDays      = "invalid_trial_days"
	CodeInvalidCategory       = "invalid_comp_category"
	CodeInvalidAdminTier      = "invalid_tier"
	CodeInviteNotesTooLong    = "invite_notes_too_long"
	CodeInvalidMaxRedemptions = "invalid_max_redemptions"
	CodeInvalidExpiresAt      = "invalid_expires_at"
)

// =============================================================================
// /v1/admin/invites — Mint and manage invite codes (internal admin only)
// =============================================================================
//
// Internal admin tooling for provisioning controlled signup access. Same
// auth posture as /v1/admin/keys: localhost-only in Phase 1 (reachable via
// kubectl port-forward), Google IAP in Phase 2. The created_by field is
// captured from the request in Phase 1 and overridden by the IAP-verified
// JWT email in Phase 2.
//
// Issuing one of these codes is the *only* way new customers (post-Royal
// Bank) enter the system while signup_mode=invite_only. Every code is a
// row with a created_by + timestamp — the auditable artifact a regulator
// reviews when asking "who granted this customer access?"

// AdminCreateInviteRequest mints a new invite code.
type AdminCreateInviteRequest struct {
	// Tier granted to keys redeemed from this invite (required).
	// Values: free, standard, premium, enterprise.
	Tier string `json:"tier"`

	// MaxRedemptions caps how many keys can be minted from this code.
	// Defaults to 1. Use higher values for promo codes ("BLACKFRIDAY: 100 redemptions").
	MaxRedemptions int `json:"max_redemptions,omitempty"`

	// ExpiresAt is when the code stops being redeemable (RFC 3339).
	// Empty/omitted = never expires. Use for time-limited promos.
	ExpiresAt string `json:"expires_at,omitempty"`

	// CreatedBy is the operator identity recorded for audit (e.g., gcloud
	// account email). Required in Phase 1; overridden by IAP email in Phase 2.
	CreatedBy string `json:"created_by"`

	// Notes is free-text context for the audit trail (e.g., "Royal Bank beta",
	// "Q1 conference comp"). Max 500 chars. Surfaced in the admin invite list.
	Notes string `json:"notes,omitempty"`

	// Scopes are capability scopes inherited by every key minted from this
	// invite. Omit or pass empty for the default ["api"]. Pass ["api","mcp"]
	// for design-partner invites that need MCP from day one. Must always
	// include "api" — every key needs REST access.
	Scopes []string `json:"scopes,omitempty"`
}

// AdminCreateInviteResponse echoes the audit metadata and returns the plaintext
// code ONCE. Codes are reversible (stored in plaintext so customers can be
// re-sent their code if lost), but operators should still capture this response.
type AdminCreateInviteResponse struct {
	// Plaintext invite code (noble_inv_ + 20 hex chars).
	Code string `json:"code"`

	// Unique invite ID (UUID).
	ID string `json:"id"`

	// Tier granted by this invite.
	Tier string `json:"tier"`

	// Maximum redemptions allowed.
	MaxRedemptions int `json:"max_redemptions"`

	// Expiry timestamp (RFC 3339), empty when never expires.
	ExpiresAt string `json:"expires_at,omitempty"`

	// Operator who minted the invite.
	CreatedBy string `json:"created_by"`

	// Free-text notes recorded for this invite.
	Notes string `json:"notes,omitempty"`

	// When the invite was created (RFC 3339).
	CreatedAt string `json:"created_at"`

	// Scopes inherited by every key minted from this invite.
	Scopes []string `json:"scopes"`
}

// InviteResponse is a single invite in admin listings. The plaintext code is
// included — invites are not secret credentials (the redeemed API key is).
type InviteResponse struct {
	ID              string   `json:"id"`
	Code            string   `json:"code"`
	Tier            string   `json:"tier"`
	MaxRedemptions  int      `json:"max_redemptions"`
	RedemptionsUsed int      `json:"redemptions_used"`
	ExpiresAt       string   `json:"expires_at,omitempty"`
	Status          string   `json:"status"`
	CreatedBy       string   `json:"created_by"`
	Notes           string   `json:"notes,omitempty"`
	CreatedAt       string   `json:"created_at"`
	RevokedAt       string   `json:"revoked_at,omitempty"`
	Scopes          []string `json:"scopes"`
}

// InviteListResponse wraps a list of invites for admin tooling.
type InviteListResponse struct {
	Total   int              `json:"total"`
	Invites []InviteResponse `json:"invites"`
}

// MaxInviteNotesLength caps the notes field on an invite to prevent abuse.
const MaxInviteNotesLength = 500

// =============================================================================
// POST /v1/admin/keys/scopes - Grant or revoke capability scopes on an
// existing API key. Localhost-only. Writes an append-only audit row to
// customers.api_key_scope_change capturing before/after, operator, and
// reason — examiners reconstruct capability history from that table.
// =============================================================================

// AdminChangeKeyScopesRequest mutates the scopes on an existing API key.
// The change is transactional: the UPDATE on customers.api_key and the
// INSERT on customers.api_key_scope_change either both commit or neither.
type AdminChangeKeyScopesRequest struct {
	// KeyID is customers.api_key.id of the target key (required).
	KeyID int64 `json:"key_id"`

	// Add lists scopes to grant. Already-present scopes are silently ignored.
	// Recognized values today: "mcp". ("api" cannot be added — every key has
	// it by construction.)
	Add []string `json:"add,omitempty"`

	// Remove lists scopes to revoke. Already-absent scopes are silently
	// ignored. "api" cannot be removed — every key must retain REST access.
	Remove []string `json:"remove,omitempty"`

	// Reason is the human-readable justification recorded on the audit row
	// (required). Examples: "Royal Bank MCP design-partner enrollment",
	// "revoked per support ticket #1234". Max 500 chars.
	Reason string `json:"reason"`

	// ChangedBy is the operator identity recorded for audit (required).
	// Phase 1: gcloud account email passed in the request body. Phase 2:
	// overridden by the IAP-verified email and the request body field is
	// ignored.
	ChangedBy string `json:"changed_by"`
}

// AdminChangeKeyScopesResponse returns the before/after state and the
// audit row ID so operators can cite it in change tickets.
type AdminChangeKeyScopesResponse struct {
	KeyID        int64    `json:"key_id"`
	ClientID     string   `json:"client_id"`
	KeyPrefix    string   `json:"key_prefix"`
	ScopesBefore []string `json:"scopes_before"`
	ScopesAfter  []string `json:"scopes_after"`
	AuditID      int64    `json:"audit_id"`
	ChangedAt    string   `json:"changed_at"` // RFC 3339
}

// =============================================================================
// GET /v1/admin/ownership/pending - 50 Percent Rule extraction review queue.
// Localhost-only. Lists LLM-extracted ownership assertions (#63 Phase C)
// awaiting human review: every relation the list-text extractor persisted to
// ownership.extracted_relation with its verbatim source quote. Reviewing
// these is how an operator validates the extraction layer feeding the
// ownership graph.
// =============================================================================

// OwnershipPendingResponse lists extracted ownership relations awaiting
// review, oldest first.
type OwnershipPendingResponse struct {
	// Total is the number of relations awaiting review (may exceed
	// len(Relations) when the queue is longer than the page cap).
	Total     int                        `json:"total"`
	Relations []OwnershipPendingRelation `json:"relations"`
}

// OwnershipPendingRelation is one LLM-extracted ownership assertion, exactly
// as persisted to the audit store before it became a graph edge.
type OwnershipPendingRelation struct {
	// ID is the assertion's stable identifier in ownership.extracted_relation.
	ID int64 `json:"id"`

	// List is the sanctions list whose published text the assertion came
	// from ("france", "uk", "un", "eu").
	List string `json:"list"`

	// UID is the source-native designation ID of the list record.
	UID string `json:"uid"`

	// Subject is the list record's subject name (the designated party whose
	// entry carried the text).
	Subject string `json:"subject"`

	// OwnerText and OwnedText are the owner and owned entity names exactly
	// as written in the source text.
	OwnerText string `json:"owner_text"`
	OwnedText string `json:"owned_text"`

	// RelType is "ownership" or "control".
	RelType string `json:"rel_type"`

	// Percent is the ownership percentage, present only when the source
	// text states a number.
	Percent *float64 `json:"percent,omitempty"`

	// Quote is the verbatim minimal substring of the list text the
	// assertion was extracted from — the audit evidence.
	Quote string `json:"quote"`

	// OwnerKey and OwnedKey are the graph entity keys the names resolved
	// to; empty when unresolved.
	OwnerKey string `json:"owner_key,omitempty"`
	OwnedKey string `json:"owned_key,omitempty"`

	// Model is the LLM that performed the extraction.
	Model string `json:"model"`

	// ListPublishID is the list snapshot the text came from.
	ListPublishID int `json:"list_publish_id"`

	// ExtractedAt is when the assertion was extracted (RFC 3339).
	ExtractedAt string `json:"extracted_at"`
}

// MaxOwnershipPendingPage caps one review-queue page.
const MaxOwnershipPendingPage = 500

// =============================================================================
// GET /v1/usage - Check API usage for the current key
// =============================================================================

// UsageResponse returns the current usage stats for the authenticated API key.
type UsageResponse struct {
	// Tier of the authenticated key
	Tier string `json:"tier"`

	// Requests used in the current window
	Used int `json:"used"`

	// Total request limit for the current window
	Limit int `json:"limit"`

	// Requests remaining in the current window
	Remaining int `json:"remaining"`

	// Rate limit window: "day" (free) or "month" (paid)
	Window string `json:"window"`

	// Trial details — present only when this key is a comped/trial key.
	// Customers and customer dashboards use this to show "your trial ends in N days".
	Trial *TrialInfo `json:"trial,omitempty"`
}

// TrialInfo describes the trial window for a comped API key.
// Trial keys receive full enterprise-tier access until ends_at, after which
// a daily job flips the key's status to "expired" and subsequent requests
// return 402 Payment Required with code=trial_expired.
type TrialInfo struct {
	// When the trial expires (RFC 3339, UTC)
	EndsAt string `json:"ends_at"`

	// Days remaining until expiry (0 on the day of expiry; never negative)
	DaysRemaining int `json:"days_remaining"`

	// Comp category for the trial: design_partner, pilot, evaluation, event
	Category string `json:"category,omitempty"`
}

// =============================================================================
// GET /v1/alerts - List alerts for the authenticated tenant
// =============================================================================
//
// Returns List[AlertResponse], cursor-paginated by alert id (?after=&limit=),
// ordered id ascending — see the "Pagination" contract. Filters (all optional):
// status, source, min_score, max_score, assigned_to, from, to (YYYY-MM-DD).
// There is no total; use GET /v1/alerts/stats for queue counts.
//
// =============================================================================
// GET /v1/alerts/{id} - Single alert with full detail
// =============================================================================
//
// Returns a single AlertResponse including the match payload and the full case
// activity timeline (Activity, oldest first). 404 if the id is unknown or not
// owned by the caller's tenant.

// AlertResponse is a single alert in list or detail views.
type AlertResponse struct {
	// Unique alert identifier
	ID int64 `json:"id"`

	// The name that was screened
	ScreenedName string `json:"screened_name"`

	// Combined match score (0-100)
	Score float64 `json:"score"`

	// Number of sanctions matches
	MatchCount int `json:"match_count"`

	// How the alert originated: "api" (POST /v1/screen match), "batch"
	// (POST /v1/batch item), "monitoring" (portfolio monitoring delta),
	// "ownership" (a "blocked" 50 Percent Rule determination — see
	// ScreenResponse.Ownership; for these, score is always 100 and the
	// determination evidence is in match_details), or "console" (legacy).
	Source string `json:"source"`

	// Alert lifecycle status
	Status string `json:"status"`

	// Analyst assigned to this alert (email or "apikey:<prefix>")
	AssignedTo string `json:"assigned_to,omitempty"`

	// Structured resolution reason (only when closed)
	Reason string `json:"reason,omitempty"`

	// Disposition records what action was taken for true matches.
	// Values: "blocked", "rejected", "permitted_gl", "no_action_required".
	Disposition string `json:"disposition,omitempty"`

	// GLCitation documents which general license permits the transaction.
	GLCitation string `json:"gl_citation,omitempty"`

	// Whether the four-eyes rule applies to this alert (score >= 90)
	FourEyesRequired bool `json:"four_eyes_required"`

	// SLA deadline (RFC 3339). Score >= 90: 24h, others: 72h from assignment.
	DueAt string `json:"due_at,omitempty"`

	// Whether the SLA deadline has passed for an open alert
	Overdue bool `json:"overdue"`

	// SDN match details (present when matched against a specific SDN entry)
	SdnUID       int    `json:"sdn_uid,omitempty"`
	SdnFirstName string `json:"sdn_first_name,omitempty"`
	SdnLastName  string `json:"sdn_last_name,omitempty"`

	// Full match payload (JSON array of all screening matches)
	MatchPayload json.RawMessage `json:"match_payload,omitempty"`

	// Portfolio entity (present when alert is linked to a monitored entity)
	Entity *AlertEntityResponse `json:"entity,omitempty"`

	// Case activity timeline (present in detail view, omitted in list)
	Activity []AlertActivityResponse `json:"activity,omitempty"`

	// When the alert was created (RFC 3339)
	CreatedAt string `json:"created_at"`
}

// AlertEntityResponse is the portfolio entity linked to an alert.
type AlertEntityResponse struct {
	FullName    string `json:"full_name"`
	DateOfBirth string `json:"date_of_birth,omitempty"`
	Country     string `json:"country,omitempty"`
	EntityType  string `json:"entity_type"`
}

// AlertActivityResponse is a single entry in the alert's audit trail.
type AlertActivityResponse struct {
	// Who performed the action (email, "apikey:<prefix>", or
	// "system:monitoring" for list_event entries)
	Actor string `json:"actor"`

	// Action type: "status_change", "assigned", "note", "escalated",
	// "reopened", or "list_event". A list_event entry records a sanctions
	// list update that matched this alert's entity while the alert was open
	// — the same person re-designated or modified on the same list — so the
	// timeline shows every designation event during the alert's life; the
	// note carries the change type, list, publish id, and score. (A
	// designation on a different list raises its own alert instead.)
	Action string `json:"action"`

	// Previous status (for status_change actions)
	FromStatus string `json:"from_status,omitempty"`

	// New status (for status_change actions)
	ToStatus string `json:"to_status,omitempty"`

	// Structured reason code (for resolution actions)
	Reason string `json:"reason,omitempty"`

	// Disposition (for true match closures)
	Disposition string `json:"disposition,omitempty"`

	// General license citation (for permitted_gl dispositions)
	GLCitation string `json:"gl_citation,omitempty"`

	// Free-text investigation note
	Note string `json:"note,omitempty"`

	// When this action occurred (RFC 3339)
	Time string `json:"time"`

	// ID is the case-activity row id. Present in the activity export
	// (GET /v1/alerts/activity) where it is the cursor for ?after=; omitted in
	// the alert-detail timeline.
	ID int64 `json:"id,omitempty"`

	// Alert ID (present in activity export, omitted in alert detail)
	AlertID int64 `json:"alert_id,omitempty"`
}

// =============================================================================
// POST /v1/alerts/{id}/resolve - Resolve an alert with a structured reason
// =============================================================================

// AlertResolveRequest is the input for resolving an alert.
type AlertResolveRequest struct {
	// Target status: "closed_false_positive" or "closed_true_match"
	Status string `json:"status"`

	// Structured reason code (required)
	Reason string `json:"reason"`

	// Disposition records what action was taken for true matches (required when status=closed_true_match).
	// Values: "blocked", "rejected", "permitted_gl", "no_action_required".
	// OFAC requires filing blocking/reject reports within 10 business days.
	Disposition string `json:"disposition,omitempty"`

	// GLCitation documents which general license permits the transaction (required when disposition=permitted_gl).
	// Example: "GL 8A — Iran humanitarian trade" or "Russia GL 25G".
	GLCitation string `json:"gl_citation,omitempty"`

	// Optional investigation note
	Note string `json:"note,omitempty"`
}

// =============================================================================
// POST /v1/alerts/{id}/assign - Assign an alert to an analyst
// =============================================================================

// AlertAssignRequest is the input for assigning an alert.
type AlertAssignRequest struct {
	// Email of the analyst to assign to (required)
	AssignTo string `json:"assign_to"`
}

// =============================================================================
// POST /v1/alerts/{id}/review - Start investigation (assigned → under_review)
// =============================================================================

// AlertReviewRequest is the input for starting investigation on an alert.
// Unlike resolve, no reason code is required — the analyst is beginning work.
type AlertReviewRequest struct {
	// Optional note capturing initial observations
	Note string `json:"note,omitempty"`
}

// =============================================================================
// POST /v1/alerts/{id}/notes - Add an investigation note
// =============================================================================

// AlertNoteRequest is the input for adding a note to an alert.
type AlertNoteRequest struct {
	// Investigation note text (required, max 2000 chars)
	Note string `json:"note"`
}

// =============================================================================
// POST /v1/alerts/{id}/escalate - Escalate an alert
// =============================================================================

// AlertEscalateRequest is the input for escalating an alert.
type AlertEscalateRequest struct {
	// Optional note explaining the escalation
	Note string `json:"note,omitempty"`
}

// =============================================================================
// Alert Constants
// =============================================================================

// Alert statuses define the lifecycle of an alert.
// Both the console UI and REST API enforce the same transitions.
const (
	AlertStatusNew             = "new"
	AlertStatusAssigned        = "assigned"
	AlertStatusUnderReview     = "under_review"
	AlertStatusEscalated       = "escalated"
	AlertStatusClosedFP        = "closed_false_positive"
	AlertStatusClosedTrueMatch = "closed_true_match"
)

// Alert resolution reason codes. Structured reasons are required for closing
// an alert and serve as the auditable justification an OFAC examiner will review.
const (
	ReasonFPNameOnly           = "false_positive_name_only"
	ReasonFPDOBMismatch        = "false_positive_dob_mismatch"
	ReasonFPCountryMismatch    = "false_positive_country_mismatch"
	ReasonFPEntityTypeMismatch = "false_positive_entity_type_mismatch"
	ReasonFPOther              = "false_positive_other"
	ReasonTrueMatch            = "true_match"
)

// Disposition constants record what action was taken on a confirmed true match.
// OFAC requires blocking/reject reports within 10 business days (31 C.F.R. Part 501).
const (
	DispositionBlocked          = "blocked"
	DispositionRejected         = "rejected"
	DispositionPermittedGL      = "permitted_gl"
	DispositionNoActionRequired = "no_action_required"
)

// validReasons is the immutable set of accepted resolution reason codes.
// Unexported to prevent runtime mutation — compliance state machine integrity.
var validReasons = map[string]bool{
	ReasonFPNameOnly:           true,
	ReasonFPDOBMismatch:        true,
	ReasonFPCountryMismatch:    true,
	ReasonFPEntityTypeMismatch: true,
	ReasonFPOther:              true,
	ReasonTrueMatch:            true,
}

// IsValidReason reports whether r is an accepted resolution reason code.
func IsValidReason(r string) bool { return validReasons[r] }

// validDispositions is the immutable set of accepted disposition values for true matches.
var validDispositions = map[string]bool{
	DispositionBlocked:          true,
	DispositionRejected:         true,
	DispositionPermittedGL:      true,
	DispositionNoActionRequired: true,
}

// IsValidDisposition reports whether d is an accepted disposition value.
func IsValidDisposition(d string) bool { return validDispositions[d] }

// validTransitions defines the allowed status transitions for alerts.
// Alerts cannot be closed without passing through under_review — this ensures
// every closure has an investigation step in the audit trail. Closed alerts
// can be reopened to under_review when an examiner finds a premature closure.
// Escalated alerts can be sent back to under_review for further investigation.
// Unexported to prevent runtime mutation — compliance state machine integrity.
var validTransitions = map[string]map[string]bool{
	AlertStatusNew:             {AlertStatusAssigned: true, AlertStatusEscalated: true},
	AlertStatusAssigned:        {AlertStatusUnderReview: true, AlertStatusEscalated: true},
	AlertStatusUnderReview:     {AlertStatusEscalated: true, AlertStatusClosedFP: true, AlertStatusClosedTrueMatch: true},
	AlertStatusEscalated:       {AlertStatusUnderReview: true, AlertStatusClosedFP: true, AlertStatusClosedTrueMatch: true},
	AlertStatusClosedFP:        {AlertStatusUnderReview: true},
	AlertStatusClosedTrueMatch: {AlertStatusUnderReview: true},
}

// IsValidTransition reports whether transitioning from one status to another is allowed.
func IsValidTransition(from, to string) bool {
	allowed, ok := validTransitions[from]
	return ok && allowed[to]
}

// FourEyesScoreThreshold is the minimum score (0-100) that triggers the
// four-eyes rule: a different analyst must close the alert than the one
// who last moved it through the workflow.
const FourEyesScoreThreshold = 90

// SLA deadlines based on alert score.
const (
	SLAHighScoreHours    = 24 // score >= FourEyesScoreThreshold
	SLADefaultScoreHours = 72 // score < FourEyesScoreThreshold
)

// MaxNoteLength is the maximum character length for investigation notes.
const MaxNoteLength = 2000

// AlertService sentinel errors. Defined here (alongside the interface in server.go)
// so that both internal/alert and HTTP handlers share the same error values.
var (
	ErrAlertNotFound            = errors.New("alert not found")
	ErrAlertInvalidReason       = errors.New("invalid reason code")
	ErrAlertInvalidTransition   = errors.New("invalid status transition")
	ErrAlertInvalidDisposition  = errors.New("invalid disposition")
	ErrAlertDispositionRequired = errors.New("disposition required for true match closure")
	ErrAlertGLCitationRequired  = errors.New("gl_citation required when disposition is permitted_gl")
	ErrAlertFourEyes            = errors.New("four-eyes required: a different analyst must close high-score alerts")
	ErrAlertConcurrentModified  = errors.New("alert status changed concurrently")
	ErrAlertInvalidAssignee     = errors.New("assignee is not an active team member")
	ErrAlertEmptyNote           = errors.New("note cannot be empty")
	ErrAlertNoteTooLong         = errors.New("note exceeds 2000 character limit")
)

// API limits for batch operations
const (
	// MaxBatchSize is the maximum number of names in a single batch.
	MaxBatchSize = 10_000

	// MaxIDsPerRequest caps how many entries ScreenRequest.IDs may contain.
	// Real entities rarely carry more than a handful of identifiers; the cap
	// is generous enough for compounded passport + tax ID + crypto wallet
	// portfolios while bounding worst-case work per screening call.
	MaxIDsPerRequest = 20
)

// =============================================================================
// GET /v1/alerts/activity - Export case activity audit trail
// =============================================================================
//
// Returns List[AlertActivityResponse]: the case-activity audit trail, cursor-
// paginated by activity row id (?after=&limit=). Filters: from, to (YYYY-MM-DD),
// alert_id, actor, action. Large pulls belong to the async export job.

// =============================================================================
// POST /v1/alerts/bulk/resolve - Bulk resolve alerts
// =============================================================================

// BulkResolveRequest resolves multiple alerts with the same status and reason.
type BulkResolveRequest struct {
	// Alert IDs to resolve
	AlertIDs []int64 `json:"alert_ids"`

	// Target status: "closed_false_positive" or "closed_true_match"
	Status string `json:"status"`

	// Structured reason code (required)
	Reason string `json:"reason"`

	// Disposition for true matches (required when status=closed_true_match)
	Disposition string `json:"disposition,omitempty"`

	// GL citation (required when disposition=permitted_gl)
	GLCitation string `json:"gl_citation,omitempty"`

	// Optional note applied to all alerts
	Note string `json:"note,omitempty"`
}

// BulkResolveResponse reports per-alert success or failure.
type BulkResolveResponse struct {
	Resolved int                 `json:"resolved"`
	Failed   int                 `json:"failed"`
	Results  []BulkResolveResult `json:"results"`
}

// BulkResolveResult is the outcome for a single alert in a bulk resolve.
type BulkResolveResult struct {
	AlertID int64  `json:"alert_id"`
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty"`
}

// MaxBulkResolveSize limits how many alerts can be resolved in a single bulk request.
const MaxBulkResolveSize = 200

// =============================================================================
// POST /v1/alerts/bulk/assign - Bulk assign alerts
// =============================================================================

// BulkAssignRequest assigns multiple alerts to the same analyst.
type BulkAssignRequest struct {
	// Alert IDs to assign
	AlertIDs []int64 `json:"alert_ids"`

	// Email of the analyst to assign to (required)
	AssignTo string `json:"assign_to"`
}

// BulkAssignResponse reports per-alert success or failure.
type BulkAssignResponse struct {
	Assigned int                `json:"assigned"`
	Failed   int                `json:"failed"`
	Results  []BulkAssignResult `json:"results"`
}

// BulkAssignResult is the outcome for a single alert in a bulk assign.
type BulkAssignResult struct {
	AlertID int64  `json:"alert_id"`
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty"`
}

// MaxBulkAssignSize limits how many alerts can be assigned in a single bulk request.
const MaxBulkAssignSize = 200

// =============================================================================
// GET /v1/alerts/stats - Alert queue statistics
// =============================================================================

// AlertStatsResponse provides a breakdown of the alert queue for management
// dashboards and compliance reporting. Answers "how many alerts by status
// and score tier?" without paginating through the full list.
type AlertStatsResponse struct {
	// Total alerts across all statuses
	Total int `json:"total"`

	// Counts by status
	ByStatus map[string]int `json:"by_status"`

	// Counts by score band for open (non-closed) alerts
	ByScoreBand map[string]int `json:"by_score_band"`

	// SLA compliance for open alerts
	Overdue    int `json:"overdue"`
	WithinSLA  int `json:"within_sla"`
	NoDeadline int `json:"no_deadline"`
}

// ActivityStatsResponse is the count companion to GET /v1/alerts/activity.
// Answers "how many case-activity records match this filter/period?" without
// paging the trail. Honors the same alert_id/actor/action/from/to filters as
// the list endpoint.
type ActivityStatsResponse struct {
	// Total activity records matching the (optional) filters.
	Total int `json:"total"`

	// ByAction counts records by action (e.g. assign, escalate, dismiss).
	ByAction map[string]int `json:"by_action"`
}

// =============================================================================
// GET /v1/alerts/resolutions/stats - Observed false-positive rate from analyst
// resolutions
// =============================================================================
//
// The production false-positive feedback loop (#92): every alert resolution
// carries a structured reason code, and this endpoint aggregates those
// dispositions into an observed FP rate by score band — the measured
// counterpart to the fixture-derived FP benchmark. Use it to answer "of the
// alerts we raise at each score band, what share do analysts dismiss as
// false positives?" — the driving input of the threshold tuning procedure
// (docs/testing/tuning.md).
//
// Counting model: resolution events from the immutable case-activity trail
// (action=status_change into a closed_* status), joined to the alert for its
// score. A reopened-and-reclosed alert contributes each closure — the rate
// measures analyst decisions, not current alert states. Only scores >= the
// tenant's alert threshold ever create alerts, so bands below the threshold
// in effect at alert time are structurally empty.
//
// Optional query parameters: from and to (YYYY-MM-DD, inclusive) bound the
// resolution date; omitting both aggregates all history.

// ResolutionBandStats is one score band's resolution outcomes.
type ResolutionBandStats struct {
	// Resolved is total resolution events in this band.
	Resolved int `json:"resolved"`

	// FalsePositives is resolutions into closed_false_positive.
	FalsePositives int `json:"false_positives"`

	// TrueMatches is resolutions into closed_true_match.
	TrueMatches int `json:"true_matches"`

	// FPRate is FalsePositives / Resolved (0 when the band is empty).
	FPRate float64 `json:"fp_rate"`
}

// ResolutionStatsResponse reports resolution-derived screening quality
// metrics. "Resolution" here is the analyst decision recorded by POST
// /v1/alerts/{id}/resolve — distinct from ScreenMatch.DismissalSignals,
// which are engine-computed score-reduction signals on a single match.
type ResolutionStatsResponse struct {
	// Total resolution events in the window.
	Total int `json:"total"`

	// FalsePositives and TrueMatches are the window-wide outcome split.
	FalsePositives int `json:"false_positives"`
	TrueMatches    int `json:"true_matches"`

	// ObservedFPRate is FalsePositives / Total (0 when Total is 0) — the
	// production-measured false-positive rate.
	ObservedFPRate float64 `json:"observed_fp_rate"`

	// ByScoreBand splits outcomes by the alert's match score band
	// ("95-100", "90-94", "80-89", "below-80" — same bands as
	// GET /v1/alerts/stats).
	ByScoreBand map[string]ResolutionBandStats `json:"by_score_band"`

	// ByReason counts resolutions by their structured reason code
	// (Reason* constants).
	ByReason map[string]int `json:"by_reason"`

	// From/To echo the applied window bounds (YYYY-MM-DD), empty when
	// unbounded.
	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`
}

// =============================================================================
// GET /v1/alerts/{id}/ofac-report - Generate OFAC-ready blocking/reject report
// =============================================================================

// OFACReportResponse assembles everything OFAC needs for a blocking or reject
// report into a single response. Only available on alerts resolved as
// closed_true_match with a disposition of "blocked" or "rejected".
type OFACReportResponse struct {
	// Alert that triggered this report
	AlertID int64 `json:"alert_id"`

	// Report type derived from disposition: "blocking" or "reject"
	ReportType string `json:"report_type"`

	// When this report was generated (RFC 3339)
	GeneratedAt string `json:"generated_at"`

	// The name that was screened
	ScreenedName string `json:"screened_name"`

	// SDN entry that matched
	SDNMatch OFACReportSDNMatch `json:"sdn_match"`

	// Screening audit data
	Screening OFACReportScreening `json:"screening"`

	// How the alert was resolved
	Resolution OFACReportResolution `json:"resolution"`

	// Fields your institution must complete before filing
	InstitutionFields OFACReportInstitutionFields `json:"institution_fields"`
}

// OFACReportSDNMatch contains the matched SDN entry details for the report.
type OFACReportSDNMatch struct {
	UID          string        `json:"uid"`
	FirstName    string        `json:"first_name,omitempty"`
	LastName     string        `json:"last_name,omitempty"`
	Programs     []string      `json:"programs,omitempty"`
	Score        float64       `json:"score"`
	MatchSources []MatchSource `json:"match_sources,omitempty"`
}

// OFACReportScreening contains audit trail data from the screening.
type OFACReportScreening struct {
	ScreenedAt      string `json:"screened_at"`
	OFACPublishID   string `json:"ofac_publish_id,omitempty"`
	OFACPublishDate string `json:"ofac_publish_date,omitempty"`
	TraceID         string `json:"trace_id"`
}

// OFACReportResolution contains the alert resolution details.
type OFACReportResolution struct {
	Status      string `json:"status"`
	Disposition string `json:"disposition"`
	Reason      string `json:"reason"`
	ResolvedBy  string `json:"resolved_by"`
	ResolvedAt  string `json:"resolved_at"`
	GLCitation  string `json:"gl_citation,omitempty"`
	Note        string `json:"note,omitempty"`
}

// OFACReportInstitutionFields are fields Noble Sight cannot provide.
// Your institution must complete these before filing with OFAC.
type OFACReportInstitutionFields struct {
	TransactionDescription *string `json:"transaction_description"`
	TransactionValue       *string `json:"transaction_value"`
	Instructions           string  `json:"instructions"`
}

// ErrAlertNotTrueMatch is returned when requesting an OFAC report for an alert
// that is not resolved as a true match with a reportable disposition.
var ErrAlertNotTrueMatch = errors.New("OFAC report requires a true match alert with blocked or rejected disposition")

// Error code for OFAC report precondition failures.
const CodeAlertNotReportable = "alert_not_reportable"

// =============================================================================
// GET /v1/account - Account overview for the authenticated API key
// =============================================================================

// AccountResponse returns the account overview for the authenticated API key.
// Combines tier, usage, billing status, and rate limits in a single call.
type AccountResponse struct {
	// Client identifier
	ClientID string `json:"client_id"`

	// Current API key prefix (for identification)
	KeyPrefix string `json:"key_prefix"`

	// Current tier: free, standard, premium, enterprise
	Tier string `json:"tier"`

	// Billing status: "active", "none" (free tier), "past_due", "canceled"
	BillingStatus string `json:"billing_status"`

	// Usage in the current rate limit window
	Usage AccountUsage `json:"usage"`

	// Features available on this tier
	Features AccountFeatures `json:"features"`

	// Capability scopes granted to this key. Every key has "api" (REST access).
	// Additional scopes like "mcp" gate access to specific surfaces — the MCP
	// server sends X-Noble-Client: mcp on every request, which the API rejects
	// with 403 (code: scope_required) when "mcp" is not present here. Agents
	// can read this to discover whether MCP setup will work before attempting.
	Scopes []string `json:"scopes"`
}

// AccountUsage contains current usage stats.
type AccountUsage struct {
	// Requests used in the current window
	Used int `json:"used"`

	// Total request limit for the current window
	Limit int `json:"limit"`

	// Requests remaining
	Remaining int `json:"remaining"`

	// Rate limit window: "day" (free) or "month" (paid)
	Window string `json:"window"`
}

// AccountFeatures describes what the current tier unlocks.
type AccountFeatures struct {
	Screening         bool `json:"screening"`
	DeepScreen        bool `json:"deep_screen"`
	BatchScreening    bool `json:"batch_screening"`
	PortfolioMonitor  bool `json:"portfolio_monitoring"`
	ComplianceExports bool `json:"compliance_exports"`
	AlertManagement   bool `json:"alert_management"`
	MaxBatchSize      int  `json:"max_batch_size"`

	// MCP reports whether this key can use the Model Context Protocol server —
	// the 'mcp' scope. Granted on every tier.
	MCP bool `json:"mcp"`

	// ConfidentialPortfolio reports whether this key holds the Confidential
	// Portfolio (BYOK) add-on: portfolio PII stored encrypted at rest under a
	// customer-controlled KMS key. Enterprise add-on; manage the key via
	// /v1/portfolio/key.
	ConfidentialPortfolio bool `json:"confidential_portfolio"`

	// AlertThreshold is the minimum match score that triggers alert creation.
	// Screenings with a highest match score below this value do not generate alerts.
	// Default: 80. Configured per tenant; valid range 50-95 (bounds are
	// database-enforced so no configuration can silently suppress
	// strong-match alerts).
	AlertThreshold int `json:"alert_threshold"`
}

// =============================================================================
// /v1/portfolio/key - Confidential Portfolio (BYOK) key management
//
//	GET    /v1/portfolio/key  → key status/metadata (never key material)
//	POST   /v1/portfolio/key  → provision a per-customer KMS-wrapped key
//	DELETE /v1/portfolio/key?confirm=<client_id>  → revoke + crypto-shred
//
// Requires the Confidential Portfolio add-on (RequireConfidentialPortfolio).
// DELETE is irreversible: it destroys the KMS key, permanently rendering all of
// the customer's encrypted portfolio PII unreadable. It demands the client_id as
// a confirmation query parameter to prevent accidental destruction.
//
// Capacity: encrypted portfolios are supported up to ~1,000,000 entities.
// Ciphertext cannot be probed through the trigram index, so portfolio
// monitoring decrypts the encrypted subset in memory on each list delta —
// a cost that grows linearly with encrypted rows. Larger encrypted portfolios
// require an engineering conversation (searchable-encryption roadmap) before
// onboarding; plaintext portfolios have no such ceiling.
// =============================================================================

// PortfolioKeyStatusResponse reports the state of a client's Confidential
// Portfolio encryption key. It never includes key material (DEK or wrapped DEK).
type PortfolioKeyStatusResponse struct {
	// Status is "active" (key in use), "revoked" (crypto-shredded), or "none"
	// (never provisioned).
	Status    string `json:"status"`
	CreatedAt string `json:"created_at,omitempty"`
	RevokedAt string `json:"revoked_at,omitempty"`
}

// =============================================================================
// POST /v1/account/checkout - Create a Stripe Checkout session for tier upgrade
// =============================================================================

// CheckoutRequest is the input for creating a billing checkout session.
type CheckoutRequest struct {
	// Target tier to upgrade to: "standard", "premium"
	// Enterprise requires contacting sales.
	Tier string `json:"tier"`

	// AddOn, when set, purchases an add-on instead of a tier upgrade. The only
	// supported value is "confidential_portfolio" (the BYOK Enterprise add-on),
	// which requires the account already be on the Enterprise tier.
	AddOn string `json:"add_on,omitempty"`
}

// AddOnConfidentialPortfolio is the CheckoutRequest.AddOn value that purchases
// the Confidential Portfolio (BYOK) Enterprise add-on.
const AddOnConfidentialPortfolio = "confidential_portfolio"

// CheckoutResponse returns the Stripe Checkout URL for payment.
type CheckoutResponse struct {
	// URL to redirect the user to for payment
	CheckoutURL string `json:"checkout_url"`
}

// Error codes for billing operations.
const (
	// CodeDeepScreenUnavailable: deep_screen was requested (and the tier
	// allows it) but this deployment has no AI backend configured. 503 —
	// the request is NOT silently downgraded to standard screening; retry
	// without deep_screen or contact support. (Runtime AI failures degrade
	// with an explicit deep_screen_fallback_reason instead.)
	CodeDeepScreenUnavailable = "deep_screen_unavailable"

	CodeBillingNotEnabled = "billing_not_enabled"
	CodeAlreadyOnTier     = "already_on_tier"
	CodeInvalidTier       = "invalid_upgrade_tier"
)

// =============================================================================
// POST /v1/watchlist - Add an internal watchlist entry
// =============================================================================

// WatchlistAddRequest is the input for adding a watchlist entry.
type WatchlistAddRequest struct {
	// Full name to add to the watchlist (required)
	FullName string `json:"full_name"`

	// List name for categorization (e.g., "SAR Subjects", "Exited Customers").
	// Defaults to "default".
	ListName string `json:"list_name,omitempty"`

	// Why this entity is on the watchlist (recommended for audit trail)
	Reason string `json:"reason,omitempty"`

	// Government identifier (optional)
	IDNumber string `json:"id_number,omitempty"`

	// ID type (e.g., "Passport", "SSN") (optional)
	IDType string `json:"id_type,omitempty"`

	// Country code ISO 3166-1 alpha-2 (optional)
	Country string `json:"country,omitempty"`

	// Entity type: "individual" or "entity" (default: "individual")
	EntityType string `json:"entity_type,omitempty"`

	// Expiration date in RFC 3339 format (optional). Entry stops matching after this date.
	ExpiresAt string `json:"expires_at,omitempty"`
}

// WatchlistResponse is a single watchlist entry.
type WatchlistResponse struct {
	// Entry ID
	ID int64 `json:"id"`

	// Full name on the watchlist
	FullName string `json:"full_name"`

	// List category
	ListName string `json:"list_name"`

	// Why this entity was added
	Reason string `json:"reason,omitempty"`

	// Government identifier
	IDNumber string `json:"id_number,omitempty"`

	// ID type
	IDType string `json:"id_type,omitempty"`

	// Country code
	Country string `json:"country,omitempty"`

	// Entity type
	EntityType string `json:"entity_type"`

	// Who added this entry
	AddedBy string `json:"added_by"`

	// When this entry was created (RFC 3339)
	CreatedAt string `json:"created_at"`

	// When this entry expires (RFC 3339), if set
	ExpiresAt string `json:"expires_at,omitempty"`

	// Entry status: "active" or "removed"
	Status string `json:"status"`
}

// GET /v1/watchlist returns List[WatchlistResponse], cursor-paginated by entry
// id (?after=&limit=), ordered id ascending — see the "Pagination" contract.
// Optional filters: list_name, status (defaults to "active").

// MaxWatchlistNameLength is the maximum length for a watchlist entry name.
const MaxWatchlistNameLength = 500

// MaxWatchlistImportSize is the maximum entries in a single bulk import.
const MaxWatchlistImportSize = 10_000

// =============================================================================
// Webhooks — POST /v1/webhooks, GET /v1/webhooks, DELETE /v1/webhooks?id=N
// =============================================================================

// Webhook limits.
const (
	// MaxWebhooksPerTenant is the maximum number of active webhook registrations per tenant.
	MaxWebhooksPerTenant = 5

	// MinWebhookSecretLength is the minimum length for the shared HMAC secret.
	MinWebhookSecretLength = 32

	// MaxWebhookURLLength is the maximum allowed URL length.
	MaxWebhookURLLength = 2048

	// MaxWebhookDeliveryPasses is the number of delivery passes before an
	// alert event is marked failed. Passes are scheduled on a persisted
	// backoff spanning roughly 10 hours and survive server restarts; each
	// pass makes one POST per registered endpoint that has not yet accepted
	// the event. Events carry a stable evt_* id (payload "id" and
	// X-Noble-Event-ID header) so consumers can deduplicate at-least-once
	// delivery. A delivery failure never suppresses the alert itself —
	// GET /v1/alerts remains the system of record.
	MaxWebhookDeliveryPasses = 8
)

// WebhookCreateRequest registers a URL to receive alert notifications.
type WebhookCreateRequest struct {
	// HTTPS URL to receive POST notifications (required)
	URL string `json:"url"`

	// Shared secret for HMAC-SHA256 signature verification (required, min 32 chars).
	// Noble signs every outbound payload with this secret. The customer verifies
	// the X-Noble-Signature header to confirm authenticity.
	Secret string `json:"secret"`
}

// WebhookResponse is a registered webhook. The URL is masked after creation.
type WebhookResponse struct {
	ID        int64  `json:"id"`
	URL       string `json:"url"`
	Status    string `json:"status"`
	CreatedAt string `json:"created_at"`
}

// GET /v1/webhooks returns List[WebhookResponse]. Unlike the other collection
// endpoints it is NOT paginated — a tenant holds at most MaxWebhooksPerTenant
// registrations, so the endpoint returns them all in data and ignores any
// ?after=/?limit= cursor params.

// WebhookStatsResponse is the count companion to GET /v1/webhooks. Because
// registrations are capped per tenant, the headline value is how much of that
// budget remains — "how many more webhooks can I register?"
type WebhookStatsResponse struct {
	// Total registered webhooks for the tenant.
	Total int `json:"total"`

	// ByStatus counts registrations by status (e.g. active, disabled).
	ByStatus map[string]int `json:"by_status"`

	// Limit is the per-tenant cap (MaxWebhooksPerTenant).
	Limit int `json:"limit"`

	// Remaining registrations available before hitting Limit (never negative).
	Remaining int `json:"remaining"`
}

// WebhookEvent is the payload POSTed to customer webhook URLs.
// Customers verify authenticity via the X-Noble-Signature header:
//
//	signature = HMAC-SHA256(secret, request_body)
//	header:     X-Noble-Signature: sha256=<hex>
type WebhookEvent struct {
	// Unique event ID (evt_ prefix)
	ID string `json:"id"`

	// Event type: "alert.created"
	Type string `json:"type"`

	// When this event was generated (RFC 3339)
	CreatedAt string `json:"created_at"`

	// Event payload (AlertResponse JSON)
	Data json.RawMessage `json:"data"`
}

// =============================================================================
// GET /status - Public system status (no auth required)
// =============================================================================

// StatusResponse reports system health for customer monitoring dashboards.
// No authentication required — compliance teams need to check this independently.
type StatusResponse struct {
	// Overall status: "operational", "degraded", "outage"
	Status string `json:"status"`

	// Human-readable description
	Message string `json:"message"`

	// Component health
	Components StatusComponents `json:"components"`

	// When this status was generated (RFC 3339)
	Timestamp string `json:"timestamp"`
}

// StatusComponents reports health of individual subsystems.
type StatusComponents struct {
	// Database connectivity
	Database ComponentStatus `json:"database"`

	// Screening API availability
	Screening ComponentStatus `json:"screening"`

	// Sanctions list ingestion freshness, from the same computation as
	// GET /v1/lists: "operational" when every deployed list was polled
	// within the freshness window (24h), "degraded" when any list is
	// stale — screening continues against the last imported version;
	// query GET /v1/lists for per-list status. "outage" when freshness
	// cannot be determined (database unreachable). A degraded lists
	// component degrades the overall status.
	Lists ComponentStatus `json:"lists"`
}

// ComponentStatus is the health of a single component.
type ComponentStatus struct {
	// Status: "operational", "degraded", "outage"
	Status string `json:"status"`

	// Response time in milliseconds (where measurable)
	LatencyMs *int64 `json:"latency_ms,omitempty"`
}

// Status constants for system health reporting.
const (
	StatusOperational = "operational"
	StatusDegraded    = "degraded"
	StatusOutage      = "outage"
)

// =============================================================================
// Headers
// =============================================================================
//
// X-API-Key (required for /v1/* endpoints): API key for authentication.
//            Keys use the format: noble_live_ + 32 hex characters.
//
//   Screening API tiers:
//     Free:       100 screenings/day   ($0/mo)
//     Standard:     5,000 screenings/mo  ($199/mo)
//     Premium: 25,000 screenings/mo ($499/mo)
//     Enterprise:   100,000+ screenings/mo (custom pricing)
//
//   Portfolio Monitoring: per-entity add-on, available on any paid tier.
//
// X-Trace-ID (optional): Client-provided trace ID for audit logging.
//                        Will be included in logs and database query comments.
//
// X-Noble-Client (optional): Identifies the official Noble client making the
//                            request. Currently recognized values:
//                              mcp  — the `noble mcp` Model Context Protocol
//                                     server. When this header is present, the
//                                     API key must carry the "mcp" scope or
//                                     the request is rejected 403
//                                     (code: scope_required).
//                            Third-party clients should not set this header.
//                            Setting it without the matching scope is harmless
//                            but produces a 403 instead of normal access.
//
// Response headers on every request:
//   X-Request-Id:          Server-generated request ID (req_ + 16 hex chars).
//
// Response headers on authenticated requests:
//   X-RateLimit-Limit:     Request limit for this key (daily or monthly).
//   X-RateLimit-Remaining: Requests remaining in current window.
//   X-RateLimit-Window:    "day" (Free) or "month" (paid tiers).
//   X-RateLimit-Reset:     Unix timestamp when the rate limit window resets.
//
// Response headers on 429 (rate limit exceeded):
//   Retry-After:           Seconds until the rate limit window resets.
//
// Response headers on requests authenticated by a trial/comp key:
//   X-Trial-Ends-At:        RFC 3339 timestamp when the trial expires.
//   X-Trial-Days-Remaining: Whole days until trial expiry (0 on the final day).
//
// Response on 402 (trial expired):
//   Error code: trial_expired. The customer's trial_ends_at has passed and a
//   nightly job has flipped the key's status to "expired". Contact sales to
//   convert or extend.