Open source Loom alternative. Beautiful, shareable screen recordings.
Rust appcapcossloommacnextjsnextjs15open-sourceossreactrecordrustscreen-capturescreen-recorderscreenshotsolidjstauritauri-apptypescriptvite
use std::{
collections::HashMap,
io::{IsTerminal, Read},
path::{Path, PathBuf},
sync::{Arc, RwLock},
time::{Duration, Instant},
};
use clap::{ArgGroup, Args, Subcommand, ValueEnum};
use futures::StreamExt;
use reqwest::{Method, Response, StatusCode};
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value, json};
use tokio::io::AsyncWriteExt;
use url::Url;
use crate::{OutputFormat, atomic, confirmation, credentials, resolve_format, write_json};
#[derive(Args)]
pub struct CapsArgs {
#[command(subcommand)]
command: CapsCommands,
}
#[derive(Subcommand)]
enum CapsCommands {
List(ListArgs),
Get(TargetArgs),
Context(TargetArgs),
Status(TargetArgs),
Wait(WaitArgs),
Process(ProcessArgs),
Import(ImportArgs),
Transcript(TranscriptArgs),
TranscriptReplace(TranscriptReplaceArgs),
Download(DownloadArgs),
Duplicate(CapOperationArgs),
Delete(CapOperationArgs),
Password(PasswordArgs),
Unlock(UnlockArgs),
Comments(CommentsArgs),
Reactions(ReactionsArgs),
Update(UpdateArgs),
Sharing(SharingArgs),
Settings(SettingsArgs),
Date(DateArgs),
Move(MoveArgs),
Shares(SharesArgs),
}
#[derive(Clone, Copy, ValueEnum)]
enum CapsScope {
All,
Owned,
Shared,
}
impl CapsScope {
const fn as_str(self) -> &'static str {
match self {
Self::All => "all",
Self::Owned => "owned",
Self::Shared => "shared",
}
}
}
#[derive(Args)]
struct ListArgs {
#[arg(long, value_enum, default_value_t = CapsScope::All)]
scope: CapsScope,
#[arg(long)]
organization: Option<String>,
#[arg(long)]
folder: Option<String>,
#[arg(long)]
search: Option<String>,
#[arg(long)]
updated_after: Option<String>,
#[arg(long)]
cursor: Option<String>,
#[arg(long, default_value_t = 50, value_parser = clap::value_parser!(u16).range(1..=100))]
limit: u16,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct TargetArgs {
cap: String,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Clone, Copy, ValueEnum)]
enum WaitFor {
Transcript,
Ai,
All,
}
#[derive(Clone, Copy, ValueEnum)]
enum ProcessTarget {
Transcript,
Ai,
All,
}
impl ProcessTarget {
const fn as_str(self) -> &'static str {
match self {
Self::Transcript => "transcript",
Self::Ai => "ai",
Self::All => "all",
}
}
}
#[derive(Args)]
struct ProcessArgs {
cap: String,
#[arg(long, value_enum, default_value_t = ProcessTarget::All)]
target: ProcessTarget,
#[arg(long)]
retry: bool,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct ImportArgs {
#[command(subcommand)]
command: ImportCommands,
}
#[derive(Subcommand)]
enum ImportCommands {
Loom(LoomImportArgs),
}
#[derive(Args)]
struct LoomImportArgs {
loom_url: String,
#[arg(long)]
organization: String,
#[arg(long)]
owner_email: Option<String>,
#[arg(long)]
space: Option<String>,
#[arg(long)]
wait: bool,
#[arg(long, default_value_t = 600)]
timeout: u64,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
fn loom_import_payload(loom_url: &str, owner_email: Option<&str>, space: Option<&str>) -> Value {
let mut payload = json!({ "loomUrl": loom_url });
if let Some(owner_email) = owner_email {
payload["ownerEmail"] = json!(owner_email);
}
if let Some(space) = space {
payload["spaceName"] = json!(space);
}
payload
}
#[derive(Args)]
struct WaitArgs {
cap: String,
#[arg(long, value_enum, default_value_t = WaitFor::All)]
r#for: WaitFor,
#[arg(long, default_value_t = 600)]
timeout: u64,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Clone, Copy, ValueEnum)]
enum TranscriptFormat {
Text,
Json,
Vtt,
}
impl TranscriptFormat {
const fn as_str(self) -> &'static str {
match self {
Self::Text => "text",
Self::Json => "json",
Self::Vtt => "vtt",
}
}
}
#[derive(Args)]
struct TranscriptArgs {
cap: String,
#[arg(long, value_enum, default_value_t = TranscriptFormat::Text)]
format: TranscriptFormat,
#[arg(long)]
output: PathBuf,
}
#[derive(Args)]
struct TranscriptReplaceArgs {
cap: String,
#[arg(long)]
input: PathBuf,
#[arg(long)]
expected_revision: Option<String>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct DownloadArgs {
cap: String,
#[arg(long)]
output: PathBuf,
}
#[derive(Args)]
struct CapOperationArgs {
cap: String,
#[arg(long)]
wait: bool,
#[arg(long, default_value_t = 600)]
timeout: u64,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct PasswordArgs {
#[command(subcommand)]
command: PasswordCommands,
}
#[derive(Subcommand)]
enum PasswordCommands {
Set(PasswordSetArgs),
Clear(PasswordClearArgs),
}
#[derive(Args)]
struct PasswordSetArgs {
cap: String,
#[arg(long)]
password_stdin: bool,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct PasswordClearArgs {
cap: String,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct UnlockArgs {
cap: String,
#[arg(long)]
password_stdin: bool,
#[arg(
long,
help = "Allow a permission-restricted file fallback on macOS or Linux when the OS credential store is unavailable"
)]
allow_file_credential: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct CommentsArgs {
#[command(subcommand)]
command: CommentsCommands,
}
#[derive(Subcommand)]
enum CommentsCommands {
Add(CommentAddArgs),
Reply(CommentReplyArgs),
Delete(CommentDeleteArgs),
}
#[derive(Args)]
struct CommentAddArgs {
cap: String,
content: String,
#[arg(long)]
timestamp_ms: Option<u64>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct CommentReplyArgs {
cap: String,
comment_id: String,
content: String,
#[arg(long)]
timestamp_ms: Option<u64>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct CommentDeleteArgs {
cap: String,
comment_id: String,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct ReactionsArgs {
#[command(subcommand)]
command: ReactionsCommands,
}
#[derive(Subcommand)]
enum ReactionsCommands {
Add(ReactionAddArgs),
}
#[derive(Args)]
struct ReactionAddArgs {
cap: String,
reaction: String,
#[arg(long)]
timestamp_ms: Option<u64>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct UpdateArgs {
cap: String,
#[arg(long)]
title: String,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct SharingArgs {
#[command(subcommand)]
command: SharingCommands,
}
#[derive(Subcommand)]
enum SharingCommands {
Set(SharingSetArgs),
}
#[derive(Args)]
#[command(group(ArgGroup::new("visibility").required(true).args(["public", "private"])))]
struct SharingSetArgs {
cap: String,
#[arg(long)]
public: bool,
#[arg(long)]
private: bool,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct SettingsArgs {
#[command(subcommand)]
command: SettingsCommands,
}
#[derive(Subcommand)]
enum SettingsCommands {
Get(TargetArgs),
Set(SettingsSetArgs),
}
#[derive(Args)]
struct SettingsSetArgs {
cap: String,
#[arg(long)]
disable_summary: Option<bool>,
#[arg(long)]
disable_captions: Option<bool>,
#[arg(long)]
disable_chapters: Option<bool>,
#[arg(long)]
disable_reactions: Option<bool>,
#[arg(long)]
disable_transcript: Option<bool>,
#[arg(long)]
disable_comments: Option<bool>,
#[arg(long)]
default_playback_speed: Option<f64>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct DateArgs {
#[command(subcommand)]
command: DateCommands,
}
#[derive(Subcommand)]
enum DateCommands {
Set(DateSetArgs),
}
#[derive(Args)]
struct DateSetArgs {
cap: String,
created_at: String,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Clone, Copy, ValueEnum)]
enum CapContainer {
Personal,
Organization,
Space,
}
impl CapContainer {
const fn as_str(self) -> &'static str {
match self {
Self::Personal => "personal",
Self::Organization => "organization",
Self::Space => "space",
}
}
}
#[derive(Args)]
struct MoveArgs {
cap: String,
#[arg(long, value_enum)]
container: CapContainer,
#[arg(long)]
organization: String,
#[arg(long)]
space: Option<String>,
#[arg(long)]
folder: Option<String>,
#[arg(long)]
root: bool,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct SharesArgs {
#[command(subcommand)]
command: ShareCommands,
}
#[derive(Subcommand)]
enum ShareCommands {
List(TargetArgs),
Organization(OrganizationSharesArgs),
Space(SpaceSharesArgs),
}
#[derive(Args)]
struct OrganizationSharesArgs {
#[command(subcommand)]
command: OrganizationShareCommands,
}
#[derive(Subcommand)]
enum OrganizationShareCommands {
Add(OrganizationShareArgs),
Remove(OrganizationShareRemoveArgs),
}
#[derive(Args)]
struct OrganizationShareArgs {
cap: String,
organization: String,
#[arg(long)]
folder: Option<String>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct OrganizationShareRemoveArgs {
cap: String,
organization: String,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct SpaceSharesArgs {
#[command(subcommand)]
command: SpaceShareCommands,
}
#[derive(Subcommand)]
enum SpaceShareCommands {
Add(SpaceShareArgs),
Remove(SpaceShareRemoveArgs),
}
#[derive(Args)]
struct SpaceShareArgs {
cap: String,
space: String,
#[arg(long)]
folder: Option<String>,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Args)]
struct SpaceShareRemoveArgs {
cap: String,
space: String,
#[arg(long)]
yes: bool,
#[arg(long, value_enum, default_value_t = OutputFormat::Text)]
format: OutputFormat,
}
#[derive(Debug, Deserialize, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct AgentApiError {
pub code: String,
pub message: String,
pub retryable: bool,
pub retry_after_ms: Option<u64>,
pub request_id: Option<String>,
}
impl std::fmt::Display for AgentApiError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(formatter, "{}: {}", self.code, self.message)
}
}
impl std::error::Error for AgentApiError {}
impl AgentApiError {
fn local(code: &str, message: impl Into<String>) -> Self {
Self {
code: code.to_string(),
message: message.into(),
retryable: false,
retry_after_ms: None,
request_id: None,
}
}
}
#[derive(Clone)]
pub struct AgentClient {
http: reqwest::Client,
access_token: String,
server: String,
access_grants: Arc<RwLock<HashMap<String, credentials::AgentAccessGrant>>>,
access_grant_checks: Arc<RwLock<HashMap<String, Instant>>>,
reload_access_grants: bool,
}
#[derive(Clone, Copy)]
enum AgentRequestBody<'a> {
Json(&'a Value),
Text(&'a str),
}
impl AgentClient {
pub fn from_credentials() -> Result<Self, AgentApiError> {
let credential = credentials::resolve_agent()
.map_err(|message| AgentApiError::local("AUTH_REQUIRED", message))?;
let mut client = Self::new(credential.server, credential.access_token)?;
client.reload_access_grants = true;
Ok(client)
}
pub fn new(server: String, access_token: String) -> Result<Self, AgentApiError> {
let parsed = Url::parse(&server)
.map_err(|_| AgentApiError::local("INVALID_REQUEST", "Invalid Cap server URL"))?;
if parsed.scheme() != "http" && parsed.scheme() != "https" {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"Cap server URL must use HTTP or HTTPS",
));
}
let http = reqwest::Client::builder()
.connect_timeout(Duration::from_secs(10))
.read_timeout(Duration::from_secs(60))
.user_agent(concat!("cap-cli/", env!("CARGO_PKG_VERSION")))
.build()
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))?;
Ok(Self {
http,
access_token,
server: server.trim_end_matches('/').to_string(),
access_grants: Arc::new(RwLock::new(HashMap::new())),
access_grant_checks: Arc::new(RwLock::new(HashMap::new())),
reload_access_grants: false,
})
}
fn endpoint(&self, path: &str) -> String {
format!("{}/api/v1{path}", self.server)
}
async fn parse_error(response: Response) -> AgentApiError {
let status = response.status();
let body = response.bytes().await.unwrap_or_default();
serde_json::from_slice::<AgentApiError>(&body).unwrap_or_else(|_| {
AgentApiError::local(
if status == StatusCode::UNAUTHORIZED {
"AUTH_REQUIRED"
} else if status == StatusCode::TOO_MANY_REQUESTS {
"RATE_LIMITED"
} else {
"TEMPORARY_UNAVAILABLE"
},
format!("Cap returned HTTP {status}"),
)
})
}
async fn request(
&self,
method: Method,
path: &str,
body: Option<AgentRequestBody<'_>>,
idempotency_key: Option<&str>,
user_confirmed: bool,
) -> Result<Response, AgentApiError> {
let mut attempt = 0_u32;
loop {
let mut request = self
.http
.request(method.clone(), self.endpoint(path))
.bearer_auth(&self.access_token);
match body {
Some(AgentRequestBody::Json(body)) => request = request.json(body),
Some(AgentRequestBody::Text(body)) => {
request = request
.header("Content-Type", "text/plain; charset=utf-8")
.body(body.to_string());
}
None => {}
}
if let Some(grant) = self.access_grant_for_path(path) {
request = request.header("X-Cap-Access-Grant", grant);
}
if let Some(key) = idempotency_key {
request = request.header("Idempotency-Key", key);
}
if user_confirmed {
request = request.header("X-Cap-Confirmation", "user");
}
let response = match request.send().await {
Ok(response) => response,
Err(error) => {
let error = AgentApiError {
code: "TEMPORARY_UNAVAILABLE".to_string(),
message: error.to_string(),
retryable: true,
retry_after_ms: Some(500),
request_id: None,
};
if attempt >= 2 {
return Err(error);
}
tokio::time::sleep(Duration::from_millis(error.retry_after_ms.unwrap_or(500)))
.await;
attempt += 1;
continue;
}
};
if response.status().is_success() {
return Ok(response);
}
let status = response.status();
let error = Self::parse_error(response).await;
let retryable = error.retryable
|| status == StatusCode::TOO_MANY_REQUESTS
|| status.is_server_error();
if !retryable || attempt >= 2 {
return Err(error);
}
let delay = error
.retry_after_ms
.unwrap_or(200_u64.saturating_mul(1_u64 << attempt))
.min(5_000);
tokio::time::sleep(Duration::from_millis(delay)).await;
attempt += 1;
}
}
pub async fn get_json(&self, path: &str) -> Result<Value, AgentApiError> {
self.request(Method::GET, path, None, None, false)
.await?
.json()
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))
}
pub async fn mutate_json(
&self,
method: Method,
path: &str,
body: &Value,
) -> Result<Value, AgentApiError> {
let idempotency_key = uuid::Uuid::new_v4().to_string();
self.request(
method,
path,
Some(AgentRequestBody::Json(body)),
Some(&idempotency_key),
false,
)
.await?
.json()
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))
}
pub async fn mutate_json_confirmed(
&self,
method: Method,
path: &str,
body: &Value,
) -> Result<Value, AgentApiError> {
let idempotency_key = uuid::Uuid::new_v4().to_string();
self.request(
method,
path,
Some(AgentRequestBody::Json(body)),
Some(&idempotency_key),
true,
)
.await?
.json()
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))
}
async fn mutate_text_confirmed(
&self,
method: Method,
path: &str,
body: &str,
) -> Result<Value, AgentApiError> {
let idempotency_key = uuid::Uuid::new_v4().to_string();
self.request(
method,
path,
Some(AgentRequestBody::Text(body)),
Some(&idempotency_key),
true,
)
.await?
.json()
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))
}
async fn stream_authorized(&self, path: &str, output: &Path) -> Result<u64, AgentApiError> {
let response = self.request(Method::GET, path, None, None, false).await?;
stream_response(response, output).await
}
async fn unlock_json(&self, id: &str, password: &str) -> Result<Value, AgentApiError> {
self.request(
Method::POST,
&format!("/caps/{id}/unlock"),
Some(AgentRequestBody::Text(password)),
None,
false,
)
.await?
.json()
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))
}
fn access_grant_for_path(&self, path: &str) -> Option<String> {
let id = path
.strip_prefix("/caps/")?
.split(['/', '?'])
.next()
.filter(|id| !id.is_empty())?;
if let Some(grant) = self
.access_grants
.read()
.ok()
.and_then(|grants| grants.get(id).cloned())
.filter(|grant| grant.expires_at > chrono::Utc::now())
{
return Some(grant.value);
}
if !self.reload_access_grants {
return None;
}
if self
.access_grant_checks
.read()
.ok()
.and_then(|checks| checks.get(id).copied())
.is_some_and(|checked_at| checked_at.elapsed() < Duration::from_secs(1))
{
return None;
}
if let Ok(mut checks) = self.access_grant_checks.write() {
checks.insert(id.to_string(), Instant::now());
}
let grant = credentials::agent_access_grant(id)?;
if let Ok(mut grants) = self.access_grants.write() {
grants.insert(id.to_string(), grant.clone());
}
Some(grant.value)
}
}
pub fn cap_id(value: &str) -> Result<String, AgentApiError> {
let id = if value.starts_with("http://") || value.starts_with("https://") {
let url = Url::parse(value)
.map_err(|_| AgentApiError::local("INVALID_REQUEST", "Invalid Cap URL"))?;
let segments = url
.path_segments()
.ok_or_else(|| AgentApiError::local("INVALID_REQUEST", "Invalid Cap URL"))?
.filter(|segment| !segment.is_empty())
.collect::<Vec<_>>();
match segments.as_slice() {
[kind, id] if matches!(*kind, "s" | "watch" | "embed" | "c") => (*id).to_string(),
[id] => (*id).to_string(),
_ => {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"URL does not identify a Cap",
));
}
}
} else {
value.to_string()
};
if id.len() < 5
|| id.len() > 128
|| !id
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-')
{
return Err(AgentApiError::local(
"INVALID_REQUEST",
"Cap ID contains invalid characters",
));
}
Ok(id)
}
fn encode_query(parameters: &[(&str, Option<String>)]) -> String {
let mut serializer = url::form_urlencoded::Serializer::new(String::new());
for (key, value) in parameters {
if let Some(value) = value {
serializer.append_pair(key, value);
}
}
serializer.finish()
}
async fn stream_response(response: Response, output: &Path) -> Result<u64, AgentApiError> {
if let Some(parent) = output.parent()
&& !parent.as_os_str().is_empty()
{
tokio::fs::create_dir_all(parent)
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))?;
}
let temporary = output.with_extension(format!("part-{}", uuid::Uuid::new_v4()));
let mut file = tokio::fs::File::create(&temporary)
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))?;
let mut stream = response.bytes_stream();
let mut written = 0_u64;
let write_result = async {
while let Some(chunk) = stream.next().await {
let chunk = chunk.map_err(|error| {
AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string())
})?;
file.write_all(&chunk).await.map_err(|error| {
AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string())
})?;
written = written.saturating_add(chunk.len() as u64);
}
file.flush()
.await
.map_err(|error| AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string()))
}
.await;
drop(file);
if let Err(error) = write_result {
let _ = tokio::fs::remove_file(&temporary).await;
return Err(error);
}
if let Err(error) = atomic::replace(&temporary, output) {
let _ = tokio::fs::remove_file(&temporary).await;
return Err(AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
error.to_string(),
));
}
Ok(written)
}
fn print_value(value: &Value, format: OutputFormat) -> Result<(), String> {
match format {
OutputFormat::Json => write_json(value),
OutputFormat::Text => {
println!(
"{}",
serde_json::to_string_pretty(value).map_err(|error| error.to_string())?
);
Ok(())
}
}
}
fn wait_complete(status: &Value, wait_for: WaitFor) -> Result<bool, AgentApiError> {
let state = |key: &str| {
status
.get(key)
.and_then(|value| value.get("status"))
.and_then(Value::as_str)
};
let complete = |key| match state(key) {
Some("complete" | "skipped" | "no_audio" | "unavailable") => Ok(true),
Some("error") => Err(AgentApiError::local(
"NOT_READY",
format!("{key} processing failed"),
)),
Some(_) => Ok(false),
None => Err(AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
"Cap returned an invalid status",
)),
};
match wait_for {
WaitFor::Transcript => complete("transcript"),
WaitFor::Ai => complete("ai"),
WaitFor::All => Ok(complete("transcript")? && complete("ai")?),
}
}
pub fn opaque_id(value: &str, field: &str) -> Result<String, AgentApiError> {
if value.is_empty()
|| value.len() > 128
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-')
{
return Err(AgentApiError::local(
"INVALID_REQUEST",
format!("{field} contains invalid characters"),
));
}
Ok(value.to_string())
}
fn read_unlock_password(password_stdin: bool) -> Result<String, AgentApiError> {
let password = if password_stdin {
let mut value = String::new();
std::io::stdin()
.lock()
.take(1_025)
.read_to_string(&mut value)
.map_err(|error| AgentApiError::local("INVALID_REQUEST", error.to_string()))?;
if let Some(value) = value.strip_suffix('\n') {
value.strip_suffix('\r').unwrap_or(value).to_string()
} else {
value
}
} else {
if !std::io::stdin().is_terminal() {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"Non-interactive unlock requires --password-stdin",
));
}
rpassword::prompt_password("Cap password: ")
.map_err(|error| AgentApiError::local("INVALID_REQUEST", error.to_string()))?
};
if password.is_empty() || password.len() > 512 {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"Password must be between 1 and 512 bytes",
));
}
Ok(password)
}
async fn run_cap_operation(
client: &AgentClient,
args: CapOperationArgs,
deleting: bool,
global_json: bool,
) -> Result<(), AgentApiError> {
let id = cap_id(&args.cap)?;
confirmation::require(
args.yes,
if deleting {
"Permanently delete the Cap and its media"
} else {
"Duplicate the Cap and its media"
},
)
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let path = if deleting {
format!("/caps/{id}")
} else {
format!("/caps/{id}/duplicate")
};
let value = client
.mutate_json_confirmed(
if deleting {
Method::DELETE
} else {
Method::POST
},
&path,
&json!({}),
)
.await?;
let value = if args.wait {
let operation_id = value.get("id").and_then(Value::as_str).ok_or_else(|| {
AgentApiError::local("TEMPORARY_UNAVAILABLE", "Cap returned an invalid operation")
})?;
crate::jobs::wait_operation(client, operation_id, args.timeout).await?
} else {
value
};
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
impl CapsArgs {
fn output_format(&self, global_json: bool) -> OutputFormat {
let local = match &self.command {
CapsCommands::List(args) => args.format,
CapsCommands::Get(args) | CapsCommands::Context(args) | CapsCommands::Status(args) => {
args.format
}
CapsCommands::Wait(args) => args.format,
CapsCommands::Process(args) => args.format,
CapsCommands::Import(args) => match &args.command {
ImportCommands::Loom(args) => args.format,
},
CapsCommands::Transcript(_) | CapsCommands::Download(_) => OutputFormat::Text,
CapsCommands::TranscriptReplace(args) => args.format,
CapsCommands::Duplicate(args) | CapsCommands::Delete(args) => args.format,
CapsCommands::Password(args) => match &args.command {
PasswordCommands::Set(args) => args.format,
PasswordCommands::Clear(args) => args.format,
},
CapsCommands::Unlock(args) => args.format,
CapsCommands::Comments(args) => match &args.command {
CommentsCommands::Add(args) => args.format,
CommentsCommands::Reply(args) => args.format,
CommentsCommands::Delete(args) => args.format,
},
CapsCommands::Reactions(args) => match &args.command {
ReactionsCommands::Add(args) => args.format,
},
CapsCommands::Update(args) => args.format,
CapsCommands::Sharing(args) => match &args.command {
SharingCommands::Set(args) => args.format,
},
CapsCommands::Settings(args) => match &args.command {
SettingsCommands::Get(args) => args.format,
SettingsCommands::Set(args) => args.format,
},
CapsCommands::Date(args) => match &args.command {
DateCommands::Set(args) => args.format,
},
CapsCommands::Move(args) => args.format,
CapsCommands::Shares(args) => match &args.command {
ShareCommands::List(args) => args.format,
ShareCommands::Organization(args) => match &args.command {
OrganizationShareCommands::Add(args) => args.format,
OrganizationShareCommands::Remove(args) => args.format,
},
ShareCommands::Space(args) => match &args.command {
SpaceShareCommands::Add(args) => args.format,
SpaceShareCommands::Remove(args) => args.format,
},
},
};
resolve_format(global_json, local)
}
pub async fn run(self, global_json: bool) -> Result<(), String> {
let output_format = self.output_format(global_json);
let result = self.run_inner(global_json).await;
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,
});
}
result.map_err(|error| error.to_string())
}
async fn run_inner(self, global_json: bool) -> Result<(), AgentApiError> {
let client = AgentClient::from_credentials()?;
match self.command {
CapsCommands::List(args) => {
let query = encode_query(&[
("scope", Some(args.scope.as_str().to_string())),
("organizationId", args.organization),
("folderId", args.folder),
("search", args.search),
("updatedAfter", args.updated_after),
("cursor", args.cursor),
("limit", Some(args.limit.to_string())),
]);
let value = client.get_json(&format!("/caps?{query}")).await?;
let format = resolve_format(global_json, args.format);
if format == OutputFormat::Text {
let caps = value.get("caps").and_then(Value::as_array).ok_or_else(|| {
AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
"Cap returned an invalid list",
)
})?;
for cap in caps {
println!(
"{}\t{}\t{}",
cap.get("id").and_then(Value::as_str).unwrap_or(""),
cap.get("title").and_then(Value::as_str).unwrap_or(""),
cap.get("updatedAt").and_then(Value::as_str).unwrap_or("")
);
}
if let Some(cursor) = value.get("nextCursor").and_then(Value::as_str) {
println!("next cursor: {cursor}");
}
Ok(())
} else {
print_value(&value, format)
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
}
CapsCommands::Get(args) => {
let id = cap_id(&args.cap)?;
let value = client.get_json(&format!("/caps/{id}")).await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Context(args) => {
let id = cap_id(&args.cap)?;
let value = client.get_json(&format!("/caps/{id}/context")).await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Status(args) => {
let id = cap_id(&args.cap)?;
let value = client.get_json(&format!("/caps/{id}/status")).await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Wait(args) => {
if args.timeout == 0 || args.timeout > 86_400 {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"--timeout must be between 1 and 86400 seconds",
));
}
let id = cap_id(&args.cap)?;
let started = tokio::time::Instant::now();
let deadline = started + Duration::from_secs(args.timeout);
let mut attempt = 0_u32;
loop {
let value = client.get_json(&format!("/caps/{id}/status")).await?;
if wait_complete(&value, args.r#for)? {
return print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| {
AgentApiError::local("TEMPORARY_UNAVAILABLE", message)
});
}
if tokio::time::Instant::now() >= deadline {
return Err(AgentApiError {
code: "NOT_READY".to_string(),
message: "Timed out waiting for Cap processing".to_string(),
retryable: true,
retry_after_ms: Some(2_000),
request_id: value
.get("requestId")
.and_then(Value::as_str)
.map(str::to_string),
});
}
let base = 500_u64.saturating_mul(1_u64 << attempt.min(4));
let jitter = u64::from(uuid::Uuid::new_v4().as_bytes()[0]);
tokio::time::sleep(Duration::from_millis((base + jitter).min(10_000))).await;
attempt = attempt.saturating_add(1);
}
}
CapsCommands::Process(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(
args.yes,
"Start paid Cap processing when work is not already complete",
)
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::POST,
&format!("/caps/{id}/process"),
&json!({
"target": args.target.as_str(),
"retry": args.retry,
}),
)
.await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Import(args) => match args.command {
ImportCommands::Loom(args) => {
if args.timeout == 0 || args.timeout > 86_400 {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"--timeout must be between 1 and 86400 seconds",
));
}
confirmation::require(
args.yes,
if args.owner_email.is_some() || args.space.is_some() {
"Import the Loom video and apply the requested organization assignment"
} else {
"Import the Loom video into Cap"
},
)
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let organization = opaque_id(&args.organization, "Organization ID")?;
let value = client
.mutate_json_confirmed(
Method::POST,
&format!("/organizations/{organization}/imports/loom"),
&loom_import_payload(
&args.loom_url,
args.owner_email.as_deref(),
args.space.as_deref(),
),
)
.await?;
let value = if args.wait {
let operation_id =
value.get("id").and_then(Value::as_str).ok_or_else(|| {
AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
"Cap returned an invalid Loom import operation",
)
})?;
crate::jobs::wait_operation(&client, operation_id, args.timeout).await?
} else {
value
};
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
},
CapsCommands::Transcript(args) => {
let id = cap_id(&args.cap)?;
let path = format!("/caps/{id}/transcript?format={}", args.format.as_str());
let bytes = client.stream_authorized(&path, &args.output).await?;
let result = json!({
"id": id,
"path": args.output,
"format": args.format.as_str(),
"bytes": bytes,
});
print_value(
&result,
if global_json {
OutputFormat::Json
} else {
OutputFormat::Text
},
)
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::TranscriptReplace(args) => {
let id = cap_id(&args.cap)?;
let metadata = tokio::fs::metadata(&args.input)
.await
.map_err(|error| AgentApiError::local("INVALID_REQUEST", error.to_string()))?;
if metadata.len() > 12 * 1024 * 1024 {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"Transcript JSON must not exceed 12 MiB",
));
}
let input = tokio::fs::read(&args.input)
.await
.map_err(|error| AgentApiError::local("INVALID_REQUEST", error.to_string()))?;
let document: Value = serde_json::from_slice(&input)
.map_err(|error| AgentApiError::local("INVALID_REQUEST", error.to_string()))?;
let expected_revision = args
.expected_revision
.or_else(|| {
document
.get("revision")
.and_then(Value::as_str)
.map(str::to_string)
})
.ok_or_else(|| {
AgentApiError::local(
"INVALID_REQUEST",
"Provide --expected-revision or a transcript JSON revision",
)
})?;
let cues = document.get("cues").cloned().ok_or_else(|| {
AgentApiError::local("INVALID_REQUEST", "Transcript JSON must contain cues")
})?;
confirmation::require(args.yes, "Replace the Cap transcript")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::PUT,
&format!("/caps/{id}/transcript"),
&json!({
"expectedRevision": expected_revision,
"cues": cues,
}),
)
.await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Download(args) => {
let id = cap_id(&args.cap)?;
let info = client.get_json(&format!("/caps/{id}/download")).await?;
let url = info.get("url").and_then(Value::as_str).ok_or_else(|| {
AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
"Cap returned an invalid download",
)
})?;
let response = client.http.get(url).send().await.map_err(|error| {
AgentApiError::local("TEMPORARY_UNAVAILABLE", error.to_string())
})?;
if !response.status().is_success() {
return Err(AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
format!("Download returned HTTP {}", response.status()),
));
}
let bytes = stream_response(response, &args.output).await?;
let result = json!({ "id": id, "path": args.output, "bytes": bytes });
print_value(
&result,
if global_json {
OutputFormat::Json
} else {
OutputFormat::Text
},
)
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Duplicate(args) => {
run_cap_operation(&client, args, false, global_json).await
}
CapsCommands::Delete(args) => run_cap_operation(&client, args, true, global_json).await,
CapsCommands::Password(args) => {
let (value, format) = match args.command {
PasswordCommands::Set(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Set the Cap password")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let password = read_unlock_password(args.password_stdin)?;
let value = client
.mutate_text_confirmed(
Method::PUT,
&format!("/caps/{id}/password"),
&password,
)
.await?;
drop(password);
(value, args.format)
}
PasswordCommands::Clear(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Clear the Cap password")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_text_confirmed(Method::PUT, &format!("/caps/{id}/password"), "")
.await?;
(value, args.format)
}
};
print_value(&value, resolve_format(global_json, format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Unlock(args) => {
let id = cap_id(&args.cap)?;
let password = read_unlock_password(args.password_stdin)?;
let response = client.unlock_json(&id, &password).await?;
drop(password);
let access_grant = response
.get("accessGrant")
.and_then(Value::as_str)
.ok_or_else(|| {
AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
"Cap returned an invalid access grant",
)
})?;
let expires_at = response
.get("expiresAt")
.and_then(Value::as_str)
.ok_or_else(|| {
AgentApiError::local(
"TEMPORARY_UNAVAILABLE",
"Cap returned an invalid access grant expiry",
)
})?;
credentials::store_agent_access_grant(
&id,
access_grant.to_string(),
expires_at.to_string(),
args.allow_file_credential,
)
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))?;
print_value(
&json!({ "id": id, "unlocked": true, "expiresAt": expires_at }),
resolve_format(global_json, args.format),
)
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Comments(args) => {
let (value, format) = match args.command {
CommentsCommands::Add(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Post the comment")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::POST,
&format!("/caps/{id}/comments"),
&json!({
"content": args.content,
"timestampMs": args.timestamp_ms,
}),
)
.await?;
(value, args.format)
}
CommentsCommands::Reply(args) => {
let id = cap_id(&args.cap)?;
let comment_id = opaque_id(&args.comment_id, "Comment ID")?;
confirmation::require(args.yes, "Post the reply")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::POST,
&format!("/caps/{id}/comments/{comment_id}/replies"),
&json!({
"content": args.content,
"timestampMs": args.timestamp_ms,
}),
)
.await?;
(value, args.format)
}
CommentsCommands::Delete(args) => {
let id = cap_id(&args.cap)?;
let comment_id = opaque_id(&args.comment_id, "Comment ID")?;
confirmation::require(args.yes, "Delete the comment")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json(
Method::DELETE,
&format!("/caps/{id}/comments/{comment_id}"),
&json!({}),
)
.await?;
(value, args.format)
}
};
print_value(&value, resolve_format(global_json, format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Reactions(args) => {
let (value, format) = match args.command {
ReactionsCommands::Add(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Post the reaction")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::POST,
&format!("/caps/{id}/reactions"),
&json!({
"content": args.reaction,
"timestampMs": args.timestamp_ms,
}),
)
.await?;
(value, args.format)
}
};
print_value(&value, resolve_format(global_json, format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Update(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Change the Cap title")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::PATCH,
&format!("/caps/{id}"),
&json!({ "title": args.title }),
)
.await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Sharing(args) => {
let (value, format) = match args.command {
SharingCommands::Set(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Change the Cap visibility")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json_confirmed(
Method::PATCH,
&format!("/caps/{id}"),
&json!({ "public": args.public && !args.private }),
)
.await?;
(value, args.format)
}
};
print_value(&value, resolve_format(global_json, format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Settings(args) => match args.command {
SettingsCommands::Get(args) => {
let id = cap_id(&args.cap)?;
let value = client.get_json(&format!("/caps/{id}/settings")).await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
SettingsCommands::Set(args) => {
let id = cap_id(&args.cap)?;
let mut body = Map::new();
for (key, value) in [
("disableSummary", args.disable_summary),
("disableCaptions", args.disable_captions),
("disableChapters", args.disable_chapters),
("disableReactions", args.disable_reactions),
("disableTranscript", args.disable_transcript),
("disableComments", args.disable_comments),
] {
if let Some(value) = value {
body.insert(key.to_string(), Value::Bool(value));
}
}
if let Some(value) = args.default_playback_speed {
body.insert("defaultPlaybackSpeed".to_string(), json!(value));
}
if body.is_empty() {
return Err(AgentApiError::local(
"INVALID_REQUEST",
"Provide at least one Cap setting",
));
}
confirmation::require(args.yes, "Update the Cap viewer settings")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json(
Method::PATCH,
&format!("/caps/{id}/settings"),
&Value::Object(body),
)
.await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
},
CapsCommands::Date(args) => match args.command {
DateCommands::Set(args) => {
let id = cap_id(&args.cap)?;
confirmation::require(args.yes, "Change the Cap recording date")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json(
Method::PATCH,
&format!("/caps/{id}/date"),
&json!({ "createdAt": args.created_at }),
)
.await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
},
CapsCommands::Move(args) => {
let id = cap_id(&args.cap)?;
let organization_id = opaque_id(&args.organization, "Organization ID")?;
let space_id = args
.space
.as_deref()
.map(|space| opaque_id(space, "Space ID"))
.transpose()?;
let folder_id = if args.root {
None
} else {
args.folder
.as_deref()
.map(|folder| opaque_id(folder, "Folder ID"))
.transpose()?
};
confirmation::require(args.yes, "Move the Cap")
.map_err(|message| AgentApiError::local("INVALID_REQUEST", message))?;
let value = client
.mutate_json(
Method::PATCH,
&format!("/caps/{id}/location"),
&json!({
"container": args.container.as_str(),
"organizationId": organization_id,
"spaceId": space_id,
"folderId": folder_id,
}),
)
.await?;
print_value(&value, resolve_format(global_json, args.format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
CapsCommands::Shares(args) => {
let (value, format) = match args.command {
ShareCommands::List(args) => {
let id = cap_id(&args.cap)?;
let value = client.get_json(&format!("/caps/{id}/shares")).await?;
(value, args.format)
}
ShareCommands::Organization(args) => match args.command {
OrganizationShareCommands::Add(args) => {
let id = cap_id(&args.cap)?;
let organization = opaque_id(&args.organization, "Organization ID")?;
let folder = args
.folder
.as_deref()
.map(|value| opaque_id(value, "Folder ID"))
.transpose()?;
confirmation::require(args.yes, "Share the Cap with the organization")
.map_err(|message| {
AgentApiError::local("INVALID_REQUEST", message)
})?;
let value = client
.mutate_json(
Method::PUT,
&format!("/caps/{id}/shares/organizations/{organization}"),
&json!({ "folderId": folder }),
)
.await?;
(value, args.format)
}
OrganizationShareCommands::Remove(args) => {
let id = cap_id(&args.cap)?;
let organization = opaque_id(&args.organization, "Organization ID")?;
confirmation::require(args.yes, "Remove the organization share")
.map_err(|message| {
AgentApiError::local("INVALID_REQUEST", message)
})?;
let value = client
.mutate_json(
Method::DELETE,
&format!("/caps/{id}/shares/organizations/{organization}"),
&json!({}),
)
.await?;
(value, args.format)
}
},
ShareCommands::Space(args) => match args.command {
SpaceShareCommands::Add(args) => {
let id = cap_id(&args.cap)?;
let space = opaque_id(&args.space, "Space ID")?;
let folder = args
.folder
.as_deref()
.map(|value| opaque_id(value, "Folder ID"))
.transpose()?;
confirmation::require(args.yes, "Share the Cap with the space")
.map_err(|message| {
AgentApiError::local("INVALID_REQUEST", message)
})?;
let value = client
.mutate_json(
Method::PUT,
&format!("/caps/{id}/shares/spaces/{space}"),
&json!({ "folderId": folder }),
)
.await?;
(value, args.format)
}
SpaceShareCommands::Remove(args) => {
let id = cap_id(&args.cap)?;
let space = opaque_id(&args.space, "Space ID")?;
confirmation::require(args.yes, "Remove the space share").map_err(
|message| AgentApiError::local("INVALID_REQUEST", message),
)?;
let value = client
.mutate_json(
Method::DELETE,
&format!("/caps/{id}/shares/spaces/{space}"),
&json!({}),
)
.await?;
(value, args.format)
}
},
};
print_value(&value, resolve_format(global_json, format))
.map_err(|message| AgentApiError::local("TEMPORARY_UNAVAILABLE", message))
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
#[test]
fn loom_import_payload_omits_unset_optional_fields() {
assert_eq!(
loom_import_payload("https://www.loom.com/share/abc", None, None),
json!({ "loomUrl": "https://www.loom.com/share/abc" })
);
assert_eq!(
loom_import_payload(
"https://www.loom.com/share/abc",
Some("[email protected]"),
Some("Team"),
),
json!({
"loomUrl": "https://www.loom.com/share/abc",
"ownerEmail": "[email protected]",
"spaceName": "Team",
})
);
}
async fn read_request(stream: &mut tokio::net::TcpStream) -> String {
let mut bytes = Vec::new();
let mut buffer = [0_u8; 1_024];
loop {
let read = stream.read(&mut buffer).await.unwrap();
if read == 0 {
break;
}
bytes.extend_from_slice(&buffer[..read]);
if let Some(headers_end) = bytes.windows(4).position(|window| window == b"\r\n\r\n") {
let headers = String::from_utf8_lossy(&bytes[..headers_end + 4]);
let content_length = headers
.lines()
.find_map(|line| {
line.to_ascii_lowercase()
.strip_prefix("content-length:")
.and_then(|value| value.trim().parse::<usize>().ok())
})
.unwrap_or(0);
if bytes.len() >= headers_end + 4 + content_length {
break;
}
}
}
String::from_utf8(bytes).unwrap()
}
async fn mock_response(stream: &mut tokio::net::TcpStream, status: &str, body: &str) {
stream
.write_all(
format!(
"HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
body.len()
)
.as_bytes(),
)
.await
.unwrap();
}
#[test]
fn accepts_ids_and_known_cap_urls() {
assert_eq!(cap_id("cap_12345").unwrap(), "cap_12345");
assert_eq!(cap_id("https://cap.so/s/cap_12345").unwrap(), "cap_12345");
assert_eq!(
cap_id("https://videos.example.com/cap_12345").unwrap(),
"cap_12345"
);
assert!(cap_id("https://cap.so/settings/billing").is_err());
}
#[test]
fn terminal_wait_states_do_not_start_work() {
assert!(
wait_complete(
&json!({"transcript":{"status":"complete"}}),
WaitFor::Transcript
)
.unwrap()
);
assert!(wait_complete(&json!({"ai":{"status":"skipped"}}), WaitFor::Ai).unwrap());
assert!(
wait_complete(&json!({"ai":{"status":"processing"}}), WaitFor::Ai)
.is_ok_and(|done| !done)
);
}
#[tokio::test]
async fn operation_wait_bounds_slow_responses() {
for send_headers in [false, true] {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
let request = read_request(&mut stream).await;
assert!(request.starts_with("GET /api/v1/operations/op_test HTTP/1.1\r\n"));
let body = r#"{"state":"succeeded"}"#;
if send_headers {
stream
.write_all(
format!(
"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\n\r\n",
body.len()
)
.as_bytes(),
)
.await
.unwrap();
}
tokio::time::sleep(Duration::from_secs(3)).await;
if send_headers {
stream.write_all(body.as_bytes()).await.unwrap();
} else {
mock_response(&mut stream, "200 OK", body).await;
}
});
let client =
AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
let result = tokio::time::timeout(
Duration::from_millis(1_400),
crate::jobs::wait_operation(&client, "op_test", 1),
)
.await;
server.abort();
assert!(server.await.unwrap_err().is_cancelled());
let error = result
.expect("operation wait exceeded its deadline")
.unwrap_err();
assert_eq!(error.code, "NOT_READY");
assert_eq!(error.message, "Timed out waiting for the Cap operation");
assert!(error.retryable);
assert_eq!(error.retry_after_ms, Some(2_000));
assert_eq!(error.request_id, None);
}
}
#[tokio::test]
async fn operation_wait_bounds_poll_sleeps_and_keeps_the_last_request_id() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
for request_id in ["request_1", "request_2"] {
let (mut stream, _) = listener.accept().await.unwrap();
read_request(&mut stream).await;
mock_response(
&mut stream,
"200 OK",
&json!({"state":"running", "requestId":request_id}).to_string(),
)
.await;
}
});
let client = AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
let result = tokio::time::timeout(
Duration::from_millis(1_400),
crate::jobs::wait_operation(&client, "op_test", 1),
)
.await;
server.abort();
if let Err(error) = server.await {
assert!(error.is_cancelled(), "{error}");
}
let error = result
.expect("operation wait exceeded its deadline")
.unwrap_err();
assert_eq!(error.code, "NOT_READY");
assert_eq!(error.request_id.as_deref(), Some("request_2"));
}
#[tokio::test]
async fn operation_wait_keeps_the_request_id_when_the_next_poll_stalls() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
read_request(&mut stream).await;
mock_response(
&mut stream,
"200 OK",
r#"{"state":"queued","requestId":"request_1"}"#,
)
.await;
drop(stream);
let (mut stream, _) = listener.accept().await.unwrap();
read_request(&mut stream).await;
tokio::time::sleep(Duration::from_secs(3)).await;
mock_response(&mut stream, "200 OK", r#"{"state":"succeeded"}"#).await;
});
let client = AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
let result = tokio::time::timeout(
Duration::from_millis(1_400),
crate::jobs::wait_operation(&client, "op_test", 1),
)
.await;
server.abort();
assert!(server.await.unwrap_err().is_cancelled());
let error = result
.expect("operation wait exceeded its deadline")
.unwrap_err();
assert_eq!(error.code, "NOT_READY");
assert_eq!(error.request_id.as_deref(), Some("request_1"));
}
#[tokio::test]
async fn operation_wait_returns_terminal_results_without_polling() {
for state in ["succeeded", "failed"] {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let body = json!({"state":state, "error":{"message":"Operation failed"}});
let response = body.to_string();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
read_request(&mut stream).await;
mock_response(&mut stream, "200 OK", &response).await;
});
let client =
AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
let result = tokio::time::timeout(
Duration::from_millis(400),
crate::jobs::wait_operation(&client, "op_test", 1),
)
.await
.expect("terminal operation should return immediately");
server.abort();
if let Err(error) = server.await {
assert!(error.is_cancelled(), "{error}");
}
match state {
"succeeded" => assert_eq!(result.unwrap(), body),
_ => {
let error = result.unwrap_err();
assert_eq!(error.code, "OPERATION_FAILED");
assert_eq!(error.message, "Operation failed");
assert!(!error.retryable);
}
}
}
}
#[tokio::test]
async fn mutation_retries_reuse_the_same_idempotency_key() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
let mut keys = Vec::new();
for attempt in 0..2 {
let (mut stream, _) = listener.accept().await.unwrap();
let request = read_request(&mut stream).await;
let key = request
.lines()
.find_map(|line| {
line.to_ascii_lowercase()
.strip_prefix("idempotency-key:")
.map(str::trim)
.map(str::to_string)
})
.unwrap();
keys.push(key);
if attempt == 0 {
mock_response(
&mut stream,
"503 Service Unavailable",
r#"{"code":"TEMPORARY_UNAVAILABLE","message":"retry","retryable":true,"retryAfterMs":1,"requestId":"request_1"}"#,
)
.await;
} else {
mock_response(&mut stream, "200 OK", r#"{"ok":true}"#).await;
}
}
keys
});
let client = AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
let value = client
.mutate_json(
Method::POST,
"/caps/cap_test/comments",
&json!({"content":"ok"}),
)
.await
.unwrap();
assert_eq!(value["ok"], true);
let keys = server.await.unwrap();
assert_eq!(keys.len(), 2);
assert_eq!(keys[0], keys[1]);
}
#[tokio::test]
async fn mutation_transport_retries_reuse_the_same_idempotency_key() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
let mut keys = Vec::new();
for attempt in 0..2 {
let (mut stream, _) = listener.accept().await.unwrap();
let request = read_request(&mut stream).await;
keys.push(
request
.lines()
.find_map(|line| {
line.to_ascii_lowercase()
.strip_prefix("idempotency-key:")
.map(str::trim)
.map(str::to_string)
})
.unwrap(),
);
if attempt == 1 {
mock_response(&mut stream, "200 OK", r#"{"ok":true}"#).await;
}
}
keys
});
let client = AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
let value = client
.mutate_json(
Method::POST,
"/caps/cap_test/comments",
&json!({"content":"ok"}),
)
.await
.unwrap();
assert_eq!(value["ok"], true);
let keys = server.await.unwrap();
assert_eq!(keys.len(), 2);
assert_eq!(keys[0], keys[1]);
}
#[tokio::test]
async fn access_grants_are_sent_only_as_headers() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let server = tokio::spawn(async move {
let (mut stream, _) = listener.accept().await.unwrap();
let request = read_request(&mut stream).await;
mock_response(&mut stream, "200 OK", r#"{"ok":true}"#).await;
request
});
let client = AgentClient::new(format!("http://{address}"), "token".to_string()).unwrap();
client.access_grants.write().unwrap().insert(
"cap_test".to_string(),
credentials::AgentAccessGrant {
value: "encrypted_access_grant".to_string(),
expires_at: chrono::Utc::now() + chrono::Duration::minutes(1),
},
);
client.get_json("/caps/cap_test/context").await.unwrap();
let request = server.await.unwrap();
assert!(request.contains("x-cap-access-grant: encrypted_access_grant"));
assert!(!request.contains("password"));
}
}