use std::fmt;
use std::str::FromStr;
use serde::de::Error as _;
use serde::{Deserialize, Deserializer, Serialize};
const COMPANY_PREFIX: &str = "co_";
const DOCUMENT_PREFIX: &str = "doc_";
const TOKEN_LENGTH: usize = 26;
const CROCKFORD_LOWER: &str = "0123456789abcdefghjkmnpqrstvwxyz";
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
#[serde(transparent)]
pub struct CompanyId(String);
impl CompanyId {
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for CompanyId {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.0)
}
}
impl FromStr for CompanyId {
type Err = &'static str;
fn from_str(value: &str) -> Result<Self, Self::Err> {
let token = value
.strip_prefix(COMPANY_PREFIX)
.ok_or("company IDs must begin with co_")?;
if token.len() != TOKEN_LENGTH {
return Err("company IDs must contain a 26-character token");
}
if !matches!(token.as_bytes().first(), Some(b'0'..=b'7')) {
return Err("company ID token must encode exactly 128 bits");
}
if !token
.chars()
.all(|character| CROCKFORD_LOWER.contains(character))
{
return Err("company IDs use canonical lowercase Crockford Base32");
}
Ok(Self(value.to_owned()))
}
}
impl<'de> Deserialize<'de> for CompanyId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Self::from_str(&value).map_err(D::Error::custom)
}
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize)]
#[serde(transparent)]
pub struct DocumentId(String);
impl DocumentId {
pub fn as_str(&self) -> &str {
&self.0
}
}
impl fmt::Display for DocumentId {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.0)
}
}
impl FromStr for DocumentId {
type Err = &'static str;
fn from_str(value: &str) -> Result<Self, Self::Err> {
let token = value
.strip_prefix(DOCUMENT_PREFIX)
.ok_or("document IDs must begin with doc_")?;
if token.len() != TOKEN_LENGTH {
return Err("document IDs must contain a 26-character token");
}
if !matches!(token.as_bytes().first(), Some(b'0'..=b'7')) {
return Err("document ID token must encode exactly 128 bits");
}
if !token
.chars()
.all(|character| CROCKFORD_LOWER.contains(character))
{
return Err("document IDs use canonical lowercase Crockford Base32");
}
Ok(Self(value.to_owned()))
}
}
impl<'de> Deserialize<'de> for DocumentId {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
let value = String::deserialize(deserializer)?;
Self::from_str(&value).map_err(D::Error::custom)
}
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Envelope<T> {
pub data: T,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CallerResource {
pub object: String,
pub credential_id: String,
pub organization_id: String,
pub principal_type: String,
#[serde(default)]
pub scopes: Vec<String>,
pub limits: CallerLimits,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CallerLimits {
pub max_search_results: u16,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CompanyLifecycle {
pub status: String,
#[serde(default)]
pub canonical_id: Option<CompanyId>,
#[serde(default)]
pub successor_ids: Vec<CompanyId>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CompanyIdentifier {
pub scheme: String,
pub value: String,
#[serde(default)]
pub country_scope: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CompanyResource {
pub id: CompanyId,
pub object: String,
pub lifecycle: CompanyLifecycle,
#[serde(default)]
pub name: Option<String>,
#[serde(default)]
pub summary: Option<String>,
#[serde(default)]
pub country_code: Option<String>,
#[serde(default)]
pub company_status: Option<String>,
#[serde(default)]
pub company_type: Option<String>,
#[serde(default)]
pub industry: Option<String>,
#[serde(default)]
pub business_model: Option<String>,
#[serde(default)]
pub product_category: Option<String>,
#[serde(default)]
pub operating_geography: Option<String>,
#[serde(default)]
pub as_of_date: Option<String>,
#[serde(default)]
pub identifiers: Vec<CompanyIdentifier>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct OfficerSource {
pub system: String,
#[serde(default)]
pub url: Option<String>,
#[serde(default)]
pub title: Option<String>,
#[serde(default)]
pub published_at: Option<String>,
#[serde(default)]
pub observed_at: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CompanyOfficerResource {
pub object: String,
pub name: String,
#[serde(default)]
pub roles: Vec<String>,
#[serde(default)]
pub appointed_on: Option<String>,
#[serde(default)]
pub resigned_on: Option<String>,
pub source: OfficerSource,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct CompanyOfficerPage {
pub object: String,
pub requested_company_id: CompanyId,
pub company_id: CompanyId,
pub data: Vec<CompanyOfficerResource>,
pub has_more: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DocumentLifecycle {
pub status: String,
#[serde(default)]
pub canonical_id: Option<DocumentId>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DocumentSource {
pub system: String,
pub record_id: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DocumentAccessCapabilities {
pub metadata: bool,
pub bytes: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct DocumentResource {
pub id: DocumentId,
pub object: String,
pub lifecycle: DocumentLifecycle,
pub company_id: CompanyId,
pub source: DocumentSource,
pub document_type: String,
#[serde(default)]
pub document_category: Option<String>,
#[serde(default)]
pub title: Option<String>,
#[serde(default)]
pub file_name: Option<String>,
#[serde(default)]
pub content_type: Option<String>,
#[serde(default)]
pub file_extension: Option<String>,
#[serde(default)]
pub sha256: Option<String>,
#[serde(default)]
pub byte_size: Option<u64>,
#[serde(default)]
pub filed_at: Option<String>,
#[serde(default)]
pub published_date: Option<String>,
#[serde(default)]
pub published_at: Option<String>,
pub collected_at: String,
pub availability: String,
pub access: DocumentAccessCapabilities,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ExternalIdentifierSelector {
pub scheme: String,
pub value: String,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ResolveCompanyRequest {
#[serde(skip_serializing_if = "Option::is_none")]
pub id: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub domain: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub jurisdiction: Option<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub identifiers: Vec<ExternalIdentifierSelector>,
pub limit: u16,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ResolutionCandidate {
pub id: CompanyId,
#[serde(default)]
pub match_reasons: Vec<String>,
#[serde(default)]
pub name: Option<String>,
#[serde(default)]
pub jurisdiction: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct ResolutionResource {
pub object: String,
pub status: String,
#[serde(default)]
pub result: Option<ResolutionCandidate>,
#[serde(default)]
pub candidates: Vec<ResolutionCandidate>,
#[serde(default)]
pub requested_id: Option<CompanyId>,
#[serde(default)]
pub canonical_id: Option<CompanyId>,
#[serde(default)]
pub successor_ids: Vec<CompanyId>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
pub struct CompanyFilters {
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub countries: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub company_status: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub company_types: Vec<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub financial: Option<FinancialRange>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum FinancialField {
Revenue,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ReportingScope {
Company,
Group,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct FinancialRange {
pub field: FinancialField,
pub gte: Option<i64>,
pub lte: Option<i64>,
pub currency: String,
pub fiscal_year: i32,
pub reporting_scope: ReportingScope,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CompanyInclude {
Profile,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct SearchCompaniesRequest {
#[serde(skip_serializing_if = "Option::is_none")]
pub query: Option<String>,
pub filters: CompanyFilters,
pub include: Vec<CompanyInclude>,
#[serde(skip_serializing_if = "Option::is_none")]
pub cursor: Option<String>,
pub limit: u16,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct CompanySearchItem {
#[serde(flatten)]
pub company: CompanyResource,
#[serde(default)]
pub relevance_score: Option<f32>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct CompanyPage {
pub data: Vec<CompanySearchItem>,
#[serde(default)]
pub next_cursor: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Problem {
pub r#type: String,
pub title: String,
pub status: u16,
pub detail: String,
pub instance: String,
pub request_id: String,
pub code: String,
pub retryable: bool,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn company_id_accepts_only_the_public_canonical_grammar() {
let valid = "co_014d2pf2dbsqqg28t5cy4tqkff";
assert_eq!(CompanyId::from_str(valid).unwrap().as_str(), valid);
for invalid in [
"018f6d3d-11a3-7c22-9c8f-3e64e1e7fa83",
"co_814d2pf2dbsqqg28t5cy4tqkff",
"co_014D2pf2dbsqqg28t5cy4tqkff",
"co_014d2pf2dbsqqg28t5cy4tqkfi",
"fact_014d2pf2dbsqqg28t5cy4tqkff",
] {
assert!(CompanyId::from_str(invalid).is_err(), "accepted {invalid}");
}
}
#[test]
fn additive_fields_and_unknown_lifecycle_values_remain_compatible() {
let json = r#"{
"id":"co_014d2pf2dbsqqg28t5cy4tqkff",
"object":"company",
"lifecycle":{"status":"future_status","future_link":"co_x"},
"name":"Example",
"future_field":{"nested":true}
}"#;
let company: CompanyResource = serde_json::from_str(json).unwrap();
assert_eq!(company.lifecycle.status, "future_status");
assert_eq!(company.name.as_deref(), Some("Example"));
}
#[test]
fn standalone_document_response_matches_the_owned_client_contract() {
let envelope: Envelope<DocumentResource> =
serde_json::from_str(crate::client::TEST_DOCUMENT_METADATA).unwrap();
assert_eq!(envelope.data.id.as_str(), "doc_014d2pf2dbsqqg28t5cy4tqkff");
assert!(envelope.data.access.metadata);
assert!(!envelope.data.access.bytes);
}
}