@fin.cx/opendata 3.6.0 → 4.1.0

package/dist_ts/handelsregister/classes.handelsregistererror.js

@@ -0,0 +1,37 @@
+/**
+ * The typed error of the register client. Its message names the failure and never contains
+ * register data, so it can be logged.
+ */
+export class HandelsregisterError extends Error {
+    code;
+    /** the HTTP status of a refusal */
+    status;
+    /** epoch ms of the next possible request (`rate_limited`) */
+    retryAt;
+    /** the step that failed */
+    step;
+    /**
+     * counted requests the call had sent before it failed. A request that was sent may have counted
+     * at the portal even when its answer did not arrive.
+     */
+    countedRequests;
+    /**
+     * the candidates of an `ambiguous` reference, and for `not_found` the entries with the same
+     * number whose location suffix differs
+     */
+    matches;
+    /** a message the portal showed instead of the expected page, German */
+    portalMessage;
+    constructor(codeArg, messageArg, detailsArg = {}) {
+        super(messageArg, detailsArg.cause === undefined ? undefined : { cause: detailsArg.cause });
+        this.name = 'HandelsregisterError';
+        this.code = codeArg;
+        this.status = detailsArg.status;
+        this.retryAt = detailsArg.retryAt;
+        this.step = detailsArg.step;
+        this.countedRequests = detailsArg.countedRequests;
+        this.matches = detailsArg.matches;
+        this.portalMessage = detailsArg.portalMessage;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5oYW5kZWxzcmVnaXN0ZXJlcnJvci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2hhbmRlbHNyZWdpc3Rlci9jbGFzc2VzLmhhbmRlbHNyZWdpc3RlcmVycm9yLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQTZDQTs7O0dBR0c7QUFDSCxNQUFNLE9BQU8sb0JBQXFCLFNBQVEsS0FBSztJQUM3QixJQUFJLENBQTRCO0lBQ2hELG1DQUFtQztJQUNuQixNQUFNLENBQVU7SUFDaEMsNkRBQTZEO0lBQzdDLE9BQU8sQ0FBVTtJQUNqQywyQkFBMkI7SUFDWCxJQUFJLENBQXdCO0lBQzVDOzs7T0FHRztJQUNhLGVBQWUsQ0FBVTtJQUN6Qzs7O09BR0c7SUFDYSxPQUFPLENBQW9CO0lBQzNDLHVFQUF1RTtJQUN2RCxhQUFhLENBQVU7SUFFdkMsWUFBWSxPQUFrQyxFQUFFLFVBQWtCLEVBQUUsYUFBMkMsRUFBRTtRQUMvRyxLQUFLLENBQUMsVUFBVSxFQUFFLFVBQVUsQ0FBQyxLQUFLLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLEVBQUUsS0FBSyxFQUFFLFVBQVUsQ0FBQyxLQUFLLEVBQUUsQ0FBQyxDQUFDO1FBQzVGLElBQUksQ0FBQyxJQUFJLEdBQUcsc0JBQXNCLENBQUM7UUFDbkMsSUFBSSxDQUFDLElBQUksR0FBRyxPQUFPLENBQUM7UUFDcEIsSUFBSSxDQUFDLE1BQU0sR0FBRyxVQUFVLENBQUMsTUFBTSxDQUFDO1FBQ2hDLElBQUksQ0FBQyxPQUFPLEdBQUcsVUFBVSxDQUFDLE9BQU8sQ0FBQztRQUNsQyxJQUFJLENBQUMsSUFBSSxHQUFHLFVBQVUsQ0FBQyxJQUFJLENBQUM7UUFDNUIsSUFBSSxDQUFDLGVBQWUsR0FBRyxVQUFVLENBQUMsZUFBZSxDQUFDO1FBQ2xELElBQUksQ0FBQyxPQUFPLEdBQUcsVUFBVSxDQUFDLE9BQU8sQ0FBQztRQUNsQyxJQUFJLENBQUMsYUFBYSxHQUFHLFVBQVUsQ0FBQyxhQUFhLENBQUM7SUFDaEQsQ0FBQztDQUNGIn0=

package/dist_ts/handelsregister/classes.portalsession.d.ts

@@ -0,0 +1,46 @@
+import { type THandelsregisterStep } from './classes.handelsregistererror.js';
+export interface IPortalSessionSettings {
+    portalUrl: string;
+    userAgent: string;
+    requestTimeoutMs: number;
+    maxResponseBytes: number;
+    signal?: AbortSignal;
+}
+/** what the caller of a session learns about the progress of its call */
+export interface ICallProgress {
+    step?: THandelsregisterStep;
+    /** counted requests sent so far */
+    countedRequests: number;
+}
+export interface IPortalResponse {
+    /** the URL that answered, after redirects */
+    url: string;
+    contentType: string;
+    body: Uint8Array;
+}
+/**
+ * One visit to the register portal: a cookie jar, the fixed language and a limit for every
+ * request. It lives for one call of the client and is dropped afterwards, so nothing is shared
+ * between calls or callers.
+ */
+export declare class PortalSession {
+    private settings;
+    private progress;
+    private cookies;
+    private origin;
+    /** the signal of the request in flight */
+    private currentSignal?;
+    constructor(settings: IPortalSessionSettings, progress: ICallProgress);
+    /** resolves a path or a relative action against the portal or a page */
+    resolve(targetArg: string, baseArg?: string): string;
+    get(urlArg: string): Promise<IPortalResponse>;
+    /** submits a form as `application/x-www-form-urlencoded` */
+    post(urlArg: string, fieldsArg: Array<[string, string]>): Promise<IPortalResponse>;
+    private fail;
+    private request;
+    private send;
+    /** a signal for one request: the caller's signal and the request's own time limit */
+    private requestSignal;
+    private failureOf;
+    private readBody;
+}

package/dist_ts/handelsregister/classes.portalsession.js

@@ -0,0 +1,160 @@
+import { HandelsregisterError } from './classes.handelsregistererror.js';
+const redirectStatuses = new Set([301, 302, 303]);
+const maxRedirects = 3;
+/**
+ * One visit to the register portal: a cookie jar, the fixed language and a limit for every
+ * request. It lives for one call of the client and is dropped afterwards, so nothing is shared
+ * between calls or callers.
+ */
+export class PortalSession {
+    settings;
+    progress;
+    cookies = new Map();
+    origin;
+    /** the signal of the request in flight */
+    currentSignal;
+    constructor(settings, progress) {
+        this.settings = settings;
+        this.progress = progress;
+        this.origin = new URL(settings.portalUrl).origin;
+    }
+    /** resolves a path or a relative action against the portal or a page */
+    resolve(targetArg, baseArg = this.origin) {
+        return new URL(targetArg, baseArg).toString();
+    }
+    async get(urlArg) {
+        return this.request('GET', urlArg);
+    }
+    /** submits a form as `application/x-www-form-urlencoded` */
+    async post(urlArg, fieldsArg) {
+        return this.request('POST', urlArg, new URLSearchParams(fieldsArg).toString());
+    }
+    fail(codeArg, messageArg, extraArg = {}) {
+        return new HandelsregisterError(codeArg, messageArg, {
+            ...extraArg,
+            step: this.progress.step,
+            countedRequests: this.progress.countedRequests,
+        });
+    }
+    async request(methodArg, urlArg, bodyArg) {
+        let method = methodArg;
+        let url = urlArg;
+        let body = bodyArg;
+        for (let redirects = 0;; redirects++) {
+            if (new URL(url).origin !== this.origin) {
+                throw this.fail('unexpected_response', 'The portal pointed to another site.');
+            }
+            const response = await this.send(method, url, body);
+            if (redirectStatuses.has(response.status)) {
+                const location = response.headers.get('location');
+                await response.body?.cancel();
+                if (!location || redirects >= maxRedirects) {
+                    throw this.fail('unexpected_response', 'The portal redirected in a way this version does not follow.');
+                }
+                url = new URL(location, url).toString();
+                method = 'GET';
+                body = undefined;
+                continue;
+            }
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                throw this.fail('refused', `The register portal answered with HTTP status ${response.status}.`, {
+                    status: response.status,
+                });
+            }
+            return {
+                url,
+                contentType: response.headers.get('content-type') ?? '',
+                body: await this.readBody(response),
+            };
+        }
+    }
+    async send(methodArg, urlArg, bodyArg) {
+        if (this.settings.signal?.aborted) {
+            throw this.fail('aborted', 'The call was aborted.', { cause: this.settings.signal.reason });
+        }
+        const headers = {
+            'User-Agent': this.settings.userAgent,
+            Accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+            'Accept-Language': 'de-DE,de;q=0.9',
+        };
+        if (this.cookies.size > 0) {
+            headers.Cookie = [...this.cookies].map(([name, value]) => `${name}=${value}`).join('; ');
+        }
+        if (bodyArg !== undefined) {
+            headers['Content-Type'] = 'application/x-www-form-urlencoded';
+        }
+        let response;
+        try {
+            response = await fetch(urlArg, {
+                method: methodArg,
+                headers,
+                body: bodyArg,
+                redirect: 'manual',
+                signal: this.requestSignal(),
+            });
+        }
+        catch (error) {
+            throw this.failureOf(error);
+        }
+        for (const cookie of response.headers.getSetCookie()) {
+            const pair = cookie.split(';', 1)[0];
+            const separator = pair.indexOf('=');
+            if (separator > 0) {
+                this.cookies.set(pair.slice(0, separator).trim(), pair.slice(separator + 1).trim());
+            }
+        }
+        return response;
+    }
+    /** a signal for one request: the caller's signal and the request's own time limit */
+    requestSignal() {
+        const timeout = AbortSignal.timeout(this.settings.requestTimeoutMs);
+        this.currentSignal = this.settings.signal ? AbortSignal.any([this.settings.signal, timeout]) : timeout;
+        return this.currentSignal;
+    }
+    failureOf(errorArg) {
+        if (errorArg instanceof HandelsregisterError) {
+            return errorArg;
+        }
+        if (this.settings.signal?.aborted) {
+            return this.fail('aborted', 'The call was aborted.', { cause: this.settings.signal.reason });
+        }
+        if (this.currentSignal?.aborted) {
+            return this.fail('timeout', 'The register portal did not answer in time.', { cause: errorArg });
+        }
+        return this.fail('unreachable', 'The register portal could not be reached.', { cause: errorArg });
+    }
+    async readBody(responseArg) {
+        if (!responseArg.body) {
+            return new Uint8Array(0);
+        }
+        const reader = responseArg.body.getReader();
+        const chunks = [];
+        let total = 0;
+        try {
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done) {
+                    break;
+                }
+                total += chunk.value.byteLength;
+                if (total > this.settings.maxResponseBytes) {
+                    await reader.cancel();
+                    throw this.fail('too_large', 'An answer of the register portal exceeded the size limit.');
+                }
+                chunks.push(chunk.value);
+            }
+        }
+        catch (error) {
+            throw this.failureOf(error);
+        }
+        const body = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return body;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5wb3J0YWxzZXNzaW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvaGFuZGVsc3JlZ2lzdGVyL2NsYXNzZXMucG9ydGFsc2Vzc2lvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsb0JBQW9CLEVBQTZCLE1BQU0sbUNBQW1DLENBQUM7QUF3QnBHLE1BQU0sZ0JBQWdCLEdBQUcsSUFBSSxHQUFHLENBQUMsQ0FBQyxHQUFHLEVBQUUsR0FBRyxFQUFFLEdBQUcsQ0FBQyxDQUFDLENBQUM7QUFDbEQsTUFBTSxZQUFZLEdBQUcsQ0FBQyxDQUFDO0FBRXZCOzs7O0dBSUc7QUFDSCxNQUFNLE9BQU8sYUFBYTtJQU1KO0lBQTBDO0lBTHRELE9BQU8sR0FBRyxJQUFJLEdBQUcsRUFBa0IsQ0FBQztJQUNwQyxNQUFNLENBQVM7SUFDdkIsMENBQTBDO0lBQ2xDLGFBQWEsQ0FBZTtJQUVwQyxZQUFvQixRQUFnQyxFQUFVLFFBQXVCO1FBQWpFLGFBQVEsR0FBUixRQUFRLENBQXdCO1FBQVUsYUFBUSxHQUFSLFFBQVEsQ0FBZTtRQUNuRixJQUFJLENBQUMsTUFBTSxHQUFHLElBQUksR0FBRyxDQUFDLFFBQVEsQ0FBQyxTQUFTLENBQUMsQ0FBQyxNQUFNLENBQUM7SUFDbkQsQ0FBQztJQUVELHdFQUF3RTtJQUNqRSxPQUFPLENBQUMsU0FBaUIsRUFBRSxVQUFrQixJQUFJLENBQUMsTUFBTTtRQUM3RCxPQUFPLElBQUksR0FBRyxDQUFDLFNBQVMsRUFBRSxPQUFPLENBQUMsQ0FBQyxRQUFRLEVBQUUsQ0FBQztJQUNoRCxDQUFDO0lBRU0sS0FBSyxDQUFDLEdBQUcsQ0FBQyxNQUFjO1FBQzdCLE9BQU8sSUFBSSxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsTUFBTSxDQUFDLENBQUM7SUFDckMsQ0FBQztJQUVELDREQUE0RDtJQUNyRCxLQUFLLENBQUMsSUFBSSxDQUFDLE1BQWMsRUFBRSxTQUFrQztRQUNsRSxP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

package/dist_ts/handelsregister/classes.slidingwindowgate.d.ts

@@ -0,0 +1,32 @@
+import type { IRegisterCountedRequest, IRegisterRequestGate } from './interfaces.js';
+export interface ISlidingWindowGateOptions {
+    /** requests allowed within one window; default 60, the portal's limit */
+    limit?: number;
+    /** length of the window; default one hour */
+    windowMs?: number;
+    /** clock; default `Date.now` */
+    now?: () => number;
+}
+/**
+ * Holds the portal's limit of 60 searches and retrievals per hour over a sliding window: a request
+ * is allowed when fewer than `limit` requests were allowed in the `windowMs` before it. A refusal is
+ * a `HandelsregisterError` with the code `rate_limited` and `retryAt`, the moment the oldest request
+ * leaves the window.
+ *
+ * The window lives in this object, so it counts for one process. Share one gate between every
+ * client of the installation that reaches the portal from the same address.
+ */
+export declare class SlidingWindowGate implements IRegisterRequestGate {
+    readonly limit: number;
+    readonly windowMs: number;
+    private now;
+    /** epoch ms of the allowed requests still inside the window, oldest first */
+    private allowed;
+    constructor(optionsArg?: ISlidingWindowGateOptions);
+    private prune;
+    acquire(_requestArg: IRegisterCountedRequest): Promise<void>;
+    /** requests still allowed now */
+    remaining(): number;
+    /** epoch ms from which the next request is allowed; now, when one is allowed already */
+    nextAllowedAt(): number;
+}

package/dist_ts/handelsregister/classes.slidingwindowgate.js

@@ -0,0 +1,55 @@
+import { HandelsregisterError } from './classes.handelsregistererror.js';
+import { portalRequestsPerHour } from './constants.js';
+/**
+ * Holds the portal's limit of 60 searches and retrievals per hour over a sliding window: a request
+ * is allowed when fewer than `limit` requests were allowed in the `windowMs` before it. A refusal is
+ * a `HandelsregisterError` with the code `rate_limited` and `retryAt`, the moment the oldest request
+ * leaves the window.
+ *
+ * The window lives in this object, so it counts for one process. Share one gate between every
+ * client of the installation that reaches the portal from the same address.
+ */
+export class SlidingWindowGate {
+    limit;
+    windowMs;
+    now;
+    /** epoch ms of the allowed requests still inside the window, oldest first */
+    allowed = [];
+    constructor(optionsArg = {}) {
+        this.limit = optionsArg.limit ?? portalRequestsPerHour;
+        this.windowMs = optionsArg.windowMs ?? 60 * 60 * 1000;
+        this.now = optionsArg.now ?? Date.now;
+        if (!Number.isInteger(this.limit) || this.limit < 1) {
+            throw new RangeError('limit must be a positive integer');
+        }
+        if (!Number.isFinite(this.windowMs) || this.windowMs <= 0) {
+            throw new RangeError('windowMs must be positive');
+        }
+    }
+    prune(nowArg) {
+        while (this.allowed.length > 0 && this.allowed[0] <= nowArg - this.windowMs) {
+            this.allowed.shift();
+        }
+    }
+    async acquire(_requestArg) {
+        const now = this.now();
+        this.prune(now);
+        if (this.allowed.length >= this.limit) {
+            const retryAt = this.allowed[0] + this.windowMs;
+            throw new HandelsregisterError('rate_limited', `The limit of ${this.limit} register requests per window is used up.`, { retryAt });
+        }
+        this.allowed.push(now);
+    }
+    /** requests still allowed now */
+    remaining() {
+        this.prune(this.now());
+        return this.limit - this.allowed.length;
+    }
+    /** epoch ms from which the next request is allowed; now, when one is allowed already */
+    nextAllowedAt() {
+        const now = this.now();
+        this.prune(now);
+        return this.allowed.length < this.limit ? now : this.allowed[this.allowed.length - this.limit] + this.windowMs;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zbGlkaW5nd2luZG93Z2F0ZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2hhbmRlbHNyZWdpc3Rlci9jbGFzc2VzLnNsaWRpbmd3aW5kb3dnYXRlLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxNQUFNLG1DQUFtQyxDQUFDO0FBQ3pFLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBWXZEOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxPQUFPLGlCQUFpQjtJQUNaLEtBQUssQ0FBUztJQUNkLFFBQVEsQ0FBUztJQUN6QixHQUFHLENBQWU7SUFDMUIsNkVBQTZFO0lBQ3JFLE9BQU8sR0FBYSxFQUFFLENBQUM7SUFFL0IsWUFBWSxhQUF3QyxFQUFFO1FBQ3BELElBQUksQ0FBQyxLQUFLLEdBQUcsVUFBVSxDQUFDLEtBQUssSUFBSSxxQkFBcUIsQ0FBQztRQUN2RCxJQUFJLENBQUMsUUFBUSxHQUFHLFVBQVUsQ0FBQyxRQUFRLElBQUksRUFBRSxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUM7UUFDdEQsSUFBSSxDQUFDLEdBQUcsR0FBRyxVQUFVLENBQUMsR0FBRyxJQUFJLElBQUksQ0FBQyxHQUFHLENBQUM7UUFDdEMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQUMsSUFBSSxDQUFDLEtBQUssQ0FBQyxJQUFJLElBQUksQ0FBQyxLQUFLLEdBQUcsQ0FBQyxFQUFFLENBQUM7WUFDcEQsTUFBTSxJQUFJLFVBQVUsQ0FBQyxrQ0FBa0MsQ0FBQyxDQUFDO1FBQzNELENBQUM7UUFDRCxJQUFJLENBQUMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLElBQUksSUFBSSxDQUFDLFFBQVEsSUFBSSxDQUFDLEVBQUUsQ0FBQztZQUMxRCxNQUFNLElBQUksVUFBVSxDQUFDLDJCQUEyQixDQUFDLENBQUM7UUFDcEQsQ0FBQztJQUNILENBQUM7SUFFTyxLQUFLLENBQUMsTUFBYztRQUMxQixPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxHQUFHLENBQUMsSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxJQUFJLE1BQU0sR0FBRyxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDNUUsSUFBSSxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsQ0FBQztRQUN2QixDQUFDO0lBQ0gsQ0FBQztJQUVNLEtBQUssQ0FBQyxPQUFPLENBQUMsV0FBb0M7UUFDdkQsTUFBTSxHQUFHLEdBQUcsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDO1FBQ3ZCLElBQUksQ0FBQyxLQUFLLENBQUMsR0FBRyxDQUFDLENBQUM7UUFDaEIsSUFBSSxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU0sSUFBSSxJQUFJLENBQUMsS0FBSyxFQUFFLENBQUM7WUFDdEMsTUFBTSxPQUFPLEdBQUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxDQUFDLENBQUMsR0FBRyxJQUFJLENBQUMsUUFBUSxDQUFDO1lBQ2hELE1BQU0sSUFBSSxvQkFBb0IsQ0FDNUIsY0FBYyxFQUNkLGdCQUFnQixJQUFJLENBQUMsS0FBSywyQ0FBMkMsRUFDckUsRUFBRSxPQUFPLEVBQUUsQ0FDWixDQUFDO1FBQ0osQ0FBQztRQUNELElBQUksQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQ3pCLENBQUM7SUFFRCxpQ0FBaUM7SUFDMUIsU0FBUztRQUNkLElBQUksQ0FBQyxLQUFLLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxDQUFDLENBQUM7UUFDdkIsT0FBTyxJQUFJLENBQUMsS0FBSyxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDO0lBQzFDLENBQUM7SUFFRCx3RkFBd0Y7SUFDakYsYUFBYTtRQUNsQixNQUFNLEdBQUcsR0FBRyxJQUFJLENBQUMsR0FBRyxFQUFFLENBQUM7UUFDdkIsSUFBSSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQztRQUNoQixPQUFPLElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxHQUFHLElBQUksQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLEdBQUcsQ0FBQyxDQUFDLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLE1BQU0sR0FBRyxJQUFJLENBQUMsS0FBSyxDQUFDLEdBQUcsSUFBSSxDQUFDLFFBQVEsQ0FBQztJQUNqSCxDQUFDO0NBQ0YifQ==

package/dist_ts/handelsregister/constants.d.ts

@@ -0,0 +1,13 @@
+import type { IStructuredContentNotice, TRegisterDocument, TRegisterType } from './interfaces.js';
+export declare const registerTypes: readonly TRegisterType[];
+export declare const registerDocuments: readonly TRegisterDocument[];
+/** the portal's note on its structured register content, from its start page (2026-09-23) */
+export declare const structuredContentNotice: IStructuredContentNotice;
+/** the portal's maximum number of hits for one search */
+export declare const portalMaximumHits = 100;
+export declare const defaultPortalUrl = "https://www.handelsregister.de";
+export declare const defaultUserAgent = "@fin.cx/opendata (+https://code.foss.global/fin.cx/opendata)";
+export declare const defaultRequestTimeoutMs = 20000;
+export declare const defaultMaxResponseBytes: number;
+/** the portal's terms: at most 60 searches or retrievals of entities per hour */
+export declare const portalRequestsPerHour = 60;

package/dist_ts/handelsregister/constants.js

@@ -0,0 +1,19 @@
+export const registerTypes = ['HRA', 'HRB', 'GnR', 'PR', 'VR', 'GsR'];
+export const registerDocuments = ['AD', 'CD', 'HD', 'DK', 'UT', 'VÖ', 'SI'];
+/** the portal's note on its structured register content, from its start page (2026-09-23) */
+export const structuredContentNotice = {
+    de: 'Soweit in den Ländern strukturierte Informationen zum Abruf zur Verfügung gestellt werden, handelt es sich ' +
+        'um einen unverbindlichen Service. Der Inhalt kann in speziellen Fällen vom Inhalt des aktuellen Abdrucks ' +
+        'abweichen und diesen ggf. nicht vollständig wiedergeben.',
+    en: 'Where the federal states provide structured information for retrieval, this is a non-binding service. In ' +
+        'special cases its content can differ from the current printout and may not reproduce it completely.',
+};
+/** the portal's maximum number of hits for one search */
+export const portalMaximumHits = 100;
+export const defaultPortalUrl = 'https://www.handelsregister.de';
+export const defaultUserAgent = '@fin.cx/opendata (+https://code.foss.global/fin.cx/opendata)';
+export const defaultRequestTimeoutMs = 20_000;
+export const defaultMaxResponseBytes = 5 * 1024 * 1024;
+/** the portal's terms: at most 60 searches or retrievals of entities per hour */
+export const portalRequestsPerHour = 60;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc3RhbnRzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvaGFuZGVsc3JlZ2lzdGVyL2NvbnN0YW50cy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFFQSxNQUFNLENBQUMsTUFBTSxhQUFhLEdBQTZCLENBQUMsS0FBSyxFQUFFLEtBQUssRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxLQUFLLENBQUMsQ0FBQztBQUVoRyxNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBaUMsQ0FBQyxJQUFJLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxJQUFJLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxJQUFJLENBQUMsQ0FBQztBQUUxRyw2RkFBNkY7QUFDN0YsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQTZCO0lBQy9ELEVBQUUsRUFDQSw2R0FBNkc7UUFDN0csMkdBQTJHO1FBQzNHLDBEQUEwRDtJQUM1RCxFQUFFLEVBQ0EsMkdBQTJHO1FBQzNHLHFHQUFxRztDQUN4RyxDQUFDO0FBRUYseURBQXlEO0FBQ3pELE1BQU0sQ0FBQyxNQUFNLGlCQUFpQixHQUFHLEdBQUcsQ0FBQztBQUVyQyxNQUFNLENBQUMsTUFBTSxnQkFBZ0IsR0FBRyxnQ0FBZ0MsQ0FBQztBQUVqRSxNQUFNLENBQUMsTUFBTSxnQkFBZ0IsR0FBRyw4REFBOEQsQ0FBQztBQUUvRixNQUFNLENBQUMsTUFBTSx1QkFBdUIsR0FBRyxNQUFNLENBQUM7QUFFOUMsTUFBTSxDQUFDLE1BQU0sdUJBQXVCLEdBQUcsQ0FBQyxHQUFHLElBQUksR0FBRyxJQUFJLENBQUM7QUFFdkQsaUZBQWlGO0FBQ2pGLE1BQU0sQ0FBQyxNQUFNLHFCQUFxQixHQUFHLEVBQUUsQ0FBQyJ9

package/dist_ts/handelsregister/data.codelists.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Code tables for reading the register portal's structured register content (SI, XJustiz).
+ *
+ * Taken on 2026-09-23 from the code lists published on XRepository (https://www.xrepository.de):
+ * - urn:xoev-de:xunternehmen:codeliste:rechtsformen_2.4, the codes the justice registers can carry;
+ * - urn:xoev-de:xjustiz:codeliste:gds.rollenbezeichnung_3.6, the roles that occur in register content;
+ * - urn:xoev-de:xjustiz:codeliste:reg.status-rechtstraeger_2.0;
+ * - urn:xoev-de:bund:bfj:codeliste:bfj.staat_7.0, reduced to key and ISO 3166-1 alpha-2 code.
+ *
+ * The register courts are the options of the portal's search form of the same day; their codes
+ * are those of urn:xoev-de:xjustiz:codeliste:gds.gerichte.
+ */
+import type { IRegisterCourt } from './interfaces.js';
+export interface ILegalFormLabel {
+    /** short designation, for example `GmbH` */
+    short?: string;
+    /** full designation, for example `Gesellschaft mit beschränkter Haftung` */
+    long: string;
+}
+/** XUnternehmen legal form code → designation */
+export declare const legalFormLabels: Readonly<Record<string, ILegalFormLabel>>;
+/** XJustiz role code → designation */
+export declare const roleLabels: Readonly<Record<string, string>>;
+/** XJustiz status code of the legal entity → designation */
+export declare const entityStatusLabels: Readonly<Record<string, string>>;
+/** BfJ state key → ISO 3166-1 alpha-2 */
+export declare const stateKeyToIso: Readonly<Record<string, string>>;
+/** the register courts of the portal, as its search form names them */
+export declare const registerCourts: readonly IRegisterCourt[];