@opusdns/api 1.137.0 → 1.138.0

package/README.md

@@ -61,34 +61,69 @@ import {
 
 ## Documentation
 
-There are two documentation setups in this repository:
-
-### Legacy: GitHub Pages API Reference (production)
-
-The `docs/` folder is a static site that embeds
-[`@scalar/api-reference`](https://github.com/scalar/scalar) and is published
-via GitHub Pages on [developers.opusdns.com](https://developers.opusdns.com/).
-Source of truth: [`docs/index.html`](./docs/index.html). Do **not** put
-guides/Markdown content here.
-
-### Scalar Docs 2.0 (local preview)
-
-A more sophisticated documentation setup using
-[Scalar Docs 2.0](https://scalar.com/products/docs/getting-started) is
-contained in [`scalar/`](./scalar/). The Scalar project config lives at
-[`scalar/scalar.config.json`](./scalar/scalar.config.json), guide content lives
-under [`scalar/content/`](./scalar/content/), and the API reference is
-fetched from the raw GitHub copy of [`src/openapi.yaml`](./src/openapi.yaml).
-
-To preview locally:
+[developers.opusdns.com](https://developers.opusdns.com/) is served by
+[Scalar Docs 2.0](https://scalar.com/products/docs/getting-started) from
+[`scalar/`](./scalar/) in this repository.
+
+### How publishing works
+
+**Merging to `main` publishes.** Scalar's GitHub integration builds `main`; there
+is no deploy workflow in this repo and no Scalar token. The custom domain is
+declared in the config itself
+([`scalar/scalar.config.json`](./scalar/scalar.config.json), `siteConfig.customDomain`),
+not in CI. Nothing in the repository shows this connection, so it is written down
+here: if publishing ever stops, the integration in the Scalar dashboard is where
+to look.
+
+**Every PR gets a preview.** The same integration builds each pull request and
+posts a throwaway URL as a comment (`…--opusdns-api-spec.apidocumentation.com`),
+so you can read a change as rendered before merging it. Use it — a bad `filepath`
+or an icon name Scalar does not know renders as nothing rather than failing, and
+merging is what makes that public.
+
+The preview does not, however, cover the bots' own PRs: GitHub suppresses
+workflow runs for pull requests opened with a token rather than by a person, so
+both bots validate the config inline before opening theirs.
+
+### Layout
+
+| Path | What |
+| --- | --- |
+| `scalar/scalar.config.json` | The whole site: tabs, sidebar routes, theme. Every page's title, icon and URL live here — content files carry no frontmatter |
+| `scalar/content/` | Guide Markdown |
+| `scalar/content/tld-knowledge-base/` | **Generated** from `OpusDNS/tld-specifications` by `scripts/generate_tld_knowledge_base.py` |
+| `scalar/content/mcp-server/` | **Generated** in `OpusDNS/opusdns-mcp`, which opens a PR here carrying the diff. `scripts/sync_mcp_docs.py` lives here but is run from there — see [`scripts/mcp_docs/`](./scripts/mcp_docs/) |
+| `src/openapi.yaml` | The spec. The API Reference tab is fetched by Scalar from the raw GitHub URL at build time, so it is eventually consistent rather than bundled |
+
+Two bots write `scalar.config.json`: **Generate TLD Knowledge Base**, a workflow
+in this repo, and **Publish MCP docs to api-spec**, a workflow in
+`OpusDNS/opusdns-mcp` that opens its PR here. Each rebuilds only the subtree it
+owns and both serialise identically (`json.dumps(..., indent=2,
+ensure_ascii=False)` plus a trailing newline), so hand edits should match that
+style — otherwise the next bot PR reformats your lines.
+
+### Local preview
 
 ```bash
 npm install
 npm --prefix scalar install
 npm run docs:preview
 # → http://localhost:7970
+
+npm --prefix scalar run check   # validate scalar.config.json
 ```
 
+Run `check` before pushing anything that touches the config. A `filepath`
+pointing at a file that does not exist, or an icon name Scalar does not know,
+renders as nothing — and merging is what publishes.
+
+### The legacy `docs/` folder
+
+[`docs/`](./docs/) is a static GitHub Pages site that embeds
+[`@scalar/api-reference`](https://github.com/scalar/scalar). GitHub Pages is
+still configured for it, but DNS points at Scalar, so **it is not what serves the
+domain**. Treat it as vestigial; do not put content there.
+
 ### Links
 
 - [Main website](https://www.opusdns.com/)

package/package.json

@@ -3,7 +3,7 @@
     "@opusdns/api-spec-ts-generator": "^1.5.0"
   },
   "name": "@opusdns/api",
-  "version": "1.137.0",
+  "version": "1.138.0",
   "description": "TypeScript types for the OpusDNS OpenAPI specification",
   "main": "./src/index.ts",
   "module": "./src/index.ts",

package/src/openapi.yaml

@@ -15765,7 +15765,7 @@ info:
     \n\n"
   summary: OpusDNS - your gateway to a seamless domain management experience.
   title: OpusDNS API
-  version: 2026-08-26-021624
+  version: 2026-08-26-165903
   x-logo:
     altText: OpusDNS API Reference
     url: https://d24lr4zqs1tgqh.cloudfront.net/c9505a20-5ae1-406c-b060-d392569caebf.jpg
@@ -23423,18 +23423,33 @@ paths:
       - domain_forwards:manage
   /v1/domain-search/suggest:
     get:
-      description: Get a list of domain suggestions based on a search query
+      description: "Get a list of domain suggestions based on a search query.\n\n\
+        Suggestions are generated and ranked by relevance rather than enumerated from\
+        \ a fixed list, so the\nresults depend on the shape of `query`:\n\n- **Keyword\
+        \ or phrase** (e.g. `bluewidgets`) \u2014 every result is a generated name,\
+        \ and its `available`\n  flag is best-effort.\n- **Full domain name** (e.g.\
+        \ `bluewidgets.de`) \u2014 the queried domain is always returned as the first\n\
+        \  result, with availability checked directly against the registry.\n\nUse\
+        \ a full domain name, or `GET /v1/availability`, whenever you need a definitive\
+        \ answer about a\nspecific domain."
       operationId: suggest_v1_domain_search_suggest_get
       parameters:
-      - description: The primary keyword or phrase for the domain search
+      - description: The primary keyword or phrase for the domain search. A full domain
+          name is always returned as the first result, with registry-checked availability.
         in: query
         name: query
         required: true
         schema:
-          description: The primary keyword or phrase for the domain search
+          description: The primary keyword or phrase for the domain search. A full
+            domain name is always returned as the first result, with registry-checked
+            availability.
           title: Query
           type: string
-      - description: The TLDs to include in the search
+      - description: 'Restricts results to these TLDs. This is a filter, not a guarantee:
+          suggestions are ranked by relevance across the whole requested set, so a
+          listed TLD may be absent from the results even when available names exist
+          in it, and raising `limit` does not change that. To guarantee a TLD is represented,
+          query it on its own.'
         examples:
           list:
             summary: A list of TLDs
@@ -23451,7 +23466,11 @@ paths:
               type: string
             type: array
           - type: 'null'
-          description: The TLDs to include in the search
+          description: 'Restricts results to these TLDs. This is a filter, not a guarantee:
+            suggestions are ranked by relevance across the whole requested set, so
+            a listed TLD may be absent from the results even when available names
+            exist in it, and raising `limit` does not change that. To guarantee a
+            TLD is represented, query it on its own.'
           title: Tlds
       - description: The maximum number of domain suggestions to return
         in: query
@@ -33664,9 +33683,33 @@ tags:
 - description: ''
   name: domain_tld_specific
   x-displayName: TLD specific domain management
-- description: 'Endpoints for searching domains.
-
-    '
+- description: "Endpoints for searching domains.\n\n### Keyword queries vs. full domain\
+    \ names\n\n`GET /v1/domain-search/suggest` behaves differently depending on the\
+    \ shape of the `query` value:\n\n- **Keyword or phrase** (e.g. `bluewidgets`)\
+    \ \u2014 every result is a name produced by our suggestion engine, which generates\
+    \ candidates and ranks them by relevance. No particular name is guaranteed to\
+    \ appear.\n- **Full domain name** (e.g. `bluewidgets.de`) \u2014 the queried domain\
+    \ is always returned as the first result, and its availability is checked directly\
+    \ against the registry rather than coming from the suggestion engine.\n\nUse a\
+    \ full domain name whenever you need a definitive answer about one specific domain.\
+    \ To check several specific domains at once, use `GET /v1/availability` instead.\n\
+    \n### `tlds` restricts results, it does not guarantee them\n\nThe `tlds` parameter\
+    \ is a filter: results are limited to the TLDs you list, but a TLD you list may\
+    \ still be absent from the response. Suggestions are ranked by relevance across\
+    \ the whole requested set, so a keyword whose strongest candidates are `.com`/`.net`/`.org`\
+    \ names can return no `.de` results even though available `.de` names exist for\
+    \ that keyword.\n\nThis is consistent for a given keyword rather than random \u2014\
+    \ the same query returns the same TLD mix each time \u2014 and raising `limit`\
+    \ does not change it.\n\nTo guarantee that a TLD is represented, query it on its\
+    \ own:\n\n```\nGET /v1/domain-search/suggest?query=bluewidgets&tlds=de&limit=5\n\
+    ```\n\nIssuing one request per TLD is the reliable way to build a per-TLD view\
+    \ in a search interface.\n\n### Availability of suggestions\n\nThe `available`\
+    \ flag on a generated suggestion is best-effort. Our suggestion engine's data\
+    \ is not authoritative for every TLD, and it is less accurate for some ccTLDs,\
+    \ so a suggestion can occasionally be shown as available when it is not.\n\nAvailability\
+    \ is authoritative in two cases: when the query is a full domain name (the first\
+    \ result), and for domains checked via `GET /v1/availability`. Always confirm\
+    \ with one of those before presenting a domain as purchasable.\n"
   name: domain_search
   x-displayName: Domain search
 - description: "Endpoints for managing host objects (nameserver glue records).\n\n\

package/src/schema.d.ts

@@ -1063,7 +1063,18 @@ export interface paths {
         };
         /**
          * Suggest domains
-         * @description Get a list of domain suggestions based on a search query
+         * @description Get a list of domain suggestions based on a search query.
+         *
+         *     Suggestions are generated and ranked by relevance rather than enumerated from a fixed list, so the
+         *     results depend on the shape of `query`:
+         *
+         *     - **Keyword or phrase** (e.g. `bluewidgets`) — every result is a generated name, and its `available`
+         *       flag is best-effort.
+         *     - **Full domain name** (e.g. `bluewidgets.de`) — the queried domain is always returned as the first
+         *       result, with availability checked directly against the registry.
+         *
+         *     Use a full domain name, or `GET /v1/availability`, whenever you need a definitive answer about a
+         *     specific domain.
          */
         get: operations["suggest_v1_domain_search_suggest_get"];
         put?: never;
@@ -19178,9 +19189,9 @@ export interface operations {
     suggest_v1_domain_search_suggest_get: {
         parameters: {
             query: {
-                /** @description The primary keyword or phrase for the domain search */
+                /** @description The primary keyword or phrase for the domain search. A full domain name is always returned as the first result, with registry-checked availability. */
                 query: string;
-                /** @description The TLDs to include in the search */
+                /** @description Restricts results to these TLDs. This is a filter, not a guarantee: suggestions are ranked by relevance across the whole requested set, so a listed TLD may be absent from the results even when available names exist in it, and raising `limit` does not change that. To guarantee a TLD is represented, query it on its own. */
                 tlds?: string[] | null;
                 /** @description The maximum number of domain suggestions to return */
                 limit?: number | null;