diff --git a/SMG.md b/SMG.md index 6f31acfdb61..a46c055783e 100644 --- a/SMG.md +++ b/SMG.md @@ -50,13 +50,14 @@ What we carry on top of upstream. `git log --first-parent --oneline main..smg` i | Branch | Type | Upstream PR | State | Upstream files touched | | --- | --- | --- | --- | --- | -| `feat/members-table-search` | A | [CapSoftware/Cap#3919](https://github.com/CapSoftware/Cap/pull/3919) | In smg ([#4](https://github.com/Solomedia/cap/pull/4)), PR open upstream | `apps/web/app/(org)/dashboard/settings/organization/components/MembersCard.tsx`, `apps/web/content/docs/teams.mdx` | | `feat/preview-og-fallback-relative-redirect` | A | [CapSoftware/Cap#3963](https://github.com/CapSoftware/Cap/pull/3963) | In smg ([#10](https://github.com/Solomedia/cap/pull/10)), PR open upstream | `apps/web/app/api/video/preview/route.ts` | | `feat/share-unfurl-ai-summary` | A | Not opened (improvement, not a fix; propose later if wanted) | In smg ([#11](https://github.com/Solomedia/cap/pull/11)) | `apps/web/app/s/[videoId]/page.tsx`, `apps/web/lib/share-video-metadata.ts` | | `feat/google-account-linking` | A | [CapSoftware/Cap#3964](https://github.com/CapSoftware/Cap/pull/3964) | In smg ([#12](https://github.com/Solomedia/cap/pull/12)), PR open upstream | `packages/database/auth/auth-options.ts`, `apps/web/app/(org)/login/form.tsx` | Type A: upstream-able (`feat/*`). Type B: SMG-only (`internal/*`). States: `In smg`, `PR open`, `Merged upstream`, `Rejected upstream → SMG-only`. +Dropped: `feat/members-table-search` (2026-11-13). Upstream rewrote the members card with its own name and email search, so the 2026-11-13 sync takes upstream's version and [CapSoftware/Cap#3919](https://github.com/CapSoftware/Cap/pull/3919) was closed. The role and status filters and column sorting went with it. + ## Scope Only the server side: `apps/web`, `apps/media-server` and shared `packages/*`. The desktop app, CLI and Chrome extension stay on the official builds. diff --git a/apps/cli/skill/cap/SKILL.md b/apps/cli/skill/cap/SKILL.md index 68f6f60c095..321bb31c98e 100644 --- a/apps/cli/skill/cap/SKILL.md +++ b/apps/cli/skill/cap/SKILL.md @@ -67,6 +67,16 @@ and `cap jobs` for account, organization, sharing, storage, billing, analytics, operation workflows. Inspect each command's current arguments with `--help`; do not reconstruct them from this skill. +For a developer app, `cap developers transcripts create --file |--url --wait` turns audio or +video into text and `cap developers videos upload ` uploads a video. Over MCP these are +`developer_transcript_create` (with `file_path` or `url`), `developer_transcript_wait`, +`developer_transcript_get`, and `developer_video_upload`. A transcript spends the app's prepaid credits and +an uploaded video is billed daily for storage, so name the app, the file, and the price and get confirmation +first. An uploaded video comes back as `processing` until its playback files are ready. A `queued` or `processing` transcript is not done: +wait for `complete`. A `complete` transcript with empty text and a `wordCount` of 0 means the audio had no +speech; it is still billed for its length, while a transcript that fails is not charged. `INSUFFICIENT_CREDITS` means the app needs a top-up through +`cap developers credits purchase`. + Organization invites deliver email by default. Use `cap organizations invite add ... --no-email` only when the user explicitly wants a link-only invite, and report the returned `emailDelivery` state. diff --git a/apps/cli/src/account.rs b/apps/cli/src/account.rs index ffb5ca0510b..f3ab59b4d81 100644 --- a/apps/cli/src/account.rs +++ b/apps/cli/src/account.rs @@ -5,7 +5,9 @@ use reqwest::Method; use serde_json::{Map, Value, json}; use crate::{ - OutputFormat, agent_client, caps::AgentClient, confirmation, credentials, resolve_format, + OutputFormat, agent_client, + caps::{AgentApiError, AgentClient}, + confirmation, credentials, resolve_format, }; #[derive(Args)] @@ -100,7 +102,7 @@ struct AccountReferralsArgs { } impl AccountArgs { - pub async fn run(self, global_json: bool) -> Result<(), String> { + pub async fn run(self, global_json: bool) -> Result<(), AgentApiError> { match self.command { AccountCommands::Get(args) => agent_client::read("/me", global_json, args.format).await, AccountCommands::Update(args) => { @@ -124,7 +126,7 @@ impl AccountArgs { body.insert("defaultOrganizationId".to_string(), Value::Null); } if body.is_empty() { - return Err("Provide at least one account update".to_string()); + return Err("Provide at least one account update".to_string().into()); } confirmation::require(args.yes, "Update the Cap account")?; agent_client::mutate(Method::PATCH, "/me", &json!(body), global_json, args.format) @@ -157,23 +159,27 @@ impl AccountArgs { }, AccountCommands::Referrals(args) => { confirmation::require(args.yes, "Open the Cap referral portal")?; - let client = AgentClient::from_credentials().map_err(|error| error.to_string())?; + let client = AgentClient::from_credentials()?; let value = client .mutate_json_confirmed(Method::POST, "/me/referrals", &json!({})) - .await - .map_err(|error| error.to_string())?; + .await?; agent_client::open_browser_action(&value, args.no_open); - agent_client::print_value(&value, resolve_format(global_json, args.format)) + Ok(agent_client::print_value( + &value, + resolve_format(global_json, args.format), + )?) } AccountCommands::SignOutAll(args) => { confirmation::require(args.yes, "Sign out every Cap device and agent")?; - let client = AgentClient::from_credentials().map_err(|error| error.to_string())?; + let client = AgentClient::from_credentials()?; let value = client .mutate_json_confirmed(Method::POST, "/me/sign-out-all", &json!({})) - .await - .map_err(|error| error.to_string())?; + .await?; credentials::delete_agent()?; - agent_client::print_value(&value, resolve_format(global_json, args.format)) + Ok(agent_client::print_value( + &value, + resolve_format(global_json, args.format), + )?) } } } diff --git a/apps/cli/src/agent_client.rs b/apps/cli/src/agent_client.rs index 6ed1a4dbe77..a12b45dad3c 100644 --- a/apps/cli/src/agent_client.rs +++ b/apps/cli/src/agent_client.rs @@ -5,7 +5,11 @@ use clap::ValueEnum; use reqwest::Method; use serde_json::{Value, json}; -use crate::{OutputFormat, caps::AgentClient, resolve_format, write_json}; +use crate::{ + OutputFormat, + caps::{AgentApiError, AgentClient}, + resolve_format, write_json, +}; pub fn print_value(value: &Value, format: OutputFormat) -> Result<(), String> { match format { @@ -20,13 +24,14 @@ pub fn print_value(value: &Value, format: OutputFormat) -> Result<(), String> { } } -pub async fn read(path: &str, global_json: bool, format: OutputFormat) -> Result<(), String> { - let client = AgentClient::from_credentials().map_err(|error| error.to_string())?; - let value = client - .get_json(path) - .await - .map_err(|error| error.to_string())?; - print_value(&value, resolve_format(global_json, format)) +pub async fn read( + path: &str, + global_json: bool, + format: OutputFormat, +) -> Result<(), AgentApiError> { + let client = AgentClient::from_credentials()?; + let value = client.get_json(path).await?; + Ok(print_value(&value, resolve_format(global_json, format))?) } pub async fn mutate( @@ -35,13 +40,10 @@ pub async fn mutate( body: &Value, global_json: bool, format: OutputFormat, -) -> Result<(), String> { - let client = AgentClient::from_credentials().map_err(|error| error.to_string())?; - let value = client - .mutate_json(method, path, body) - .await - .map_err(|error| error.to_string())?; - print_value(&value, resolve_format(global_json, format)) +) -> Result<(), AgentApiError> { + let client = AgentClient::from_credentials()?; + let value = client.mutate_json(method, path, body).await?; + Ok(print_value(&value, resolve_format(global_json, format))?) } pub async fn mutate_confirmed( @@ -50,13 +52,10 @@ pub async fn mutate_confirmed( body: &Value, global_json: bool, format: OutputFormat, -) -> Result<(), String> { - let client = AgentClient::from_credentials().map_err(|error| error.to_string())?; - let value = client - .mutate_json_confirmed(method, path, body) - .await - .map_err(|error| error.to_string())?; - print_value(&value, resolve_format(global_json, format)) +) -> Result<(), AgentApiError> { + let client = AgentClient::from_credentials()?; + let value = client.mutate_json_confirmed(method, path, body).await?; + Ok(print_value(&value, resolve_format(global_json, format))?) } pub fn query(parameters: &[(&str, Option)]) -> String { diff --git a/apps/cli/src/analytics.rs b/apps/cli/src/analytics.rs index 0976f364718..a1335dff54a 100644 --- a/apps/cli/src/analytics.rs +++ b/apps/cli/src/analytics.rs @@ -1,6 +1,6 @@ use clap::{Args, ValueEnum}; -use crate::{OutputFormat, agent_client}; +use crate::{OutputFormat, agent_client, caps::AgentApiError}; #[derive(Clone, Copy, ValueEnum)] enum AnalyticsRange { @@ -36,7 +36,7 @@ pub struct AnalyticsArgs { } impl AnalyticsArgs { - pub async fn run(self, global_json: bool) -> Result<(), String> { + pub async fn run(self, global_json: bool) -> Result<(), AgentApiError> { let query = agent_client::query(&[ ("organizationId", Some(self.organization)), ("spaceId", self.space), diff --git a/apps/cli/src/caps.rs b/apps/cli/src/caps.rs index 1ace9536eac..47f0a9b5abb 100644 --- a/apps/cli/src/caps.rs +++ b/apps/cli/src/caps.rs @@ -566,7 +566,7 @@ struct SpaceShareRemoveArgs { format: OutputFormat, } -#[derive(Debug, Deserialize, Serialize)] +#[derive(Debug, Default, Deserialize, Serialize)] #[serde(rename_all = "camelCase")] pub struct AgentApiError { pub code: String, @@ -574,6 +574,16 @@ pub struct AgentApiError { pub retryable: bool, pub retry_after_ms: Option, pub request_id: Option, + #[serde(flatten)] + pub context: Box, +} + +#[derive(Debug, Default, Deserialize, Serialize)] +pub struct AgentErrorContext { + #[serde(default, skip_serializing_if = "Option::is_none")] + pub hint: Option, + #[serde(flatten, skip_deserializing)] + pub details: serde_json::Map, } impl std::fmt::Display for AgentApiError { @@ -584,15 +594,70 @@ impl std::fmt::Display for AgentApiError { impl std::error::Error for AgentApiError {} +impl From for AgentApiError { + fn from(message: String) -> Self { + let first_line = message.lines().next().unwrap_or_default(); + match first_line.split_once(": ") { + Some((code, text)) + if !code.is_empty() + && code + .bytes() + .all(|byte| byte.is_ascii_uppercase() || byte == b'_') => + { + Self::local(code, text) + } + _ => Self::local("COMMAND_FAILED", first_line), + } + } +} + impl AgentApiError { - fn local(code: &str, message: impl Into) -> Self { + pub fn local(code: &str, message: impl Into) -> Self { Self { code: code.to_string(), message: message.into(), - retryable: false, - retry_after_ms: None, - request_id: None, + ..Default::default() + } + } + + pub fn with_hint(mut self, hint: impl Into) -> Self { + self.context.hint = Some(hint.into()); + self + } + + pub fn with_detail(mut self, key: &str, value: impl Into) -> Self { + self.context.details.insert(key.to_string(), value.into()); + self + } + + pub fn describe(&self) -> String { + let mut text = self.to_string(); + for (key, value) in &self.context.details { + let value = match value { + Value::String(value) => value.clone(), + other => other.to_string(), + }; + text.push_str(&format!("\n{key}: {value}")); + } + if let Some(hint) = &self.context.hint + && !self.message.contains(hint.as_str()) + { + text.push_str(&format!("\nhint: {hint}")); } + text + } + + pub fn emit_json(&self) { + #[derive(Serialize)] + struct JsonError<'a> { + error: &'a str, + #[serde(flatten)] + details: &'a AgentApiError, + } + let _ = write_json(&JsonError { + error: &self.message, + details: self, + }); } } @@ -708,7 +773,11 @@ impl AgentClient { retryable: true, retry_after_ms: Some(500), request_id: None, - }; + ..Default::default() + } + .with_hint( + "Cap could not be reached. Check the network and CAP_SERVER_URL, then retry.", + ); if attempt >= 2 { return Err(error); } @@ -1147,18 +1216,9 @@ impl CapsArgs { if let Err(error) = &result && output_format == OutputFormat::Json { - #[derive(Serialize)] - struct JsonError<'a> { - error: &'a str, - #[serde(flatten)] - details: &'a AgentApiError, - } - let _ = write_json(&JsonError { - error: &error.message, - details: error, - }); + error.emit_json(); } - result.map_err(|error| error.to_string()) + result.map_err(|error| error.describe()) } async fn run_inner(self, global_json: bool) -> Result<(), AgentApiError> { @@ -1247,6 +1307,7 @@ impl CapsArgs { .get("requestId") .and_then(Value::as_str) .map(str::to_string), + ..Default::default() }); } let base = 500_u64.saturating_mul(1_u64 << attempt.min(4)); diff --git a/apps/cli/src/developer_media.rs b/apps/cli/src/developer_media.rs new file mode 100644 index 00000000000..9b9a5ea0f36 --- /dev/null +++ b/apps/cli/src/developer_media.rs @@ -0,0 +1,957 @@ +use std::{path::Path, time::Duration}; + +use reqwest::Method; +use serde_json::{Map, Value, json}; +use tokio_util::io::ReaderStream; + +use crate::{ + caps::{AgentApiError, AgentClient, opaque_id}, + upload, +}; + +pub const TRANSCRIPT_MAX_FILE_BYTES: u64 = 2 * 1024 * 1024 * 1024; +pub const VIDEO_MAX_FILE_BYTES: u64 = 5 * 1024 * 1024 * 1024; +pub const DEFAULT_WAIT_SECONDS: u64 = 900; +pub const MAX_WAIT_SECONDS: u64 = 86_400; + +#[derive(Default)] +pub struct Created(std::sync::Mutex>); + +impl Created { + pub fn record(&self, id: &str, status: &str) { + if let Ok(mut created) = self.0.lock() { + *created = Some((id.to_string(), status.to_string())); + } + } + + pub fn get(&self) -> Option<(String, String)> { + self.0.lock().ok().and_then(|created| created.clone()) + } + + fn record_from(&self, value: &Value, object: &str) { + if let (Some(id), Some(status)) = ( + value_text(value, object, "id"), + value_text(value, object, "status"), + ) { + self.record(id, status); + } + } +} + +#[derive(Default)] +pub struct TranscriptOptions { + pub name: Option, + pub language: Option, + pub user_id: Option, +} + +fn invalid(message: impl Into) -> AgentApiError { + AgentApiError { + code: "INVALID_REQUEST".to_string(), + message: message.into(), + retryable: false, + retry_after_ms: None, + request_id: None, + ..Default::default() + } +} + +fn file_name(path: &Path) -> Result { + path.file_name() + .and_then(|value| value.to_str()) + .map(str::to_string) + .ok_or_else(|| invalid("File name is invalid")) +} + +async fn file_length(path: &Path, max_bytes: u64, limit: &str) -> Result { + let metadata = tokio::fs::metadata(path) + .await + .map_err(|error| invalid(format!("Could not read {}: {error}", path.display())))?; + if !metadata.is_file() { + return Err(invalid(format!("{} is not a file", path.display()))); + } + if metadata.len() == 0 { + return Err(invalid(format!("{} is empty", path.display()))); + } + if metadata.len() > max_bytes { + return Err(invalid(format!( + "{} is larger than the {limit} limit", + path.display() + ))); + } + Ok(metadata.len()) +} + +fn ensure_audio_stream(path: &Path) -> Result<(), AgentApiError> { + ffmpeg::init().map_err(|error| invalid(format!("Failed to initialise FFmpeg: {error}")))?; + let input = ffmpeg::format::input(path) + .map_err(|_| invalid(format!("{} is not an audio or video file", path.display())))?; + if input.streams().best(ffmpeg::media::Type::Audio).is_none() { + return Err(invalid(format!("{} has no audio track", path.display()))); + } + Ok(()) +} + +fn options_body(options: &TranscriptOptions) -> Map { + let mut body = Map::new(); + for (key, value) in [ + ("name", &options.name), + ("language", &options.language), + ("userId", &options.user_id), + ] { + if let Some(value) = value { + body.insert(key.to_string(), Value::String(value.clone())); + } + } + body +} + +pub fn transcript_file_body( + file_name: &str, + content_length: u64, + options: &TranscriptOptions, +) -> Value { + let mut body = options_body(options); + body.insert("fileName".to_string(), Value::String(file_name.to_string())); + body.insert("contentLength".to_string(), Value::from(content_length)); + Value::Object(body) +} + +pub fn transcript_url_body(url: &str, options: &TranscriptOptions) -> Value { + let mut body = options_body(options); + body.insert("url".to_string(), Value::String(url.to_string())); + Value::Object(body) +} + +pub fn without_upload_target(mut value: Value) -> Value { + if let Some(object) = value.as_object_mut() { + object.remove("upload"); + } + value +} + +async fn put_file(target: &Value, path: &Path, content_length: u64) -> Result<(), AgentApiError> { + let url = target + .get("url") + .and_then(Value::as_str) + .ok_or_else(|| invalid("Cap returned an upload target without a URL"))?; + if target.get("method").and_then(Value::as_str) != Some("PUT") { + return Err(invalid("Cap returned an unsupported upload target")); + } + let file = tokio::fs::File::open(path) + .await + .map_err(|error| invalid(format!("Could not open {}: {error}", path.display())))?; + let mut request = reqwest::Client::new() + .put(url) + .header(reqwest::header::CONTENT_LENGTH, content_length) + .body(reqwest::Body::wrap_stream(ReaderStream::new(file))); + if let Some(headers) = target.get("headers").and_then(Value::as_object) { + for (name, value) in headers { + if name.eq_ignore_ascii_case("content-length") { + continue; + } + if let Some(value) = value.as_str() { + request = request.header(name, value); + } + } + } + let response = request.send().await.map_err(|error| AgentApiError { + code: "TEMPORARY_UNAVAILABLE".to_string(), + message: format!("File upload failed: {}", error.without_url()), + retryable: true, + retry_after_ms: Some(1_000), + request_id: None, + ..Default::default() + })?; + if response.status().is_success() { + Ok(()) + } else { + Err(AgentApiError { + code: "TEMPORARY_UNAVAILABLE".to_string(), + message: format!("Storage rejected the upload ({})", response.status()), + retryable: false, + retry_after_ms: None, + request_id: None, + ..Default::default() + }) + } +} + +fn transcript_id(value: &Value) -> Result { + value + .get("transcript") + .and_then(|transcript| transcript.get("id")) + .and_then(Value::as_str) + .map(str::to_string) + .ok_or_else(|| invalid("Cap returned a transcript without an ID")) +} + +pub async fn create_transcript_from_file( + client: &AgentClient, + app_id: &str, + path: &Path, + options: &TranscriptOptions, + created_resource: &Created, +) -> Result { + let app_id = opaque_id(app_id, "Developer app ID")?; + let content_length = file_length(path, TRANSCRIPT_MAX_FILE_BYTES, "2 GB").await?; + ensure_audio_stream(path)?; + let created = client + .mutate_json_confirmed( + Method::POST, + &format!("/developer/apps/{app_id}/transcripts"), + &transcript_file_body(&file_name(path)?, content_length, options), + ) + .await?; + let id = transcript_id(&created)?; + created_resource.record(&id, "uploading"); + let started = async { + let target = created + .get("upload") + .filter(|target| !target.is_null()) + .ok_or_else(|| invalid("Cap did not return an upload target"))?; + put_file(target, path, content_length).await?; + client + .mutate_json_confirmed( + Method::POST, + &format!("/developer/apps/{app_id}/transcripts/{id}/start"), + &json!({}), + ) + .await + }; + let started = started + .await + .map_err(|error| error.with_detail("transcriptId", id.as_str()))?; + created_resource.record_from(&started, "transcript"); + Ok(started) +} + +pub async fn create_transcript_from_url( + client: &AgentClient, + app_id: &str, + url: &str, + options: &TranscriptOptions, + created_resource: &Created, +) -> Result { + let app_id = opaque_id(app_id, "Developer app ID")?; + let parsed = url::Url::parse(url).map_err(|_| invalid("The URL is not valid"))?; + if !matches!(parsed.scheme(), "http" | "https") { + return Err(invalid("The URL must start with http:// or https://")); + } + let created = client + .mutate_json_confirmed( + Method::POST, + &format!("/developer/apps/{app_id}/transcripts"), + &transcript_url_body(url, options), + ) + .await + .map(without_upload_target)?; + created_resource.record_from(&created, "transcript"); + Ok(created) +} + +pub fn transcript_path( + app_id: &str, + transcript_id: &str, + segments: bool, +) -> Result { + let app_id = opaque_id(app_id, "Developer app ID")?; + let transcript_id = opaque_id(transcript_id, "Developer transcript ID")?; + let query = if segments { "?include=segments" } else { "" }; + Ok(format!( + "/developer/apps/{app_id}/transcripts/{transcript_id}{query}" + )) +} + +pub fn transcript_status(value: &Value) -> Option<&str> { + value + .get("transcript") + .and_then(|transcript| transcript.get("status")) + .and_then(Value::as_str) +} + +fn value_text<'a>(value: &'a Value, object: &str, field: &str) -> Option<&'a str> { + value + .get(object) + .and_then(|object| object.get(field)) + .and_then(Value::as_str) +} + +fn request_id(value: &Value) -> Option { + value + .get("requestId") + .and_then(Value::as_str) + .map(str::to_string) +} + +pub fn transcript_failure(value: &Value, transcript_id: &str) -> AgentApiError { + AgentApiError { + code: "TRANSCRIPT_FAILED".to_string(), + message: format!( + "{} ({})", + value_text(value, "transcript", "errorMessage") + .unwrap_or("The transcript could not be created"), + value_text(value, "transcript", "errorCode").unwrap_or("transcription_failed") + ), + retryable: false, + retry_after_ms: None, + request_id: request_id(value), + ..Default::default() + } + .with_detail("transcriptId", transcript_id) + .with_detail("status", "error") + .with_hint( + "A failed transcript is not charged. Remove it with `cap developers transcripts delete`.", + ) +} + +pub fn validate_wait_seconds(timeout_seconds: Option) -> Result { + let timeout = timeout_seconds.unwrap_or(DEFAULT_WAIT_SECONDS); + if timeout == 0 || timeout > MAX_WAIT_SECONDS { + return Err(invalid("timeoutSeconds must be between 1 and 86400")); + } + Ok(timeout) +} + +fn wait_delay(attempt: u32) -> Duration { + let delay = 500_u64.saturating_mul(1_u64 << attempt.min(4)); + Duration::from_millis(delay.min(5_000)) +} + +enum WaitProgress { + Done, + Pending(String), +} + +struct Wait<'a> { + path: String, + resource: &'a str, + id_field: &'a str, + id: &'a str, + timeout_seconds: u64, + resume: String, +} + +impl Wait<'_> { + fn timed_out(&self, status: Option<&str>, request_id: Option) -> AgentApiError { + let error = AgentApiError { + code: "NOT_READY".to_string(), + message: format!( + "Timed out after {} seconds waiting for the {}", + self.timeout_seconds, self.resource + ), + retryable: true, + retry_after_ms: Some(2_000), + request_id, + ..Default::default() + } + .with_detail(self.id_field, self.id) + .with_hint(format!("Keep waiting with `{}`.", self.resume)); + match status { + Some(status) => error.with_detail("status", status), + None => error, + } + } + + async fn run( + &self, + client: &AgentClient, + progress: impl Fn(&Value) -> Result, + ) -> Result { + let deadline = tokio::time::Instant::now() + Duration::from_secs(self.timeout_seconds); + let mut status: Option = None; + let mut last_request_id = None; + let mut attempt = 0_u32; + loop { + let fetched = tokio::time::timeout_at(deadline, client.get_json(&self.path)).await; + let Ok(fetched) = fetched else { + return Err(self.timed_out(status.as_deref(), last_request_id)); + }; + let value = fetched.map_err(|error| error.with_detail(self.id_field, self.id))?; + match progress(&value).map_err(|error| error.with_detail(self.id_field, self.id))? { + WaitProgress::Done => return Ok(value), + WaitProgress::Pending(current) => status = Some(current), + } + last_request_id = request_id(&value); + let wake = tokio::time::Instant::now() + wait_delay(attempt); + if wake >= deadline { + tokio::time::sleep_until(deadline).await; + return Err(self.timed_out(status.as_deref(), last_request_id)); + } + tokio::time::sleep_until(wake).await; + attempt = attempt.saturating_add(1); + } + } +} + +pub async fn wait_for_transcript( + client: &AgentClient, + app_id: &str, + transcript_id: &str, + timeout_seconds: u64, +) -> Result { + let wait = Wait { + path: transcript_path(app_id, transcript_id, false)?, + resource: "transcript", + id_field: "transcriptId", + id: transcript_id, + timeout_seconds, + resume: format!("cap developers transcripts wait {app_id} {transcript_id}"), + }; + wait.run(client, |value| match transcript_status(value) { + Some("complete") => Ok(WaitProgress::Done), + Some("error") => Err(transcript_failure(value, transcript_id)), + Some("uploading") => Err(AgentApiError::local( + "NOT_READY", + "The transcript is still waiting for its file", + ) + .with_detail("status", "uploading")), + Some(status @ ("queued" | "processing")) => Ok(WaitProgress::Pending(status.to_string())), + _ => Err(invalid("Cap returned an invalid transcript status")), + }) + .await +} + +pub fn video_path(app_id: &str, video_id: &str) -> Result { + let app_id = opaque_id(app_id, "Developer app ID")?; + let video_id = opaque_id(video_id, "Developer video ID")?; + Ok(format!("/developer/apps/{app_id}/videos/{video_id}")) +} + +pub fn video_status(value: &Value) -> Option<&str> { + value_text(value, "video", "status") +} + +pub fn video_failure(value: &Value, video_id: &str) -> AgentApiError { + AgentApiError { + code: "VIDEO_FAILED".to_string(), + message: value_text(value, "video", "errorReason") + .unwrap_or("The video could not be processed") + .to_string(), + retryable: false, + retry_after_ms: None, + request_id: request_id(value), + ..Default::default() + } + .with_detail("videoId", video_id) + .with_detail("status", "errored") + .with_hint("Remove it with `cap developers videos delete`, then upload the file again.") +} + +pub async fn get_video( + client: &AgentClient, + app_id: &str, + video_id: &str, +) -> Result { + client.get_json(&video_path(app_id, video_id)?).await +} + +pub async fn wait_for_video( + client: &AgentClient, + app_id: &str, + video_id: &str, + timeout_seconds: u64, +) -> Result { + let wait = Wait { + path: video_path(app_id, video_id)?, + resource: "video", + id_field: "videoId", + id: video_id, + timeout_seconds, + resume: format!("cap developers videos wait {app_id} {video_id}"), + }; + wait.run(client, |value| match video_status(value) { + Some("ready") => Ok(WaitProgress::Done), + Some("errored") => Err(video_failure(value, video_id)), + Some("uploading") => Err(AgentApiError::local( + "NOT_READY", + "The video is still waiting for its file", + ) + .with_detail("status", "uploading") + .with_hint("Upload the file with `cap developers videos upload`.")), + Some("processing") => Ok(WaitProgress::Pending("processing".to_string())), + _ => Err(invalid("Cap returned an invalid video status")), + }) + .await +} + +pub fn created_id(value: &Value, object: &str) -> Result { + value_text(value, object, "id") + .map(str::to_string) + .ok_or_else(|| invalid(format!("Cap returned a {object} without an ID"))) +} + +async fn app_context(client: &AgentClient, app_id: &str) -> Result { + let app_id = opaque_id(app_id, "Developer app ID")?; + client + .get_json(&format!("/developer/apps/{app_id}/context")) + .await +} + +fn preview(action: &str, effect: &str, target: Value) -> Value { + json!({ + "dryRun": true, + "action": action, + "effect": effect, + "target": target, + }) +} + +fn active_keys(context: &Value) -> Vec { + context + .get("keys") + .and_then(Value::as_array) + .map(|keys| { + keys.iter() + .filter(|key| key.get("revokedAt").is_none_or(Value::is_null)) + .map(|key| { + json!({ + "keyType": key.get("keyType"), + "keyPrefix": key.get("keyPrefix"), + }) + }) + .collect() + }) + .unwrap_or_default() +} + +fn app_target(context: &Value) -> Value { + json!({ + "appId": context.pointer("/app/id"), + "name": context.pointer("/app/name"), + "environment": context.pointer("/app/environment"), + "videoCount": context.pointer("/usage/videoCount"), + "storageMinutes": context.pointer("/usage/storageMinutes"), + "domainCount": context.get("domains").and_then(Value::as_array).map(Vec::len), + "activeKeys": active_keys(context), + }) +} + +pub async fn preview_app_delete( + client: &AgentClient, + app_id: &str, +) -> Result { + let context = app_context(client, app_id).await?; + Ok(preview( + "delete_developer_app", + "Deletes the app, revokes its keys and stops playback of its videos. Unused credit is lost.", + app_target(&context), + )) +} + +pub async fn preview_key_rotation( + client: &AgentClient, + app_id: &str, +) -> Result { + let context = app_context(client, app_id).await?; + Ok(preview( + "rotate_developer_keys", + "Revokes the active keys at once and prints a new public and secret key one time.", + app_target(&context), + )) +} + +pub fn domain_entry<'a>(context: &'a Value, domain: &str) -> Option<&'a Value> { + let wanted = domain.trim_end_matches('/'); + context + .get("domains") + .and_then(Value::as_array)? + .iter() + .find(|entry| { + ["id", "domain"].iter().any(|field| { + entry + .get(field) + .and_then(Value::as_str) + .is_some_and(|value| value.eq_ignore_ascii_case(wanted)) + }) + }) +} + +pub async fn resolve_domain( + client: &AgentClient, + app_id: &str, + domain: &str, +) -> Result { + let context = app_context(client, app_id).await?; + domain_entry(&context, domain).cloned().ok_or_else(|| { + AgentApiError::local("NOT_FOUND", "Domain not found in this developer app").with_hint( + format!("Run `cap developers get {app_id}` to list the app's domains and their ids."), + ) + }) +} + +pub fn domain_removal_preview(app_id: &str, domain: &Value) -> Value { + preview( + "remove_developer_domain", + "Requests from this origin are refused once it is removed.", + json!({ + "appId": app_id, + "domainId": domain.get("id"), + "domain": domain.get("domain"), + }), + ) +} + +pub async fn preview_video_delete( + client: &AgentClient, + app_id: &str, + video_id: &str, +) -> Result { + let value = client + .get_json(&format!("{}?restart=false", video_path(app_id, video_id)?)) + .await?; + Ok(preview( + "delete_developer_video", + "Deletes the video and stops its playback, share and embed links.", + json!({ + "appId": app_id, + "videoId": value.pointer("/video/id"), + "name": value.pointer("/video/name"), + "status": value.pointer("/video/status"), + "durationSeconds": value.pointer("/video/durationSeconds"), + "shareUrl": value.pointer("/video/shareUrl"), + }), + )) +} + +pub async fn preview_transcript_delete( + client: &AgentClient, + app_id: &str, + transcript_id: &str, +) -> Result { + let value = client + .get_json(&transcript_path(app_id, transcript_id, false)?) + .await?; + Ok(preview( + "delete_developer_transcript", + "Deletes the transcript and its stored text. The charge is not refunded.", + json!({ + "appId": app_id, + "transcriptId": value.pointer("/transcript/id"), + "name": value.pointer("/transcript/name"), + "status": value.pointer("/transcript/status"), + "durationSeconds": value.pointer("/transcript/durationSeconds"), + }), + )) +} + +pub async fn usage(client: &AgentClient, app_id: &str) -> Result { + let context = app_context(client, app_id).await?; + let field = |name: &str| context.get(name).cloned().unwrap_or(Value::Null); + Ok(json!({ + "appId": context.pointer("/app/id"), + "name": context.pointer("/app/name"), + "usage": field("usage"), + "credits": field("credits"), + "billing": field("billing"), + "billingHint": field("billingHint"), + "requestId": field("requestId"), + })) +} + +pub const NO_SPEECH_NOTE: &str = + "No speech was found, so the transcript is empty. It was billed for its audio length."; + +pub fn transcript_has_no_speech(value: &Value) -> bool { + transcript_status(value) == Some("complete") + && value + .get("transcript") + .and_then(|transcript| transcript.get("wordCount")) + .and_then(Value::as_u64) + == Some(0) + && value + .get("text") + .and_then(Value::as_str) + .unwrap_or_default() + .trim() + .is_empty() +} + +pub fn video_create_body( + file_name: &str, + content_length: u64, + name: Option<&str>, + user_id: Option<&str>, +) -> Value { + let mut body = Map::new(); + body.insert("fileName".to_string(), Value::String(file_name.to_string())); + body.insert("contentLength".to_string(), Value::from(content_length)); + if let Some(name) = name { + body.insert("name".to_string(), Value::String(name.to_string())); + } + if let Some(user_id) = user_id { + body.insert("userId".to_string(), Value::String(user_id.to_string())); + } + Value::Object(body) +} + +pub async fn upload_video( + client: &AgentClient, + app_id: &str, + path: &Path, + name: Option<&str>, + user_id: Option<&str>, + created_resource: &Created, +) -> Result { + let app_id = opaque_id(app_id, "Developer app ID")?; + let content_length = file_length(path, VIDEO_MAX_FILE_BYTES, "5 GB").await?; + let meta = upload::probe_video_meta(path).map_err(invalid)?; + if meta.duration_in_secs <= 0.0 { + return Err(invalid(format!( + "Could not read the duration of {}", + path.display() + ))); + } + let created = client + .mutate_json_confirmed( + Method::POST, + &format!("/developer/apps/{app_id}/videos"), + &video_create_body(&file_name(path)?, content_length, name, user_id), + ) + .await?; + let video_id = created + .get("video") + .and_then(|video| video.get("id")) + .and_then(Value::as_str) + .ok_or_else(|| invalid("Cap returned a video without an ID"))? + .to_string(); + created_resource.record(&video_id, "uploading"); + let completed = async { + let target = created + .get("upload") + .ok_or_else(|| invalid("Cap did not return an upload target"))?; + put_file(target, path, content_length).await?; + client + .mutate_json_confirmed( + Method::POST, + &format!("/developer/apps/{app_id}/videos/{video_id}/complete"), + &json!({ + "durationSeconds": meta.duration_in_secs, + "width": meta.width, + "height": meta.height, + "fps": meta.fps, + }), + ) + .await + }; + let completed = completed + .await + .map_err(|error| error.with_detail("videoId", video_id.as_str()))?; + created_resource.record_from(&completed, "video"); + Ok(completed) +} + +#[cfg(test)] +mod tests { + use serde_json::json; + + use super::{ + TranscriptOptions, transcript_failure, transcript_file_body, transcript_has_no_speech, + transcript_path, transcript_status, transcript_url_body, validate_wait_seconds, + video_create_body, without_upload_target, + }; + + #[test] + fn transcript_bodies_only_send_requested_options() { + let bare = transcript_url_body("https://example.com/a.mp3", &TranscriptOptions::default()); + assert_eq!(bare, json!({ "url": "https://example.com/a.mp3" })); + + let options = TranscriptOptions { + name: Some("Standup".to_string()), + language: Some("en".to_string()), + user_id: Some("user-1".to_string()), + }; + assert_eq!( + transcript_file_body("standup.m4a", 1_024, &options), + json!({ + "fileName": "standup.m4a", + "contentLength": 1_024, + "name": "Standup", + "language": "en", + "userId": "user-1", + }) + ); + } + + #[test] + fn upload_targets_never_leave_the_process() { + let value = without_upload_target(json!({ + "transcript": { "id": "t1" }, + "upload": { "method": "PUT", "url": "https://storage.example/signed" }, + "requestId": "r1", + })); + assert!(value.get("upload").is_none()); + assert_eq!(value["transcript"]["id"], "t1"); + } + + #[test] + fn transcript_paths_reject_unsafe_identifiers() { + assert_eq!( + transcript_path("app_1", "tr-1", true).unwrap(), + "/developer/apps/app_1/transcripts/tr-1?include=segments" + ); + assert!(transcript_path("app/1", "tr-1", false).is_err()); + assert!(transcript_path("app_1", "../secrets", false).is_err()); + } + + #[test] + fn failed_transcripts_report_the_server_reason() { + let value = json!({ + "transcript": { + "status": "error", + "errorCode": "insufficient_credits", + "errorMessage": "The credit balance could not cover this transcript.", + }, + "requestId": "r1", + }); + assert_eq!(transcript_status(&value), Some("error")); + let error = transcript_failure(&value, "tr-1"); + assert_eq!(error.code, "TRANSCRIPT_FAILED"); + assert!(error.message.contains("insufficient_credits")); + assert_eq!(error.request_id.as_deref(), Some("r1")); + } + + #[test] + fn only_a_complete_transcript_without_words_counts_as_no_speech() { + let no_speech = |status: &str, words: serde_json::Value| { + transcript_has_no_speech(&json!({ + "transcript": { "status": status, "wordCount": words }, + "text": "", + })) + }; + assert!(no_speech("complete", json!(0))); + assert!(!no_speech("complete", json!(12))); + assert!(!no_speech("complete", json!(null))); + assert!(!no_speech("error", json!(0))); + assert!(!no_speech("processing", json!(null))); + assert!(!transcript_has_no_speech(&json!({ "text": "" }))); + assert!(!transcript_has_no_speech(&json!({ + "transcript": { "status": "complete", "wordCount": 0 }, + "text": "hello there", + }))); + assert!(transcript_has_no_speech(&json!({ + "transcript": { "status": "complete", "wordCount": 0 }, + }))); + } + + #[test] + fn wait_timeouts_are_bounded() { + assert_eq!(validate_wait_seconds(None).unwrap(), 900); + assert_eq!(validate_wait_seconds(Some(30)).unwrap(), 30); + assert!(validate_wait_seconds(Some(0)).is_err()); + assert!(validate_wait_seconds(Some(86_401)).is_err()); + } + + #[test] + fn video_bodies_only_send_requested_fields() { + assert_eq!( + video_create_body("demo.mp4", 2_048, None, None), + json!({ "fileName": "demo.mp4", "contentLength": 2_048 }) + ); + assert_eq!( + video_create_body("demo.mp4", 2_048, Some("Demo"), Some("user-1")), + json!({ + "fileName": "demo.mp4", + "contentLength": 2_048, + "name": "Demo", + "userId": "user-1", + }) + ); + } + + #[test] + fn video_paths_accept_ids_that_begin_with_a_dash() { + assert_eq!( + super::video_path("app_1", "-Vid0000000dash").unwrap(), + "/developer/apps/app_1/videos/-Vid0000000dash" + ); + assert_eq!( + transcript_path("app_1", "-EDG5hrbuAwXDNY", false).unwrap(), + "/developer/apps/app_1/transcripts/-EDG5hrbuAwXDNY" + ); + assert!(super::video_path("app_1", "../video").is_err()); + } + + #[test] + fn failed_waits_keep_the_id_they_waited_on() { + let transcript = transcript_failure( + &json!({ + "transcript": { + "status": "error", + "errorCode": "source_unreachable", + "errorMessage": "The URL answered 404", + }, + "requestId": "r1", + }), + "-EDG5hrbuAwXDNY", + ); + assert_eq!( + transcript.context.details["transcriptId"], + "-EDG5hrbuAwXDNY" + ); + assert_eq!(transcript.context.details["status"], "error"); + assert!(transcript.context.hint.is_some()); + + let video = super::video_failure( + &json!({ + "video": { "status": "errored", "errorReason": "The file could not be decoded" }, + "requestId": "r2", + }), + "video-1", + ); + assert_eq!(video.code, "VIDEO_FAILED"); + assert_eq!(video.message, "The file could not be decoded"); + assert_eq!(video.context.details["videoId"], "video-1"); + assert_eq!(video.request_id.as_deref(), Some("r2")); + + let serialized = serde_json::to_value(&video).unwrap(); + assert_eq!(serialized["videoId"], "video-1"); + assert_eq!(serialized["code"], "VIDEO_FAILED"); + assert!(serialized["hint"].is_string()); + assert!(video.describe().contains("videoId: video-1")); + } + + #[test] + fn server_hints_survive_parsing_and_extra_fields_are_dropped() { + let error: crate::caps::AgentApiError = serde_json::from_value(json!({ + "_tag": "AgentForbiddenError", + "code": "FORBIDDEN", + "message": "The developer:read permission is required. Run `cap auth login --profile full`.", + "retryable": false, + "retryAfterMs": null, + "requestId": "r3", + "hint": "Run `cap auth login --profile full`.", + "requiredScopes": ["developer:read"], + })) + .unwrap(); + assert_eq!( + error.context.hint.as_deref(), + Some("Run `cap auth login --profile full`.") + ); + assert!(error.context.details.is_empty()); + assert!(!error.describe().contains("hint:")); + let serialized = serde_json::to_value(&error).unwrap(); + assert!(serialized.get("_tag").is_none()); + assert_eq!(serialized["hint"], "Run `cap auth login --profile full`."); + } + + #[test] + fn domains_resolve_by_id_or_by_origin() { + let context = json!({ + "domains": [ + { "id": "dom-1", "domain": "https://app.example.com" }, + { "id": "-dom-2", "domain": "https://www.example.com" }, + ], + }); + let id = |value: &str| { + super::domain_entry(&context, value) + .and_then(|entry| entry.get("id")) + .and_then(|id| id.as_str()) + .map(str::to_string) + }; + assert_eq!(id("dom-1").as_deref(), Some("dom-1")); + assert_eq!(id("https://app.example.com/").as_deref(), Some("dom-1")); + assert_eq!(id("HTTPS://WWW.EXAMPLE.COM").as_deref(), Some("-dom-2")); + assert_eq!(id("https://other.example.com"), None); + } +} diff --git a/apps/cli/src/developers.rs b/apps/cli/src/developers.rs index a831b03ba91..a4c9fb26b82 100644 --- a/apps/cli/src/developers.rs +++ b/apps/cli/src/developers.rs @@ -1,14 +1,37 @@ +use std::path::PathBuf; + use clap::{Args, Subcommand, ValueEnum}; use reqwest::Method; use serde_json::{Map, Value, json}; use crate::{ OutputFormat, agent_client, - caps::{AgentClient, opaque_id}, - confirmation, resolve_format, + caps::{AgentApiError, AgentClient, opaque_id}, + confirmation, + developer_media::{self, TranscriptOptions}, + resolve_format, }; +const ABOUT: &str = "\ +Cap Infra is Cap's usage-billed video and speech API. A developer app holds its videos, +transcripts, allowed domains, API keys and prepaid credits. + +Amounts: 100,000 micro-credits are $1. Credit purchases are in cents, from 500 ($5) to +100000 ($1,000). Durations are in seconds. + +A typical job: + cap developers list --json + cap developers videos upload ./demo.mp4 --wait --yes --json + cap developers videos get