thread-master/apps/backend/generate/api/settings.api

syntax = "v1"

type (
	// GetAi：設定 + 模型清單一併回（避免前端分開打兩支）
	GetAiReq {
		// 可選：預覽另一個 provider 的模型清單（不改存檔）
		Provider string `form:"provider,optional"`
	}

	AiSettingsData {
		Provider                 string   `json:"provider"`
		Model                    string   `json:"model"`
		ResearchProvider         string   `json:"research_provider"`
		ResearchModel            string   `json:"research_model"`
		ApiKeyConfigured         bool     `json:"api_key_configured"`
		ResearchApiKeyConfigured bool     `json:"research_api_key_configured"`
		PlatformKeyAvailable     bool     `json:"platform_key_available"`
		// Models — 目前 models_provider 的可用模型（真拉 + 5 分鐘快取）
		Models         []string `json:"models"`
		ModelsProvider string   `json:"models_provider"`
		// SelectedModel — 與 Model 相同；明確給前端「上次設定的模型」
		SelectedModel string `json:"selected_model"`
		// ModelsFromCache — 這次模型清單是否來自快取
		ModelsFromCache bool `json:"models_from_cache,optional"`
		// ModelsError — 真拉失敗時提示（仍回 fallback models）
		ModelsError string `json:"models_error,optional"`
	}

	SaveAiReq {
		Provider                 string `json:"provider,optional"`
		Model                    string `json:"model,optional"`
		ResearchProvider         string `json:"research_provider,optional"`
		ResearchModel            string `json:"research_model,optional"`
		ApiKey                   string `json:"api_key,optional"`
		ResearchApiKey           string `json:"research_api_key,optional"`
		ApiKeyConfigured         *bool  `json:"api_key_configured,optional"`
		ResearchApiKeyConfigured *bool  `json:"research_api_key_configured,optional"`
	}

	PlacementSettingsData {
		WebSearchProvider     string `json:"web_search_provider"`
		ExpandStrategy        string `json:"expand_strategy"`
		BraveApiKeyConfigured bool   `json:"brave_api_key_configured"`
		ExaApiKeyConfigured   bool   `json:"exa_api_key_configured"`
		DevModeEnabled        bool   `json:"dev_mode_enabled"`
		PlatformKeyAvailable  bool   `json:"platform_key_available"`
	}

	SavePlacementReq {
		ExpandStrategy      string `json:"expand_strategy,optional"`
		DevModeEnabled      *bool  `json:"dev_mode_enabled,optional"`
		ExaApiKey           string `json:"exa_api_key,optional"`
		ExaApiKeyConfigured *bool  `json:"exa_api_key_configured,optional"`
	}

	ListModelsReq {
		Provider string `form:"provider,optional"`
	}

	ListModelsData {
		List       []string `json:"list"`
		Provider   string   `json:"provider"`
		// SelectedModel — 若該 provider 為使用者目前存檔 provider，回傳已選 model
		SelectedModel   string `json:"selected_model,optional"`
		FromCache       bool   `json:"from_cache,optional"`
		ModelsError     string `json:"models_error,optional"`
	}

	// Threads OAuth 平台狀態（App Secret 永不回傳）
	ThreadsSettingsData {
		Provider       string `json:"provider"` // fake | meta
		Configured     bool   `json:"configured"`
		OauthReady     bool   `json:"oauth_ready"`
		ConnectPath    string `json:"connect_path"` // 前端連帳入口
		// 給 Meta 後台「Valid OAuth Redirect URIs」貼上用
		CallbackUrl    string `json:"callback_url"`
		// 前端公開 origin（應 https）
		PublicWebBase  string `json:"public_web_base"`
		// App Id 遮罩，例 2733…9930；未設定空字串
		AppIdMasked    string `json:"app_id_masked,optional"`
		Hint           string `json:"hint"`
	}
)

@server (
	group:      settings
	prefix:     /api/v1/settings
	middleware: AuthJWT
)
service gateway {
	@handler GetAi
	get /ai (GetAiReq) returns (AiSettingsData)

	@handler SaveAi
	put /ai (SaveAiReq) returns (AiSettingsData)

	@handler GetPlacement
	get /placement returns (PlacementSettingsData)

	@handler SavePlacement
	put /placement (SavePlacementReq) returns (PlacementSettingsData)

	@handler ListModels
	get /models (ListModelsReq) returns (ListModelsData)

	@handler GetThreads
	get /threads returns (ThreadsSettingsData)
}