Metadata-Version: 2.4
Name: sugarcrm_25_api
Version: 0.1.0
Summary: Lightweight REST API client for on-site SugarCRM 25.1.3
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

- **`sugar_api.py`** — the core library. 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 dependencies**

   ```bash
   pip install -r requirements.txt
   # or, if using uv/pyproject.toml:
   uv sync
   ```

2. **Configure credentials**

   Copy `.env.example` to `.env` and fill in your instance details:

   ```bash
   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 sugar_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.
