ggen-api 5.1.0

REST API layer for ggen monetization: marketplace, billing, and SaaS operations
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171

//! API request and response models

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
use validator::Validate;

/// User registration request
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct RegisterRequest {
    #[validate(email)]
    pub email: String,
    #[validate(length(min = 6))]
    pub password: String,
    #[validate(length(min = 1))]
    pub username: String,
}

/// Login request
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct LoginRequest {
    pub email: String,
    #[validate(length(min = 6))]
    pub password: String,
}

/// Login response with JWT token
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LoginResponse {
    pub token: String,
    pub user_id: String,
    pub username: String,
    pub email: String,
    pub tier: String,
    pub expires_in_secs: u64,
}

/// Marketplace package search request
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct SearchRequest {
    pub query: String,
    #[validate(range(min = 1, max = 100))]
    pub limit: Option<u32>,
    pub offset: Option<u32>,
    pub category: Option<String>,
    pub sort_by: Option<String>, // "relevance", "downloads", "recent", "rating"
}

/// Package search result
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PackageResult {
    pub id: String,
    pub name: String,
    pub version: String,
    pub author: String,
    pub description: String,
    pub downloads: u64,
    pub price: Option<f64>,
    pub license: String,
    pub rating: f32,
}

/// Package purchase request
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PurchaseRequest {
    pub package_id: String,
    pub version: String,
}

/// Purchase response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PurchaseResponse {
    pub transaction_id: String,
    pub package_id: String,
    pub price: f64,
    pub status: String, // "pending", "completed", "failed"
    pub payment_url: Option<String>,
}

/// API key creation request
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct CreateApiKeyRequest {
    #[validate(length(min = 1))]
    pub name: String,
    pub expires_in_days: Option<u32>,
}

/// API key response (only returned on creation)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiKeyResponse {
    pub id: String,
    pub key: String, // Hashed in database, only shown once
    pub name: String,
    pub created_at: DateTime<Utc>,
    pub expires_at: Option<DateTime<Utc>>,
}

/// Usage tracking request
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UsageRequest {
    pub operation: String, // "api_call", "marketplace_search", "installation", etc.
    pub cost_credits: u32,
}

/// Usage statistics response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UsageStatsResponse {
    pub user_id: String,
    pub tier: String,
    pub period_start: DateTime<Utc>,
    pub period_end: DateTime<Utc>,
    pub api_calls_used: u64,
    pub api_calls_limit: u64,
    pub templates_used: u64,
    pub templates_limit: u64,
    pub total_credits_used: u64,
    pub total_credits_available: u64,
}

/// Invoice response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InvoiceResponse {
    pub invoice_id: String,
    pub user_id: String,
    pub amount: f64,
    pub currency: String,
    pub status: String, // "paid", "pending", "failed"
    pub issued_at: DateTime<Utc>,
    pub due_at: DateTime<Utc>,
    pub items: Vec<InvoiceItem>,
}

/// Invoice line item
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct InvoiceItem {
    pub description: String,
    pub quantity: u32,
    pub unit_price: f64,
    pub total: f64,
}

/// Subscription upgrade/downgrade request
#[derive(Debug, Clone, Serialize, Deserialize, Validate)]
pub struct UpgradeRequest {
    pub new_tier: String, // "free", "pro", "enterprise"
}

/// Health check response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct HealthResponse {
    pub status: String,
    pub timestamp: DateTime<Utc>,
    pub version: String,
}

/// Generic paginated response wrapper
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PaginatedResponse<T> {
    pub data: Vec<T>,
    pub total: u64,
    pub limit: u32,
    pub offset: u32,
}

/// Error response
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ErrorResponse {
    pub error: String,
    pub status: u16,
    pub timestamp: DateTime<Utc>,
}