makerstash/API_EXAMPLES.md

# API Examples - All New Features

Quick reference for all new API endpoints with curl examples.

## 1. Cost Calculator APIs

### Get Cost for Single Model
```bash
curl -X GET "http://localhost:3000/api/models/1/cost?materialType=pla" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "modelId": 1,
  "name": "Benchy",
  "fileName": "benchy.stl",
  "fileSize": 2097152,
  "material": "pla",
  "weight": 20.97,
  "units": 0.021,
  "costPerUnit": 15,
  "estimatedCost": 0.31,
  "confidence": "low"
}
```

### Calculate Costs for Multiple Models (Batch)
```bash
curl -X POST "http://localhost:3000/api/models/batch/cost" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "modelIds": [1, 2, 3],
    "materialType": "petg"
  }'
```

**Response:**
```json
{
  "materialType": "petg",
  "models": [
    {
      "modelId": 1,
      "name": "Model 1",
      "weight": 25.5,
      "units": 0.0255,
      "costPerUnit": 20,
      "estimatedCost": 0.51
    },
    {
      "modelId": 2,
      "name": "Model 2",
      "weight": 32.1,
      "units": 0.0321,
      "costPerUnit": 20,
      "estimatedCost": 0.64
    },
    {
      "modelId": 3,
      "name": "Model 3",
      "weight": 18.7,
      "units": 0.0187,
      "costPerUnit": 20,
      "estimatedCost": 0.37
    }
  ],
  "totalCost": 1.52,
  "averageCost": 0.51
}
```

### Get Available Materials
```bash
curl -X GET "http://localhost:3000/api/models/config/materials"
```

**Response:**
```json
{
  "materials": [
    { "type": "pla", "costPerUnit": 15, "density": 1.24 },
    { "type": "abs", "costPerUnit": 18, "density": 1.04 },
    { "type": "petg", "costPerUnit": 20, "density": 1.27 },
    { "type": "nylon", "costPerUnit": 35, "density": 1.14 },
    { "type": "tpu", "costPerUnit": 40, "density": 1.21 },
    { "type": "carbon", "costPerUnit": 50, "density": 1.3 },
    { "type": "bamboo", "costPerUnit": 25, "density": 1.25 },
    { "type": "standard", "costPerUnit": 12, "density": 1.15 },
    { "type": "tough", "costPerUnit": 18, "density": 1.18 },
    { "type": "flexible", "costPerUnit": 20, "density": 1.2 },
    { "type": "castable", "costPerUnit": 25, "density": 1.22 }
  ]
}
```

---

## 2. Enhanced Search APIs

### Search with Full-Text + Filters
```bash
curl -X GET "http://localhost:3000/api/models?search=benchy&license=MIT&fileType=.stl" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Search with Sorting
```bash
curl -X GET "http://localhost:3000/api/models?search=support&sortBy=name&sortOrder=ASC" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Search with Size Range
```bash
curl -X GET "http://localhost:3000/api/models?minSize=1000000&maxSize=10000000" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Full Query Example
```bash
curl -X GET "http://localhost:3000/api/models?search=bambu&license=MIT&fileType=.3mf&hasSupports=true&sortBy=created_at&sortOrder=DESC&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "models": [
    {
      "id": 1,
      "name": "Bambu X1 Part",
      "description": "Compatible with Bambu Lab X1",
      "license": "MIT",
      "file_type": ".3mf",
      "file_size": 5242880,
      "creator": "User123",
      "is_supported": 1,
      "tags": ["bambu", "printer", "compatible"],
      "collection_name": "3D Printer Parts",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "page": 1,
  "limit": 20
}
```

---

## 3. License Management APIs

### Upload Model with License
```bash
curl -X POST "http://localhost:3000/api/models" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@model.stl" \
  -F "name=My Model" \
  -F "license=MIT" \
  -F "description=A great model"
```

### Filter by License
```bash
curl -X GET "http://localhost:3000/api/models?license=Creative%20Commons" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Update Model License (Edit Endpoint - if available)
```bash
curl -X PUT "http://localhost:3000/api/models/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "license": "CC0"
  }'
```

---

## 4. Printer APIs (Bambu)

### Connect Bambu Printer
```bash
curl -X POST "http://localhost:3000/api/printers/bambu/connect" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "printerName": "My Bambu X1",
    "serialNumber": "0000000ABC123",
    "modelName": "X1-Carbon",
    "accessToken": "YOUR_BAMBU_ACCESS_TOKEN"
  }'
```

**Response:**
```json
{
  "message": "Printer connected successfully",
  "printerConnected": true
}
```

### List Connected Printers
```bash
curl -X GET "http://localhost:3000/api/printers/printers" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "printers": [
    {
      "id": 1,
      "printer_type": "bambu",
      "printer_name": "My Bambu X1",
      "serial_number": "0000000ABC123",
      "model_name": "X1-Carbon"
    }
  ]
}
```

### Get Printer Status
```bash
curl -X GET "http://localhost:3000/api/printers/bambu/1/status" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "status": "idle",
    "temperature": 25,
    "chamber_temp": 28
  }
}
```

### Get Printer Info
```bash
curl -X GET "http://localhost:3000/api/printers/bambu/1/info" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "serialNumber": "0000000ABC123",
    "modelName": "X1-Carbon",
    "firmwareVersion": "01.05.06.00",
    "ipAddress": "192.168.1.100",
    "status": "idle",
    "temperature": 25
  }
}
```

### Get Current Print Job
```bash
curl -X GET "http://localhost:3000/api/printers/bambu/1/job" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "jobId": "job_123",
    "fileName": "benchy.3mf",
    "progress": 45,
    "timeRemaining": 2700,
    "status": "printing",
    "layer": 100,
    "totalLayers": 220
  }
}
```

### Get Temperature Readings
```bash
curl -X GET "http://localhost:3000/api/printers/bambu/1/temperature" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "success": true,
  "data": {
    "nozzleTemp": 220,
    "bedTemp": 60,
    "chamberTemp": 45,
    "nozzleTargetTemp": 220,
    "bedTargetTemp": 60
  }
}
```

### Get Print History
```bash
curl -X GET "http://localhost:3000/api/printers/bambu/1/history?limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "success": true,
  "data": [
    {
      "jobId": "job_123",
      "fileName": "benchy.3mf",
      "duration": 4320,
      "completedAt": "2024-01-01T12:00:00Z",
      "status": "completed"
    }
  ]
}
```

### Control Print (Pause/Resume/Stop)
```bash
# Pause
curl -X POST "http://localhost:3000/api/printers/bambu/1/control" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "pause" }'

# Resume
curl -X POST "http://localhost:3000/api/printers/bambu/1/control" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "resume" }'

# Stop
curl -X POST "http://localhost:3000/api/printers/bambu/1/control" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "action": "stop" }'
```

**Response:**
```json
{
  "success": true,
  "data": { "status": "paused" }
}
```

### Disconnect Printer
```bash
curl -X DELETE "http://localhost:3000/api/printers/printers/1" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "message": "Printer disconnected"
}
```

---

## 5. Theme APIs

### Get Current User (with Theme)
```bash
curl -X GET "http://localhost:3000/api/auth/me" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response:**
```json
{
  "user": {
    "id": 1,
    "username": "testuser",
    "email": "test@example.com",
    "theme": "dark",
    "created_at": "2024-01-01T00:00:00Z"
  }
}
```

### Update User Theme
```bash
curl -X PUT "http://localhost:3000/api/auth/me/theme" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "theme": "dark" }'
```

**Response:**
```json
{
  "message": "Theme updated",
  "theme": "dark"
}
```

---

## Integration Examples

### Complete Workflow: Upload, Calculate Cost, Filter, Connect Printer

```bash
#!/bin/bash

TOKEN="your_auth_token"
API="http://localhost:3000/api"

# 1. Upload model with license
echo "1. Uploading model..."
curl -X POST "$API/models" \
  -H "Authorization: Bearer $TOKEN" \
  -F "files=@benchy.stl" \
  -F "name=Benchy" \
  -F "license=MIT" \
  -F "description=Test benchmark model"

# 2. Get cost estimate for models with MIT license
echo "2. Calculating costs for MIT licensed models..."
curl -X GET "$API/models?license=MIT" \
  -H "Authorization: Bearer $TOKEN" | jq '.models[0].id'

# 3. Calculate batch cost
echo "3. Getting cost estimates..."
curl -X POST "$API/models/batch/cost" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"modelIds": [1, 2], "materialType": "pla"}'

# 4. Connect printer
echo "4. Connecting Bambu printer..."
curl -X POST "$API/printers/bambu/connect" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "printerName": "My X1",
    "serialNumber": "000ABC123",
    "modelName": "X1-Carbon",
    "accessToken": "YOUR_TOKEN"
  }'

# 5. Check printer status
echo "5. Checking printer status..."
curl -X GET "$API/printers/bambu/1/status" \
  -H "Authorization: Bearer $TOKEN"

# 6. Switch to dark theme
echo "6. Switching theme..."
curl -X PUT "$API/auth/me/theme" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"theme": "dark"}'

echo "Done!"
```

---

## Error Responses

### Invalid Material Type
```json
{
  "error": "Unknown material type: xyz"
}
```

### Printer Connection Failed
```json
{
  "success": false,
  "error": "Failed to authenticate with Bambu Labs"
}
```

### Invalid Theme
```json
{
  "error": "Theme must be \"light\" or \"dark\""
}
```

### Unauthorized
```json
{
  "error": "Unauthorized"
}
```

---

## Rate Limiting Notes

- No rate limiting implemented
- Consider adding in production
- Suggested: 100 requests/min per user

---

## Authentication

All protected endpoints require:
```
Authorization: Bearer YOUR_JWT_TOKEN
```

Get token via:
```bash
POST /api/auth/login
{
  "username": "user",
  "password": "pass"
}
```

---

## Test Data

### Material Types for Testing
- `pla` - Common FDM, $15/kg
- `resin` - Standard resin, $12/ml
- `carbon` - Expensive, $50/kg

### License Types for Testing
- `MIT` - Common open source
- `Creative Commons` - Creative works
- `CC0` - Public domain
- `Unknown` - No license specified

---

## Postman Collection

Can be imported into Postman for easier API testing. Environment variables:
- `{{base_url}}` = http://localhost:3000
- `{{token}}` = Your auth token
- `{{printer_id}}` = Your printer ID

---

End of API Examples