import { SetMetadata } from "@nestjs/common";

/**
 * Permission levels for workspace access control.
 * These map to WorkspaceMemberRole from the database schema.
 */
export enum Permission {
  /** Requires OWNER role - full control over workspace */
  WORKSPACE_OWNER = "workspace:owner",

  /** Requires ADMIN or OWNER role - administrative functions */
  WORKSPACE_ADMIN = "workspace:admin",

  /** Requires MEMBER, ADMIN, or OWNER role - standard access */
  WORKSPACE_MEMBER = "workspace:member",

  /** Any authenticated workspace member including GUEST */
  WORKSPACE_ANY = "workspace:any",
}

export const PERMISSION_KEY = "permission";

/**
 * Decorator to specify required permission level for a route.
 * Use with PermissionGuard to enforce role-based access control.
 *
 * @param permission - The minimum permission level required
 *
 * @example
 * ```typescript
 * @RequirePermission(Permission.WORKSPACE_ADMIN)
 * @Delete(':id')
 * async deleteWorkspace(@Param('id') id: string) {
 *   // Only ADMIN or OWNER can execute this
 * }
 * ```
 *
 * @example
 * ```typescript
 * @RequirePermission(Permission.WORKSPACE_MEMBER)
 * @Get()
 * async getTasks() {
 *   // Any workspace member can execute this
 * }
 * ```
 */
export const RequirePermission = (permission: Permission) =>
  SetMetadata(PERMISSION_KEY, permission);
