Metadata-Version: 2.4
Name: damsle
Version: 1.0.0
Summary: Digital Asset Marketplace & SaaS Licensing Engine CLI & SDK
Project-URL: Homepage, https://github.com/vyofgod/DAMSLE
Project-URL: Bug Tracker, https://github.com/vyofgod/DAMSLE/issues
Author-email: vyofgod <contact@vyofgod.com>
License-Expression: MIT
License-File: LICENSE
Keywords: go,licensing,marketplace,microservices,saas
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Requires-Dist: click>=8.0.0
Requires-Dist: requests>=2.25.0
Description-Content-Type: text/markdown

# DAMSLE

**Digital Asset Marketplace & SaaS Licensing Engine**

A production-grade, open-source Go boilerplate for building digital asset marketplaces with automated license management. Three decoupled microservices, event-driven architecture, and zero-dependency frontend.

[![Go 1.23+](https://img.shields.io/badge/Go-1.23+-00ADD8?style=flat&logo=go)](https://go.dev/dl/)
[![Docker Compose](https://img.shields.io/badge/Docker_Compose-Ready-2496ED?style=flat&logo=docker)](https://docs.docker.com/compose/)
[![NATS JetStream](https://img.shields.io/badge/Messaging-NATS_JetStream-27AA89?style=flat&logo=nats.io)](https://nats.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- **Clean Architecture**: Decoupled microservices (`cart`, `payment`, `license`)
- **Event-Driven**: Built on NATS JetStream for reliable async messaging
- **High Performance**: DragonflyDB for ultra-fast caching and distributed locking
- **Payment Abstraction**: Seamless support for Stripe and LemonSqueezy
- **Modern UI**: Zero-dependency vanilla HTML/CSS/JS frontend dashboard

## Quick Start

**Docker Compose:**
```bash
git clone https://github.com/vyofgod/DAMSLE.git
cd DAMSLE
docker compose up -d
```

Then open `http://localhost:8080` for the frontend.

## Installation Methods

### Option 1: Python CLI & SDK (PyPI)

Install the management tool and developer SDK instantly:
```bash
pip install damsle
```

Manage your stack with ease:
```bash
damsle up      # Start the infrastructure
damsle ps      # Check service status
damsle down    # Stop everything
```

### Option 2: Docker Compose (Manual)

Start all services and infrastructure instantly:
```bash
docker compose up -d
```

Verify services are running:
```bash
curl http://localhost:8081/healthz  # Cart
curl http://localhost:8082/healthz  # Payment
curl http://localhost:8083/healthz  # License
```

### Option 2: Local Development

Start infrastructure only:
```bash
docker compose up -d nats dragonflydb
```

Run services (in separate terminals):
```bash
cd services/cart && go run ./cmd/server
cd services/payment && go run ./cmd/server
cd services/license && go run ./cmd/server
```

Serve frontend:
```bash
cd web && python3 -m http.server 8080
```

### Option 3: Kubernetes Deployment

Deploy to your K8s cluster:
```bash
kubectl apply -f deploy/k8s/namespace.yaml
kubectl apply -f deploy/k8s/nats/
kubectl apply -f deploy/k8s/dragonflydb/
kubectl apply -f deploy/k8s/cart-service/
kubectl apply -f deploy/k8s/payment-service/
kubectl apply -f deploy/k8s/license-service/
kubectl apply -f deploy/k8s/ingress.yaml
```

## Usage

### 1. Manage Cart

- Interact with the `Cart Service` on `:8081`
- Endpoints: `GET /api/v1/cart/{id}`, `POST /api/v1/cart/{id}/items`
- Perform checkout: `POST /api/v1/cart/{id}/checkout`

### 2. Process Payments

- Handled by `Payment Service` on `:8082`
- Verify payment status: `GET /api/v1/payments/{id}`
- Receives provider webhooks (e.g., Stripe) at `/api/v1/payments/webhook`

### 3. Issue & Validate Licenses

- Governed by `License Service` on `:8083`
- Create products: `POST /api/v1/products`
- Validate issued keys: `POST /api/v1/licenses/validate`

## Architecture & Specifications

### System Design
```text
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    Cart     │     │   Payment   │     │   License   │
│   Service   │     │   Service   │     │   Service   │
│   :8081     │     │   :8082     │     │   :8083     │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       └───────────┬───────┴───────────┬───────┘
                   │                   │
             ┌─────┴─────┐      ┌──────┴──────┐
             │   NATS    │      │ DragonflyDB │
             │ JetStream │      │  (Redis)    │
             └───────────┘      └─────────────┘
```

### Event Flow
- `cart.checkout` → `payment.completed` → `license.issued`

### Tech Stack
- **Language**: Go 1.23
- **Cache / Store**: DragonflyDB (Redis-compatible)
- **Locking**: Distributed mutex via `bsm/redislock`
- **Frontend**: Vanilla HTML/CSS/JS

## Configuration

All configuration is handled via environment variables:

- `PORT`: Service port (`8081/8082/8083`)
- `NATS_URL`: NATS server URL (default: `nats://localhost:4222`)
- `DRAGONFLY_ADDR`: DragonflyDB address (default: `localhost:6379`)
- `PAYMENT_PROVIDER`: Provider choice (`stripe` or `lemonsqueezy`)
- `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET`: Stripe credentials
- `LICENSE_KEY_SECRET`: HMAC secret for key generation
- `LOG_LEVEL`: Logging verbosity (`debug`, `info`, `warn`, `error`)

## Python SDK Usage

Integrate DAMSLE into your Python applications with ease:

```python
from damsle import DamsleClient

client = DamsleClient("http://localhost:8083")

# Validate a license key
result = client.validate_license(
    product_id="my-product-uuid",
    license_key="ABCD-1234-EFGH"
)

if result.get("valid"):
    print("Welcome, licensed user!")
else:
    print(f"Access denied: {result.get('message')}")
```

## Important Notes

- **Secret Management** - Ensure `LICENSE_KEY_SECRET` and payment API keys are kept secure
- **Event Idempotency** - Services are designed to handle duplicate events safely
- **Data Persistence** - DragonflyDB is used for caching, configure persistence if required for production

## Links

- **GitHub**: https://github.com/vyofgod/DAMSLE
- **Issues**: https://github.com/vyofgod/DAMSLE/issues

## Contributing

Contributions welcome! Please submit a Pull Request.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Disclaimer

This software is provided "as is" without warranty. Ensure proper testing in staging environments before deploying to production.

---

**Empowering Digital Commerce with DAMSLE**

*Version 1.0.0*
