# Getting Started

### Overview

The Pepperi JS Client Side API (Beta) enables you to extend the functionality of Pepperi’s Native and Web Apps. This API operates within the Rule-Engine-based User Defined Fields (UDFs) or Workflow’s Custom Web Forms. 

***

### Namespace: pepperi.api

* **peperi.api Namespace:**
  * Functions do not trigger auto-calculation of the app’s business logic (Rule Engine).
  * Suitable for use in calculated UDFs within the Rule Engine.
  * Only “api” functions are supported in the Rule Engine.
* **peperi.app Namespace:**
  * Triggers the app’s business logic (Rule Engine) for calculations.
  * Supported functions:
    * peperi.app.accounts.update
    * peperi.app.activities.update
    * peperi.app.transactions.update
    * peperi.app.transactionLines.update
    * peperi.app.transactionScopeItems.update
    * peperi.app.transactions.addLines
    * peperi.app.transactions.removeLines
  * Both “api” and “app” namespaces can be used in Custom Web Forms (visible or hidden) as a step in a Workflow.

***

### Asynchronous Behavior: Custom Web Forms vs Calculated UDFs

* **Custom Web Forms:**
  * All Client API functions operate asynchronously.
  * Two additional parameters are required:
    * responseCallback: Callback function to handle the response.
    * requestID: Optional identifier for the request (recommended for tracking).
  * **Example:**

    ```javascript
    pepperi.api.activities.get({
      key: { UUID: "aefb523e-74ac-4041-8bb1-a76a3b5e78d8" },
      fields: ["ExternalID", "MyTSA"],
      responseCallback: "<your_callback_function>",
      requestID: "<your_request_id>"
    });
    ```
* **Calculated UDFs (Rule Engine):**
  * Synchronous execution; no asynchronous parameters needed.

***

### Date and Time Handling

* **API Format:** Dates are retrieved and updated in UTC only, using ISO 8601 format (e.g., 2018-12-18T12:29:02Z or 2018-12-18Z).
* **Rule Engine Format:**
  * Retrieved via GetValueByAPIName in Unix timestamp format (seconds since January 1, 1970, UTC).
  * Conversion required for updates. **Example:**

    ```javascript
    var date = new Date(TSACaptureDateTime * 1000); // Convert to milliseconds
    var ret_object = pepperi.api.accounts.update({
      objects: [{
        UUID: GetValueByApiName("Account.UUID"),
        TSALastActiveDate: date.toISOString() // Update in UTC ISO format
      }]
    });
    ```
* **Filters:** Dates in filter objects can be non-UTC; the function converts them internally to UTC.

***

### Logging

* **Purpose:** Send logs to Pepperi servers to track issues.
* **Behavior:**
  * iOS/Android: Logs sent only on app crashes.
  * Web App: Logs sent constantly in real-time.
* **Syntax:**

  ```javascript
  pepperi.log({ message: "<your message>", verbosity: "Low" });
  ```

  * **verbosity:** Optional (Low, Medium, High); defaults to Low.

***

### Error Handling

* **Error Object:** All functions return the same error structure on failure:

  ```json
  {
    "success": false,
    "value": "",
    "error": {
      "code": 54,
      "message": "<relevant error message>"
    }
  }
  ```

***

### Context Retrieval

* **Purpose:** Retrieves the run-time scope, crucial for Custom Web Forms within Workflows.
* **Syntax:**
  * **Custom Web Forms (Async):**

    ```javascript
    pepperi.app.getContext({ responseCallback: "mycallback" });
    ```
  * **Calculated UDFs (Sync):**

    ```javascript
    var ret = pepperi.app.getContext({});
    ```
* **Returned Object:**

  ```json
  {
    "CPIDateTime": "2018-12-23T12:34:56Z",
    "appVersion": "",
    "appType": "web",
    "OSType": "",
    "OSVersion": "",
    "company": {
      "id": 30011895,
      "name": "Regine_DO_NOT_CHANGE_ClientAPI"
    },
    "user": {
      "id": 4492855,
      "uuid": "d8ce933a-a0dd-4a9f-9b88-c83581180dc5",
      "externalId": ""
    },
    "account": {
      "id": 18163276,
      "name": "Cat n Dog New",
      "uuid": "67274419-7f66-46f6-847a-72aa19d3db8a"
    },
    "transaction": {
      "id": -50,
      "externalId": "",
      "uuid": "131023c8-bbfd-4a15-ba4b-030fe7bdb44c"
    }
  }
  ```

***

### Filter Object for Search Functions

* **Purpose:** Used in “search” functions across the Client API to filter multiple objects.
* **Simple Example:**

  ```json
  {
    "ApiName": "UnitPrice",
    "Operation": ">=",
    "Values": ["7"]
  }
  ```
* **Complex Example with Multiple Conditions:**

  ```json
  {
    "Operation": "AND",
    "LeftNode": {
      "ApiName": "UnitPrice",
      "Operation": ">",
      "Values": ["7"]
    },
    "RightNode": {
      "ApiName": "Transaction.ActionDateTime",
      "Operation": "InTheLast",
      "Values": ["4", "Weeks"]
    }
  }
  ```
* **Supported Operators by Data Type:**

  ```json
  {
      "String": [
          "Contains",
          "StartWith",
          "EndWith",
          "IsEqual",
          "IsNotEqual",
          "IsEmpty",
          "IsNotEmpty"
      ],
      "Integer": [
          ">",
          "<",
          "=",
          ">=",
          "<=",
          "!=",
          "Between",
          "IsEmpty",
          "IsNotEmpty"
      ],
      "Real": [
          ">",
          "<",
          "=",
          ">=",
          "<=",
          "!=",
          "Between",
          "IsEmpty",
          "IsNotEmpty"
      ],
      "Boolean": [
          "IsEqual"
      ],
      "DateTime": [
          "Today",
          "ThisWeek",
          "ThisMonth",
          "Before",
          "After",
          "Between",
          "On",
          "InTheLast",
          "NotInTheLast",
          "DueIn",
          "NotDueIn",
          "IsEmpty",
          "IsNotEmpty"
      ],
      "File": [
          "IsEmpty",
          "IsNotEmpty"
      ],
      "MultiDropDown": [
          "IsEqual",
          "IsNotEqual",
          "IsEmpty",
          "IsNotEmpty"
      ],
      "PropertyMultiDropDown": [
          "IsEqual",
          "IsNotEqual",
          "IsEmpty",
          "IsNotEmpty"
      ],
      "UsersSpecialMultiDropDown": [
          "IsLoggedInUser",
          "IsEqual",
          "IsNotEqual",
          "IsEmpty",
          "IsNotEmpty"
      ]
  }
  ```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.pepperi.com/master.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.