zohopy 0.1.0__tar.gz

zohopy-0.1.0/.dockerignore

@@ -0,0 +1,25 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+.git/
+.github/
+.gsd/
+.bg-shell/
+.env
+.env.*
+!.env.example
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+site/
+tests/
+docs/
+AGENT.md
+CHANGELOG.md
+CONTRIBUTING.md

zohopy-0.1.0/.env.example

@@ -0,0 +1,25 @@
+# ZohoPy Configuration
+# Copy this to .env and fill in your values.
+# NEVER commit .env — it is in .gitignore.
+#
+# Quick setup: python -m zohopy
+# This runs the setup wizard which generates .env for you.
+
+# OAuth2 credentials from https://api-console.zoho.com/ (Self Client)
+ZOHO_CLIENT_ID=
+ZOHO_CLIENT_SECRET=
+
+# Refresh token — generated by exchanging the Self Client grant code.
+# Run `python -m zohopy` to do this interactively.
+ZOHO_REFRESH_TOKEN=
+
+# Your Zoho organization ID (auto-discovered during setup)
+ZOHO_ORGANIZATION_ID=
+
+# API domain returned during token exchange (auto-detects data center)
+# e.g. https://www.zohoapis.com, https://www.zohoapis.eu, etc.
+ZOHO_API_DOMAIN=
+
+# Data center — auto-detected from API_DOMAIN if set.
+# Manual override: us, eu, in, au, jp, ca, cn, sa
+ZOHO_DATA_CENTER=

zohopy-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,75 @@
+name: 🐛 Bug Report
+description: Report a bug in ZohoPy
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting a bug! Please fill in the details below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the bug.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code or steps to reproduce the issue.
+      placeholder: |
+        ```python
+        from zohopy import ZohoConfig, SyncZohoClient
+        config = ZohoConfig()
+        # ...
+        ```
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened (include tracebacks if applicable).
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: ZohoPy Version
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      placeholder: "3.12"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: product
+    attributes:
+      label: Zoho Product
+      options:
+        - Books
+        - Inventory
+        - Both
+        - N/A
+    validations:
+      required: true

zohopy-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,54 @@
+name: 🚀 Feature Request
+description: Suggest a new feature or enhancement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for your feature suggestion!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / Motivation
+      description: What problem does this solve? Why is it needed?
+      placeholder: I want to be able to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How should this work? Include API examples if possible.
+      placeholder: |
+        ```python
+        # Ideal usage
+        books.invoices.bulk_create([...])
+        ```
+    validations:
+      required: true
+
+  - type: dropdown
+    id: product
+    attributes:
+      label: Zoho Product
+      options:
+        - Books
+        - Inventory
+        - New Product (specify below)
+        - Core Library
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any workarounds or alternative approaches you've considered.
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: Links to Zoho API docs, screenshots, etc.

zohopy-0.1.0/.github/PULL_REQUEST_TEMPLATE/pull_request.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What does this PR do? Link related issues with "Closes #123". -->
+
+## Changes
+
+- 
+
+## Checklist
+
+- [ ] Tests added / updated
+- [ ] `ruff check` passes
+- [ ] `mypy` passes
+- [ ] Docs updated (if public API changed)
+- [ ] No credentials, org IDs, or secrets in the diff
+- [ ] CHANGELOG.md updated (for user-facing changes)

zohopy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint & Type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check src/ tests/
+      - name: Ruff format check
+        run: ruff format --check src/ tests/
+      - name: Mypy
+        run: mypy src/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run unit tests
+        run: pytest tests/unit/ --cov=zohopy --cov-report=xml -v
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

zohopy-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build
+        run: python -m build
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/zohopy
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    needs: publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Sign with Sigstore
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: ./dist/*.tar.gz ./dist/*.whl
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release create "${{ github.ref_name }}" --generate-notes
+      - name: Upload to GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: gh release upload "${{ github.ref_name }}" dist/** --clobber

zohopy-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing & Coverage
+.coverage
+htmlcov/
+.pytest_cache/
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# Environment / Secrets — NEVER COMMIT
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+credentials/
+secrets/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docs build
+site/
+
+# Local tooling
+.gsd/
+.bg-shell/

zohopy-0.1.0/AGENT.md

@@ -0,0 +1,173 @@
+# ZohoPy — Agent Reference
+
+Machine-readable reference for AI coding agents.
+All CLI commands support `--json` for structured output.
+
+## Quick Reference
+
+```bash
+# Setup
+zohopy setup                                    # Interactive OAuth wizard
+zohopy config --json                            # Show configuration
+
+# Organizations
+zohopy orgs --json                              # List all organizations
+
+# Contacts
+zohopy contacts list --json                     # List all contacts
+zohopy contacts list --type customer --json     # Filter by type
+zohopy contacts get CONTACT_ID --json           # Get single contact
+zohopy contacts create '{"contact_name":"X","contact_type":"customer"}' --json
+
+# Items
+zohopy items list --json                        # List all items
+zohopy items get ITEM_ID --json
+zohopy items create '{"name":"Widget","rate":50}' --json
+
+# Invoices
+zohopy invoices list --json                     # List invoices
+zohopy invoices list --status sent --json       # Filter by status
+zohopy invoices get INVOICE_ID --json
+zohopy invoices create '{"customer_id":"X","line_items":[{"item_id":"Y","quantity":1}]}' --json
+zohopy invoices mark-sent INVOICE_ID --json
+zohopy invoices void INVOICE_ID --json
+
+# Bills
+zohopy bills list --json
+zohopy bills get BILL_ID --json
+zohopy bills create '{"vendor_id":"X","bill_number":"B-001","date":"2026-04-03","line_items":[...]}' --json
+zohopy bills void BILL_ID --json
+
+# Estimates
+zohopy estimates list --json
+zohopy estimates get ESTIMATE_ID --json
+zohopy estimates create '{"customer_id":"X","line_items":[...]}' --json
+
+# Sales Orders
+zohopy sales-orders list --json
+zohopy sales-orders get SALESORDER_ID --json
+zohopy sales-orders create '{"customer_id":"X","line_items":[...]}' --json
+
+# Purchase Orders
+zohopy purchase-orders list --json
+zohopy purchase-orders get PURCHASEORDER_ID --json
+zohopy purchase-orders create '{"vendor_id":"X","line_items":[...]}' --json
+
+# Expenses
+zohopy expenses list --json
+zohopy expenses get EXPENSE_ID --json
+zohopy expenses create '{"account_id":"X","amount":50,"date":"2026-04-03"}' --json
+
+# Payments
+zohopy payments list-customer --json
+zohopy payments list-vendor --json
+
+# Taxes
+zohopy taxes list --json
+zohopy taxes create '{"tax_name":"VAT","tax_percentage":5}' --json
+
+# Settings
+zohopy settings preferences --json
+zohopy settings currencies --json
+zohopy settings templates --json
+zohopy settings users --json
+
+# Raw API (escape hatch)
+zohopy raw get /books/v3/contacts --json
+zohopy raw post /books/v3/contacts --data '{"contact_name":"Test"}' --json
+```
+
+## Python SDK Quick Reference
+
+```python
+from zohopy import ZohoConfig, SyncZohoClient
+from zohopy.products.books import ZohoBooks
+
+with SyncZohoClient(ZohoConfig()) as client:
+    books = ZohoBooks(client)
+
+    # 43 resource attributes available:
+    # books.contacts, books.invoices, books.items, books.bills,
+    # books.estimates, books.sales_orders, books.purchase_orders,
+    # books.expenses, books.credit_notes, books.vendor_credits,
+    # books.customer_payments, books.vendor_payments,
+    # books.recurring_invoices, books.recurring_bills,
+    # books.recurring_expenses, books.sales_receipts,
+    # books.retainer_invoices, books.customer_debit_notes,
+    # books.contact_persons, books.bank_accounts,
+    # books.bank_transactions, books.chart_of_accounts,
+    # books.journals, books.base_currency_adjustments,
+    # books.projects, books.tasks, books.time_entries,
+    # books.fixed_assets, books.fixed_asset_types,
+    # books.organizations, books.taxes, books.currencies,
+    # books.users, books.preferences, books.templates,
+    # books.opening_balances, books.custom_fields,
+    # books.custom_views, books.custom_modules,
+    # books.reporting_tags, books.workflows,
+    # books.locations, books.crm_integration
+
+    # Every resource has: create(), list(), get(id), update(id, data), delete(id)
+    # Plus resource-specific actions (mark_sent, void, approve, etc.)
+```
+
+## Error Handling
+
+```python
+from zohopy import (
+    ZohoNotFoundError,           # 404 — resource not found
+    ZohoValidationError,         # 400 — bad request (base)
+    ZohoInvalidFieldError,       # 400 code 2 — bad field value
+    ZohoDuplicateError,          # 400 code 4 — already exists
+    ZohoEmptyBodyError,          # 400 code 11 — missing body
+    ZohoBusinessRuleError,       # 400 code 4xxx — rule violation
+    ZohoFeatureNotEnabledError,  # 400 code 110xxx — enable first
+    ZohoResourceDependentError,  # 400 code 36/1004 — has deps
+    ZohoAuthenticationError,     # 401 — bad/expired token
+    ZohoForbiddenError,          # 403 — insufficient scopes
+    ZohoRateLimitError,          # 429 — rate limited (.retry_after)
+    ZohoServerError,             # 5xx — Zoho server error
+)
+```
+
+## Multi-Currency Transactions
+
+All transaction endpoints (invoices, bills, estimates, etc.) support:
+- `currency_id` — ID of the currency
+- `exchange_rate` — exchange rate to base currency
+
+```python
+books.invoices.create({
+    "customer_id": "...",
+    "currency_id": "AED_CURRENCY_ID",
+    "exchange_rate": 3.67,
+    "line_items": [{"item_id": "...", "quantity": 1}],
+})
+```
+
+## Landed Cost
+
+Set `is_landed_cost: True` on bills:
+
+```python
+books.bills.create({
+    "vendor_id": "...",
+    "is_landed_cost": True,
+    "line_items": [
+        {"item_id": "...", "quantity": 1, "rate": 120}
+    ],
+})
+# Response includes: allocated_landed_costs, unallocated_landed_costs
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ZOHO_CLIENT_ID` | Yes | OAuth client ID |
+| `ZOHO_CLIENT_SECRET` | Yes | OAuth client secret |
+| `ZOHO_REFRESH_TOKEN` | Yes | Permanent refresh token |
+| `ZOHO_ORGANIZATION_ID` | Yes | Zoho org ID |
+| `ZOHO_API_DOMAIN` | No | Auto-detects data center |
+| `ZOHO_DATA_CENTER` | No | Manual: us/eu/in/au/jp/ca/cn/sa |
+| `ZOHOPY_LOG_LEVEL` | No | DEBUG/INFO/WARNING/ERROR |
+| `ZOHOPY_LOG_FORMAT` | No | console/json |

zohopy-0.1.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-03
+
+### Added
+
+- **Zoho Books API v3** — complete coverage with 43 resource types and 347 methods (sync + async)
+- **Sales cycle:** Contacts, Contact Persons, Estimates, Sales Orders, Invoices, Recurring Invoices, Sales Receipts, Credit Notes, Customer Debit Notes, Customer Payments, Retainer Invoices
+- **Purchase cycle:** Purchase Orders, Bills, Recurring Bills, Vendor Credits, Vendor Payments, Expenses, Recurring Expenses
+- **Banking:** Bank Accounts, Bank Transactions, Chart of Accounts, Journals, Base Currency Adjustments
+- **Projects:** Projects, Tasks, Time Entries
+- **Assets:** Fixed Assets, Fixed Asset Types
+- **Settings:** Organizations, Taxes (+ authorities + exemptions), Currencies (+ exchange rates), Users, Preferences, Templates, Opening Balances, Custom Fields, Custom Views, Custom Modules, Reporting Tags, Workflows, Locations
+- **Integration:** Zoho CRM import (customer, vendor, item)
+- **Multi-currency** support on all transactions with exchange rates
+- **Landed cost** support on bills
+- **CLI** — `zohopy` command with 30+ commands, `--json` on every command
+- **OAuth setup wizard** — Self Client + Browser redirect flows with org picker UI
+- **Structured logging** via structlog (JSON/console)
+- **Typed exceptions** — 10+ exception classes mapped from Zoho error codes
+- **Docker + Docker Compose** support
+- **CI/CD** — GitHub Actions with lint, type-check, test matrix (3.10–3.13), PyPI release
+
+[Unreleased]: https://github.com/talas9/zohopy/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/talas9/zohopy/releases/tag/v0.1.0

zohopy-0.1.0/Dockerfile

@@ -0,0 +1,37 @@
+# ZohoPy Docker image
+#
+# Build: docker build -t zohopy .
+# Run:   docker run --env-file .env zohopy contacts list --json
+#
+# NOTE: Build the wheel first with `python -m build` or let CI do it.
+# If no pre-built wheel, we use SETUPTOOLS_SCM_PRETEND_VERSION.
+
+FROM python:3.13-slim
+
+LABEL org.opencontainers.image.source="https://github.com/talas9/zohopy"
+LABEL org.opencontainers.image.description="ZohoPy — Python client for Zoho APIs"
+LABEL org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+
+# Copy source and install
+COPY pyproject.toml README.md LICENSE ./
+COPY src/ src/
+
+# Install — use pretend version since .git is not available
+ENV SETUPTOOLS_SCM_PRETEND_VERSION=0.1.0
+RUN pip install --no-cache-dir . && rm -rf /app/src /app/pyproject.toml
+
+# Non-root user
+RUN useradd --create-home --shell /bin/bash zohopy
+USER zohopy
+
+# Runtime config
+ENV ZOHOPY_LOG_LEVEL=INFO \
+    ZOHOPY_LOG_FORMAT=json \
+    PYTHONUNBUFFERED=1
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD python -c "from zohopy import ZohoConfig; print('ok')" || exit 1
+
+ENTRYPOINT ["zohopy"]

zohopy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 talas9
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.