Skip to main content

sylphx_apps_sdk_management/
lib.rs

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