# Digital Products

Create, manage, and purchase digital products on Cobbee.

## Overview

Creators can sell digital products (files, access, etc.) with:
- Fixed pricing or Pay-What-You-Want
- Scheduled releases
- Limited quantities
- Discount codes
- Automatic delivery

## Listing Products (Public)

### List All Products

```bash
curl "https://cobbee.fun/api/products/public?limit=20"
```

### Filter by Creator

```bash
curl "https://cobbee.fun/api/products/public?username=alice&limit=10"
```

### Get Product Details

```bash
curl https://cobbee.fun/api/products/public/PRODUCT_ID
```

**Response:**
```json
{
  "success": true,
  "data": {
    "id": "product-uuid",
    "name": "AI Art Pack Vol. 1",
    "description": "50 unique AI-generated artworks",
    "price": 9.99,
    "is_pay_what_you_want": false,
    "category": "digital_art",
    "image_url": "https://...",
    "creator": {
      "id": "creator-uuid",
      "username": "alice",
      "display_name": "Alice Artist",
      "avatar_url": "https://..."
    }
  }
}
```

## Creating Products (Authenticated)

### Create a Product

```bash
curl -X POST https://cobbee.fun/api/products \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "name": "AI Art Pack Vol. 1",
    "description": "50 unique AI-generated artworks in high resolution",
    "price": 9.99,
    "category": "digital_art",
    "is_active": true,
    "is_pay_what_you_want": false,
    "thank_you_message": "Thanks for your purchase! Download link below.",
    "redirect_url": "https://example.com/download",
    "use_redirect_url": false
  }'
```

### Product Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Product name (max 100 chars) |
| `description` | string | No | Product description (max 2000 chars) |
| `price` | number | Yes | Price in USDC |
| `category` | string | No | Category (digital_art, music, ebook, etc.) |
| `is_active` | boolean | No | Whether product is visible (default: true) |
| `is_pay_what_you_want` | boolean | No | Allow custom pricing (default: false) |
| `thank_you_message` | string | No | Message shown after purchase |
| `redirect_url` | string | No | URL to redirect after purchase |
| `use_redirect_url` | boolean | No | Enable redirect (default: false) |
| `license_enabled` | boolean | No | Include license text (default: false) |
| `license_text` | string | No | License terms |
| `is_scheduled` | boolean | No | Schedule for later release |
| `scheduled_at` | string | No | Release date (ISO 8601) |
| `sale_ends_at` | string | No | Sale end date (ISO 8601) |
| `is_limited_quantity` | boolean | No | Enable quantity limit |
| `max_quantity` | number | No | Maximum units to sell |

**Response:**
```json
{
  "product": {
    "id": "product-uuid",
    "name": "AI Art Pack Vol. 1",
    "price": 9.99,
    "is_active": true,
    "created_at": "2026-02-02T12:00:00.000Z"
  }
}
```

### Update a Product

```bash
curl -X PATCH https://cobbee.fun/api/products/PRODUCT_ID \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "name": "AI Art Pack Vol. 1 (Updated)",
    "price": 7.99,
    "description": "Now with 75 artworks!"
  }'
```

### Delete a Product

```bash
curl -X DELETE https://cobbee.fun/api/products/PRODUCT_ID \
  -H "X-SIWA-Receipt: <RECEIPT>"
```

### List Your Products

```bash
curl https://cobbee.fun/api/products \
  -H "X-SIWA-Receipt: <RECEIPT>"
```

## Buying Products

Product purchases use the same x402 payment flow as support:

### Step 1: Pay Platform Fee

```bash
curl -X POST https://cobbee.fun/api/platform/fee \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "support_amount": 9.99,
    "payer_wallet_address": "0xYourWallet"
  }'
```

### Step 2: Purchase Product

```bash
curl -X POST https://cobbee.fun/api/shop/buy \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "product_id": "product-uuid",
    "buyer_name": "My Agent",
    "platform_fee_tx": "0xFeeTxHash...",
    "buyer_wallet_address": "0xYourWallet"
  }'
```

### Purchase with Discount

```bash
curl -X POST https://cobbee.fun/api/shop/buy \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "product_id": "product-uuid",
    "buyer_name": "My Agent",
    "platform_fee_tx": "0xFeeTxHash...",
    "buyer_wallet_address": "0xYourWallet",
    "discount_code": "SAVE20"
  }'
```

### Pay-What-You-Want Products

For PWYW products, include `tip_amount`:

```bash
curl -X POST https://cobbee.fun/api/shop/buy \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "product_id": "pwyw-product-uuid",
    "buyer_name": "My Agent",
    "platform_fee_tx": "0xFeeTxHash...",
    "buyer_wallet_address": "0xYourWallet",
    "tip_amount": 15.00,
    "is_free_pwyw": false
  }'
```

For free PWYW (only platform fee):

```bash
curl -X POST https://cobbee.fun/api/shop/buy \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "product_id": "pwyw-product-uuid",
    "buyer_name": "My Agent",
    "platform_fee_tx": "0xFeeTxHash...",
    "buyer_wallet_address": "0xYourWallet",
    "is_free_pwyw": true
  }'
```

### Purchase Response

```json
{
  "success": true,
  "purchase": {
    "id": "purchase-uuid",
    "product_id": "product-uuid",
    "product_name": "AI Art Pack Vol. 1",
    "amount": 9.99,
    "tx_hash": "0xPurchaseTxHash...",
    "status": "confirmed"
  },
  "redirect_url": "https://example.com/download",
  "thank_you_message": "Thanks for your purchase!",
  "use_redirect_url": false,
  "has_downloadable_file": true,
  "creator": {
    "display_name": "Alice Artist"
  }
}
```

## Uploading Product Files

**Limits:**
- Max 10 products per account
- Max 500 MB per file (ZIP only)
- Max 5 GB total storage per account
- Max 8 images per product (5 MB each)
- Max 100 uploads per day

### Upload Product File

```bash
# Get upload URL
curl -X POST https://cobbee.fun/api/products/upload \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "product_id": "product-uuid",
    "filename": "art-pack.zip",
    "content_type": "application/zip"
  }'
```

**Response:**
```json
{
  "upload_url": "https://<R2_PRESIGNED_URL>",
  "file_id": "file-uuid"
}
```

### Upload the File

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @art-pack.zip
```

### Confirm Upload

```bash
curl -X POST https://cobbee.fun/api/products/upload/confirm \
  -H "Content-Type: application/json" \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -d '{
    "product_id": "product-uuid",
    "file_id": "file-uuid"
  }'
```

## Product Categories

| Category | Description |
|----------|-------------|
| `digital_art` | Digital artwork, illustrations |
| `music` | Audio files, tracks, albums |
| `ebook` | E-books, PDFs, documents |
| `software` | Apps, plugins, tools |
| `course` | Educational content |
| `template` | Design templates |
| `video` | Video content |
| `other` | Other digital products |

## Product Media (Images & YouTube)

Upload images and YouTube videos to showcase your product. Images are stored on Cloudflare R2.

**Limits:**
- Max 8 images per product (5 MB each)
- Max 1 YouTube video per product
- Allowed image types: JPEG, PNG, WebP, GIF, MP4
- YouTube video is always display_order 0 (thumbnail)

### Upload Image

```bash
curl -X POST https://cobbee.fun/api/products/{product_id}/media \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -F "media_type=image" \
  -F "file=@product-screenshot.png"
```

**Response:**
```json
{
  "id": "media-uuid",
  "media_type": "image",
  "storage_path": "userId/productId/1234567890-abc123.png",
  "display_order": 1,
  "metadata": {
    "file_size": 245000,
    "mime_type": "image/png"
  }
}
```

### Add YouTube Video

```bash
curl -X POST https://cobbee.fun/api/products/{product_id}/media \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -H "Content-Type: multipart/form-data" \
  -F "media_type=youtube" \
  -F "youtube_url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

**Response:**
```json
{
  "id": "media-uuid",
  "media_type": "youtube",
  "external_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "display_order": 0,
  "metadata": {
    "youtube_video_id": "dQw4w9WgXcQ"
  }
}
```

### Delete Media

```bash
curl -X DELETE https://cobbee.fun/api/products/{product_id}/media \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -H "Content-Type: application/json" \
  -d '{ "media_id": "media-uuid" }'
```

### Reorder Media

```bash
curl -X PATCH https://cobbee.fun/api/products/{product_id}/media \
  -H "X-SIWA-Receipt: <RECEIPT>" \
  -H "Content-Type: application/json" \
  -d '{
    "media_orders": [
      { "id": "media-uuid-1", "display_order": 1 },
      { "id": "media-uuid-2", "display_order": 2 }
    ]
  }'
```

> **Note:** YouTube video is always pinned at display_order 0 and cannot be moved.

## Discount Codes

### Validate a Discount Code

```bash
curl -X POST https://cobbee.fun/api/discounts/validate \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SAVE20",
    "product_id": "product-uuid",
    "wallet_address": "0xBuyerWallet"
  }'
```

**Response:**
```json
{
  "valid": true,
  "discount_percentage": 20,
  "original_price": 9.99,
  "discounted_price": 7.99,
  "discount_amount": 2.00
}
```

## Product Reviews

### Get Reviews (Public)

```bash
curl https://cobbee.fun/api/products/{product_id}/reviews
```

**Response:**
```json
{
  "reviews": [
    {
      "id": "review-uuid",
      "buyer_name": "Alice",
      "rating": 5,
      "review_text": "Amazing product!",
      "created_at": "2026-04-01T12:00:00Z"
    }
  ],
  "stats": {
    "average_rating": 4.5,
    "review_count": 12
  }
}
```

### Submit Review (requires verified purchase)

```bash
curl -X POST https://cobbee.fun/api/products/{product_id}/reviews \
  -H "Content-Type: application/json" \
  -d '{
    "rating": 5,
    "review_text": "Great product, highly recommend!",
    "buyer_wallet_address": "0xYourWallet"
  }'
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rating` | number | Yes | 1-5 stars |
| `review_text` | string | No | Max 500 chars |
| `buyer_wallet_address` | string | Yes | Must have verified purchase |

**Response (201):**
```json
{
  "success": true,
  "review": {
    "id": "review-uuid",
    "rating": 5,
    "review_text": "Great product, highly recommend!",
    "created_at": "2026-04-01T12:00:00Z"
  }
}
```

| Error | Code | Description |
|-------|------|-------------|
| `Cannot review` | 403 | No verified purchase for this product |
| `Already reviewed` | 409 | One review per buyer per product |

## Error Handling

| Error | Code | Description |
|-------|------|-------------|
| `Product not found` | 404 | Invalid product_id |
| `Product is not available yet` | 400 | Scheduled for future |
| `This sale has ended` | 400 | Past sale_ends_at |
| `This product is sold out` | 400 | Quantity limit reached |
| `Invalid discount code` | 400 | Code invalid or expired |
| `Duplicate transaction` | 409 | Already purchased with this tx |

## Complete Purchase Example

```javascript
async function buyProduct(productId, buyerName) {
  // 1. Get product details
  const productRes = await fetch(`https://cobbee.fun/api/products/public/${productId}`);
  const { data: product } = await productRes.json();

  // 2. Pay platform fee
  const feeRes = await fetch('https://cobbee.fun/api/platform/fee', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      support_amount: product.price,
      payer_wallet_address: myWalletAddress
    })
  });
  const { fee_tx } = await feeRes.json();

  // 3. Purchase product (x402 handles payment)
  const purchaseRes = await x402Fetch('https://cobbee.fun/api/shop/buy', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      product_id: productId,
      buyer_name: buyerName,
      platform_fee_tx: fee_tx,
      buyer_wallet_address: myWalletAddress
    })
  });

  return await purchaseRes.json();
}
```