Skip to main content

Crate kival_sdk

Crate kival_sdk 

Source
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.example

Path 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 → transport

Responses and errors flow back through:

transport → B → A

Middleware 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-After header, 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_attachment
  • get_object_attachment_content

For large payloads, use the streaming alternatives:

  • upload_object_attachment_body accepts a reqwest::Body;
  • get_object_attachment_content_response returns 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;client
pub use client::ApiErrorKind;client
pub use client::BaseUrlError;client
pub use client::BoxTransport;client
pub use client::BoxTransportFuture;client
pub use client::ClientBuilder;client
pub use client::ClientError;client
pub use client::DefaultTransport;client
pub use client::HttpTransport;client
pub use client::KivalClient;client
pub use client::MapTransportError;client
pub use client::ObjectVersionIdentifier;client
pub use client::ResponseTransport;client
pub use client::Transport;client
pub use client::TransportError;client
pub use client::TransportErrorKind;client
pub use client::UrlError;client
pub 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::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::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§

clientclient
Client for Kival.
wire
Wire protocol for Kival.

Enums§

ApiKeyScope
Capability granted to an API key.
ArchiveListStatus
Archive status filter for collection queries.
ArchiveStatus
Archive lifecycle status shared by archivable resources.
CommentStatus
Current lifecycle state of a comment body.
EventOrder
Event sequence ordering.
GrantPrincipal
Principal targeted by an object grant.
MembershipRole
Membership role for groups and workspaces.
ObjectGraphDirection
Traversal direction for an object-centered graph.
ObjectListOrder
Sort order for object collection queries.
ObjectRole
Object permission role.
SearchCategory
Search document category.
SearchMatchKind
Search match classification.
SearchMode
Search matching mode.
UserListStatus
User lifecycle selector for administration queries.
UserStatus
User lifecycle status.