#![forbid(unsafe_code)]
#![warn(missing_debug_implementations)]
pub mod client;
pub mod error;
pub mod models;
pub use client::{
Analytics, Bundle, CabalSpy, CabalSpyBuilder, Calls, CallsOpts, FeedOpts, LeaderboardOpts, Signals, SignalOpts,
System, Tokens, Transactions, Wallets, BATCH_MAX_ADDRESSES, BATCH_MAX_MINTS, DEFAULT_BASE_URL,
DEFAULT_WS_URL, DEMO_API_KEY,
};
pub use error::{ApiErrorBody, Error, RateLimit, Result};
pub use models::{
ActiveTokensSummary, AnalyticsMode, BestCall, BundleEntry, BundlePosition, BundleResponse, BundleWallet,
Call, CallPerformance, CallStatsBlock, CallStatsPeriod, CallStatsResponse, CallTier, CallToken,
CallTrigger, CallWallet, Chain, CountResponse, DemoInfo, DemoUpgrade, Envelope, FeedTransaction, HealthResponse, HoldingsAfter, MetaResponse,
Pagination, Period, PeriodStats, ResponseMeta, Signal, SignalMode, SignalTokenBlock,
SignalWallet, SignalWindow, SignalsResponse, TokenBlock, TokenStats, TokenTrader, TotalHolders,
TotalHoldings, TraderHoldings, TraderStats, TransactionsList, VolumeResponse, WalletProfile,
WalletTracker, WalletType, WinRateDistribution, CHAINS,
};
pub fn parse_api_timestamp(value: &str) -> Option<i64> {
let text = value.trim();
let bytes = text.as_bytes();
if bytes.len() < 19 {
return None;
}
if !matches!(bytes[10], b' ' | b'T') {
return None;
}
let num = |from: usize, to: usize| -> Option<i64> { text.get(from..to)?.parse::<i64>().ok() };
let year = num(0, 4)?;
let month = num(5, 7)?;
let day = num(8, 10)?;
let hour = num(11, 13)?;
let minute = num(14, 16)?;
let second = num(17, 19)?;
if !(1..=12).contains(&month) || !(1..=31).contains(&day) {
return None;
}
if hour > 23 || minute > 59 || second > 60 {
return None;
}
Some(days_from_civil(year, month, day) * 86_400 + hour * 3_600 + minute * 60 + second)
}
fn days_from_civil(year: i64, month: i64, day: i64) -> i64 {
let year = if month <= 2 { year - 1 } else { year };
let era = if year >= 0 { year } else { year - 399 } / 400;
let year_of_era = year - era * 400;
let doy = (153 * (if month > 2 { month - 3 } else { month + 9 }) + 2) / 5 + day - 1;
let doe = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + doy;
era * 146_097 + doe - 719_468
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn timestamps_are_read_as_utc() {
assert_eq!(parse_api_timestamp("2026-07-25 21:33:14"), Some(1785015194));
assert_eq!(parse_api_timestamp("2026-07-25T21:33:14Z"), Some(1785015194));
assert_eq!(parse_api_timestamp("1970-01-01 00:00:00"), Some(0));
assert_eq!(parse_api_timestamp("2000-02-29 12:00:00"), Some(951825600));
}
#[test]
fn bad_timestamps_return_none() {
assert_eq!(parse_api_timestamp(""), None);
assert_eq!(parse_api_timestamp("nonsense"), None);
assert_eq!(parse_api_timestamp("2026-13-01 00:00:00"), None);
assert_eq!(parse_api_timestamp("2026-07-25"), None);
}
#[test]
fn chains_know_their_wallet_types() {
assert!(Chain::Solana.supports(WalletType::Whale));
assert!(!Chain::Eth.supports(WalletType::Whale));
assert!(!Chain::Base.supports(WalletType::Whale));
assert!(Chain::Rh.supports(WalletType::Smart));
assert_eq!(Chain::Eth.wallet_types().len(), 1);
assert_eq!(Chain::Solana.currency(), "SOL");
assert_eq!(Chain::Rh.currency(), "ETH");
assert!(Chain::Solana.has_rest_marketcap());
assert!(!Chain::Base.has_rest_marketcap());
}
#[test]
fn enums_serialize_to_the_wire_format() {
assert_eq!(Chain::Rh.as_str(), "rh");
assert_eq!(Period::D30.as_str(), "30d");
assert_eq!(AnalyticsMode::TopPerformers.as_str(), "top_performers");
assert_eq!(SignalMode::Cluster.as_str(), "cluster");
assert_eq!(serde_json::to_string(&Chain::Bnb).unwrap(), "\"bnb\"");
assert_eq!(serde_json::to_string(&Period::H6).unwrap(), "\"6h\"");
assert_eq!(
serde_json::to_string(&AnalyticsMode::WinRate).unwrap(),
"\"win_rate\""
);
}
#[test]
fn responses_survive_missing_and_unknown_fields() {
let raw = r#"{
"token": {"mint": "abc", "market_cap": null, "price_usd": null},
"total_holders": {"kol_count": 2},
"some_field_added_later": {"nested": true}
}"#;
let stats: TokenStats = serde_json::from_str(raw).unwrap();
assert_eq!(stats.token.mint.as_deref(), Some("abc"));
assert_eq!(stats.token.market_cap, None);
assert_eq!(stats.total_holders.kol_count, Some(2));
assert!(stats.traders.is_empty());
assert!(stats.extra.contains_key("some_field_added_later"));
}
#[test]
fn calls_are_parsed() {
let raw = r#"[{
"call_id": "c_0123456789ab", "blockchain": "solana", "tier": "moderate",
"tier_label": "Moderate Gamble", "called_at": "2026-10-01T12:00:00Z",
"token": {"mint": "Mint1", "symbol": "EX", "name": "Example", "logo": null},
"market_cap_at_call": 25000.0,
"trigger": {"kol_count": 2, "smart_count": 1, "native_symbol": "SOL", "total_native": 9.5,
"wallets": [{"address": "W1", "type": "kol", "name": "", "amount_native": 6.0, "bought_at": null}]},
"performance": {"status": "pending", "peak_multiple": null},
"links": {"terminal": "https://app.cabalspy.xyz/token/Mint1"},
"timestamp": "2026-10-01T12:00:00Z"
}]"#;
let calls: Vec<Call> = serde_json::from_str(raw).unwrap();
assert_eq!(calls[0].tier, Some(CallTier::Moderate));
assert_eq!(calls[0].trigger.wallets[0].wallet_type, Some(WalletType::Kol));
assert_eq!(calls[0].performance.as_ref().unwrap().status.as_deref(), Some("pending"));
assert!(calls[0].extra.contains_key("timestamp"));
assert_eq!(CallTier::Whale.as_str(), "whale");
assert_eq!(CallStatsPeriod::D90.as_str(), "90d");
}
#[test]
fn a_null_total_does_not_break_pagination() {
let p: Pagination = serde_json::from_str(r#"{"limit": 50, "total": null, "has_more": true, "next_cursor": "x"}"#).unwrap();
assert_eq!(p.total, 0);
assert!(p.has_more);
}
#[test]
fn call_stats_are_parsed() {
let raw = r#"{"period": "7d", "totals": {"calls": 120, "evaluated": 112,
"hit_rate": {"2x": 45.5, "5x": null}, "median_peak_multiple": 1.9},
"chains": {"solana": {"calls": 120, "tiers": {"gamble": {"calls": 80}}}},
"best_calls": [{"call_id": "c_1", "mint": "M", "peak_multiple": 12.0}]}"#;
let s: CallStatsResponse = serde_json::from_str(raw).unwrap();
assert_eq!(s.totals.hit_rate["2x"], Some(45.5));
assert_eq!(s.totals.hit_rate["5x"], None);
assert_eq!(s.chains["solana"].tiers["gamble"].calls, 80);
assert_eq!(s.best_calls[0].peak_multiple, Some(12.0));
}
}