Skip to main content

Crate odp_directory

Crate odp_directory 

Source
Expand description

§odp-directory

Canonical directory client for the Offering Discovery Protocol.

This crate owns fixed production and sandbox Directory access, validated Service search results, facets, suggestions, and opaque continuation traversal. Its asynchronous client provides a Rustls-backed HTTP transport and permits callers to inject a compatible transport.

Use Environment::Production for https://directory.offeringprotocol.org or Environment::Sandbox for https://sandbox.inflowpay.ai. These are the only Directory origins accepted by the client.

use odp_core::{PaymentOption, Protocol};
use odp_directory::{
    DirectoryClient, Environment, IterationOptions, PaymentFilter, SearchRequest, ServiceFilters,
    SuggestionRequest,
};

let directory = DirectoryClient::new(Environment::Production)?;
let services = directory
    .collect_services(
        &SearchRequest {
            filters: Some(ServiceFilters {
                payments: vec![PaymentFilter {
                    authentication: None,
                    name: Protocol::Mpp,
                    options: vec![PaymentOption::Solana],
                }],
                ..ServiceFilters::default()
            }),
            query: "plants".to_owned(),
            ..SearchRequest::default()
        },
        IterationOptions {
            max_items: 10,
            max_pages: 2,
        },
    )
    .await?;

for service in services {
    println!("{}: {}", service.name, service.service_origin);
}

let suggestions = directory
    .suggest_services(&SuggestionRequest {
        limit: 5,
        prefix: "pla".to_owned(),
        ..Default::default()
    })
    .await?;

search_services returns one native ODP Service-only response. continue_search_services follows one opaque next reference. collect_services performs bounded Service-only traversal, stopping at the response or item limit without fetching another response. Search filters cover keywords, ODP operations, enrollment protocols, payment protocols, payment options, trust protocols, and the authentication requirements attached to operations and payments. Search responses can also carry facets for building data-driven filters without packaging the Directory’s current vocabulary into the Agent. Each returned Service preserves its enrollment, payment, and trust protocol advertisements. Unrecognized protocol descriptors are filtered while recognized descriptors remain strictly validated.

See the workspace guide and the ODP specification.

§Search Services and Collections

use odp_directory::{DirectoryClient, DirectoryResult, Environment, ResourceSearchRequest};

let directory = DirectoryClient::new(Environment::Production)?;
let response = directory.search(&ResourceSearchRequest {
    query: "weather forecast".to_owned(),
    limit: 25,
    ..ResourceSearchRequest::default()
}).await?;
for item in response.items {
    match item {
        DirectoryResult::Service(item) => println!("Service: {}", item.service.name),
        DirectoryResult::Collection(item) => println!("Collection: {} ({}, through {})",
            item.collection.name, item.collection.id, item.service.service_origin),
        DirectoryResult::Unknown { kind, .. } => println!("Unsupported result type: {kind}"),
    }
}
for issue in response.issues {
    eprintln!("Skipped result {}: {}", issue.index, issue.message);
}

ResourceSearchRequest.types can restrict results to ResultType::Service or ResultType::Collection. None selects both; explicit lists must be nonempty and distinct. Filters apply to the owning Service. An empty query is omitted, allowing browsing.

Collection identity is its owning service.service_id plus its case-sensitive Collection ID. Several OpenAPI documents can share an API origin without being the same Directory Service. The result’s indexed_at describes the Collection’s freshness; service.indexed_at describes the parent’s freshness. Both are timestamp strings. service.service_id identifies the Directory’s Service record. Service results may include optional publisher attribution with publisher_id, name, and website_url. The website is a display link, not a discovery or execution target. Omitted or null publisher attribution is accepted, and additional fields are preserved; Collection attribution is the owning service itself.

For service.source.source_type == "odp", inspect the owning Service’s live ODP document, then use the Agent client’s get_collection to retrieve current details. An OpenAPI Collection is a Directory presentation group, not an ODP operation target. Directory metadata is not authority to execute an Action or send credentials. Unknown future result types retain their full raw JSON and are not interpreted as Services. Malformed known results become indexed issues without discarding valid results. Additional fields are retained in additional maps.

Mixed results use DirectoryIndexedService, separate from the native DirectoryService returned by search_services. Each mixed Service requires service_id, service_origin, name, indexed_at and source. Imported descriptions and languages are optional; missing lists become empty vectors. Imported results do not expose native ODP operations. Native results retain ODP validation. Unverified execution fields such as http and payment_origins are not returned.

DirectorySource describes the document used for discovery:

  • source_type is "odp", "openapi", or an unknown future string. Unknown formats remain readable but must not be passed to ODP operations.
  • url is the exact document URL, including path and query. It may differ from the API origin; do not reconstruct it from service_origin.
  • x402_discovery records supporting fixed-path x402 discovery, not proof that an endpoint accepts payments. Advertised evidence remains in protocols.

The client does not fetch or execute OpenAPI documents.

§Filter by source

use odp_directory::{DirectoryClient, Environment, ResourceSearchRequest, ServiceFilters, SourceType, SuggestionRequest};

let directory = DirectoryClient::new(Environment::Production)?;
let filters = ServiceFilters {
    sources: Some(vec![SourceType::Openapi]),
    ..Default::default()
};
let results = directory.search(&ResourceSearchRequest {
    filters: Some(filters.clone()),
    query: "weather".to_owned(),
    ..Default::default()
}).await?;
let names = directory.suggest(&SuggestionRequest {
    filters: Some(filters),
    prefix: "we".to_owned(),
    ..Default::default()
}).await?;

sources: None omits the filter. An explicit list must contain one or both distinct SourceType::Odp and SourceType::Openapi values. Sources are alternatives, combined with other filter categories using AND; Collections inherit the owning Service’s source. Native search_services accepts the filter but remains ODP-only, so an OpenAPI-only filter yields no native matches. Unsupported source filter values are rejected during deserialization.

§Mixed search bounds and suggestions

Mixed search returns at most 100 results. limit: 0 omits the limit, using the server’s default of 100. The server does not currently offer continuation: absent next does not mean every match was returned. continue_search accepts an opaque same-origin continuation if one is supplied. Each call returns one response. Facets count all matching targets, not just returned items; a Service and two Collections count as three. Collection search does not depend on permission to display its card on the Directory landing page.

suggest sends POST /v1/directory/suggestions. SuggestionRequest.filters accepts the same ServiceFilters as search, including AEP, keywords, ODP operations, payments, sources and trust. Collection filters apply to their owning Service. Matching spans names, descriptions and keywords, but output contains deduplicated names of matching Services and Collections. Despite the argument name prefix, matching uses substrings and whitespace-separated alternative terms. suggest_services uses GET /v1/services/suggestions for Service-only keyword-prefix suggestions and does not accept filters. Both return strings from the server’s items array; the default and maximum limit are 25.

See the canonical Directory example.

§Migration

  • Mixed result service fields use DirectoryIndexedService; its required service_id is a field rather than an optional accessor. Native Service-only models are unchanged.

  • Explicit ServiceFilters literals include sources: None or ..Default::default().

  • Known mixed results require source metadata from the Directory. Missing sources are reported as item issues, not assumed to be ODP.

  • Service-only search calls become search_services; continue_search calls become continue_search_services.

  • Aggregating search_services(request, options) calls become collect_services(request, options).

  • search_pages is removed. To retain individual responses, call search_services followed by continue_search_services with an explicit application limit.

  • Service-only suggest calls become suggest_services.

  • search, continue_search, and suggest select mixed discovery.

Structs§

CollectionResult
CollectionSummary
DirectoryClient
DirectoryIndexedService
DirectoryIssue
DirectoryService
DirectorySource
Facet
Facets
HttpRequest
HttpResponse
IterationOptions
OperationFilter
PaymentFilter
PaymentOptionFacetValue
Publisher
ReqwestTransport
ResourceSearchRequest
SearchPage
SearchRequest
SearchResponse
ServiceFilters
ServiceIssue
A record the Directory published that this client would not hand back.
ServiceResult
SuggestionRequest
TransportError

Enums§

DirectoryError
DirectoryResult
Environment
ResultType
SourceType

Traits§

Transport