import type { JSONSupport, JSONSupportMixinProperties } from "../core/JSONSupport.js";

export interface OAuthInfoProperties extends JSONSupportMixinProperties, Partial<Pick<OAuthInfo, "appId" | "authNamespace" | "expiration" | "flowType" | "forceUserId" | "locale" | "minTimeUntilExpiration" | "popup" | "popupCallbackUrl" | "popupWindowFeatures" | "portalUrl" | "preserveUrlHash" | "userId">> {}

/**
 * This class contains information about an OAuth 2.0 configuration. Use it in combination with the
 * [IdentityManager](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-IdentityManager.html) widget to aid in working with OAuth 2.0 authentication.
 *
 * One-step authentication has been superseded by the recommended two-step approach with [Proof Key for Code Exchange (PKCE)](https://oauth.net/2/pkce/).
 *
 * This update coincides with recommendations in the [OAuth 2.1](https://oauth.net/2.1/) specification. Although one-step authentication is still supported, the API will no longer default to this. If needing to retain this setting, it is necessary to set [flowType](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#flowType) to `implicit`.
 *
 * Please refer to the [4.23 Release Notes](https://developers.arcgis.com/javascript/latest/release-notes/#updated-oauth-authentication) for additional information regarding this update.
 *
 * @since 4.0
 * @see [Sample - Access ArcGIS Online items using OAuth 2.0](https://developers.arcgis.com/javascript/latest/sample-code/identity-oauth-basic/)
 * @see [Authentication and secure resources](https://developers.arcgis.com/javascript/latest/secure-resources/)
 * @see [Authentication and OAuth 2](https://developers.arcgis.com/authentication/)
 * @see [Proxy pages with the API](https://developers.arcgis.com/javascript/latest/proxies/)
 * @see [ArcGIS portals](https://developers.arcgis.com/javascript/latest/arcgis-organization-portals/)
 * @see [IdentityManager](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-IdentityManager.html)
 * @see [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth)
 */
export default class OAuthInfo extends JSONSupport {
  /**
   * @example
   * const [OAuthInfo, esriId] = await $arcgis.import([
   *   "@arcgis/core/identity/OAuthInfo.js",
   *   "@arcgis/core/identity/IdentityManager.js"
   * ]);
   * // Create a new OAuthInfo object.
   * // The OAuth sign-in page will be shown in a popup window and use the specified callback URL.
   * const info = new OAuthInfo({
   *   appId: "<put client id here>",
   *   popup: true,
   *   // If using a callback page other than the default one,
   *   // make sure it supports the authentication type used.
   *   popupCallbackUrl: "<url to callback page>"
   * });
   *
   * // Add this OAuthInfo object to the IdentityManager.
   * esriId.registerOAuthInfos([info]);
   */
  constructor(properties?: OAuthInfoProperties);
  /** The registered application id. */
  accessor appId: string | null | undefined;
  /**
   * Applications with the same value will share the stored token on the same host.
   *
   * @default "/"
   */
  accessor authNamespace: string;
  /**
   * The number of minutes that the token is valid.
   *
   * @default 20160 // two weeks
   */
  accessor expiration: number;
  /**
   * Set this property to specify the type of authentication to use. One-step authentication has been superseded in favor of the recommended two-step approach (ie. [`grant_type=authorization-code`](https://developers.arcgis.com/documentation/mapping-apis-and-services/security/oauth-2/#oauth-20-grant-types)).
   *
   * > [!WARNING]
   * >
   * > This update coincides with recommendations in the [OAuth 2.1](https://oauth.net/2.1/) recommendation.
   *
   * Possible Value | Description
   * ---------------|------------
   * auto | **Recommended.** Automatically defaults to two-step authentication with [PKCE](https://oauth.net/2/pkce/) if accessing resources from ArcGIS Online or ArcGIS Enterprise version 10.9 or higher. One-step authentication is used if accessing an earlier version of ArcGIS Enterprise.
   * authorization-code | Similar to `auto`, this also uses two-step authentication with [PKCE](https://oauth.net/2/pkce/), but this does not check the server version. **Do not use this type if accessing resources on older server versions without PKCE support.**
   * implicit | One-step authentication. This is no longer a recommended approach and has been superseded by two-step authentication. Use this type if working with older server versions (ie. prior to 10.9). Please refer to [OAuth 2.0 Security Best Current Practices](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-14#section-2.1.2) for additional information.
   *
   * > [!WARNING]
   * >
   * > When signing into an application via a [popup](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popup), the referenced [callback page](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popupCallbackUrl) should be compatible for whatever authentication type is used. The default [oauth-callback.html](https://github.com/Esri/jsapi-resources/blob/main/oauth/oauth-callback.html) has been updated to allow for these updates in the two-step approach, although it will still work if using the one-step flow.
   *
   * @default "auto"
   * @since 4.23
   * @example
   * // The `flowType` defaults to `auto`.
   * // If using a supported server/portal version, two-step authentication is used.
   * // If not, reverts to one-step.
   * const infoAuto = new OAuthInfo({
   *   appId: "<put client id here>"
   * });
   * @example
   * // One-step workflow - no longer recommended.
   * // Should only be used if working with older versions of Server/Portal, (ie. < 10.9).
   * const infoImplicit = new OAuthInfo({
   *   appId: "<put client id here>",
   *   flowType: "implicit",
   *   popup: true,
   *   // Updated callback page works with both two-step and one-step authentication
   *   popupCallbackUrl: "oauth-callback.html"
   * });
   */
  accessor flowType: "auto" | "authorization-code" | "implicit";
  /**
   * Set this property to `true` to force the user to sign in with the id in [userId](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#userId).
   * If the [userId](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#userId) is not set, it will update after the user signs in. If the token expires, the same user will be required to sign in again.
   *
   * @default false
   * @since 4.18
   * @see [userId](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#userId)
   */
  accessor forceUserId: boolean;
  /**
   * The locale for the OAuth sign-in page. The default locale
   * is based on your browser/OS and the organization locale.
   * You can use this property to change
   * this. The locale needs to follow the language dash country code
   * syntax supported by ArcGIS.com.
   *
   * @default // Based on your browser/OS and the organization locale.
   * @see [intl](https://developers.arcgis.com/javascript/latest/api-reference/esri-intl.html)
   */
  accessor locale: string | null | undefined;
  /**
   * The minimum time in minutes before a saved token is due to expire that
   * should still be considered valid for use.
   *
   * @default 30
   */
  accessor minTimeUntilExpiration: number;
  /**
   * Set to `true` to show the OAuth sign-in page in a popup window. Make certain to have a valid callback page referenced in the [popupCallbackUrl](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popupCallbackUrl). A sample callback page, [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth), is provided to help with this.
   * The referenced [callback page](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popupCallbackUrl) should be compatible for whatever [authentication type](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#flowType) is used. The default [oauth-callback.html](https://github.com/Esri/jsapi-resources/blob/main/oauth/oauth-callback.html) has been updated to allow for these updates in the two-step approach, although it will still work if using the one-step flow.
   *
   * @default false
   * @see [flowType](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#flowType)
   * @see [popupCallbackUrl](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popupCallbackUrl)
   * @see [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth)
   */
  accessor popup: boolean;
  /**
   * Applicable if working with the popup user-login workflow.
   * This is a relative page URL that redirects the user back to
   * the secured application after successful login.
   *
   * The referenced callback page should be compatible for whatever [authentication type](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#flowType) is used. The default [oauth-callback.html](https://github.com/Esri/jsapi-resources/blob/main/oauth/oauth-callback.html) has been updated to allow for these updates in the two-step approach, although it will still work if using the one-step flow.
   *
   * @default "oauth-callback.html"
   * @see [popup](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popup)
   * @see [oauth-callback.html](https://github.com/Esri/jsapi-resources/tree/main/oauth)
   */
  accessor popupCallbackUrl: string;
  /**
   * The window features passed to
   * [window.open()](https://developer.mozilla.org/en-US/docs/Web/API/Window/open).
   *
   * @default "height=490,width=800,resizable,scrollbars,status"
   */
  accessor popupWindowFeatures: string;
  /**
   * The URL to either an ArcGIS Online or an ArcGIS Enterprise portal.
   * For example, `https://www.arcgis.com`, or `https://www.example.com/arcgis`.
   * An organization URL can be specified if wanting to display the organization's settings; e.g `https://yourorg.maps.arcgis.com`.
   * See the [ArcGIS portal documentation](https://developers.arcgis.com/javascript/latest/arcgis-organization-portals/) for more information.
   *
   * @default "https://www.arcgis.com"
   */
  accessor portalUrl: string;
  /**
   * Set this property to `true` when [popup](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popup) is `false` in order to have the window's location hash value restored after signing in.
   *
   * @default false
   * @since 4.14
   * @see [popup](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#popup)
   */
  accessor preserveUrlHash: boolean;
  /**
   * The user id used when `forceUserId` is `true`. This is updated after a user
   * signs in, or it can be preset to a specific id.
   *
   * @since 4.18
   * @see [forceUserId](https://developers.arcgis.com/javascript/latest/api-reference/esri-identity-OAuthInfo.html#forceUserId)
   */
  accessor userId: string | null | undefined;
  /**
   * Creates a copy of the OAuthInfo object.
   *
   * @returns Returns a copy of the OAuthInfo.
   * @since 4.4
   */
  clone(): OAuthInfo;
}