@chilkat/react-native 11.6.1

package/src/specs/HttpCurl.nitro.ts

@@ -0,0 +1,550 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { BinData } from './BinData.nitro'
+import type { JsonArray } from './JsonArray.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+import type { StringBuilder } from './StringBuilder.nitro'
+import type { Xml } from './Xml.nitro'
+
+/**
+ * curl-style HTTP requests with dependency resolution
+ *
+ * Run curl commands and automatically resolve values needed by later requests
+ *
+ * The `HttpCurl` class executes HTTP requests expressed as curl
+ * commands, with support for variable substitution, reusable curl functions, automatic
+ * dependency resolution, response extraction, and structured diagnostics.
+ *
+ * Variables such as `{{access_token}}`, `{{site_id}}`, or
+ * `{{drive_id}}` can appear in URLs, headers, query parameters, or request
+ * bodies. If a variable is not yet known, `HttpCurl` can build an execution
+ * plan from previously defined curl functions, run the prerequisite requests, extract
+ * values from JSON responses, and then execute the final target request.
+ *
+ * **Define dependencies**
+ * Use `AddFunction` with `AddOutput` or `AddOutput2`.
+ *
+ * **Manage variables**
+ * Use `SetVar`, `GetVar`, `ClearVar`, and `GetAllVars`.
+ *
+ * **Preview execution**
+ * Use `ExaminePlan` or `ToRawRequest` before sending.
+ *
+ * **Read responses**
+ * Get text, binary, JSON, XML, or stream directly to a file.
+ *
+ * After `DoYourThing` completes, check `StatusCode` and retrieve
+ * the response using the appropriate getter. If something fails,
+ * `FailReason`, `FailedCurl`, and `LastErrorText`
+ * help identify the failed step and the reason.
+ *
+ * **Note:**
+ * `HttpCurl` is not derived from curl/libcurl and does not wrap
+ * libcurl. It accepts curl-style command text and executes the request using Chilkat’s
+ * own HTTP implementation.
+ *
+ * For an extended overview, see
+ * [HttpCurl Class Overview](https://www.chilkatsoft.com/httpcurl_class_overview.asp).
+ *
+ * **See also:**
+ *
+ * -
+ * [HttpCurl Overview](https://www.chilkatsoft.com/httpcurl_overview.asp)
+ * — concepts, variable substitution, dependency resolution, and workflow examples.
+ *
+ * -
+ * [Dependency Engine](https://www.chilkatsoft.com/curl_dependency_engine.asp)
+ * — how execution plans are derived, unknown variables are resolved, and cached
+ * variables are managed.
+ *
+ * Each `HttpCurl` 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 HttpCurl()`.
+ *
+ * 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 HttpCurl.abort} and assigning {@link HttpCurl.onPercentDone} / {@link
+ * HttpCurl.onProgressInfo}.
+ */
+export interface HttpCurl 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
+
+  /**
+   * Returns the HTTP status code from the last call to {@link HttpCurl.doYourThing}. A value of `0`
+   * indicates no response header was received.
+   *
+   * This property is read-only.
+   */
+  readonly statusCode: number
+
+  /**
+   * Returns the HTTP response body from the last call to {@link HttpCurl.doYourThing}.
+   *
+   * This property is read-only.
+   */
+  readonly responseBodyStr: string
+
+  /**
+   * Set this property to the path of a file to stream the response body to a file. If the response
+   * is streamed to a file, it will not be available in {@link HttpCurl.responseBodyStr}, {@link
+   * HttpCurl.getResponseSb}, or {@link HttpCurl.getResponseBd}.
+   */
+  responseFilePath: string
+
+  /**
+   * Enables variable substitution in the body of the request.  The default value is `true`.
+   */
+  enableBodyVars: boolean
+
+  /**
+   * Set to an integer value indicating the reason for failure for the methods {@link
+   * HttpCurl.doYourThing} and {@link HttpCurl.examinePlan}
+   *
+   * Possible values are:
+   *
+   * - No error - the method succeeded or hasn't yet been called.
+   *
+   * - curl command syntax error.
+   *
+   * - HTTP response status code indidcates an authentication (401) or authorization (403) error.
+   *
+   * - HTTP response status code indicates an error, but not an authentication or authorization
+   *   error.
+   *
+   * - HTTP communications failure.
+   *
+   * - Impossible to derive an execution plan from defined outputs and inputs.
+   *
+   * - A step in the execution plan did not resolve any dependency variables.
+   *
+   * - Failed to get curl data from a local file source **(see the note below)**.
+   *
+   * - If we are within a `Chilkat.Js` context and don't have permission to read the local
+   *   filesystem.
+   *
+   * - Chilkat has not been successfully unlocked by previously and successfully calling
+   *   UnlockBundle.
+   *
+   * - Failed to open or create the local output file (if a curl option directed output to a file).
+   *
+   * **Note:** `curl` can read data from a local file and send it in a request (usually POST/PUT)
+   * using special syntax:
+   *
+   * - `-d @file.txt` → reads the file and sends it as request body (form-style encoding).
+   *
+   * - `--data-binary @file.bin` → sends raw file contents exactly as-is.
+   *
+   * - `-F "file=@file.txt"` → uploads the file as multipart/form-data.
+   *
+   * The `@` tells `curl` to load the data from a local file instead of using a literal string.
+   *
+   * This property is read-only.
+   */
+  readonly failReason: number
+
+  /**
+   * Set to the specific curl command in the execution plan that failed.
+   *
+   * This property is read-only.
+   */
+  readonly failedCurl: string
+
+  /**
+   * Specifies the interval, in milliseconds, between `AbortCheck`
+   * event callbacks.
+   *
+   * This allows an application to periodically decide whether a long-running
+   * operation should be aborted.
+   *
+   * The default value is `0`, which means no `AbortCheck`
+   * callbacks are generated.
+   */
+  heartbeatMs: number
+
+  /**
+   * Provides a comma-separated list of uncommon option keywords.
+   *
+   * This property defaults to an empty string and should normally remain empty.
+   */
+  uncommonOptions: string
+
+  // ---- Methods ----
+
+  /**
+   * Runs a the `targetCurl` command specified in `targetCurl`. If the `targetCurl` contains
+   * variable names enclosed in `{{` and `}}`, then an execution plan is constructed from defined
+   * functions and outputs to resolve unknown variables, and the execution plan is run. The final
+   * step in the execution plan is always the `targetCurl` command.
+   *
+   * Returns success (`true`) if a response was received, in which case the response status code
+   * will be available in {@link HttpCurl.statusCode} and the content of the response body will be
+   * available in one of two places:
+   *
+   * - If {@link HttpCurl.responseFilePath} is non-empty, the response body was streamed to the
+   *   specified file path.
+   *
+   * - If {@link HttpCurl.responseFilePath} is empty, the response body can be retrieved via {@link
+   *   HttpCurl.responseBodyStr}, {@link HttpCurl.getResponseSb}, or {@link HttpCurl.getResponseBd}.
+   *   Binary responses should only be retrieved via `ResponseBodyBd`.
+   *
+   * Assuming the HTTP response is JSON, the target outputs (variables) specified by prior calls to
+   * {@link HttpCurl.addTargetOutput} will be populated by applying each variable's JSON path to the
+   * response JSON.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link HttpCurl.doYourThingAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  doYourThing(targetCurl: string): void
+
+  /**
+   * Asynchronous form of {@link HttpCurl.doYourThing}: 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 HttpCurl.abort} (which cancels it) and the {@link HttpCurl.onPercentDone} /
+   * {@link HttpCurl.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  doYourThingAsync(targetCurl: string): Promise<void>
+
+  /**
+   * Sets authorization information that is applied to all calls to {@link HttpCurl.doYourThing}.
+   * See the examples below for details.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  setAuth(json: JsonObject): void
+
+  /**
+   * Used for debugging purposes. This method behaves the same as {@link HttpCurl.doYourThing}, but
+   * only converts the `curlCommand` to an HTTP request message in `sb` containing the full
+   * structure:
+   *
+   * - start line
+   *
+   * - headers
+   *
+   * - optional body or multipart body
+   *
+   * It does not actually send the HTTP request.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  toRawRequest(curlCommand: string, sb: StringBuilder): void
+
+  /**
+   * Appends to `sb` the HTTP response body from the last call to {@link HttpCurl.doYourThing}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  getResponseSb(sb: StringBuilder): void
+
+  /**
+   * Appends to `bd` the HTTP response body from the last call to {@link HttpCurl.doYourThing}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  getResponseBd(bd: BinData): void
+
+  /**
+   * Writes to `json` the HTTP response body from the last call to {@link HttpCurl.doYourThing}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  getResponseJson(json: JsonObject): void
+
+  /**
+   * Writes to `xml` the HTTP response body from the last call to {@link HttpCurl.doYourThing}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  getResponseXml(xml: Xml): void
+
+  /**
+   * Writes to `jarr` the HTTP response body from the last call to {@link HttpCurl.doYourThing}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  getResponseJarr(jarr: JsonArray): void
+
+  /**
+   * Sets the value of a variable to be replaced in curl commands. Variable names are enclosed in
+   * `{{` and `}}` and can occur in the path, query params, or the body of the request.
+   */
+  setVar(varName: string, varValue: string): void
+
+  /**
+   * Adds an automatically mapped variable for the target curl command. When a JSON response is
+   * received from a curl request, the value at the JSON path specified by `jsonPath` is extracted
+   * (if present) and assigned to the variable named by `varName`.
+   *
+   * This is useful in common workflows where one request returns an identifier (such as an \`id\`)
+   * that must be reused in a subsequent curl request.
+   */
+  addTargetOutput(jsonPath: string, varName: string): void
+
+  /**
+   * Undefines the variable with the specified name. If `varName` equals `"*"`, then all variables
+   * are cleared.
+   */
+  clearVar(varName: string): void
+
+  /**
+   * Retrieves the current value of the variable specified by `varName`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  getVar(varName: string): string
+
+  /**
+   * Adds a named curl function that can be used in dependency resolution. Inputs required by the
+   * curl function are indicated by the variable names enclosed in `{{` and `}}`. Outputs are
+   * defined in one or more calls to {@link HttpCurl.addOutput}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  addFunction(funcName: string, curl: string): void
+
+  /**
+   * Adds or updates a defined output for a dependency resolution curl function previously defined
+   * by calling {@link HttpCurl.addFunction}. The `jsonPath` is the JSON path in the JSON response
+   * body where the `varName`'s value is located. If either the `funcName` or `jsonPath` already
+   * exist for the `funcName`, then the output is updated.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  addOutput(funcName: string, jsonPath: string, varName: string): void
+
+  /**
+   * Used for debugging. Returns in `json` the plan of execution that would occur for the `curl`
+   * based on the variables that are either unknown or already known. The plan of execution is what
+   * would occur if {@link HttpCurl.doYourThing} was called with the current state of knowledge.
+   *
+   * If no execution plan is possible with the current known inputs and outputs, then `json`
+   * provides information about what is missing and the method returns `false`.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  examinePlan(curl: string, json: JsonObject): void
+
+  /**
+   * Returns all defined variables in `json`.
+   */
+  getAllVars(json: JsonObject): void
+
+  /**
+   * Clears (undefines) the target output for the specified `varName`. If `varName` equals `"*"`,
+   * then all target outputs are cleared.
+   */
+  clearTargetOutput(varName: string): void
+
+  /**
+   * Returns `true` if the `varName` is defined, otherwise returns `false`. Setting `varName` to
+   * `"!"` checks whether all target output variables have been defined. It returns `true` if every
+   * target output is set, and `false` if any are missing.
+   */
+  varDefined(varName: string): boolean
+
+  /**
+   * Adds or updates an output variable definition for a dependency-resolution curl function
+   * previously created by calling
+   * `AddFunction`.
+   * Use this method when the curl response is JSON containing an array of objects, and a value
+   * needs to be extracted
+   * from one specific array element.
+   *
+   * The method searches the array located at `arrayPath`, finds the array element where the value
+   * at
+   * `wherePath` matches `whereValue`, and then extracts the value at `subPath`.
+   * The extracted value is assigned to the variable named by `varName`.
+   *
+   * The `wherePath` and `subPath` values are paths relative to each individual array element.
+   * The comparison between `whereValue` and the JSON value found at `wherePath` is either
+   * case-sensitive or case-insensitive depending on the value of `caseSensitive`.
+   *
+   * **Parameters**
+   *
+   * -
+   * `funcName` — The name of the curl function previously added by calling `AddFunction`.
+   * The output definition is associated with this function.
+   *
+   * -
+   * `arrayPath` — The JSON path identifying the array of records within the JSON response.
+   *
+   * -
+   * `wherePath` — A relative JSON path within each array element used to locate the matching
+   * record.
+   *
+   * -
+   * `whereValue` — The value to match against the JSON value found at `wherePath`.
+   *
+   * -
+   * `caseSensitive` — If `true`, the comparison between `whereValue` and the JSON value is
+   * case-sensitive. If `false`, the comparison is case-insensitive.
+   *
+   * -
+   * `subPath` — A relative JSON path within the matched array element identifying the value to
+   * extract.
+   *
+   * -
+   * `varName` — The name of the variable that will receive the extracted value.
+   *
+   * **Example**
+   *
+   * Given the following JSON response:
+   *
+   * ```
+   * {
+   *   "drives": [
+   *     {
+   *       "name": "Documents",
+   *       "id": "A123"
+   *     },
+   *     {
+   *       "name": "Shared",
+   *       "id": "B456"
+   *     }
+   *   ]
+   * }
+   * ```
+   *
+   * The following call:
+   *
+   * ```
+   * AddOutput2("GetDrive","drives","name","shared",false,"id","drive_id")
+   * ```
+   *
+   * searches the `drives` array for the element whose `name` matches
+   * `"shared"` using case-insensitive comparison. The matching element is:
+   *
+   * ```
+   * {
+   *   "name": "Shared",
+   *   "id": "B456"
+   * }
+   * ```
+   *
+   * The value of `id` is extracted and assigned to the variable
+   * `drive_id`, resulting in:
+   *
+   * ```
+   * drive_id = "B456"
+   * ```
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link HttpCurl.lastErrorText}.
+   */
+  addOutput2(funcName: string, arrayPath: string, wherePath: string, whereValue: string, caseSensitive: boolean, subPath: string, varName: string): 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 HttpCurl.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
+}