diff --git a/src/contract/types.gen.ts b/src/contract/types.gen.ts index f06d262..4c609bc 100644 --- a/src/contract/types.gen.ts +++ b/src/contract/types.gen.ts @@ -97,14 +97,14 @@ export interface paths { "/api/ard/search": { /** * Search agentic resources (Agentic Resource Discovery) - * @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is a readiness-weighted relevance score (0-100): match quality for the query (dominant), multiplied by a 0.6-1.0 factor from the domain's agent-readiness. It is distinct from the raw agent-readiness score returned by POST /api/scan and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. + * @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. */ post: operations["ardSearch"]; }; "/api/ard/explore": { /** * Faceted exploration of agentic resources (Agentic Resource Discovery) - * @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. An optional query narrows the set before faceting. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. + * @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. */ post: operations["ardExplore"]; }; @@ -146,7 +146,7 @@ export interface paths { "/api/agent-files/{domain}": { /** * Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json) - * @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.1). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air::..., identity https://), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved /server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files `. + * @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.2). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air::..., identity https://), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved /server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files `. */ get: operations["generateAgentFiles"]; }; @@ -544,7 +544,7 @@ export interface components { * @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning. * @enum {string} */ - contractVersion: "1.32.0"; + contractVersion: "1.36.0"; /** * @description Present only when this body is a stored result served by the freshness gate instead of a fresh scan. Absent on a live scan. * @enum {boolean} @@ -747,7 +747,7 @@ export interface components { * @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning. * @enum {string} */ - contractVersion: "1.32.0"; + contractVersion: "1.36.0"; /** @description Wall-clock duration of the scan that produced this stored result */ durationMs: number | null; /** @@ -795,7 +795,7 @@ export interface components { * @description The contract version this catalog conforms to - identical to the OpenAPI info.version and the MCP server version. SemVer: a major means a response-envelope break (a stable field, or a layer id, removed or renamed or changed in meaning, or the default response format flipping) and is safe to pin; check-catalog membership changes ship on a minor. The full versioning policy is published in the API description at /api/openapi.json. * @enum {string} */ - contractVersion: "1.32.0"; + contractVersion: "1.36.0"; /** @description The four scored layers in scoring order, with display name and current weight. */ layers: { /** @description Stable layer id: discovery, accessibility, usability, or payments. Removing or renaming a layer id is a major version change. Note one intentional divergence: the id 'accessibility' carries the display name 'Access'. */ @@ -894,7 +894,7 @@ export interface components { * @description The contract version this response conforms to - identical to the OpenAPI info.version and the MCP server version. The full versioning policy is published in the API description at /api/openapi.json. * @enum {string} */ - contractVersion: "1.32.0"; + contractVersion: "1.36.0"; /** @description The apex domain derived from the requested URL. */ domain: string; /** @description The normalized URL the run targeted. */ @@ -3090,22 +3090,24 @@ export interface operations { }; /** * Search agentic resources (Agentic Resource Discovery) - * @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is a readiness-weighted relevance score (0-100): match quality for the query (dominant), multiplied by a 0.6-1.0 factor from the domain's agent-readiness. It is distinct from the raw agent-readiness score returned by POST /api/scan and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. + * @description Runs an Agentic Resource Discovery (ARD) search over ora's catalog of agent-ready resources. Returns resources ranked by relevance to a free-text query, with optional field filters and federation control. The per-result `score` is pure relevance (0-100): match quality for the query, never a trust or readiness rating. Results are ordered by relevance with agent-readiness reordering close matches, so `score` need not decrease down the list; the readiness itself is in `oraScorecard` and GET /api/score/{domain}. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. */ ardSearch: { requestBody: { content: { "application/json": { query: { + /** @description Optional JSON-LD context (a string, object or array, at most 4096 characters serialized). Accepted per ARD v0.91; ora binds no additional filter keys from it. */ + "@context"?: unknown; /** @description Free-text search query. May be omitted when filter is present (a filter-only browse); at least one of text/filter is required. */ text?: string; - /** @description Optional field filters: a map of field name to an allowed value (a scalar string or an array of strings; OR within a key, AND across keys). */ + /** @description Optional field filters: a map of field name to an allowed value (a scalar string or an array of strings; OR within a key, AND across keys). Keys: type, identifier, displayName, tags, capabilities, version, publisher (derived from the URN identifier), and literal dot-paths under trustManifest.* and metadata.* (a path crossing an array matches when any element does). Any other key returns 400 INVALID_ARGUMENT. */ filter?: { [key: string]: string | string[]; }; }; /** - * @description Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated) and degrades to own-results-only when disabled. + * @description Federation policy. 'none': ora's own index only. 'referrals': ora's results plus referrals[] pointers to upstream registries. 'auto': ora merges upstream registry results into results (each tagged with its upstream source); merging is off by default (server-gated), and while it is off 'auto' returns referrals[] as 'referrals' does. * @default auto * @enum {string} */ @@ -3115,13 +3117,13 @@ export interface operations { * @default 10 */ pageSize?: number; - /** @description Opaque pagination token from a previous response. */ + /** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */ pageToken?: string; }; }; }; responses: { - /** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null). ora is non-federating, so referrals is []. Each result's trustManifest.attestations[0] is a reference { type, uri, mediaType } to GET /api/ard/attestation/{domain}, not inlined claims. Results from ora's own index also carry an `oraScorecard` vendor extension ({ score?, grade?, category?, checkedAt? }): agent-readiness score/grade only when ora has scored the domain (never a fabricated 0/F), category whenever ora has classified it - all distinct from the relevance `score`; the signed claim remains the attestation endpoint. */ + /** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null). referrals lists upstream registries in 'referrals' mode, and in 'auto' mode while upstream merging is off. Each result's trustManifest.attestations[0] is a reference { type, uri, mediaType } to GET /api/ard/attestation/{domain}, not inlined claims. Results from ora's own index also carry an `oraScorecard` vendor extension ({ score?, grade?, category?, checkedAt? }): agent-readiness score/grade only when ora has scored the domain (never a fabricated 0/F), category whenever ora has classified it - all distinct from the relevance `score`; the signed claim remains the attestation endpoint. Ora product entries (type application/vnd.ora.product+json) reference the JSON score document GET /api/score/{domain} as their url when scored, or carry inline data { domain, name, category?, status: 'not_scanned' } when not, with the human report page in `oraReportUrl`; skill entries use application/agent-skills+md (a type filter on the earlier application/ai-skill+md matches too). Entries crawled from other publishers' catalogs carry `oraPublisherBinding`: 'verified' when the entry's urn:air publisher is the site ora crawled it from, else 'unverified' (ARD ยง4.5.1); an unverified entry carries no trustManifest and sorts after verified ones at equal relevance. */ 200: { content: never; }; @@ -3147,7 +3149,7 @@ export interface operations { }; /** * Faceted exploration of agentic resources (Agentic Resource Discovery) - * @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. An optional query narrows the set before faceting. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. + * @description Returns facet aggregations (counts per field value) for an Agentic Resource Discovery (ARD) result set. Use this to build filter UIs over the ARD catalog. A `type` bucket's value is the raw media type, so it can be used as a filter value as-is. An optional query narrows the set before faceting: with text, the set is exactly what POST /api/ard/search matches for the same text and filter; without it, the whole index narrowed by the filter. Rate limited to 30 requests per minute per IP - returns 429 if exceeded. */ ardExplore: { requestBody: { @@ -3155,15 +3157,18 @@ export interface operations { "application/json": { /** @description Optional query to narrow the set before faceting (same shape as POST /api/ard/search's query). */ query?: { + /** @description Optional JSON-LD context, as on POST /api/ard/search. */ + "@context"?: unknown; /** @description Free-text search query. */ text?: string; + /** @description Same keys as POST /api/ard/search's filter; an unsupported key returns 400 INVALID_ARGUMENT. */ filter?: { [key: string]: string[]; }; }; resultType: { facets: { - /** @description The resource field to aggregate on. */ + /** @description The resource field to aggregate on: any search filter key, or category. An unsupported field returns 400 INVALID_ARGUMENT. */ field: string; /** @description Max facet values to return for this field. */ limit?: number; @@ -3206,11 +3211,11 @@ export interface operations { ardListAgents: { parameters: { query?: { - /** @description Results per page (1-100, default 20). */ + /** @description Results per page (1-100, default 20). A larger value clamps to 100; a non-positive or non-integer value returns 400 INVALID_ARGUMENT. */ pageSize?: number; - /** @description Opaque pagination token from a previous response. */ + /** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */ pageToken?: string; - /** @description EBNF filter expression, e.g. "type = 'application/mcp-server-card+json' AND updatedAfter > '2026-01-01'". Fields: type, displayName, publisherId, tags, updatedAt. Operators: = != > < >= <=, conditions joined by AND. An unsupported field/operator/syntax returns 400 INVALID_ARGUMENT. */ + /** @description EBNF filter expression, e.g. "type = 'application/mcp-server-card+json' AND updatedAfter > '2026-01-01'". Fields: type, displayName, publisherId, tags, updatedAt (and updatedAfter / updatedBefore). Operators: = != > < >= <=, conditions joined by AND; a comma-separated type, publisherId or tags value means OR. An unsupported field/operator/syntax (createdAfter included) returns 400 INVALID_ARGUMENT. */ filter?: string; /** @description Sort expression " [ASC|DESC]", e.g. "displayName DESC". Fields: displayName, updatedAt, identifier, type. */ orderBy?: string; @@ -3331,7 +3336,7 @@ export interface operations { }; /** * Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json) - * @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.1). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air::..., identity https://), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved /server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files `. + * @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.2). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air::..., identity https://), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved /server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files `. */ generateAgentFiles: { parameters: { diff --git a/src/contract/version.ts b/src/contract/version.ts index 028909d..8061fee 100644 --- a/src/contract/version.ts +++ b/src/contract/version.ts @@ -2,4 +2,4 @@ // Regenerate: pnpm contract:gen [--url ] /** The ora contract version (spec info.version) these types were generated from. */ -export const BUILT_AGAINST = "1.32.0"; +export const BUILT_AGAINST = "1.36.0";