dark-obsidian 1.0.0

Official Python SDK for the Dark Obsidian Business Management API

dark-obsidian

Official Python SDK for the Dark Obsidian Business Management API.

pip install dark-obsidian

Quick start

from dark_obsidian import DarkObsidian

client = DarkObsidian(api_key="do_live_...")

The killer endpoint — one call connects your storefront to your entire business

from dark_obsidian import DarkObsidian
from dark_obsidian.models.orders import CreateOrderParams, CreateOrderItemParams, InlineCustomer

client = DarkObsidian(api_key="do_live_...")

order = client.orders.create(CreateOrderParams(
    items=[
        CreateOrderItemParams(product_id="prod_id_here", quantity=2),
    ],
    customer=InlineCustomer(
        name="Ahmed Khan",
        email="[e-mail]",
        phone="[phone]",
    ),
    payment_method="card",
    send_invoice=True,
))

print(f"Order:   {order.order_number}")
print(f"Invoice: {order.invoice_number}")
print(f"Loyalty: {order.loyalty_points_earned} pts earned")

Resources

from dark_obsidian.models.products import ListProductsParams, CreateProductParams

# Products
products = client.products.list(ListProductsParams(in_stock=True))
product  = client.products.get("id")
created  = client.products.create(CreateProductParams(name="Panadol 500mg", price=45.0))
client.products.update("id", UpdateProductParams(price=48.0))
client.products.delete("id")

# Customers
from dark_obsidian.models.customers import CreateCustomerParams, ListCustomersParams
customers = client.customers.list(ListCustomersParams(search="Ahmed"))
customer  = client.customers.create(CreateCustomerParams(name="Fatima Malik", phone="[phone]"))

# Inventory
from dark_obsidian.models.inventory import AdjustInventoryParams, TransferInventoryParams
client.inventory.adjust(AdjustInventoryParams(
    product_id="id", quantity=200, reason="Received from Al-Habib Distributors"
))
client.inventory.transfer(TransferInventoryParams(
    product_id="id",
    from_warehouse_id="wh-main",
    to_warehouse_id="wh-branch",
    quantity=50,
))

# Analytics
dash = client.analytics.dashboard(days=30)
top  = client.analytics.top_products(days=30, limit=10)

# AI
from dark_obsidian.models.ai import AnalyzeParams
response = client.ai.analyze(AnalyzeParams(question="What should I reorder this week?"))
print(response.answer)

Async usage

import asyncio
from dark_obsidian import AsyncDarkObsidian
from dark_obsidian.models.products import ListProductsParams

async def main():
    async with AsyncDarkObsidian(api_key="do_live_...") as client:
        products = await client.products.list(ListProductsParams(in_stock=True))
        print(f"Found {len(products)} products in stock")

asyncio.run(main())

Error handling

from dark_obsidian import DarkObsidian, DarkObsidianError
from dark_obsidian.models.errors import ErrorCode

try:
    order = client.orders.create(...)
except DarkObsidianError as err:
    print(f"[{err.code}] {err.message}")
    print(f"Request ID: {err.request_id}")   # for support

    if err.code == ErrorCode.INSUFFICIENT_STOCK:
        print("Some items are out of stock")
    elif err.code == ErrorCode.VALIDATION_ERROR and err.fields:
        for f in err.fields:
            print(f"  {f.field}: {f.message}")

Webhooks

from dark_obsidian import verify_webhook_signature
import os

# Flask example:
from flask import Flask, request, abort
import json

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["DARK_OBSIDIAN_WEBHOOK_SECRET"]

@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    raw_body  = request.get_data(as_text=True)
    signature = request.headers.get("X-Dark-Obsidian-Signature", "")

    if not verify_webhook_signature(WEBHOOK_SECRET, raw_body, signature):
        abort(401)

    event = json.loads(raw_body)
    print(f"Received: {event['event']}")
    return "", 200

Supported events: sale.completed, sale.voided, po.received, po.returned, inventory.low_stock, inventory.out_of_stock, invoice.payment_recorded, expense.approved, payroll.processed, leave.approved, leave.rejected, announcement.published, customer.group_upgraded

Context manager (auto-close)

with DarkObsidian(api_key="do_live_...") as client:
    products = client.products.list()
# httpx.Client is closed automatically

Requirements

• Python 3.10+
• httpx (installed automatically)

API reference

https://darkobsedian.sameergul.com/docs