@kirjapro/mcp-server 0.5.10 → 0.6.0

package/CHANGELOG.md

@@ -1,17 +1,46 @@
 # Changelog
 
+## [0.6.0] - 2026-05-26
+
+Syncs the published package with the 2026-05-22 offers/server-side migrations and fixes two latent bugs surfaced by an audit. Minor-bumped (not patch) because `kirjapro_update_offer_status` narrows its accepted input.
+
+### Changed
+
+- **`kirjapro_update_offer_status` (breaking input change)** — now delegates to the `record_offer_status_change` SECURITY DEFINER RPC (atomic status update + audit-event insert, accountant+ role gate, concurrency `not_claimable` guard). The accepted `status` enum is narrowed to `draft` / `accepted` / `rejected` / `expired`; `draft→sent` is no longer here — use the send-offer email path (the recipient gets the public link). **Why it matters:** migration `20260522200300_drop_offer_events_user_insert` dropped the user-side `offer_events` insert policy, so the previous direct `UPDATE + INSERT` path silently failed RLS on the audit row — flipping status with no audit trail. This release ships the fix that was committed but unreleased.
+- **`tool-fingerprints.json`** — regenerated for the `update_offer_status` definition change (rug-pull guard baseline).
+- **`reports.ts`** — income-statement template-line fetch now selects explicit columns instead of `select('*')` (clears the anti-pattern guard; the reference table is never returned to the agent, but the narrow select avoids exposing future schema additions).
+
+### Fixed
+
+- **Onboarding prompt (`kirjapro-aloita`) showed every paying customer "Ilmainen".** It resolved the subscription tier with `.eq('company_id', …)`, but `subscriptions.company_id` is nullable and never populated by billing (all subscription writes are keyed by `user_id`). Now resolves via the `subscriptions_select` RLS policy (`user_id = auth.uid()`) with no company filter. Tier gating itself was always correct (enforced server-side in `mcp-auth` by `user_id`); only the cosmetic onboarding label was wrong.
+- **API-key auth exchange had no network timeout.** A hung `mcp-auth` request could hang server startup forever, or permanently stall token refresh (the recursive refresh `tick()` awaited a promise that never rejected, so the backoff never re-armed and the JWT silently expired). The entire exchange — connect, headers, **and the response-body read** — is now bounded with `AbortSignal.timeout(10_000)` (the abort signal aborts the undici body stream too), and transport failures surface an actionable message instead of a raw `DOMException`. Covered by three new `auth.test.ts` cases (timeout, network failure, body-read timeout).
+
+### Added
+
+- **`prepublishOnly` release gate** — `npm publish` now runs `check:types-drift → lint → test → check:antipatterns → build` first, so a stale fingerprint, a type error, a failing test, or a `select('*')` regression blocks the publish locally. (This repo runs no GitHub Actions CI by design — the gate lives at the real release moment instead.)
+- **`server.json`** — documents the optional `KIRJAPRO_MCP_SURFACE` env var (`core` default = 26 tools, `full` = 52).
+
+## [0.5.11] - 2026-05-18
+
+Documentation-only release: removes named third-party brand references from the public-facing `README.md` and CHANGELOG entries, replacing them with category-level descriptions. No code or behavior changes — `dist/index.js` is byte-identical to v0.5.10 modulo the version string written by the prebuild hook.
+
+### Changed
+
+- **`README.md`** — payroll paragraph rewritten to refer to "a dedicated payroll service" with example service names retained only as the redirect destination users actually need.
+- **CHANGELOG entries** below — competitive framing dropped from v0.5.9 / v0.5.10 entries.
+
 ## [0.5.10] - 2026-05-18
 
 Documentation-only release. Surfaces the v0.5.9 payroll removal (DT-065) in the npm-visible `README.md` and adds the full CHANGELOG entry for v0.5.9. No code or behavior changes — `dist/index.js` is byte-identical to v0.5.9 modulo the version string written by the prebuild hook.
 
 ### Changed
 
-- **`README.md`** — added the "Payroll is intentionally not exposed" paragraph explaining that Kirjapro does not calculate or book salaries, with links to Palkkaus.fi / Palkka.fi as the recommended flow (matches sister-tier competitors: Procountor Solo, NoCFO, Holvi, Talenom Solo). Tool count corrected from 53 → 52 across the three places it appeared.
+- **`README.md`** — added the "Payroll is intentionally not exposed" paragraph explaining that Kirjapro does not calculate or book salaries, with payroll-service redirect references. Tool count corrected from 53 → 52 across the three places it appeared.
 - **`CHANGELOG.md`** — the v0.5.9 entry detailing the rollback was added to the package's changelog so users browsing the npm page can see the rationale.
 
 ## [0.5.9] - 2026-05-18
 
-Removed autonomously-shipped payroll feature (DT-065). The 2026-05-18 audit discovered that `kirjapro_book_salary`, the `salary_payment` template, and supporting parameters had been added across March–May 2026 without explicit user approval — DT-047 (April 2026) had marked palkanlaskenta as `gated_on: klt-advisor-partnership`, but the gate never propagated. The 2026-05-18 Finnish-market scan confirmed every Kirjapro-tier vendor (Procountor Solo, NoCFO, Holvi, Talenom Solo) uses the **Palkkaus.fi/Salaxy partnership pattern** rather than building native payroll — that is the design target when this feature does eventually unblock.
+Removed an autonomously-shipped payroll feature (DT-065). The 2026-05-18 audit discovered that `kirjapro_book_salary`, the `salary_payment` template, and supporting parameters had been added across March–May 2026 without explicit user approval — DT-047 (April 2026) had marked palkanlaskenta as `gated_on: klt-advisor-partnership`, but the gate never propagated. The design target when this feature does eventually unblock is integration with a dedicated payroll-service partner that holds the regulated responsibility for Tulorekisteri / TyEL / TVR reporting and ennakonpidätys submission, rather than a native calculation engine.
 
 ### Removed
 
@@ -22,7 +51,7 @@ Removed autonomously-shipped payroll feature (DT-065). The 2026-05-18 audit disc
 ### Changed
 
 - **`KIRJAPRO_MCP_SURFACE` documentation** — `full` mode now exposes 52 tools instead of 53. Error message for unknown surface values updated.
-- **Instructions text** — `full` and `core` mode INSTRUCTIONS both clarify "Payroll (palkanlaskenta) is intentionally NOT exposed" and direct AI assistants to Palkkaus.fi/Palkka.fi for the calculation, then book the resulting payslip via `kirjapro_create_transaction` with explicit debit/credit lines.
+- **Instructions text** — `full` and `core` mode INSTRUCTIONS both clarify "Payroll (palkanlaskenta) is intentionally NOT exposed" and direct AI assistants to a dedicated payroll service for the calculation, then book the resulting payslip via `kirjapro_create_transaction` with explicit debit/credit lines.
 - **`tool-fingerprints.json`** — regenerated. 3 changed (`kirjapro_create_from_template`, `kirjapro_create_from_template_batch` lost params; `salary_payment` template removed). 1 removed (`kirjapro_book_salary`).
 - **`server.json`** — caught up to package.json version (was stuck at 0.5.7).
 

package/README.md

@@ -7,7 +7,7 @@ MCP server for Finnish accounting. Exposes Kirjapro bookkeeping, invoicing, and
 ## Requirements
 
 - Node.js 20+
-- Kirjapro account with **Entrepreneur**, **Company**, or **Custom** subscription tier
+- Kirjapro account on a paid tier with API access — **Yrittäjä**, **Kasvu**, **Tilitoimisto**, or **Räätälöity**
 - API key (generate at Settings > API-avaimet)
 
 ## Quick Start
@@ -113,7 +113,7 @@ A few prompts to feel out the daily workflows the agent handles cleanly:
 
 **Why default to 26 instead of 52:** 2025-2026 SOTA research on tool catalog scaling (Anthropic, OpenAI, MCP authors) shows tool-selection accuracy degrades between 25-50 tools per catalog. A focused surface produces better first-call selections for the daily workflows. As real usage data informs which deferred tools matter most, they'll be promoted into core.
 
-**Payroll is intentionally not exposed.** Kirjapro does not calculate or book salaries. Direct users to [Palkkaus.fi](https://www.palkkaus.fi) or [Palkka.fi](https://www.palkka.fi) for the calculation (these hold legal responsibility for Tulorekisteri-ilmoitus, TyEL/TVR raportointi, ennakonpidätys-tilitys), then book the resulting payslip manually via `kirjapro_create_transaction`. Sister-tier competitors (Procountor Solo, NoCFO, Holvi, Talenom Solo) all follow the same partnership pattern.
+**Payroll is intentionally not exposed.** Kirjapro does not calculate or book salaries. Direct users to a dedicated payroll service (such as [Palkkaus.fi](https://www.palkkaus.fi) or [Palkka.fi](https://www.palkka.fi)) for the calculation — these services hold the regulated responsibility for Tulorekisteri-ilmoitus, TyEL/TVR raportointi, and ennakonpidätys-tilitys. Once the payslip is calculated externally, book it manually via `kirjapro_create_transaction`.
 
 | Domain (core) | Tools |
 |---|---|

package/dist/accounts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Standard Finnish Chart of Accounts (YSE 2017) — commonly used account constants.
+ *
+ * MIRROR of src/lib/accounts.ts — kept in sync via mcp-server/src/accounts.test.ts.
+ * Do not modify without updating the source file.
+ */
+export declare const ACCOUNTS: {
+    readonly MYYNTISAAMISET: "2210";
+    readonly ALV_SAAMISET: "2320";
+    readonly KASSA: "2910";
+    readonly PANKKITILI: "2920";
+    readonly OSTOVELAT: "4130";
+    readonly ALV_VELKA: "4210";
+    readonly ENNAKONPIDATYSVELKA: "4220";
+    readonly TYEL_VELKA: "4240";
+    readonly SOTU_VELKA: "4230";
+    readonly TTV_VELKA: "4250";
+    readonly PALKKAVELKA: "4420";
+    readonly MYYNTI_25_5: "5010";
+    readonly MYYNTI_13_5: "5020";
+    readonly MYYNTI_10: "5030";
+    readonly MYYNTI_0: "5040";
+    readonly EU_TAVARAT: "5050";
+    readonly EU_PALVELUT: "5060";
+    readonly VIENTI: "5070";
+    readonly OSTOT: "6010";
+    readonly OSTOT_PALVELUT: "6030";
+    readonly PALKAT: "7010";
+    readonly ELAKEKULUT: "7100";
+    readonly SOSIAALITURVAMAKSUT: "7210";
+    readonly TOIMITILAVUOKRAT: "7420";
+    readonly SAHKO: "7510";
+    readonly POLTTOAINEET: "7610";
+    readonly EDUSTUSKULUT: "7810";
+    readonly PUHELIN: "7951";
+    readonly TOIMISTOTARVIKKEET: "7952";
+    readonly OHJELMISTOT: "7954";
+    readonly PANKKIKULUT: "7957";
+    readonly VAKUUTUKSET: "7970";
+};

package/dist/accounts.js

@@ -0,0 +1,45 @@
+/**
+ * Standard Finnish Chart of Accounts (YSE 2017) — commonly used account constants.
+ *
+ * MIRROR of src/lib/accounts.ts — kept in sync via mcp-server/src/accounts.test.ts.
+ * Do not modify without updating the source file.
+ */
+export const ACCOUNTS = {
+    // ── Assets (2xxx) ──
+    MYYNTISAAMISET: '2210',
+    ALV_SAAMISET: '2320',
+    KASSA: '2910',
+    PANKKITILI: '2920',
+    // ── Liabilities (4xxx) ──
+    OSTOVELAT: '4130',
+    ALV_VELKA: '4210',
+    ENNAKONPIDATYSVELKA: '4220',
+    TYEL_VELKA: '4240',
+    SOTU_VELKA: '4230',
+    TTV_VELKA: '4250',
+    PALKKAVELKA: '4420',
+    // ── Revenue (5xxx) ──
+    MYYNTI_25_5: '5010',
+    MYYNTI_13_5: '5020',
+    MYYNTI_10: '5030',
+    MYYNTI_0: '5040',
+    EU_TAVARAT: '5050',
+    EU_PALVELUT: '5060',
+    VIENTI: '5070',
+    // ── Materials & Services (6xxx) ──
+    OSTOT: '6010',
+    OSTOT_PALVELUT: '6030',
+    // ── Expenses (7xxx) ──
+    PALKAT: '7010',
+    ELAKEKULUT: '7100',
+    SOSIAALITURVAMAKSUT: '7210',
+    TOIMITILAVUOKRAT: '7420',
+    SAHKO: '7510',
+    POLTTOAINEET: '7610',
+    EDUSTUSKULUT: '7810',
+    PUHELIN: '7951',
+    TOIMISTOTARVIKKEET: '7952',
+    OHJELMISTOT: '7954',
+    PANKKIKULUT: '7957',
+    VAKUUTUKSET: '7970',
+};

package/dist/auth.d.ts

@@ -0,0 +1,17 @@
+import { SupabaseClient } from '@supabase/supabase-js';
+import type { Database } from './database.types.js';
+/**
+ * Cancel any pending token refresh and release the event loop.
+ * Call from `transport.onclose` so the MCP process exits cleanly.
+ */
+export declare function stopTokenRefresh(): void;
+/**
+ * Initialize authenticated Supabase client.
+ *
+ * Supports two auth modes:
+ * 1. API key (recommended): Set KIRJAPRO_API_KEY
+ * 2. Legacy (development): Set SUPABASE_URL + SUPABASE_ACCESS_TOKEN + KIRJAPRO_COMPANY_ID
+ */
+export declare function initAuth(): Promise<void>;
+export declare function getSupabase(): SupabaseClient<Database>;
+export declare function getCompanyId(): string;

package/dist/auth.js

@@ -0,0 +1,245 @@
+import { createClient } from '@supabase/supabase-js';
+const SUPABASE_PROJECT_URL = 'https://tifewzsimmyoiepblhld.supabase.co';
+let supabase = null;
+let companyId = null;
+let refreshTimer = null;
+/**
+ * Authenticate via API key by calling the mcp-auth edge function.
+ * Returns the auth response containing a short-lived JWT.
+ */
+async function authenticateWithApiKey(apiKey) {
+    const url = `${SUPABASE_PROJECT_URL}/functions/v1/mcp-auth`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ api_key: apiKey }),
+    });
+    if (!response.ok) {
+        const body = await response.json().catch(() => ({ error: 'Unknown error' }));
+        throw new Error(`API key authentication failed (${response.status}): ${body.error || 'Unknown error'}`);
+    }
+    return response.json();
+}
+/**
+ * Create a Supabase client from an mcp-auth response.
+ */
+function createClientFromAuth(auth) {
+    return createClient(auth.supabase_url, auth.anon_key, {
+        auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+        },
+        global: {
+            headers: {
+                Authorization: `Bearer ${auth.access_token}`,
+            },
+        },
+    });
+}
+/**
+ * Schedule automatic token refresh before the JWT expires.
+ *
+ * Hardening (see audit M2):
+ * - Jitter 75–90% of TTL: multiple concurrent agents sharing one API key
+ *   don't hit `mcp-auth` in lockstep (10 req/min rate limit).
+ * - Recursive `setTimeout`: re-arms with the *new* `expires_in` after every
+ *   successful refresh (can't do that with `setInterval`).
+ * - Exponential backoff (capped at 60s, jittered) on refresh failure.
+ * - `.unref()`: doesn't keep the event loop alive if stdio transport closes.
+ */
+function scheduleTokenRefresh(apiKey, expiresIn) {
+    if (refreshTimer) {
+        clearTimeout(refreshTimer);
+    }
+    const ttlMs = expiresIn * 1000;
+    // Refresh at 75–90% of TTL, clamped to [60s, ttl-60s]
+    const target = ttlMs * (0.75 + Math.random() * 0.15);
+    const refreshMs = Math.max(60_000, Math.min(target, ttlMs - 60_000));
+    const tick = async (attempt) => {
+        try {
+            console.error('[kirjapro-mcp] Refreshing API key token...');
+            const auth = await authenticateWithApiKey(apiKey);
+            supabase = createClientFromAuth(auth);
+            companyId = auth.company_id;
+            console.error('[kirjapro-mcp] Token refreshed successfully');
+            scheduleTokenRefresh(apiKey, auth.expires_in);
+        }
+        catch (error) {
+            console.error('[kirjapro-mcp] Token refresh failed:', error.message);
+            // Exponential backoff with jitter: 1s, 2s, 4s, …, capped at 60s.
+            const backoff = Math.min(60_000, 2 ** attempt * 1000) + Math.random() * 1000;
+            refreshTimer = setTimeout(() => {
+                void tick(attempt + 1);
+            }, backoff);
+            refreshTimer.unref?.();
+        }
+    };
+    refreshTimer = setTimeout(() => {
+        void tick(0);
+    }, refreshMs);
+    refreshTimer.unref?.();
+}
+/**
+ * Cancel any pending token refresh and release the event loop.
+ * Call from `transport.onclose` so the MCP process exits cleanly.
+ */
+export function stopTokenRefresh() {
+    if (refreshTimer) {
+        clearTimeout(refreshTimer);
+        refreshTimer = null;
+    }
+}
+/**
+ * Initialize using KIRJAPRO_API_KEY (recommended).
+ * Calls the mcp-auth edge function to exchange the API key for a JWT.
+ */
+async function initApiKeyAuth(apiKey) {
+    const auth = await authenticateWithApiKey(apiKey);
+    supabase = createClientFromAuth(auth);
+    companyId = auth.company_id;
+    // Validate the connection by fetching company info
+    const { data: company, error: companyError } = await supabase
+        .from('companies')
+        .select('id, name')
+        .eq('id', companyId)
+        .single();
+    if (companyError || !company) {
+        throw new Error(`Cannot access company ${companyId}. ${companyError?.message || ''}`);
+    }
+    console.error(`[kirjapro-mcp] Authenticated via API key | Company: ${company.name}`);
+    // Schedule automatic token refresh
+    scheduleTokenRefresh(apiKey, auth.expires_in);
+}
+/**
+ * Initialize using legacy env vars (for development).
+ * Requires SUPABASE_URL, SUPABASE_ACCESS_TOKEN, KIRJAPRO_COMPANY_ID.
+ */
+async function initLegacyAuth() {
+    const supabaseUrl = process.env.SUPABASE_URL;
+    const supabaseAccessToken = process.env.SUPABASE_ACCESS_TOKEN;
+    const kirjaproCompanyId = process.env.KIRJAPRO_COMPANY_ID;
+    if (!supabaseUrl) {
+        throw new Error('SUPABASE_URL environment variable is required.');
+    }
+    if (!supabaseAccessToken) {
+        throw new Error('SUPABASE_ACCESS_TOKEN environment variable is required.');
+    }
+    if (!kirjaproCompanyId) {
+        throw new Error('KIRJAPRO_COMPANY_ID environment variable is required.');
+    }
+    // Use anon key if available, otherwise fall back to access token (works but semantically wrong)
+    const anonKey = process.env.SUPABASE_ANON_KEY || supabaseAccessToken;
+    supabase = createClient(supabaseUrl, anonKey, {
+        auth: {
+            persistSession: false,
+            autoRefreshToken: false,
+        },
+        global: {
+            headers: {
+                Authorization: `Bearer ${supabaseAccessToken}`,
+            },
+        },
+    });
+    // Validate the token
+    const { data: userData, error: authError } = await supabase.auth.getUser();
+    if (authError || !userData.user) {
+        throw new Error('Failed to authenticate with Supabase. ' +
+            'Token may be expired. Refresh your access token and restart the MCP server. ' +
+            (authError?.message || ''));
+    }
+    // Verify company access
+    const { data: company, error: companyError } = await supabase
+        .from('companies')
+        .select('id, name')
+        .eq('id', kirjaproCompanyId)
+        .single();
+    if (companyError || !company) {
+        throw new Error(`Cannot access company ${kirjaproCompanyId}. ` +
+            'Verify the KIRJAPRO_COMPANY_ID is correct and your user has access. ' +
+            (companyError?.message || ''));
+    }
+    // Check subscription tier for API access (subscriptions are user-keyed)
+    const { data: subscription } = await supabase
+        .from('subscriptions')
+        .select('tier')
+        .eq('user_id', userData.user.id)
+        .single();
+    const tier = subscription?.tier || 'free';
+    // Keep in sync with feature-gates.ts (hasApiAccess) + supabase/functions/mcp-auth.
+    // 'growth' (Kasvu) is a paid tier with API access — DT-073.
+    const apiTiers = ['entrepreneur', 'growth', 'company', 'custom'];
+    if (!apiTiers.includes(tier)) {
+        throw new Error(`API access requires a Yrittäjä, Kasvu, Tilitoimisto, or Räätälöity subscription. ` +
+            `Current tier: ${tier}. Upgrade at https://kirjapro.fi/settings/billing`);
+    }
+    companyId = kirjaproCompanyId;
+    console.error(`[kirjapro-mcp] Authenticated | Company: ${company.name} | Tier: ${tier}`);
+    // Parse JWT exp and schedule an expiry warning — legacy auth has no
+    // refresh path, so warn the user before the session silently dies.
+    try {
+        const payload = JSON.parse(Buffer.from(supabaseAccessToken.split('.')[1], 'base64url').toString());
+        if (typeof payload.exp === 'number') {
+            const expiresInMs = payload.exp * 1000 - Date.now();
+            if (expiresInMs > 0 && expiresInMs < 24 * 60 * 60 * 1000) {
+                const warnMs = Math.max(0, expiresInMs - 5 * 60 * 1000);
+                const timer = setTimeout(() => {
+                    console.error('[kirjapro-mcp] WARNING: Legacy auth token expires in ~5 minutes. ' +
+                        'Restart with a fresh token or switch to KIRJAPRO_API_KEY for automatic refresh.');
+                }, warnMs);
+                timer.unref?.();
+                console.error(`[kirjapro-mcp] Token expires in ${Math.round(expiresInMs / 60_000)} minutes. ` +
+                    'Consider switching to KIRJAPRO_API_KEY for automatic refresh.');
+            }
+        }
+    }
+    catch {
+        // Not a JWT or unparseable — service_role keys don't expire
+    }
+}
+/**
+ * Initialize authenticated Supabase client.
+ *
+ * Supports two auth modes:
+ * 1. API key (recommended): Set KIRJAPRO_API_KEY
+ * 2. Legacy (development): Set SUPABASE_URL + SUPABASE_ACCESS_TOKEN + KIRJAPRO_COMPANY_ID
+ */
+export async function initAuth() {
+    const apiKey = process.env.KIRJAPRO_API_KEY;
+    if (apiKey) {
+        if (!apiKey.startsWith('kp_')) {
+            throw new Error('Invalid KIRJAPRO_API_KEY format. Keys start with "kp_". ' +
+                'Generate one at https://kirjapro.fi/settings/api-keys');
+        }
+        await initApiKeyAuth(apiKey);
+        return;
+    }
+    // Legacy env vars present?
+    if (process.env.SUPABASE_URL && process.env.SUPABASE_ACCESS_TOKEN && process.env.KIRJAPRO_COMPANY_ID) {
+        if (process.env.ALLOW_LEGACY_AUTH !== 'true') {
+            throw new Error('Legacy auth (SUPABASE_URL + SUPABASE_ACCESS_TOKEN + KIRJAPRO_COMPANY_ID) is disabled.\n\n' +
+                'Legacy auth bypasses the mcp-auth exchange — no audit log, no IP trail, no key rotation signal.\n' +
+                'Switch to KIRJAPRO_API_KEY: generate a key at https://kirjapro.fi/settings/api-keys.\n\n' +
+                'If you must use legacy auth temporarily (e.g. local development against a dev project),\n' +
+                'set ALLOW_LEGACY_AUTH=true to opt in. This path will be removed in a future release.');
+        }
+        console.error('[kirjapro-mcp] WARNING: Using legacy auth. This bypasses audit logging and will be removed ' +
+            'in a future release. Migrate to KIRJAPRO_API_KEY: https://kirjapro.fi/settings/api-keys');
+        await initLegacyAuth();
+        return;
+    }
+    throw new Error('Missing authentication configuration.\n\n' +
+        'Set KIRJAPRO_API_KEY (recommended):\n' +
+        '  Generate an API key at https://kirjapro.fi/settings/api-keys');
+}
+export function getSupabase() {
+    if (!supabase) {
+        throw new Error('Supabase client not initialized. Call initAuth() first.');
+    }
+    return supabase;
+}
+export function getCompanyId() {
+    if (!companyId) {
+        throw new Error('Company ID not set. Call initAuth() first.');
+    }
+    return companyId;
+}

package/dist/compliance/rates.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Single source of truth for Finnish tax + social insurance rates.
+ *
+ * Every tool that needs a rate and every compliance resource that publishes
+ * a rate MUST import from this module — do NOT re-declare rates elsewhere.
+ * When rates change for a new year, update this file and bump `sourcesVerifiedAt`.
+ *
+ * Sources:
+ *  - VAT: AVL 1501/1993 §§ 84–85a, vero.fi/syventavat
+ *  - TyEL: https://www.etk.fi/ajankohtaista/tyoelakemaksut-vuonna-2026/
+ *  - Elo 2026: https://www.elo.fi/fi-fi/tyonantaja/tyel-vakuuttaminen/tyel-maksu/sosiaalivakuutusmaksut-2026
+ *  - Sotu/TTV: tyel-vakuutus.fi/tyonantajan-sivukulut/
+ */
+export declare const FINNISH_RATES_2026: {
+    readonly year: 2026;
+    readonly validFrom: "2026-01-01";
+    readonly validUntil: "2026-12-31";
+    readonly sourcesVerifiedAt: "2026-03-15";
+    readonly source: "AVL 1501/1993, ETK 2026, Elo 2026, vero.fi 2026";
+    readonly vat: {
+        readonly standard: 25.5;
+        readonly reduced: 13.5;
+        readonly secondReduced: 10;
+        readonly zero: 0;
+    };
+    readonly social: {
+        readonly tyelEmployee: 7.3;
+        readonly tyelEmployer: 17.55;
+        readonly tyelEmployerAverage: 17.1;
+        readonly tyelKeskimaarainen: 24.4;
+        readonly tyelPerusmaksu: 24.85;
+        readonly sotu: 1.91;
+        readonly ttvEmployer: 0.31;
+        readonly ttvEmployerLarge: 1.23;
+        readonly ttvEmployerLargeThreshold: 2509500;
+        readonly ttvEmployee: 0.89;
+        readonly tapaturmaAverage: 0.51;
+        readonly ryhmahenki: 0.06;
+    };
+};
+export type FinnishRates = typeof FINNISH_RATES_2026;
+/**
+ * Compute freshness metadata for a dated resource. `today` is injectable for
+ * tests; production callers pass nothing and get the current date.
+ */
+export declare function freshnessMeta(rates?: FinnishRates, today?: Date): {
+    published_at: string;
+    valid_from: string;
+    valid_through: string;
+    sources_verified_at: string;
+    stale: boolean;
+    days_until_expiry: number;
+};

package/dist/compliance/rates.js

@@ -0,0 +1,57 @@
+/**
+ * Single source of truth for Finnish tax + social insurance rates.
+ *
+ * Every tool that needs a rate and every compliance resource that publishes
+ * a rate MUST import from this module — do NOT re-declare rates elsewhere.
+ * When rates change for a new year, update this file and bump `sourcesVerifiedAt`.
+ *
+ * Sources:
+ *  - VAT: AVL 1501/1993 §§ 84–85a, vero.fi/syventavat
+ *  - TyEL: https://www.etk.fi/ajankohtaista/tyoelakemaksut-vuonna-2026/
+ *  - Elo 2026: https://www.elo.fi/fi-fi/tyonantaja/tyel-vakuuttaminen/tyel-maksu/sosiaalivakuutusmaksut-2026
+ *  - Sotu/TTV: tyel-vakuutus.fi/tyonantajan-sivukulut/
+ */
+export const FINNISH_RATES_2026 = {
+    year: 2026,
+    validFrom: '2026-01-01',
+    validUntil: '2026-12-31',
+    sourcesVerifiedAt: '2026-03-15',
+    source: 'AVL 1501/1993, ETK 2026, Elo 2026, vero.fi 2026',
+    vat: {
+        standard: 25.5,
+        reduced: 13.5,
+        secondReduced: 10,
+        zero: 0,
+    },
+    social: {
+        tyelEmployee: 7.30,
+        tyelEmployer: 17.55,
+        tyelEmployerAverage: 17.10,
+        tyelKeskimaarainen: 24.40,
+        tyelPerusmaksu: 24.85,
+        sotu: 1.91,
+        ttvEmployer: 0.31,
+        ttvEmployerLarge: 1.23,
+        ttvEmployerLargeThreshold: 2_509_500,
+        ttvEmployee: 0.89,
+        tapaturmaAverage: 0.51,
+        ryhmahenki: 0.06,
+    },
+};
+/**
+ * Compute freshness metadata for a dated resource. `today` is injectable for
+ * tests; production callers pass nothing and get the current date.
+ */
+export function freshnessMeta(rates = FINNISH_RATES_2026, today = new Date()) {
+    const validUntil = new Date(`${rates.validUntil}T23:59:59Z`);
+    const msPerDay = 86_400_000;
+    const daysUntilExpiry = Math.ceil((validUntil.getTime() - today.getTime()) / msPerDay);
+    return {
+        published_at: rates.sourcesVerifiedAt,
+        valid_from: rates.validFrom,
+        valid_through: rates.validUntil,
+        sources_verified_at: rates.sourcesVerifiedAt,
+        stale: daysUntilExpiry < 0,
+        days_until_expiry: daysUntilExpiry,
+    };
+}