@cyanheads/ris-austria-mcp-server 0.1.5

package/dist/mcp-server/tools/definitions/ris-track-changes.tool.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview ris_track_changes — the precise, deletion-aware change feed over RIS's
+ * History controller: every document added or changed in one application within an exact
+ * date window, optionally including deletions. The delta-sync and monitoring primitive the
+ * coarse, additive-only `changed_since` (ImRisSeit) intervals cannot express. History
+ * responses reuse the standard normalized envelope, so each changed document surfaces in a
+ * cross-class record shape (identity, label, dates, binding, renditions) plus `changed`;
+ * removed documents surface as `deleted` records. The service maps the four History
+ * application-name aliases (BrKons→Bundesnormen, LrKons→Landesnormen, Gr→Gemeinderecht,
+ * GrA→GemeinderechtAuth) internally.
+ * @module mcp-server/tools/definitions/ris-track-changes
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const risTrackChanges: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    application: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    changed_from: z.ZodOptional<z.ZodString>;
+    changed_to: z.ZodOptional<z.ZodString>;
+    include_deleted: z.ZodOptional<z.ZodBoolean>;
+    page: z.ZodOptional<z.ZodNumber>;
+    page_size: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<10>, z.ZodLiteral<20>, z.ZodLiteral<50>, z.ZodLiteral<100>]>>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        document_number: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        short_title: z.ZodOptional<z.ZodString>;
+        organ: z.ZodOptional<z.ZodString>;
+        changed: z.ZodOptional<z.ZodString>;
+        published: z.ZodOptional<z.ZodString>;
+        document_url: z.ZodOptional<z.ZodString>;
+        binding_status: z.ZodEnum<{
+            translation: "translation";
+            authentic: "authentic";
+            consolidated_informational: "consolidated_informational";
+            historical_record: "historical_record";
+            decision: "decision";
+            preparatory: "preparatory";
+            administrative_directive: "administrative_directive";
+        }>;
+        deleted: z.ZodBoolean;
+        deleted_at: z.ZodOptional<z.ZodString>;
+        content_urls: z.ZodObject<{
+            xml: z.ZodOptional<z.ZodString>;
+            html: z.ZodOptional<z.ZodString>;
+            pdf: z.ZodOptional<z.ZodString>;
+            rtf: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        authentic_pdf_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "invalid_query";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "RIS rejected a parameter value — the in-band Client error message is passed through verbatim; it names the invalid element and its valid values (e.g. an application History does not carry).";
+    readonly recovery: "Correct the parameter RIS names in the message. Ground valid application codes with ris_list_reference topic applications.";
+}, {
+    readonly reason: "upstream_error";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "RIS is unreachable, returned a server error, or served an HTML error page.";
+    readonly retryable: true;
+    readonly recovery: "RIS is temporarily unavailable — retry after a short delay. If it persists, reduce page_size or narrow the window.";
+}], {
+    readonly totalCount: z.ZodNumber;
+    readonly page: z.ZodNumber;
+    readonly pageSize: z.ZodNumber;
+    readonly truncated: z.ZodOptional<z.ZodBoolean>;
+    readonly application: z.ZodString;
+    readonly changedFrom: z.ZodOptional<z.ZodString>;
+    readonly changedTo: z.ZodOptional<z.ZodString>;
+    readonly notice: z.ZodOptional<z.ZodString>;
+}>;
+//# sourceMappingURL=ris-track-changes.tool.d.ts.map

package/dist/mcp-server/tools/definitions/ris-track-changes.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ris-track-changes.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/ris-track-changes.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAiI3E,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkK1B,CAAC"}

package/dist/mcp-server/tools/definitions/ris-track-changes.tool.js

@@ -0,0 +1,265 @@
+/**
+ * @fileoverview ris_track_changes — the precise, deletion-aware change feed over RIS's
+ * History controller: every document added or changed in one application within an exact
+ * date window, optionally including deletions. The delta-sync and monitoring primitive the
+ * coarse, additive-only `changed_since` (ImRisSeit) intervals cannot express. History
+ * responses reuse the standard normalized envelope, so each changed document surfaces in a
+ * cross-class record shape (identity, label, dates, binding, renditions) plus `changed`;
+ * removed documents surface as `deleted` records. The service maps the four History
+ * application-name aliases (BrKons→Bundesnormen, LrKons→Landesnormen, Gr→Gemeinderecht,
+ * GrA→GemeinderechtAuth) internally.
+ * @module mcp-server/tools/definitions/ris-track-changes
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
+import { RIS_APPLICATIONS } from '../../../services/ris/reference/index.js';
+import { getRisService } from '../../../services/ris/ris-service.js';
+import { isoDateString } from './_shared.js';
+const APPLICATION_CODES = RIS_APPLICATIONS.map((app) => app.code);
+const APPLICATION_BY_CODE = new Map(RIS_APPLICATIONS.map((app) => [app.code, app]));
+const BINDING_STATUSES = [
+    'authentic',
+    'consolidated_informational',
+    'historical_record',
+    'decision',
+    'preparatory',
+    'administrative_directive',
+    'translation',
+];
+/** Map an empty string from a form-based client to `undefined`. */
+function meaningful(value) {
+    return value !== undefined && value !== '' ? value : undefined;
+}
+const ContentUrlsSchema = z
+    .object({
+    xml: z.string().optional().describe('XML rendition URL (RIS Nutzdaten schema).'),
+    html: z.string().optional().describe('HTML rendition URL.'),
+    pdf: z.string().optional().describe('PDF rendition URL.'),
+    rtf: z.string().optional().describe('RTF rendition URL.'),
+})
+    .describe('Rendition URLs of the changed document. Empty for a deletion record.');
+const ChangeRecordSchema = z
+    .object({
+    document_number: z
+        .string()
+        .describe('Technical RIS document number (Technisch.ID) — pass with application to ris_get_document.'),
+    title: z.string().optional().describe('Document title, HTML markup stripped, where present.'),
+    short_title: z.string().optional().describe('Short title (Kurztitel), where assigned.'),
+    organ: z
+        .string()
+        .optional()
+        .describe('Issuing body (Organ) of the document, where the record carries one.'),
+    changed: z
+        .string()
+        .optional()
+        .describe('Date this document last changed in RIS (Allgemein.Geaendert).'),
+    published: z
+        .string()
+        .optional()
+        .describe('Date this document was first published in RIS (Allgemein.Veroeffentlicht).'),
+    document_url: z
+        .string()
+        .optional()
+        .describe('RIS web view of the document (Allgemein.DokumentUrl) — for humans.'),
+    binding_status: z
+        .enum(BINDING_STATUSES)
+        .describe('Legal binding status of the queried application — authentic (amtssigniert, legally binding), consolidated_informational, historical_record, decision, preparatory, administrative_directive, or translation.'),
+    deleted: z
+        .boolean()
+        .describe('True when this record marks a document removed from RIS (include_deleted only).'),
+    deleted_at: z
+        .string()
+        .optional()
+        .describe('Deletion import timestamp (ImportTimestamp) — deletion records only.'),
+    content_urls: ContentUrlsSchema,
+    authentic_pdf_url: z
+        .string()
+        .optional()
+        .describe('The amtssigniert authentic PDF (.pdfsig, Authentisch DataType), where the changed document publishes one.'),
+})
+    .describe('One change-feed entry — a changed document, or a deletion record.');
+/** Map a normalized History change to the tool's record shape. */
+function toRecord(change, bindingStatus) {
+    if (change.kind === 'deleted') {
+        const { deletedAt, documentNumber, organ } = change.record;
+        return {
+            binding_status: bindingStatus,
+            content_urls: {},
+            deleted: true,
+            document_number: documentNumber,
+            ...(deletedAt !== undefined && { deleted_at: deletedAt }),
+            ...(organ !== undefined && { organ }),
+        };
+    }
+    const { hit } = change;
+    const md = hit.metadata;
+    const title = md.title;
+    const shortTitle = 'shortTitle' in md ? md.shortTitle : undefined;
+    const { html, pdf, rtf, xml } = hit.contentUrls;
+    return {
+        binding_status: bindingStatus,
+        content_urls: {
+            ...(xml !== undefined && { xml }),
+            ...(html !== undefined && { html }),
+            ...(pdf !== undefined && { pdf }),
+            ...(rtf !== undefined && { rtf }),
+        },
+        deleted: false,
+        document_number: hit.documentNumber,
+        ...(hit.contentUrls.authentic !== undefined && {
+            authentic_pdf_url: hit.contentUrls.authentic,
+        }),
+        ...(hit.changed !== undefined && { changed: hit.changed }),
+        ...(hit.documentUrl !== undefined && { document_url: hit.documentUrl }),
+        ...(hit.organ !== undefined && { organ: hit.organ }),
+        ...(hit.published !== undefined && { published: hit.published }),
+        ...(shortTitle !== undefined && { short_title: shortTitle }),
+        ...(title !== undefined && { title }),
+    };
+}
+export const risTrackChanges = tool('ris_track_changes', {
+    title: 'Track RIS Changes',
+    description: 'Track every document added or changed in one RIS application within an exact date window (changed_from/changed_to) via the History controller, optionally including deletions (include_deleted) — the delta-sync and monitoring primitive for mirrors and watchers, and the only surface that reports removals. Unlike the search tools’ coarse, additive-only changed_since intervals, this is exact-dated and deletion-aware. application takes any RIS application code (e.g. BrKons, Dsk, BgblAuth); the four History name aliases are handled internally. Each changed document comes back in a compact cross-class record — document_number (for ris_get_document), title, dates, binding_status, and rendition URLs — plus its last-changed date; removed documents come back as deleted records with a deletion timestamp. One application per call; page explicitly for large windows. Application codes and coverage: ris_list_reference topic applications.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        application: z
+            .enum(APPLICATION_CODES)
+            .describe('RIS application whose change feed to read (standard code, e.g. BrKons, LrKons, Dsk, BgblAuth). History’s four aliased names are mapped internally. Codes: ris_list_reference topic applications.'),
+        changed_from: isoDateString
+            .optional()
+            .describe('Include documents changed on/after this date (YYYY-MM-DD, AenderungenVon). Exact date, not a coarse interval.'),
+        changed_to: isoDateString
+            .optional()
+            .describe('Include documents changed on/before this date (YYYY-MM-DD, AenderungenBis).'),
+        include_deleted: z
+            .boolean()
+            .optional()
+            .describe('true also returns documents removed from RIS in the window, as deleted records — the only way to observe deletions.'),
+        page: z.number().int().min(1).optional().describe('1-based result page. Default 1.'),
+        page_size: z
+            .union([z.literal(10), z.literal(20), z.literal(50), z.literal(100)])
+            .optional()
+            .describe('Documents per page — RIS accepts 10, 20, 50, or 100. Default 20.'),
+    }),
+    output: z.object({
+        results: z
+            .array(ChangeRecordSchema)
+            .describe('Change-feed entries for the requested page. Totals, paging, and the applied window in enrichment.'),
+    }),
+    enrichment: {
+        totalCount: z.number().describe('Total change-feed entries across all pages.'),
+        page: z.number().describe('1-based page number RIS served.'),
+        pageSize: z.number().describe('Page size RIS applied.'),
+        truncated: z
+            .boolean()
+            .optional()
+            .describe('Present and true when more pages exist beyond this one — raise page to continue.'),
+        application: z.string().describe('The application whose change feed was read.'),
+        changedFrom: z
+            .string()
+            .optional()
+            .describe('The changed_from bound the server applied (echo), when set.'),
+        changedTo: z
+            .string()
+            .optional()
+            .describe('The changed_to bound the server applied (echo), when set.'),
+        notice: z
+            .string()
+            .optional()
+            .describe('Zero-hit guidance — names the likely cause and the concrete next call.'),
+    },
+    errors: [
+        {
+            reason: 'invalid_query',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'RIS rejected a parameter value — the in-band Client error message is passed through verbatim; it names the invalid element and its valid values (e.g. an application History does not carry).',
+            recovery: 'Correct the parameter RIS names in the message. Ground valid application codes with ris_list_reference topic applications.',
+        },
+        {
+            reason: 'upstream_error',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'RIS is unreachable, returned a server error, or served an HTML error page.',
+            retryable: true,
+            recovery: 'RIS is temporarily unavailable — retry after a short delay. If it persists, reduce page_size or narrow the window.',
+        },
+    ],
+    async handler(input, ctx) {
+        const changedFrom = meaningful(input.changed_from);
+        const changedTo = meaningful(input.changed_to);
+        // application is a Zod enum of the reference codes, so the lookup always resolves.
+        const bindingStatus = APPLICATION_BY_CODE.get(input.application).binding;
+        const params = {
+            application: input.application,
+            ...(changedFrom !== undefined && { changedFrom }),
+            ...(changedTo !== undefined && { changedTo }),
+            ...(input.include_deleted === true && { includeDeleted: true }),
+            ...(input.page !== undefined && { page: input.page }),
+            ...(input.page_size !== undefined && { pageSize: input.page_size }),
+        };
+        // Map in-band RIS errors onto this tool's declared contract so reason +
+        // recovery reach the wire (service-level throws carry neither).
+        const result = await getRisService()
+            .trackChanges(params, ctx)
+            .catch((err) => {
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.InvalidParams) {
+                throw ctx.fail('invalid_query', err.message, { ...ctx.recoveryFor('invalid_query') });
+            }
+            if (err instanceof McpError && err.code === JsonRpcErrorCode.ServiceUnavailable) {
+                throw ctx.fail('upstream_error', err.message, { ...ctx.recoveryFor('upstream_error') });
+            }
+            throw err;
+        });
+        ctx.log.info('Change feed read', {
+            application: input.application,
+            entries: result.changes.length,
+            total: result.total,
+        });
+        ctx.enrich.total(result.total);
+        ctx.enrich({ application: input.application, page: result.page, pageSize: result.pageSize });
+        if (changedFrom !== undefined)
+            ctx.enrich({ changedFrom });
+        if (changedTo !== undefined)
+            ctx.enrich({ changedTo });
+        if (result.total > (result.page - 1) * result.pageSize + result.changes.length) {
+            ctx.enrich({ truncated: true });
+        }
+        if (result.total === 0) {
+            ctx.enrich.notice(`0 changes in ${input.application} between ${changedFrom ?? 'the start of the feed'} and ${changedTo ?? 'now'}. Windows are exact dates — widen the range, or use the search tools' changed_since for coarse recency filtering.`);
+        }
+        return { results: result.changes.map((change) => toRecord(change, bindingStatus)) };
+    },
+    // format() populates content[] — the markdown twin of structuredContent. Every output
+    // field renders here; totals, paging, and the applied window ride the enrichment trailer.
+    format: (result) => {
+        if (result.results.length === 0) {
+            return [{ type: 'text', text: '_No changes on this page._' }];
+        }
+        const blocks = result.results.map((r) => {
+            const lines = [
+                `## ${r.title ?? r.short_title ?? r.document_number}${r.deleted ? ' — deleted' : ''}`,
+                `**Document:** ${r.document_number}`,
+            ];
+            if (r.short_title !== undefined)
+                lines.push(`**Short title:** ${r.short_title}`);
+            if (r.organ !== undefined)
+                lines.push(`**Organ:** ${r.organ}`);
+            lines.push(`**Binding:** ${r.binding_status}`);
+            if (r.changed !== undefined || r.published !== undefined) {
+                lines.push(`**Changed:** ${r.changed ?? 'unknown'}${r.published !== undefined ? ` | **Published:** ${r.published}` : ''}`);
+            }
+            lines.push(`**Deleted:** ${r.deleted ? `yes${r.deleted_at !== undefined ? ` (${r.deleted_at})` : ''}` : 'no'}`);
+            if (r.document_url !== undefined)
+                lines.push(`**RIS view:** ${r.document_url}`);
+            if (r.authentic_pdf_url !== undefined)
+                lines.push(`**Authentic PDF:** ${r.authentic_pdf_url}`);
+            const urls = ['html', 'pdf', 'rtf', 'xml']
+                .filter((key) => r.content_urls[key] !== undefined)
+                .map((key) => `[${key.toUpperCase()}](${r.content_urls[key]})`);
+            if (urls.length > 0)
+                lines.push(`**Text:** ${urls.join(' · ')}`);
+            return lines.join('\n');
+        });
+        return [{ type: 'text', text: blocks.join('\n\n') }];
+    },
+});
+//# sourceMappingURL=ris-track-changes.tool.js.map

package/dist/mcp-server/tools/definitions/ris-track-changes.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ris-track-changes.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/ris-track-changes.tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAG3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAG9D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAA0B,CAAC;AAE3F,MAAM,mBAAmB,GAAG,IAAI,GAAG,CACjC,gBAAgB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAC/C,CAAC;AAEF,MAAM,gBAAgB,GAAG;IACvB,WAAW;IACX,4BAA4B;IAC5B,mBAAmB;IACnB,UAAU;IACV,aAAa;IACb,0BAA0B;IAC1B,aAAa;CACiC,CAAC;AAEjD,mEAAmE;AACnE,SAAS,UAAU,CAAC,KAAyB;IAC3C,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,2CAA2C,CAAC;IAChF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qBAAqB,CAAC;IAC3D,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;IACzD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC;CAC1D,CAAC;KACD,QAAQ,CAAC,sEAAsE,CAAC,CAAC;AAEpF,MAAM,kBAAkB,GAAG,CAAC;KACzB,MAAM,CAAC;IACN,eAAe,EAAE,CAAC;SACf,MAAM,EAAE;SACR,QAAQ,CACP,2FAA2F,CAC5F;IACH,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sDAAsD,CAAC;IAC7F,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,0CAA0C,CAAC;IACvF,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,qEAAqE,CAAC;IAClF,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,+DAA+D,CAAC;IAC5E,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,4EAA4E,CAAC;IACzF,YAAY,EAAE,CAAC;SACZ,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,oEAAoE,CAAC;IACjF,cAAc,EAAE,CAAC;SACd,IAAI,CAAC,gBAAgB,CAAC;SACtB,QAAQ,CACP,8MAA8M,CAC/M;IACH,OAAO,EAAE,CAAC;SACP,OAAO,EAAE;SACT,QAAQ,CAAC,iFAAiF,CAAC;IAC9F,UAAU,EAAE,CAAC;SACV,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CAAC,sEAAsE,CAAC;IACnF,YAAY,EAAE,iBAAiB;IAC/B,iBAAiB,EAAE,CAAC;SACjB,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP,2GAA2G,CAC5G;CACJ,CAAC;KACD,QAAQ,CAAC,mEAAmE,CAAC,CAAC;AAIjF,kEAAkE;AAClE,SAAS,QAAQ,CAAC,MAAiB,EAAE,aAA+B;IAClE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC;QAC3D,OAAO;YACL,cAAc,EAAE,aAAa;YAC7B,YAAY,EAAE,EAAE;YAChB,OAAO,EAAE,IAAI;YACb,eAAe,EAAE,cAAc;YAC/B,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;YACzD,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;SACtC,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,GAAG,GAAG,CAAC,QAAQ,CAAC;IACxB,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;IACvB,MAAM,UAAU,GAAG,YAAY,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC;IAChD,OAAO;QACL,cAAc,EAAE,aAAa;QAC7B,YAAY,EAAE;YACZ,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;YACjC,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC;YACnC,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;YACjC,GAAG,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,CAAC;SAClC;QACD,OAAO,EAAE,KAAK;QACd,eAAe,EAAE,GAAG,CAAC,cAAc;QACnC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,SAAS,KAAK,SAAS,IAAI;YAC7C,iBAAiB,EAAE,GAAG,CAAC,WAAW,CAAC,SAAS;SAC7C,CAAC;QACF,GAAG,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;QAC1D,GAAG,CAAC,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC;QACvE,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QACpD,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC;QAChE,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;QAC5D,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAC,mBAAmB,EAAE;IACvD,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EACT,w6BAAw6B;IAC16B,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE;IAC9E,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC;QACd,WAAW,EAAE,CAAC;aACX,IAAI,CAAC,iBAAiB,CAAC;aACvB,QAAQ,CACP,kMAAkM,CACnM;QACH,YAAY,EAAE,aAAa;aACxB,QAAQ,EAAE;aACV,QAAQ,CACP,+GAA+G,CAChH;QACH,UAAU,EAAE,aAAa;aACtB,QAAQ,EAAE;aACV,QAAQ,CAAC,6EAA6E,CAAC;QAC1F,eAAe,EAAE,CAAC;aACf,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CACP,qHAAqH,CACtH;QACH,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QACpF,SAAS,EAAE,CAAC;aACT,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;aACpE,QAAQ,EAAE;aACV,QAAQ,CAAC,kEAAkE,CAAC;KAChF,CAAC;IACF,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,OAAO,EAAE,CAAC;aACP,KAAK,CAAC,kBAAkB,CAAC;aACzB,QAAQ,CACP,mGAAmG,CACpG;KACJ,CAAC;IACF,UAAU,EAAE;QACV,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;QAC9E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QAC5D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wBAAwB,CAAC;QACvD,SAAS,EAAE,CAAC;aACT,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,kFAAkF,CAAC;QAC/F,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,6CAA6C,CAAC;QAC/E,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,6DAA6D,CAAC;QAC1E,SAAS,EAAE,CAAC;aACT,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,2DAA2D,CAAC;QACxE,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,wEAAwE,CAAC;KACtF;IACD,MAAM,EAAE;QACN;YACE,MAAM,EAAE,eAAe;YACvB,IAAI,EAAE,gBAAgB,CAAC,eAAe;YACtC,IAAI,EAAE,+LAA+L;YACrM,QAAQ,EACN,4HAA4H;SAC/H;QACD;YACE,MAAM,EAAE,gBAAgB;YACxB,IAAI,EAAE,gBAAgB,CAAC,kBAAkB;YACzC,IAAI,EAAE,4EAA4E;YAClF,SAAS,EAAE,IAAI;YACf,QAAQ,EACN,oHAAoH;SACvH;KACF;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG;QACtB,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QACnD,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC/C,mFAAmF;QACnF,MAAM,aAAa,GAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,CAAoB,CAAC,OAAO,CAAC;QAE7F,MAAM,MAAM,GAAuB;YACjC,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,GAAG,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,CAAC;YACjD,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,KAAK,CAAC,eAAe,KAAK,IAAI,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;YAC/D,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YACrD,GAAG,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC;SACpE,CAAC;QAEF,wEAAwE;QACxE,gEAAgE;QAChE,MAAM,MAAM,GAAG,MAAM,aAAa,EAAE;aACjC,YAAY,CAAC,MAAM,EAAE,GAAG,CAAC;aACzB,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;YACtB,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,CAAC,aAAa,EAAE,CAAC;gBAC3E,MAAM,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;YACxF,CAAC;YACD,IAAI,GAAG,YAAY,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,CAAC,kBAAkB,EAAE,CAAC;gBAChF,MAAM,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,GAAG,CAAC,OAAO,EAAE,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;YAC1F,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC,CAAC,CAAC;QACL,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,kBAAkB,EAAE;YAC/B,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM;YAC9B,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC,CAAC;QAEH,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/B,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC7F,IAAI,WAAW,KAAK,SAAS;YAAE,GAAG,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;QAC3D,IAAI,SAAS,KAAK,SAAS;YAAE,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QACvD,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;YAC/E,GAAG,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;QAED,IAAI,MAAM,CAAC,KAAK,KAAK,CAAC,EAAE,CAAC;YACvB,GAAG,CAAC,MAAM,CAAC,MAAM,CACf,gBAAgB,KAAK,CAAC,WAAW,YAAY,WAAW,IAAI,uBAAuB,QAAQ,SAAS,IAAI,KAAK,mHAAmH,CACjO,CAAC;QACJ,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC;IACtF,CAAC;IAED,sFAAsF;IACtF,0FAA0F;IAC1F,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;QACjB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACtC,MAAM,KAAK,GAAG;gBACZ,MAAM,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,eAAe,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE;gBACrF,iBAAiB,CAAC,CAAC,eAAe,EAAE;aACrC,CAAC;YACF,IAAI,CAAC,CAAC,WAAW,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACjF,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/D,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC;YAC/C,IAAI,CAAC,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;gBACzD,KAAK,CAAC,IAAI,CACR,gBAAgB,CAAC,CAAC,OAAO,IAAI,SAAS,GAAG,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAC/G,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,IAAI,CACR,gBAAgB,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CACpG,CAAC;YACF,IAAI,CAAC,CAAC,YAAY,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;YAChF,IAAI,CAAC,CAAC,iBAAiB,KAAK,SAAS;gBACnC,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC;YAC1D,MAAM,IAAI,GAAI,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAW;iBAClD,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;iBAClD,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAClE,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACjE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QACH,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvD,CAAC;CACF,CAAC,CAAC"}

package/dist/services/ris/normalizer.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Normalizer for RIS OGD responses: unwraps the JSON-serialized-XML envelope,
+ * coerces object-or-array lists, classifies in-band errors, and maps the six controller
+ * metadata classes to the normalized shapes in `types.ts`.
+ *
+ * Error classification (observed live 2026-07-05): the handbook documents an `@type`
+ * attribute on `OgdSearchResult.Error`, but production responses omit it and prefix the
+ * message with `soap:Client.` / `soap:Server.` instead — both signals are checked. Client
+ * errors become `InvalidParams` with RIS's message passed through (it names the invalid
+ * element); everything else is treated as a transient upstream failure, never a
+ * `SerializationError`.
+ * @module services/ris/normalizer
+ */
+import type { OneOrMany, RawDocumentReference, RawOgdSearchResult, RawWrappedList, RisChangeSet, RisHit, RisSearchResult } from './types.js';
+/** Coerce RIS's object-or-array serialization to an array (empty for null/undefined/''). */
+export declare function coerceOneOrMany<T>(value: OneOrMany<T> | '' | undefined): T[];
+/**
+ * Coerce a RIS wrapped list (`{ item: T | T[] }`), a bare scalar, or an empty element to
+ * a string array — the upstream uses all three shapes for the same logical field.
+ */
+export declare function coerceWrappedList(value: RawWrappedList<string> | string | '' | undefined): string[];
+/** Strip `<br/>` markers and residual HTML remnants from RIS text fields. */
+export declare function stripHtmlRemnants(text: string): string;
+/** Parse `[CELEX-Nr.: …]` markers (possibly multi-valued) out of RIS text fields. */
+export declare function parseCelexReferences(...texts: (string | undefined)[]): string[];
+/** Detect an HTML error page masquerading as an API response. */
+export declare function isHtmlErrorPage(text: string): boolean;
+/**
+ * Throw when the envelope carries an in-band error. Client errors pass RIS's message
+ * through — it names the invalid element and its expected datatype; Server and
+ * unclassifiable errors are transient (`ServiceUnavailable`).
+ */
+export declare function assertNoInBandError(result: RawOgdSearchResult): void;
+/** Parse a search-controller response into a normalized result page. */
+export declare function parseSearchResponse(payload: unknown): RisSearchResult;
+/** Parse a History-controller response, separating changed documents from deletions. */
+export declare function parseHistoryResponse(payload: unknown): RisChangeSet;
+/** Normalize one search hit. Throws `ServiceUnavailable` on unrecognized hit shapes. */
+export declare function normalizeHit(ref: RawDocumentReference): RisHit;
+//# sourceMappingURL=normalizer.d.ts.map

package/dist/services/ris/normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../../src/services/ris/normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,SAAS,EAKT,oBAAoB,EAQpB,kBAAkB,EAGlB,cAAc,EAId,YAAY,EAIZ,MAAM,EAKN,eAAe,EAEhB,MAAM,YAAY,CAAC;AAMpB,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,SAAS,GAAG,CAAC,EAAE,CAG5E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,EAAE,GAAG,SAAS,GACtD,MAAM,EAAE,CAMV;AAWD,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQtD;AAgBD,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,GAAG,KAAK,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,CAW/E;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAwBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CASpE;AAiCD,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAGrE;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY,CAoBnE;AAiTD,wFAAwF;AACxF,wBAAgB,YAAY,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CA8B9D"}