ax 0.10.2 → 0.10.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/api/shared.d.ts +9 -0
- package/dist/contract/types.gen.d.ts +129 -26
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +19 -1
- package/dist/index.js +19 -1
- package/dist/main.cjs +60 -60
- package/package.json +3 -3
package/dist/api/shared.d.ts
CHANGED
|
@@ -22,6 +22,15 @@ export declare function errorBody(res: Response): Promise<{
|
|
|
22
22
|
code: string | null;
|
|
23
23
|
payload: unknown;
|
|
24
24
|
}>;
|
|
25
|
+
/**
|
|
26
|
+
* The key-wide 429 a partner key gets once it has used its monthly usage
|
|
27
|
+
* limit (contract 1.37.0): `error: "usage_limit_reached"` with `kind`,
|
|
28
|
+
* `period`, `used`, `limit` and `resets_at`. Its Retry-After counts to the
|
|
29
|
+
* next 1st of the month, so it must not be read as the per-minute or daily
|
|
30
|
+
* limits the other 429s describe. Returns the message to show, or null for
|
|
31
|
+
* any other 429. Reads a clone, so the caller can still consume the body.
|
|
32
|
+
*/
|
|
33
|
+
export declare function usageLimitMessage(res: Response): Promise<string | null>;
|
|
25
34
|
/** Best-effort human message from an error response body. */
|
|
26
35
|
export declare function errorBodyText(res: Response): Promise<string>;
|
|
27
36
|
export declare const pause: (ms: number) => Promise<void>;
|
|
@@ -94,14 +94,14 @@ export interface paths {
|
|
|
94
94
|
"/api/ard/search": {
|
|
95
95
|
/**
|
|
96
96
|
* Search agentic resources (Agentic Resource Discovery)
|
|
97
|
-
* @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
|
|
97
|
+
* @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.
|
|
98
98
|
*/
|
|
99
99
|
post: operations["ardSearch"];
|
|
100
100
|
};
|
|
101
101
|
"/api/ard/explore": {
|
|
102
102
|
/**
|
|
103
103
|
* Faceted exploration of agentic resources (Agentic Resource Discovery)
|
|
104
|
-
* @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.
|
|
104
|
+
* @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.
|
|
105
105
|
*/
|
|
106
106
|
post: operations["ardExplore"];
|
|
107
107
|
};
|
|
@@ -143,7 +143,7 @@ export interface paths {
|
|
|
143
143
|
"/api/agent-files/{domain}": {
|
|
144
144
|
/**
|
|
145
145
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
146
|
-
* @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.
|
|
146
|
+
* @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:<domain>:..., identity https://<domain>), 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-url>/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/<domain>. 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 <domain>`.
|
|
147
147
|
*/
|
|
148
148
|
get: operations["generateAgentFiles"];
|
|
149
149
|
};
|
|
@@ -178,7 +178,7 @@ export interface paths {
|
|
|
178
178
|
"/api/journey/domains/{host}": {
|
|
179
179
|
/**
|
|
180
180
|
* Get or create a domain's agent journey
|
|
181
|
-
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
181
|
+
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint, except a monthly journey usage limit when the key carries one. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
182
182
|
*/
|
|
183
183
|
post: operations["getOrCreateDomainJourney"];
|
|
184
184
|
};
|
|
@@ -203,6 +203,13 @@ export interface paths {
|
|
|
203
203
|
*/
|
|
204
204
|
get: operations["listJourneyAgents"];
|
|
205
205
|
};
|
|
206
|
+
"/api/usage": {
|
|
207
|
+
/**
|
|
208
|
+
* Read your partner API key's usage and usage limits
|
|
209
|
+
* @description Returns the calling key's own usage for the current period, per kind (scans, journeys) and per period (only month today, the calendar month in UTC): how many new dispatches the key started since period_start, its limit, what remains, and when the count resets. Cached and stored answers are not counted. limit and remaining are null when the key has no limit for that kind; a key with no limit is never refused for usage. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); the key is read from the token, so a caller can only see its own numbers. Every response carries Cache-Control: no-store. Rate limited to 60 requests per minute per key.
|
|
210
|
+
*/
|
|
211
|
+
get: operations["getKeyUsage"];
|
|
212
|
+
};
|
|
206
213
|
"/api/feedback/{domain}": {
|
|
207
214
|
/**
|
|
208
215
|
* Get agent feedback for a product
|
|
@@ -539,7 +546,7 @@ export interface components {
|
|
|
539
546
|
* @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.
|
|
540
547
|
* @enum {string}
|
|
541
548
|
*/
|
|
542
|
-
contractVersion: "1.
|
|
549
|
+
contractVersion: "1.38.0";
|
|
543
550
|
/**
|
|
544
551
|
* @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.
|
|
545
552
|
* @enum {boolean}
|
|
@@ -742,7 +749,7 @@ export interface components {
|
|
|
742
749
|
* @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.
|
|
743
750
|
* @enum {string}
|
|
744
751
|
*/
|
|
745
|
-
contractVersion: "1.
|
|
752
|
+
contractVersion: "1.38.0";
|
|
746
753
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
747
754
|
durationMs: number | null;
|
|
748
755
|
/**
|
|
@@ -790,7 +797,7 @@ export interface components {
|
|
|
790
797
|
* @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.
|
|
791
798
|
* @enum {string}
|
|
792
799
|
*/
|
|
793
|
-
contractVersion: "1.
|
|
800
|
+
contractVersion: "1.38.0";
|
|
794
801
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
795
802
|
layers: {
|
|
796
803
|
/** @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'. */
|
|
@@ -889,7 +896,7 @@ export interface components {
|
|
|
889
896
|
* @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.
|
|
890
897
|
* @enum {string}
|
|
891
898
|
*/
|
|
892
|
-
contractVersion: "1.
|
|
899
|
+
contractVersion: "1.38.0";
|
|
893
900
|
/** @description The apex domain derived from the requested URL. */
|
|
894
901
|
domain: string;
|
|
895
902
|
/** @description The normalized URL the run targeted. */
|
|
@@ -2284,6 +2291,61 @@ export interface components {
|
|
|
2284
2291
|
/** @description Optional recovery hint (e.g. /api/scan on NOT_FOUND). */
|
|
2285
2292
|
next?: string;
|
|
2286
2293
|
};
|
|
2294
|
+
/**
|
|
2295
|
+
* @description A partner key's usage per kind, returned by GET /api/usage. Each kind holds one entry per period; month is the only period today, and a future period is a sibling key next to it.
|
|
2296
|
+
* @example {
|
|
2297
|
+
* "key": "acme",
|
|
2298
|
+
* "scans": {
|
|
2299
|
+
* "month": {
|
|
2300
|
+
* "used": 1250,
|
|
2301
|
+
* "limit": 5000,
|
|
2302
|
+
* "remaining": 3750,
|
|
2303
|
+
* "period_start": "2026-10-01T00:00:00.000Z",
|
|
2304
|
+
* "resets_at": "2026-11-01T00:00:00.000Z"
|
|
2305
|
+
* }
|
|
2306
|
+
* },
|
|
2307
|
+
* "journeys": {
|
|
2308
|
+
* "month": {
|
|
2309
|
+
* "used": 12,
|
|
2310
|
+
* "limit": null,
|
|
2311
|
+
* "remaining": null,
|
|
2312
|
+
* "period_start": "2026-10-01T00:00:00.000Z",
|
|
2313
|
+
* "resets_at": "2026-11-01T00:00:00.000Z"
|
|
2314
|
+
* }
|
|
2315
|
+
* }
|
|
2316
|
+
* }
|
|
2317
|
+
*/
|
|
2318
|
+
KeyUsage: {
|
|
2319
|
+
/** @description The name of the key that made the request. */
|
|
2320
|
+
key: string;
|
|
2321
|
+
/** @description Scan dispatches: POST /api/scan, GET /api/scan/stream, POST /api/scan/checks, POST /api/v2/scan and the MCP scan_domain and run_checks tools. */
|
|
2322
|
+
scans: {
|
|
2323
|
+
month: components["schemas"]["KeyUsagePeriod"];
|
|
2324
|
+
};
|
|
2325
|
+
/** @description Journey dispatches: POST /api/journey/runs and POST /api/journey/domains/{host}. */
|
|
2326
|
+
journeys: {
|
|
2327
|
+
month: components["schemas"]["KeyUsagePeriod"];
|
|
2328
|
+
};
|
|
2329
|
+
};
|
|
2330
|
+
/** @description One kind's usage in one period. */
|
|
2331
|
+
KeyUsagePeriod: {
|
|
2332
|
+
/** @description New dispatches the key started since period_start. */
|
|
2333
|
+
used: number;
|
|
2334
|
+
/** @description The key's limit for this kind and period; null when it has none. */
|
|
2335
|
+
limit: number | null;
|
|
2336
|
+
/** @description limit minus used, never below 0; null when there is no limit. At 0 the endpoints that dispatch this kind answer 429 usage_limit_reached until resets_at. */
|
|
2337
|
+
remaining: number | null;
|
|
2338
|
+
/**
|
|
2339
|
+
* Format: date-time
|
|
2340
|
+
* @description Start of the current period (the 1st of the month, 00:00 UTC).
|
|
2341
|
+
*/
|
|
2342
|
+
period_start: string;
|
|
2343
|
+
/**
|
|
2344
|
+
* Format: date-time
|
|
2345
|
+
* @description When the count resets (the 1st of next month, 00:00 UTC).
|
|
2346
|
+
*/
|
|
2347
|
+
resets_at: string;
|
|
2348
|
+
};
|
|
2287
2349
|
/** @description Draft agent discovery files for one domain, returned by GET /api/agent-files/{domain}. */
|
|
2288
2350
|
AgentFilesBundle: {
|
|
2289
2351
|
/** @description The domain the files speak for (leading www. dropped). */
|
|
@@ -2629,7 +2691,7 @@ export interface operations {
|
|
|
2629
2691
|
"application/json": components["schemas"]["McpAuthRequiredResponse"];
|
|
2630
2692
|
};
|
|
2631
2693
|
};
|
|
2632
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=true). Cache-served responses never count against the daily quota. The response includes a Retry-After header indicating seconds until the next request is allowed, and a JSON body with error and retry_after_ms. */
|
|
2694
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=true). Cache-served responses never count against the daily quota. The response includes a Retry-After header indicating seconds until the next request is allowed, and a JSON body with error and retry_after_ms. A keyed caller whose key has used its monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2633
2695
|
429: {
|
|
2634
2696
|
headers: {
|
|
2635
2697
|
/** @description Seconds until next allowed request */
|
|
@@ -2707,7 +2769,7 @@ export interface operations {
|
|
|
2707
2769
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2708
2770
|
};
|
|
2709
2771
|
};
|
|
2710
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP), which this endpoint spends from the same budget as the v1 scan routes so a caller cannot drain it twice by switching endpoints. The response carries a Retry-After header; a durable deny also carries retry_after_ms in the body. */
|
|
2772
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP), which this endpoint spends from the same budget as the v1 scan routes so a caller cannot drain it twice by switching endpoints. The response carries a Retry-After header; a durable deny also carries retry_after_ms in the body. A keyed caller whose key has used its monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2711
2773
|
429: {
|
|
2712
2774
|
headers: {
|
|
2713
2775
|
/** @description Seconds until next allowed request */
|
|
@@ -2767,7 +2829,7 @@ export interface operations {
|
|
|
2767
2829
|
400: {
|
|
2768
2830
|
content: never;
|
|
2769
2831
|
};
|
|
2770
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=1). The response carries a Retry-After header with the seconds until the caller's window frees up. */
|
|
2832
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap or the durable daily quota (30 scans per rolling 24h per IP; 6 per day for force=1). The response carries a Retry-After header with the seconds until the caller's window frees up. A keyed caller whose key has used its monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2771
2833
|
429: {
|
|
2772
2834
|
headers: {
|
|
2773
2835
|
/** @description Seconds until next allowed request */
|
|
@@ -2800,7 +2862,7 @@ export interface operations {
|
|
|
2800
2862
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
2801
2863
|
};
|
|
2802
2864
|
};
|
|
2803
|
-
/** @description Rate limit exceeded - either the 10-per-minute burst cap (body `{ error }`) or the durable daily scan budget shared with POST /api/scan (body also carries `retry_after_ms`). Both carry a Retry-After header with the seconds until the caller's window frees up. */
|
|
2865
|
+
/** @description Rate limit exceeded - either the 10-per-minute burst cap (body `{ error }`) or the durable daily scan budget shared with POST /api/scan (body also carries `retry_after_ms`). Both carry a Retry-After header with the seconds until the caller's window frees up. A keyed caller whose key has used its monthly scan limit gets 429 with error `usage_limit_reached` and `kind`, `period`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
2804
2866
|
429: {
|
|
2805
2867
|
headers: {
|
|
2806
2868
|
/** @description Seconds until next allowed request */
|
|
@@ -3081,22 +3143,24 @@ export interface operations {
|
|
|
3081
3143
|
};
|
|
3082
3144
|
/**
|
|
3083
3145
|
* Search agentic resources (Agentic Resource Discovery)
|
|
3084
|
-
* @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
|
|
3146
|
+
* @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.
|
|
3085
3147
|
*/
|
|
3086
3148
|
ardSearch: {
|
|
3087
3149
|
requestBody: {
|
|
3088
3150
|
content: {
|
|
3089
3151
|
"application/json": {
|
|
3090
3152
|
query: {
|
|
3153
|
+
/** @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. */
|
|
3154
|
+
"@context"?: unknown;
|
|
3091
3155
|
/** @description Free-text search query. May be omitted when filter is present (a filter-only browse); at least one of text/filter is required. */
|
|
3092
3156
|
text?: string;
|
|
3093
|
-
/** @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). */
|
|
3157
|
+
/** @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. */
|
|
3094
3158
|
filter?: {
|
|
3095
3159
|
[key: string]: string | string[];
|
|
3096
3160
|
};
|
|
3097
3161
|
};
|
|
3098
3162
|
/**
|
|
3099
|
-
* @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
|
|
3163
|
+
* @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.
|
|
3100
3164
|
* @default auto
|
|
3101
3165
|
* @enum {string}
|
|
3102
3166
|
*/
|
|
@@ -3106,13 +3170,13 @@ export interface operations {
|
|
|
3106
3170
|
* @default 10
|
|
3107
3171
|
*/
|
|
3108
3172
|
pageSize?: number;
|
|
3109
|
-
/** @description Opaque pagination token from a previous response. */
|
|
3173
|
+
/** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */
|
|
3110
3174
|
pageToken?: string;
|
|
3111
3175
|
};
|
|
3112
3176
|
};
|
|
3113
3177
|
};
|
|
3114
3178
|
responses: {
|
|
3115
|
-
/** @description The ARD SearchResponse: { results, referrals, pageToken? }. pageToken is omitted when the result set is exhausted (never null).
|
|
3179
|
+
/** @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. */
|
|
3116
3180
|
200: {
|
|
3117
3181
|
content: never;
|
|
3118
3182
|
};
|
|
@@ -3138,7 +3202,7 @@ export interface operations {
|
|
|
3138
3202
|
};
|
|
3139
3203
|
/**
|
|
3140
3204
|
* Faceted exploration of agentic resources (Agentic Resource Discovery)
|
|
3141
|
-
* @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.
|
|
3205
|
+
* @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.
|
|
3142
3206
|
*/
|
|
3143
3207
|
ardExplore: {
|
|
3144
3208
|
requestBody: {
|
|
@@ -3146,15 +3210,18 @@ export interface operations {
|
|
|
3146
3210
|
"application/json": {
|
|
3147
3211
|
/** @description Optional query to narrow the set before faceting (same shape as POST /api/ard/search's query). */
|
|
3148
3212
|
query?: {
|
|
3213
|
+
/** @description Optional JSON-LD context, as on POST /api/ard/search. */
|
|
3214
|
+
"@context"?: unknown;
|
|
3149
3215
|
/** @description Free-text search query. */
|
|
3150
3216
|
text?: string;
|
|
3217
|
+
/** @description Same keys as POST /api/ard/search's filter; an unsupported key returns 400 INVALID_ARGUMENT. */
|
|
3151
3218
|
filter?: {
|
|
3152
3219
|
[key: string]: string[];
|
|
3153
3220
|
};
|
|
3154
3221
|
};
|
|
3155
3222
|
resultType: {
|
|
3156
3223
|
facets: {
|
|
3157
|
-
/** @description The resource field to aggregate on. */
|
|
3224
|
+
/** @description The resource field to aggregate on: any search filter key, or category. An unsupported field returns 400 INVALID_ARGUMENT. */
|
|
3158
3225
|
field: string;
|
|
3159
3226
|
/** @description Max facet values to return for this field. */
|
|
3160
3227
|
limit?: number;
|
|
@@ -3197,11 +3264,11 @@ export interface operations {
|
|
|
3197
3264
|
ardListAgents: {
|
|
3198
3265
|
parameters: {
|
|
3199
3266
|
query?: {
|
|
3200
|
-
/** @description Results per page (1-100, default 20). */
|
|
3267
|
+
/** @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. */
|
|
3201
3268
|
pageSize?: number;
|
|
3202
|
-
/** @description Opaque pagination token from a previous response. */
|
|
3269
|
+
/** @description Opaque pagination token from a previous response. A token ora did not issue returns 400 INVALID_ARGUMENT. */
|
|
3203
3270
|
pageToken?: string;
|
|
3204
|
-
/** @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. */
|
|
3271
|
+
/** @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. */
|
|
3205
3272
|
filter?: string;
|
|
3206
3273
|
/** @description Sort expression "<field> [ASC|DESC]", e.g. "displayName DESC". Fields: displayName, updatedAt, identifier, type. */
|
|
3207
3274
|
orderBy?: string;
|
|
@@ -3322,7 +3389,7 @@ export interface operations {
|
|
|
3322
3389
|
};
|
|
3323
3390
|
/**
|
|
3324
3391
|
* Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
|
|
3325
|
-
* @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.
|
|
3392
|
+
* @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:<domain>:..., identity https://<domain>), 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-url>/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/<domain>. 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 <domain>`.
|
|
3326
3393
|
*/
|
|
3327
3394
|
generateAgentFiles: {
|
|
3328
3395
|
parameters: {
|
|
@@ -3485,7 +3552,7 @@ export interface operations {
|
|
|
3485
3552
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3486
3553
|
};
|
|
3487
3554
|
};
|
|
3488
|
-
/** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (20 runs per rolling 24h per IP anonymous, plus 3000 per rolling 24h shared by all anonymous callers, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. */
|
|
3555
|
+
/** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (20 runs per rolling 24h per IP anonymous, plus 3000 per rolling 24h shared by all anonymous callers, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. A keyed caller whose key has used its monthly journey limit gets 429 with error `usage_limit_reached` and `kind`, `period`, `used`, `limit`, `resets_at` and `retry_after_ms`; its Retry-After counts to the next 1st of the month (UTC). That refusal is key-wide; GET /api/usage shows the numbers. */
|
|
3489
3556
|
429: {
|
|
3490
3557
|
headers: {
|
|
3491
3558
|
/** @description Seconds until next allowed request */
|
|
@@ -3529,7 +3596,7 @@ export interface operations {
|
|
|
3529
3596
|
};
|
|
3530
3597
|
/**
|
|
3531
3598
|
* Get or create a domain's agent journey
|
|
3532
|
-
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
3599
|
+
* @description Returns the agent journey for a domain, running one only if there is not one already. Send only the domain and no body: ora selects the intent and the agent. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); without one, 401 PARTNER_KEY_REQUIRED. 200 means nothing was dispatched and an existing run answered, either finished (carrying its `result`) or still running (open `stream_url` to watch it). 201 means a new run was dispatched. Branch on `dispatched`. Two response views (see the `view` parameter): `graph` (JourneyDomainRunGraph, the default - `result` narrowed to what drawing the journey needs) and `full` (JourneyDomainRun, the complete projection, on `?view=full`). A finished run is served indefinitely; `run_age_seconds` gives its age. There is no per-caller rate limit on this endpoint, except a monthly journey usage limit when the key carries one. Each domain is capped at 100 runs per rolling 24h, and one domain cannot start two runs at once - both are per-domain, neither limits how many domains you may ask for or how fast.
|
|
3533
3600
|
*/
|
|
3534
3601
|
getOrCreateDomainJourney: {
|
|
3535
3602
|
parameters: {
|
|
@@ -3567,7 +3634,7 @@ export interface operations {
|
|
|
3567
3634
|
"application/json": components["schemas"]["ErrorResponse"];
|
|
3568
3635
|
};
|
|
3569
3636
|
};
|
|
3570
|
-
/** @description Back off and retry the SAME DOMAIN; the body carries `retry_after_ms` and a `Retry-After` header. All three codes here are per-domain, never key-wide, so do not throttle your other traffic. `POLL_TOO_FAST`: more than 3 requests for this domain inside 2 seconds; back off by this response's `retry_after_ms`. The in-flight `200` also carries `retry_after_ms`, and a poller that honours it never sees this code. `DISPATCH_IN_PROGRESS`: another request is already starting this domain. `TARGET_CAPPED`: this domain is over its 100-per-24h cap. */
|
|
3637
|
+
/** @description Back off and retry the SAME DOMAIN; the body carries `retry_after_ms` and a `Retry-After` header. All three codes here are per-domain, never key-wide, so do not throttle your other traffic. `POLL_TOO_FAST`: more than 3 requests for this domain inside 2 seconds; back off by this response's `retry_after_ms`. The in-flight `200` also carries `retry_after_ms`, and a poller that honours it never sees this code. `DISPATCH_IN_PROGRESS`: another request is already starting this domain. `TARGET_CAPPED`: this domain is over its 100-per-24h cap. One refusal here is key-wide instead: `error: "usage_limit_reached"` (no `code`) means the key has used its monthly journey limit, with `kind`, `period`, `used`, `limit`, `resets_at` and `retry_after_ms` in the body and a Retry-After that counts to the next 1st of the month (UTC); stop dispatching journeys until `resets_at`. GET /api/usage shows the numbers. */
|
|
3571
3638
|
429: {
|
|
3572
3639
|
headers: {
|
|
3573
3640
|
/** @description Seconds until next allowed request */
|
|
@@ -3677,6 +3744,42 @@ export interface operations {
|
|
|
3677
3744
|
};
|
|
3678
3745
|
};
|
|
3679
3746
|
};
|
|
3747
|
+
/**
|
|
3748
|
+
* Read your partner API key's usage and usage limits
|
|
3749
|
+
* @description Returns the calling key's own usage for the current period, per kind (scans, journeys) and per period (only month today, the calendar month in UTC): how many new dispatches the key started since period_start, its limit, what remains, and when the count resets. Cached and stored answers are not counted. limit and remaining are null when the key has no limit for that kind; a key with no limit is never refused for usage. Requires an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora); the key is read from the token, so a caller can only see its own numbers. Every response carries Cache-Control: no-store. Rate limited to 60 requests per minute per key.
|
|
3750
|
+
*/
|
|
3751
|
+
getKeyUsage: {
|
|
3752
|
+
responses: {
|
|
3753
|
+
/** @description The key's usage, limits and reset time. */
|
|
3754
|
+
200: {
|
|
3755
|
+
content: {
|
|
3756
|
+
"application/json": components["schemas"]["KeyUsage"];
|
|
3757
|
+
};
|
|
3758
|
+
};
|
|
3759
|
+
/** @description `code: "PARTNER_KEY_REQUIRED"` - no recognized partner API key. An absent, malformed and unrecognized key all answer the same way. */
|
|
3760
|
+
401: {
|
|
3761
|
+
content: {
|
|
3762
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
3763
|
+
};
|
|
3764
|
+
};
|
|
3765
|
+
/** @description `code: "RATE_LIMITED"` - more than 60 requests in a minute from this address, or for this key. */
|
|
3766
|
+
429: {
|
|
3767
|
+
headers: {
|
|
3768
|
+
/** @description Seconds until next allowed request */
|
|
3769
|
+
"Retry-After"?: number;
|
|
3770
|
+
};
|
|
3771
|
+
content: {
|
|
3772
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
3773
|
+
};
|
|
3774
|
+
};
|
|
3775
|
+
/** @description `code: "USAGE_UNAVAILABLE"` - usage could not be read right now. Retry shortly; the route never answers a guessed zero. */
|
|
3776
|
+
503: {
|
|
3777
|
+
content: {
|
|
3778
|
+
"application/json": components["schemas"]["ErrorResponse"];
|
|
3779
|
+
};
|
|
3780
|
+
};
|
|
3781
|
+
};
|
|
3782
|
+
};
|
|
3680
3783
|
/**
|
|
3681
3784
|
* Get agent feedback for a product
|
|
3682
3785
|
* @description Returns feedback submitted by AI agents about their experience using a product. Includes aggregate stats and individual reviews.
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
/** The ora contract version (spec info.version) these types were generated from. */
|
|
2
|
-
export declare const BUILT_AGAINST = "1.
|
|
2
|
+
export declare const BUILT_AGAINST = "1.38.0";
|
package/dist/index.cjs
CHANGED
|
@@ -70,6 +70,20 @@ async function errorBody(res) {
|
|
|
70
70
|
payload
|
|
71
71
|
};
|
|
72
72
|
}
|
|
73
|
+
async function usageLimitMessage(res) {
|
|
74
|
+
let body = null;
|
|
75
|
+
try {
|
|
76
|
+
body = await res.clone().json();
|
|
77
|
+
} catch {
|
|
78
|
+
return null;
|
|
79
|
+
}
|
|
80
|
+
if (body?.error !== "usage_limit_reached") return null;
|
|
81
|
+
const used = body.used !== void 0 && body.limit !== void 0 ? ` (${body.used} of ${body.limit})` : "";
|
|
82
|
+
const resets = body.resets_at ? ` It resets at ${body.resets_at}.` : "";
|
|
83
|
+
const scope = body.kind ? `${body.kind} limit` : "usage limit";
|
|
84
|
+
const period = body.period ? ` for the ${body.period}` : "";
|
|
85
|
+
return `this API key has used its ${scope}${period}${used}.${resets} GET /api/usage shows the numbers; ask ora to raise the limit.`;
|
|
86
|
+
}
|
|
73
87
|
async function errorBodyText(res) {
|
|
74
88
|
return (await errorBody(res)).message;
|
|
75
89
|
}
|
|
@@ -142,7 +156,7 @@ async function fetchAgentFiles(domain, options = {}) {
|
|
|
142
156
|
}
|
|
143
157
|
|
|
144
158
|
// src/contract/version.ts
|
|
145
|
-
var BUILT_AGAINST = "1.
|
|
159
|
+
var BUILT_AGAINST = "1.38.0";
|
|
146
160
|
|
|
147
161
|
// src/contract/index.ts
|
|
148
162
|
function minor(version) {
|
|
@@ -220,6 +234,8 @@ async function consumeScanStream(base, target, options) {
|
|
|
220
234
|
}
|
|
221
235
|
if (res.status === 429) {
|
|
222
236
|
dog.disarm();
|
|
237
|
+
const usage = await usageLimitMessage(res);
|
|
238
|
+
if (usage) throw new AuditApiError(`ora usage limit reached: ${usage}`);
|
|
223
239
|
const wait = res.headers.get("retry-after");
|
|
224
240
|
throw new AuditApiError(
|
|
225
241
|
`ora rate limit exceeded${wait ? ` \u2014 retry after ${wait}s` : ""} (burst: 10 scans/min/IP; daily: 30 scans + 6 force per 24h). An ora-issued scan API key lifts these limits: set ORA_SCAN_API_KEY or pass --api-key.`
|
|
@@ -452,6 +468,8 @@ async function triggerRun(base, target, options) {
|
|
|
452
468
|
);
|
|
453
469
|
}
|
|
454
470
|
if (res.status === 429) {
|
|
471
|
+
const usage = await usageLimitMessage(res);
|
|
472
|
+
if (usage) throw new DeepJourneyApiError(`ora usage limit reached: ${usage}`);
|
|
455
473
|
const wait = res.headers.get("retry-after");
|
|
456
474
|
const caps = options.apiKey ? "keyed allowance: 1000 runs per 24h per key" : "burst: 20/min/IP; daily: 20 runs per 24h per IP \u2014 an ora partner API key raises this to 1000/24h per key: set ORA_PARTNER_API_KEY or pass --api-key";
|
|
457
475
|
throw new DeepJourneyApiError(
|
package/dist/index.js
CHANGED
|
@@ -32,6 +32,20 @@ async function errorBody(res) {
|
|
|
32
32
|
payload
|
|
33
33
|
};
|
|
34
34
|
}
|
|
35
|
+
async function usageLimitMessage(res) {
|
|
36
|
+
let body = null;
|
|
37
|
+
try {
|
|
38
|
+
body = await res.clone().json();
|
|
39
|
+
} catch {
|
|
40
|
+
return null;
|
|
41
|
+
}
|
|
42
|
+
if (body?.error !== "usage_limit_reached") return null;
|
|
43
|
+
const used = body.used !== void 0 && body.limit !== void 0 ? ` (${body.used} of ${body.limit})` : "";
|
|
44
|
+
const resets = body.resets_at ? ` It resets at ${body.resets_at}.` : "";
|
|
45
|
+
const scope = body.kind ? `${body.kind} limit` : "usage limit";
|
|
46
|
+
const period = body.period ? ` for the ${body.period}` : "";
|
|
47
|
+
return `this API key has used its ${scope}${period}${used}.${resets} GET /api/usage shows the numbers; ask ora to raise the limit.`;
|
|
48
|
+
}
|
|
35
49
|
async function errorBodyText(res) {
|
|
36
50
|
return (await errorBody(res)).message;
|
|
37
51
|
}
|
|
@@ -104,7 +118,7 @@ async function fetchAgentFiles(domain, options = {}) {
|
|
|
104
118
|
}
|
|
105
119
|
|
|
106
120
|
// src/contract/version.ts
|
|
107
|
-
var BUILT_AGAINST = "1.
|
|
121
|
+
var BUILT_AGAINST = "1.38.0";
|
|
108
122
|
|
|
109
123
|
// src/contract/index.ts
|
|
110
124
|
function minor(version) {
|
|
@@ -182,6 +196,8 @@ async function consumeScanStream(base, target, options) {
|
|
|
182
196
|
}
|
|
183
197
|
if (res.status === 429) {
|
|
184
198
|
dog.disarm();
|
|
199
|
+
const usage = await usageLimitMessage(res);
|
|
200
|
+
if (usage) throw new AuditApiError(`ora usage limit reached: ${usage}`);
|
|
185
201
|
const wait = res.headers.get("retry-after");
|
|
186
202
|
throw new AuditApiError(
|
|
187
203
|
`ora rate limit exceeded${wait ? ` \u2014 retry after ${wait}s` : ""} (burst: 10 scans/min/IP; daily: 30 scans + 6 force per 24h). An ora-issued scan API key lifts these limits: set ORA_SCAN_API_KEY or pass --api-key.`
|
|
@@ -414,6 +430,8 @@ async function triggerRun(base, target, options) {
|
|
|
414
430
|
);
|
|
415
431
|
}
|
|
416
432
|
if (res.status === 429) {
|
|
433
|
+
const usage = await usageLimitMessage(res);
|
|
434
|
+
if (usage) throw new DeepJourneyApiError(`ora usage limit reached: ${usage}`);
|
|
417
435
|
const wait = res.headers.get("retry-after");
|
|
418
436
|
const caps = options.apiKey ? "keyed allowance: 1000 runs per 24h per key" : "burst: 20/min/IP; daily: 20 runs per 24h per IP \u2014 an ora partner API key raises this to 1000/24h per key: set ORA_PARTNER_API_KEY or pass --api-key";
|
|
419
437
|
throw new DeepJourneyApiError(
|