@chilkat/react-native 11.6.1

package/src/specs/AuthGoogle.nitro.ts

@@ -0,0 +1,291 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { JsonObject } from './JsonObject.nitro'
+import type { Pfx } from './Pfx.nitro'
+import type { Socket } from './Socket.nitro'
+
+/**
+ * Obtain Google OAuth 2.0 access tokens using a service account.
+ *
+ * `AuthGoogle` obtains OAuth 2.0 access tokens for Google
+ * Cloud Platform APIs and Google Apps APIs using a Google service account. It
+ * supports JSON private keys and P12 private keys, OAuth scopes, optional
+ * delegated user access, custom JWT claims, access-token validity tracking,
+ * token lifetime settings, and integration with Chilkat request classes that
+ * need a Google bearer token.
+ *
+ * **Service account auth**
+ *
+ * Authenticate server-to-server using a Google service account rather than
+ * an interactive browser-based user consent flow.
+ *
+ * **JSON or P12 keys**
+ *
+ * Load service account credentials from modern JSON private keys or from
+ * legacy P12 private key files.
+ *
+ * **Scopes and claims**
+ *
+ * Specify the OAuth scopes required by the target Google API and add custom
+ * JWT claims when needed.
+ *
+ * **Delegated user access**
+ *
+ * Use domain-wide delegation by setting a subject email when the service
+ * account is authorized to act on behalf of a Google Workspace user.
+ *
+ * **Access-token tracking**
+ *
+ * Inspect the generated access token, expiration time, remaining lifetime,
+ * and validity state before using or refreshing credentials.
+ *
+ * **Chilkat API integration**
+ *
+ * Pass the resulting bearer token to Chilkat HTTP, REST, storage, mail, or
+ * other Google API request workflows.
+ *
+ * **Common pattern:**
+ * Load the service account JSON key or P12 key, set the service account email,
+ * required `Scope`, optional delegated `SubEmailAddress`,
+ * and token lifetime, then call `ObtainAccessToken`. Use
+ * `AuthGoogle` for service-account OAuth flows; use
+ * `Chilkat.OAuth2` when the application needs an interactive
+ * three-legged OAuth flow involving a user's browser consent.
+ *
+ * For an extended overview, see
+ * [AuthGoogle Class Overview](https://www.chilkatsoft.com/authgoogle_class_overview.asp).
+ *
+ * Each `AuthGoogle` 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 AuthGoogle()`.
+ *
+ * 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 AuthGoogle.abort} and assigning {@link AuthGoogle.onPercentDone} / {@link
+ * AuthGoogle.onProgressInfo}.
+ */
+export interface AuthGoogle 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
+
+  /**
+   * The access token to be used in Google API requests. This property is set on a successful call
+   * to ObtainAccessToken.
+   *
+   * **Important:** This class is used for authenticating calls to the Google Cloud Platform API and
+   * Google Apps API using a **service account.**.
+   * For 3-legged OAuth2, where a browser must be used to interactively get permission from the
+   * Google account owner, use the Chilkat OAuth2 class/object.
+   */
+  accessToken: string
+
+  /**
+   * The client email address of the service account. If a JSON key is used, then the client_email
+   * should already be specified within the JSON key, and this property is unused. This property
+   * must be set if using a P12 key.
+   */
+  emailAddress: string
+
+  /**
+   * The expiration time, in seconds, of the access token to be requested. The maximum value is 1
+   * hour (3600 seconds). The default value is 3600.
+   */
+  expireNumSeconds: number
+
+  /**
+   * The JSON key for obtaining an access token. An application must set either the P12 or JSON
+   * private key, but not both.
+   */
+  jsonKey: string
+
+  /**
+   * If the access token is valid, contains the number of seconds remaining until it expires. A
+   * value of 0 indicates an invalid or expired access token.
+   *
+   * This property is read-only.
+   */
+  readonly numSecondsRemaining: number
+
+  /**
+   * A space-delimited list of the permissions that the application requests.
+   */
+  scope: string
+
+  /**
+   * The email address of the user for which the application is requesting delegated access.
+   */
+  subEmailAddress: string
+
+  /**
+   * `true` if the AccessToken property contains a valid non-expired access token obtained via the
+   * call to ObtainAccessToken.
+   *
+   * This property is read-only.
+   */
+  readonly valid: boolean
+
+  /**
+   * This property can be set to override the default current date/time value for the `iat` claim of
+   * the JWT. It can be set to a value indicating the number of seconds from 1970-01-01T00:00:00Z
+   * UTC.
+   *
+   * The default value is 0, which indicates to use the iat value for the current system date/time.
+   * Unless explicitly needed, always leave this property at the default value.
+   */
+  iat: number
+
+  // ---- Methods ----
+
+  /**
+   * Returns the private key in a PFX (P12) object. This is only possible if the private key was
+   * previously set by calling SetP12.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link AuthGoogle.lastErrorText}.
+   */
+  getP12(): Pfx
+
+  /**
+   * Sends the HTTP request to fetch the access token. When this method completes successfully, the
+   * access token is available in the AccessToken property. The `connection` is an existing
+   * connection to www.googleapis.com.
+   *
+   * **Important:** Make sure your computer's date/time is accurately set to the current date/time,
+   * otherwise you'll get a 400 response status code with this error: `Invalid JWT: Token must be a
+   * short-lived token (60 minutes) and in a reasonable timeframe. Check your iat and exp values and
+   * use a clock with skew to account for clock differences between systems.`.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link AuthGoogle.obtainAccessTokenAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link AuthGoogle.lastErrorText}.
+   */
+  obtainAccessToken(connection: Socket): void
+
+  /**
+   * Asynchronous form of {@link AuthGoogle.obtainAccessToken}: 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 AuthGoogle.abort} (which cancels it) and the {@link AuthGoogle.onPercentDone} /
+   * {@link AuthGoogle.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link AuthGoogle.lastErrorText}.
+   */
+  obtainAccessTokenAsync(connection: Socket): Promise<void>
+
+  /**
+   * Sets the P12 private key to be used for obtaining an access token. An application must set
+   * either the P12 or JSON private key, but not both.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link AuthGoogle.lastErrorText}.
+   */
+  setP12(key: Pfx): void
+
+  /**
+   * Adds additional custom claims to the JWT claims set.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link AuthGoogle.lastErrorText}.
+   */
+  addClaims(json: JsonObject): 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 AuthGoogle.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
+}