Metadata-Version: 2.4
Name: sugarcrm_25_api
Version: 0.1.1
Summary: Lightweight REST API client for on-site SugarCRM 25.1.3
Project-URL: Source, https://github.com/makaveli006/sugarcrm_25_api.git
Author: Subin
License-Expression: MIT
License-File: LICENSE
Keywords: crm,oauth2,rest-api,sugarcrm
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Description-Content-Type: text/markdown

# 🧡 SugarCRM API Toolkit

A lightweight Python client library for talking to an **on-site SugarCRM 25.1.3** instance over its REST API (`v11_24`).

No manual OAuth handling, no repeated logins — just import the functions you need and go. 🚀

---

## 📦 What's Inside

- **`sugarcrm_25_api`** — the core library (`pip install sugarcrm_25_api`). Everything lives here:
  - 🔐 OAuth2 login, token caching (`.sugar_token.json`), and automatic refresh
  - 🧱 CRUD helpers — `get_record`, `list_records`, `create_record`, `update_record`, `delete_record`
  - 📎 File uploads — `upload()` (Documents, audio, any file type; can link + set a relate field in one call)
  - ⚡ Bulk operations — `bulk_create`, `bulk_update`, `bulk_delete` (chunked, parallelized, with retries)
  - 🛠️ `raw()` — an escape hatch for any REST endpoint not covered by the typed helpers

---

## ⚙️ Setup

1. **Install the package**

   ```bash
   pip install sugarcrm_25_api
   # or, if using uv:
   uv add sugarcrm_25_api
   ```

2. **Create a `.env` file**

   The library reads credentials from a `.env` file in the **current working directory** — wherever you run your script from. It's not shipped as part of the pip install, so if you didn't clone this repo, create it yourself with these keys:

   ```env
   # Instance base URL, no trailing slash (e.g. https://yourcompany.sugarondemand.com)
   SUGAR_URL=

   # REST API version — defaults to v11_24 if omitted
   SUGAR_API_VERSION=v11_24

   # Platform name registered in Admin > Configure API Platforms
   SUGAR_PLATFORM=

   # Sugar user credentials (ideally a dedicated API-only account)
   SUGAR_USERNAME=
   SUGAR_PASSWORD=

   # OAuth2 client registered on the platform
   SUGAR_CLIENT_ID=
   SUGAR_CLIENT_SECRET=
   ```

   (If you did clone this repo, `.env.example` has the same template — just `cp .env.example .env`.)

   | Variable | Description |
   |---|---|
   | `SUGAR_URL` | Base URL of your on-site Sugar instance (no trailing slash) |
   | `SUGAR_API_VERSION` | REST API version — defaults to `v11_24` |
   | `SUGAR_PLATFORM` | Platform name registered in **Admin > Configure API Platforms** |
   | `SUGAR_USERNAME` / `SUGAR_PASSWORD` | Credentials for a Sugar user (ideally a dedicated API-only account) |
   | `SUGAR_CLIENT_ID` / `SUGAR_CLIENT_SECRET` | OAuth2 client registered on the platform |

   ⚠️ **Never commit `.env`** — it holds live credentials. It's already excluded in `.gitignore`.

3. **You're ready.** Import what you need:

   ```python
   from sugarcrm_25_api import list_records, update_record, bulk_create

   hits = list_records("Contacts", {"last_name": "Rodriguez"})
   update_record("Contacts", hits["records"][0]["id"], {"case_status_c": "Open"})
   bulk_create("Contacts", "new_claimants.json", chunk=100, parallel=3)
   ```

---

## 🔑 How Auth Works

- First call automatically logs in and caches the token to `.sugar_token.json`.
- Every subsequent call reuses that cached token — no repeated logins.
- Tokens auto-refresh when they're near expiry; if a refresh fails, it falls back to a fresh login.
- Safe for concurrent/parallel use — if multiple processes race to refresh, they'll pick up each other's cached token instead of colliding.

---

## 🧯 Safety Notes

- `bulk_delete()` defaults to `dry_run=True` — it only **counts** matches until you explicitly pass `dry_run=False`.
- `.env` and `.sugar_token.json` contain live secrets — both are git-ignored by default. Double-check before committing anything.
- This targets an **on-site (self-hosted)** Sugar instance, not SugarCloud — there's no vendor-managed rate limiting, so be mindful of `parallel`/`chunk` sizes on bulk operations to avoid overloading the server.

---

## 🏥 Context

Built against a healthcare/claims-oriented Sugar instance (custom modules like Hospital Systems, Encounters, Medical Records, Eligibility Results) — so some helpers (e.g. `attach_audio`-style file linking via `upload()`) are tailored to that workflow, but the core CRUD/bulk API is generic and reusable for any module.
