directory

ODP directory package

Package directory searches the one canonical ODP directory for candidate Services. It does not search Service catalogs. After discovery, an Agent inspects each result's live ODP document and queries that Service's Collections and Offerings.

The production origin is fixed at https://api.inflowpay.ai. Select Sandbox to use the fixed https://sandbox.inflowpay.ai environment. Callers cannot configure another origin.

Search Services

SearchServices lazily traverses directory pages and yields validated Service summaries. Filters are structured and work without natural-language interpretation.

directoryClient, err := directory.New(directory.Options{})
if err != nil {
	return err
}

request := directory.SearchRequest{
	Query: "compute",
	Filters: &directory.ServiceFilters{
		Keywords: []string{"gpu", "accelerator"},
		Payments: []directory.PaymentFilter{{
			Name: odp.ProtocolMPP,
			Options: []odp.PaymentOption{odp.PaymentOptionInflow, odp.PaymentOptionSolana},
		}},
	},
	Limit: 25,
}

for candidate, err := range directoryClient.SearchServices(ctx, request, directory.IterationOptions{}) {
	if err != nil {
		return err
	}
	fmt.Printf("%s: %s\n", candidate.Name, candidate.ServiceOrigin)
}

Options within one payment filter are alternatives. The example matches Services that accept either InFlow or Solana through MPP. A protocol-only PaymentFilter{Name: odp.ProtocolMPP} matches any Service that advertises MPP. Facets.Payments reports protocol counts, Facets.PaymentOptions reports each protocol-option count independently, and Facets.Trust reports trust protocol counts.

Use SearchPages when facet counts or page-level additive members are needed:

for page, err := range directoryClient.SearchPages(ctx, request, directory.IterationOptions{}) {
	if err != nil {
		return err
	}
	consume(page.Items, page.Facets)
}

Opaque continuation links are followed with GET on the selected canonical origin. A continuation that leaves that origin, repeats a page already visited, or cannot be resolved ends the traversal with an error. Stopping iteration stops network activity.

IterationOptions.MaxPages is the caller's page budget and defaults to 16. Reaching it ends the sequence without an error, and the last page keeps the Next that ContinueSearchPages or ContinueSearchServices resumes from:

var resume string
for page, err := range directoryClient.SearchPages(ctx, request, directory.IterationOptions{MaxPages: 4}) {
	if err != nil {
		return err
	}
	consume(page.Items, page.Facets)
	resume = page.Next
}
if resume != "" {
	for page, err := range directoryClient.ContinueSearchPages(ctx, resume, directory.IterationOptions{}) {
		// ...
	}
}

A budget above 10,000 pages is rejected, and a directory that offers a continuation for 10,000 consecutive pages ends the traversal with an error rather than quietly appearing exhausted. MaxItems bounds SearchServices at up to 10,000 results.

Malformed results

One unusable record does not discard the page it arrived on. A record that fails validation is omitted from Items and reported in SearchPage.Issues with its index and the reason; IterationOptions.OnIssue receives the same reports while iterating Services:

options := directory.IterationOptions{OnIssue: func(issue directory.Issue) {
	log.Printf("directory %s result %d: %s", issue.Scope, issue.Index, issue.Message)
}}

A malformed page envelope, by contrast, still fails the traversal.

Suggestions

Suggestions help an Agent discover keyword vocabulary without downloading a global keyword list.

suggestions, err := directoryClient.SuggestServices(ctx, directory.SuggestionRequest{
	Prefix: "gp",
	Limit:  5,
})

Sandbox

directoryClient, err := directory.New(directory.Options{
	Environment: directory.Sandbox,
})

Options.HTTPClient permits transport policy and test injection while preserving the selected canonical origin. The client accepts up to five same-origin redirects, bounds response bodies, and returns non-success responses as *directory.RequestError with the status and response headers. RequestError.Retryable marks the 429 and 5xx statuses worth retrying, and Message quotes only a structured field of a JSON error document, stripped of control characters and clamped in length.

Directory results filter unrecognized enrollment, payment, and trust descriptors while preserving recognized, validated protocol capabilities.

Related documentation

• Agent integration
• Protocol models and validation
• Canonical directory
• Normative specification and schemas