HiveHub.Cloud Internal SDK

Internal Rust SDK for Hive services (Vectorizer, Nexus, Synap, LessTokens) to communicate with the HiveHub.Cloud API.

Features

• Service Modules: Full support for Vectorizer, Nexus, Synap, and LessTokens services
• Access Key Management: Generate, list, get, and revoke service-specific access keys
• Quota Management: Check and update service quotas
• Usage Tracking: Track resource usage across all services
• Type-Safe: Fully typed request/response models with Serialize + Deserialize
• Async/Await: Built on Tokio for async operations
• Error Handling: Comprehensive error types with HTTP status code mapping
• 70+ Tests: Unit tests, integration tests with mock server, error handling tests

Installation

Add to your Cargo.toml:

[dependencies]
hivehub-internal-sdk = "1.0"
tokio = { version = "1.42", features = ["full"] }

Quick Start

use hivehub_internal_sdk::{HiveHubCloudClient, models::AccessKeyPermission};
use uuid::Uuid;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize client from environment
    let client = HiveHubCloudClient::from_env()?;

    // Or with explicit configuration
    let client = HiveHubCloudClient::new(
        "svc_api_key".to_string(),
        "http://localhost:12000".to_string(),
    )?;

    let user_id = Uuid::new_v4();

    // Use Vectorizer service
    let collections = client.vectorizer()
        .get_user_collections(&user_id)
        .await?;
    println!("Found {} collections", collections.total_collections);

    // Generate access keys
    let key = client.access_keys()
        .generate_vectorizer_key("my-key", vec![AccessKeyPermission::Read, AccessKeyPermission::Write])
        .await?;
    println!("Generated key: {}", key.access_key);

    Ok(())
}

Configuration

From Environment Variables

export HIVEHUB_CLOUD_SERVICE_API_KEY="svc_vectorizer_abc123"
export HIVEHUB_CLOUD_BASE_URL="http://localhost:12000"

let client = HiveHubCloudClient::from_env()?;

Services

Vectorizer

// Get user collections
let collections = client.vectorizer().get_user_collections(&user_id).await?;

// Validate collection ownership
let validation = client.vectorizer().validate_collection(&collection_id, &user_id).await?;

// Create collection
let result = client.vectorizer().create_collection(&user_id, &request).await?;

// Update usage
client.vectorizer().update_usage(&collection_id, &usage_request).await?;

Nexus

// Get user database info
let db_info = client.nexus().get_user_database(&user_id).await?;

// Check quota
let quota = client.nexus().check_quota(&request).await?;

// Consume credits
let result = client.nexus().consume_credits(&user_id, &request).await?;

Synap

// Get user resources
let resources = client.synap().get_user_resources(&user_id).await?;

// Create resource
let result = client.synap().create_resource(&user_id, &request).await?;

// Validate resource
let validation = client.synap().validate_resource(&name, &user_id, ResourceType::Queue).await?;

LessTokens

// Get user tokens
let tokens = client.lesstokens().get_user_tokens(&user_id).await?;

// Validate tokens
let validation = client.lesstokens().validate_tokens(&user_id, 1).await?;

// Consume tokens
let result = client.lesstokens().consume_tokens(&user_id, &request).await?;

// Check limit
let limit = client.lesstokens().check_limit(&user_id).await?;

Access Keys

use hivehub_internal_sdk::models::{ServiceType, AccessKeyPermission};

// Generate key
let key = client.access_keys()
    .generate_vectorizer_key("my-key", vec![AccessKeyPermission::Read])
    .await?;

// List keys
let keys = client.access_keys().list(Some(ServiceType::Vectorizer)).await?;

// Revoke key
client.access_keys().revoke(&key_id).await?;

Error Handling

use hivehub_internal_sdk::HiveHubCloudError;

match client.vectorizer().get_user_collections(&user_id).await {
    Ok(collections) => println!("Found {} collections", collections.total_collections),
    Err(HiveHubCloudError::Authentication(msg)) => eprintln!("Auth failed: {}", msg),
    Err(HiveHubCloudError::QuotaExceeded(msg)) => eprintln!("Quota exceeded: {}", msg),
    Err(HiveHubCloudError::NotFound(msg)) => eprintln!("Not found: {}", msg),
    Err(HiveHubCloudError::BadRequest(msg)) => eprintln!("Bad request: {}", msg),
    Err(HiveHubCloudError::ServiceUnavailable(msg)) => eprintln!("Service unavailable: {}", msg),
    Err(e) => eprintln!("Error: {}", e),
}

Testing

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

Documentation

• Full API documentation: /docs/specs/INTERNAL_SDK.md
• Generated docs: cargo doc --open

License

MIT