sokoweb 0.1.19

Sokoweb package

SokoWeb – DHT-Based Commerce Network

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

Quick Start

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

curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "alice123",
    "email": "[e-mail]",
    "full_name": "Alice Wonderland",
    "phone_number": "[phone]",
    "scopes": ["products:write", "products:read", "credits:manage"]
  }'

Get Access Token

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

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": "[phone]",
      "shop_name": "Tech Store",
      "seller_location": [-1.2921, 36.8219]
    },
    "extended": {
      "brand": "Example",
      "condition": "new"
    }
  }'

Upload Product Image

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

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

Search by category/shop

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

Search by location (within radius)

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

Combined search

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

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

Purchase Credits

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

Category Operations

# 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