@anml-foundation/client

ANML 1.0 client library for Node.js / TypeScript

anmlfoundation.org · GitHub · RFC Draft

---

A TypeScript-first client library for the Agentic Notation Markup Language (ANML) 1.0 — a machine-first markup language for agent-to-agent and agent-to-service communication over the internet.

Features

• Full ANML 1.0 document parsing (XML and JSON serializations)
• Well-known URI, Link header, and HTML link discovery
• 7-step RFC disclosure evaluation with consent management
• Action execution with parameter binding (urlencoded, multipart, JSON)
• Multi-step workflow navigation
• Knowledge exchange (inform/ask handling)
• SRI verification (SHA-256/384/512)
• Async pagination over nav.next links
• Builder pattern for client construction
• HTTP middleware support
• Zero runtime dependencies beyond fast-xml-parser

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5.0+

Installation

npm install @anml-foundation/client

Quick Start

import { AnmlClient } from "@anml-foundation/client";

// Create a client with builder pattern
const client = AnmlClient.builder()
  .baseUrl("https://example.com")
  .allowDomains(["example.com"])
  .userAgent("MyAgent/1.0")
  .build();

// Discover ANML support
const anmlUrl = await client.discover("https://example.com");

// Fetch an ANML document
const doc = await client.fetchUrl("https://example.com/.well-known/anml");

// Access document content
console.log(doc.head?.title);
console.log(doc.body?.content);

// Execute an action
const response = await client.executeAction(doc, "submit-airline", {
  airline: "Example Air",
});

// Paginate through results
for await (const page of client.paginate(doc)) {
  console.log(page.body?.content);
}

Parsing Documents

import { parseAnmlXml, parseAnmlJson, parseAnml } from "@anml-foundation/client";

// Parse XML
const doc1 = parseAnmlXml(xmlString);

// Parse JSON
const doc2 = parseAnmlJson(jsonString);

// Auto-detect from content type
const doc3 = parseAnml(content, "application/anml+json");

Discovery

import {
  discoverWellKnown,
  discoverLinkHeader,
  discoverHtmlLink,
} from "@anml-foundation/client";

// Well-known URI discovery
const url = await discoverWellKnown("https://example.com");

// Link header discovery
const anmlUrl = discoverLinkHeader(httpResponse);

// HTML link discovery
const href = discoverHtmlLink(htmlContent);

Disclosure & Consent

import {
  ConsentStore,
  evaluateDisclosure,
  DisclosureRequirement,
} from "@anml-foundation/client";

const store = new ConsentStore();

// Grant consent
store.grant("email", "example.com", DisclosureRequirement.ExplicitConsent);

// Evaluate disclosure
const result = evaluateDisclosure(doc, "email", "example.com", store, trustPolicy);
if (result.allowed) {
  // Safe to disclose
}

Flow Navigation

import { FlowNavigator } from "@anml-foundation/client";

const nav = new FlowNavigator(doc);

console.log(nav.getCurrentStep());  // Current step
console.log(nav.getNextStep());     // Next step
console.log(nav.isComplete());      // Flow completion status
console.log(nav.getProgress());     // Progress (0 to 1)

Knowledge Exchange

import {
  extractInforms,
  extractAsks,
  buildAnswer,
  buildRefuse,
} from "@anml-foundation/client";

// Get service information
const informs = extractInforms(doc);

// Get information requests
const asks = extractAsks(doc);

// Build responses
const answer = buildAnswer(asks[0], "Example Air");
const refusal = buildRefuse(asks[0], "User declined");

Integrity Verification

import { verifySri, computeSri } from "@anml-foundation/client";

// Compute SRI hash
const hash = await computeSri(data, "sha256");

// Verify SRI hash
await verifySri(data, "sha256-abc123...");

API Reference

AnmlClient

Method	Description
static builder()	Create a new client builder
fetch(path)	Fetch ANML document from relative path
fetchUrl(url)	Fetch ANML document from absolute URL
discover(baseUrl)	Discover ANML support via well-known URI
executeAction(doc, actionId, params?)	Execute an action
paginate(doc)	Async iterate over paginated documents
getConfig()	Get client configuration
getConsentStore()	Get the consent store

AnmlClientBuilder

Method	Description
baseUrl(url)	Set base URL
allowDomains(domains)	Set allow-list trust policy
denyAll()	Set deny-all trust policy
userAgent(agent)	Set User-Agent header
allowInsecure()	Disable HTTPS enforcement
timeouts(config)	Set timeout configuration
retryPolicy(policy)	Set retry policy
resourceLimits(limits)	Set resource limits
header(name, value)	Add default header
middleware(mw)	Add HTTP middleware
build()	Build the client

Architecture

src/
├── index.ts          # Public API re-exports
├── client.ts         # Main AnmlClient class with builder
├── types.ts          # Full ANML 1.0 type definitions
├── parser.ts         # XML and JSON parsing
├── discovery.ts      # Well-known, Link header, HTML discovery
├── disclosure.ts     # 7-step disclosure evaluation
├── action.ts         # Action execution with param binding
├── flow.ts           # Multi-step workflow navigation
├── knowledge.ts      # Knowledge exchange utilities
├── integrity.ts      # SRI verification
├── pagination.ts     # Async pagination
├── middleware.ts     # HTTP middleware chain
├── config.ts         # Configuration and trust policies
└── errors.ts         # Typed error hierarchy

License

ISC © ANML Foundation