Metadata-Version: 2.4
Name: cashfin-business-sdk
Version: 0.2.2
Summary: All your Cashfin business use-cases can be done programmatically.
Author-email: Cashfin <dev@cashfin.com>
License-Expression: MIT
Project-URL: Homepage, https://cashfin.africa
Project-URL: Documentation, https://docs.cashfin.africa
Project-URL: Repository, https://gitlab.com/cashfin_africa1/cashfin_sdks
Keywords: cashfin,payment,business,sdk,api
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Dynamic: license-file

# Cashfin Business Python SDK

Official Python SDK for the [Cashfin Business API](https://docs.cashfin.africa). Manage payments, invoices, subscriptions, shop, CRM, purchases, and marketing from your Python application.

## Installation

```bash
pip install cashfin-business-sdk
```

## Quick Start

```python
import os
from cashfin_sdk.main import CashfinSDK

os.environ["CASHFIN_CLIENT_SECRET"] = "cs_your_client_secret"
os.environ["CASHFIN_BASE_URL"] = "https://api.cashfin.africa"

sdk = CashfinSDK()
```

## Usage

### Payments

```python
# M-Pesa STK push
sdk.business.payment.request_stk_push(
    phone_number="+254712345678",
    ref_id="order-001",
    amount=500
)

# Transactions
sdk.business.transactions.list(page=1, limit=20, status="completed")
sdk.business.transactions.get("transaction_id")

# Receipts
sdk.business.receipts.list()
sdk.business.receipts.get("receipt_id")

# Payment links
sdk.business.payment_links.create(title="Website Payment", amount=1000)
sdk.business.payment_links.list()
sdk.business.payment_links.get("link_id")

# Invoices
sdk.business.invoices.create(
    customerid="customer_id",
    items=[{"itemid": "prod_id", "quantity": 1, "rate": 1000}],
    duedate="2025-12-31"
)
sdk.business.invoices.list()
sdk.business.invoices.get("invoice_id")
sdk.business.invoices.update("invoice_id", status="paid")

# Subscriptions
sdk.business.subscriptions.create(
    customerid="customer_id",
    items=[{"itemid": "plan_id", "quantity": 1, "rate": 500}],
    billingcycle="monthly",
    autorenew=True
)
sdk.business.subscriptions.get("sub_id")
sdk.business.subscriptions.cancel("sub_id")
sdk.business.subscriptions.pause("sub_id")
sdk.business.subscriptions.resume("sub_id")
sdk.business.subscriptions.generate_invoice("sub_id")
```

### Shop

```python
# Products
sdk.business.products.list(status="published", type="product")
sdk.business.products.get("product_id")
sdk.business.products.create(title="T-Shirt", price=1500, stock=100)
sdk.business.products.update("product_id", price=1200, stock=80)

# Product categories
sdk.business.categories.list()
sdk.business.categories.create(title="Apparel")
sdk.business.categories.update("category_id", status="archived")

# Orders
sdk.business.orders.checkout(
    items=[{"itemid": "prod_id", "quantity": 2, "rate": 1500}],
    customeremail="buyer@example.com"
)
sdk.business.orders.list(status="processing")
sdk.business.orders.get("order_id")
```

### CRM

```python
# Customers
sdk.business.customers.create(
    name="Jane Doe",
    email="jane@example.com",
    phone="254712345678",
    country="Kenya",
    currency="KES"
)
sdk.business.customers.list(search="jane")
sdk.business.customers.get("customer_id")
sdk.business.customers.update("customer_id", company="Acme Ltd")

# Contacts
sdk.business.contacts.create(name="John Smith", email="john@example.com")
sdk.business.contacts.list()
sdk.business.contacts.get("contact_id")

# Leads
sdk.business.leads.create(name="Alice", source="website", budget=50000)
sdk.business.leads.list(status="new")

# Quotes (read-only)
sdk.business.quotes.list(status="sent")
sdk.business.quotes.get("quote_id")

# Contracts (read-only)
sdk.business.contracts.list(status="active")
sdk.business.contracts.get("contract_id")

# Bookings (read-only)
sdk.business.bookings.list(status="scheduled")
sdk.business.bookings.get("booking_id")

# Appointments (read-only)
sdk.business.appointments.list(status="active")
sdk.business.appointments.get("appointment_id")
```

### Purchases

```python
# Vendors
sdk.business.vendors.create(name="Office Supplies Co", type="business", phone="254700000000")
sdk.business.vendors.list()
sdk.business.vendors.get("vendor_id")
sdk.business.vendors.update("vendor_id", city="Nairobi")

# Expenses
sdk.business.expenses.create(title="Office rent", amount=30000, expensedate="2025-01-01")
sdk.business.expenses.list(status="approved")
sdk.business.expenses.get("expense_id")

# Bills
sdk.business.bills.create(
    title="Electricity bill",
    amount=5000,
    billdate="2025-01-01",
    duedate="2025-01-15"
)
sdk.business.bills.list()
sdk.business.bills.get("bill_id")

# Purchase orders
sdk.business.purchase_orders.create(
    title="Q1 stock order",
    orderdate="2025-01-01",
    deliverydate="2025-01-20"
)
sdk.business.purchase_orders.list()
sdk.business.purchase_orders.get("po_id")
```

### Marketing

```python
# Campaigns (read-only)
sdk.business.campaigns.list(medium="email", status="sent")
sdk.business.campaigns.get("campaign_id")

# Marketing lists
sdk.business.marketing_lists.create(name="Newsletter", type="email")
sdk.business.marketing_lists.list()
sdk.business.marketing_lists.get("list_id")
sdk.business.marketing_lists.add_contact(
    list_id="list_id",
    email="subscriber@example.com",
    firstname="Bob"
)
```

## Environment Variables

| Variable | Description |
|---|---|
| `CASHFIN_CLIENT_SECRET` | Your API client secret (from Cashfin Dashboard) |
| `CASHFIN_BASE_URL` | API base URL (default: `https://api.cashfin.africa`) |

## Development

```bash
# Install UV
pip install uv

# Install dependencies
uv sync

# Run tests
uv run python -m pytest
```
