Crate wavekat_platform_client 

Rust client for the WaveKat platform.

Reusable across consumers (the wavekat-cli binary wk, the WaveKat desktop daemon, future WaveKat tools) so platform auth and HTTP plumbing have one implementation, not many.

Quick start

use wavekat_platform_client::{loopback_handshake, Client, HandshakeOptions};

let pending = loopback_handshake(
    "https://platform.wavekat.com",
    HandshakeOptions::default(),
)?;
println!("Open: {}", pending.url());
let outcome = pending.wait().await?;

let client = Client::new("https://platform.wavekat.com", outcome.token)?;
let me = client.whoami().await?;
println!("signed in as {}", me.login);

What this crate is (and isn’t)

• Storage-agnostic. Client::new(base_url, token) is the contract. The crate never reads or writes disk; consumers pick where the token lives (config file, OS keychain, env var, in-memory test fixture).
• Browser-agnostic. loopback_handshake returns the sign-in URL; the caller decides how to open it (webbrowser::open, shell.openExternal, println!, …).
• Runtime-light. Async surface uses reqwest; consumers bring their own tokio runtime.

Structs

Client

HTTP client with the bearer token baked into its default headers.

HandshakeOptions

Tunables for loopback_handshake.

HandshakeOutcome

Result of a successful handshake.

InstallHeartbeatRequest

Body of POST /api/voice/installs/heartbeat. The daemon supplies install_id + app_version; Client::install_heartbeat fills the environment fields from SystemInfo::detect.

InstallHeartbeatResponse

The platform’s view of an install row, echoed back from a heartbeat.

Me

The signed-in user, as returned by GET /api/me.

Page

One page of GET /api/voice/{R}.

PendingHandshake

In-flight handshake. Returned by loopback_handshake before the caller decides how to surface the URL.

ReleaseCredential

Everything a release build needs to sign requests: the per-version private key, its public key, the master-issued certificate over that public key, and the version the certificate is bound to.

RequestSignature

The freshness/identity values produced when signing a request: the unix-seconds timestamp and per-request nonce the signature covers, plus the hex Ed25519 signature itself. Returned by ReleaseCredential::sign_request; the caller sends these in the X-WK-Sig-Ts / X-WK-Sig-Nonce / X-WK-Sig headers.

ShareRecordingRequest

Body of POST /api/voice/recordings/{id}/share — create or update a recording’s share. The recording must already be synced (metadata + bytes) or the platform returns 404.

ShareRecordingResponse

The platform’s response to a successful share command. share_url is the full https link the user copies; token is the opaque capability identifier embedded in it (returned separately so the daemon can store it for display without re-parsing the URL).

SyncEnvelope

Wire-level envelope that every sync record carries.

SyncRequest

Body shape for POST /api/voice/{R}/sync.

SyncResponse

Response from POST /api/voice/{R}/sync.

SystemInfo

Best-effort snapshot of the host environment, detected at call time. Every field is best-effort; a probe that fails contributes None (or, for the always-available os / arch, the compile-time target) rather than failing the heartbeat.

Token

Bearer token used to authenticate against the platform.

VoiceAccountRecord

One SIP account line’s configuration as it crosses the wire from a device up to the platform and back down to another device (wavekat-voice/docs/40-account-config-sync.md).

VoiceAccounts

Marker for the /api/voice/accounts/{sync,list} endpoint pair.

VoiceAccountsQuery

Query params for GET /api/voice/accounts. All fields optional.

VoiceCallRecord

One historical call as it crosses the wire from the daemon up to the platform.

VoiceCalls

Marker for the /api/voice/calls/{sync,list} endpoint pair.

VoiceCallsQuery

Query params for GET /api/voice/calls. All fields optional — the default returns the newest page.

VoiceRecordingRecord

One per-call recording’s metadata as it crosses the wire from the daemon up to the platform. The WAV bytes ride on a separate follow-up call (Client::upload_recording_bytes) so the idempotent metadata sync stays small and a flaky bytes upload doesn’t force the daemon to re-ship the row.

VoiceRecordingSyncItem

One item in the platform’s response to POST /api/voice/recordings/sync. Lets the daemon learn the R2 key the platform stamped (so a subsequent bytes PUT can target it) without re-deriving it, and check whether bytes have already landed on a prior cycle (so the daemon can mark the local row synced without re-uploading the WAV).

VoiceRecordings

Marker for the /api/voice/recordings/{sync,list} endpoint pair.

VoiceRecordingsQuery

Query params for GET /api/voice/recordings.

VoiceRecordingsSyncResponse

Full response from POST /api/voice/recordings/sync. Superset of the generic crate::SyncResponse — see Client::sync_recordings.

VoiceTranscriptRecord

One ASR transcript segment (“final” in wavekat-asr parlance) as it crosses the wire. Each segment is a row on the daemon side (transcripts table); the daemon batches a slice of them per upload and the platform upserts per (user_id, source_id).

VoiceTranscripts

Marker for the /api/voice/transcripts/{sync,list} endpoint pair.

VoiceTranscriptsQuery

Query params for GET /api/voice/transcripts — required call_source_id (the endpoint refuses a flat list).

Enums

Error

All errors surfaced by the crate.

ShareVisibility

Access tier for a shared recording, mirroring Loom’s model. Wire-stable snake_case strings — the platform’s Zod schema validates against this exact list, so a rename here would bounce every share command with a 400.

VoiceCallDirection

Inbound vs. outbound. Wire-stable snake_case strings — never renumber or rename. New states (e.g. internal) would be a wire addition, not a replacement.

VoiceCallDisposition

User-visible disposition. Derived from VoiceCallEndReason by the daemon; the platform stores both, so future UI surfaces can read either without re-deriving.

VoiceCallEndReason

Finer-grained terminal reason — kept distinct from VoiceCallDisposition because the disposition collapses hangup_local and hangup_remote to Answered, losing the “who hung up?” answer the row otherwise carries.

VoiceTranscriptChannel

Wire-stable transcript channel tag. Matches the daemon’s TranscriptChannelLabel and events::TranscriptChannel.

VoiceTransport

SIP transport for a synced account line. Wire-stable snake_case; mirrors the daemon’s TransportKind.

Traits

HasSyncEnvelope

Records that carry a SyncEnvelope expose it via this trait so the bridge crate can stamp the schemaVersion field uniformly across resources. One-line impl per record type:

SyncEndpoint

One sync-able platform resource.

Functions

cert_payload

The certificate payload the master key signs to bless a per-version public key. Binding the version in means a cert can’t be reused to vouch for a key under a different (e.g. un-revoked) version.

generate_keypair

A freshly generated Ed25519 keypair as hex (private_hex, public_hex).

generate_master

Generate the offline release master keypair. Identical to generate_keypair — named for intent at the call site (the master is generated once, by hand, and its private half guarded as a CI secret).

issue_release_credential

Issue a ReleaseCredential for version: generate a per-version keypair and sign its certificate with the master private key (master_private_key_hex). Run by CI at release time.

loopback_handshake

Bind the loopback listener and compute the platform sign-in URL.

verify_cert

Verify that cert_hex is a valid master signature over cert_payload(version, public_key_hex). The platform performs the equivalent check in TypeScript; this Rust copy backs the round-trip tests and documents the exact bytes.

verify_request

Verify a request signature against a per-version public key.

Type Aliases

Result