feat(clients): openai admin: organization admin API, usage, costs, audit logs, webhooks

121-call table checked against the OpenAI OpenAPI document, admin-key-only
client, destructive guards, WebhookVerifier (Standard Webhooks HMAC-SHA256),
demo routes under /ai/openai/admin, local and opt-in live tests.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-24 07:43:17 +02:00
co-authored by Claude Sonnet 5.5
parent 2e0270c043
commit 9e550889cc
47 changed files with 5533 additions and 3 deletions
+219
View File
@@ -0,0 +1,219 @@
#include "openai/admin/usage.h"
#include <algorithm>
#include "llm/error.h"
#include "openai/admin/caps.h"
#include "openai/admin/validate.h"
namespace molo::openai::admin {
namespace {
struct Endpoint {
UsageKind kind;
const char* name;
Call call;
const char* group_by; // comma list from the spec; "" = unconstrained
};
// USAGE-ENDPOINTS-BEGIN (name, group_by enum; checked by tools/check_spec.py)
const Endpoint kEndpoints[] = {
{UsageKind::kCompletions, "completions", Call::kUsageCompletions,
"project_id,user_id,api_key_id,model,batch,service_tier,api_source"},
{UsageKind::kEmbeddings, "embeddings", Call::kUsageEmbeddings,
"project_id,user_id,api_key_id,model"},
{UsageKind::kModerations, "moderations", Call::kUsageModerations,
"project_id,user_id,api_key_id,model"},
{UsageKind::kImages, "images", Call::kUsageImages,
"project_id,user_id,api_key_id,model,size,source"},
{UsageKind::kAudioSpeeches, "audio_speeches", Call::kUsageAudioSpeeches,
"project_id,user_id,api_key_id,model"},
{UsageKind::kAudioTranscriptions, "audio_transcriptions", Call::kUsageAudioTranscriptions,
"project_id,user_id,api_key_id,model"},
{UsageKind::kVectorStores, "vector_stores", Call::kUsageVectorStores, "project_id"},
{UsageKind::kCodeInterpreterSessions, "code_interpreter_sessions",
Call::kUsageCodeInterpreterSessions, "project_id"},
{UsageKind::kFileSearchCalls, "file_search_calls", Call::kUsageFileSearchCalls,
"project_id,user_id,api_key_id,vector_store_id"},
{UsageKind::kWebSearchCalls, "web_search_calls", Call::kUsageWebSearchCalls,
"project_id,user_id,api_key_id,model,context_level,api_source"},
{UsageKind::kDecisions, "decisions", Call::kUsageDecisions, ""},
};
// USAGE-ENDPOINTS-END
const Endpoint& endpoint(UsageKind kind) {
for (const Endpoint& e : kEndpoints)
if (e.kind == kind) return e;
Validate::fail("unknown usage endpoint");
}
int max_buckets(const std::string& width) {
if (width == "1m") return AdminCaps::kMaxBuckets1m;
if (width == "1h") return AdminCaps::kMaxBuckets1h;
return AdminCaps::kMaxBuckets1d;
}
void common(Query& q, std::int64_t start, const std::optional<std::int64_t>& end,
const std::string& page) {
Validate::epoch("start_time", start);
q.set_int("start_time", start);
if (end) {
Validate::epoch("end_time", *end);
if (*end <= start) Validate::fail("end_time must be after start_time");
q.set_int("end_time", *end);
}
if (!page.empty()) q.set("page", page);
}
void group_by_check(const std::vector<std::string>& values, const std::vector<std::string>& allowed) {
Validate::count("group_by", values.size(), AdminCaps::kMaxGroupBy, true);
for (const std::string& g : values) {
Validate::text("group_by", g, 64);
if (!allowed.empty() && std::find(allowed.begin(), allowed.end(), g) == allowed.end())
Validate::fail("group_by " + g + " is not allowed here");
}
}
void filter(Query& q, Call call, const char* name, const std::vector<std::string>& values) {
if (values.empty()) return;
if (!CallTable::allows_query(call, name))
Validate::fail(std::string(name) + " is not a filter of " + CallTable::spec(call).key);
q.add_all(name, values);
}
} // namespace
const std::vector<UsageKind>& UsageEndpoints::all() {
static const std::vector<UsageKind> kinds = [] {
std::vector<UsageKind> v;
for (const Endpoint& e : kEndpoints) v.push_back(e.kind);
return v;
}();
return kinds;
}
Call UsageEndpoints::call(UsageKind kind) { return endpoint(kind).call; }
std::string UsageEndpoints::name(UsageKind kind) { return endpoint(kind).name; }
std::optional<UsageKind> UsageEndpoints::parse(const std::string& name) {
for (const Endpoint& e : kEndpoints)
if (name == e.name) return e.kind;
return std::nullopt;
}
std::vector<std::string> UsageEndpoints::group_by(UsageKind kind) {
return CallTable::split(endpoint(kind).group_by);
}
Query UsageQuery::to_query(UsageKind kind) const {
const Call call = UsageEndpoints::call(kind);
Query q;
common(q, start_time, end_time, page);
if (!bucket_width.empty()) {
Validate::one_of("bucket_width", bucket_width, {"1m", "1h", "1d"});
q.set("bucket_width", bucket_width);
}
if (limit) {
Validate::range("limit", *limit, 1, max_buckets(bucket_width));
q.set_int("limit", *limit);
}
filter(q, call, "project_ids", project_ids);
filter(q, call, "user_ids", user_ids);
filter(q, call, "api_key_ids", api_key_ids);
filter(q, call, "models", models);
if (batch) {
if (!CallTable::allows_query(call, "batch")) Validate::fail("batch is not a filter here");
q.set_bool("batch", *batch);
}
group_by_check(group_by, UsageEndpoints::group_by(kind));
filter(q, call, "group_by", group_by);
for (const std::string& s : sources)
Validate::one_of("source", s, {"image.generation", "image.edit", "image.variation"});
for (const std::string& s : sizes)
Validate::one_of("size", s, {"256x256", "512x512", "1024x1024", "1792x1792", "1024x1792"});
filter(q, call, "sources", sources);
filter(q, call, "sizes", sizes);
filter(q, call, "vector_store_ids", vector_store_ids);
filter(q, call, "context_levels", context_levels);
return q;
}
Query CostQuery::to_query() const {
Query q;
common(q, start_time, end_time, page);
if (!bucket_width.empty()) {
Validate::one_of("bucket_width", bucket_width, {"1d"});
q.set("bucket_width", bucket_width);
}
if (limit) {
Validate::range("limit", *limit, 1, AdminCaps::kMaxCostBuckets);
q.set_int("limit", *limit);
}
filter(q, Call::kCosts, "project_ids", project_ids);
filter(q, Call::kCosts, "api_key_ids", api_key_ids);
filter(q, Call::kCosts, "line_items", line_items);
group_by_check(group_by, {"project_id", "user_id", "line_item", "api_key_id", "api_source"});
filter(q, Call::kCosts, "group_by", group_by);
return q;
}
AdminService::Json Usage::query(UsageKind kind, const UsageQuery& query) {
return execute(UsageEndpoints::call(kind), {}, query.to_query(kind));
}
WalkResult Usage::walk(UsageKind kind, const UsageQuery& query) {
UsageQuery first = query;
first.page.clear();
return AdminService::walk(UsageEndpoints::call(kind), {}, first.to_query(kind), "page", query.page);
}
AdminService::Json Costs::query(const CostQuery& query) {
return execute(Call::kCosts, {}, query.to_query());
}
WalkResult Costs::walk(const CostQuery& query) {
CostQuery first = query;
first.page.clear();
return AdminService::walk(Call::kCosts, {}, first.to_query(), "page", query.page);
}
const clients::body::Json::Array& UsageSummary::buckets_of(const clients::body::Json& doc) {
static const clients::body::Json::Array none;
if (doc.is_array()) return doc.as_array();
const clients::body::Json* data = doc.is_object() ? doc.find("data") : nullptr;
return data && data->is_array() ? data->as_array() : none;
}
std::map<std::string, double> UsageSummary::totals(const clients::body::Json& buckets) {
std::map<std::string, double> sum;
for (const auto& bucket : buckets_of(buckets)) {
const auto* results = bucket.is_object() ? bucket.find("results") : nullptr;
if (!results || !results->is_array()) continue;
for (const auto& r : results->as_array()) {
if (!r.is_object()) continue;
for (const auto& [name, value] : r.as_object())
if (value.is_number()) sum[name] += value.as_number();
}
}
return sum;
}
std::map<std::string, double> UsageSummary::cost_by_currency(const clients::body::Json& buckets) {
std::map<std::string, double> sum;
for (const auto& bucket : buckets_of(buckets)) {
const auto* results = bucket.is_object() ? bucket.find("results") : nullptr;
if (!results || !results->is_array()) continue;
for (const auto& r : results->as_array()) {
const auto* amount = r.is_object() ? r.find("amount") : nullptr;
if (!amount || !amount->is_object()) continue;
const auto* value = amount->find("value");
const auto* currency = amount->find("currency");
if (value && value->is_number())
sum[currency && currency->is_string() ? currency->as_string() : "unknown"] += value->as_number();
}
}
return sum;
}
} // namespace molo::openai::admin