# Milestone 6: App Store Backend API

**Status**: Decided
**Goal**: REST API for app submission, review, and distribution.

## Decision

**Go + Chi router** with JSON REST API:

```
Framework:   Chi (lightweight, idiomatic)
Validation:  go-playground/validator/v10
OpenAPI:     ogen (generated from spec)
Middleware:  Custom auth, rate limiting, logging
Database:    SQLite via repository pattern
```

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                     mosis-portal container                       │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                     Chi Router                              │ │
│  │  /v1/auth/*     /v1/apps/*     /v1/store/*     /v1/keys/*  │ │
│  └──────────────────────┬─────────────────────────────────────┘ │
│                         │                                        │
│  ┌──────────┬───────────┼───────────┬──────────┐               │
│  │ Handlers │ Services  │  Repos    │ SQLite   │               │
│  └──────────┴───────────┴───────────┴──────────┘               │
│                                                                  │
│  /volume1/mosis/data/portal.db                                  │
│  /volume1/mosis/packages/                                       │
└─────────────────────────────────────────────────────────────────┘
```

---

## Overview

The backend API serves the developer portal, CLI tools, and device-side app management. It handles authentication, app lifecycle, file storage, and telemetry ingestion.

---

## API Design Principles

1. **RESTful** - Standard HTTP methods and status codes
2. **JSON** - Request and response bodies in JSON
3. **Versioned** - `/v1/` prefix for breaking changes
4. **Consistent** - Same patterns across all endpoints
5. **Documented** - OpenAPI specification

---

## Base URL

```
Production: https://api.mosis.dev/v1
Staging:    https://api.staging.mosis.dev/v1
Local:      http://localhost:8080/v1
```

---

## Authentication

### Headers

```
Authorization: Bearer <jwt_token>
# or
X-API-Key: mk_live_xxxxxxxx
```

### Scopes

| Scope | Description |
|-------|-------------|
| `apps:read` | Read app metadata |
| `apps:write` | Create/update apps |
| `versions:upload` | Upload new versions |
| `versions:publish` | Publish versions |
| `telemetry:read` | Read analytics |
| `keys:manage` | Manage API keys |

---

## Endpoints

### Authentication

```yaml
POST /v1/auth/oauth/github:
  summary: Start GitHub OAuth flow
  response: { redirect_url: string }

GET /v1/auth/oauth/github/callback:
  summary: GitHub OAuth callback
  query:
    code: string
    state: string
  response: { access_token, refresh_token, user }

POST /v1/auth/oauth/google:
  summary: Start Google OAuth flow
  response: { redirect_url: string }

GET /v1/auth/oauth/google/callback:
  summary: Google OAuth callback

POST /v1/auth/refresh:
  summary: Refresh access token
  body: { refresh_token: string }
  response: { access_token, refresh_token }

POST /v1/auth/logout:
  summary: Invalidate tokens
  auth: required

GET /v1/auth/me:
  summary: Get current user
  auth: required
  response: Developer
```

### Apps

```yaml
GET /v1/apps:
  summary: List developer's apps
  auth: required
  query:
    status: draft | published | suspended
    page: number
    limit: number
  response: { apps: App[], total: number }

POST /v1/apps:
  summary: Create new app
  auth: required
  body:
    package_id: string  # com.developer.appname
    name: string
    description?: string
    category?: string
  response: App

GET /v1/apps/:id:
  summary: Get app details
  auth: required
  response: App

PATCH /v1/apps/:id:
  summary: Update app metadata
  auth: required
  body:
    name?: string
    description?: string
    category?: string
    tags?: string[]
  response: App

DELETE /v1/apps/:id:
  summary: Delete app (if no published versions)
  auth: required
  response: { success: true }
```

### App Versions

```yaml
GET /v1/apps/:id/versions:
  summary: List app versions
  auth: required
  query:
    status: draft | review | approved | published | rejected
    page: number
    limit: number
  response: { versions: AppVersion[], total: number }

POST /v1/apps/:id/versions:
  summary: Create new version (get upload URL)
  auth: required
  body:
    version_name: string    # 1.0.0
    version_code: number    # 1
    release_notes?: string
  response:
    version: AppVersion
    upload_url: string      # Presigned S3 URL
    upload_expires: string  # ISO timestamp

PUT /v1/apps/:id/versions/:vid/upload-complete:
  summary: Mark upload as complete, trigger validation
  auth: required
  response: AppVersion

GET /v1/apps/:id/versions/:vid:
  summary: Get version details
  auth: required
  response: AppVersion

POST /v1/apps/:id/versions/:vid/submit:
  summary: Submit version for review
  auth: required
  response: AppVersion  # status: review

POST /v1/apps/:id/versions/:vid/publish:
  summary: Publish approved version
  auth: required
  response: AppVersion  # status: published

DELETE /v1/apps/:id/versions/:vid:
  summary: Delete draft version
  auth: required
  response: { success: true }
```

### Public App Store

```yaml
GET /v1/store/apps:
  summary: Browse/search published apps
  auth: none
  query:
    q: string           # Search query
    category: string
    sort: popular | recent | name
    page: number
    limit: number
  response: { apps: PublicApp[], total: number }

GET /v1/store/apps/:package_id:
  summary: Get app store listing
  auth: none
  response: PublicApp

GET /v1/store/apps/:package_id/download:
  summary: Get download URL for latest version
  auth: none (or device token)
  response:
    download_url: string
    version: string
    size: number
    signature: string

GET /v1/store/apps/:package_id/versions/:version_code/download:
  summary: Get download URL for specific version
  auth: none
  response: { download_url, version, size, signature }
```

### API Keys

```yaml
GET /v1/keys:
  summary: List API keys
  auth: required
  response: { keys: APIKey[] }

POST /v1/keys:
  summary: Create API key
  auth: required
  body:
    name: string
    permissions: string[]
    expires_at?: string
  response:
    key: APIKey
    secret: string  # Only shown once!

DELETE /v1/keys/:id:
  summary: Revoke API key
  auth: required
  response: { success: true }
```

### Signing Keys

```yaml
GET /v1/signing-keys:
  summary: List signing keys
  auth: required
  response: { keys: SigningKey[] }

POST /v1/signing-keys:
  summary: Register signing key
  auth: required
  body:
    name: string
    public_key: string  # PEM format
  response: SigningKey

DELETE /v1/signing-keys/:id:
  summary: Revoke signing key
  auth: required
  response: { success: true }
```

### Telemetry

```yaml
POST /v1/telemetry/events:
  summary: Submit telemetry events (batch)
  auth: device token or API key
  body:
    events:
      - app_id: string
        event_type: string
        event_data: object
        timestamp: string
  response: { received: number }

POST /v1/telemetry/crash:
  summary: Submit crash report
  auth: device token or API key
  body:
    app_id: string
    app_version: string
    crash_type: string
    message: string
    stack_trace: string
    context: object
    timestamp: string
  response: { id: string }

GET /v1/apps/:id/analytics:
  summary: Get app analytics
  auth: required
  query:
    start_date: string
    end_date: string
    metrics: downloads | active_users | crashes
  response:
    data:
      - date: string
        downloads: number
        active_users: number
        crashes: number

GET /v1/apps/:id/crashes:
  summary: Get crash reports
  auth: required
  query:
    version?: string
    page: number
    limit: number
  response: { crashes: CrashReport[], total: number }
```

---

## Data Models (Go)

### Developer

```go
type Developer struct {
    ID        string    `json:"id"`
    Email     string    `json:"email"`
    Name      string    `json:"name"`
    AvatarURL *string   `json:"avatar_url,omitempty"`
    Verified  bool      `json:"verified"`
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}
```

### App

```go
type AppStatus string

const (
    AppStatusDraft     AppStatus = "draft"
    AppStatusPublished AppStatus = "published"
    AppStatusSuspended AppStatus = "suspended"
)

type App struct {
    ID            string      `json:"id"`
    PackageID     string      `json:"package_id"`
    Name          string      `json:"name"`
    Description   *string     `json:"description,omitempty"`
    Category      *string     `json:"category,omitempty"`
    Tags          []string    `json:"tags"`
    Status        AppStatus   `json:"status"`
    IconURL       *string     `json:"icon_url,omitempty"`
    LatestVersion *AppVersion `json:"latest_version,omitempty"`
    CreatedAt     time.Time   `json:"created_at"`
    UpdatedAt     time.Time   `json:"updated_at"`
}
```

### AppVersion

```go
type VersionStatus string

const (
    VersionStatusDraft      VersionStatus = "draft"
    VersionStatusUploading  VersionStatus = "uploading"
    VersionStatusValidating VersionStatus = "validating"
    VersionStatusReview     VersionStatus = "review"
    VersionStatusApproved   VersionStatus = "approved"
    VersionStatusPublished  VersionStatus = "published"
    VersionStatusRejected   VersionStatus = "rejected"
)

type AppVersion struct {
    ID              string        `json:"id"`
    AppID           string        `json:"app_id"`
    VersionName     string        `json:"version_name"`
    VersionCode     int           `json:"version_code"`
    PackageURL      *string       `json:"package_url,omitempty"`
    PackageSize     *int64        `json:"package_size,omitempty"`
    Signature       *string       `json:"signature,omitempty"`
    Permissions     []string      `json:"permissions"`
    MinMosisVersion *string       `json:"min_mosis_version,omitempty"`
    ReleaseNotes    *string       `json:"release_notes,omitempty"`
    Status          VersionStatus `json:"status"`
    ReviewNotes     *string       `json:"review_notes,omitempty"`
    PublishedAt     *time.Time    `json:"published_at,omitempty"`
    CreatedAt       time.Time     `json:"created_at"`
}
```

### PublicApp

```go
type PublicApp struct {
    PackageID     string    `json:"package_id"`
    Name          string    `json:"name"`
    Description   *string   `json:"description,omitempty"`
    Category      *string   `json:"category,omitempty"`
    Tags          []string  `json:"tags"`
    IconURL       *string   `json:"icon_url,omitempty"`
    AuthorName    string    `json:"author_name"`
    LatestVersion string    `json:"latest_version"`
    DownloadCount int64     `json:"download_count"`
    Rating        *float64  `json:"rating,omitempty"`
    CreatedAt     time.Time `json:"created_at"`
    UpdatedAt     time.Time `json:"updated_at"`
}
```

### APIKey

```go
type APIKey struct {
    ID          string     `json:"id"`
    Name        string     `json:"name"`
    KeyPrefix   string     `json:"key_prefix"` // "mk_live_abc..."
    Permissions []string   `json:"permissions"`
    LastUsedAt  *time.Time `json:"last_used_at,omitempty"`
    ExpiresAt   *time.Time `json:"expires_at,omitempty"`
    CreatedAt   time.Time  `json:"created_at"`
}
```

### CrashReport

```go
type CrashReport struct {
    ID          string                 `json:"id"`
    AppID       string                 `json:"app_id"`
    AppVersion  string                 `json:"app_version"`
    CrashType   string                 `json:"crash_type"`
    Message     string                 `json:"message"`
    StackTrace  string                 `json:"stack_trace"`
    Context     map[string]interface{} `json:"context"`
    Occurrences int                    `json:"occurrences"`
    FirstSeen   time.Time              `json:"first_seen"`
    LastSeen    time.Time              `json:"last_seen"`
}
```

---

## Error Handling

### Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid package_id format",
    "details": {
      "field": "package_id",
      "constraint": "Must match pattern: ^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)+$"
    }
  }
}
```

### Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| `UNAUTHORIZED` | 401 | Missing or invalid auth |
| `FORBIDDEN` | 403 | Insufficient permissions |
| `NOT_FOUND` | 404 | Resource not found |
| `VALIDATION_ERROR` | 400 | Invalid request body |
| `CONFLICT` | 409 | Resource already exists |
| `RATE_LIMITED` | 429 | Too many requests |
| `INTERNAL_ERROR` | 500 | Server error |

---

## Rate Limiting

### Headers

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200
```

### Limits

| Endpoint Category | Limit | Window |
|-------------------|-------|--------|
| Auth | 10 | 1 minute |
| Read | 1000 | 1 hour |
| Write | 100 | 1 hour |
| Upload | 10 | 1 hour |
| Telemetry | 10000 | 1 hour |

---

## Pagination

### Request

```
GET /v1/apps?page=2&limit=20
```

### Response

```json
{
  "apps": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 45,
    "total_pages": 3
  }
}
```

---

## Webhooks (Future)

```yaml
POST /v1/webhooks:
  summary: Register webhook
  body:
    url: string
    events: string[]  # version.published, crash.new
    secret: string

Webhook Payload:
  headers:
    X-Mosis-Signature: sha256=xxx
  body:
    event: string
    data: object
    timestamp: string
```

---

## OpenAPI Specification

Full OpenAPI 3.0 spec will be generated and hosted at:
- `https://api.mosis.dev/v1/openapi.json`
- `https://api.mosis.dev/v1/docs` (Swagger UI)

---

## Implementation Structure (Go)

```
cmd/
└── portal/
    └── main.go              # Entry point, wire dependencies

internal/
├── api/
│   ├── router.go            # Chi router setup
│   ├── middleware/
│   │   ├── auth.go          # JWT/API key validation
│   │   ├── ratelimit.go     # Token bucket rate limiter
│   │   ├── logging.go       # Request/response logging
│   │   └── recovery.go      # Panic recovery
│   └── handlers/
│       ├── auth.go          # OAuth2 + token endpoints
│       ├── apps.go          # App CRUD
│       ├── versions.go      # Version upload/publish
│       ├── store.go         # Public store API
│       ├── keys.go          # API/signing keys
│       └── telemetry.go     # Event ingestion
├── service/
│   ├── app.go               # Business logic
│   ├── version.go
│   ├── auth.go
│   └── storage.go           # File storage operations
├── repository/
│   ├── sqlite/              # SQLite implementations
│   │   ├── app.go
│   │   ├── version.go
│   │   ├── developer.go
│   │   └── migrations/      # SQL migrations
│   └── interfaces.go        # Repository interfaces
└── domain/
    ├── app.go               # Domain types
    ├── version.go
    └── developer.go

pkg/
├── validator/               # Custom validation rules
└── signing/                 # Ed25519 operations
```

### Chi Router Setup

```go
func NewRouter(
    authHandler *handlers.AuthHandler,
    appHandler *handlers.AppHandler,
    storeHandler *handlers.StoreHandler,
) chi.Router {
    r := chi.NewRouter()

    // Global middleware
    r.Use(middleware.RequestID)
    r.Use(middleware.RealIP)
    r.Use(middleware.Logger)
    r.Use(middleware.Recoverer)
    r.Use(middleware.Timeout(30 * time.Second))

    // API v1
    r.Route("/v1", func(r chi.Router) {
        // Public routes
        r.Group(func(r chi.Router) {
            r.Post("/auth/oauth/github", authHandler.GitHubOAuth)
            r.Get("/auth/oauth/github/callback", authHandler.GitHubCallback)
            r.Post("/auth/refresh", authHandler.Refresh)
            r.Get("/store/apps", storeHandler.ListApps)
            r.Get("/store/apps/{packageID}", storeHandler.GetApp)
        })

        // Protected routes
        r.Group(func(r chi.Router) {
            r.Use(middleware.RequireAuth)
            r.Get("/auth/me", authHandler.Me)
            r.Route("/apps", func(r chi.Router) {
                r.Get("/", appHandler.List)
                r.Post("/", appHandler.Create)
                r.Route("/{appID}", func(r chi.Router) {
                    r.Get("/", appHandler.Get)
                    r.Patch("/", appHandler.Update)
                    r.Delete("/", appHandler.Delete)
                    r.Route("/versions", func(r chi.Router) {
                        r.Get("/", appHandler.ListVersions)
                        r.Post("/", appHandler.CreateVersion)
                    })
                })
            })
        })
    })

    return r
}
```

---

## Deliverables

- [ ] OpenAPI specification
- [ ] Authentication middleware
- [ ] Rate limiting middleware
- [ ] Auth endpoints
- [ ] Apps CRUD endpoints
- [ ] Versions endpoints with upload flow
- [ ] Store public endpoints
- [ ] API keys management
- [ ] Signing keys management
- [ ] Telemetry ingestion
- [ ] Error handling
- [ ] Request validation
- [ ] Integration tests

---

## Open Questions

1. ~~GraphQL alongside REST?~~ → REST only for simplicity
2. WebSocket for real-time review status? → Consider for v1.1
3. ~~Batch operations for bulk updates?~~ → Not needed for MVP
4. ~~API versioning strategy (URL vs header)?~~ → URL prefix (/v1/)

---

## References

- [REST API Design Guidelines](https://github.com/microsoft/api-guidelines)
- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
- [HTTP Status Codes](https://httpstatuses.com/)