@tpmjs/official-tax-deduction-scan 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 TPMJS
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+import * as ai from 'ai';
+
+/**
+ * Tax Deduction Scan Tool for TPMJS
+ * Scans expense data for potential tax deductions by category
+ */
+/**
+ * Expense record
+ */
+interface Expense {
+    description: string;
+    amount: number;
+    category: string;
+    date?: string;
+    vendor?: string;
+}
+/**
+ * Entity type for tax treatment
+ */
+type EntityType = 'sole-proprietor' | 'partnership' | 'llc' | 's-corp' | 'c-corp' | 'individual';
+/**
+ * Deduction category with rules
+ */
+interface DeductionCategory {
+    category: string;
+    totalAmount: number;
+    deductibleAmount: number;
+    deductionRate: number;
+    items: Array<{
+        description: string;
+        amount: number;
+        deductible: number;
+    }>;
+    notes: string[];
+    documentationRequired: string[];
+}
+/**
+ * Input interface for tax deduction scan
+ */
+interface TaxDeductionScanInput {
+    expenses: Expense[];
+    entityType: EntityType;
+    taxYear?: number;
+}
+/**
+ * Output interface for tax deduction scan
+ */
+interface TaxDeductionScanResult {
+    deductions: DeductionCategory[];
+    summary: {
+        totalExpenses: number;
+        totalDeductible: number;
+        totalNonDeductible: number;
+        deductionRate: number;
+        topDeductionCategory: string;
+        topDeductionAmount: number;
+        flaggedForReview: string[];
+    };
+}
+/**
+ * Tax Deduction Scan Tool
+ * Scans expenses and identifies potential tax deductions
+ */
+declare const taxDeductionScanTool: ai.Tool<TaxDeductionScanInput, TaxDeductionScanResult>;
+
+export { type TaxDeductionScanResult, taxDeductionScanTool as default, taxDeductionScanTool };

package/dist/index.js

@@ -0,0 +1,261 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var DEDUCTION_RULES = {
+  "office-supplies": {
+    rate: 1,
+    notes: ["Fully deductible if used exclusively for business"],
+    documentation: ["Receipts", "Purchase records"]
+  },
+  "home-office": {
+    rate: 1,
+    notes: ["Must be used exclusively and regularly for business"],
+    documentation: ["Square footage calculation", "Utility bills", "Mortgage/rent statements"],
+    entitySpecific: {
+      individual: {
+        rate: 1,
+        notes: [
+          "Simplified option: $5 per square foot up to 300 sq ft",
+          "Regular method: Percentage of home expenses"
+        ]
+      }
+    }
+  },
+  travel: {
+    rate: 1,
+    notes: ["Must be ordinary and necessary for business"],
+    documentation: ["Travel receipts", "Business purpose documentation", "Itinerary"]
+  },
+  meals: {
+    rate: 0.5,
+    notes: ["Generally 50% deductible", "100% deductible for company events (all employees)"],
+    documentation: ["Receipts", "Business purpose", "Attendees list"]
+  },
+  entertainment: {
+    rate: 0,
+    notes: ["Entertainment expenses are generally NOT deductible (post-TCJA)"],
+    documentation: ["N/A - Not deductible"]
+  },
+  vehicle: {
+    rate: 1,
+    notes: [
+      "Standard mileage rate or actual expenses",
+      "2024 rate: $0.67/mile (business use)",
+      "Keep detailed mileage log"
+    ],
+    documentation: ["Mileage log", "Vehicle registration", "Fuel receipts if using actual method"]
+  },
+  "professional-development": {
+    rate: 1,
+    notes: ["Training, courses, and conferences related to current business"],
+    documentation: ["Course receipts", "Conference registration", "Business relevance"]
+  },
+  software: {
+    rate: 1,
+    notes: ["Business software subscriptions fully deductible"],
+    documentation: ["Subscription receipts", "Software licenses"]
+  },
+  advertising: {
+    rate: 1,
+    notes: ["Marketing and advertising expenses fully deductible"],
+    documentation: ["Ad receipts", "Marketing invoices", "Campaign records"]
+  },
+  "professional-fees": {
+    rate: 1,
+    notes: ["Legal, accounting, consulting fees for business"],
+    documentation: ["Professional service invoices", "Engagement letters"]
+  },
+  insurance: {
+    rate: 1,
+    notes: ["Business insurance premiums deductible"],
+    documentation: ["Insurance policies", "Premium statements"],
+    entitySpecific: {
+      "sole-proprietor": {
+        rate: 1,
+        notes: ["Health insurance may be deductible as self-employed health insurance"]
+      }
+    }
+  },
+  utilities: {
+    rate: 1,
+    notes: ["Business portion of utilities deductible"],
+    documentation: ["Utility bills", "Business use percentage calculation"]
+  },
+  rent: {
+    rate: 1,
+    notes: ["Business space rent fully deductible"],
+    documentation: ["Lease agreement", "Rent receipts"]
+  },
+  "phone-internet": {
+    rate: 1,
+    notes: ["Business portion deductible", "Personal use must be excluded"],
+    documentation: ["Phone/internet bills", "Business use percentage"]
+  },
+  depreciation: {
+    rate: 1,
+    notes: ["Equipment and property depreciation", "Section 179 may allow immediate expensing"],
+    documentation: ["Asset purchase records", "Depreciation schedule"]
+  },
+  "charitable-contributions": {
+    rate: 0,
+    notes: ["Personal charitable contributions - itemized deduction, not business expense"],
+    documentation: ["Donation receipts"],
+    entitySpecific: {
+      "c-corp": {
+        rate: 1,
+        notes: ["C-corps can deduct charitable contributions as business expense"]
+      }
+    }
+  },
+  other: {
+    rate: 0.5,
+    notes: ["Review with tax professional", "May be partially deductible"],
+    documentation: ["Receipts", "Business purpose documentation"]
+  }
+};
+var taxDeductionScanTool = tool({
+  description: "Scans expense data for potential tax deductions by category. Applies category-specific deduction rules and identifies documentation requirements.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      expenses: {
+        type: "array",
+        description: "Expense records to scan",
+        items: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "Expense description"
+            },
+            amount: {
+              type: "number",
+              description: "Expense amount"
+            },
+            category: {
+              type: "string",
+              description: "Expense category (e.g., office-supplies, travel, meals, vehicle, software)"
+            },
+            date: {
+              type: "string",
+              description: "Expense date (ISO format)"
+            },
+            vendor: {
+              type: "string",
+              description: "Vendor name"
+            }
+          },
+          required: ["description", "amount", "category"]
+        }
+      },
+      entityType: {
+        type: "string",
+        enum: ["sole-proprietor", "partnership", "llc", "s-corp", "c-corp", "individual"],
+        description: "Business entity type for tax treatment"
+      },
+      taxYear: {
+        type: "number",
+        description: "Tax year (default: current year)"
+      }
+    },
+    required: ["expenses", "entityType"],
+    additionalProperties: false
+  }),
+  execute: async ({ expenses, entityType }) => {
+    if (!Array.isArray(expenses) || expenses.length === 0) {
+      throw new Error("Expenses must be a non-empty array");
+    }
+    const validEntityTypes = [
+      "sole-proprietor",
+      "partnership",
+      "llc",
+      "s-corp",
+      "c-corp",
+      "individual"
+    ];
+    if (!validEntityTypes.includes(entityType)) {
+      throw new Error(
+        `Invalid entity type: ${entityType}. Must be one of: ${validEntityTypes.join(", ")}`
+      );
+    }
+    const categoryMap = /* @__PURE__ */ new Map();
+    let totalExpenses = 0;
+    for (const expense of expenses) {
+      if (!expense.category || typeof expense.amount !== "number" || expense.amount < 0) {
+        throw new Error("Each expense must have a category and non-negative amount");
+      }
+      const normalizedCategory = expense.category.toLowerCase().trim();
+      if (!categoryMap.has(normalizedCategory)) {
+        categoryMap.set(normalizedCategory, []);
+      }
+      categoryMap.get(normalizedCategory).push(expense);
+      totalExpenses += expense.amount;
+    }
+    const deductions = [];
+    let totalDeductible = 0;
+    const flaggedForReview = [];
+    for (const [category, categoryExpenses] of categoryMap.entries()) {
+      const rules = DEDUCTION_RULES[category] || DEDUCTION_RULES["other"];
+      let deductionRate = rules.rate;
+      let notes = [...rules.notes];
+      if (rules.entitySpecific?.[entityType]) {
+        const entityRules = rules.entitySpecific[entityType];
+        deductionRate = entityRules.rate;
+        if (entityRules.notes) {
+          notes = [...entityRules.notes, ...notes];
+        }
+      }
+      const categoryTotal = categoryExpenses.reduce((sum, exp) => sum + exp.amount, 0);
+      const deductibleAmount = categoryTotal * deductionRate;
+      const items = categoryExpenses.map((exp) => ({
+        description: exp.description,
+        amount: exp.amount,
+        deductible: Math.round(exp.amount * deductionRate * 100) / 100
+      }));
+      if (deductionRate === 0 && categoryTotal > 0) {
+        flaggedForReview.push(
+          `${category}: $${categoryTotal.toFixed(2)} - Not deductible, review classification`
+        );
+      }
+      if (category === "meals" && categoryTotal > 1e4) {
+        flaggedForReview.push(
+          `${category}: High meal expenses - Ensure proper business documentation`
+        );
+      }
+      if (category === "other" && categoryTotal > 5e3) {
+        flaggedForReview.push(
+          `${category}: Significant uncategorized expenses - Review with tax professional`
+        );
+      }
+      deductions.push({
+        category,
+        totalAmount: Math.round(categoryTotal * 100) / 100,
+        deductibleAmount: Math.round(deductibleAmount * 100) / 100,
+        deductionRate,
+        items,
+        notes,
+        documentationRequired: rules.documentation
+      });
+      totalDeductible += deductibleAmount;
+    }
+    deductions.sort((a, b) => b.deductibleAmount - a.deductibleAmount);
+    const topDeduction = deductions[0];
+    const totalNonDeductible = totalExpenses - totalDeductible;
+    const overallDeductionRate = totalExpenses > 0 ? totalDeductible / totalExpenses * 100 : 0;
+    return {
+      deductions,
+      summary: {
+        totalExpenses: Math.round(totalExpenses * 100) / 100,
+        totalDeductible: Math.round(totalDeductible * 100) / 100,
+        totalNonDeductible: Math.round(totalNonDeductible * 100) / 100,
+        deductionRate: Math.round(overallDeductionRate * 100) / 100,
+        topDeductionCategory: topDeduction?.category || "N/A",
+        topDeductionAmount: topDeduction?.deductibleAmount || 0,
+        flaggedForReview
+      }
+    };
+  }
+});
+var index_default = taxDeductionScanTool;
+
+export { index_default as default, taxDeductionScanTool };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@tpmjs/official-tax-deduction-scan",
+  "version": "0.1.0",
+  "description": "Scans expense data for potential tax deductions by category",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "finance",
+    "tax",
+    "deductions",
+    "expenses"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3",
+    "@tpmjs/tsconfig": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/tpmjs.git",
+    "directory": "packages/tools/official/tax-deduction-scan"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "finance",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "taxDeductionScanTool",
+        "description": "Scans expense data for potential tax deductions by category",
+        "parameters": [
+          {
+            "name": "expenses",
+            "type": "array",
+            "description": "Expense records to scan for deductions",
+            "required": true
+          },
+          {
+            "name": "entityType",
+            "type": "string",
+            "description": "Business entity type for tax treatment",
+            "required": true
+          },
+          {
+            "name": "taxYear",
+            "type": "number",
+            "description": "Tax year",
+            "required": false
+          }
+        ],
+        "returns": {
+          "type": "TaxDeductionScanResult",
+          "description": "Deduction analysis with documentation requirements and flags"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}