@xallindrome-labs/pricing-domain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Wilson
+
+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/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @xallindrome-labs/pricing-domain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A small, dependency-free pricing model: a base package, per-unit overage and monthly add-ons. Pure functions, so it runs the same in a browser widget, a serverless function or a test. "Unit" is whatever you sell in quantity (posts, hours, seats, deliverables).
+
+```bash
+npm install @xallindrome-labs/pricing-domain
+```
+
+```js
+import { calculatePricing, EXAMPLE_PRICING_CONFIG } from "@xallindrome-labs/pricing-domain";
+
+const result = calculatePricing(
+  { packageKey: "starter", premiumUnits: 2, baseUnits: 5, selectedAddOnKeys: ["monthly_review"] },
+  EXAMPLE_PRICING_CONFIG
+);
+console.log(result.totalMonthlyRevenue); // 830
+```
+
+Also exported: `parsePricingConfig` / `parsePublicPricingConfig` (JSON string to config, `null` if malformed), `toPublicPricingConfigResponse` and `toPublicPricingEstimate` (shape output for visitors, without margin or overhead), and the TypeScript types. `EXAMPLE_PRICING_CONFIG` holds example numbers only; replace them with your own.
+
+Part of [xallindrome-widgets](https://github.com/xallindrome-labs/xallindrome-widgets). MIT licensed.
+
+---
+
+**Built by [Xallindrome](https://xallindrome.co)**: we build automation and AI workflows for small businesses. If you'd like something like this for your business, [book a diagnostic](https://xallindrome.co).

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Small, dependency-free pricing model: a base package plus per-unit overage
+ * and monthly add-ons. Pure functions only, so it runs in a browser widget,
+ * a serverless function or a test the same way.
+ *
+ * "Unit" is whatever you sell in quantity (posts, hours, seats, deliverables).
+ */
+export type PricingPackage = {
+    key: string;
+    name: string;
+    /** Monthly price of the package. */
+    price: number;
+    /** Units included in the package. */
+    units: number;
+};
+export type PricingAddOn = {
+    key: string;
+    name: string;
+    monthlyPrice: number;
+};
+export type PricingConfig = {
+    /** Price of one extra "premium" unit beyond the package. */
+    premiumUnitPrice: number;
+    /** Price of one extra "base" unit beyond the package. */
+    baseUnitPrice: number;
+    /** Your fixed monthly cost, used only for the margin figure. Defaults to 0. */
+    fixedOverhead?: number;
+    packages: PricingPackage[];
+    addOns: PricingAddOn[];
+};
+export type PublicPricingPackage = PricingPackage & {
+    description?: string;
+    priceCue?: string;
+};
+export type PublicPricingConfig = {
+    premiumUnitPrice: number;
+    baseUnitPrice: number;
+    fixedOverhead?: number;
+    packages: PublicPricingPackage[];
+    addOns: PricingAddOn[];
+    disclaimer?: string;
+    ctaLabel?: string;
+    ctaUrl?: string;
+    premiumUnitLabel?: string;
+    baseUnitLabel?: string;
+};
+export type PricingCalculationInput = {
+    packageKey: string;
+    premiumUnits: number;
+    baseUnits: number;
+    selectedAddOnKeys: string[];
+};
+export type PricingCalculationResult = {
+    packageName: string;
+    basePrice: number;
+    packageUnits: number;
+    premiumUnits: number;
+    premiumRevenue: number;
+    baseUnits: number;
+    baseRevenue: number;
+    activeAddOns: PricingAddOn[];
+    addOnSubtotal: number;
+    extraUnits: number;
+    extraRevenue: number;
+    totalMonthlyRevenue: number;
+    totalUnits: number;
+    effectivePricePerUnit: number;
+    monthlyMargin: number;
+};
+export type PublicPricingConfigResponse = {
+    packages: Array<{
+        key: string;
+        name: string;
+        description?: string;
+        priceCue: string;
+    }>;
+    premiumUnitPrice: number;
+    baseUnitPrice: number;
+    premiumUnitLabel: string;
+    baseUnitLabel: string;
+    disclaimer: string;
+    ctaLabel: string;
+    ctaUrl: string;
+};
+export type PublicPricingEstimate = {
+    packageName: string;
+    premiumUnits: number;
+    baseUnits: number;
+    extraRevenue: number;
+    totalMonthlyRevenue: number;
+};
+/** Example numbers only. Replace them with your own pricing. */
+export declare const EXAMPLE_PRICING_CONFIG: PricingConfig;
+export declare const EXAMPLE_PUBLIC_PRICING_CONFIG: PublicPricingConfig;
+/** Parses a JSON string into a PricingConfig. Returns null if it is empty or malformed. */
+export declare function parsePricingConfig(value: string | undefined | null, fallback?: PricingConfig): PricingConfig | null;
+/** Parses a JSON string into a PublicPricingConfig. Returns null if it is empty or malformed. */
+export declare function parsePublicPricingConfig(value: string | undefined | null, fallback?: PublicPricingConfig): PublicPricingConfig | null;
+export declare function calculatePricing(input: PricingCalculationInput, config: PricingConfig): PricingCalculationResult;
+/** Shapes a config for public display: no overhead, formatted price cues and labels. */
+export declare function toPublicPricingConfigResponse(config: PublicPricingConfig): PublicPricingConfigResponse;
+/** Strips a calculation down to the fields that are safe to show a visitor (no margin, no overhead). */
+export declare function toPublicPricingEstimate(result: PricingCalculationResult): PublicPricingEstimate;

package/dist/index.js

@@ -0,0 +1,200 @@
+/**
+ * Small, dependency-free pricing model: a base package plus per-unit overage
+ * and monthly add-ons. Pure functions only, so it runs in a browser widget,
+ * a serverless function or a test the same way.
+ *
+ * "Unit" is whatever you sell in quantity (posts, hours, seats, deliverables).
+ */
+function formatCurrency(value) {
+    return new Intl.NumberFormat("en-US", {
+        style: "currency",
+        currency: "USD",
+        maximumFractionDigits: 0
+    }).format(value);
+}
+/** Example numbers only. Replace them with your own pricing. */
+export const EXAMPLE_PRICING_CONFIG = {
+    premiumUnitPrice: 40,
+    baseUnitPrice: 20,
+    packages: [
+        { key: "starter", name: "Starter", price: 500, units: 10 },
+        { key: "growth", name: "Growth", price: 1200, units: 30 },
+        { key: "scale", name: "Scale", price: 2500, units: 80 },
+        { key: "none", name: "No Base Package", price: 0, units: 0 }
+    ],
+    addOns: [
+        { key: "monthly_review", name: "Monthly Review Call", monthlyPrice: 150 },
+        { key: "priority_support", name: "Priority Support", monthlyPrice: 100 }
+    ]
+};
+export const EXAMPLE_PUBLIC_PRICING_CONFIG = {
+    premiumUnitPrice: EXAMPLE_PRICING_CONFIG.premiumUnitPrice,
+    baseUnitPrice: EXAMPLE_PRICING_CONFIG.baseUnitPrice,
+    packages: EXAMPLE_PRICING_CONFIG.packages.map((pkg) => ({
+        ...pkg,
+        priceCue: pkg.price > 0 ? `Starts at ${formatCurrency(pkg.price)}/month` : "Custom add-ons only"
+    })),
+    addOns: EXAMPLE_PRICING_CONFIG.addOns,
+    disclaimer: "Estimates are provided for planning only and may vary based on scope and requirements.",
+    ctaLabel: "Book a call",
+    ctaUrl: "https://example.com/book",
+    premiumUnitLabel: `Premium units (${formatCurrency(EXAMPLE_PRICING_CONFIG.premiumUnitPrice)} each)`,
+    baseUnitLabel: `Base units (${formatCurrency(EXAMPLE_PRICING_CONFIG.baseUnitPrice)} each)`
+};
+function parsePackages(value) {
+    return value.map((item) => {
+        const pkg = item;
+        return {
+            key: String(pkg.key),
+            name: String(pkg.name),
+            price: Number(pkg.price),
+            units: Number(pkg.units)
+        };
+    });
+}
+function parseAddOns(value, fallback) {
+    if (!Array.isArray(value)) {
+        return fallback;
+    }
+    return value.map((item) => {
+        const addOn = item;
+        return {
+            key: String(addOn.key),
+            name: String(addOn.name),
+            monthlyPrice: Number(addOn.monthlyPrice)
+        };
+    });
+}
+/** Parses a JSON string into a PricingConfig. Returns null if it is empty or malformed. */
+export function parsePricingConfig(value, fallback = EXAMPLE_PRICING_CONFIG) {
+    if (!value) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed.packages)) {
+            return null;
+        }
+        return {
+            premiumUnitPrice: Number(parsed.premiumUnitPrice ?? fallback.premiumUnitPrice),
+            baseUnitPrice: Number(parsed.baseUnitPrice ?? fallback.baseUnitPrice),
+            fixedOverhead: Number(parsed.fixedOverhead ?? fallback.fixedOverhead ?? 0),
+            packages: parsePackages(parsed.packages),
+            addOns: parseAddOns(parsed.addOns, fallback.addOns)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Parses a JSON string into a PublicPricingConfig. Returns null if it is empty or malformed. */
+export function parsePublicPricingConfig(value, fallback = EXAMPLE_PUBLIC_PRICING_CONFIG) {
+    if (!value) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (!Array.isArray(parsed.packages)) {
+            return null;
+        }
+        const str = (v, fb) => (typeof v === "string" ? v : fb);
+        return {
+            premiumUnitPrice: Number(parsed.premiumUnitPrice ?? fallback.premiumUnitPrice),
+            baseUnitPrice: Number(parsed.baseUnitPrice ?? fallback.baseUnitPrice),
+            fixedOverhead: Number(parsed.fixedOverhead ?? fallback.fixedOverhead ?? 0),
+            packages: parsed.packages.map((item) => {
+                const pkg = item;
+                return {
+                    key: String(pkg.key),
+                    name: String(pkg.name),
+                    price: Number(pkg.price),
+                    units: Number(pkg.units),
+                    description: str(pkg.description, undefined),
+                    priceCue: str(pkg.priceCue, undefined)
+                };
+            }),
+            addOns: parseAddOns(parsed.addOns, fallback.addOns),
+            disclaimer: str(parsed.disclaimer, fallback.disclaimer),
+            ctaLabel: str(parsed.ctaLabel, fallback.ctaLabel),
+            ctaUrl: str(parsed.ctaUrl, fallback.ctaUrl),
+            premiumUnitLabel: str(parsed.premiumUnitLabel, fallback.premiumUnitLabel),
+            baseUnitLabel: str(parsed.baseUnitLabel, fallback.baseUnitLabel)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function calculatePricing(input, config) {
+    if (!Number.isInteger(input.premiumUnits) ||
+        !Number.isInteger(input.baseUnits) ||
+        input.premiumUnits < 0 ||
+        input.baseUnits < 0) {
+        throw new Error("Unit counts must be non-negative integers.");
+    }
+    const selectedPackage = config.packages.find((pkg) => pkg.key === input.packageKey);
+    if (!selectedPackage) {
+        throw new Error("Invalid package key.");
+    }
+    const fixedOverhead = Number(config.fixedOverhead ?? 0);
+    const premiumRevenue = input.premiumUnits * config.premiumUnitPrice;
+    const baseRevenue = input.baseUnits * config.baseUnitPrice;
+    const selectedAddOnKeys = Array.isArray(input.selectedAddOnKeys)
+        ? Array.from(new Set(input.selectedAddOnKeys.map((key) => String(key))))
+        : [];
+    const activeAddOns = config.addOns.filter((addOn) => selectedAddOnKeys.includes(addOn.key));
+    const addOnSubtotal = activeAddOns.reduce((total, addOn) => total + addOn.monthlyPrice, 0);
+    const extraRevenue = premiumRevenue + baseRevenue;
+    const totalMonthlyRevenue = selectedPackage.price + extraRevenue + addOnSubtotal;
+    const totalUnits = selectedPackage.units + input.premiumUnits + input.baseUnits;
+    const effectivePricePerUnit = totalUnits > 0 ? totalMonthlyRevenue / totalUnits : 0;
+    const monthlyMargin = totalMonthlyRevenue - fixedOverhead;
+    return {
+        packageName: selectedPackage.name,
+        basePrice: selectedPackage.price,
+        packageUnits: selectedPackage.units,
+        premiumUnits: input.premiumUnits,
+        premiumRevenue,
+        baseUnits: input.baseUnits,
+        baseRevenue,
+        activeAddOns,
+        addOnSubtotal: Number(addOnSubtotal.toFixed(2)),
+        extraUnits: input.premiumUnits + input.baseUnits,
+        extraRevenue,
+        totalMonthlyRevenue,
+        totalUnits,
+        effectivePricePerUnit: Number(effectivePricePerUnit.toFixed(2)),
+        monthlyMargin: Number(monthlyMargin.toFixed(2))
+    };
+}
+/** Shapes a config for public display: no overhead, formatted price cues and labels. */
+export function toPublicPricingConfigResponse(config) {
+    return {
+        packages: config.packages.map((pkg) => ({
+            key: pkg.key,
+            name: pkg.name,
+            description: pkg.description,
+            priceCue: pkg.priceCue ??
+                (pkg.price > 0 ? `Starts at ${formatCurrency(pkg.price)}/month` : "Custom add-ons only")
+        })),
+        premiumUnitPrice: config.premiumUnitPrice,
+        baseUnitPrice: config.baseUnitPrice,
+        premiumUnitLabel: config.premiumUnitLabel ?? `Premium units (${formatCurrency(config.premiumUnitPrice)} each)`,
+        baseUnitLabel: config.baseUnitLabel ?? `Base units (${formatCurrency(config.baseUnitPrice)} each)`,
+        disclaimer: config.disclaimer ??
+            EXAMPLE_PUBLIC_PRICING_CONFIG.disclaimer ??
+            "Estimates may vary by scope.",
+        ctaLabel: config.ctaLabel ?? EXAMPLE_PUBLIC_PRICING_CONFIG.ctaLabel ?? "Book a call",
+        ctaUrl: config.ctaUrl ?? EXAMPLE_PUBLIC_PRICING_CONFIG.ctaUrl ?? "https://example.com/book"
+    };
+}
+/** Strips a calculation down to the fields that are safe to show a visitor (no margin, no overhead). */
+export function toPublicPricingEstimate(result) {
+    return {
+        packageName: result.packageName,
+        premiumUnits: result.premiumUnits,
+        baseUnits: result.baseUnits,
+        extraRevenue: result.extraRevenue,
+        totalMonthlyRevenue: result.totalMonthlyRevenue
+    };
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@xallindrome-labs/pricing-domain",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Dependency-free pricing model: base package + per-unit overage + monthly add-ons.",
+  "keywords": [
+    "pricing",
+    "quote",
+    "calculator",
+    "packages",
+    "add-ons",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Andrew Wilson (https://xallindrome.co)",
+  "homepage": "https://github.com/xallindrome-labs/xallindrome-widgets/tree/main/libs/pricing-domain#readme",
+  "bugs": "https://github.com/xallindrome-labs/xallindrome-widgets/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xallindrome-labs/xallindrome-widgets.git",
+    "directory": "libs/pricing-domain"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3"
+  }
+}