/**
 * TypeScript types for the SentryAgent.ai AgentIdP SDK.
 * All request and response shapes derived from the AgentIdP OpenAPI 3.0 specs.
 */

// ─────────────────────────────────────────────────────────────────────────────
// Shared enums
// ─────────────────────────────────────────────────────────────────────────────

/** Functional classification of an AI agent. */
export type AgentType =
  | 'screener'
  | 'classifier'
  | 'orchestrator'
  | 'extractor'
  | 'summarizer'
  | 'router'
  | 'monitor'
  | 'custom';

/** Lifecycle status of an AI agent. */
export type AgentStatus = 'active' | 'suspended' | 'decommissioned';

/** Target deployment environment. */
export type DeploymentEnv = 'development' | 'staging' | 'production';

/** Lifecycle status of a credential. */
export type CredentialStatus = 'active' | 'revoked';

/** OAuth 2.0 scopes supported by AgentIdP. */
export type OAuthScope = 'agents:read' | 'agents:write' | 'tokens:read' | 'audit:read';

/** Audit event action types. */
export type AuditAction =
  | 'agent.created'
  | 'agent.updated'
  | 'agent.decommissioned'
  | 'agent.suspended'
  | 'agent.reactivated'
  | 'token.issued'
  | 'token.revoked'
  | 'token.introspected'
  | 'credential.generated'
  | 'credential.rotated'
  | 'credential.revoked'
  | 'auth.failed';

/** Outcome of an audited action. */
export type AuditOutcome = 'success' | 'failure';

// ─────────────────────────────────────────────────────────────────────────────
// Agent Registry
// ─────────────────────────────────────────────────────────────────────────────

/** A registered AI agent identity. */
export interface Agent {
  agentId: string;
  email: string;
  agentType: AgentType;
  version: string;
  capabilities: string[];
  owner: string;
  deploymentEnv: DeploymentEnv;
  status: AgentStatus;
  createdAt: string;
  updatedAt: string;
}

/** Request body for registering a new agent. */
export interface RegisterAgentRequest {
  email: string;
  agentType: AgentType;
  version: string;
  capabilities: string[];
  owner: string;
  deploymentEnv: DeploymentEnv;
}

/** Request body for updating agent metadata (all fields optional). */
export interface UpdateAgentRequest {
  agentType?: AgentType;
  version?: string;
  capabilities?: string[];
  owner?: string;
  deploymentEnv?: DeploymentEnv;
  status?: AgentStatus;
}

/** Query parameters for listing agents. */
export interface ListAgentsParams {
  page?: number;
  limit?: number;
  owner?: string;
  agentType?: AgentType;
  status?: AgentStatus;
}

/** Paginated list of agents. */
export interface PaginatedAgents {
  data: Agent[];
  total: number;
  page: number;
  limit: number;
}

// ─────────────────────────────────────────────────────────────────────────────
// Credential Management
// ─────────────────────────────────────────────────────────────────────────────

/** A credential record (clientSecret never included). */
export interface Credential {
  credentialId: string;
  clientId: string;
  status: CredentialStatus;
  createdAt: string;
  expiresAt: string | null;
  revokedAt: string | null;
}

/** A credential record with the plain-text secret — returned once only on create/rotate. */
export interface CredentialWithSecret extends Credential {
  clientSecret: string;
}

/** Optional request body for generating or rotating a credential. */
export interface GenerateCredentialRequest {
  expiresAt?: string;
}

/** Query parameters for listing credentials. */
export interface ListCredentialsParams {
  page?: number;
  limit?: number;
  status?: CredentialStatus;
}

/** Paginated list of credentials. */
export interface PaginatedCredentials {
  data: Credential[];
  total: number;
  page: number;
  limit: number;
}

// ─────────────────────────────────────────────────────────────────────────────
// OAuth 2.0 Tokens
// ─────────────────────────────────────────────────────────────────────────────

/** OAuth 2.0 access token response. */
export interface TokenResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
  scope: string;
}

/** Token introspection response (RFC 7662). */
export interface IntrospectResponse {
  active: boolean;
  sub?: string;
  client_id?: string;
  scope?: string;
  token_type?: string;
  iat?: number;
  exp?: number;
}

// ─────────────────────────────────────────────────────────────────────────────
// Audit Log
// ─────────────────────────────────────────────────────────────────────────────

/** An immutable audit event record. */
export interface AuditEvent {
  eventId: string;
  agentId: string;
  action: AuditAction;
  outcome: AuditOutcome;
  ipAddress: string;
  userAgent: string;
  metadata: Record<string, unknown>;
  timestamp: string;
}

/** Query parameters for the audit log. */
export interface QueryAuditLogParams {
  page?: number;
  limit?: number;
  agentId?: string;
  action?: AuditAction;
  outcome?: AuditOutcome;
  fromDate?: string;
  toDate?: string;
}

/** Paginated list of audit events. */
export interface PaginatedAuditEvents {
  data: AuditEvent[];
  total: number;
  page: number;
  limit: number;
}

// ─────────────────────────────────────────────────────────────────────────────
// SDK Config
// ─────────────────────────────────────────────────────────────────────────────

/** Configuration for AgentIdPClient. */
export interface AgentIdPClientConfig {
  /** Base URL of the AgentIdP server, e.g. http://localhost:3000/api/v1 */
  baseUrl: string;
  /** The agent's clientId (agentId UUID). */
  clientId: string;
  /** The agent's clientSecret. */
  clientSecret: string;
  /** OAuth 2.0 scopes to request. Defaults to all scopes. */
  scopes?: OAuthScope[];
}
