@frihet/mcp-server 2.0.1 → 2.0.2

package/README.md

@@ -19,7 +19,7 @@
   <a href="https://www.npmjs.com/package/@frihet/mcp-server"><img src="https://img.shields.io/npm/v/@frihet/mcp-server?style=flat&color=18181b&labelColor=09090b" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/@frihet/mcp-server"><img src="https://img.shields.io/npm/dm/@frihet/mcp-server?style=flat&color=18181b&labelColor=09090b&label=downloads" alt="npm downloads"></a>
   <a href="https://registry.modelcontextprotocol.io/?q=io.frihet"><img src="https://img.shields.io/badge/MCP_Registry-io.frihet%2Ferp-4A90D9?style=flat&logo=anthropic&logoColor=white" alt="MCP Registry"></a>
-  <img src="https://img.shields.io/badge/catalogue-156_operations-18181b?style=flat&labelColor=09090b" alt="156 canonical catalogue operations">
+  <img src="https://img.shields.io/badge/catalogue-158_operations-18181b?style=flat&labelColor=09090b" alt="158 canonical catalogue operations">
   <a href="https://github.com/Frihet-io/frihet-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-18181b?style=flat&labelColor=09090b" alt="license"></a>
 </p>
 
@@ -38,7 +38,7 @@ You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/h
 Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.
 ```
 
-156 canonical operations. Five fiscal aliases. Ten prompts. The local package serves 11 resources; the hosted Worker deliberately serves the 7 static resources, while API-backed workspace resources remain local-profile only.
+158 canonical operations. Five fiscal aliases. Ten prompts. The local package serves 11 resources; the hosted Worker deliberately serves the 7 static resources, while API-backed workspace resources remain local-profile only.
 
 ---
 
@@ -77,7 +77,7 @@ Local installs need Node 22.23.4+, 24.22.1+ or 26.12.1+. Other clients are cover
 
 Also listed on [Glama](https://glama.ai/mcp/servers/Frihet-io/frihet-mcp), [Cursor Directory](https://cursor.directory/plugins/mcp-frihet), [mcp.so](https://mcp.so/servers/frihet-mcp), [mcpservers.org](https://mcpservers.org/servers/frihet-io/frihet-mcp) and the [ToolSDK registry](https://github.com/toolsdk-ai/toolsdk-mcp-registry/blob/main/packages/finance-fintech/frihet-mcp.json).
 
-> **Surface truth:** the catalogue contains 156 canonical operations. The local full profile serves 161 tool names, 11 resources, and 10 prompts (156 canonical operations plus 5 fiscal aliases). The hosted grouped profile serves 164 tool names, 7 resources, and 10 prompts (the same names plus 3 discovery tools, with API-backed resources kept local-only). The separately reviewed OpenAI profile serves 33 tool names, 0 resources, and 0 prompts. These counts describe the current source release; the hosted server reports the version it is running at `/health`. Catalogue membership is not a promise that a backing API is enabled for every workspace.
+> **Surface truth:** the catalogue contains 158 canonical operations. The local full profile serves 163 tool names, 11 resources, and 10 prompts (158 canonical operations plus 5 fiscal aliases). The hosted grouped profile serves 166 tool names, 7 resources, and 10 prompts (the same names plus 3 discovery tools, with API-backed resources kept local-only). The separately reviewed OpenAI profile serves 33 tool names, 0 resources, and 0 prompts. These counts describe the current source release; the hosted server reports the version it is running at `/health`. Catalogue membership is not a promise that a backing API is enabled for every workspace.
 
 ---
 
@@ -197,7 +197,7 @@ If you are an agent reading this repository, the contract is machine-readable an
 
 ## What to expect
 
-This MCP is a **structured data interface** -- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. Most of the 156 canonical operations are CRUD operations over the REST API; the rest are read-only summaries and fiscal/e-invoice actions. Alias and discovery names are counted separately.
+This MCP is a **structured data interface** -- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. Most of the 158 canonical operations are CRUD operations over the REST API; the rest are read-only summaries and fiscal/e-invoice actions. Alias and discovery names are counted separately.
 
 It does not do OCR, PDF scanning, file upload or image processing. To digitize a paper invoice, extract the data first (a vision model, an OCR service, or manual entry), then ask the assistant to create the record. One API key maps to one Frihet workspace, and you need a Frihet account at [app.frihet.io](https://app.frihet.io).
 
@@ -206,7 +206,7 @@ It does not do OCR, PDF scanning, file upload or image processing. To digitize a
 ## Full catalogue
 
 <details>
-<summary><strong>All 156 canonical operations, resources and prompts</strong></summary>
+<summary><strong>All 158 canonical operations, resources and prompts</strong></summary>
 
 ### Invoices (12)
 
@@ -629,7 +629,7 @@ Test with the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspect
 
 | Package | What it is |
 |---------|-----------|
-| [`@frihet/mcp-server`](https://www.npmjs.com/package/@frihet/mcp-server) | This MCP server (156 canonical operations + 5 alias names; 11 local resources; 10 prompts) |
+| [`@frihet/mcp-server`](https://www.npmjs.com/package/@frihet/mcp-server) | This MCP server (158 canonical operations + 5 alias names; 11 local resources; 10 prompts) |
 | [`@frihet/sdk`](https://github.com/Frihet-io/frihet-sdk) | TypeScript SDK (`frihet.invoices.create()`) |
 | [`frihet`](https://www.npmjs.com/package/frihet) | CLI (`frihet invoices list --status overdue`) |
 | [`n8n-nodes-frihet`](https://www.npmjs.com/package/n8n-nodes-frihet) | n8n community node for workflow automation |

package/dist/canary/mcp-harness.d.ts

@@ -15,7 +15,7 @@
  */
 export declare const HARNESS_CONTRACT_VERSION = 1;
 export declare const INSPECTOR_PINNED_VERSION = "2.3.0";
-export declare const CANONICAL_OPERATIONS_COUNT = 156;
+export declare const CANONICAL_OPERATIONS_COUNT = 158;
 export declare const FISCAL_ALIASES_COUNT: number;
 export type CheckStatus = "PASS" | "FAIL" | "UNSUPPORTED" | "NOT_EXERCISED";
 export type OverallStatus = "PASS" | "PASS_WITH_GAPS" | "FAIL";

package/dist/canary/mcp-harness.js

@@ -24,8 +24,9 @@ export const HARNESS_CONTRACT_VERSION = 1;
 export const INSPECTOR_PINNED_VERSION = "2.3.0";
 // Updated 2026-10-10 by issue #124 (IGIC-pattern withdraw of dead onboarding_status /
 // onboarding_persona_set — the Frihet-ERP /v1/onboarding/* family is absent, so the
-// MCP catalogue now declares 156 canonical operations, down from 158).
-export const CANONICAL_OPERATIONS_COUNT = 156;
+// MCP catalogue then declared 156 canonical operations, down from 158; the two read-only
+// purchase-order tools (ADR 0027 S2) bring it to 158).
+export const CANONICAL_OPERATIONS_COUNT = 158;
 export const FISCAL_ALIASES_COUNT = Object.keys(FISCAL_MODELO_ALIASES).length;
 /**
  * Executes the complete compatibility harness in-process and returns

package/dist/claude-profile.js

@@ -170,7 +170,9 @@ export const CLAUDE_EXCLUDED_TOOLS = {
     "period_reopen": "The handler deliberately defers execution; capability truth marks this deferred.",
     "refund_sale": "Executes an actual Stripe money transfer; excluded under Directory policy section 4.A.",
     "send_quote": "Previewed recipient is not atomically bound and delivery is not retry-safe.",
-    "sync_channel": "The handler deliberately defers execution; capability truth marks this deferred."
+    "sync_channel": "The handler deliberately defers execution; capability truth marks this deferred.",
+    "get_purchase_order": "Added after the 176de12 Claude operational candidate freeze; not yet admitted to the Claude profile.",
+    "list_purchase_orders": "Added after the 176de12 Claude operational candidate freeze; not yet admitted to the Claude profile."
 };
 export const CLAUDE_CANDIDATE_RESOURCES = new Set([
     "frihet://config/currencies",

package/dist/client-interface.d.ts

@@ -101,6 +101,13 @@ export interface IFrihetClient {
     createVendor(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateVendor(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
     deleteVendor(id: string): Promise<void>;
+    listPurchaseOrders(params?: {
+        status?: string;
+        vendorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<Record<string, unknown>>>;
+    getPurchaseOrder(id: string): Promise<Record<string, unknown>>;
     sendInvoice(id: string, to?: string): Promise<Record<string, unknown>>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
     getInvoicePdf(id: string): Promise<import("./client.js").BinaryDocument>;

package/dist/client.d.ts

@@ -275,6 +275,13 @@ export declare class FrihetClient {
     createVendor(data: Record<string, unknown>): Promise<Record<string, unknown>>;
     updateVendor(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
     deleteVendor(id: string): Promise<void>;
+    listPurchaseOrders(params?: {
+        status?: string;
+        vendorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<Record<string, unknown>>>;
+    getPurchaseOrder(id: string): Promise<Record<string, unknown>>;
     sendInvoice(id: string, to?: string): Promise<Record<string, unknown>>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Record<string, unknown>>;
     getInvoicePdf(id: string): Promise<BinaryDocument>;

package/dist/client.js

@@ -850,6 +850,22 @@ export class FrihetClient {
     async deleteVendor(id) {
         return this.request("DELETE", `/vendors/${pathSegment(id)}`);
     }
+    // ---------------------------------------------------------------- Purchase Orders
+    // ----------------------------------------------------------------
+    // ADR 0027 S2, server-owned lifecycle. Routes are read-only here; the
+    // write surface (create draft, send, confirm, cancel, receive,
+    // reverse-receipt, bill) is deliberately not exposed by the MCP server.
+    async listPurchaseOrders(params) {
+        return this.requestPaginated("GET", "/purchase-orders", undefined, {
+            status: params?.status,
+            vendorId: params?.vendorId,
+            limit: params?.limit,
+            offset: params?.offset,
+        });
+    }
+    async getPurchaseOrder(id) {
+        return this.requestUnwrapped("GET", `/purchase-orders/${pathSegment(id)}`);
+    }
     // ---------------------------------------------------------------- Invoice Actions
     // ----------------------------------------------------------------
     async sendInvoice(id, to) {

package/dist/demo-client.d.ts

@@ -3,12 +3,12 @@
  *
  * A drop-in IFrihetClient that makes ZERO network calls: it serves the canned
  * PII-safe fixtures in demo-fixtures.ts. index.ts swaps this in for FrihetClient
- * when demo mode is on, so tools (which stringify the client's return value)
- * automatically propagate the `_demo`/`_demoNotice` banner without any change
- * under src/tools/.
+ * when demo mode is on. Single-record fixtures carry their own demo stamps;
+ * server-composition.ts stamps paginated MCP results after profile projection
+ * and declares those fields only on demo schemas, preserving live contracts.
  *
  * Response contract (see SPEC-mcp-demo-mode.md option B/C):
- *   - reads/lists → fixture data stamped `_demo:true` (READ notice).
+ *   - reads/lists → MCP fixture data stamped `_demo:true` (READ notice).
  *   - lists without fixtures → EMPTY PaginatedResponse, still stamped.
  *   - writes → plausible fixture-shaped object with a `demo_`-prefixed id
  *     (WRITE notice "…Simulated — not persisted.").
@@ -23,10 +23,7 @@ import { type BinaryDocument, type EInvoiceDocument, type EInvoiceExportResult,
 type Rec = Record<string, unknown>;
 export declare class DemoFrihetClient implements IFrihetClient {
     readonly isDemoClient: true;
-    listInvoices(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
+    listInvoices(params?: Parameters<IFrihetClient["listInvoices"]>[0]): Promise<PaginatedResponse<Rec>>;
     getInvoice(id: string): Promise<Rec>;
     createInvoice(data: Rec): Promise<Rec>;
     updateInvoice(id: string, data: Rec): Promise<Rec>;
@@ -35,10 +32,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         limit?: number;
         offset?: number;
     }): Promise<PaginatedResponse<Rec>>;
-    listExpenses(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
+    listExpenses(params?: Parameters<IFrihetClient["listExpenses"]>[0]): Promise<PaginatedResponse<Rec>>;
     getExpense(id: string): Promise<Rec>;
     createExpense(data: Rec): Promise<Rec>;
     updateExpense(id: string, data: Rec): Promise<Rec>;
@@ -75,6 +69,13 @@ export declare class DemoFrihetClient implements IFrihetClient {
     createVendor(data: Rec): Promise<Rec>;
     updateVendor(id: string, data: Rec): Promise<Rec>;
     deleteVendor(_id: string): Promise<void>;
+    listPurchaseOrders(params?: {
+        status?: string;
+        vendorId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<PaginatedResponse<Rec>>;
+    getPurchaseOrder(id: string): Promise<Rec>;
     sendInvoice(id: string, to?: string): Promise<Rec>;
     markInvoicePaid(id: string, paidDate?: string): Promise<Rec>;
     getInvoicePdf(id: string): Promise<BinaryDocument>;
@@ -271,10 +272,7 @@ export declare class DemoFrihetClient implements IFrihetClient {
         offset?: number;
     }): Promise<PaginatedResponse<Rec>>;
     getBankAccount(id: string): Promise<Rec>;
-    listTransactions(params?: {
-        limit?: number;
-        offset?: number;
-    }): Promise<PaginatedResponse<Rec>>;
+    listTransactions(params?: Parameters<IFrihetClient["listTransactions"]>[0]): Promise<PaginatedResponse<Rec>>;
     categorizeTransaction(id: string, data: {
         category: string;
         notes?: string;

package/dist/demo-client.js

@@ -3,12 +3,12 @@
  *
  * A drop-in IFrihetClient that makes ZERO network calls: it serves the canned
  * PII-safe fixtures in demo-fixtures.ts. index.ts swaps this in for FrihetClient
- * when demo mode is on, so tools (which stringify the client's return value)
- * automatically propagate the `_demo`/`_demoNotice` banner without any change
- * under src/tools/.
+ * when demo mode is on. Single-record fixtures carry their own demo stamps;
+ * server-composition.ts stamps paginated MCP results after profile projection
+ * and declares those fields only on demo schemas, preserving live contracts.
  *
  * Response contract (see SPEC-mcp-demo-mode.md option B/C):
- *   - reads/lists → fixture data stamped `_demo:true` (READ notice).
+ *   - reads/lists → MCP fixture data stamped `_demo:true` (READ notice).
  *   - lists without fixtures → EMPTY PaginatedResponse, still stamped.
  *   - writes → plausible fixture-shaped object with a `demo_`-prefixed id
  *     (WRITE notice "…Simulated — not persisted.").
@@ -19,7 +19,7 @@
  */
 import { toApiEInvoiceExportFormat, } from "./client.js";
 import { Buffer } from "node:buffer";
-import { READ_STAMP, FISCAL_STAMP, DEMO_NOW, demoPage, demoEmptyPage, findOrStub, demoId, simulateWrite, simulateAction, demoClients, demoProducts, demoInvoices, demoExpenses, demoQuotes, demoVendors, demoBankAccounts, demoTransactions, } from "./demo-fixtures.js";
+import { READ_STAMP, FISCAL_STAMP, DEMO_NOW, demoPage, demoEmptyPage, findOrStub, demoId, simulateWrite, simulateAction, demoClients, demoMoney, demoSum, demoTopClients, demoProducts, demoInvoices, demoExpenses, demoQuotes, demoVendors, demoPurchaseOrders, demoBankAccounts, demoTransactions, } from "./demo-fixtures.js";
 const DEMO_RBAC_ROLES = ["owner", "admin", "manager", "sales", "accountant", "employee", "viewer"];
 const DEMO_RBAC_RESOURCES = [
     "workspace", "invoices", "quotes", "expenses", "clients", "products", "accounting",
@@ -78,7 +78,12 @@ export class DemoFrihetClient {
     isDemoClient = true;
     // ---------------------------------------------------------------- Invoices
     async listInvoices(params) {
-        return demoPage(demoInvoices, params);
+        const filtered = demoInvoices.filter((row) => (!params?.from || (typeof row.issueDate === "string" && row.issueDate >= params.from))
+            && (!params?.to || (typeof row.issueDate === "string" && row.issueDate <= params.to))
+            && (!params?.status || row.status === params.status)
+            && (!params?.clientId || row.clientId === params.clientId)
+            && (!params?.seriesId || row.seriesId === params.seriesId));
+        return demoPage(filtered, params, ["issueDate", "documentNumber", "id"]);
     }
     async getInvoice(id) {
         return findOrStub(demoInvoices, id);
@@ -109,7 +114,11 @@ export class DemoFrihetClient {
     }
     // ---------------------------------------------------------------- Expenses
     async listExpenses(params) {
-        return demoPage(demoExpenses, params);
+        const filtered = demoExpenses.filter((row) => (!params?.from || (typeof row.date === "string" && row.date >= params.from))
+            && (!params?.to || (typeof row.date === "string" && row.date <= params.to))
+            && (!params?.vendorId || row.vendorId === params.vendorId)
+            && (!params?.category || row.category === params.category));
+        return demoPage(filtered, params, ["date", "id"]);
     }
     async getExpense(id) {
         return findOrStub(demoExpenses, id);
@@ -187,6 +196,21 @@ export class DemoFrihetClient {
     async deleteVendor(_id) {
         return;
     }
+    // ---------------------------------------------------------------- Purchase Orders
+    // Read-only surface (ADR 0027 S2). Write tools are intentionally absent.
+    async listPurchaseOrders(params) {
+        const filtered = demoPurchaseOrders.filter((po) => {
+            if (params?.status && po.status !== params.status)
+                return false;
+            if (params?.vendorId && po.vendorId !== params.vendorId)
+                return false;
+            return true;
+        });
+        return demoPage(filtered, params);
+    }
+    async getPurchaseOrder(id) {
+        return findOrStub(demoPurchaseOrders, id);
+    }
     // ---------------------------------------------------------------- Invoice actions
     async sendInvoice(id, to) {
         // Email dispatch — simulated, no email is actually sent.
@@ -371,6 +395,17 @@ export class DemoFrihetClient {
     }
     // ---------------------------------------------------------------- Intelligence
     async getBusinessContext() {
+        const month = DEMO_NOW.slice(0, 7);
+        const today = DEMO_NOW.slice(0, 10);
+        const monthInvoices = demoInvoices.filter((invoice) => String(invoice.issueDate).startsWith(month));
+        const monthExpenses = demoExpenses.filter((expense) => String(expense.date).startsWith(month));
+        // Fixture invoices have no partial payments: paid means settled; drafts are not receivables.
+        const unpaid = demoInvoices.filter((invoice) => invoice.status === "sent" || invoice.status === "overdue");
+        const overdue = unpaid.filter((invoice) => String(invoice.dueDate) < today);
+        const lastInvoice = [...demoInvoices].sort((a, b) => String(b.issueDate).localeCompare(String(a.issueDate)))[0];
+        const lastExpense = [...demoExpenses].sort((a, b) => String(b.date).localeCompare(String(a.date)))[0];
+        const revenue = demoSum(monthInvoices.filter((invoice) => invoice.status !== "draft" && invoice.status !== "cancelled"), "total");
+        const expenses = demoSum(monthExpenses, "amount");
         return {
             business: {
                 name: "Demo Studio SL",
@@ -382,39 +417,70 @@ export class DemoFrihetClient {
             defaults: { taxRate: 21, irpfRate: 15, dueDays: 30, currency: "EUR" },
             plan: {
                 name: "free",
-                invoices: { used: 5, limit: 999 },
-                expenses: { used: demoExpenses.length, limit: 5 },
+                invoices: { used: monthInvoices.length, limit: 999 },
+                expenses: { used: monthExpenses.length, limit: 5 },
                 aiMessages: { used: 2, limit: 30 },
             },
-            series: [{ id: "default", prefix: "F", current: 5, year: 2026 }],
+            series: [{ id: "default", prefix: "F", current: demoInvoices.length, year: Number(DEMO_NOW.slice(0, 4)) }],
             recentActivity: {
-                lastInvoice: { number: "F-2026-005", date: "2026-07-18", client: "Acme Studio" },
-                lastExpense: { date: "2026-07-17", vendor: "Demo Supplies", amount: 405.6 },
-                overdueCount: 1,
-                overdueAmount: 640,
-                unpaidCount: 2,
+                lastInvoice: lastInvoice
+                    ? { number: lastInvoice.documentNumber, date: lastInvoice.issueDate, client: lastInvoice.clientName }
+                    : null,
+                lastExpense: lastExpense
+                    ? { date: lastExpense.date, vendor: lastExpense.vendor, amount: lastExpense.amount }
+                    : null,
+                overdueCount: overdue.length,
+                overdueAmount: demoSum(overdue, "total"),
+                unpaidCount: unpaid.length,
+                coverage: { totalAnalyzed: demoInvoices.length, sampleLimit: 500, isTruncated: false, asOf: today, currency: "EUR", excludedForeignInvoices: 0 },
             },
-            topClients: [{ name: "Acme Studio", totalRevenue: 2200, invoiceCount: 2 }],
+            topClients: demoTopClients(demoInvoices.filter((invoice) => invoice.status === "paid")),
             currentMonth: {
-                revenue: 3960.4,
-                expenses: 405.6,
-                profit: 3554.8,
-                invoiceCount: 5,
-                expenseCount: demoExpenses.length,
+                revenue,
+                expenses,
+                profit: demoMoney(revenue - expenses),
+                invoiceCount: monthInvoices.length,
+                expenseCount: monthExpenses.length,
             },
             ...READ_STAMP,
         };
     }
     async getMonthlySummary(month) {
+        const period = month ?? DEMO_NOW.slice(0, 7);
+        const invoices = demoInvoices.filter((invoice) => String(invoice.issueDate).startsWith(`${period}-`));
+        const expenses = demoExpenses.filter((expense) => String(expense.date).startsWith(`${period}-`));
+        // Match /v1/monthly: drafts count as created, but do not contribute revenue or tax.
+        const issued = invoices.filter((invoice) => invoice.status !== "draft" && invoice.status !== "cancelled");
+        const deductible = expenses.filter((expense) => expense.taxDeductible !== false);
+        const revenue = {
+            total: demoSum(issued, "total"), taxBase: demoSum(issued, "subtotal"),
+            tax: demoSum(issued, "taxAmount"), irpf: demoSum(issued, "irpfAmount"),
+        };
+        const expenseTotal = demoSum(expenses, "amount");
+        const inputTax = demoSum(deductible, "tax");
+        const byCategory = {};
+        for (const expense of expenses) {
+            const category = String(expense.category ?? "other");
+            byCategory[category] = demoMoney((byCategory[category] ?? 0) + Number(expense.amount));
+        }
+        const vatPayable = demoMoney(revenue.tax - inputTax);
         return {
-            period: month ?? "2026-07",
-            revenue: { total: 3960.4, taxBase: 3273.06, tax: 687.34, irpf: 0 },
-            expenses: { total: 405.6, deductible: 405.6, tax: 70.4 },
-            profit: { gross: 3554.8, net: 2937.86 },
-            invoices: { created: 5, sent: 1, paid: 3, overdue: 1 },
-            topClients: [{ name: "Acme Studio", totalRevenue: 2200, invoiceCount: 2 }],
-            byCategory: { supplies: 405.6 },
-            taxLiability: { vatPayable: 616.94, irpfRetained: 0, estimatedModel303: 616.94 },
+            period,
+            revenue,
+            expenses: { total: expenseTotal, deductible: demoSum(deductible, "amount"), tax: inputTax },
+            profit: {
+                gross: demoMoney(revenue.total - expenseTotal),
+                net: demoMoney(revenue.total - expenseTotal - revenue.tax + inputTax + revenue.irpf),
+            },
+            invoices: {
+                created: invoices.length,
+                sent: invoices.filter((invoice) => invoice.status === "sent" || invoice.status === "partial").length,
+                paid: invoices.filter((invoice) => invoice.status === "paid").length,
+                overdue: invoices.filter((invoice) => invoice.status === "overdue").length,
+            },
+            topClients: demoTopClients(issued),
+            byCategory,
+            taxLiability: { vatPayable, irpfRetained: revenue.irpf, estimatedModel303: vatPayable },
             ...READ_STAMP,
         };
     }
@@ -517,7 +583,12 @@ export class DemoFrihetClient {
         return findOrStub(demoBankAccounts, id);
     }
     async listTransactions(params) {
-        return demoPage(demoTransactions, params);
+        const filtered = demoTransactions.filter((row) => (!params?.from || (typeof row.postedAt === "string" && row.postedAt >= params.from))
+            && (!params?.to || (typeof row.postedAt === "string" && row.postedAt <= params.to))
+            && (!params?.accountId || row.accountId === params.accountId)
+            && (!params?.status || row.status === params.status)
+            && (!params?.category || row.category === params.category));
+        return demoPage(filtered, params, ["postedAt", "id"]);
     }
     async categorizeTransaction(id, data) {
         return simulateAction(id, { category: data.category, ...(data.notes ? { notes: data.notes } : {}) });

package/dist/demo-fixtures.d.ts

@@ -31,11 +31,11 @@ export declare const DEMO_NOW = "2026-07-15T10:00:00.000Z";
 /** Test IBAN (ECBS/AEAT example — never a real account). */
 export declare const DEMO_TEST_IBAN = "ES9121000418450200051332";
 export type DemoPaginated = PaginatedResponse<Record<string, unknown>>;
-/** Wrap a fixture array in a PaginatedResponse. */
-export declare function demoPage(data: Record<string, unknown>[], params?: {
+/** Page fixtures after filtering; opt-in string keys sort descending on a copy. */
+export declare function demoPage(data: readonly Record<string, unknown>[], params?: {
     limit?: number;
     offset?: number;
-}): DemoPaginated;
+}, descendingKeys?: readonly string[]): DemoPaginated;
 /** Empty PaginatedResponse for surfaces without dedicated fixtures. */
 export declare function demoEmptyPage(params?: {
     limit?: number;
@@ -43,15 +43,25 @@ export declare function demoEmptyPage(params?: {
 }): DemoPaginated;
 export declare const demoClients: Record<string, unknown>[];
 export declare const demoProducts: Record<string, unknown>[];
+export declare function demoMoney(n: number): number;
 export declare const demoInvoices: Record<string, unknown>[];
+/** Aggregate stored fixture amounts; never recalculate invoice taxes here. */
+export declare function demoSum(records: Record<string, unknown>[], field: string): number;
+/** Rank only the invoices selected by the caller (paid or issued in a month). */
+export declare function demoTopClients(invoices: Record<string, unknown>[]): {
+    name: string;
+    totalRevenue: number;
+    invoiceCount: number;
+}[];
 export declare const demoExpenses: Record<string, unknown>[];
 export declare const demoQuotes: Record<string, unknown>[];
 export declare const demoVendors: Record<string, unknown>[];
+export declare const demoPurchaseOrders: Record<string, unknown>[];
 export declare const demoBankAccounts: Record<string, unknown>[];
 export declare const demoTransactions: Record<string, unknown>[];
 /** Find a fixture by id, or synthesize a minimal stamped object with that id. */
 export declare function findOrStub(collection: Record<string, unknown>[], id: string): Record<string, unknown> & DemoStamp;
-/** Deterministic-ish demo id (no network, no clock dependency). */
+/** Simulated ids cannot alias read-only fixtures (no network or clock dependency). */
 export declare function demoId(prefix: string): string;
 /**
  * Simulate a create/update: echo the input, stamp a fabricated demo id +

package/dist/demo-fixtures.js

@@ -36,12 +36,21 @@ export const EMPTY_STAMP = {
 export const DEMO_NOW = "2026-07-15T10:00:00.000Z";
 /** Test IBAN (ECBS/AEAT example — never a real account). */
 export const DEMO_TEST_IBAN = "ES9121000418450200051332";
-/** Wrap a fixture array in a PaginatedResponse. */
-export function demoPage(data, params) {
+/** Page fixtures after filtering; opt-in string keys sort descending on a copy. */
+export function demoPage(data, params, descendingKeys) {
     const limit = params?.limit ?? 50;
     const offset = params?.offset ?? 0;
+    const ordered = descendingKeys?.length ? [...data].sort((a, b) => {
+        for (const key of descendingKeys) {
+            const left = String(a[key] ?? "");
+            const right = String(b[key] ?? "");
+            if (left !== right)
+                return left < right ? 1 : -1;
+        }
+        return 0;
+    }) : data;
     return {
-        data: data.slice(offset, offset + limit),
+        data: ordered.slice(offset, offset + limit),
         total: data.length,
         limit,
         offset,
@@ -124,16 +133,17 @@ export const demoProducts = [
     { id: "demo_prd_007", name: "Menú catering (por persona)", unitPrice: 18, taxRate: 10, description: "Servicio de catering, IVA reducido hostelería", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
     { id: "demo_prd_008", name: "Libro técnico impreso", unitPrice: 24, taxRate: 4, description: "Publicación impresa, IVA superreducido", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
 ];
-function money(n) {
+export function demoMoney(n) {
     return Math.round(n * 100) / 100;
 }
 function invoice(opts) {
-    const subtotal = money(opts.items.reduce((s, i) => s + i.quantity * i.unitPrice, 0));
-    const taxAmount = money(subtotal * (opts.taxRate / 100));
-    const irpfAmount = opts.irpfRate ? money(subtotal * (opts.irpfRate / 100)) : 0;
-    const total = money(subtotal + taxAmount - irpfAmount);
+    const subtotal = demoMoney(opts.items.reduce((s, i) => s + i.quantity * i.unitPrice, 0));
+    const taxAmount = demoMoney(subtotal * (opts.taxRate / 100));
+    const irpfAmount = opts.irpfRate ? demoMoney(subtotal * (opts.irpfRate / 100)) : 0;
+    const total = demoMoney(subtotal + taxAmount - irpfAmount);
     return {
         id: opts.id,
+        documentNumber: `F-${opts.issueDate.slice(0, 4)}-${opts.id.split("_").at(-1)}`,
         clientId: opts.clientId,
         clientName: opts.clientName,
         items: opts.items,
@@ -163,16 +173,29 @@ export const demoInvoices = [
     invoice({ id: "demo_inv_008", clientId: "demo_cli_003", clientName: "Servicios Insulares Canarias SL", items: [{ description: "Mantenimiento mensual", quantity: 3, unitPrice: 150 }], taxRate: 7, status: "overdue", issueDate: "2026-04-05", dueDate: "2026-05-05", notes: "IGIC 7% — factura vencida", clientLocation: "canarias" }),
     invoice({ id: "demo_inv_009", clientId: "demo_cli_004", clientName: "Marina Delgado (autónoma)", items: [{ description: "Diseño de marca", quantity: 1, unitPrice: 1200 }, { description: "Auditoría SEO", quantity: 1, unitPrice: 600 }], taxRate: 21, status: "draft", issueDate: "2026-07-08", dueDate: "2026-08-08", irpfRate: 15, notes: "Autónoma con retención IRPF 15%", clientLocation: "peninsula" }),
 ];
+/** Aggregate stored fixture amounts; never recalculate invoice taxes here. */
+export function demoSum(records, field) {
+    return demoMoney(records.reduce((sum, record) => sum + Number(record[field] ?? 0), 0));
+}
+/** Rank only the invoices selected by the caller (paid or issued in a month). */
+export function demoTopClients(invoices) {
+    return demoClients.map((client) => {
+        const matched = invoices.filter((invoice) => invoice.clientId === client.id);
+        return { name: String(client.name), totalRevenue: demoSum(matched, "total"), invoiceCount: matched.length };
+    }).filter((client) => client.invoiceCount > 0)
+        .sort((a, b) => b.totalRevenue - a.totalRevenue)
+        .slice(0, 5);
+}
 /* ------------------------------------------------------------------ */
 /*  Expenses (6) — categorized                                         */
 /* ------------------------------------------------------------------ */
 export const demoExpenses = [
-    { id: "demo_exp_001", description: "Suscripción software de diseño", amount: 15.4, category: "software", date: "2026-07-01", vendor: "Herramientas Digitales SL", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_002", description: "Material de oficina", amount: 48.2, category: "office_supplies", date: "2026-06-18", vendor: "Papelería Central", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_003", description: "Comida de trabajo con cliente", amount: 62.0, category: "meals", date: "2026-06-22", vendor: "Restaurante El Puerto", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_004", description: "Combustible desplazamiento", amount: 70.0, category: "travel", date: "2026-06-25", vendor: "Estación de Servicio Norte", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_005", description: "Cuota gestoría mensual", amount: 90.0, category: "professional_services", date: "2026-07-01", vendor: "Gestoría Ramírez", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
-    { id: "demo_exp_006", description: "Hosting anual", amount: 120.0, category: "software", date: "2026-05-30", vendor: "Proveedor Cloud SL", taxDeductible: true, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_001", description: "Suscripción software de diseño", amount: 15.4, category: "software", date: "2026-07-01", vendor: "Herramientas Digitales SL", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_002", description: "Material de oficina", amount: 48.2, category: "office_supplies", date: "2026-06-18", vendor: "Papelería Central", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_003", description: "Comida de trabajo con cliente", amount: 62.0, category: "meals", date: "2026-06-22", vendor: "Restaurante El Puerto", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_004", description: "Combustible desplazamiento", amount: 70.0, category: "travel", date: "2026-06-25", vendor: "Estación de Servicio Norte", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_005", description: "Cuota gestoría mensual", amount: 90.0, category: "professional_services", date: "2026-07-01", vendor: "Gestoría Ramírez", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
+    { id: "demo_exp_006", description: "Hosting anual", amount: 120.0, category: "software", date: "2026-05-30", vendor: "Proveedor Cloud SL", taxDeductible: true, currency: "EUR", createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
 ];
 /* ------------------------------------------------------------------ */
 /*  Quotes (2)                                                         */
@@ -218,6 +241,51 @@ export const demoVendors = [
     { id: "demo_ven_002", name: "Proveedor Cloud SL", email: "facturacion@example.com", phone: "+34 600 000 011", taxId: "B22222222", address: { city: "Barcelona", postalCode: "08007", country: "ES" }, createdAt: DEMO_NOW, updatedAt: DEMO_NOW },
 ];
 /* ------------------------------------------------------------------ */
+/*  Purchase orders (2) — ADR 0027 S2 read-only surface.              */
+/*  Same vendor ids as demoVendors so list+get read coherently.       */
+/* ------------------------------------------------------------------ */
+export const demoPurchaseOrders = [
+    {
+        id: "demo_po_001",
+        poNumber: "PO-2026-0001",
+        vendorId: "demo_ven_001",
+        vendorName: "Gestoría Ramírez",
+        status: "sent",
+        items: [
+            { description: "Asesoria contable mensual", quantity: 1, unitPrice: 350, productId: "demo_prod_001" },
+        ],
+        issueDate: "2026-09-01",
+        expectedDate: "2026-10-01",
+        taxRate: 21,
+        subtotal: 350,
+        tax: 73.5,
+        total: 423.5,
+        currency: "EUR",
+        notes: "Renovacion contrato asesoria",
+        createdAt: DEMO_NOW,
+        updatedAt: DEMO_NOW,
+    },
+    {
+        id: "demo_po_002",
+        poNumber: "PO-2026-0002",
+        vendorId: "demo_ven_002",
+        vendorName: "Proveedor Cloud SL",
+        status: "draft",
+        items: [
+            { description: "Hosting VPS 4 vCPU", quantity: 12, unitPrice: 45, productId: "demo_prod_002" },
+            { description: "Backup storage 500 GB", quantity: 1, unitPrice: 80 },
+        ],
+        issueDate: "2026-09-15",
+        taxRate: 21,
+        subtotal: 620,
+        tax: 130.2,
+        total: 750.2,
+        currency: "EUR",
+        createdAt: DEMO_NOW,
+        updatedAt: DEMO_NOW,
+    },
+];
+/* ------------------------------------------------------------------ */
 /*  Banking — 1 account + 4 transactions                              */
 /* ------------------------------------------------------------------ */
 export const demoBankAccounts = [
@@ -250,10 +318,10 @@ export function findOrStub(collection, id) {
     return { id, ...READ_STAMP };
 }
 let demoIdCounter = 0;
-/** Deterministic-ish demo id (no network, no clock dependency). */
+/** Simulated ids cannot alias read-only fixtures (no network or clock dependency). */
 export function demoId(prefix) {
     demoIdCounter += 1;
-    return `${prefix}_${String(demoIdCounter).padStart(3, "0")}`;
+    return `${prefix}_simulated_${String(demoIdCounter).padStart(3, "0")}`;
 }
 /**
  * Simulate a create/update: echo the input, stamp a fabricated demo id +