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.

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.

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.

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.

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