@tpmjs/official-cash-flow-project 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,89 @@
+import * as ai from 'ai';
+
+/**
+ * Cash Flow Project Tool for TPMJS
+ * Projects cash flow based on receivables, payables, and recurring items
+ */
+/**
+ * Receivable item with expected payment date
+ */
+interface Receivable {
+    description: string;
+    amount: number;
+    dueDate: string;
+    probability?: number;
+}
+/**
+ * Payable item with expected payment date
+ */
+interface Payable {
+    description: string;
+    amount: number;
+    dueDate: string;
+    recurring?: boolean;
+    frequency?: 'weekly' | 'monthly' | 'quarterly' | 'annually';
+}
+/**
+ * Recurring revenue or expense item
+ */
+interface RecurringItem {
+    description: string;
+    amount: number;
+    frequency: 'weekly' | 'monthly' | 'quarterly' | 'annually';
+    type: 'income' | 'expense';
+    startDate?: string;
+    endDate?: string;
+}
+/**
+ * Cash flow projection for a specific period
+ */
+interface CashFlowPeriod {
+    period: string;
+    startingBalance: number;
+    inflows: number;
+    outflows: number;
+    netChange: number;
+    endingBalance: number;
+    inflowDetails: Array<{
+        description: string;
+        amount: number;
+    }>;
+    outflowDetails: Array<{
+        description: string;
+        amount: number;
+    }>;
+}
+/**
+ * Input interface for cash flow projection
+ */
+interface CashFlowProjectInput {
+    currentCash: number;
+    receivables: Receivable[];
+    payables: Payable[];
+    recurringItems?: RecurringItem[];
+    projectionMonths?: number;
+}
+/**
+ * Output interface for cash flow projection
+ */
+interface CashFlowProjectResult {
+    projections: CashFlowPeriod[];
+    summary: {
+        currentCash: number;
+        projectedCashAtEnd: number;
+        totalInflows: number;
+        totalOutflows: number;
+        netChange: number;
+        averageMonthlyBurn: number;
+        runwayMonths: number | null;
+        lowestBalance: number;
+        lowestBalancePeriod: string;
+    };
+}
+/**
+ * Cash Flow Project Tool
+ * Projects future cash flow based on receivables, payables, and recurring items
+ */
+declare const cashFlowProjectTool: ai.Tool<CashFlowProjectInput, CashFlowProjectResult>;
+
+export { type CashFlowProjectResult, cashFlowProjectTool, cashFlowProjectTool as default };

package/dist/index.js

@@ -0,0 +1,285 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var cashFlowProjectTool = tool({
+  description: "Projects cash flow based on receivables, payables, and recurring items. Calculates runway at current burn rate and identifies cash flow risks.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      currentCash: {
+        type: "number",
+        description: "Current cash balance"
+      },
+      receivables: {
+        type: "array",
+        description: "Expected receivables with due dates",
+        items: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "Description of receivable"
+            },
+            amount: {
+              type: "number",
+              description: "Amount expected to receive"
+            },
+            dueDate: {
+              type: "string",
+              description: "Expected payment date (ISO format)"
+            },
+            probability: {
+              type: "number",
+              description: "Probability of payment (0-1)"
+            }
+          },
+          required: ["description", "amount", "dueDate"]
+        }
+      },
+      payables: {
+        type: "array",
+        description: "Expected payables with due dates",
+        items: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "Description of payable"
+            },
+            amount: {
+              type: "number",
+              description: "Amount to pay"
+            },
+            dueDate: {
+              type: "string",
+              description: "Payment due date (ISO format)"
+            },
+            recurring: {
+              type: "boolean",
+              description: "Whether this is a recurring payment"
+            },
+            frequency: {
+              type: "string",
+              enum: ["weekly", "monthly", "quarterly", "annually"],
+              description: "Frequency if recurring"
+            }
+          },
+          required: ["description", "amount", "dueDate"]
+        }
+      },
+      recurringItems: {
+        type: "array",
+        description: "Recurring revenue or expenses",
+        items: {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "Description of recurring item"
+            },
+            amount: {
+              type: "number",
+              description: "Amount per period"
+            },
+            frequency: {
+              type: "string",
+              enum: ["weekly", "monthly", "quarterly", "annually"],
+              description: "Frequency of recurrence"
+            },
+            type: {
+              type: "string",
+              enum: ["income", "expense"],
+              description: "Whether this is income or expense"
+            },
+            startDate: {
+              type: "string",
+              description: "Start date (ISO format)"
+            },
+            endDate: {
+              type: "string",
+              description: "End date (ISO format)"
+            }
+          },
+          required: ["description", "amount", "frequency", "type"]
+        }
+      },
+      projectionMonths: {
+        type: "number",
+        description: "Number of months to project (default: 12)"
+      }
+    },
+    required: ["currentCash", "receivables", "payables"],
+    additionalProperties: false
+  }),
+  execute: async ({
+    currentCash,
+    receivables,
+    payables,
+    recurringItems = [],
+    projectionMonths = 12
+  }) => {
+    if (typeof currentCash !== "number" || currentCash < 0) {
+      throw new Error("Current cash must be a non-negative number");
+    }
+    if (!Array.isArray(receivables)) {
+      throw new Error("Receivables must be an array");
+    }
+    if (!Array.isArray(payables)) {
+      throw new Error("Payables must be an array");
+    }
+    if (projectionMonths < 1 || projectionMonths > 60) {
+      throw new Error("Projection months must be between 1 and 60");
+    }
+    const projections = [];
+    const now = /* @__PURE__ */ new Date();
+    let runningBalance = currentCash;
+    let totalInflows = 0;
+    let totalOutflows = 0;
+    let lowestBalance = currentCash;
+    let lowestBalancePeriod = formatMonth(now);
+    for (let i = 0; i < projectionMonths; i++) {
+      const periodStart = new Date(now.getFullYear(), now.getMonth() + i, 1);
+      const periodEnd = new Date(now.getFullYear(), now.getMonth() + i + 1, 0);
+      const periodLabel = formatMonth(periodStart);
+      const inflowDetails = [];
+      const outflowDetails = [];
+      for (const receivable of receivables) {
+        const dueDate = new Date(receivable.dueDate);
+        if (dueDate >= periodStart && dueDate <= periodEnd) {
+          const probability = receivable.probability ?? 1;
+          const expectedAmount = receivable.amount * probability;
+          inflowDetails.push({
+            description: receivable.description,
+            amount: expectedAmount
+          });
+        }
+      }
+      for (const payable of payables) {
+        const dueDate = new Date(payable.dueDate);
+        if (dueDate >= periodStart && dueDate <= periodEnd) {
+          outflowDetails.push({
+            description: payable.description,
+            amount: payable.amount
+          });
+        }
+        if (payable.recurring && payable.frequency) {
+          const shouldInclude = shouldRecur(
+            new Date(payable.dueDate),
+            periodStart,
+            periodEnd,
+            payable.frequency
+          );
+          if (shouldInclude && dueDate < periodStart) {
+            outflowDetails.push({
+              description: `${payable.description} (recurring)`,
+              amount: payable.amount
+            });
+          }
+        }
+      }
+      for (const item of recurringItems) {
+        const startDate = item.startDate ? new Date(item.startDate) : /* @__PURE__ */ new Date(0);
+        const endDate = item.endDate ? new Date(item.endDate) : new Date(9999, 11, 31);
+        if (periodStart >= startDate && periodEnd <= endDate) {
+          const occurrences = getOccurrencesInPeriod(periodStart, periodEnd, item.frequency);
+          for (let j = 0; j < occurrences; j++) {
+            if (item.type === "income") {
+              inflowDetails.push({
+                description: item.description,
+                amount: item.amount
+              });
+            } else {
+              outflowDetails.push({
+                description: item.description,
+                amount: item.amount
+              });
+            }
+          }
+        }
+      }
+      const periodInflows = inflowDetails.reduce((sum, item) => sum + item.amount, 0);
+      const periodOutflows = outflowDetails.reduce((sum, item) => sum + item.amount, 0);
+      const netChange = periodInflows - periodOutflows;
+      const endingBalance = runningBalance + netChange;
+      if (endingBalance < lowestBalance) {
+        lowestBalance = endingBalance;
+        lowestBalancePeriod = periodLabel;
+      }
+      projections.push({
+        period: periodLabel,
+        startingBalance: runningBalance,
+        inflows: periodInflows,
+        outflows: periodOutflows,
+        netChange,
+        endingBalance,
+        inflowDetails,
+        outflowDetails
+      });
+      runningBalance = endingBalance;
+      totalInflows += periodInflows;
+      totalOutflows += periodOutflows;
+    }
+    const averageMonthlyBurn = totalOutflows > totalInflows ? (totalOutflows - totalInflows) / projectionMonths : 0;
+    let runwayMonths = null;
+    if (averageMonthlyBurn > 0) {
+      runwayMonths = currentCash / averageMonthlyBurn;
+    }
+    return {
+      projections,
+      summary: {
+        currentCash,
+        projectedCashAtEnd: runningBalance,
+        totalInflows,
+        totalOutflows,
+        netChange: totalInflows - totalOutflows,
+        averageMonthlyBurn: Math.round(averageMonthlyBurn * 100) / 100,
+        runwayMonths: runwayMonths !== null ? Math.round(runwayMonths * 10) / 10 : null,
+        lowestBalance: Math.round(lowestBalance * 100) / 100,
+        lowestBalancePeriod
+      }
+    };
+  }
+});
+function formatMonth(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  return `${year}-${month}`;
+}
+function shouldRecur(originalDate, periodStart, periodEnd, frequency) {
+  if (originalDate >= periodStart && originalDate <= periodEnd) {
+    return false;
+  }
+  const monthsDiff = (periodStart.getFullYear() - originalDate.getFullYear()) * 12 + (periodStart.getMonth() - originalDate.getMonth());
+  switch (frequency) {
+    case "monthly":
+      return monthsDiff > 0 && monthsDiff % 1 === 0;
+    case "quarterly":
+      return monthsDiff > 0 && monthsDiff % 3 === 0;
+    case "annually":
+      return monthsDiff > 0 && monthsDiff % 12 === 0;
+    case "weekly":
+      return monthsDiff > 0;
+    default:
+      return false;
+  }
+}
+function getOccurrencesInPeriod(_periodStart, _periodEnd, frequency) {
+  switch (frequency) {
+    case "weekly":
+      return 4;
+    // Approximate 4 weeks per month
+    case "monthly":
+      return 1;
+    case "quarterly":
+      return 0.33;
+    // Approximately 1/3 per month
+    case "annually":
+      return 0.08;
+    // Approximately 1/12 per month
+    default:
+      return 1;
+  }
+}
+var index_default = cashFlowProjectTool;
+
+export { cashFlowProjectTool, index_default as default };

package/package.json

@@ -0,0 +1,94 @@
+{
+  "name": "@tpmjs/official-cash-flow-project",
+  "version": "0.1.0",
+  "description": "Projects cash flow based on receivables, payables, and recurring items",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "finance",
+    "cash-flow",
+    "projection",
+    "runway"
+  ],
+  "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/cash-flow-project"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "finance",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "cashFlowProjectTool",
+        "description": "Projects cash flow based on receivables, payables, and recurring items",
+        "parameters": [
+          {
+            "name": "currentCash",
+            "type": "number",
+            "description": "Current cash balance",
+            "required": true
+          },
+          {
+            "name": "receivables",
+            "type": "array",
+            "description": "Expected receivables with due dates",
+            "required": true
+          },
+          {
+            "name": "payables",
+            "type": "array",
+            "description": "Expected payables with due dates",
+            "required": true
+          },
+          {
+            "name": "recurringItems",
+            "type": "array",
+            "description": "Recurring revenue or expenses",
+            "required": false
+          },
+          {
+            "name": "projectionMonths",
+            "type": "number",
+            "description": "Number of months to project",
+            "required": false
+          }
+        ],
+        "returns": {
+          "type": "CashFlowProjectResult",
+          "description": "Cash flow projections with runway calculation"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}