ris-mcp-ts 1.1.3 → 1.3.0

package/README.md

@@ -33,11 +33,11 @@ The server translates these natural language requests into structured API calls
 
 - **12 specialized tools** covering all major RIS collections
 - **Federal law** (ABGB, StGB, UGB, ...) and **state law** for all 9 provinces
-- **Court decisions** from 11 court types (Supreme Court, Constitutional Court, Administrative Court, ...)
+- **Court decisions** from 16 court types (Supreme Court, Constitutional Court, Administrative Court, ...)
 - **Law gazettes** — Federal (BGBl) and state (LGBl)
 - **Government bills**, ministerial decrees, cabinet protocols
 - **Full document retrieval** with smart prefix-based routing
-- **Change history tracking** across 30 application types
+- **Change history tracking** across 36 application types
 - **Markdown and JSON** output formats
 - **Free and open** — uses Austria's Open Government Data API, no API key needed
 
@@ -148,7 +148,7 @@ npx -y ris-mcp-ts
 |------|-------------|
 | `ris_bundesrecht` | Search federal laws (ABGB, StGB, UGB, etc.) |
 | `ris_landesrecht` | Search state/provincial laws (all 9 provinces) |
-| `ris_judikatur` | Search court decisions (11 court types) |
+| `ris_judikatur` | Search court decisions (16 court types) |
 | `ris_bundesgesetzblatt` | Search Federal Law Gazettes (BGBl I/II/III) |
 | `ris_landesgesetzblatt` | Search State Law Gazettes (LGBl) |
 | `ris_regierungsvorlagen` | Search government bills |
@@ -156,7 +156,7 @@ npx -y ris-mcp-ts
 | `ris_bezirke` | Search district authority announcements |
 | `ris_gemeinden` | Search municipal law and regulations |
 | `ris_sonstige` | Search miscellaneous collections (8 sub-apps) |
-| `ris_history` | Track document change history (30 app types) |
+| `ris_history` | Track document change history (36 app types) |
 | `ris_verordnungen` | Search state ordinance gazettes |
 
 ## Tool Reference
@@ -172,8 +172,9 @@ Search Austrian federal laws such as ABGB, StGB, UGB, and more.
 |-----------|------|-------------|
 | `suchworte` | string | Full-text search (e.g., "Mietrecht", "Schadenersatz") |
 | `titel` | string | Search in law titles (e.g., "ABGB", "Strafgesetzbuch") |
-| `paragraph` | string | Section number (e.g., "1295" for §1295) |
-| `applikation` | string | "BrKons" (consolidated, default), "Begut" (draft reviews), "Erv" (English version) |
+| `paragraph` | string | Section number (e.g., "1295" for §1295, "7" for Art 7) |
+| `abschnitt_typ` | string | Type of section `paragraph` refers to: "Paragraph" (default), "Artikel" (article-based laws like B-VG), "Anlage" (annex) |
+| `applikation` | string | "BrKons" (consolidated, default), "Begut" (drafts), "BgblAuth" (gazette), "Erv" (English translations) |
 | `fassung_vom` | string | Date for historical version (YYYY-MM-DD) |
 | `seite` | number | Page number (default: 1) |
 | `limit` | number | Results per page: 10, 20, 50, 100 (default: 20) |
@@ -181,6 +182,8 @@ Search Austrian federal laws such as ABGB, StGB, UGB, and more.
 
 All parameters are optional. At least one search parameter (`suchworte`, `titel`, or `paragraph`) should be provided.
 
+> **Note:** `applikation="Erv"` (English translations) uses a different parameter vocabulary internally (`SearchTerms`/`Title`) and does not support `paragraph`/`abschnitt_typ` or `fassung_vom`.
+
 </details>
 
 <details>
@@ -195,6 +198,10 @@ Search state laws of the nine Austrian provinces.
 | `suchworte` | string | Full-text search |
 | `titel` | string | Search in law titles |
 | `bundesland` | string | Province: Wien, Niederoesterreich, Oberoesterreich, Salzburg, Tirol, Vorarlberg, Kaernten, Steiermark, Burgenland |
+| `paragraph` | string | Section number (e.g., "1" for §1, "7" for Art 7) |
+| `abschnitt_typ` | string | Type of section `paragraph` refers to: "Paragraph" (default), "Artikel", "Anlage" |
+| `fassung_vom` | string | Date for historical version (YYYY-MM-DD) |
+| `gesetzesnummer` | string | Exact law number (Gesetzesnummer) of a specific state law |
 | `applikation` | string | "LrKons" (consolidated, default) |
 | `seite` | number | Page number |
 | `limit` | number | Results per page |
@@ -212,18 +219,25 @@ Search court decisions from Austrian courts.
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `suchworte` | string | Full-text search in decisions |
-| `gericht` | string | Court type (see below) |
+| `gerichtsbarkeit` | string | Court system / data collection to search — the RIS "Applikation" (see below; default "Justiz") |
+| `dokumenttyp` | string | "rechtssatz" (headnotes only), "entscheidungstext" (full texts only), or "beide" (both, default) |
+| `gericht` | string | Actual court within the jurisdiction (e.g., "OGH", "OLG Wien"); applies to gerichtsbarkeit="Justiz" |
+| `rechtsgebiet` | string | Broad legal area: "Zivilrecht" or "Strafrecht" (Justiz) |
+| `fachgebiet` | string | OGH subject area (e.g., "Arbeitsrecht"); Justiz, needs dokumenttyp "entscheidungstext"/"beide" |
+| `entscheidungsart` | string | Decision type (e.g., "Erkenntnis", "Beschluss"); allowed values differ by jurisdiction |
+| `sammlungsnummer` | string | Collection number: VfSlg (Vfgh) or VwSlg (Vwgh) |
 | `norm` | string | Legal norm (e.g., "1319a ABGB") |
 | `geschaeftszahl` | string | Case number (e.g., "5Ob234/20b") |
 | `entscheidungsdatum_von` | string | Decision date from (YYYY-MM-DD) |
 | `entscheidungsdatum_bis` | string | Decision date to (YYYY-MM-DD) |
+| `sortierung` | string | Sort by decision date: "datum_auf" (oldest first) or "datum_ab" (newest first) |
 | `seite` | number | Page number |
 | `limit` | number | Results per page |
 | `response_format` | string | "markdown" or "json" |
 
-**Available courts:**
+**Available `gerichtsbarkeit` values (16):**
 
-| Value | Court |
+| Value | Court system |
 |-------|-------|
 | `Justiz` | Supreme Court (OGH), Higher Regional Courts (OLG), Regional Courts (LG) — default |
 | `Vfgh` | Constitutional Court |
@@ -231,11 +245,16 @@ Search court decisions from Austrian courts.
 | `Bvwg` | Federal Administrative Court |
 | `Lvwg` | Provincial Administrative Courts |
 | `Dsk` | Data Protection Authority |
-| `AsylGH` | Asylum Court (historical) |
+| `AsylGH` | Asylum Court (historical, until 2013) |
 | `Normenliste` | Index of legal norms |
 | `Pvak` | Personnel Representation Supervisory Commission |
 | `Gbk` | Equal Treatment Commission |
 | `Dok` | Disciplinary Commission |
+| `Verg` | Federal Procurement Office (historical, dissolved 2014) |
+| `Uvs` | Independent Administrative Senates (historical, dissolved 2014) |
+| `Ubas` | Independent Federal Asylum Senate (historical, dissolved 2014) |
+| `Umse` | Environmental Senate (historical, dissolved 2014) |
+| `Bks` | Federal Communications Board (historical, dissolved 2014) |
 
 </details>
 
@@ -325,12 +344,19 @@ At least one of `dokumentnummer` or `url` is required. Long documents are trunca
 |--------|------|
 | NOR | Federal norms |
 | LBG, LKT, LNO, LOO, LSB, LST, LTI, LVB, LWI | State laws (9 provinces) |
-| JWR, JFR, JWT, BVWG, LVWG, DSB, GBK, PVAK, ASYLGH | Court decisions |
-| BGBLA, BGBL | Federal Law Gazette |
+| JWR, JWT | Supreme Administrative Court (VwGH) |
+| JFR, JFT | Constitutional Court (VfGH) |
+| JJR, JJT | Ordinary courts (Justiz) |
+| BVWG, LVWG | Federal / State Administrative Courts |
+| DSB, PDK, GBK, PVAB, DKT, NL, ASYLGH | Data protection, equal treatment, personnel, disciplinary, norm lists, asylum |
+| VERG, JUR, JUT, UBAS, UMSE, BKS | Historical jurisdictions (dissolved 2014) |
+| BGBLA, BGBL, BGBLPDF | Federal Law Gazette (authentic / 1945–2003 / PDF) |
 | REGV | Government bills |
 | BVB | District authorities |
 | VBL | Ordinance gazettes |
-| MRP, ERL | Cabinet protocols, ministerial decrees |
+| MRP, ERL, PRUEF, AVSV, SPG, KMGER | Cabinet protocols, decrees, trade exams, social insurance, health plans, court announcements |
+
+> The full routing registry lives in `DOCUMENT_ROUTES` (`src/client.ts`); unknown prefixes fall back to a Justiz search.
 
 </details>
 

package/dist/client.d.ts

@@ -35,35 +35,35 @@ export declare function isAllowedUrl(url: string): boolean;
 /**
  * Search federal law (Bundesrecht).
  */
-export declare function searchBundesrecht(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchBundesrecht(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Search state/provincial law (Landesrecht).
  */
-export declare function searchLandesrecht(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchLandesrecht(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Search case law/jurisprudence (Judikatur).
  */
-export declare function searchJudikatur(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchJudikatur(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Search district administrative authorities (Bezirke).
  */
-export declare function searchBezirke(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchBezirke(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Search municipal law (Gemeinden).
  */
-export declare function searchGemeinden(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchGemeinden(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Search miscellaneous legal collections (Sonstige).
  */
-export declare function searchSonstige(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchSonstige(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Search document change history (History).
  */
-export declare function searchHistory(params: Record<string, unknown>, timeout?: number): Promise<NormalizedSearchResults>;
+export declare function searchHistory(params: Record<string, unknown>, timeout?: number, signal?: AbortSignal): Promise<NormalizedSearchResults>;
 /**
  * Fetch HTML content from a document URL.
  */
-export declare function getDocumentContent(url: string, timeout?: number): Promise<string>;
+export declare function getDocumentContent(url: string, timeout?: number, signal?: AbortSignal): Promise<string>;
 /**
  * Validate dokumentnummer contains only safe characters.
  * Defense-in-depth check in addition to Zod schema.
@@ -76,6 +76,28 @@ export declare function getDocumentContent(url: string, timeout?: number): Promi
  * Examples: NOR40052761, BVWG_W123_2000000_1_00
  */
 export declare function isValidDokumentnummer(dokumentnummer: string): boolean;
+/**
+ * RIS search endpoint used for the fallback search when direct URL fetch fails.
+ */
+export type DocumentEndpoint = 'Bundesrecht' | 'Landesrecht' | 'Judikatur' | 'Sonstige' | 'Bezirke';
+/**
+ * Routing information for a Dokumentnummer prefix.
+ */
+export interface DocumentRoute {
+    /** Folder segment in the ris.bka.gv.at/Dokumente/<folder>/ direct URL. */
+    urlFolder: string;
+    /** Search endpoint used for the fallback search. */
+    endpoint: DocumentEndpoint;
+    /** `Applikation` API parameter for the fallback search. */
+    applikation: string;
+}
+/**
+ * Look up the routing information for a Dokumentnummer by its prefix.
+ *
+ * @param dokumentnummer - The RIS document number (e.g., "NOR12019037")
+ * @returns The matching route, or null if the prefix is unknown
+ */
+export declare function getDocumentRoute(dokumentnummer: string): DocumentRoute | null;
 /**
  * Construct a direct document URL based on the Dokumentnummer prefix.
  *
@@ -103,7 +125,9 @@ export type DirectDocumentResult = {
  *
  * @param dokumentnummer - The RIS document number (e.g., "NOR12019037")
  * @param timeout - Request timeout in milliseconds
+ * @param signal - Caller's cancellation signal; a cancellation is thrown rather
+ *   than reported as an unsuccessful fetch, so callers do not fall back to a search
  * @returns Result object with HTML content on success, or error details on failure
  */
-export declare function getDocumentByNumber(dokumentnummer: string, timeout?: number): Promise<DirectDocumentResult>;
+export declare function getDocumentByNumber(dokumentnummer: string, timeout?: number, signal?: AbortSignal): Promise<DirectDocumentResult>;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,uBAAuB,EAIxB,MAAM,YAAY,CAAC;AAMpB;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAKjD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;gBAClC,OAAO,SAAiC;CAIrD;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAC9C,SAAgB,aAAa,CAAC,EAAE,KAAK,CAAC;gBAE1B,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,KAAK;CAKnD;AAcD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOjD;AA6HD;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,SAAkB,GACxB,OAAO,CAAC,uBAAuB,CAAC,CAElC;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqChG;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAOrE;AAyDD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiB1E;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,SAAkB,GACxB,OAAO,CAAC,oBAAoB,CAAC,CAkC/B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -46,6 +46,47 @@ export class RISParsingError extends RISAPIError {
 // =============================================================================
 const BASE_URL = 'https://data.bka.gv.at/ris/api/v2.6/';
 const DEFAULT_TIMEOUT = 30000; // 30 seconds in milliseconds
+/** HTTP status codes treated as transient and worth a single retry. */
+const TRANSIENT_STATUS_CODES = new Set([502, 503, 504]);
+/** Delay before the single retry of a transient failure. */
+const RETRY_DELAY_MS = 500;
+/**
+ * Resolve after the given number of milliseconds, or reject as soon as the
+ * caller cancels — a cancelled request should not sit out the retry backoff.
+ */
+function delay(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const timeoutId = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timeoutId);
+            reject(signal.reason);
+        }, { once: true });
+    });
+}
+/**
+ * Combine the per-request timeout with the caller's cancellation signal so the
+ * fetch aborts on whichever fires first.
+ */
+function withTimeoutSignal(timeoutSignal, callerSignal) {
+    return callerSignal ? AbortSignal.any([timeoutSignal, callerSignal]) : timeoutSignal;
+}
+/**
+ * Determine whether an error is transient (a gateway error or timeout) and
+ * therefore worth retrying once.
+ */
+function isTransientError(error) {
+    if (error instanceof RISTimeoutError) {
+        return true;
+    }
+    if (error instanceof RISAPIError && error.statusCode !== undefined) {
+        return TRANSIENT_STATUS_CODES.has(error.statusCode);
+    }
+    return false;
+}
 /**
  * Allowed hostnames for document content fetching (SSRF protection).
  */
@@ -123,20 +164,18 @@ function extractSearchResults(parsedResponse) {
     };
 }
 /**
- * Make a request to the RIS API.
+ * Perform a single request attempt against the RIS API.
  */
-async function request(endpoint, params, timeout = DEFAULT_TIMEOUT) {
-    const url = new URL(endpoint, BASE_URL);
-    url.search = buildParams(params).toString();
+async function requestOnce(url, endpoint, timeout, signal) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     try {
-        const response = await fetch(url.toString(), {
+        const response = await fetch(url, {
             method: 'GET',
             headers: {
                 Accept: 'application/json',
             },
-            signal: controller.signal,
+            signal: withTimeoutSignal(controller.signal, signal),
         });
         clearTimeout(timeoutId);
         if (!response.ok) {
@@ -149,6 +188,12 @@ async function request(endpoint, params, timeout = DEFAULT_TIMEOUT) {
     }
     catch (e) {
         clearTimeout(timeoutId);
+        // The combined signal makes a timeout and a caller cancellation look alike
+        // to fetch, so the signals decide: a cancelled request is not an upstream
+        // failure and must not be dressed up as one.
+        if (signal?.aborted) {
+            throw e;
+        }
         if (e instanceof RISAPIError || e instanceof RISParsingError) {
             throw e;
         }
@@ -161,58 +206,80 @@ async function request(endpoint, params, timeout = DEFAULT_TIMEOUT) {
         throw new RISAPIError(`Request failed for ${endpoint}: ${String(e)}`);
     }
 }
+/**
+ * Make a request to the RIS API, retrying once on transient failures
+ * (HTTP 502/503/504 and timeouts) after a short delay.
+ */
+async function request(endpoint, params, timeout = DEFAULT_TIMEOUT, signal) {
+    const url = new URL(endpoint, BASE_URL);
+    url.search = buildParams(params).toString();
+    const urlString = url.toString();
+    try {
+        return await requestOnce(urlString, endpoint, timeout, signal);
+    }
+    catch (e) {
+        if (!isTransientError(e)) {
+            throw e;
+        }
+        // A cancelled request is not a transient upstream error: `delay` rejects
+        // straight away if the caller has cancelled, or as soon as it does, so the
+        // second attempt never starts.
+        await delay(RETRY_DELAY_MS, signal);
+        return requestOnce(urlString, endpoint, timeout, signal);
+    }
+}
 /**
  * Search federal law (Bundesrecht).
  */
-export async function searchBundesrecht(params, timeout = DEFAULT_TIMEOUT) {
-    return request('Bundesrecht', params, timeout);
+export async function searchBundesrecht(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('Bundesrecht', params, timeout, signal);
 }
 /**
  * Search state/provincial law (Landesrecht).
  */
-export async function searchLandesrecht(params, timeout = DEFAULT_TIMEOUT) {
-    return request('Landesrecht', params, timeout);
+export async function searchLandesrecht(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('Landesrecht', params, timeout, signal);
 }
 /**
  * Search case law/jurisprudence (Judikatur).
  */
-export async function searchJudikatur(params, timeout = DEFAULT_TIMEOUT) {
-    return request('Judikatur', params, timeout);
+export async function searchJudikatur(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('Judikatur', params, timeout, signal);
 }
 /**
  * Search district administrative authorities (Bezirke).
  */
-export async function searchBezirke(params, timeout = DEFAULT_TIMEOUT) {
-    return request('Bezirke', params, timeout);
+export async function searchBezirke(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('Bezirke', params, timeout, signal);
 }
 /**
  * Search municipal law (Gemeinden).
  */
-export async function searchGemeinden(params, timeout = DEFAULT_TIMEOUT) {
-    return request('Gemeinden', params, timeout);
+export async function searchGemeinden(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('Gemeinden', params, timeout, signal);
 }
 /**
  * Search miscellaneous legal collections (Sonstige).
  */
-export async function searchSonstige(params, timeout = DEFAULT_TIMEOUT) {
-    return request('Sonstige', params, timeout);
+export async function searchSonstige(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('Sonstige', params, timeout, signal);
 }
 /**
  * Search document change history (History).
  */
-export async function searchHistory(params, timeout = DEFAULT_TIMEOUT) {
-    return request('History', params, timeout);
+export async function searchHistory(params, timeout = DEFAULT_TIMEOUT, signal) {
+    return request('History', params, timeout, signal);
 }
 /**
  * Fetch HTML content from a document URL.
  */
-export async function getDocumentContent(url, timeout = DEFAULT_TIMEOUT) {
+export async function getDocumentContent(url, timeout = DEFAULT_TIMEOUT, signal) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), timeout);
     try {
         const response = await fetch(url, {
             method: 'GET',
-            signal: controller.signal,
+            signal: withTimeoutSignal(controller.signal, signal),
         });
         clearTimeout(timeoutId);
         if (!response.ok) {
@@ -223,6 +290,10 @@ export async function getDocumentContent(url, timeout = DEFAULT_TIMEOUT) {
     }
     catch (e) {
         clearTimeout(timeoutId);
+        // See requestOnce: only the signals distinguish a cancellation from a timeout.
+        if (signal?.aborted) {
+            throw e;
+        }
         if (e instanceof RISAPIError) {
             throw e;
         }
@@ -258,52 +329,83 @@ export function isValidDokumentnummer(dokumentnummer) {
     return /^[A-Z][A-Z0-9_]+$/.test(dokumentnummer);
 }
 /**
- * URL patterns for different document types based on Dokumentnummer prefix.
- * The {dokumentnummer} placeholder will be replaced with the actual document number.
+ * Single source of truth mapping Dokumentnummer prefixes to their direct-URL
+ * folder and fallback-search routing. Used by both {@link constructDocumentUrl}
+ * (direct URL) and the ris_dokument fallback search (via {@link getDocumentRoute}).
+ * Prefixes are matched longest-first.
+ *
+ * The Judikatur document-ID scheme is `J<court><R|T>` where R = Rechtssatz and
+ * T = Entscheidungstext: JJ = Justiz, JW = VwGH, JF = VfGH, JU = UVS.
+ *
+ * Folder segments and endpoints verified against RIS API v2.6
+ * (data.bka.gv.at / ris.bka.gv.at) on 2026-07-03.
  */
-const DOCUMENT_URL_PATTERNS = {
-    // Bundesrecht (Federal Law)
-    NOR: 'https://ris.bka.gv.at/Dokumente/Bundesnormen/{dokumentnummer}/{dokumentnummer}.html',
-    // Landesrecht (State Law) - one prefix per state
-    LBG: 'https://ris.bka.gv.at/Dokumente/LrBgld/{dokumentnummer}/{dokumentnummer}.html',
-    LKT: 'https://ris.bka.gv.at/Dokumente/LrK/{dokumentnummer}/{dokumentnummer}.html',
-    LNO: 'https://ris.bka.gv.at/Dokumente/LrNO/{dokumentnummer}/{dokumentnummer}.html',
-    LOO: 'https://ris.bka.gv.at/Dokumente/LrOO/{dokumentnummer}/{dokumentnummer}.html',
-    LSB: 'https://ris.bka.gv.at/Dokumente/LrSbg/{dokumentnummer}/{dokumentnummer}.html',
-    LST: 'https://ris.bka.gv.at/Dokumente/LrStmk/{dokumentnummer}/{dokumentnummer}.html',
-    LTI: 'https://ris.bka.gv.at/Dokumente/LrT/{dokumentnummer}/{dokumentnummer}.html',
-    LVB: 'https://ris.bka.gv.at/Dokumente/LrVbg/{dokumentnummer}/{dokumentnummer}.html',
-    LWI: 'https://ris.bka.gv.at/Dokumente/LrW/{dokumentnummer}/{dokumentnummer}.html',
-    // Judikatur (Case Law)
-    JWR: 'https://ris.bka.gv.at/Dokumente/Vwgh/{dokumentnummer}/{dokumentnummer}.html',
-    JFR: 'https://ris.bka.gv.at/Dokumente/Vfgh/{dokumentnummer}/{dokumentnummer}.html',
-    JFT: 'https://ris.bka.gv.at/Dokumente/Vfgh/{dokumentnummer}/{dokumentnummer}.html',
-    JWT: 'https://ris.bka.gv.at/Dokumente/Justiz/{dokumentnummer}/{dokumentnummer}.html',
-    JJR: 'https://ris.bka.gv.at/Dokumente/Justiz/{dokumentnummer}/{dokumentnummer}.html',
-    BVWG: 'https://ris.bka.gv.at/Dokumente/Bvwg/{dokumentnummer}/{dokumentnummer}.html',
-    LVWG: 'https://ris.bka.gv.at/Dokumente/Lvwg/{dokumentnummer}/{dokumentnummer}.html',
-    DSB: 'https://ris.bka.gv.at/Dokumente/Dsk/{dokumentnummer}/{dokumentnummer}.html',
-    GBK: 'https://ris.bka.gv.at/Dokumente/Gbk/{dokumentnummer}/{dokumentnummer}.html',
-    PVAK: 'https://ris.bka.gv.at/Dokumente/Pvak/{dokumentnummer}/{dokumentnummer}.html',
-    ASYLGH: 'https://ris.bka.gv.at/Dokumente/AsylGH/{dokumentnummer}/{dokumentnummer}.html',
-    // Bundesgesetzblätter (Federal Law Gazettes)
-    BGBLA: 'https://ris.bka.gv.at/Dokumente/BgblAuth/{dokumentnummer}/{dokumentnummer}.html',
-    BGBL: 'https://ris.bka.gv.at/Dokumente/BgblAlt/{dokumentnummer}/{dokumentnummer}.html',
-    BGBLPDF: 'https://ris.bka.gv.at/Dokumente/BgblPdf/{dokumentnummer}/{dokumentnummer}.html',
-    // Regierungsvorlagen (Government Bills)
-    REGV: 'https://ris.bka.gv.at/Dokumente/RegV/{dokumentnummer}/{dokumentnummer}.html',
-    // Bezirke (District Administrative Authorities)
-    BVB: 'https://ris.bka.gv.at/Dokumente/Bvb/{dokumentnummer}/{dokumentnummer}.html',
-    // Verordnungsblätter (State Ordinance Gazettes)
-    VBL: 'https://ris.bka.gv.at/Dokumente/Vbl/{dokumentnummer}/{dokumentnummer}.html',
-    // Sonstige (Miscellaneous)
-    MRP: 'https://ris.bka.gv.at/Dokumente/Mrp/{dokumentnummer}/{dokumentnummer}.html',
-    ERL: 'https://ris.bka.gv.at/Dokumente/Erlaesse/{dokumentnummer}/{dokumentnummer}.html',
-    PRUEF: 'https://ris.bka.gv.at/Dokumente/PruefGewO/{dokumentnummer}/{dokumentnummer}.html',
-    AVSV: 'https://ris.bka.gv.at/Dokumente/Avsv/{dokumentnummer}/{dokumentnummer}.html',
-    SPG: 'https://ris.bka.gv.at/Dokumente/Spg/{dokumentnummer}/{dokumentnummer}.html',
-    KMGER: 'https://ris.bka.gv.at/Dokumente/KmGer/{dokumentnummer}/{dokumentnummer}.html',
+const DOCUMENT_ROUTES = {
+    // --- Bundesrecht (Federal Law) ---
+    NOR: { urlFolder: 'Bundesnormen', endpoint: 'Bundesrecht', applikation: 'BrKons' },
+    BGBLPDF: { urlFolder: 'BgblPdf', endpoint: 'Bundesrecht', applikation: 'BgblPdf' },
+    BGBLA: { urlFolder: 'BgblAuth', endpoint: 'Bundesrecht', applikation: 'BgblAuth' },
+    BGBL: { urlFolder: 'BgblAlt', endpoint: 'Bundesrecht', applikation: 'BgblAlt' },
+    REGV: { urlFolder: 'RegV', endpoint: 'Bundesrecht', applikation: 'RegV' },
+    // --- Landesrecht (State Law) — one prefix per state ---
+    LBG: { urlFolder: 'LrBgld', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LKT: { urlFolder: 'LrK', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LNO: { urlFolder: 'LrNO', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LOO: { urlFolder: 'LrOO', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LSB: { urlFolder: 'LrSbg', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LST: { urlFolder: 'LrStmk', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LTI: { urlFolder: 'LrT', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LVB: { urlFolder: 'LrVbg', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    LWI: { urlFolder: 'LrW', endpoint: 'Landesrecht', applikation: 'LrKons' },
+    VBL: { urlFolder: 'Vbl', endpoint: 'Landesrecht', applikation: 'Vbl' },
+    // --- Judikatur (Case Law) ---
+    JWR: { urlFolder: 'Vwgh', endpoint: 'Judikatur', applikation: 'Vwgh' },
+    JWT: { urlFolder: 'Vwgh', endpoint: 'Judikatur', applikation: 'Vwgh' },
+    JFR: { urlFolder: 'Vfgh', endpoint: 'Judikatur', applikation: 'Vfgh' },
+    JFT: { urlFolder: 'Vfgh', endpoint: 'Judikatur', applikation: 'Vfgh' },
+    JJR: { urlFolder: 'Justiz', endpoint: 'Judikatur', applikation: 'Justiz' },
+    JJT: { urlFolder: 'Justiz', endpoint: 'Judikatur', applikation: 'Justiz' },
+    BVWG: { urlFolder: 'Bvwg', endpoint: 'Judikatur', applikation: 'Bvwg' },
+    LVWG: { urlFolder: 'Lvwg', endpoint: 'Judikatur', applikation: 'Lvwg' },
+    DSB: { urlFolder: 'Dsk', endpoint: 'Judikatur', applikation: 'Dsk' },
+    PDK: { urlFolder: 'Dsk', endpoint: 'Judikatur', applikation: 'Dsk' },
+    GBK: { urlFolder: 'Gbk', endpoint: 'Judikatur', applikation: 'Gbk' },
+    PVAB: { urlFolder: 'Pvak', endpoint: 'Judikatur', applikation: 'Pvak' },
+    DKT: { urlFolder: 'Dok', endpoint: 'Judikatur', applikation: 'Dok' },
+    VERG: { urlFolder: 'Verg', endpoint: 'Judikatur', applikation: 'Verg' },
+    JUR: { urlFolder: 'Uvs', endpoint: 'Judikatur', applikation: 'Uvs' },
+    JUT: { urlFolder: 'Uvs', endpoint: 'Judikatur', applikation: 'Uvs' },
+    UBAS: { urlFolder: 'Ubas', endpoint: 'Judikatur', applikation: 'Ubas' },
+    UMSE: { urlFolder: 'Umse', endpoint: 'Judikatur', applikation: 'Umse' },
+    BKS: { urlFolder: 'Bks', endpoint: 'Judikatur', applikation: 'Bks' },
+    ASYLGH: { urlFolder: 'AsylGH', endpoint: 'Judikatur', applikation: 'AsylGH' },
+    NL: { urlFolder: 'Normenliste', endpoint: 'Judikatur', applikation: 'Normenliste' },
+    // --- Sonstige (Miscellaneous) ---
+    MRP: { urlFolder: 'Mrp', endpoint: 'Sonstige', applikation: 'Mrp' },
+    ERL: { urlFolder: 'Erlaesse', endpoint: 'Sonstige', applikation: 'Erlaesse' },
+    PRUEF: { urlFolder: 'PruefGewO', endpoint: 'Sonstige', applikation: 'PruefGewO' },
+    AVSV: { urlFolder: 'Avsv', endpoint: 'Sonstige', applikation: 'Avsv' },
+    SPG: { urlFolder: 'Spg', endpoint: 'Sonstige', applikation: 'Spg' },
+    KMGER: { urlFolder: 'KmGer', endpoint: 'Sonstige', applikation: 'KmGer' },
+    // --- Bezirke (District Administrative Authorities) ---
+    BVB: { urlFolder: 'Bvb', endpoint: 'Bezirke', applikation: 'Bvb' },
 };
+/** Prefixes sorted longest-first so specific prefixes win over shorter ones. */
+const DOCUMENT_ROUTE_PREFIXES = Object.keys(DOCUMENT_ROUTES).sort((a, b) => b.length - a.length);
+/**
+ * Look up the routing information for a Dokumentnummer by its prefix.
+ *
+ * @param dokumentnummer - The RIS document number (e.g., "NOR12019037")
+ * @returns The matching route, or null if the prefix is unknown
+ */
+export function getDocumentRoute(dokumentnummer) {
+    for (const prefix of DOCUMENT_ROUTE_PREFIXES) {
+        if (dokumentnummer.startsWith(prefix)) {
+            return DOCUMENT_ROUTES[prefix];
+        }
+    }
+    return null;
+}
 /**
  * Construct a direct document URL based on the Dokumentnummer prefix.
  *
@@ -315,15 +417,11 @@ export function constructDocumentUrl(dokumentnummer) {
     if (!isValidDokumentnummer(dokumentnummer)) {
         return null;
     }
-    // Find matching prefix (check longer prefixes first to avoid false matches)
-    const prefixes = Object.keys(DOCUMENT_URL_PATTERNS).sort((a, b) => b.length - a.length);
-    for (const prefix of prefixes) {
-        if (dokumentnummer.startsWith(prefix)) {
-            const pattern = DOCUMENT_URL_PATTERNS[prefix];
-            return pattern.replace(/{dokumentnummer}/g, dokumentnummer);
-        }
+    const route = getDocumentRoute(dokumentnummer);
+    if (!route) {
+        return null;
     }
-    return null;
+    return `https://ris.bka.gv.at/Dokumente/${route.urlFolder}/${dokumentnummer}/${dokumentnummer}.html`;
 }
 /**
  * Attempt to fetch a document directly by its Dokumentnummer using URL construction.
@@ -333,9 +431,11 @@ export function constructDocumentUrl(dokumentnummer) {
  *
  * @param dokumentnummer - The RIS document number (e.g., "NOR12019037")
  * @param timeout - Request timeout in milliseconds
+ * @param signal - Caller's cancellation signal; a cancellation is thrown rather
+ *   than reported as an unsuccessful fetch, so callers do not fall back to a search
  * @returns Result object with HTML content on success, or error details on failure
  */
-export async function getDocumentByNumber(dokumentnummer, timeout = DEFAULT_TIMEOUT) {
+export async function getDocumentByNumber(dokumentnummer, timeout = DEFAULT_TIMEOUT, signal) {
     // Validate dokumentnummer before any URL operations
     if (!isValidDokumentnummer(dokumentnummer)) {
         return {
@@ -351,10 +451,15 @@ export async function getDocumentByNumber(dokumentnummer, timeout = DEFAULT_TIME
         };
     }
     try {
-        const html = await getDocumentContent(url, timeout);
+        const html = await getDocumentContent(url, timeout, signal);
         return { success: true, html, url };
     }
     catch (e) {
+        // Reporting a cancellation as a failed direct fetch would send the caller
+        // into its fallback search — a second round-trip nobody is waiting for.
+        if (signal?.aborted) {
+            throw e;
+        }
         if (e instanceof RISAPIError) {
             return {
                 success: false,