Metadata-Version: 2.4
Name: ghost-citadel-sdk
Version: 0.1.0
Summary: The official Python SDK for Ghost Citadel — Stripe webhook automation, license verification & SaaS monetization primitives.
Author-email: Ghost Citadel Engineering <dev@api.citadel-serve.com>
License: Apache-2.0
Project-URL: Homepage, https://api.citadel-serve.com
Project-URL: Documentation, https://docs.citadel-serve.com
Project-URL: Repository, https://github.com/tgg49099-dotcom/ghostcitadelle
Project-URL: Issues, https://github.com/tgg49099-dotcom/ghostcitadelle/issues
Project-URL: Get API Key, https://api.citadel-serve.com/dashboard/signup
Keywords: stripe,webhook,billing,saas,api-key,monetization,fastapi,license,rate-limiting,self-hosted
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.95.0; extra == "fastapi"
Requires-Dist: uvicorn>=0.20.0; extra == "fastapi"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.0.270; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Ghost Citadel — Python SDK

> **The Stripe webhook manager + API key billing boilerplate for SaaS founders.**

[![Get API Key](https://img.shields.io/badge/Get%20API%20Key-https%3A%2F%2Fapi.citadel--serve.com-7c3aed?style=for-the-badge)](https://api.citadel-serve.com)
[![CI](https://github.com/tgg49099-dotcom/ghostcitadelle/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tgg49099-dotcom/ghostcitadelle/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org)
[![pip](https://img.shields.io/badge/pip-ghost--citadel--sdk-3776AB.svg)](https://pypi.org/project/ghost-citadel-sdk/)

---

## Why Citadel?

You're a one-person SaaS team shipping at night. Stripe webhooks eat your
weekend. License keys are issued in Notion. Rate limiting is a sticky note.
You've duct-taped your **API key billing boilerplate** together three times
already.

**Citadel** is the boring infra that lets you stop duct-taping.

- 🔁 **Stripe webhook manager** — idempotent, retried, fan-out done.
- 🔐 **License verification** — issue, verify, revoke from one endpoint.
- ⚡ **FastAPI rate limiting** — primitives wired straight into the SDK.
- 💸 **SaaS monetization** — usage-based billing, dunning, and seat
  management without a sales call.
- 🏗️ **Self-serve infrastructure** — sign up, get an API key, ship.

> ⚠️ The package is open source. **Production usage requires an active
> Citadel subscription.** Get your API key instantly at
> **[https://api.citadel-serve.com](https://api.citadel-serve.com)**.
>
> Without a key, the SDK raises a styled `CitadelAuthError` pointing
> straight at the activation URL — by design.

---

## Quickstart

```bash
pip install ghost-citadel-sdk
```

```python
from citadel import CitadelClient

client = CitadelClient(api_key="ck_live_...")  # or set CITADEL_API_KEY

client.register_webhook(
    url="https://your-app.com/stripe/webhook",
    events=["checkout.session.completed", "invoice.paid"],
)

result = client.verify_license(
    license_key="LIC-1234-ABCD",
    product_id="prod_citadel",
)
print(result)
```

### Trying it without a key? You'll see this:

```
┌──────────────────────────────────────────────────────────────────────┐
│  CitadelAuthError: API Key missing or invalid.                       │
│                                                                      │
│  To use this SDK in production and automate your Stripe              │
│  webhooks/licensing, get your API key instantly at                   │
│                                                                      │
│       https://api.citadel-serve.com                                  │
│                                                                      │
│  Citadel — Stripe webhook manager · SaaS monetization                │
│  primitives · Self-serve infrastructure for founders.                │
└──────────────────────────────────────────────────────────────────────┘
```

---

## Ready-to-use Examples

The `examples/` folder contains copy-paste-ready boilerplates tuned for the
exact stacks developers search for on GitHub:

| Folder | Stack | Keywords captured |
| ------ | ----- | ----------------- |
| [`examples/fastapi-stripe-billing/`](examples/fastapi-stripe-billing/) | FastAPI + Stripe + Citadel | FastAPI Stripe billing integration, FastAPI rate limiting |
| [`examples/nextjs-webhook-handler/`](examples/nextjs-webhook-handler/) | Next.js App Router + Stripe | Next.js Stripe webhook boilerplate |

Each example ships with a README that doubles as a landing page for search
engines — drop them in your repo, get traffic, convert on the activation CTA.

---

## API surface

| Method | Endpoint | Purpose |
| ------ | -------- | ------- |
| `client.verify_license(license_key, product_id)` | `POST /v1/verify-license` | Validate a license key |
| `client.register_webhook(url, events)` | `POST /v1/webhooks` | Register a Stripe webhook |
| `client.list_webhooks()` | `GET /v1/webhooks` | List webhooks for this account |
| `client.ping()` | `GET /v1/ping` | Health check + auth probe |

Full schema: [`citadel-openapi.yaml`](./citadel-openapi.yaml).

---

## Subscription requirement

This is open source. Running it in production — i.e. serving real Stripe
events, verifying real licenses, consuming rate-limit budget — requires an
**active Citadel API key** linked to a paying Citadel account.

- Free tier: 1,000 events / month, perfect for side projects.
- Pro tier: unlimited webhooks, seat-based pricing, priority support.
- Scale tier: dedicated infrastructure, custom SLAs.

**Activate your account → [https://api.citadel-serve.com](https://api.citadel-serve.com)**

---

## License

Apache-2.0. The code is yours. The production runtime is ours.

— *Ghost Citadel Engineering*
