Skip to main content

sylphx_sdk_management/
lib.rs

1//! Sylphx Management-plane SDK — wire types from `sylphx-api-types` only.
2//! Agent-complete operator surface (no Console required).
3
4#![forbid(unsafe_code)]
5#![deny(missing_docs)]
6
7mod agent_computer;
8mod generated_agent_computer;
9
10pub use generated_agent_computer::{
11    AgentComputerControlClient, AgentComputerDataClient, AgentComputerMediaClient,
12    ArtifactIngestClient, AGENT_COMPUTER_DESCRIPTOR_GRAPH_SHA256,
13    AGENT_COMPUTER_DESCRIPTOR_ROOT_FILE, AGENT_COMPUTER_DESCRIPTOR_ROOT_SHA256,
14};
15
16use std::time::Duration;
17
18use reqwest::Method;
19use serde_json::Value;
20use sylphx_sdk_core::{
21    strip_json_nulls, Credential, RetryConfig, SdkError, Transport, TransportConfig,
22    DEFAULT_MANAGEMENT_BASE_URL,
23};
24use sylphx_api_types::{
25    BindResourceResponse,
26    CreateDeployResponse,
27    CreateFlagResponse,
28    CreateResourceResponse,
29    DeleteEnvVarResponse,
30    DeleteResourceResponse,
31    Deployment,
32    Environment,
33    EnvVar,
34    HealthResponse,
35    ListDeploymentsResponse,
36    ListEnvironmentsResponse,
37    ListEnvVarsResponse,
38    ListFlagsResponse,
39    ListLogsResponse,
40    ListProjectDomainsResponse,
41    ListProjectServicesResponse,
42    ListProjectsResponse,
43    ListResourcesResponse,
44    LogLine,
45    OrganizationRef,
46    PageRequest,
47    Project,
48    GetProjectStatusResponse,
49    ProjectDomain,
50    ProjectService,
51    Resource,
52    SetEnvVarResponse,
53    WhoAmIResponse,
54};
55
56/// Exact request-extension identity shared with Platform admission middleware.
57pub use sylphx_api_types::{
58    VerifiedBindingContext, VerifiedBindingContextError, VERIFIED_BINDING_CONTEXT_REVISION,
59};
60
61/// Management-plane client.
62#[derive(Debug, Clone)]
63pub struct ManagementClient {
64    transport: Transport,
65}
66
67/// Builder for [`ManagementClient`].
68#[derive(Debug, Clone)]
69pub struct ManagementClientBuilder {
70    token: String,
71    base_url: String,
72    timeout: Duration,
73    retry: RetryConfig,
74}
75
76/// Pagination options mapped 1:1 onto wire [`PageRequest`].
77#[derive(Debug, Clone, Default)]
78pub struct ListOptions {
79    /// Opaque page token (`PageRequest.page_token`).
80    pub page_token: Option<String>,
81    /// Page size hint (`PageRequest.page_size`).
82    pub page_size: Option<u32>,
83}
84
85impl ListOptions {
86    /// Convert to the protobuf wire page message.
87    pub fn to_page_request(&self) -> PageRequest {
88        PageRequest {
89            page_token: self.page_token.clone().unwrap_or_default(),
90            page_size: self.page_size.unwrap_or(0),
91            ..Default::default()
92        }
93    }
94}
95
96impl ManagementClient {
97    /// Start a builder with a management token.
98    pub fn builder(token: impl Into<String>) -> ManagementClientBuilder {
99        ManagementClientBuilder {
100            token: token.into(),
101            base_url: DEFAULT_MANAGEMENT_BASE_URL.to_string(),
102            timeout: Duration::from_secs(30),
103            retry: RetryConfig::default(),
104        }
105    }
106
107    /// Convenience constructor with defaults.
108    pub fn new(token: impl Into<String>) -> Result<Self, SdkError> {
109        Self::builder(token).build()
110    }
111
112    /// Descriptor-generated Agent Computer control service.
113    pub fn agent_computer_control(&self) -> AgentComputerControlClient {
114        AgentComputerControlClient::new(self.transport.clone())
115    }
116
117    /// Descriptor-generated Agent Computer data service.
118    pub fn agent_computer_data(&self) -> AgentComputerDataClient {
119        AgentComputerDataClient::new(self.transport.clone())
120    }
121
122    /// Descriptor-generated Agent Computer media service.
123    pub fn agent_computer_media(&self) -> AgentComputerMediaClient {
124        AgentComputerMediaClient::new(self.transport.clone())
125    }
126
127    /// Descriptor-generated application-artifact ingest service.
128    pub fn artifact_ingest(&self) -> ArtifactIngestClient {
129        ArtifactIngestClient::new(self.transport.clone())
130    }
131
132    /// `GET /health`.
133    pub async fn health(&self) -> Result<HealthResponse, SdkError> {
134        self.transport
135            .get_json::<HealthResponse>("/health", &[])
136            .await
137    }
138
139    /// Forward-compatible health probe: returns the JSON `status` string only.
140    ///
141    /// Live Management `/health` may carry additive operator fields (`draining`,
142    /// `services`, …) ahead of the frozen wire `HealthResponse`. Doctor and
143    /// readiness checks use this when typed decode rejects unknown fields.
144    pub async fn health_status_probe(&self) -> Result<String, SdkError> {
145        let (_status, body) = self
146            .transport
147            .raw_request(Method::GET, "/health", None::<&Value>, &[])
148            .await?;
149        body.get("status")
150            .and_then(Value::as_str)
151            .map(str::to_string)
152            .ok_or_else(|| SdkError::Decode("health response missing status".into()))
153    }
154
155    /// `GET /projects` as raw JSON (forward-compatible when Project fields advance).
156    pub async fn list_projects_json(
157        &self,
158        org_id: Option<&str>,
159    ) -> Result<Value, SdkError> {
160        let (_status, body) = self
161            .transport
162            .raw_request(Method::GET, "/projects", None::<&Value>, &org_header(org_id))
163            .await?;
164        Ok(body)
165    }
166
167    /// `GET /backups` as raw JSON (forward-compatible list envelope).
168    pub async fn list_backups_json(
169        &self,
170        resource_id: Option<&str>,
171        org_id: Option<&str>,
172    ) -> Result<Value, SdkError> {
173        let path = if let Some(rid) = resource_id {
174            format!("/resources/{}/backups", urlencoding_encode(rid))
175        } else {
176            "/backups".to_string()
177        };
178        let (_status, body) = self
179            .transport
180            .raw_request(Method::GET, &path, None::<&Value>, &org_header(org_id))
181            .await?;
182        Ok(body)
183    }
184
185    /// `GET /whoami` as wire [`WhoAmIResponse`].
186    pub async fn whoami(&self) -> Result<WhoAmIResponse, SdkError> {
187        self.transport
188            .get_json::<WhoAmIResponse>("/whoami", &[])
189            .await
190    }
191
192    /// Organizations for the authenticated principal (from WhoAmI).
193    pub async fn list_orgs(&self) -> Result<Vec<OrganizationRef>, SdkError> {
194        Ok(self.whoami().await?.orgs)
195    }
196
197    /// `GET /projects`.
198    pub async fn list_projects(
199        &self,
200        org_id: Option<&str>,
201        page: Option<&ListOptions>,
202    ) -> Result<ListProjectsResponse, SdkError> {
203        let query = page_query(page);
204        let headers = org_header(org_id);
205        self.transport
206            .get_json_query::<ListProjectsResponse>("/projects", &query, &headers)
207            .await
208    }
209
210    /// Project rows only.
211    pub async fn list_project_items(
212        &self,
213        org_id: Option<&str>,
214        page: Option<&ListOptions>,
215    ) -> Result<Vec<Project>, SdkError> {
216        Ok(self.list_projects(org_id, page).await?.data)
217    }
218
219    /// `GET /projects/{id}`.
220    pub async fn get_project(&self, id: &str, org_id: Option<&str>) -> Result<Project, SdkError> {
221        let path = format!("/projects/{}", urlencoding_encode(id));
222        self.transport
223            .get_json::<Project>(&path, &org_header(org_id))
224            .await
225    }
226
227    /// `POST /projects` — create project.
228    pub async fn create_project(
229        &self,
230        name: &str,
231        slug: Option<&str>,
232        org_id: Option<&str>,
233        description: Option<&str>,
234        git_ref: Option<&str>,
235    ) -> Result<Project, SdkError> {
236        let mut body = serde_json::json!({ "name": name });
237        if let Some(s) = slug {
238            body["slug"] = serde_json::json!(s);
239        }
240        if let Some(d) = description {
241            body["description"] = serde_json::json!(d);
242        }
243        if let Some(r) = git_ref {
244            body["ref"] = serde_json::json!(r);
245        }
246        self.transport
247            .post_json::<Value, Project>("/projects", &body, &org_header(org_id))
248            .await
249    }
250
251    /// `GET /projects/{project_id}/environments`.
252    pub async fn list_environments(
253        &self,
254        project_id: &str,
255        page: Option<&ListOptions>,
256        org_id: Option<&str>,
257    ) -> Result<ListEnvironmentsResponse, SdkError> {
258        let query = page_query(page);
259        let path = format!(
260            "/projects/{}/environments",
261            urlencoding_encode(project_id)
262        );
263        self.transport
264            .get_json_query::<ListEnvironmentsResponse>(&path, &query, &org_header(org_id))
265            .await
266    }
267
268    /// Environment rows only.
269    pub async fn list_environment_items(
270        &self,
271        project_id: &str,
272        page: Option<&ListOptions>,
273        org_id: Option<&str>,
274    ) -> Result<Vec<Environment>, SdkError> {
275        Ok(self
276            .list_environments(project_id, page, org_id)
277            .await?
278            .data)
279    }
280
281    /// `GET /projects/{project_id}/environments/{environment_id}`.
282    pub async fn get_environment(
283        &self,
284        project_id: &str,
285        environment_id: &str,
286        org_id: Option<&str>,
287    ) -> Result<Environment, SdkError> {
288        let path = format!(
289            "/projects/{}/environments/{}",
290            urlencoding_encode(project_id),
291            urlencoding_encode(environment_id)
292        );
293        self.transport
294            .get_json::<Environment>(&path, &org_header(org_id))
295            .await
296    }
297
298    /// `GET /projects/{project_id}/deployments`.
299    pub async fn list_deployments(
300        &self,
301        project_id: &str,
302        page: Option<&ListOptions>,
303        org_id: Option<&str>,
304    ) -> Result<ListDeploymentsResponse, SdkError> {
305        let query = page_query(page);
306        let path = format!(
307            "/projects/{}/deployments",
308            urlencoding_encode(project_id)
309        );
310        self.transport
311            .get_json_query::<ListDeploymentsResponse>(&path, &query, &org_header(org_id))
312            .await
313    }
314
315    /// Deployment rows only.
316    pub async fn list_deployment_items(
317        &self,
318        project_id: &str,
319        page: Option<&ListOptions>,
320        org_id: Option<&str>,
321    ) -> Result<Vec<Deployment>, SdkError> {
322        Ok(self
323            .list_deployments(project_id, page, org_id)
324            .await?
325            .data)
326    }
327
328    /// `POST /projects/{project_id}/deploy`.
329    ///
330    /// Dual-oracle of TS `deployments.triggerResolved`: body may carry `envId`,
331    /// `envType`, git identity (`gitSha`/`ref`), optional `serviceId`, and
332    /// `force` to supersede an in-flight identical SHA.
333    pub async fn create_deploy(
334        &self,
335        project_id: &str,
336        env_type: Option<&str>,
337        env_id: Option<&str>,
338        git_ref: Option<&str>,
339        service_id: Option<&str>,
340        org_id: Option<&str>,
341    ) -> Result<CreateDeployResponse, SdkError> {
342        self.create_deploy_with_options(
343            project_id,
344            env_type,
345            env_id,
346            git_ref,
347            service_id,
348            false,
349            org_id,
350        )
351        .await
352    }
353
354    /// Extended deploy trigger with force (ADR-style explicit rebuild).
355    pub async fn create_deploy_with_options(
356        &self,
357        project_id: &str,
358        env_type: Option<&str>,
359        env_id: Option<&str>,
360        git_ref: Option<&str>,
361        service_id: Option<&str>,
362        force: bool,
363        org_id: Option<&str>,
364    ) -> Result<CreateDeployResponse, SdkError> {
365        let mut body = serde_json::Map::new();
366        if let Some(v) = env_type {
367            body.insert("envType".into(), Value::String(v.into()));
368        }
369        if let Some(v) = env_id {
370            body.insert("envId".into(), Value::String(v.into()));
371        }
372        if let Some(v) = git_ref {
373            // Product deploy admits both gitSha (full) and ref (branch/tag).
374            // Prefer gitSha when value looks like a full/short SHA.
375            let looks_like_sha = v.len() >= 7
376                && v.chars()
377                    .all(|c| c.is_ascii_hexdigit());
378            if looks_like_sha {
379                body.insert("gitSha".into(), Value::String(v.into()));
380                body.insert("gitCommit".into(), Value::String(v.into()));
381            } else {
382                body.insert("ref".into(), Value::String(v.into()));
383            }
384        }
385        if let Some(v) = service_id {
386            let (field, value) = management_deploy_service_field(v);
387            body.insert(field.into(), Value::String(value.into()));
388        }
389        if force {
390            body.insert("force".into(), Value::Bool(true));
391        }
392        let path = format!("/projects/{}/deploy", urlencoding_encode(project_id));
393        self.transport
394            .post_json::<Value, CreateDeployResponse>(
395                &path,
396                &Value::Object(body),
397                &org_header(org_id),
398            )
399            .await
400    }
401
402    /// `POST /projects/{project_id}/rollback`.
403
404    /// `GET /projects/{project_id}/status`.
405    pub async fn get_project_status(
406        &self,
407        project_id: &str,
408        org_id: Option<&str>,
409    ) -> Result<GetProjectStatusResponse, SdkError> {
410        let path = format!("/projects/{}/status", urlencoding_encode(project_id));
411        self.transport
412            .get_json::<GetProjectStatusResponse>(&path, &org_header(org_id))
413            .await
414    }
415
416    /// `GET /projects/{project_id}/env-vars`, with live fallback to `GET /secrets?projectId=`.
417    ///
418    /// Live Management no longer serves nested `/projects/{id}/env-vars` (honest 404).
419    /// Product secrets (`environment_secrets`) are the operator-facing key surface and
420    /// map to redacted `EnvVar` rows (`secret=true`, value omitted).
421    /// List environment variables (canonical secrets surface).
422    ///
423    /// `GET /secrets?projectId=` — the environment-secrets store is the sole
424    /// env-var plane; legacy `/projects/{id}/env-vars` paths are removed.
425    pub async fn list_env_vars(
426        &self,
427        project_id: &str,
428        env_id: Option<&str>,
429        org_id: Option<&str>,
430    ) -> Result<ListEnvVarsResponse, SdkError> {
431        let mut qs = format!("projectId={}", urlencoding_encode(project_id));
432        if let Some(v) = env_id {
433            qs.push_str(&format!("&environmentId={}", urlencoding_encode(v)));
434        }
435        let path = format!("/secrets?{qs}");
436        let (_status, body) = self
437            .transport
438            .raw_request(Method::GET, &path, None::<&Value>, &org_header(org_id))
439            .await?;
440        let secrets = body
441            .get("secrets")
442            .and_then(Value::as_array)
443            .cloned()
444            .unwrap_or_default();
445        let data = secrets
446            .into_iter()
447            .filter_map(|s| {
448                let key = s.get("key")?.as_str()?.to_string();
449                let env_id = s
450                    .pointer("/environment/id")
451                    .and_then(Value::as_str)
452                    .map(str::to_string);
453                Some(EnvVar {
454                    key,
455                    value: None,
456                    secret: true,
457                    env_type: None,
458                    env_id,
459                    ..Default::default()
460                })
461            })
462            .collect();
463        Ok(ListEnvVarsResponse {
464            object: "list".into(),
465            data,
466            ..Default::default()
467        })
468    }
469
470    /// Set an environment variable (canonical secrets surface).
471    ///
472    /// `POST /secrets` — all env-var values are stored as encrypted secrets.
473    pub async fn set_env_var(
474        &self,
475        project_id: &str,
476        key: &str,
477        value: &str,
478        env_id: Option<&str>,
479        org_id: Option<&str>,
480    ) -> Result<SetEnvVarResponse, SdkError> {
481        let mut body = serde_json::json!({
482            "projectId": project_id,
483            "key": key,
484            "value": value,
485        });
486        if let Some(v) = env_id {
487            body["environmentId"] = Value::String(v.into());
488        }
489        let (_status, resp) = self
490            .transport
491            .raw_request(Method::POST, "/secrets", Some(&body), &org_header(org_id))
492            .await?;
493        let created = resp.get("id").is_some();
494        Ok(SetEnvVarResponse {
495            env_var: EnvVar {
496                key: key.to_string(),
497                value: None,
498                secret: true,
499                env_type: None,
500                env_id: env_id.map(str::to_string),
501                ..Default::default()
502            }.into(),
503            created,
504            ..Default::default()
505        })
506    }
507
508    /// Delete an environment variable (canonical secrets surface).
509    ///
510    /// `DELETE /secrets` requires the secret id, so the key is resolved via the
511    /// project's secret list first.
512    pub async fn delete_env_var(
513        &self,
514        project_id: &str,
515        key: &str,
516        env_id: Option<&str>,
517        org_id: Option<&str>,
518    ) -> Result<DeleteEnvVarResponse, SdkError> {
519        let mut qs = format!("projectId={}", urlencoding_encode(project_id));
520        if let Some(v) = env_id {
521            qs.push_str(&format!("&environmentId={}", urlencoding_encode(v)));
522        }
523        let (_status, body) = self
524            .transport
525            .raw_request(
526                Method::GET,
527                &format!("/secrets?{qs}"),
528                None::<&Value>,
529                &org_header(org_id),
530            )
531            .await?;
532        let secrets = body
533            .get("secrets")
534            .and_then(Value::as_array)
535            .cloned()
536            .unwrap_or_default();
537        let secret_id = secrets.iter().find_map(|s| {
538            let k = s.get("key")?.as_str()?;
539            if k == key {
540                s.get("id")?.as_str().map(str::to_string)
541            } else {
542                None
543            }
544        });
545        let Some(secret_id) = secret_id else {
546            return Ok(DeleteEnvVarResponse {
547                deleted: false,
548                key: key.to_string(),
549                ..Default::default()
550            });
551        };
552        let delete_body = serde_json::json!({ "id": secret_id });
553        let (_status, resp) = self
554            .transport
555            .raw_request(Method::DELETE, "/secrets", Some(&delete_body), &org_header(org_id))
556            .await?;
557        let deleted = resp
558            .get("deleted")
559            .and_then(Value::as_bool)
560            .or_else(|| resp.get("ok").and_then(Value::as_bool))
561            .unwrap_or(true);
562        Ok(DeleteEnvVarResponse {
563            deleted,
564            key: key.to_string(),
565            ..Default::default()
566        })
567    }
568
569    /// `GET /projects/{id}/logs` or `GET /environments/{id}/logs`.
570    pub async fn list_logs(
571        &self,
572        project_id: Option<&str>,
573        environment_id: Option<&str>,
574        log_type: Option<&str>,
575        env_type: Option<&str>,
576        limit: Option<u32>,
577        level: Option<&str>,
578        service: Option<&str>,
579        grep: Option<&str>,
580        org_id: Option<&str>,
581    ) -> Result<ListLogsResponse, SdkError> {
582        let mut query: Vec<(&str, String)> = Vec::new();
583        if let Some(v) = log_type {
584            query.push(("type", v.to_string()));
585        }
586        if let Some(v) = env_type {
587            query.push(("envType", v.to_string()));
588        }
589        if let Some(v) = limit {
590            query.push(("limit", v.to_string()));
591        }
592        if let Some(v) = level {
593            query.push(("level", v.to_string()));
594        }
595        if let Some(v) = service {
596            query.push(("service", v.to_string()));
597        }
598        if let Some(v) = grep {
599            query.push(("grep", v.to_string()));
600        }
601        let path = if let Some(env) = environment_id {
602            format!("/environments/{}/logs", urlencoding_encode(env))
603        } else if let Some(prj) = project_id {
604            format!("/projects/{}/logs", urlencoding_encode(prj))
605        } else {
606            return Err(SdkError::InvalidUrl(
607                "list_logs requires project_id or environment_id".into(),
608            ));
609        };
610        self.transport
611            .get_json_query::<ListLogsResponse>(&path, &query, &org_header(org_id))
612            .await
613    }
614
615    /// Convenience: log lines only.
616    pub async fn list_log_items(
617        &self,
618        project_id: Option<&str>,
619        environment_id: Option<&str>,
620        log_type: Option<&str>,
621        env_type: Option<&str>,
622        limit: Option<u32>,
623        level: Option<&str>,
624        service: Option<&str>,
625        grep: Option<&str>,
626        org_id: Option<&str>,
627    ) -> Result<Vec<LogLine>, SdkError> {
628        Ok(self
629            .list_logs(
630                project_id,
631                environment_id,
632                log_type,
633                env_type,
634                limit,
635                level,
636                service,
637                grep,
638                org_id,
639            )
640            .await?
641            .data)
642    }
643
644    /// `GET /resources`.
645    pub async fn list_resources(
646        &self,
647        kind: Option<&str>,
648        project_id: Option<&str>,
649        page: Option<&ListOptions>,
650        org_id: Option<&str>,
651    ) -> Result<ListResourcesResponse, SdkError> {
652        let mut query = page_query(page);
653        if let Some(v) = kind {
654            query.push(("kind", v.to_string()));
655        }
656        if let Some(v) = project_id {
657            query.push(("projectId", v.to_string()));
658        }
659        self.transport
660            .get_json_query::<ListResourcesResponse>("/resources", &query, &org_header(org_id))
661            .await
662    }
663
664    /// `GET /resources/{id}`.
665    pub async fn get_resource(
666        &self,
667        id: &str,
668        org_id: Option<&str>,
669    ) -> Result<Resource, SdkError> {
670        let path = format!("/resources/{}", urlencoding_encode(id));
671        self.transport
672            .get_json::<Resource>(&path, &org_header(org_id))
673            .await
674    }
675
676    /// `POST /resources`.
677    pub async fn create_resource(
678        &self,
679        kind: &str,
680        name: &str,
681        project_id: Option<&str>,
682        tier: Option<&str>,
683        storage_gb: Option<u32>,
684        org_id: Option<&str>,
685    ) -> Result<CreateResourceResponse, SdkError> {
686        let mut body = serde_json::json!({ "kind": kind, "name": name });
687        if let Some(v) = project_id {
688            body["projectId"] = Value::String(v.into());
689        }
690        if let Some(v) = tier {
691            body["tier"] = Value::String(v.into());
692        }
693        if let Some(v) = storage_gb {
694            body["storageGb"] = Value::Number(v.into());
695        }
696        self.transport
697            .post_json::<Value, CreateResourceResponse>("/resources", &body, &org_header(org_id))
698            .await
699    }
700
701    /// `DELETE /resources/{id}`.
702    pub async fn delete_resource(
703        &self,
704        id: &str,
705        org_id: Option<&str>,
706    ) -> Result<DeleteResourceResponse, SdkError> {
707        let path = format!("/resources/{}", urlencoding_encode(id));
708        self.transport
709            .delete_json::<DeleteResourceResponse>(&path, &org_header(org_id))
710            .await
711    }
712
713    /// `POST /resources/{id}/bindings`.
714    pub async fn bind_resource(
715        &self,
716        resource_id: &str,
717        environment_id: &str,
718        project_id: Option<&str>,
719        org_id: Option<&str>,
720    ) -> Result<BindResourceResponse, SdkError> {
721        let mut body = serde_json::json!({ "environmentId": environment_id });
722        if let Some(v) = project_id {
723            body["projectId"] = Value::String(v.into());
724        }
725        let path = format!(
726            "/resources/{}/bindings",
727            urlencoding_encode(resource_id)
728        );
729        self.transport
730            .post_json::<Value, BindResourceResponse>(&path, &body, &org_header(org_id))
731            .await
732    }
733
734    /// `POST /resources/{id}/branch`.
735
736    /// `POST /projects/{id}/storage`.
737
738    /// `GET /projects/{id}/storage`.
739
740    /// `GET /backups` or `GET /resources/{id}/backups`.
741
742    /// `POST /backups/trigger` or resource-scoped.
743
744    /// `POST /backups/{id}/restore`.
745
746    /// `GET /flags`.
747    pub async fn list_flags(
748        &self,
749        project_id: Option<&str>,
750        org_id: Option<&str>,
751    ) -> Result<ListFlagsResponse, SdkError> {
752        let mut query: Vec<(&str, String)> = Vec::new();
753        if let Some(v) = project_id {
754            query.push(("projectId", v.to_string()));
755        }
756        self.transport
757            .get_json_query::<ListFlagsResponse>("/flags", &query, &org_header(org_id))
758            .await
759    }
760
761    /// `POST /flags`.
762    pub async fn create_flag(
763        &self,
764        key: &str,
765        description: Option<&str>,
766        project_id: Option<&str>,
767        enabled: Option<bool>,
768        org_id: Option<&str>,
769    ) -> Result<CreateFlagResponse, SdkError> {
770        let mut body = serde_json::json!({ "key": key });
771        if let Some(v) = description {
772            body["description"] = Value::String(v.into());
773        }
774        if let Some(v) = project_id {
775            body["projectId"] = Value::String(v.into());
776        }
777        if let Some(v) = enabled {
778            body["enabled"] = Value::Bool(v);
779        }
780        self.transport
781            .post_json::<Value, CreateFlagResponse>("/flags", &body, &org_header(org_id))
782            .await
783    }
784
785    /// `POST /flags/{key}/toggle`.
786
787    /// `GET /projects/{id}/previews/{pr}/cost`.
788
789    /// `GET /projects/{id}/services`.
790    pub async fn list_project_services(
791        &self,
792        project_id: &str,
793        org_id: Option<&str>,
794    ) -> Result<ListProjectServicesResponse, SdkError> {
795        let path = format!("/projects/{}/services", urlencoding_encode(project_id));
796        self.transport
797            .get_json::<ListProjectServicesResponse>(&path, &org_header(org_id))
798            .await
799    }
800
801    /// Service rows only.
802    pub async fn list_project_service_items(
803        &self,
804        project_id: &str,
805        org_id: Option<&str>,
806    ) -> Result<Vec<ProjectService>, SdkError> {
807        Ok(self.list_project_services(project_id, org_id).await?.data)
808    }
809
810    /// `GET /projects/{id}/domains`.
811    pub async fn list_project_domains(
812        &self,
813        project_id: &str,
814        org_id: Option<&str>,
815    ) -> Result<ListProjectDomainsResponse, SdkError> {
816        let path = format!("/projects/{}/domains", urlencoding_encode(project_id));
817        // Live Management returns either a list envelope `{data:[…]}` or a bare
818        // domain array. Accept both so the CLI table path stays typed.
819        let (_status, mut body) = self
820            .transport
821            .raw_request(Method::GET, &path, None::<&Value>, &org_header(org_id))
822            .await?;
823        strip_json_nulls(&mut body);
824        if let Ok(list) = serde_json::from_value::<ListProjectDomainsResponse>(body.clone()) {
825            return Ok(list);
826        }
827        if let Ok(rows) = serde_json::from_value::<Vec<ProjectDomain>>(body.clone()) {
828            return Ok(ListProjectDomainsResponse {
829                object: "list".into(),
830                data: rows,
831                transport: None,
832            ..Default::default()
833            });
834        }
835        Err(SdkError::Decode(format!(
836            "unexpected domains payload: {body}"
837        )))
838    }
839
840    /// Domain rows only.
841    pub async fn list_project_domain_items(
842        &self,
843        project_id: &str,
844        org_id: Option<&str>,
845    ) -> Result<Vec<ProjectDomain>, SdkError> {
846        Ok(self.list_project_domains(project_id, org_id).await?.data)
847    }
848
849    /// Escape hatch: authenticated raw Management REST call.
850    pub async fn api(
851        &self,
852        method: Method,
853        path: &str,
854        body: Option<&Value>,
855        org_id: Option<&str>,
856    ) -> Result<(u16, Value), SdkError> {
857        self.api_with_headers(method, path, body, org_id, &[]).await
858    }
859
860    /// Escape hatch with extra headers (e.g. Idempotency-Key, fencing token).
861    pub async fn api_with_headers(
862        &self,
863        method: Method,
864        path: &str,
865        body: Option<&Value>,
866        org_id: Option<&str>,
867        extra_headers: &[(&str, &str)],
868    ) -> Result<(u16, Value), SdkError> {
869        let org = org_header(org_id);
870        let mut headers: Vec<(&str, &str)> = org;
871        headers.extend_from_slice(extra_headers);
872        self.transport
873            .raw_request(method, path, body, &headers)
874            .await
875    }
876}
877
878impl ManagementClientBuilder {
879    /// Override base URL (include `/v1`).
880    pub fn base_url(mut self, url: impl Into<String>) -> Self {
881        self.base_url = url.into();
882        self
883    }
884
885    /// Override timeout.
886    pub fn timeout(mut self, timeout: Duration) -> Self {
887        self.timeout = timeout;
888        self
889    }
890
891    /// Override retry.
892    pub fn retry(mut self, retry: RetryConfig) -> Self {
893        self.retry = retry;
894        self
895    }
896
897    /// Build client.
898    pub fn build(self) -> Result<ManagementClient, SdkError> {
899        let transport = Transport::new(TransportConfig {
900            base_url: self.base_url,
901            credential: Credential::bearer(self.token)?,
902            timeout: self.timeout,
903            retry: self.retry,
904        })?;
905        Ok(ManagementClient { transport })
906    }
907}
908
909fn page_query(page: Option<&ListOptions>) -> Vec<(&str, String)> {
910    let mut query: Vec<(&str, String)> = Vec::new();
911    if let Some(p) = page {
912        let pr = p.to_page_request();
913        if !pr.page_token.is_empty() {
914            query.push(("pageToken", pr.page_token));
915        }
916        if pr.page_size > 0 {
917            query.push(("pageSize", pr.page_size.to_string()));
918        }
919    }
920    query
921}
922
923/// Map CLI `--service` onto the Management deploy contract.
924/// Live `POST /projects/:id/deploy` accepts `serviceId` (UUID / `svc_` typeid)
925/// or `serviceName`. A product name sent as `serviceId` is `invalid_service_id`.
926fn management_deploy_service_field(service: &str) -> (&'static str, &str) {
927    let service = service.trim();
928    let looks_like_id = service.starts_with("svc_")
929        || (service.len() >= 32
930            && service
931                .chars()
932                .all(|c| c.is_ascii_hexdigit() || c == '-'));
933    if looks_like_id {
934        ("serviceId", service)
935    } else {
936        ("serviceName", service)
937    }
938}
939
940fn org_header(org_id: Option<&str>) -> Vec<(&str, &str)> {
941    // Dual-send all accepted org selectors. Server `resolve_org_for_projects`
942    // accepts x-org-id, x-organization-id, and x-preferred-org-id equivalently;
943    // clients send all three so partial consumers (Console preferred-only or
944    // native-only) keep working without re-auth.
945    match org_id {
946        Some(id) => vec![
947            ("x-preferred-org-id", id),
948            ("x-org-id", id),
949            ("x-organization-id", id),
950        ],
951        None => vec![],
952    }
953}
954
955fn urlencoding_encode(s: &str) -> String {
956    let mut out = String::with_capacity(s.len());
957    for b in s.bytes() {
958        match b {
959            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => {
960                out.push(b as char)
961            }
962            _ => out.push_str(&format!("%{b:02X}")),
963        }
964    }
965    out
966}
967
968
969#[cfg(test)]
970mod management_deploy_service_field_tests {
971    use super::management_deploy_service_field;
972
973    #[test]
974    fn product_name_uses_service_name() {
975        assert_eq!(
976            management_deploy_service_field("platform-migrator"),
977            ("serviceName", "platform-migrator")
978        );
979    }
980
981    #[test]
982    fn typeid_and_uuid_use_service_id() {
983        assert_eq!(
984            management_deploy_service_field("svc_0000000000e008000000001886"),
985            ("serviceId", "svc_0000000000e008000000001886")
986        );
987        assert_eq!(
988            management_deploy_service_field("00000000-0000-7000-8000-00000000a106"),
989            ("serviceId", "00000000-0000-7000-8000-00000000a106")
990        );
991    }
992}
993
994#[cfg(test)]
995mod org_header_tests {
996    use super::org_header;
997
998    #[test]
999    fn org_header_dual_sends_preferred_and_native_keys() {
1000        let h = org_header(Some("org_1"));
1001        let keys: Vec<&str> = h.iter().map(|(k, _)| *k).collect();
1002        assert!(keys.contains(&"x-preferred-org-id"));
1003        assert!(keys.contains(&"x-org-id"));
1004        assert!(keys.contains(&"x-organization-id"));
1005        assert!(org_header(None).is_empty());
1006    }
1007}
1008
1009#[cfg(test)]
1010mod domain_decode_tests {
1011    use super::*;
1012    use sylphx_sdk_core::strip_json_nulls;
1013
1014    #[test]
1015    fn live_domain_array_decodes() {
1016        let raw = r#"[{"apexDomain":"spiron.ai","createdAt":"2026-03-12T11:39:44.369365+00:00","email":null,"hostnames":[{"createdAt":"2026-03-12T11:39:44.369365+00:00","dnsStatus":"active","domainId":"9e5c2d14-91af-4e99-93db-3b867e51b7fc","hostname":"api.spiron.ai","id":"f379dd15-e75b-4aaf-9a23-666ae0fe3317","instruction":{"name":"api.spiron.ai","ttl":300,"type":"CNAME","value":"cname.sylphx.com"},"isPrimary":true,"lastCheckError":null,"redirectTo":null,"serviceId":"019e0740-34b6-7fdc-a1fd-9944f901864c","verifiedAt":"2026-03-12T11:39:44.369365+00:00"}],"id":"9e5c2d14-91af-4e99-93db-3b867e51b7fc"}]"#;
1017        let mut body: Value = serde_json::from_str(raw).unwrap();
1018        strip_json_nulls(&mut body);
1019        let rows: Result<Vec<ProjectDomain>, _> = serde_json::from_value(body);
1020        assert!(rows.is_ok(), "decode failed: {:?}", rows.err());
1021    }
1022}