@lacspace/commission 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data 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 conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+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.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,112 @@
+<div align="center">
+
+# @lacspace/commission
+
+**A commission & payout calculation engine — flat, percentage and marginal-tiered rules, plus exact proportional splits.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/commission?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/commission)
+[![install size](https://packagephobia.com/badge?p=@lacspace/commission)](https://packagephobia.com/result?p=@lacspace/commission)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/commission?label=minzip)](https://bundlephobia.com/package/@lacspace/commission)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/commission)
+[![license](https://img.shields.io/npm/l/@lacspace/commission?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> Every marketplace and sales tool re-implements the same money maths badly: what commission does this sale earn, what's left for the seller, and how do you split a payout across several parties **without losing a cent**? This does all three, correctly, in integer minor units — no floats, no rounding drift.
+
+- 💰 **Three rule kinds** — `flat` fee, `percent`, or `tiered` marginal brackets
+- 🧢 **Bounds** — optional `min` (floor) and `max` (cap) on any rule
+- ✂️ **Exact splits** — proportional allocation where the parts always sum to the total
+- 🔢 **Integer minor units** — cents / paisa in, cents / paisa out, never a float
+- ⚡ Isomorphic — Node, edge runtimes & browsers · 📦 ESM + CJS · zero dependencies · fully typed
+
+## Install
+
+```bash
+npm install @lacspace/commission      # or pnpm add / yarn add / bun add
+```
+
+## Commission rules
+
+```ts
+import { commission } from "@lacspace/commission";
+
+// 15% of a $10.00 sale (amounts are in cents)
+commission({ type: "percent", rate: 0.15 }, 1000);
+// → { commission: 150, net: 850, effectiveRate: 0.15 }
+
+// flat fee, floored to at least 50c and capped at $1.00
+commission({ type: "flat", amount: 5, min: 50, max: 100 }, 1000);
+// → { commission: 50, net: 950, effectiveRate: 0.05 }
+```
+
+## Marginal tiers
+
+```ts
+import { commission } from "@lacspace/commission";
+
+const rule = {
+  type: "tiered" as const,
+  tiers: [
+    { upTo: 1000, rate: 0.1 },   // first $10.00  @ 10%
+    { upTo: 5000, rate: 0.05 },  // next  $40.00  @ 5%
+    { upTo: null, rate: 0.02 },  // remainder     @ 2%
+  ],
+};
+
+commission(rule, 6000);
+// 0..1000 → 100, 1000..5000 → 200, 5000..6000 → 20
+// → { commission: 320, net: 5680, effectiveRate: 0.0533… }
+```
+
+## Splitting a payout
+
+```ts
+import { split } from "@lacspace/commission";
+
+// share $10.00 70/30 — the parts always sum to exactly the total
+split(1000, [
+  { party: "seller", rate: 0.7 },
+  { party: "platform", rate: 0.3 },
+]);
+// → [ { party: "seller", amount: 700 }, { party: "platform", amount: 300 } ]
+
+// awkward thirds: the leftover cent is handed to the largest remainder
+split(100, [
+  { party: "a", rate: 1 },
+  { party: "b", rate: 1 },
+  { party: "c", rate: 1 },
+]);
+// → [ { party: "a", amount: 34 }, { party: "b", amount: 33 }, { party: "c", amount: 33 } ]
+```
+
+## API
+
+| Function | Description |
+| --- | --- |
+| `commission(rule, amount)` | `{ commission, net, effectiveRate }` — charge for `amount` under `rule` |
+| `split(amount, shares)` | `{ party, amount }[]` — proportional split whose parts sum to `amount` exactly |
+
+**Rule** is `{ type: "flat"; amount }` \| `{ type: "percent"; rate /*0..1*/ }` \| `{ type: "tiered"; tiers }`, each optionally with `{ min?, max? }`. Tiers are marginal brackets `{ upTo: number \| null; rate }`, the last with `upTo: null` for infinity. All money is in **integer minor units**; the raw commission is rounded to the nearest unit then clamped into `[min, max]`.
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — permissive freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+<!-- LACSPACE-DEV-PLATFORM -->
+
+---
+
+## The Lacspace Developer Platform
+
+`@lacspace/commission` is part of **63+ zero-dependency, isomorphic TypeScript packages**. Explore the ecosystem:
+
+- 🗂️ **All packages** — https://developer.lacspace.com/packages
+- 🧭 **Developer handbook** — https://developer.lacspace.com/handbook
+- 🧪 **Live playground** — https://developer.lacspace.com/playground
+- 🖥️ **Finished app templates** — https://templates.lacspace.com
+- 🚀 **Scaffold a full app** — `npm create lacspace-app@latest`
+
+Free under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — a permissive, free-to-use licence.

package/dist/index.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+// src/index.ts
+function commission(rule, amount) {
+  const amt = Math.trunc(amount);
+  let raw;
+  switch (rule.type) {
+    case "flat":
+      raw = rule.amount;
+      break;
+    case "percent":
+      raw = amt * rule.rate;
+      break;
+    case "tiered": {
+      let acc = 0;
+      let lower = 0;
+      for (const tier of rule.tiers) {
+        const upper = tier.upTo === null ? amt : Math.min(tier.upTo, amt);
+        if (upper > lower) {
+          acc += (upper - lower) * tier.rate;
+          lower = upper;
+        }
+        if (tier.upTo !== null && amt <= tier.upTo) break;
+      }
+      raw = acc;
+      break;
+    }
+  }
+  let c = Math.round(raw);
+  if (rule.max !== void 0 && c > rule.max) c = rule.max;
+  if (rule.min !== void 0 && c < rule.min) c = rule.min;
+  const net = amt - c;
+  const effectiveRate = amt === 0 ? 0 : c / amt;
+  return { commission: c, net, effectiveRate };
+}
+function split(amount, shares) {
+  const n = shares.length;
+  if (n === 0) return [];
+  const amt = Math.trunc(amount);
+  const total = shares.reduce((s, x) => s + x.rate, 0);
+  if (total <= 0) {
+    const base = Math.trunc(amt / n);
+    const rem = amt - base * n;
+    return shares.map((s, i) => ({ party: s.party, amount: base + (i < rem ? 1 : 0) }));
+  }
+  const ideals = shares.map((s) => amt * s.rate / total);
+  const parts = shares.map((s, i) => {
+    const ideal = ideals[i] ?? 0;
+    return { party: s.party, amount: Math.floor(ideal) };
+  });
+  const allocated = parts.reduce((a, p) => a + p.amount, 0);
+  let remainder = amt - allocated;
+  const order = ideals.map((ideal, i) => ({ i, frac: ideal - Math.floor(ideal) })).sort((a, b) => b.frac - a.frac);
+  let k = 0;
+  while (remainder > 0 && order.length > 0) {
+    const target = order[k % order.length];
+    if (target) {
+      const part = parts[target.i];
+      if (part) part.amount += 1;
+    }
+    remainder--;
+    k++;
+  }
+  return parts;
+}
+
+exports.commission = commission;
+exports.split = split;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/commission — commission & payout calculation engine.\n *\n * All money is expressed in **integer minor units** (e.g. cents, paisa).\n * There are no floating-point money values anywhere in this package.\n *\n * Isomorphic, dependency-free, side-effect-free.\n */\n\n/** Optional floor / cap applied to a computed commission (minor units). */\nexport interface CommissionBounds {\n  /** Minimum commission (floor), in minor units. */\n  min?: number;\n  /** Maximum commission (cap), in minor units. */\n  max?: number;\n}\n\n/** A single marginal bracket in a tiered rule. */\nexport interface Tier {\n  /**\n   * Upper boundary of this bracket, in minor units, or `null` for infinity.\n   * The last tier in a list should use `upTo: null`.\n   */\n  upTo: number | null;\n  /** Marginal rate applied to the portion of `amount` inside this bracket (0..1). */\n  rate: number;\n}\n\n/** A commission rule: flat fee, percentage, or marginal tiers. */\nexport type CommissionRule =\n  | ({ type: \"flat\"; amount: number } & CommissionBounds)\n  | ({ type: \"percent\"; rate: number } & CommissionBounds)\n  | ({ type: \"tiered\"; tiers: Tier[] } & CommissionBounds);\n\n/** Result of a commission computation (all money in minor units). */\nexport interface CommissionResult {\n  /** Commission charged, in minor units. */\n  commission: number;\n  /** Amount left after commission (`amount - commission`), in minor units. */\n  net: number;\n  /** Effective rate = `commission / amount` (0..1); `0` when amount is `0`. */\n  effectiveRate: number;\n}\n\n/** A payout share used by {@link split}. */\nexport interface Share {\n  party: string;\n  /** Relative weight of this share. Shares need not sum to 1. */\n  rate: number;\n}\n\n/** One allocated slice returned by {@link split}. */\nexport interface SplitPart {\n  party: string;\n  /** Allocated amount, in minor units. */\n  amount: number;\n}\n\n/**\n * Compute the commission for `amount` under `rule`.\n *\n * `amount` is truncated to an integer number of minor units. The raw\n * commission is rounded to the nearest minor unit, then clamped into\n * `[min, max]` when those bounds are present.\n */\nexport function commission(rule: CommissionRule, amount: number): CommissionResult {\n  const amt = Math.trunc(amount);\n\n  let raw: number;\n  switch (rule.type) {\n    case \"flat\":\n      raw = rule.amount;\n      break;\n    case \"percent\":\n      raw = amt * rule.rate;\n      break;\n    case \"tiered\": {\n      let acc = 0;\n      let lower = 0;\n      for (const tier of rule.tiers) {\n        const upper = tier.upTo === null ? amt : Math.min(tier.upTo, amt);\n        if (upper > lower) {\n          acc += (upper - lower) * tier.rate;\n          lower = upper;\n        }\n        if (tier.upTo !== null && amt <= tier.upTo) break;\n      }\n      raw = acc;\n      break;\n    }\n  }\n\n  let c = Math.round(raw);\n  if (rule.max !== undefined && c > rule.max) c = rule.max;\n  if (rule.min !== undefined && c < rule.min) c = rule.min;\n\n  const net = amt - c;\n  const effectiveRate = amt === 0 ? 0 : c / amt;\n  return { commission: c, net, effectiveRate };\n}\n\n/**\n * Split `amount` (minor units) proportionally across `shares`.\n *\n * Uses the largest-remainder method so the returned amounts always sum to\n * `amount` **exactly** — no minor units are lost or invented. When the shares'\n * rates sum to zero, `amount` is distributed as evenly as possible instead.\n */\nexport function split(amount: number, shares: Share[]): SplitPart[] {\n  const n = shares.length;\n  if (n === 0) return [];\n\n  const amt = Math.trunc(amount);\n  const total = shares.reduce((s, x) => s + x.rate, 0);\n\n  // Degenerate weights: fall back to an even distribution.\n  if (total <= 0) {\n    const base = Math.trunc(amt / n);\n    const rem = amt - base * n;\n    return shares.map((s, i) => ({ party: s.party, amount: base + (i < rem ? 1 : 0) }));\n  }\n\n  const ideals = shares.map((s) => (amt * s.rate) / total);\n  const parts: SplitPart[] = shares.map((s, i) => {\n    const ideal = ideals[i] ?? 0;\n    return { party: s.party, amount: Math.floor(ideal) };\n  });\n\n  const allocated = parts.reduce((a, p) => a + p.amount, 0);\n  let remainder = amt - allocated;\n\n  // Hand out the leftover minor units to the largest fractional parts first.\n  const order = ideals\n    .map((ideal, i) => ({ i, frac: ideal - Math.floor(ideal) }))\n    .sort((a, b) => b.frac - a.frac);\n\n  let k = 0;\n  while (remainder > 0 && order.length > 0) {\n    const target = order[k % order.length];\n    if (target) {\n      const part = parts[target.i];\n      if (part) part.amount += 1;\n    }\n    remainder--;\n    k++;\n  }\n\n  return parts;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,75 @@
+/**
+ * @lacspace/commission — commission & payout calculation engine.
+ *
+ * All money is expressed in **integer minor units** (e.g. cents, paisa).
+ * There are no floating-point money values anywhere in this package.
+ *
+ * Isomorphic, dependency-free, side-effect-free.
+ */
+/** Optional floor / cap applied to a computed commission (minor units). */
+interface CommissionBounds {
+    /** Minimum commission (floor), in minor units. */
+    min?: number;
+    /** Maximum commission (cap), in minor units. */
+    max?: number;
+}
+/** A single marginal bracket in a tiered rule. */
+interface Tier {
+    /**
+     * Upper boundary of this bracket, in minor units, or `null` for infinity.
+     * The last tier in a list should use `upTo: null`.
+     */
+    upTo: number | null;
+    /** Marginal rate applied to the portion of `amount` inside this bracket (0..1). */
+    rate: number;
+}
+/** A commission rule: flat fee, percentage, or marginal tiers. */
+type CommissionRule = ({
+    type: "flat";
+    amount: number;
+} & CommissionBounds) | ({
+    type: "percent";
+    rate: number;
+} & CommissionBounds) | ({
+    type: "tiered";
+    tiers: Tier[];
+} & CommissionBounds);
+/** Result of a commission computation (all money in minor units). */
+interface CommissionResult {
+    /** Commission charged, in minor units. */
+    commission: number;
+    /** Amount left after commission (`amount - commission`), in minor units. */
+    net: number;
+    /** Effective rate = `commission / amount` (0..1); `0` when amount is `0`. */
+    effectiveRate: number;
+}
+/** A payout share used by {@link split}. */
+interface Share {
+    party: string;
+    /** Relative weight of this share. Shares need not sum to 1. */
+    rate: number;
+}
+/** One allocated slice returned by {@link split}. */
+interface SplitPart {
+    party: string;
+    /** Allocated amount, in minor units. */
+    amount: number;
+}
+/**
+ * Compute the commission for `amount` under `rule`.
+ *
+ * `amount` is truncated to an integer number of minor units. The raw
+ * commission is rounded to the nearest minor unit, then clamped into
+ * `[min, max]` when those bounds are present.
+ */
+declare function commission(rule: CommissionRule, amount: number): CommissionResult;
+/**
+ * Split `amount` (minor units) proportionally across `shares`.
+ *
+ * Uses the largest-remainder method so the returned amounts always sum to
+ * `amount` **exactly** — no minor units are lost or invented. When the shares'
+ * rates sum to zero, `amount` is distributed as evenly as possible instead.
+ */
+declare function split(amount: number, shares: Share[]): SplitPart[];
+
+export { type CommissionBounds, type CommissionResult, type CommissionRule, type Share, type SplitPart, type Tier, commission, split };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @lacspace/commission — commission & payout calculation engine.
+ *
+ * All money is expressed in **integer minor units** (e.g. cents, paisa).
+ * There are no floating-point money values anywhere in this package.
+ *
+ * Isomorphic, dependency-free, side-effect-free.
+ */
+/** Optional floor / cap applied to a computed commission (minor units). */
+interface CommissionBounds {
+    /** Minimum commission (floor), in minor units. */
+    min?: number;
+    /** Maximum commission (cap), in minor units. */
+    max?: number;
+}
+/** A single marginal bracket in a tiered rule. */
+interface Tier {
+    /**
+     * Upper boundary of this bracket, in minor units, or `null` for infinity.
+     * The last tier in a list should use `upTo: null`.
+     */
+    upTo: number | null;
+    /** Marginal rate applied to the portion of `amount` inside this bracket (0..1). */
+    rate: number;
+}
+/** A commission rule: flat fee, percentage, or marginal tiers. */
+type CommissionRule = ({
+    type: "flat";
+    amount: number;
+} & CommissionBounds) | ({
+    type: "percent";
+    rate: number;
+} & CommissionBounds) | ({
+    type: "tiered";
+    tiers: Tier[];
+} & CommissionBounds);
+/** Result of a commission computation (all money in minor units). */
+interface CommissionResult {
+    /** Commission charged, in minor units. */
+    commission: number;
+    /** Amount left after commission (`amount - commission`), in minor units. */
+    net: number;
+    /** Effective rate = `commission / amount` (0..1); `0` when amount is `0`. */
+    effectiveRate: number;
+}
+/** A payout share used by {@link split}. */
+interface Share {
+    party: string;
+    /** Relative weight of this share. Shares need not sum to 1. */
+    rate: number;
+}
+/** One allocated slice returned by {@link split}. */
+interface SplitPart {
+    party: string;
+    /** Allocated amount, in minor units. */
+    amount: number;
+}
+/**
+ * Compute the commission for `amount` under `rule`.
+ *
+ * `amount` is truncated to an integer number of minor units. The raw
+ * commission is rounded to the nearest minor unit, then clamped into
+ * `[min, max]` when those bounds are present.
+ */
+declare function commission(rule: CommissionRule, amount: number): CommissionResult;
+/**
+ * Split `amount` (minor units) proportionally across `shares`.
+ *
+ * Uses the largest-remainder method so the returned amounts always sum to
+ * `amount` **exactly** — no minor units are lost or invented. When the shares'
+ * rates sum to zero, `amount` is distributed as evenly as possible instead.
+ */
+declare function split(amount: number, shares: Share[]): SplitPart[];
+
+export { type CommissionBounds, type CommissionResult, type CommissionRule, type Share, type SplitPart, type Tier, commission, split };

package/dist/index.js

@@ -0,0 +1,67 @@
+// src/index.ts
+function commission(rule, amount) {
+  const amt = Math.trunc(amount);
+  let raw;
+  switch (rule.type) {
+    case "flat":
+      raw = rule.amount;
+      break;
+    case "percent":
+      raw = amt * rule.rate;
+      break;
+    case "tiered": {
+      let acc = 0;
+      let lower = 0;
+      for (const tier of rule.tiers) {
+        const upper = tier.upTo === null ? amt : Math.min(tier.upTo, amt);
+        if (upper > lower) {
+          acc += (upper - lower) * tier.rate;
+          lower = upper;
+        }
+        if (tier.upTo !== null && amt <= tier.upTo) break;
+      }
+      raw = acc;
+      break;
+    }
+  }
+  let c = Math.round(raw);
+  if (rule.max !== void 0 && c > rule.max) c = rule.max;
+  if (rule.min !== void 0 && c < rule.min) c = rule.min;
+  const net = amt - c;
+  const effectiveRate = amt === 0 ? 0 : c / amt;
+  return { commission: c, net, effectiveRate };
+}
+function split(amount, shares) {
+  const n = shares.length;
+  if (n === 0) return [];
+  const amt = Math.trunc(amount);
+  const total = shares.reduce((s, x) => s + x.rate, 0);
+  if (total <= 0) {
+    const base = Math.trunc(amt / n);
+    const rem = amt - base * n;
+    return shares.map((s, i) => ({ party: s.party, amount: base + (i < rem ? 1 : 0) }));
+  }
+  const ideals = shares.map((s) => amt * s.rate / total);
+  const parts = shares.map((s, i) => {
+    const ideal = ideals[i] ?? 0;
+    return { party: s.party, amount: Math.floor(ideal) };
+  });
+  const allocated = parts.reduce((a, p) => a + p.amount, 0);
+  let remainder = amt - allocated;
+  const order = ideals.map((ideal, i) => ({ i, frac: ideal - Math.floor(ideal) })).sort((a, b) => b.frac - a.frac);
+  let k = 0;
+  while (remainder > 0 && order.length > 0) {
+    const target = order[k % order.length];
+    if (target) {
+      const part = parts[target.i];
+      if (part) part.amount += 1;
+    }
+    remainder--;
+    k++;
+  }
+  return parts;
+}
+
+export { commission, split };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/commission — commission & payout calculation engine.\n *\n * All money is expressed in **integer minor units** (e.g. cents, paisa).\n * There are no floating-point money values anywhere in this package.\n *\n * Isomorphic, dependency-free, side-effect-free.\n */\n\n/** Optional floor / cap applied to a computed commission (minor units). */\nexport interface CommissionBounds {\n  /** Minimum commission (floor), in minor units. */\n  min?: number;\n  /** Maximum commission (cap), in minor units. */\n  max?: number;\n}\n\n/** A single marginal bracket in a tiered rule. */\nexport interface Tier {\n  /**\n   * Upper boundary of this bracket, in minor units, or `null` for infinity.\n   * The last tier in a list should use `upTo: null`.\n   */\n  upTo: number | null;\n  /** Marginal rate applied to the portion of `amount` inside this bracket (0..1). */\n  rate: number;\n}\n\n/** A commission rule: flat fee, percentage, or marginal tiers. */\nexport type CommissionRule =\n  | ({ type: \"flat\"; amount: number } & CommissionBounds)\n  | ({ type: \"percent\"; rate: number } & CommissionBounds)\n  | ({ type: \"tiered\"; tiers: Tier[] } & CommissionBounds);\n\n/** Result of a commission computation (all money in minor units). */\nexport interface CommissionResult {\n  /** Commission charged, in minor units. */\n  commission: number;\n  /** Amount left after commission (`amount - commission`), in minor units. */\n  net: number;\n  /** Effective rate = `commission / amount` (0..1); `0` when amount is `0`. */\n  effectiveRate: number;\n}\n\n/** A payout share used by {@link split}. */\nexport interface Share {\n  party: string;\n  /** Relative weight of this share. Shares need not sum to 1. */\n  rate: number;\n}\n\n/** One allocated slice returned by {@link split}. */\nexport interface SplitPart {\n  party: string;\n  /** Allocated amount, in minor units. */\n  amount: number;\n}\n\n/**\n * Compute the commission for `amount` under `rule`.\n *\n * `amount` is truncated to an integer number of minor units. The raw\n * commission is rounded to the nearest minor unit, then clamped into\n * `[min, max]` when those bounds are present.\n */\nexport function commission(rule: CommissionRule, amount: number): CommissionResult {\n  const amt = Math.trunc(amount);\n\n  let raw: number;\n  switch (rule.type) {\n    case \"flat\":\n      raw = rule.amount;\n      break;\n    case \"percent\":\n      raw = amt * rule.rate;\n      break;\n    case \"tiered\": {\n      let acc = 0;\n      let lower = 0;\n      for (const tier of rule.tiers) {\n        const upper = tier.upTo === null ? amt : Math.min(tier.upTo, amt);\n        if (upper > lower) {\n          acc += (upper - lower) * tier.rate;\n          lower = upper;\n        }\n        if (tier.upTo !== null && amt <= tier.upTo) break;\n      }\n      raw = acc;\n      break;\n    }\n  }\n\n  let c = Math.round(raw);\n  if (rule.max !== undefined && c > rule.max) c = rule.max;\n  if (rule.min !== undefined && c < rule.min) c = rule.min;\n\n  const net = amt - c;\n  const effectiveRate = amt === 0 ? 0 : c / amt;\n  return { commission: c, net, effectiveRate };\n}\n\n/**\n * Split `amount` (minor units) proportionally across `shares`.\n *\n * Uses the largest-remainder method so the returned amounts always sum to\n * `amount` **exactly** — no minor units are lost or invented. When the shares'\n * rates sum to zero, `amount` is distributed as evenly as possible instead.\n */\nexport function split(amount: number, shares: Share[]): SplitPart[] {\n  const n = shares.length;\n  if (n === 0) return [];\n\n  const amt = Math.trunc(amount);\n  const total = shares.reduce((s, x) => s + x.rate, 0);\n\n  // Degenerate weights: fall back to an even distribution.\n  if (total <= 0) {\n    const base = Math.trunc(amt / n);\n    const rem = amt - base * n;\n    return shares.map((s, i) => ({ party: s.party, amount: base + (i < rem ? 1 : 0) }));\n  }\n\n  const ideals = shares.map((s) => (amt * s.rate) / total);\n  const parts: SplitPart[] = shares.map((s, i) => {\n    const ideal = ideals[i] ?? 0;\n    return { party: s.party, amount: Math.floor(ideal) };\n  });\n\n  const allocated = parts.reduce((a, p) => a + p.amount, 0);\n  let remainder = amt - allocated;\n\n  // Hand out the leftover minor units to the largest fractional parts first.\n  const order = ideals\n    .map((ideal, i) => ({ i, frac: ideal - Math.floor(ideal) }))\n    .sort((a, b) => b.frac - a.frac);\n\n  let k = 0;\n  while (remainder > 0 && order.length > 0) {\n    const target = order[k % order.length];\n    if (target) {\n      const part = parts[target.i];\n      if (part) part.amount += 1;\n    }\n    remainder--;\n    k++;\n  }\n\n  return parts;\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/commission",
+  "version": "1.0.0",
+  "description": "Commission & payout calculation engine — flat, percentage and marginal-tiered rules with min/cap, plus exact proportional split with remainder distribution. Integer minor units, zero floats. Isomorphic (Node, edge, browser).",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "commission",
+    "payout",
+    "marketplace",
+    "sales-commission",
+    "tiered",
+    "percentage",
+    "revenue-share",
+    "split",
+    "minor-units",
+    "fintech",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://developer.lacspace.com/packages/commission",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "commission"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {},
+  "publishConfig": {
+    "access": "public"
+  }
+}