@tpmjs/official-revenue-breakdown 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,62 @@
+import * as ai from 'ai';
+
+/**
+ * Revenue Breakdown Tool for TPMJS
+ * Breaks down revenue by segment, product, or period with growth rates
+ */
+/**
+ * Revenue data item
+ */
+interface RevenueItem {
+    product?: string;
+    segment?: string;
+    region?: string;
+    period?: string;
+    amount: number;
+}
+/**
+ * Breakdown dimension type
+ */
+type Dimension = 'product' | 'segment' | 'region' | 'period';
+/**
+ * Revenue breakdown item with growth metrics
+ */
+interface BreakdownItem {
+    name: string;
+    revenue: number;
+    percentage: number;
+    growth?: number;
+    growthPercentage?: number;
+    periods?: Array<{
+        period: string;
+        revenue: number;
+    }>;
+}
+/**
+ * Input interface for revenue breakdown
+ */
+interface RevenueBreakdownInput {
+    revenue: RevenueItem[];
+    dimension: Dimension;
+}
+/**
+ * Output interface for revenue breakdown
+ */
+interface RevenueBreakdownResult {
+    breakdown: BreakdownItem[];
+    summary: {
+        totalRevenue: number;
+        numberOfCategories: number;
+        topCategory: string;
+        topCategoryRevenue: number;
+        topCategoryPercentage: number;
+        averageGrowth?: number;
+    };
+}
+/**
+ * Revenue Breakdown Tool
+ * Analyzes revenue by specified dimension and calculates growth rates
+ */
+declare const revenueBreakdownTool: ai.Tool<RevenueBreakdownInput, RevenueBreakdownResult>;
+
+export { type RevenueBreakdownResult, revenueBreakdownTool as default, revenueBreakdownTool };

package/dist/index.js

@@ -0,0 +1,149 @@
+import { tool, jsonSchema } from 'ai';
+
+// src/index.ts
+var revenueBreakdownTool = tool({
+  description: "Breaks down revenue by segment, product, region, or period. Calculates period-over-period growth rates and identifies top performers.",
+  inputSchema: jsonSchema({
+    type: "object",
+    properties: {
+      revenue: {
+        type: "array",
+        description: "Revenue data with segments and periods",
+        items: {
+          type: "object",
+          properties: {
+            product: {
+              type: "string",
+              description: "Product name"
+            },
+            segment: {
+              type: "string",
+              description: "Business segment"
+            },
+            region: {
+              type: "string",
+              description: "Geographic region"
+            },
+            period: {
+              type: "string",
+              description: 'Time period (e.g., "2024-Q1", "2024-01")'
+            },
+            amount: {
+              type: "number",
+              description: "Revenue amount"
+            }
+          },
+          required: ["amount"]
+        }
+      },
+      dimension: {
+        type: "string",
+        enum: ["product", "segment", "region", "period"],
+        description: "Breakdown dimension"
+      }
+    },
+    required: ["revenue", "dimension"],
+    additionalProperties: false
+  }),
+  execute: async ({ revenue, dimension }) => {
+    if (!Array.isArray(revenue) || revenue.length === 0) {
+      throw new Error("Revenue must be a non-empty array");
+    }
+    const validDimensions = ["product", "segment", "region", "period"];
+    if (!validDimensions.includes(dimension)) {
+      throw new Error(
+        `Invalid dimension: ${dimension}. Must be one of: ${validDimensions.join(", ")}`
+      );
+    }
+    const revenueMap = /* @__PURE__ */ new Map();
+    const periodMap = /* @__PURE__ */ new Map();
+    let totalRevenue = 0;
+    for (const item of revenue) {
+      if (typeof item.amount !== "number" || item.amount < 0) {
+        throw new Error("Each revenue item must have a non-negative amount");
+      }
+      const key = getKeyForDimension(item, dimension);
+      if (!key) {
+        throw new Error(
+          `Revenue item missing required field for dimension "${dimension}": ${JSON.stringify(item)}`
+        );
+      }
+      const current = revenueMap.get(key) || [];
+      current.push(item.amount);
+      revenueMap.set(key, current);
+      if (item.period) {
+        if (!periodMap.has(key)) {
+          periodMap.set(key, /* @__PURE__ */ new Map());
+        }
+        const periods = periodMap.get(key);
+        const periodRevenue = periods.get(item.period) || 0;
+        periods.set(item.period, periodRevenue + item.amount);
+      }
+      totalRevenue += item.amount;
+    }
+    if (totalRevenue === 0) {
+      throw new Error("Total revenue cannot be zero");
+    }
+    const breakdown = [];
+    for (const [name, amounts] of revenueMap.entries()) {
+      const itemRevenue = amounts.reduce((sum, amount) => sum + amount, 0);
+      const percentage = itemRevenue / totalRevenue * 100;
+      const breakdownItem = {
+        name,
+        revenue: Math.round(itemRevenue * 100) / 100,
+        percentage: Math.round(percentage * 100) / 100
+      };
+      if (periodMap.has(name)) {
+        const periods = periodMap.get(name);
+        const periodEntries = Array.from(periods.entries()).sort(
+          (a, b) => a[0].localeCompare(b[0])
+        );
+        if (periodEntries.length >= 2) {
+          const oldestPeriod = periodEntries[0];
+          const newestPeriod = periodEntries[periodEntries.length - 1];
+          const growth = newestPeriod[1] - oldestPeriod[1];
+          const growthPercentage = oldestPeriod[1] !== 0 ? growth / oldestPeriod[1] * 100 : 0;
+          breakdownItem.growth = Math.round(growth * 100) / 100;
+          breakdownItem.growthPercentage = Math.round(growthPercentage * 100) / 100;
+        }
+        breakdownItem.periods = periodEntries.map(([period, revenue2]) => ({
+          period,
+          revenue: Math.round(revenue2 * 100) / 100
+        }));
+      }
+      breakdown.push(breakdownItem);
+    }
+    breakdown.sort((a, b) => b.revenue - a.revenue);
+    const topCategory = breakdown[0];
+    const growthRates = breakdown.filter((item) => item.growthPercentage !== void 0).map((item) => item.growthPercentage);
+    const averageGrowth = growthRates.length > 0 ? Math.round(growthRates.reduce((sum, g) => sum + g, 0) / growthRates.length * 100) / 100 : void 0;
+    return {
+      breakdown,
+      summary: {
+        totalRevenue: Math.round(totalRevenue * 100) / 100,
+        numberOfCategories: breakdown.length,
+        topCategory: topCategory.name,
+        topCategoryRevenue: topCategory.revenue,
+        topCategoryPercentage: topCategory.percentage,
+        averageGrowth
+      }
+    };
+  }
+});
+function getKeyForDimension(item, dimension) {
+  switch (dimension) {
+    case "product":
+      return item.product || null;
+    case "segment":
+      return item.segment || null;
+    case "region":
+      return item.region || null;
+    case "period":
+      return item.period || null;
+    default:
+      return null;
+  }
+}
+var index_default = revenueBreakdownTool;
+
+export { index_default as default, revenueBreakdownTool };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@tpmjs/official-revenue-breakdown",
+  "version": "0.1.0",
+  "description": "Breaks down revenue by segment, product, or period with growth rates",
+  "type": "module",
+  "keywords": [
+    "tpmjs",
+    "finance",
+    "revenue",
+    "breakdown",
+    "growth"
+  ],
+  "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/revenue-breakdown"
+  },
+  "homepage": "https://tpmjs.com",
+  "license": "MIT",
+  "tpmjs": {
+    "category": "finance",
+    "frameworks": [
+      "vercel-ai"
+    ],
+    "tools": [
+      {
+        "name": "revenueBreakdownTool",
+        "description": "Breaks down revenue by segment, product, or period with growth rates",
+        "parameters": [
+          {
+            "name": "revenue",
+            "type": "array",
+            "description": "Revenue data with segments and periods",
+            "required": true
+          },
+          {
+            "name": "dimension",
+            "type": "string",
+            "description": "Breakdown dimension (product, segment, region, period)",
+            "required": true
+          }
+        ],
+        "returns": {
+          "type": "RevenueBreakdownResult",
+          "description": "Revenue breakdown with growth rates and summary"
+        }
+      }
+    ]
+  },
+  "dependencies": {
+    "ai": "6.0.0-beta.124"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}