Expand description
SDK for Kival.
§Kival SDK
kival-sdk is the official Rust SDK for Kival, a self-hosted collaborative knowledge system for organizations. It provides typed API access for applications, integrations, automation, and agents through Kival’s serializable wire types and an asynchronous HTTP client built on tower::Service.
The client classifies unsuccessful HTTP responses before they reach user-provided middleware. Timeouts, retries, tracing, metrics, and circuit breakers can therefore operate on structured ClientError values without reimplementing Kival’s response handling.
§Features
The client feature is enabled by default and includes:
- the asynchronous Reqwest client;
- the Tower transport stack;
- middleware and custom transport support.
Disable default features to use only Kival’s wire types:
[dependencies]
kival-sdk = { version = "0.1", default-features = false }This is useful for servers, schema tooling, and other crates that serialize Kival data without making outbound requests.
§Creating a client
use kival_sdk::{ClientBuilder, ClientError, WorkspaceListParams};
async fn list_workspaces() -> Result<(), ClientError> {
let client = ClientBuilder::new()
.with_api_key(
std::env::var("KIVAL_API_KEY")
.expect("KIVAL_API_KEY is required"),
)
.connect("https://kival.example")?;
let workspaces = client
.list_workspaces(&WorkspaceListParams::default())
.await?;
println!("Found {} workspaces", workspaces.items.len());
Ok(())
}The server URL must be an HTTP or HTTPS origin root:
https://kival.examplePath prefixes, embedded credentials, query strings, and fragments are rejected instead of being silently discarded.
§Middleware
Add Tower middleware with ClientBuilder::layer:
use std::time::Duration;
use kival_sdk::{ClientBuilder, ClientError};
use tower::timeout::TimeoutLayer;
fn main() -> Result<(), ClientError> {
let client = ClientBuilder::new()
.layer(TimeoutLayer::new(Duration::from_secs(10)))
.connect("https://kival.example")?;
Ok(())
}Layer ordering follows tower::ServiceBuilder. The first layer added receives the request first.
For:
ClientBuilder::new()
.layer(A)
.layer(B)requests flow through:
A → B → transportResponses and errors flow back through:
transport → B → AMiddleware errors must be convertible into ClientError. Tower’s boxed errors are supported directly. Custom middleware can use ClientError::transport or implement From<YourError> for ClientError.
§Custom transports
ClientBuilder::connect_with_transport accepts any compatible Tower service over reqwest::Request.
Custom transports are useful for:
- deterministic tests;
- request recording;
- alternate HTTP executors;
- specialized transport instrumentation.
Use KivalClient::boxed to erase a concrete transport stack into BoxTransport. This is useful when clients with different middleware stacks must share a common type.
§Authentication
Pass an API key with ClientBuilder::with_api_key.
Authenticated operations reject missing credentials before executing the transport. Public health and readiness requests never include the configured API key.
Authorization headers are marked as sensitive in Reqwest, so their values are redacted from ordinary request debug output.
§Realtime invalidations
API keys with realtime:read may connect to Kival’s authenticated realtime endpoint:
wss://kival.example/api/v1/realtime
Authorization: Bearer <token>Object-scoped messages additionally require objects:read or objects:write, the workspace must be delegated to the key, and the owning user must still be able to view the object. events:read remains an independent capability. Personal inbox invalidations are delivered only to interactive browser sessions.
The WebSocket carries lightweight invalidations. Fetch authoritative state through the HTTP client, assume messages may be delayed, duplicated, missed, or reordered, and resynchronize after reconnecting. Kival does not provide WebSocket replay.
The Rust SDK exports RealtimeMessage for decoding the wire payload. A WebSocket client used with an API key must send the bearer token in the handshake Authorization header.
§Errors
ClientError::Api preserves the information needed to inspect and classify a Kival API failure:
- the HTTP status;
- a semantic
ApiErrorKind; - Kival’s stable error code, when present;
- the human-readable error message;
- the raw
Retry-Afterheader, when present.
Error response bodies are bounded before being retained. Transport and middleware failures preserve their underlying source through TransportError.
§Attachments
The buffered attachment methods are convenient for ordinary payloads:
upload_object_attachmentget_object_attachment_content
For large payloads, use the streaming alternatives:
upload_object_attachment_bodyaccepts areqwest::Body;get_object_attachment_content_responsereturns the response for incremental consumption.
§License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Re-exports§
pub use client::ApiError;clientpub use client::ApiErrorKind;clientpub use client::BaseUrlError;clientpub use client::BoxTransport;clientpub use client::BoxTransportFuture;clientpub use client::ClientBuilder;clientpub use client::ClientError;clientpub use client::DefaultTransport;clientpub use client::HttpTransport;clientpub use client::KivalClient;clientpub use client::MapTransportError;clientpub use client::ObjectVersionIdentifier;clientpub use client::ResponseTransport;clientpub use client::Transport;clientpub use client::TransportError;clientpub use client::TransportErrorKind;clientpub use client::UrlError;clientpub use wire::API_PREFIX;pub use wire::ApiErrorBody;pub use wire::ApiErrorResponse;pub use wire::ApiKey;pub use wire::ApiKeyListResponse;pub use wire::ApiKeyResponse;pub use wire::AuthenticatedSessionResponse;pub use wire::BacklinkSourceObject;pub use wire::COMMENT_BODY_MAX_CHARS;pub use wire::COMMENT_MENTION_MAX_USERS;pub use wire::Comment;pub use wire::CommentAuthor;pub use wire::CommentListResponse;pub use wire::CommentMention;pub use wire::CommentMentionCandidate;pub use wire::CommentMentionCandidateListResponse;pub use wire::CommentMentionCandidateParams;pub use wire::CommentResponse;pub use wire::CommentThread;pub use wire::CommentThreadListResponse;pub use wire::CommentThreadResponse;pub use wire::CreateApiKeyRequest;pub use wire::CreateApiKeyResponse;pub use wire::CreateCommentRequest;pub use wire::CreateGroupMembershipRequest;pub use wire::CreateGroupRequest;pub use wire::CreateObjectEdgeRequest;pub use wire::CreateObjectGrantRequest;pub use wire::CreateObjectRequest;pub use wire::CreateWorkspaceGroupRequest;pub use wire::CreateWorkspaceMembershipRequest;pub use wire::CreateWorkspaceRequest;pub use wire::DEFAULT_LIMIT;pub use wire::Event;pub use wire::EventListParams;pub use wire::FavoriteState;pub use wire::GraphEdgeKind;pub use wire::Group;pub use wire::GroupListParams;pub use wire::GroupMembership;pub use wire::GroupMembershipResponse;pub use wire::GroupResponse;pub use wire::InboxEntry;pub use wire::InboxListParams;pub use wire::InboxUnreadCountResponse;pub use wire::InboxUpdatedResponse;pub use wire::ListParams;pub use wire::ListResponse;pub use wire::MAX_LIMIT;pub use wire::MarkInboxReadRequest;pub use wire::ObjectAttachment;pub use wire::ObjectAttachmentResponse;pub use wire::ObjectBacklink;pub use wire::ObjectBacklinkReference;pub use wire::ObjectBacklinksParams;pub use wire::ObjectBacklinksResponse;pub use wire::ObjectEdge;pub use wire::ObjectEdgeResponse;pub use wire::ObjectGrant;pub use wire::ObjectGrantResponse;pub use wire::ObjectGraphEdge;pub use wire::ObjectGraphNode;pub use wire::ObjectGraphParams;pub use wire::ObjectGraphResponse;pub use wire::ObjectGraphTruncation;pub use wire::ObjectListItem;pub use wire::ObjectListParams;pub use wire::ObjectNotificationPreference;pub use wire::ObjectResource;pub use wire::ObjectResponse;pub use wire::ObjectVersion;pub use wire::ObjectVersionResponse;pub use wire::ObjectVersionWikilink;pub use wire::ObjectVersionWikilinksResponse;pub use wire::PatchField;pub use wire::PinState;pub use wire::RealtimeMessage;pub use wire::ReuseObjectAttachmentRequest;pub use wire::SearchHit;pub use wire::SearchParams;pub use wire::SearchResponse;pub use wire::SearchTermCoverage;pub use wire::Session;pub use wire::SessionListResponse;pub use wire::SessionOnlyResponse;pub use wire::Status;pub use wire::StatusResponse;pub use wire::UpdateApiKeyRequest;pub use wire::UpdateCommentRequest;pub use wire::UpdateGroupMembershipRequest;pub use wire::UpdateGroupRequest;pub use wire::UpdateInboxEntryRequest;pub use wire::UpdateObjectGrantRequest;pub use wire::UpdateObjectNotificationPreferenceRequest;pub use wire::UpdateObjectRequest;pub use wire::UpdateUserRequest;pub use wire::UpdateWorkspaceMembershipRequest;pub use wire::UpdateWorkspaceRequest;pub use wire::UploadObjectAttachmentParams;pub use wire::User;pub use wire::UserListParams;pub use wire::UserResponse;pub use wire::WhoamiResponse;pub use wire::Workspace;pub use wire::WorkspaceGraphEdge;pub use wire::WorkspaceGraphLimits;pub use wire::WorkspaceGraphNode;pub use wire::WorkspaceGraphParams;pub use wire::WorkspaceGraphResponse;pub use wire::WorkspaceGroup;pub use wire::WorkspaceGroupListParams;pub use wire::WorkspaceGroupResponse;pub use wire::WorkspaceListItem;pub use wire::WorkspaceListParams;pub use wire::WorkspaceMembership;pub use wire::WorkspaceMembershipResponse;pub use wire::WorkspaceResponse;
Modules§
Enums§
- ApiKey
Scope - Capability granted to an API key.
- Archive
List Status - Archive status filter for collection queries.
- Archive
Status - Archive lifecycle status shared by archivable resources.
- Comment
Status - Current lifecycle state of a comment body.
- Event
Order - Event sequence ordering.
- Grant
Principal - Principal targeted by an object grant.
- Membership
Role - Membership role for groups and workspaces.
- Object
Graph Direction - Traversal direction for an object-centered graph.
- Object
List Order - Sort order for object collection queries.
- Object
Role - Object permission role.
- Search
Category - Search document category.
- Search
Match Kind - Search match classification.
- Search
Mode - Search matching mode.
- User
List Status - User lifecycle selector for administration queries.
- User
Status - User lifecycle status.