@paro.io/expert-shared-components 1.14.52 → 1.14.53

package/lib/tax-axis/lib/adapters/useEngineOutput.d.ts

@@ -0,0 +1,144 @@
+import type { Strategy, ComputedMap } from "../types";
+export interface EngineCalculationTrace {
+    strategy_id: string;
+    branch_executed: string | null;
+    formula: string;
+    inputs: Record<string, unknown>;
+    result_gross: number | null;
+    confidence_interval: {
+        low: number;
+        high: number;
+        basis: string;
+    } | null;
+    position_strength: string;
+    irs_cite: string;
+    data_quality_flag: string | null;
+    forms_required: string[];
+    deadline_flag: string | null;
+    amt_flag: boolean;
+}
+export interface EngineStrategyAnalysis {
+    strategy_id: string;
+    strategy_name: string;
+    priority_tier: "HIGH" | "MEDIUM" | "LOW" | "NOT_RECOMMENDED";
+    weighted_score: number;
+    scores: {
+        financial_impact: number;
+        applicability: number;
+        complexity: number;
+        risk: number;
+        cash_flow: number;
+    };
+    quick_win: boolean;
+    calculation_trace: EngineCalculationTrace;
+    engagement_recommendation: string;
+    risk_disclosure: string | null;
+}
+export interface EngineClientSummaryStrategy {
+    slot: number;
+    strategy_name: string;
+    savings_range: string;
+    why_it_applies: string;
+    next_step: string;
+    quick_win_badge: boolean;
+    deadline_flag?: string | null;
+}
+export interface EngineCpaWorkflow {
+    workpaper_codes: string[] | null;
+    section_6694_notices: Array<{
+        strategy_id: string;
+        position_strength: string;
+        notice: string;
+    }>;
+    prior_year_flags: string[];
+    conflict_of_interest_checklist: Array<{
+        strategy_id: string;
+        conflict_prompt: string;
+        confirmed_no_conflict: boolean;
+    }>;
+    engagement_recommendations: string[];
+}
+export interface EngineOutput {
+    engagement_id: string;
+    generated_at: string;
+    algorithm_version: string;
+    business_profile: {
+        entity_type: string;
+        industry: string;
+        industry_vertical: string;
+        states: string[];
+        data_years: number;
+        confidence_tier: string;
+        effective_tax_rate: number | null;
+        data_quality_flags: string[];
+    };
+    eligibility_screening: {
+        excluded_strategies: Array<{
+            strategy_id: string;
+            status: "EXCLUDED";
+            reason: string;
+            irs_cite: string;
+        }>;
+    };
+    strategy_analysis: EngineStrategyAnalysis[];
+    strategy_interaction_warnings: Array<{
+        strategy_pair: [string, string];
+        warning_text: string;
+    }>;
+    implementation_roadmap: {
+        quick_wins: Array<{
+            strategy_id: string;
+            action: string;
+            deadline?: string | null;
+        }>;
+        immediate: Array<{
+            strategy_id: string;
+            action: string;
+            deadline?: string | null;
+        }>;
+        thirty_day: Array<{
+            strategy_id: string;
+            action: string;
+            deadline?: string | null;
+        }>;
+        ninety_day: Array<{
+            strategy_id: string;
+            action: string;
+            deadline?: string | null;
+        }>;
+        annual: Array<{
+            strategy_id: string;
+            action: string;
+            deadline?: string | null;
+        }>;
+    };
+    cpa_workflow: EngineCpaWorkflow;
+    client_summary: {
+        opening: string;
+        strategies: EngineClientSummaryStrategy[];
+        data_quality_note: string | null;
+        interaction_warning: string | null;
+        closing: string;
+    };
+    risk_disclosures: string[];
+    client_risk_disclosures: {
+        accuracy_penalty_warning: string | null;
+        applies_to_strategies: string[];
+    };
+    amt_flags: Array<{
+        trigger: string;
+        strategy_id: string;
+        flag_text: string;
+    }>;
+    nexus_flags: Array<{
+        state: string;
+        nexus_type: string;
+        flag_text: string;
+    }>;
+}
+export interface EngineOutputAdapterResult {
+    strategies: Strategy[];
+    computedMap: ComputedMap;
+    engineOutput: EngineOutput;
+}
+export declare function useEngineOutput(engineOutput: EngineOutput | null | undefined): EngineOutputAdapterResult | null;

package/lib/tax-axis/lib/adapters/useEngineOutput.js

@@ -0,0 +1,155 @@
+"use strict";
+// ═══════════════════════════════════════════════════════════════════
+// useEngineOutput — adapts live EngineOutput from paro-graphql-api
+// into the Strategy[] + ComputedMap shapes the FE components consume.
+//
+// Strategy: use the static STRATEGIES catalog as a structural template
+// (rank, cat, entities, authority, etc.) and override savings/priority/score
+// from the live engine data. Falls back to static data when a strategy_id
+// has no match in the catalog (future-proofing for new strategies).
+// ═══════════════════════════════════════════════════════════════════
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useEngineOutput = useEngineOutput;
+const react_1 = require("react");
+const data_1 = require("../data");
+// ── Strategy ID → rank mapping (S1..S26 → rank 1..25 catalog) ───────
+// Maps engine strategy_ids like "S2", "S5" etc. to catalog ranks.
+// Built once from the static STRATEGIES array by matching code/name heuristics.
+const ENGINE_ID_TO_RANK = {
+    S1: 1, // Business Entity Structure (S-Corp election)
+    S2: 2, // Section 179
+    S3: 3, // Bonus Depreciation §168(k)
+    S4: 4, // QBI §199A
+    S5: 5, // R&D Credit §41
+    S6: 6, // WOTC §51
+    S7: 7, // Retirement Plan
+    S8: 8, // Cost Segregation
+    S9: 9, // HSA
+    S10: 10, // Business Meals
+    S11: 11, // Professional Services / Legal
+    S12: 12, // Home Office
+    S13: 13, // Health Care Credit §45R
+    S14: 14, // Charitable / DAF
+    S15: 15, // SALT PTE
+    S16: 16, // §163(j) Interest
+    S17: 17, // Income Deferral
+    S18: 18, // Opportunity Zone §1400Z
+    S19: 19, // §179D Energy
+    S20: 20, // Accounting Method
+    S21: 21, // OBBBA Overtime
+    S22: 22, // OBBBA Tips / Overtime
+    S23: 23, // §174A R&E catch-up
+    S24: 24, // Childcare §45F
+    S25: 25, // OBBBA Trump Accounts
+};
+const CATALOG_BY_RANK = new Map(data_1.STRATEGIES.map((s) => [s.rank, s]));
+// ── Priority tier mapping ─────────────────────────────────────────────
+function mapPriority(tier, quickWin) {
+    if (quickWin)
+        return "QUICK WIN";
+    if (tier === "HIGH")
+        return "HIGH";
+    if (tier === "MEDIUM")
+        return "MEDIUM";
+    if (tier === "LOW")
+        return "LOW";
+    return "NOT RECOMMENDED";
+}
+// ── Timeline bucket from implementation_roadmap ───────────────────────
+function resolveTimelineBucket(strategyId, roadmap) {
+    if (roadmap.quick_wins.some((r) => r.strategy_id === strategyId))
+        return "now";
+    if (roadmap.immediate.some((r) => r.strategy_id === strategyId))
+        return "now";
+    if (roadmap.thirty_day.some((r) => r.strategy_id === strategyId))
+        return "30d";
+    if (roadmap.ninety_day.some((r) => r.strategy_id === strategyId))
+        return "90d";
+    if (roadmap.annual.some((r) => r.strategy_id === strategyId))
+        return "filing";
+    return "filing";
+}
+// ── CalculationTrace → StrategyTraceStep[] ───────────────────────────
+function traceFromEngine(trace) {
+    const steps = [];
+    // Emit formula as step 1
+    if (trace.formula) {
+        steps.push({
+            n: 1,
+            step: "Formula",
+            formula: trace.formula,
+            result: trace.result_gross != null ? `$${trace.result_gross.toLocaleString()}` : "See CI",
+            src: trace.irs_cite || "",
+        });
+    }
+    // Emit confidence interval as step 2 when present
+    if (trace.confidence_interval) {
+        steps.push({
+            n: 2,
+            step: "Confidence range",
+            formula: `Low × ${trace.confidence_interval.basis}`,
+            result: `$${trace.confidence_interval.low.toLocaleString()} – $${trace.confidence_interval.high.toLocaleString()}`,
+            src: trace.irs_cite || "",
+        });
+    }
+    return steps;
+}
+function adaptEngineOutput(engineOutput) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
+    const strategies = [];
+    const computedMap = new Map();
+    for (const analysis of engineOutput.strategy_analysis) {
+        if (analysis.priority_tier === "NOT_RECOMMENDED")
+            continue;
+        const rank = ENGINE_ID_TO_RANK[analysis.strategy_id];
+        const template = rank != null ? CATALOG_BY_RANK.get(rank) : undefined;
+        const trace = analysis.calculation_trace;
+        const ci = trace === null || trace === void 0 ? void 0 : trace.confidence_interval;
+        const lo = (_b = (_a = ci === null || ci === void 0 ? void 0 : ci.low) !== null && _a !== void 0 ? _a : template === null || template === void 0 ? void 0 : template.lo) !== null && _b !== void 0 ? _b : 0;
+        const hi = (_d = (_c = ci === null || ci === void 0 ? void 0 : ci.high) !== null && _c !== void 0 ? _c : template === null || template === void 0 ? void 0 : template.hi) !== null && _d !== void 0 ? _d : 0;
+        const timelineBucket = resolveTimelineBucket(analysis.strategy_id, engineOutput.implementation_roadmap);
+        const strategy = {
+            rank: rank !== null && rank !== void 0 ? rank : 99,
+            code: (_e = template === null || template === void 0 ? void 0 : template.code) !== null && _e !== void 0 ? _e : analysis.strategy_id,
+            name: analysis.strategy_name,
+            cat: (_f = template === null || template === void 0 ? void 0 : template.cat) !== null && _f !== void 0 ? _f : "deductions",
+            priority: mapPriority(analysis.priority_tier, analysis.quick_win),
+            score: Math.round(analysis.weighted_score),
+            entities: (_g = template === null || template === void 0 ? void 0 : template.entities) !== null && _g !== void 0 ? _g : ["S-Corporation", "C-Corporation", "Partnership/LLC", "Sole Proprietorship"],
+            lo,
+            hi,
+            timeline: (_h = template === null || template === void 0 ? void 0 : template.timeline) !== null && _h !== void 0 ? _h : timelineBucket,
+            timelineBucket,
+            authority: (_j = trace === null || trace === void 0 ? void 0 : trace.irs_cite) !== null && _j !== void 0 ? _j : template === null || template === void 0 ? void 0 : template.authority,
+            forms: (_l = (_k = trace === null || trace === void 0 ? void 0 : trace.forms_required) === null || _k === void 0 ? void 0 : _k.join(", ")) !== null && _l !== void 0 ? _l : template === null || template === void 0 ? void 0 : template.forms,
+            warning: (_o = (_m = analysis.risk_disclosure) !== null && _m !== void 0 ? _m : template === null || template === void 0 ? void 0 : template.warning) !== null && _o !== void 0 ? _o : null,
+            abstract: analysis.engagement_recommendation,
+            trace: traceFromEngine(trace),
+            needsPTE: template === null || template === void 0 ? void 0 : template.needsPTE,
+            onlyIndustry: template === null || template === void 0 ? void 0 : template.onlyIndustry,
+            excludeIndustry: template === null || template === void 0 ? void 0 : template.excludeIndustry,
+            preferIndustry: template === null || template === void 0 ? void 0 : template.preferIndustry,
+            minEmployees: template === null || template === void 0 ? void 0 : template.minEmployees,
+            needsOwnerComp: template === null || template === void 0 ? void 0 : template.needsOwnerComp,
+            clientBrief: (_q = (_p = engineOutput.client_summary.strategies.find((cs) => cs.strategy_name === analysis.strategy_name)) === null || _p === void 0 ? void 0 : _p.why_it_applies) !== null && _q !== void 0 ? _q : template === null || template === void 0 ? void 0 : template.clientBrief,
+            action: (_s = (_r = engineOutput.client_summary.strategies.find((cs) => cs.strategy_name === analysis.strategy_name)) === null || _r === void 0 ? void 0 : _r.next_step) !== null && _s !== void 0 ? _s : template === null || template === void 0 ? void 0 : template.action,
+        };
+        strategies.push(strategy);
+        computedMap.set(strategy.rank, {
+            lo,
+            hi,
+            trace: strategy.trace,
+        });
+    }
+    // Sort by weighted_score descending (same ordering the FE uses)
+    strategies.sort((a, b) => b.score - a.score);
+    return { strategies, computedMap, engineOutput };
+}
+// ── React hook ────────────────────────────────────────────────────────
+function useEngineOutput(engineOutput) {
+    return (0, react_1.useMemo)(() => {
+        if (!engineOutput)
+            return null;
+        return adaptEngineOutput(engineOutput);
+    }, [engineOutput]);
+}

package/lib/tax-axis/lib/data/documents.d.ts

@@ -1,3 +1,4 @@
 import { DocSpec } from "../types";
 export type TaxAxisEntityTypeKey = "S_CORP" | "C_CORP" | "PARTNERSHIP" | "LLC" | "SOLE_PROP";
+export declare const DOC_SPECS_BASE: DocSpec[];
 export declare function getDocSpecs(entityType?: TaxAxisEntityTypeKey | string | null): DocSpec[];

package/lib/tax-axis/lib/data/documents.js

@@ -7,6 +7,7 @@
 // uploadTaxAxisDocument mutation.
 // ═══════════════════════════════════════════════════════════════════
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOC_SPECS_BASE = void 0;
 exports.getDocSpecs = getDocSpecs;
 const DOC_META = {
     federal_tax_return: {
@@ -217,6 +218,10 @@ function buildDocSpec(documentType) {
         help: meta.help,
     };
 }
+// All doc specs across all entity types — used for reverse-mapping strategy → document needs.
+exports.DOC_SPECS_BASE = LLC_TYPES
+    .map(buildDocSpec)
+    .filter((s) => s !== null);
 function getDocSpecs(entityType) {
     var _a;
     const types = entityType

package/lib/tax-axis/lib/documentFieldCatalog.d.ts

@@ -0,0 +1,13 @@
+export interface FieldDef {
+    label: string;
+    sourceRef?: string;
+}
+export interface SectionDef {
+    head: string;
+    fields: string[];
+}
+export interface DocFieldCatalog {
+    sections: SectionDef[];
+    fields: Record<string, FieldDef>;
+}
+export declare const DOCUMENT_FIELD_CATALOG: Record<string, DocFieldCatalog>;