@smartsamurai/krapi-sdk/src/types/auth.ts

KRAPI TypeScript SDK - Easy-to-use client SDK for connecting to self-hosted KRAPI servers (like Appwrite SDK)

/**
 * Authentication & User Management Types
 */

import { QueryOptions } from "./core";

// ===================================
// AUTHENTICATION & SESSIONS
// ===================================

export interface LoginRequest {
  username: string;
  password: string;
  remember?: boolean;
}

export interface LoginResponse {
  success: boolean;
  session_token: string;
  user: User;
  expires_at: string;
}

export interface SessionToken {
  token: string;
  user_id: string;
  expires_at: string;
  created_at: string;
  last_used_at?: string;
}

export interface Session {
  id: string;
  user_id: string;
  token: string;
  expires_at: string;
  created_at: string;
  last_used_at?: string;
  ip_address?: string;
  user_agent?: string;
  is_active: boolean;
  // Additional properties for backend compatibility
  type?: SessionType;
  project_id?: string;
  scopes?: Scope[];
  metadata?: Record<string, unknown>;
  consumed?: boolean;
  user_type?: "admin" | "project";
}

export interface SessionValidation {
  valid: boolean;
  user?: User;
  expires_at?: string;
  session_token?: string;
}

export interface RefreshResponse {
  success: boolean;
  session_token: string;
  expires_at: string;
}

export interface ProjectLoginRequest {
  projectId: string;
  username: string;
  password: string;
  email?: string;
}

// ===================================
// USER MANAGEMENT
// ===================================

export interface User {
  id: string;
  username: string;
  email: string;
  role: UserRole;
  status: UserStatus;
  created_at: string;
  updated_at: string;
  last_login_at?: string;
  profile?: UserProfile;
  project_id?: string; // For project users
  // Additional properties for backend compatibility
  permissions?: string[];
  phone?: string;
  is_verified?: boolean;
  scopes?: Scope[];
}

export interface ProjectUser {
  id: string;
  project_id: string;
  username: string;
  email: string;
  role: UserRole;
  status: UserStatus;
  created_at: string;
  updated_at: string;
  last_login?: string;
  // Backend-specific properties
  phone?: string;
  is_verified?: boolean;
  scopes?: string[];
  password?: string;
  permissions?: string[];
}

export interface AdminUser {
  id: string;
  username: string;
  email: string;
  role: AdminRole;
  access_level: AccessLevel;
  permissions: string[];
  active: boolean;
  created_at: string;
  updated_at: string;
  last_login?: string;
  login_count?: number;
  // Backend-specific properties
  api_key?: string;
  password_hash?: string;
}

export interface UserProfile {
  first_name?: string;
  last_name?: string;
  display_name?: string;
  avatar_url?: string;
  bio?: string;
  metadata?: Record<string, unknown>;
}

export type UserRole =
  | "admin"
  | "user"
  | "viewer"
  | "editor"
  | "owner"
  | "member";

export type UserStatus = "active" | "inactive" | "suspended" | "pending";

// Legacy enum exports for backward compatibility
export enum AdminRole {
  SUPER_ADMIN = "super_admin",
  ADMIN = "admin",
  MODERATOR = "moderator",
  DEVELOPER = "developer",
  // Additional roles for backend compatibility
  MASTER_ADMIN = "master_admin",
  PROJECT_ADMIN = "project_admin",
  LIMITED_ADMIN = "limited_admin",
}

export enum AccessLevel {
  READ = "read",
  WRITE = "write",
  DELETE = "delete",
  ADMIN = "admin",
  READ_ONLY = "read_only",
  READ_WRITE = "read_write",
  FULL = "full",
}

export enum Scope {
  READ = "read",
  WRITE = "write",
  DELETE = "delete",
  ADMIN = "admin",
  // Additional scopes for backend compatibility
  MASTER = "master",
  ADMIN_READ = "admin:read",
  ADMIN_WRITE = "admin:write",
  ADMIN_DELETE = "admin:delete",
  PROJECTS_READ = "projects:read",
  PROJECTS_WRITE = "projects:write",
  PROJECTS_DELETE = "projects:delete",
  COLLECTIONS_READ = "collections:read",
  COLLECTIONS_WRITE = "collections:write",
  COLLECTIONS_DELETE = "collections:delete",
  DOCUMENTS_READ = "documents:read",
  DOCUMENTS_WRITE = "documents:write",
  DOCUMENTS_DELETE = "documents:delete",
  STORAGE_READ = "storage:read",
  STORAGE_WRITE = "storage:write",
  STORAGE_DELETE = "storage:delete",
  EMAIL_SEND = "email:send",
  EMAIL_READ = "email:read",
  FUNCTIONS_EXECUTE = "functions:execute",
  FUNCTIONS_WRITE = "functions:write",
  FUNCTIONS_DELETE = "functions:delete",
  // User management scopes
  USERS_READ = "users:read",
  USERS_WRITE = "users:write",
  USERS_DELETE = "users:delete",
  // Data management scopes
  DATA_READ = "data:read",
  DATA_WRITE = "data:write",
  DATA_DELETE = "data:delete",
  // File management scopes
  FILES_READ = "files:read",
  FILES_WRITE = "files:write",
  FILES_DELETE = "files:delete",
}

/**
 * Project-specific scopes for users within a project
 *
 * NOTE: These scopes are ONLY for managing resources within a SINGLE project.
 * Global scopes like "projects:read" are reserved for main KRAPI app admin users,
 * not for project users. Projects are isolated - they cannot see or manage other projects.
 */
export enum ProjectScope {
  // User management scopes (for users within THIS project only)
  USERS_READ = "users:read",
  USERS_WRITE = "users:write",
  USERS_DELETE = "users:delete",
  // Data management scopes (collections and documents within THIS project only)
  DATA_READ = "data:read",
  DATA_WRITE = "data:write",
  DATA_DELETE = "data:delete",
  // File management scopes (files within THIS project only)
  FILES_READ = "files:read",
  FILES_WRITE = "files:write",
  FILES_DELETE = "files:delete",
  // Function execution scopes (functions within THIS project only)
  FUNCTIONS_EXECUTE = "functions:execute",
  // Email scopes (emails within THIS project only)
  EMAIL_SEND = "email:send",
  // Collection-specific scopes (within THIS project only)
  COLLECTIONS_READ = "collections:read",
  COLLECTIONS_WRITE = "collections:write",
  COLLECTIONS_DELETE = "collections:delete",
  // Document-specific scopes (within THIS project only)
  DOCUMENTS_READ = "documents:read",
  DOCUMENTS_WRITE = "documents:write",
  DOCUMENTS_DELETE = "documents:delete",
}

export interface CreateUserRequest {
  username: string;
  email: string;
  password: string;
  role?: UserRole;
  profile?: Partial<UserProfile>;
  metadata?: Record<string, unknown>;
}

export interface UpdateUserRequest {
  username?: string;
  email?: string;
  password?: string;
  role?: UserRole;
  status?: UserStatus;
  profile?: Partial<UserProfile>;
  metadata?: Record<string, unknown>;
}

export interface UserListOptions extends QueryOptions {
  role?: UserRole;
  status?: UserStatus;
}

// ===================================
// API KEYS
// ===================================

export interface ApiKey {
  id: string;
  name: string;
  key: string;
  scopes: ApiKeyScope[];
  project_id?: string;
  user_id: string;
  status: ApiKeyStatus;
  expires_at?: string;
  created_at: string;
  last_used_at?: string;
  usage_count: number;
  rate_limit?: number;
  metadata?: Record<string, unknown>;
  // Backend-specific properties
  project_ids?: string[];
}

export type ApiKeyScope =
  | "read"
  | "write"
  | "delete"
  | "projects:read"
  | "projects:write"
  | "projects:delete"
  | "collections:read"
  | "collections:write"
  | "collections:delete"
  | "documents:read"
  | "documents:write"
  | "documents:delete"
  | "files:read"
  | "files:write"
  | "files:delete"
  | "users:read"
  | "users:write"
  | "users:delete"
  | "email:send"
  | "email:read"
  | "functions:execute"
  | "functions:write"
  | "functions:delete"
  | "admin:read"
  | "admin:write"
  | "admin:delete"
  | "backup:create"
  | "backup:read"
  | "backup:delete"
  | "system:read"
  | "system:write";

export type ApiKeyStatus = "active" | "inactive" | "revoked" | "expired";

export interface CreateApiKeyRequest {
  name: string;
  scopes: ApiKeyScope[];
  project_id?: string;
  expires_at?: string;
  metadata?: Record<string, unknown>;
}

export interface ApiKeyListOptions extends QueryOptions {
  project_id?: string;
  status?: ApiKeyStatus;
}

// ===================================
// SESSION TYPES
// ===================================

export enum SessionType {
  USER = "user",
  API_KEY = "api_key",
  SERVICE = "service",
  SYSTEM = "system",
}