Metadata-Version: 2.1
Name: sokoweb
Version: 0.1.20
Summary: Sokoweb package
Home-page: UNKNOWN
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev

# SokoWeb – DHT-Based Commerce Network

Distributed commerce network using Kademlia DHT for peer-to-peer product/service listings, search, and discovery

## Quick Start

```bash
pip install sokoweb==0.1.18
sokoweb-up
```

You'll be prompted for:
- NODE_PORT (default: 8000)
- NODE_TCP_PORT (default: 8500)
- ADVERTISE_IP (default: localhost)

**Note:** Use public IP/domain to join network. Localhost works for exploration but won't connect. Tunneling services like Ngrok typically won't work as network requires UDP and TCP access.

## Requirements

- Python 3.9+
- Docker 27.3.1+
- docker compose 2.29.7+

## API Examples

### Register User

```bash
curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "alice123",
    "email": "alice@example.com",
    "full_name": "Alice Wonderland",
    "phone_number": "+254712345678",
    "scopes": ["products:write", "products:read", "credits:manage"]
  }'
```

### Get Access Token

```bash
curl -X POST http://localhost:8000/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=alice&password=alice123&scope=products:write products:read credits:manage"
```

**Available scopes:**
- products:write - Create/modify products
- products:read - View products
- credits:manage - Purchase/manage credits
- categories:write - Suggest categories
- categories:read - View categories

### Post Product

```bash
curl -X POST http://localhost:8000/products \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "core": {
      "name": "Smartphone",
      "category": "Electronics",
      "price": 500.00,
      "description": "New smartphone",
      "seller_phone": "+254712345678",
      "shop_name": "Tech Store",
      "seller_location": [-1.2921, 36.8219]
    },
    "extended": {
      "storage_duration_days": 1,
      "tags": ["samsung S21","5G"],
      "metadata": { "color": "black" }
    }
  }'
```

### Upload Product Image

```bash
curl -X POST http://localhost:8000/products/{product_id}/image \
  -H "Authorization: Bearer <your_token>" \
  -F "image=@/path/to/image.jpg"
```

### Retrieve Products

#### By ID

```bash
curl http://localhost:8000/products/{product_id} \
  -H "Authorization: Bearer <your_token>"
```

#### Search by category/shop

```bash
curl "http://localhost:8000/products?category=Electronics&shop_name=Tech%20Store" \
  -H "Authorization: Bearer <your_token>"
```

#### Search by location (within radius)

```bash
curl "http://localhost:8000/products?latitude=-1.2921&longitude=36.8219&radius_km=10" \
  -H "Authorization: Bearer <your_token>"
```

#### Combined search

```bash
curl "http://localhost:8000/products?category=Electronics&latitude=-1.2921&longitude=36.8219&radius_km=5" \
  -H "Authorization: Bearer <your_token>"
```

### Credits Management

#### Check Balance

```bash
curl http://localhost:8000/credits/balance \
  -H "Authorization: Bearer <your_token>"
```

### Purchase Credits

```bash
curl -X POST http://localhost:8000/credits/purchase \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "phone_number": "+254712345678"
  }'
```

### Category Operations

```bash
# Suggest a new category (only works in production)
curl -X POST http://<your-public-ip>:8000/categories/suggest \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "category_name": "Smart Home"
  }'

# Retrieve all categories
curl http://localhost:8000/categories \
  -H "Authorization: Bearer <your_token>"
```



**Note:** Substitute localhost with your Public IP in production. The same applies for port, if it's different in your case.

## Docker Management

- Detach from containers: Ctrl+P followed by Ctrl+Q
- View your containers: `docker ps`
- Stop containers: `docker stop <container_name>`
- Remove containers: `docker rm -f <container_name>`

## Contributing

This project is open source and contributions are welcome.

## License

MIT License

