Authentication and Authorization Types

interface LightdashUser {
  userUuid: string;
  firstName: string;
  lastName: string;
  email: string;
  organizationUuid?: string;
  organizationName?: string;
  organizationCreatedAt?: Date;
  isTrackingAnonymized: boolean;
  isMarketingOptedIn: boolean;
  isSetupComplete: boolean;
  isActive: boolean;
  role?: OrganizationMemberRole;
  abilityRules?: unknown;
}

interface SessionUser extends LightdashUser {
  userId: number;
  ability: MemberAbility;
  isActive: boolean;
  isMarketingOptedIn: boolean;
  isSetupComplete: boolean;
  isEmailVerified: boolean;
  locale: string;
}

/**
 * Serialized account for API responses
 * Omits ability and abilityRules for tsoa compatibility
 */
type SerializedAccount = Omit<Account, 'user' | keyof AccountHelpers> & {
  user: Omit<Account['user'], 'ability' | 'abilityRules'>;
};

/**
 * API response for getting account information
 */
type ApiGetAccountResponse = {
  status: 'ok';
  results: SerializedAccount;
};

interface LightdashUserWithOrg extends LightdashUser {
  organizationUuid: string;
  organizationName: string;
}

interface UpdatedByUser {
  userUuid: string;
  firstName: string;
  lastName: string;
}

// Authorization ability type (from @casl/ability)
// For complete Subject and PossibleAbilities types, see authorization.md
type AbilityAction = 'create' | 'delete' | 'export' | 'manage' | 'promote' | 'update' | 'view';

type PossibleAbilities = [
  AbilityAction,
  Subject | ForcedSubject<Exclude<Subject, 'all'>>
];

type MemberAbility = Ability<PossibleAbilities>;

interface UserAllowedOrganization {
  organizationUuid: string;
  name: string;
  membersCount: number;
  role: OrganizationMemberRole;
}

interface IntrinsicUserAttributes {
  user_uuid: string;
  email: string;
  organization_id: string;
  is_admin: boolean;
  groups: string[];
  role: string;
}

function isUserWithOrg(user: LightdashUser): user is LightdashUserWithOrg;
function getIntrinsicUserAttributes(user: SessionUser): IntrinsicUserAttributes;

import {
  type LightdashUserWithAbilityRules,
  type OpenIdUser,
  type ApiGetAuthenticatedUserResponse,
  type ApiGetLoginOptionsResponse,
  type ApiRegisterUserResponse,
  type ApiUserAllowedOrganizationsResponse,
  type LoginOptionTypes,
  type LoginOptions,
  type ApiSpaceResponse,
  type ApiSpaceSummaryListResponse,
  type OnbordingRecord,
  LocalIssuerTypes,
  isOpenIdUser,
  assertEmbeddedAuth,
  assertIsAccountWithOrg,
  assertSessionAuth
} from '@lightdash/common';

/**
 * Lightdash user with CASL ability rules included
 */
interface LightdashUserWithAbilityRules extends LightdashUser {
  abilityRules: unknown[];
}

/**
 * OpenID Connect user type
 */
interface OpenIdUser {
  openId: {
    subject: string;
    issuer: string;
    issuerType: LocalIssuerTypes;
    email: string;
    firstName?: string;
    lastName?: string;
  };
}

/**
 * Enum for local issuer types
 */
enum LocalIssuerTypes {
  GOOGLE = 'google',
  OKTA = 'okta',
  ONELOGIN = 'onelogin',
  AZUREAD = 'azuread',
  OIDC = 'oidc',
}

/**
 * Union type of all login option types
 */
type LoginOptionTypes = 'password' | 'google' | 'okta' | 'oneLogin' | 'azuread' | 'oidc';

/**
 * Login options available for authentication
 */
type LoginOptions = {
  forceRedirect: boolean;
  redirectUri?: string;
  showOptions: LoginOptionTypes[];
};

/**
 * API response for getting authenticated user
 */
type ApiGetAuthenticatedUserResponse = {
  status: 'ok';
  results: SessionUser;
};

/**
 * API response for getting login options
 */
type ApiGetLoginOptionsResponse = {
  status: 'ok';
  results: LoginOptions;
};

/**
 * API response for user registration
 */
type ApiRegisterUserResponse = {
  status: 'ok';
  results: {
    userUuid: string;
  };
};

/**
 * API response for user's allowed organizations
 */
type ApiUserAllowedOrganizationsResponse = {
  status: 'ok';
  results: UserAllowedOrganization[];
};

/**
 * Onboarding record for tracking user onboarding progress
 * Note: This may be a typo in the source for "OnboardingRecord"
 */
type OnbordingRecord = {
  organizationUuid: string;
  ranQueryAt: Date | null;
  shownSuccessAt: Date | null;
};

/**
 * Type guard to check if user is OpenID user
 */
function isOpenIdUser(user: any): user is OpenIdUser;

/**
 * Assert that authentication is embedded auth
 * @throws Error if not embedded auth
 */
function assertEmbeddedAuth(auth: any): asserts auth is EmbeddedAuth;

/**
 * Assert that account has organization
 * @throws Error if account doesn't have organization
 */
function assertIsAccountWithOrg(account: any): asserts account is AccountWithOrg;

/**
 * Assert that authentication is session auth
 * @throws Error if not session auth
 */
function assertSessionAuth(auth: any): asserts auth is SessionAuth;

/**
 * API response for getting a single space
 */
type ApiSpaceResponse = {
  status: 'ok';
  results: Space;
};

/**
 * API response for listing space summaries
 */
type ApiSpaceSummaryListResponse = {
  status: 'ok';
  results: SpaceSummary[];
};

interface Space {
  organizationUuid: string;
  uuid: string;
  name: string;
  isPrivate: boolean;
  pinnedListUuid: string | null;
  pinnedListOrder: number | null;
  dashboards: SpaceDashboard[];
  queries: SpaceQuery[];
  access: SpaceShare[];
  projectUuid: string;
  slug: string;
  chartCount: number;
  dashboardCount: number;
  groupsAccess: SpaceGroup[];
}

interface SpaceSummary {
  organizationUuid: string;
  uuid: string;
  name: string;
  isPrivate: boolean;
  pinnedListUuid: string | null;
  pinnedListOrder: number | null;
  projectUuid: string;
  userAccess: SpaceShare;
  chartCount: number;
  dashboardCount: number;
  access: SpaceShare[];
  slug: string;
}

interface CreateSpace {
  name: string;
  isPrivate?: boolean;
  access?: SpaceShare[];
  tags?: string[];
}

interface UpdateSpace {
  name?: string;
  isPrivate?: boolean;
  access?: SpaceShare[];
}

interface SpaceShare {
  userUuid: string;
  firstName: string;
  lastName: string;
  email: string;
  role: SpaceMemberRole;
  hasDirectAccess: boolean;
  inheritedFrom?: string;
  inheritedRole?: SpaceMemberRole;
}

interface SpaceGroup {
  groupUuid: string;
  groupName: string;
  spaceRole: SpaceMemberRole;
}

enum SpaceMemberRole {
  VIEWER = 'viewer',
  EDITOR = 'editor',
  ADMIN = 'admin',
}

interface Group {
  /** The group's UUID */
  uuid: string;
  /** A friendly name for the group */
  name: string;
  /** The time that the group was created */
  createdAt: Date;
  /** The UUID of the user that created the group */
  createdByUserUuid: string | null;
  /** The time that the group was last updated */
  updatedAt: Date;
  /** The UUID of the user that last updated the group */
  updatedByUserUuid: string | null;
  /** The UUID of the organization that the group belongs to */
  organizationUuid: string;
}

interface CreateGroup extends Pick<Group, 'name'> {
  members?: Pick<GroupMember, 'userUuid'>[];
}

type UpdateGroup = Pick<Group, 'name'>;

/** A summary for a Lightdash user within a group */
interface GroupMember {
  /** Unique id for the user */
  userUuid: string;
  /** Primary email address for the user */
  email: string;
  /** The user's first name */
  firstName: string;
  /** The user's last name */
  lastName: string;
}

interface GroupMembership {
  groupUuid: string;
  userUuid: string;
}

/** Details for a group including a list of the group's members */
interface GroupWithMembers extends Group {
  /** A list of the group's members */
  members: GroupMember[];
  memberUuids: string[];
}

function isGroupWithMembers(
  g: Group | GroupWithMembers
): g is GroupWithMembers;

interface UpdateGroupWithMembers {
  name?: string;
  members?: Pick<GroupMember, 'userUuid'>[];
}

interface ApiGroupMembersResponse {
  status: 'ok';
  results: GroupMember[];
}

interface ApiGroupResponse {
  status: 'ok';
  results: Group | GroupWithMembers;
}

interface ApiCreateGroupResponse {
  status: 'ok';
  results: GroupWithMembers;
}

interface ApiGroupListResponse {
  status: 'ok';
  results: KnexPaginatedData<Group[] | GroupWithMembers[]>;
}

interface ProjectAccess {
  projectUuid: string;
  userUuid: string;
  roleUuid: string;
  roleName: string;
  firstName: string;
  lastName: string;
}

interface GroupProjectAccess {
  groupUuid: string;
  projectUuid: string;
  roleUuid: string;
  roleName: string;
  groupName: string;
}

interface Role {
  roleUuid: string;
  name: string;
  description: string | null;
  organizationUuid: string | null; // System roles don't have an organization
  ownerType: 'user' | 'system';
  createdBy: string | null;
  createdAt: Date | null; // System roles don't have dates
  updatedAt: Date | null;
}

interface RoleWithScopes extends Role {
  scopes: string[];
}

interface CreateRole {
  name: string;
  description?: string;
  scopes?: string[];
}

interface UpdateRole {
  name?: string;
  description?: string;
  scopes?: {
    add: string[];
    remove: string[];
  };
}

interface AddScopesToRole {
  scopeNames: string[];
}

interface ApiGetRolesResponse {
  status: 'ok';
  results: Role[] | RoleWithScopes[];
}

interface ApiRoleWithScopesResponse {
  status: 'ok';
  results: RoleWithScopes;
}

interface ApiDefaultRoleResponse {
  status: 'ok';
  results: Role;
}

type ApiDeleteRoleResponse = ApiSuccessEmpty;

type ApiRemoveScopeFromRoleResponse = ApiSuccessEmpty;

type ApiUnassignRoleFromUserResponse = ApiSuccessEmpty;

interface ApiGetProjectAccessResponse {
  status: 'ok';
  results: {
    users: ProjectAccess[];
    groups: GroupProjectAccess[];
  };
}

interface RoleAssignment {
  roleId: string;
  roleName: string;
  ownerType: 'user' | 'system';
  assigneeType: 'user' | 'group';
  assigneeId: string;
  assigneeName: string;
  organizationId?: string; // for org-level assignments
  projectId?: string; // for project-level assignments
  createdAt: Date;
  updatedAt: Date;
}

interface CreateRoleAssignmentRequest {
  roleId: string;
  assigneeType: 'user' | 'group';
  assigneeId: string;
}

interface CreateUserRoleAssignmentRequest {
  roleId: string;
}

interface CreateGroupRoleAssignmentRequest {
  roleId: string;
}

interface UpdateRoleAssignmentRequest {
  roleId: string;
}

interface UpsertUserRoleAssignmentRequest {
  roleId: string;
  sendEmail?: boolean;
}

interface ApiRoleAssignmentResponse {
  status: 'ok';
  results: RoleAssignment;
}

interface ApiRoleAssignmentListResponse {
  status: 'ok';
  results: RoleAssignment[];
}

enum AuthTokenPrefix {
  SCIM = 'scim_',
  SERVICE_ACCOUNT = 'ldsvc_',
  PERSONAL_ACCESS_TOKEN = 'ldpat_',
  OAUTH_APP = 'ldapp_',
  OAUTH_REFRESH = 'ldref_',
}

type AuthType = 'session' | 'pat' | 'service-account' | 'jwt' | 'oauth';

type Authentication =
  | PersonalAccessTokenAuth
  | ServiceAccountAuth
  | JwtAuth
  | OauthAuth;

interface PersonalAccessTokenAuth {
  token: string;
  type: 'personalAccessToken';
}

interface ServiceAccountAuth {
  token: string;
  type: 'serviceAccount';
}

interface JwtAuth {
  token: string;
  type: 'jwt';
}

interface OauthAuth {
  token: string;
  type: 'oauth';
}

/**
 * Personal Access Token for API authentication
 */
interface PersonalAccessToken {
  /** Unique identifier for the token */
  uuid: string;
  /** Timestamp when the token was created */
  createdAt: Date;
  /** Timestamp when the token was last used */
  lastUsedAt: Date | null;
  /** Timestamp when the token was rotated */
  rotatedAt: Date | null;
  /** Optional expiration date for the token */
  expiresAt: Date | null;
  /** Human-readable description of the token's purpose */
  description: string;
}

/**
 * Personal Access Token with the actual token value (only returned on creation)
 */
interface PersonalAccessTokenWithToken extends PersonalAccessToken {
  /** The actual token string (only included when first created) */
  token: string;
}

/**
 * Data required to create a new Personal Access Token
 */
interface CreatePersonalAccessToken {
  /** Optional expiration date for the token */
  expiresAt: Date | null;
  /** Human-readable description of the token's purpose */
  description: string;
  /** Whether this token was automatically generated by the system */
  autoGenerated: boolean;
}

interface EmbedContent {
  type: 'dashboard' | 'chart';
  uuid: string;
}

interface EmbedAccess {
  content: EmbedContent;
  filtering?: DashboardFilterInteractivityOptions;
  controls?: UserAccessControls;
  parameters?: ParameterInteractivityOptions;
}

interface UserAccessControls {
  canViewProject: boolean;
  canEditContent: boolean;
  canManageSpaces: boolean;
  canManageUsers: boolean;
  canManageOrganization: boolean;
}

/**
 * Helper methods for account type checking
 */
interface AccountHelpers {
  /** Is this user logged in? */
  isAuthenticated: () => boolean;
  /** Is this account for a known user in our database? */
  isRegisteredUser: () => boolean;
  /** Is this account for an anonymous external user? */
  isAnonymousUser: () => boolean;
  /** Is this account for a session user? */
  isSessionUser: () => boolean;
  /** Is this account for a JWT user? */
  isJwtUser: () => boolean;
  /** Is this account for a service account? */
  isServiceAccount: () => boolean;
  /** Is this account for a personal access token? */
  isPatUser: () => boolean;
  /** Is this account for a oauth user? */
  isOauthUser: () => boolean;
}

/**
 * Base account interface that all account types extend
 */
interface BaseAccount {
  organization: AccountOrganization;
  authentication: Authentication;
  user: AccountUser;
}

/**
 * Account for registered users with session authentication
 */
interface SessionAccount extends BaseAccount, AccountHelpers {
  authentication: SessionAuth;
  user: LightdashSessionUser;
}

/**
 * Account for anonymous users with JWT authentication (embeds)
 */
interface AnonymousAccount extends BaseAccount, AccountHelpers {
  authentication: JwtAuth;
  user: ExternalUser;
  access: EmbedAccess;
  embed: OssEmbed;
}

/**
 * Account for personal access token authentication
 */
interface ApiKeyAccount extends BaseAccount, AccountHelpers {
  authentication: PersonalAccessTokenAuth;
  user: LightdashSessionUser;
}

/**
 * Account for service account authentication
 */
interface ServiceAcctAccount extends BaseAccount, AccountHelpers {
  authentication: ServiceAccountAuth;
  user: LightdashSessionUser;
}

/**
 * Account for OAuth authentication
 */
interface OauthAccount extends BaseAccount, AccountHelpers {
  authentication: OauthAuth;
  user: LightdashSessionUser;
}

/**
 * Union type of all account types
 */
type Account =
  | SessionAccount
  | AnonymousAccount
  | ApiKeyAccount
  | ServiceAcctAccount
  | OauthAccount;

interface OssEmbed {
  embedUuid: string;
  projectUuid: string;
  enabled: boolean;
  createdAt: Date;
  content: EmbedContent;
  access: EmbedAccess[];
  secret: string;
}

/**
 * A user attribute definition for row-level security and personalization
 */
interface UserAttribute {
  /** Unique identifier for the attribute */
  uuid: string;
  /** Timestamp when the attribute was created */
  createdAt: Date;
  /** Name of the attribute */
  name: string;
  /** UUID of the organization this attribute belongs to */
  organizationUuid: string;
  /** Optional human-readable description */
  description?: string;
  /** User-specific attribute values */
  users: UserAttributeValue[];
  /** Group-specific attribute values */
  groups: GroupAttributeValue[];
  /** Default value when no specific value is set */
  attributeDefault: string | null;
}

/**
 * A specific user's value for an attribute
 */
interface UserAttributeValue {
  /** UUID of the user */
  userUuid: string;
  /** User's email address */
  email: string;
  /** The attribute value for this user */
  value: string;
}

/**
 * A specific group's value for an attribute
 */
interface GroupAttributeValue {
  /** UUID of the group */
  groupUuid: string;
  /** The attribute value for this group */
  value: string;
}

/**
 * Map of attribute names to arrays of values
 */
type UserAttributeValueMap = Record<string, string[]>;

/**
 * Data required to create a user-specific attribute value
 */
type CreateUserAttributeValue = Omit<UserAttributeValue, 'email'>;

/**
 * Data required to create a group-specific attribute value
 */
type CreateGroupAttributeValue = GroupAttributeValue;

/**
 * Data required to create a new user attribute
 */
interface CreateUserAttribute {
  /** Name of the attribute */
  name: string;
  /** Optional human-readable description */
  description?: string;
  /** Default value when no specific value is set */
  attributeDefault: string | null;
  /** User-specific attribute values */
  users: CreateUserAttributeValue[];
  /** Group-specific attribute values */
  groups: CreateGroupAttributeValue[];
}

/**
 * API response for listing user attributes
 */
interface ApiUserAttributesResponse {
  status: 'ok';
  results: UserAttribute[];
}

/**
 * API response for creating a user attribute
 */
interface ApiCreateUserAttributeResponse {
  status: 'ok';
  results: UserAttribute;
}

/**
 * Supported OpenID Connect identity providers
 */
enum OpenIdIdentityIssuerType {
  GOOGLE = 'google',
  OKTA = 'okta',
  ONELOGIN = 'oneLogin',
  AZUREAD = 'azuread',
  GENERIC_OIDC = 'oidc',
  SNOWFLAKE = 'snowflake',
  DATABRICKS = 'databricks',
  SLACK = 'slack',
}

/**
 * Type guard to check if a string is a valid OpenIdIdentityIssuerType
 */
function isOpenIdIdentityIssuerType(
  value: string
): value is OpenIdIdentityIssuerType;

/**
 * Data required to create a new OpenID identity
 */
type CreateOpenIdIdentity = {
  /** OIDC subject identifier from the identity provider */
  subject: string;
  /** OIDC issuer URL */
  issuer: string;
  /** Type of identity provider */
  issuerType: OpenIdIdentityIssuerType;
  /** Internal user ID to link this identity to */
  userId: number;
  /** User's email address from the identity provider */
  email: string;
  /** Optional refresh token (used for Google Drive access) */
  refreshToken?: string;
  /** Optional team ID (used for Slack) */
  teamId?: string;
};

/**
 * Data for updating an existing OpenID identity
 */
type UpdateOpenIdentity = Pick<
  CreateOpenIdIdentity,
  'subject' | 'issuer' | 'email' | 'issuerType' | 'refreshToken'
>;

/**
 * Complete OpenID identity record
 */
type OpenIdIdentity = Omit<CreateOpenIdIdentity, 'userId'> & {
  /** User UUID (replaces userId for external use) */
  userUuid: string;
  /** Timestamp when identity was created */
  createdAt: Date;
};

/**
 * Summary view of an OpenID identity
 */
type OpenIdIdentitySummary = Pick<
  OpenIdIdentity,
  'issuer' | 'email' | 'createdAt' | 'issuerType'
>;

/**
 * Data for deleting an OpenID identity
 */
type DeleteOpenIdentity = Pick<
  OpenIdIdentitySummary,
  'issuer' | 'email'
>;

interface Organization {
  organizationUuid: string;
  name: string;
  chartColors?: string[];  // Default color palette for projects
  chartDarkColors?: string[];  // Dark mode color palette
  colorPaletteUuid?: string;  // Active color palette UUID
  needsProject?: boolean;  // Organization needs a project
  defaultProjectUuid?: string;  // Default project for user login
  createdAt?: Date;
}

type CreateOrganization = Pick<Organization, 'name'>;

type UpdateOrganization = Partial<Omit<Organization, 'organizationUuid' | 'needsProject'>>;

interface ApiOrganization {
  status: 'ok';
  results: Organization;
}

interface OrganizationProject {
  projectUuid: string;
  name: string;
  type: ProjectType;
  createdByUserUuid: string | null;
  createdAt: Date;
  upstreamProjectUuid: string | null;
  warehouseType?: WarehouseTypes;
  requireUserCredentials?: boolean;
}

interface ApiOrganizationProjects {
  status: 'ok';
  results: OrganizationProject[];
}

enum OrganizationMemberRole {
  MEMBER = 'member',  // No project access by default
  VIEWER = 'viewer',  // View-only access to all projects
  INTERACTIVE_VIEWER = 'interactive_viewer',  // View + create projects
  EDITOR = 'editor',  // Create, edit, and delete projects
  DEVELOPER = 'developer',  // Same as EDITOR
  ADMIN = 'admin',  // Full organization access
}

const OrganizationMemberRoleLabels: Record<OrganizationMemberRole, string>;

function isOrganizationMemberRole(x: string): x is OrganizationMemberRole;
function getRoleDescription(role: OrganizationMemberRole): string | null;

interface OrganizationMemberProfile {
  userUuid: string;
  userCreatedAt: Date;
  userUpdatedAt: Date;
  firstName: string;
  lastName: string;
  email: string;
  organizationUuid: string;
  role: OrganizationMemberRole;
  roleUuid: string | undefined;
  isActive: boolean;  // Can user login
  isInviteExpired?: boolean;  // Has invite expired
  isPending?: boolean;  // User lacks authentication method
}

interface OrganizationMemberProfileWithGroups extends OrganizationMemberProfile {
  groups: Pick<Group, 'name' | 'uuid'>[];
}

type OrganizationMemberProfileUpdate = Pick<OrganizationMemberProfile, 'role'>;

interface ApiOrganizationMemberProfiles {
  status: 'ok';
  results: KnexPaginatedData<OrganizationMemberProfile[]>;
}

interface ApiOrganizationMemberProfile {
  status: 'ok';
  results: OrganizationMemberProfile;
}

function isOrganizationMemberProfileWithGroups(
  obj: OrganizationMemberProfile | OrganizationMemberProfileWithGroups
): obj is OrganizationMemberProfileWithGroups;

interface OnboardingRecord {
  ranQueryAt: Date | null;
  shownSuccessAt: Date | null;
}

interface OnboardingStatus {
  ranQuery: boolean;
}

interface ApiOnboardingStatusResponse {
  status: 'ok';
  results: OnboardingStatus;
}

type AllowedEmailDomainsRole =
  | OrganizationMemberRole.EDITOR
  | OrganizationMemberRole.INTERACTIVE_VIEWER
  | OrganizationMemberRole.VIEWER
  | OrganizationMemberRole.MEMBER;

type AllowedEmailDomainProjectsRole =
  | ProjectMemberRole.EDITOR
  | ProjectMemberRole.INTERACTIVE_VIEWER
  | ProjectMemberRole.VIEWER;

const AllowedEmailDomainsRoles: AllowedEmailDomainsRole[];
const AllowedEmailDomainProjectRoles: AllowedEmailDomainProjectsRole[];

interface AllowedEmailDomains {
  organizationUuid: string;
  emailDomains: string[];
  role: AllowedEmailDomainsRole;
  projects: Array<{
    projectUuid: string;
    role: AllowedEmailDomainProjectsRole;
  }>;
}

type UpdateAllowedEmailDomains = Omit<AllowedEmailDomains, 'organizationUuid'>;

interface ApiOrganizationAllowedEmailDomains {
  status: 'ok';
  results: AllowedEmailDomains;
}

function isAllowedEmailDomainsRole(
  role: OrganizationMemberRole
): role is AllowedEmailDomainsRole;

function isAllowedEmailDomainProjectRole(
  role: ProjectMemberRole | OrganizationMemberRole
): role is AllowedEmailDomainProjectsRole;

interface OrganizationColorPalette {
  colorPaletteUuid: string;
  organizationUuid: string;
  name: string;
  colors: string[];  // Light mode colors
  darkColors: string[] | null;  // Dark mode colors
  createdAt: Date;
}

interface OrganizationColorPaletteWithIsActive extends OrganizationColorPalette {
  isActive: boolean;  // Is this the active palette
}

interface CreateColorPalette {
  name: string;
  colors: string[];
  darkColors?: string[];
}

interface UpdateColorPalette {
  uuid: string;
  name?: string;
  colors?: string[];
  darkColors?: string[];
}

interface ApiColorPaletteResponse {
  status: 'ok';
  results: OrganizationColorPalette;
}

interface ApiColorPalettesResponse {
  status: 'ok';
  results: OrganizationColorPaletteWithIsActive[];
}

interface ApiCreatedColorPaletteResponse {
  status: 'ok';
  results: OrganizationColorPalette;
}

interface OrganizationWarehouseCredentials {
  organizationWarehouseCredentialsUuid: string;
  organizationUuid: string;
  name: string;
  description: string | null;
  warehouseType: WarehouseTypes;
  createdAt: Date;
  createdByUserUuid: string | null;
  credentials: WarehouseCredentials;  // Non-sensitive only
}

interface CreateOrganizationWarehouseCredentials {
  name: string;
  description?: string | null;
  credentials: CreateWarehouseCredentials;  // Includes sensitive fields
}

interface UpdateOrganizationWarehouseCredentials {
  name?: string;
  description?: string | null;
  credentials?: CreateWarehouseCredentials;
}

interface ApiOrganizationWarehouseCredentialsResponse {
  status: 'ok';
  results: OrganizationWarehouseCredentials;
}

interface ApiOrganizationWarehouseCredentialsListResponse {
  status: 'ok';
  results: OrganizationWarehouseCredentials[];
}

type OrganizationWarehouseCredentialsSummary = Pick<
  OrganizationWarehouseCredentials,
  'organizationWarehouseCredentialsUuid' | 'name' | 'description' | 'warehouseType'
>;

interface ApiOrganizationWarehouseCredentialsSummaryListResponse {
  status: 'ok';
  results: OrganizationWarehouseCredentialsSummary[];
}

/**
 * OAuth 2.0 client configuration
 */
interface OAuthClient {
  clientUuid: string;
  clientId: string;
  clientSecret: string | undefined;
  clientName: string;
  redirectUris: string[];
  grants: string[];
  scopes: string[] | null;
  createdAt: Date;
  createdByUserUuid: string | null;
  expiresAt: Date | null;
}

/**
 * OAuth 2.0 authorization code
 * Issued during the authorization flow before token exchange
 */
interface OAuthAuthorizationCode {
  authorizationCodeUuid: string;
  authorizationCode: string;
  expiresAt: Date;
  redirectUri: string;
  scopes: string[];
  userUuid: string;
  organizationUuid: string;
  createdAt: Date;
  usedAt: Date | null;
  codeChallenge: string | null;
  codeChallengeMethod: 'S256' | 'plain' | null;
}

/**
 * OAuth 2.0 authorization request parameters
 * Used to initiate the authorization code flow
 */
interface OAuthAuthorizationRequest {
  response_type: 'code';
  client_id: string;
  redirect_uri: string;
  scope?: string;
  state?: string;
  code_challenge?: string;
  code_challenge_method?: 'S256' | 'plain';
}

/**
 * OAuth 2.0 access token
 * Used to authenticate API requests
 */
interface OAuthAccessToken {
  accessTokenUuid: string;
  accessToken: string;
  expiresAt: Date;
  scopes: string[];
  userUuid: string;
  organizationUuid: string;
  createdAt: Date;
  lastUsedAt: Date | null;
  revokedAt: Date | null;
  authorizationCodeUuid: string | null;
}

/**
 * OAuth 2.0 refresh token
 * Used to obtain new access tokens without re-authentication
 */
interface OAuthRefreshToken {
  refreshTokenUuid: string;
  refreshToken: string;
  expiresAt: Date;
  scopes: string[];
  userUuid: string;
  organizationUuid: string;
  createdAt: Date;
  lastUsedAt: Date | null;
  revokedAt: Date | null;
  accessTokenUuid: string;
}

/**
 * OAuth 2.0 token request
 * Supports authorization_code, refresh_token, and client_credentials grant types
 */
interface OAuthTokenRequest {
  grant_type: 'authorization_code' | 'refresh_token' | 'client_credentials';
  code?: string;
  refresh_token?: string;
  redirect_uri?: string;
  client_id: string;
  client_secret: string;
  scope?: string;
  code_verifier?: string;
}

/**
 * OAuth 2.0 token response
 * Returned after successful token exchange
 */
interface OAuthTokenResponse {
  access_token: string;
  token_type: 'Bearer';
  expires_in: number;
  refresh_token?: string;
  scope?: string;
}

/**
 * OAuth 2.0 token introspection request
 * Used to validate and get metadata about a token
 */
interface OAuthIntrospectRequest {
  token: string;
  token_type_hint?: 'access_token' | 'refresh_token';
  client_id?: string;
  client_secret?: string;
}

/**
 * OAuth 2.0 token introspection response
 * Contains token metadata and validation status
 */
interface OAuthIntrospectResponse {
  active: boolean;
  scope?: string;
  client_id?: string;
  username?: string;
  token_type?: string;
  exp?: number;
  iat?: number;
  nbf?: number;
  sub?: string;
  aud?: string;
  iss?: string;
  jti?: string;
}

/**
 * OAuth 2.0 token revocation request
 * Used to invalidate access or refresh tokens
 */
interface OAuthRevokeRequest {
  token: string;
  token_type_hint?: 'access_token' | 'refresh_token';
}

/**
 * User with organization UUID
 * Used in OAuth token operations
 */
type UserWithOrganizationUuid = {
  userId: number;
  organizationUuid: string;
};