import type Accessor from "../core/Accessor.js";
import type Extent from "../geometry/Extent.js";
import type { PortalGroupSortField } from "./types.js";
import type { ExtentProperties } from "../geometry/Extent.js";

export interface PortalQueryParamsProperties extends Partial<Pick<PortalQueryParams, "categories" | "filter" | "num" | "query" | "sortField" | "sortOrder" | "start">> {
  /**
   * Only relevant when querying for [PortalItems](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalItem.html).
   * When specified, restricts the results of the query to the extent defined here.
   *
   * The [spatial reference](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Extent.html#spatialReference) of the
   * given extent must be WGS84 (wkid 4326) or Web Mercator (wkid 3857).
   */
  extent?: ExtentProperties | null;
}

/**
 * The parameters used to perform a query for Items, Groups, and Users within a [Portal](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-Portal.html).
 *
 * @since 4.0
 * @see [Portal#queryGroups()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-Portal.html#queryGroups)
 * @see [Portal#queryItems()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-Portal.html#queryItems)
 * @see [Portal#queryUsers()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-Portal.html#queryUsers)
 * @see [PortalGroup#queryItems()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalGroup.html#queryItems)
 * @see [PortalUser#queryFavorites()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalUser.html#queryFavorites)
 */
export default class PortalQueryParams extends Accessor {
  constructor(properties?: PortalQueryParamsProperties);
  /**
   * An array of categories stored within the item. Use this property to filter
   * the results from [Portal#queryItems()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-Portal.html#queryItems) and
   * [PortalGroup#queryItems()](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalGroup.html#queryItems). It
   * accepts an array of:
   * * individual string elements or
   * * an array of strings.
   *
   * The query looks at each element within the array and performs a SQL `AND` operation on them.
   * If the element is an array instead of a single string element, the elements within this array
   * are read as `OR`. See the snippet below:
   *
   * > [!WARNING]
   * >
   * > Note: String[] elements are only supported by [ArcGIS Online](https://doc.arcgis.com/en/arcgis-online/reference/what-is-agol.htm) and version 10.6.1 of [Portal for ArcGIS Enterprise](https://enterprise.arcgis.com/en/portal/).
   *
   * @since 4.8
   * @example
   * // Query items with categories tagged as 'Basemaps' OR 'Imagery' AND 'People' OR 'Environment'
   * // i.e. (Basemaps || Imagery) && (People || Environment)
   * params.categories = [["Basemaps", "Imagery"], ["People", "Environment"]];
   */
  accessor categories: Array<string | string[]> | null | undefined;
  /**
   * Only relevant when querying for [PortalItems](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalItem.html).
   * When specified, restricts the results of the query to the extent defined here.
   *
   * The [spatial reference](https://developers.arcgis.com/javascript/latest/api-reference/esri-geometry-Extent.html#spatialReference) of the
   * given extent must be WGS84 (wkid 4326) or Web Mercator (wkid 3857).
   */
  get extent(): Extent | null | undefined;
  set extent(value: ExtentProperties | null | undefined);
  /**
   * Structured filter to use instead of the [query](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalQueryParams.html#query) property.
   *
   * @since 4.22
   * @see [ArcGIS REST API Search Reference](https://developers.arcgis.com/rest/users-groups-and-items/search-reference.htm)
   */
  accessor filter: string | null | undefined;
  /**
   * The maximum number of results to be included in the
   * [result](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalQueryResult.html#results) set response.
   * The maximum value allowed is `100`. The [start](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalQueryParams.html#start) property combined
   * with the `num` property can be used to paginate the search results.
   *
   * @default 10
   */
  accessor num: number;
  /**
   * The query string used for the search. View the
   * [ArcGIS REST API Search Reference](https://developers.arcgis.com/rest/users-groups-and-items/search-reference.htm)
   * for details on constructing a valid query.
   *
   * @see [ArcGIS REST API Search Reference](https://developers.arcgis.com/rest/users-groups-and-items/search-reference.htm)
   */
  accessor query: string | null | undefined;
  /**
   * A comma-delimited list of fields to sort. Field names may vary depending on what is being queried. For example, the fields allowed for a user query are much more limited than if performing a basic search query for portal items. A list of possible field names is listed below. These names correspond to either item (search), group, and/or user queries.
   *
   * Field name | Query functionality
   * ---------------|------------
   * title | search, group
   * uploaded | search
   * modified | search
   * username | user
   * created | user, group
   * type | search
   * owner | search, group
   * avg-rating | search
   * num-ratings | search
   * num-comments | search
   * num-views | search
   *
   * @see [Rest API: Search](https://developers.arcgis.com/rest/users-groups-and-items/search.htm)
   * @see [Rest API: Group Search](https://developers.arcgis.com/rest/users-groups-and-items/group-search.htm)
   * @see [Rest API: User Search](https://developers.arcgis.com/rest/users-groups-and-items/user-search.htm)
   */
  accessor sortField: PortalGroupSortField | null | undefined;
  /**
   * The order in which to sort the results.
   *
   * Possible Value | Description
   * ---------------|------------
   * asc | Sort the results in ascending order.
   * desc | Sort the results in descending order.
   *
   * @default "asc"
   */
  accessor sortOrder: "asc" | "desc";
  /**
   * The index of the first entry in the result set response. The index is 1-based.
   * The [start](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalQueryParams.html#start) property, along with the [num](https://developers.arcgis.com/javascript/latest/api-reference/esri-portal-PortalQueryParams.html#num) property can be used
   * to paginate the search results.
   *
   * @default 1
   */
  accessor start: number;
  /**
   * Creates a deep clone of the instance of PortalQueryParams that calls this method.
   *
   * @returns A clone of the instance that called this method.
   */
  clone(): PortalQueryParams;
}