@chilkat/react-native 11.6.1

package/src/specs/OAuth2.nitro.ts

@@ -0,0 +1,1023 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { Socket } from './Socket.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+
+/**
+ * OAuth2 Authorization Code Flow
+ *
+ * Obtain OAuth2 access tokens from desktop and native applications
+ *
+ * The `OAuth2` class enables desktop and native applications
+ * to perform the OAuth 2.0 Authorization Code Flow for obtaining an initial
+ * access token. The flow begins with `StartAuth`, which generates
+ * the authorization URL to open in a browser and starts a background listener
+ * for the local redirect callback.
+ *
+ * **Browser-based authorization**
+ * Use `LaunchBrowser` to open the generated authorization URL.
+ *
+ * **Local redirect handling**
+ * Chilkat listens locally for the provider’s redirect response.
+ *
+ * **Token exchange**
+ * The authorization code is exchanged for access and refresh tokens.
+ *
+ * **Diagnostics and state**
+ * Inspect `AuthFlowState`, `FailureInfo`, and token response data.
+ *
+ * After the user grants or denies authorization, Chilkat captures the redirect
+ * response, completes the token exchange, and makes the results available through
+ * properties such as `AccessToken`, `RefreshToken`,
+ * `AccessTokenResponse`, `AuthFlowState`, and
+ * `FailureInfo`.
+ *
+ * The class also supports PKCE, refresh-token requests, custom authorization and
+ * token parameters, secure OS-backed secret resolution, and detailed diagnostic
+ * information.
+ *
+ * **Note:**
+ * This class is primarily used to obtain the initial OAuth2 access token. After
+ * that, applications typically use the refresh token to obtain new access tokens
+ * for an extended period without requiring further user interaction.
+ *
+ * For an extended overview, see
+ * [OAuth2 Class Overview](https://www.chilkatsoft.com/oauth2_class_overview.asp).
+ *
+ * Each `OAuth2` instance owns a native Chilkat object. It is released when the JavaScript object is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new OAuth2()`.
+ *
+ * Methods that can take a while (network, files, compression, key generation) also have an
+ * `...Async` form returning a `Promise`; it runs on a native worker thread so the UI keeps
+ * rendering. While such a call is pending, every other call on this object throws, except
+ * {@link OAuth2.abort} and assigning {@link OAuth2.onPercentDone} / {@link OAuth2.onProgressInfo}.
+ */
+export interface OAuth2 extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * Provides HTML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * Provides plain text information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * Provides XML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * If set to a file path, this property logs the LastErrorText of each Chilkat method or property
+   * call to the specified file. This logging helps identify the context and history of Chilkat
+   * calls leading up to any crash or hang, aiding in debugging.
+   *
+   * Enabling the VerboseLogging property provides more detailed information.
+   *
+   * This property is mainly used for debugging rare instances where a Chilkat method call causes a
+   * hang or crash, which should generally not happen.
+   *
+   * Possible causes of hangs include:
+   *
+   * - A timeout property set to 0, indicating an infinite timeout.
+   *
+   * - A hang occurring within an event callback in the application code.
+   *
+   * - An internal bug in the Chilkat code causing the hang.
+   */
+  debugLogFilePath: string
+
+  /**
+   * If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may
+   * contain more verbose information. The default value is `false`. Verbose logging should only be
+   * used for debugging. The potentially large quantity of logged information may adversely affect
+   * peformance.
+   */
+  verboseLogging: boolean
+
+  /**
+   * Indicates the success or failure of the most recent method call: `true` means success, `false`
+   * means failure. This property remains unchanged by property setters or getters. This method is
+   * present to address challenges in checking for null or Nothing returns in certain programming
+   * languages. Note: This property does not apply to methods that return integer values or to
+   * boolean-returning methods where the boolean does not indicate success or failure.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * Specifies the authorization endpoint to which the user's browser is directed. {@link
+   * OAuth2.startAuth} appends the client identifier, redirect URI, scope, state, PKCE values, and
+   * other configured authorization parameters.
+   *
+   * ProviderAuthorization endpointToken endpoint
+   *
+   * | Google | | `https://accounts.google.com/o/oauth2/v2/auth` | |
+   * `https://oauth2.googleapis.com/token` |
+   *
+   * | Microsoft identity platform | |
+   * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize` | |
+   * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token` |
+   *
+   * | Salesforce production | | `https://login.salesforce.com/services/oauth2/authorize` | |
+   * `https://login.salesforce.com/services/oauth2/token` |
+   *
+   * | QuickBooks Online | | `https://appcenter.intuit.com/connect/oauth2` | |
+   * `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` |
+   *
+   * | X API |  | `https://x.com/i/oauth2/authorize` |  | `https://api.x.com/2/oauth2/token` |
+   *
+   * **Prefer provider metadata:** When the provider publishes OAuth authorization-server metadata
+   * or OpenID Connect discovery metadata, use its current `authorization_endpoint` value rather
+   * than copying an endpoint from an old example.
+   *
+   * **Environment and tenant matter:** Sandbox, production, regional, and tenant-specific
+   * deployments can use different endpoints. The authorization and token endpoints must belong to
+   * the same provider environment.
+   */
+  authorizationEndpoint: string
+
+  /**
+   * Specifies the provider's token endpoint. Chilkat sends authorization-code and refresh-token
+   * requests to this URL over TLS.
+   *
+   * ProviderAuthorization endpointToken endpoint
+   *
+   * | Google | | `https://accounts.google.com/o/oauth2/v2/auth` | |
+   * `https://oauth2.googleapis.com/token` |
+   *
+   * | Microsoft identity platform | |
+   * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize` | |
+   * `https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token` |
+   *
+   * | Salesforce production | | `https://login.salesforce.com/services/oauth2/authorize` | |
+   * `https://login.salesforce.com/services/oauth2/token` |
+   *
+   * | QuickBooks Online | | `https://appcenter.intuit.com/connect/oauth2` | |
+   * `https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` |
+   *
+   * | X API |  | `https://x.com/i/oauth2/authorize` |  | `https://api.x.com/2/oauth2/token` |
+   *
+   * **Back-channel endpoint:** Unlike the authorization endpoint, the token endpoint is contacted
+   * directly by the application, not opened in the user's browser.
+   *
+   * **Use the provider's current HTTPS endpoint:** Endpoint locations can change. Prefer the value
+   * published in the provider's OAuth or OpenID Connect metadata, and do not mix sandbox and
+   * production endpoints.
+   */
+  tokenEndpoint: string
+
+  /**
+   * Specifies the client identifier assigned when the application is registered with the
+   * authorization server. It identifies the application in authorization and token requests.
+   *
+   * **Not a password:** A client ID is normally public and may appear in authorization URLs. Its
+   * security role is identification, not authentication.
+   */
+  clientId: string
+
+  /**
+   * Specifies the client secret assigned to a confidential client by the authorization server. It
+   * is used when the provider requires the client to authenticate at the token endpoint.
+   *
+   * **Protect this value:** A client secret is a credential. Do not place it in source control,
+   * logs, browser URLs, or distributable desktop/mobile binaries. Native applications are public
+   * clients and generally cannot keep a shared secret confidential; use PKCE and follow the
+   * provider's registration requirements.
+   *
+   * **PKCE is separate:** PKCE protects the authorization code. It does not transform an embedded
+   * secret into a confidential credential and does not replace client authentication for a provider
+   * that requires it.
+   */
+  clientSecret: string
+
+  /**
+   * Specifies the access scopes requested from the authorization server. A scope is a
+   * provider-defined permission or capability associated with the resulting access token.
+   *
+   * OAuth scope values are commonly separated by a single SPACE character:
+   *
+   * ```
+   * openid email profile https://www.googleapis.com/auth/drive.readonly
+   * ```
+   *
+   * - `openid` requests OpenID Connect processing and an ID token when used with an appropriate
+   *   response type.
+   *
+   * - `email` and `profile` request standard OpenID Connect claims.
+   *
+   * - The Google Drive URI requests read-only access to Drive files.
+   *
+   * **Provider-defined and consented:** Scope names, separators, defaults, and offline-access
+   * requirements vary by provider. Request the minimum permissions needed and verify the granted
+   * scope returned in the token response.
+   */
+  scope: string
+
+  /**
+   * Set to `true` to enable Proof Key for Code Exchange (PKCE) for the authorization-code flow. The
+   * default is `false`.
+   *
+   * When enabled, Chilkat generates a high-entropy code verifier, sends its transformed challenge
+   * in the authorization request, and sends the original verifier during the token exchange.
+   *
+   * **Recommended for native applications:** PKCE binds the authorization code to the application
+   * instance that initiated the flow, reducing the risk that an intercepted code can be redeemed by
+   * another client. Current OAuth security guidance requires PKCE for public clients and recommends
+   * it broadly.
+   */
+  codeChallenge: boolean
+
+  /**
+   * Selects the PKCE transformation used when {@link OAuth2.codeChallenge} is `true`.
+   *
+   * ValueBehavior
+   *
+   * | `S256` | | Sends a Base64URL-encoded SHA-256 digest of the code verifier. This is the default
+   * and recommended method. |
+   *
+   * | `plain` | | Sends the code verifier itself as the challenge. Use only for compatibility with
+   * a provider that cannot support `S256`. |
+   *
+   * **Avoid downgrading:** If a provider rejects `S256`, do not automatically retry with `plain`
+   * unless the provider is known and explicitly requires it.
+   */
+  codeChallengeMethod: string
+
+  /**
+   * Contains the raw response body returned by the token endpoint after a successful
+   * authorization-code exchange or refresh-token request.
+   *
+   * Most providers return JSON similar to:
+   *
+   * ```
+   * {
+   *   "token_type": "Bearer",
+   *   "expires_in": 3600,
+   *   "access_token": "...",
+   *   "scope": "read write",
+   *   "refresh_token": "..."
+   * }
+   * ```
+   *
+   * FieldTypical meaning
+   *
+   * | `access_token` |  | Credential presented to the protected API. |
+   *
+   * | `token_type` |  | Usually `Bearer`. |
+   *
+   * | `expires_in` |  | Access-token lifetime in seconds, when supplied. |
+   *
+   * | `scope` |  | Scopes actually granted, when supplied. |
+   *
+   * | `refresh_token` |  | Credential used to request later access tokens, when issued. |
+   *
+   * | `id_token` |  | OpenID Connect identity token, when requested and issued. |
+   *
+   * Some providers return form-encoded text instead of JSON. Use {@link
+   * OAuth2.getAccessTokenResponseSb} when a `StringBuilder` destination is preferred.
+   *
+   * **Sensitive response:** This property can contain live credentials. Do not include it in
+   * ordinary logs, exception reports, telemetry, or user-visible diagnostics.
+   *
+   * This property is read-only.
+   */
+  readonly accessTokenResponse: string
+
+  /**
+   * Reports the current state of the background authorization flow.
+   *
+   * ValueStateMeaning
+   *
+   * | `0` |  | Idle |  | No authorization flow has been started. |
+   *
+   * | `1` |  | Waiting for redirect |  | The local listener is waiting for the browser callback. |
+   *
+   * | `2` | | Exchanging code | | The redirect was received and the background thread is waiting
+   * for the token-endpoint response. |
+   *
+   * | `3` |  | Success |  | The flow completed and token response properties are available. |
+   *
+   * | `4` | | Denied | | The authorization server returned an access-denied response. Inspect
+   * {@link OAuth2.accessTokenResponse}. |
+   *
+   * | `5` | | Failed | | The flow failed before successful completion. Inspect {@link
+   * OAuth2.failureInfo} and `LastErrorText`. |
+   *
+   * **Polling pattern:** After opening the authorization URL, periodically read this property until
+   * it is `3`, `4`, or `5`. Avoid a tight loop; sleep briefly or use the host environment's timer
+   * mechanism.
+   *
+   * This property is read-only.
+   */
+  readonly authFlowState: number
+
+  /**
+   * Contains diagnostic information when {@link OAuth2.authFlowState} is `5`. The value is cleared
+   * when {@link OAuth2.startAuth} begins a new flow.
+   *
+   * Use this property for failures in the listener, redirect processing, network connection, or
+   * token exchange. Provider-declared authorization denial is represented by state `4` and is
+   * normally available in {@link OAuth2.accessTokenResponse}.
+   *
+   * **Review before logging:** Diagnostics can include URLs, response bodies, or request details.
+   * Remove authorization codes, tokens, client credentials, and personal information before storing
+   * or transmitting logs.
+   *
+   * This property is read-only.
+   */
+  readonly failureInfo: string
+
+  /**
+   * Gets or sets the HTML response sent by Chilkat's local listener to the browser after
+   * authorization is granted and the redirect is accepted.
+   *
+   * The default HTML immediately redirects the browser to Chilkat's confirmation page:
+   *
+   * ```
+   * <html>
+   *   <head><meta http-equiv='refresh'
+   *     content='0;url=https://www.chilkatsoft.com/oauth2_allowed.html'></head>
+   *   <body>Thank you for allowing access.</body>
+   * </html>
+   * ```
+   *
+   * Replace this value to display application-specific instructions or redirect to a page operated
+   * by your organization.
+   *
+   * **Do not expose credentials:** The HTML is shown in a browser. Do not insert the authorization
+   * code, access token, refresh token, client secret, or raw callback URL into this page.
+   */
+  redirectAllowHtml: string
+
+  /**
+   * Gets or sets the HTML response sent by Chilkat's local listener to the browser when the
+   * authorization server reports that access was denied.
+   *
+   * The default HTML immediately redirects the browser to Chilkat's denial page:
+   *
+   * ```
+   * <html>
+   *   <head><meta http-equiv='refresh'
+   *     content='0;url=https://www.chilkatsoft.com/oauth2_denied.html'></head>
+   *   <body>The app will not have access.</body>
+   * </html>
+   * ```
+   *
+   * Replace this value to display application-specific instructions or redirect to a page operated
+   * by your organization.
+   *
+   * **Denial is not a transport failure:** User denial is represented by {@link
+   * OAuth2.authFlowState} value `4`. It should normally be handled as a completed flow in which
+   * consent was not granted.
+   */
+  redirectDenyHtml: string
+
+  /**
+   * Contains the `access_token` extracted from the most recent successful token response. It is
+   * updated after a successful authorization-code exchange or refresh-token request.
+   *
+   * The access token is presented to the protected API, commonly in an HTTP header:
+   *
+   * ```
+   * Authorization: Bearer ACCESS_TOKEN
+   * ```
+   *
+   * **Bearer credential:** Anyone possessing a bearer access token can use the authority it grants
+   * until the token expires or is revoked. Store it securely, transmit it only over TLS, and never
+   * place it in a URL or ordinary log.
+   */
+  accessToken: string
+
+  /**
+   * Contains the `token_type` value from the most recent successful token response. The common
+   * value is `Bearer`.
+   *
+   * **Use the returned type:** OAuth does not require every token to use the same presentation
+   * mechanism. Follow the authorization server's documentation and the returned token type when
+   * constructing API requests.
+   */
+  tokenType: string
+
+  /**
+   * Gets or sets the refresh token used to obtain new access tokens. Chilkat populates this
+   * property when the token endpoint issues a `refresh_token`, and {@link
+   * OAuth2.refreshAccessToken} reads it when creating a refresh request.
+   *
+   * A provider may omit the refresh token unless an offline-access scope or provider-specific
+   * authorization parameter was requested. A refresh response may also return a replacement token.
+   *
+   * **Long-lived credential:** Refresh tokens commonly outlive access tokens and can be used
+   * without user interaction. Protect them at least as carefully as passwords, persist replacements
+   * after rotation, and delete them when authorization is revoked.
+   */
+  refreshToken: string
+
+  /**
+   * Specifies the local TCP port on which Chilkat listens for the browser's OAuth redirect. Choose
+   * an available nonprivileged port, typically between `1024` and `65535`.
+   *
+   * The redirect URI registered with the provider must match the host, selected port, and
+   * terminating slash generated by this object. For example:
+   *
+   * ```
+   * http://127.0.0.1:3017/
+   * ```
+   *
+   * - Use `http` for a loopback redirect handled entirely on the local computer.
+   *
+   * - Use {@link OAuth2.localHost} to select `localhost` or `127.0.0.1`.
+   *
+   * - Include the final `/` when registering the redirect URI.
+   *
+   * **Provider registration must match:** Authorization servers differ in their support for
+   * loopback ports and redirect-URI matching. Register the exact form required by the provider. The
+   * IPv4 loopback literal `127.0.0.1` is generally more predictable than resolving `localhost`.
+   */
+  listenPort: number
+
+  /**
+   * Selects the host name used in the loopback redirect URI:
+   *
+   * ValueRedirect form
+   *
+   * | `localhost` |  | `http://localhost:{port}/` |
+   *
+   * | `127.0.0.1` |  | `http://127.0.0.1:{port}/` |
+   *
+   * The default is `localhost`. The value must match the redirect URI registered with the provider.
+   *
+   * **Loopback recommendation:** `127.0.0.1` avoids DNS and hosts-file ambiguity and is generally
+   * preferable when the provider accepts an IPv4 loopback-literal redirect.
+   */
+  localHost: string
+
+  /**
+   * Specifies an optional provider-defined `resource` parameter identifying the API or audience for
+   * which a token is requested.
+   *
+   * This is used by some OAuth deployments, including older Microsoft identity endpoints and
+   * certain Dynamics configurations. Modern Microsoft v2 endpoints generally identify the target
+   * API through scope values instead.
+   *
+   * **Not a universal OAuth parameter:** Set this property only when the authorization server
+   * documents a required `resource` value. Do not assume that an API base URL is always the correct
+   * value.
+   */
+  resource: string
+
+  /**
+   * Defines the inclusive end of a local-listener port range that begins with {@link
+   * OAuth2.listenPort}. The default value of `0` disables range selection and uses only
+   * `ListenPort`.
+   *
+   * When nonzero, Chilkat selects an available port in the inclusive range. For example,
+   * `ListenPort=55110` and `ListenPortRangeEnd=55117` permit ports `55110` through `55117`.
+   *
+   * **Redirect registration:** The provider must accept the selected redirect URI. If it requires
+   * every exact port to be pre-registered, register each port in the range. If the provider
+   * supports the native-app loopback convention with a variable port, follow its documented
+   * registration form.
+   *
+   * Read {@link OAuth2.listenPortSelected} to determine which port was used.
+   */
+  listenPortRangeEnd: number
+
+  /**
+   * Specifies a public HTTPS callback URL on an application-controlled web server when the provider
+   * will not redirect directly to `localhost` or a loopback IP address.
+   *
+   * The intermediary endpoint receives the provider's redirect and forwards the complete callback,
+   * including `code`, `state`, `error`, and any provider-specific parameters, to the local listener
+   * used by Chilkat.
+   *
+   * **Security responsibility:** The intermediary handles a short-lived authorization code and
+   * state value. It must use HTTPS, avoid logging sensitive query data, validate and preserve
+   * parameters correctly, and prevent use as an open redirect.
+   *
+   * **Use only when necessary:** A direct loopback redirect with PKCE is simpler and avoids
+   * introducing a public relay. Prefer it whenever the provider supports native-application
+   * loopback redirects.
+   */
+  appCallbackUrl: string
+
+  /**
+   * Controls how `ClientId` and `ClientSecret` are supplied during the authorization-code token
+   * exchange.
+   *
+   * ValueBehavior
+   *
+   * | `true` | | Sends HTTP Basic authentication using the client ID as the username and the client
+   * secret as the password. |
+   *
+   * | `false` | | Sends the client ID and client secret as request parameters. This is the default.
+   * |
+   *
+   * **Match the provider's client-authentication method:** Some authorization servers require HTTP
+   * Basic authentication; others require parameters or no client secret for public clients. A wrong
+   * choice usually produces an `invalid_client` response.
+   *
+   * **TLS is mandatory:** Both forms expose the secret to the token endpoint. They differ in HTTP
+   * representation, not in the need for a secure TLS connection.
+   */
+  useBasicAuth: boolean
+
+  /**
+   * Set to `true` to include an OpenID Connect `nonce` parameter in the authorization request. The
+   * nonce is generated by Chilkat using the byte length specified by {@link OAuth2.nonceLength}.
+   * The default is `false`.
+   *
+   * In OpenID Connect, the authorization server includes the nonce in the ID token so the client
+   * can associate that token with the authorization request and detect replay or token-substitution
+   * problems.
+   *
+   * **Nonce versus state:** `nonce` protects the relationship between an OpenID Connect request and
+   * its ID token. OAuth `state` correlates the browser callback with the initiating request and is
+   * used for CSRF protection. They are related security controls but are not interchangeable.
+   */
+  includeNonce: boolean
+
+  /**
+   * Specifies the response mode requested from an OpenID Connect or provider-specific authorization
+   * endpoint.
+   *
+   * Set to `form_post` to add `response_mode=form_post`, causing the authorization server to return
+   * parameters in an auto-submitted HTML form that sends an HTTP POST to the redirect URI. The
+   * default is an empty string, which omits the parameter and lets the provider choose its normal
+   * mode.
+   *
+   * **Provider support required:** Use only a response mode supported by the provider and
+   * compatible with Chilkat's local listener or intermediary callback.
+   */
+  responseMode: string
+
+  /**
+   * Specifies the authorization response type. The default is `code`, which requests an
+   * authorization code.
+   *
+   * Set to `id_token+code` when a provider requires the OpenID Connect hybrid response
+   * `response_type=id_token code`; the plus sign is the URL-encoded representation of a SPACE in
+   * the query string.
+   *
+   * **Prefer the code flow unless required otherwise:** Hybrid responses add an ID token to the
+   * browser-facing authorization response and require correct OpenID Connect validation, including
+   * issuer, audience, signature, expiration, and nonce checks.
+   */
+  responseType: string
+
+  /**
+   * Specifies the number of random bytes used to generate the hexadecimal OpenID Connect nonce when
+   * {@link OAuth2.includeNonce} is `true`. The resulting string contains two hexadecimal characters
+   * per byte.
+   *
+   * The default is `4` bytes, which produces an 8-character hexadecimal nonce.
+   *
+   * **Entropy matters:** For security-sensitive OpenID Connect use, consider a substantially larger
+   * nonce, such as 16 bytes or more, unless the provider imposes a different requirement.
+   */
+  nonceLength: number
+
+  /**
+   * Provides a comma-separated list of specialized compatibility options. The default is an empty
+   * string and is appropriate for normal OAuth providers.
+   *
+   * KeywordEffect
+   *
+   * | `NO_OAUTH2_SCOPE` | | Omits the `scope` parameter from the authorization-code token request.
+   * |
+   *
+   * | `ExchangeCodeForTokenUsingJson` | | Sends the authorization-code token request as an HTTP
+   * POST with a JSON body instead of the normal form/query representation. |
+   *
+   * | `RefreshTokenUsingJson` | | Sends the refresh-token request as an HTTP POST with a JSON body.
+   * |
+   *
+   * **Leave empty unless required:** These options alter interoperability behavior outside the
+   * normal OAuth token-request format. Enable one only when the provider's documentation or Chilkat
+   * support explicitly requires it.
+   */
+  uncommonOptions: string
+
+  /**
+   * Contains the raw HTTP request received from the browser by Chilkat's local redirect listener.
+   * It is intended for troubleshooting callback and provider-parameter problems.
+   *
+   * ```
+   * GET /?state=...&code=... HTTP/1.1
+   * Host: 127.0.0.1:3017
+   * User-Agent: ...
+   * Accept: text/html,...
+   * ```
+   *
+   * The value can include the request target, query or form parameters, and browser-supplied
+   * headers.
+   *
+   * **Highly sensitive diagnostic data:** The request can contain an authorization code, state
+   * value, provider identifiers, and browser metadata. Do not record it in production logs without
+   * careful redaction.
+   *
+   * This property is read-only.
+   */
+  readonly redirectReqReceived: string
+
+  /**
+   * Allows the application to supply an explicit OAuth `state` value. Normally this property should
+   * remain empty so Chilkat generates a cryptographically random state value and validates the
+   * returned value automatically.
+   *
+   * The automatically generated state is intentionally not exposed through this property.
+   *
+   * The special token `{listenPort}` may appear in an explicitly supplied value. Chilkat replaces
+   * it with the actual listener port selected for the flow.
+   *
+   * **Do not weaken state:** State correlates the redirect with the initiating browser flow and
+   * helps prevent CSRF and authorization-response injection. If supplying your own value, make it
+   * unpredictable, unique per flow, and free of secrets or sensitive application data.
+   */
+  stateParam: string
+
+  /**
+   * Returns the local port selected for the current or most recently completed authorization flow.
+   *
+   * When a range is configured with {@link OAuth2.listenPortRangeEnd}, use this value to determine
+   * the actual loopback redirect port. It is also available for the `{listenPort}` substitution
+   * supported by {@link OAuth2.stateParam}.
+   *
+   * This property is read-only.
+   */
+  readonly listenPortSelected: number
+
+  /**
+   * Set to `true` to use the legacy out-of-band redirect URI `urn:ietf:wg:oauth:2.0:oob`. The
+   * application must obtain the displayed authorization code and pass it to {@link
+   * OAuth2.exchangeCodeForToken}. The default is `false`.
+   *
+   * **Legacy and often unsupported:** OOB authorization exposes a code for manual copy/paste and is
+   * no longer accepted by many providers. For desktop applications, use a loopback redirect with
+   * PKCE whenever possible.
+   */
+  oob: boolean
+
+  /**
+   * Controls automatic resolution of selected values from operating-system secure storage. The
+   * default is `false`.
+   *
+   * When `true`, the following properties may contain a secret specification beginning with `!!`
+   * instead of a literal value:
+   *
+   * - {@link OAuth2.authorizationEndpoint}
+   *
+   * - {@link OAuth2.tokenEndpoint}
+   *
+   * - {@link OAuth2.clientId}
+   *
+   * - {@link OAuth2.clientSecret}
+   *
+   * The specification has the form:
+   *
+   * ```
+   * !![appName|]service[|domain]|username
+   * ```
+   *
+   * Chilkat resolves the value through Windows Credential Manager on Windows or Apple Keychain on
+   * macOS.
+   *
+   * **Purpose:** Secret specifications allow deployment-specific values to remain outside source
+   * code and configuration files. Although endpoints and client IDs are not normally secret,
+   * resolving them the same way can centralize application configuration.
+   *
+   * **Platform availability:** This feature depends on supported operating-system credential
+   * storage. Ensure the named credential exists and that the process identity has permission to
+   * read it.
+   */
+  enableSecrets: boolean
+
+  // ---- Methods ----
+
+  /**
+   * Starts an OAuth 2.0 Authorization Code flow and returns the authorization URL that the
+   * application should open in the user's browser.
+   *
+   * Before calling this method, configure {@link OAuth2.clientId}, {@link
+   * OAuth2.authorizationEndpoint}, {@link OAuth2.tokenEndpoint}, the requested {@link
+   * OAuth2.scope}, and the redirect-listener settings such as {@link OAuth2.listenPort}. Configure
+   * {@link OAuth2.clientSecret} only when the provider requires client authentication for this
+   * application type.
+   *
+   * - Chilkat constructs and returns the provider's authorization URL.
+   *
+   * - Chilkat starts a background thread that listens for the redirect request, validates the
+   *   returned state, and exchanges the authorization code at the token endpoint.
+   *
+   * Open the returned URL with {@link OAuth2.launchBrowser} or another browser-launch mechanism.
+   * Poll {@link OAuth2.authFlowState} until the flow reaches a terminal state.
+   *
+   * **PKCE and client authentication:** Enabling {@link OAuth2.codeChallenge} protects the
+   * authorization code from interception and is strongly recommended for desktop and other native
+   * applications. PKCE does not make a client secret confidential and does not replace client
+   * authentication when the provider requires it for a confidential client.
+   *
+   * **Failure detection:** String-returning bindings return an empty or null-equivalent value on
+   * failure. Check the normal method-success indicator and inspect `LastErrorText` before
+   * attempting to open the returned URL.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  startAuth(): string
+
+  /**
+   * Requests cancellation of the authorization flow currently running in the background thread.
+   *
+   * Returns `true` if the cancellation request is accepted. After cancellation, inspect {@link
+   * OAuth2.authFlowState} and {@link OAuth2.failureInfo} to determine the final state.
+   *
+   * **Scope of cancellation:** This stops the local authorization operation. It does not revoke an
+   * access token, refresh token, authorization grant, or consent that the provider has already
+   * issued.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  cancel(): void
+
+  /**
+   * Suspends the calling thread for `millisec` milliseconds.
+   *
+   * This convenience method is commonly used in a polling loop that checks {@link
+   * OAuth2.authFlowState} while the authorization flow continues on Chilkat's background thread.
+   *
+   * **Thread behavior:** The calling thread is blocked for the requested interval. In a graphical
+   * application, use the platform's normal asynchronous or timer mechanism when blocking the UI
+   * thread would make the application unresponsive.
+   */
+  sleepMs(millisec: number): void
+
+  /**
+   * Sends a refresh-token grant request to {@link OAuth2.tokenEndpoint} to obtain a new access
+   * token without repeating interactive browser authorization.
+   *
+   * Configure {@link OAuth2.clientId}, {@link OAuth2.refreshToken}, and {@link
+   * OAuth2.tokenEndpoint}, together with whatever client authentication the provider requires. This
+   * may include {@link OAuth2.clientSecret} and {@link OAuth2.useBasicAuth}.
+   *
+   * On success, Chilkat updates {@link OAuth2.accessToken}, {@link OAuth2.tokenType}, and {@link
+   * OAuth2.accessTokenResponse}. If the provider rotates refresh tokens and returns a new
+   * `refresh_token`, {@link OAuth2.refreshToken} is also updated.
+   *
+   * **Persist rotated refresh tokens:** Some providers invalidate the old refresh token as soon as
+   * a new one is issued. After a successful refresh, securely persist the current value of
+   * `RefreshToken` rather than assuming the previous value remains usable.
+   *
+   * **Provider-specific requests:** Use {@link OAuth2.setRefreshHeader} and {@link
+   * OAuth2.addRefreshQueryParam} only when the provider documents additional headers or parameters.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link OAuth2.refreshAccessTokenAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  refreshAccessToken(): void
+
+  /**
+   * Asynchronous form of {@link OAuth2.refreshAccessToken}: the same call on a native worker
+   * thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link OAuth2.abort} (which cancels it) and the {@link OAuth2.onPercentDone} /
+   * {@link OAuth2.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  refreshAccessTokenAsync(): Promise<void>
+
+  /**
+   * Associates `sock` with this object for HTTP connections to the token endpoint. This method is
+   * optional.
+   *
+   * - Pass an unconnected `Socket` when it is configured with HTTP-proxy, SOCKS-proxy, local-bind,
+   *   or other connection options that Chilkat should use when opening the token-endpoint
+   *   connection.
+   *
+   * - Pass an already connected socket when traffic must travel through an established SSH tunnel
+   *   or another prebuilt connection.
+   *
+   * Without this method, Chilkat opens a direct TLS connection to the token endpoint.
+   *
+   * **Browser traffic is separate:** This socket controls Chilkat's back-channel token requests. It
+   * does not configure the user's browser, the provider's authorization page, or the browser's
+   * redirect to the local listener.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  useConnection(sock: Socket): void
+
+  /**
+   * Returns the decoded value of `paramName` from the authorization redirect received by Chilkat's
+   * local listener.
+   *
+   * Call this after the redirect has been received. It is useful for provider-specific parameters
+   * in addition to the standard `code`, `state`, and `error` values. For example, QuickBooks can
+   * return a company identifier named `realmId`:
+   *
+   * ```
+   * http://localhost:55568/?state=...&code=...&realmId=1234567890
+   * ```
+   *
+   * **Provider extensions:** OAuth defines the core redirect parameters, but providers may add
+   * their own values. Consult the provider's documentation before depending on an additional
+   * parameter.
+   *
+   * **Sensitive redirect data:** Authorization codes and related callback parameters are
+   * credentials or security-sensitive correlation values. Avoid writing them to ordinary
+   * application logs.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  getRedirectRequestParam(paramName: string): string
+
+  /**
+   * Adds or replaces an HTTP request header used by subsequent calls to {@link
+   * OAuth2.refreshAccessToken}. `name` is the header field name and `value` is its value.
+   *
+   * Call this method once for each required header. Passing an empty `value` removes the named
+   * header.
+   *
+   * ```
+   * Accept: application/json
+   * ```
+   *
+   * **Normally unnecessary:** Standard OAuth refresh requests do not require application-defined
+   * headers beyond those generated by the client. Add headers only when the authorization server
+   * explicitly requires them, and never place access tokens, refresh tokens, or client secrets in
+   * diagnostic headers.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  setRefreshHeader(name: string, value: string): void
+
+  /**
+   * Adds a provider-specific name/value parameter to the authorization-code token request that
+   * Chilkat sends after receiving the browser redirect. Call the method multiple times to add
+   * multiple parameters.
+   *
+   * This setting affects the code-for-token exchange performed by {@link OAuth2.startAuth} or
+   * {@link OAuth2.exchangeCodeForToken}; it does not alter the browser authorization URL or
+   * refresh-token requests.
+   *
+   * **Nonstandard extension:** The normal authorization-code request parameters are generated
+   * automatically. Use this method only for an additional parameter documented by the provider, and
+   * do not duplicate standard parameters such as `grant_type`, `code`, or `redirect_uri` unless
+   * instructed by Chilkat support.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  addTokenQueryParam(name: string, value: string): void
+
+  /**
+   * Adds a name/value query parameter to the authorization URL produced by {@link
+   * OAuth2.startAuth}. Call the method multiple times to add multiple provider-specific
+   * authorization parameters.
+   *
+   * Typical examples include provider extensions such as `access_type=offline`, `prompt=consent`,
+   * or an account-selection hint.
+   *
+   * **Do not add secrets:** Authorization parameters are placed in a URL and can appear in browser
+   * history, proxy logs, and diagnostics. Never put a client secret, access token, refresh token,
+   * or other credential in an authorization query parameter.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  addAuthQueryParam(name: string, value: string): void
+
+  /**
+   * Adds a provider-specific name/value parameter to requests sent by {@link
+   * OAuth2.refreshAccessToken}. Call the method multiple times to add multiple parameters.
+   *
+   * **Use only when documented:** Chilkat automatically supplies the standard refresh-token grant
+   * parameters. Additional parameters are provider extensions and should be added only when
+   * required by the authorization server.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  addRefreshQueryParam(name: string, value: string): void
+
+  /**
+   * Asks the operating system to open `url` in the user's default web browser. On Windows, macOS,
+   * and supported Linux desktop environments, an existing browser may open the URL in a new tab.
+   *
+   * This method is typically called with the authorization URL returned by {@link
+   * OAuth2.startAuth}. Returns `false` if the operating system cannot launch a browser or open the
+   * URL.
+   *
+   * **No browser automation:** This method only opens the URL. Chilkat does not control the
+   * browser, enter credentials, approve consent, or close the browser window.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  launchBrowser(url: string): void
+
+  /**
+   * Exchanges the authorization code in `code` for tokens at {@link OAuth2.tokenEndpoint}.
+   *
+   * This is used when the application obtains the authorization code outside Chilkat's
+   * local-listener workflow, most commonly with the legacy out-of-band mode selected by {@link
+   * OAuth2.oob}. Configure the same client, endpoint, redirect, PKCE, and token-request settings
+   * that the provider requires for the original authorization request.
+   *
+   * On success, the token properties and {@link OAuth2.accessTokenResponse} are populated in the
+   * same manner as a successful background exchange.
+   *
+   * **Legacy OOB flow:** Many major providers no longer accept `urn:ietf:wg:oauth:2.0:oob`. Prefer
+   * an authorization-code flow with a loopback redirect and PKCE whenever the provider supports it.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link OAuth2.exchangeCodeForTokenAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  exchangeCodeForToken(code: string): void
+
+  /**
+   * Asynchronous form of {@link OAuth2.exchangeCodeForToken}: the same call on a native worker
+   * thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link OAuth2.abort} (which cancels it) and the {@link OAuth2.onPercentDone} /
+   * {@link OAuth2.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  exchangeCodeForTokenAsync(code: string): Promise<void>
+
+  /**
+   * Copies the raw token-endpoint response into `sb` and returns `true` on success.
+   *
+   * This is the `StringBuilder` equivalent of reading {@link OAuth2.accessTokenResponse}. The
+   * response is commonly JSON, but some providers return form-encoded or other text; this method
+   * does not guarantee JSON.
+   *
+   * **Contains credentials:** The response can contain an access token and refresh token. Treat the
+   * destination `StringBuilder` as sensitive data and avoid logging or exposing its contents.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link OAuth2.lastErrorText}.
+   */
+  getAccessTokenResponseSb(sb: StringBuilder): void
+
+  // ---- Events (ReactNativeGen_DESIGN.md §6) ----
+
+  /**
+   * Called with the percent completed (0..100) while a long-running method runs, when Chilkat
+   * can measure progress. Runs on the JavaScript thread, so it is only useful with the
+   * `...Async` methods (during a synchronous call the thread is busy and the events arrive
+   * after it returns). Assign `undefined` to remove.
+   */
+  onPercentDone?: (pctDone: number) => void
+
+  /**
+   * Called with a name/value pair of progress information while a long-running method runs
+   * (what is reported depends on the class and method). Runs on the JavaScript thread; see
+   * {@link OAuth2.onPercentDone}. Assign `undefined` to remove.
+   */
+  onProgressInfo?: (name: string, value: string) => void
+
+  /**
+   * Requests that the pending `...Async` call on this object stop at its next progress check.
+   * The promise then rejects with Chilkat's abort error. Chilkat checks at least every
+   * `heartbeatMs` milliseconds on the classes that have that property, so set it (e.g. 250)
+   * for a responsive cancel. Harmless when nothing is pending.
+   */
+  abort(): void
+}