vynco

Rust SDK for the VynCo Swiss Corporate Intelligence API.

Access 320,000+ Swiss companies from the Zefix commercial registry with full-text search, change tracking, relationship mapping, AI-generated dossiers, and advanced analytics.

Installation

[dependencies]
vynco = "1.0"

For the synchronous (blocking) client:

[dependencies]
vynco = { version = "1.0", features = ["blocking"] }

Quick Start

use vynco::{Client, CompanyListParams};

#[tokio::main]
async fn main() -> Result<(), vynco::VyncoError> {
    let client = Client::builder("vc_live_your_api_key")
        .build()?;

    // List companies with filtering
    let params = CompanyListParams {
        search: Some("Novartis".into()),
        canton: Some("BS".into()),
        ..Default::default()
    };
    let resp = client.companies().list(&params).await?;
    println!("Found {} companies", resp.data.total_count);
    println!("Credits used: {:?}", resp.meta.credits_used);

    // Get company by UID
    let company = client.companies().get("CHE-100.023.968").await?;
    println!("{}: {}", company.data.name, company.data.purpose);

    // Full-text search (FTS5)
    let results = client.companies().search(&vynco::CompanySearchRequest {
        query: "pharma".into(),
        limit: Some(10),
    }).await?;
    println!("Search returned {} results", results.data.len());

    // Check credit balance
    let balance = client.credits().balance().await?;
    println!("Balance: {} credits", balance.data.balance);

    Ok(())
}

Blocking Client

use vynco::blocking::Client;

fn main() -> Result<(), vynco::VyncoError> {
    let client = Client::builder("vc_live_your_api_key")
        .build()?;

    let balance = client.credits().balance()?;
    println!("Balance: {} credits", balance.data.balance);

    Ok(())
}

API Coverage

14 resource modules covering 52 endpoints:

Resource	Methods	Credits
companies()	list, get, count, statistics, search, batch, compare	1-5
changes()	list, by_company, statistics, by_sogc, review, batch	0-2
persons()	list, get, roles, connections, board_members, network_stats	3-10
dossiers()	list, get, generate, statistics	0-100
relationships()	for_company, hierarchy	10
news()	for_company, recent	1-2
reports()	for_company	5
analytics()	cluster, anomalies, cohorts, cantons, auditors, rfm_segments, velocity	3-25
watches()	list, create, remove, notifications	0
api_keys()	list, create, revoke	0
credits()	balance, usage, history	0
billing()	create_checkout, create_portal	0
teams()	me, create, members, invite_member, update_member_role, remove_member, billing_summary	0
health()	check	0

Response Metadata

Every response includes header metadata for credit tracking and rate limiting:

let resp = client.companies().get("CHE-100.023.968").await?;

println!("Request ID: {:?}", resp.meta.request_id);         // X-Request-Id
println!("Credits used: {:?}", resp.meta.credits_used);      // X-Credits-Used
println!("Credits remaining: {:?}", resp.meta.credits_remaining); // X-Credits-Remaining
println!("Rate limit: {:?}", resp.meta.rate_limit_limit);    // X-Rate-Limit-Limit
println!("Rate limit remaining: {:?}", resp.meta.rate_limit_remaining); // X-RateLimit-Remaining
println!("Rate limit reset: {:?}", resp.meta.rate_limit_reset); // X-RateLimit-Reset
println!("Data source: {:?}", resp.meta.data_source);        // X-Data-Source

Example CLI

A full CLI example is included to demonstrate real-world SDK usage:

export VYNCO_API_KEY="vc_live_your_api_key"

cargo run --example vynco_cli -- health                            # API health check
cargo run --example vynco_cli -- credits                           # Credit balance
cargo run --example vynco_cli -- team                              # Team info
cargo run --example vynco_cli -- companies --canton ZH --search "Novartis"  # List with filters
cargo run --example vynco_cli -- search "pharmaceutical"           # Full-text search
cargo run --example vynco_cli -- company CHE-105.805.649           # Lookup by UID
cargo run --example vynco_cli -- count --canton GE                 # Count companies
cargo run --example vynco_cli -- stats                             # Database statistics
cargo run --example vynco_cli -- changes                           # Recent changes

See examples/vynco_cli.rs for the full source.

Configuration

use std::time::Duration;

let client = Client::builder("vc_live_your_api_key")
    .base_url("https://api.vynco.ch/api/v1")  // default
    .timeout(Duration::from_secs(60))           // default: 30s
    .max_retries(3)                             // default: 2
    .build()?;

The client automatically retries on HTTP 429 (rate limited) and 5xx (server error) with exponential backoff (500ms x 2^attempt). It respects the Retry-After header when present.

Error Handling

All API errors are mapped to typed variants:

use vynco::VyncoError;

match client.companies().get("CHE-000.000.000").await {
    Ok(resp) => println!("{}", resp.data.name),
    Err(VyncoError::Authentication(_)) => println!("Invalid API key"),
    Err(VyncoError::InsufficientCredits(_)) => println!("Top up credits"),
    Err(VyncoError::Forbidden(_)) => println!("Insufficient permissions"),
    Err(VyncoError::NotFound(body)) => println!("Not found: {}", body.detail),
    Err(VyncoError::Validation(body)) => println!("Bad request: {}", body.detail),
    Err(VyncoError::Conflict(_)) => println!("Resource conflict"),
    Err(VyncoError::RateLimit(_)) => println!("Rate limited, retry later"),
    Err(VyncoError::Server(_)) => println!("Server error"),
    Err(e) => eprintln!("Error: {e}"),
}

Error bodies follow RFC 7807 Problem Details with error_type, title, detail, status, and message fields.

Feature Flags

Feature	Default	Description
rustls-tls	Yes	Use rustls for TLS (no OpenSSL dependency)
native-tls	No	Use the platform's native TLS stack
blocking	No	Enable the synchronous blocking client

Minimum Supported Rust Version

Rust 1.83 or later.

License

Apache-2.0