SDK Overview

The TypeScript SDK is the natural client foundation for OAN applications. It should hide repetitive protocol plumbing without hiding the trust model. Developers should be able to register resources, query Discovery, inspect lifecycle, fetch package material, and verify evidence through typed helpers instead of rebuilding raw HTTP calls.

The SDK should also make endpoint configuration predictable. Official services are the default, third-party baseUrl is supported, and explicit endpoint overrides are available when a developer needs direct control.

The SDK is not only a convenience wrapper. It is a safety layer. OAN asks clients to perform checks that are easy to implement incorrectly if every application hand-rolls them. A well-designed SDK makes the secure path ordinary and keeps enough detail available for debugging and audit.

OAN protocol stack

Client Configuration

OAN clients should support a layered configuration model:

Option Meaning Precedence
baseUrl Unified official or third-party service entry. Default route source.
registrarEndpoint Direct Registrar endpoint. Overrides Registrar routes from baseUrl.
discoveryEndpoint Direct Discovery endpoint. Overrides Discovery routes from baseUrl.
rootEndpoint Direct Root lookup or status endpoint. Advanced override.
cdnEndpoint Direct package distribution endpoint. Advanced override.

This lets ordinary applications use one URL while tests and specialized deployments can override individual services. The SDK should document which routes are derived from baseUrl and which explicit endpoints override them.

Configuration should also be observable. When an SDK submits a registration or queries Discovery, developers should be able to see which endpoint was used. This avoids a common deployment mistake: believing a request reached official services while it actually used an old local or test endpoint.

Core SDK Responsibilities

The SDK should help with:

  • building registration requests;
  • validating resource type fields;
  • preparing or checking DID Document material;
  • serializing authorizedDomains and capabilityTags;
  • submitting to Registrar;
  • observing lifecycle status;
  • constructing Discovery queries;
  • parsing Discovery responses;
  • fetching package material when needed;
  • verifying signatures, hashes, Root proof, and lifecycle;
  • reporting precise error categories.

The SDK should not encourage developers to treat OAN as only a search API. The evidence fields are part of the product surface.

In practice, the SDK should expose both high-level and low-level layers. A high-level helper can make common use easy. A lower-level result object should still include raw response material, proof references, identifiers, hashes, lifecycle state, and endpoint information for applications that need stronger control.

Registration Helpers

Registration helpers should make resource-specific requirements visible. A Skill registration should ask for manifest or package material. An MCP Server registration should ask for MCP endpoint and tool/resource/prompt descriptions. A Tool/API registration should ask for schema or endpoint references. An Agent Service registration should ask for service endpoint and protocol binding.

The SDK can provide common helpers while still letting applications supply richer metadata. The result should be a correct OAN package proposal, not merely a form post.

Typed builders are useful here. A Skill builder can require package or manifest references. An McpServer builder can require protocol binding and endpoint fields. A ToolApi builder can make schema references natural. This reduces invalid submissions before they reach Registrar.

Discovery Helpers

Discovery helpers should support natural-language query text, resource type, protocol, capability tags, optional domain filters, limit, and explanation options. Responses should preserve candidate evidence. A high-level helper may return a convenient list, but advanced callers should be able to inspect DID, package, proof, domains, lifecycle, and raw response material.

For agent workflows, a useful pattern is:

  1. query Discovery;
  2. rank or select candidates;
  3. verify selected candidate evidence;
  4. continue with MCP, skill install, API call, or agent-service invocation.

The SDK should make that pattern straightforward.

For autonomous agents, the SDK can become the difference between “agent searched the web and picked a URL” and “agent selected a Root-verifiable resource candidate.” That is a major product boundary. The SDK should make it easy for agents to keep the trust context attached to the selected resource.

Verification Helpers

Verification is where the SDK can save developers from subtle mistakes. It should expose checks for Discovery signature, Root proof, DID Document hash, metadata hash, package hash, resource type consistency, lifecycle state, domain scope, and endpoint or artifact binding.

Error messages should be structured enough for applications to respond. A lifecycle failure is different from a hash mismatch. A domain mismatch is different from a network timeout. A missing Root proof is different from a low semantic score.

Compatibility across SDKs should eventually be tested with shared vectors: DID Document canonical forms, package hashes, signed Discovery responses, lifecycle states, domain coverage cases, and negative examples. Without shared vectors, different language SDKs can drift while appearing to support the same protocol.

Further Reading