Silicon Waveform Rust client

Add the package with cargo add silicon-waveform-client. Production clients use https://backend.waveform.teamofsilicons.com as their API origin.

silicon-waveform-client is stateless. Construct it with Auth::Anonymous, then use with_bearer with an access token obtained by exchanging an IAM SLT through login. The client never asks for IAM credentials or persists a session. refresh exchanges a refresh token; logout revokes a token and correctly accepts Waveform's 204 No Content response.

client.iam().await? returns typed IamInfo containing app_id, iam_base_url, and the upstream IAM testing_environment_id (null in production). It requires no login and honors the selected test environment.

client.with_bearer(access_token).login_status().await? returns typed LoginStatus: authenticated, optional actor (principal_id, actor_type, public_id), org_id, and testing_environment_id. It verifies the token via auth/me; anonymous clients return false without network access, and HTTP 401/403 also return false. Other failures remain errors. No tokens are returned in status, and it does not refresh or persist them.

The stateless client does not resolve home directories. The CLI uses SILICON_HOME as its default home when present, otherwise ~, with an explicit waveform config home setting taking precedence. See CLI guide.

Use with_test_environment(TestEnvironmentKey::new(app_secret)?) to select a sandbox. current_test_environment() validates the secret with IAM and returns safe metadata. Every request carries the selector; invalid selectors fail, without production fallback. No separate Briefcase key is needed. login accepts a test SLT or existing public ID in this mode.

Speech methods are tts and stt; each accepts an optional provider_order prefix to override the account's first choices. capabilities is unauthenticated. Authenticated control methods include me, actor-scoped jobs/job, provider preferences and update_preferences, and write-only personal provider-key methods. jobs_page accepts optional operation, limit (1-100), and opaque cursor values. A Job is terminal when its status is completed or failed; wait_for_job polls until a terminal state or caller timeout, and failed rows include error_code.

Legacy test-plane lifecycle methods require the organization ID because IAM authorization is organization-scoped: create_test_environment, test_environments, test_environment_detail, test_environment_key, rotate_test_environment_key, delete_test_environment, and restore_test_environment. test_environment and clean_test_environment operate on a legacy selected plane. Manage new discovered worlds in IAM.

Automatic package maintenance

The client checks crates.io after a request finishes, at most once per hour per client and its clones. Checks are enabled by default. Use client.with_auto_update(false) or WAVEFORM_CLIENT_AUTO_UPDATE=false to opt out. client.update_status() exposes the last outcome. A failure leaves the API result unchanged, and cancelled attempts retain their hourly throttle.

When a newer silicon-waveform-client release exists, maintenance runs cargo update -p silicon-waveform-client --precise <version> against the nearest consuming Cargo manifest. This updates its lockfile for the next build; it cannot replace library code already loaded in the current process. Unpublished packages or incompatible dependency constraints produce a failed maintenance status. No publish or installation was performed during local tests.

TTS temporary_url is optional. Published Briefcase one-shot uploads return a permanent authenticated URL. Test-plane TTS uses the same upload adapter and also returns temporary_url: null.

Personal provider keys saved through put_provider_key are selected by the backend for that authenticated account and plane. A matching personal key replaces the deployment key for that provider; other providers retain their own configured keys. Key storage errors stop the operation, and deleting a personal key restores deployment-key selection on subsequent requests.

Polling a running speech operation

Create a UUID and use client.with_speech_request_id(id)? for that logical speech operation. It sends X-Request-ID on TTS/STT requests; authentication, preferences and history calls remain independent. Use a fresh UUID for a new operation and retain the original UUID and idempotency key for a retry.

Run the synchronous speech future concurrently with client.wait_for_job(&id.to_string(), org, actor, timeout, interval). The polling method retries an initial 404 while authorization and job creation are pending. Its timeout covers HTTP requests as well as polling delays. It returns the job record for either terminal state; inspect status and error_code. A successful speech response retains the canonical ID if an idempotency key already existed.

TtsRequest.voice_profile: Option<String> selects a profile for one generation. voice_profiles(org, actor) returns a typed catalog. update_preferences_with_voice(org, actor, tts_order, stt_order, voice_profile) updates defaults atomically; the existing update_preferences method preserves the saved voice. TTS responses and jobs expose optional VoiceProfileRef metadata.

Reporting and settings

report(message, pr, idempotency_key) submits an authenticated report, with simulated delivery in sandboxes. set_telemetry(org, actor, enabled) controls the account opt-out. telemetry::from_environment() provides an optional Space Station sender for embedding programs; only record safe action labels and outcomes.