Metadata-Version: 2.2
Name: mercury-orm
Version: 0.2.2
Summary: ORM for Custom Objects de Zendesk
Home-page: https://github.com/BCR-CX/mercury-orm
Author: Pedro Andrade
Author-email: pedro.moisesandrade@gmail.com
License: MIT
Project-URL: Homepage, https://github.com/BCR-CX/mercury-orm
Project-URL: Issues, https://github.com/BCR-CX/mercury-orm/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: Unidecode==1.3.8
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Mercury (ORM Zendesk CustomObjects)

Mercury is a Python ORM (Object-Relational Mapping) designed to integrate seamlessly with the Zendesk Custom Objects API. It provides a Django-like interface for defining, managing, and interacting with Zendesk custom objects and records, simplifying the communication with Zendesk's API.

## Key Features

-   **Custom Object Representation**: Define Zendesk custom objects using Python classes.
-   **Automatic Record Management**: Built-in methods for creating, reading, updating, and deleting records via Zendesk's API.
-   **Support for All Field Types**: Compatible with all Zendesk custom field types including name, text, dropdown, checkbox, date, integer, and more.
-   **Automatic Object Creation**: Automatically create Zendesk custom objects and fields from Python class definitions.
-   **Easy Record Operations**: Simple API to manage custom object records, with built-in support for querying, filtering, and pagination.
-   **Support field Name autoincrement and unique constraint**: Supports automatic field name incrementation and enforcement of unique constraints.

## Installation

```bash
pip install mercury-orm
# add variables in .env or:
export ZENDESK_SUBDOMAIN=<your_zendesk_subdomain>.
export ZENDESK_API_TOKEN=<your_zendesk_api_token>.
export ZENDESK_EMAIL=<your_zendesk_email>.
```

## CRUD Operations with Records

Mercury ORM provides simple methods for performing CRUD (Create, Read, Update, Delete) operations on Zendesk custom object records. Below are examples of how to manage records in your custom objects.

### Creating a CustomObjects

```
class Product(CustomObject):
    name = fields.TextField("name")
    code = fields.TextField("code")
    description = fields.TextareaField("description")
    price = fields.DecimalField("price")
    active = fields.CheckboxField("active")
    voltage = fields.DropdownField("voltage", choices=["220", "110", "Bivolt"])
```

### Creating a Custom Object and Fields in Zendesk

Once you define the custom object class, you can create it in Zendesk using ZendeskObjectManager. This will automatically create the custom object and its fields in Zendesk.

```
from mercuryormc.zendesk_manager import ZendeskObjectManager

# Create the custom object and fields in Zendesk
manager = ZendeskObjectManager()
manager.create_custom_object_from_model(Product)
# or
manager.get_or_create_custom_object_from_model(Product)
```

### Record Manager

Each custom object class is automatically assigned a RecordManager that handles interaction with the Zendesk API. The RecordManager allows you to:

-   Create records: `Product.objects.create(**kwargs)`
-   Get a single record: `Product.objects.get(id=1)`
-   Filter records: `Product.objects.filter(active=True)`
-   Delete records: `Product.objects.delete(id=1)`
-   Retrieve all records: `Product.objects.all()`
-   Search all records: `Product.objects.search(word="something")`
-   Find records: `Product.objects.find(filters=filters)`
-   Find records with pagination: `Product.objects.find_paginated(filters=filters)`

### Creating a Record

You can create a new record by instantiating your custom object and calling the `save()` method:

```python
product = Product(name="Sample Product", code="12345", price=99.99, active=True)
product.save()

#or
Product.objects.create(name="Sample Product", code="12345", price=99.99, active=True)
```

### Retrieving a Record

You can retrieve an individual record by using the get() method:

```
retrieved_product = Product.objects.get(id=product.id)
```

### Updating a Record

To update a record, modify its attributes and call the save() method again:

```
retrieved_product.price = 89.99
retrieved_product.save()
```

### Deleting a Record

To delete a record from Zendesk, call the delete() method on the object:

```
retrieved_product.delete()
```

## Querying and Filtering Records

You can retrieve all records or filter them based on certain criteria.

```
all_products = Product.objects.all()
filtered_products = Product.objects.filter(active=True)
last_object = Product.objects.last()
find_products = Products.objects.find(filters=filters)
find_products_paginated = Products.objects.find_paginated(filters=filters)
```

## Find Method Explanation

The `find` method is based on Zendesk's filtering options for custom objects. It allows filtering records using logical operators and comparison operators.

### Supported Logical Operators

-   **`$or`**
-   **`$and`**

### Supported Comparison Operators

#### Custom Fields:

Custom objects have the following types of custom fields that you can filter on:

| Field Type          | Supported Operators                                                       | Meaning (in same order)                                                   |
| ------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Checkbox            | `$eq`                                                                     | is                                                                        |
| Date                | `$eq`, `$noteq`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`                  | is, is not, after, after or on, before, before or on, present, in range   |
| Decimal             | `$eq`, `$noteq`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`, `$in`, `$notin` | is, is not, after, after or on, before, before or on, present, in, not in |
| Drop-down           | `$eq`, `$noteq`, `$contains`, `$notcontains`, `$exists`                   | is, is not, contains, not contained, present                              |
| Integer             | `$eq`, `$noteq`, `$gt`, `$gte`, `$lt`, `$lte`, `$exists`, `$in`, `$notin` | is, is not, after, after or on, before, before or on, present, in, not in |
| Lookup Relationship | `$eq`, `$noteq`, `$exists`                                                | is, is not, present                                                       |
| Multi-line text     | `$eq`, `$noteq`, `$contains`, `$notcontains`, `$exists`                   | is, is not, contains, not contained, present                              |
| Multi-select        | `$eq`, `$noteq`, `$contains`, `$notcontains`, `$exists`, `$in`, `$notin`  | is, is not, contains, not contained, present, in, not in                  |
| Text                | `$eq`, `$noteq`, `$contains`, `$notcontains`, `$exists`                   | is, is not, contains, not contained, present                              |

---

#### Standard Fields

Custom objects have the following standard fields that you can filter on:

| Field Type        | Supported Operators | Meaning (in same order)    |
| ----------------- | ------------------- | -------------------------- |
| `created_at`      | `$gt`               | after                      |
| `created_by_user` | `$eq`               | is equal to a user ID      |
| `external_id`     | `$eq`               | is equal to an external ID |
| `name`            | `$contains`         | contains                   |
| `updated_at`      | `$gt`               | after                      |
| `updated_by_user` | `$eq`               | is equal to a user ID      |

### Filter Examples

#### Single Comparison

```python
filters = {
    {"custom_object_fields.price": {"$eq": "12"}}
}
```

In this case, records where the field named `price` is equal to **12** will be returned.

#### OR Comparison

```python
filters = {
    "$or": [
        {"name": {"$contains": "value"}},
        {"updated_at": {"$gt": "2024-12-13"}}
    ]
}
```

In this case, records where the `name` contains **value** or `updated_at` is greater than **2024-12-13** will be returned

#### AND Comparison

```python
filters = {
    "$and": [
        {"name": {"$contains": "value"}},
        {"updated_at": {"$gt": "2024-12-13"}}
    ]
}
```

In this case, records where the `name` contains **value** and `updated_at` is greater than **2024-12-13** will be returned.

#### Combined OR and AND Comparison

```python
filters = {
    "$or": [
        {"name": {"$contains": "value"}},
        {"updated_at": {"$gt": "2024-12-13"}}
    ],
    "$and":[
        {"custom_object_fields.price": {"$eq": "12"}},
        {"custom_object_fields.origin": {"$eq": "BR"}}
    ]
}
```

In this case, records matching the `OR` conditions (`name` contains **value** or `updated_at` is greater than **2024-12-13**) and the `AND` conditions (`price` equals **12** and `origin` equals **BR**) will be returned.

For more information, visit: [Zendesk Documentation](https://developer.zendesk.com/documentation/custom-data/v2/searching-custom-object-records/)
