@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/workflows/daily-operational-brief.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Daily Operational Brief workflow ("¿Qué debería revisar hoy en mi negocio y por qué?").
+ *
+ * Grounded strictly in read-only Frihet workspace tools:
+ * - get_business_context
+ * - list_invoices
+ * - list_quotes
+ * - list_expenses
+ * - list_clients
+ * - list_client_activities
+ *
+ * Enforces:
+ * 1. Explicit temporal scope (`unfiltered_operational_sample_as_of_date` vs `currentMonthActivity`)
+ *    and per-resource coverage (inspected vs total records).
+ * 2. Strict separation between draft documents (non-issued) and real/issued activity.
+ * 3. Explicit amount provenance (`stored_field`, `derived_from_items`, `business_context_summary`,
+ *    `unavailable`, or `mixed_currency_unconverted`).
+ *    - Absent/corrupt amounts NEVER coerce to 0 (`amount: null`, `provenance: "unavailable"`).
+ *    - Multi-currency totals NEVER sum across currencies without conversion (`totalsByCurrency`, `currency: "MIXED"`).
+ *    - Derived line-item totals apply canonical per-line `discount`, document `discountRate`,
+ *      `taxRate`, `equivalenceSurchargeRate`, and `irpfRate` over the discounted tax-exclusive base.
+ * 4. Honest unpaid invoice semantics: full nominal totals of unpaid invoices are labeled
+ *    "importe nominal de facturas no marcadas como pagadas; saldo pendiente real no determinable
+ *    sin desglose de cobros parciales ni conciliación bancaria" (`realOutstandingBalanceDeterminable: false`).
+ * 5. Record-backed prioritized review items and suggested next actions without auto-executing writes.
+ * 6. Explicit declaration of what cannot be determined ("knownUnknowns").
+ */
+import type { IFrihetClient } from "../client-interface.js";
+export type AmountProvenanceKind = "stored_field" | "derived_from_items" | "business_context_summary" | "unavailable" | "mixed_currency_unconverted";
+export interface CurrencyBucketAmount {
+    amount: number;
+    currency: string;
+    provenance: "stored_field" | "derived_from_items";
+    documentCount: number;
+}
+export interface ProvenancedAmount {
+    amount: number | null;
+    currency: string;
+    provenance: AmountProvenanceKind;
+    fieldOrFormula: string;
+    totalsByCurrency?: Record<string, CurrencyBucketAmount>;
+    unavailableCount?: number;
+}
+export interface ResourceCoverage {
+    collection: "invoices" | "quotes" | "expenses" | "clients" | "client_activities";
+    sourceTool: string;
+    inspected: number;
+    total: number;
+    complete: boolean;
+}
+export interface BriefCoverageSummary {
+    asOfDate: string;
+    periodMonth: string;
+    referenceMonth: string;
+    temporalScope: "unfiltered_operational_sample_as_of_date";
+    temporalScopeNote: string;
+    isPartial: boolean;
+    resources: Record<"invoices" | "quotes" | "expenses" | "clients" | "client_activities", ResourceCoverage>;
+}
+export interface BriefDocumentSummary {
+    id: string;
+    documentNumber: string | null;
+    status: string;
+    counterpartyName: string;
+    issueDate: string | null;
+    dueDate: string | null;
+    amount: ProvenancedAmount;
+}
+export interface BriefPriorityItem {
+    priority: "high" | "medium" | "low";
+    category: "overdue_invoice" | "draft_invoice" | "draft_or_expiring_quote" | "expense_review" | "client_followup" | "plan_quota";
+    title: string;
+    why: string;
+    recordRefs: Array<{
+        type: "invoice" | "quote" | "expense" | "client" | "client_activity" | "plan_quota";
+        id: string;
+        label: string;
+    }>;
+    amount?: ProvenancedAmount;
+    suggestedNextAction: {
+        description: string;
+        recommendedTool: string;
+        requiresConfirmation: boolean;
+        autoExecuted: false;
+    };
+}
+export interface DailyOperationalBrief {
+    question: string;
+    coverage: BriefCoverageSummary;
+    activitySeparation: {
+        draftActivity: {
+            note: string;
+            invoiceDraftsCount: number;
+            invoiceDraftsTotal: ProvenancedAmount;
+            invoiceDrafts: BriefDocumentSummary[];
+            quoteDraftsCount: number;
+            quoteDraftsTotal: ProvenancedAmount;
+            quoteDrafts: BriefDocumentSummary[];
+        };
+        issuedActivity: {
+            note: string;
+            realOutstandingBalanceDeterminable: false;
+            unpaidNominalSemantics: "nominal_unpaid_invoice_totals_without_partial_payments";
+            issuedInvoicesCount: number;
+            issuedInvoicesByStatus: Record<string, number>;
+            issuedInvoicesTotal: ProvenancedAmount;
+            issuedInvoices: BriefDocumentSummary[];
+            paidInvoicesCount: number;
+            paidInvoicesTotal: ProvenancedAmount;
+            paidInvoices: BriefDocumentSummary[];
+            unpaidNominalInvoicesCount: number;
+            unpaidNominalTotal: ProvenancedAmount;
+            unpaidNominalTotalsByCurrency: Record<string, CurrencyBucketAmount>;
+            overdueNominalInvoicesCount: number;
+            overdueNominalTotal: ProvenancedAmount;
+            onTimeNominalPendingCount: number;
+            onTimeNominalPendingTotal: ProvenancedAmount;
+            outstandingInvoicesCount: number;
+            outstandingInvoicesTotal: ProvenancedAmount;
+            overdueInvoicesCount: number;
+            overdueInvoicesTotal: ProvenancedAmount;
+            onTimePendingCount: number;
+            onTimePendingTotal: ProvenancedAmount;
+            outstandingInvoices: BriefDocumentSummary[];
+        };
+        recordedExpenses: {
+            note: string;
+            expensesCount: number;
+            expensesTotal: ProvenancedAmount;
+            deductibleCount: number;
+            deductibleTotal: ProvenancedAmount;
+            nonDeductibleCount: number;
+            nonDeductibleTotal: ProvenancedAmount;
+            pendingReviewCount: number;
+        };
+        currentMonthActivity: {
+            referenceMonth: string;
+            note: string;
+            issuedInvoicesInMonthCount: number;
+            issuedInvoicesInMonthTotal: ProvenancedAmount;
+            invoiceDraftsInMonthCount: number;
+            invoiceDraftsInMonthTotal: ProvenancedAmount;
+            expensesInMonthCount: number;
+            expensesInMonthTotal: ProvenancedAmount;
+        };
+    };
+    priorities: BriefPriorityItem[];
+    knownUnknowns: string[];
+    mutationsExecuted: 0;
+    markdown: string;
+}
+export interface GenerateDailyBriefOptions {
+    asOfDate?: string;
+    pageLimit?: number;
+    maxActivityClients?: number;
+}
+export declare function formatProvenancedAmount(p: ProvenancedAmount): string;
+export declare function resolveDocumentAmount(doc: Record<string, unknown>, defaultCurrency?: string): ProvenancedAmount;
+export declare function sumProvenancedAmounts(amounts: ProvenancedAmount[], defaultCurrency?: string): ProvenancedAmount;
+export declare function generateDailyOperationalBrief(client: Pick<IFrihetClient, "getBusinessContext" | "listInvoices" | "listQuotes" | "listExpenses" | "listClients" | "listClientActivities">, options?: GenerateDailyBriefOptions): Promise<DailyOperationalBrief>;
+export declare function buildScenario1CompleteWorkspaceClient(callLog: string[]): Pick<IFrihetClient, "getBusinessContext" | "listInvoices" | "listQuotes" | "listExpenses" | "listClients" | "listClientActivities">;
+export declare function buildScenario2PartialCoverageClient(callLog: string[]): Pick<IFrihetClient, "getBusinessContext" | "listInvoices" | "listQuotes" | "listExpenses" | "listClients" | "listClientActivities">;
+//# sourceMappingURL=daily-operational-brief.d.ts.map