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.
@@ -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 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.
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.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:<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>`.
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.32.0";
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.32.0";
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.32.0";
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.32.0";
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 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.
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 degrades to own-results-only when disabled.
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). 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. */
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.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:<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>`.
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.32.0";
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.32.0";
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.32.0";
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(