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"
)

// =============================================================================
// 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)
	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, or a digital currency
	// (crypto wallet) address. 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 — uppercased with
	// spaces, dashes, dots, and slashes stripped.
	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"`
}

// 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"`

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

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

	// 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"`

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

// 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
)

// 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-2.5-flash").
	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.
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"
)

// 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"`

	// 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"`
}

// =============================================================================
// 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: ofac, uk, eu, france, belgium, netherlands, un, canada, australia", l)
		}
	}
	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"
	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"
	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"
	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"`
}

// 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"`
}

// 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"`

	// 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"`
}

// =============================================================================
// 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.
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 for screenings persisted before this field existed.
	RequestID string `json:"request_id,omitempty"`

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

	// Original screening request
	Request ScreenRequest `json:"request"`

	// Original screening response
	Response ScreenResponse `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. 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/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/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 screening was initiated: "console", "api", "batch", "monitoring"
	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 or "apikey:<prefix>")
	Actor string `json:"actor"`

	// Action type: "status_change", "assigned", "note", "escalated", "reopened"
	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/{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"`

	// AlertThreshold is the minimum match score (0-100) that triggers alert creation.
	// Screenings with a highest match score below this value do not generate alerts.
	// Default: 80. Configured per tenant.
	AlertThreshold int `json:"alert_threshold"`
}

// =============================================================================
// 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"`
}

// 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 (
	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

	// MaxWebhookRetries is the number of delivery attempts before marking as failed.
	MaxWebhookRetries = 3
)

// 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"`
}

// 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.