@jvaarala/vm-buketti 0.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+MIT License
+
+Copyright (c) 2026 Jesse Väärälä
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+DATA LICENSE NOTICE
+
+The data retrieved through this library originates from budjetti.vm.fi and is
+published by the Ministry of Finance of Finland as part of the open government
+data programme. The data is licensed under the Creative Commons Attribution 4.0
+International license (CC BY 4.0):
+
+  http://creativecommons.org/licenses/by/4.0/
+
+Users of this library must comply with the CC BY 4.0 terms when using the data,
+including crediting the Ministry of Finance of Finland as the source.

package/README.md

@@ -0,0 +1,96 @@
+# vm-buketti
+
+TypeScript client for the Finnish state budget open data API at [budjetti.vm.fi](https://budjetti.vm.fi).
+
+Turns the XML-based API into a lazy-loading tree you can navigate by awaiting properties — no manual XML parsing, no upfront fetches.
+
+## Install
+
+```sh
+npm install @jvaarala/vm-buketti
+```
+
+## Usage
+
+```ts
+import { createVmBuketti } from '@jvaarala/vm-buketti';
+
+// Node 18+ (direct fetch — no proxy needed):
+const service = createVmBuketti();
+
+// Browser (requires a CORS proxy):
+const service = createVmBuketti({ proxyUrl: '/proxy' });
+
+// Navigate the budget tree
+const juuri   = service.getJuuri();
+const vuodet  = await juuri.Vuosi;                     // all budget years
+const teos    = vuodet[0].Teos[0];                     // first publication (e.g. tae)
+const kanta   = teos.Kanta[0];                         // budget version
+const pkList  = await kanta.Paaluokka;                 // expense main classes (lazy fetch)
+const menot   = await pkList[0].Menoluku;              // chapters within first main class
+```
+
+Data is fetched on demand. Accessing a property for the first time fires the corresponding XML request; repeated accesses return the cached Promise.
+
+## API
+
+### `createVmBuketti(options?)`
+
+Returns a `VmBuketti` instance.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `proxyUrl` | `string` | Prefix for CORS proxy requests, e.g. `'/proxy'`. Appends `?url=<encoded>`. |
+| `fetchXml` | `(url: string) => Promise<string>` | Custom fetch function. Takes precedence over `proxyUrl`. |
+| `onError` | `(error: Error, url: string) => void` | Called when a sub-link fetch fails. Defaults to silent (partial data returned). |
+
+### `service.getJuuri(): Juuri`
+
+Returns the root node. Calling this does not trigger any network requests — fetches are deferred until properties are accessed.
+
+## Budget hierarchy
+
+```
+Juuri
+└── Vuosi[]           (year)
+    └── Teos[]        (publication: tae, ltae1–ltae7)
+        └── Kanta[]   (version: hallituksenEsitys, eduskunnanKirjelma, …)
+            ├── Paaluokka[]   → Menoluku[]   → Menomomentti[]   (expenses)
+            └── Osasto[]      → Tuloluku[]   → Tulomomentti[]   (revenues)
+```
+
+## TypeScript types
+
+All types mirror the XSD schema from budjetti.vm.fi. Lazy nodes (fetched on demand) use `Lazy*` prefixed types with `Promise<T[]>` children.
+
+```ts
+import type { LazyVuosi, LazyKanta, Menoluku } from '@jvaarala/vm-buketti';
+```
+
+Enumerated attributes (e.g. `teostyyppi`, `momenttityyppi`) include a `| (string & {})` fallback so that values the XSD hasn't yet listed — such as `ltae6`/`ltae7` in live data — are accepted without TypeScript errors while known values still benefit from autocomplete.
+
+## Regenerating types
+
+If the upstream XSD changes, regenerate `src/schema.ts`:
+
+```sh
+npm run gen-schema
+```
+
+The generated file must not be edited by hand.
+
+## Requirements
+
+- Node 18+ or any modern browser (uses `fetch` and `DOMParser`)
+- No runtime dependencies
+
+## Data license
+
+The budget data accessed through this library is published by the Finnish Ministry of Finance as part of the open government data programme. Budget proposals have been available in machine-readable XML format since 2014 (government proposals from 2014, Ministry of Finance drafts from 2016). Parliamentary letters are also published in machine-readable form.
+
+The data is licensed under the **Creative Commons Attribution 4.0 International** license (CC BY 4.0):
+http://creativecommons.org/licenses/by/4.0/
+
+When using data retrieved via this library, you must credit the Ministry of Finance of Finland as the data source.
+
+This library itself (the wrapper code) is MIT-licensed.

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export type { Laskelmaraha, Muutos, Vertailuluvut, Budjettilaskelma, Tulomomentti, Tuloluku, Osasto, Menomomentti, Menoluku, Paaluokka, Kanta, Teos, Vuosi, LazyOsasto, LazyPaaluokka, LazyKanta, LazyTeos, LazyVuosi, Juuri, } from './schema.js';
+import type { Juuri } from './schema.js';
+export interface VmBukettiOptions {
+    /**
+     * URL of a CORS proxy endpoint that accepts `?url=<encoded>` query params.
+     *
+     * @example
+     * createVmBuketti({ proxyUrl: '/proxy' });
+     */
+    proxyUrl?: string;
+    /**
+     * Custom function for fetching XML content from a URL.
+     * Use this to add custom headers, authentication, etc.
+     * Takes precedence over `proxyUrl`.
+     *
+     * Defaults to `fetch(url)` using the global `fetch`.
+     */
+    fetchXml?: (url: string) => Promise<string>;
+    /**
+     * Called when a sub-link fetch fails during lazy loading.
+     * If not provided, failures are silently ignored (partial data is returned).
+     */
+    onError?: (error: Error, url: string) => void;
+}
+export interface VmBuketti {
+    getJuuri(): Juuri;
+}
+/**
+ * Creates a VmBuketti instance for accessing the Finnish state budget API.
+ *
+ * @example
+ * // Node.js (fetch available globally in Node 18+):
+ * const service = createVmBuketti();
+ *
+ * @example
+ * // Browser with CORS proxy:
+ * const service = createVmBuketti({
+ *   fetchXml: url => fetch('/proxy?url=' + encodeURIComponent(url)).then(r => r.text())
+ * });
+ */
+export declare function createVmBuketti(options?: VmBukettiOptions): VmBuketti;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EACrD,YAAY,EAAE,QAAQ,EAAE,MAAM,EAC9B,YAAY,EAAE,QAAQ,EAAE,SAAS,EACjC,KAAK,EAAE,IAAI,EAAE,KAAK,EAClB,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EACzD,KAAK,GACN,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5C;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,IAAI,KAAK,CAAC;CACnB;AA2ID;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAuBrE"}

package/dist/index.js

@@ -0,0 +1,152 @@
+const ROOT_URL = 'https://budjetti.vm.fi/opendata/opendata-xml.jsp';
+const XLINK_NS = 'http://www.w3.org/1999/xlink';
+// ── XML helpers ──────────────────────────────────────────────────────────────
+function parseXML(text) {
+    const doc = new DOMParser().parseFromString(text, 'application/xml');
+    const err = doc.querySelector('parsererror');
+    if (err)
+        throw new Error('XML parse error: ' + err.textContent?.slice(0, 120));
+    return doc;
+}
+function getHref(el) {
+    return el.getAttributeNS(XLINK_NS, 'href') || el.getAttribute('xlink:href') || null;
+}
+function toCamel(s) {
+    return s.replace(/[-:]([a-z])/g, (_, c) => c.toUpperCase());
+}
+// ── Generic lazy tree builder ────────────────────────────────────────────────
+//
+// The traversal algorithm is the same for every node in the tree:
+//   - If the element has xlink:href it must be fetched before its children are
+//     readable. A Proxy intercepts child-property accesses and fires the fetch
+//     on demand, caching the resulting Promise.
+//   - Otherwise, children are already in the DOM and can be wrapped eagerly;
+//     but if any child element carries an xlink:href the child array is still
+//     wrapped in a Promise so callers use a consistent await pattern.
+//
+// The Juuri root is treated the same way via a document-level Proxy.
+function readAttrs(el) {
+    const out = {};
+    for (const attr of el.attributes) {
+        if (attr.namespaceURI)
+            continue; // skip xlink:href, xmlns:* and any other namespace attrs
+        const key = toCamel(attr.name);
+        out[key] = /^-?\d+(\.\d+)?$/.test(attr.value) ? Number(attr.value) : attr.value;
+    }
+    return out;
+}
+function buildNode(el, rootDoc, resolveEl) {
+    const attrs = readAttrs(el);
+    if (getHref(el)) {
+        // xlink element: children unknown until fetched — use a Proxy
+        let resolved = null;
+        const ensure = () => {
+            if (!resolved)
+                resolved = resolveEl(el, rootDoc);
+            return resolved;
+        };
+        const childCache = new Map();
+        return new Proxy(attrs, {
+            get(target, prop) {
+                if (typeof prop !== 'string')
+                    return undefined;
+                if (prop === 'then')
+                    return undefined;
+                if (Object.prototype.hasOwnProperty.call(target, prop))
+                    return target[prop];
+                if (!childCache.has(prop)) {
+                    childCache.set(prop, ensure().then(() => {
+                        const children = [...el.children].filter(c => c.tagName === prop);
+                        return children.map(c => buildNode(c, rootDoc, resolveEl));
+                    }));
+                }
+                return childCache.get(prop);
+            },
+        });
+    }
+    // Non-xlink element: children are in the DOM now
+    const node = { ...attrs };
+    const groups = new Map();
+    for (const child of el.children) {
+        if (!groups.has(child.tagName))
+            groups.set(child.tagName, []);
+        groups.get(child.tagName).push(child);
+    }
+    for (const [tag, children] of groups) {
+        node[tag] = children.map(c => buildNode(c, rootDoc, resolveEl));
+    }
+    return node;
+}
+function buildJuuri(fetchRoot, resolveEl) {
+    const childCache = new Map();
+    let docP = null;
+    const ensure = () => {
+        if (!docP)
+            docP = fetchRoot();
+        return docP;
+    };
+    return new Proxy({}, {
+        get(_, prop) {
+            if (typeof prop !== 'string' || prop === 'then')
+                return undefined;
+            if (!childCache.has(prop))
+                childCache.set(prop, ensure().then(doc => [...doc.documentElement.children]
+                    .filter(c => c.tagName === prop)
+                    .map(el => buildNode(el, doc, resolveEl))));
+            return childCache.get(prop);
+        },
+    });
+}
+// ── Fetch infrastructure ─────────────────────────────────────────────────────
+function makeResolveEl(fetchXml, onError) {
+    return async function resolveEl(el, rootDoc) {
+        const h = getHref(el);
+        if (!h)
+            return;
+        const url = new URL(h, ROOT_URL).href;
+        try {
+            const text = await fetchXml(url);
+            const doc = parseXML(text);
+            while (el.lastChild)
+                el.removeChild(el.lastChild);
+            [...doc.documentElement.children].forEach(c => el.appendChild(rootDoc.importNode(c, true)));
+            el.removeAttributeNS(XLINK_NS, 'href');
+            el.removeAttribute('xlink:href');
+        }
+        catch (e) {
+            onError?.(e, url);
+        }
+    };
+}
+// ── Public factory ───────────────────────────────────────────────────────────
+/**
+ * Creates a VmBuketti instance for accessing the Finnish state budget API.
+ *
+ * @example
+ * // Node.js (fetch available globally in Node 18+):
+ * const service = createVmBuketti();
+ *
+ * @example
+ * // Browser with CORS proxy:
+ * const service = createVmBuketti({
+ *   fetchXml: url => fetch('/proxy?url=' + encodeURIComponent(url)).then(r => r.text())
+ * });
+ */
+export function createVmBuketti(options) {
+    const doFetch = async (url) => {
+        const r = await fetch(url);
+        if (!r.ok)
+            throw new Error(`Server returned ${r.status} for ${url}`);
+        return r.text();
+    };
+    const fetchXml = options?.fetchXml ?? (options?.proxyUrl
+        ? (url) => doFetch(options.proxyUrl + '?url=' + encodeURIComponent(url))
+        : doFetch);
+    const resolveEl = makeResolveEl(fetchXml, options?.onError);
+    return {
+        getJuuri() {
+            return buildJuuri(() => fetchXml(ROOT_URL).then(parseXML), resolveEl);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,98 @@
+export interface Laskelmaraha {
+    tyyppi: 'toteutuma' | 'aiemmin-budjetoitu' | 'aiemmin-budjetoitu-ltae' | 'aiemmin-budjetoitu-ltae1' | 'aiemmin-budjetoitu-ltae2' | 'aiemmin-budjetoitu-ltae3' | 'aiemmin-budjetoitu-ltae4' | 'aiemmin-budjetoitu-ltae5' | 'muutosraha' | 'maararaha' | (string & {});
+    vuosi: string | null;
+    arvo: number | null;
+}
+export interface Muutos {
+    kuvaus: string | null;
+    Laskelmaraha: Laskelmaraha[];
+}
+export interface Vertailuluvut {
+    Laskelmaraha: Laskelmaraha[];
+}
+export interface Budjettilaskelma {
+    Laskelmaraha: Laskelmaraha[];
+    Muutos: Muutos[];
+    Vertailuluvut: Vertailuluvut[];
+}
+export interface Tulomomentti {
+    nimi: string | null;
+    numero: string | null;
+    momenttityyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'siirretty' | 'uusi' | (string & {}) | null;
+    infoOsa: string | null;
+    Budjettilaskelma: Budjettilaskelma[];
+}
+export interface Tuloluku {
+    nimi: string | null;
+    numero: string | null;
+    lukutyyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'uusi' | (string & {}) | null;
+    infoOsa: string | null;
+    Tulomomentti: Tulomomentti[];
+}
+export interface Osasto {
+    numero: string | null;
+    nimi: string | null;
+    Tuloluku: Tuloluku[];
+}
+export interface Menomomentti {
+    maararahalaji: 'arviomaararaha' | 'kiinteamaararaha' | 'siirtomaararaha_2v' | 'siirtomaararaha_3v' | 'siirtomaararaha_5v' | (string & {}) | null;
+    nimi: string | null;
+    numero: string | null;
+    momenttityyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'siirretty' | 'uusi' | (string & {}) | null;
+    infoOsa: string | null;
+    Budjettilaskelma: Budjettilaskelma[];
+}
+export interface Menoluku {
+    nimi: string | null;
+    numero: string | null;
+    lukutyyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'uusi' | (string & {}) | null;
+    infoOsa: string | null;
+    Menomomentti: Menomomentti[];
+}
+export interface Paaluokka {
+    numero: string | null;
+    nimi: string | null;
+    Menoluku: Menoluku[];
+}
+export interface Kanta {
+    kanta: 'valtiovarainministerionKanta' | 'hallituksenEsitys' | 'eduskunnanKirjelma' | (string & {}) | null;
+    Osasto: Osasto[];
+    Paaluokka: Paaluokka[];
+}
+export interface Teos {
+    nimi: string | null;
+    teostyyppi: 'tae' | 'ltae1' | 'ltae2' | 'ltae3' | 'ltae4' | 'ltae5' | (string & {}) | null;
+    Kanta: Kanta[];
+}
+export interface Vuosi {
+    vuosi: number;
+    Teos: Teos[];
+}
+export interface LazyOsasto {
+    numero: string | null;
+    nimi: string | null;
+    readonly Tuloluku: Promise<Tuloluku[]>;
+}
+export interface LazyPaaluokka {
+    numero: string | null;
+    nimi: string | null;
+    readonly Menoluku: Promise<Menoluku[]>;
+}
+export interface LazyKanta {
+    kanta: 'valtiovarainministerionKanta' | 'hallituksenEsitys' | 'eduskunnanKirjelma' | (string & {}) | null;
+    readonly Osasto: Promise<LazyOsasto[]>;
+    readonly Paaluokka: Promise<LazyPaaluokka[]>;
+}
+export interface LazyTeos {
+    nimi: string | null;
+    teostyyppi: 'tae' | 'ltae1' | 'ltae2' | 'ltae3' | 'ltae4' | 'ltae5' | (string & {}) | null;
+    Kanta: LazyKanta[];
+}
+export interface LazyVuosi {
+    vuosi: number;
+    Teos: LazyTeos[];
+}
+export interface Juuri {
+    readonly Vuosi: Promise<LazyVuosi[]>;
+}
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -0,0 +1,4 @@
+// Auto-generated from https://budjetti.vm.fi/indox/opendata/kl_buketti.xsd
+// Regenerate with: npm run gen-schema
+export {};
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,sCAAsC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@jvaarala/vm-buketti",
+  "version": "0.1.0",
+  "description": "TypeScript client for the Finnish state budget open data API (budjetti.vm.fi)",
+  "author": "Jesse Väärälä",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jvaarala/vm-buketti.git"
+  },
+  "homepage": "https://github.com/jvaarala/vm-buketti#readme",
+  "bugs": {
+    "url": "https://github.com/jvaarala/vm-buketti/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "sideEffects": false,
+  "files": ["dist", "src"],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "gen-schema": "node scripts/gen-schema.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "finland",
+    "budget",
+    "talousarvio",
+    "budjetti",
+    "vm.fi",
+    "opendata",
+    "budjetti.vm.fi",
+    "api",
+    "typescript",
+    "client"
+  ],
+  "devDependencies": {
+    "typescript": "^6.0.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,214 @@
+export type {
+  Laskelmaraha, Muutos, Vertailuluvut, Budjettilaskelma,
+  Tulomomentti, Tuloluku, Osasto,
+  Menomomentti, Menoluku, Paaluokka,
+  Kanta, Teos, Vuosi,
+  LazyOsasto, LazyPaaluokka, LazyKanta, LazyTeos, LazyVuosi,
+  Juuri,
+} from './schema.js';
+
+import type { Juuri } from './schema.js';
+
+export interface VmBukettiOptions {
+  /**
+   * URL of a CORS proxy endpoint that accepts `?url=<encoded>` query params.
+   *
+   * @example
+   * createVmBuketti({ proxyUrl: '/proxy' });
+   */
+  proxyUrl?: string;
+
+  /**
+   * Custom function for fetching XML content from a URL.
+   * Use this to add custom headers, authentication, etc.
+   * Takes precedence over `proxyUrl`.
+   *
+   * Defaults to `fetch(url)` using the global `fetch`.
+   */
+  fetchXml?: (url: string) => Promise<string>;
+
+  /**
+   * Called when a sub-link fetch fails during lazy loading.
+   * If not provided, failures are silently ignored (partial data is returned).
+   */
+  onError?: (error: Error, url: string) => void;
+}
+
+export interface VmBuketti {
+  getJuuri(): Juuri;
+}
+
+const ROOT_URL = 'https://budjetti.vm.fi/opendata/opendata-xml.jsp';
+const XLINK_NS = 'http://www.w3.org/1999/xlink';
+
+type ResolveEl = (el: Element, rootDoc: Document) => Promise<void>;
+
+// ── XML helpers ──────────────────────────────────────────────────────────────
+
+function parseXML(text: string): Document {
+  const doc = new DOMParser().parseFromString(text, 'application/xml');
+  const err = doc.querySelector('parsererror');
+  if (err) throw new Error('XML parse error: ' + err.textContent?.slice(0, 120));
+  return doc;
+}
+
+function getHref(el: Element): string | null {
+  return el.getAttributeNS(XLINK_NS, 'href') || el.getAttribute('xlink:href') || null;
+}
+
+function toCamel(s: string): string {
+  return s.replace(/[-:]([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+// ── Generic lazy tree builder ────────────────────────────────────────────────
+//
+// The traversal algorithm is the same for every node in the tree:
+//   - If the element has xlink:href it must be fetched before its children are
+//     readable. A Proxy intercepts child-property accesses and fires the fetch
+//     on demand, caching the resulting Promise.
+//   - Otherwise, children are already in the DOM and can be wrapped eagerly;
+//     but if any child element carries an xlink:href the child array is still
+//     wrapped in a Promise so callers use a consistent await pattern.
+//
+// The Juuri root is treated the same way via a document-level Proxy.
+
+function readAttrs(el: Element): Record<string, string | number> {
+  const out: Record<string, string | number> = {};
+  for (const attr of el.attributes) {
+    if (attr.namespaceURI) continue; // skip xlink:href, xmlns:* and any other namespace attrs
+    const key = toCamel(attr.name);
+    out[key] = /^-?\d+(\.\d+)?$/.test(attr.value) ? Number(attr.value) : attr.value;
+  }
+  return out;
+}
+
+function buildNode(el: Element, rootDoc: Document, resolveEl: ResolveEl): unknown {
+  const attrs = readAttrs(el);
+
+  if (getHref(el)) {
+    // xlink element: children unknown until fetched — use a Proxy
+    let resolved: Promise<void> | null = null;
+    const ensure = (): Promise<void> => {
+      if (!resolved) resolved = resolveEl(el, rootDoc);
+      return resolved;
+    };
+    const childCache = new Map<string, Promise<unknown[]>>();
+
+    return new Proxy(attrs as Record<string, unknown>, {
+      get(target, prop) {
+        if (typeof prop !== 'string') return undefined;
+        if (prop === 'then') return undefined;
+        if (Object.prototype.hasOwnProperty.call(target, prop)) return target[prop];
+        if (!childCache.has(prop)) {
+          childCache.set(prop, ensure().then(() => {
+            const children = [...el.children].filter(c => c.tagName === prop);
+            return children.map(c => buildNode(c, rootDoc, resolveEl));
+          }));
+        }
+        return childCache.get(prop);
+      },
+    });
+  }
+
+  // Non-xlink element: children are in the DOM now
+  const node: Record<string, unknown> = { ...attrs };
+
+  const groups = new Map<string, Element[]>();
+  for (const child of el.children) {
+    if (!groups.has(child.tagName)) groups.set(child.tagName, []);
+    groups.get(child.tagName)!.push(child);
+  }
+
+  for (const [tag, children] of groups) {
+    node[tag] = children.map(c => buildNode(c, rootDoc, resolveEl));
+  }
+
+  return node;
+}
+
+function buildJuuri(fetchRoot: () => Promise<Document>, resolveEl: ResolveEl): Juuri {
+  const childCache = new Map<string, Promise<unknown[]>>();
+  let docP: Promise<Document> | null = null;
+  const ensure = (): Promise<Document> => {
+    if (!docP) docP = fetchRoot();
+    return docP;
+  };
+
+  return new Proxy({} as unknown as Juuri, {
+    get(_, prop) {
+      if (typeof prop !== 'string' || prop === 'then') return undefined;
+      if (!childCache.has(prop))
+        childCache.set(prop, ensure().then(doc =>
+          [...doc.documentElement.children]
+            .filter(c => c.tagName === prop)
+            .map(el => buildNode(el, doc, resolveEl))
+        ));
+      return childCache.get(prop);
+    },
+  });
+}
+
+// ── Fetch infrastructure ─────────────────────────────────────────────────────
+
+function makeResolveEl(
+  fetchXml: (url: string) => Promise<string>,
+  onError?: (error: Error, url: string) => void,
+): ResolveEl {
+  return async function resolveEl(el: Element, rootDoc: Document): Promise<void> {
+    const h = getHref(el);
+    if (!h) return;
+    const url = new URL(h, ROOT_URL).href;
+    try {
+      const text = await fetchXml(url);
+      const doc = parseXML(text);
+      while (el.lastChild) el.removeChild(el.lastChild);
+      [...doc.documentElement.children].forEach(c =>
+        el.appendChild(rootDoc.importNode(c, true))
+      );
+      el.removeAttributeNS(XLINK_NS, 'href');
+      el.removeAttribute('xlink:href');
+    } catch (e) {
+      onError?.(e as Error, url);
+    }
+  };
+}
+
+// ── Public factory ───────────────────────────────────────────────────────────
+
+/**
+ * Creates a VmBuketti instance for accessing the Finnish state budget API.
+ *
+ * @example
+ * // Node.js (fetch available globally in Node 18+):
+ * const service = createVmBuketti();
+ *
+ * @example
+ * // Browser with CORS proxy:
+ * const service = createVmBuketti({
+ *   fetchXml: url => fetch('/proxy?url=' + encodeURIComponent(url)).then(r => r.text())
+ * });
+ */
+export function createVmBuketti(options?: VmBukettiOptions): VmBuketti {
+  const doFetch = async (url: string) => {
+    const r = await fetch(url);
+    if (!r.ok) throw new Error(`Server returned ${r.status} for ${url}`);
+    return r.text();
+  };
+
+  const fetchXml = options?.fetchXml ?? (
+    options?.proxyUrl
+      ? (url: string) => doFetch(options.proxyUrl! + '?url=' + encodeURIComponent(url))
+      : doFetch
+  );
+
+  const resolveEl = makeResolveEl(fetchXml, options?.onError);
+
+  return {
+    getJuuri(): Juuri {
+      return buildJuuri(
+        () => fetchXml(ROOT_URL).then(parseXML),
+        resolveEl,
+      );
+    },
+  };
+}

package/src/schema.ts

@@ -0,0 +1,120 @@
+// Auto-generated from https://budjetti.vm.fi/indox/opendata/kl_buketti.xsd
+// Regenerate with: npm run gen-schema
+
+export interface Laskelmaraha {
+  tyyppi: 'toteutuma' | 'aiemmin-budjetoitu' | 'aiemmin-budjetoitu-ltae' | 'aiemmin-budjetoitu-ltae1' | 'aiemmin-budjetoitu-ltae2' | 'aiemmin-budjetoitu-ltae3' | 'aiemmin-budjetoitu-ltae4' | 'aiemmin-budjetoitu-ltae5' | 'muutosraha' | 'maararaha' | (string & {});
+  vuosi: string | null;
+  arvo: number | null;
+}
+
+export interface Muutos {
+  kuvaus: string | null;
+  Laskelmaraha: Laskelmaraha[];
+}
+
+export interface Vertailuluvut {
+  Laskelmaraha: Laskelmaraha[];
+}
+
+export interface Budjettilaskelma {
+  Laskelmaraha: Laskelmaraha[];
+  Muutos: Muutos[];
+  Vertailuluvut: Vertailuluvut[];
+}
+
+export interface Tulomomentti {
+  nimi: string | null;
+  numero: string | null;
+  momenttityyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'siirretty' | 'uusi' | (string & {}) | null;
+  infoOsa: string | null;
+  Budjettilaskelma: Budjettilaskelma[];
+}
+
+export interface Tuloluku {
+  nimi: string | null;
+  numero: string | null;
+  lukutyyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'uusi' | (string & {}) | null;
+  infoOsa: string | null;
+  Tulomomentti: Tulomomentti[];
+}
+
+export interface Osasto {
+  numero: string | null;
+  nimi: string | null;
+  Tuloluku: Tuloluku[];
+}
+
+export interface Menomomentti {
+  maararahalaji: 'arviomaararaha' | 'kiinteamaararaha' | 'siirtomaararaha_2v' | 'siirtomaararaha_3v' | 'siirtomaararaha_5v' | (string & {}) | null;
+  nimi: string | null;
+  numero: string | null;
+  momenttityyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'siirretty' | 'uusi' | (string & {}) | null;
+  infoOsa: string | null;
+  Budjettilaskelma: Budjettilaskelma[];
+}
+
+export interface Menoluku {
+  nimi: string | null;
+  numero: string | null;
+  lukutyyppi: 'aktiivinen' | 'poistettava' | 'poistettu' | 'uusi' | (string & {}) | null;
+  infoOsa: string | null;
+  Menomomentti: Menomomentti[];
+}
+
+export interface Paaluokka {
+  numero: string | null;
+  nimi: string | null;
+  Menoluku: Menoluku[];
+}
+
+export interface Kanta {
+  kanta: 'valtiovarainministerionKanta' | 'hallituksenEsitys' | 'eduskunnanKirjelma' | (string & {}) | null;
+  Osasto: Osasto[];
+  Paaluokka: Paaluokka[];
+}
+
+export interface Teos {
+  nimi: string | null;
+  teostyyppi: 'tae' | 'ltae1' | 'ltae2' | 'ltae3' | 'ltae4' | 'ltae5' | (string & {}) | null;
+  Kanta: Kanta[];
+}
+
+export interface Vuosi {
+  vuosi: number;
+  Teos: Teos[];
+}
+
+// ── Lazy types (for elements with xlink:href and their ancestors) ────────────
+
+export interface LazyOsasto {
+  numero: string | null;
+  nimi: string | null;
+  readonly Tuloluku: Promise<Tuloluku[]>;
+}
+
+export interface LazyPaaluokka {
+  numero: string | null;
+  nimi: string | null;
+  readonly Menoluku: Promise<Menoluku[]>;
+}
+
+export interface LazyKanta {
+  kanta: 'valtiovarainministerionKanta' | 'hallituksenEsitys' | 'eduskunnanKirjelma' | (string & {}) | null;
+  readonly Osasto: Promise<LazyOsasto[]>;
+  readonly Paaluokka: Promise<LazyPaaluokka[]>;
+}
+
+export interface LazyTeos {
+  nimi: string | null;
+  teostyyppi: 'tae' | 'ltae1' | 'ltae2' | 'ltae3' | 'ltae4' | 'ltae5' | (string & {}) | null;
+  Kanta: LazyKanta[];
+}
+
+export interface LazyVuosi {
+  vuosi: number;
+  Teos: LazyTeos[];
+}
+
+export interface Juuri {
+  readonly Vuosi: Promise<LazyVuosi[]>;
+}