ai-catalog 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,303 @@
+/**
+ * Type definitions for the Agentic Resource Discovery (ARD) ai-catalog.json
+ * format, spec v1.0. Mirrors github.com/Agent-Card/ai-catalog.
+ */
+/** The current ARD spec major.minor this library targets. */
+declare const SPEC_VERSION = "1.0";
+/** Well-known path where a catalog may be served for domain-level discovery. */
+declare const WELL_KNOWN_PATH = "/.well-known/ai-catalog.json";
+/** IANA media type a catalog SHOULD be served with. */
+declare const CATALOG_MEDIA_TYPE = "application/ai-catalog+json";
+/** Link relation used to advertise a catalog from HTML / HTTP Link headers. */
+declare const LINK_REL = "ai-catalog";
+/** RECOMMENDED maximum nesting depth when resolving nested catalogs. */
+declare const DEFAULT_MAX_DEPTH = 4;
+/**
+ * Recognized "known types" from the spec. These are RECOMMENDED, not required —
+ * the `type` field accepts any string.
+ */
+declare const KnownType: {
+    /** A nested AI Catalog. */
+    readonly AiCatalog: "application/ai-catalog+json";
+    /** Reserved generic Agent Card format. */
+    readonly AgentCard: "application/agent-card+json";
+    /** An A2A Agent Card. */
+    readonly A2aAgentCard: "application/a2a-agent-card+json";
+    /** An MCP Server Card. */
+    readonly McpServerCard: "application/mcp-server-card+json";
+    /** Agent Skill metadata JSON. */
+    readonly AgentSkillsJson: "application/agent-skills+json";
+    /** Agent Skill in Markdown. */
+    readonly AgentSkillsMd: "application/agent-skills+md";
+    /** Agent Skill bundle (ZIP). */
+    readonly AgentSkillsZip: "application/agent-skills+zip";
+    /** Agent Skill bundle (gzipped tarball). */
+    readonly AgentSkillsGzip: "application/agent-skills+gzip";
+};
+type KnownTypeValue = (typeof KnownType)[keyof typeof KnownType];
+/** Identifies the operator of a catalog. */
+interface HostInfo {
+    /** Human-readable name of the host. REQUIRED. */
+    displayName: string;
+    /** Verifiable identifier for the host (DID or domain). */
+    identifier?: string;
+    /** URL to the host's documentation. */
+    documentationUrl?: string;
+    /** URL (or data: URI) to the host's logo. */
+    logoUrl?: string;
+    /** Verifiable identity / trust metadata for the host itself. */
+    trustManifest?: TrustManifest;
+}
+/** Identifies the entity responsible for an artifact. */
+interface Publisher {
+    /** Verifiable identifier for the publisher organization. REQUIRED. */
+    identifier: string;
+    /** Human-readable name of the publisher. REQUIRED. */
+    displayName: string;
+    /** Type hint for the identifier, e.g. "did", "dns". */
+    identityType?: string;
+}
+/**
+ * Trust Manifest: optional verifiable identity, attestation, and provenance
+ * metadata. This library treats the inner structure permissively; see the spec
+ * for the full shape. The `identity.identifier` domain MUST align with the
+ * publisher domain segment of the entry's `urn:air` identifier.
+ */
+interface TrustManifest {
+    identifier?: string;
+    identity?: {
+        identifier: string;
+        identityType?: string;
+        [k: string]: unknown;
+    };
+    attestations?: unknown[];
+    provenance?: unknown[];
+    signature?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * A single AI artifact in the catalog. MUST carry an `identifier` and `type`,
+ * and exactly one of `url` or `data`.
+ */
+interface CatalogEntry {
+    /**
+     * Unique artifact identifier. For open/federated systems this MUST follow
+     * `urn:air:{publisher}:{namespace}:{name}`.
+     */
+    identifier: string;
+    /** Media type of the referenced artifact, e.g. an entry in {@link KnownType}. */
+    type: KnownTypeValue | (string & {});
+    /** URL where the full artifact document can be retrieved. */
+    url?: string;
+    /** The complete artifact document inline. */
+    data?: unknown;
+    /** Human-readable name; set only to override the artifact's own name. */
+    displayName?: string;
+    /** Short description of the artifact. */
+    description?: string;
+    /** Keywords for filtering and discovery. */
+    tags?: string[];
+    /** Artifact version; SemVer RECOMMENDED. */
+    version?: string;
+    /** ISO 8601 / RFC 3339 timestamp of last modification. */
+    updatedAt?: string;
+    /** The entity that publishes this artifact. */
+    publisher?: Publisher;
+    /** Verifiable identity / trust metadata for this artifact. */
+    trustManifest?: TrustManifest;
+    /** Open map for custom metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** A top-level AI Catalog document. */
+interface AiCatalog {
+    /** Spec version in "Major.Minor" format, e.g. "1.0". REQUIRED. */
+    specVersion: string;
+    /** Catalog entries. MAY be empty. REQUIRED. */
+    entries: CatalogEntry[];
+    /** The operator of this catalog. */
+    host?: HostInfo;
+    /** Open map for custom catalog-level metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Parsed pieces of a `urn:air:{publisher}:{namespace}:{name}` identifier. */
+interface AirUrn {
+    /** Publisher domain, e.g. "example.com". */
+    publisher: string;
+    /** Namespace, possibly colon-separated, e.g. "mcp" or "finance:agent". */
+    namespace: string;
+    /** Stable artifact name within the namespace. */
+    name: string;
+}
+
+/**
+ * Parse a `urn:air:{publisher}:{namespace}:{name}` identifier into its parts.
+ * The namespace may contain colons (e.g. `finance:agent`), so it is everything
+ * between the publisher and the final segment.
+ *
+ * Returns `null` for any string that is not a well-formed `urn:air` URN.
+ *
+ * @example
+ * parseAirUrn("urn:air:example.com:finance:agent:research")
+ * // { publisher: "example.com", namespace: "finance:agent", name: "research" }
+ */
+declare function parseAirUrn(identifier: string): AirUrn | null;
+/** True if `identifier` is a well-formed `urn:air` URN. */
+declare function isAirUrn(identifier: string): boolean;
+/**
+ * Build a `urn:air` identifier from its parts. The namespace may be a single
+ * string (possibly colon-separated) or an array of segments.
+ *
+ * @throws if any part is empty.
+ */
+declare function buildAirUrn(publisher: string, namespace: string | string[], name: string): string;
+/**
+ * The trailing name segment of any identifier — the portion after the final
+ * `:` or `/`. Used as the last-resort display name (spec resolution step 3).
+ */
+declare function identifierTail(identifier: string): string;
+
+/** A single validation problem. `path` is a JSON-pointer-ish location. */
+interface ValidationIssue {
+    path: string;
+    message: string;
+    /** `error` violates a MUST; `warning` violates a SHOULD/RECOMMENDED. */
+    severity: "error" | "warning";
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * Validate a parsed value against the ARD ai-catalog.json spec (v1.0).
+ *
+ * Checks the normative MUST rules — required members, exactly-one-of url/data,
+ * identifier/version uniqueness, Host Info / Publisher shape — as `errors`, and
+ * the RECOMMENDED rules — `urn:air` identifiers, known media types, RFC 3339
+ * timestamps, spec version — as `warnings`. Pass `{ strict: true }` to treat
+ * warnings as errors.
+ */
+declare function validateCatalog(doc: unknown, opts?: {
+    strict?: boolean;
+}): ValidationResult;
+/** Throwing variant: validates and throws an Error listing all problems. */
+declare function assertValidCatalog(doc: unknown, opts?: {
+    strict?: boolean;
+}): asserts doc is AiCatalog;
+
+/**
+ * Typed builder for an ai-catalog.json document. Chainable; call `.build()` to
+ * get the plain object or `.toJSON(indent?)` for a serialized string.
+ *
+ * @example
+ * const catalog = new CatalogBuilder({ displayName: "Acme" })
+ *   .addEntry({
+ *     identifier: "urn:air:acme.com:mcp:weather",
+ *     type: KnownType.McpServerCard,
+ *     url: "https://acme.com/.well-known/mcp/weather.json",
+ *   })
+ *   .build();
+ */
+declare class CatalogBuilder {
+    private catalog;
+    constructor(host?: HostInfo, specVersion?: string);
+    /** Set or replace the Host Info object. */
+    setHost(host: HostInfo): this;
+    /** Set a catalog-level metadata key. */
+    setMetadata(key: string, value: unknown): this;
+    /** Append a catalog entry. */
+    addEntry(entry: CatalogEntry): this;
+    /** Append several catalog entries. */
+    addEntries(entries: CatalogEntry[]): this;
+    /**
+     * Add a nested-catalog entry (`type: application/ai-catalog+json`) that points
+     * at another catalog by URL.
+     */
+    addNestedCatalog(identifier: string, url: string, extra?: Partial<CatalogEntry>): this;
+    /** The built catalog object (a fresh shallow copy each call). */
+    build(): AiCatalog;
+    /** Validate the built catalog, throwing on any error. Returns the catalog. */
+    validateOrThrow(opts?: {
+        strict?: boolean;
+    }): AiCatalog;
+    /** Serialize to a JSON string. */
+    toJSON(indent?: number): string;
+}
+/** Functional shorthand for `new CatalogBuilder(host)`. */
+declare function defineCatalog(host?: HostInfo): CatalogBuilder;
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface DiscoverOptions {
+    /** Fetch implementation. Defaults to global `fetch` (Node 18+). */
+    fetch?: FetchLike;
+    /** Per-request timeout in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Skip the `/.well-known/ai-catalog.json` fallback (steps 1–2 only). */
+    noWellKnownFallback?: boolean;
+}
+interface DiscoverResult {
+    /** The resolved catalog URL. */
+    url: string;
+    /** How the catalog was located. */
+    via: "link-header" | "html-link" | "well-known";
+    /** The parsed catalog document. */
+    catalog: AiCatalog;
+}
+/**
+ * Parse an HTTP `Link` header for a `rel="ai-catalog"` target.
+ * Exported for testing and reuse.
+ */
+declare function parseLinkHeader(header: string | null | undefined): string | null;
+/**
+ * Find a `<link rel="ai-catalog" href="...">` in an HTML document.
+ * Exported for testing and reuse.
+ */
+declare function parseHtmlLink(html: string): string | null;
+/**
+ * Run the spec's agent-driven discovery procedure against a website URL:
+ *
+ *   1. HTTP `Link` header with `rel="ai-catalog"`
+ *   2. HTML `<link rel="ai-catalog">`
+ *   3. fall back to `/.well-known/ai-catalog.json`
+ *
+ * Returns the located catalog and how it was found, or throws if no valid
+ * catalog can be discovered.
+ */
+declare function discover(siteUrl: string, opts?: DiscoverOptions): Promise<DiscoverResult>;
+/** Fetch and parse a catalog from a known URL, throwing on HTTP/parse errors. */
+declare function fetchCatalog(url: string, fetchFn?: FetchLike, timeoutMs?: number): Promise<AiCatalog>;
+interface ResolveOptions extends DiscoverOptions {
+    /** Maximum nesting depth to walk. Default 4 (spec RECOMMENDED). */
+    maxDepth?: number;
+}
+interface ResolvedEntry extends CatalogEntry {
+    /** URL of the catalog this entry was found in. */
+    sourceCatalogUrl: string;
+    /** Nesting depth at which it was found (0 = root catalog). */
+    depth: number;
+}
+/**
+ * Walk a catalog and all of its nested catalogs (entries of type
+ * `application/ai-catalog+json` carrying a `url`), returning every leaf entry
+ * flattened. Respects the spec's depth limit and guards against cycles by URL.
+ *
+ * Pass either a catalog object plus its `rootUrl`, or just a URL string to fetch
+ * the root first.
+ */
+declare function resolveCatalog(root: AiCatalog | string, opts?: ResolveOptions & {
+    rootUrl?: string;
+}): Promise<ResolvedEntry[]>;
+/**
+ * Resolve a human-readable display name for an entry per the spec order:
+ *   1. `entry.displayName`
+ *   2. a `referencedName` the caller already fetched (A2A `name` / MCP `title`)
+ *   3. the trailing segment of the identifier
+ */
+declare function resolveDisplayName(entry: CatalogEntry, referencedName?: string): string;
+/**
+ * From entries sharing an `identifier`, pick the most recent — by SemVer when
+ * all versions parse, else by `updatedAt`, else the last in document order.
+ */
+declare function selectLatest(entries: CatalogEntry[], identifier: string): CatalogEntry | undefined;
+
+export { type AiCatalog, type AirUrn, CATALOG_MEDIA_TYPE, CatalogBuilder, type CatalogEntry, DEFAULT_MAX_DEPTH, type DiscoverOptions, type DiscoverResult, type HostInfo, KnownType, type KnownTypeValue, LINK_REL, type Publisher, type ResolveOptions, type ResolvedEntry, SPEC_VERSION, type TrustManifest, type ValidationIssue, type ValidationResult, WELL_KNOWN_PATH, assertValidCatalog, buildAirUrn, defineCatalog, discover, fetchCatalog, identifierTail, isAirUrn, parseAirUrn, parseHtmlLink, parseLinkHeader, resolveCatalog, resolveDisplayName, selectLatest, validateCatalog };

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+/**
+ * Type definitions for the Agentic Resource Discovery (ARD) ai-catalog.json
+ * format, spec v1.0. Mirrors github.com/Agent-Card/ai-catalog.
+ */
+/** The current ARD spec major.minor this library targets. */
+declare const SPEC_VERSION = "1.0";
+/** Well-known path where a catalog may be served for domain-level discovery. */
+declare const WELL_KNOWN_PATH = "/.well-known/ai-catalog.json";
+/** IANA media type a catalog SHOULD be served with. */
+declare const CATALOG_MEDIA_TYPE = "application/ai-catalog+json";
+/** Link relation used to advertise a catalog from HTML / HTTP Link headers. */
+declare const LINK_REL = "ai-catalog";
+/** RECOMMENDED maximum nesting depth when resolving nested catalogs. */
+declare const DEFAULT_MAX_DEPTH = 4;
+/**
+ * Recognized "known types" from the spec. These are RECOMMENDED, not required —
+ * the `type` field accepts any string.
+ */
+declare const KnownType: {
+    /** A nested AI Catalog. */
+    readonly AiCatalog: "application/ai-catalog+json";
+    /** Reserved generic Agent Card format. */
+    readonly AgentCard: "application/agent-card+json";
+    /** An A2A Agent Card. */
+    readonly A2aAgentCard: "application/a2a-agent-card+json";
+    /** An MCP Server Card. */
+    readonly McpServerCard: "application/mcp-server-card+json";
+    /** Agent Skill metadata JSON. */
+    readonly AgentSkillsJson: "application/agent-skills+json";
+    /** Agent Skill in Markdown. */
+    readonly AgentSkillsMd: "application/agent-skills+md";
+    /** Agent Skill bundle (ZIP). */
+    readonly AgentSkillsZip: "application/agent-skills+zip";
+    /** Agent Skill bundle (gzipped tarball). */
+    readonly AgentSkillsGzip: "application/agent-skills+gzip";
+};
+type KnownTypeValue = (typeof KnownType)[keyof typeof KnownType];
+/** Identifies the operator of a catalog. */
+interface HostInfo {
+    /** Human-readable name of the host. REQUIRED. */
+    displayName: string;
+    /** Verifiable identifier for the host (DID or domain). */
+    identifier?: string;
+    /** URL to the host's documentation. */
+    documentationUrl?: string;
+    /** URL (or data: URI) to the host's logo. */
+    logoUrl?: string;
+    /** Verifiable identity / trust metadata for the host itself. */
+    trustManifest?: TrustManifest;
+}
+/** Identifies the entity responsible for an artifact. */
+interface Publisher {
+    /** Verifiable identifier for the publisher organization. REQUIRED. */
+    identifier: string;
+    /** Human-readable name of the publisher. REQUIRED. */
+    displayName: string;
+    /** Type hint for the identifier, e.g. "did", "dns". */
+    identityType?: string;
+}
+/**
+ * Trust Manifest: optional verifiable identity, attestation, and provenance
+ * metadata. This library treats the inner structure permissively; see the spec
+ * for the full shape. The `identity.identifier` domain MUST align with the
+ * publisher domain segment of the entry's `urn:air` identifier.
+ */
+interface TrustManifest {
+    identifier?: string;
+    identity?: {
+        identifier: string;
+        identityType?: string;
+        [k: string]: unknown;
+    };
+    attestations?: unknown[];
+    provenance?: unknown[];
+    signature?: unknown;
+    [k: string]: unknown;
+}
+/**
+ * A single AI artifact in the catalog. MUST carry an `identifier` and `type`,
+ * and exactly one of `url` or `data`.
+ */
+interface CatalogEntry {
+    /**
+     * Unique artifact identifier. For open/federated systems this MUST follow
+     * `urn:air:{publisher}:{namespace}:{name}`.
+     */
+    identifier: string;
+    /** Media type of the referenced artifact, e.g. an entry in {@link KnownType}. */
+    type: KnownTypeValue | (string & {});
+    /** URL where the full artifact document can be retrieved. */
+    url?: string;
+    /** The complete artifact document inline. */
+    data?: unknown;
+    /** Human-readable name; set only to override the artifact's own name. */
+    displayName?: string;
+    /** Short description of the artifact. */
+    description?: string;
+    /** Keywords for filtering and discovery. */
+    tags?: string[];
+    /** Artifact version; SemVer RECOMMENDED. */
+    version?: string;
+    /** ISO 8601 / RFC 3339 timestamp of last modification. */
+    updatedAt?: string;
+    /** The entity that publishes this artifact. */
+    publisher?: Publisher;
+    /** Verifiable identity / trust metadata for this artifact. */
+    trustManifest?: TrustManifest;
+    /** Open map for custom metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** A top-level AI Catalog document. */
+interface AiCatalog {
+    /** Spec version in "Major.Minor" format, e.g. "1.0". REQUIRED. */
+    specVersion: string;
+    /** Catalog entries. MAY be empty. REQUIRED. */
+    entries: CatalogEntry[];
+    /** The operator of this catalog. */
+    host?: HostInfo;
+    /** Open map for custom catalog-level metadata. */
+    metadata?: Record<string, unknown>;
+}
+/** Parsed pieces of a `urn:air:{publisher}:{namespace}:{name}` identifier. */
+interface AirUrn {
+    /** Publisher domain, e.g. "example.com". */
+    publisher: string;
+    /** Namespace, possibly colon-separated, e.g. "mcp" or "finance:agent". */
+    namespace: string;
+    /** Stable artifact name within the namespace. */
+    name: string;
+}
+
+/**
+ * Parse a `urn:air:{publisher}:{namespace}:{name}` identifier into its parts.
+ * The namespace may contain colons (e.g. `finance:agent`), so it is everything
+ * between the publisher and the final segment.
+ *
+ * Returns `null` for any string that is not a well-formed `urn:air` URN.
+ *
+ * @example
+ * parseAirUrn("urn:air:example.com:finance:agent:research")
+ * // { publisher: "example.com", namespace: "finance:agent", name: "research" }
+ */
+declare function parseAirUrn(identifier: string): AirUrn | null;
+/** True if `identifier` is a well-formed `urn:air` URN. */
+declare function isAirUrn(identifier: string): boolean;
+/**
+ * Build a `urn:air` identifier from its parts. The namespace may be a single
+ * string (possibly colon-separated) or an array of segments.
+ *
+ * @throws if any part is empty.
+ */
+declare function buildAirUrn(publisher: string, namespace: string | string[], name: string): string;
+/**
+ * The trailing name segment of any identifier — the portion after the final
+ * `:` or `/`. Used as the last-resort display name (spec resolution step 3).
+ */
+declare function identifierTail(identifier: string): string;
+
+/** A single validation problem. `path` is a JSON-pointer-ish location. */
+interface ValidationIssue {
+    path: string;
+    message: string;
+    /** `error` violates a MUST; `warning` violates a SHOULD/RECOMMENDED. */
+    severity: "error" | "warning";
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * Validate a parsed value against the ARD ai-catalog.json spec (v1.0).
+ *
+ * Checks the normative MUST rules — required members, exactly-one-of url/data,
+ * identifier/version uniqueness, Host Info / Publisher shape — as `errors`, and
+ * the RECOMMENDED rules — `urn:air` identifiers, known media types, RFC 3339
+ * timestamps, spec version — as `warnings`. Pass `{ strict: true }` to treat
+ * warnings as errors.
+ */
+declare function validateCatalog(doc: unknown, opts?: {
+    strict?: boolean;
+}): ValidationResult;
+/** Throwing variant: validates and throws an Error listing all problems. */
+declare function assertValidCatalog(doc: unknown, opts?: {
+    strict?: boolean;
+}): asserts doc is AiCatalog;
+
+/**
+ * Typed builder for an ai-catalog.json document. Chainable; call `.build()` to
+ * get the plain object or `.toJSON(indent?)` for a serialized string.
+ *
+ * @example
+ * const catalog = new CatalogBuilder({ displayName: "Acme" })
+ *   .addEntry({
+ *     identifier: "urn:air:acme.com:mcp:weather",
+ *     type: KnownType.McpServerCard,
+ *     url: "https://acme.com/.well-known/mcp/weather.json",
+ *   })
+ *   .build();
+ */
+declare class CatalogBuilder {
+    private catalog;
+    constructor(host?: HostInfo, specVersion?: string);
+    /** Set or replace the Host Info object. */
+    setHost(host: HostInfo): this;
+    /** Set a catalog-level metadata key. */
+    setMetadata(key: string, value: unknown): this;
+    /** Append a catalog entry. */
+    addEntry(entry: CatalogEntry): this;
+    /** Append several catalog entries. */
+    addEntries(entries: CatalogEntry[]): this;
+    /**
+     * Add a nested-catalog entry (`type: application/ai-catalog+json`) that points
+     * at another catalog by URL.
+     */
+    addNestedCatalog(identifier: string, url: string, extra?: Partial<CatalogEntry>): this;
+    /** The built catalog object (a fresh shallow copy each call). */
+    build(): AiCatalog;
+    /** Validate the built catalog, throwing on any error. Returns the catalog. */
+    validateOrThrow(opts?: {
+        strict?: boolean;
+    }): AiCatalog;
+    /** Serialize to a JSON string. */
+    toJSON(indent?: number): string;
+}
+/** Functional shorthand for `new CatalogBuilder(host)`. */
+declare function defineCatalog(host?: HostInfo): CatalogBuilder;
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface DiscoverOptions {
+    /** Fetch implementation. Defaults to global `fetch` (Node 18+). */
+    fetch?: FetchLike;
+    /** Per-request timeout in ms. Default 10000. */
+    timeoutMs?: number;
+    /** Skip the `/.well-known/ai-catalog.json` fallback (steps 1–2 only). */
+    noWellKnownFallback?: boolean;
+}
+interface DiscoverResult {
+    /** The resolved catalog URL. */
+    url: string;
+    /** How the catalog was located. */
+    via: "link-header" | "html-link" | "well-known";
+    /** The parsed catalog document. */
+    catalog: AiCatalog;
+}
+/**
+ * Parse an HTTP `Link` header for a `rel="ai-catalog"` target.
+ * Exported for testing and reuse.
+ */
+declare function parseLinkHeader(header: string | null | undefined): string | null;
+/**
+ * Find a `<link rel="ai-catalog" href="...">` in an HTML document.
+ * Exported for testing and reuse.
+ */
+declare function parseHtmlLink(html: string): string | null;
+/**
+ * Run the spec's agent-driven discovery procedure against a website URL:
+ *
+ *   1. HTTP `Link` header with `rel="ai-catalog"`
+ *   2. HTML `<link rel="ai-catalog">`
+ *   3. fall back to `/.well-known/ai-catalog.json`
+ *
+ * Returns the located catalog and how it was found, or throws if no valid
+ * catalog can be discovered.
+ */
+declare function discover(siteUrl: string, opts?: DiscoverOptions): Promise<DiscoverResult>;
+/** Fetch and parse a catalog from a known URL, throwing on HTTP/parse errors. */
+declare function fetchCatalog(url: string, fetchFn?: FetchLike, timeoutMs?: number): Promise<AiCatalog>;
+interface ResolveOptions extends DiscoverOptions {
+    /** Maximum nesting depth to walk. Default 4 (spec RECOMMENDED). */
+    maxDepth?: number;
+}
+interface ResolvedEntry extends CatalogEntry {
+    /** URL of the catalog this entry was found in. */
+    sourceCatalogUrl: string;
+    /** Nesting depth at which it was found (0 = root catalog). */
+    depth: number;
+}
+/**
+ * Walk a catalog and all of its nested catalogs (entries of type
+ * `application/ai-catalog+json` carrying a `url`), returning every leaf entry
+ * flattened. Respects the spec's depth limit and guards against cycles by URL.
+ *
+ * Pass either a catalog object plus its `rootUrl`, or just a URL string to fetch
+ * the root first.
+ */
+declare function resolveCatalog(root: AiCatalog | string, opts?: ResolveOptions & {
+    rootUrl?: string;
+}): Promise<ResolvedEntry[]>;
+/**
+ * Resolve a human-readable display name for an entry per the spec order:
+ *   1. `entry.displayName`
+ *   2. a `referencedName` the caller already fetched (A2A `name` / MCP `title`)
+ *   3. the trailing segment of the identifier
+ */
+declare function resolveDisplayName(entry: CatalogEntry, referencedName?: string): string;
+/**
+ * From entries sharing an `identifier`, pick the most recent — by SemVer when
+ * all versions parse, else by `updatedAt`, else the last in document order.
+ */
+declare function selectLatest(entries: CatalogEntry[], identifier: string): CatalogEntry | undefined;
+
+export { type AiCatalog, type AirUrn, CATALOG_MEDIA_TYPE, CatalogBuilder, type CatalogEntry, DEFAULT_MAX_DEPTH, type DiscoverOptions, type DiscoverResult, type HostInfo, KnownType, type KnownTypeValue, LINK_REL, type Publisher, type ResolveOptions, type ResolvedEntry, SPEC_VERSION, type TrustManifest, type ValidationIssue, type ValidationResult, WELL_KNOWN_PATH, assertValidCatalog, buildAirUrn, defineCatalog, discover, fetchCatalog, identifierTail, isAirUrn, parseAirUrn, parseHtmlLink, parseLinkHeader, resolveCatalog, resolveDisplayName, selectLatest, validateCatalog };